What are agent hooks?

A hook is configured in a settings file and tied to an event, optionally filtered by a matcher such as a tool name. Events named in the docs include SessionStart, PreToolUse, PostToolUse, SubagentStop and Stop. Most hooks use a command handler that runs a shell command. Other handler types post event data to a URL, ask a model a single question, or start a multi-turn agent check with tool access, and the docs mark agent-based hooks as experimental.

The hook receives event data as JSON on standard input and answers through its exit code and output. Exit code 0 means no objection, so a PreToolUse call still goes through the normal permission flow. Exit code 2 blocks the action and sends the stderr text back to Claude as feedback. A hook can also exit 0 and print JSON to deny, ask or allow a tool call. When several hooks match, all of them run, and for permission decisions the most restrictive answer wins.

Typical uses in the guide are formatting a file after every edit, sending a desktop notification, blocking writes to protected files, and re-injecting context after compaction. Not every event can be blocked, so the per-event rules in the reference matter. The guide presents hooks as deterministic: configured actions happen every time their event and matcher fire. It calls the general feature hooks, and uses agent-based hooks only for the multi-turn handler type.