Claude Code Hooks Fail Open by Default: A Missing Script, a Timeout or Exit 1 Lets the Action Through — Using onFailure: "block" from v2.1.295

Many people treat a hook as a security gate that "guarantees a Block," but the official hooks documentation is explicit: only exit code 2 blocks an action by itself. Any other non-zero exit does not block; it just shows a hook error line in the transcript. That means that when a guard script breaks, the default outcome is to let the action through. v2.1.295, released October 8, 2026, adds onFailure: "block" to close exactly this hole.

The default is fail-open: what lets an action through

According to the official hooks documentation, none of the following blocks a PreToolUse call:

• A missing or non-executable script: an exit code like 127 is treated as a non-blocking error. The documentation itself warns that a mistyped path in settings.json leaves the gate silently disabled.
• A timeout: when a command, http or mcp_tool hook times out, the tool call proceeds through the normal permission flow. The default timeout for these is 600 seconds, 30 seconds for prompt hooks and 60 seconds for agent hooks.
• Exit code 1 or any other non-zero value: the usual Unix failure code is only a warning here; the documentation says to use exit 2 if the hook is meant to enforce a policy.
• HTTP hook trouble: a non-2xx status, a connection failure, or a 2xx with a non-JSON body are all non-blocking errors. An HTTP hook cannot block on status code alone; it must return a 2xx JSON body with the decision fields.

onFailure: "block" in v2.1.295

The release notes describe it this way: command and HTTP hooks can be set to block the action, instead of letting it through, when the hook cannot start, times out, or exits with an unexpected code. A test published by Developers Digest on October 9 ran six configurations through claude -p on v2.1.295, changing only the PreToolUse hook: with nothing set, both a missing script and a timeout let the command run; with "onFailure": "block" both were blocked, while a working guard still allowed safe commands.

That write-up also states the scope: it matters only for events that can block, such as PreToolUse, UserPromptSubmit and Stop, and prompt, agent and MCP tool hooks are not covered. The configuration below follows that article's example (the page of the official hooks documentation I could read does not show this key, so confirm with the official docs or claude Plugin validate before relying on it):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard.sh",
            "timeout": 5,
            "onFailure": "block"
          }
        ]
      }
    ]
  }
}

The guard script has to fail closed too

onFailure alone is not enough. If a script finishes but exits 0 because some command inside it failed, Claude Code sees a successful allow. The Developers Digest author found that a guard without error handling, on a machine without jq, exited 0, which would have let rm -rf through. The sturdier pattern is to make any unexpected error exit 2. Below is a sketch written on that principle (the matching rule is deliberately crude and only shows the flow):

#!/usr/bin/env bash
set -euo pipefail
trap 'echo "guard crashed" >&2; exit 2' ERR
cmd=$(jq -r '.tool_input.command')
if printf '%s' "$cmd" | grep -Eq 'rm +-rf +/'; then
  echo "blocked: destructive rm" >&2
  exit 2
fi

Here trap ... ERR turns a failure such as a missing jq into exit 2, while a grep inside an if condition that finds no match returns 1 without firing the trap.

Don't set everything to block

Failing closed has a cost: if the HTTP endpoint your guard depends on goes down, every Bash call is blocked, and a convenience hook such as a formatter or notifier does not need to stall a whole session when it breaks. The following is my recommendation, an inference rather than official policy:

• Set onFailure: "block" only for irreversible or abusable actions (deletes, pushes, credential exfiltration).
• Pair it with a short timeout. The official default is 600 seconds, so a hung guard can make an action wait up to ten minutes.
• A regex guard is one layer; combine it with a Sandbox or deny rules.

Related fixes in the same weeks

v2.1.294 (October 8) fixed prompt and agent hooks written as instructions (for example "Block commands that…") letting through what they should block, and improved how prompt hooks on Stop and SubagentStop are judged so Claude is less likely to stop early. A summary of the earlier v2.1.288 notes also mentions that a PreToolUse hook skipped because of a matching failure now blocks the call (see the original notes for details). With several "the gate didn't hold" fixes landing within one month, it is worth re-testing your own hooks.