Claude Code Hook Failures: onFailure Block Tested

Claude Code 2.1.295 added onFailure: "block" for command and HTTP hooks.¹ Without it, on most events, a hook that fails, times out or never starts lets the action go ahead.²

In my tests, 2.1.295 and 2.1.296 blocked those failures. Builds 2.1.294 and 2.1.287 ignored the setting.

What You'll Learn

• What onFailure is and which hook types support it
• How I tested it, and what ran on which version
• The full result tables for UserPromptSubmit hooks and Bash tool hooks
• Three behaviors worth knowing, including a blind spot for JSON fragments that follows from the docs
• A small guard script and a settings file you can copy
• What the field does not cover

What onFailure does

onFailure is a field on a hook definition in Claude Code settings. It accepts "continue", the default, or "block", and the docs list it for command and http hooks only.²

Anthropic's changelog entry for version 2.1.295, dated October 8, 2026, reads: "Added onFailure: "block" for command and HTTP hooks: a hook that can't start, times out, or exits with an unexpected code blocks the action instead of letting it through".¹

The problem it solves is stated plainly in the hooks reference: "On most events, when a hook fails or times out, Claude Code still carries out the action, so a policy hook with a wrong path or a crashing script lets everything through."²

That is a fail-open design. In my view it suits a notification hook, and it is a poor fit for a hook whose job is to say no.

The docs count five things as a failure: a command that can't start, an exit code other than 0 or 2, an HTTP connection error or non-2xx status, a timeout, and invalid output. Plain-text stdout from a command hook is explicitly not a failure.²

With block set, the failure does what exit code 2 does on that event, except on PermissionRequest, where it denies the request. A failed PreToolUse hook blocks the tool call, and a failed UserPromptSubmit hook blocks the prompt.²

For how hooks and approval prompts fit together in the Claude Agent SDK, see our human-in-the-loop guide. For the plugin-side equivalent, see the .catch note in our Claude Code mods use cases post.

How I tested it

I installed four builds from npm into separate folders: @anthropic-ai/claude-code at 2.1.296, 2.1.295, 2.1.294 and 2.1.287. Each reports its version with claude --version.

The registry shows 2.1.287 published on October 1, 2026, 2.1.294 on October 8, 2.1.295 on October 8 and 2.1.296 on October 9.³ The two oldest builds predate the release that added the field, so they work as controls.

As a cross-check, the text blocking because onFailure appears in the 2.1.295 and 2.1.296 binaries and in neither of the two older ones.

Each case ran claude -p with a settings file passed through --settings, on Linux x64 with Node v22.22.0. Every hook in the matrix had a 3 second timeout.

Hook scripts were tiny Node files: one exits 0, one exits 1 after writing to stderr, one exits 2, one sleeps for 30 seconds, one prints plain text, and several print JSON-like output of different shapes. One more case points at a script path that does not exist, and one uses an HTTP hook aimed at a closed port.

Two event types, because they fail in different ways:

• UserPromptSubmit. The hook runs before the model processes the prompt.² A blocked prompt returns the text UserPromptSubmit operation blocked by hook. A passed prompt gets a normal reply.
• PreToolUse on Bash. I asked the model to run touch <marker file> with --allowedTools Bash, so no permission prompt got in the way. Then I checked two things: whether the marker file existed afterwards, and what the tool_result in the JSON stream said.

The marker check depended on the model copying the file path correctly. That is why the tool_result is the cross-check.

A first pass where the marker check gave wrong answers came from my test setup, so I discarded it.

Here is what ran where. The full matrix ran on 2.1.296 and 2.1.287, except the allow-decision and exit-2 Bash rows, which ran on 2.1.296 only.

On 2.1.295 and 2.1.294 I ran shorter sets.

For 2.1.295, the release that added the field, that was six UserPromptSubmit behaviors and four Bash behaviors, one run each, plus the can't-start case below. For 2.1.294, the closest build before the change, it was eight UserPromptSubmit behaviors and the Bash cases for a missing script, exit 1 and a timeout.

Each UserPromptSubmit case on 2.1.296 and 2.1.287 ran once in the matrix, except the JSON-shaped cases at the bottom of the first table, which ran two to five times. The Bash results come from the corrected test script, which ran each case twice with the same result both times, except the two cases marked as one run.

npm install @anthropic-ai/claude-code@2.1.296
claude -p "say hi" --settings ./settings.json --output-format stream-json --verbose --include-hook-events < /dev/null
claude -p "Use the Bash tool to run exactly this command and nothing else: touch /tmp/marker" --settings ./settings.json --allowedTools Bash --output-format stream-json --verbose --include-hook-events < /dev/null

