@narumitw/pi-plan-mode 0.13.0 → 0.14.0

package/src/plan-mode.ts

@@ -1,18 +1,48 @@
-import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolInfo,
+} from "@earendil-works/pi-coding-agent";
+import {
+	extractProposedPlan,
+	latestAssistantText,
+	parseProposedPlan,
+	messageContainsInactivePlanModeArtifact,
+	messageContainsLegacyPlanModeContextArtifact,
+	stripProposedPlanBlocksFromMessage,
+} from "./message-transform.js";
+import { buildPlanModePrompt } from "./prompt.js";
+import {
+	askPlanModeQuestions,
+	normalizePlanModeQuestionParams,
+	PLAN_MODE_QUESTION_PARAMS,
+	PLAN_MODE_QUESTION_TOOL_NAME,
+	planModeQuestionAnswered,
+	planModeQuestionCancelled,
+} from "./question-tool.js";
+import {
+	canSelectToolInPlanMode,
+	classifyPlanModeTool,
+	isBuiltinTool,
+	isSafeCommand,
+	readCommand,
+	SAFE_BUILTIN_PLAN_TOOLS,
+} from "./tool-policy.js";
+import {
+	configuredThinkingLevel,
+	PLAN_MODE_THINKING_LEVELS,
+	readPlanModeSettings,
+	type PlanModeFixedThinkingLevel,
+	type PlanModeSettings,
+} from "./settings.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 const STATUS_KEY = "plan-mode";
 const PLAN_WIDGET_KEY = "plan-mode-plan";
-const PLAN_CONTEXT_MESSAGE_TYPE = "plan-mode-context";
 const PROPOSED_PLAN_MESSAGE_TYPE = "proposed-plan";
-const PLAN_MODE_QUESTION_TOOL_NAME = "plan_mode_question";
-const PLAN_CONTEXT_MARKER = "[CODEX-LIKE PLAN MODE ACTIVE]";
-const SAFE_BUILTIN_PLAN_TOOLS = new Set(["read", "bash", "grep", "find", "ls"]);
 const BLOCKED_BUILTIN_TOOLS = new Set(["edit", "write"]);
 const DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
 const TOOL_SELECTOR_PAGE_SIZE = 10;
