@bacnh85/pi-plan 0.1.1 → 0.1.2

package/README.md

@@ -2,10 +2,11 @@
 
 Pi extension that adds a lightweight plan mode inspired by Codex and Claude Code:
 
-- Toggle plan mode with `/plan`, `/plan on`, `/plan off`, or `Ctrl+Alt+P`.
-- Pick separate thinking/reasoning levels for planning and normal execution with `/plan levels`.
+- Toggle plan mode with `/plan` or `Ctrl+Alt+P`.
+- Remembers separate thinking/reasoning levels for planning and normal execution based on the active mode when you change Pi's reasoning level.
 - Keeps planning read-only by disabling built-in `edit`/`write` and blocking destructive shell commands.
 - Provides a `write_plan` tool so the agent writes reviewable Markdown plans into `.agents/plans/` in the current workspace.
+- Provides an `ask_plan_question` tool so the agent can ask selection-style clarifying questions during planning, with an option for free-form user input.
 - Prompts after a plan is written so you can approve execution, approve only, keep planning, or refine with feedback.
 
 ## Install
@@ -39,29 +40,35 @@ pi --plan
 | Command / shortcut | Description |
 | --- | --- |
 | `/plan` | Toggle plan mode. |
-| `/plan on` / `/plan off` | Explicitly enter or exit plan mode. |
-| `/plan levels` | Select planning and normal/execution thinking levels. |
-| `/plan status` | Show current mode, thinking levels, and last plan file. |
-| `/plan high` | Set the plan-mode thinking level directly (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). |
 | `Ctrl+Alt+P` | Toggle plan mode. |
 
 ## Workflow
 
 1. Enter plan mode.
 2. Ask pi to research the task and propose an implementation.
-3. The model explores read-only context and calls `write_plan`.
-4. The plan is saved under `.agents/plans/<timestamp>-<title>.md`.
-5. Choose one of the approval options:
+3. The model explores read-only context. If a consequential decision remains ambiguous, it can call `ask_plan_question` so you can choose an option or type your own answer.
+4. The model calls `write_plan`.
+5. The plan is saved under `.agents/plans/<timestamp>-<title>.md`.
+6. Choose one of the approval options:
    - **Approve and execute**: exits plan mode, restores tools, applies normal thinking level, and sends a follow-up execution prompt.
    - **Approve only**: exits plan mode without starting work.
    - **Keep planning**: remains in plan mode.
    - **Refine with feedback**: sends your feedback as a follow-up planning prompt.
 
+## Reasoning levels
+
+pi-plan remembers two reasoning levels:
+
+- Change Pi's active reasoning level while plan mode is active to update the planning level.
+- Change Pi's active reasoning level in normal or execution mode to update the normal/execution level.
+
+The remembered levels are restored when switching modes and across resumed sessions.
+
 ## Design notes
 
 Research findings used for this extension:
 
-- Pi has no built-in plan mode by design, but extensions can implement it with commands, shortcuts, tool gating, status widgets, and prompt injection.
+- Pi has no built-in plan mode by design, but extensions can implement it with commands, shortcuts, tools, tool gating, and prompt injection.
 - Claude Code plan mode emphasizes read-only exploration, writing a Markdown plan, and an approval flow before edits.
 - Codex guidance recommends plan mode for complex or ambiguous tasks and using higher reasoning levels for harder planning/debugging work.
 

package/index.ts

@@ -7,8 +7,9 @@ import path from "node:path";
 const STATUS_KEY = "pi-plan";
 const PLAN_DIR = path.join(".agents", "plans");
 const PLAN_TOOL = "write_plan";
+const PLAN_QUESTION_TOOL = "ask_plan_question";
 const PLAN_MODE_DISABLED_TOOLS = new Set(["edit", "write"]);
-const DEFAULT_PLAN_TOOLS = ["read", "bash", "grep", "find", "ls", PLAN_TOOL];
+const DEFAULT_PLAN_TOOLS = ["read", "bash", "grep", "find", "ls", PLAN_TOOL, PLAN_QUESTION_TOOL];
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
 
 type ThinkingLevel = (typeof THINKING_LEVELS)[number];
