Claude Code Hooks: Exit 1 vs 2 and Hooks That Do Not Block

A Claude Code hook returns exit 1, yet the tool call continues. First check whether the failing check's status actually becomes the hook's final exit status. Then distinguish PreToolUse, which runs before the call, from PostToolUse, which runs after it.

The official hooks reference was checked on October 25, 2026. The table and downloadable model cover synchronous command hooks with empty stdout. They are not tests of Claude Code itself.

#Why exit 1 and exit 2 differ

Exit 2 from PreToolUse blocks the pending tool call; stderr supplies the reason. Exit 1 or 127 can instead return to the normal permission flow, depending on onFailure. Returning to that flow does not grant permission: the usual permission decisions still apply.

PostToolUse exit 2 sends stderr to Claude, but the tool has already run. Reporting a check result and preventing an operation belong at different points in that sequence. This table compares whether the tool can still be stopped; it does not reproduce differences in error presentation.

#Make onFailure explicit in hooks settings

onFailure: "block" requires Claude Code v2.1.295 or later. On Windows without Git Bash, a failing shell-form hook with onFailure unset can instead block the call. The downloadable model rejects an unset value and requires continue or block, excluding that platform-dependent default. Check the failure setting and Windows conditions against your installed version.

This illustrative .claude/settings.json shows the nesting. It blocks every matching Bash call, so it is not a configuration to paste into everyday work. The experiment does not create or apply any hook settings.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "node",
        "args": ["-e", "process.exit(2)"],
        "onFailure": "block"
      }]
    }]
  }
}

Check the matcher, event, and final hook exit status in that order to distinguish a hook that never ran, a hook that ran without blocking, and a check that happened after the operation.

#A later success can swallow the failing status

A check can exit 2 while its wrapper returns 0 from a later successful command. These POSIX shell examples use only fixed Node code: the check always exits 2 and the later command always exits 0.

# Swallows the check status. The whole script exits 0.
node -e 'process.exit(2)'
node -e 'process.exit(0)'

Exiting at the failed check preserves 2 and skips the later command. || exit $? returns that preceding failure in a POSIX shell; it is not a PowerShell recipe.

node -e 'process.exit(2)' || exit $?
node -e 'process.exit(0)'

#Compare 16 cases offline

Save hook-exit.mjs and hook-exit-demo.mjs in the same directory. Node.js is required. Starting the demo with Bun still uses Node.js for its child processes.

node hook-exit-demo.mjs
# Or, with both Bun and Node.js installed:
bun hook-exit-demo.mjs

The demo observes exit 0, 1, 2, and 127 from fixed internal code. The 127 is an explicitly returned synthetic value, not a reproduction of a missing executable. It feeds two events, four statuses, and two explicit settings into the model, then compares wrappers that preserve or swallow the status. It never executes arguments as commands, contacts a service, reads or writes settings, or calls an AI.

The output has observedExits: [0, 1, 2, 127] and wrappers: {"preserved": 2, "swallowed": 0}. The wrappers reproduce the sequence using Node child processes without depending on a POSIX shell. The labels normal-permission-flow, block, and already-ran belong to this explanation model, not Claude Code's log messages.

#Keep JSON and timeout handling outside this table

Review hooks that print valid JSON separately. Current official documentation reads valid JSON on nonzero exits too. Exit 2 retains its event-specific blocking effect; on other nonzero exits, JSON can determine the decision, except for hooks configured to block on failure. For structured decisions, consult the documented approach of exit 0 and one JSON object.

This model is an interpretation of the documentation. It does not test JSON parsing, timeouts, launch failures, async hooks, or other events. Its output cannot establish Claude Code's actual behavior or a protection guarantee. Record the event, explicit onFailure, final exit status, and untested conditions in your context handoff. If the selected connection settings also look wrong, check MCP configuration scopes.