Claude Code Hooks

Claude Code fires hooks at tool-call boundaries. A hook is a shell command that receives a JSON event on stdin and, for blocking hooks, decides via its exit code whether the tool call proceeds. This is the only mechanism that structurally stops a behavior, a prose rule in CLAUDE.md is a suggestion the completion drive can override; a hook is a wall.

When a hook is the right tool (and when it isn't)

Write a hook when a rule keeps getting violated even though it's already written down. The tell: you added the prose rule, it read clearly, and the behavior recurred anyway, because at the moment of action, attention is 100% on "get the thing done" and the reminder loses. That recurrence is the signal to move the rule from prose (advisory) to a hook (enforced). Governance rule of thumb: Tier-0 irreversible action + only prose, no hook → it should be a hook. (Tier-0 here = an action whose damage cannot be undone from inside the session: destroying uncommitted work, pushing secrets to a remote, deleting files, publishing something outward. The test is reversibility, not severity.)

Do not reach for a hook when: the rule has never actually recurred (don't pre-build guards for hypothetical mistakes, cost with no proven benefit), or the "rule" is a judgment call with no mechanical signature (a hook can only match tokens/patterns; it can't judge whether a design is good).

If the symptom is “it keeps reviewing / waiting / retrying,” do not assume the answer is another hook. First complete the Loop Contract in rule 7 and read pitfall #36. The loop may be created entirely by an agent repeatedly applying a prose rule.

Hook types and what the exit code means