Why are your OpenCode 2 permission rules not taking effect?
Troubleshoot configuration sources, rule order, subagents and policies with schema-checked V2 examples. Includes external-directory defaults and why policies do not sandbox plugin processes.
Checked November 18, 2026 (Asia/Shanghai), against that day’s V2 documentation and public JSON Schema. We checked structure offline; we did not start OpenCode, call a model or test runtime enforcement.
You asked for confirmation before pushing, but saw no prompt. Your primary agent cannot edit, yet a subagent still can. Before adding duplicate rules, identify the loaded configurations, the last matching rule, and the agent actually taking the action.
This is a permission-troubleshooting guide, not an operating-system sandbox tutorial. For models and subscriptions, see the OpenCode tool page.
Separate three different ordering rules
Do not compress Config, Permissions and Policies into “project configuration wins.”
| Question | Documented rule | Common mistake |
|---|---|---|
| Ordinary setting values | User-global and project files merge; system settings rank higher, macOS managed settings highest | Assuming the closest project file always overrides system settings |
permissions | Ordered matching; last match wins, with agent rules appended after shared rules | Assuming specificity wins, or subagents inherit the primary agent’s restrictions |
policies | Last match within a file; broader administrative sources outrank narrower sources | Expecting a repository allow to lift a global or organization restriction |
1. Find all sources, not just the current directory
For ordinary settings, OpenCode searches from the current directory to the filesystem root. It merges direct opencode.json(c) files from farthest to closest, then .opencode/opencode.json(c) files in that same order. Discovered .opencode configurations therefore override ordinary matching settings in direct files; this is more than “the nearest file wins.” User-global configuration is ~/.config/opencode/opencode.json(c); the Linux system directory is /etc/opencode.
This does not let projects override system or managed settings. Nor should this ordinary-settings loading order be reused as the policy order.
For policies, authority runs highest to lowest: macOS MDM → system → connected Console workspace → user-global → direct project configurations → .opencode configurations. Within each of the last two categories, outer directories outrank inner ones. Console policy changes apply on the next fetch, usually about a minute later. Disconnecting clears that connection’s policies; a temporarily unreachable Console retains its last policies.
Record the actual launch directory, system/global/ancestor configurations and connected Console workspace. Do not publish whole configuration files containing credentials.
2. Look for the last match, not the most specific pattern
Native V2 uses permissions, shell and subagent. Do not casually mix those examples with V1’s permission, bash and task. The migration guide says supported V1 configuration is still normalized and loaded: not every old field needs immediate deletion. When both forms set the same canonical value, a valid native V2 value takes precedence.
Each permission rule requires three strings: action, resource and effect. Effects are allow, deny or ask.
- The last matching rule wins, with no specificity ranking. Put broad rules first and exceptions later.
*can match slashes, and?matches one character. These are not Git pathspec rules.- A shell pattern ending in
*also matches the command without arguments:git push *coversgit push. - When an operation checks multiple resources, any deny denies it; otherwise any ask prompts; only all-allow proceeds.
- “Ask if no rule matches” does not mean “ask by default for everything.” Every agent starts with an allow-
*base rule, followed by ask rules for reading.envand.env.*, with.env.exampleallowed.
An explainable starting configuration, not a complete security policy
Place this in the project’s opencode.json, or merge it into an existing opencode.jsonc. Back up first; do not replace unrelated settings:
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "shell", "resource": "*", "effect": "ask" },
{ "action": "shell", "resource": "git status --short", "effect": "allow" },
{ "action": "shell", "resource": "git --no-pager diff --no-ext-diff --no-textconv", "effect": "allow" },
{ "action": "shell", "resource": "git push *", "effect": "deny" },
{ "action": "external_directory", "resource": "*", "effect": "ask" }
],
"agents": {
"reviewer": {
"description": "Review without edit or shell tools",
"mode": "subagent",
"permissions": [
{ "action": "edit", "resource": "*", "effect": "deny" },
{ "action": "shell", "resource": "*", "effect": "deny" }
]
}
}
}
The intent is: ask for shell commands generally; allow two exact Git inspection commands without prompting; deny matching git push commands; ask for external directories; append edit and shell denials for the reviewer subagent.
We deliberately avoid automatically allowing arbitrary git diff * arguments. Git’s --output can write a file, and external diff/textconv can run programs. The exact diff command uses --no-ext-diff --no-textconv to narrow the allowance. It still does not guarantee that host Git configuration or the whole process is read-only. Other argument forms fall back to asking only in the absence of other overriding rules or applicable preexisting saved approvals; do not answer “Allow always” just to save time. See the official git diff documentation.
This is not a guarantee that pushing is impossible. An absolute Git path, wrapper script, another tool or another network route may not match git push *. Such commands may fall back to asking; do not approve commands you do not understand. Enforced network or filesystem isolation needs separate operating-system/container controls.
3. Check external directories and subagents separately
Paths outside both the active Location and its non-root project worktree are checked against external_directory before read or edit. External directories are allowed by default, not prompted by default. The example explicitly adds an ask rule.
For read, edit and external_directory, ~ and $HOME prefixes expand at configuration load. Shell resources remain raw command text and do not get that expansion. Shell directory inference is best-effort, not a filesystem boundary.
Agent-specific rules append after shared rules. A custom subagent has its own permissions, not a subset of its parent’s. Consequently:
- Denying edits for the primary agent does not automatically give
reviewerthe same denial. - The example explicitly denies both
editandshellforreviewer, rather than changing only the primary agent. - This is still not proof that every write path is blocked. Audit MCP tools, plugins and other actions separately; an
editrule does not represent every side effect.
Use policies for enforced restrictions, but never give them ask
This is a separate configuration fragment. For organization-level restrictions, deploy the relevant policy through an appropriate higher-authority source instead of expecting a repository file to constrain everyone:
{
"$schema": "https://opencode.ai/config.json",
"policies": [
{ "action": "tool.use", "resource": "shell:git push *", "effect": "deny" }
]
}
Its tool.use resource is action:resource. It is checked after ordinary permissions and saved approvals. A matching denial blocks rather than prompts, with an error such as Blocked by configuration policy; Console denials name the workspace.
Policy effects are only allow or deny, never ask. An allow overrides earlier matching policy denials only when it is the final matching statement after source authority and statement order are applied, not because its pattern is more specific. The agent’s ordinary permission checks still apply; it does not grant access directly. With no matching policy, existing checks continue.
Saved “Allow always” approvals are durable project-scoped allows and do not override configured denials. If a restriction appears bypassed, check for a non-match, a later overriding rule, or a different agent/action actually performing the operation.
4. Valid JSON does not prove a policy loaded
Policies explicitly documents that invalid statements are dropped with a server-log warning, while the rest of the list remains active. After editing a deny, inspect logs rather than merely balancing braces.
On the check date, the Permissions page’s Scanner section also contained an example nesting permissions inside policies. That disagrees with the public schema and the Policies page’s three-field statement shape. We do not use that nested shape, and did not verify whether the runtime has a compatibility path. Resolve such conflicts against the version in use, the public schema and server logs; a webpage example is not an execution result.
Check version compatibility before relying on new policy actions:
- Clients older than 2.2.3 ignore
integration.connect, the new meaning ofintegration.use,mcp.use,skill.useandplugin.use. - Clients older than 2.2.6 ignore
websearch.use. - Old
integration.usestatements withmcp:,skill:orplugin:prefixes convert to the respective new actions. A bareintegration.use: *now controls integration sources, not all MCP servers, skills and plugins.
To disable those three categories, the currently documented native shape is:
{
"policies": [
{ "action": "mcp.use", "resource": "*", "effect": "deny" },
{ "action": "skill.use", "resource": "*", "effect": "deny" },
{ "action": "plugin.use", "resource": "*", "effect": "deny" }
]
}
This is a separate restrictive example that disables every corresponding capability. Do not add it to every project indiscriminately; first decide whether those capabilities are needed.
These settings do not sandbox plugin processes
The documentation explicitly says policies do not sandbox plugin code. Denying a provider blocks the normal provider/model path; it does not remove a plugin’s ability to make network requests. Shell also retains the host user’s filesystem, process and network authority.
Load only trusted plugins and MCP servers. Inspect configuration and launch commands in unfamiliar repositories; a JSON snippet is not a reason to run untrusted code. We did not test any particular plugin or MCP server.
An acceptance checklist that does not require a real push
Prepare a fake repository and synthetic files in an isolated directory. Do not test with real .env, SSH material or production directories.
| Check | Documented expectation, not an observed result here |
|---|---|
| The primary agent’s two exact Git commands | Match explicit allows; extra arguments may not match |
Canonical git push and git push origin main | Match the example denial; do not initiate a real push as a test |
| An external synthetic directory | Check external_directory first and inspect later overrides |
reviewer edit/shell actions | Match its own denials, not just the primary agent’s |
| A configured deny after a saved approval | The old approval must not lift a configured denial |
Invalid policy fields or ask | Check schema errors and server warnings, not assumed enforcement |
Our local checks cover the public schema, JSON example consistency and Git arguments in an isolated fake repository. We did not start OpenCode or test actual enforcement, scanner parsing, Console synchronization or plugin isolation. If runtime checks require inference, paid requests or real accounts, obtain that authorization first. Offline checks are not “tested security.”
Official sources (checked November 18, 2026, Asia/Shanghai)
- Config: locations, ordinary setting merge order, system and managed settings.
- Permissions: matching, defaults, directories, subagents, saved approvals and host authority.
- Policies: administrative precedence, invalid-statement warnings, version gates and plugin limits.
- Public JSON Schema: offline field/shape validation, not runtime proof.
- Migrate from V1: legacy compatibility and valid native V2 values taking precedence.
- git diff:
--output,--no-ext-diffand--no-textconv.
📚 Keep Reading
📚 Related Guides
AI Coding Agent Security Guide 2026: How to Protect Against Repository Access, Shell Execution, and Prompt Injection Risks
AI coding agents are getting more capable, but more power means more risk. This guide covers four critical dimensions — repository permissions, shell execution, prompt injection, and credential leaks — with practical security measures drawn from Claude Code, Codex, Copilot, Gemini CLI, and Cursor.
AI Coding Agents in 2026: A Practical Roadmap from Autocomplete to Cloud Teammates
As of June 2026, AI coding tools are moving from autocomplete and AI IDEs into engineered agent workflows. This guide maps the shift across Codex, Claude Code, GitHub Copilot, Gemini CLI, MCP, security, and team adoption.
AI Coding Tool Skills & Extension Systems: Claude Code, Cursor, Cline Complete Guide
A deep dive into AI coding tool extension capabilities: Claude Code's Agent Skills / Hooks / Plugins, Cursor's .mdc Rules, the cross-tool AGENTS.md standard, and how to build your own AI-powered workflow.
📖 Related Comparisons
Best AI Coding Tools 2026: Mainstream Tools Reviewed & Ranked
A practical AI coding tools comparison for 2026, covering Cursor, Claude Code, Copilot, Windsurf, and other mainstream tools across coding ability, pricing, flexibility, and more.
OpenCode vs Cursor 2026: Free Open-Source TUI vs Top AI IDE
OpenCode vs Cursor compared: free terminal TUI Agent vs premium AI IDE — pricing, coding ability, China accessibility, and workflow to help you choose the right tool.
Terminal AI Coding Big Three: Claude Code vs OpenCode vs Aider
A comprehensive comparison of three mainstream terminal CLI AI coding tools: Claude Code, OpenCode, and Aider — covering features, pricing, model support, and use cases.
🔧 Tools in This Article
💰 Related money-saving plans
Based on the tools and APIs in this guide — get started for less.
OpenCode + Volcano Ark Agent Plan
Open-Source Agent CLI BundlePlug the open-source OpenCode CLI into Ark Agent Plan — get Doubao coding, Seedance video, Seedream image, embedding-vision and the Harness toolchain right in your terminal. Billed in AFP on 5h + daily rolling windows; Medium tier and above include a 24/7 AI companion. A solid pick for terminal users who want a Claude Code-like experience with China-native models and Agent tooling.
For: China-native devs running Agent + multimodal workflows in the terminal · Fans of OpenCode and open-source clients
OpenCode + Volcengine Ark Coding Plan
Terminal Enthusiast's PickA domestic alternative for terminal enthusiasts. Open-source CLI client supporting 75+ model providers and multi-session management, with Volcengine Ark API for direct China access. Ark offers Lite and Pro tiers; since March 13, 2026, new-user subscriptions open in limited quantities each day at 10:30.
For: Terminal power users · Budget-conscious developers in China
🎁 Grab deals & free trials
Free quotas, first-month discounts, and sign-up links for tools & coding plans — kept up to date.
View all deals →