{"version":"2.1.246","anchor":"headless-runs-halt-at-the-spend-cap-and-stop-background-agen","canonical_anchor":"headless-runs-halt-at-the-spend-cap-and-stop-background-agen","heading":"Headless runs halt at the spend cap and stop background agents","tier":"use","area":"Headless Mode","scope":null,"heads_up":null,"url":"https:\/\/changelogs.core-directive.com\/v\/2.1.246\/e\/headless-runs-halt-at-the-spend-cap-and-stop-background-agen","release_url":"https:\/\/changelogs.core-directive.com\/v\/2.1.246","markdown":"### Headless runs halt at the spend cap and stop background agents\n\nHeadless runs now stop at your spend cap and shut down background agents instead of spending on.\n\n**What**\n\nIn 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.\n\n**Details**\n\n- Fires only outside shutdown: when the session is already closing or the turn was aborted, neither the stderr notice nor the accompanying `print_budget_halt` telemetry event is produced.\n- Emits a `print_budget_halt` telemetry event when the halt does fire, carrying the stop of background agents with it.\n- The halt lives in a dedicated print-path helper rather than inline in the main loop.\n- Queued commands that an interrupt clears are now recorded with the reason `cleared_on_cancel`.\n- 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.\n- 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.\n\n**Evidence**\n\n`; stopping background agents.`, `cleared_on_cancel`\n\n- Area: Headless Mode\n- Names: `--max-budget-usd`\n- Tier: Use it now\n- Useful: 4\/5\n- Signal: 3\/5"}