Independent AI intelligence Two editions daily · ET
Fervor AI

Analysis · November 19, 2026 · concept

Claude CodeClaude Code hooksclaude-codeagent-securityagent-harnessmcp

Claude Code Safety Hooks Fail Open by Default. One Setting Makes Them Actually Block.

A crashed or missing policy script lets every tool call through unless you say otherwise. Here is how onFailure: "block" works, a two-minute test to prove it, and what it still won't cover.

Most safety checks for coding agents are tested on the day they work. Almost nobody tests the day they break.

That gap matters more than it sounds. A team writes a small script that inspects every shell command Claude Code is about to run and refuses anything that touches production. They wire it in, watch it refuse a scary command once, and move on. Months later someone renames the scripts folder. The check stops running. Nothing complains loudly, and every command goes through.

That is not a hypothetical failure mode invented for this article. It is the documented default. Claude Code's own hooks reference says that on most events, when a hook fails or times out, Claude Code still carries out the action, and "a policy hook with a wrong path or a crashing script then lets everything through."

There is a fix, and on November 18 it got wider. Claude Code 2.1.328 extended the "onFailure": "block" setting to hooks that call a tool on an MCP server. The result is simple to state: a check that opens when it breaks is a suggestion, and one field turns it back into a gate.

First, what a hook is

Claude Code is Anthropic's command-line coding agent. A hook is a check you attach to a moment in its work. "Before any tool runs" is one such moment (the PreToolUse event). "When you submit a prompt" is another (UserPromptSubmit).

When that moment arrives, Claude Code hands your hook a JSON description of what is about to happen, such as the exact shell command. Your hook decides. The reference lists five kinds:

  • Command hooks run a script on your machine.
  • HTTP hooks post the JSON to a URL.
  • MCP tool hooks call a tool on an MCP server you have configured. MCP, the Model Context Protocol, is the standard way agents talk to outside tools.
  • Prompt hooks and agent hooks ask a model to judge.

The first three are the ones people use as hard policy, because they run your logic instead of a model's opinion.

How a hook says "no", and how it accidentally says "yes"

A command hook signals its decision through its exit code, the number a program returns when it finishes. On PreToolUse, exit code 2 blocks the tool call. Exit code 0 lets the hook return a JSON decision.

Any other exit code is treated as a "non-blocking error". So is a script that never starts, prints broken JSON, or runs past its timeout. Non-blocking means the action goes ahead and you get a small hook error notice in the transcript.

The docs list exactly what counts as a failure:

  • Can't start: the script or executable doesn't exist.
  • Exit code other than 0 or 2, even if the hook printed JSON that says "allow".
  • HTTP error: the connection fails or the response isn't a 2xx status.
  • Timeout: the hook reaches its timeout. The default is 600 seconds for command, HTTP and MCP tool hooks on most events.
  • Invalid output: JSON that can't be parsed or fails validation.

Read that list as an attacker would, or just as an unlucky Tuesday would. A typo in a path, a Node version bump that breaks one import, a policy server that is down for maintenance. Each one turns your gate into an open door.

The docs even warn about the first one directly: watch for the error notice on a policy hook's first run, "because a mistyped path in settings.json means the hook never runs."

The switch: onFailure

onFailure is an optional field on a hook. It takes "continue" or "block". With "block" set, a failure does what exit code 2 would have done on that event. A failed PreToolUse hook blocks the tool call. A failed UserPromptSubmit hook blocks the prompt. On PermissionRequest (the moment Claude Code would ask you to approve a tool), it denies the request.

The version history is worth knowing because it decides what you can use today:

  • Command and HTTP hooks gained onFailure in Claude Code v2.1.295, per the hooks reference.
  • MCP tool hooks gained "onFailure": "block" in v2.1.328, which reached npm on November 18 at 23:09 UTC. The changelog entry reads: "a hook whose call fails blocks the action."
  • As of this morning, the npm package tags 2.1.328 as latest while the stable tag still points at 2.1.311. So the command-hook version works on stable, and the MCP version needs the latest build.

One honest wrinkle: when I read the hooks reference for this piece, it still described onFailure only for command and HTTP hooks, and the MCP tool hook section listed only server, tool and input. The changelog is ahead of the docs. Treat the MCP version as real but freshly shipped, and test it yourself.

Put this into practice

This takes about ten minutes, most of it reading your own settings.

1. Check your version. Run claude --version. You need 2.1.295 or later for command and HTTP hooks, and 2.1.328 or later for MCP tool hooks.

