What
In print/headless mode Claude Code now compares the run's cost against --max-budget-usd, and on reaching the cap it writes a notice to stderr and stops any background agents still running rather than letting them keep spending. The check consults shutdown state first, so an interrupted turn or a session already tearing down will not trip the cap or print the notice on its way out.
Details
- Fires only outside shutdown: when the session is already closing or the turn was aborted, neither the stderr notice nor the accompanying
print_budget_halttelemetry event is produced. - Emits a
print_budget_halttelemetry event when the halt does fire, carrying the stop of background agents with it. - The halt lives in a dedicated print-path helper rather than inline in the main loop.
- Queued commands that an interrupt clears are now recorded with the reason
cleared_on_cancel. - Prompt-suggestion teardown and retirement of a parked permission prompt now go through one shared helper, so ending a session and interrupting a turn follow the same path.
- Ships with a new environment variable,
CLAUDE_CODE_PRINT_ENGINE_LOOP, that selects an alternate print engine loop; with the variable unset the accessor returns false, so that alternate loop is present but off in this build.
Evidence
; stopping background agents., cleared_on_cancel
Strings lifted out of the shipped bundle, so the claim above can be checked against them.
Names in the bundle--max-budget-usd
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Added since
A small documentation edit on Manage costs effectively touched a line naming --max-budget-usd after this was published.
For a response from the Claude API billed at the 1.1× [data residency rate](https://platform.claude.com/docs/en/about-claude/pricing#data-residency-pricing), Claude Code multiplies the list price of that response's tokens by 1.1 in the ses…costs see the edit
Confirmed since
Anthropic's documentation has since written up --max-budget-usd, on CLI reference.
| `--max-budget-usd` | Maximum dollar amount to spend on API calls before stopping (print mode only). Spend from [subagents](/docs/en/sub-agents) counts toward the cap. When you return to a conversation with `--continue` or `--resume`, tot…cli-reference see the edit
One source agreesOne thing we can check says the same as this entry.
Anthropic's documentation agrees
Anthropic's documentation has since written up --max-budget-usd, on CLI reference.