[DOCS] Plan mode docs do not clarify that `Edit(...)` allow rules cannot permit writes

[coygeek]

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/permission-modes

Section/Topic

## Analyze before you edit with plan mode and the introduction that explains how permission rules layer on top of modes

Current Documentation

The permission-modes page currently says:

In every mode except bypassPermissions, writes to protected paths are never auto-approved, guarding repository state and Claude's own configuration against accidental corruption.

Modes set the baseline. Layer permission rules on top to pre-approve or block specific tools in any mode except bypassPermissions, which skips the permission layer entirely.

Later on the same page it says:

Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan, but does not edit your source. Permission prompts still apply the same as default mode.

The permissions page also says:

• Allow rules let Claude Code use the specified tool without manual approval.

| plan | Plan Mode: Claude reads files and runs read-only shell commands to explore but does not edit your source files |

What's Wrong or Missing?

After the Claude Code v2.1.136 fix for plan mode not blocking file writes when a matching Edit(...) allow rule exists, the docs still do not explain the precedence between plan mode and allow rules.

The current wording can be read two different ways:

A. Broad allow-rule language

The docs say permission rules can pre-approve tools in any mode except bypassPermissions, which suggests a matching Edit(...) rule can still enable writes during plan mode.

B. Read-only plan-mode language

Other pages say plan mode is read-only and does not edit source files.

What is missing is an explicit statement that plan mode stays read-only even when a matching Edit(...) or Write allow rule exists, and that file writes remain blocked until the user exits plan mode and switches to a write-capable mode.

Suggested Improvement

Add a short precedence note anywhere plan mode and permission rules are explained, especially on permission-modes and the main permissions page.

Suggested text:

Plan mode is always read-only. Edit(...), Write, and other file-write allow rules do not permit source edits while plan mode is active. To make file changes, exit or approve the plan and switch to a mode that allows writes, such as default, acceptEdits, auto, or bypassPermissions.

If the Agent SDK has different semantics, document that distinction explicitly instead of leaving the precedence implicit.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Line(s)	Context
https://code.claude.com/docs/en/permission-modes	24-26, 121-123	Says permission rules can pre-approve tools in any mode except bypassPermissions, but later says plan mode does not edit source
https://code.claude.com/docs/en/permissions	25-29, 39	Defines allow rules as running tools without manual approval while also describing plan mode as read-only
https://code.claude.com/docs/en/agent-sdk/permissions	28-33, 230-232	SDK permission flow shows allow rules after the mode check, while plan mode is described as read-only

Total scope: 3 pages affected

Version context: Claude Code v2.1.136 changelog includes: Fixed plan mode not blocking file writes when a matching Edit(...) allow rule exists.

[coygeek]

checked docs, not resolved yet

[coygeek]

Verified against the latest docs; this still appears unresolved.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.