# Configuration and one-off grants

The defaults gate the `opus`, `fable`, and `sol` tiers; recognize explicit light pins matching
`sonnet`, `haiku`, `terra`, or `luna`; notify on confirmed events; and allow no standing exceptions.

Create the starter file:

```sh
gate init-config
```

It is written to `~/.config/gate/config.toml` on Linux and macOS or
`%APPDATA%\gate\config.toml` on Windows.
Set `GATE_CONFIG` to use a different path.

```toml
superheavy_pattern = "(?<![a-z0-9])(?:opus|fable|sol)(?![a-z0-9])"
light_pattern = "(?<![a-z0-9])(?:sonnet|haiku|terra|luna)(?![a-z0-9])"
allow = [
    "adversarial-critic",
    "workflow:deep-research",
]
notify = true
notify_command = []
throttle_seconds = 60
```

Allowlisted launches remain visible: they are allowed and notify at normal urgency.

`notify_command` runs directly as an argument vector, without a shell. Keep it that way:
`{title}` and `{body}` include hook-payload text, so do not interpolate them into `sh -c`,
PowerShell source, or another shell-evaluated string.

## One-off grants

A grant is a terminal-minted, TTL-bounded exception.
The default is one launch for 15 minutes:

```sh
gate grant general-purpose
gate grants
gate revoke general-purpose
```

Use `--session <session_id>` to bind the grant to the exact session named in a deny message:

```sh
gate grant general-purpose --uses 1 --ttl 15m --session session-123
```

Agents can request that command but cannot mint the grant themselves.
Every successful consumption sends a normal-urgency notification and decrements the remaining
uses.

## Terminal tinting

`gate tint` reads its own optional config at `~/.config/gate/tint.toml` (override with
`GATE_TINT_CONFIG`). Write a commented starter with `gate tint init`:

```toml
base_color = "slate"        # revert color when leaving a triggered dir
denial_window = 600         # seconds a deny event keeps tinting
activity_window = 3600      # seconds heavy/workflow activity counts as active

[aliases]                   # name -> hex; overrides built-ins
jade = "#2B8A6E"

[events]                    # predicate -> color; severity order is fixed
denied_recently = "red"
heavy_active = "orange"
workflow_active = "amber"
grant_active = "violet"

[directories]               # nested tables compose regex prefixes
"~/my/apps" = { irix = "jade", "superheavy-gate" = "cyan" }

[commands]
"^git push" = "red"

[places]                    # literal path prefixes (escaped, match on boundary)
"~/vault" = "violet"
```

See [Terminal tinting](tint.md) for the full model: event predicates, precedence,
overrides, and terminal caveats.