# Permissions Which tool calls run, which stop to ask, and which are refused. ```json { "permission": { "bash": { "*": "ask", "git *": "allow", "bun test": "allow" }, "edit_file": { "*": "ask", "src/generated/*": "deny" }, "read_file": { "*": "allow", "*.env": "deny" } } } ``` Three decisions: `allow` runs it, `ask` prompts, `deny` refuses without asking. ## Why rules match the command, not the tool The obvious design gates by tool name: `bash` needs approval, `read_file` does not. That is what this used to do, and it fails for a reason worth stating. `bash` covers `git status` and `rm -rf` equally. A user working through a batch of edits presses `a` — always allow — on the first prompt, and every later command runs unasked, including the one they would have refused. The gate was strongest at the moment it mattered least and gone by the time it mattered. Rules match the **subject** of a call: the command for `bash`, the path for anything touching a file, the pattern for a search. `git *` can be allowed while `*` still asks, so the prompts that remain are the ones worth reading. ## Subjects per tool | Tool | Matched against | |---|---| | `bash` | the command, e.g. `git status --porcelain` | | `read_file` `write_file` `edit_file` `multi_edit` `list_dir` | the path | | `read_many_files` | every path in the batch; one match is enough | | `glob` `grep` | the pattern | | `git_diff` `git_log` `git_blame` | the path, when given | | `git_show` | the ref | | `task` | the subagent description | | `skill` | the skill name | | everything else | `*` only | A tool with no subject — `git_status` takes no arguments — matches `*` and nothing narrower. That is why a rule for it is a plain decision rather than a pattern table: ```json { "permission": { "git_status": "allow" } } ``` ## Patterns `*` spans any characters including newlines, `?` matches exactly one. Everything else is literal: `*.env` does not match `configxenv`, because a rule you wrote by hand should mean what it looks like. Newlines matter for `bash`, where a command can legitimately contain one: ```json { "permission": { "bash": { "git commit *": "allow" } } } ``` That still matches `git commit -m "line one\nline two"`. ## Order is the whole rule Later rules win. A config reads top to bottom, so put the catch-all first and narrow after it: ```json { "permission": { "bash": { "*": "ask", "git *": "allow", "git push *": "ask" } } } ``` `git status` is allowed, `git push origin main` asks again. Reverse those last two and `git push` is allowed, because the broader rule now comes last. This is plain precedence with no special case for `deny`, and that is deliberate. An earlier version made `deny` win wherever it sat, on the theory that a refusal should be impossible to undo by accident. It made the most useful shape in the system unexpressible: ```json { "permission": { "edit_file": { "*": "deny", "src/generated/*": "allow" } } } ``` Default-deny with narrow exceptions is what a careful user writes, and it is the same shape as `*.env` denied while `*.env.example` is allowed. Refusals that must never be configurable belong in the [guard plugin](plugins.md), which runs ahead of this and which `--yolo` cannot reach. ## Defaults With no `permission` config: | Tool | Default | |---|---| | `read_file` `read_many_files` | `allow`, except `*.env`, `*.env.*`, and `*.pem` which are `deny`. `*.env.example` is allowed | | `glob` `grep` `list_dir` | `allow` | | the git tools | `allow` — they cannot mutate anything | | `task`, and every session tool | `allow` — they touch the agent's own state | | `write_file` `edit_file` `multi_edit` `bash` | `ask` | | anything else, including every `mcp__*` tool | `ask` | Credentials are denied on read rather than gated, because there is no recovery. A model that greps for a config value and finds a secret has that secret in its context, on the wire, and in the session file on disk. `.env.example` is the one such file that is safe and the one a model usually wants. An unrecognised tool asks. MCP tools are third-party code with unknown side effects, so `mcp__fs__read_file` sounding harmless is not a reason to let it through. ## Config replaces a default, it does not merge Anything you say about a tool replaces its default for that tool entirely: ```json { "permission": { "read_file": { "*": "allow" } } } ``` That allows reading `.env`. Merging pattern-by-pattern would leave you unable to remove a default deny rule, and a safety feature you cannot switch off is one people work around instead. A wildcard in a tool key covers a family: ```json { "permission": { "mcp__*": "deny" } } ``` ## What `always` grants Answering `a` at a prompt whitelists a **pattern**, not the tool. For `bash` that is the command's first word: ``` bash wants to run git status --porcelain y allow once | a always allow bash git * | n deny ``` Approving that runs `git log` and `git diff` unprompted for the rest of the session, and still asks about `npm publish`. Everything else falls back to `*`, because a path pattern guessed from one path is more often wrong than useful. Grants last for the session and are never written to disk. They also cannot outrank a rule: with `"rm *": "deny"` in your config, `a` on a different command does not unlock `rm`. ## The repeat guard A tool called three times in one turn with **identical** input asks for approval even when the rules allow it: ``` read_file is repeating the same call allowed by the rules, but this is the third identical call this turn src/session.ts ``` A model repeating an identical call is not making progress: either it is ignoring the result, or the result is not what it needed. `bash: allow` is a statement about which commands are safe, not permission to run one in a loop until the step limit ends the turn. The count is per turn and resets on the next prompt, so a tool used once in each of several turns never trips it. ## Order of checks ``` guard plugin refusal; --yolo cannot reach it → permission rules allow / ask / deny, matched on the subject → repeat guard an allowed call that has now repeated 3x asks anyway → the tool runs ``` A denied call **provably never executes**: the decision is enforced by the SDK, which never reaches the tool's `execute`. A tool cannot forget to honour a denial because the tool is not consulted. See [architecture](architecture.md#why-approval-goes-through-the-sdk). ## `--yolo` Folds `ask` into `allow`. It does not touch `deny`, from your config or from the defaults, and it does not reach the guard plugin. So `--yolo` still refuses to read `.env` and still refuses `rm -rf`. In headless mode there is no terminal to prompt on, so an `ask` is denied and the model is told. `--yolo` is what makes a headless run able to write. See [headless](headless.md). ## A typo never widens access An unrecognised decision string is dropped when the config is parsed, which leaves the pattern unmatched and the tool on its default: ```json { "permission": { "bash": { "*": "alow" } } } ``` `bash` asks, as it would with no config at all. The alternative — treating an unparseable value as `allow` — would mean one misspelling silently removing the gate. ## Worked examples **Trust the tools you run constantly, keep the rest gated.** ```json { "permission": { "bash": { "*": "ask", "git status*": "allow", "git diff*": "allow", "git log*": "allow", "bun test*": "allow", "bun run typecheck": "allow" } } } ``` **Let it edit source, never touch generated output or CI config.** ```json { "permission": { "edit_file": { "*": "ask", "src/*": "allow", "src/generated/*": "deny", ".github/*": "deny" }, "write_file": { "*": "ask", "src/generated/*": "deny", ".github/*": "deny" } } } ``` **Read-only, enforced by rules rather than by asking.** The `plan` agent variant does this by withholding the tools, which is stronger; use rules when you want the tools present but inert. ```json { "permission": { "write_file": "deny", "edit_file": "deny", "multi_edit": "deny", "bash": "deny" } } ``` **An unattended job that may commit but never push.** ```json { "permission": { "bash": { "*": "deny", "git add *": "allow", "git commit *": "allow", "bun test*": "allow" } } } ``` ## What this is not Rules gate the *call*, not what the command does once it runs. `bash` with `git *` allowed will run `git config --global` and a `git` alias that shells out to anything. There is no sandbox: no `seccomp`, no Seatbelt, no filesystem jail around the shell. `jail()` keeps the **file tools** inside the workspace — see [tools](tools.md#path-safety) — and the guard plugin refuses a list of irreversible commands. Both are worth having and neither is containment. Run the agent in a container or a VM when the workspace is not the trust boundary.