DEV Community: Hamid Ahmadian

Claude Code Permission Rules and Hooks: The Precedence Order Nobody Documents Clearly

Hamid Ahmadian — Wed, 09 Sep 2026 07:35:20 +0000

Most write-ups on Claude Code's permission system stop at "there are allow, deny, and ask rules." That's true, but it skips the part that actually determines whether your setup holds up under pressure: the rules have a fixed evaluation order, hooks interact with that order in a specific and non-obvious way, and a small set of paths can't be unlocked by any rule at all, in any mode short of full bypass. Here's the part that's easy to get wrong in practice.

Deny beats allow, always — specificity never matters

Claude Code evaluates deny, then ask, then allow, and the first match wins. Rule specificity does not change the outcome. A broad Bash(aws *) deny blocks a call even when a much narrower Bash(aws s3 ls) allow also matches. This is the single most common source of "why isn't my allow rule working" confusion — if a broader deny exists anywhere in the chain, no allow rule, however precisely scoped, can punch a hole in it. If you're debugging a rule that seems to be ignored, check for a deny match before you assume the allow syntax is wrong.

There's also a distinction worth internalizing between a bare tool-name deny and a scoped one. "deny": ["Bash"] removes Bash from Claude's available tools entirely — it's not an option Claude even considers. Bash(rm *) leaves Bash available but blocks matching invocations when attempted. Deciding whether to eliminate a capability outright or fence off a dangerous subset of it is a real design choice, not just a syntax preference.

A few paths nothing can unlock

