---
title: Session guard and runaway guards
description: Pause sessions that stall, loop or overspend, set time and dollar caps with session_guard, and set an output budget with guards.
section: security
order: 70
audience: [user, operator, builder]
sources: [packages/harness/src/guards, docs/session-guard.md, packages/harness/src/config/schema.ts]
features: [security.session-guard, security.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 {#quick-start}

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

## The session guard {#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:

```text
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 {#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:

```json
{"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 {#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](/docs/harness.md)). 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 {#related}

- [The automation section](/docs/automation.md): schedules and the inbox.
- [Guardrails](/docs/security/guardrails.md#kinds): `spend` rules.
