Guides / Cap a runaway agent
Cap a runaway agent
Give every agent and session a dollar cap, see what happens when one hits it, and how loop pause stops repeats.
For: A team lead whose agents run unattended.
Petrova checks caps before it sends a call anywhere. A call that would cross a cap is refused with nothing held and nothing charged. Caps can be set for the whole account, a project, a key, an agent or a session. A parent agent's cap covers itself and every child agent that names it.
Use a key that can set caps
Setting caps needs "Set caps" (
budget:write). Keep it on a separate key from the one your agents spend with, so an agent can never raise its own cap.npm run sandbox:key -- --caps # a key with budget:write, shown onceCap the agent
Amounts are nano-USD strings: $1 =
"1000000000". This capsresearch-botat $5:curl -s http://127.0.0.1:4100/v1/budgets -H "authorization: Bearer $CAPS_KEY" -H 'content-type: application/json' \ -d '{"scope":"agent","ref":"research-bot","limit_nusd":"5000000000"}'The answer shows
committed_nusd(charged plus held right now) andremaining_nusd. Other scopes:"account"(no ref),"project"and"key"(a project or key id of your account),"session"(the session id). In the dashboard: Caps.Make sure the agent is named
Claude Code sends
x-claude-code-agent-id,x-claude-code-parent-agent-idandx-claude-code-session-idby itself. On the OpenAI routes you can also sendx-petrova-agent-idandx-petrova-session-id. A malformed id is refused, never dropped, so a cap cannot be skipped by a typo.Watch it stop
Try it in the sandbox: run a runaway agent and watch the cap stop it. The refused call gets:
HTTP 429 x-should-retry: false {"type":"error","error":{"type":"rate_limit_error","message":"Spend limit reached ..."}}Claude Code and the SDKs treat this as final and do not retry. On OpenAI routes it is
429 spend_limit_reached.Loop pause catches repeats
If the same tool call shows up 3 times in the last 20, the answer carries
x-petrova-loop: warn. At 5 times (or an A-B-A-B pattern 8 times) Petrova answers429withx-petrova-loop: pausebefore anything is held. That paused call costs $0.
What can go wrong
403 scope_denied: this key cannot set caps. Use the caps key.400 invalid_budget: a bad amount, or a project or key from another account.- Only an operator can turn loop pause off, for the whole process. There is no per-agent "keep going" switch yet.
Next
Checked against the code on 16 November 2026.