TL;DR

When a Claude Code hook does not fire, run /hooks. If it is missing, the file or JSON is wrong. If it is listed, check the matcher: it is case-sensitive, must be a string and is ignored on Stop. Then check that you exit 2 or print JSON, not exit 1, and that your shell profile prints nothing.

When a Claude Code hook does not fire, run /hooks first. If the hook is not listed, Claude Code never loaded it: the documented causes include invalid JSON, hooks defined outside settings.json, or a matcher written as an array. If it is listed but does nothing, check the matcher, the event, the exit code and the shell. This guide restates what the hooks guide, the hooks reference and debug your configuration document, as read in November 2026. It is not a record of reproducing each failure.

How to tell an outage from a local problem

A command hook is a shell command that runs on your machine, so a hook that does nothing is a local configuration question first. Prompt and agent hooks call a Claude model instead, so an API problem can affect those. If the whole session is failing or slow, check status.claude.com and the Claude Code Outage Radar before touching your settings. If only one hook misbehaves, the problem is local and the steps below apply.

Symptom, likely cause and fix

SymptomLikely causeWhat to do
Hook missing from /hooksInvalid JSON, wrong file, or hooks in a standalone file or in ~/.claude.jsonPut them under "hooks" in settings.json; remove trailing commas and comments
Listed, never runsmatcher is lowercase (bash) or misspelledMatching is case-sensitive: use Bash, Edit, Write
Entry listed as invalidmatcher is a JSON arrayUse one string: "Edit|Write"
Stop hook fires every turnStop does not support matchers, so the matcher is ignoredRemove the matcher and test inside the script
JSON decision has no effectShell profile prints text before the JSON, or a field sits at the wrong levelGuard profile echo lines; nest permissionDecision in hookSpecificOutput
jq: command not found in the transcriptScript parses input with jq, which is not installedInstall jq or parse with Node or Python
Exit 1 did not blockOnly exit 2 blocks; other non-zero codes are non-blocking errorsExit 2 with the reason on stderr, or exit 0 with JSON

Did the hook load at all?

Run /hooks. It lists every hook registered for the session, grouped by event. Hooks belong under the "hooks" key in a settings file: .claude/settings.json for the project, ~/.claude/settings.json for every project. ~/.claude.json holds app state, and only plugins load a separate hooks/hooks.json. The docs say edits to settings.json take effect in the running session after a brief delay. If /hooks still shows the old definition a few seconds after you save, run /hooks again, and restart the session if it persists. A menu reading "Only hooks from managed settings run here" means your organisation set allowManagedHooksOnly.

Why does a listed hook never fire?

The debug guide calls the matcher the usual cause when a hook appears but does not fire. A matcher that contains only letters, digits, underscores, hyphens, spaces, commas and | is an exact name or a list, so "Edit|Write" works. Anything else is treated as a JavaScript regular expression, unanchored, so Edit.* also matches NotebookEdit. MCP tools are named mcp__server__tool, and mcp__memory without .* matches nothing. The docs say comma separators need Claude Code v2.1.191 or later, and that earlier versions never match one, so use | on older versions.

Stop is different: the reference lists it among the events with no matcher support, so it fires on every occurrence and a matcher on it does nothing. The same list names UserPromptSubmit, TaskCompleted and several others. Put any condition inside the hook script instead.

Exit 2 or JSON: which one blocks?

Exit 0 means success, and Claude Code reads any JSON on stdout. Exit 2 is a blocking error on events that can block, and stderr becomes the reason. Any other code is a non-blocking error: the action proceeds. Exit 1 therefore does not block. Pick one method per hook, as the hooks guide advises. The reference says that with exit 2, JSON is still read but cannot override the block, so even "allow" does not let the action through.

For a PreToolUse decision, use exit 0 and print JSON with the decision nested in hookSpecificOutput. The docs' examples parse input with jq and say to use Python or Node.js if jq is missing. This Node sketch has no jq dependency; it is an illustration written from the documented JSON shape, not a copy of an Anthropic example, and it should print the deny JSON for rm -rf build and nothing for ls. Pipe sample input into it before relying on it:

let raw = "";
process.stdin.on("data", (d) => (raw += d));
process.stdin.on("end", () => {
  const input = JSON.parse(raw);
  const cmd = (input.tool_input && input.tool_input.command) || "";
  if (/\brm\s+-rf\b/.test(cmd)) {
    process.stdout.write(JSON.stringify({
      hookSpecificOutput: {
        hookEventName: "PreToolUse",
        permissionDecision: "deny",
        permissionDecisionReason: "rm -rf is blocked by project policy"
      }
    }));
  }
  process.exit(0);
});

Register it with a matcher on Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm.mjs"
          }
        ]
      }
    ]
  }
}

permissionDecision accepts allow, deny, ask or defer; the guide says defer is for non-interactive mode with the -p flag. A hook returning allow does not override deny rules in settings, and a hook deny holds in every permission mode. Silence from a hook leaves the normal permission flow alone.

Why was the tool call denied anyway?

A denied call is not always a hook. Run /permissions to see the resolved allow and deny rules. A hook cannot loosen a deny rule, so an allow from your hook will not rescue a call that a rule blocks. The debug guide also notes that Bash rules match the literal command string, so a Bash(rm *) deny rule does not block /bin/rm. On Windows without Git Bash, a failed or timed-out PreToolUse or PermissionRequest hook can itself block the call. The reference's fixes are to install Git for Windows or set CLAUDE_CODE_GIT_BASH_PATH if Git Bash is installed where Claude Code does not find it. For a PowerShell guard hook it also describes "shell": "powershell".

Is your shell profile corrupting the JSON?

Hooks run in non-interactive shells, but Git Bash and some setups still source your profile. Anything it prints reaches stdout ahead of your JSON, Claude Code reads output that does not start with { as plain text, so the JSON is ignored, and because the hook exited 0 the transcript shows no error. Wrap profile output so it runs only interactively:

if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

How do you watch a hook run?

Start with claude --debug-file ./claude-debug.log, trigger the event and search the log for the hook lines. The hooks guide names two strings worth searching: Hook output does not start with { and Hook JSON output had unrecognized keys. Press Ctrl+O for the transcript view to see a blocking message or a hook error notice. Test a script by hand first with echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh and then echo $?. The log is private, so do not paste it anywhere.

What about Stop hooks that loop?

The hooks guide says Claude Code overrides a Stop hook after it blocks eight times in a row with no tool call from Claude in between, and that CLAUDE_CODE_STOP_HOOK_BLOCK_CAP raises the cap. The sibling guide covers the counter pattern and the /goal alternative in how to stop Claude Code from ending its turn. If instructions in a file are being ignored rather than a hook failing, your CLAUDE.md is not a control explains why only hooks and permissions enforce anything. To rule out your own configuration, start claude --safe-mode, which the CLI reference says disables CLAUDE.md, skills, plugins, hooks and MCP servers, among other customizations, for the session. Managed hooks and policy from an organisation still apply.

More practical writing for people building with AI tools is on the Lead Source blog.

Fixed? Two optional things

Check Anthropic’s status and get an alert when an incident is resolved: Claude Code status and alerts, an independent resource by Lead Source.

Official source: status.claude.com.

Written by the team at Lead Source, where the day job is lead source tracking: working out which marketing actually brings customers.