Skip to content

Task budgets countdown

Bernstein adopts Anthropic's Opus 4.7 task-budgets beta header (task-budgets-2026-03-13) and pipes a deterministic per-turn countdown of remaining tokens, dollars, and steps to the agent. Models that see the countdown can finish gracefully instead of running until the budget enforcer SIGKILLs them.

Why it exists

Without a countdown the model has no way to know it is about to be killed. It writes one more file, opens one more tool call, and the orchestrator pulls the rug. Anthropic published the task-budgets-2026-03-13 header in March 2026 specifically so the model can land soft. This module is the integration point.

The banner

Every per-turn user message is prefixed with a single deterministic line:

[budget] tokens left: 18,420 of 64,000 (28%) | $0.42 of $1.50 | steps: 7 of 30 | mode: graceful-finish-on-low

It is generated by bernstein.core.cost.budget_countdown.format_countdown and shared across every adapter so non-Anthropic agents see the same information. The line is intentionally one row of plain text - no ANSI, no JSON - so it survives every transport (stream-json stdout, MCP messages, system-prompt prefixes) and stays cheap enough to inject every turn.

Two budget modes

The agent identity card declares one of two modes via AgentIdentityCard.budget_mode:

Mode Behaviour
graceful-finish-on-low (default) At ≤ 20% headroom or step >= max_steps, the orchestrator hands the agent one final turn to commit work and emit a summary.
hard-stop-on-zero Mirrors Cursor Glass's $5 arbitration pause - the orchestrator fires budget_actions.suggest_downgrade immediately when the headroom hits zero.

Both decisions are computed by should_finish_gracefully which is pure and side-effect free.

Opting in to the Anthropic beta

The Claude adapter only emits the upstream beta header when the operator opts in via env var:

export BERNSTEIN_ANTHROPIC_TASK_BUDGETS=true

When set, the adapter propagates ANTHROPIC_BETA=task-budgets-2026-03-13 to every spawned Claude Code process. Pre-existing operator-set ANTHROPIC_BETA values are preserved - the new value is appended once, idempotently.

Metrics

Two Prometheus surfaces land on /metrics:

  • bernstein_task_budget_graceful_finish_total{role} - counts agents that landed via the soft path.
  • bernstein_task_budget_remaining_at_finish_pct{role} - histogram of the headroom percentage at the moment of finish; lower buckets prove the agent is actually using the countdown.

References