Skip to content
Docs menu

Session guard and runaway guards

Pause sessions that stall, loop or overspend, set time and dollar caps with session_guard, and set an output budget with guards.

View .md

A model that keeps calling tools without getting anywhere costs money and fills the context. Venom has two layers against that: the runaway guards, which refuse a looping call, and the session guard, which pauses a whole session. Both pause rather than kill: the session keeps its context, and your next message continues it.

Quick start

session_guard:
  stall_calls: 12     # 0: off
  max_minutes: 90     # unset: no limit
  max_usd: 5
guards:
  output_budget: 20000

The session guard

The session guard watches the main session (a subagent's calls count as its parent's) and pauses it on:

  • A stall: stall_calls model calls in a row with no progress. Progress is a file changed (a successful edit, write or patch) or a tool kind the session hadn't used since your last message. The window counts as a stall only when the calls are near-identical: at most a third of them (and at least 3) are distinct tool-and-argument pairs. Polling one status command or retrying one call reads that way; reading many different files does not.
  • A time or spend limit since your last message: max_minutes and max_usd (list price). Useful for venom serve sessions an automation or a phone drives.

When it fires, the run stops and the session pauses with one notice:

Session paused: 12 model calls in a row with no progress ... Send a message to continue.

Without a UI (venom serve, headless), it leaves one durable inbox item titled Paused: … with the last calls. Any later tool call is refused until a person writes. To resume, send a message; in venom serve the inbox item resumes it too (approve, or reply with the next prompt). The counters start again from that message.

Scheduled runs have their own max_usd and max_minutes caps (default 120 minutes). A run that hits either stops with status budget and leaves a Paused: inbox item, with its worktree kept so a reply can continue it.

Key Type Default What it does
session_guard object The session guard
session_guard.stall_calls integer, 0 to 200 12 Model calls in a row with no progress before a pause; 0 turns it off
session_guard.max_minutes integer, 1 to 10080 no limit Pause after this many minutes since your last message
session_guard.max_usd number, 0.01 to 100000 no limit Pause after this much spend since your last message, at list price

In Venom Cloud

An org admin can set a longest run in minutes and a most spend in dollars for a session with no human message (Fleet → Session guard). venom tells the cloud when you last wrote with the x-venom-human-at header on the main agent's requests. Over a limit, every request of that session answers 429 session_paused with x-should-retry: false, until you write again or an admin presses Resume on the Fleet page:

{"error": {"code": "session_paused", "reason": "spend", "limit": 5, "spent_usd": 5.2, "minutes": 12,
  "session_id": "…", "resume_url": "https://…/fleet#paused", "message": "This session was paused: …"}}

This is a cost control, not a security boundary: a client that doesn't send x-venom-human-at isn't guarded.

Runaway guards

These run on every call, before the permission check, so a looping call is refused without a prompt:

Guard Fires on Default
Repeats the same call (tool and arguments) several times in a row 3
Failures the same bash failure, with the same output fingerprint, several times in a row 3
Re-reads reading lines of an unchanged file already returned 6
Tool-call ceiling calls in one run (headless only; with a UI the run goes on without asking) 200
Stuck detector a file edited back to an earlier content (A → B → A → B), or one call failing the same way 3 times with other calls between on
Bash timeout one command's run time 120 s

With a UI you are asked whether to let the call run. Headless, it is denied, and a stuck run posts a Stuck: … item to the inbox. The stuck detector first shifts up one gear (eco → normal → power) once per session, then asks.

Most limits are harness options for apps that embed venom (see the harness section). The one venom.yaml key:

Key Type Default What it does
guards object Run guards
guards.output_budget integer, 1 to 100000000, or null no budget Output tokens a run is meant to use (also --output-budget). When the model stops before about 90% of it, a message says how much is used and to keep going. Stops after 3 nudges when the last two continuations each made under 500 tokens. Never in subagents