@narumitw/pi-plan-mode 0.14.1 → 0.15.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@narumitw/pi-plan-mode)](https://www.npmjs.com/package/@narumitw/pi-plan-mode) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
 
-`@narumitw/pi-plan-mode` adds a Codex-like `/plan` collaboration mode to Pi. Plan mode is for read-only exploration, clarifying questions, and a final implementation-ready `<proposed_plan>` block before any code mutation happens.
+`@narumitw/pi-plan-mode` adds a Codex-like `/plan` collaboration mode to Pi. Plan mode is for read-only exploration, clarifying questions, and a structured implementation-ready plan before any code mutation happens.
 
 Pi core intentionally does not ship a built-in plan mode; this package provides one as an independently installable extension.
 
@@ -13,14 +13,17 @@ Pi core intentionally does not ship a built-in plan mode; this package provides
 - Enables built-in read-only tools by default while Plan mode is active.
 - Disables extension and custom tools by default, with a `/plan tools` selector for explicit user-risk opt-in.
 - Blocks `update_plan`, mutating built-in tools, and unsafe shell forms such as writes, substitutions, background jobs, dependency installs, and mutating Git commands.
-- Injects Codex-like Plan mode instructions: explore first, ask decision questions for high-impact ambiguity, do not mutate files, and finish with `<proposed_plan>` only when decision-complete.
-- Adds a required `plan_mode_question` tool so the agent can ask structured Plan-mode questions before finalizing a plan.
-- Detects proposed plan blocks and prompts you to implement, stay in Plan mode, or exit and discard the plan.
+- Injects Codex-like Plan mode instructions: explore first, ask decision questions for high-impact ambiguity, do not mutate files, and finalize only when decision-complete.
+- Adds required `plan_mode_question` and `plan_mode_complete` tools for structured questions and completion.
+- Presents the complete plan and prompts you to implement, stay in Plan mode, or exit and discard it.
+- Keeps legacy `<proposed_plan>` responses compatible without advertising XML as the primary workflow.
 - Shows Plan mode state in Pi's statusline as `plan active` or `plan ready`; `@narumitw/pi-statusline` adds the default `📝` icon unless configured otherwise.
 - Persists Plan mode state in the Pi session so resume restores the mode.
 
 ## 📦 Install
 
+This release requires Pi 0.80.6 or newer.
+
 ```bash
 pi install npm:@narumitw/pi-plan-mode
 ```
@@ -43,13 +46,17 @@ pi -e ./extensions/pi-plan-mode
 /plan
 /plan <prompt>
 /plan tools
+/plan show
+/plan finalize
+/plan implement
+/plan exit
 ```
 
-Use `/plan` to enter Plan mode before writing your planning prompt. Use `/plan <prompt>` to enter Plan mode and immediately submit `<prompt>` as the first Plan-mode user message. Use `/plan tools` to choose which tools are active while Plan mode is enabled; the selector is paginated at 10 tools per page.
+Use `/plan` to enter Plan mode before writing your planning prompt. Use `/plan <prompt>` to enter Plan mode and immediately submit `<prompt>` as the first Plan-mode user message. Use `/plan tools` to choose which tools are active while Plan mode is enabled; the selector is paginated at 10 tools per page. `/plan show` displays the stored plan without starting a model turn, `/plan finalize` explicitly asks the agent to complete the plan or ask one remaining material question, and `/plan implement` hands a stored plan to a normal implementation turn. `show` and `implement` fail closed when no plan is stored; `finalize` requires active Plan mode.
 
 When Plan mode is active, ask the agent to design the change. The agent may inspect files and run read-only commands, but it should not edit files or execute the implementation. It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
 
-By default, Plan mode manages only Pi's built-in tools: `read`, limited `bash`, available read-only built-ins such as `grep`, `find`, and `ls`, plus the required `plan_mode_question` tool. Built-in `edit` and `write` are blocked. `update_plan` is also blocked because it tracks execution progress rather than conversational planning. Extension and custom tools are disabled by default because Pi tools do not expose standardized mutability metadata; enable them from `/plan tools` only when you accept the risk for that session. For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
+By default, Plan mode manages only Pi's built-in tools: `read`, limited `bash`, available read-only built-ins such as `grep`, `find`, and `ls`, plus the required `plan_mode_question` and `plan_mode_complete` tools. Built-in `edit` and `write` are blocked. `update_plan` is also blocked because it tracks execution progress rather than conversational planning. Extension and custom tools are disabled by default because Pi tools do not expose standardized mutability metadata; enable them from `/plan tools` only when you accept the risk for that session. For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
 
 Limited `bash` uses a fail-closed policy. It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`. It rejects output/input redirects, command substitution, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands. Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted. This is extension-level risk reduction, not an OS sandbox.
 
@@ -57,34 +64,18 @@ Limited `bash` uses a fail-closed policy. It accepts common inspection commands,
 
 Pi activates tools by tool name. The `/plan tools` selector stores selections by name and shows each currently effective tool's source from Pi metadata, such as `built-in`, a user extension path, or a project extension path. If an extension overrides a built-in tool with the same name, Pi exposes the effective tool for that name and the selector shows that source.
 
-A complete Plan mode answer should appear only after the agent has resolved discoverable facts and any high-impact user decisions. It should include exactly one block like this:
-
-```xml
-<proposed_plan>
-# Title
-
-## Summary
-...
+A complete Plan mode answer should appear only after the agent has resolved discoverable facts and high-impact user decisions. The agent must call `plan_mode_complete({ plan })` alone as its final action, passing the complete Markdown plan. The tool rejects empty or whitespace-only plans and plans longer than 50,000 JavaScript characters; it does not truncate. Its visible result contains the full plan, and versioned result details let the extension restore it safely from the active session branch.
 
-## Key Changes
-...
+`plan_mode_complete` uses Pi's `terminate: true` hint. Termination is best effort: if a model puts it in a parallel tool batch, Pi terminates the batch early only when every finalized sibling tool also terminates. The prompt therefore requires the completion call to be standalone and last. The extension deliberately does not infer completion from phrases such as “I will present the plan,” and it does not automatically retry a turn with no plan because research and clarification turns may legitimately remain unfinished. If a turn ends without a plan, Plan mode stays active; use `/plan finalize` for explicit recovery.
 
-## Test Plan
-...
+Legacy sessions and models may still submit one non-empty `<proposed_plan>` block with tags on their own lines. That compatibility path remains accepted, but it is not the primary workflow. Empty, malformed, unclosed, or multiple legacy blocks keep Plan mode active and produce a warning.
 
-## Assumptions
-...
-</proposed_plan>
-```
-
-The tags must be on their own lines and the block must be non-empty, complete, and unique within the response. Empty, malformed, unclosed, or multiple blocks keep Plan mode active and produce a warning so the plan can be corrected.
-
-After a valid proposed plan is detected, `/plan` lets you choose whether to implement the plan, stay in Plan mode, or exit Plan mode. Choosing implementation disables Plan mode, restores full tool access, and immediately starts an implementation turn with the proposed plan. Choosing Stay keeps the plan ready while you decide what to do next; to revise the plan, choose Stay and type your revision feedback in the normal prompt. When that next Plan-mode turn starts, the previous plan is no longer treated as the latest implementable plan unless the agent produces an updated `<proposed_plan>`. Choosing exit/off disables Plan mode and discards the proposed plan so it is not carried into later non-plan turns.
+After completion, `/plan` opens the ready actions when interactive UI is available. Choosing implementation—or running `/plan implement`—disables Plan mode, restores full tool access, and starts an implementation turn with the stored plan. Choosing Stay keeps the plan ready. Revision feedback starts another Plan-mode turn and clears the previous implementable plan until an updated completion arrives. For clarification-only follow-ups, the agent answers and resubmits the complete unchanged plan so it remains implementable. Exit/off discards the plan and removes its completion result from later non-Plan model context. Without interactive UI, the plan remains visible in the tool result and stored as `plan ready`; use `/plan show`, `/plan implement`, or `/plan exit` directly.
 
 While Plan mode is enabled, the extension also publishes a compact status for Pi statuslines. With `@narumitw/pi-statusline`, this appears in the extension status area:
 
 - `plan active`: Plan mode is enabled and still gathering context or drafting a plan.
-- `plan ready`: A `<proposed_plan>` was detected and remains ready until you implement it, continue planning, or exit Plan mode.
+- `plan ready`: A completed plan is stored until you implement it, continue planning, or exit Plan mode.
 
 You can also exit directly. Direct exit discards the latest proposed plan instead of treating it as an implementation request:
 
@@ -94,7 +85,7 @@ You can also exit directly. Direct exit discards the latest proposed plan instea
 
 ## ⚙️ Thinking level
 
-Plan mode inherits Pi's current thinking level by default. To request a fixed level only while Plan mode is active, create `$PI_CODING_AGENT_DIR/plan-mode.json` (normally `~/.pi/agent/plan-mode.json`):
+Plan mode inherits Pi's current thinking level by default. To request a fixed level only while Plan mode is active, create `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`):
 
 ```json
 {
@@ -102,7 +93,9 @@ Plan mode inherits Pi's current thinking level by default. To request a fixed le
 }
 ```
 
-Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved. The settings file is optional, is read at session start, and never changes Pi's default setting. Invalid settings produce a warning and fall back to `inherit`.
+Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved. The settings file is optional, is read at session start, and never changes Pi's default setting. Invalid settings produce a warning and fall back to `inherit`.
+
+Compatibility: a valid legacy `plan-mode.json` is migrated automatically to `pi-plan-mode.json`. If both files exist, the new filename takes precedence.
 
 ## 🧠 Codex-like behavior
 
@@ -111,10 +104,11 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
 - Plan mode is a conversational collaboration mode, not TODO/progress tracking.
 - `/plan <prompt>` follows Codex behavior by switching to Plan mode before submitting the inline prompt.
 - The agent should use `plan_mode_question` for important non-discoverable preferences or tradeoffs before finalizing.
+- The agent completes with a standalone `plan_mode_complete` tool call instead of relying on semantic prose detection.
 - `update_plan` checklist use is blocked while Plan mode is active.
-- The implementation boundary is explicit: Plan mode restores tools before starting implementation, choosing implementation immediately triggers a normal agent turn with full tool access, and plain exit/off discards the proposed plan.
+- The implementation boundary is explicit: Plan mode restores tools before starting implementation, choosing implementation immediately triggers a normal agent turn with full tool access, and plain exit/off discards the stored plan.
 - Pi extension safety is approximated with tool classification and fail-closed bash filtering; non-built-in tools remain user-selected at user risk because Pi does not expose standardized tool mutability metadata.
-- Unlike native Codex, Pi detects complete plan blocks after the turn rather than streaming protocol-level Plan items, and it cannot provide sandbox-level enforcement.
+- Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
 
 ## 🗂️ Package layout
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-plan-mode",
-	"version": "0.14.1",
+	"version": "0.15.1",
 	"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
 	"type": "module",
 	"license": "MIT",
@@ -29,7 +29,7 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.3",
-		"@earendil-works/pi-coding-agent": "0.80.3",
+		"@earendil-works/pi-coding-agent": "0.80.6",
 		"typescript": "6.0.3"
 	},
 	"repository": {

package/src/completion-tool.ts

@@ -0,0 +1,70 @@
+export const PLAN_MODE_COMPLETE_TOOL_NAME = "plan_mode_complete";
+export const PLAN_MODE_COMPLETE_VERSION = 1;
+export const PLAN_MODE_MAX_CHARS = 50_000;
+
+export type PlanModeCompletionDetails = {
+	version: typeof PLAN_MODE_COMPLETE_VERSION;
+	source: typeof PLAN_MODE_COMPLETE_TOOL_NAME;
+	plan: string;
+};
+
+export const PLAN_MODE_COMPLETE_PARAMS = {
+	type: "object",
+	additionalProperties: false,
+	required: ["plan"],
+	properties: {
+		plan: {
+			type: "string",
+			minLength: 1,
+			maxLength: PLAN_MODE_MAX_CHARS,
+			description: "The complete decision-ready implementation plan in Markdown.",
+		},
+	},
+} as const;
+
+type NormalizePlanModeCompletionResult =
+	| { ok: true; plan: string }
+	| { ok: false; error: string };
+
+export function normalizePlanModeCompletion(input: unknown): NormalizePlanModeCompletionResult {
+	if (!isRecord(input) || typeof input.plan !== "string") {
+		return { ok: false, error: "plan must be a string" };
+	}
+	const plan = input.plan.trim();
+	if (!plan) return { ok: false, error: "plan must not be empty" };
+	if (plan.length > PLAN_MODE_MAX_CHARS) {
+		return {
+			ok: false,
+			error: `plan must not exceed ${PLAN_MODE_MAX_CHARS} characters`,
+		};
+	}
+	return { ok: true, plan };
+}
+
+export function planFromCompletionDetails(value: unknown) {
+	if (!isRecord(value)) return undefined;
+	if (
+		value.version !== PLAN_MODE_COMPLETE_VERSION ||
+		value.source !== PLAN_MODE_COMPLETE_TOOL_NAME
+	) {
+		return undefined;
+	}
+	const normalized = normalizePlanModeCompletion({ plan: value.plan });
+	return normalized.ok ? normalized.plan : undefined;
+}
+
+export function planModeCompleted(plan: string) {
+	return {
+		content: [{ type: "text" as const, text: `**Proposed Plan**\n\n${plan}` }],
+		details: {
+			version: PLAN_MODE_COMPLETE_VERSION,
+			source: PLAN_MODE_COMPLETE_TOOL_NAME,
+			plan,
+		} satisfies PlanModeCompletionDetails,
+		terminate: true,
+	};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/message-transform.ts

@@ -1,3 +1,5 @@
+import { PLAN_MODE_COMPLETE_TOOL_NAME } from "./completion-tool.js";
+
 const PLAN_CONTEXT_MESSAGE_TYPE = "plan-mode-context";
 const PROPOSED_PLAN_MESSAGE_TYPE = "proposed-plan";
 const PROPOSED_PLAN_PATTERN = /^<proposed_plan>[\t ]*\r?\n([\s\S]*?)\r?\n<\/proposed_plan>[\t ]*$/gm;
@@ -56,14 +58,47 @@ export function messageContainsLegacyPlanModeContextArtifact(message: unknown) {
 }
 
 export function messageContainsInactivePlanModeArtifact(message: unknown) {
-	return unwrapSessionMessage(message).customType === PROPOSED_PLAN_MESSAGE_TYPE;
+	const candidate = unwrapSessionMessage(message);
+	return (
+		candidate.customType === PROPOSED_PLAN_MESSAGE_TYPE ||
+		(candidate.role === "toolResult" && candidate.toolName === PLAN_MODE_COMPLETE_TOOL_NAME)
+	);
 }
 
 export function stripProposedPlanBlocksFromMessage<T>(message: T): T {
+	return replaceAssistantContent(message, stripProposedPlanBlocksFromContent);
+}
+
+export function stripPlanModeCompletionCallsFromMessage<T>(message: T): T {
+	return replaceAssistantContent(message, (content) => {
+		if (!Array.isArray(content)) return content;
+		const nextContent = content.filter((block) => {
+			const candidate = block as { type?: string; name?: string };
+			return !(
+				candidate.type === "toolCall" && candidate.name === PLAN_MODE_COMPLETE_TOOL_NAME
+			);
+		});
+		return nextContent.length === content.length ? content : nextContent;
+	});
+}
+
+export function isEmptyAssistantMessage(message: unknown) {
+	const candidate = unwrapSessionMessage(message);
+	return (
+		candidate.role === "assistant" &&
+		Array.isArray(candidate.content) &&
+		candidate.content.length === 0
+	);
+}
+
+function replaceAssistantContent<T>(
+	message: T,
+	transform: (content: unknown) => unknown,
+): T {
 	const candidate = unwrapSessionMessage(message);
 	if (candidate.role !== "assistant") return message;
 
-	const content = stripProposedPlanBlocksFromContent(candidate.content);
+	const content = transform(candidate.content);
 	if (content === candidate.content) return message;
 
 	if (isSessionMessageEntry(message)) {
@@ -74,7 +109,12 @@ export function stripProposedPlanBlocksFromMessage<T>(message: T): T {
 
 function unwrapSessionMessage(message: unknown) {
 	const entry = message as { message?: unknown };
-	return (entry.message ?? message) as { role?: string; customType?: string; content?: unknown };
+	return (entry.message ?? message) as {
+		role?: string;
+		customType?: string;
+		toolName?: string;
+		content?: unknown;
+	};
 }
 
 function isSessionMessageEntry<T>(message: T): message is T & { message: SessionMessage } {

package/src/plan-mode.ts

@@ -3,12 +3,20 @@ import type {
 	ExtensionContext,
 	ToolInfo,
 } from "@earendil-works/pi-coding-agent";
+import {
+	PLAN_MODE_COMPLETE_PARAMS,
+	PLAN_MODE_COMPLETE_TOOL_NAME,
+	normalizePlanModeCompletion,
+	planModeCompleted,
+} from "./completion-tool.js";
 import {
 	extractProposedPlan,
+	isEmptyAssistantMessage,
 	latestAssistantText,
 	parseProposedPlan,
 	messageContainsInactivePlanModeArtifact,
 	messageContainsLegacyPlanModeContextArtifact,
+	stripPlanModeCompletionCallsFromMessage,
 	stripProposedPlanBlocksFromMessage,
 } from "./message-transform.js";
 import { buildPlanModePrompt } from "./prompt.js";
@@ -30,11 +38,14 @@ import {
 } from "./tool-policy.js";
 import {
 	configuredThinkingLevel,
-	PLAN_MODE_THINKING_LEVELS,
 	readPlanModeSettings,
-	type PlanModeFixedThinkingLevel,
 	type PlanModeSettings,
 } from "./settings.js";
+import {
+	restorePlanModeState,
+	type PlanCompletionSource,
+	type PlanModeState,
+} from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 const STATUS_KEY = "plan-mode";
@@ -50,35 +61,21 @@ interface CommandArgumentCompletion {
 	description?: string;
 }
 
-interface PlanModeState {
-	enabled: boolean;
-	latestPlan?: string;
-	awaitingAction: boolean;
-	selectedToolNames?: string[];
-	selectedToolKeys?: string[];
-	previousThinkingLevel?: PlanModeFixedThinkingLevel;
-	appliedThinkingLevel?: PlanModeFixedThinkingLevel;
-	manualThinkingLevel?: PlanModeFixedThinkingLevel;
+interface ReadyPresentationIntent {
+	nonce: number;
+	plan: string;
+	source: PlanCompletionSource;
 }
 
-type SessionEntry = {
-	type?: string;
-	customType?: string;
-	data?: Partial<PlanModeState>;
-	message?: SessionMessage;
-};
-
-type SessionMessage = {
-	role?: string;
-	content?: unknown;
-};
-
 type TextBlock = {
 	type?: string;
 	text?: string;
 };
 
 const PLAN_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
+	{ value: "show", label: "show", description: "Show the completed plan" },
+	{ value: "finalize", label: "finalize", description: "Request a completed plan" },
+	{ value: "implement", label: "implement", description: "Implement the completed plan" },
 	{ value: "exit", label: "exit", description: "Leave Plan mode" },
 	{ value: "off", label: "off", description: "Leave Plan mode" },
 	{ value: "tools", label: "tools", description: "Select tools allowed in Plan mode" },
@@ -88,6 +85,8 @@ export default function planMode(pi: ExtensionAPI) {
 	let state: PlanModeState = { enabled: false, awaitingAction: false };
 	let settings: PlanModeSettings = { thinkingLevel: "inherit" };
 	let previousTools: string[] | undefined;
+	let readyPresentationIntent: ReadyPresentationIntent | undefined;
+	let nextReadyPresentationNonce = 0;
 
 	pi.registerFlag("plan", {
 		description: "Start in Codex-like Plan mode",
@@ -140,12 +139,50 @@ export default function planMode(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: PLAN_MODE_COMPLETE_TOOL_NAME,
+		label: "Complete plan",
+		description:
+			"Submit the complete decision-ready implementation plan for user review. Only available while Plan mode is active, and must be the final standalone action.",
+		promptSnippet: "Submit the final Plan-mode implementation plan",
+		promptGuidelines: [
+			"Call plan_mode_complete alone as the final action only after the implementation plan is decision-complete.",
+		],
+		parameters: PLAN_MODE_COMPLETE_PARAMS,
+		async execute(_toolCallId, params: unknown, _signal, _onUpdate, ctx) {
+			if (!state.enabled) {
+				throw new Error("plan_mode_complete is only available while Plan mode is active");
+			}
+			const parsed = normalizePlanModeCompletion(params);
+			if (!parsed.ok) throw new Error(parsed.error);
+
+			acceptCompletedPlan(parsed.plan, PLAN_MODE_COMPLETE_TOOL_NAME, ctx);
+			return planModeCompleted(parsed.plan);
+		},
+	});
+
 	pi.registerCommand("plan", {
 		description: "Enter or manage Codex-like Plan mode",
 		getArgumentCompletions: completePlanArguments,
 		handler: async (args, ctx) => {
 			const prompt = args.trim();
 			const command = prompt.toLowerCase();
+			if (command === "show") {
+				showStoredPlan(ctx);
+				return;
+			}
+			if (command === "finalize") {
+				requestFinalPlan(ctx);
+				return;
+			}
+			if (command === "implement") {
+				if (!state.enabled || !state.latestPlan?.trim()) {
+					ctx.ui.notify("No completed plan is available to implement.", "warning");
+					return;
+				}
+				startImplementation(ctx);
+				return;
+			}
 			if (command === "exit" || command === "off") {
 				exitPlanMode(ctx);
 				ctx.ui.notify("Plan mode disabled. Proposed plan discarded.", "info");
@@ -170,12 +207,14 @@ export default function planMode(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		readyPresentationIntent = undefined;
 		settings = { thinkingLevel: "inherit" };
 		const loadedSettings = await readPlanModeSettings();
 		if (loadedSettings.kind === "loaded") settings = loadedSettings.settings;
 		else if (loadedSettings.kind === "invalid") {
 			ctx.ui.notify(`pi-plan-mode settings ignored: ${loadedSettings.reason}`, "warning");
 		}
+		if (loadedSettings.notice) ctx.ui.notify(loadedSettings.notice, "warning");
 		restoreState(ctx);
 		if (pi.getFlag("plan") === true) state.enabled = true;
 		if (state.enabled) {
@@ -199,6 +238,7 @@ export default function planMode(pi: ExtensionAPI) {
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {
+		readyPresentationIntent = undefined;
 		captureManualThinkingLevel();
 		persistState();
 		if (state.enabled) {
@@ -249,14 +289,22 @@ export default function planMode(pi: ExtensionAPI) {
 		return {
 			messages: messagesWithoutLegacyPlanContext
 				.filter((message: unknown) => !messageContainsInactivePlanModeArtifact(message))
-				.map(stripProposedPlanBlocksFromMessage),
+				.map(stripProposedPlanBlocksFromMessage)
+				.map(stripPlanModeCompletionCallsFromMessage)
+				.filter((message: unknown) => !isEmptyAssistantMessage(message)),
 		};
 	});
 
 	pi.on("before_agent_start", (event, ctx) => {
 		if (!state.enabled) return;
 		if (state.latestPlan || state.awaitingAction) {
-			state = { ...state, latestPlan: undefined, awaitingAction: false };
+			readyPresentationIntent = undefined;
+			state = {
+				...state,
+				latestPlan: undefined,
+				latestPlanSource: undefined,
+				awaitingAction: false,
+			};
 			persistState();
 			updateUi(ctx);
 		}
@@ -279,30 +327,36 @@ export default function planMode(pi: ExtensionAPI) {
 			updateUi(ctx);
 			return;
 		}
-		const proposedPlan = parsedPlan.plan;
-
-		state = { ...state, latestPlan: proposedPlan, awaitingAction: true };
-		persistState();
-		updateUi(ctx);
+		acceptCompletedPlan(parsedPlan.plan, "legacy_proposed_plan", ctx);
+	});
 
-		scheduleAfterCurrentAgentRun(async () => {
-			if (!state.enabled || state.latestPlan !== proposedPlan) return;
-			if (ctx.hasUI) await showPlanReadyMenu(ctx);
-			if (!state.enabled || state.latestPlan !== proposedPlan) return;
+	pi.on("agent_settled", async (_event, ctx) => {
+		const intent = readyPresentationIntent;
+		if (!intent || !readyPresentationIsCurrent(intent)) return;
+		if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
 
-			pi.sendMessage(
-				{
-					customType: PROPOSED_PLAN_MESSAGE_TYPE,
-					content: `**Proposed Plan**\n\n${proposedPlan}`,
-					display: true,
-				},
-				{ triggerTurn: false },
-			);
-		});
+		readyPresentationIntent = undefined;
+		try {
+			if (intent.source === "legacy_proposed_plan") {
+				pi.sendMessage(
+					{
+						customType: PROPOSED_PLAN_MESSAGE_TYPE,
+						content: `**Proposed Plan**\n\n${intent.plan}`,
+						display: true,
+					},
+					{ triggerTurn: false },
+				);
+			}
+			if (ctx.hasUI && completedPlanIsCurrent(intent)) {
+				await showPlanReadyMenu(ctx);
+			}
+		} catch (error: unknown) {
+			if (!isStaleExtensionContextError(error)) throw error;
+		}
 	});
 
 	function enterPlanMode(ctx: ExtensionContext) {
-		if (!state.enabled) previousTools = withoutPlanModeQuestionTool(safeGetActiveTools());
+		if (!state.enabled) previousTools = withoutRequiredPlanModeTools(safeGetActiveTools());
 		state = { ...state, enabled: true, awaitingAction: false };
 		activatePlanModeTools();
 		applyPlanThinkingLevel();
@@ -321,10 +375,12 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function exitPlanMode(ctx: ExtensionContext) {
 		const wasEnabled = state.enabled;
+		readyPresentationIntent = undefined;
 		state = {
 			...state,
 			enabled: false,
 			latestPlan: undefined,
+			latestPlanSource: undefined,
 			awaitingAction: false,
 			manualThinkingLevel: undefined,
 		};
@@ -349,17 +405,82 @@ export default function planMode(pi: ExtensionAPI) {
 		}
 	}
 
-	function scheduleAfterCurrentAgentRun(task: () => Promise<void> | void) {
-		setTimeout(() => {
-			void Promise.resolve(task()).catch((error: unknown) => {
-				const message = error instanceof Error ? error.message : String(error);
-				console.error(`Plan mode follow-up failed: ${message}`);
-			});
-		}, 0);
+	function acceptCompletedPlan(
+		plan: string,
+		source: PlanCompletionSource,
+		ctx: ExtensionContext,
+	) {
+		if (
+			state.enabled &&
+			state.awaitingAction &&
+			state.latestPlan === plan &&
+			state.latestPlanSource === source
+		) {
+			return;
+		}
+		state = {
+			...state,
+			latestPlan: plan,
+			latestPlanSource: source,
+			awaitingAction: true,
+		};
+		readyPresentationIntent = {
+			nonce: ++nextReadyPresentationNonce,
+			plan,
+			source,
+		};
+		persistState();
+		updateUi(ctx);
+	}
+
+	function completedPlanIsCurrent(intent: ReadyPresentationIntent) {
+		return (
+			state.enabled &&
+			state.awaitingAction &&
+			state.latestPlan === intent.plan &&
+			state.latestPlanSource === intent.source
+		);
+	}
+
+	function readyPresentationIsCurrent(intent: ReadyPresentationIntent) {
+		return completedPlanIsCurrent(intent) && readyPresentationIntent?.nonce === intent.nonce;
+	}
+
+	function showStoredPlan(ctx: ExtensionContext) {
+		const plan = state.latestPlan?.trim();
+		if (!state.enabled || !plan) {
+			ctx.ui.notify("No completed plan is available. Use /plan finalize when planning is complete.", "info");
+			return;
+		}
+		try {
+			pi.sendMessage(
+				{
+					customType: PROPOSED_PLAN_MESSAGE_TYPE,
+					content: `**Proposed Plan**\n\n${plan}`,
+					display: true,
+				},
+				{ triggerTurn: false },
+			);
+		} catch (error: unknown) {
+			const detail = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Unable to show completed plan: ${detail}`, "error");
+		}
+	}
+
+	function requestFinalPlan(ctx: ExtensionContext) {
+		if (!state.enabled) {
+			ctx.ui.notify("Plan mode is not active. Use /plan first.", "warning");
+			return;
+		}
+		sendPlanModeUserMessage(
+			"Finalize the current implementation plan now. If any material decision remains, use plan_mode_question instead. Otherwise call plan_mode_complete alone as your final action with the complete decision-ready plan.",
+			ctx,
+		);
 	}
 
 	function startImplementation(ctx: ExtensionContext) {
 		const plan = state.latestPlan?.trim();
+		const source = state.latestPlanSource;
 		exitPlanMode(ctx);
 
 		if (!plan) {
@@ -373,7 +494,7 @@ export default function planMode(pi: ExtensionAPI) {
 		);
 		if (!sent) {
 			enterPlanMode(ctx);
-			state = { ...state, latestPlan: plan, awaitingAction: true };
+			state = { ...state, latestPlan: plan, latestPlanSource: source, awaitingAction: true };
 			persistState();
 			updateUi(ctx);
 		}
@@ -393,10 +514,19 @@ export default function planMode(pi: ExtensionAPI) {
 					"Stay in Plan mode",
 					"Exit Plan mode",
 				]
-			: ["Configure Plan-mode tools", "Stay in Plan mode", "Exit Plan mode"];
+			: [
+					"Request final plan",
+					"Configure Plan-mode tools",
+					"Stay in Plan mode",
+					"Exit Plan mode",
+				];
 		const choice = await ctx.ui.select(planStatusText(), choices);
 		if (choice === "Show latest proposed plan") {
-			ctx.ui.notify(state.latestPlan ?? "No proposed plan yet.", "info");
+			showStoredPlan(ctx);
+			return;
+		}
+		if (choice === "Request final plan") {
+			requestFinalPlan(ctx);
 			return;
 		}
 		if (choice === "Implement this plan") {
@@ -497,7 +627,7 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 
 	function activatePlanModeTools() {
-		previousTools ??= withoutPlanModeQuestionTool(safeGetActiveTools());
+		previousTools ??= withoutRequiredPlanModeTools(safeGetActiveTools());
 		applyPlanModeTools();
 	}
 
@@ -507,7 +637,9 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function planModeToolNames() {
 		const tools = selectableTools();
-		if (tools.length === 0) return ["read", "bash", PLAN_MODE_QUESTION_TOOL_NAME];
+		if (tools.length === 0) {
+			return ["read", "bash", PLAN_MODE_QUESTION_TOOL_NAME, PLAN_MODE_COMPLETE_TOOL_NAME];
+		}
 
 		const selectedNames = planModeSelectedNames(tools);
 		return withRequiredPlanModeTools(
@@ -549,7 +681,10 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function selectableTools() {
 		return safeGetAllTools()
-			.filter((tool) => tool.name !== PLAN_MODE_QUESTION_TOOL_NAME)
+			.filter(
+				(tool) =>
+					tool.name !== PLAN_MODE_QUESTION_TOOL_NAME && tool.name !== PLAN_MODE_COMPLETE_TOOL_NAME,
+			)
 			.sort(compareTools);
 	}
 
@@ -567,7 +702,7 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function restoreTools() {
 		const restoredTools = previousTools ?? DEFAULT_TOOLS;
-		pi.setActiveTools(withoutPlanModeQuestionTool(restoredTools));
+		pi.setActiveTools(withoutRequiredPlanModeTools(restoredTools));
 		previousTools = undefined;
 	}
 
@@ -620,7 +755,7 @@ export default function planMode(pi: ExtensionAPI) {
 
 	function deactivatePlanModeQuestionTool() {
 		const activeTools = safeGetActiveTools();
-		const filteredTools = withoutPlanModeQuestionTool(activeTools);
+		const filteredTools = withoutRequiredPlanModeTools(activeTools);
 		if (filteredTools.length !== activeTools.length) {
 			pi.setActiveTools(filteredTools);
 		}
@@ -639,30 +774,7 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 
 	function restoreState(ctx: ExtensionContext) {
-		state = { enabled: false, awaitingAction: false };
-		const entries = ctx.sessionManager.getEntries() as SessionEntry[];
-		const entry = entries
-			.filter((candidate) => candidate.type === "custom" && candidate.customType === STATE_ENTRY_TYPE)
-			.pop();
-		if (!isRecord(entry?.data)) return;
-		const enabled = entry.data.enabled === true;
-		state = {
-			enabled,
-			latestPlan:
-				enabled && typeof entry.data.latestPlan === "string" ? entry.data.latestPlan : undefined,
-			awaitingAction: enabled && entry.data.awaitingAction === true,
-			selectedToolNames: stringArray(entry.data.selectedToolNames),
-			selectedToolKeys: stringArray(entry.data.selectedToolKeys),
-			previousThinkingLevel: enabled
-				? fixedThinkingLevel(entry.data.previousThinkingLevel)
-				: undefined,
-			appliedThinkingLevel: enabled
-				? fixedThinkingLevel(entry.data.appliedThinkingLevel)
-				: undefined,
-			manualThinkingLevel: enabled
-				? fixedThinkingLevel(entry.data.manualThinkingLevel)
-				: undefined,
-		};
+		state = restorePlanModeState(ctx.sessionManager.getBranch(), STATE_ENTRY_TYPE);
 	}
 
 	function updateUi(ctx: ExtensionContext) {
@@ -676,7 +788,7 @@ export default function planMode(pi: ExtensionAPI) {
 			ctx.ui.setWidget(PLAN_WIDGET_KEY, [
 				"Plan mode: planning",
 				formatToolSummary(),
-				"Produce a <proposed_plan> block.",
+				"Finish with plan_mode_complete when decision-ready.",
 			]);
 		} else {
 			ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
@@ -697,7 +809,7 @@ export default function planMode(pi: ExtensionAPI) {
 	function planStatusText() {
 		if (!state.enabled) return "Plan mode is off.";
 		if (state.latestPlan) return `Plan mode is active and a proposed plan is ready. ${formatToolSummary()}`;
-		return `Plan mode is active. ${formatToolSummary()} Explore, ask, and produce a <proposed_plan> block.`;
+		return `Plan mode is active. ${formatToolSummary()} Explore, ask, and finish with plan_mode_complete when decision-ready.`;
 	}
 
 	function formatToolSummary() {
@@ -761,32 +873,33 @@ function unique(values: string[]) {
 	return Array.from(new Set(values));
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function stringArray(value: unknown) {
-	return Array.isArray(value) && value.every((item): item is string => typeof item === "string")
-		? unique(value)
-		: undefined;
-}
-
-function fixedThinkingLevel(value: unknown): PlanModeFixedThinkingLevel | undefined {
-	return typeof value === "string" &&
-		value !== "inherit" &&
-		PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
-		? (value as PlanModeFixedThinkingLevel)
-		: undefined;
+function isStaleExtensionContextError(error: unknown) {
+	return (
+		error instanceof Error &&
+		(error.message.includes("This extension ctx is stale after session replacement or reload") ||
+			error.message.includes("Extension context is no longer active"))
+	);
 }
 
 export function withRequiredPlanModeTools(toolNames: string[]) {
-	return unique([...withoutPlanModeQuestionTool(toolNames), PLAN_MODE_QUESTION_TOOL_NAME]);
+	return unique([
+		...withoutRequiredPlanModeTools(toolNames),
+		PLAN_MODE_QUESTION_TOOL_NAME,
+		PLAN_MODE_COMPLETE_TOOL_NAME,
+	]);
 }
 
 export function withoutPlanModeQuestionTool(toolNames: string[]) {
 	return toolNames.filter((toolName) => toolName !== PLAN_MODE_QUESTION_TOOL_NAME);
 }
 
+function withoutRequiredPlanModeTools(toolNames: string[]) {
+	return toolNames.filter(
+		(toolName) =>
+			toolName !== PLAN_MODE_QUESTION_TOOL_NAME && toolName !== PLAN_MODE_COMPLETE_TOOL_NAME,
+	);
+}
+
 function invalidPlanMessage(kind: "empty" | "multiple" | "malformed" | "unclosed") {
 	const detail = {
 		empty: "the block is empty",

package/src/prompt.ts

@@ -32,27 +32,28 @@ You are in Plan Mode, a Codex-like collaboration mode for producing a decision-c
 - Use plan_mode_question for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. Ask 1-3 concise questions with 2-4 meaningful options. Do not include filler options.
 - If plan_mode_question returns cancelled or ui_unavailable, do not jump straight to a final plan when the missing answer is high impact. Ask one concise plain-text question or proceed only with a clearly stated low-risk assumption.
 
-## Finalization rule
+## Ending each turn
 
-Only output the final plan when it is decision-complete and leaves no decisions to the implementer. When presenting the official plan, output exactly one proposed plan block and keep the tags exactly as shown:
+Every Plan-mode turn that advances or finalizes the plan must end in exactly one of these ways:
 
-<proposed_plan>
-# Title
+- If a material decision remains, use plan_mode_question. If interactive UI is unavailable, ask one concise plain-text question instead.
+- If the implementation plan is decision-complete, call plan_mode_complete alone as your final action. Do not call other tools in the same batch and do not emit a normal assistant response after it.
 
-## Summary
-...
+If a follow-up asks only for clarification and does not change or challenge the plan, answer it directly, then call plan_mode_complete alone as the final action with the complete unchanged plan so it remains available for implementation.
 
-## Key Changes
-...
+Never end with prose that merely announces you are about to present, write, or finalize the plan. Submit the actual plan with plan_mode_complete in that turn.
 
-## Test Plan
-...
+## Completion rule
 
-## Assumptions
-...
-</proposed_plan>
+Only call plan_mode_complete when the plan leaves no implementation decisions unresolved. Pass the complete plan as Markdown with:
 
-Keep the proposed plan concise, human and agent digestible, and free of open decisions. Prefer grouped behavior-level changes over file-by-file or symbol-by-symbol inventories. Do not ask "should I proceed?" in the final output; the Plan-mode ready menu handles implementation, staying in Plan mode, or exit.
+- A clear title
+- A brief summary
+- Important changes to behavior, public APIs, interfaces, or types
+- Test cases and verification scenarios
+- Explicit assumptions and defaults chosen where needed
 
-Produce at most one <proposed_plan> block per turn. If the user requests revisions after a prior proposed plan, any new block must be a complete replacement. If there is not enough information for a complete replacement, continue planning without a block. If a follow-up only asks for clarification and does not change or challenge the plan, answer it and then reproduce the prior proposed plan unchanged.`;
+Keep the plan concise, human and agent digestible, and free of open decisions. Prefer grouped behavior-level changes over file-by-file or symbol-by-symbol inventories. Do not ask "should I proceed?"; plan_mode_complete opens the Plan-mode ready flow.
+
+If the user requests revisions after a completed plan, the next plan_mode_complete call must contain a complete replacement, not a delta. If there is not enough information for a complete replacement, continue planning with plan_mode_question instead of calling plan_mode_complete.`;
 }

package/src/settings.ts

@@ -1,8 +1,10 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { access, link, lstat, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-export const PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
+export const PLAN_MODE_SETTINGS_FILE = "pi-plan-mode.json";
+const LEGACY_PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
 export const PLAN_MODE_THINKING_LEVELS = [
 	"inherit",
 	"off",
@@ -11,6 +13,7 @@ export const PLAN_MODE_THINKING_LEVELS = [
 	"medium",
 	"high",
 	"xhigh",
+	"max",
 ] as const;
 
 export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
@@ -19,9 +22,9 @@ export interface PlanModeSettings {
 	thinkingLevel: PlanModeThinkingLevel;
 }
 export type PlanModeSettingsLoadResult =
-	| { kind: "missing" }
-	| { kind: "invalid"; reason: string }
-	| { kind: "loaded"; settings: PlanModeSettings };
+	| { kind: "missing"; notice?: string }
+	| { kind: "invalid"; reason: string; notice?: string }
+	| { kind: "loaded"; settings: PlanModeSettings; notice?: string };
 
 export function normalizePlanModeSettings(value: unknown): PlanModeSettings | undefined {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
@@ -34,22 +37,127 @@ export function normalizePlanModeSettings(value: unknown): PlanModeSettings | un
 }
 
 export async function readPlanModeSettings(
-	settingsPath = join(getAgentDir(), PLAN_MODE_SETTINGS_FILE),
+	settingsPath?: string,
 ): Promise<PlanModeSettingsLoadResult> {
+	if (settingsPath) return readSettingsFile(settingsPath);
+	const canonicalPath = join(getAgentDir(), PLAN_MODE_SETTINGS_FILE);
+	const canonical = await readSettingsFile(canonicalPath);
+	const legacyPath = join(getAgentDir(), LEGACY_PLAN_MODE_SETTINGS_FILE);
+	if (canonical.kind !== "missing") {
+		return (await exists(legacyPath))
+			? {
+					...canonical,
+					notice: `${LEGACY_PLAN_MODE_SETTINGS_FILE} ignored because ${PLAN_MODE_SETTINGS_FILE} takes precedence.`,
+				}
+			: canonical;
+	}
+
+	const legacySnapshot = await readSettingsSnapshot(legacyPath);
+	const legacy = legacySnapshot.result;
+	const raced = await readSettingsFile(canonicalPath);
+	if (raced.kind !== "missing") return raced;
+	if (legacy.kind !== "loaded") return legacy;
+	let installedIdentity: FileIdentity;
+	try {
+		installedIdentity = await installFileExclusively(
+			canonicalPath,
+			legacySnapshot.contents ?? "",
+		);
+	} catch (error) {
+		const created = await readSettingsFile(canonicalPath);
+		if (created.kind !== "missing") {
+			return {
+				...created,
+				notice: `${LEGACY_PLAN_MODE_SETTINGS_FILE} ignored because ${PLAN_MODE_SETTINGS_FILE} was created concurrently.`,
+			};
+		}
+		return {
+			...legacy,
+			notice: `Plan-mode settings migration failed: ${formatError(error)}. The legacy file was used for this session.`,
+		};
+	}
+	if (!(await fileContentsEqual(legacyPath, legacySnapshot.contents ?? ""))) {
+		const removed = await removeFileIfIdentityMatches(
+			canonicalPath,
+			installedIdentity,
+			legacySnapshot.contents ?? "",
+		);
+		return {
+			...legacy,
+			notice: removed
+				? `${LEGACY_PLAN_MODE_SETTINGS_FILE} changed during migration; the stale ${PLAN_MODE_SETTINGS_FILE} snapshot was removed.`
+				: `${LEGACY_PLAN_MODE_SETTINGS_FILE} changed during migration, but ${PLAN_MODE_SETTINGS_FILE} was replaced concurrently and takes precedence on the next load.`,
+		};
+	}
+	try {
+		await rm(legacyPath);
+		return {
+			...legacy,
+			notice: `Plan-mode settings migrated from ${LEGACY_PLAN_MODE_SETTINGS_FILE} to ${PLAN_MODE_SETTINGS_FILE}.`,
+		};
+	} catch (error) {
+		return {
+			...legacy,
+			notice: `Plan-mode settings migrated to ${PLAN_MODE_SETTINGS_FILE}, but ${LEGACY_PLAN_MODE_SETTINGS_FILE} could not be removed: ${formatError(error)}.`,
+		};
+	}
+}
+
+type FileIdentity = { dev: number; ino: number };
+
+async function installFileExclusively(filePath: string, contents: string): Promise<FileIdentity> {
+	const tempFile = join(dirname(filePath), `.${PLAN_MODE_SETTINGS_FILE}.${randomUUID()}.tmp`);
+	try {
+		await writeFile(tempFile, contents, { encoding: "utf8", flag: "wx" });
+		const identity = await lstat(tempFile);
+		await link(tempFile, filePath);
+		return { dev: identity.dev, ino: identity.ino };
+	} finally {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+	}
+}
+
+async function removeFileIfIdentityMatches(
+	filePath: string,
+	expected: FileIdentity,
+	expectedContents: string,
+) {
+	try {
+		const current = await lstat(filePath);
+		if (current.dev !== expected.dev || current.ino !== expected.ino) return false;
+		if ((await readFile(filePath, "utf8")) !== expectedContents) return false;
+		await rm(filePath);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function readSettingsFile(settingsPath: string): Promise<PlanModeSettingsLoadResult> {
+	return (await readSettingsSnapshot(settingsPath)).result;
+}
+
+async function readSettingsSnapshot(settingsPath: string): Promise<{
+	result: PlanModeSettingsLoadResult;
+	contents?: string;
+}> {
 	let contents: string;
 	try {
 		contents = await readFile(settingsPath, "utf8");
 	} catch (error: unknown) {
-		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
-		return { kind: "invalid", reason: formatError(error) };
+		if (isNodeError(error) && error.code === "ENOENT") return { result: { kind: "missing" } };
+		return { result: { kind: "invalid", reason: formatError(error) } };
 	}
 	try {
 		const settings = normalizePlanModeSettings(JSON.parse(contents) as unknown);
-		return settings
-			? { kind: "loaded", settings }
-			: { kind: "invalid", reason: "invalid settings shape" };
+		return {
+			contents,
+			result: settings
+				? { kind: "loaded", settings }
+				: { kind: "invalid", reason: "invalid settings shape" },
+		};
 	} catch (error: unknown) {
-		return { kind: "invalid", reason: formatError(error) };
+		return { contents, result: { kind: "invalid", reason: formatError(error) } };
 	}
 }
 
@@ -59,6 +167,23 @@ export function configuredThinkingLevel(
 	return settings.thinkingLevel === "inherit" ? undefined : settings.thinkingLevel;
 }
 
+async function fileContentsEqual(path: string, expected: string) {
+	try {
+		return (await readFile(path, "utf8")) === expected;
+	} catch {
+		return false;
+	}
+}
+
+async function exists(path: string) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
 	return error instanceof Error && "code" in error;
 }

package/src/state.ts

@@ -0,0 +1,128 @@
+import {
+	PLAN_MODE_COMPLETE_TOOL_NAME,
+	normalizePlanModeCompletion,
+	planFromCompletionDetails,
+} from "./completion-tool.js";
+import {
+	PLAN_MODE_THINKING_LEVELS,
+	type PlanModeFixedThinkingLevel,
+} from "./settings.js";
+
+export type PlanCompletionSource =
+	| typeof PLAN_MODE_COMPLETE_TOOL_NAME
+	| "legacy_proposed_plan";
+
+export interface PlanModeState {
+	enabled: boolean;
+	latestPlan?: string;
+	latestPlanSource?: PlanCompletionSource;
+	awaitingAction: boolean;
+	selectedToolNames?: string[];
+	selectedToolKeys?: string[];
+	previousThinkingLevel?: PlanModeFixedThinkingLevel;
+	appliedThinkingLevel?: PlanModeFixedThinkingLevel;
+	manualThinkingLevel?: PlanModeFixedThinkingLevel;
+}
+
+type SessionEntry = {
+	type?: string;
+	customType?: string;
+	data?: unknown;
+	message?: {
+		role?: string;
+		toolName?: string;
+		details?: unknown;
+	};
+};
+
+export function restorePlanModeState(entries: unknown[], stateEntryType: string): PlanModeState {
+	const branch = entries as SessionEntry[];
+	let stateEntryIndex = -1;
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const candidate = branch[index];
+		if (candidate?.type === "custom" && candidate.customType === stateEntryType) {
+			stateEntryIndex = index;
+			break;
+		}
+	}
+	const entry = branch[stateEntryIndex];
+	if (!isRecord(entry?.data)) return { enabled: false, awaitingAction: false };
+
+	const enabled = entry.data.enabled === true;
+	const persistedSource = enabled
+		? planCompletionSource(entry.data.latestPlanSource)
+		: undefined;
+	const persistedPlan = enabled
+		? normalizePersistedPlan(entry.data.latestPlan, persistedSource)
+		: undefined;
+	const recoveredPlan =
+		enabled && !persistedPlan
+			? latestCompletionPlan(branch.slice(stateEntryIndex + 1))
+			: undefined;
+	const latestPlan = persistedPlan ?? recoveredPlan;
+	return {
+		enabled,
+		latestPlan,
+		latestPlanSource: enabled
+			? (persistedPlan ? persistedSource : undefined) ??
+				(recoveredPlan ? PLAN_MODE_COMPLETE_TOOL_NAME : undefined)
+			: undefined,
+		awaitingAction: enabled && latestPlan !== undefined,
+		selectedToolNames: stringArray(entry.data.selectedToolNames),
+		selectedToolKeys: stringArray(entry.data.selectedToolKeys),
+		previousThinkingLevel: enabled
+			? fixedThinkingLevel(entry.data.previousThinkingLevel)
+			: undefined,
+		appliedThinkingLevel: enabled
+			? fixedThinkingLevel(entry.data.appliedThinkingLevel)
+			: undefined,
+		manualThinkingLevel: enabled
+			? fixedThinkingLevel(entry.data.manualThinkingLevel)
+			: undefined,
+	};
+}
+
+function normalizePersistedPlan(value: unknown, source: PlanCompletionSource | undefined) {
+	if (typeof value !== "string") return undefined;
+	if (source === PLAN_MODE_COMPLETE_TOOL_NAME) {
+		const normalized = normalizePlanModeCompletion({ plan: value });
+		return normalized.ok ? normalized.plan : undefined;
+	}
+	return value.trim() || undefined;
+}
+
+function latestCompletionPlan(entries: SessionEntry[]) {
+	for (let index = entries.length - 1; index >= 0; index -= 1) {
+		const message = entries[index]?.message;
+		if (message?.role !== "toolResult" || message.toolName !== PLAN_MODE_COMPLETE_TOOL_NAME) {
+			continue;
+		}
+		const plan = planFromCompletionDetails(message.details);
+		if (plan) return plan;
+	}
+	return undefined;
+}
+
+function planCompletionSource(value: unknown): PlanCompletionSource | undefined {
+	return value === PLAN_MODE_COMPLETE_TOOL_NAME || value === "legacy_proposed_plan"
+		? value
+		: undefined;
+}
+
+function fixedThinkingLevel(value: unknown): PlanModeFixedThinkingLevel | undefined {
+	return typeof value === "string" &&
+		value !== "inherit" &&
+		PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
+		? (value as PlanModeFixedThinkingLevel)
+		: undefined;
+}
+
+function stringArray(value: unknown) {
+	return Array.isArray(value) && value.every((item): item is string => typeof item === "string")
+		? Array.from(new Set(value))
+		: undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}