claude-code - 💡(How to fix) Fix [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:

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.