Budgets for AI coding agents: tool-call limits and spend per run
Preview guide. We’re verifying these steps against the public installation.
By Nodrail · 6 min read
On this page
A budget for an AI coding agent is a limit on how much one agent may do in one step or one run: a number of tool calls, tokens or dollars. In Nodrail a budget is an entry in your rules file. Near the limit, decisions carry a warning. Over it, the agent's next actions are denied or sent to a person. Tool calls are counted by Nodrail itself. Tokens and dollars are only as accurate as what the agents report.
This guide uses Claude Code with example agents dev, qa, reviewer and github. The names are yours to change.
The agent names, rules and numbers in this guide are illustrative. Adapt them to your own agents and test them before relying on them.
Why a coding agent needs a budget
Agents get stuck. A dev subagent can loop on a failing test for 200 tool calls, or rewrite the same file again and again. Nothing is wrong with any single call, so per-call rules allow each one. The problem is the total.
A budget turns "this has gone on too long" into a rule. When the agent reaches it, a person looks before it continues.
Runs and steps
Budgets count against a run or a step.
- A run is one piece of work. In the Claude Code integration the run key is the
NODRAIL_RUNenvironment variable when it is set. Otherwise it is the repository and branch the session started on, such asgithub.com/acme/app/fix-42, kept for the whole session so switching branch doesn't switch runs. On the default branch, or with no branch, it is the Claude Code session. A call that arrives with no run at all is held by every budget that covers it: a budget that can't count fails closed. - A step is one agent working inside the run, from start to finish. Each time
devis dispatched is a new step.
per: step resets with every dispatch. per: run adds up across the whole piece of work.
The budget entries
- required_engine_version: 3
- budget: Builder step limit
step_agent: dev
per: step
tool_calls: 60
warn_at: 40
otherwise: require_approval
- budget: Run spend
per: run
usd: 20
otherwise: deny
The first entry limits each dev step to 60 tool calls. From call 40, each decision carries a warning. Past 60, every further action by dev in that step needs approval.
The second entry has no step_agent, so it applies to every agent in the run. Once the agents together have reported USD 20 or more, further actions in the run are denied.
The fields:
| Field | Meaning |
|---|---|
budget | A name. It shows in the explanation when the budget is hit. |
step_agent | Optional. Only that agent's steps count and are held. Without it, every agent. |
per | step or run. |
tool_calls, tokens, usd | The limit. Set exactly one; use one budget per limit. tokens and usd are known only when a step ends, so limit them per run. |
warn_at | Optional. Below the limit. From this value, decisions carry a warning; the effect does not change. |
otherwise | What happens over the limit: require_approval or deny. |
Files with budgets need required_engine_version: 3. Older engines refuse them instead of ignoring them.
What happens over the limit
Over a budget, the otherwise effect is added to every action by that agent in that scope. Like a gate, a budget never allows anything. It adds a deny or a review, and the usual precedence decides: deny, then review, then allow. An action still needs an allow rule to run.
Locally, require_approval makes Claude Code ask the person at the keyboard. In Nodrail Cloud, it creates a request in Approvals, and Insights counts how often each budget held an action and in which runs.
At or past warn_at, the decision carries a warning and nothing else changes. Use it to see the agent coming up on the limit before it stops.
What is counted and what is reported
This is the part to get right before you rely on a budget.
Tool calls are counted. Every tool call the integration decides is recorded as an action in the run. tool_calls counts those actions for the step or run, including the one being decided, so a limit of 60 allows the 60th call and holds the 61st. Nodrail sees these calls, so the count does not depend on the agent.
Tokens and dollars are reported. tokens and usd add up what the agents' receipts reported when they finished. A receipt is the short block an agent writes at the end of its final message. If an agent ends without a receipt, or with a receipt that has no usage, there is nothing to add. A token or dollar budget limits only what agents report.
Two consequences:
- A spend budget is checked against finished steps. An agent that is still working has not reported yet, so a single long step can go past a spend limit before the run sees it. Use a
tool_callslimit per step to stop that case. - Do not use a
usdbudget as a billing control. Your model provider's own spend limits are the control for that. The run budget is a signal inside your workflow.
Choosing numbers
There are no right numbers. Start by watching:
-
Run your agents for a few days with a generous limit,
otherwise: require_approval, andwarn_atwell below the limit. -
Look at the recorded steps. The local CLI lists them:
nodrail-policy runs list nodrail-policy runs report -
Set the step limit a little above what normal steps use. Steps that hit it are the ones worth a look.
Give builders and reviewers different limits. A reviewer step that makes 60 tool calls is unusual. A dev step that makes 60 may be normal.
Limits
- Counts depend on what the integration sees. Calls that do not pass through the hook are not counted. See the APF boundary notes.
- The run key and agent names are declared by the integration, not authenticated. Locally the history is a file in your repository's git directory.
- Reported usage is what the agent said. A receipt can be wrong or missing.
- Budgets and pricing are separate. A budget does not change what Nodrail Cloud counts. Cloud counts governed actions on every plan, as described on pricing. Budgets themselves are on every plan.
Next steps
- Every field, the hook setup and how to test gates in CI: Runs, gates and budgets (preview).
- Hold the pull request until QA and review passed: stop an AI coding agent from opening a pull request before QA (preview).
- Make your agents report a verdict and usage: agent receipts and run history (preview).
- Read the rule format in Agent Policy Format, and set up the local hook with Getting started.
Choose a metric your harness can supply. Test a run at its limit and a run with missing history. Write a budget in APF (preview) and inspect the run inputs expected by the library.