[DOCS] Plan mode exit docs omit higher-permission restore behavior

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 plan approval/exit flow for permission modes

Current Documentation

The main permission-mode 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

The same page also documents that higher-permission modes can exist in the same session:

Enabled optional modes slot in after plan, with bypassPermissions first and auto last.

Separately, the hooks guide says:

When the hook approves, Claude Code exits plan mode and restores whatever permission mode was active before you entered plan mode.

What's Wrong or Missing?

The docs do not explain how plan-mode exit behaves when the session entered plan mode from a higher permission level.

Changelog v2.1.105 includes this fix:

Fixed Bash tool suggesting acceptEdits permission mode when exiting plan mode would downgrade from a higher permission level

That indicates the post-plan suggestion/restore behavior depends on the permission mode that was active before planning. The main permission-modes page currently lists generic exit choices, but it does not explain that exiting plan mode should avoid suggesting acceptEdits when that would downgrade a session that previously had a higher permission level. The only place that mentions restoration behavior is the hook-specific path in hooks-guide.

Suggested Improvement

Update permission-modes to document how Claude chooses the permission mode after approving a plan, especially when plan mode was entered from auto or bypassPermissions.

Suggested content:

• Add a note under the plan approval options explaining that Claude preserves the prior permission level when appropriate instead of suggesting a lower-permission continuation such as acceptEdits
• Include at least one example covering a session that entered plan mode from a higher-permission mode
• Add a cross-reference to the hook behavior so the restore logic is described consistently across interactive and hook-driven plan exits

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/permission-modes | Main description of plan-mode exit choices and permission-mode cycling |
| https://code.claude.com/docs/en/hooks-guide | Documents restoration of the pre-plan permission mode, but only for hook-approved exits |
| https://code.claude.com/docs/en/tools-reference | ExitPlanMode is listed here, but its description does not explain post-plan permission-mode behavior |

Total scope: 3 pages affected

Source: Changelog v2.1.105

Exact changelog entry: Fixed Bash tool suggesting acceptEdits permission mode when exiting plan mode would downgrade from a higher permission level