[DOCS] Plan approval docs do not explain untouched-plan handling or stale snapshot protection

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The "Review and approve a plan" section, especially the relationship between approving an unchanged plan, opening the plan with Ctrl+G, and the plan file stored on disk. The teammate plan-approval workflow on the Agent Teams page should be cross-referenced because it uses the same approval concept.

Current Documentation

The permission modes page currently says:

When the plan is ready, Claude presents it and asks how to proceed. From that prompt you can: Approve and start in auto mode Approve and accept edits Approve and review each edit manually Keep planning with feedback * Refine with Ultraplan for browser-based review

It also says:

Press Ctrl+G to open the proposed plan in your default text editor and edit it directly before Claude proceeds.

For agent teams, the related workflow says:

When a teammate finishes planning, it sends a plan approval request to the lead. The lead reviews the plan and either approves it or rejects it with feedback. If rejected, the teammate stays in plan mode, revises based on the feedback, and resubmits. Once approved, the teammate exits plan mode and begins implementation.

What's Wrong or Missing?

The documentation describes approval and optional editing as separate actions, but does not explain how Claude Code distinguishes an approval of an unchanged plan from a plan that the user actually edited in the external editor. It also does not state that approving without edits must preserve the current plan file rather than write a stale in-memory snapshot back to disk.

Claude Code v2.1.210 fixed plan approvals without edits being labeled (edited by user) and overwriting the plan file with a stale snapshot. This is a user-visible plan-file integrity and review-state behavior: users need to know that an untouched approval is not treated as an edit, and that the plan they reviewed is not silently replaced during approval.

The same omission affects teammate plan approvals. The Agent Teams page explains that approval starts implementation, but not whether the lead's approval changes the plan file or how an unchanged plan is represented.

Suggested Improvement

Add a note to the plan approval section describing the two paths explicitly:

• Approving without opening or changing the plan preserves the plan file and does not label it as edited by the user.
• If the plan is opened with Ctrl+G and changed, Claude Code uses the edited plan when continuing and indicates that the user edited it.

Clarify that approval must not overwrite the plan on disk with an older snapshot, and add the same distinction to the Agent Teams plan-approval workflow or link back to the canonical explanation. Include a v2.1.210 minimum-version note if the behavior needs to be distinguished from earlier releases.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permission-modes | "Review and approve a plan" and Ctrl+G plan editing workflow |
| https://code.claude.com/docs/en/agent-teams | "Require plan approval for teammates" workflow |

Total scope: 2 pages affected

The behavior change is documented in the Claude Code v2.1.210 release notes. The clarification should cover both the interactive plan approval dialog and lead-approved teammate plans without broadening the issue into unrelated plan storage or permission-mode behavior.