[DOCS] [CLI] `--permission-mode plan` not restored on `--resume`/`--continue` after v2.1.132 (docs say it isn't, but it now is)

Open 💬 2 comments Opened May 7, 2026 by coygeek

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

PreToolUse hook section — "defer" workflow paragraph (line ~1232)

Current Documentation

The docs currently say:

--resume does not restore the permission mode from the prior session. Pass the same --permission-mode flag on resume that was active when the tool was deferred. Claude Code logs a warning if the modes differ.

This statement no longer reflects actual behavior for --permission-mode plan after v2.1.132.

What's Wrong or Missing?

A. Outdated claim about `--resume` and permission modes

The changelog for v2.1.132 (line 20) includes this fix:

Fixed --permission-mode flag being ignored when resuming a plan-mode session with -p --continue/--resume, and plan mode not being re-applied after ExitPlanMode within the same session

After this fix, --permission-mode plan is correctly restored when resuming a plan-mode session with -p --continue or -p --resume. The hooks.md warning that says the opposite is now incorrect.

B. Missing documentation for restored plan mode on resume

There is no documentation section that explicitly confirms that --permission-mode plan (or plan mode generally) is now restored on resume. Users who relied on the old limitation in hooks.md may not realize this now works as expected.

C. Missing documentation for `ExitPlanMode` re-application

The changelog also notes that "plan mode not being re-applied after ExitPlanMode within the same session" was fixed. There is no documentation that explains this behavior — i.e., that after a session calls ExitPlanMode and then resumes, plan mode is correctly re-applied.

Suggested Improvement

Update hooks.md

Remove or narrow the absolute statement that --resume never restores permission mode. Replace it with a note that reflects the v2.1.132 fix for plan mode:

For sessions deferred in plan mode, -p --resume and -p --continue correctly re-apply plan mode as of v2.1.132, including after ExitPlanMode within the same session. If you rely on other permission modes during resume, pass the same --permission-mode flag that was active when the tool was deferred.

Add new section to permission-modes.md

Add a note in the plan mode documentation clarifying the v2.1.132 fix:

Plan mode and --resume: Starting in v2.1.132, --permission-mode plan is correctly restored when resuming a session with -p --continue or -p --resume. Previously, the --permission-mode flag was ignored on resume for plan-mode sessions. Plan mode is also re-applied after ExitPlanMode within the same session.

Add to headless.md

The "Continue conversations" section could note the restored behavior:

When resuming a session that was in plan mode, the mode is restored automatically (v2.1.132+). For other permission modes, pass the same --permission-mode flag on resume.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/hooks | ~1232 | Warning that --resume does not restore permission mode — now outdated for plan mode |
| https://code.claude.com/docs/en/permission-modes | 119–155 | Plan mode entry/exit docs; no mention of resume restoration |
| https://code.claude.com/docs/en/headless | 230–248 | Continue conversations section; no mention of permission mode restoration |

Total scope: 3 pages affected

Version: v2.1.132

Changelog entry (v2.1.132 line 20):