opencode permissions and auto-approve, explained
opencode permissions are a permission block in opencode.json. It maps each tool to allow, ask, or deny, with patterns for bash, edit, read and a few other keys ("git status *": "allow", "rm *": "deny"), resolved last-match-wins. Anything at ask prompts you with once, always, or reject. Every way to auto-approve, up to --auto, keeps your deny rules standing. That section is the one most people come here for.
This page explains how each mechanism behaves, the interactions the docs don’t make obvious, and where the model ends. The key-by-key schema, defaults, config layers, and worked examples are in the opencode permissions reference. Wiring workspace rules in is the install guide.
opencode is one of the most-starred open-source coding agents (the repo now lives at anomalyco/opencode, and the old sst path redirects). It has a real rule language, a three-way native gate, an escape hatch that doesn’t waive your denies, and a plugin system that can hook the permission system itself.
The permission system
Rules live in the permission block of opencode.json. That is ~/.config/opencode/opencode.json globally, or opencode.json at the project root, which loads later and wins for the keys it sets:
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"webfetch": "allow",
"bash": {
"*": "ask",
"git status *": "allow",
"rm *": "deny"
}
}
}
There are three verdicts. allow runs without a prompt, deny blocks, and ask fires the native gate. Rules come in two granularities: per tool (read, edit, bash, webfetch, task, skill, and others) and pattern maps on the keys that take them (bash over the parsed command, edit and read over the file path, webfetch over the URL; see the full key table).
Resolution is last-match-wins, so order is how you set specificity. A catch-all "*": "ask" followed by "git status *": "allow" quiets the safe case and keeps the prompt for everything else. A bare "git status" matches only the bare command, so the star matters. Per-agent overrides exist too (agent.<name>.permission.*, or frontmatter in agent Markdown), and agent rules take precedence. The built-in plan agent asks on every file edit and every bash command by default.
Know the defaults before you trust them: most tools default to allow. Only a few things ship restrictive. read denies *.env files by default (allowing *.env.example). Two guard pseudo-tools default to ask: external_directory (touching paths outside the project) and doom_loop (the same call repeated three times with identical input, a tripwire for stuck agents). Everything else is quiet until you write rules.
The pattern language is glob-over-command-string. That is enough for real policy, with the usual caveat of string matching: a command has many spellings. rm * doesn’t match command rm, an interpreter wrapper, or a deletion done with find -delete. Treat patterns as a record of intent for the common spellings, not as a boundary. Every harness’s denylist has taught the same lesson.
The native gate: once / always / reject
A tool resolving to ask prompts the human with three answers. The middle one is the design choice to notice: always approves the pattern for the rest of the session, so the same call shape stops asking. The third identical yes becomes a session rule instead of a fourth prompt. Scoping it to the session, not forever, is the right default.
One thing to know about always: within its session it quietly turns an ask into an allow, and nothing records it where you can review it. The prompt is pleasant to use. What it built up over a long session is what you will want an independent record of.
The --auto flag
--auto skips the ask prompts, but explicit deny rules remain enforced. Compare Cline’s CLI (auto-approve everything, on by default) or the yolo modes that waive whole rule systems. opencode’s escape hatch removes the human, not the policy.
The catch: anything you gated only with ask becomes an allow under --auto. If a rule matters unattended, it has to be a deny (or be decided by a policy layer), because the ask tier disappears exactly when nobody is watching. This is the empty-chair test applied to one flag.
Auto-approve in opencode, safely
“How do I stop opencode asking me?” has four answers. They differ in scope, in what they leave gated, and in whether anything records what you waved through. The binary’s own help text for the widest one sums it up: --auto auto-approve permissions that are not explicitly denied (dangerous!) (1.18.4). Narrowest first.
1. Allow patterns: per command shape, permanent, reviewable. This is the right default. Auto-approve the shapes you’d approve every time and leave the rest at ask. Last-match-wins means the broad rule goes first and the exceptions after it:
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"read": "allow",
"edit": "ask",
"webfetch": "ask",
"bash": {
"*": "ask",
"git status*": "allow",
"git diff*": "allow",
"git log*": "allow",
"npm test*": "allow",
"npm run lint*": "allow",
"rm -rf *": "deny",
"git push --force*": "deny"
}
}
}
This goes in ~/.config/opencode/opencode.json, or at the repo root to apply to one project (the project file wins there). It is the only auto-approve that survives a restart and sits in a file you can diff. Patterns match the command string, so rm -rf * catches that spelling and not find -delete. Put destructive shapes in deny to record intent, not as a boundary.
2. always at the gate: per shape, session-scoped, unrecorded. When the native prompt fires, always approves that call shape until the session ends, then forgets. It suits the third identical npm test in a long session. Nothing outside opencode records what got promoted.
3. --auto: everything at ask, for the run. Every permission that isn’t an explicit deny is approved. Denies still hold, which is why it is the best-behaved yolo flag on the comparison page. But everything you relied on the prompt for is now an allow, including edit, external_directory, and doom_loop, unless you wrote a deny. Unattended, this is the flag you will reach for. The section below covers what still stands under it.
4. Policy pre-approval: a rule skips the prompt, and a row records it. With the ACP plugin installed, every tool whose permission resolves to ask reaches permission.ask before the prompt renders. An ACP allow sets the permission to allow, so there is no prompt and the call runs. The decision, the tool, the arguments, and the session land in the audit log. An ACP ask leaves the native once/always/reject gate to fire as it would without the plugin.
So a workspace rule like “git, npm test, and reads are fine; edits ask; anything touching production asks” is an auto-approve that is the same on every machine with the plugin, instead of one opencode.json per laptop. The permission block still matters. A tool at allow in your config never reaches permission.ask, which is why the installer sets bash, edit, and webfetch to ask. It fills gaps only and never overrides a value you set.
What stays gated
Whatever you auto-approve, a call still stops when:
- Your config says
deny. Explicit deny patterns hold underalwaysand under--auto. - Policy says
deny. With the plugin,tool.execute.beforeruns on every tool call, including tools atallowthat never see a prompt, and an ACPdenythrows. That is how opencode blocks from that hook. The agent sees the reason:[ACP] Denied by policy: <reason>. - Policy says
askand someone is there. An ACPaskon a tool ataskin your config shows up as the native gate.tool.execute.beforehas no ask option, so anaskverdict reaching a tool atallowcan only deny. That is one more reason to keep the block.
What always blocks
Under the workspace policy sits the hardline floor, a short list that denies in every workspace, above policy. No tenant setting, tier default, standing approval, always, or --auto can allow it. The bar is that no legitimate agent task ever needs it:
- recursive delete of the root filesystem, a system directory, or the home directory (quoting and
${HOME}spellings included) mkfsddor a redirect onto a raw block device- a fork bomb
kill -1shutdown,reboot,halt,poweroff,init 0or6,systemctl poweroff
Commands wrapped in sh -c '…' or eval '…' are scanned as commands. A hit comes back as:
[ACP] Denied by policy: hardline floor: recursive delete of the root filesystem — blocked unconditionally; this pattern cannot be allowed by policy or approval
The floor is evaluated on the gateway, so it holds whenever the gateway answers. If the gateway is unreachable, the plugin fails open by default (see below). Set ACP_FAIL_MODE=closed for runs where the floor must hold with no one watching. Everything softer is ordinary policy that your workspace sets, and you can widen it as far as you like without touching the floor.
Unattended: one more setting
If the gateway is unreachable, the opencode plugin fails open by default. The call proceeds, with one loud warning per session, because an ACP outage must not lock you out of an attended session. For an --auto run nobody is watching, flip it: export ACP_FAIL_MODE=closed (or echo closed > ~/.acp/failmode). The shared ACP hook on Claude Code, Cursor, Codex and Qwen Code reads the same setting, and so does the opencode plugin. The pi and Prime Agent extensions have no such switch: attended sessions fail open and unattended ones fail closed.
A policy deny blocks regardless of fail mode. The mode only decides what happens when there is no answer at all. The installer’s default path sets up a workspace for opencode. It skips opencode under --local, and says so.
The plugin surface
opencode has a JS/TS plugin system. Modules export hooks that run in-process. The ones that matter for control:
permission.askfires when a tool’s permission resolves toask. A plugin can resolve the prompt in code: pre-approve, deny, or leave it to the human. Few harnesses expose their permission system itself as an extension point, not just the tool calls.tool.execute.beforefires before execution, and a throw blocks the call. It is deny-only.tool.execute.afteris observational and fires after the result exists.- A general event bus (
permission.asked/permission.replied,command.executed,file.edited, session events) lets a plugin observe token usage, costs, and tool results in-process.
Three caveats from the field. First, the permission hook only fires for tools that resolve to ask. A tool at allow never touches it. A plugin that needs to see every call must pair it with tool.execute.before as a backstop, which can only deny, not ask. Second, plugin coverage is only as complete as the permission block routing tools into it, so config and plugin have to be set up together. That is why our installer writes both. Third, plugins auto-load from the project’s .opencode/plugins/ directory with no registration step. That is convenient, and it also means a cloned repository can ship code that runs inside your agent with your permissions. Treat project plugin directories like a repo’s install scripts.
What’s not there
- No sandbox. No OS-level isolation ships with opencode. The boundary is the permission system.
- No native audit beyond the session log. That is the run’s own record, on the run’s own machine. The always promotions in particular pile up unseen.
- Per-machine config.
opencode.jsonsits wherever each install put it, and two machines’ effective policies drift apart. The one native answer is the managed config layer (/etc/opencode/,/Library/Application Support/opencode/), which opencode loads last and documents as not user-overridable. It pins the rule on that machine and records nothing about what the rule did (locking a rule).
Where the native model ends
opencode is strong on the attended side: a real rule language, an escape hatch that keeps your denies, and a permission system a plugin can hook. The limits are the usual four. The record is written by the process it describes, the policy is per machine, the ask tier disappears unattended, and the rules don’t travel to your other harnesses.
Our plugin fills that gap using opencode’s own extension points. Workspace policy resolves permission.ask: allow pre-approves the prompt away, deny blocks, and ask falls through to the native once/always/reject gate, so the prompt you know stays. tool.execute.before backstops the rest, and every decision lands in a ledger off the machine. The same policy applies on opencode, Claude Code, dsh, and Hermes, with one place to see what ran and why.
Frequently asked questions
How do permissions work in opencode?
A permission block in opencode.json maps tools to allow, ask, or deny, with per-tool entries and bash command patterns like “git status*”: “allow” or “rm *”: “deny”, resolved last-match-wins. A tool resolving to ask fires opencode’s native gate, where the human answers once, always, or reject. Tools not covered by an entry follow the defaults.
How do I auto-approve tool calls in opencode?
Four ways, from narrowest to widest. Allow patterns in the permission block (“git status*”: “allow”) auto-approve one command shape permanently and reviewably. Answering always at the native gate auto-approves that shape for the rest of the session. The --auto flag auto-approves every permission that is not explicitly denied, and the binary’s own help text calls it dangerous. And with the ACP plugin, a policy allow sets the permission to allow before the prompt renders, so the call is pre-approved with an audit row and denies still fire. Whichever you pick, a deny always wins.
Does opencode's --auto flag disable permissions?
It skips the ask prompts, but deny rules are still enforced. Full-auto mode in many harnesses waives everything, while opencode keeps your explicit denies standing. What --auto removes is the human judgment on the ask tier, so anything you only gated with ask becomes an allow when the flag is on.
What can't be auto-approved in opencode?
Three things hold whatever you do at the ask tier. Explicit deny patterns in your permission block survive --auto. With the ACP plugin, a policy deny throws [ACP] Denied by policy:
Can a plugin intercept opencode's tool calls?
Yes. opencode has a JS/TS plugin system whose hooks run in-process, including hooks on the permission system itself (permission.ask) and on tool execution (tool.execute.before/after). One caveat from field experience: permission.ask only fires for tools whose permission resolves to ask, so a plugin that wants to see every call needs tool.execute.before as the backstop, and that hook is deny-only.
What audit trail does opencode keep?
The session log, which is the run’s own record on the machine that ran it. There’s no native decision ledger recording what was evaluated and why across sessions or machines. opencode’s event bus is rich enough that a plugin can build one (token usage, tool results, and costs are all observable in-process), but nothing ships by default.
Where do opencode permission settings go?
In the permission key of opencode.json, globally at ~/.config/opencode/opencode.json or per project at the repo root. Layers merge, a project file can loosen a global rule because it loads later, and managed config overrides everything. The full layer order is in the opencode permissions reference.
What does each opencode permission answer do?
When a call resolves to ask, once approves that request only, always approves matching requests for the rest of the current session, and reject denies it. Always is session-scoped and recorded nowhere you can review; to keep an approval, write it as an allow pattern in the file.
Running opencode? One command adds a plugin. Each tool call it sees is recorded, and a force-push, destructive SQL or curl | sh is blocked until you approve it on the console or from the email.
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
irm https://agenticcontrolplane.com/install.ps1 | iex
What the installer writes · opencode guide · free up to 5 agents