hooks-cookbook

Hooks cookbook

A hook runs on every matching event, in the user's critical path. The one rule that makes hooks safe to ship: a hook reports, but it never breaks the flow when its tooling is absent. No interpreter, no jq, wrong tool, wrong target, unreadable file -- every one of those is a clean exit 0, not an error. Earn the right to block only for a rule you are certain about, and even then translate the failure into a structured response instead of a raw crash.

Build every hook in this order: parse the event, early-return unless it is relevant, run the checker, translate the result into an advisory or a block. Sections 1-3 are the contract; the recipe gallery applies it.

When to use

• Authoring a new hook (PreToolUse, PostToolUse, SessionStart, UserPromptSubmit, Stop, or a git pre-commit script).
• Turning an ad-hoc checker script into something safe to run on every edit.
• Deciding whether a check should warn or hard-block, and wiring the response.

When not to use

• Wiring an existing, finished hook -- that is a settings.json edit, not authoring. See examples/hooks/README.md.
• A one-off manual check you run by hand. Hooks are for the automatic path.

---

1. The contract you are coding against

A hook is a command. Claude Code sends it a JSON event on stdin and reads its exit code and stdout.

Stdin fields you will use (all events carry session_id, cwd, hook_event_name):

Event	Key fields on stdin
PreToolUse	tool_name, tool_input (args the tool will run)
PostToolUse	tool_name, tool_input, tool_response
UserPromptSubmit	prompt (the text the user just submitted)
SessionStart	source (startup|resume|clear|compact)

Exit codes -- the coarse channel:

Exit	Meaning	Effect
0	success	flow proceeds; stdout is consumed (see below)
2	blocking error	stderr is fed back to the agent; the action is stopped
other	non-blocking error	stderr is shown to the user; flow proceeds