Enforce a tool-call budget ceiling
An unbudgeted agent run ends when it happens to finish, which is never a number you can quote. Set the ceiling first, meter every call, and stop at the line rather than discovering it in the bill.
Procedure
- State the ceiling before step one, in the units you are billed in:
max_calls=40 max_tokens=200000 max_usd=1.50. - Track a running total from the first call; never estimate the total at the end from a feeling.
- Set a soft alarm at 70% and a hard stop at 100%. At the alarm, decide: finish, simplify, or abort early.
- Charge each step its real cost — a fan-out of ten children costs ten calls, not one.
- Reserve a floor for the final step: never spend the last 10% before the task's own verification can run.
- When the hard stop trips, emit a partial result with the work completed and the reason for stopping, not a silent failure.
- Log per step:
step=7 calls=3 cum_calls=18 pct=45so the trajectory, not just the endpoint, is visible. - If a step's cost is unknown, bound it first with a cheap probe (a
--dry-run, ahead, a count) before committing budget. - Carry the running total across a resumed run by reading it from the checkpoint, not restarting the meter at zero.
- Meter wall-clock separately from tokens; a run can be under budget on tokens and still over on time.
Pitfalls
- Counting only the top-level calls and ignoring nested fan-out, so the ledger is wrong by an order of magnitude.
- Setting the ceiling after the run and reporting whatever it spent as "the budget".
- Hard-stopping with no partial output, wasting everything spent to reach the limit.
- Spending the reserve on exploration, leaving nothing for the verification the task required.
- Treating the soft alarm as a warning to ignore until the hard stop ends the run abruptly.
- Budgeting tokens but not wall-clock, then timing out mid-run with the token limit untouched.
Verification
python3 tools/budget.py notes/action.log --ceiling 40
# prints cumulative calls per step; fails if any step pushes cum_calls past 40
Report the ceiling, the spent total at exit, and whether the final verification step still ran.