Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

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

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

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

  1. 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.
  2. Sort by event and field. For each hook, write down the event, and whether it prints plain text or returns additionalContext, updatedInput, or updatedToolOutput. Anything on the four stdout events, or returning additionalContext on a per-call event, goes in the "adds tokens" pile. Anything returning updatedInput or updatedToolOutput goes in the "cuts tokens" pile. Everything else is, on tokens, free.
  3. 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.
  4. Cut or move the worst one. Move static text from UserPromptSubmit into the project instructions, where it is read once. Move per-call status dumps off PostToolUse, or replace them with a PostToolUse rewrite 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.
  5. Check the transcript, not the settings. After the change, run one normal task and look at what the model actually received. Injected context on UserPromptSubmit appears as a system reminder, not as a chat message, so the settings file alone cannot tell you what landed.

Related playbooks

Sources

Back to: Coding playbooks hub · Also: Two hooks that enforce your coding conventions · Token cost calculator · What an agent costs, in plain figures