Claude Code hooks: every event, the settings.json shape, and tested recipes (plus an X data budget guard)

The hooks reference lists 33 events. They fall into three cadences: per session (SessionStart, SessionEnd), per turn (UserPromptSubmit, Stop, StopFailure), and per tool call inside the agentic loop (PreToolUse, PostToolUse and their relatives). The rest are standalone events such as FileChanged, CwdChanged and the model-switch pair. The third column is what exit code 2 does on that event, which is the quickest way to know whether a hook there can stop anything.

Matchers differ by event. Tool events match tool_name; SessionStart matches how the session started; Notification matches the notification type (permission_prompt, idle_prompt, auth_success, elicitation_dialog, agent_needs_input, and more); PreCompact and PostCompact match manual or auto; StopFailure matches the error type (rate_limit, overloaded, billing_error, ...). UserPromptSubmit, Stop, PostToolBatch, TeammateIdle, TaskCreated, TaskCompleted, the worktree pair, MessageDisplay and CwdChanged have no matcher support: a matcher there is silently ignored and the hook fires every time.

What people actually use. In our X sample, posts that name an event mostly name four: PreToolUse (46.3%), Stop (24.2%), SessionStart (20.0%) and PostToolUse (18.9%). 18 of the 33 events, including PostToolBatch, FileChanged, ConfigChange and the model-switch pair, did not appear once. The newer events are documented and working; they are simply not yet part of the shared recipes people copy.

Hooks live under a top-level hooks key in a settings file, nested three levels deep: the event name maps to an array of matcher groups, and each matcher group holds a matcher string plus a hooks array of handlers. Where the file sits sets the scope.

Entries merge across levels instead of replacing each other, and the same handler defined in two settings files runs once. Matching hooks for one event run in parallel. Edits to settings files are normally picked up by a file watcher; the /hooks command opens a read-only browser that shows every configured hook and the file it came from.

Handler types. command runs a shell command or an executable; http POSTs the event JSON to a URL and reads the same JSON output from the response body; mcp_tool calls a tool on an MCP server you already configured; prompt asks a Claude model for a one-shot decision; agent spawns a subagent that can read files before deciding (the docs mark agent hooks experimental).

Common fields. type (required), if (one permission rule such as Bash(git *) or Edit(*.ts), evaluated only on tool events), timeout in seconds (defaults: 600 for command, http and mcp_tool, lowered to 30 on UserPromptSubmit and the model-switch events; 30 for prompt; 60 for agent), and statusMessage for the spinner text. Command hooks add command, args, async, asyncRewake, shell and onFailure (Claude Code v2.1.295 or later).

Exec form vs shell form. With args present, command is resolved as an executable and spawned with no shell, so a path placeholder such as ${CLAUDE_PROJECT_DIR} needs no quoting. Without args, the string goes to sh -c (Git Bash or PowerShell on Windows), which gives you pipes and && but means every placeholder must sit in double quotes.

Environment variables. Every command hook gets CLAUDE_PROJECT_DIR (the root where the session started; it does not follow Claude into a worktree, read cwd from the input for that), and plugin hooks also get CLAUDE_PLUGIN_ROOT and CLAUDE_PLUGIN_DATA. CLAUDE_ENV_FILE exists only for SessionStart, Setup, CwdChanged and FileChanged: append export lines to it to set variables for every later Bash command. CLAUDE_CODE_REMOTE is true in cloud sessions, CLAUDE_EFFORT carries the effort level, and there is no CLAUDE_MODEL variable.

This project file registers the three everyday hooks on this page: a formatter after edits, a guard before Bash and file writes, and a desktop ping on notifications.

How Claude Code reads a matcher depends on the characters in it, and this is where most broken hooks come from.

Pipe lists. Edit|Write is the same exact-name list as Edit, Write. Unanchored means substring. Edit.* matches both Edit and NotebookEdit. Write ^Edit$ when you mean exactly one tool. Matchers are case-sensitive, so bash matches nothing.

