Budget Guard

Budget Guard

Inputs

• $run: the run to bound — a phase, a loop, or the whole pipeline. Defaults to the run being launched in the current turn.

Overview

Give every autonomous run a contract it cannot exceed. Budget-guard is not an action so much as a discipline the other skills wrap themselves in: it forces the five stop conditions to exist before the run starts, holds the run to them during, and makes the exit honest. It's what turns a loop that could run forever into one that provably terminates within a known cost.

The five stop conditions (declare all before running)

A run is safe only when ALL five exist. Missing one is the hole a runaway escapes through.

Phase 0: Size the budget to the task and the directive

Set the numbers deliberately, not by reflex:

• If the user gave a token/scale directive (e.g. "+500k", "quick pass", "be thorough"), map it to the budget: a big target → a wider fan-out and more rounds; "quick" → tight caps. In a Workflow, read budget.total / budget.remaining(); the target is a HARD ceiling once reached.
• Scale the hard cap to the work: a typecheck-fix loop rarely needs >6 rounds; a broad audit might take 8. Total agents scale with the item count but stay bounded (and concurrency-capped — see fan-out-work).
• Default token budget when none is given: bound it (e.g. ~150k output tokens for a phase) rather than leaving it open. An unbounded default is not a default.

Success criteria: all five conditions have concrete values, justified by the task and any directive.

Phase 1: Enforce during the run

Check the conditions every iteration / at every barrier, cheaply:

• decrement the iteration/agent counters; compare spend to the budget BEFORE launching the next expensive step (don't discover you're over budget after paying for the overshoot);
• track the progress signal (see converge-loop) so the no-progress rule can fire;
• watch the escalation triggers continuously — an irreversible step or an ambiguity is a stop, whenever it appears.

When any condition fires, halt at the next safe boundary (finish the in-flight unit's commit, don't abort mid-write) and go to Phase 2.

Success criteria: the run cannot exceed any declared limit; a limit hit halts it at a safe point.

Phase 2: Exit honestly (or escalate)

Classify and report the exit:

• done — done-condition met within budget. Report cost used.
• capped / over-budget — limit hit first. Report the honest partial: what's done, what remains, the cost spent. Offer the user the re-scope decision (raise budget / narrow scope / hand off) — never raise it yourself.
• escalated — a named trigger fired. STOP and surface the specific decision (with AskUserQuestion when interactive), then wait. Resume only on the user's answer.

Success criteria: exactly one exit reason; cost reported; any user decision surfaced, not assumed.

Common Rationalizations

Red Flags

• A loop/workflow launched with no stated caps in the transcript.
• Iteration or agent counts climbing past the declared cap.
• "Just one more round" after the no-progress rule should have fired.
• A cap or budget number quietly increased mid-run.
• An irreversible action taken inside an autonomous run without a stop-and-ask.
• A run reported "done" that actually hit a limit (a capped run wearing a success badge).

Guardrails

• Never start an unattended run without all five stop conditions declared.
• Never exceed a declared cap/budget; halt at the next safe boundary and report.
• Never raise your own budget to keep going — that's a user decision.
• Never take an irreversible action or resolve a real ambiguity inside the run — escalate.
• Never report a capped/escalated run as a clean success.

Native goal/loop routing

On Claude Code, compile the five stop conditions into the native machinery instead of only tracking them by hand: the done-condition becomes the /goal objective (verified each turn by a separate model — the strongest form of "machine-checkable"); the hard cap becomes /loop's count/time stop; the budget is the session/turn token target (in a Workflow, budget.remaining() — a HARD ceiling); escalation triggers stay in the run body plus the deterministic guard hooks. The no-progress rule has no native equivalent on Claude Code — keep it hand-tracked (Codex's /goal has it natively: blocked after 3 consecutive stuck turns). Full mapping: converge-loop's references/native-goal-loop.md.

When To Load References

• converge-loop (skill) — the loop-level termination set and no-progress/anti-thrash detectors this guard enforces at the iteration level; its references/native-goal-loop.md holds the /goal + /loop compilation table.
• checkpoint-resume (skill) — so a run stopped at a budget/escalation boundary resumes without redoing finished work.

Output Contract

Report:

1. the five stop conditions used (with values)
2. cost spent (iterations / agents / tokens / time) vs. the budget
3. exit reason — done / capped / over-budget / escalated
4. on a non-done exit: the honest remaining gap + the user decision offered (never taken unilaterally)