@hank-warren/pi-plan-mode 0.1.0

package/src/presentation.ts

@@ -0,0 +1,108 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { PlanModeState } from "./state.js";
+
+const STATUS_KEY = "plan-mode";
+const PLAN_WIDGET_KEY = "plan-mode-plan";
+
+export function updatePlanModeUi(
+	ctx: ExtensionContext,
+	state: PlanModeState,
+	toolSummary: () => string,
+) {
+	ctx.ui.setStatus(STATUS_KEY, formatStatus(state));
+	if (state.enabled && state.latestPlan) {
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
+			"Proposed plan ready",
+			"Use /plan to implement, save, revise, or exit Plan mode.",
+		]);
+	} else if (state.enabled) {
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
+			"Plan mode: planning",
+			toolSummary(),
+			"Finish with plan_mode_complete when decision-ready.",
+		]);
+	} else if (state.savedPlan) {
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
+			"Plan saved for later",
+			"Use /plan to show, implement, or clear it.",
+		]);
+	} else if (state.activeImplementation) {
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, [
+			"Implementation plan active",
+			"Use /plan to show, replace, or clear it.",
+		]);
+	} else {
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
+	}
+}
+
+export function clearPlanModeUi(ctx: ExtensionContext) {
+	ctx.ui.setStatus(STATUS_KEY, undefined);
+	ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
+}
+
+export function showStoredPlan(pi: ExtensionAPI, ctx: ExtensionContext, state: PlanModeState) {
+	const readyPlan = state.enabled ? state.latestPlan?.trim() : undefined;
+	const savedPlan = state.savedPlan?.plan.trim();
+	if (savedPlan && (ctx.mode === "print" || ctx.mode === "json")) {
+		throw new Error("Saved plan display is unavailable in print/JSON mode. Use TUI or RPC.");
+	}
+	const activePlan = state.activeImplementation?.plan.trim();
+	const plan = readyPlan ?? savedPlan ?? activePlan;
+	if (!plan) {
+		ctx.ui.notify(
+			"No completed plan is available. Use /plan finalize when planning is complete.",
+			"info",
+		);
+		return;
+	}
+	const title = readyPlan
+		? "Proposed Plan"
+		: savedPlan
+			? "Saved Plan"
+			: "Active Implementation Plan";
+	showPlanModePlan(pi, ctx, title, plan);
+}
+
+export function showPlanModePlan(
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	title: string,
+	plan: string,
+) {
+	try {
+		pi.sendMessage(
+			{
+				customType: "proposed-plan",
+				content: `**${title}**\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");
+	}
+}
+
+export function planModeStatusText(state: PlanModeState, toolSummary: () => string) {
+	if (state.enabled) {
+		if (state.latestPlan) {
+			return `Plan mode is active and a proposed plan is ready. ${toolSummary()}`;
+		}
+		return `Plan mode is active. ${toolSummary()} Explore, ask, and finish with plan_mode_complete when decision-ready.`;
+	}
+	if (state.savedPlan) return "A plan is saved for later.";
+	if (state.activeImplementation) return "An implementation plan is active.";
+	return "Plan mode is off.";
+}
+
+function formatStatus(state: PlanModeState) {
+	if (state.enabled) {
+		if (state.awaitingAction || state.latestPlan) return "plan ready";
+		return "plan active";
+	}
+	if (state.savedPlan) return "plan saved";
+	if (state.activeImplementation) return "plan implementing";
+	return undefined;
+}

package/src/prompt.ts

@@ -0,0 +1,67 @@
+import type { PlanModeBashPolicy } from "./settings.js";
+
+const PLAN_CONTEXT_MARKER = "[CODEX-LIKE PLAN MODE ACTIVE]";
+
+export function buildPlanModePrompt(options: { bashPolicy?: PlanModeBashPolicy } = {}) {
+	const bashPolicy = options.bashPolicy ?? "limited";
+	const bashRule =
+		bashPolicy === "auto-permissions"
+			? "- Bash calls outside Plan Mode's inspection allowlist may be delegated to Auto Permissions when a matching guarded rule is active. Its approval permits information gathering, not implementation: keep every Bash action non-mutating and within the planning request."
+			: "- Bash is limited by Plan Mode's reviewed inspection policy. Use only accepted non-mutating inspection commands.";
+	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.
+${bashRule}
+- 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.
+- For an unanswered preference or tradeoff, use the recommended option only when it is low risk and record that default as an explicit assumption in the final plan.
+
+## 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.
+
+## Ending each turn
+
+Every Plan-mode turn that advances or finalizes the plan must end in exactly one of these ways:
+
+- 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.
+
+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.
+
+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.
+
+## Completion rule
+
+Only call plan_mode_complete when the plan leaves no implementation decisions unresolved. Pass the complete plan as Markdown with:
+
+- 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
+
+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/question-tool.ts

@@ -0,0 +1,273 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const PLAN_MODE_QUESTION_TOOL_NAME = "plan_mode_question";
+
+export type PlanModeQuestionOption = {
+	label: string;
+	description?: string;
+};
+
+export type PlanModeQuestion = {
+	id: string;
+	header: string;
+	question: string;
+	options: PlanModeQuestionOption[];
+};
+
+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[];
+};
+
+export 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;
+
+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 };
+}
+
+export async function answerPlanModeQuestions(
+	questions: PlanModeQuestion[],
+	ctx: ExtensionContext,
+	lifecycle: { isCurrent(): boolean; isEnabled(): boolean },
+) {
+	const answers = await askPlanModeQuestions(
+		questions,
+		ctx,
+		() => lifecycle.isCurrent() && lifecycle.isEnabled(),
+	);
+	if (!lifecycle.isCurrent()) {
+		return planModeQuestionCancelled(
+			questions,
+			"cancelled",
+			"Plan-mode question cancelled because the session changed.",
+		);
+	}
+	if (!lifecycle.isEnabled()) {
+		return planModeQuestionCancelled(
+			questions,
+			"plan_mode_inactive",
+			"Plan-mode question cancelled because Plan mode is no longer active.",
+		);
+	}
+	if (!answers) {
+		return planModeQuestionCancelled(
+			questions,
+			"cancelled",
+			"User cancelled the Plan-mode question prompt.",
+		);
+	}
+	return planModeQuestionAnswered(questions, answers);
+}
+
+export async function askPlanModeQuestions(
+	questions: PlanModeQuestion[],
+	ctx: ExtensionContext,
+	shouldContinue: () => boolean = () => true,
+): 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 (!shouldContinue() || !choice) return undefined;
+		if (choice === otherChoice) {
+			const customAnswer = (await ctx.ui.editor(question.question, ""))?.trim();
+			if (!shouldContinue() || !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}` : ""}`;
+}
+
+export function planModeQuestionAnswered(
+	questions: PlanModeQuestion[],
+	answers: PlanModeQuestionAnswer[],
+) {
+	return {
+		content: [
+			{ type: "text" as const, text: formatPlanModeQuestionPayload({ cancelled: false, answers }) },
+		],
+		details: { cancelled: false, questions, answers } satisfies PlanModeQuestionDetails,
+	};
+}
+
+export 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;
+}

package/src/required-tools.ts

@@ -0,0 +1,22 @@
+import { PLAN_MODE_COMPLETE_TOOL_NAME } from "./completion-tool.js";
+import { PLAN_MODE_QUESTION_TOOL_NAME } from "./question-tool.js";
+import { unique } from "./tool-selection.js";
+
+export function withRequiredPlanModeTools(toolNames: string[]) {
+	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);
+}
+
+export function withoutRequiredPlanModeTools(toolNames: string[]) {
+	return toolNames.filter(
+		(toolName) =>
+			toolName !== PLAN_MODE_QUESTION_TOOL_NAME && toolName !== PLAN_MODE_COMPLETE_TOOL_NAME,
+	);
+}

package/src/saved-plan-menu.ts

@@ -0,0 +1,93 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
+import { type PlanExportDestinationProvider, planExportInputScreen } from "./plan-export-screen.js";
+
+interface SavedPlanMenuOptions {
+	statusText: string;
+	implementationOutcome(): string;
+	getExportDestination: PlanExportDestinationProvider;
+	signal: AbortSignal;
+	isCurrent(): boolean;
+	show(): void;
+	implementHere(): void | Promise<void>;
+	implementFresh(signal: AbortSignal): void | Promise<void>;
+	exportPlan(path: string, signal: AbortSignal): Promise<boolean>;
+	settings(signal: AbortSignal): Promise<boolean>;
+	clear(): void;
+}
+
+export async function showSavedPlanMenu(ctx: ExtensionContext, options: SavedPlanMenuOptions) {
+	if (!ctx.hasUI) {
+		throw new Error(
+			`${options.statusText} Use /plan show, /plan implement, /plan export, or /plan exit.`,
+		);
+	}
+	type Screen = "saved" | "export";
+	type Action = "show" | "implement-here" | "implement-fresh" | "export" | "settings" | "clear";
+	const menu = defineMenu<undefined, Screen, Action, ExtensionContext>({
+		start: "saved",
+		screens: {
+			saved: () => ({
+				kind: "actions",
+				title: "Saved plan",
+				lines: [
+					options.statusText,
+					"Implement here keeps this planning conversation.",
+					"Start fresh transfers only the approved plan to a new session.",
+					options.implementationOutcome(),
+				],
+				items: [
+					{ id: "show", label: "Show saved plan", action: "show" },
+					{
+						id: "implement-here",
+						label: "Implement here",
+						description: "Continue in this session with the planning conversation.",
+						action: "implement-here",
+					},
+					{
+						id: "implement-fresh",
+						label: "Start fresh and implement",
+						description: "Open a new linked session; transfer only the approved plan.",
+						action: "implement-fresh",
+						busyLabel: "Starting fresh implementation session…",
+					},
+					{ id: "export", label: "Export plan…", to: "export" },
+					{ id: "settings", label: "Settings", action: "settings" },
+					{ id: "clear", label: "Clear saved plan", action: "clear" },
+				],
+				hint: "close",
+			}),
+			export: () => planExportInputScreen(options.getExportDestination),
+		},
+		actions: {
+			show: async () => {
+				options.show();
+				return { kind: "close" };
+			},
+			"implement-here": async () => {
+				await options.implementHere();
+				return { kind: "close" };
+			},
+			"implement-fresh": async ({ signal }) => {
+				await options.implementFresh(signal);
+				return { kind: "close" };
+			},
+			export: async ({ value, signal }) =>
+				(await options.exportPlan(value ?? "", signal)) ? { kind: "close" } : { kind: "rejected" },
+			settings: async ({ signal }) => {
+				const close = await options.settings(signal);
+				if (signal.aborted || !options.isCurrent()) return { kind: "rejected" };
+				return close ? { kind: "close" } : { kind: "stay" };
+			},
+			clear: async () => {
+				options.clear();
+				return { kind: "close" };
+			},
+		},
+	});
+	await runMenu(ctx, menu, {
+		getState: () => undefined,
+		signal: options.signal,
+		isCurrent: options.isCurrent,
+	});
+}

package/src/saved-plan-preflight.ts

@@ -0,0 +1,39 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function savedPlanBlocksNewWorkflow(ctx: ExtensionContext, hasSavedPlan: boolean) {
+	if (!hasSavedPlan) return false;
+	const message =
+		"A plan is saved for later. Implement or clear it before starting another Plan-mode workflow.";
+	if (!ctx.hasUI) throw new Error(message);
+	ctx.ui.notify(message, "warning");
+	return true;
+}
+
+export async function preflightSavedPlanImplementation(
+	ctx: ExtensionContext,
+	isCurrent: () => boolean,
+) {
+	if (ctx.mode === "print" || ctx.mode === "json") {
+		throw new Error("Saved plan implementation is unavailable in print/JSON mode. Use TUI or RPC.");
+	}
+	const model = ctx.model;
+	if (!model) {
+		ctx.ui.notify("Unable to implement saved plan: no model is selected.", "warning");
+		return false;
+	}
+	let auth: Awaited<ReturnType<ExtensionContext["modelRegistry"]["getApiKeyAndHeaders"]>>;
+	try {
+		auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+	} catch (error: unknown) {
+		if (!isCurrent()) return false;
+		const detail = error instanceof Error ? error.message : String(error);
+		ctx.ui.notify(`Unable to implement saved plan: ${detail}`, "error");
+		return false;
+	}
+	if (!isCurrent()) return false;
+	if (!auth.ok) {
+		ctx.ui.notify(`Unable to implement saved plan: ${auth.error}`, "warning");
+		return false;
+	}
+	return true;
+}