Permissions

Permissions control whether an agent may perform an action on a resource.

Configure

A common setup is to ask before running shell commands, allow routine Git inspection, and always block pushes. Add these ordered rules to opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
  ],
}

The last matching rule wins, so the specific exceptions follow the broad rule.

Rules

Each rule requires three string fields:

{
  "permissions": [
    { "action": "read", "resource": "*", "effect": "allow" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
  ],
}

If no rule matches, OpenCode uses ask.

Matching

Actions and resources use simple whole-value wildcards:

{
  "permissions": [
    { "action": "edit", "resource": "packages/docs/*.mdx", "effect": "allow" },
  ],
}

This pattern matches the entire normalized path. Backslashes are normalized to slashes, and matching is case-insensitive on Windows.

A shell pattern ending in * also matches the command without arguments:

{ "action": "shell", "resource": "git status *", "effect": "allow" }

This matches both git status and git status --short.

OpenCode combines rules in order and uses the last match. Lower-priority configuration is loaded first, global rules are appended next, and agent rules are appended last.

{
  "permissions": [
    { "action": "read", "resource": "*", "effect": "allow" },
    { "action": "read", "resource": "secrets/*", "effect": "deny" },
  ],
}

Operations may check several resources, such as a patch that touches multiple files. Any deny denies the operation; otherwise any ask asks; otherwise the operation is allowed.

Actions

V2 action names are strings, so plugins may define more actions. Built-in tools currently use these actions and resources:

For example, allow one skill and deny all other skills:

{
  "permissions": [
    { "action": "skill", "resource": "*", "effect": "deny" },
    { "action": "skill", "resource": "effect", "effect": "allow" },
  ],
}

doom_loop and lsp are not current V2 Core permission actions.

Directories

A path outside both the active Location and its non-root project worktree is checked against external_directory before its read or edit rules. The default policy allows external_directory, so external paths are not prompted unless you add a rule. To be asked before any access outside the project:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "*", "effect": "ask" },
  ],
}

Narrower rules after it can allow or deny specific directories:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "external_directory", "resource": "~/projects/reference/*", "effect": "allow" },
    { "action": "read", "resource": "~/projects/reference/*", "effect": "allow" },
    { "action": "edit", "resource": "~/projects/reference/*", "effect": "deny" },
  ],
}

This applies to external paths used by read, edit, write, and patch. Shell checks its external working directory and directories inferred by its scanner before checking shell resources.

For external_directory, read, and edit, a leading ~, ~/, $HOME, or $HOME/ is expanded when configuration loads:

{ "action": "read", "resource": "$HOME/reference/*", "effect": "allow" }

Shell resources remain raw command text and are not home-expanded.

Relative mutation paths may leave the active Location while remaining inside its project worktree. Explicit external paths are canonicalized before matching, so authorize only trusted directory boundaries.

Scanner

Enable the experimental portable shell scanner with:

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "portable_shell_scanner": true,
  },
}

The portable scanner replaces the default tree-sitter scanner; tree-sitter is not a fallback or second opinion. A command the portable scanner cannot analyze returns a scanner error, not a permission denial.

The flag changes only parser selection. Existing permission rules, saved approval patterns, and best-effort directory inference still apply. There is no extra approval mode or blanket restriction for unknown directories.

Defaults

Every agent, including custom agents, starts with this ordered base policy:

[
  { "action": "*", "resource": "*", "effect": "allow" },
  { "action": "read", "resource": "*.env", "effect": "ask" },
  { "action": "read", "resource": "*.env.*", "effect": "ask" },
  { "action": "read", "resource": "*.env.example", "effect": "allow" },
]

Shipped agents append these policies:

Because no default rule asks for external_directory, reads and edits outside the Location and worktree proceed without a prompt. Add an external_directory ask or deny rule, as shown in Directories, to restore a prompt or block outside access. Later global and agent rules override these defaults.

Agents

Put shared rules at the top level and narrower rules under agents.<id>.permissions:

{
  "$schema": "https://opencode.ai/config.json",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
  ],
  "agents": {
    "reviewer": {
      "description": "Review code without changing it",
      "mode": "subagent",
      "permissions": [
        { "action": "edit", "resource": "*", "effect": "deny" },
      ],
    },
  },
}

Agent rules are appended after global rules; they do not replace the global array. A custom subagent uses its own permissions, not a subset of its parent’s permissions.

Approvals

When a rule resolves to ask, clients can reply with:

For example, choosing Allow always for git status --short may save a shell prefix that covers later git status commands:

shell: git status * → allow

Saved approvals are durable, project-scoped allow rules. They never override a configured deny. Tools choose the proposed saved pattern: some propose *, shell proposes command prefixes, and skills and subagents propose their IDs. Review broad approvals and remove those no longer needed.

Clients may attach feedback when rejecting. Non-interactive clients must decide how to handle approval requests; configured deny rules always remain enforced.

Policies

A policy can hard-deny a permission check after these rules and saved approvals run. It turns allow or ask into deny and never grants access.

{
  "policies": [{ "action": "tool.use", "resource": "shell:sudo *", "effect": "deny" }],
}

Global and Console-managed policies override project configuration, which is how an organization blocks a command that a repository would allow.