Spend Budget

The spend budget is one of Forge's four enforced controls. It bounds cost: when a configured ceiling on tokens, dollars, or tool calls is crossed, the tool returns a non-zero exit. It is the complement to the verify circuit-breaker, which bounds iterations.

Commands

forge budget record --change <c>   # add spend, enforce ceiling
forge budget check  --change <c>   # read-only verdict
forge budget reset  --change <c>   # clear the ledger

Each change keeps its own ledger:

# .forge/changes/<c>/budget.yaml
tokens: 1200
usd: 0.42
tool_calls: 37
records: 5

How enforcement works

• record adds reported spend to the ledger and returns non-zero with BUDGET EXCEEDED when a configured ceiling is strictly crossed. Ceilings are set with --max-tokens N, --max-usd X, and --max-tool-calls K.
• check is read-only and gives the same verdict without adding anything.
• reset clears the ledger.

Exactly at the limit is fine

Reaching exactly a configured limit is within budget. Only strictly going over blocks. 1000/1000 passes; 1001/1000 blocks.

No ceiling means no blocking

With no --max-* ceiling configured, the ledger simply accumulates spend and never blocks. Enforcement only turns on when you give it a ceiling to enforce.

The honest limit

Forge is not inside the model's inference loop, so it does not meter tokens itself. Whoever holds the numbers — a host hook, or the agent — reports spend into the ledger, and Forge enforces the ceiling against what was reported.

• Tool-call count is reliably reportable from a PostToolUse hook (one call, one increment).
• Tokens and dollars need host support: your host must expose usage, and you pipe it in with forge budget record --tokens <n> --usd <x>.

Division of labor

The reporter knows the numbers; the enforcer owns the ceiling. Forge is the enforcer. See Connect a live agent for wiring a host hook that feeds the ledger.

Example

$ forge budget record --change checkout --tokens 600 --max-tokens 1000
Budget[checkout]: tokens=600 usd=0.00 tool_calls=0 (records=1)
Budget: within limits
# exit 0

$ forge budget record --change checkout --tokens 600 --max-tokens 1000
Budget[checkout]: tokens=1200 usd=0.00 tool_calls=0 (records=2)
BUDGET EXCEEDED — tokens 1200/1000. STOP and escalate to a human; a human resets with: forge budget reset --change checkout
# exit 1

The first record lands at 600/1000 and passes. The second brings the total to 1200/1000, strictly over the ceiling, so it prints BUDGET EXCEEDED and returns exit 1.

Where it fits

The budget bounds SPEND; the circuit-breaker bounds ITERATIONS. Together they cap the two ways an autonomous loop runs away — doing too much work, and spending too much doing it. Both emit into the session timeline so cost is auditable and attributed.

Next steps

• The enforcement doctrine — where the budget sits among the four controls.
• Verify circuit-breaker — the sibling gate that bounds iterations.
• The guardrails gate — the control that blocks dangerous actions.
• Session timeline — where every spend record lands, attributed and auditable.
• Connect a live agent — wiring a host hook that feeds the ledger.