Correction, October 13: Blocking depends on the hook event. A hook that runs after a tool call cannot undo it, and this setting has no effect on background command hooks.

A broken guardrail hook can let an action proceed even though you expected a check. Claude Code 2.1.295 adds an option to stop before-action events when that check fails. According to the Claude Code changelog, command and HTTP hooks, which run scripts or call web services, now accept onFailure: "block". For an event that can block, such as PreToolUse, a failed hook stops the action. Failures include a missing command, a timeout, output in a format Claude Code cannot use, or a web connection or response error.

What a hook is, and why failure matters

A hook is a small script or web request that Claude Code runs at set moments, such as before it executes a shell command or edits a file. Builders use hooks to refuse changes to a .env file that holds secrets, reject a destructive command, or log every action.

Set onFailure: "block" explicitly on hooks that must stop unsafe actions. The default is "continue", which lets a failed check proceed through the normal permission flow. This setting does not apply to background command hooks or the Stop, SubagentStop, TaskCompleted, and TeammateIdle events.

Configure blocking and test a failed check

Add onFailure: "block" to any hook whose job is to say no. Use the hooks reference to place it inside the command or HTTP hook entry in your settings. To prevent a tool call, use a before-action event such as PreToolUse. A PostToolUse hook runs after the tool and cannot undo its action.

Then test the failure path on purpose:

  1. In a disposable project, pick a PreToolUse hook that checks shell commands.
  2. Break it deliberately: point it at a script path that doesn’t exist.
  3. Ask Claude Code to run a harmless command that hook normally covers.
  4. Confirm the action is blocked, and that you can see why.

A broken blocking hook stops work until you repair it. Choose that behavior where an unchecked action would expose secrets or change production data. For logging, decide whether missing a log must stop the action, rather than treating all logging hooks alike.

The same release warns when claude plugin install or enable writes to a settings file Claude Code does not load. Installing or enabling a plugin in that file will not activate it.

End of article