@@ -31,6 +32,17 @@ interface WritePlanParams {
 	status?: PlanStatus;
 }
 
+interface PlanQuestionOption {
+	label: string;
+	description?: string;
+}
+
+interface PlanQuestionParams {
+	question: string;
+	options: PlanQuestionOption[];
+	allowOther?: boolean;
+}
+
 const DESTRUCTIVE_BASH_PATTERNS = [
 	/\brm\b/i,
 	/\brmdir\b/i,
@@ -103,6 +115,7 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 	let lastPlanPath: string | undefined;
 	let lastPlanTitle: string | undefined;
 	let lastPlanStatus: PlanStatus | undefined;
+	let applyingStoredThinking = false;
 
 	function setStatus(ctx: ExtensionContext): void {
 		if (planModeEnabled) {
@@ -116,17 +129,8 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
 	}
 
-	function setPlanWidget(ctx: ExtensionContext): void {
-		if (!planModeEnabled) {
-			ctx.ui.setWidget(STATUS_KEY, undefined);
-			return;
-		}
-		ctx.ui.setWidget(STATUS_KEY, [
-			ctx.ui.theme.fg("warning", "Plan mode: read-only exploration"),
-			`Plan file target: ${PLAN_DIR}/`,
-			`Plan thinking: ${planThinking}; normal thinking: ${normalThinking}`,
-			"Use write_plan when the plan is ready for approval.",
-		]);
+	function clearPlanWidget(ctx: ExtensionContext): void {
+		ctx.ui.setWidget(STATUS_KEY, undefined);
 	}
 
 	function persistState(): void {
@@ -154,7 +158,23 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 	}
 
 	function applyThinking(level: ThinkingLevel): void {
+		applyingStoredThinking = true;
 		pi.setThinkingLevel(level);
+		setTimeout(() => {
+			applyingStoredThinking = false;
+		}, 0);
+	}
+
+	function recordActiveThinkingLevel(level: ThinkingLevel, ctx: ExtensionContext): void {
+		if (planModeEnabled) {
+			if (planThinking === level) return;
+			planThinking = level;
+		} else {
+			if (normalThinking === level) return;
+			normalThinking = level;
+		}
+		setStatus(ctx);
+		persistState();
 	}
 
 	function enterPlanMode(ctx: ExtensionContext): void {
@@ -163,7 +183,7 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		enablePlanTools();
 		applyThinking(planThinking);
 		setStatus(ctx);
-		setPlanWidget(ctx);
+		clearPlanWidget(ctx);
 		persistState();
 		ctx.ui.notify(`Plan mode enabled. Thinking=${planThinking}. Plans will be written to ${PLAN_DIR}/`, "info");
 	}
@@ -174,43 +194,14 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		restoreTools();
 		if (restoreThinking) applyThinking(normalThinking);
 		setStatus(ctx);
-		setPlanWidget(ctx);
+		clearPlanWidget(ctx);
 		persistState();
 		ctx.ui.notify(`Plan mode disabled. Thinking=${pi.getThinkingLevel()}.`, "info");
 	}
 
-	async function chooseThinkingLevels(ctx: ExtensionContext): Promise<void> {
-		const plan = await ctx.ui.select("Plan mode reasoning level", [...THINKING_LEVELS]);
-		if (plan && isThinkingLevel(plan)) planThinking = plan;
-		const normal = await ctx.ui.select("Normal/execution reasoning level", [...THINKING_LEVELS]);
-		if (normal && isThinkingLevel(normal)) normalThinking = normal;
-		if (planModeEnabled) applyThinking(planThinking);
-		else applyThinking(normalThinking);
-		setStatus(ctx);
-		setPlanWidget(ctx);
-		persistState();
-		ctx.ui.notify(`pi-plan levels: plan=${planThinking}, normal=${normalThinking}`, "info");
-	}
-
 	async function handlePlanCommand(args: string, ctx: ExtensionContext): Promise<void> {
-		const subcommand = args.trim();
-		if (subcommand === "levels") return chooseThinkingLevels(ctx);
-		if (subcommand === "on" || subcommand === "start") return enterPlanMode(ctx);
-		if (subcommand === "off" || subcommand === "stop") return leavePlanMode(ctx);
-		if (subcommand === "status") {
-			ctx.ui.notify(
-				[`Mode: ${planModeEnabled ? "planning" : executionMode ? "executing" : "normal"}`, `Plan thinking: ${planThinking}`, `Normal thinking: ${normalThinking}`, `Last plan: ${lastPlanPath ? relativeToCwd(ctx.cwd, lastPlanPath) : "none"}`].join("\n"),
-				"info",
-			);
-			return;
-		}
-		if (subcommand.length > 0 && isThinkingLevel(subcommand)) {
-			planThinking = subcommand;
-			if (planModeEnabled) applyThinking(planThinking);
-			setStatus(ctx);
-			setPlanWidget(ctx);
-			persistState();
-			ctx.ui.notify(`Plan thinking set to ${planThinking}`, "info");
+		if (args.trim().length > 0) {
+			ctx.ui.notify("/plan does not take arguments; use /plan or Ctrl+Alt+P to toggle plan mode.", "warning");
 			return;
 		}
 		if (planModeEnabled) leavePlanMode(ctx);
@@ -253,12 +244,83 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		},
 	});
 
-	pi.registerCommand("plan", {
-		description: "Toggle pi-plan mode; subcommands: on, off, levels, status, or a thinking level",
-		getArgumentCompletions: (prefix) => {
-			const values = ["on", "off", "levels", "status", ...THINKING_LEVELS].filter((value) => value.startsWith(prefix));
-			return values.length ? values.map((value) => ({ label: value, value })) : null;
+	pi.registerTool({
+		name: PLAN_QUESTION_TOOL,
+		label: "Ask Plan Question",
+		description: "Ask the user a consequential planning question with selectable options and optional free-form input.",
+		promptSnippet: "Ask the user a concise planning question with 2-4 concrete options when an open decision materially affects the plan.",
+		promptGuidelines: [
+			"Use only after repository research leaves a consequential ambiguity that affects the plan.",
+			"Prefer 2-4 concrete options with short labels and useful descriptions.",
+			"Do not ask about details that can be discovered from the repository.",
+			"If the user already gave a preference, incorporate it instead of asking again.",
+		],
+		parameters: Type.Object({
+			question: Type.String({ description: "The planning question to ask the user" }),
+			options: Type.Array(
+				Type.Object({
+					label: Type.String({ description: "Short selectable option label" }),
+					description: Type.Optional(Type.String({ description: "Optional explanation shown with the option" })),
+				}),
+				{ description: "Concrete options for the user to choose from" },
+			),
+			allowOther: Type.Optional(Type.Boolean({ description: "Whether to allow a free-form user answer; defaults to true" })),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const typedParams = params as PlanQuestionParams;
+			const options = typedParams.options ?? [];
+			if (options.length === 0) {
+				return {
+					content: [{ type: "text", text: "Error: ask_plan_question requires at least one option." }],
+					details: { question: typedParams.question, answer: null },
+				};
+			}
+			if (!ctx.hasUI) {
+				return {
+					content: [{ type: "text", text: "UI is not available. Ask this planning question directly in chat and wait for the user's answer." }],
+					details: { question: typedParams.question, options, answer: null },
+				};
+			}
+
+			const allowOther = typedParams.allowOther !== false;
+			const labels = options.map((option) =>
+				option.description ? `${option.label} — ${option.description}` : option.label,
+			);
+			const otherLabel = "Other / type my answer";
+			const choice = await ctx.ui.select(typedParams.question, allowOther ? [...labels, otherLabel] : labels);
+			if (!choice) {
+				return {
+					content: [{ type: "text", text: "User cancelled the planning question." }],
+					details: { question: typedParams.question, options, answer: null, cancelled: true },
+				};
+			}
+
+			if (choice === otherLabel) {
+				const answer = (await ctx.ui.editor("Your answer", ""))?.trim();
+				if (!answer) {
+					return {
+						content: [{ type: "text", text: "User cancelled the planning question." }],
+						details: { question: typedParams.question, options, answer: null, cancelled: true },
+					};
+				}
+				return {
+					content: [{ type: "text", text: `User wrote: ${answer}` }],
+					details: { question: typedParams.question, options, answer, wasCustom: true },
+				};
+			}
+
+			const selectedIndex = labels.indexOf(choice);
+			const selected = options[selectedIndex];
+			const answer = selected?.label ?? choice;
+			return {
+				content: [{ type: "text", text: `User selected: ${answer}` }],
+				details: { question: typedParams.question, options, answer, selectedIndex: selectedIndex + 1, wasCustom: false },
+			};
 		},
+	});
+
+	pi.registerCommand("plan", {
+		description: "Toggle pi-plan mode",
 		handler: async (args, ctx) => handlePlanCommand(args, ctx),
 	});
 
@@ -291,7 +353,13 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 			applyThinking(planThinking);
 		}
 		setStatus(ctx);
-		setPlanWidget(ctx);
+		clearPlanWidget(ctx);
+	});
+
+	pi.on("thinking_level_select", async (event, ctx) => {
+		if (applyingStoredThinking) return;
+		if (!isThinkingLevel(event.level)) return;
+		recordActiveThinkingLevel(event.level, ctx);
 	});
 
 	pi.on("tool_call", async (event) => {
@@ -311,7 +379,7 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 			return {
 				message: {
 					customType: "pi-plan-context",
-					content: `[PI-PLAN MODE ACTIVE]\nYou are in read-only planning mode. Research the codebase and produce a reviewable implementation plan before making changes.\n\nRules:\n- Do not edit source files, configs, lockfiles, or git state.\n- You may read files, search, inspect git state, and run read-only shell commands.\n- Ask concise clarifying questions if requirements are ambiguous.\n- When the plan is ready, call ${PLAN_TOOL} with a complete Markdown plan.\n- The plan file must live in ${PLAN_DIR}/. Current/next plan path: ${relativePlan}\n\nPlan content should include:\n1. Goal and assumptions.\n2. Key findings with durable file/symbol paths.\n3. Proposed implementation steps.\n4. Verification plan.\n5. Risks, open questions, and rejected alternatives if relevant.`,
+					content: `[PI-PLAN MODE ACTIVE]\nYou are in read-only planning mode. Research the codebase and produce a reviewable implementation plan before making changes.\n\nRules:\n- Do not edit source files, configs, lockfiles, or git state.\n- You may read files, search, inspect git state, and run read-only shell commands.\n- Ask concise clarifying questions if requirements are ambiguous. Use ${PLAN_QUESTION_TOOL} for consequential open decisions with 2-4 clear options and an Other/user-opinion path.\n- Do not ask about details you can discover from repository evidence. If the user already gave an opinion, incorporate it instead of asking again.\n- When the plan is ready, call ${PLAN_TOOL} with a complete Markdown plan.\n- The plan file must live in ${PLAN_DIR}/. Current/next plan path: ${relativePlan}\n\nPlan content should include:\n1. Goal and assumptions.\n2. Key findings with durable file/symbol paths.\n3. Proposed implementation steps.\n4. Verification plan.\n5. Risks, open questions, and rejected alternatives if relevant.`,
 					display: false,
 				},
 			};
@@ -350,7 +418,7 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 			restoreTools();
 			applyThinking(normalThinking);
 			setStatus(ctx);
-			setPlanWidget(ctx);
+			clearPlanWidget(ctx);
 			persistState();
 			pi.sendUserMessage(`Execute the approved plan in ${relativePlan}. Keep the implementation scoped to the plan, update the plan if reality differs materially, and run the verification described there.`, { deliverAs: "followUp" });
 		} else if (choice === "Approve only (exit plan mode)") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bacnh85/pi-plan",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Pi extension that adds a plan mode with workspace markdown plans and thinking-level presets.",
   "license": "MIT",
   "publishConfig": {