Agent harness token overhead: where it goes

What agent harness token overhead is

Agent harness token overhead is every token that reaches the model without you typing it: the system prompt, the tool schemas, the files the harness read on your behalf, the tool results it fed back, and the whole conversation replayed on each turn. Keep the model, change the harness, and the bill still moves. It moves a lot. The model is not the reason.

The gap comes from five mechanisms, and every one of them is measurable on your own box. If the word is new to you, what an agent harness actually is covers the layer being priced here.

Why one instruction is not one request

The API underneath all of these tools is stateless. It remembers nothing between calls, so the client sends the entire conversation again on every call. Anthropic's Claude Code cost documentation states the consequence directly: the full conversation goes with every request, and each time the model uses tools, another request goes out carrying that batch of tool results.

The second half is where the money is. One instruction from you that takes six tool calls is seven requests. The first carries the preamble and your prompt. The second carries all of that plus the first tool call and its output. The seventh carries everything before it. So the input tokens billed across a single instruction grow with roughly the square of the number of tool calls it took. Ten tool calls against three is not a 3x difference on that instruction. The ratio of the squares puts it nearer 11x, which is how two harnesses reach very different totals while doing the same work.

Under all of it sits the preamble, resent on every request whether or not it earns its place.

[
  {
    "requests": 5,
    "preamble_tokens_resent": "75,000"
  },
  {
    "requests": 10,
    "preamble_tokens_resent": "150,000"
  },
  {
    "requests": 20,
    "preamble_tokens_resent": "300,000"
  },
  {
    "requests": 40,
    "preamble_tokens_resent": "600,000"
  },
  {
    "requests": 80,
    "preamble_tokens_resent": "1,200,000"
  }
]

That block is multiplication, not a measurement of any product. It assumes a 15,000 token preamble because that is a round number to reason with. Across 80 requests it reaches 1,200,000 input tokens before one line of your code has been read. Take your real preamble size from /context and substitute it. The shape of the curve does not change.

Caching changes the price of those tokens, not the count

Prompt caching does not send fewer tokens. It changes what a resent token costs. As of September 2026 Anthropic documents the rates as multiples of the base input price, and the API reports each category separately in the usage object, as cache_read_input_tokens, cache_creation_input_tokens and input_tokens.

[
  {
    "label": "Cache read (hit)",
    "price_multiplier": 0.1
  },
  {
    "label": "Uncached input",
    "price_multiplier": 1
  },
  {
    "label": "Cache write, 5 minute TTL",
    "price_multiplier": 1.25
  },
  {
    "label": "Cache write, 1 hour TTL",
    "price_multiplier": 2
  }
]

A warm prefix serves your history at 0.1 of the base input price. The same bytes re-processed after the window closed are written back at 1.25. Divide the second by the first and identical content costs 12.5 times as much, decided by nothing except whether you came back in time. The window is documented as one hour on a subscription, and five minutes by default on an API key or a cloud provider. An agent parked on a VPS that gets one prompt an hour pays that rebuild on nearly every prompt.

The cache matches a prefix, and that detail decides more than any feature list. Anything that alters an earlier part of the request invalidates everything after it. A harness that stamps the current time into its system prompt, or reorders its tool list between turns, breaks its own prefix every turn and pays the write rate again and again. Two harnesses can send byte-identical context and still bill differently, because one of them keeps its prefix stable and the other does not.

The tool surface you pay for before you type anything

A tool definition is text: a name, a description written for the model, and a JSON schema with a line of prose per parameter. A few hundred tokens each is normal, and a well-stocked harness carries dozens. That block sits in front of every request in the session.

Harnesses differ here by design. Claude Code defers MCP (model context protocol) tool definitions by default, so only server instructions and tool names enter context until the model actually calls one. A harness that inlines every schema from every connected server carries all of it from the first request onward. Run /context to see the real split in your session, with your servers connected, between system prompt, tools, memory files and conversation.

Two cheap wins fall out of that screen. Servers you are not using this week can be switched off with /mcp. A command line tool you already have installed, gh or aws, adds nothing to context at all, because the model reaches it through the shell tool it was already carrying.

File re-reads instead of context you already bought

