# Spend Budget

The spend budget is one of Forge's four [enforced controls](/harness/overview). 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](/harness/circuit-breaker), which bounds iterations.

## Commands

```sh
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:

```yaml
# .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.

::: info 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.
:::

::: warning 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>`.

::: tip Division of labor
The reporter knows the numbers; the enforcer owns the ceiling. Forge is the enforcer. See [Connect a live agent](/harness/live-agent-hooks) for wiring a host hook that feeds the ledger.
:::

## Example

```text
$ 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](/harness/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](/harness/timeline) so cost is auditable and attributed.

## Next steps

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