Why do Claude Code hooks fail silently so often?

Because the SDK treats hook failures as non-blocking by design. Per the /concepts/hooks page in the vault: 'Production hooks fail in two ways: incorrect matchers (a hook targeting Read never fires on Grep, each tool has a unique name) and silent errors (exit code 0 when validation fails, so Claude never sees the block).' A misconfigured hook simply does not run; the tool call proceeds; the agent has no signal that anything went wrong; the policy fails open. The whole point of hooks is to be deterministic, and a silent failure is the opposite of that.

What are the four silent-failure causes I should check first?

Incorrect hooks key placement in claude_config.json (often nested in the wrong section), mismatched event name casing (PreToolUse vs pre_tool_use - the SDK is case-sensitive), non-zero exit codes swallowed without --verbose, and file permission errors on the hook script itself (forgot chmod +x). Each has a one-line fix. Walk them in order; the first one that fires is usually the cause.

What does claude --debug actually surface?

Hook registration on startup (the list of every hook the SDK has loaded, with its matcher and event), every tool-use interception (the matcher check and the decision), the subprocess exit code, and any stderr the hook wrote. If a hook does not appear in the registration list, it never loaded. If it appears but does not fire on the expected tool, the matcher is wrong. If it fires and exits non-zero with no stderr, you have an erroring-silently case.

How do I distinguish between the three failure modes?

Three distinct symptoms, three distinct fixes. (a) Registered but skipped: hook is loaded but the event/tool filter does not match. Symptom: claude --debug shows registration but no invocation on the tool. Fix: check the matcher string; 'Read' does not match 'ReadFile'. (b) Registered and erroring silently: hook runs but exits non-zero without stderr capture. Symptom: invocation shows up but the side effect never lands. Fix: explicit '2>> ~/.claude/hook.log' redirection. (c) Never registered: config parse failed. Symptom: hook missing from the registration list. Fix: validate JSON with 'jq . claude_config.json' and confirm the hooks key is at the top level.

What is the --hooks-dry-run pattern and when should I use it?

Record a real session once. Replay it with --hooks-dry-run as often as you need to validate hook logic against the exact payloads Claude would have sent, without re-running expensive tool calls or mutating state. This is the cheapest iteration loop available for hook authoring. Use it whenever you change a matcher, change the hook script, or want to confirm an existing hook would have fired on yesterday's session.

How do I prove a hook actually ran instead of just hoping?

Every hook should write a heartbeat line to a known sink, even on success. A one-line append to ~/.claude/hook.log with timestamp, event name, tool name, and decision is enough. Absence of the line is then a positive failure signal - you can grep for it after the fact. Without the heartbeat, silence is ambiguous: the hook might have run and decided to allow, or it might have never run at all. Distinguishing is impossible without explicit logging.

Why does my hook fire on the parent session but not on subagent tool calls?

Because the subagent runs in its own context with its own SDK loop. Hooks declared in the parent's claude_config.json may not propagate, depending on configuration scope and the spawn mechanism. This is structurally adjacent to the CLAUDE.md inheritance problem documented at /knowledge/subagent-claude-md-inheritance: subagents start with whatever you inject, not with the parent's ambient configuration. Test hooks in the actual context where they need to enforce, not just in the parent.

What are the standard hook exit codes and what does each mean?

Per the Skilljar Claude Code 101 Lesson 12 material: exit code 0 allows the tool call; exit code 2 denies it and routes Claude back with the stderr message; exit code 1 is treated as a hook error (the SDK logs it but typically still allows the tool to proceed). The exam-relevant distinction is 0 vs 2: 0 is permit, 2 is deny. Use 2 plus a clear stderr message for any policy violation; do not use exit 0 with a printed warning - the warning is invisible to the model.

Can I use relative paths in hook commands?

No. Per the /concepts/hooks page: 'Deterministic path handling is mandatory. The recommendation is absolute paths only in hook commands. Relative paths trigger path-interception attacks (MITRE T1574.007).' Use ${HOME} expansion or a setup script that replaces $PWD placeholders with absolute paths to share hook configs across team members. Relative paths are also a common source of silent failure - the hook fails to find the script when the working directory changes mid-session.

How does hook debugging show up on the CCA-F exam?

Under D3 (Agent Operations, 20%) primarily, with D2 overlap when the question concerns whether a hook is the right enforcement tool in the first place. Stem pattern: 'A PostToolUse hook is configured but the side effect never occurs. Three causes are listed. Which is the FIRST diagnostic step?' The right answer is always to run claude --debug or check the registration list. Common distractors: 'Restart Claude Code' (clears state but does not reveal the failure mode), 'Switch to PreToolUse' (changes the semantics, not the debug), 'Use a more capable model' (Model vs Design - irrelevant to a deterministic gate).

What is the missing-output anti-pattern the exam tests for?

