D3 · Claude Code › Cluster 6 · Hooks

6.4 · Blocking & Decision Control

exit 2 · deny · approve

CONCEPT Two ways to say "no": exit 2, or a JSON decision

Blocking is the heart of guardrail hooks. There are two mechanisms, and the exam tests both:

CONCEPT PreToolUse uses permissionDecision; others use decision

PreToolUse is special: it returns a hookSpecificOutput object with a permissionDecision of allow, deny, or ask, plus a permissionDecisionReason:

permissionDecisionEffect
"allow"Skip the interactive prompt — but deny/ask rules from settings still apply
"deny"Cancel the tool call; send the reason to Claude
"ask"Show the normal permission prompt to the user

Other events (PostToolUse, Stop, SubagentStop, UserPromptSubmit) use a top-level {"decision": "block", "reason": "…"} instead. And any event can set the universal {"continue": false, "stopReason": "…"} to halt Claude entirely.

⚠️ Hooks can tighten but not loosen. A hook returning "allow" does not override a deny rule in your permission settings — deny rules always win. But a PreToolUse hook returning "deny" blocks the tool even in bypassPermissions mode, because PreToolUse runs before the permission check. This is how you enforce policy users can't skip.

DIAGRAM How PreToolUse resolves

flowchart TD T["Claude requests a tool"] --> HK["PreToolUse hook runs"] HK --> D{"permissionDecision?"} D -->|"deny (or exit 2)"| NO["🔴 Tool blocked
reason → Claude
(wins even in bypass)"] D -->|"ask"| ASK["🟠 Show permission prompt"] D -->|"allow"| RULES{"deny rule in settings?"} RULES -->|"yes"| NO RULES -->|"no"| GO["✅ Tool runs
prompt skipped"] classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class GO ok; class ASK gate; class NO bad;

CODE Deny a tool with structured JSON

Instead of exit 2, this hook prints a PreToolUse decision. "deny" cancels the call and returns the reason to Claude so it can adjust.

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive rm blocked by policy hook"
    }
  }'
  exit 0            # JSON path uses exit 0, NOT exit 2
fi
exit 0              # no decision → normal permission flow
For a Stop hook that forces more work, return {"decision": "block", "reason": "Tests still failing — keep going"}. Guard against loops by checking stop_hook_active and exiting early when it's true.

TRADE-OFFS exit 2 vs. permissionDecision JSON

✅ exit 2 + stderr

  • One line to block; stderr is the reason
  • Great for quick guardrails and Stop-continuation
  • No JSON to assemble or validate

✅ permissionDecision JSON

  • Three outcomes: allow / deny / ask
  • Can also rewrite input or add context in one object
  • Only PreToolUse uses this shape — others use decision

EXAM TRAPS

Trap: "A hook's allow overrides a deny rule." → It doesn't. Deny rules from any settings scope always win; hooks can tighten, not loosen.
Trap: Using permissionDecision on a PostToolUse or Stop hook. → Those use top-level {"decision":"block","reason":…}. permissionDecision/allow/deny/ask is PreToolUse-only.
Trap: "bypassPermissions mode skips PreToolUse deny." → No — a PreToolUse deny blocks even in bypass mode, since the hook runs before the permission check.
Trap: A Stop hook that blocks forever. → Claude Code caps consecutive Stop blocks (default 8). Check stop_hook_active and exit 0 to let Claude stop.

PRACTICE

Q1 · Which field/values does a PreToolUse hook use to decide a tool's fate?

hookSpecificOutput.permissionDecision = "allow", "deny", or "ask", with a permissionDecisionReason. Or simply exit 2 to block.

Q2 · Can a hook force a tool through despite a settings deny rule?

No. Returning "allow" skips the interactive prompt but never overrides a deny rule. Hooks can tighten restrictions, not loosen them.

Q3 · How do you make Claude keep working after it tries to stop?

A Stop hook returns {"decision":"block","reason":"…"} (or exits 2 with stderr). The reason becomes its next instruction. Guard against loops with stop_hook_active.