A file the harness reads stays in the conversation for the rest of the session, so you pay rent on it: every later request carries it again. At the cache read rate that rent is small. After one cache miss you pay full price for the entire pile at once.

The same task therefore costs different amounts depending on how the harness gathers information. Grepping a 4,000 line file for the twelve lines that matter costs a fraction of reading the file. Re-reading a file the harness already has doubles the rent for the remainder of the session. Pasting a 40,000 line test log into context, when the failing assertion is nine lines, is the most expensive habit in agentic coding.

That last one you can fix yourself on any harness with hooks. A pre-tool hook can rewrite npm test into the same command piped through grep -E 'FAIL|ERROR' and head -100, so the model sees the failures and never the 40,000 lines. Claude Code documents this exact pattern as a PreToolUse hook. The saving compounds, because the filtered output is what gets carried on every subsequent request too.

Compaction is a large request, not a free cleanup

As the conversation approaches the context limit the harness has two options, and both cost money. It can summarise, which means sending the whole conversation once more so the model can compress it. Or it can drop old turns, which is cheap up front and often causes the model to re-read files it already had.

Summarising has a second cost that is easy to miss. It rewrites the conversation, so the cached prefix no longer matches and the next request writes the cache again. Claude Code labels this in its own prompt cache statistics as an expected rebuild, which is a useful phrase to look for when a quiet session shows a large number.

/clear is the cheap alternative, and it is underused. Starting a fresh session for unrelated work costs nothing, while carrying this morning's context into an unrelated afternoon question means paying for that history on every turn until you stop.

Subagent fan-out duplicates context on purpose

A subagent is a second conversation with its own context window. It gets its own preamble, its own tool schemas and its own file reads, and its result returns into the parent conversation where it is then carried on every remaining request. Five subagents running at once means five preambles.

The trade can be worth it. Verbose work such as a test run or a documentation crawl stays in the subagent's context, and only a short answer lands in yours. It can also be pure duplication, when three subagents each read the same four files to answer three related questions.

Anthropic documents the upper end of this. Agent teams, where each teammate is a separate instance with its own context window, use approximately 7x the tokens of a standard session when teammates run in plan mode (Claude Code documentation, checked September 2026). That figure belongs to that feature, and it is the right order of magnitude to expect from any fan-out design before you measure your own.

Retries cost more than the failed call

A tool call that fails charges you three times. You pay for the request that made it. You pay for the retry, which carries everything the first request carried plus the error. Then you pay rent on the error for the rest of the session, because a line such as bash: jq: command not found stays in the transcript and rides along on every later request.

This is where a bad tool schema turns into a large bill. A harness whose edit tool fails on whitespace and retries four times has spent more on the four failures than the successful edit cost, and it has grown the context that every remaining turn must carry. Failure rate is a token cost, which is why a harness that verifies its own edits can be cheaper than one that simply issues more of them.

The 70x claim, and why it is not ours

A comparison that circulated in 2026 put two harnesses on the same model roughly seventy times apart in token spend on one task. We did not run that comparison, and this post does not present the figure as a measurement of ours. The claim and its method belong to the write-up: read the harness comparison that reports the seventy-fold gap and judge the method on its own terms.

Treat every cross-harness multiplier, that one included, as a fact about two specific setups on one specific task. It depends on the repository, the prompt, how many tool calls each side needed, whether the session was warm or cold, how many MCP servers were connected, the thinking budget in use, and whether a subagent was involved. Change any of those and the ratio changes. So the number worth having is your own baseline.

How to measure your own agent's token spend

Get one number you trust before tuning anything.

1. Start a clean session with /clear, in a real repository rather than a toy one.
2. Give one specific instruction with a known scope. "Add a null check to the parse function in src/config.py" is a baseline. "Improve error handling" is not, because it sends the harness looking, and looking is file reads.
3. Run /usage and write down the session block numbers per model: input, output, cache read and cache write.
4. Repeat the identical instruction in the other harness, on the same repository, from the same starting commit.

The Claude Code session block also prints a prompt cache line giving the share of input tokens served from cache and the number of misses, which tells you whether a large total is real work or a rebuilt cache. what each of those token counters actually counts walks the fields one at a time, and why output tokens cost several times what input tokens do matters here, because thinking tokens are billed as output.

