Exit codes and JSON — what actually blocks

Lesson 9.1 got the hook onto the right event with a matcher that matches, so the handler runs. It reads the tool input, decides the command is one you never want run, prints a refusal to stderr, and exits 1 — the code every shell script on your machine uses to mean "no".

The command ran. A hook error notice scrolled past in the transcript and nobody read it.

That is not a bug in your matcher. It is the exit-code contract, and it is the one part of hooks where being nearly right leaves you a gate that is open and looks closed.

Exit 0: silence is not approval

Exit code 0 with no output means the hook has no decision to report, so the tool call continues through the normal permission flow. The hook can deny the call, but staying silent doesn't approve it. — Hooks reference

Read both halves. Exiting 0 does not wave the call through — it hands it back to the permission rules, which may still deny it or still ask you. Nor does it endorse the call, which matters when a hook's "pass" branch was meant to auto-approve something. It is declining to have an opinion. Exit 0 is also the intended code when you print JSON: use exit codes alone for signalling, or exit 0 and print JSON, one approach per hook.

The other half of exit 0 is where your diagnostics go:

Stderr from a hook that exits 0 goes to the debug log only, never the transcript, and Claude never sees it. — Hooks reference

The stdout rule: start with {, end with }

Claude Code decides whether your stdout is a decision or just text from its first and last characters, ignoring surrounding whitespace:

A JSON array is not hook output, however valid it is as JSON. Neither is an object with a log line printed after it. Where plain text then goes depends on the event: for most, it lands in the debug log and is never shown. The exceptions are UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch, where plain-text stdout is added as context Claude can see and act on. The last of those is the newest arrival — the event itself only exists from v2.1.251. Output strings are capped at 10,000 characters; anything longer is written to a file and replaced with a preview and that path.

Exit 2: the code that blocks

Exit 2 means a blocking error. On events that can block, exit 2 blocks whether or not you print JSON: even a JSON permissionDecision of "allow" can't override it. — Hooks reference

Where the message comes from decides whether your refusal is legible: "the blocking message is the reason from your JSON's blocking decision when it makes one, and your stderr text otherwise." An exit-2 hook whose JSON fails schema validation still blocks — stderr becomes the reason, and the validation failure goes to the debug log. That behaviour arrived in v2.1.214; before it, the same combination was a non-blocking error and the action proceeded, which is one more reason not to mix the two approaches in one hook.

"Events that can block" is a real restriction. A sample of the per-event table:

PermissionRequest is the row that catches people: the event whose whole subject is a permission decision ignores exit 2. You deny through its decision object.

Every other exit code, including the hook that could not start

Here is the warning the docs put in a box, and the reason your exit 1 gate let the command through:

For most hook events, exit code 2 is the only exit code that blocks through the code alone. Without valid JSON on stdout, Claude Code treats exit code 1 as a non-blocking error and proceeds with the action, even though 1 is the conventional Unix failure code. If your hook is meant to enforce a policy, use exit 2. The exception is WorktreeCreate, where any non-zero exit code aborts worktree creation. — Hooks reference

The full contract, for events using the standard decision model:

Two readings fall out. Once your JSON parses and validates, every exit code but 2 stops mattering — the JSON alone decides and the hook is not reported as an error. Exit 2 stays outside that rule: it blocks, and a validating "allow" does not rescue the call. And every non-blocking row proceeds, including the row you did not write on purpose:

A hook that can't start lands in the same non-blocking bucket. When the script path doesn't exist or isn't executable, the shell exits with a code like 127 […] When you set up a policy hook, watch for this notice on its first run: a mistyped path in settings.json leaves the gate silently disabled. — Hooks reference

JSON decision control on PreToolUse

PreToolUse carries most policy, and it does not use the top-level decision field the other events use:

PreToolUse previously used top-level decision and reason fields, but these are deprecated for this event. Use hookSpecificOutput.permissionDecision and hookSpecificOutput.permissionDecisionReason instead. — Hooks reference

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Writes to migrations go through review"
  }
}

"allow" is not a master key: "deny and ask rules are still evaluated regardless of what the hook returns."

"deny" and exit 2 route the same way — "a hook that blocks by exiting 2 routes the same way as deny: Claude sees the stderr message as the denial reason" — so the choice is about what else you want to do. JSON reaches the outcomes an exit code cannot express: "ask" instead of a flat refusal, or updatedInput to rewrite the tool's arguments and let a narrowed call through. Exit 2 is the shorter road when all you have is a refusal. "defer" is honored only in non-interactive runs with -p; interactive sessions log a warning and ignore it.

On the events that keep the top-level pattern — PostToolUse, Stop, UserPromptSubmit — the only value decision takes is "block". There is no "approve": you let an action proceed by omitting the field or exiting 0 with no JSON, which is the shape Lesson 5.2 used for a Stop hook.

When hooks disagree

Nothing stops two hooks matching the same call, and they do not take turns: matching hooks run in parallel (Lesson 9.1), so a block from one does not prevent another from running.

On PreToolUse the disagreement has a defined answer, and it is the safe one: "when multiple PreToolUse hooks return different decisions, precedence is deny > defer > ask > allow" — so a permissive hook cannot undo a strict one. Everything else about the parallelism is yours to manage. A sibling's side effects have already happened by the time another hook denies: the deny stops the tool call, not the other handler. And when two hooks return updatedInput for one tool, the last to finish wins, in an order that is non-deterministic because they ran at once. The documented advice is not to have two hooks rewriting the same input.

What a hook can tighten, and what it cannot loosen

PreToolUse hooks fire before any permission-mode check, in every permission mode, including dontAsk. A hook that returns permissionDecision: "deny" blocks the tool even in bypassPermissions mode or with --dangerously-skip-permissions. — Hooks guide

A hook deny is stronger than any mode a user can switch into. The converse does not hold: "a hook returning "allow" doesn't bypass deny rules from settings […] Hooks can tighten restrictions but not loosen them past what permission rules allow."

A hook is a ratchet and it turns one way. When you catch yourself writing one to widen what is permitted, the mechanism you want is a permission rule — Level 10.

The gate that holds

• exit 2, or JSON that validates — never exit 1, and if you print JSON, print only the JSON.
• Watch the first run. A Failed with non-blocking status code: notice is the difference between a gate and a script that never ran. Make the hook refuse something on purpose before you trust it to refuse something by accident.