Plan mode UX: read-only constraint scope and ExitPlanMode interaction confusing for non-technical users

Summary

Plan mode restrictions and ExitPlanMode flow are unclear for users without technical competence. In a long session, the user struggles to understand: what is allowed in plan mode, when ExitPlanMode should be called, how plan mode interacts with auto mode.

Empirical observations (session 2026-06-08)

1. System reminder says read-only except plan file, but Bash commands like date and ls (read-only) are accepted — boundary unclear to non-technical users
2. ExitPlanMode tool description says do not use for research tasks but the plan workflow instructions say end turns with AskUserQuestion or ExitPlanMode — contradiction
3. When user types a question that is research not implementation, AI gets stuck deciding whether to invoke ExitPlanMode (per workflow) or skip it (per tool description)
4. After ExitPlanMode approved, auto mode activates but the transition is not clearly communicated to user

Expected behavior

• Clearer documentation in CLI output about what plan mode actually restricts (reads OK? Bash OK? Writes only to plan file?)
• Either ExitPlanMode applies to research too, or workflow instructions should clarify when to skip it
• Mode transitions (plan -> exit -> auto) should have explicit messages

Impact

Medium. Affects user trust and workflow efficiency. Non-technical users get stuck repeatedly asking what is happening.

Environment

• macOS Darwin 24.6.0
• Claude Code current latest 2026-06-08