For continuous measurement on a VPS, export telemetry instead of reading a screen:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
claude

The claude_code.token.usage metric carries a query_source attribute whose value is main, subagent or auxiliary, so fan-out appears as its own series instead of hiding inside a session total. claude_code.cost.usage gives the same split in dollars, computed locally from list prices, so treat it as an estimate rather than an invoice. Tools that read local session history instead are covered in the roundup of Claude Code spend tracking tools.

To price the preamble on its own, ask the API what a request would cost before sending it:

curl https://api.anthropic.com/v1/messages/count_tokens \
  -H 'content-type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{
        "model": "claude-sonnet-5",
        "system": "your system prompt here",
        "messages": [{"role": "user", "content": "hello"}]
      }'

The reply is a single input_tokens count, and the call bills nothing. Add your real tools array to the same request body, because the endpoint counts tool definitions too, and the result is the exact per-request floor of your setup, measured rather than guessed. Multiply it by the request count from your baseline run and you have the preamble share of that session.

The four levers you actually control

Everything above reduces to four changes you can make on your own box.

Shrink the tool surface. Disconnect MCP servers you are not using today. Prefer a command line tool the model can call through the shell over a server that adds definitions. Confirm the result in /context instead of assuming it worked.

Keep context narrow. Clear between unrelated tasks. Keep the always-loaded memory file short, with 200 lines as the documented guidance, and move long procedures into skills that load only when invoked. Write specific prompts, because a vague one makes the harness explore. the context management moves with the largest effect goes further on this lever.

Route the cheap steps to a cheap model. Formatting, renaming, log triage and test running do not need your most expensive model. A subagent can be pinned to a small model while the main conversation stays on a large one. routing each step to the model that can do it covers how to split the work, and what breaks when the split is wrong.

Turn off what resends state while you are idle. This is the one people miss. A scheduled task fires on its interval and sends the full context each time, whether anything changed or not. Idle check-ins, cross-session messages and background summarisation do smaller versions of the same thing. An agent left running in tmux for a week can spend real money doing nothing, so audit whatever is set to fire on a timer. Then put a budget and an alert around the machine itself: capping what a VPS-hosted agent can spend covers spend limits, per-key accounting and the alerting that catches a runaway loop before the invoice does.

One dated reference point

Numbers here go stale fast, so take this as a single anchor rather than a target. Anthropic's cost documentation, checked in September 2026, reports an average around 13 US dollars per developer per active day across enterprise deployments, with 90% of users staying under 30 dollars per active day. If your own single-file baseline sits far outside that shape, the cause is almost always one of the mechanisms above rather than the model you picked.

FAQ

Why do two agent harnesses cost different amounts on the same model?

The model price is per token, and the harness decides how many tokens exist. It sets the size of the system prompt and tool schemas resent on every request, how many tool calls a task takes (each one is another full request carrying everything before it), whether it re-reads files it already holds, how it compacts, how many subagents it spawns, and how it recovers from a failed tool call. None of that is the model's doing, which is why swapping harnesses can change a bill by an order of magnitude while the output quality stays similar.

Does prompt caching make resent context free?

No. Caching changes the price, not the count. The documented rates as of September 2026 are 0.1x the base input price for a cache read, 1.25x for a five minute cache write and 2x for a one hour write. A session you return to after the window has closed re-processes the entire history at a write rate, so an idle agent that gets one prompt an hour can cost more per prompt than a busy one that keeps its cache warm.

How do I find out where my tokens are going?

Run /context for the standing cost, meaning system prompt, tool definitions and memory files, and /usage for the session totals split into input, output, cache read and cache write. For an agent running on a VPS, set CLAUDE_CODE_ENABLE_TELEMETRY=1 and export OpenTelemetry metrics. The claude_code.token.usage metric carries a query_source attribute of main, subagent or auxiliary, which separates fan-out from your own conversation without any log parsing.

Do subagents save tokens or waste them?

Both, depending on the shape of the work. A subagent that swallows verbose output, such as a full test run, and returns ten lines saves you rent on everything it did not return. Several subagents that each read the same files to answer related questions duplicate that context once per agent, and every preamble is paid again. Anthropic documents agent teams at roughly 7x a standard session when teammates run in plan mode, so measure your own fan-out before making it the default.