Your token budget doesn't count your conversation

// what everyone assumes

The Messages API is stateless. Every request you send carries the whole conversation again — system prompt, every prior turn, every tool result from earlier laps. So when a parameter called a budget appears, the natural reading is that it caps that pile.

It isn't. The budget is scoped to the turn, not to the transcript.

What it actually counts

Two things, and only on the turn in progress: what Claude generates, and the tool results it reads back. The history you resend rides along free.

Anthropic's own worked example makes the size of the gap concrete: a three-turn loop that puts roughly 20,820 tokens of payload on the wire counts 19,000 against the budget. The difference is the resend.

This is the exact inverse of the thing that makes agent runs expensive. A twenty-call agent bills like two hundred precisely because the context is resent and re-billed every lap — and a task budget deliberately does not count that regrowth. Your bill and your budget are measuring different things.

A budget the model can see

This is what separates it from the cap you already have. max_tokens is an enforced per-response ceiling the model is not aware of. Hit it and the response stops mid-thought and comes back with stop_reason: "max_tokens". Nothing warned it; nothing wrapped up.

With a task budget the server injects a countdown marker Claude sees while generating, so it can prioritise and close cleanly instead of being guillotined. That difference — a limit the model can plan around versus one it walks into — is the whole reason the parameter exists. It is the API-level version of the point in nothing is telling your agent to stop.

The trap: leave remaining alone

remaining defaults to total, and the server tracks the countdown itself. The temptation is to be helpful and decrement it yourself. Don't — not in an ordinary loop that resends history.

The failure is quiet in the worst way: nothing errors, the agent just finishes early and you conclude the budget was too small. Pass remaining only when you compact or rewrite history, so the server can no longer derive prior spend on its own.

The fine print

Four things that decide whether this is available to you at all:

Model support is narrower than people expect, and it is worth checking before you plan around it:

Task budgets are also not available on the Claude Code or Cowork surfaces. And do not confuse this with Managed Agents session budgets, which are a different thing entirely: hard, dollar-denominated, platform-enforced caps on a session. A task budget is advisory and token-denominated. Say "paces", never "prevents".

Sources: Claude API — Task budgets (beta) · Claude API — Handling stop reasons · Claude API — Managed Agents session budgets. Verified 2026-08-30.