[DOCS] Plan mode docs do not mention that read-only tool calls are auto-allowed on session start (fixed in v2.1.198)

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

• The opening paragraph of "## Analyze before you edit with plan mode", which describes how plan mode handles permissions

Current Documentation

The current plan mode section reads:

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 "Enter plan mode" instructions then say:

Enter plan mode by pressing Shift+Tab or prefixing a single prompt with /plan. You can also start in plan mode from the CLI: ``bash claude --permission-mode plan ``

What's Wrong or Missing?

The release notes for v2.1.198 include a fix that changes how plan mode behaves when the session starts in plan mode:

Fixed plan mode not auto-allowing read-only tool calls when a session starts in plan mode

Before v2.1.198, starting a session in plan mode still surfaced permission prompts for read-only file reads and Bash exploration calls (the "Permission prompts still apply the same as default mode" line). Now those read-only calls are auto-allowed on session start, which is a meaningful behavior change for anyone scripting plan-mode sessions or running them in CI.

The docs do not mention this auto-allow behavior anywhere, so users starting sessions in plan mode (with claude --permission-mode plan, --permission-mode plan in scripts, or defaultMode: "plan" in settings) will not know that read-only calls are now auto-allowed.

Suggested Improvement

Before:

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.

After:

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. As of v2.1.198, sessions that start in plan mode (with --permission-mode plan or defaultMode: "plan") auto-allow read-only tool calls such as file reads, globbing, grep, and read-only Bash exploration, so research proceeds without permission prompts. Edits, writes, and other mutating calls still prompt.

If the team wants to be more precise about which read-only tools are included, list the same categories named in the change ("read-only file reads, globbing, grep, read-only Bash exploration"). Avoid implying that all Bash commands are auto-allowed; only the read-only subset should be.

Impact

Medium - Makes feature difficult to understand

Additional Context

Related v2.1.198 change:

Fixed plan mode not auto-allowing read-only tool calls when a session starts in plan mode

The "Set plan mode as the default" example in the same page references defaultMode: "plan", so users who follow that recipe will also rely on the new behavior. None of the existing open docs issues in the prefetched queue describe this specific fix.

Affected Pages:

| Page | Context |
|---|---|
| https://code.claude.com/docs/en/permission-modes | "Analyze before you edit with plan mode" opening paragraph |