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

> Discover OpenCode plan agent permissions. Learn about default access control and file edit restrictions, including allowed modifications to plan files.

- Repository: [Anomaly/opencode](https://github.com/anomalyco/opencode)
- Tags: permissions
- Published: 2026-02-16

---

**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`](https://github.com/anomalyco/opencode/blob/main/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`](https://github.com/anomalyco/opencode/blob/main/packages/opencode/src/agent/agent.ts). The configuration uses the `PermissionNext` system to evaluate action patterns against file paths:

```typescript
// 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`](https://github.com/anomalyco/opencode/blob/main/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`](https://github.com/anomalyco/opencode/blob/main/.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`](https://github.com/anomalyco/opencode/blob/main/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`](https://github.com/anomalyco/opencode/blob/main/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`](https://github.com/anomalyco/opencode/blob/main/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`](https://github.com/anomalyco/opencode/blob/main/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`](https://github.com/anomalyco/opencode/blob/main/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.