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.
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 asbash(python:*)orbash(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:
- Hard deny, in every mode.
rm -r(orfind -delete) on/,~, system directories or anything outside the workspace and temp dirs;mkfs,dd of=/dev/…and disk tools;curl … | shand its variants; force-push or delete ofmain,master,trunkordevelop; 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. - Deny rules, from any source.
- Ask rules, from any source, also in yolo.
- Plan mode denies anything that is not read-only.
- 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. - Allow rules from trusted sources, and the built-in read-only allowlist.
- The mode's default (the table above). Dangerous but legal operations (
sudo,git reset --hard,git push --forceto other branches,rm -rin 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-editsor--yolo. - "permission mode yolo is off". The organisation policy limits the modes.
venom doctorshows the policy and its contact. - Auto mode isn't in the cycle. No
sandbox-execorbwrapwas found, or the sandbox is off. - A project's allow rules don't apply. The project isn't trusted. Run
venom trust.
Related
- Sandbox: what sandboxed bash can reach.
- Project trust and Organisation policy.
- The configuration section for the rest of
venom.yaml.