Hook Debugging And Recovery — Claude Code Guide

Debug hooks by layers

Hook debugging should distinguish event selection, matcher selection, handler execution, environment, and side effects. Test one layer at a time so a failed formatter is not confused with a matcher that never triggered.

Layer	Question
Event	Did the lifecycle event occur?
Matcher	Did the intended path or tool match?
Handler	Did the command receive the expected input?
Environment	Were shell, path, and permissions available?
Side effect	What changed and can it be reversed?

Hook debugging ladder

Record the event in log-only mode.
Use one known-safe path and matcher.
Replace the handler with a harmless report.
Inspect expanded arguments and environment.
Run the real handler on one test file.
Check diff and generated output.
Add blocking only after the earlier steps are stable.
Record a disable path and the next recovery action.

Diagnosis record

Documented diagnosis shape

{"symptom":"hook did not run","event":"afterFileEdit","matcher":"src/**/*.ts","observed":"no report","hypothesis":"matcher syntax differs by version","nextCheck":"inspect current /hooks output","status":"documented example"}

Recovery options

Disable the hook for the current session.
Return from blocking to log-only.
Narrow the matcher.
Use a manual command while the integration is investigated.
Remove generated side effects before retrying.
Record the version-specific behavior and open question.