Headless runs now stop at your spend cap and shut down background agents instead of spending on.
What's wrong with this entry?
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.
- 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.
; stopping background agents., cleared_on_cancel
Strings lifted out of the shipped bundle, so the claim above can be checked against them.
Related
Other releases about the same thing. Found by shared names or similar wording; neither means one caused the other.
-
v2.1.219
Headless text output recovers the last full assistant message on an incomplete run
Both mention headless mode
-
v2.1.227
Headless mode reports fatal errors instead of dying quietly
Both mention headless mode
-
v2.1.248
Headless loop guards against missing stream event fields
Both mention headless mode