Permissions are the mechanism. Intent is what you meant to model.

Harness Engineering tells this the long way in the chapter on bounding tools. A staff engineer wires up a server exposing a runSql tool that takes a string and runs it. No allowlist of statement types, no dry run, no confirmation. The task is a schema cleanup, the planning doc has moved, the agent infers intent from stale schema comments and runs DROP TABLE on the wrong table. Staging is restored from the previous night's snapshot and nothing ships that day.

He was not embarrassed about the model. He was embarrassed about the charter. The model did what the tool let it do, and the tool let it drop a table because nobody had told the tool that dropping tables was special. That is the loose end of the dial, and it is the one everybody writes about.

0.1 · The other end, which is where teams actually live

Picture the strict charter instead. One broad rule, and a prompt on every tool call. The agent works and every fifteen seconds a dialog interrupts. Over an afternoon the engineer spends as much time answering prompts as the agent spends writing code, and the team blames the agent. The agent did what the charter asked. The charter asked too often.

Then somebody finds the bypass mode, and the strictness converts to zero enforcement in one keystroke. This is the part worth saying plainly: a list too strict to work inside does not produce caution. It produces a session with no checks at all. The failure mode of over-restriction is under-restriction, arriving later and unlogged.

0.2 · The postures, and what each one is for

Modern harnesses ship more than one dial position, and knowing the ends is not enough. These are Claude Code's, and the shape generalizes: one posture per level of human attention.

Read the dontAsk row twice, because it is the one that changes how you write a list. A posture that denies anything unlisted and never prompts is only usable if the list is complete. Completeness is impossible while the project can be run eleven ways, and straightforward when it can be run one way. That is the whole argument of Part II, arrived at from the strict end rather than the loose one.

The same order runs across settings scopes. A deny anywhere beats an allow anywhere: user settings, project settings, local settings, command-line flags. Managed settings sit above all of it and cannot be overridden even from the command line. So the deny list is the one place a platform team can write something a project cannot argue with, and the allow list is the place a project describes its own work.

1.1 · Two ways to say no, and they are not the same tool

A deny rule that names a bare tool removes that tool from the model's context. It does not exist; nothing is refused, because nothing is attempted. A deny rule with a specifier leaves the tool in place and refuses the matching calls when the agent tries them.

The second row is the one that teaches. A refusal returned as the result of the call is readable: the agent sees that php artisan test was denied, reads the rule that says what to run instead, and runs that. A capability quietly absent from context produces no learning and no confusion either. Both are fine. Confusing them produces a charter that explains a rule the agent has no way to encounter.

1.2 · The specifier forms worth knowing

The last row has a reason worth carrying into section 2. You cannot write Bash(command:rm *), and the harness ignores it with a warning, because a rule that matched only the command parameter would be defeated by a compound command. The surface that decides has to be the surface the shell will actually execute.

2.1 · The star, and everything before it

Everything before the first * matches as written, so the words in front of the star are the entire constraint. Put the star after the subcommand, because the subcommand is the word that decides what the program does.

Row three is not a curiosity. git -c makes git run a program you name, so any rule whose star sits before the git subcommand is a general execution grant with a git-shaped label on it. The harness warns at startup about an allow rule with a star before the subcommand. Read the warning.

The :* suffix is the same thing as a trailing space-star, and only at the end. Bash(ls:*) and Bash(ls *) are one rule written two ways. In the middle of a pattern the colon is a literal character, so Bash(git:* push) matches nothing you intended.

2.2 · Compound commands, which the harness handles

This one is good news, and it is worth knowing so you stop writing defensive rules against it. The harness understands shell separators. A rule must match each subcommand independently, so an allow of Bash(safe-cmd *) does not authorize safe-cmd && other-cmd. Deny and ask rules go the other way: they fire if any subcommand matches, including one nested in a subshell, a command substitution, or a loop body.

1. allow side Every subcommand needs its own match. The recognized separators are &&, ||, ;, |, |&, & and newlines.
2. deny side One matching subcommand anywhere is enough. echo "$(git clean -f)" trips a Bash(git clean *) rule.
3. unparseable A dangling operator such as npm test && is not split at all, and allow rules do not approve it. It prompts.

2.3 · Wrappers: some are stripped, and the dangerous ones are not

