---
title: Permission modes and rules
description: Choose a permission mode, write allow, ask and deny rules, and understand the order in which venom judges every tool call.
section: security
order: 10
audience: [user, operator, builder, agent]
sources: [packages/harness/src/permissions/modes.ts, packages/harness/src/permissions/engine.ts, packages/harness/src/permissions/auto.ts, packages/harness/src/extensions/permissions.ts, cli/src/branding.ts, cli/src/keys.ts, docs/configuration.md]
features: [security.permissions]
---

Every tool call the agent makes (a read, an edit, a bash command, a web fetch, an MCP tool, a subagent) goes through
the permission engine before it runs. The engine answers allow, ask or deny. "Ask" opens a dialog in the TUI; in
print, json and rpc modes, and anywhere else nobody can answer, an ask becomes a deny with the reason, so a headless
run never hangs.

## Quick start {#quick-start}

```bash
venom                                   # starts in default mode: edits and unlisted commands ask
venom --permission-mode accept-edits    # workspace edits go ahead, commands still ask
venom --yolo                            # no prompts, bash in the OS sandbox
venom --plan                            # read-only, the agent writes a plan to .venom/plans/
```

In the TUI, `alt+m` (or the leader `ctrl+g m`) cycles the modes, `/mode <name>` sets one and `/mode` alone opens a
picker. `/permissions` shows the current mode, every active rule and the file it came from. `/sudo`, `alt+s` or
`ctrl+g s` toggles sudo mode for the session.

A project's rules, in `venom.yaml`:

```yaml
permissions:
  mode: default
  allow:
    - "bash(npm test:*)"
    - "bash(go test:*)"
  ask:
    - "bash(git push:*)"
  deny:
    - "bash(terraform apply:*)"
    - "read(~/.kube/**)"
```

## Modes {#modes}

| Mode | Reads in the workspace | Edits in the workspace | Bash |
|---|---|---|---|
| `plan` | allow | deny, except `.venom/plans/` | read-only allowlist only, no command substitution |
| `default` | allow | ask | read-only allowlist or an allow rule, else ask |
| `accept-edits` | allow | allow | as default, plus `mkdir`, `touch`, `cp`, `mv` and output redirects inside the workspace |
| `auto` | allow | allow | as accept-edits, but what would ask only because of the mode default goes to a classifier instead of you; bash always runs in the OS sandbox |
| `yolo` | allow | allow | allow; bash runs in the OS sandbox unless `--no-sandbox` |
| `sudo` (session only) | allow | allow | allow, without the OS sandbox unless `--sandbox`; no prompts at all |

The `alt+m` cycle is `plan → default → accept-edits → auto → yolo`. Entering yolo from the cycle or `/mode` asks for
confirmation the first time in a session and says whether bash will be sandboxed; `--yolo` and config don't ask.
`auto` is skipped when no OS sandbox is available.

Mode names accept Claude Code's spellings too: `read-only` and `readonly` mean `plan`; `ask` and `normal` mean
`default`; `acceptEdits` means `accept-edits`; `bypass` and `full-access` mean `yolo`; `bypassPermissions` and
`dangerously-skip-permissions` mean `sudo`; `dontAsk` means `default` (headless runs already deny every ask).

`--mode` is pi's output mode (`text`, `json`, `rpc`), not a permission mode. `venom --mode accept-edits` stops with
exit 2 and tells you to use `--permission-mode`.

### Auto mode {#auto}