-const PROPOSED_PLAN_PATTERN = /<proposed_plan>\s*([\s\S]*?)\s*<\/proposed_plan>/i;
-const PROPOSED_PLAN_BLOCK_PATTERN = /<proposed_plan>\s*[\s\S]*?\s*<\/proposed_plan>/gi;
 
 interface CommandArgumentCompletion {
 	value: string;
@@ -26,6 +56,9 @@ interface PlanModeState {
 	awaitingAction: boolean;
 	selectedToolNames?: string[];
 	selectedToolKeys?: string[];
+	previousThinkingLevel?: PlanModeFixedThinkingLevel;
+	appliedThinkingLevel?: PlanModeFixedThinkingLevel;
+	manualThinkingLevel?: PlanModeFixedThinkingLevel;
 }
 
 type SessionEntry = {
@@ -45,146 +78,15 @@ type TextBlock = {
 	text?: string;
 };
 
-type PlanModeQuestionOption = {
-	label: string;
-	description?: string;
-};
-
-type PlanModeQuestion = {
-	id: string;
-	header: string;
-	question: string;
-	options: PlanModeQuestionOption[];
-};
-
-type PlanModeQuestionParams = {
-	questions: PlanModeQuestion[];
-};
-
-type PlanModeQuestionAnswer = {
-	id: string;
-	header: string;
-	question: string;
-	answer: string;
-	wasCustom: boolean;
-	optionIndex?: number;
-};
-
-type PlanModeQuestionReason = "cancelled" | "ui_unavailable" | "plan_mode_inactive" | "invalid_input";
-
-type PlanModeQuestionDetails = {
-	cancelled: boolean;
-	reason?: PlanModeQuestionReason;
-	questions: PlanModeQuestion[];
-	answers?: PlanModeQuestionAnswer[];
-};
-
 const PLAN_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 	{ 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" },
 ];
 
-const PLAN_MODE_QUESTION_PARAMS = {
-	type: "object",
-	additionalProperties: false,
-	required: ["questions"],
-	properties: {
-		questions: {
-			type: "array",
-			minItems: 1,
-			maxItems: 3,
-			description: "Questions to show the user. Prefer 1 and do not exceed 3.",
-			items: {
-				type: "object",
-				additionalProperties: false,
-				required: ["id", "header", "question", "options"],
-				properties: {
-					id: {
-						type: "string",
-						description: "Stable identifier for mapping answers (snake_case).",
-					},
-					header: {
-						type: "string",
-						description: "Short header label shown in the UI (12 or fewer chars).",
-					},
-					question: {
-						type: "string",
-						description: "Single-sentence prompt shown to the user.",
-					},
-					options: {
-						type: "array",
-						minItems: 2,
-						maxItems: 4,
-						description:
-							"Provide 2-4 mutually exclusive choices. Put the recommended option first when there is a clear default.",
-						items: {
-							type: "object",
-							additionalProperties: false,
-							required: ["label", "description"],
-							properties: {
-								label: {
-									type: "string",
-									description: "User-facing label (1-5 words).",
-								},
-								description: {
-									type: "string",
-									description: "One short sentence explaining impact/tradeoff if selected.",
-								},
-							},
-						},
-					},
-				},
-			},
-		},
-	},
-} as const;
-
-const MUTATING_BASH_PATTERNS = [
-	/\brm\b/i,
-	/\brmdir\b/i,
-	/\bmv\b/i,
-	/\bcp\b/i,
-	/\bmkdir\b/i,
-	/\btouch\b/i,
-	/\bchmod\b/i,
-	/\bchown\b/i,
-	/\bchgrp\b/i,
-	/\bln\b/i,
-	/\btee\b/i,
-	/\btruncate\b/i,
-	/\bdd\b/i,
-	/(^|[^<])>(?!>)/,
-	/>>/,
-	/\bnpm\s+(install|uninstall|update|ci|link|publish|version)\b/i,
-	/\byarn\s+(add|remove|install|publish|upgrade)\b/i,
-	/\bpnpm\s+(add|remove|install|publish|update)\b/i,
-	/\bbun\s+(add|remove|install|update|publish)\b/i,
-	/\bpip\s+(install|uninstall)\b/i,
-	/\buv\s+(add|remove|sync|lock|pip\s+install)\b/i,
-	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|switch|stash|cherry-pick|revert|tag|init|clone)\b/i,
-	/\bsudo\b/i,
-	/\bsu\b/i,
-	/\bkill\b/i,
-	/\bpkill\b/i,
-	/\bkillall\b/i,
-	/\breboot\b/i,
-	/\bshutdown\b/i,
-	/\bsystemctl\s+(start|stop|restart|enable|disable)\b/i,
-	/\bservice\s+\S+\s+(start|stop|restart)\b/i,
-	/\b(vim?|nano|emacs|code|subl)\b/i,
-];
-
-const SAFE_BASH_PATTERNS = [
-	/^\s*(cat|head|tail|less|more|grep|find|ls|pwd|echo|printf|wc|sort|uniq|diff|file|stat|du|df|tree|which|whereis|type|env|printenv|uname|whoami|id|date|uptime|ps|jq|awk|rg|fd|bat|eza)\b/i,
-	/^\s*sed\s+-n\b/i,
-	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get|ls-files|grep)\b/i,
-	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)\b/i,
-	/^\s*(node|python|python3|npm|tsc|biome|ruff|ty)\s+--version\b/i,
-];
-
 export default function planMode(pi: ExtensionAPI) {
 	let state: PlanModeState = { enabled: false, awaitingAction: false };
+	let settings: PlanModeSettings = { thinkingLevel: "inherit" };
 	let previousTools: string[] | undefined;
 
 	pi.registerFlag("plan", {
@@ -267,25 +169,65 @@ export default function planMode(pi: ExtensionAPI) {
 		},
 	});
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
+		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");
+		}
 		restoreState(ctx);
 		if (pi.getFlag("plan") === true) state.enabled = true;
