Permissions

OpenCode v2 replaces V1’s tool-grouped permission map with one ordered permissions array. Each rule specifies an action, a resource pattern, and an effect.

Rule Format

{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

Rules are evaluated in order. The last matching rule wins. Put catch-all "*" rules first and specific rules after.

Effects

Effect	Behavior
`allow`	Run without approval
`ask`	Prompt for approval
`deny`	Block the action

Actions

V2 renames several V1 permission keys:

V1 Key	V2 Action	What it gates
`bash`	`shell`	Shell commands (matches parsed commands)
`task`	`subagent`	Launching subagents
`write` / `patch`	`edit`	All file modifications
-	`read`	Reading files
-	`glob`	File globbing
-	`grep`	Content search
-	`list`	Directory listing
-	`external_directory`	Paths outside working directory
-	`webfetch`	URL fetching
-	`websearch`	Web search
-	`lsp`	LSP queries
-	`skill`	Loading skills
-	`question`	Asking the user questions
-	`doom_loop`	Recovery when agent repeats tool calls

V1 to V2 Migration

// V1
{
  "permission": {
    "bash": { "git push *": "ask" },
    "edit": "allow"
  },
  "tools": { "websearch": false }
}

// V2
{
  "permissions": [
    { "action": "shell", "resource": "git push *", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" },
    { "action": "websearch", "resource": "*", "effect": "deny" }
  ]
}

Gotcha: V2 also accepts the V1 permission map format for backwards compatibility. Valid native V2 values take precedence when both forms set the same canonical value.

Auto Mode

Start with --auto to auto-approve requests that aren’t explicitly denied:

opencode2 --auto

Explicit deny rules still apply. Auto mode only changes ask to allow.

Defaults

If you don’t configure permissions:

Most permissions default to allow
doom_loop and external_directory default to ask
read is allow, but .env files are denied by default

{
  "permission": {
    "read": {
      "*": "allow",
      "*.env": "deny",
      "*.env.*": "deny",
      "*.env.example": "allow"
    }
  }
}

Per-Agent Overrides

Agents can override global permissions. Agent rules merge with global config, with agent rules taking precedence:

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git *", "effect": "allow" }
  ],
  "agents": {
    "reviewer": {
      "mode": "subagent",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "*", "effect": "deny" },
        { "action": "subagent", "resource": "explore", "effect": "allow" }
      ]
    }
  }
}

What “Ask” Does

When OpenCode prompts for approval, you get three choices:

once - approve just this request
always - approve future matching requests for the rest of the session
reject - deny the request