Two categories are protected below the level where rules even get consulted. Protected paths — .git, .claude, .vscode, shell rc files, .mcp.json, and similar — are never auto-approved by any allow rule, in any mode short of bypassPermissions. The safety check runs before Claude Code evaluates your allow rules, so an entry like Edit(.claude/**) in settings.json has no effect on this gate. That's deliberate: it stops a compromised or misconfigured allow rule from silently granting write access to the files that define Claude Code's own permissions and hooks.

Critical paths are the same idea applied to destructive removal: rm/rmdir targeting the filesystem root, a top-level directory like /usr or /etc, your home directory, or your working directory and its parents is refused — no allow rule and no PreToolUse hook returning "allow" can approve one of these, in any mode, including bypass. It's a hard-coded circuit breaker against model error, not a policy setting you can tune.

Hooks are dynamic; rules are static — and they interact in one specific way

Permission rules are a fixed list you write once. PreToolUse hooks are scripts that run before a tool call executes, inspect the actual arguments, and return a decision based on runtime context a static rule can't express — scanning a file's contents, calling a validation service, checking what a command would actually touch.

The interaction is worth memorizing exactly: hook decisions do not bypass permission rules. Claude Code still evaluates deny and ask rules regardless of what a PreToolUse hook returns — a matching deny rule blocks a call even if the hook said "allow". The reverse also holds: a blocking hook (exit code 2) overrides allow rules. That gives you a genuinely useful pattern — allow a whole tool broadly ("allow": ["Bash"]) and register a hook that rejects only the specific commands you actually want blocked, instead of hand-maintaining an exhaustive deny list that has to anticipate every dangerous variant in advance:

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{hookSpecificOutput:{hookEventName:"PreToolUse",
    permissionDecision:"deny",
    permissionDecisionReason:"Destructive command blocked by hook"}}'
fi
exit 0

Exit code 2 is a blocking error — it prevents the tool call outright, even if the hook also printed JSON saying "permissionDecision": "allow". Any other non-zero exit is treated as non-blocking: the call proceeds through the normal permission flow as though the hook hadn't run at all. That distinction between "exit 2" and "any other failure" is easy to get backwards under a deadline, and getting it backwards means a hook you wrote to block something silently does nothing.

The rule of thumb

Use permission rules for static, unconditional facts: "never let Claude read secrets/" doesn't depend on context, so a deny rule is the right tool. Use a hook for anything that depends on inspecting what a command actually contains: "block any commit that touches the production migration path" needs runtime context a name-matched rule can't express. Deterministic controls — deny rules, a hook that reliably exits 2 on a match — hold every time, regardless of how a specific request got reasoned about. A classifier or a well-behaved model only reduces how often something goes wrong; it isn't a guarantee.

None of this replaces sandboxing, and it isn't the whole threat model — prompt injection and MCP trust are their own topics. But precedence order, protected/critical paths, and the hook-vs-rule interaction are the three things that most often produce a security policy that looks correct on paper and doesn't actually hold. I wrote up the fuller picture — sandbox scope, MCP trust, managed settings, incident response — at Claude Code Sandboxing and Security.

How Claude Code Actually Works: The Agentic Loop, Not Autocomplete

Hamid Ahmadian — Thu, 20 Aug 2026 21:34:42 +0000

Autocomplete predicts the next few tokens from the file you're looking at. Claude Code does something structurally different: it runs a loop — decide what to do, do it with a real tool, look at what actually happened, decide what to do next — until the task is done or it needs you. Here's what that loop actually looks like, tool call by tool call.

Autocomplete vs. an agent

	Inline autocomplete	Claude Code (agentic)
Input	Current file, cursor position	Your request, plus whatever it chooses to read
Action	Predicts next tokens	Chooses and executes tools: read, search, edit, run commands
Feedback	None	Sees command output, test results, errors — and reacts
Scope	One file, one cursor	Any number of files, your terminal, your git history
Stops when	It emits a suggestion	The task is verified done, or it needs your input

The difference that matters is the feedback loop. Autocomplete has no way of knowing if the code it suggested even compiles. Claude Code can run pytest, see a failure, read the traceback, fix the function, and re-run the tests — without you doing anything in between.

The loop, concretely

Every task cycles through three phases:

Gather context — read a file, grep for a symbol, check test output
Take action — edit a file, run a command, stage a commit
Verify — did the edit apply, did the tests pass, did the command exit 0

Given "fix the failing tests," a plausible sequence:

1. Bash    -> run the test suite, see what fails
2. Read    -> open the file the failing test exercises
3. Grep    -> find other callers of the broken function
4. Edit    -> apply the fix
5. Bash    -> re-run the tests
   still failing?  -> back to step 2
   passing?        -> report what was wrong and what changed

Nothing here is scripted — it's what emerges from feeding each tool result back into the next decision. That's the mechanical definition of "agentic": the next action is a function of the last observation, not a fixed script.

Two details explain behavior that otherwise looks mysterious. Edit requires a prior Read — it won't blindly rewrite a file it hasn't looked at this conversation. And Edit is exact-string replacement, not a diff or regex — if the snippet it's trying to match isn't verbatim present, the edit fails outright rather than silently applying something close-enough.

Permission modes: the safety/autonomy dial

Handing a model shell access is powerful and genuinely risky, so Claude Code gates it with permission modes:

Auto — reads, edits, and shell commands run without prompting; a separate classifier model reviews actions in the background and blocks risky categories (force-pushes, prod deploys, curl | bash). Default on Pro/Max/Team.
Manual — asks before every edit and command. Default on Enterprise.
Accept edits — reads and file edits run free; good for fast iteration you'll review with git diff afterward.
Plan — research and propose, but zero edits until you approve.
Bypass permissions — nothing gated, ever. Isolated containers only, never your primary machine.

The dimension that actually matters is reversibility. A file edit is cheap to review and cheap to undo — Claude Code snapshots files before editing specifically so you can revert with /rewind. A force-push or a production migration is a different category entirely, which is why even the most permissive modes still gate that class of action separately.

Where it remembers things

Sessions don't share memory by default — each one starts with a fresh context window. What persists is whatever you put in a CLAUDE.md at your project root (read at the start of every session), plus whatever Claude saves to auto-memory as it learns your project. If you want it to reliably know "we use pnpm, not npm," write it down — don't rely on having mentioned it three sessions ago.

I wrote a longer, interactive version of this — with a walkthrough diagram of the loop, the full permission-mode reference, and a practice quiz — here: Claude Code Fundamentals