Files
opencode-primer/docs/reference/permissions.md
T
Wesam AbousaidandClaude Opus 4.8 29a69a35b0 docs: refresh for OpenCode v1.16.2 and fix correctness bugs
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>
2026-06-08 19:00:39 +02:00

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: write and apply_patch are both gated under the edit key, 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 the build agent.
  • The built-in plan agent sets edit and bash to "ask" so analysis sessions can't surprise-write files.
  • external_directory is 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.