@janvitos/pi-plan-build 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 janvitos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# Pi Plan & Build
+
+**Plan safely, approve explicitly, then implement here or in a clean session.**
+
+A global [Pi coding agent](https://github.com/badlogic/pi-mono) extension that adds persistent **Plan** and **Build** modes, guarded plan-file editing, interactive planning questions, full-plan review, explicit approval, and clean-session implementation handoffs.
+
+## Features
+
+- New sessions start in **Build** mode.
+- Bare `Tab` cycles **Build → Plan → Build** and replaces normal Tab autocomplete.
+- `[Build]` and `[Plan]` status indicators in Pi's footer.
+- `/plan`, `/build`, and the `--plan` startup flag.
+- Per-session plans at `~/.pi/agent/plans/<session-id>.md`.
+- In Plan mode, built-in `edit` and `write` are restricted to the exact plan file.
+- Interactive `question`, `plan_enter`, and `plan_exit` tools.
+- The complete saved plan is rendered in the transcript before approval—without the built-in write preview's truncation.
+- Three approval actions:
+  - **Switch to Build and implement here**
+  - **Start fresh and implement**
+  - **Stay in Plan mode**
+- Staying in Plan mode produces a durable acknowledgement and stops the run until the user responds.
+- Mode state survives reloads, resumes, and forks.
+
+## Requirements
+
+- Pi `0.84.1` or newer
+- Node.js `22.6` or newer for the test command
+- TUI or RPC UI support for interactive questions and approval dialogs
+
+## Install
+
+Install the npm package with Pi's package manager:
+
+```bash
+pi install npm:@janvitos/pi-plan-build
+```
+
+Pi stores npm packages under `~/.pi/agent/npm/`; `~/.pi/agent/extensions/` is reserved for directly auto-discovered extension files and directories. Start a new Pi process after installation, or run `/reload` in an existing session.
+
+### Install from GitHub
+
+```bash
+pi install git:github.com/janvitos/pi-plan-build
+```
+
+### Local development install
+
+```bash
+git clone https://github.com/janvitos/pi-plan-build.git ~/src/pi-plan-build
+ln -s ~/src/pi-plan-build ~/.pi/agent/extensions/pi-plan-build
+```
+
+Do not install more than one npm, Git, or local copy at the same time; duplicate extension loads cause command and flag conflicts.
+
+## Usage
+
+| Action | Result |
+| --- | --- |
+| `Tab` | Cycle Build and Plan |
+| `/plan` | Select Plan mode |
+| `/build` | Select Build mode |
+| `pi --plan` | Start a new session in Plan mode |
+| `/build-fresh` | Confirm a pending clean-session implementation |
+
+The agent may also enter Plan mode with `plan_enter` when planning or investigation is safer than immediate execution.
+
+### Plan approval
+
+When planning is complete, `plan_exit` displays the entire persisted plan and asks whether to:
+
+1. implement in the current session;
+2. prepare a clean linked implementation session; or
+3. stay in Plan mode.
+
+Selecting **Start fresh and implement** stops the current run and pre-fills `/build-fresh`. Press Enter to confirm. Pi only exposes session creation to user-invoked command contexts, so this confirmation is required. The command creates a linked child session, copies the approved plan to its canonical plan file, switches it to Build, and starts implementation without transferring the planning conversation.
+
+Selecting **Stay in Plan mode** displays:
+
+> Staying in Plan mode. Let me know when you’re ready to revise or implement the plan.
+
+The agent then stops and waits for the next user message.
+
+## Plan-mode permissions
+
+Normal tools remain visible so the model can inspect the project. While a Plan run is active:
+
+- `edit` and `write` are permitted only for the canonical session plan file;
+- other `edit` and `write` calls are blocked by the extension;
+- bash is not restricted at the permission layer, but the Plan prompt explicitly permits read-only exploration only.
+
+This mirrors the intended permission-oriented workflow rather than hiding normal tool schemas.
+
+## Design and attribution
+
+Pi Plan & Build is an independent extension with its own workflow and UI behavior. Its original mode prompts and transition semantics were informed by OpenCode 1.18.16, while clean-session implementation ideas were informed by the former `pi-plan-mode` extension. Those behaviors have since been adapted and extended for Pi; this project is not affiliated with either project.
+
+The Plan workflow uses Pi's native exploration tools directly and does not bundle or require subagents.
+
+## Development
+
+```bash
+npm test
+npm pack --dry-run
+```
+
+The tests cover state decoding, safe plan paths, mutation restrictions, deferred transitions, complete plan rendering, approval decisions, stop behavior, fresh-session handoff content, and question formatting.
+
+### Publishing
+
+After authenticating an npm account with access to the `@janvitos` scope, validate and publish the public package:
+
+```bash
+npm publish --dry-run
+npm publish
+```
+
+The `prepublishOnly` hook runs the test suite before either command publishes a package.
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,417 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CustomEditor, getAgentDir, getMarkdownTheme, type EntryRenderer, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, Markdown, matchesKey, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { registerQuestionTool } from "./question-ui.ts";
+import {
+	buildPlanReminder,
+	PLAN_ENTER_DESCRIPTION,
+	PLAN_EXIT_DESCRIPTION,
+	PLAN_TO_BUILD_REMINDER,
+} from "./prompts.ts";
+import {
+	applyManualSelection,
+	buildFreshImplementationHandoff,
+	buildPlanExitFreshResult,
+	buildPlanExitStayResult,
+	buildPlanReviewMessage,
+	classifyPlanExitChoice,
+	decodeModeState,
+	isAllowedPlanMutation,
+	makePlanPath,
+	nextMode,
+	PLAN_EXIT_APPROVE_CHOICE,
+	PLAN_EXIT_FRESH_CHOICE,
+	PLAN_EXIT_STAY_ACKNOWLEDGEMENT,
+	PLAN_EXIT_STAY_CHOICE,
+	type Mode,
+	unique,
+} from "./utils.ts";
+
+const STATE_TYPE = "pi-plan-build-state";
+const LEGACY_STATE_TYPE = "opencode-modes-state";
+const PLAN_REVIEW_ENTRY_TYPE = "pi-plan-build-review";
+const LEGACY_PLAN_REVIEW_ENTRY_TYPE = "opencode-plan-review";
+const MODE_NOTICE_ENTRY_TYPE = "pi-plan-build-notice";
+const LEGACY_MODE_NOTICE_ENTRY_TYPE = "opencode-mode-notice";
+const STATUS_KEY = "pi-plan-build-mode";
+const MANAGED_TOOLS = new Set(["question", "plan_enter", "plan_exit"]);
+const MODE_ADDED_TOOLS = new Set([...MANAGED_TOOLS, "edit", "write"]);
+const EMPTY_PARAMETERS = Type.Object({});
+
+type PendingReminder = "plan" | "build" | undefined;
+interface StoredState {
+	version: 1;
+	selectedMode: Mode;
+	pendingReminder?: "plan" | "build";
+	toolsBeforeModes?: string[];
+}
+
+function shorten(filePath: string, cwd: string): string {
+	const relative = path.relative(cwd, filePath);
+	if (relative && !relative.startsWith("..") && !path.isAbsolute(relative)) return relative;
+	const home = os.homedir();
+	return filePath.startsWith(`${home}${path.sep}`) ? `~${filePath.slice(home.length)}` : filePath;
+}
+
+export default function planBuildModes(pi: ExtensionAPI): void {
+	let selectedMode: Mode = "build";
+	let runMode: Mode | undefined;
+	let pendingReminder: PendingReminder;
+	let planPath = "";
+	let toolsBeforeModes: string[] = [];
+	let currentContext: ExtensionContext | undefined;
+	let freshImplementationPlan: string | undefined;
+
+	pi.registerFlag("plan", {
+		description: "Start in Plan mode",
+		type: "boolean",
+		default: false,
+	});
+
+	registerQuestionTool(pi);
+	const renderPlanReview: EntryRenderer<{ plan: string }> = (entry) => {
+		const plan = typeof entry.data?.plan === "string" ? entry.data.plan : "Plan unavailable";
+		return new Markdown(buildPlanReviewMessage(plan), 0, 0, getMarkdownTheme());
+	};
+	const renderModeNotice: EntryRenderer<{ message: string }> = (entry, _options, theme) => {
+		const message = typeof entry.data?.message === "string" ? entry.data.message : "Plan mode unchanged.";
+		return new Text(theme.fg("warning", message), 0, 0);
+	};
+	pi.registerEntryRenderer<{ plan: string }>(PLAN_REVIEW_ENTRY_TYPE, renderPlanReview);
+	pi.registerEntryRenderer<{ plan: string }>(LEGACY_PLAN_REVIEW_ENTRY_TYPE, renderPlanReview);
+	pi.registerEntryRenderer<{ message: string }>(MODE_NOTICE_ENTRY_TYPE, renderModeNotice);
+	pi.registerEntryRenderer<{ message: string }>(LEGACY_MODE_NOTICE_ENTRY_TYPE, renderModeNotice);
+
+	function stateData(): StoredState {
+		return { version: 1, selectedMode, pendingReminder, toolsBeforeModes };
+	}
+
+	function persist(): void {
+		pi.appendEntry(STATE_TYPE, stateData());
+	}
+
+	function updateStatus(ctx: ExtensionContext): void {
+		const label = selectedMode === "plan"
+			? ctx.ui.theme.fg("warning", "Plan")
+			: ctx.ui.theme.fg("border", "Build");
+		ctx.ui.setStatus(STATUS_KEY, `[${label}]`);
+	}
+
+	function discoverUnmanagedTools(): void {
+		const additions = pi.getActiveTools().filter((name) => !MODE_ADDED_TOOLS.has(name) && !toolsBeforeModes.includes(name));
+		toolsBeforeModes = unique([...toolsBeforeModes, ...additions]);
+	}
+
+	function applyTools(mode: Mode): void {
+		discoverUnmanagedTools();
+		const base = [...toolsBeforeModes];
+		if (mode === "plan") {
+			pi.setActiveTools(unique([...base, "edit", "write", "question", "plan_exit"]));
+		} else {
+			pi.setActiveTools(unique([...base, "question", "plan_enter"]));
+		}
+	}
+
+	async function ensurePlanDirectory(): Promise<void> {
+		await fs.promises.mkdir(path.dirname(planPath), { recursive: true });
+	}
+
+	async function selectMode(mode: Mode, ctx: ExtensionContext, source: "manual" | "tool"): Promise<void> {
+		if (mode === selectedMode && (source === "manual" || mode === runMode)) return;
+		const previous = selectedMode;
+		if (mode === "plan") await ensurePlanDirectory();
+
+		if (source === "manual") {
+			const next = applyManualSelection(mode, runMode, ctx.isIdle());
+			selectedMode = next.selectedMode;
+			runMode = next.runMode;
+			pendingReminder = previous === mode ? pendingReminder : mode;
+			if (ctx.isIdle()) applyTools(mode);
+		} else {
+			selectedMode = mode;
+			runMode = mode;
+			pendingReminder = undefined;
+			applyTools(mode);
+		}
+		updateStatus(ctx);
+		persist();
+		ctx.ui.notify(`${mode === "plan" ? "Plan" : "Build"} mode selected`, "info");
+	}
+
+	pi.registerCommand("plan", {
+		description: "Switch to Plan mode",
+		handler: async (_args, ctx) => selectMode("plan", ctx, "manual"),
+	});
+	pi.registerCommand("build", {
+		description: "Switch to Build mode",
+		handler: async (_args, ctx) => selectMode("build", ctx, "manual"),
+	});
+	pi.registerCommand("build-fresh", {
+		description: "Start a clean linked session and implement the plan selected in plan_exit",
+		handler: async (_args, ctx) => {
+			const plan = freshImplementationPlan;
+			if (!plan) {
+				ctx.ui.notify("No fresh implementation is pending. Choose ‘Start fresh and implement’ from plan_exit first.", "warning");
+				return;
+			}
+			if (selectedMode !== "plan") {
+				freshImplementationPlan = undefined;
+				ctx.ui.notify("Fresh implementation is no longer available because Plan mode is not active.", "warning");
+				return;
+			}
+			if (ctx.mode === "print" || ctx.mode === "json") {
+				throw new Error("Fresh implementation requires TUI or RPC mode");
+			}
+			if (!ctx.model) {
+				ctx.ui.notify("Cannot start implementation because no model is selected.", "warning");
+				return;
+			}
+
+			freshImplementationPlan = undefined;
+			const parentSession = ctx.sessionManager.getSessionFile();
+			const sourceTools = [...toolsBeforeModes];
+			const handoff = buildFreshImplementationHandoff(plan);
+			let destinationPlanPath = "";
+			let setupError: string | undefined;
+			let kickoffError: string | undefined;
+			try {
+				const result = await ctx.newSession({
+					...(parentSession ? { parentSession } : {}),
+					setup: async (sessionManager) => {
+						try {
+							destinationPlanPath = makePlanPath(
+								path.join(getAgentDir(), "plans"),
+								sessionManager.getSessionId(),
+							);
+							await fs.promises.mkdir(path.dirname(destinationPlanPath), { recursive: true });
+							await fs.promises.writeFile(destinationPlanPath, plan, "utf8");
+							sessionManager.appendCustomEntry(STATE_TYPE, {
+								version: 1,
+								selectedMode: "build",
+								pendingReminder: "build",
+								toolsBeforeModes: sourceTools,
+							} satisfies StoredState);
+						} catch (error: unknown) {
+							setupError = error instanceof Error ? error.message : String(error);
+						}
+					},
+					withSession: async (replacementCtx) => {
+						if (setupError) {
+							replacementCtx.ui.setEditorText(handoff);
+							replacementCtx.ui.notify(
+								`Fresh session opened, but setup failed: ${setupError}. The implementation request is in the editor.`,
+								"error",
+							);
+							return;
+						}
+						try {
+							await replacementCtx.sendUserMessage(handoff);
+							replacementCtx.ui.notify(
+								`Fresh implementation session started with plan ${shorten(destinationPlanPath, replacementCtx.cwd)}.`,
+								"info",
+							);
+						} catch (error: unknown) {
+							kickoffError = error instanceof Error ? error.message : String(error);
+							replacementCtx.ui.setEditorText(handoff);
+							replacementCtx.ui.notify(
+								`Fresh session opened, but implementation did not start: ${kickoffError}. The request is in the editor.`,
+								"error",
+							);
+						}
+					},
+				});
+				if (result.cancelled) {
+					freshImplementationPlan = plan;
+					ctx.ui.notify("Fresh implementation cancelled; the source plan remains available.", "info");
+				}
+			} catch (error: unknown) {
+				freshImplementationPlan = plan;
+				const detail = error instanceof Error ? error.message : String(error);
+				try {
+					ctx.ui.notify(`Unable to start a fresh implementation session: ${detail}`, "error");
+				} catch {
+					// The source command context may be stale after partial session replacement.
+				}
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "plan_enter",
+		label: "Enter Plan Mode",
+		description: PLAN_ENTER_DESCRIPTION,
+		parameters: EMPTY_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			await selectMode("plan", ctx, "tool");
+			const exists = fs.existsSync(planPath);
+			const info = exists
+				? `A plan file already exists at ${planPath}. You can read it and make incremental edits using the edit tool.`
+				: `No plan file exists yet. You should create your plan at ${planPath} using the write tool.`;
+			return {
+				content: [{ type: "text", text: buildPlanReminder(info) }],
+				details: { mode: "plan", planPath },
+			};
+		},
+		renderCall(_args, theme) {
+			return new Text(theme.fg("toolTitle", theme.bold("Enter Plan mode")), 0, 0);
+		},
+		renderResult(_result, _options, theme) {
+			return new Text(theme.fg("success", "Switched to Plan mode"), 0, 0);
+		},
+	});
+
+	pi.registerTool({
+		name: "plan_exit",
+		label: "Exit Plan Mode",
+		description: PLAN_EXIT_DESCRIPTION,
+		parameters: EMPTY_PARAMETERS,
+		executionMode: "sequential",
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			if (!ctx.hasUI) throw new Error("plan_exit requires an interactive TUI or RPC client");
+			let plan: string;
+			try {
+				plan = await fs.promises.readFile(planPath, "utf8");
+			} catch (error: unknown) {
+				const detail = error instanceof Error ? error.message : String(error);
+				throw new Error(`Cannot request plan approval because the plan file could not be read: ${detail}`);
+			}
+			if (!plan.trim()) throw new Error("Cannot request plan approval because the plan file is empty");
+			pi.appendEntry(PLAN_REVIEW_ENTRY_TYPE, { plan, planPath });
+			const displayPath = shorten(planPath, ctx.cwd);
+			const choice = await ctx.ui.select(
+				`Build Agent: Plan at ${displayPath} is complete. What would you like to do?`,
+				[PLAN_EXIT_APPROVE_CHOICE, PLAN_EXIT_FRESH_CHOICE, PLAN_EXIT_STAY_CHOICE],
+			);
+			const decision = classifyPlanExitChoice(choice);
+			if (decision === "stay") {
+				freshImplementationPlan = undefined;
+				pi.appendEntry(MODE_NOTICE_ENTRY_TYPE, { message: PLAN_EXIT_STAY_ACKNOWLEDGEMENT });
+				return buildPlanExitStayResult(planPath, choice === undefined);
+			}
+			if (decision === "implement-fresh") {
+				freshImplementationPlan = plan;
+				ctx.ui.setEditorText("/build-fresh");
+				return buildPlanExitFreshResult(planPath);
+			}
+			freshImplementationPlan = undefined;
+			await selectMode("build", ctx, "tool");
+			return {
+				content: [
+					{
+						type: "text",
+						text: `${PLAN_TO_BUILD_REMINDER}\n\nA plan file exists at ${planPath}. The plan has been approved; execute the plan now.`,
+					},
+				],
+				details: { approved: true, mode: "build", planPath },
+			};
+		},
+		renderCall(_args, theme) {
+			return new Text(theme.fg("toolTitle", theme.bold("Request plan approval")), 0, 0);
+		},
+		renderResult(result, _options, theme, context) {
+			const details = result.details as { approved?: boolean; action?: string } | undefined;
+			if (details?.action === "implement-fresh" && !context.isError) {
+				return new Text(
+					theme.fg("success", "Clean-session implementation selected — press Enter to run /build-fresh."),
+					0,
+					0,
+				);
+			}
+			if (details?.approved === true && !context.isError) {
+				return new Text(theme.fg("success", "Plan approved; switched to Build mode"), 0, 0);
+			}
+			return new Text(theme.fg("warning", PLAN_EXIT_STAY_ACKNOWLEDGEMENT), 0, 0);
+		},
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (runMode !== "plan" || (event.toolName !== "edit" && event.toolName !== "write")) return;
+		const inputPath = (event.input as { path?: unknown }).path;
+		if (isAllowedPlanMutation(ctx.cwd, inputPath, planPath)) return;
+		return {
+			block: true,
+			reason: `Plan mode only permits edit/write access to the plan file: ${planPath}`,
+		};
+	});
+
+	pi.on("before_agent_start", async (_event, ctx) => {
+		runMode = selectedMode;
+		applyTools(runMode);
+		let content: string | undefined;
+		if (runMode === "plan") {
+			await ensurePlanDirectory();
+			const exists = fs.existsSync(planPath);
+			content = buildPlanReminder(
+				exists
+					? `A plan file already exists at ${planPath}. You can read it and make incremental edits using the edit tool.`
+					: `No plan file exists yet. You should create your plan at ${planPath} using the write tool.`,
+			);
+		} else if (pendingReminder === "build") {
+			content = PLAN_TO_BUILD_REMINDER;
+			if (fs.existsSync(planPath)) content += `\n\nA plan file exists at ${planPath}. You should execute the plan defined within it.`;
+		}
+		pendingReminder = undefined;
+		persist();
+		if (!content) return;
+		return { message: { customType: "pi-plan-build-reminder", content, display: false } };
+	});
+
+	pi.on("agent_settled", async (_event, ctx) => {
+		runMode = undefined;
+		applyTools(selectedMode);
+		updateStatus(ctx);
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		currentContext = ctx;
+		const entries = ctx.sessionManager.getEntries();
+		const latest = entries
+			.filter(
+				(entry: any) =>
+					entry.type === "custom" &&
+					(entry.customType === STATE_TYPE || entry.customType === LEGACY_STATE_TYPE),
+			)
+			.pop() as { data?: unknown } | undefined;
+		const decoded = decodeModeState(latest?.data);
+		const raw = latest?.data as StoredState | undefined;
+		selectedMode = decoded?.selectedMode ?? (pi.getFlag("plan") === true ? "plan" : "build");
+		pendingReminder = raw?.pendingReminder ?? (decoded ? undefined : pi.getFlag("plan") === true ? "plan" : undefined);
+		toolsBeforeModes = Array.isArray(raw?.toolsBeforeModes)
+			? raw.toolsBeforeModes.filter((name): name is string => typeof name === "string" && !MANAGED_TOOLS.has(name))
+			: pi.getActiveTools().filter((name) => !MANAGED_TOOLS.has(name));
+		planPath = makePlanPath(path.join(getAgentDir(), "plans"), ctx.sessionManager.getSessionId());
+		if (selectedMode === "plan") await ensurePlanDirectory();
+		applyTools(selectedMode);
+		updateStatus(ctx);
+
+		if (ctx.mode === "tui") {
+			class ModeEditor extends CustomEditor {
+				onCycle?: () => void;
+				override handleInput(data: string): void {
+					if (matchesKey(data, Key.tab)) {
+						this.onCycle?.();
+						return;
+					}
+					super.handleInput(data);
+				}
+			}
+			ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+				const editor = new ModeEditor(tui, theme, keybindings);
+				editor.onCycle = () => {
+					if (currentContext) void selectMode(nextMode(selectedMode), currentContext, "manual");
+				};
+				return editor;
+			});
+		}
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		ctx.ui.setEditorComponent(undefined);
+		currentContext = undefined;
+	});
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@janvitos/pi-plan-build",
+  "version": "0.1.0",
+  "description": "Plan safely, approve explicitly, then implement here or in a clean session.",
+  "type": "module",
+  "license": "MIT",
+  "author": "janvitos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/janvitos/pi-plan-build.git"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-coding-agent",
+    "plan-mode",
+    "build-mode",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=22.6"
+  },
+  "files": [
+    "index.ts",
+    "prompts.ts",
+    "question-ui.ts",
+    "utils.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test utils.test.ts",
+    "prepublishOnly": "npm test"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  }
+}