Results at a glance

The grid below shows every row of the two tables.

Teal means the hook stopped the prompt or the command, orange means a failure got through, amber means plain text, which the docs do not count as a failure, and grey means the case passed as it should or I did not test it.

The next two sections carry the same data as tables.

Cells are transcribed from the saved output of my test runs on October 13, 2026, and checked against it. The cells marked "not tested" are cases I did not run on 2.1.287. Builds 2.1.295 and 2.1.294 ran shorter sets and matched 2.1.296 and 2.1.287.

Results: UserPromptSubmit hooks

A UserPromptSubmit hook is the quickest way to see the field work, since a blocked prompt stops before the model answers. "Passed" means the model answered. "Blocked" means the hook stopped the prompt.

The "valid JSON, then exit 1" row matches the docs. With block set, an exit code other than 0 or 2 counts as a failure even when the hook printed valid JSON.²

The Bash table below has the version that prints an allow decision.

The schema row used {"decision":"maybe"} and, in a second variant, an additionalContext value of 5. The hook outcome in the event stream was error in both, and both blocked under block.

The {not json} row is a parse failure rather than a schema failure. It also reported error and blocked.

Results: hooks on Bash tool calls

This is the case that decides whether a command runs. "Ran" means the marker file existed and the tool result was a success. "Not run" means no marker file and a tool result carrying the hook error.

When it blocks, the error text is specific. For the missing script it read PreToolUse:Bash hook error: [node .../missing.js]: failed; blocking because onFailure is "block", followed by Node's own stack trace.

For the sleeping script the word failed was replaced by timed out. That is the wording the docs promise.²

The missing-script rows use node with a script path that does not exist, so Node starts and then exits with code 1. That matches the docs' own test, which leaves the script missing.²

The docs list a missing script or executable as examples of a hook that can't start.² I also ran a nonexistent command path, on Bash only, one run each. Run through the shell, it exited with code 127.

For the nonexistent command path, the command was not run under block on 2.1.296 and 2.1.295, and it ran under block on 2.1.294 and 2.1.287. With the default setting on 2.1.296 it ran.

The tool_result text from a real run on October 13, 2026, rendered as an image from the captured output. The marker file was not created.

The version columns are the ones to take away. On 2.1.295, every case I ran matched 2.1.296.

In the 2.1.287 cases I ran, the block setting had no effect. In the Bash cases I re-ran on both older builds, the output never mentioned onFailure and stderr was empty.

On 2.1.294, the UserPromptSubmit cases for a missing script, exit 1, a timeout, a schema error, {not json} and a refused HTTP connection all passed with block set. Exit 2 still blocked. The Bash cases for a missing script, exit 1 and a timeout all ran.

If your team shares a settings file and some people are on an older build, such as the two I tested, the file looks safe there and is not.

Three behaviors worth knowing

JSON fragments count as plain text. The hooks reference says a non-async command hook's stdout is parsed as JSON when the whole output is a single JSON object.² Output that does not start with {, or starts with { but does not end with }, is plain text.

Output that starts with { and ends with } but is not valid JSON is a parse failure.²

The docs add a separate rule for several lines that each parse as JSON on their own, which I did not test.²