MCP tools. MCP server tools appear in tool events as mcp__<server>__<tool>. To catch every tool from one server you need the .* suffix: mcp__memory has only exact-match characters, so it is compared as an exact string and matches no tool at all. mcp__brave-search__.* works for hyphenated server names, mcp__.*__write.* catches write tools on any server, and a plugin-bundled server uses a scoped segment such as mcp__plugin_my-plugin_db__.*. Since Claude Code v2.1.274 the input also carries an mcp_server object with the server name and a source; the docs recommend basing trust decisions on source rather than on the tool-name prefix.

The if field narrows further. A handler-level if holds exactly one permission rule and is only evaluated on tool events (on any other event a hook with if never runs). For Bash, leading VAR=value assignments are stripped and each subcommand is checked, so Bash(git *) fires on npm test && git push, and commands inside $() and backticks are checked too. When Claude Code cannot tell which commands a Bash string runs, it runs the hook anyway. The docs are explicit that this filter is best-effort: use permission rules, not an if pattern, for a hard allow or deny.

Which file tools. For Write, Edit and Read, tool_input.file_path always arrives absolute (Claude Code expands ~ and relative paths first), with backslashes on Windows. A path check written with forward slashes never matches on Windows and lets the call through.

A command hook gets the event JSON on stdin: common fields (session_id, transcript_path, cwd, permission_mode, hook_event_name, and prompt_id once there is user input) plus event fields such as tool_name, tool_input and tool_use_id for tool events, tool_response and duration_ms for PostToolUse, and stop_hook_active plus last_assistant_message for Stop. It answers with an exit code and, optionally, one JSON object on stdout.

Exit 1 does not block. It is the usual Unix failure code, but in Claude Code it is a non-blocking error. A policy hook must exit 2, return a deny decision, or set "onFailure": "block", which also turns a missing script, a crash or a timeout into a block. A timed-out PreToolUse hook without that flag lets the call continue through the normal permission flow.

JSON output. Print only one JSON object; a line your shell profile echoes first is enough to make Claude Code read the output as plain text. Universal fields: continue (false stops Claude entirely), stopReason, systemMessage (a warning shown to the user) and terminalSequence (a desktop notification, title or bell, because hooks have no /dev/tty). Event-specific control comes in two styles: a top-level decision: "block" plus reason for UserPromptSubmit, PostToolUse, PostToolBatch, Stop, SubagentStop, ConfigChange and PreCompact, and a hookSpecificOutput object with hookEventName for PreToolUse, PermissionRequest and others.

PreToolUse decisions. permissionDecision is allow, deny, ask or defer (defer needs -p mode), with permissionDecisionReason; updatedInput replaces the whole tool input before it runs; additionalContext adds a note next to the tool result. When several hooks disagree, deny beats defer, which beats ask, which beats allow. A hook's allow never overrides a deny rule in settings, while a hook's deny holds in every permission mode, including the mode that --dangerously-skip-permissions turns on. The old top-level approve / block values for this event are deprecated.

PostToolUse and Stop. PostToolUse cannot undo anything (the tool already ran); decision: "block" puts your reason next to the result, and updatedToolOutput replaces what Claude sees. A Stop hook that blocks makes Claude keep working; check stop_hook_active to avoid loops, because Claude Code overrides the block after eight consecutive continuations (raise it with CLAUDE_CODE_STOP_HOOK_BLOCK_CAP). additionalContext, systemMessage and plain stdout are each capped at 10,000 characters; longer text is saved to a file and Claude gets a preview.

Context injection. On SessionStart, UserPromptSubmit, UserPromptExpansion and PostModelSwitch, plain-text stdout is added to Claude's context as-is; elsewhere stdout only goes to the debug log (claude --debug, then ~/.claude/debug/<session-id>.txt). The docs advise writing injected text as facts ("This repo uses bun test") rather than as commands.

The formatter. A PostToolUse hook on Edit|Write reads tool_input.file_path and formats that one file by extension. It always exits 0: the edit already happened, and a formatter that blocks only confuses Claude. We tested it by piping a sample Write payload for a file containing const a = {b:1}; Prettier rewrote it to const a = { b: 1 }; and the hook printed nothing, which is the expected success path. The docs' one-liner version is jq -r '.tool_input.file_path' | xargs npx prettier --write.

