[liuedcson]

Problem

Entering plan mode rewrote the active tool list: it dropped the editing aliases and re-appended the plan tools. A real Step profile already offers every plan tool, so the rewrite produced the same 42 tools in a different order — 21 positions changed, no capability gained or lost.

The provider serializes tools ahead of the system prompt and messages, so the request's entire cached prefix is keyed on that block. Entering plan mode therefore invalidated the prompt cache for the whole conversation.

Measured on a live session (188 requests, stepcode-anthropic/deepseek-v4.1-flash-api):

event	prompt	cache read	hit
user /plan entry	233,198	1,664	0.7%
exit	281,715	233,088	82.7%
agent-initiated entry	325,365	281,472	86.5%

Same-turn requests outside those events held 98–99.9% for the whole session. The two entries alone re-billed 273k tokens, and one of them was the model calling enter_plan_mode on its own, so it is not avoidable by asking users not to use plan mode.

Change

Plan mode is a permission narrowing, not a capability change. The tool_call hook already denies mutations outside the plan file, so the editing tools do not need to disappear from the list.

• enable() no longer rebuilds the list. It appends only plan tools the profile is missing, and leaves an already-complete list untouched.
• Exit subtracts the tools entering actually appended, instead of replaying a snapshot, so a tool activated mid-plan (a late MCP catalog, find_tools) keeps its place.
• Entries carry version: 2 and store no replaced list. A legacy baseline is replayed only when the entry that narrowed the list is a legacy one, so a newer plan session can no longer replay an older session's snapshot and reorder or drop tools.
• The plan-file guard resolves both paths through resolveToCwd — the helper the file tools themselves use — so ~, @, and unicode-space inputs cannot pass the check and then land elsewhere.
• The denial states that plan mode is a permission restriction, forbids retrying or routing around it through a shell, and points at the plan file and exit_plan_mode.

This matches how Kimi Code implements plan mode (a toolExecutor.onBeforeExecuteTool veto, with no tool-list mutation) and MiniMax Code (only the two lifecycle tools change).

Verification

• plan-mode-prompt-cache-prefix.test.ts captures the actual request tool block and system prompt across a full entry → write plan → exit cycle and asserts all three requests are byte-identical; it also asserts a non-plan write is still denied.
• Extension tests cover: a profile that genuinely lacks plan tools (append-only), an entry that adds nothing (no setActiveTools, no persisted baseline), a new-format restore (nothing reapplied), a stale legacy baseline (not replayed), and a mid-plan tool surviving exit.
• All 17 plan-mode cases fail against main and pass here.
• tsgo --noEmit clean; biome check clean; check:ts-imports, check:layer-direction, check:coding-agent-entry-freeze, check:no-observability, check:public-boundary pass.

Full vitest --run in this worktree reports 7 failures, all pre-existing and unrelated: 6 in test/completion-check-cli.test.ts (also fails on an unmodified origin/main worktree) and 1 in test/suite/regressions/2791-fswatch-error-crash.test.ts (spawns the CLI from dist/, which this worktree has not built).

Known gap (not addressed here)

For user-initiated /plan, the model learns plan mode is on only when a write is denied — the extension injects nothing into context, and the tool list no longer changes. Agent-initiated entry is unaffected (enter_plan_mode returns the mode in its result). A cache-safe tail reminder would close the gap, but it changes request content every turn, so it belongs in its own change rather than this fix.

Docs

docs/plan-approval.md and packages/coding-agent/docs/step-integration.md now describe the append-only restore contract and the version: 2 snapshots.