@prjct.app/pi-plan 0.1.3 → 0.2.1

package/CHANGELOG.md

@@ -1,4 +1,10 @@
-# Changelog
+## [0.2.1](https://github.com/prjct-app/pi-plan/compare/v0.2.0...v0.2.1) (2026-09-10)
+
+## [0.2.0](https://github.com/prjct-app/pi-plan/compare/v0.1.3...v0.2.0) (2026-09-10)
+
+### Features
+
+* richer plan TUI, structured planning, and hardened review flow ([582411f](https://github.com/prjct-app/pi-plan/commit/582411f6ab21e45f2d49858629e066b6efee5853))
 
 ## 0.1.3
 

package/CONTRIBUTING.md

@@ -12,3 +12,7 @@
 ## Package documentation
 
 Follow [docs/package.md](docs/package.md) and its versioned official references. Keep README examples consistent with registered commands, distinguish tested behavior from unverified compatibility, and verify `npm run check:package` before release.
+
+## Releases
+
+Merging a releasable change into `main` automatically publishes to npm. Use conventional commit messages and read [Automatic releases](docs/releases.md) before merging. The workflow manages versions and authenticates with npm through OIDC.

package/README.md

@@ -6,6 +6,12 @@ Plan before editing in PI Agent with read-only tool restrictions, an approval st
 
 `@prjct.app/pi-plan` · Planning commands and progress UI; one extension.
 
+## Demo
+
+[![Watch the pi-plan promotional demo](media/pi-plan-demo/poster.png)](https://github.com/prjct-app/pi-plan/raw/refs/heads/main/media/pi-plan-demo/pi-plan-demo.mp4)
+
+[Watch or download the 40-second demo](https://github.com/prjct-app/pi-plan/raw/refs/heads/main/media/pi-plan-demo/pi-plan-demo.mp4). It shows read-only exploration, structured planning, human review, and tracked execution in PI Agent. The film follows the package's monochrome cover identity and uses an original instrumental soundtrack with no voice-over or external samples.
+
 ## Install
 
 Requires Pi installed separately and Node.js **22.19 or later**. Compatibility is tested with **Pi 0.85.1**; newer versions are not yet verified. This is an independent community package.
@@ -24,10 +30,19 @@ For project-only installation, add `-l`: `pi install -l npm:@prjct.app/pi-plan`.
 | --- | --- |
 | `/plan` | Toggle planning mode |
 | `Ctrl+Alt+P` | Toggle planning mode from the keyboard |
-| `/todos` | Show the current plan's steps |
+| `/todos` | Open the current plan dialog with steps, progress, and verification |
 | `pi --plan` | Start with planning enabled after the extension is installed |
 
-Run `/plan`, then ask Pi to investigate a concrete task. Numbered steps under a `Plan:` heading become a progress list. Choose whether to execute when prompted. During execution, `[DONE:n]` markers update completed steps.
+Run `/plan`, then ask Pi to investigate a concrete task. The planner answers with a **Goal**, a short **Approach**, numbered steps under a `Plan:` heading that reference real files, a **Verify** section with the exact validation commands, and any **Risks**.
+
+When a plan is ready, a review dialog offers four actions:
+
+- **Execute the plan** — restore full tools and track step progress.
+- **Refine the plan** — send feedback and keep planning.
+- **Stay in plan mode** — keep read-only exploration.
+- **Discard the plan** — exit plan mode and drop the steps.
+
+During execution, a progress widget shows a completion bar, the current step, and the Verify command; `[DONE:n]` markers update completed steps, the footer shows `▸ plan n/total`, and the transcript renders the plan, kickoff, and completion with collapsed summaries expandable via `Ctrl+O`. After the final step, Pi runs the Verify commands and reports the result.
 
 Planning disables the managed `edit` and `write` tools and checks Bash calls against a read-only allowlist. Other custom tools and external processes can retain write capabilities. Plan mode is a workflow policy, not a security sandbox.
 
@@ -46,7 +61,7 @@ pi remove npm:@prjct.app/pi-plan
 
 Use `pi config` to enable or disable individual resources. Use `pi config -l` for project settings and add `-l` to removal when you installed locally.
 
-To pin version 0.1.3, use `pi install npm:@prjct.app/pi-plan@0.1.3`. Pi skips pinned npm versions during package updates. For a Git installation, update or remove using the same `git:github.com/prjct-app/pi-plan` source instead of the npm source.
+To pin version 0.2.0, use `pi install npm:@prjct.app/pi-plan@0.2.0`. Pi skips pinned npm versions during package updates. For a Git installation, update or remove using the same `git:github.com/prjct-app/pi-plan` source instead of the npm source.
 
 When switching from GitHub to npm, remove the Git installation first, then install the npm package and restart Pi.
 
@@ -56,7 +71,7 @@ If `/work` is unknown, install Pi Workflows too. If `/todos` is empty, ask for n
 
 ## Package and API documentation
 
-Uses documented tool selection, `tool_call`, commands, shortcuts, flags, `appendEntry()`, `pi.events`, and status/widget APIs.
+Uses documented tool selection, `tool_call`, commands, shortcuts, flags, `appendEntry()`, `pi.events`, status/widget APIs, custom message and entry renderers, and documented TUI components (`SelectList`, `DynamicBorder`, `Text`, `Container`). Plan progress records are display-only entries that never enter the model context; only the execution kickoff instruction does.
 
 See [Package structure and compatibility](docs/package.md) for the manifest, dependency policy, shipped resources, and official references. This package follows the [official Pi package guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md) and [extension API guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md) for the tested version.
 
@@ -71,7 +86,7 @@ npm test
 npm run check:package
 ```
 
-Pi loads the TypeScript entry point directly; no build step is required. To try this checkout for one run, use `pi -e .`. Tests use isolated temporary state and do not call model APIs. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution rules and [CHANGELOG.md](CHANGELOG.md) for release notes.
+Pi loads the TypeScript entry point directly; no build step is required. To try this checkout for one run, use `pi -e .`. Tests use isolated temporary state and do not call model APIs. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution rules, [Automatic releases](docs/releases.md) for publishing, and [CHANGELOG.md](CHANGELOG.md) for release notes.
 
 ## License
 

package/docs/package.md

@@ -35,7 +35,7 @@ Third-party runtime dependencies belong in `dependencies`. Companion extensions
 
 ## Public interfaces
 
-Uses documented tool selection, `tool_call`, commands, shortcuts, flags, `appendEntry()`, `pi.events`, and status/widget APIs.
+Uses documented tool selection, `tool_call`, commands, shortcuts, flags, `appendEntry()`, `pi.events`, status/widget APIs, custom message and entry renderers (`registerMessageRenderer()`, `registerEntryRenderer()`), and documented TUI components (`SelectList`, `DynamicBorder`, `Text`, `Container`) from `@earendil-works/pi-tui` and `@earendil-works/pi-coding-agent`. Plan progress records are display-only entries that never enter the model context; only the execution kickoff instruction does.
 
 ## Published contents
 

package/index.ts

@@ -1,3 +1,3 @@
 export { PLAN_MODE_ENABLE_EVENT } from "./src/events.ts";
-export { default } from "./src/index.ts";
-export { extractTodoItems, isSafeCommand, markCompletedSteps } from "./src/utils.ts";
+export { default, installPlan } from "./src/index.ts";
+export { extractTodoItems, extractVerification, isSafeCommand, markCompletedSteps } from "./src/utils.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prjct.app/pi-plan",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Plan before editing in PI Agent with read-only tool restrictions, an approval step, and task progress tracking.",
   "type": "module",
   "keywords": [

package/src/index.ts

@@ -7,31 +7,125 @@
  * Features:
  * - /plan command or Ctrl+Alt+P to toggle
  * - Bash restricted to allowlisted read-only commands
- * - Extracts numbered plan steps from "Plan:" sections
+ * - Structured plans: Goal, Approach, numbered steps, Verify, Risks
+ * - Plan review dialog (execute / refine / stay / discard)
  * - [DONE:n] markers to complete steps during execution
- * - Progress tracking widget during execution
+ * - Progress widget with bar, current-step highlight, and footer status
+ * - Custom renderers for plan, execution, and completion messages
  */
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
+import { DynamicBorder, type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	Container,
+	Key,
+	matchesKey,
+	SelectList,
+	type SelectItem,
+	Text,
+	truncateToWidth,
+} from "@earendil-works/pi-tui";
 import { PLAN_MODE_ENABLE_EVENT, type PlanModeEnableRequest } from "./events.ts";
-import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "./utils.ts";
+import {
+	extractTodoItems,
+	extractVerification,
+	isSafeCommand,
+	markCompletedSteps,
+	progressBar,
+	type TodoItem,
+} from "./utils.ts";
 
 // Tools
-const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "ask_user"];
-const NORMAL_MODE_TOOLS = ["read", "bash", "edit", "write"];
 const PLAN_MODE_DISABLED_TOOLS = new Set<string>(["edit", "write"]);
-const PLAN_MANAGED_TOOLS = new Set<string>([...PLAN_MODE_TOOLS, ...NORMAL_MODE_TOOLS]);
+
+// Custom message types that carry instructions. They are only relevant while
+// their mode is active and are filtered out of the model context afterwards.
+const PLAN_INSTRUCTION_TYPE = "plan-mode-context";
 
 interface PlanModeState {
 	enabled: boolean;
 	todos?: TodoItem[];
 	executing?: boolean;
+	verify?: string;
 	toolsBeforePlanMode?: string[];
 }
 
+interface PlanListDetails {
+	steps: TodoItem[];
+	verify?: string;
+}
+
+type ReviewChoice = "execute" | "refine" | "stay" | "discard";
+
+const PLAN_MODE_PROMPT = `[PLAN MODE ACTIVE]
+You are in plan mode: read-only exploration before any edit.
+
+Restrictions:
+- The edit and write tools are disabled.
+- Bash is limited to an allowlist of read-only commands.
+- Never attempt changes; describe exactly what you would change instead.
+
+Process:
+1. Investigate first: open the real files, symbols, and tests involved. Do not speculate about code you have not read.
+2. If the request is ambiguous or has multiple viable approaches, ask the user (ask_user when available) before finalizing the plan.
+3. Produce the plan in exactly this format:
+
+**Goal:** one sentence describing the end state
+**Approach:** 2-3 sentences on the strategy and key trade-offs
+
+Plan:
+1. Imperative step naming the concrete file(s)/symbol(s) and the change
+2. ...
+
+**Verify:** the exact command(s) that prove the plan succeeded
+**Risks:** one line per risk, only when real risks exist
+
+Rules:
+- 3 to 8 steps, ordered by dependency, each independently checkable.
+- Every step must reference real paths or symbols found during investigation.
+- No filler steps such as "run tests" or "update docs" unless the user asked; the Verify section covers validation.
+- Keep each step to one line; put file lists or notes as indented sub-bullets under its step.`;
+
+function executionRules(verify: string | undefined): string {
+	const verification = verify
+		? `When every step is done, verify with: ${verify} — and report the actual result.`
+		: "When every step is done, run the project's verification commands and report the actual result.";
+	return `Rules:
+- If a step is blocked, explain why and continue with the next unblocked step.
+- Include a [DONE:n] tag in your response only after step n is actually applied.
+- ${verification}`;
+}
+
+// Kickoff message: the full approved plan, sent once when execution starts.
+function executionKickoffPrompt(todos: TodoItem[], verify: string | undefined): string {
+	const stepList = todos.map((t) => `${t.step}. ${t.text}`).join("\n");
+	const first = todos.find((t) => !t.completed);
+	return `[EXECUTING PLAN - Full tool access restored]
+
+Approved steps:
+${stepList}
+
+Complete the steps in order, starting with step ${first?.step ?? 1}${first ? `: ${first.text}` : ""}.
+${executionRules(verify)}`;
+}
+
+// Per-start injection: progress plus only the remaining steps. Completed
+// steps are already visible in the transcript and would be stale noise.
+function executionContextPrompt(todos: TodoItem[], verify: string | undefined): string {
+	const doneCount = todos.filter((t) => t.completed).length;
+	const remaining = todos.filter((t) => !t.completed);
+	const stepList = remaining.map((t) => `${t.step}. ${t.text}`).join("\n");
+	return `[EXECUTING PLAN - Full tool access restored]
+
+Progress: ${doneCount}/${todos.length} steps complete.
+Remaining steps:
+${stepList}
+
+${executionRules(verify)}`;
+}
+
 // Type guard for assistant messages
 function isAssistantMessage(m: AgentMessage): m is AssistantMessage {
 	return m.role === "assistant" && Array.isArray(m.content);
@@ -45,10 +139,62 @@ function getTextContent(message: AssistantMessage): string {
 		.join("\n");
 }
 
-export default function planModeExtension(pi: ExtensionAPI): void {
+// Collapsed one-line transcript view (pi-team pattern).
+function collapsed(text: string): Component {
+	return {
+		invalidate() {},
+		render(width: number) {
+			return [truncateToWidth(text, width)];
+		},
+	};
+}
+
+function formatStep(item: TodoItem, theme: Theme, current: TodoItem | undefined): string {
+	if (item.completed) {
+		return theme.fg("success", "✓ ") + theme.fg("muted", theme.strikethrough(item.text));
+	}
+	if (item === current) {
+		return theme.fg("accent", "▸ ") + theme.fg("text", item.text);
+	}
+	return theme.fg("dim", "○ ") + theme.fg("muted", item.text);
+}
+
+function planListView(details: PlanListDetails | undefined, expanded: boolean, theme: Theme): Component {
+	const steps = details?.steps ?? [];
+	const heading = `▸ Plan · ${steps.length} step${steps.length === 1 ? "" : "s"}`;
+	if (!expanded) return collapsed(`${heading} · Ctrl+O details`);
+	const lines = [theme.fg("accent", theme.bold(heading))];
+	for (const item of steps) lines.push(`${item.step}. ${item.completed ? "✓" : "○"} ${item.text}`);
+	if (details?.verify) lines.push(theme.fg("muted", `Verify: ${details.verify}`));
+	return new Text(lines.join("\n"), 1, 0);
+}
+
+function planCompleteView(details: PlanListDetails | undefined, expanded: boolean, theme: Theme): Component {
+	const steps = details?.steps ?? [];
+	const heading = `▸ Plan complete ✓ · ${steps.length}/${steps.length}`;
+	if (!expanded) return collapsed(heading);
+	const lines = [theme.fg("success", theme.bold(heading))];
+	for (const item of steps) lines.push(theme.fg("muted", `✓ ${item.text}`));
+	if (details?.verify) lines.push(theme.fg("muted", `Verified with: ${details.verify}`));
+	return new Text(lines.join("\n"), 1, 0);
+}
+
+function planExecuteView(details: PlanListDetails | undefined, expanded: boolean, theme: Theme): Component {
+	const steps = details?.steps ?? [];
+	const first = steps.find((t) => !t.completed);
+	const heading = `▸ Execute plan · start at step ${first?.step ?? 1} of ${steps.length}`;
+	if (!expanded) return collapsed(`${heading} · Ctrl+O details`);
+	const lines = [theme.fg("accent", theme.bold(heading))];
+	for (const item of steps) lines.push(`${item.step}. ${item.text}`);
+	if (details?.verify) lines.push(theme.fg("muted", `Verify: ${details.verify}`));
+	return new Text(lines.join("\n"), 1, 0);
+}
+
+export function installPlan(pi: ExtensionAPI): void {
 	let planModeEnabled = false;
 	let executionMode = false;
 	let todoItems: TodoItem[] = [];
+	let planVerify: string | undefined;
 	let toolsBeforePlanMode: string[] | undefined;
 
 	pi.registerFlag("plan", {
@@ -57,58 +203,60 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		default: false,
 	});
 
+	function uniqueToolNames(toolNames: string[]): string[] {
+		return [...new Set(toolNames)];
+	}
+
 	function updateStatus(ctx: ExtensionContext): void {
 		// Footer status
 		if (executionMode && todoItems.length > 0) {
 			const completed = todoItems.filter((t) => t.completed).length;
-			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("accent", `📋 ${completed}/${todoItems.length}`));
+			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("accent", `▸ plan ${completed}/${todoItems.length}`));
 		} else if (planModeEnabled) {
-			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("warning", "⏸ plan"));
+			const drafted = todoItems.length > 0 ? ` · ${todoItems.length} steps ready` : "";
+			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("warning", `⏸ plan${drafted}`));
 		} else {
 			ctx.ui.setStatus("plan-mode", undefined);
 		}
 
-		// Widget showing todo list
+		// Progress widget below the editor while executing
 		if (executionMode && todoItems.length > 0) {
-			const lines = todoItems.map((item) => {
-				if (item.completed) {
-					return (
-						ctx.ui.theme.fg("success", "☑ ") + ctx.ui.theme.fg("muted", ctx.ui.theme.strikethrough(item.text))
-					);
-				}
-				return `${ctx.ui.theme.fg("muted", "☐ ")}${item.text}`;
-			});
-			ctx.ui.setWidget("plan-todos", lines);
+			ctx.ui.setWidget("plan-todos", (_tui, theme) => ({
+				invalidate() {},
+				render(width: number) {
+					const total = todoItems.length;
+					const doneCount = todoItems.filter((t) => t.completed).length;
+					const pct = Math.round((doneCount / total) * 100);
+					const barColor = doneCount === total ? "success" : "accent";
+					const current = todoItems.find((t) => !t.completed);
+					const lines = [
+						theme.fg("accent", theme.bold(`▸ Plan ${doneCount}/${total}`)) +
+							" " +
+							theme.fg(barColor, progressBar(doneCount, total)) +
+							theme.fg("muted", ` ${pct}%`),
+					];
+					for (const item of todoItems) lines.push(formatStep(item, theme, current));
+					if (planVerify) lines.push(theme.fg("dim", `Verify: ${planVerify}`));
+					return lines.map((line) => truncateToWidth(line, width));
+				},
+			}));
 		} else {
 			ctx.ui.setWidget("plan-todos", undefined);
 		}
 	}
 
-	function uniqueToolNames(toolNames: string[]): string[] {
-		return [...new Set(toolNames)];
-	}
-
-	function getPlanModeTools(activeToolNames: string[]): string[] {
-		return uniqueToolNames(activeToolNames.filter((name) => !PLAN_MODE_DISABLED_TOOLS.has(name)));
-	}
-
-	function getNormalModeTools(activeToolNames: string[]): string[] {
-		return uniqueToolNames([
-			...NORMAL_MODE_TOOLS,
-			...activeToolNames.filter((name) => !PLAN_MANAGED_TOOLS.has(name)),
-		]);
-	}
-
 	function enablePlanModeTools(): void {
 		if (toolsBeforePlanMode === undefined) {
 			toolsBeforePlanMode = pi.getActiveTools();
 		}
-		pi.setActiveTools(getPlanModeTools(toolsBeforePlanMode));
+		pi.setActiveTools(uniqueToolNames(toolsBeforePlanMode.filter((name) => !PLAN_MODE_DISABLED_TOOLS.has(name))));
 	}
 
 	function restoreNormalModeTools(): void {
-		pi.setActiveTools(toolsBeforePlanMode ?? getNormalModeTools(pi.getActiveTools()));
-		toolsBeforePlanMode = undefined;
+		if (toolsBeforePlanMode !== undefined) {
+			pi.setActiveTools(toolsBeforePlanMode);
+			toolsBeforePlanMode = undefined;
+		}
 	}
 
 	function persistState(): void {
@@ -116,30 +264,34 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 			enabled: planModeEnabled,
 			todos: todoItems,
 			executing: executionMode,
+			verify: planVerify,
 			toolsBeforePlanMode,
-		});
+		} satisfies PlanModeState);
 	}
 
 	function enablePlanMode(ctx: ExtensionContext, source?: string): void {
 		planModeEnabled = true;
 		executionMode = false;
 		todoItems = [];
+		planVerify = undefined;
 		enablePlanModeTools();
 		ctx.ui.notify(
 			source
-				? `Plan mode enabled by ${source}. Built-in write tools disabled.`
-				: "Plan mode enabled. Built-in write tools disabled.",
+				? `Plan mode enabled by ${source}. Write tools disabled; bash is read-only.`
+				: "Plan mode enabled. Write tools disabled; bash is read-only.",
+			"info",
 		);
 		updateStatus(ctx);
 		persistState();
 	}
 
-	function disablePlanMode(ctx: ExtensionContext): void {
+	function disablePlanMode(ctx: ExtensionContext, reason = "Plan mode disabled. Full access restored."): void {
 		planModeEnabled = false;
 		executionMode = false;
 		todoItems = [];
+		planVerify = undefined;
 		restoreNormalModeTools();
-		ctx.ui.notify("Plan mode disabled. Full access restored.");
+		ctx.ui.notify(reason, "info");
 		updateStatus(ctx);
 		persistState();
 	}
@@ -152,6 +304,81 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		}
 	}
 
+	// Bordered SelectList dialog (documented TUI Pattern 1).
+	function planReviewDialog(ctx: ExtensionContext): Promise<ReviewChoice | null> {
+		return ctx.ui.custom<ReviewChoice | null>((tui, theme, _kb, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			container.addChild(
+				new Text(theme.fg("accent", theme.bold(`Plan ready · ${todoItems.length} steps`)), 1, 0),
+			);
+			container.addChild(
+				new Text(todoItems.map((t) => theme.fg("muted", ` ${t.step}. ${t.text}`)).join("\n"), 1, 0),
+			);
+			if (planVerify) container.addChild(new Text(theme.fg("dim", ` Verify: ${planVerify}`), 1, 0));
+
+			const items: SelectItem[] = [
+				{ value: "execute", label: "Execute the plan", description: "Restore full tools and track step progress" },
+				{ value: "refine", label: "Refine the plan", description: "Send feedback and keep planning" },
+				{ value: "stay", label: "Stay in plan mode", description: "Keep read-only exploration" },
+				{ value: "discard", label: "Discard the plan", description: "Exit plan mode and drop these steps" },
+			];
+			const list = new SelectList(items, items.length, {
+				selectedPrefix: (t) => theme.fg("accent", t),
+				selectedText: (t) => theme.fg("accent", t),
+				description: (t) => theme.fg("muted", t),
+				scrollInfo: (t) => theme.fg("dim", t),
+				noMatch: (t) => theme.fg("warning", t),
+			});
+			list.onSelect = (item) => done(item.value as ReviewChoice);
+			list.onCancel = () => done(null);
+			container.addChild(list);
+
+			container.addChild(new Text(theme.fg("dim", "↑↓ navigate • enter select • esc stay in plan mode"), 1, 0));
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (w) => container.render(w),
+				invalidate: () => container.invalidate(),
+				handleInput: (data) => {
+					list.handleInput(data);
+					tui.requestRender();
+				},
+			};
+		});
+	}
+
+	function showTodosDialog(ctx: ExtensionContext): Promise<null> {
+		const total = todoItems.length;
+		const doneCount = todoItems.filter((t) => t.completed).length;
+		return ctx.ui.custom<null>((tui, theme, _kb, done) => {
+			const container = new Container();
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+			const title = executionMode
+				? `Executing plan · ${doneCount}/${total} done`
+				: planModeEnabled
+					? `Draft plan · ${total} steps`
+					: `Plan · ${doneCount}/${total} done`;
+			container.addChild(new Text(theme.fg("accent", theme.bold(title)), 1, 0));
+			const current = todoItems.find((t) => !t.completed);
+			container.addChild(
+				new Text(todoItems.map((item) => ` ${item.step}. ${formatStep(item, theme, current)}`).join("\n"), 1, 0),
+			);
+			if (planVerify) container.addChild(new Text(theme.fg("dim", ` Verify: ${planVerify}`), 1, 0));
+			container.addChild(new Text(theme.fg("dim", "esc/enter close"), 1, 0));
+			container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+			return {
+				render: (w) => container.render(w),
+				invalidate: () => container.invalidate(),
+				handleInput: (data) => {
+					if (matchesKey(data, Key.escape) || matchesKey(data, Key.enter)) done(null);
+					tui.requestRender();
+				},
+			};
+		});
+	}
+
 	pi.events.on(PLAN_MODE_ENABLE_EVENT, (data) => {
 		const request = data as PlanModeEnableRequest;
 		if (!request?.ctx || typeof request.source !== "string") return;
@@ -166,14 +393,18 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 	});
 
 	pi.registerCommand("todos", {
-		description: "Show current plan todo list",
+		description: "Show the current plan steps and progress",
 		handler: async (_args, ctx) => {
 			if (todoItems.length === 0) {
-				ctx.ui.notify("No todos. Create a plan first with /plan", "info");
+				ctx.ui.notify("No plan steps. Create a plan first with /plan", "info");
+				return;
+			}
+			if (!ctx.hasUI) {
+				const list = todoItems.map((item) => `${item.step}. ${item.completed ? "✓" : "○"} ${item.text}`).join("\n");
+				ctx.ui.notify(`Plan:\n${list}`, "info");
 				return;
 			}
-			const list = todoItems.map((item, i) => `${i + 1}. ${item.completed ? "✓" : "○"} ${item.text}`).join("\n");
-			ctx.ui.notify(`Plan Progress:\n${list}`, "info");
+			await showTodosDialog(ctx);
 		},
 	});
 
@@ -182,9 +413,29 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		handler: async (ctx) => togglePlanMode(ctx),
 	});
 
-	// Block destructive bash commands in plan mode
+	pi.registerEntryRenderer<PlanListDetails>("plan-todo-list", (entry, { expanded }, theme) =>
+		planListView(entry.data, expanded, theme),
+	);
+	pi.registerEntryRenderer<PlanListDetails>("plan-complete", (entry, { expanded }, theme) =>
+		planCompleteView(entry.data, expanded, theme),
+	);
+	pi.registerMessageRenderer<PlanListDetails>("plan-mode-execute", (message, { expanded }, theme) =>
+		planExecuteView(message.details, expanded, theme),
+	);
+
+	// In plan mode, block writes defensively (even if another extension
+	// re-adds them) and restrict bash to the read-only allowlist.
 	pi.on("tool_call", async (event) => {
-		if (!planModeEnabled || event.toolName !== "bash") return;
+		if (!planModeEnabled) return;
+
+		if (PLAN_MODE_DISABLED_TOOLS.has(event.toolName)) {
+			return {
+				block: true,
+				reason: `Plan mode: ${event.toolName} is disabled. Present the plan and get approval before editing.`,
+			};
+		}
+
+		if (event.toolName !== "bash") return;
 
 		const command = event.input.command as string;
 		if (!isSafeCommand(command)) {
@@ -195,23 +446,37 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		}
 	});
 
-	// Filter out stale plan mode context when not in plan mode
+	// Filter stale instruction messages so old mode prompts never accumulate
+	// in the model context. Each mode keeps only its LATEST injected copy;
+	// older duplicates are dropped. Display entries (plan list, completion)
+	// live outside the LLM context entirely (appendEntry, not sendMessage).
 	pi.on("context", async (event) => {
-		if (planModeEnabled) return;
+		const messages = event.messages;
+		let lastPlanInstruction = -1;
+		let lastExecutionInstruction = -1;
+		messages.forEach((m, i) => {
+			const customType = (m as { customType?: string }).customType;
+			if (customType === PLAN_INSTRUCTION_TYPE) lastPlanInstruction = i;
+			if (customType === "plan-execution-context") lastExecutionInstruction = i;
+		});
 
 		return {
-			messages: event.messages.filter((m) => {
+			messages: messages.filter((m, i) => {
 				const msg = m as AgentMessage & { customType?: string };
-				if (msg.customType === "plan-mode-context") return false;
+				if (msg.customType === PLAN_INSTRUCTION_TYPE) return planModeEnabled && i === lastPlanInstruction;
+				if (msg.customType === "plan-execution-context") return executionMode && i === lastExecutionInstruction;
+				if (msg.customType === "plan-mode-execute") return executionMode;
 				if (msg.role !== "user") return true;
 
+				// Legacy sessions stored the plan-mode prompt as plain user text.
 				const content = msg.content;
 				if (typeof content === "string") {
-					return !content.includes("[PLAN MODE ACTIVE]");
+					return planModeEnabled || !content.includes("[PLAN MODE ACTIVE]");
 				}
 				if (Array.isArray(content)) {
-					return !content.some(
-						(c) => c.type === "text" && (c as TextContent).text?.includes("[PLAN MODE ACTIVE]"),
+					return (
+						planModeEnabled ||
+						!content.some((c) => c.type === "text" && (c as TextContent).text?.includes("[PLAN MODE ACTIVE]"))
 					);
 				}
 				return true;
@@ -224,44 +489,18 @@ export default function planModeExtension(pi: ExtensionAPI): void {
 		if (planModeEnabled) {
 			return {
 				message: {
-					customType: "plan-mode-context",
-					content: `[PLAN MODE ACTIVE]
-You are in plan mode - a read-only exploration mode for safe code analysis.
-
-Restrictions:
-- Built-in edit and write tools are disabled
-- Other currently active tools remain available
-- Bash is restricted to an allowlist of read-only commands
-
-Ask clarifying questions using ask_user when available; otherwise ask the user directly.
-Use an available web-search skill via bash for web research when needed.
-
-Create a detailed numbered plan under a "Plan:" header:
-
-Plan:
-1. First step description
-2. Second step description
-...
-
-Do NOT attempt to make changes - just describe what you would do.`,
+					customType: PLAN_INSTRUCTION_TYPE,
+					content: PLAN_MODE_PROMPT,
 					display: false,
 				},
 			};
 		}
 
 		if (executionMode && todoItems.length > 0) {
-			const remaining = todoItems.filter((t) => !t.completed);
-			const todoList = remaining.map((t) => `${t.step}. ${t.text}`).join("\n");
 			return {
 				message: {
 					customType: "plan-execution-context",
-					content: `[EXECUTING PLAN - Full tool access enabled]
-
-Remaining steps:
-${todoList}
-
-Execute each step in order.
-After completing a step, include a [DONE:n] tag in your response.`,
+					content: executionContextPrompt(todoItems, planVerify),
 					display: false,
 				},
 			};
@@ -285,13 +524,14 @@ After completing a step, include a [DONE:n] tag in your response.`,
 		// Check if execution is complete
 		if (executionMode && todoItems.length > 0) {
 			if (todoItems.every((t) => t.completed)) {
-				const completedList = todoItems.map((t) => `~~${t.text}~~`).join("\n");
-				pi.sendMessage(
-					{ customType: "plan-complete", content: `**Plan Complete!** ✓\n\n${completedList}`, display: true },
-					{ triggerTurn: false },
-				);
+				// Display-only record; kept out of the LLM context on purpose.
+				pi.appendEntry("plan-complete", {
+					steps: todoItems,
+					verify: planVerify,
+				} satisfies PlanListDetails);
 				executionMode = false;
 				todoItems = [];
+				planVerify = undefined;
 				updateStatus(ctx);
 				persistState(); // Save cleared state so resume doesn't restore old execution mode
 			}
@@ -300,35 +540,25 @@ After completing a step, include a [DONE:n] tag in your response.`,
 
 		if (!planModeEnabled || !ctx.hasUI) return;
 
-		// Extract todos from last assistant message
+		// Extract the plan from the last assistant message
 		const lastAssistant = [...event.messages].reverse().find(isAssistantMessage);
 		if (lastAssistant) {
-			const extracted = extractTodoItems(getTextContent(lastAssistant));
+			const text = getTextContent(lastAssistant);
+			const extracted = extractTodoItems(text);
 			if (extracted.length > 0) {
 				todoItems = extracted;
+				planVerify = extractVerification(text);
 			}
 		}
 
 		if (todoItems.length === 0) return;
+		updateStatus(ctx);
 		persistState();
 
-		// Show plan steps and prompt for next action
-		const todoListText = todoItems.map((t, i) => `${i + 1}. ☐ ${t.text}`).join("\n");
-		const planTodoListMessage = {
-			customType: "plan-todo-list",
-			content: `**Plan Steps (${todoItems.length}):**\n\n${todoListText}`,
-			display: true,
-		};
+		const choice = await planReviewDialog(ctx);
 
-		const choice = await ctx.ui.select("Plan mode - what next?", [
-			"Execute the plan (track progress)",
-			"Stay in plan mode",
-			"Refine the plan",
-		]);
-
-		if (choice?.startsWith("Execute")) {
-			const firstTodoItem = todoItems[0];
-			if (!firstTodoItem) return;
+		if (choice === "execute") {
+			const details: PlanListDetails = { steps: todoItems, verify: planVerify };
 
 			planModeEnabled = false;
 			executionMode = true;
@@ -336,26 +566,28 @@ After completing a step, include a [DONE:n] tag in your response.`,
 			updateStatus(ctx);
 			persistState();
 
-			const remainingList = todoItems.map((t) => `${t.step}. ${t.text}`).join("\n");
-			const execMessage = `Execute the plan.
-
-Remaining steps:
-${remainingList}
-
-Start with: ${firstTodoItem.text}
-After completing a step, include a [DONE:n] tag in your response.`;
-			pi.sendMessage(planTodoListMessage, { deliverAs: "followUp" });
+			// The step list is a display-only entry; only the kickoff instruction
+			// enters the LLM context.
+			pi.appendEntry("plan-todo-list", details);
 			pi.sendMessage(
-				{ customType: "plan-mode-execute", content: execMessage, display: true },
+				{
+					customType: "plan-mode-execute",
+					content: executionKickoffPrompt(todoItems, planVerify),
+					display: true,
+					details,
+				},
 				{ triggerTurn: true, deliverAs: "followUp" },
 			);
-		} else if (choice === "Refine the plan") {
+		} else if (choice === "refine") {
 			const refinement = await ctx.ui.editor("Refine the plan:", "");
 			if (refinement?.trim()) {
-				pi.sendMessage(planTodoListMessage, { deliverAs: "followUp" });
+				pi.appendEntry("plan-todo-list", { steps: todoItems, verify: planVerify } satisfies PlanListDetails);
 				pi.sendUserMessage(refinement.trim(), { deliverAs: "followUp" });
 			}
+		} else if (choice === "discard") {
+			disablePlanMode(ctx, "Plan discarded. Full access restored.");
 		}
+		// "stay" or dialog cancelled: remain in plan mode.
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {
@@ -369,18 +601,21 @@ After completing a step, include a [DONE:n] tag in your response.`;
 			planModeEnabled = true;
 		}
 
-		const entries = ctx.sessionManager.getEntries();
+		// getBranch() scopes restore to this branch, never a fork's copy.
+		const entries = ctx.sessionManager.getBranch();
 
 		// Restore persisted state
 		const planModeEntry = entries
-			.filter((e: { type: string; customType?: string }) => e.type === "custom" && e.customType === "plan-mode")
-			.pop() as { data?: PlanModeState } | undefined;
-
-		if (planModeEntry?.data) {
-			planModeEnabled = planModeEntry.data.enabled ?? planModeEnabled;
-			todoItems = planModeEntry.data.todos ?? todoItems;
-			executionMode = planModeEntry.data.executing ?? executionMode;
-			toolsBeforePlanMode = planModeEntry.data.toolsBeforePlanMode ?? toolsBeforePlanMode;
+			.filter((e) => e.type === "custom" && e.customType === "plan-mode")
+			.pop();
+
+		if (planModeEntry?.type === "custom" && planModeEntry.data) {
+			const data = planModeEntry.data as PlanModeState;
+			planModeEnabled = data.enabled ?? planModeEnabled;
+			todoItems = data.todos ?? todoItems;
+			executionMode = data.executing ?? executionMode;
+			planVerify = data.verify ?? planVerify;
+			toolsBeforePlanMode = data.toolsBeforePlanMode ?? toolsBeforePlanMode;
 		}
 
 		// On resume: re-scan messages to rebuild completion state
@@ -390,8 +625,8 @@ After completing a step, include a [DONE:n] tag in your response.`;
 			// Find the index of the last plan-mode-execute entry (marks when current execution started)
 			let executeIndex = -1;
 			for (let i = entries.length - 1; i >= 0; i--) {
-				const entry = entries[i] as { type: string; customType?: string };
-				if (entry.customType === "plan-mode-execute") {
+				const entry = entries[i];
+				if (entry.type === "custom_message" && entry.customType === "plan-mode-execute") {
 					executeIndex = i;
 					break;
 				}
@@ -401,7 +636,7 @@ After completing a step, include a [DONE:n] tag in your response.`;
 			const messages: AssistantMessage[] = [];
 			for (let i = executeIndex + 1; i < entries.length; i++) {
 				const entry = entries[i];
-				if (entry.type === "message" && "message" in entry && isAssistantMessage(entry.message as AgentMessage)) {
+				if (entry.type === "message" && isAssistantMessage(entry.message as AgentMessage)) {
 					messages.push(entry.message as AssistantMessage);
 				}
 			}
@@ -415,3 +650,7 @@ After completing a step, include a [DONE:n] tag in your response.`;
 		updateStatus(ctx);
 	});
 }
+
+export default function planModeExtension(pi: ExtensionAPI): void {
+	installPlan(pi);
+}

package/src/utils.ts

@@ -21,13 +21,20 @@ const DESTRUCTIVE_PATTERNS = [
 	/\bshred\b/i,
 	/(^|[^<])>(?!>)/,
 	/>>/,
+	// find/awk/sed/perl in-place or exec mutations
+	/\bfind\b[^|]*\s(-delete|-exec\b|-ok\b)/i,
+	/\bsed\s+-\w*i/i,
+	/\bawk\s+-i\s*inplace\b/i,
+	/\bperl\s+-\w*i/i,
+	/\bxargs\b/i,
+	/\bpatch\b/i,
 	/\bnpm\s+(install|uninstall|update|ci|link|publish)/i,
 	/\byarn\s+(add|remove|install|publish)/i,
 	/\bpnpm\s+(add|remove|install|publish)/i,
 	/\bpip\s+(install|uninstall)/i,
 	/\bapt(-get)?\s+(install|remove|purge|update|upgrade)/i,
 	/\bbrew\s+(install|uninstall|upgrade)/i,
-	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone)/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|branch\s+-[dD]|stash|cherry-pick|revert|tag|init|clone|clean|restore|switch|worktree|rm|apply|am\b|reflog\s+expire)/i,
 	/\bsudo\b/i,
 	/\bsu\b/i,
 	/\bkill\b/i,
@@ -77,10 +84,15 @@ const SAFE_PATTERNS = [
 	/^\s*top\b/,
 	/^\s*htop\b/,
 	/^\s*free\b/,
-	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get)/i,
-	/^\s*git\s+ls-/i,
+	/^\s*nl\b/,
+	/^\s*readlink\b/,
+	/^\s*realpath\b/,
+	/^\s*basename\b/,
+	/^\s*dirname\b/,
+	/^\s*git\s+(status|log|diff|show|branch|remote|blame|grep|describe|rev-parse|ls-|config\s+--get)/i,
 	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)/i,
 	/^\s*yarn\s+(list|info|why|audit)/i,
+	/^\s*pnpm\s+(list|ls|why|outdated|audit)/i,
 	/^\s*node\s+--version/i,
 	/^\s*python\s+--version/i,
 	/^\s*curl\s/i,
@@ -106,49 +118,74 @@ export interface TodoItem {
 	completed: boolean;
 }
 
+// Clean display text without changing its meaning: keep verbs such as
+// "Delete" or "Remove" because stripping them inverts the step's intent.
 export function cleanStepText(text: string): string {
 	let cleaned = text
 		.replace(/\*{1,2}([^*]+)\*{1,2}/g, "$1") // Remove bold/italic
 		.replace(/`([^`]+)`/g, "$1") // Remove code
-		.replace(
-			/^(Use|Run|Execute|Create|Write|Read|Check|Verify|Update|Modify|Add|Remove|Delete|Install)\s+(the\s+)?/i,
-			"",
-		)
 		.replace(/\s+/g, " ")
 		.trim();
 
 	if (cleaned.length > 0) {
 		cleaned = cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
 	}
-	if (cleaned.length > 50) {
-		cleaned = `${cleaned.slice(0, 47)}...`;
+	if (cleaned.length > 100) {
+		cleaned = `${cleaned.slice(0, 97)}...`;
 	}
 	return cleaned;
 }
 
+// Header accepted as "Plan:", "**Plan:**", "## Plan:", and similar variants.
+const PLAN_HEADER = /(?:^|\n)\s*(?:#{1,6}\s+)?\*{0,2}Plan\*{0,2}\s*:\*{0,2}\s*\n/i;
+const NUMBERED_STEP = /^\s*(\d+)[.)]\s+(.+)$/;
+const CONTINUATION = /^\s+\S/;
+
 export function extractTodoItems(message: string): TodoItem[] {
 	const items: TodoItem[] = [];
-	const headerMatch = message.match(/\*{0,2}Plan:\*{0,2}\s*\n/i);
-	if (!headerMatch) return items;
-
-	const planSection = message.slice(message.indexOf(headerMatch[0]) + headerMatch[0].length);
-	const numberedPattern = /^\s*(\d+)[.)]\s+\*{0,2}([^*\n]+)/gm;
+	const headerMatch = message.match(PLAN_HEADER);
+	if (!headerMatch || headerMatch.index === undefined) return items;
 
-	for (const match of planSection.matchAll(numberedPattern)) {
-		const text = match[2]
-			.trim()
-			.replace(/\*{1,2}$/, "")
-			.trim();
-		if (text.length > 5 && !text.startsWith("`") && !text.startsWith("/") && !text.startsWith("-")) {
-			const cleaned = cleanStepText(text);
+	const planSection = message.slice(headerMatch.index + headerMatch[0].length);
+	for (const line of planSection.split("\n")) {
+		const stepMatch = line.match(NUMBERED_STEP);
+		if (stepMatch) {
+			const cleaned = cleanStepText(stepMatch[2]);
 			if (cleaned.length > 3) {
 				items.push({ step: items.length + 1, text: cleaned, completed: false });
 			}
+			continue;
 		}
+		// Indented sub-bullets belong to the previous step; skip them without
+		// ending the section. Any other line ends the numbered plan, so later
+		// numbered lists (e.g. verification steps) are never captured.
+		if (items.length > 0 && line.trim().length > 0 && !CONTINUATION.test(line)) break;
 	}
 	return items;
 }
 
+// Extract the "**Verify:**" section: the exact commands that prove the plan.
+export function extractVerification(message: string): string | undefined {
+	const match = message.match(/(?:^|\n)\s*(?:#{1,6}\s+)?\*{0,2}Verify\*{0,2}\s*:\*{0,2}\s*/i);
+	if (!match || match.index === undefined) return undefined;
+
+	const lines: string[] = [];
+	for (const line of message.slice(match.index + match[0].length).split("\n")) {
+		if (line.trim().length === 0) {
+			if (lines.length > 0) break;
+			continue;
+		}
+		// Stop at the next section header such as "**Risks:**".
+		if (lines.length > 0 && /^\s*(?:#{1,6}\s|\*{0,2}[A-Z][A-Za-z ]*\*{0,2}\s*:)/.test(line)) break;
+		lines.push(line.trim().replace(/^[-*]\s+/, ""));
+	}
+	const text = lines
+		.join("; ")
+		.replace(/`([^`]+)`/g, "$1")
+		.trim();
+	return text.length > 0 ? text.slice(0, 200) : undefined;
+}
+
 export function extractDoneSteps(message: string): number[] {
 	const steps: number[] = [];
 	for (const match of message.matchAll(/\[DONE:(\d+)\]/gi)) {
@@ -166,3 +203,9 @@ export function markCompletedSteps(text: string, items: TodoItem[]): number {
 	}
 	return doneSteps.length;
 }
+
+export function progressBar(completed: number, total: number, width = 8): string {
+	const ratio = total <= 0 ? 0 : completed / total;
+	const filled = Math.max(0, Math.min(width, Math.round(ratio * width)));
+	return "█".repeat(filled) + "░".repeat(width - filled);
+}