2. Find every hook you treat as a gate. Look in ~/.claude/settings.json, your project's .claude/settings.json and .claude/settings.local.json, any hooks your installed plugins ship, and any managed settings your company deploys. The ones that matter are PreToolUse, PermissionRequest and UserPromptSubmit hooks whose job is to say no.

3. Add the field. A PreToolUse hook that checks Bash commands looks like this once it fails closed:

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

4. Break it on purpose. This is the step people skip, and it is the whole point. The docs describe the test: leave check-command.js missing, then ask Claude to run a harmless command like ls. With the field set, Claude Code blocks the call and the error includes failed; blocking because onFailure is "block". After a timeout the message says timed out instead. Without the field, the same missing script is a non-blocking error and ls runs.

If you see ls output, your gate is still open. Fix that before anything else.

5. Return decisions with exit 0 or exit 2, nothing else. With "block" set, a stray exit 1 now stops work. That is the behavior you asked for, so make sure your script only uses 1 when something really broke.

6. For MCP-based checks, add the same field and test the same way. If your policy lives on an MCP server (a central "is this allowed?" service, for example), the hook names the server and tool:

{
  "type": "mcp_tool",
  "server": "policy",
  "tool": "check_command",
  "input": { "command": "${tool_input.command}" },
  "onFailure": "block"
}

Then stop the server and ask for ls again. You want a refusal, not a listing.

The edges you should know about

The setting is narrow on purpose, and the docs are clear about where it does nothing.

Some events ignore it. Stop (Claude finishing a reply), SubagentStop, TaskCompleted and TeammateIdle hooks are excluded, because exit code 2 on those events sends Claude back to keep working, and Claude can't repair a hook that won't run. Background hooks that set async or asyncRewake are excluded too.

MCP hooks don't exist at launch. SessionStart at startup and every Setup event fire before your MCP servers are connected, so Claude Code skips their MCP tool hooks without calling the tool. For anything that must happen at session start, the docs say to use a command hook.

An MCP tool that reports an error is a separate case. The reference says a tool that returns isError: true (the MCP way of saying "I failed") produces a non-blocking error. It does not yet say whether onFailure: "block" changes that. Until it does, have your policy tool return an explicit deny decision rather than an error when it wants to refuse, and test the error path yourself.

One path already fails closed. On PreToolUse, if Claude Code can't read an MCP tool's answer at all (an oversized reply, for example), it refuses the tool call the hook was checking. That's good, and it's easy to mistake for the general rule. It isn't.

Blocking has a cost. A hook that times out once a week used to be invisible. Now it stops a session. If your policy script calls the network, give it a sensible timeout instead of the 600-second default, and log its failures somewhere you will actually read.

A hook that never runs can't fail. If your matcher or if condition doesn't match the tool call, the hook is skipped, not failed, and onFailure never comes into play. Test the match as well as the failure.

It is per hook, not per project. There is no single "fail closed everywhere" switch in what I read. Every gate needs its own line.

Why this is the right default to change

There is a reasonable argument for the fail-open default. Most hooks are not gates. They format code, post a Slack message, write a log line. If any of those broke and froze your agent, you would turn hooks off entirely. Defaulting to "keep working" protects the common case.

The trouble is that the same default covers the uncommon, important case, and it does so silently. A formatter that fails costs you a messy diff. A policy check that fails costs you the policy.

That's the useful way to think about every safety check you hand an agent, in Claude Code or anywhere else: a check is defined by what it does when it breaks. Asking "does my hook refuse dangerous commands?" is half the question. The other half is "what happens when my hook can't answer?"

What it won't do for you

Be honest with yourself about what onFailure buys.

It doesn't make a bad policy good. If your script allows rm -rf when it shouldn't, failing closed on crashes changes nothing.

It doesn't stop someone with write access to your settings from deleting the hook. Managed settings are the place for rules that individual developers shouldn't be able to remove.

And it doesn't replace the permission system. Without the field, the docs say a stalled hook simply leaves the call in the normal permission flow, so "don't count on a stalled hook to act as a gate." With "onFailure": "block" on a supported hook and event, a timeout blocks instead. That's the whole trade, and it only applies to the hooks you mark.

Your move

Open your settings file and count the hooks whose job is to say no. For each one, add "onFailure": "block", rename its script for thirty seconds, and ask Claude to run ls. If it refuses, rename the script back and you're done. If it runs, you just found a gate that was never closed, and it cost you half a minute instead of an incident.

Sources: Claude Code changelog, 2.1.328 · Claude Code hooks reference · Block the action when a hook fails · npm: @anthropic-ai/claude-code. Docs and changelog read November 19, 2026, against Claude Code 2.1.328.