Reading the Anthropic Claude Code hooks documentation properly

This research library uses AI-assisted source research and drafting. Linked sources support product claims; analysis and proposed exercises are our interpretation. Unless an article documents a test and its results, do not read it as a hands-on review or an independently verified benchmark.

A Claude Code hook runs at a configured lifecycle event. A command hook receives event data and can report a result or make a decision where the event supports one. The official hooks reference defines that behavior; a shell script that runs successfully is not automatically an enforcement control.

Choose the event that can enforce the requirement

For a tool call that has not run, PreToolUse can block it. A PostToolUse hook runs after the action and cannot undo it by returning an error. Exit code 2 has event-specific blocking behavior; other exit codes do not necessarily block. Structured output has its own schema and decision fields.

Keep a blocking decision synchronous. An asynchronous hook runs after the workflow has continued and cannot serve as the gate that prevented an earlier edit. Also test missing scripts, malformed input and timeouts. Do not assume that an ordinary shell failure means the tool call was denied.

Check every route to the protected state

A hook matching Edit and Write does not cover a Bash command that edits the same file. If the requirement is that a lockfile cannot be hand-edited, decide whether that is a review convention or a permission boundary. For the latter, inspect all available write paths and use stronger filesystem or sandbox controls where necessary.

A useful trial uses a disposable repository with one protected file and one ordinary source file. Test an allowed edit, a denied direct write, a shell-mediated write and a failed hook execution. After each attempt, inspect the file itself. A refusal message with a changed file is a failed boundary test.

Record the client version, hook configuration and observed result. Keep test fixtures free of real credentials or production data. Do not broaden the agent’s access just to make the hook experiment easier.

Keep maintenance visible

Store team configuration at the appropriate project scope and personal experiments at local scope. Confirm the effective configuration on another teammate’s machine before describing the rule as team-wide.

Quote shell variables, inspect how event fields enter commands, and keep blocking hooks fast. Use asynchronous work for tasks that can safely happen later, such as nonblocking reporting. A formatter may reduce review noise; a permission gate has a different requirement and must be tested as one.

Updated 21 September 2026: checked the current hook reference, removed the incomplete lockfile snippet, and clarified event, failure and alternate-write-path limits.