Before matching, a fixed set of wrappers comes off, so Bash(npm test *) also covers timeout 30 npm test. The stripped set is timeout, time, nice, nohup, stdbuf, the builtins command and builtin, zsh's noglob, a leading assignment of certain known-safe environment variables, and bare xargs.

The list is built in and it is not configurable, which means the runners are not on it. This is the single most important sentence on this page for anybody about to write Bash(docker compose exec *):

Two smaller relatives. Exec wrappers such as watch, setsid, ionice and flock cannot be prefix-approved at all, so in manual mode they always prompt. And find with -exec or -delete is not covered by Bash(find *); those forms need an exact-match rule for the whole command string.

2.4 · Rules that constrain arguments are fragile

A rule like Bash(curl http://github.com/ *) looks like a domain restriction and is not one. Options before the URL miss it. A different protocol misses it. A redirect through a shortener defeats it. URL=http://github.com && curl $URL defeats it. Two spaces instead of one defeats it.

The working shape is to deny the network tools in the shell, allow the fetch tool with an explicit domain list, and put anything more specific in a hook. The general rule underneath: constrain the program, not its arguments. Argument shapes are an unbounded space and a permission pattern is a finite guess at it.

Which is the moment to say what all six of these traps have in common, because it is the argument of the rest of the page. Every one of them is the gap between what the rule matches and what the author meant. Nobody writing Bash(git *) meant may execute arbitrary programs; they meant may do the git work this project involves. The pattern language cannot say the second thing, so it says the first thing and the difference is a grant nobody reviewed. Part II is about closing that gap by changing what the list points at.

2.5 · Path rules, and the single-slash trap

The third row bites in user settings, where Read(/secrets/**) resolves under ~/.claude/ rather than into any project. If you want a rule in user settings to apply inside every project, write it absolute or home-relative.

2.6 · The read-only set you are already getting for free

A built-in set of shell commands is treated as read-only and runs without a prompt in every mode: ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd, and the read-only forms of git. Redirection changes that, because the target of a > is checked against your Edit rules as if the agent had written the file directly.

Which means a large fraction of the entries in a typical allowlist are doing nothing at all. Section 7 counts them in my own repositories.

"allow": [
  "Bash(make *)",
  "Bash(git *)", "Bash(gh *)", "Bash(jira *)",
  "Bash(ls *)", "Bash(wc *)", "Bash(find *)", "Bash(grep *)", "Bash(echo *)",
  "Bash(docker compose exec *)",
  "Bash(curl *)", "Bash(xargs *)", "Bash(tee *)",
  "mcp__puppeteer__puppeteer_navigate",
  "mcp__puppeteer__puppeteer_screenshot",
  "mcp__puppeteer__puppeteer_fill",
  "mcp__puppeteer__puppeteer_click",
  "mcp__puppeteer__puppeteer_evaluate",
  "mcp__puppeteer__puppeteer_hover",
  "mcp__puppeteer__puppeteer_select",
  "mcp__…__createJiraIssue", "mcp__…__editJiraIssue", "mcp__…__createIssueLink",
  "Skill(update-config)"
],
"deny": [
  "Bash(php *)", "Bash(php artisan *)", "Bash(npm *)",
  "Bash(npx *)", "Bash(composer *)", "Bash(./vendor/bin/*)"
]

The bottom half of that file is the toolchain deny list from section 6, and it works. The top half is where the intent gap lives. Read the next table one row at a time: the middle column is what somebody was trying to say, and the right column is what the rule says instead.

3.1 · The two rows that are already right

Look at the first and last rows before the eight in the middle, because they are the answer and they are already in the file. The MCP entries name one operation each: navigate, screenshot, fill, click. Nobody wrote mcp__puppeteer__*, because the tools have names and naming them was easy. And Bash(make *) is one line standing in for seventy-eight named tasks, which is the same trick performed on the shell.

Both are cases where the thing being permitted had a name. That is the whole difference. Where the unit of permission has a name, the list enumerates intents and reads correctly. Where it does not, the author reaches for the program name and a wildcard, and grants the program's entire surface because that is the only thing the language lets them say.

A target carries four things a command pattern cannot. A name, chosen by a person, in the vocabulary of the work rather than the vocabulary of the tool. A recipe, which says exactly what the intent expands to. A place in a tracked file, so adding one is a diff and a reviewer. And a help line, so the permitted set is discoverable instead of guessable. That is the smallest artifact I know of that carries we decided the project does this.

So the principle, stated once: permit the allowable set of intents, and nothing else. Every entry in the allow list names one intent, or names a file that enumerates them. An entry that grants a program's whole surface is not a stricter or looser version of that principle. It is a different thing, standing in for an intent that was never written down.

4.1 · The seven accidental grants, resolved

Each row takes one entry from section 3 and names the intent it was standing in for. The right column is what replaces it, and in five of the seven the varying part becomes an argument rather than a wider pattern.

The FILES= row is not hypothetical: that charter already has make psalm-files FILES="a.php b.php", written because a full analysis run was too slow, and it is the exact shape the argument needs. The parameterized target was already there. The allowlist just never caught up with it.

4.2 · Arguments are what keep a parameterized intent a single intent

This is the part that makes the strict posture livable, and it is why the answer is not simply write narrower patterns. Work varies. You want style fixed in one directory today and another tomorrow; a migration rolled back one step, then three. A pattern-shaped list handles variation by widening until it covers the family, which is how Bash(./vendor/bin/*) gets written. A target handles it by taking an argument, and the permitted set does not move.

make pint-fix
make pint-fix ARGS=app/Services/Billing
make migrate-rollback ARGS=--step=1
make psalm-files FILES="app/Actions/Approve.php app/Http/Api.php"

# Every one of these is Bash(make *). The list is unchanged.
# A pattern-shaped list would have grown a rule for each shape,
# then one wildcard that swallowed all four.

There is a bill for this and section 8 is where it comes due: an argument interpolated into a shell recipe can carry shell. The charter above interpolates $(ARGS) unquoted in about a dozen recipes, including make tinker ARGS=--execute='…', which is arbitrary code execution by documented design. Arguments are the right mechanism and they are the part of the door that needs a lock.

4.3 · Why one entry for seventy-eight intents is not cheating

Bash(make *) is one rule standing in for a large set, which looks like exactly the move the eight bad rows made. The difference is where the set is written down. A program grant stands in for a set nobody has ever listed: the union of everything git or gh can do, discovered at the moment it matters. A door stands in for a set that exists as text, in the repository, with a name and a recipe per member, in front of a reviewer.

4.4 · A name beats a command, for a second reason

make test is a stable name for an unstable thing. Underneath it may be pest, then phpunit, then two tiers run concurrently by paratest inside a container. Each of those rewrites a command-shaped allowlist and none of them touch a target-shaped one. The charter's instruction to the agent (run make test, run make lint) also stops going stale, which is the same benefit arriving in the prose layer.

And a target records a decision, where an allowlist entry records a click. A command in an allowlist means a prompt fired and a human said yes once. A target means a person decided this is a thing the project does, wrote it down, and named it. Those are different artifacts with different review paths, and only one of them is legible six months later.

4.5 · Three artifacts pointing the same direction

A rule states the intent, the config makes it non-negotiable, and the Makefile makes compliance the easy path. Five Guardrails works this trio in one screen as the cheapest guardrail there is; here it is as the shape:

1. the rule Always-on prose: use make targets, never the raw tool, and here is what to do when no target fits. This is the part that teaches, and it enforces nothing. In the charter above it is marked locked, with a why field recording the incident that produced it.
2. the config A deny list for the raw tools and an allow for the door. This is the part that refuses, and it explains nothing.
3. the Makefile The enumeration of intents, self-documenting, so the permitted set is discoverable rather than guessable. This is the part that makes the other two survivable.

Miss the third and you have built the strict charter from section 0: a wall with no gate, which lasts until somebody finds the bypass flag. The escape hatch in the rule text matters as much as the wall does, and the real one says it in two lines: no appropriate target exists, add one to the Makefile and document it; an existing target is not flexible enough, add ARGS= support rather than reaching for the raw tool.

test                 ## both PHP test tiers concurrently — the pre-commit gate
test-parallel        ## use-case tier via paratest, no database
test-adapter         ## adapter tier against an in-memory database
pint-fix             ## fix PHP code style (ARGS= for extra flags)
psalm-files          ## analyse a specific file set: FILES="a.php b.php"
migrate-rollback     ## roll back the last batch (ARGS=--step=1)
tinker               ## a Laravel console (ARGS=--execute='…')
shell                ## bash in the app container

# Seventy-eight of these. Two — tinker and shell — are general
# execution, which means they are not intents at all. Section 8.1
# is what to do about that, and it is not "decide carefully".

Here is the sentence from the guardrails page that this whole stack exists to produce. A project runs entirely inside Docker. An agent that types php artisan migrate runs it on the host, which has no PHP extension set and no database. Then, being helpful, the agent invents a workaround. The failure is not the wrong command. It is that the wrong command was available.

Move the toolchain into the container and that availability goes away as a matter of fact rather than policy. There is no host php to run. The deny rule is then a courtesy that returns a readable refusal instead of a confusing environment error, and the courtesy is worth having, but it is no longer the thing holding the line.

flowchart TD
  A["the agent proposes a command"] --> R{"permission rules · deny, ask, allow"}
  R -->|"not make"| X["refused, with a readable reason"]
  R -->|"make target"| M["make · the only door"]
  M --> C["docker compose · the container"]
  C --> T["the toolchain, which exists only here"]
  C --> B["filesystem bound · no host credentials · ephemeral"]
  X --> L["the agent reads the rule and runs make instead"]
  class A dim
  class R warn
  class X warn
  class L dim
  class M pass
  class C pass
  class T pass
  class B block

Read the last row as the strongest control on the page. The cheapest way to bound exposure to production is to have none: no write access, no read access, and no credential on the machine that could become either. Production deploys, production data and production migrations sit behind a human. That is not least privilege applied carefully; it is a line drawn before the privilege question is asked, and it is the one grant I do not make.

5.1 · The harness has a sandbox too, and it is not the same boundary

Claude Code can enforce filesystem and network bounds at the OS level for Bash commands and their children, and it merges those bounds with your Read and Edit deny rules and your WebFetch domain rules. That is a real floor and it is worth turning on. It is also not your container: it bounds the shell the agent runs, while the container bounds the environment your project runs in.

Two honest notes about the overlap. Path deny rules cover the built-in file tools and the file commands the harness recognizes in Bash, and they do not cover an arbitrary subprocess that opens files itself, which a test suite does constantly: for that you need OS-level enforcement, container or sandbox. And a container with your repository bind-mounted does not protect a secret that lives in the repository. Both layers leave a gap the other one covers, so run both and know which one you are relying on for what.

**Always use `make` targets.** Never run `npm`, `npx`, `php`,
`php artisan`, `composer`, `vite`, or similar tools directly — they
execute on the host, not in the container, and bypass the project's
environment.

- No appropriate target exists → add one to the `Makefile` and
  document it in `.claude/features/common-commands.md`.
- An existing target is not flexible enough → add `ARGS=` support
  rather than reaching for the raw tool.
- Coreutils (`ls`, `grep`, `tail`, `git`, etc.) are fine to run directly.

"permissions": {
  "allow": [
    "Bash(make *)",
    "Bash(git diff *)", "Bash(git commit *)",
    "Bash(gh pr *)"
  ],
  "ask": [
    "Bash(git push *)"
  ],
  "deny": [
    "Bash(php *)", "Bash(composer *)", "Bash(npm *)",
    "Bash(npx *)", "Bash(./vendor/bin/*)",
    "Bash(git push --force *)", "Bash(git push -f *)",
    "Read(./.env)", "Read(~/.aws/**)", "Read(~/.ssh/**)"
  ]
}

sequenceDiagram
  participant A as the agent
  participant P as the permission gate
  participant M as make
  participant D as the container
  A->>P: php artisan test
  P-->>A: denied by Bash(php *)
  Note over A: the refusal is the result of the call, so the agent reads it
  A->>A: re-reads the always-on rule: use a make target
  A->>P: make test
  P-->>M: allowed by Bash(make *)
  M->>D: docker compose exec app pest
  D-->>A: 214 passed, 2 failed, with file and line

6.1 · The consequence of deny-first, which changes how you write the escape

Somebody will want php artisan tinker next week. You cannot get it by adding an allow rule, because Bash(php *) in deny is evaluated first and a deny cannot carry an exception. That constraint is a feature, and it leaves exactly three moves:

The first move is the one that compounds, and notice what it does to the argument. A request to widen the agent's capability has become a pull request against a file, with a name, a recipe and a reviewer. That is the same shape as every other change to how the project is built, which is the point: permission decisions stop being a private settings file and start being engineering.

6.2 · And when the work varies

The next request will not be make test. It will be the test suite over one directory, or style fixed in one module, or a rollback of exactly one migration batch. That is the same intent with a parameter, and section 4.2 is where it goes: into ARGS= or a named variable, not into a wider entry. The allowlist stays one line, and section 8 is the bill for interpolating a variable into a shell recipe.

7.1 · Replaced by the door

7.2 · Dead on arrival

These were never doing anything, because the read-only set runs without a prompt in every mode. Five of the twenty-four entries in section 3 are in this category, which is how you know the pattern is not a beginner's mistake but a default nobody rechecks.

"allow": [
  "Bash(ls *)",     // already free
  "Bash(wc *)",     // already free
  "Bash(find *)",   // already free, and -exec was never covered anyway
  "Bash(grep *)",   // already free
  "Bash(echo *)",   // already free
  "Bash(git *)",    // git -c core.fsmonitor=<script> runs anything
  "Bash(xargs *)",  // xargs sh -c runs anything
  "Bash(tee *)",    // writes any path, unseen by the file rules
  "Bash(curl *)"    // unbounded egress
]

Bash(git *) is the one to look at twice, because it is the most reasonable-looking line in the file. It reads as a convenience and it is a general execution grant, since git -c runs a program you name. The read-only git forms are already free, so the honest version of this entry is two rules for the writing subcommands, or a make commit target, and no wildcard at all.

7.3 · Kept, and narrowed

The last row is the load-bearing one, and it is the same lesson the measured work on rule placement produced: never let the thing that enforces a rule sit inside the thing it enforces against. A Makefile the agent can edit is not a permission boundary. It is a suggestion with extra steps, because the path from I need a capability to I have it is two tool calls and no human.

"deny": [
  "Bash(make -f *)", "Bash(make --file *)",
  "Bash(make -C *)", "Bash(make --directory *)",
  "Edit(/Makefile)",
  "Edit(/.claude/**)"
]
# Changing what the project can do is now a human's edit and a
# reviewer's read. That is the whole security property of the stack.

8.1 · The target that means “anything”

Two targets in that catalog are general execution: make shell opens a shell in the container, and make tinker ARGS=--execute='…' evaluates whatever you hand it. Both are useful. Both are also the exact thing the door was built to prevent, and having them inside the door is worse than having them outside it, because they are now covered by the one entry that looks safe.

Say it in the vocabulary of section 4 and the problem is obvious. The permitted set is supposed to be the allowable set of intents. An intent of run arbitrary code in the app container is not a member of that set; it is the set. One such target collapses seventy-eight named intents back down to Bash(*), and the allowlist still reads like one tidy line.

8.2 · Restrict the targets by operation instead

The repair is the same move applied one level down. The reason those targets exist is that people had specific operations to perform and no named target for them, so they reached for the general one. Name the operations. Then the general targets are not load-bearing and can be refused.

# instead of: make tinker ARGS=--execute='User::where(...)->first()'
user-show:      ## one user record as JSON. EMAIL=
	@$(EXEC_T) php artisan app:user-show "$(EMAIL)"

queue-retry:    ## retry one failed job. ID=
	@$(EXEC_T) php artisan queue:retry "$(ID)"

cache-clear:    ## clear application cache. No parameters
	@$(EXEC_T) php artisan cache:clear

migrate-rollback: ## roll back one batch. STEP= (an integer)
	@test "$(STEP)" -gt 0 2>/dev/null || { echo "STEP must be a positive integer"; exit 2; }
	@$(EXEC_T) php artisan migrate:rollback --step="$(STEP)"

# instead of: make shell
logs:           ## tail container logs. SERVICE= (app|queue|db)
db-console:     ## a read-only psql session against the dev database

Three properties changed there and each one matters. The parameter is named for what it is, so EMAIL= cannot carry a flag and STEP= is checked to be an integer before anything runs. The variable is quoted, so it cannot carry shell. And the operation is one operation, so the help line is an honest description of what the agent is permitted to do rather than a category.

"allow": [ "Bash(make *)" ],
"deny": [
  "Bash(make shell*)",        // interactive container shell
  "Bash(make tinker*)",       // arbitrary application code
  "Bash(make artisan*)",      // the whole framework CLI
  "Bash(make -f *)", "Bash(make --file *)",
  "Bash(make -C *)", "Bash(make --directory *)"
]

This is the one place on the page where the precedence rule from section 1 pays for itself. Deny is evaluated before allow and specificity is not consulted, so a narrow deny reliably carves a hole out of a broad allow. The general targets stay in the Makefile for the humans who type them in their own terminal, where no permission rule applies, and they are unavailable to the agent. One artifact, two audiences, and the difference expressed in the config rather than in a comment.

Note what the deny list looks like now: five or six entries about make itself. That is the right shape. Once the allow side names one door, the deny side is where the interesting decisions live, and each one reads as a sentence about intent — the agent does not get an interactive shell, the agent does not evaluate arbitrary application code.

Two of the three have ordinary fixes and one does not. The runner entry becomes three targets. The unquoted variables get quotes, or a validating hook, and the two deliberately-general targets (tinker, shell) stay in the catalog and out of unattended profiles. The self-editing grant has no safe narrow form: a capability that can rewrite the permission file is the permission file. It comes out, and a human edits config.

8.3 · Why removing Skill(update-config) does not fix it

I said earlier that the self-editing grant comes out and a human edits config. That is the right instinct and it does not work, and the reason it does not work is worth more than the fix, because the same shape defeats several other repairs on this page.

1. the skill was never the capability It is a wrapper over the Edit tool on a path. Deny the skill and the agent edits .claude/settings.json directly, with the tool it already has for editing files in the repository.
2. so deny the path Edit(/.claude/**). Now the door is the way in: a new Makefile target whose recipe runs sed or a script over the settings file. Path rules cover the built-in file tools and the file commands the harness recognizes in a shell command. They do not cover a subprocess that opens a file itself.
3. so deny that too Edit(/Makefile). Both denies now live in .claude/settings.json, which is the file they protect. The rule guarding the file is inside the file, so any path to writing that file is also a path to deleting the rule.
4. and the config is bigger than the file A project skill can carry its own allowed-tools frontmatter, which pre-approves tools for that skill, and workspace trust never gates it. So .claude/skills/ is a permission surface too, and an agent that can write files under .claude/ can grant itself tools without touching settings.json at all.

That is the circularity, and it is the reason the measured work on rule placement puts it as a law rather than a tip: never let the rung that enforces a rule sit inside the rung it enforces against. A deny rule protecting its own file is an enforcer inside its own blast radius. It stops an incurious agent, which is worth something, and it stops nothing that is actually trying.

8.4 · Where the rule has to live instead

Deny rules from any scope beat allow rules from any scope, and managed settings cannot be overridden even from the command line. So move the self-protection up, out of the workspace the agent works in, and back it with the one control that is not a runtime check at all.

The last row is the one that actually closes it, and it closes it for the Makefile at the same time. Every control in this article can be edited by whoever can write the repository; the question is only whether writing it requires a person. Runtime rules make the agent's path expensive. Code owners on those two paths make the agent's path go through a reviewer. Use both, and stop expecting a config file to defend itself.

8.5 · What the door still buys, honestly stated

With those denies in place, Bash(make *) grants exactly the set of targets in a reviewed file, plus whatever a recipe's own escape hatches allow. That is a real and checkable bound, and it is weaker than a per-command allowlist would be in theory. In practice it is stronger, for one reason: it is short enough that somebody reads it. A forty-line allowlist nobody reviews grants whatever nobody noticed.

So the claim is not that a door is airtight. It is that a door moves the enumeration from a file written by clicking into a file written by deciding, and puts it in front of a reviewer. Then section 5's container catches what the review misses, and section 9 is about what to do with the layer underneath that.

Two facts bound what a rule can do. Path denies cover the built-in file tools and the file commands the harness recognizes in a shell command; they do not cover a subprocess that opens files itself, which is what every test suite and every script does. And the read side of the boundary is not the interesting one anyway: a secret that reaches the model's context can leave it, in a PR description, in a quoted error, in a sub-agent's report.

So the deny list is a short list of things it is worth being categorical about, and the floor under it is somewhere else.

9.1 · The injection case, where deny earns more than its keep

There is one place a deny list does real security work rather than habit work. Untrusted content that reaches the context can ask the agent to run something, and the agent has no reliable way to tell that request from yours. A deny rule refuses it without the agent's cooperation, and deny rules fire on any subcommand, including one hidden in a command substitution or a loop body. So the list is exactly the layer that turns the model was persuaded into the call did not run.

That is the argument Prompt Injection develops properly, and the short version here is that the entries that matter for it are the egress ones. Deny the shell network tools, allowlist fetch by host, and treat everything that comes back through either as data rather than instruction.

A PreToolUse hook runs before the permission prompt for every tool call, and its output can deny the call, force a prompt, or skip the prompt. The precedence is worth memorizing because it is not symmetric. A hook that returns allow does not defeat a deny or ask rule: those are evaluated regardless. A hook that exits with code 2 stops the call before the rules are consulted, so a block beats an allow rule. Refusal composes; permission does not.

That last row is a legitimate and underused posture: put the whole tool in the allow list and register a hook that rejects the specific commands you care about. It inverts the default, which is usually wrong, and is occasionally exactly right for a sandboxed throwaway environment where you want speed with a handful of absolute stops.

Five Guardrails works the whole ascent, from a rule and a deny entry up to a hook that compiles the same rule into a sensor and returns a refusal the agent can act on. The relevant design decision from it, restated for this page: a refusal should name the rule, the reason, and the sanctioned path. A hook can do that in a sentence. A deny rule can only say no, which is why the always-on prose from section 6 has to carry the rest.

1. pass 1 · free Delete every entry for a command in the read-only set: ls, cat, grep, find, wc, head, tail, which, diff, stat, du, echo, pwd, cd, and the read-only git forms. They ran without a prompt anyway.
2. pass 2 · shadowed Sort the list and look for a broad entry above narrow ones. Bash(python3 *) makes every specific python entry dead. Delete the narrow ones, then decide whether you actually meant the broad one. Usually you meant a target.
3. pass 3 · runners Find every entry whose program executes its arguments: docker exec, npx, devbox run, mise exec, direnv exec, python3 -c, sh -c, git *, find * with -exec. Each one is an execution grant wearing a specific label. Replace with a target, or name the runner and the inner command.
4. pass 4 · frozen Every remaining entry: say out loud why it is there. An entry whose reason is a prompt fired once in July is not a decision. Delete it and let the prompt fire again, once, with a person present to make the call properly.
5. pass 5 · intent For each survivor, name the one intent it permits, in the vocabulary of the work rather than the tool. If the sentence needs an and, the entry is standing in for several intents and at least one of them is not the one you wanted. Give that intent a target and point the entry at the door instead. This is the pass that shortens the list permanently; the four above it only tidy.

# In session: every rule, and which settings file it came from.
# This is the resolved view, across user, project and local scope.
/permissions

# On disk: the allow list of every project, longest first. The ones
# at the top of this output are the ones to read this afternoon.
for f in */.claude/settings*.json; do
  printf '%3d  %s\n' \
    "$(python3 -c "import json,sys;print(len(json.load(open('$f')).get('permissions',{}).get('allow',[])))")" \
    "$f"
done | sort -rn

11.1 · Where an entry lives is a statement about who decided it

The local file is the one that matters for hygiene, because its whole purpose is to absorb clicks. Reading it once a week is the cheapest audit in this article: each entry either becomes a target in the Makefile, gets promoted into the tracked settings file with a reason, or goes away. An entry that survives three of those reviews without becoming either is telling you the toolchain has a door you have not built yet.

Two mechanics worth knowing while you move entries around. Allow rules in a project's settings are capability grants, so they apply only after you accept the workspace-trust dialog for that folder; deny and ask rules are not gated that way, because they only restrict. And a settings.local.json that is tracked in git is treated as repository-supplied rather than yours, and waits for the same trust step. If you check the local file in, you have made it project config with a misleading name.

{
  "permissions": {
    "defaultMode": "default",
    "allow": [
      "Bash(make *)",
      "Bash(git commit *)", "Bash(git checkout -b *)",
      "Bash(gh pr view *)", "Bash(gh pr create *)", "Bash(gh pr diff *)",
      "WebFetch(domain:docs.internal.example.com)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      // the toolchain: it lives in the container, not on the host
      "Bash(php *)", "Bash(composer *)", "Bash(npm *)", "Bash(npx *)",
      "Bash(./vendor/bin/*)", "Bash(docker compose exec *)",
      // the door stays a door: no redirecting it at another file
      "Bash(make -f *)", "Bash(make --file *)",
      "Bash(make -C *)", "Bash(make --directory *)",
      // the targets that are not intents: general execution
      "Bash(make shell*)", "Bash(make tinker*)", "Bash(make artisan*)",
      // the irreversible and the secret
      "Bash(git push --force *)", "Bash(git push -f *)",
      "Bash(rm -rf *)", "Bash(curl *)", "Bash(wget *)",
      "Read(./.env)", "Read(~/.aws/**)", "Read(~/.ssh/**)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}

{
  "permissions": {
    "deny": [
      // note the double slash: a single slash in user settings
      // resolves under ~/.claude/ and protects nothing. §2.5
      "Edit(//**/.claude/**)",
      "Edit(//**/Makefile)"
    ],
    "disableBypassPermissionsMode": "disable"
  }
}
# Plus code owners on those two paths, because a runtime rule makes
# the agent's route expensive and review is what makes it human.

Three notes on reading those files. The comments are for you, not for the parser: strip them before you use them, because the settings format is JSON. The Edit denies sit in the second file rather than the first, for the reason section 8.3 works through. And the docker compose exec entry in the deny list is not a contradiction of the Makefile below, which runs that exact command. Permission rules match what the agent asks the shell to run. What a permitted program then spawns is invisible to them, which is the mechanism the whole door depends on: the agent cannot type docker compose exec, and make test can.

.PHONY: help test lint lint-fix migrate build dev shell

COMPOSE := docker compose
EXEC    := $(COMPOSE) exec -T app

help:          ## this list
	@grep -E '^[a-z-]+:.*##' $(MAKEFILE_LIST) \
	  | sed 's/:.*## /\t/' | expand -t22

test:          ## the whole suite, in the container
	@$(EXEC) ./vendor/bin/pest

lint:          ## static analysis and style, check only
	@$(EXEC) ./vendor/bin/pint --test
	@$(EXEC) ./vendor/bin/phpstan analyse

lint-fix:      ## fix style. ARGS=path to scope it
	@$(EXEC) ./vendor/bin/pint "$(ARGS)"   # quoted, on purpose

migrate:       ## migrations, dev database only
	@$(EXEC) php artisan migrate

shell:         ## interactive shell in the container. A deliberate grant
	@$(COMPOSE) exec app bash

12.1 · Fifteen rules

1. Every allow entry names one intent, in the vocabulary of the work. An entry standing in for a program's whole surface is a bug, however convenient.§3 · §4
2. The project has one entry point for work, and the allow list names it. The intents are enumerated behind it, as targets.§4
3. Work that varies takes an argument. Widening a pattern to cover a family is the failure this replaces.§4.2
4. No target grants the agent general execution. A shell, a language console and the framework CLI are denied by name, and the operations people reached for them with are named targets with typed parameters.§8.1 · §8.2
5. The toolchain lives in a container. There is no host copy of it to reach for.§5
6. Adding a capability is a target and a review, never a settings entry and a click.§6
7. The door's own files are not writable by the agent — the Makefile and the whole settings directory — and the rule that says so lives in a scope the agent cannot write, backed by code owners on both paths.§8.3 · §8.4
8. Redirecting flags are denied: make -f, make -C, and their long forms.§8
9. Every variable a recipe interpolates is named for its value, quoted, and validated, and no recipe takes a program name from an overridable variable.§8.2
10. No entry names a program that executes its arguments unless the inner command is named too.§2 · §11
11. No allow entry duplicates the read-only set, and no allow entry is shadowed by a broader one.§11
12. Wildcards sit after the subcommand, and the startup warnings about rule shape are read, not dismissed.§2
13. The shell's network tools are denied and fetching is allowlisted by host.§9
14. The bypass posture is locked off, and production has no credential on the machine.§9
15. The local settings file is drained weekly: every entry becomes a target, a reviewed entry, or nothing.§11

12.2 · Three levels

12.3 · Where I fail it

The charter in section 3 is mine and it is running. It fails rule 1 seven times over, rule 4 three times (make shell, make tinker, make artisan are all reachable through the door), rule 7 through Skill(update-config) and a self-protecting deny that would sit in the file it protects, rule 9 in about a dozen recipes that interpolate $(ARGS) unquoted, rule 10 twice, and rule 13 outright: it allows Bash(curl *). What it gets right is the part that took the longest to learn, which is the rule layer: a locked always-on rule, a why field recording the incident that produced it, seventy-eight named targets, and hooks on four events.

That split is the honest lesson of the page, and it is why the intent framing is worth the trouble. I modeled the intent correctly in prose and then encoded it in a language that cannot hold it, and the encoding drifted for a year without anybody noticing, because nothing compares the two. Level 2 below is the level at which they stop drifting apart.