Guide 31 of 61 · Cost
Set spend budgets and stop runaway loops
Give each agent task a cost budget and a token rate, see what the agent meets at the cap, and stop loops and runaway subagents with limits of their own.
Give each agent task a cost budget and a token rate, know how each model call is held against the budget before it is sent and charged once its price is known, recognise what the agent sees when it reaches the cap, and stop loops and runaway subagents with limits of their own.
1. Put a budget in the policy
The default packs carry no budget. Add a circuit_breaker under security_boundaries of your agent's policy: max_cost_usd_per_task is the budget in US dollars, max_tokens_per_minute a token rate over a sliding minute, and on_limit_breach what happens to the task once the budget is spent (suspend_and_alert or kill); left unset, a spent budget only refuses the calls and the task keeps running. With scope: task_tree, the default, the task and its subagents share one budget; with task, each has its own. Costs come from the versioned price catalog, so the policy holds no prices.
Lint the policy and restart agentgarmd, which reads it only when it starts. The samples are for a no-root install on Linux; the first guide has the macOS and root variants. While the policy is in mode: audit, a breach is recorded but nothing is refused, suspended or killed.
security_boundaries:
circuit_breaker:
# One budget for the task and its subagents (task: each task its own).
scope: task_tree
max_cost_usd_per_task: 5.00
max_tokens_per_minute: 200000
on_limit_breach: suspend_and_alertagentgarm policy lint ~/.config/agentgarm/agents.d/claude-code.yamlsystemctl --user restart agentgarmdChecked by the walk: these commands ran as written on a no-root Linux install.
See also
Watch your agent for a week, then enforceStart a policy in audit mode, see what enforcing it would have blocked in your own history, fix the rules that get in the way, then switch it to enforce.
2. Launch the agent through the proxy
A budget binds the model calls agentgarm-session's proxy can hold, which are calls it can attribute to a task. agentgarm run sets ANTHROPIC_CUSTOM_HEADERS so that Claude Code sends its task id with every call. A call that names no task, such as one from Codex, takes the task of the process that made it, so it is held all the same; a call from a process in no task, or whose process cannot be found, is recorded but not held. Subscription traffic is never proxied, so a budget counts API-key and gateway-key calls only.
How firmly this holds depends on the platform. On macOS the sandbox lets the agent reach the network only through the proxy, which rates the model-call class B. On Linux, egress through the proxy is best effort, so model calls rate C. On either, the task id is the agent's own claim, honoured only from a process inside that task: an agent that names another task's id cannot spend that task's budget, but its own calls then go unattributed and escape its holds, though they are still recorded.
agentgarm run -- claudeagentgarm statusChecked by the walk: these commands ran as written on a no-root Linux install.
See also
Check that protection is onSee whether AgentGarm's services are up, what assurance level each agent session has and why, and what to do about a bypass alert.
3. Know how each call is held and settled
Before forwarding a call, the proxy asks agentgarmd to hold its estimated cost: the request's input at about four bytes a token plus its output ceiling, priced from the catalog, or the running average cost of the calls under the same budget when that is larger or the model is not priced. When the response ends, the call's catalog-priced cost settles the hold, once. A billed call without a complete price is charged at least what was held; a call that was never billed releases its hold.
A call that would cross the budget is let through only when nothing else in the scope is in flight, so concurrent subagents overspend by at most one call's estimate, plus anything that call costs beyond it, while agentgarmd answers. If agentgarmd does not answer within 250 ms, the call is forwarded without a hold and still charged when it settles, so calls made while agentgarmd is unreachable can add to the overspend. Spend and holds of a task that outlives an agentgarmd restart are restored; its token rate starts over.
4. Recognise the cap
A refused call is answered by the proxy and never reaches the provider, in the provider's error format. Once the budget is spent the agent gets a 403 permission_error, “AgentGarm: the task's budget is reached”, a Budget alert is recorded, and on_limit_breach, if set, applies: on Linux the task's cgroup is frozen or killed, and on Windows its Job Object is suspended or terminated. On macOS, or without a cgroup, a suspend stops the task's whole tree: the root and every process it started, found by parent process and swept again until nothing new turns up, while a process you stopped yourself (Ctrl-Z) is left as it was. A process that detaches from the tree before the sweep reaches it escapes, unless the Endpoint Security client, which is in preview, tracks it. A kill there reaches the root and the processes the Endpoint Security client tracks. A suspended task is denied every further decision and survives a restart of agentgarmd. It stays suspended until root removes its breach hold with sudo agentgarm task resume, the task's id and --hold breach, from outside every governed task preview; it runs again once no other hold is left. Resume is not built on Windows yet, where a suspended task stays suspended until it is killed.
A call that does not fit while another is in flight, or one over the token rate, gets a 429 rate_limit_error with retry-after: 2, “AgentGarm: the task's budget is nearly reached or its token rate is; retry shortly”, and nothing else happens. A warning is recorded once when spend crosses 80% of the budget. Both show among the alerts on the dashboard's Overview and its Alerts screen.
Under a cost budget, a call to a provider that bills in another currency than US dollars, such as the catalog's CNY providers, is refused with a 403, “AgentGarm: the task's budget is in USD and this provider bills in CNY”, without the breach action, since no exchange rate is applied yet. And while a provider's own rate limit for a key is in force, the proxy answers further calls with that key itself, with a 429 and a retry-after until it lifts, so a runaway agent does not burn a shared key's window.
agentgarm ui --open5. Stop runaway loops
agentgarmd counts every call a hook asks about, denied or not, by its action: the command, file path and access, host and port, or tool and arguments, with runs of whitespace collapsed. More than max_identical_tool_calls identical calls within window_seconds is a loop, and its action applies: alert only records it; suspend_and_alert (the default when unset) also denies the call and suspends the task, and kill denies it and ends the task, as for a spent budget. Claude Code sees the denied call as “AgentGarm: the agent is repeating the same call”. Every pack ships with loop detection set to alert. The match is literal on purpose: a loop whose arguments change every time is left to the budget and the token rate.
swarm_governance:
max_subagent_depth: 4
max_concurrent_subagents: 8
loop_detection:
max_identical_tool_calls: 8
window_seconds: 120
action: alert loop_detection:
# More than this many identical calls within the window is a loop.
max_identical_tool_calls: 6
window_seconds: 120
action: suspend_and_alert6. Limit agent swarms
max_subagent_depth caps how deeply subagents nest (a root task is depth 0), and max_concurrent_subagents how many may be live in one task tree. agentgarmd refuses to register a subagent beyond either limit; in audit mode it only logs the breach. A subagent here is a task that a process already inside a governed task registers with agentgarmd, which finds its parent from the process's lineage. Nothing AgentGarm ships registers one today: agentgarm run refuses every launch from inside a governed task, so these limits bind only a client that registers its own tasks. Subagents an agent runs in its own process run inside its task: they share its budget and loop limits but are not counted here. Pair these with scope: task_tree, so that every subagent spends from the root task's budget instead of starting its own. inherit_task_budget under swarm_governance is another way to say the same thing: true means scope: task_tree and false means scope: task, used when scope is unset. A policy that sets both to different scopes does not compile.
swarm_governance:
# A root task is depth 0: a subagent nested deeper than this is refused.
max_subagent_depth: 2
# Live subagents in one task tree.
max_concurrent_subagents: 4