package/prompts.ts

@@ -0,0 +1,69 @@
+// Prompt text pinned to OpenCode 1.18.16. The subagent phases are intentionally
+// adapted to direct Pi exploration/design, as documented in README.md.
+
+export const PLAN_TO_BUILD_REMINDER = `<system-reminder>
+Your operational mode has changed from plan to build.
+You are no longer in read-only mode.
+You are permitted to make file changes, run shell commands, and utilize your arsenal of tools as needed.
+</system-reminder>`;
+
+export function buildPlanReminder(planInfo: string): string {
+	return `<system-reminder>
+Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supersedes any other instructions you have received.
+
+## Plan File Info:
+${planInfo}
+You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.
+
+## Plan Workflow
+
+### Phase 1: Initial Understanding
+Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions.
+
+1. Focus on understanding the user's request and the code associated with their request.
+2. Explore the codebase directly with Pi's read, grep, find, ls, and read-only shell operations. Read the minimum set of high-value files needed to understand existing patterns and testing.
+3. After exploring the code, use the question tool to clarify ambiguities in the user request up front.
+
+### Phase 2: Design
+Goal: Design an implementation approach.
+
+Design the implementation directly based on the user's intent and your exploration results. Consider simplicity, correctness, maintainability, existing patterns, edge cases, and verification. Skip extended design only for truly trivial tasks such as typo fixes, single-line changes, or simple renames.
+
+### Phase 3: Review
+Goal: Review the design and ensure alignment with the user's intentions.
+1. Read the critical files identified during exploration to deepen your understanding.
+2. Ensure that the design aligns with the user's original request.
+3. Use question tool to clarify any remaining questions with the user.
+
+### Phase 4: Final Plan
+Goal: Write your final plan to the plan file (the only file you can edit).
+- Include only your recommended approach, not all alternatives.
+- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively.
+- Include the paths of critical files to be modified.
+- Include a verification section describing how to test the changes end-to-end (run the code, use available tools, run tests).
+
+### Phase 5: Call plan_exit tool
+At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call plan_exit to indicate to the user that you are done planning.
+This is critical - your turn should only end with either asking the user a question or calling plan_exit. Do not stop unless it's for these 2 reasons.
+
+**Important:** Use question tool to clarify requirements/approach, use plan_exit to request plan approval. Do NOT use question tool to ask "Is this plan okay?" - that's what plan_exit does.
+
+NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.
+</system-reminder>`;
+}
+
+export const PLAN_ENTER_DESCRIPTION = `Use this tool when the user asks you to plan, when a request needs investigation before implementation, or when switching to the plan agent is the safest next step. The tool changes the current continuation to Plan mode.`;
+
+export const PLAN_EXIT_DESCRIPTION = `Use this tool when you have completed the planning phase and are ready to exit plan agent.
+
+This tool displays the complete plan and asks the user whether to implement it in this session, prepare a clean-session implementation, or stay in Plan mode.
+
+Call this tool:
+- After you have written a complete plan to the plan file
+- After you have clarified any questions with the user
+- When you are confident the plan is ready for implementation
+
+Do NOT call this tool:
+- Before you have created or finalized the plan
+- If you still have unanswered questions about the implementation
+- If the user has indicated they want to continue planning`;

