1
# Tool Budget Guard
2
3
Three budgets, checked continuously, with a defined ending when one runs out.
4
5
## The budgets
6
7
| Budget | Guards against | Default |
8
|---|---|---|
9
| Tool calls | Loops and thrash | `max_tool_calls` (40) |
10
| Wall clock | Hangs and slow crawls | `max_wall_clock_s` (900) |
11
| Tokens | Context bloat, cost | 70% of the context window |
12
13
Track all three from the first step. Report them at the end whether or not one was
14
hit. A task that finished at 38 of 40 tool calls was nearly a runaway, and you only
15
learn that if the number is visible.
16
17
## Checkpoints
18
19
Every 25% of the largest budget, stop and answer in one line each:
20
21
1. What have I actually established since the last checkpoint?
22
2. Is the remaining budget enough to finish?
23
3. If not, what is the smallest useful thing I can deliver with what is left?
24
25
Answer 1 being "nothing" twice in a row is a stuck loop. Escalate immediately rather
26
than waiting for the ceiling.
27
28
## Detecting a loop before the budget dies
29
30
Three signals, any one of which means stop:
31
32
- **Repeated call.** The same tool with the same arguments twice in a row.
33
- **Repeated error.** The same error text three times, however you varied the call.
34
- **No new facts.** Two consecutive checkpoints where question 1 is empty.
35
36
The response to a loop is never "try once more." It is to change approach or escalate.
37
38
## When a budget is exhausted
39
40
Follow `on_exhausted`:
41
42
- **report** (default). Stop and deliver partial work. Say what you established, what
43
  you did not, what you would do next, and which budget ran out. Never present partial
44
  work as complete.
45
- **ask.** Same report, then request more budget with a specific number and a reason:
46
  "another 20 calls to check the two remaining candidates."
47
- **abort.** Stop and roll back any partial side effects you own. Use this where a
48
  half-finished state is worse than nothing: migrations, deploys, bulk writes.
49
50
Whatever the mode, never silently continue past a budget. A budget you can quietly
51
exceed is not a budget.
52
53
## Interaction with retries
54
55
Retries spend budget. Count them. A retry policy and a budget that do not know about
56
each other will burn the whole allowance on one failing call. Cap retries at 3 per
57
distinct operation and count each against `max_tool_calls`.
58