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.

Time: 5 minutesTest build: no real money

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.

  1. 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 once
  2. Cap the agent

    Amounts are nano-USD strings: $1 = "1000000000". This caps research-bot at $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) and remaining_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.

  3. Make sure the agent is named

    Claude Code sends x-claude-code-agent-id, x-claude-code-parent-agent-id and x-claude-code-session-id by itself. On the OpenAI routes you can also send x-petrova-agent-id and x-petrova-session-id. A malformed id is refused, never dropped, so a cap cannot be skipped by a typo.

  4. 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.

  5. 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 answers 429 with x-petrova-loop: pause before 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.