My results follow the single-object rule on UserPromptSubmit. With block set on 2.1.296, {not json} was blocked in both of its runs. {not json passed in all five of its runs, and {"a":1, passed in both of its runs.

So a UserPromptSubmit hook that prints a fragment of its decision and still exits 0 gets through. That matches the documented rule, but it is easy to miss. Have the script exit non-zero on every error path, and let onFailure handle the rest.

A blocked prompt still exited 0 in my claude -p runs. When a UserPromptSubmit hook blocked a prompt, claude -p still exited with 0 in my check. That held for an exit 1 hook under block and for an exit 2 hook.

Classmethod's developer blog saw exit code 0 for a blocked prompt too, with an exit 1 hook, in its write-up of the same release.⁴ In CI, read the output rather than the exit status.

A default timeout can be long. The docs give 600 seconds as the default for command, HTTP and MCP tool hooks, lowered to 30 seconds on UserPromptSubmit and the two model-switch events, and to 10 on MessageDisplay.² I set 3 seconds in the matrix and 5 seconds in the guard test below.

A guard script that fails closed

Here is a small PreToolUse guard. It denies rm -rf on purpose with exit 2 and lets everything else through. If its input is not valid JSON, the script throws and exits 1, and under block an exit 1 stops the call, as the tables above show.

let raw = "";
process.stdin.on("data", (chunk) => (raw += chunk));
process.stdin.on("end", () => {
  const input = JSON.parse(raw);
  const command = (input.tool_input && input.tool_input.command) || "";
  if (/\brm\s+-rf\b/.test(command)) {
    process.stderr.write("Blocked: rm -rf is not allowed here\n");
    process.exit(2);
  }
  process.exit(0);
});

The regex is a demo. It misses variants such as rm -fr and rm -r -f, so treat it as a starting point. Save it as .claude/hooks/check-command.js and point a project .claude/settings.json at it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node",
            "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/check-command.js"],
            "timeout": 5,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

I ran both files on 2.1.296 in a fresh git folder. Fed directly through Node, ls exited 0, rm -rf build exited 2 with the message, and the text not json exited 1.

Through Claude Code, a touch command ran and an rm -rf command was blocked with the script's own message. With the script renamed away, the call was blocked with the failed; blocking because onFailure is "block" text.

When I changed "block" to "continue" and renamed the script away again, the touch ran. That is the fail-open default.

What onFailure does not cover

The docs say the field has no effect on Stop, SubagentStop, TaskCompleted and TeammateIdle hooks, because exit code 2 on those events sends Claude back to work and Claude cannot repair a hook that will not run. It also does nothing for background command hooks that set async or asyncRewake.²

The field tables list it for command and http hooks only, so prompt, agent and MCP tool hooks do not document such a switch.²

I did not test any of these. I also did not test PostToolUse, where the tool has already run by the time the hook fails, nor PermissionRequest, where the docs say a failure denies the request when block is set.²

Schema errors, malformed JSON and HTTP hooks were tested on UserPromptSubmit only, and the HTTP case was a refused connection, not a non-2xx response or a slow reply.

Exit code 1 and a 30 second sleep stand in for crashes and hangs. I did not test a killed process.

Everything here ran through claude -p against the CLI's default model on one platform, and I read the JSON event stream for most cases rather than the interactive interface. The results are a sample, not a guarantee.

A rollout checklist

Our read: treat this as a short checklist rather than a policy rewrite.

1. Set "onFailure": "block" on every PreToolUse or UserPromptSubmit command or HTTP hook that denies something.
2. Keep exit code 2 for deliberate denials, and let onFailure cover the cases where the hook itself breaks.
3. Set a timeout that fits the hook. My guard ran under a 5 second timeout without trouble, far below the 600 second default.
4. Leave the script missing once, as the docs suggest, and confirm you see the blocking because onFailure text.²
5. Pin a minimum version. The field needs 2.1.295 or later,² and the two older builds I tested ignored it, with no mention of onFailure in their Bash output.
6. Plan for the downside. A broken guard now blocks the calls it matches, so ship hook changes with a test, as you would any gate.

Why it matters in practice

Here is a real-world report. A GitHub issue opened on July 26, 2026 against Claude Code 2.1.220 reports 6,865 hook_non_blocking_error entries in one session, all with exit code 127.⁵

The reporter attributes it to an unquoted project path containing a space. They say eleven PreToolUse hooks were affected, and their breakdown lists twelve scripts, one of them named verify-on-stop.sh.⁵

They counted the entries in the session transcript file, and the issue title says there was no visible signal.⁵ That is one user's report, and I did not reproduce it.

The claudeissues.com mirror shows the issue closed as not planned on September 8, 2026.⁵ I did not check why it was closed.

If the report is accurate, it shows what fail-open looks like in practice. The guards are configured, the hooks fail to launch, and the only trace the reporter found was a record in the transcript file.

For the secrets-blocking pattern this protects, see our tested Claude Code mod that blocks .env reads. For the wider plugin risk, see Plugin4Shell and coding agent hardening.

Bottom Line

A policy hook that fails open stops enforcing the moment it breaks. Since version 2.1.295, one setting covers command and HTTP hooks, with the exclusions listed above.

In my tests on 2.1.296 it held for a missing script, exit 1 and a timeout on both event types. On UserPromptSubmit it also held for schema errors, brace-wrapped invalid JSON and a refused HTTP connection.

Add it to every PreToolUse or UserPromptSubmit command or HTTP hook that denies, pin the version, and test the failure path once.

One blind spot follows from the documented parsing rule, and it held up in my test: a JSON fragment counts as plain text, so have the script exit non-zero on every error path.

References