package/question-ui.ts

@@ -0,0 +1,111 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { formatQuestionAnswers, type QuestionAnswerData } from "./utils.ts";
+
+const OptionSchema = Type.Object({
+	label: Type.String({ description: "Display label for the option" }),
+	description: Type.Optional(Type.String({ description: "Explanation shown with the option" })),
+});
+
+const PromptSchema = Type.Object({
+	question: Type.String({ description: "The question to ask" }),
+	header: Type.String({ description: "Short header (12 characters or fewer)", maxLength: 12 }),
+	options: Type.Array(OptionSchema, { minItems: 2, maxItems: 4 }),
+	multiple: Type.Optional(Type.Boolean({ description: "Allow more than one selection" })),
+	custom: Type.Optional(Type.Boolean({ description: "Allow a custom answer; defaults to true" })),
+});
+
+export const QuestionParameters = Type.Object({
+	questions: Type.Array(PromptSchema, { minItems: 1, description: "Questions to ask the user" }),
+});
+
+export type QuestionAnswer = QuestionAnswerData;
+
+async function askOne(
+	ctx: any,
+	prompt: {
+		question: string;
+		header: string;
+		options: Array<{ label: string; description?: string }>;
+		multiple?: boolean;
+		custom?: boolean;
+	},
+): Promise<QuestionAnswer> {
+	const allowCustom = prompt.custom !== false;
+	const labels = prompt.options.map((option) =>
+		option.description ? `${option.label} — ${option.description}` : option.label,
+	);
+	const selected: string[] = [];
+	let usedCustom = false;
+
+	if (!prompt.multiple) {
+		const choices = [...labels, ...(allowCustom ? ["Type your own answer"] : [])];
+		const choice = await ctx.ui.select(`${prompt.header}: ${prompt.question}`, choices);
+		if (!choice) throw new Error("User cancelled the question");
+		if (allowCustom && choice === "Type your own answer") {
+			const custom = await ctx.ui.input(prompt.header, prompt.question);
+			if (!custom?.trim()) throw new Error("User cancelled the question");
+			selected.push(custom.trim());
+			usedCustom = true;
+		} else {
+			selected.push(prompt.options[labels.indexOf(choice)]?.label ?? choice);
+		}
+	} else {
+		const remaining = prompt.options.map((option) => option.label);
+		while (true) {
+			const choices = [
+				...remaining.map((label) => `Add: ${label}`),
+				...(allowCustom ? ["Add a custom answer"] : []),
+				...(selected.length ? [`Done (${selected.join(", ")})`] : []),
+			];
+			const choice = await ctx.ui.select(`${prompt.header}: ${prompt.question}`, choices);
+			if (!choice) throw new Error("User cancelled the question");
+			if (choice.startsWith("Done (")) break;
+			if (choice === "Add a custom answer") {
+				const custom = await ctx.ui.input(prompt.header, prompt.question);
+				if (custom?.trim()) {
+					selected.push(custom.trim());
+					usedCustom = true;
+				}
+				continue;
+			}
+			const label = choice.slice("Add: ".length);
+			selected.push(label);
+			remaining.splice(remaining.indexOf(label), 1);
+			if (remaining.length === 0 && !allowCustom) break;
+		}
+	}
+
+	return { question: prompt.question, header: prompt.header, answers: selected, custom: usedCustom };
+}
+
+export function registerQuestionTool(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "question",
+		label: "Question",
+		description: `Use this tool when you need to ask the user questions during execution. This allows you to gather preferences, clarify ambiguous instructions, get implementation decisions, or offer choices. When custom is enabled (default), do not add an Other option yourself. Put the recommended option first and suffix its label with "(Recommended)".`,
+		parameters: QuestionParameters,
+		executionMode: "sequential",
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			if (!ctx.hasUI) throw new Error("The question tool requires an interactive TUI or RPC client");
+			if (params.questions.length === 0) throw new Error("At least one question is required");
+			const answers: QuestionAnswer[] = [];
+			for (const prompt of params.questions) answers.push(await askOne(ctx, prompt));
+			const formatted = formatQuestionAnswers(answers);
+			return {
+				content: [{ type: "text", text: `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.` }],
+				details: { answers },
+			};
+		},
+		renderCall(args, theme) {
+			const count = Array.isArray(args.questions) ? args.questions.length : 0;
+			return new Text(theme.fg("toolTitle", theme.bold(`question (${count})`)), 0, 0);
+		},
+		renderResult(result, _options, theme) {
+			const details = result.details as { answers?: QuestionAnswer[] } | undefined;
+			if (!details?.answers) return new Text(theme.fg("warning", "Question cancelled"), 0, 0);
+			return new Text(details.answers.map((a) => `${theme.fg("success", "✓")} ${a.header}: ${a.answers.join(", ")}`).join("\n"), 0, 0);
+		},
+	});
+}