-		if (state.enabled) activatePlanModeTools();
-		else deactivatePlanModeQuestionTool();
+		if (state.enabled) {
+			activatePlanModeTools();
+			applyPlanThinkingLevel();
+		} else deactivatePlanModeQuestionTool();
 		updateUi(ctx);
 	});
 
+	pi.on("thinking_level_select", (event) => {
+		if (!state.enabled || !state.appliedThinkingLevel) return;
+		if (event.level !== state.appliedThinkingLevel) {
+			state = {
+				...state,
+				manualThinkingLevel: event.level,
+				previousThinkingLevel: undefined,
+				appliedThinkingLevel: undefined,
+			};
+			persistState();
+		}
+	});
+
 	pi.on("session_shutdown", (_event, ctx) => {
+		captureManualThinkingLevel();
 		persistState();
+		if (state.enabled) {
+			restoreTools();
+			restoreThinkingLevel();
+		}
 		clearUi(ctx);
 	});
 
 	pi.on("tool_call", async (event) => {
 		if (!state.enabled) return;
-		if (isBlockedBuiltinToolName(event.toolName)) {
+		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 mutating tool '${event.toolName}'. Use /plan and choose implementation when the plan is ready.`,
+				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.`,
 			};
 		}
 		if (event.toolName !== "bash" || !isBuiltinToolName(event.toolName)) return;
@@ -328,12 +270,16 @@ export default function planMode(pi: ExtensionAPI) {
 		if (!state.enabled) return;
 
 		const text = latestAssistantText(event.messages);
-		const proposedPlan = extractProposedPlan(text);
-		if (!proposedPlan) {
+		const parsedPlan = parseProposedPlan(text);
+		if (parsedPlan.kind !== "valid") {
+			if (parsedPlan.kind !== "absent") {
+				ctx.ui.notify(invalidPlanMessage(parsedPlan.kind), "warning");
+			}
 			persistState();
 			updateUi(ctx);
 			return;
 		}
+		const proposedPlan = parsedPlan.plan;
 
 		state = { ...state, latestPlan: proposedPlan, awaitingAction: true };
 		persistState();
@@ -359,6 +305,7 @@ export default function planMode(pi: ExtensionAPI) {
 		if (!state.enabled) previousTools = withoutPlanModeQuestionTool(safeGetActiveTools());
 		state = { ...state, enabled: true, awaitingAction: false };
 		activatePlanModeTools();
+		applyPlanThinkingLevel();
 		persistState();
 		updateUi(ctx);
 	}
@@ -369,20 +316,37 @@ export default function planMode(pi: ExtensionAPI) {
 		if (!wasEnabled) {
 			ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 		}
-		sendPlanModeUserMessage(prompt, ctx);
+		if (!sendPlanModeUserMessage(prompt, ctx) && !wasEnabled) exitPlanMode(ctx);
 	}
 
 	function exitPlanMode(ctx: ExtensionContext) {
 		const wasEnabled = state.enabled;
-		state = { ...state, enabled: false, latestPlan: undefined, awaitingAction: false };
-		if (wasEnabled) restoreTools();
+		state = {
+			...state,
+			enabled: false,
+			latestPlan: undefined,
+			awaitingAction: false,
+			manualThinkingLevel: undefined,
+		};
+		if (wasEnabled) {
+			restoreTools();
+			restoreThinkingLevel();
+			state = { ...state, manualThinkingLevel: undefined };
+		}
 		persistState();
 		updateUi(ctx);
 	}
 
 	function sendPlanModeUserMessage(message: string, ctx: ExtensionContext) {
-		if (ctx.isIdle()) pi.sendUserMessage(message);
-		else pi.sendUserMessage(message, { deliverAs: "followUp" });
+		try {
+			if (ctx.isIdle()) pi.sendUserMessage(message);
+			else pi.sendUserMessage(message, { deliverAs: "followUp" });
+			return true;
+		} catch (error: unknown) {
+			const detail = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Unable to send Plan-mode message: ${detail}`, "error");
+			return false;
+		}
 	}
 
 	function scheduleAfterCurrentAgentRun(task: () => Promise<void> | void) {
@@ -403,10 +367,16 @@ export default function planMode(pi: ExtensionAPI) {
 			return;
 		}
 
-		sendPlanModeUserMessage(
+		const sent = sendPlanModeUserMessage(
 			`Plan mode is now disabled. Full tool access is restored. Implement this proposed plan now:\n\n${plan}`,
 			ctx,
 		);
+		if (!sent) {
+			enterPlanMode(ctx);
+			state = { ...state, latestPlan: plan, awaitingAction: true };
+			persistState();
+			updateUi(ctx);
+		}
 	}
 
 	async function showPlanMenu(ctx: ExtensionContext) {
@@ -596,11 +566,58 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 
 	function restoreTools() {
-		const restoredTools = previousTools && previousTools.length > 0 ? previousTools : DEFAULT_TOOLS;
+		const restoredTools = previousTools ?? DEFAULT_TOOLS;
 		pi.setActiveTools(withoutPlanModeQuestionTool(restoredTools));
 		previousTools = undefined;
 	}
 
+	function applyPlanThinkingLevel() {
+		if (state.manualThinkingLevel) {
+			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
+				pi.setThinkingLevel(state.manualThinkingLevel);
+			}
+			return;
+		}
+		const configured = configuredThinkingLevel(settings);
+		if (!configured) {
+			state = {
+				...state,
+				previousThinkingLevel: undefined,
+				appliedThinkingLevel: undefined,
+			};
+			return;
+		}
+		const current = pi.getThinkingLevel();
+		if (!state.appliedThinkingLevel) state.previousThinkingLevel = current;
+		if (current !== configured) pi.setThinkingLevel(configured);
+		state.appliedThinkingLevel = pi.getThinkingLevel();
+	}
+
+	function captureManualThinkingLevel() {
+		if (!state.appliedThinkingLevel) return;
+		const current = pi.getThinkingLevel();
+		if (current === state.appliedThinkingLevel) return;
+		state = {
+			...state,
+			manualThinkingLevel: current,
+			previousThinkingLevel: undefined,
+			appliedThinkingLevel: undefined,
+		};
+	}
+
+	function restoreThinkingLevel() {
+		captureManualThinkingLevel();
+		const { appliedThinkingLevel, previousThinkingLevel } = state;
+		if (
+			appliedThinkingLevel &&
+			previousThinkingLevel &&
+			pi.getThinkingLevel() === appliedThinkingLevel
+		) {
+			pi.setThinkingLevel(previousThinkingLevel);
+		}
+		state = { ...state, appliedThinkingLevel: undefined, previousThinkingLevel: undefined };
+	}
+
 	function deactivatePlanModeQuestionTool() {
 		const activeTools = safeGetActiveTools();
 		const filteredTools = withoutPlanModeQuestionTool(activeTools);
@@ -622,18 +639,29 @@ 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 (!entry?.data) return;
-		const enabled = entry.data.enabled ?? false;
+		if (!isRecord(entry?.data)) return;
+		const enabled = entry.data.enabled === true;
 		state = {
 			enabled,
-			latestPlan: enabled ? entry.data.latestPlan : undefined,
-			awaitingAction: enabled ? (entry.data.awaitingAction ?? false) : false,
-			selectedToolNames: entry.data.selectedToolNames,
-			selectedToolKeys: entry.data.selectedToolKeys,
+			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,
 		};
 	}
 
@@ -677,12 +705,6 @@ export default function planMode(pi: ExtensionAPI) {
 		return `Tools: ${names.length > 0 ? names.join(", ") : "none"}`;
 	}
 
-	function isBlockedBuiltinToolName(toolName: string) {
-		if (!BLOCKED_BUILTIN_TOOLS.has(toolName)) return false;
-		const tool = toolByName(toolName);
-		return tool ? isBuiltinTool(tool) : true;
-	}
-
 	function isBuiltinToolName(toolName: string) {
 		const tool = toolByName(toolName);
 		return tool ? isBuiltinTool(tool) : toolName === "bash";
@@ -693,10 +715,6 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 }
 
-function isBuiltinTool(tool: ToolInfo) {
-	return tool.sourceInfo.source === "builtin";
-}
-
 export function completePlanArguments(argumentPrefix: string): CommandArgumentCompletion[] | null {
 	const prefix = argumentPrefix.trimStart().toLowerCase();
 	if (prefix === "") return [...PLAN_COMMAND_COMPLETIONS];
@@ -706,11 +724,6 @@ export function completePlanArguments(argumentPrefix: string): CommandArgumentCo
 	return matches.length > 0 ? [...matches] : null;
 }
 
-export function canSelectToolInPlanMode(tool: ToolInfo) {
-	if (isBuiltinTool(tool)) return SAFE_BUILTIN_PLAN_TOOLS.has(tool.name);
-	return true;
-}
-
 function toolNameFromLegacyKey(key: string, tools: ToolInfo[]) {
 	const directName = tools.find((tool) => tool.name === key)?.name;
 	if (directName) return directName;
@@ -731,11 +744,11 @@ function formatToolChoice(tool: ToolInfo, selected: boolean, index: number) {
 }
 
 function toolPolicyLabel(tool: ToolInfo) {
-	if (isBuiltinTool(tool)) {
-		if (!SAFE_BUILTIN_PLAN_TOOLS.has(tool.name)) return "built-in blocked";
-		return tool.name === "bash" ? "built-in limited" : "built-in";
-	}
-	return `user risk: ${toolSourceLabel(tool)}`;
+	const policy = classifyPlanModeTool(tool);
+	if (policy === "read-only") return "built-in read-only";
+	if (policy === "limited") return "built-in limited";
+	if (policy === "blocked") return "built-in blocked";
+	return `user opt-in: ${toolSourceLabel(tool)}`;
 }
 
 function toolSourceLabel(tool: ToolInfo) {
@@ -748,307 +761,50 @@ function unique(values: string[]) {
 	return Array.from(new Set(values));
 }
 
-export function withRequiredPlanModeTools(toolNames: string[]) {
-	return unique([...withoutPlanModeQuestionTool(toolNames), PLAN_MODE_QUESTION_TOOL_NAME]);
-}
-
-export function withoutPlanModeQuestionTool(toolNames: string[]) {
-	return toolNames.filter((toolName) => toolName !== PLAN_MODE_QUESTION_TOOL_NAME);
-}
-
-type NormalizePlanModeQuestionParamsResult =
-	| { ok: true; questions: PlanModeQuestion[] }
-	| { ok: false; error: string };
-
-export function normalizePlanModeQuestionParams(input: unknown): NormalizePlanModeQuestionParamsResult {
-	if (!isRecord(input) || !Array.isArray(input.questions)) {
-		return { ok: false, error: "questions must be an array" };
-	}
-	if (input.questions.length < 1 || input.questions.length > 3) {
-		return { ok: false, error: "questions must contain 1-3 items" };
-	}
-
-	const questions: PlanModeQuestion[] = [];
-	for (const [questionIndex, rawQuestion] of input.questions.entries()) {
-		if (!isRecord(rawQuestion)) {
-			return { ok: false, error: `question ${questionIndex + 1} must be an object` };
-		}
-
-		const id = stringField(rawQuestion.id);
-		const header = stringField(rawQuestion.header);
-		const question = stringField(rawQuestion.question);
-		if (!id || !header || !question) {
-			return {
-				ok: false,
-				error: `question ${questionIndex + 1} requires non-empty id, header, and question`,
-			};
-		}
-
-		if (!Array.isArray(rawQuestion.options)) {
-			return { ok: false, error: `question ${questionIndex + 1} options must be an array` };
-		}
-		if (rawQuestion.options.length < 2 || rawQuestion.options.length > 4) {
-			return { ok: false, error: `question ${questionIndex + 1} options must contain 2-4 items` };
-		}
-
-		const options: PlanModeQuestionOption[] = [];
-		for (const [optionIndex, rawOption] of rawQuestion.options.entries()) {
-			if (!isRecord(rawOption)) {
-				return {
-					ok: false,
-					error: `question ${questionIndex + 1} option ${optionIndex + 1} must be an object`,
-				};
-			}
-
-			const label = stringField(rawOption.label);
-			if (!label) {
-				return {
-					ok: false,
-					error: `question ${questionIndex + 1} option ${optionIndex + 1} requires a label`,
-				};
-			}
-			const description = stringField(rawOption.description);
-			if (!description) {
-				return {
-					ok: false,
-					error: `question ${questionIndex + 1} option ${optionIndex + 1} requires a description`,
-				};
-			}
-			options.push({ label, description });
-		}
-
-		questions.push({ id, header, question, options });
-	}
-
-	return { ok: true, questions };
-}
-
-async function askPlanModeQuestions(
-	questions: PlanModeQuestion[],
-	ctx: ExtensionContext,
-): Promise<PlanModeQuestionAnswer[] | undefined> {
-	const answers: PlanModeQuestionAnswer[] = [];
-	for (const question of questions) {
-		const choices = question.options.map(formatPlanModeQuestionChoice);
-		const otherChoice = `${question.options.length + 1}. Other (free-form)`;
-		const choice = await ctx.ui.select(`${question.header}: ${question.question}`, [...choices, otherChoice]);
-		if (!choice) return undefined;
-
-		if (choice === otherChoice) {
-			const customAnswer = (await ctx.ui.editor(question.question, ""))?.trim();
-			if (!customAnswer) return undefined;
-			answers.push({
-				id: question.id,
-				header: question.header,
-				question: question.question,
-				answer: customAnswer,
-				wasCustom: true,
-			});
-			continue;
-		}
-
-		const optionIndex = choices.indexOf(choice);
-		const option = question.options[optionIndex];
-		if (!option) return undefined;
-		answers.push({
-			id: question.id,
-			header: question.header,
-			question: question.question,
-			answer: option.label,
-			wasCustom: false,
-			optionIndex: optionIndex + 1,
-		});
-	}
-	return answers;
-}
-
-function formatPlanModeQuestionChoice(option: PlanModeQuestionOption, index: number) {
-	return `${index + 1}. ${option.label}${option.description ? ` — ${option.description}` : ""}`;
-}
-
-function planModeQuestionAnswered(questions: PlanModeQuestion[], answers: PlanModeQuestionAnswer[]) {
-	return {
-		content: [{ type: "text" as const, text: formatPlanModeQuestionPayload({ cancelled: false, answers }) }],
-		details: { cancelled: false, questions, answers } satisfies PlanModeQuestionDetails,
-	};
-}
-
-function planModeQuestionCancelled(
-	questions: PlanModeQuestion[],
-	reason: PlanModeQuestionReason,
-	message: string,
-) {
-	return {
-		content: [{ type: "text" as const, text: formatPlanModeQuestionPayload({ cancelled: true, reason, message }) }],
-		details: { cancelled: true, reason, questions } satisfies PlanModeQuestionDetails,
-	};
-}
-
-function formatPlanModeQuestionPayload(payload: {
-	cancelled: boolean;
-	reason?: PlanModeQuestionReason;
-	message?: string;
-	answers?: PlanModeQuestionAnswer[];
-}) {
-	return JSON.stringify(payload, null, 2);
-}
-
 function isRecord(value: unknown): value is Record<string, unknown> {
-	return typeof value === "object" && value !== null;
-}
-
-function stringField(value: unknown) {
-	return typeof value === "string" ? value.trim() : undefined;
-}
-
-function buildPlanModePrompt() {
-	return `${PLAN_CONTEXT_MARKER}
-# Plan Mode (Conversational)
-
-You are in Plan Mode, a Codex-like collaboration mode for producing a decision-complete implementation plan. Chat your way to the plan before finalizing it. A final plan must leave no implementation decisions unresolved.
-
-## Mode rules
-
-- Stay in Plan Mode until a developer or extension explicitly exits it.
-- Treat requests to implement as requests to plan the implementation; do not edit files or carry out the plan.
-- Do not use update_plan/TODO tooling in Plan Mode; Plan Mode is conversational planning, not execution progress tracking.
-- Plan Mode manages built-in tool safety only. Non-built-in tools are disabled by default and may be enabled by the user at their own risk.
-- Do not perform mutating actions: no edit/write tools, no patching, no formatting that rewrites files, no dependency installation, no commits, no migrations.
-
-## Phase 1 — Ground in the environment
-
-- Explore first and ask second. Use non-mutating exploration to read files, search, inspect configuration, run read-only checks, and resolve discoverable facts.
-- Before asking the user any question, perform at least one targeted non-mutating exploration pass unless no local environment or repository is available.
-- Do not ask questions that can be answered from repository or system truth. Ask only when multiple plausible choices remain, a needed identifier/context is missing, or the ambiguity is product intent.
-
-## Phase 2 — Intent chat
-
-- Keep asking until you can clearly state the goal, success criteria, in/out of scope, constraints, current state, and key preferences/tradeoffs.
-- Bias toward questions over guessing: if a high-impact ambiguity remains, do not produce a proposed plan yet.
-
-## Phase 3 — Implementation chat
-
-- Once intent is stable, keep asking until the spec is decision-complete: approach, interfaces, data flow, edge cases/failure modes, testing and acceptance criteria, and any migration or compatibility constraints.
-- 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
-
-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:
-
-<proposed_plan>
-# Title
-
-## Summary
-...
-
-## Key Changes
-...
-
-## Test Plan
-...
-
-## Assumptions
-...
-</proposed_plan>
-
-Keep the proposed plan concise, human and agent digestible, and free of open decisions. Do not ask "should I proceed?" in the final output; the Plan-mode ready menu handles implementation, staying in Plan mode, or exit.`;
-}
-
-function readCommand(input: unknown) {
-	const command = input as { command?: unknown } | undefined;
-	return typeof command?.command === "string" ? command.command : "";
-}
-
-export function isSafeCommand(command: string) {
-	const trimmed = command.trim();
-	if (!trimmed) return false;
-	if (MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(trimmed))) return false;
-	return SAFE_BASH_PATTERNS.some((pattern) => pattern.test(trimmed));
-}
-
-export function extractProposedPlan(text: string) {
-	const match = PROPOSED_PLAN_PATTERN.exec(text);
-	return match?.[1]?.trim();
-}
-
-export function latestAssistantText(messages: unknown) {
-	if (!Array.isArray(messages)) return "";
-	for (const entry of [...messages].reverse()) {
-		const message = (entry as { message?: SessionMessage })?.message ?? (entry as SessionMessage);
-		if (message?.role !== "assistant") continue;
-		const text = messageText(message);
-		if (text) return text;
-	}
-	return "";
-}
-
-function messageContainsLegacyPlanModeContextArtifact(message: unknown) {
-	const candidate = unwrapSessionMessage(message);
-	return candidate.customType === PLAN_CONTEXT_MESSAGE_TYPE;
+	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function messageContainsInactivePlanModeArtifact(message: unknown) {
-	const candidate = unwrapSessionMessage(message);
-	return candidate.customType === PROPOSED_PLAN_MESSAGE_TYPE;
+function stringArray(value: unknown) {
+	return Array.isArray(value) && value.every((item): item is string => typeof item === "string")
+		? unique(value)
+		: undefined;
 }
 
-export function stripProposedPlanBlocksFromMessage<T>(message: T): T {
-	const candidate = unwrapSessionMessage(message);
-	if (candidate.role !== "assistant") return message;
-
-	const content = stripProposedPlanBlocksFromContent(candidate.content);
-	if (content === candidate.content) return message;
-
-	if (isSessionMessageEntry(message)) {
-		return { ...message, message: { ...candidate, content } };
-	}
-	return { ...candidate, content } as T;
+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 unwrapSessionMessage(message: unknown) {
-	const entry = message as { message?: unknown };
-	return (entry.message ?? message) as { role?: string; customType?: string; content?: unknown };
-}
-
-function isSessionMessageEntry<T>(message: T): message is T & { message: SessionMessage } {
-	return typeof message === "object" && message !== null && "message" in message;
-}
-
-function stripProposedPlanBlocksFromContent(content: unknown) {
-	if (typeof content === "string") return stripProposedPlanBlocks(content);
-	if (!Array.isArray(content)) return content;
-
-	let changed = false;
-	const nextContent = content.map((block) => {
-		const textBlock = block as TextBlock;
-		if (textBlock.type !== "text" || typeof textBlock.text !== "string") return block;
-
-		const text = stripProposedPlanBlocks(textBlock.text);
-		if (text === textBlock.text) return block;
-
-		changed = true;
-		return { ...textBlock, text };
-	});
-	return changed ? nextContent : content;
-}
-
-export function stripProposedPlanBlocks(text: string) {
-	return text.replace(PROPOSED_PLAN_BLOCK_PATTERN, "");
+export function withRequiredPlanModeTools(toolNames: string[]) {
+	return unique([...withoutPlanModeQuestionTool(toolNames), PLAN_MODE_QUESTION_TOOL_NAME]);
 }
 
-function messageText(message: SessionMessage) {
-	return contentText(message.content);
+export function withoutPlanModeQuestionTool(toolNames: string[]) {
+	return toolNames.filter((toolName) => toolName !== PLAN_MODE_QUESTION_TOOL_NAME);
 }
 
-function contentText(content: unknown): string {
-	if (typeof content === "string") return content;
-	if (!Array.isArray(content)) return "";
-	return content
-		.map((block) => {
-			const textBlock = block as TextBlock;
-			return textBlock.type === "text" && typeof textBlock.text === "string" ? textBlock.text : "";
-		})
-		.filter(Boolean)
-		.join("\n");
-}
+function invalidPlanMessage(kind: "empty" | "multiple" | "malformed" | "unclosed") {
+	const detail = {
+		empty: "the block is empty",
+		multiple: "more than one plan block was produced",
+		malformed: "the tags must be on their own lines",
+		unclosed: "the closing tag is missing",
+	}[kind];
+	return `Proposed plan is not ready: ${detail}. Continue Plan mode and produce one complete non-empty <proposed_plan> block.`;
+}
+
+export {
+	extractProposedPlan,
+	latestAssistantText,
+	parseProposedPlan,
+	stripProposedPlanBlocks,
+	stripProposedPlanBlocksFromMessage,
+} from "./message-transform.js";
+export { buildPlanModePrompt } from "./prompt.js";
+export { normalizePlanModeQuestionParams } from "./question-tool.js";
+export { normalizePlanModeSettings, readPlanModeSettings } from "./settings.js";
+export { canSelectToolInPlanMode, classifyPlanModeTool, isSafeCommand } from "./tool-policy.js";