agent-config

Writing agent configuration that means what it says

Permission rules are the part people get wrong, because a rule that looks narrow can be wide. The behaviour below was measured on Claude Code 2.1.238 with a write probe, a command that creates a file, so the read-only classifier could not approve it on its own.

The one thing to know

Everything before the first * is matched as written, and that prefix is the only thing limiting the rule. The wildcard spans spaces.

Nearly every dangerous rule follows from that sentence.

Rule shapes that grant more than they read

A wildcard where the subcommand goes leaves only the program.

Bash(git * main) reads as "git something main". It approves every git subcommand and every option before it. Measured with that rule as the only rule present: git branch -D main deleted the branch, and git -c core.fsmonitor=<script> diff main ran the named script. -c core.fsmonitor= makes git run a program you name, so this rule is arbitrary command execution.

A leading wildcard leaves nothing at all.

Bash(* --version) has no prefix, so nothing limits it. Measured: bash -c 'touch <marker>' --version ran and the marker appeared. The tail still has to match, which is exactly what makes the rule read narrower than it is.

A runner passes the wildcard to a shell.

Bash(npx *), Bash(uvx *) and friends approve any command, because the runner executes its arguments. The rule limits the runner, not what runs.

gh api writes look like reads.

A rule shaped for fetching also approves mutation, because the method is a flag. -X, --method, -f, -F, --field, --raw-field and --input all turn a GET into a write, and short flags cluster, so -fkey=value is -f.

Some rules approve nothing at all.

:* is only recognised at the end of a pattern. A shell separator like && splits a command before rules are matched, so a rule containing one never fires. These are the harmless half of the same misunderstanding, and they are worth fixing because they give false confidence.