The guard. A PreToolUse hook on Bash|Edit|Write denies a recursive force delete, a force push to main, piping a download into a shell, and writes to .env, key files or .git/. It returns a JSON deny instead of exiting 2 so the reason reaches Claude cleanly, and stays silent otherwise so the normal permission flow decides. Register it with "onFailure": "block" so a crashed guard fails closed. Treat it as a seatbelt, not a sandbox: pattern matching on shell strings misses creative spellings, which is why Anthropic's docs point hard allow / deny rules at the permission system.

The notifier. The notify.sh registered in the settings above returns a terminalSequence (OSC 777) that Claude Code writes for you; Notification hooks cannot block and their systemMessage is discarded, but the sequence still fires in an interactive session.

Test before you register. Pipe sample JSON into each script and check stdout and the exit code, exactly as the troubleshooting section of the guide suggests. These are the runs we did for this page:

Give an agent a Twitter (X) data tool and it will happily run a search forty times while it iterates. Because MCP tools are ordinary tools in PreToolUse and PostToolUse, two small hooks turn that into a metered, capped resource. We sent the hosted twitterapi.io MCP server an initialize and a tools/list request this session: it answers as twitterapi-mcp and lists 12 tools (search_tweets, get_user_info, get_user_about, get_user_followers, get_user_followings, get_user_last_tweets, get_user_mentions, get_tweets_by_ids, get_tweet_replies, get_tweet_quotes, get_tweet_retweeters, get_trends), and its instructions say to pass your API key as the Bearer token. Added under the name twitterapi-mcp, the tools show up as mcp__twitterapi-mcp__search_tweets and so on, so one matcher, mcp__twitterapi-mcp__.*, covers all of them.

x_call_log.py (PostToolUse) walks the tool result, counts the tweets or users it returned, prices the call (15 credits per tweet with a 15-credit minimum, 18 per profile) and appends one JSON line to ~/.claude/x-ledger.jsonl. Fed a real 20-tweet search page wrapped as MCP text content, it logged 20 tweets, 300 credits, $0.003.

x_budget_guard.py (PreToolUse) sums today's ledger, adds the worst case for the call about to run (a full 20-tweet page is 300 credits), returns ask above 80% of the budget and deny above 100%, with the numbers in the reason so Claude can tell you why. With onFailure: "block", a missing or broken guard stops X calls instead of letting them through unmetered. In our test with a 500-credit budget and 318 credits already logged, it denied the next search with the message shown above.

The X data bill. twitterapi.io charges 15 credits per tweet returned ($0.15 per 1,000 tweets; a full 20-tweet page is $0.003, an empty search costs the $0.00015 minimum) and 18 credits per profile ($0.18 per 1,000). The official X API pay-per-usage rate card at docs.x.com/x-api/getting-started/pricing lists $0.005 per post read and $0.010 per user read, so the same 1,000 tweets cost $5 there against $0.15 here, roughly 33x. Our study for this page pulled 1,335 tweets in 74 requests for $0.20; at X's post-read rate that is $6.67.

The MCP server's tools all read data. For writes, use the REST write endpoints instead (Recipe 4). New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days), which is enough to run this guard with the default budget for three days; purchased credits never expire. Plans and rate limits are on the pricing page.

Pull fresh X context at startup. A SessionStart hook with matcher startup can run one search for your project's name or handle and print the top posts; plain-text stdout from SessionStart lands in Claude's context before your first prompt. Two pages cost at most $0.006. mcp_tool hooks do not run on SessionStart at launch (MCP servers are not connected yet), so this one is a command hook calling the REST endpoint /twitter/tweet/advanced_search directly; the full script is the code example at the end of this page. Keep it fast and fail silent: a hook that errors here only shows a notice, but a slow one delays every session.

Post a ship note on Stop, carefully. Stop fires at the end of every turn, not only when a task is done, so a hook that posts on every Stop would post constantly. The script below acts only when Claude's last_assistant_message contains a line starting with #shipped (ask for that line in CLAUDE.md), skips when stop_hook_active is true, and defaults to a dry run that just shows a systemMessage. Run it with "async": true so it never holds up the session; note that in -p mode Claude Code cancels async hooks still running at teardown.

