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

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.