Update the guide to the current release (v1.16.2, 2026-06-05), verified against opencode.ai/docs and github.com/anomalyco/opencode. Correctness fixes: - Plugins: tool.execute.before/after and shell.env are top-level hooks with an (input, output) signature, not event.type values. Rewrite both shipped example plugins plus the docs/migration examples so they fire. - Permissions: bash glob maps resolve last-matching-rule-wins (catch-all "*" first), not most-specific-wins. Fix prose, reorder examples, and fix the shipped opencode.json (rm -rf* deny was shadowed by a later rm *). - Drop non-existent permission keys repo_clone/repo_overview (15 keys, not 17); fix steps (integer), deprecate maxSteps/tools, move reasoningEffort into model options; fix the `mise` install command. Currency updates: - v1.15.4 -> v1.16.2; add v1.16 highlights and a changelog section. - Refresh OpenCode Zen lineup/pricing (Claude Opus 4.8, gpt-5.4, gemini-3.5-flash, qwen3.7, grok-build-0.1; correct free-tier IDs). - Add `opencode mcp add`, run --replay, extra skill paths, shift+tab, and native GitHub commands; correct the specialist-prompt count; bump dates. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
5.1 KiB
Permissions Reference
OpenCode's permission system in one page. Verified against the config JSON schema (
PermissionConfig).
The three values
Every permission accepts one of:
| Value | Behavior |
|---|---|
"allow" |
Tool runs without prompting |
"ask" |
User is prompted to approve each use |
"deny" |
Tool is blocked outright |
For bash (and any rule-style permission), you can also pass a glob-pattern map keyed by command pattern. Rules are matched in order and the last matching rule wins, so list the catch-all * first and put more specific overrides after it.
Permission keys → what they gate
| Key | Gates |
|---|---|
read |
read |
edit |
write, edit, apply_patch |
bash |
shell — supports glob-pattern overrides |
glob · grep · list |
search and listing tools |
task |
spawning subagents |
todowrite |
in-session todo list |
question |
the question tool |
external_directory |
files outside the project root |
webfetch · websearch |
network access |
lsp |
language-server tools |
skill |
loading agent skills |
doom_loop |
runaway-loop safeguards |
That's the full set — 15 keys (read, edit, glob, grep, list, bash, task, external_directory, todowrite, question, webfetch, websearch, lsp, doom_loop, skill), per the config schema.
Note:
writeandapply_patchare both gated under theeditkey, not separately.
Built-in tool list
| Tool | Purpose | Gated by |
|---|---|---|
bash |
Run shell commands | bash |
read |
Read file contents | read |
write |
Create / overwrite a file | edit |
edit |
String-replace edits | edit |
apply_patch |
Apply a unified diff | edit |
grep |
Regex search in files | grep |
glob |
File pattern matching | glob |
lsp |
LSP queries (experimental — needs OPENCODE_EXPERIMENTAL_LSP_TOOL=true) |
lsp |
skill |
Load a skill file's content | skill |
todowrite |
Manage in-session todo list | todowrite |
webfetch |
Fetch a web URL | webfetch |
websearch |
Web search (needs OpenCode provider or OPENCODE_EXPERIMENTAL_EXA=1 to use Exa) |
websearch |
question |
Ask the user something mid-execution | question |
Setting permissions
Project-wide (opencode.json)
{
"$schema": "https://opencode.ai/config.json",
"permission": {
"edit": "ask",
"bash": {
"*": "ask",
"git status*": "allow",
"git diff*": "allow",
"pnpm test*": "allow",
"rm -rf*": "deny"
},
"webfetch": "allow",
"websearch": "allow"
}
}
You can also use a top-level string ("permission": "ask") to set the same value for every permission at once.
Per-agent (opencode.json)
Per-agent settings override project-level for that agent:
{
"agent": {
"plan": {
"permission": {
"edit": "deny",
"bash": "ask"
}
}
}
}
Per-agent (markdown frontmatter)
---
description: Read-only reviewer
mode: subagent
permission:
edit: deny
bash:
"*": "ask"
"git diff*": "allow"
---
Glob-pattern bash
The bash key accepts a glob-pattern map. Patterns are matched against the full command line.
{
"permission": {
"bash": {
"*": "ask",
"git status*": "allow",
"git diff*": "allow",
"pnpm test*": "allow",
"git push --force*": "deny",
"rm -rf*": "deny"
}
}
}
Matching rules:
- Rules are matched in order and the last matching rule wins. Put the catch-all
*first, then list more specific overrides after it — a trailing*would override everything above it. *matches zero or more characters (including spaces).?matches exactly one character.- Literal text matches exactly.
Tool-level on/off (tools)
tools is independent from permission. It enables/disables a tool entirely.
{
"tools": { "websearch": false },
"agent": {
"research-agent": {
"tools": { "websearch": true }
}
}
}
Glob patterns work too — useful for MCP tools:
{
"tools": {
"github_*": false,
"slack_*": false
}
}
Defaults
- All tools are enabled by default.
- Most permissions default to
"allow"for thebuildagent. - The built-in
planagent setseditandbashto"ask"so analysis sessions can't surprise-write files. external_directoryis opt-in — files outside the project root require explicit"allow".
When to lock things down
| Scenario | Recommendation |
|---|---|
| Shared repo, multiple contributors | Commit a restrictive opencode.json so everyone's agent has the same guardrails |
| CI / headless | Use --dangerously-skip-permissions only after auditing what the prompt can reach |
| Working with secrets | external_directory: "deny" plus a plugin that blocks edits to .env/secrets/ |
| First time on a repo | Set bash: "ask" everywhere until you trust the workflows |
📚 Live reference: opencode.ai/docs/permissions and opencode.ai/docs/agents.