CRITICAL!!! Plan mode documentation does not accurately describe enforcement level

Documentation Type

Incorrect/outdated documentation

Documentation Location

Claude Code documentation — Plan Mode

Section/Topic

Plan mode enforcement behavior (what plan mode actually blocks)

Current Documentation

Plan mode is documented as preventing code changes and tool use during planning. The implication is that write operations are blocked while plan mode is active — that the mode enforces a planning-only state.

What's Wrong or Missing?

Plan mode is soft enforcement only. The Write tool fires successfully while plan mode is active. Files are created and modified. There is no technical block, no warning, no error. The only enforcement is behavioral — the system prompt says not to write. If the agent ignores that instruction (or gets confused by context), it writes anyway. The user has no indication this happened until they check the file. Assuming they check before the problem gets embedded further downline. This misleads users and can have grave consequences.

I caught this mid-session because my agent wrote a file while we were explicitly in plan mode discussing structural changes to our pipeline. The file landed. No warning. No error. I only knew because I was watching.

Suggested Improvement

Document it accurately. If plan mode is behavioral enforcement and not a hard block, say that explicitly. Users relying on plan mode to protect their codebase during architectural discussions are operating on a false assumption. Either: (1) make it a hard block at the tool level, or (2) document clearly that plan mode is a prompt-level instruction, not a system-level lock — and that the Write tool remains callable.

The current documentation implies protection that does not exist.
This is an easy fix. It requires no code changes. Claude could do it for you in seconds.

Impact

High - Prevents users from using a feature

Additional Context

Impact
Critical. A user in plan mode discussing structural changes to their codebase believes writes are blocked. They are not. Work can be silently overwritten, files created, state corrupted — all while the user believes they are in a safe planning state. The failure mode is invisible until damage is already done.

Upgrade from High (crashes on your side) to Critical (on the user's side) because this oversight could engender negative community responses when user/clients lose time and money on projects they had changed while in a mode they trusted to be safe. Where you can't trust the system, you must inform us so we can build guardrails and safeties.