@bacnh85/pi-plan 0.1.2 → 0.1.3

package/README.md

@@ -3,7 +3,7 @@
 Pi extension that adds a lightweight plan mode inspired by Codex and Claude Code:
 
 - 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.
+- Remembers separate thinking/reasoning levels for planning and normal execution across sessions 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.
@@ -50,11 +50,14 @@ pi --plan
 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.
+   - **Execute in current session**: exits plan mode, restores tools, applies normal thinking level, shows current context usage in the option label, and sends a follow-up execution prompt.
+   - **Execute in new session**: exits plan mode and prepares a fresh session that uses the saved Markdown plan file as the handoff artifact.
    - **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.
 
+Agents should ask blocking, user-answerable planning questions with `ask_plan_question` before finalizing a plan. Final plans may still list non-blocking uncertainties or implementation-time checks, but should not leave consequential user decisions unresolved.
+
 ## Reasoning levels
 
 pi-plan remembers two reasoning levels:
@@ -62,7 +65,7 @@ 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.
+The remembered levels are restored when switching modes and across independent or resumed sessions. pi-plan stores only these non-sensitive preferences under your user Pi agent directory.
 
 ## Design notes
 

package/index.ts

@@ -1,13 +1,16 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isToolCallEventType, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import os from "node:os";
 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_EXECUTE_COMMAND = "plan-execute";
+const PREFERENCES_FILE = path.join(os.homedir(), ".pi", "agent", "pi-plan", "preferences.json");
 const PLAN_MODE_DISABLED_TOOLS = new Set(["edit", "write"]);
 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;
@@ -26,6 +29,12 @@ interface PlanState {
 	lastPlanStatus?: PlanStatus;
 }
 
+interface PlanPreferences {
+	version: 1;
+	planThinking: ThinkingLevel;
+	normalThinking: ThinkingLevel;
+}
+
 interface WritePlanParams {
 	title: string;
 	content: string;
@@ -102,6 +111,43 @@ function relativeToCwd(cwd: string, absolutePath: string): string {
 	return path.relative(cwd, absolutePath).split(path.sep).join("/");
 }
 
+function formatContextUsage(ctx: ExtensionContext): string {
+	const usage = ctx.getContextUsage();
+	if (!usage || usage.percent === null) return "context usage unknown";
+	const percent = `${Math.round(usage.percent)}% context used`;
+	if (usage.tokens === null) return percent;
+	return `${percent} (${Math.round(usage.tokens / 1000)}k / ${Math.round(usage.contextWindow / 1000)}k tokens)`;
+}
+
+function buildExecutionPrompt(relativePlan: string, mode: "current" | "new"): string {
+	const prefix = mode === "new" ? "This is a fresh session created from an approved pi-plan. " : "";
+	return `${prefix}Execute the approved plan in ${relativePlan}. Read the plan file if needed, keep the implementation scoped to the plan, update the plan if reality differs materially, and run the verification described there.`;
+}
+
+function hasOpenQuestionWarning(content: string): boolean {
+	return /(^|\n)#{1,6}\s+.*open questions?.*\n[\s\S]*\?/i.test(content);
+}
+
+async function loadPreferences(): Promise<PlanPreferences | undefined> {
+	try {
+		const raw = await readFile(PREFERENCES_FILE, "utf8");
+		const parsed = JSON.parse(raw) as Partial<PlanPreferences>;
+		const savedPlanThinking = parsed.planThinking;
+		const savedNormalThinking = parsed.normalThinking;
+		if (parsed.version !== 1 || !savedPlanThinking || !savedNormalThinking || !isThinkingLevel(savedPlanThinking) || !isThinkingLevel(savedNormalThinking)) return undefined;
+		return { version: 1, planThinking: savedPlanThinking, normalThinking: savedNormalThinking };
+	} catch {
+		return undefined;
+	}
+}
+
+async function savePreferences(preferences: PlanPreferences): Promise<void> {
+	await mkdir(path.dirname(PREFERENCES_FILE), { recursive: true });
+	const temporaryPath = `${PREFERENCES_FILE}.${process.pid}.tmp`;
+	await writeFile(temporaryPath, `${JSON.stringify(preferences, null, 2)}\n`, "utf8");
+	await rename(temporaryPath, PREFERENCES_FILE);
+}
+
 function isDestructiveBash(command: string): boolean {
 	return DESTRUCTIVE_BASH_PATTERNS.some((pattern) => pattern.test(command));
 }
@@ -146,6 +192,10 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		} satisfies PlanState);
 	}
 
