Anthropic's page describes hooks as commands, HTTP endpoints, prompts or agents that Claude Code runs at points in its lifecycle (Source 1). The useful way to think about them: your CLAUDE.md asks, a hook decides. A model can forget a rule in a long session. A script that runs before every Write call cannot.

The table is a selection from the documented list of 33 events (Source 1). The labs below use the first three plus the exit-code contract that Stop shares.

Hooks are configured in JSON under a hooks key. The same shape works in several places, and the place decides who is affected (Source 1):

Inside, each entry names an event, optionally a matcher that narrows it, and a list of handlers. A matcher on a tool event filters by tool name: letters, digits, underscores, hyphens and | make an exact list (Edit|Write); anything else is read as a regular expression; * or an empty matcher matches everything. MCP tools are named mcp__server__tool, and you need .* to match all of a server's tools. Some events, such as UserPromptSubmit and Stop, take no matcher at all.

A handler has a type. The documented types are command (run a program; input arrives on stdin), http (POST the JSON to a URL), mcp_tool, prompt (a single-turn model check) and agent (a subagent that can use tools; marked experimental). This lab uses command only, in the exec form the docs recommend: a command plus an args array, so there is no shell quoting to get wrong. Useful fields:

• timeout in seconds. Defaults are documented per handler type and event (and differ between them), so set it explicitly for anything slow.
• if: a permission-rule pattern such as Bash(git *), for tool events only. The docs call it best-effort and say to use the permission system, not hooks, for hard allow or deny rules.
• onFailure: "continue" or "block". With "block" a hook that cannot run, because the script is missing or crashes, blocks the action instead of allowing it. It needs Claude Code 2.1.295 or later.

The complete settings file for this lab, which was used in the real sessions below:

Check what is loaded with /hooks inside a session (a read-only menu) or start with claude --debug to see which hooks matched and what they returned.

In: a JSON object on stdin. Every event carries common fields such as session_id, cwd, permission_mode and hook_event_name. A tool event adds tool_name and tool_input (for a Bash call, tool_input.command; for a Write, tool_input.file_path). PostToolUse also carries tool_response, and UserPromptSubmit carries the prompt text (Source 1).

Out: the exit code is the first signal:

The alternative to exit 2 is to exit 0 and print JSON. For PreToolUse the documented shape is hookSpecificOutput with permissionDecision (allow, deny, ask or defer) and a reason; updatedInput can rewrite the call's arguments. A hook that exits 0 with no JSON means "no decision", and the normal permission flow then applies. It cannot approve a call by staying silent.

The rule: Claude may edit code, but never .env, the Maven wrapper or .mvn/. The hook reads the target path from stdin and refuses on a match. Its stderr text becomes the reason Claude sees, so write it as an instruction to the model.

Step 1: test it by hand, no Claude involved. The test script builds stdin payloads in the documented shape and prints each script's exit code, stdout and stderr. (The payloads are the author's, written to match the documented fields; they are not captured from a session.)

Each row ends with whether the exit code was the one expected, and the script itself exits non-zero if any row is wrong, which is how Chapter 25 runs it in CI. The row for the original block-destructive.sh is marked as a known weakness on purpose. Read the three protect rows: .env and mvnw exit 2 with the message, an ordinary source file exits 0 with nothing.

Step 2: prove the harness honours it. A new session in the hook-lab project, with Write and Edit allowed on the command line, so that without the hook the write would succeed:

• The hook blocked it. The tool result is the hook's own message, prefixed by the harness with the event, tool and script. No .env file exists in the project afterwards.
• Claude obeyed the reason. It reported what happened and did not hunt for another way to write the file. That is behaviour of this one run, not a guarantee.
• Notice the earlier row. Its first attempt, a Bash call to check for the file, was refused by the session's dontAsk permission mode, not by a hook. Two different mechanisms produced two different messages. The log counts both as denials.

This hook never exits 2. It exits 0 and prints a permissionDecision. The benefit shows when you need ask or updatedInput instead of a flat no.

The offline table above already has its two rows: git push prints the JSON, git status prints nothing, and both exit 0. The real session allows git push on the command line, so that the permission mode would not refuse it first:

The command never ran, the reason text reached Claude, and Claude declined to try again. Nothing was pushed, and this project copy has no remote anyway; the point is that the hook, not luck, stopped it.

Two hooks that do not block. add-git-context.sh runs on UserPromptSubmit and prints one line; plain stdout on exit 0 becomes context. audit-log.sh runs on PostToolUse and appends a timestamped tool name to a file.

The context hook, asked to quote what it was given (with no tools available to cheat with):

Claude quoted the line and noted that the harness had wrapped it in UserPromptSubmit hook success:. So the context arrives, and Claude can tell where it came from.

The audit hook needs a tool call that succeeds. Claude was asked to read the feature file:

• It logged once. After all four sessions the audit log held a single line, Bash, with a timestamp. That is the one tool call that succeeded in any of them.
• It did not log the blocked or denied calls. That matches the documentation: PostToolUse fires after a call succeeds, and denials and failures have their own events. An audit trail built on PostToolUse alone will miss attempts.
• Claude chose Bash with cat, not Read, although only Read was on the allow list; the harness let this read-only command through. I did not look into why. The lesson is general: do not assume which tool Claude will pick. Match on what you need to guard, and test.

The last two rows of the offline output are the most important ones in the chapter. The original Chapter 12 hook, block-destructive.sh, depends on jq. When jq is not on the PATH the shell prints "command not found", the variable stays empty, the pattern does not match, and the script exits 0: the destructive command is allowed, silently. A hook that fails open is worse than no hook, because everyone believes the guard is there.

The strict version checks for jq first and exits 2 if it is missing, which the last row of the output shows. Note that onFailure: "block" in the settings file would not have rescued the original: the script ran and returned 0. That option covers a missing script or a crash. A broken dependency inside a script that still exits 0 has to be handled in the script.