claude-code - 💡(How to fix) Fix [BUG] Plan mode pins a stale plan file across topic pivots in same session (refile of stale-closed #21131) [1 comments, 2 participants]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet (canonical thread #21131 was auto-closed stale 2026-04-08 with an explicit "open a new issue" invite; refiling per that instruction)
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code (reproduced via claude-agent-sdk (Python) 0.1.66 — see version field below)

What's Wrong?

When entering plan mode partway through a long-lived session that previously produced a plan file on a different topic, the plan-mode harness emits a system-reminder pinning that earlier file as the only file the agent is allowed to edit. Verbatim text the agent receives:

A plan file already exists at /home/<user>/.claude/plans/<earlier-slug>.md. You can read it and make incremental edits using the Edit tool. … this is the only file you are allowed to edit — other than this you are only allowed to take READ-ONLY actions.

The agent has no in-mode affordance to mint a fresh plan file. The result is a forced choice between (a) clobbering a still-valuable unrelated plan, or (b) appending a mismatched section to a file on a different topic.

This refiles the canonical bug #21131 (auto-closed stale 2026-04-08, locked 2026-04-15; the auto-close comment explicitly invites a refile) with crisper evidence isolating the selection mechanism. Related/duplicate threads: #35943, #18258, #12505, #12827, #14866, #30398, #31245.

What Should Happen?

On plan-mode entry mid-session, one of:

1. Mint a fresh three-word-slug plan file per topic by default. Existing plans become read-only references; never auto-pinned for write.
2. Prompt "resume X or start a new plan file?" when an existing plan is detected, instead of silently pinning it.
3. Allow the agent to touch a new file in ~/.claude/plans/ from within plan mode. (Today the read-only restriction blocks even creating a fresh sibling, which is what makes the CLAUDE.md-rule workarounds dead-end — see SeanHollen's comment on #21131.)

Option (1) is the cleanest. Option (3) is the smallest behavioral change and would make existing user-side rule workarounds actually viable.

Steps to Reproduce

1. Start a long-lived Claude Code session (CLI or claude-agent-sdk consumer).
2. In that session, work on topic A long enough that the agent produces a plan file. Filename will be auto-slugged at ~/.claude/plans/<slug-A>.md.
3. Continue the same session — pivot to an unrelated topic B (different concern, independent feature).
4. Enter plan mode.
5. Observe: the harness emits the system-reminder above pinning <slug-A>.md for write, even though the new task is unrelated.

Disproof of the "most-recent-mtime" theory (this matters — selection is not "pick the newest file in the directory"):

$ ls -la --time-style=long-iso ~/.claude/plans/ | grep -E "ullman|otter"
-rw-r--r-- 1 user user 18853 2026-04-21 13:35 enumerated-inventing-ullman.md   ← pinned
-rw-r--r-- 1 user user 18097 2026-04-21 14:29 sparkling-triaging-otter.md      ← newer, NOT pinned

The pinned file was not the newest in the directory. Selection appears to be per-session sticky — the harness remembers an assignment from earlier in the same session and re-pins it on every subsequent plan-mode entry, regardless of whether the new task relates.

Error Messages/Logs

A plan file already exists at /home/<user>/.claude/plans/<slug>.md.
You can read it and make incremental edits using the Edit tool.
…
this is the only file you are allowed to edit — other than this you
are only allowed to take READ-ONLY actions.

Claude Model

Opus

Is this a regression?

I don't know

Last Working Version

(unknown)

Claude Code Version

claude-agent-sdk (Python) 0.1.66. Not using the Claude Code CLI directly — host is a claude-agent-sdk consumer (Bearings, localhost web UI). The plan-mode harness behavior is shared between the SDK and the CLI; route to whichever team owns the harness.

Platform

Anthropic API

Operating System

Other Linux

Terminal/Shell

Non-interactive/CI environment

Additional Information

• Confirmed not a host/wrapper bug. Reproduces in Bearings (a claude-agent-sdk consumer). grep across the host's source shows no file-selection logic, no system-reminder emission, and no plan-path wiring through the host's session/prompt layer — every reference to ~/.claude/plans/ in the host is a comment pointing at planning docs for traceability. The reminder originates in the plan-mode harness exposed by claude-agent-sdk / the CLI.
• Adam Goyer's comment on #21131 describes a PostToolUse hook workaround that copies plans to a git-tracked location, but the in-mode pin still destroys the original. SeanHollen's comment on #21131 shows the deadlock cleanly: even with strong CLAUDE.md rules forbidding plan-file overwrite, the agent correctly refuses to write — but has no escape hatch to create a fresh file from within plan mode.
• Current workaround: drop out of plan mode, hand off to a fresh session, replan there. Applicable in long-lived UIs like Bearings; standalone CLI users typically /clear or restart, which trades context for correctness.
• Sibling bug (filing separately once reproduced): plan-mode dropdown picker behavior in the claude-agent-sdk flow appears to be wired up incorrectly — needs its own repro before filing.