`auto` is accept-edits plus a judge. Reads, read-only commands, allow rules and workspace edits run with no
classifier. Of the calls that would still ask, only those that ask because of the mode default (an unlisted bash
command, an MCP or app tool) go to a classifier on the `fast` model tier (`venom-fast` by default). Every other ask
still comes to you: ask rules, the organisation policy, protected paths, writes outside the workspace, dangerous
commands such as `git reset --hard`, unparseable commands. `web_fetch`, `web_search` and the browser keep asking,
since they run outside the sandbox. The exception is a Venom Computer's own browser (a [computer
chat](/docs/agents/computer-chats.md#asks)): there auto opens and uses sites without asking, below.

Changing the mode of a `venom serve` session (`PUT /v1/sessions/{id}/mode`) also settles a waiting approval the new
mode allows, as allow once; the audit log records it as `via: mode`.

- The classifier sees the project directory, your last six messages and the call as JSON. It never sees assistant
  text or tool output, which is where injected instructions come from.
- It blocks pushes, publishes and deploys nobody asked for, history rewrites, credential reads, CI and agent-config
  changes, download-and-run, and anything that follows instructions from a file or tool output.
- Broad allow rules (`*`, `bash(*)`, wildcards over interpreters such as `bash(python:*)` or `bash(npx:*)`) are
  ignored while in auto; narrow rules still allow.
- Three blocks in a row, or 20 in a session, hand the next decisions to you. Headless, the run stops.
- With no OS sandbox, or with `--no-sandbox`, auto is capped to accept-edits.

| Key | Type | Default | Env var | What it does |
|---|---|---|---|---|
| `permissions.auto.timeout_ms` | integer, 100 to 600000 | none (the classifier request's own 30 s) | `VENOM_AUTO_TIMEOUT_MS` | Give up on one review after this many milliseconds. A timeout counts as a failure. |
| `permissions.auto.on_failure` | `ask` or `deny` | `ask` | `VENOM_AUTO_ON_FAILURE` | What a failed or timed-out review does. `ask` hands the call to you (headless: denied); `deny` denies it. There is no `allow`. |

The environment wins over the file. Both keys can only make the judge stricter.

### Sudo mode {#sudo}

`--sudo`, `--dangerously-skip-permissions` and `--permission-mode bypassPermissions` start in sudo; `/sudo`,
`alt+s` and `ctrl+g s` toggle it, and toggling off returns to the mode you came from. It is Claude Code's
`--dangerously-skip-permissions`: no approval prompts and bash without the OS sandbox. The status bar shows
`⚠ SUDO (no prompts, no sandbox)`.

What still holds in sudo:

| What | In sudo |
|---|---|
| The hard-deny list (below), secret reads and writes, shell rc and system writes | denied |
| A call the engine couldn't check against that list: a parse error, a glob that may reach credentials, a destructive command whose targets exist only at run time | denied; rewrite it as plain commands on literal paths |
| Your `deny` rules | denied |
| Your `ask` rules | ask: the one way to keep a check in sudo |
| The organisation policy (tool gates, deny and ask rules, the audit log) | as always |
| The browser typing a credential or paying | ask |

Sudo is never saved: a permissions file's `"mode": "sudo"`, Claude's `defaultMode: bypassPermissions` and an agent
file's `permissionMode: sudo` all mean yolo, and a resumed session never gets it back. An organisation policy that
limits the modes or requires the sandbox refuses it everywhere. `venom serve` refuses a client's `mode: sudo` with
403 `sudo_forbidden` unless it was started with `--allow-sudo`.

## How a call is judged {#order}

The first step that applies decides:

1. **Hard deny, in every mode.** `rm -r` (or `find -delete`) on `/`, `~`, system directories or anything outside the
   workspace and temp dirs; `mkfs`, `dd of=/dev/…` and disk tools; `curl … | sh` and its variants; force-push or
   delete of `main`, `master`, `trunk` or `develop`; fork bombs; `kill -1`; shutdown and reboot; reads or writes of
   secrets (`~/.ssh`, `~/.aws`, `~/.gnupg`, keychains, `.env*` other than templates such as `.env.example`, private
   keys); writes to shell rc files and system paths.
2. **Deny rules**, from any source.
3. **Ask rules**, from any source, also in yolo.
4. **Plan mode** denies anything that is not read-only.
5. **Protected paths ask in every mode**, yolo included: agent config and instructions (`.venom/`, `.claude/`,
   `AGENTS.md`, `CLAUDE.md`, `VENOM.md`, `.mcp.json`, `~/.claude`, `~/.venom`), `.git/` internals, and any write
   outside the workspace. A trusted allow rule that names the path unlocks it. When bash runs in the sandbox, a
   bash write outside the workspace is denied with the reason instead, since the sandbox would refuse it anyway.
6. **Allow rules** from trusted sources, and the built-in read-only allowlist.
7. **The mode's default** (the table above). Dangerous but legal operations (`sudo`, `git reset --hard`,
   `git push --force` to other branches, `rm -r` in the workspace, computed command names) ask outside yolo even
   when an allow rule matches.

Within a class there is no specificity ordering: deny beats ask beats allow, first match wins. These are Claude
Code's semantics.

Temp dirs count as the workspace: `os.tmpdir()`, `$TMPDIR`, `/tmp`, `/private/tmp` and, on macOS, the per-user
temp dir under `/var/folders`.

### Bash is parsed, not prefix-matched {#bash}

venom splits a command on `;`, `&&`, `||`, `|`, `&` and newlines, descends into `$(…)`, backticks, `<(…)`, subshells,
`bash -c '…'` and `eval`, strips wrappers (`sudo`, `env`, `nice`, `timeout`, `xargs`, `command`) and judges every
simple command with its redirects. Unparseable input asks, even in yolo. Paths in arguments go through the path
policy, so `cat ~/.ssh/id_rsa` is denied although `cat` is read-only. A glob or recursive walk over your home or
config directories asks in every mode.

The approval names every segment that needs it: `2 commands require approval in default mode: "npm install",
"make deploy"`.

## Rules {#rules}

A rule is `tool` or `tool(pattern)`:

| Rule | Matches |
|---|---|
| `bash(npm test:*)` | `npm test` alone or followed by arguments (`:*` is "this prefix, then anything") |
| `bash(git status)` | exactly that command |
| `edit(src/**)` | edits and writes under `src/` |
| `read(~/.kube/**)` | reads, grep, find and ls there |
| `apply_patch(src/**)` | patches only; patched files are also judged by `edit` and `write` rules |
| `web_fetch(domain:example.com)`, `web_fetch(domain:*.example.com)` | fetches to that host (the older `webfetch(…)` spelling still works) |
| `web_search` | searches; a pattern matches the query |
| `browser(domain:example.com)`, `browser_submit(domain:example.com)` | browser actions, or form submits, on that site |
| `mcp__github`, `mcp__github__create_issue` | every tool of an MCP server, or one tool |
| `task(explorer)` | a subagent by name |

### Where rules come from {#sources}

| Source | May allow |
|---|---|
| `~/.venom/permissions.json` (`allow`, `ask`, `deny`, `mode`, `sandbox`) | yes |
| `~/.venom/permissions.json` → `projects["<abs path>"].allow` ("allow always in this project") | yes; kept in your user file so a cloned repo can't pre-approve itself |
| `permissions:` in `~/.venom/config.yaml` | yes |
| `permissions:` in a project's `venom.yaml`, `<project>/.venom/permissions.json` | only once the project is [trusted](/docs/security/trust.md); ask and deny always apply |
| `~/.claude/settings.json` `permissions` | yes |
| `<project>/.claude/settings.json`, `settings.local.json` `permissions` | only once trusted; ask and deny always apply |
| "allow always this session", a slash command's `allowed-tools` (for that turn) | yes |
| The [organisation policy](/docs/security/policy.md) | never allows; its deny and ask rules beat everything |

### Approving {#approving}

The dialog offers allow once, allow always this session, allow always in this project, deny, and deny with a
message for the model. For a compound command, "allow always" stores one narrow rule per segment that asked and
shows them first (`Allow always this session: bash(npm test:*), bash(tee out.txt:*)`). Code on the command line
(`node -e`, `python -c`) gets "allow once" only. An edit that asks only because of the mode default also offers
"Allow all edits in this workspace this session", which is never written to a file. After three edits approved one
at a time, the TUI suggests accept-edits once.

For an MCP tool the denial names the rule to add (`mcp__<server>__<tool>` or `mcp__<server>`): MCP tools ask in every
mode but yolo.

## Web and browser tools {#web}

`web_fetch` asks in every mode but yolo. In yolo it runs without asking only when the host passes the sandbox's
egress allowlist. Loopback, link-local (including `169.254.169.254`), private and CGNAT addresses are denied in every
mode unless a trusted rule names the host. `web_search` asks outside yolo. `--offline` (or `VENOM_OFFLINE=1`) removes
both.

The first browser action on a site asks in every mode, except in auto (and yolo) on a Venom Computer's own browser:
the daemon names that browser to the session, and it runs in the computer's own container, so there a new site needs
no approval. Deny rules, private addresses, ask rules, submissions, frames it can't inspect and the organisation
policy still apply there. Typing into a password, one-time-code or card field, a pay or
order button, and submitting a login or payment form ask in every mode, rules included, with "allow once" only.

## Reference {#reference}

### Flags

| Flag | What it does |
|---|---|
| `--permission-mode <mode>` | Start in `plan`, `default`, `accept-edits`, `auto`, `yolo` or `sudo` |
| `--plan` | Start in plan mode |
| `--yolo` | Start in yolo: no prompts, bash in the OS sandbox |
| `--sudo`, `--dangerously-skip-permissions` | Session-only sudo: no prompts, bash without the sandbox |
| `--sandbox` | Always run bash in the OS sandbox |
| `--no-sandbox` | Never run bash in the OS sandbox |
| `--approve`, `-a` / `--no-approve` | Trust, or ignore, this project's hooks, MCP servers and allow rules for one run |

### venom.yaml keys

| Key | Type | Default | What it does |
|---|---|---|---|
| `permissions` | object | none | Start mode and rules. A project file may only tighten unless the project is trusted. |
| `permissions.mode` | `plan`, `default`, `accept-edits`, `auto`, `yolo` | `default` | The starting mode. `sudo` is never a saved mode. |
| `permissions.allow` | list of rules | `[]` | Allow rules |
| `permissions.ask` | list of rules | `[]` | Ask rules |
| `permissions.deny` | list of rules | `[]` | Deny rules |
| `permissions.auto` | object | none | Auto mode's judge, see [Auto mode](#auto) |

### Keys and commands in the TUI

| Key or command | What it does |
|---|---|
| `alt+m`, `ctrl+g m` | Cycle the persistent modes |
| `alt+s`, `ctrl+g s` | Toggle sudo |
| `/mode [name]` | Set the mode, or open the picker |
| `/permissions` | Show the mode, active rules and their sources, and the organisation policy's restrictions |
| `/sudo` | Toggle sudo for this session |

### The audit log

Every decision is appended to `~/.venom/audit.jsonl`: time, session, directory, mode, tool, summary, verdict,
outcome, how it was decided (`via`), the reason and the rule. See [Audit](/docs/security/audit.md#audit-log) for how to verify it.

## Troubleshooting {#troubleshooting}

- **A headless run says a call was denied "in default mode".** Nobody could answer the ask. Add an allow rule or
  start with `--permission-mode accept-edits` or `--yolo`.
- **"permission mode yolo is off".** The organisation policy limits the modes. `venom doctor` shows the policy and
  its contact.
- **Auto mode isn't in the cycle.** No `sandbox-exec` or `bwrap` was found, or the sandbox is off.
- **A project's allow rules don't apply.** The project isn't trusted. Run `venom trust`.

## Related {#related}

- [Sandbox](/docs/security/sandbox.md): what sandboxed bash can reach.
- [Project trust](/docs/security/trust.md) and [Organisation policy](/docs/security/policy.md).
- [The configuration section](/docs/configuration.md) for the rest of `venom.yaml`.