What the write call means. Posting runs through an authenticated session: one /twitter/user_login_v2 login ($0.10, with a proxy you supply) returns login_cookies, and each /twitter/create_tweet_v2 call is then 60 credits ($0.0006), billed per HTTP 200 call. The call acts as that X account, so X can rate-limit, lock or suspend it; keep a human pace (one note per real release, not per turn) and expect the session to need a fresh login from time to time. Reads, by contrast, need no X account at all.

Dry-run test. Piping a Stop payload whose last message ends with #shipped: v0.4 adds CSV export to the mentions CLI printed {"systemMessage": "[dry run] would post to X: v0.4 adds CSV export to the mentions CLI"}; a payload without the tag, or with stop_hook_active: true, printed nothing and exited 0.

Question. When developers post about Claude Code hooks on X, which events do they name and what do they use hooks for? Query. Three keyword searches through twitterapi.io /twitter/tweet/advanced_search with retweets excluded: "claude code" hooks (Latest, two windows) and "claude code" hook (Top), plus a separate search seeded with four event names. Sample. 1,335 tweets returned in 74 requests, 1,153 unique; the keyword set used for the event shares is 927 posts, collected in 2026. Method. Event names from the official list matched case-sensitively as whole words; Stop, Notification, Setup and Elicitation counted only with hook context ("Stop hook", quoted or in backticks) because they are ordinary English words. Use-case families are keyword regexes over the text and overlap.

What it shows. Hooks are mostly mentioned as part of a kit: 41.2% of posts list them next to skills, subagents or plugins, and only 10.2% get specific enough to name an event. When people do get specific, it is about control rather than convenience: PreToolUse dominates, guard and security vocabulary (24.5%) far outruns formatting (7.4%), even though formatting is the first recipe in most tutorials. In the search seeded with event names (300 posts), PreToolUse again appears in 46.7% of posts. Engagement is very skewed: the median post gets 2 likes while the top tenth gets 124 or more.

What the sample cannot show. Search returns what X indexes for these words, so posts that describe a hook without the word "hook" are missed, and the Top query reaches further back than the Latest windows. Keyword families are crude ("context" also matches posts about context windows). Mentions are not usage: nothing here says how many people run a given hook. Privacy. Keyword searches return posts by private individuals, so raw pages stayed on our machine and were not published; the study files hold aggregates and de-identified rows only, and no person is named or profiled. Cost. 1,335 tweets at 15 credits each is 20,025 credits, $0.20.

The hook never runs. Open /hooks and confirm it is listed under the right event. Check the matcher's case and form (an MCP matcher without .* matches nothing; bash is not Bash). In an interactive session, hooks from every settings file wait until you accept the workspace trust dialog for that folder. If the menu says only managed hooks run, an administrator set allowManagedHooksOnly.

A hook error notice appears. Failed with non-blocking status code means the exit code was neither 0 nor 2. A No such file or directory in the notice means the script never started: fix the path, use ${CLAUDE_PROJECT_DIR} in exec form, and chmod +x the script. jq: command not found means jq is missing from the hook's PATH; write the hook in Python or Node instead.

JSON has no effect. Something else reached stdout first, often an echo in ~/.zshrc or ~/.bashrc; guard it with an interactive-shell check. Or a field sits at the wrong level: permissionDecision belongs inside hookSpecificOutput with hookEventName, while decision and reason for Stop or PostToolUse are top-level. Build output with jq -n or json.dumps, never string concatenation.

Claude will not stop. A Stop hook that blocks on a condition Claude cannot meet loops until the eight-continuation cap ends the turn with a warning. Exit 0 early when stop_hook_active is true.

Turning hooks off. Set "disableAllHooks": true in a settings file, or pass --settings '{"disableAllHooks": true}' for one run; there is no switch for a single hook short of deleting its entry, and user-level settings cannot disable managed hooks. Before scripting claude -p over a repository you did not write, read its .claude/ settings: in -p and SDK sessions there is no trust dialog, so committed project hooks run.

Security. Command hooks run with your full user permissions. The docs' own checklist: validate inputs, quote every shell variable, reject .. in paths, use absolute paths, and skip .env, .git/ and key files. If a hook needs secrets (like the X API key above), read them from the environment, never from the repo.