Skip to content
Docs menu

Permission modes and rules

Choose a permission mode, write allow, ask and deny rules, and understand the order in which venom judges every tool call.

View .md

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

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:

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

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 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): 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, --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

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

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

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

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; 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 never allows; its deny and ask rules beat everything

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_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

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

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 for how to verify it.

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.