+	function persistPreferences(): void {
+		void savePreferences({ version: 1, planThinking, normalThinking }).catch(() => undefined);
+	}
+
 	function enablePlanTools(): void {
 		const baseline = toolsBeforePlan ?? pi.getActiveTools();
 		toolsBeforePlan = baseline;
@@ -175,6 +225,7 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		}
 		setStatus(ctx);
 		persistState();
+		persistPreferences();
 	}
 
 	function enterPlanMode(ctx: ExtensionContext): void {
@@ -208,6 +259,50 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		else enterPlanMode(ctx);
 	}
 
+	function beginCurrentSessionExecution(ctx: ExtensionContext, relativePlan: string): void {
+		planModeEnabled = false;
+		executionMode = true;
+		lastPlanStatus = "approved";
+		restoreTools();
+		applyThinking(normalThinking);
+		setStatus(ctx);
+		clearPlanWidget(ctx);
+		persistState();
+		persistPreferences();
+		pi.sendUserMessage(buildExecutionPrompt(relativePlan, "current"), { deliverAs: "followUp" });
+	}
+
+	async function beginNewSessionExecution(ctx: ExtensionCommandContext): Promise<void> {
+		if (!lastPlanPath) {
+			ctx.ui.notify("No approved plan is available to execute.", "error");
+			return;
+		}
+		await ctx.waitForIdle();
+		const planPathToExecute = lastPlanPath;
+		const planTitleToExecute = lastPlanTitle;
+		const relativePlan = relativeToCwd(ctx.cwd, planPathToExecute);
+		const parentSession = ctx.sessionManager.getSessionFile();
+		const state: PlanState = {
+			enabled: false,
+			executing: true,
+			planThinking,
+			normalThinking,
+			lastPlanPath: planPathToExecute,
+			lastPlanTitle: planTitleToExecute,
+			lastPlanStatus: "approved",
+		};
+		const result = await ctx.newSession({
+			parentSession,
+			setup: async (sessionManager) => {
+				sessionManager.appendCustomEntry("pi-plan", state);
+			},
+			withSession: async (replacementCtx) => {
+				await replacementCtx.sendUserMessage(buildExecutionPrompt(relativePlan, "new"));
+			},
+		});
+		if (result.cancelled) ctx.ui.notify("New-session execution cancelled.", "info");
+	}
+
 	pi.registerFlag("plan", {
 		description: "Start in pi-plan read-only planning mode",
 		type: "boolean",
@@ -219,7 +314,10 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		label: "Write Plan",
 		description: `Write or replace the current implementation plan as Markdown under ${PLAN_DIR}/. Use in plan mode when the plan is ready for user review.`,
 		promptSnippet: `Write the implementation plan to ${PLAN_DIR}/ as a Markdown file for user review`,
-		promptGuidelines: [`Use ${PLAN_TOOL} in plan mode after repository exploration; do not use edit/write for implementation until the user approves the plan.`],
+		promptGuidelines: [
+			`Use ${PLAN_TOOL} in plan mode after repository exploration; do not use edit/write for implementation until the user approves the plan.`,
+			`Do not call ${PLAN_TOOL} while blocking user-answerable questions remain; use ${PLAN_QUESTION_TOOL} first.`,
+		],
 		parameters: Type.Object({
 			title: Type.String({ description: "Short human-readable title for the plan" }),
 			content: Type.String({ description: "Complete Markdown plan content" }),
@@ -237,8 +335,11 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 			lastPlanTitle = typedParams.title.trim() || "Plan";
 			lastPlanStatus = isPlanStatus(typedParams.status) ? typedParams.status : "draft";
 			persistState();
+			const warning = hasOpenQuestionWarning(content)
+				? ` If the plan contains blocking user-answerable open questions, call ${PLAN_QUESTION_TOOL} before requesting approval.`
+				: "";
 			return {
-				content: [{ type: "text", text: `Plan written to ${relativeToCwd(ctx.cwd, destination)}. Ask the user to approve, refine, or keep planning.` }],
+				content: [{ type: "text", text: `Plan written to ${relativeToCwd(ctx.cwd, destination)}. If no blocking user-answerable questions remain, ask the user to approve, refine, execute in current session, execute in a new session, or keep planning.${warning}` }],
 				details: { path: destination, title: lastPlanTitle, status: lastPlanStatus },
 			};
 		},
@@ -324,6 +425,17 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 		handler: async (args, ctx) => handlePlanCommand(args, ctx),
 	});
 
+	pi.registerCommand(PLAN_EXECUTE_COMMAND, {
+		description: "Internal pi-plan execution bridge",
+		handler: async (args, ctx) => {
+			if (args.trim() !== "new") {
+				ctx.ui.notify(`Usage: /${PLAN_EXECUTE_COMMAND} new`, "warning");
+				return;
+			}
+			await beginNewSessionExecution(ctx);
+		},
+	});
+
 	pi.registerShortcut("ctrl+alt+p", {
 		description: "Toggle pi-plan mode",
 		handler: async (ctx) => {
@@ -333,24 +445,32 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.on("session_start", async (_event, ctx) => {
+		const preferences = await loadPreferences();
 		const entries = ctx.sessionManager.getEntries();
 		const saved = entries
 			.filter((entry: { type: string; customType?: string }) => entry.type === "custom" && entry.customType === "pi-plan")
 			.pop() as { data?: PlanState } | undefined;
+		if (preferences) {
+			planThinking = preferences.planThinking;
+			normalThinking = preferences.normalThinking;
+		}
 		if (saved?.data) {
 			planModeEnabled = saved.data.enabled ?? planModeEnabled;
 			executionMode = saved.data.executing ?? executionMode;
-			planThinking = saved.data.planThinking ?? planThinking;
-			normalThinking = saved.data.normalThinking ?? normalThinking;
+			if (!preferences && isThinkingLevel(saved.data.planThinking)) planThinking = saved.data.planThinking;
+			if (!preferences && isThinkingLevel(saved.data.normalThinking)) normalThinking = saved.data.normalThinking;
 			toolsBeforePlan = saved.data.toolsBeforePlan ?? toolsBeforePlan;
 			lastPlanPath = saved.data.lastPlanPath ?? lastPlanPath;
 			lastPlanTitle = saved.data.lastPlanTitle ?? lastPlanTitle;
 			lastPlanStatus = saved.data.lastPlanStatus ?? lastPlanStatus;
 		}
+		if (!preferences) persistPreferences();
 		if (pi.getFlag("plan") === true) planModeEnabled = true;
 		if (planModeEnabled) {
 			enablePlanTools();
 			applyThinking(planThinking);
+		} else if (executionMode) {
+			applyThinking(normalThinking);
 		}
 		setStatus(ctx);
 		clearPlanWidget(ctx);
@@ -379,7 +499,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. 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.`,
+					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- Before calling ${PLAN_TOOL}, if any consequential, user-answerable decision remains, call ${PLAN_QUESTION_TOOL} and wait for the answer. Do not place blocking user decisions in the final plan as open questions.\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, non-blocking open questions, and rejected alternatives if relevant.`,
 					display: false,
 				},
 			};
@@ -405,22 +525,29 @@ export default function piPlanExtension(pi: ExtensionAPI): void {
 	pi.on("agent_end", async (_event, ctx) => {
 		if (!planModeEnabled || !lastPlanPath || !ctx.hasUI) return;
 		const relativePlan = relativeToCwd(ctx.cwd, lastPlanPath);
+		const currentSessionChoice = `Execute in current session (${formatContextUsage(ctx)})`;
+		const newSessionChoice = "Execute in new session (fresh context)";
 		const choice = await ctx.ui.select(`Plan written: ${relativePlan}`, [
-			"Approve and execute",
+			currentSessionChoice,
+			newSessionChoice,
 			"Approve only (exit plan mode)",
 			"Keep planning",
 			"Refine with feedback",
 		]);
-		if (choice === "Approve and execute") {
+		if (choice === currentSessionChoice) {
+			beginCurrentSessionExecution(ctx, relativePlan);
+		} else if (choice === newSessionChoice) {
 			planModeEnabled = false;
-			executionMode = true;
+			executionMode = false;
 			lastPlanStatus = "approved";
 			restoreTools();
 			applyThinking(normalThinking);
 			setStatus(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" });
+			persistPreferences();
+			ctx.ui.setEditorText(`/${PLAN_EXECUTE_COMMAND} new`);
+			ctx.ui.notify("Press Enter to start execution in a new session.", "info");
 		} else if (choice === "Approve only (exit plan mode)") {
 			lastPlanStatus = "approved";
 			leavePlanMode(ctx);

package/package.json

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