Assuming a missing hook output means the hook ran successfully. It does not. A hook that crashes before writing to stdout is indistinguishable from a hook that never ran. The fix is explicit logging to a known sink so absence is a real signal. The anti-pattern is exam-relevant because the wrong answer 'no output means no problem' looks reasonable on a multiple-choice stem and is exactly the trap candidates fall into under time pressure.

Should I write hooks in shell, Python, or something else?

Anything that reads JSON on stdin and writes a meaningful exit code. Shell is fine for simple gates (path validation, regex match). Python is better when the policy needs database lookups or HTTP calls. The language does not matter; what matters is that the script is executable (chmod +x), uses absolute paths, has explicit logging, and is tested with --hooks-dry-run before going live. The Skilljar Claude Code 101 examples lean Python because the JSON parsing is cleaner, but shell with jq works equally well.

Debugging Claude Code Hooks That Fire Silently or Don't Run At All

01 · TLDR

The short version

A silent hook is the worst failure mode in agent operations: no error, no log, no signal that anything is wrong - except the side effect you depended on never happened. Three failure modes (registered-but-skipped, registered-and-erroring, never-registered) need three different fixes. Run claude --debug to see the registration list and per-invocation log. Always write a heartbeat line to a known sink so absence of the line is a positive failure signal. The exam trap under D3 is "no output means no problem" - it does not; it means you cannot distinguish a crashed hook from a skipped hook.

02 · Why this matters in production

When the deterministic gate stops being deterministic

Hooks exist because prompt-only enforcement is probabilistic. Per the /scenarios/conversational-ai-patterns scenario in the vault: "Prompt-only enforcement is probabilistic (roughly 92% in this scenario). Hooks are deterministic. They read structured state, exit 2, and route Claude back. For business-bearing guarantees (do not re-ask answered questions, do not process unverified accounts), the 8% leak from prompt-only is unacceptable." A hook that silently fails to register is even worse than prompt-only: you believe you have a deterministic gate, you do not, and the failure is invisible until an auditor catches the violation weeks later.

The most painful version of this: a PreToolUse hook designed to block refunds above $500 that never registered because the JSON config had the hooks key one level too deep. The agent processed three refunds for $750, $1,200, and $4,300 before anyone noticed. The hook script was correct. The wiring was not. There was no error message; there was just an absence of the protection the team thought it had.

03 · The mechanics

How hooks load, why they go silent, and how to diagnose each case

Per the /concepts/hooks page in the vault, the lifecycle has three steps: "Step 1: Tool Interception. Claude emits a tool_use block; the SDK extracts the tool name and input JSON. Step 2: Hook Execution. Your hook command runs as a subprocess; stdin contains a JSON object with hook_event_name, tool_name, tool_input, and optionally tool_response (PostToolUse only). Step 3: Decision Point. PreToolUse: exit code 0 (allow), 2 (deny), 1 (error)." Each of those three steps can break silently, and the diagnostic flow depends on which one.

Never registered. Symptom: the hook does not appear in the registration list when you run claude --debug. Cause: JSON parse failure, wrong key path, malformed event name. Fix: validate the config with jq, confirm the hooks key is at the top level (not nested in a comment block or wrong section), and confirm event names match the case-sensitive SDK expectation (PreToolUse, not pre_tool_use).

Registered but skipped.Symptom: claude --debug shows registration on startup, but no invocation log appears on the tool you expected. Cause: the matcher string does not match the tool name. Per /concepts/hooks: "Matcher syntax is critical. A matcher is a pipe-separated list of tool names: 'Read|Edit|Grep' fires on any of those three. The wildcard '*' matches all tools. Matchers are exact string matches; 'Read' does not match 'ReadFile'." Fix: dump the actual tool name from a debug session, copy it exactly into the matcher.

Registered and erroring silently.Symptom: invocation appears in debug log; exit code is non-zero; nothing else happens. Cause: stderr is being discarded. The hook crashed but you cannot see why. Fix: explicit "2>> ~/.claude/hook.log" redirection in the hook command string, or wrap the hook in a shell wrapper that always logs.

A minimal heartbeat-instrumented hook in shell:

#!/usr/bin/env bash
# /opt/hooks/refund-guard.sh
LOG=~/.claude/hook.log
exec 2>> "$LOG"

INPUT=$(cat)
EVENT=$(echo "$INPUT" | jq -r '.hook_event_name')
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
AMOUNT=$(echo "$INPUT" | jq -r '.tool_input.amount // 0')

echo "$(date -u +%FT%TZ) event=$EVENT tool=$TOOL amount=$AMOUNT" >> "$LOG"

if [[ "$TOOL" == "process_refund" && "$AMOUNT" -gt 500 ]]; then
  echo "Refund amount $AMOUNT exceeds policy 500" >&2
  exit 2
