@narumitw/pi-plan-mode 0.13.0 → 0.14.0

package/src/prompt.ts

@@ -0,0 +1,58 @@
+const PLAN_CONTEXT_MARKER = "[CODEX-LIKE PLAN MODE ACTIVE]";
+
+export 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.
+- 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.
+
+## 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. 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.
+
+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.`;
+}

package/src/question-tool.ts

@@ -0,0 +1,207 @@
+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 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}` : ""}`;
+}
+
+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/settings.ts

@@ -0,0 +1,68 @@
+import { readFile } from "node:fs/promises";
+import { 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_THINKING_LEVELS = [
+	"inherit",
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+] as const;
+
+export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
+export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit">;
+export interface PlanModeSettings {
+	thinkingLevel: PlanModeThinkingLevel;
+}
+export type PlanModeSettingsLoadResult =
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string }
+	| { kind: "loaded"; settings: PlanModeSettings };
+
+export function normalizePlanModeSettings(value: unknown): PlanModeSettings | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const thinkingLevel = Object.hasOwn(value, "thinkingLevel")
+		? Reflect.get(value, "thinkingLevel")
+		: "inherit";
+	return PLAN_MODE_THINKING_LEVELS.includes(thinkingLevel as PlanModeThinkingLevel)
+		? { thinkingLevel: thinkingLevel as PlanModeThinkingLevel }
+		: undefined;
+}
+
+export async function readPlanModeSettings(
+	settingsPath = join(getAgentDir(), PLAN_MODE_SETTINGS_FILE),
+): Promise<PlanModeSettingsLoadResult> {
+	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) };
+	}
+	try {
+		const settings = normalizePlanModeSettings(JSON.parse(contents) as unknown);
+		return settings
+			? { kind: "loaded", settings }
+			: { kind: "invalid", reason: "invalid settings shape" };
+	} catch (error: unknown) {
+		return { kind: "invalid", reason: formatError(error) };
+	}
+}
+
+export function configuredThinkingLevel(
+	settings: PlanModeSettings,
+): PlanModeFixedThinkingLevel | undefined {
+	return settings.thinkingLevel === "inherit" ? undefined : settings.thinkingLevel;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/tool-policy.ts

@@ -0,0 +1,356 @@
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+
+export const SAFE_BUILTIN_PLAN_TOOLS = new Set(["read", "bash", "grep", "find", "ls"]);
+export type PlanModeToolPolicy = "read-only" | "limited" | "user-opt-in" | "blocked";
+
+const BLOCKED_BUILTIN_TOOLS = new Set(["edit", "write"]);
+const MUTATING_COMMANDS = new Set([
+	"rm",
+	"rmdir",
+	"mv",
+	"cp",
+	"mkdir",
+	"touch",
+	"chmod",
+	"chown",
+	"chgrp",
+	"ln",
+	"tee",
+	"truncate",
+	"dd",
+	"sudo",
+	"su",
+	"kill",
+	"pkill",
+	"killall",
+	"reboot",
+	"shutdown",
+	"vim",
+	"vi",
+	"nano",
+	"emacs",
+	"code",
+	"subl",
+]);
+const READ_ONLY_COMMANDS = new Set([
+	"cat",
+	"head",
+	"tail",
+	"grep",
+	"find",
+	"ls",
+	"pwd",
+	"echo",
+	"printf",
+	"wc",
+	"sort",
+	"uniq",
+	"diff",
+	"file",
+	"stat",
+	"du",
+	"df",
+	"tree",
+	"which",
+	"whereis",
+	"type",
+	"printenv",
+	"uname",
+	"whoami",
+	"id",
+	"date",
+	"uptime",
+	"ps",
+	"jq",
+	"rg",
+	"fd",
+	"bat",
+	"eza",
+]);
+
+export function isBuiltinTool(tool: ToolInfo) {
+	return tool.sourceInfo.source === "builtin";
+}
+
+export function classifyPlanModeTool(tool: ToolInfo): PlanModeToolPolicy {
+	if (!isBuiltinTool(tool)) return "user-opt-in";
+	if (BLOCKED_BUILTIN_TOOLS.has(tool.name)) return "blocked";
+	if (tool.name === "bash") return "limited";
+	return SAFE_BUILTIN_PLAN_TOOLS.has(tool.name) ? "read-only" : "blocked";
+}
+
+export function canSelectToolInPlanMode(tool: ToolInfo) {
+	return classifyPlanModeTool(tool) !== "blocked";
+}
+
+export function readCommand(input: unknown) {
+	const command = input as { command?: unknown } | undefined;
+	return typeof command?.command === "string" ? command.command : "";
+}
+
+export function isSafeCommand(command: string) {
+	const segments = splitShellSegments(command);
+	return segments !== undefined && segments.length > 0 && segments.every(isSafeSegment);
+}
+
+function splitShellSegments(command: string): string[] | undefined {
+	const trimmed = command.trim();
+	if (!trimmed || /[\n\r`]/.test(trimmed)) return undefined;
+
+	const segments: string[] = [];
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	let start = 0;
+	for (let index = 0; index < trimmed.length; index += 1) {
+		const character = trimmed[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"') {
+			quote = character;
+			continue;
+		}
+		if (character === ">" || character === "<" || character === "(" || character === ")") {
+			return undefined;
+		}
+		const next = trimmed[index + 1];
+		if (character === "&" && next !== "&") return undefined;
+		const separatorLength =
+			character === ";" || character === "|"
+				? next === character
+					? 2
+					: 1
+				: character === "&" && next === "&"
+					? 2
+					: 0;
+		if (separatorLength === 0) continue;
+		const segment = trimmed.slice(start, index).trim();
+		if (!segment) return undefined;
+		segments.push(segment);
+		index += separatorLength - 1;
+		start = index + 1;
+	}
+	if (quote || escaped) return undefined;
+	const finalSegment = trimmed.slice(start).trim();
+	if (!finalSegment) return undefined;
+	segments.push(finalSegment);
+	return segments;
+}
+
+function isSafeSegment(segment: string) {
+	if (/\$\(|\$\{|(^|\s)[A-Za-z_][A-Za-z0-9_]*=/.test(segment)) return false;
+	const tokens = shellWords(segment);
+	if (!tokens || tokens.length === 0) return false;
+	const command = tokens[0]?.toLowerCase();
+	if (!command || MUTATING_COMMANDS.has(command)) return false;
+	const args = tokens.slice(1);
+	if (!hasSafeArguments(command, args)) return false;
+	if (READ_ONLY_COMMANDS.has(command)) return true;
+	return isSafeStructuredCommand(command, args);
+}
+
+function shellWords(segment: string): string[] | undefined {
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	for (const character of segment) {
+		if (escaped) {
+			word += character;
+			escaped = false;
+			continue;
+		}
+		if (character === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			else word += character;
+			continue;
+		}
+		if (character === "'" || character === '"') quote = character;
+		else if (/\s/.test(character)) {
+			if (word) words.push(word);
+			word = "";
+		} else word += character;
+	}
+	if (quote || escaped) return undefined;
+	if (word) words.push(word);
+	return words;
+}
+
+function hasSafeArguments(command: string, args: string[]) {
+	const forbidden = new Set(["-i", "--in-place", "--fix", "--write", "-delete", "--delete"]);
+	if (args.some((argument) => forbidden.has(argument))) return false;
+	if (
+		command === "sed" &&
+		args.some(
+			(argument) =>
+				argument.startsWith("--in-place=") ||
+				(/^-[^-]+/.test(argument) && argument.slice(1).includes("i")),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "find" &&
+		args.some((argument) =>
+			["-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"].includes(
+				argument,
+			),
+		)
+	) {
+		return false;
+	}
+	if (command === "date" && args.some((argument) => argument === "-s" || argument.startsWith("--set"))) {
+		return false;
+	}
+	if (
+		(command === "sort" || command === "tree") &&
+		args.some(
+			(argument) =>
+				argument === "-o" ||
+				(argument.startsWith("-o") && !argument.startsWith("--")) ||
+				argument.startsWith("--output"),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "sort" &&
+		args.some(
+			(argument) =>
+				argument === "-T" ||
+				(argument.startsWith("-T") && argument.length > 2) ||
+				argument.startsWith("--temporary-directory") ||
+				argument.startsWith("--compress-program"),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "diff" &&
+		args.some((argument) => argument === "--output" || argument.startsWith("--output="))
+	) {
+		return false;
+	}
+	if (command === "uniq" && args.filter((argument) => !argument.startsWith("-")).length > 1) {
+		return false;
+	}
+	if (
+		command === "fd" &&
+		args.some((argument) =>
+			["-x", "-X", "--exec", "--exec-batch"].some(
+				(flag) => argument === flag || argument.startsWith(`${flag}=`),
+			),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "rg" &&
+		args.some((argument) => argument === "--pre" || argument.startsWith("--pre="))
+	) {
+		return false;
+	}
+	if (
+		command === "bat" &&
+		args.some((argument) => argument === "--pager" || argument.startsWith("--pager="))
+	) {
+		return false;
+	}
+	return true;
+}
+
+function isSafeStructuredCommand(command: string, args: string[]) {
+	const subcommandIndex = args.findIndex((argument) => !argument.startsWith("-"));
+	const subcommand = args[subcommandIndex]?.toLowerCase();
+	const subcommandArgs = subcommandIndex >= 0 ? args.slice(subcommandIndex + 1) : [];
+	if (command === "sed") {
+		const script = args.find((argument) => !argument.startsWith("-"));
+		return (
+			Boolean(script) &&
+			(args.includes("-n") || args.some((argument) => /^-[^-]*n[^-]*$/.test(argument))) &&
+			/^\d+(,\d+)?p$/.test(script ?? "")
+		);
+	}
+	if (command === "git") {
+		if (!subcommand || !["status", "log", "diff", "show", "branch", "remote", "ls-files", "grep"].includes(subcommand)) return false;
+		if (subcommand === "branch" && subcommandArgs.some((argument) => !argument.startsWith("-"))) return false;
+		if (
+			subcommand === "branch" &&
+			subcommandArgs.some(
+				(argument) =>
+					[
+						"-d",
+						"-D",
+						"-m",
+						"-M",
+						"-c",
+						"-C",
+						"--delete",
+						"--move",
+						"--copy",
+						"--edit-description",
+						"--unset-upstream",
+					].includes(argument) || argument.startsWith("--set-upstream-to"),
+			)
+		)
+			return false;
+		if (subcommand === "remote") {
+			const action = subcommandArgs.find((argument) => !argument.startsWith("-"));
+			if (action && action !== "show" && action !== "get-url") return false;
+		}
+		if (
+			args.some(
+				(argument) =>
+					argument === "--output" ||
+					argument.startsWith("--output=") ||
+					argument === "--ext-diff" ||
+					argument === "--textconv" ||
+					argument === "--open-files-in-pager" ||
+					argument.startsWith("--open-files-in-pager=") ||
+					(subcommand === "grep" && (argument === "-O" || argument.startsWith("-O"))),
+			)
+		)
+			return false;
+		return true;
+	}
+	if (["node", "python", "python3", "tsc", "biome", "ruff", "ty"].includes(command)) {
+		if (args.includes("--version")) return true;
+		return (
+			command === "tsc" &&
+			args.includes("--noEmit") &&
+			!args.some(
+				(argument) =>
+					argument === "--incremental" ||
+					argument.startsWith("--incremental=") ||
+					argument === "--tsBuildInfoFile" ||
+					argument.startsWith("--tsBuildInfoFile=") ||
+					argument === "--generateTrace" ||
+					argument.startsWith("--generateTrace="),
+			)
+		);
+	}
+	if (command === "npm") {
+		if (subcommand === "audit" && subcommandArgs.includes("fix")) return false;
+		if (["list", "ls", "view", "info", "search", "outdated", "audit", "test"].includes(subcommand ?? "")) {
+			return true;
+		}
+		return subcommand === "run" && ["test", "check", "typecheck", "lint"].includes(args[1] ?? "");
+	}
+	if (["cargo", "go", "pytest", "vitest", "jest"].includes(command)) {
+		return ["test", "check"].includes(subcommand ?? "") || ["pytest", "vitest", "jest"].includes(command);
+	}
+	return false;
+}