6. Hooks

1. Event: the moment, such as PreToolUse or Stop.
2. Matcher group: which occurrences count, such as "matcher": "Bash".
3. Handler: what runs. Five types:

When an event fires, all its matching hooks run in parallel. The same handler defined in two settings files runs once.

The events fall into three cadences: once per session (SessionStart, SessionEnd), once per turn (UserPromptSubmit, Stop, StopFailure), and on every tool call (PreToolUse, PostToolUse). Around those sit permission events, subagent and task events, compaction and model-switch events, file and directory events, and MCP elicitation events.

16 of the 33 can block their action with exit code 2. The rest either fire after the fact or only observe.

• Exit 1 doesn't block. It's the normal Unix failure code, and that's exactly why it trips people up.
• When the hook itself breaks, by crashing, a missing script, or a timeout, the action goes ahead. "onFailure": "block" on a command or http hook (v2.1.295 or later) makes a failure block instead, the way exit 2 would.
• JSON output gives finer control than exit codes: exit 0 and print one JSON object. Don't mix both: exit 2 blocks no matter what the JSON says.
• Output into context is capped at 10,000 characters. Past that, Claude gets a file path and a 2,000-character preview.

• When several PreToolUse hooks answer, the strictest wins: deny, then defer, then ask, then allow.
• A hook can tighten, never loosen. Deny and ask rules are checked whatever the hook returns, so a hook's allow can't skip them.
• A hook's deny holds in every mode, bypassPermissions and --dangerously-skip-permissions included.
• PostToolUse runs only on success. Add the same hook to PostToolUseFailure to see failed calls.
• PermissionRequest fires when Claude Code is about to show you a permission prompt. It ignores exit 2; it answers with a decision object instead.

• The MCP trap: mcp__memory contains only exact-match characters, so it's compared as a whole tool name and matches nothing. Write mcp__memory__.*.
• What the matcher filters depends on the event: the tool name for tool events, startup, resume, clear, compact, or fork for SessionStart, manual or auto for compaction. Ten events, including UserPromptSubmit and Stop, have no matcher support and always fire.
• The if field narrows a tool hook further with one permission rule, such as "Bash(git *)" or "Edit(*.ts)". It's best-effort: when Claude Code can't tell what a Bash command runs, the hook runs anyway.
• Matchers are case-sensitive.

• Hooks merge across levels. User, project, and local hooks add to managed ones, never replace them.
• disableAllHooks: true turns hooks off, but set outside managed settings it can't touch managed hooks. For one run, whatever the project says: --settings '{"disableAllHooks": true}'.
• allowManagedHooksOnly in managed settings blocks user, project, local, and plugin hooks.

• Command hooks run with your full user permissions, outside the sandbox. They can read, change, or delete anything your account can. Review a hook before you add it.
• Workspace trust: an interactive session holds every settings-file hook until you accept the trust dialog for the folder. A claude -p or SDK run never shows the dialog and treats the folder as trusted, so a cloned repo's hooks run.
• The docs' checklist: validate inputs, quote shell variables, block .. in paths, use absolute paths, skip .env and keys.

• A timed-out PreToolUse hook doesn't block the call. A stalled gate is an open gate, unless onFailure is "block".
• SessionEnd hooks share a 1.5-second budget, raised to match a longer per-hook timeout up to 60 seconds.
• A Stop hook that keeps blocking is overridden after 8 blocks in a row. Check stop_hook_active in the input to avoid the loop.

Opens a read-only browser of every configured hook, labeled with where it comes from: user, project, or local settings, a plugin, or the session. Select one to see exactly what it runs. To change a hook, edit the settings file; Claude Code's file watcher picks up the change.