OpenCode Plan Agent Permissions: Default Access Control and File Edit Restrictions

The plan agent in OpenCode denies all file edit operations by default, only allowing modifications to plan files located in .opencode/plans/*.md and internal data/plans/* directories.

The plan agent in the anomalyco/opencode repository operates under a strict security model designed to prevent unintended file modifications. Unlike agents with broader write access, this agent implements a deny-by-default permission structure that restricts edit capabilities exclusively to plan-specific storage locations while maintaining read access across the entire workspace.

Default Permission Rules for the Plan Agent

According to the source code in packages/opencode/src/agent/agent.ts (lines 92-108), the plan agent's permission map explicitly allows edit operations only for files matching specific path patterns. All other edit actions fall back to an implicit deny state, creating a locked-down environment that prevents accidental source code modifications.

Allowed Edit Paths

The plan agent permits file modifications exclusively within these three path patterns:

• path.join(Global.Path.data, "plans", "*") — Internal plan files stored in the data directory
• path.join(".opencode", "plans", "*.md") — User-visible plan files in the workspace root
• path.relative(Instance.worktree, path.join(Global.Path.data, "plans", "*.md")) — Absolute work-tree paths resolved relative to the instance worktree

Denied Operations

Any edit operation targeting paths outside the plan storage directories receives an automatic deny response. The plan agent inherits standard read-only permissions, meaning it can read any file in the workspace but cannot modify, create, or delete files outside the designated plan locations. This restriction applies to all write-type actions including file creation, deletion, and content modification.

Implementation in Agent Configuration

The permission logic resides in the agent definition file at packages/opencode/src/agent/agent.ts. The configuration uses the PermissionNext system to evaluate action patterns against file paths:

// Example: checking whether the plan agent can edit a file
import { PermissionNext } from "opencode/src/permission/next";
import { Agent } from "opencode/src/agent/agent";

const planAgent = await Agent.get("plan");

// Evaluates to "allow" for plan files
PermissionNext.evaluate(
  "edit",
  ".opencode/plans/my-plan.md",
  planAgent!.permission
).action; // → "allow"

// Evaluates to "deny" for source files
PermissionNext.evaluate(
  "edit",
  "src/main.ts",
  planAgent!.permission
).action; // → "deny"

Testing and Verification

The permission restrictions are validated in the test suite at packages/opencode/test/agent/agent.test.ts (line 47). The specific test case "plan agent denies edits except .opencode/plans/"* asserts that:

• Paths matching .opencode/plans/foo.md return "allow"
• All other paths return "deny"

This test coverage ensures that the plan agent maintains its restricted permission model across updates to the codebase, preventing regression in the security boundary.

Summary

• The plan agent operates under a deny-by-default security model for all edit operations
• Edit permissions are explicitly granted only for files in .opencode/plans/*.md and internal data/plans/* directories
• The permission logic is defined in packages/opencode/src/agent/agent.ts (lines 92-108)
• Read operations remain unrestricted — the plan agent can read any workspace file
• Test coverage at packages/opencode/test/agent/agent.test.ts validates the permission restrictions

Frequently Asked Questions

Can the plan agent modify files outside the plans directory?

No. The plan agent explicitly denies all edit operations on files outside the designated plan storage locations. According to the permission map in packages/opencode/src/agent/agent.ts, only paths matching .opencode/plans/*.md or internal data/plans/* patterns receive edit approval. All other paths trigger the implicit deny rule.

Where are the plan agent permissions configured?

The default permissions are hardcoded in the agent definition file at packages/opencode/src/agent/agent.ts between lines 92 and 108. This configuration uses the PermissionNext system to evaluate action patterns against file paths, establishing the restrictive edit rules specific to the plan agent while inheriting standard read permissions from the base agent class.

Does the plan agent have read access to all files?

Yes. While the plan agent restricts write operations to plan-specific directories, it inherits standard read-only permissions that allow it to read any file in the workspace. This enables the agent to analyze the codebase when creating or modifying plans without risking unintended modifications to source files or configuration files outside the plan storage locations.

How is the plan agent permission model tested?

The permission restrictions are validated in packages/opencode/test/agent/agent.test.ts at line 47, where a test case specifically asserts that the plan agent denies edits to paths outside .opencode/plans/* while allowing modifications within that directory. This ensures the security model remains intact across code updates and prevents regression in the agent's access control boundaries.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}