Playbooks · Coding tasks
Check whether your Claude Code hooks are adding tokens to every prompt or cutting them
Written October 31, 2026
For a Claude Code user with hooks installed: four hook events add plain output to the model's context, one field adds context wherever it is supported, and two fields shrink what the model reads. Most hooks cost nothing in tokens — the expensive ones are the few that inject text on every prompt or every tool call.
The rule, in one paragraph
Claude Code's hooks reference lists 33 events, from SessionStart to ElicitationResult. A hook is a command, an HTTP endpoint, a model prompt, or a subagent that runs when an event fires, and it talks back through its exit code and what it prints. The token rule turns on where that output goes. For most events, Claude Code writes a hook's plain stdout to the debug log and does not show it to the model, so it costs nothing. The exceptions are UserPromptSubmit, UserPromptExpansion, SessionStart, and PostModelSwitch, where plain-text stdout is added as context the model can see and act on. On those four events, a stray log line is a message to the model, billed like any other context. On every other event, it is not.
The second channel is additionalContext, a field a hook returns inside its JSON output. Claude Code wraps it in a system reminder and inserts it into the conversation at the point where the hook fired, and the model reads it on the next request. It stays in the conversation after that. Unlike plain stdout, additionalContext adds tokens by design, on every event that supports it — including PostToolUse, which fires after every successful tool call. A hook that appends a status dump on PostToolUse is adding that dump to the context of every turn that follows, for as long as the conversation runs.
Which hooks add tokens
UserPromptSubmit— every prompt. Fires when a prompt is submitted, before the model processes it. Plain stdout andadditionalContextare both injected as a system reminder alongside the prompt. A hook here that prints branch, status, and rules on every prompt adds that text to every single request in the session. Keep it to what changes between prompts, or move static rules into the project instructions file, which the model reads once.UserPromptExpansion— every expanded command. Fires when a typed command expands into a prompt. The same injection rule applies: stdout andadditionalContextjoin the expanded prompt. A hook that appends a checklist to a review command adds that checklist to every invocation of the command.SessionStart— once per session. Fires when a session begins or resumes. Plain stdout is added to context, andadditionalContextis added at the start of the conversation, before the first prompt. This is the cheapest place to put session context: it is injected once, not per prompt. It is also where a long dump does the least damage, because it is read once rather than repeated.PostModelSwitch— on every model switch. Plain stdout andadditionalContextare delivered to the model with the next request after the switch. A hook here that restates the session state on every switch repeats that state each time the model changes, including switches Claude Code makes on its own when resuming.- Any event returning
additionalContext. The reference supports this field on most events, and every value is delivered to the model. When several hooks return it for the same event, the model receives all of the values. APostToolUsehook, aStophook, and aSubagentStophook can each be adding text without any of them looking expensive alone.
Every injected string has a hard cap. A hook's additionalContext, systemMessage, and initialUserMessage strings, and its plain stdout, are capped at 10,000 characters each, measured separately. Past the cap, Claude Code writes the text to a file in the session directory and passes the model the file path with a preview of up to the first 2,000 characters instead. The model can read the file, but Claude Code does not ask it to — so an over-long injection is usually a silent loss of context, not a larger bill.
Which hooks cut tokens
PreToolUsewithupdatedInput. APreToolUsehook can replace a tool call's arguments before it runs. If the model asks to read a whole file and the hook narrows the call to the relevant section, the model never sees the rest. The replacement must include unchanged fields alongside modified ones, because it replaces the entire input object.PostToolUsewithupdatedToolOutput. APostToolUsehook can replace a tool's result before the model reads it. A hook that trims a verbose command output down to the failing lines, or replaces a large listing with a summary, removes tokens the model would otherwise pay to read on every following turn. This is the one hook shape that reliably reduces cost: it edits the record, not just the reply.
Blocking hooks cost nothing in tokens and can save a great deal: a PreToolUse hook that exits with code 2 stops the tool call before it runs, so neither the call nor its output enters the context at all. Exit code 2 is the blocking code for most events; other non-zero exits are non-blocking errors that let the action proceed. A guard hook that exits 1 when it means to block is not a guard — it is a log line.
The hooks that cost model calls, not context
Two hook types run a model of their own. A prompt hook sends a prompt to a Claude model for a single-turn evaluation and returns its decision as JSON; an agent hook runs a subagent with the same shape, with a longer default timeout of 60 seconds against 30 for prompt hooks. Every firing of one of these is a model call with its own input and output, billed as model use, on top of the main conversation. They are the right tool for a judgment a script cannot make — and the wrong default for anything a shell command can decide. If a prompt hook fires on every tool call, its cost is a second conversation running alongside the first.
Command hooks have a different failure mode. The default timeout for a command hook is 600 seconds, and a hook blocks execution until it completes. A hook that reaches its timeout is canceled and its output, including any additionalContext, is discarded — the prompt still reaches the model, without the context. A slow hook that times out on UserPromptSubmit therefore costs the wait and delivers nothing. Keep command hooks fast, and set a short timeout on any hook that touches the network or a slow tool.
Audit the hooks you already have
- List them. Open every settings file that can carry hooks: the user settings, the project settings, the local settings, and any plugin
hooks.json. A hook in a file you forgot about still fires. - Sort by event and field. For each hook, write down the event, and whether it prints plain text or returns
additionalContext,updatedInput, orupdatedToolOutput. Anything on the four stdout events, or returningadditionalContexton a per-call event, goes in the "adds tokens" pile. Anything returningupdatedInputorupdatedToolOutputgoes in the "cuts tokens" pile. Everything else is, on tokens, free. - Measure the additions. Count the characters each adding hook injects, and multiply by how often its event fires: once per session, once per prompt, or once per tool call. Characters are not tokens, and no fixed ratio converts one to the other — use the count to compare hooks with each other, and use the token cost calculator with your own counts as estimates, never as a bill.
- Cut or move the worst one. Move static text from
UserPromptSubmitinto the project instructions, where it is read once. Move per-call status dumps offPostToolUse, or replace them with aPostToolUserewrite that trims the output instead. Shorten anything over a few hundred characters that fires per prompt. One hook fixed is worth more than a list of ten noted. - Check the transcript, not the settings. After the change, run one normal task and look at what the model actually received. Injected context on
UserPromptSubmitappears as a system reminder, not as a chat message, so the settings file alone cannot tell you what landed.
Related playbooks
- Two hooks that enforce your coding conventions
- Check every package name your agent invents
- Check whether your session is really on Muse Wonder or Wonder Full — and which route you are paying through
- Two gh-aw advisories: tokens and temp files
Sources
Back to: Coding playbooks hub · Also: Two hooks that enforce your coding conventions · Token cost calculator · What an agent costs, in plain figures