package/utils.ts

@@ -0,0 +1,121 @@
+import path from "node:path";
+
+export type Mode = "build" | "plan";
+
+export const PLAN_EXIT_APPROVE_CHOICE = "Switch to Build and implement here";
+export const PLAN_EXIT_FRESH_CHOICE = "Start fresh and implement";
+export const PLAN_EXIT_STAY_CHOICE = "Stay in Plan mode";
+export const PLAN_EXIT_STAY_ACKNOWLEDGEMENT =
+	"Staying in Plan mode. Let me know when you’re ready to revise or implement the plan.";
+
+export type PlanExitDecision = "implement-here" | "implement-fresh" | "stay";
+
+export function classifyPlanExitChoice(choice: string | undefined): PlanExitDecision {
+	if (choice === PLAN_EXIT_APPROVE_CHOICE) return "implement-here";
+	if (choice === PLAN_EXIT_FRESH_CHOICE) return "implement-fresh";
+	return "stay";
+}
+
+export function buildPlanReviewMessage(plan: string): string {
+	return `# Plan for Review\n\n${plan}`;
+}
+
+export function buildPlanExitFreshResult(planPath: string) {
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text: "The user selected clean-session implementation. Stop now; the /build-fresh command has been prepared for the user to submit.",
+			},
+		],
+		details: { approved: true, action: "implement-fresh" as const, mode: "plan" as const, planPath },
+		terminate: true,
+	};
+}
+
+export function buildFreshImplementationHandoff(plan: string): string {
+	return `Plan mode is now disabled. Full tool access is restored. Implement this approved plan now:\n\n${plan}`;
+}
+
+export function buildPlanExitStayResult(planPath: string, cancelled: boolean) {
+	return {
+		content: [
+			{
+				type: "text" as const,
+				text: "The user chose to stay in Plan mode. Stop now and wait for their next message before doing any further planning or taking any other action.",
+			},
+		],
+		details: { approved: false, mode: "plan" as const, planPath, cancelled },
+		terminate: true,
+	};
+}
+
+export interface PersistedModeState {
+	version: 1;
+	selectedMode: Mode;
+}
+
+export function isMode(value: unknown): value is Mode {
+	return value === "build" || value === "plan";
+}
+
+export function decodeModeState(value: unknown): PersistedModeState | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const candidate = value as { version?: unknown; selectedMode?: unknown; mode?: unknown };
+	const mode = isMode(candidate.selectedMode) ? candidate.selectedMode : isMode(candidate.mode) ? candidate.mode : undefined;
+	if (!mode) return undefined;
+	return { version: 1, selectedMode: mode };
+}
+
+export function sanitizeSessionId(value: string | undefined): string {
+	const cleaned = (value ?? "ephemeral")
+		.normalize("NFKC")
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^[-.]+|[-.]+$/g, "")
+		.slice(0, 120);
+	return cleaned || "ephemeral";
+}
+
+export function makePlanPath(plansDir: string, sessionId: string | undefined): string {
+	const root = path.resolve(plansDir);
+	const candidate = path.resolve(root, `${sanitizeSessionId(sessionId)}.md`);
+	if (path.dirname(candidate) !== root) throw new Error("Generated plan path escaped the plans directory");
+	return candidate;
+}
+
+export function resolveToolPath(cwd: string, inputPath: unknown): string | undefined {
+	if (typeof inputPath !== "string" || inputPath.trim() === "") return undefined;
+	const withoutAt = inputPath.startsWith("@") ? inputPath.slice(1) : inputPath;
+	return path.resolve(cwd, withoutAt);
+}
+
+export function isAllowedPlanMutation(cwd: string, inputPath: unknown, planPath: string): boolean {
+	const resolved = resolveToolPath(cwd, inputPath);
+	return resolved !== undefined && resolved === path.resolve(planPath);
+}
+
+export interface QuestionAnswerData {
+	question: string;
+	header: string;
+	answers: string[];
+	custom: boolean;
+}
+
+export function formatQuestionAnswers(answers: QuestionAnswerData[]): string {
+	return answers.map((answer) => `"${answer.question}"="${answer.answers.length ? answer.answers.join(", ") : "Unanswered"}"`).join(", ");
+}
+
+export function nextMode(mode: Mode): Mode {
+	return mode === "build" ? "plan" : "build";
+}
+
+export function applyManualSelection(selectedMode: Mode, runMode: Mode | undefined, idle: boolean): {
+	selectedMode: Mode;
+	runMode: Mode | undefined;
+} {
+	return { selectedMode, runMode: idle ? selectedMode : runMode };
+}
+
+export function unique(values: string[]): string[] {
+	return [...new Set(values)];
+}