fi
exit 0

Three things matter about that snippet. Every invocation writes a one-line heartbeat to a known file before any decision logic - so absence of the line proves the hook never ran. The shell redirects stderr to the same log so a crash leaves a trace. The exit codes are explicit (2 for deny with a clear message, 0 for allow). With that pattern in place, the failure modes above become falsifiable: grep the log, see whether the heartbeat is there, classify the problem, fix the right thing.

For richer iteration, use the --hooks-dry-run pattern. Record one real session with --debug capturing the full stdin payloads. Replay the recorded payloads through your hook script directly, as many times as you want, without re-incurring the tool-call cost or risking state mutation. This is the cheapest iteration loop for hook authoring; treat it as the test harness.

04 · Decision rule and checklist

Seven checks when a hook fails silently

Run claude --debug. Confirm the hook is in the registration list. If not, the config did not parse - jump to step 2.
Validate the config with jq.Confirm the hooks key is at the top level and event names match the SDK's case-sensitive expectations.
Check the matcher against the real tool name. Grep the debug log for the actual tool_name on the call you expected to intercept. Exact match only.
Check file permissions. The hook script must be executable (chmod +x). Path must be absolute.
Capture stderr to a log.2>> ~/.claude/hook.log on the command string. Without this, a crash is invisible.
Write a heartbeat line on every invocation. Even on success. Absence of the line is the positive failure signal.
Iterate with --hooks-dry-run on a recorded session. Do not test against live tool calls; the iteration loop is too slow and too destructive.

05 · Common anti-patterns

Five recurring hook-debugging mistakes

Silence as success. Assuming the hook ran because nothing crashed. Cause: no heartbeat logging. Fix: heartbeat on every invocation.
Relative paths. The hook script path is relative; the working directory changes mid-session; the hook fails to launch. Fix: absolute paths always; use $${HOME} expansion if needed.
Exit 0 with a printed warning. The hook detects a violation but exits 0 with a stderr warning. The warning is invisible to the model. Fix: exit 2 to deny; the stderr message routes back to Claude.
Wrong matcher casing or substring.Matcher is 'Read' but the tool is 'ReadFile'. The hook never fires. Fix: copy the exact tool name from the debug log.
Testing only in the parent session. The hook works in the parent but does not fire on subagent tool calls because configuration scope differs. Fix: test in the actual execution context, not just the parent.

06 · CCA-F exam mapping

How this shows up on the exam

Domain: D3 Agent Operations (20%) · D2 Tool Design overlap (18%)
What is tested: Whether you can name the FIRST diagnostic step on a silently-failing hook and whether you understand the three failure modes are distinct. The exam is diagnostic, not implementation; you read the symptom and pick the cause.
Stem pattern: A PostToolUse hook is configured but the side effect never occurs. Three causes are listed. Which is the FIRST diagnostic step?
Distractor to reject: "Restart Claude Code." Clears state but does not reveal which of the three failure modes you are in.
Second distractor: "Switch from PostToolUse to PreToolUse." Changes semantics, not diagnostics. If the hook is never registered, the event name does not matter.
Third distractor: "Add more detail to the system prompt." Prompt vs Hook heuristic per ACP-T03 §6. A prompt cannot fix a wiring problem with a deterministic gate.

07 · Sources

Vault and external references

Vault: data/aeo/reports/2026-05-17-recommendations.md §Signal - source of the four silent-failure causes and the missing-output anti-pattern.
Vault: public/concepts/hooks.md §How it works - the three-step lifecycle, matcher syntax, exact-match constraints, absolute-path requirement.
Vault: public/concepts/hooks.md§What it is - "Production hooks fail in two ways: incorrect matchers and silent errors."
Vault: 99-attachements/asc-a01-skilljar-course-content/course-02-claude-code-101/lesson-12-hooks.md - Skilljar canonical exit-code semantics (0 allow, 2 deny, 1 error) and PreToolUse block-tool-call behavior.
Vault: public/scenarios/conversational-ai-patterns.md- "Prompt-only enforcement is probabilistic (roughly 92%). Hooks are deterministic." - establishes why silent hook failure is so corrosive.
Vault: public/scenarios/agentic-tool-design.md §PreToolUse and PostToolUse - canonical hook patterns and configuration examples.
Vault: public/scenarios/claude-code-for-cicd.md - headless mode and --debug flag usage in CI contexts that surface hook behavior.

Debugging Claude Code Hooks That Fire Silently or Don't Run At All.

The short version

When the deterministic gate stops being deterministic

How hooks load, why they go silent, and how to diagnose each case

Seven checks when a hook fails silently

Five recurring hook-debugging mistakes

How this shows up on the exam

Vault and external references

Adjacent reads

Hooks

CLAUDE.md hierarchy

Subagent CLAUDE.md inheritance

Related

Share this primitive