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.
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: 20000The 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_callsmodel 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_minutesandmax_usd(list price). Useful forvenom servesessions 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 |
Related
- The automation section: schedules and the inbox.
- Guardrails:
spendrules.