@hank-warren/pi-plan-mode 0.1.0 → 1.0.0

package/src/plan-mode.ts

@@ -1,14 +1,8 @@
-import { randomUUID } from "node:crypto";
 import type {
 	ExtensionAPI,
 	ExtensionCommandContext,
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import {
-	autoPermissionsIsLoaded,
-	shouldDelegateBashToAutoPermissions,
-	snapshotAutoPermissionsTrustedGroups,
-} from "./auto-permissions-delegation.js";
 import { completePlanArguments } from "./command.js";
 import {
 	normalizePlanModeCompletion,
@@ -26,11 +20,7 @@ import {
 	formatImplementationHandoff,
 	startFreshImplementationFromState,
 } from "./fresh-implementation.js";
-import {
-	createImplementationRetentionCoordinator,
-	implementationRetentionPreview,
-} from "./implementation-retention.js";
-import { invalidPlanMessage, latestAssistantText, parseProposedPlan } from "./message-transform.js";
+import { deletePlanFile, planFilePathForSession, readPlanFile, writePlanFile } from "./plan-file.js";
 import { createPlanActionController } from "./plan-action-controller.js";
 import { createPlanExportController } from "./plan-export-controller.js";
 import {
@@ -39,7 +29,7 @@ import {
 	showStoredPlan,
 	updatePlanModeUi,
 } from "./presentation.js";
-import { buildPlanModePrompt } from "./prompt.js";
+import { buildActivePlanPointer, buildPlanModePrompt } from "./prompt.js";
 import {
 	answerPlanModeQuestions,
 	normalizePlanModeQuestionParams,
@@ -47,43 +37,23 @@ import {
 	PLAN_MODE_QUESTION_TOOL_NAME,
 	planModeQuestionCancelled,
 } from "./question-tool.js";
-import { withoutRequiredPlanModeTools, withRequiredPlanModeTools } from "./required-tools.js";
-import {
-	preflightSavedPlanImplementation,
-	savedPlanBlocksNewWorkflow,
-} from "./saved-plan-preflight.js";
 import {
 	awaitPlanModeSettingsWrites,
-	configuredBashPolicy,
-	configuredImplementationPlanRetention,
 	configuredThinkingLevel,
 	type PlanModeSettings,
 	readPlanModeSettings,
 } from "./settings.js";
-import { type PlanCompletionSource, type PlanModeState, restorePlanModeState } from "./state.js";
-import {
-	canSelectToolInPlanMode,
-	classifyPlanModeTool,
-	findBlockedCommandSegment,
-	readCommand,
-} from "./tool-policy.js";
-import {
-	compareTools,
-	filterAvailableSelectedToolNames,
-	snapshotPlanModeSelectedNames,
-	snapshotPlanModeToolNames,
-	toolPolicyLabel,
-} from "./tool-selection.js";
+import { type PlanModeState, restorePlanModeState } from "./state.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
-const PROPOSED_PLAN_MESSAGE_TYPE = "proposed-plan";
-const BLOCKED_BUILTIN_TOOLS = new Set(["edit", "write"]);
-const DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
-interface ReadyPresentationIntent {
-	nonce: number;
-	plan: string;
-	source: PlanCompletionSource;
-}
+/**
+ * Plan mode's entire enforcement surface. Everything else — bash, subagents,
+ * MCP, and other extension tools — is left to the session's normal permission
+ * layer (for example @hank-warren/pi-auto-permissions), so Plan mode never
+ * mutates the active tool set and never fights other extensions for it.
+ */
+const BLOCKED_TOOLS = new Set(["edit", "write", "update_plan"]);
+
 type InteractiveUi = typeof import("./interactive-ui.js");
 
 interface PlanModeDependencies {
@@ -91,6 +61,7 @@ interface PlanModeDependencies {
 	settingsPath?: string;
 	loadInteractiveUi?(): Promise<InteractiveUi>;
 }
+
 export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDependencies = {}) {
 	let interactiveUiPromise: Promise<InteractiveUi> | undefined;
 	const loadInteractiveUi = () => {
@@ -105,49 +76,44 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	};
 	let state: PlanModeState = { enabled: false, awaitingAction: false };
 	let settings: PlanModeSettings = { thinkingLevel: "inherit" };
-	let autoPermissionsTrustedGroups = new Set<string>();
-	let previousTools: string[] | undefined;
-	let readyPresentationIntent: ReadyPresentationIntent | undefined;
+	let sessionPlanPath: string | undefined;
+	let readyPresentationNonce = 0;
+	let pendingReadyNonce: number | undefined;
 	let latestCommandContext: ExtensionCommandContext | undefined;
-	let nextReadyPresentationNonce = 0;
 	let menuGeneration = 0;
 	let workflowGeneration = 0;
 	let refreshStateBeforeFirstAgentStart = false;
 	let menuController = new AbortController();
-	const implementationRetention = createImplementationRetentionCoordinator();
 	const persistState = () => pi.appendEntry<PlanModeState>(STATE_ENTRY_TYPE, state);
 	const planExports = createPlanExportController({
 		getState: () => state,
 		getSettings: () => settings,
-		finishReady: (ctx) => exitPlanMode(ctx),
+		finishReady: (ctx) => {
+			void exitPlanMode(ctx, { keepPlanFile: true });
+		},
 	});
 	const planActions = createPlanActionController({
 		loadInteractiveUi,
 		getState: () => state,
 		captureLifecycle: captureMenuLifecycle,
 		statusText: planStatusText,
-		implementationOutcome,
+		planPathLine: () => (state.planPath ? `Plan file: ${state.planPath}` : undefined),
 		getExportDestination: (ctx) => planExports.getDestination(ctx),
 		show: (ctx) => showStoredPlan(pi, ctx, state),
 		finalize: requestFinalPlan,
 		implementHere: startImplementation,
 		implementFresh: startFreshImplementation,
 		exportPlan: (ctx, path, signal, isCurrent) => planExports.export(path, ctx, signal, isCurrent),
-		settings: showSettings,
-		save: savePlanForLater,
 		stay: updateUi,
 		exitReady: (ctx) => {
-			exitPlanMode(ctx);
-			ctx.ui.notify("Plan mode disabled. Proposed plan discarded.", "info");
-		},
-		clearSaved: (ctx) => {
-			exitPlanMode(ctx);
-			ctx.ui.notify("Saved plan cleared.", "info");
+			void exitPlanMode(ctx).then(() => {
+				ctx.ui.notify("Plan mode disabled. Proposed plan discarded.", "info");
+			});
 		},
 	});
 
 	pi.registerFlag("plan", {
-		description: "Start in Codex-like Plan mode",
+		description: "Start in Plan mode",
 		type: "boolean",
 		default: false,
 	});
@@ -212,21 +178,19 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			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);
+			const planPath = await acceptCompletedPlan(parsed.plan, ctx);
+			return planModeCompleted(parsed.plan, planPath);
 		},
 	});
 
 	pi.registerCommand("plan", {
-		description: "Enter or manage Codex-like Plan mode",
+		description: "Enter or manage Plan mode",
 		getArgumentCompletions: completePlanArguments,
 		handler: async (args, ctx) => {
 			latestCommandContext = ctx;
 			const prompt = args.trim();
 			const command = prompt.toLowerCase();
 			if (command === "start") {
-				if (savedPlanBlocksNewWorkflow(ctx, state.savedPlan !== undefined && !state.enabled))
-					return;
 				if (state.enabled) {
 					ctx.ui.notify("Plan mode is already active.", "info");
 					return;
@@ -236,7 +200,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 				return;
 			}
 			if (command === "show") {
-				showStoredPlan(pi, ctx, state);
+				await showStoredPlan(pi, ctx, state);
 				return;
 			}
 			if (command === "finalize") {
@@ -244,17 +208,13 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 				return;
 			}
 			if (command === "implement") {
-				if (!(state.enabled && state.latestPlan?.trim()) && !state.savedPlan?.plan.trim()) {
+				if (!(await currentPlan())) {
 					ctx.ui.notify("No completed plan is available to implement.", "warning");
 					return;
 				}
 				await startImplementation(ctx);
 				return;
 			}
-			if (command === "save") {
-				savePlanForLater(ctx);
-				return;
-			}
 			const exportMatch = /^export(?:\s+([\s\S]+))?$/iu.exec(prompt);
 			if (exportMatch) {
 				const lifecycle = captureMenuLifecycle();
@@ -262,36 +222,19 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 				return;
 			}
 			if (command === "exit" || command === "off") {
-				const notification = state.activeImplementation
-					? "Active implementation plan cleared."
-					: state.savedPlan
-						? "Saved plan cleared."
-						: state.latestPlan
-							? "Plan mode disabled. Proposed plan discarded."
-							: "Plan mode disabled.";
-				exitPlanMode(ctx);
+				const hadPlan = state.planPath !== undefined;
+				const notification = state.enabled
+					? hadPlan
+						? "Plan mode disabled. Proposed plan discarded."
+						: "Plan mode disabled."
+					: hadPlan
+						? "Active implementation plan cleared."
+						: "Plan mode disabled.";
+				await exitPlanMode(ctx);
 				ctx.ui.notify(notification, "info");
 				return;
 			}
-			if (command === "tools") {
-				if (savedPlanBlocksNewWorkflow(ctx, state.savedPlan !== undefined && !state.enabled))
-					return;
-				if (state.enabled) {
-					const message =
-						"Plan-mode tools are locked while Planning is active. Exit Plan mode and choose tools before starting again.";
-					if (!ctx.hasUI) throw new Error(message);
-					ctx.ui.notify(message, "warning");
-					return;
-				}
-				if (!ctx.hasUI) {
-					throw new Error("/plan tools requires TUI or RPC mode and is unavailable here.");
-				}
-				await showLaunchMenu(ctx, "tools");
-				return;
-			}
 			if (prompt) {
-				if (savedPlanBlocksNewWorkflow(ctx, state.savedPlan !== undefined && !state.enabled))
-					return;
 				enterPlanModeWithPrompt(prompt, ctx);
 				return;
 			}
@@ -300,15 +243,11 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 					"The interactive /plan menu is unavailable in print and JSON modes. Use /plan start or /plan <prompt>.",
 				);
 			}
+			if (!state.enabled && state.planPath) {
+				await showActivePlanMenu(ctx);
+				return;
+			}
 			if (!state.enabled) {
-				if (state.activeImplementation && ctx.hasUI) {
-					await showActivePlanMenu(ctx);
-					return;
-				}
-				if (state.savedPlan) {
-					await planActions.showSaved(ctx);
-					return;
-				}
 				await showLaunchMenu(ctx);
 				return;
 			}
@@ -321,16 +260,11 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		refreshStateBeforeFirstAgentStart = event.reason === "new";
 		menuController.abort(new DOMException("Plan-mode session replaced", "AbortError"));
 		menuController = new AbortController();
-		readyPresentationIntent = undefined;
+		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
-		implementationRetention.reset();
 		settings = { thinkingLevel: "inherit" };
-		autoPermissionsTrustedGroups = snapshotAutoPermissionsTrustedGroups(
-			ctx.cwd,
-			ctx.isProjectTrusted(),
-		);
+		sessionPlanPath = resolveSessionPlanPath(ctx);
 		restoreState(ctx);
-		implementationRetention.restore(state.activeImplementation);
 		const loadedSettings = await (dependencies.readSettings?.() ?? readPlanModeSettings());
 		if (generation !== menuGeneration || menuController.signal.aborted) return;
 		if (loadedSettings.kind === "loaded") settings = loadedSettings.settings;
@@ -338,33 +272,11 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify(`pi-plan-mode settings ignored: ${loadedSettings.reason}`, "warning");
 		}
 		if (loadedSettings.notice) ctx.ui.notify(loadedSettings.notice, "warning");
-		if (
-			configuredBashPolicy(settings) === "auto-permissions" &&
-			!autoPermissionsIsLoaded(safeGetAllTools())
-		) {
-			ctx.ui.notify(
-				"Plan mode bash policy is 'auto-permissions', but the Auto Permissions extension is not loaded; guarded commands stay blocked by Plan mode.",
-				"warning",
-			);
-		}
 		const persistFlagActivation = pi.getFlag("plan") === true && !state.enabled;
 		if (persistFlagActivation) {
-			state = state.savedPlan
-				? {
-						...state,
-						enabled: true,
-						latestPlan: state.savedPlan.plan,
-						latestPlanSource: state.savedPlan.source,
-						awaitingAction: true,
-						savedPlan: undefined,
-						activeImplementation: undefined,
-					}
-				: { ...state, enabled: true, activeImplementation: undefined };
+			state = { ...state, enabled: true, awaitingAction: state.planPath !== undefined };
 		}
-		if (state.enabled) {
-			activatePlanModeTools();
-			applyPlanThinkingLevel();
-		} else deactivatePlanModeQuestionTool();
+		if (state.enabled) applyPlanThinkingLevel();
 		if (persistFlagActivation) persistState();
 		updateUi(ctx);
 	});
@@ -385,144 +297,68 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	pi.on("session_shutdown", async (_event, ctx) => {
 		menuGeneration += 1;
 		menuController.abort(new DOMException("Plan-mode session shut down", "AbortError"));
-		readyPresentationIntent = undefined;
+		pendingReadyNonce = undefined;
 		latestCommandContext = undefined;
 		refreshStateBeforeFirstAgentStart = false;
-		autoPermissionsTrustedGroups = new Set<string>();
-		implementationRetention.reset();
 		await awaitPlanModeSettingsWrites(dependencies.settingsPath);
 		captureManualThinkingLevel();
 		persistState();
-		if (state.enabled) {
-			restoreTools();
-			restoreThinkingLevel();
-		}
+		if (state.enabled) restoreThinkingLevel();
 		clearUi(ctx);
 	});
 
+	/**
+	 * The complete enforcement surface: three static built-in names. Plan mode
+	 * does not classify, inspect, or filter any other tool.
+	 */
 	pi.on("tool_call", async (event) => {
 		if (!state.enabled) return;
-		if (event.toolName === "update_plan") {
-			return {
-				block: true,
-				reason:
-					"Plan mode blocks update_plan because it tracks execution progress rather than conversational planning.",
-			};
-		}
-		const calledTool = toolByName(event.toolName);
-		if (calledTool && classifyPlanModeTool(calledTool) === "blocked") {
-			return {
-				block: true,
-				reason: `Plan mode blocks built-in tool '${event.toolName}' because its policy class is blocked.`,
-			};
-		}
-		if (!calledTool && BLOCKED_BUILTIN_TOOLS.has(event.toolName)) {
-			return {
-				block: true,
-				reason: `Plan mode blocks built-in tool '${event.toolName}' because its metadata is unavailable.`,
-			};
-		}
-		// Built-in-compatible overrides retain the canonical name but replace its source metadata.
-		if (event.toolName !== "bash") return;
-
-		const command = readCommand(event.input);
-		const blocked = findBlockedCommandSegment(command, settings.safeSubcommands);
-		if (blocked !== undefined) {
-			if (
-				configuredBashPolicy(settings) === "auto-permissions" &&
-				shouldDelegateBashToAutoPermissions(command, {
-					tools: safeGetAllTools(),
-					trustedGroups: autoPermissionsTrustedGroups,
-				})
-			) {
-				return;
-			}
-			return {
-				block: true,
-				reason: `Plan mode blocks bash commands outside its reviewed inspection policy or containing explicitly unsafe arguments.\nBlocked command: ${blocked}`,
-			};
-		}
-	});
-
-	pi.on("context", async (event, ctx) => {
-		const result = implementationRetention.transformContext(event.messages, state);
-		if (result.clearActiveImplementationId) {
-			clearActiveImplementation(result.clearActiveImplementationId, ctx);
-		}
-		return { messages: result.messages as typeof event.messages };
+		if (!BLOCKED_TOOLS.has(event.toolName)) return;
+		return {
+			block: true,
+			reason:
+				event.toolName === "update_plan"
+					? "Plan mode blocks update_plan because it tracks execution progress rather than conversational planning."
+					: `Plan mode blocks '${event.toolName}' because planning must not mutate files. Finish the plan with plan_mode_complete, then implement.`,
+		};
 	});
 
 	pi.on("before_agent_start", (event, ctx) => {
 		if (refreshStateBeforeFirstAgentStart) {
 			refreshStateBeforeFirstAgentStart = false;
 			restoreState(ctx);
-			implementationRetention.reset();
-			implementationRetention.restore(state.activeImplementation);
-			if (state.enabled) {
-				activatePlanModeTools();
-				applyPlanThinkingLevel();
-			} else deactivatePlanModeQuestionTool();
+			if (state.enabled) applyPlanThinkingLevel();
 			updateUi(ctx);
 		}
-		if (!state.enabled) return;
-		if (state.latestPlan || state.awaitingAction) {
-			readyPresentationIntent = undefined;
-			state = {
-				...state,
-				latestPlan: undefined,
-				latestPlanSource: undefined,
-				awaitingAction: false,
-			};
+		if (state.enabled && state.awaitingAction) {
+			// A new turn supersedes the previous ready plan: revision feedback
+			// re-opens planning until another plan_mode_complete arrives.
+			pendingReadyNonce = undefined;
+			state = { ...state, awaitingAction: false };
 			persistState();
 			updateUi(ctx);
 		}
-		applyPlanModeTools();
-		return {
-			systemPrompt: `${event.systemPrompt}\n\n${buildPlanModePrompt({ bashPolicy: configuredBashPolicy(settings) })}`,
-		};
-	});
-
-	pi.on("agent_end", async (event, ctx) => {
-		if (!state.enabled) return;
-
-		const text = latestAssistantText(event.messages);
-		const parsedPlan = parseProposedPlan(text);
-		if (parsedPlan.kind !== "valid") {
-			if (parsedPlan.kind !== "absent") {
-				ctx.ui.notify(invalidPlanMessage(parsedPlan.kind), "warning");
-			}
-			persistState();
-			updateUi(ctx);
-			return;
+		if (state.enabled) {
+			return { systemPrompt: `${event.systemPrompt}\n\n${buildPlanModePrompt()}` };
+		}
+		// Pointer, not payload: an active plan costs one line of context no matter
+		// how large the plan is, and survives compaction for free.
+		if (state.planPath) {
+			return {
+				systemPrompt: `${event.systemPrompt}\n\n${buildActivePlanPointer(state.planPath)}`,
+			};
 		}
-		acceptCompletedPlan(parsedPlan.plan, "legacy_proposed_plan", ctx);
 	});
 
 	onAgentSettled(pi, async (_event, ctx) => {
-		const settledImplementationId = implementationRetention.implementationSettled(
-			state.activeImplementation,
-		);
-		if (settledImplementationId) clearActiveImplementation(settledImplementationId, ctx);
-
-		const intent = readyPresentationIntent;
-		if (!intent || !readyPresentationIsCurrent(intent)) return;
+		const nonce = pendingReadyNonce;
+		if (nonce === undefined || nonce !== readyPresentationNonce) return;
+		if (!state.enabled || !state.awaitingAction) return;
 		if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
 
-		readyPresentationIntent = undefined;
+		pendingReadyNonce = 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 planActions.showReady(latestCommandContext ?? ctx);
-			}
+			if (ctx.hasUI) await planActions.showReady(latestCommandContext ?? ctx);
 		} catch (error: unknown) {
 			if (!isStaleExtensionContextError(error)) throw error;
 		}
@@ -530,15 +366,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 
 	function enterPlanMode(ctx: ExtensionContext) {
 		workflowGeneration += 1;
-		if (!state.enabled) previousTools = withoutRequiredPlanModeTools(safeGetActiveTools());
-		state = {
-			...state,
-			enabled: true,
-			awaitingAction: false,
-			savedPlan: undefined,
-			activeImplementation: undefined,
-		};
-		activatePlanModeTools();
+		state = { ...state, enabled: true, awaitingAction: false };
 		applyPlanThinkingLevel();
 		persistState();
 		updateUi(ctx);
@@ -552,36 +380,31 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 			ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 		}
 		if (sendPlanModeUserMessage(prompt, ctx)) return;
-		if (!previousState.enabled) {
-			restoreTools();
-			restoreThinkingLevel();
-		}
+		if (!wasEnabled) restoreThinkingLevel();
 		state = previousState;
 		persistState();
 		updateUi(ctx);
 	}
 
-	function exitPlanMode(ctx: ExtensionContext) {
+	async function exitPlanMode(ctx: ExtensionContext, options: { keepPlanFile?: boolean } = {}) {
 		workflowGeneration += 1;
 		const wasEnabled = state.enabled;
-		readyPresentationIntent = undefined;
+		const planPath = state.planPath;
+		pendingReadyNonce = undefined;
 		state = {
 			...state,
 			enabled: false,
-			latestPlan: undefined,
-			latestPlanSource: undefined,
+			planPath: undefined,
 			awaitingAction: false,
-			savedPlan: undefined,
-			activeImplementation: undefined,
 			manualThinkingLevel: undefined,
 		};
 		if (wasEnabled) {
-			restoreTools();
 			restoreThinkingLevel();
 			state = { ...state, manualThinkingLevel: undefined };
 		}
 		persistState();
 		updateUi(ctx);
+		if (planPath && !options.keepPlanFile) await deletePlanFile(planPath);
 	}
 
 	function sendPlanModeUserMessage(message: string, ctx: ExtensionContext) {
@@ -596,48 +419,29 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		}
 	}
 
-	function acceptCompletedPlan(plan: string, source: PlanCompletionSource, ctx: ExtensionContext) {
-		const normalized = normalizePlanModeCompletion({ plan });
-		if (!normalized.ok) {
-			ctx.ui.notify(`Proposed plan is not ready: ${normalized.error}.`, "warning");
-			persistState();
-			updateUi(ctx);
-			return;
-		}
-		if (
-			state.enabled &&
-			state.awaitingAction &&
-			state.latestPlan === normalized.plan &&
-			state.latestPlanSource === source
-		) {
-			return;
+	/**
+	 * Writes the durable plan file and marks the plan ready. A write failure
+	 * keeps Plan mode active rather than silently losing the plan.
+	 */
+	async function acceptCompletedPlan(plan: string, ctx: ExtensionContext) {
+		const planPath = sessionPlanPath ?? resolveSessionPlanPath(ctx);
+		sessionPlanPath = planPath;
+		try {
+			await writePlanFile(planPath, plan);
+		} catch (error: unknown) {
+			const detail = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Unable to save the plan to ${planPath}: ${detail}`, "error");
+			return undefined;
 		}
-		state = {
-			...state,
-			latestPlan: normalized.plan,
-			latestPlanSource: source,
-			awaitingAction: true,
-		};
-		readyPresentationIntent = {
-			nonce: ++nextReadyPresentationNonce,
-			plan: normalized.plan,
-			source,
-		};
+		state = { ...state, planPath, awaitingAction: true };
+		pendingReadyNonce = ++readyPresentationNonce;
 		persistState();
 		updateUi(ctx);
+		return planPath;
 	}
 
-	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;
+	async function currentPlan() {
+		return state.planPath ? await readPlanFile(state.planPath) : undefined;
 	}
 
 	function requestFinalPlan(ctx: ExtensionContext) {
@@ -651,157 +455,61 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		);
 	}
 
-	function savePlanForLater(ctx: ExtensionContext) {
-		const plan = state.enabled ? state.latestPlan?.trim() : undefined;
-		if (!plan) {
-			const message = "No completed plan is available to save.";
-			if (!ctx.hasUI) throw new Error(message);
-			ctx.ui.notify(message, "warning");
-			return;
-		}
-		const source = state.latestPlanSource ?? "legacy_proposed_plan";
-
-		workflowGeneration += 1;
-		readyPresentationIntent = undefined;
-		state = {
-			...state,
-			enabled: false,
-			latestPlan: undefined,
-			latestPlanSource: undefined,
-			awaitingAction: false,
-			savedPlan: { plan, source },
-			activeImplementation: undefined,
-			manualThinkingLevel: undefined,
-		};
-		restoreTools();
-		restoreThinkingLevel();
-		state = { ...state, manualThinkingLevel: undefined };
-		persistState();
-		updateUi(ctx);
-		ctx.ui.notify("Plan saved for later. Plan mode disabled.", "info");
-	}
-
 	async function startFreshImplementation(ctx: ExtensionContext, menuIsCurrent: () => boolean) {
 		await startFreshImplementationFromState(ctx, {
 			getState: () => state,
 			menuIsCurrent,
-			retention: configuredImplementationPlanRetention(settings),
 			stateEntryType: STATE_ENTRY_TYPE,
 		});
 	}
 
 	async function startImplementation(ctx: ExtensionContext) {
-		const savedPlan = state.enabled ? undefined : state.savedPlan;
-		if (savedPlan) {
-			const sessionGeneration = menuGeneration;
-			const planWorkflowGeneration = workflowGeneration;
-			const isCurrent = () =>
-				sessionGeneration === menuGeneration &&
-				planWorkflowGeneration === workflowGeneration &&
-				!menuController.signal.aborted &&
-				!state.enabled &&
-				state.savedPlan === savedPlan;
-			if (!(await preflightSavedPlanImplementation(ctx, isCurrent))) return;
-		}
-		const plan = (state.enabled ? state.latestPlan : savedPlan?.plan)?.trim();
-		const source =
-			(state.enabled ? state.latestPlanSource : savedPlan?.source) ?? "legacy_proposed_plan";
-		if (!plan) {
-			ctx.ui.notify("Plan mode disabled. No proposed plan is available to implement.", "warning");
+		const planPath = state.planPath;
+		const plan = await currentPlan();
+		if (!planPath || !plan) {
+			ctx.ui.notify("No completed plan is available to implement.", "warning");
 			return;
 		}
 
 		workflowGeneration += 1;
 		const previousState = state;
 		const wasEnabled = state.enabled;
-		readyPresentationIntent = undefined;
+		pendingReadyNonce = undefined;
 		state = {
 			...state,
 			enabled: false,
-			latestPlan: undefined,
-			latestPlanSource: undefined,
 			awaitingAction: false,
-			savedPlan: undefined,
-			activeImplementation: {
-				id: randomUUID(),
-				plan,
-				source,
-				startedAt: Date.now(),
-				retention: configuredImplementationPlanRetention(settings),
-			},
+			planPath,
 			manualThinkingLevel: undefined,
 		};
 		if (wasEnabled) {
-			restoreTools();
 			restoreThinkingLevel();
 			state = { ...state, manualThinkingLevel: undefined };
 		}
 		persistState();
 		updateUi(ctx);
 
-		const sent = sendPlanModeUserMessage(formatImplementationHandoff(plan), ctx);
-		if (!sent) {
-			if (savedPlan) {
-				state = previousState;
-			} else {
-				enterPlanMode(ctx);
-				state = previousState;
-				applyPlanThinkingLevel();
-			}
+		if (!sendPlanModeUserMessage(formatImplementationHandoff(planPath), ctx)) {
+			state = previousState;
+			if (wasEnabled) applyPlanThinkingLevel();
 			persistState();
 			updateUi(ctx);
 		}
 	}
 
-	function clearActiveImplementation(id: string, ctx: ExtensionContext) {
-		if (state.activeImplementation?.id !== id) return false;
-		workflowGeneration += 1;
-		state = { ...state, activeImplementation: undefined };
-		persistState();
-		updateUi(ctx);
-		return true;
-	}
-
-	async function showLaunchMenu(ctx: ExtensionContext, initialScreen: "main" | "tools" = "main") {
+	async function showLaunchMenu(ctx: ExtensionContext) {
 		const lifecycle = captureMenuLifecycle();
 		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
 		const ui = await loadInteractiveUi();
 		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
-		const tools = selectableTools();
 		await ui.showPlanLaunchMenu(ctx, {
-			statusText: "Status: Off — normal tools are active.",
-			initialScreen,
-			getSelectedNames: () => snapshotPlanModeSelectedNames(tools, toolSelectionSnapshot()),
-			toolSummary: (selectedNames) =>
-				`When started: ${snapshotPlanModeToolNames(tools, selectedNames, toolSelectionSnapshot()).join(", ")}`,
-			tools: tools.map((tool) => {
-				const selectable = canSelectToolInPlanMode(tool);
-				const policy = toolPolicyLabel(tool);
-				const description = tool.description ?? "No description available";
-				return {
-					name: tool.name,
-					description: `${policy} · ${description}`,
-					searchText: [policy, description].join(" "),
-					disabled: !selectable,
-					disabledReason: selectable ? undefined : "Blocked by Plan-mode policy",
-				};
-			}),
+			statusText: "Status: Off.",
 			...lifecycle,
 			start: (signal) => {
 				if (signal.aborted || !lifecycle.isCurrent()) return;
 				enterPlanMode(ctx);
 				ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 			},
-			startWithTools: (names, signal) => {
-				if (signal.aborted || !lifecycle.isCurrent()) return;
-				state = {
-					...state,
-					selectedToolNames: filterAvailableSelectedToolNames(names, tools),
-					selectedToolKeys: undefined,
-				};
-				enterPlanMode(ctx);
-				ctx.ui.notify("Plan mode enabled with the selected tools.", "info");
-			},
 			settings: (signal) => showSettings(ctx, signal, lifecycle.isCurrent),
 		});
 	}
@@ -817,6 +525,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		if (!lifecycle.isCurrent() || lifecycle.signal.aborted) return;
 		await ui.showActiveImplementationMenu(ctx, {
 			statusText: planStatusText(),
+			...(state.planPath ? { planPathLine: `Plan file: ${state.planPath}` } : {}),
 			getExportDestination: () => planExports.getDestination(ctx),
 			signal: lifecycle.signal,
 			isCurrent: lifecycle.isCurrent,
@@ -828,8 +537,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 				ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 			},
 			clear: () => {
-				exitPlanMode(ctx);
-				ctx.ui.notify("Active implementation plan cleared.", "info");
+				void exitPlanMode(ctx).then(() => {
+					ctx.ui.notify("Active implementation plan cleared.", "info");
+				});
 			},
 		});
 	}
@@ -843,7 +553,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		const ui = await loadInteractiveUi();
 		if (!isCurrent() || signal.aborted) return false;
 		const result = await ui.showPlanModeSettings(ctx, {
-			tools: selectableTools(),
 			signal,
 			isCurrent,
 			settingsPath: dependencies.settingsPath,
@@ -870,65 +579,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		};
 	}
 
-	function activatePlanModeTools() {
-		previousTools ??= withoutRequiredPlanModeTools(safeGetActiveTools());
-		applyPlanModeTools();
-	}
-
-	function applyPlanModeTools() {
-		pi.setActiveTools(planModeToolNames());
-	}
-
-	function planModeToolNames() {
-		const tools = selectableTools();
-		if (
-			tools.length === 0 &&
-			state.selectedToolNames === undefined &&
-			state.selectedToolKeys === undefined &&
-			settings.defaultPlanTools === undefined
-		) {
-			return ["read", "bash", PLAN_MODE_QUESTION_TOOL_NAME, PLAN_MODE_COMPLETE_TOOL_NAME];
-		}
-
-		const selectedNames = snapshotPlanModeSelectedNames(tools, toolSelectionSnapshot());
-		return withRequiredPlanModeTools(
-			tools
-				.filter((tool) => selectedNames.has(tool.name) && canSelectToolInPlanMode(tool))
-				.map((tool) => tool.name),
-		);
-	}
-
-	function toolSelectionSnapshot() {
-		return {
-			selectedToolNames: state.selectedToolNames,
-			selectedToolKeys: state.selectedToolKeys,
-			defaultPlanTools: settings.defaultPlanTools,
-		};
-	}
-
-	function selectableTools() {
-		return safeGetAllTools()
-			.filter(
-				(tool) =>
-					tool.name !== PLAN_MODE_QUESTION_TOOL_NAME && tool.name !== PLAN_MODE_COMPLETE_TOOL_NAME,
-			)
-			.sort(compareTools);
-	}
-
-	function safeGetAllTools() {
-		try {
-			return pi.getAllTools();
-		} catch {
-			return [];
-		}
-	}
-
-	function restoreTools() {
-		const restoredTools = previousTools ?? DEFAULT_TOOLS;
-		pi.setActiveTools(withoutRequiredPlanModeTools(restoredTools));
-		previousTools = undefined;
-	}
-
 	function applyPlanThinkingLevel() {
 		if (state.manualThinkingLevel) {
 			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
@@ -976,19 +626,11 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 		state = { ...state, appliedThinkingLevel: undefined, previousThinkingLevel: undefined };
 	}
 
-	function deactivatePlanModeQuestionTool() {
-		const activeTools = safeGetActiveTools();
-		const filteredTools = withoutRequiredPlanModeTools(activeTools);
-		if (filteredTools.length !== activeTools.length) {
-			pi.setActiveTools(filteredTools);
-		}
-	}
-
-	function safeGetActiveTools() {
+	function resolveSessionPlanPath(ctx: ExtensionContext) {
 		try {
-			return pi.getActiveTools();
+			return planFilePathForSession(ctx.sessionManager.getSessionId());
 		} catch {
-			return DEFAULT_TOOLS;
+			return planFilePathForSession(undefined);
 		}
 	}
 
@@ -997,7 +639,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	}
 
 	function updateUi(ctx: ExtensionContext) {
-		updatePlanModeUi(ctx, state, formatToolSummary);
+		updatePlanModeUi(ctx, state);
 	}
 
 	function clearUi(ctx: ExtensionContext) {
@@ -1005,33 +647,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
 	}
 
 	function planStatusText() {
-		return formatPlanModeStatusText(state, formatToolSummary);
-	}
-
-	function implementationOutcome() {
-		return implementationRetentionPreview(configuredImplementationPlanRetention(settings));
-	}
-
-	function formatToolSummary() {
-		const names = planModeToolNames();
-		return `Tools: ${names.length > 0 ? names.join(", ") : "none"}`;
-	}
-
-	function toolByName(toolName: string) {
-		return safeGetAllTools().find((candidate) => candidate.name === toolName);
+		return formatPlanModeStatusText(state);
 	}
 }
 
 export { completePlanArguments } from "./command.js";
-export {
-	extractProposedPlan,
-	latestAssistantText,
-	parseProposedPlan,
-	stripProposedPlanBlocks,
-	stripProposedPlanBlocksFromMessage,
-} from "./message-transform.js";
-export { buildPlanModePrompt } from "./prompt.js";
+export { planFilePathForSession, plansDirectory } from "./plan-file.js";
+export { buildActivePlanPointer, buildPlanModePrompt } from "./prompt.js";
 export { normalizePlanModeQuestionParams } from "./question-tool.js";
-export { withoutPlanModeQuestionTool, withRequiredPlanModeTools } from "./required-tools.js";
 export { normalizePlanModeSettings, readPlanModeSettings } from "./settings.js";
-export { canSelectToolInPlanMode, classifyPlanModeTool, isSafeCommand } from "./tool-policy.js";