@astralyn/pi 0.84.1 → 0.84.3

package/docs/bundled/README.md

@@ -9,10 +9,8 @@ These hidden built-ins use the same public Extension API available to external e
 | Feature | Tool or command | Purpose |
 |---|---|---|
 | [`llama.cpp`](../llama-cpp.md) | `/llama` | Manage models served by the local llama.cpp router |
-| [Biu](extensions/biu.md) | `/biu`, `biu://` paths | Carry a project cycle through plan, optional decomposition, execution, and archive |
 | [DeepWiki](extensions/deepwiki.md) | `deepwiki` | Query indexed public GitHub repository documentation |
 | [Question](extensions/question.md) | `question` | Ask structured questions through native interactive UI |
-| [Rewind](extensions/rewind.md) | `/rewind`, `/tree` lifecycle | Create and restore project snapshots around session operations |
 | [Router](extensions/router.md) | `/router` | Configure and probe Codex-style routing endpoints |
 | [Statusline](extensions/statusline.md) | Footer status | Show concise extension-managed activity state |
 | [Subagent](extensions/subagent.md) | `subagent`, `/agents` | Delegate bounded work to isolated child Pi sessions |

package/docs/bundled/extensions/subagent.md

@@ -85,7 +85,7 @@ They apply only to future subagent runs and never change the parent session's `/
 - Parent abort, `/reload`, `/new`, `/resume`, `/fork`, and session shutdown abort active child sessions. Queued workers do not survive the call.
 - Parallel worker failures do not cancel other independent workers.
 - Transient provider errors auto-retry: the worker session retries retryable stream errors with backoff (visible as a live `Retrying (n/m) in Xs…` countdown), and a failure that produced no work (for example a preflight auth throw) is rerun at the task level up to two more times. Provider and task retries share one absolute-deadline state; at zero it reads `Retrying now…`, and parent abort/session shutdown interrupts backoff immediately. Runs with partial work behind them are never rerun.
-- Progress is rendered in Pi's native tool transcript. While a call is running, the native shell rebuilds the Subagent renderer once per second, independently of worker output and the main Working spinner. Silent single and parallel runs therefore keep advancing their own elapsed clocks in collapsed and expanded views, and queued retries keep counting down; the generic shell `Running…` row stays hidden to avoid duplicate progress. Once settled, the final duration is fixed and refresh stops.
+- Progress is rendered in Pi's native tool transcript. While a call is running, the Subagent renderer re-schedules its own repaint once per second, independently of worker output and the main Working spinner. Silent single and parallel runs therefore keep advancing their own elapsed clocks in collapsed and expanded views, and queued retries keep counting down. Once settled, the final duration is fixed and refresh stops.
 - The collapsed view stays lean in both phases: while running, one bounded intent line (for example `Verifying changes`) carries tool uses, the `ctx:` context watermark, cost, and elapsed time above the current tool marked with `›` and the live output tail; once settled, the sentence-aware result excerpt is followed by a single metrics line (`tok · $ · duration`, plus tool uses and `ctx:` for single runs) and the configured expand hint. Live lines never quote token totals — mid-run totals are cache-inflated. The call-level status dot belongs to the tool shell; run and activity rows only use `›`, `○`, `✓`, `×`, and `■`, and parallel run rows carry stable dim ordinals that match the expanded section numbers. `Ctrl+O` expands each run into a report cover sheet: a status line, a metrics line, a fixed two-line `Prompt` preview (`… continues, N more lines`, honest about the 1KB bound), an `Activity · last n of N` digest whose successful rows are quiet aligned one-liners, a `Working` tail while streaming, and the full `Report` (or `Error`, with `Report · partial` for salvaged output) rendered as Markdown. Expanded batches start with a numbered contents list whose numbers match the `── N · ✓ Agent` section headers.
 - Failed and aborted batch runs place their bounded reason on a separate error-colored line below the run headline instead of cutting it into the status row. Reasons are capped at 200 characters and keep their hanging indent when wrapped; successful settled excerpts prefer complete leading sentences within their 96-character budget. Rounded durations switch to minute form at 60 seconds without producing `1m 60s`.
 - Full child transcripts are not stored separately. Bounded run details remain in the parent tool result, so completed calls restore naturally in the parent session tree.

package/docs/bundled/tool-presentation.md

@@ -12,9 +12,9 @@ The `@astralyn/pi` package uses Pi's native tool transcript presentation rather
 │ final result line
 ```
 
-The dim result rail continues through every visual line; an empty output line renders as a bare `│`. Calls keep their status in the leading dot: warning while pending or running, green after success, and red after failure. For default-shell tools that are still running after two seconds, the shell adds a live result row such as `Running… (2.1s)` and removes it when the call settles. Tools with purpose-built progress UI can opt out through `rendersOwnProgress`; tools using `renderShell: "self"` continue to own their entire presentation.
+The dim result rail continues through every visual line; an empty output line renders as a bare `│`. Calls keep their status in the leading dot: warning while pending or running, green after success, and red after failure. For bash commands that are still running after two seconds, the shell adds a live result row such as `Running… (2.1s)` and removes it when the call settles. Other tools with live progress render it themselves; tools using `renderShell: "self"` continue to own their entire presentation.
 
-Time-driven renderers use `renderRefreshIntervalMs` separately from `rendersOwnProgress`. The former periodically rebuilds call/result components only during the partial lifecycle; the latter only hides the generic `Running…` row. The native shell shares the shortest needed interval, constrains explicit intervals to 250ms–60s, and stops refreshing on final result, abort, disposal, session replacement, chat rebuild, or shutdown. Renderers compute elapsed/countdown values from absolute timestamps or deadlines, so a delayed repaint never changes the underlying wall-clock meaning.
+Time-driven renderers schedule their own repaints: while a result is partial they arm a timer in renderer state and call the render context's `invalidate()`, clearing the timer on the first settled render. Renderers compute elapsed/countdown values from absolute timestamps or deadlines, so a delayed repaint never changes the underlying wall-clock meaning.
 
 ## Implementation boundary
 

package/docs/docs.json

@@ -56,10 +56,6 @@
           "title": "Overview",
           "path": "bundled/README.md"
         },
-        {
-          "title": "Biu",
-          "path": "bundled/extensions/biu.md"
-        },
         {
           "title": "DeepWiki",
           "path": "bundled/extensions/deepwiki.md"
@@ -68,10 +64,6 @@
           "title": "Question",
           "path": "bundled/extensions/question.md"
         },
-        {
-          "title": "Rewind",
-          "path": "bundled/extensions/rewind.md"
-        },
         {
           "title": "Router",
           "path": "bundled/extensions/router.md"

package/docs/extensions.md

@@ -1996,10 +1996,6 @@ pi.registerTool({
   },
 
   // Optional: Custom rendering
-  // rendersOwnProgress suppresses only the shell's generic Running… row.
-  rendersOwnProgress: true,
-  // While the result is partial, rebuild renderCall/renderResult every second.
-  renderRefreshIntervalMs: 1000,
   renderCall(args, theme, context) { ... },
   renderResult(result, options, theme, context) { ... },
 });
@@ -2253,12 +2249,7 @@ By default, tool output is wrapped in Pi's native call/result shell, which owns
 
 Set `renderShell: "self"` when the tool should render its own shell instead of using the native shell. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
 
-Two independent options control live presentation:
-
-- `rendersOwnProgress: true` suppresses only the native shell's generic `Running… (Ns)` row. It does not schedule renderer updates.
-- `renderRefreshIntervalMs` periodically rebuilds `renderCall` and `renderResult` while the tool result is partial. It does not suppress generic progress.
-
-Use both when a tool renders its own elapsed time, retry countdown, or similar progress UI. Refresh intervals are rounded and constrained to 250–60,000ms. The shell may rebuild sooner when another native concern needs it, so the configured interval is the maximum refresh gap rather than an exclusive cadence. Refresh stops when the result settles or the row is disposed.
+For live progress UI (elapsed time, retry countdowns), schedule repaints from the renderer itself: store a timer handle in `context.state`, arm a `setTimeout` that calls `context.invalidate()` while `options.isPartial` is true, and clear it on the first settled render. `context.invalidate()` is a no-op after the row is disposed, so a trailing timeout is harmless.
 
 Derive displayed time from an absolute timestamp or deadline (`Date.now()`), not by decrementing a counter on every refresh. A refresh is only a repaint opportunity; event-loop stalls and machine sleep must not extend a wall-clock timeout.
 
@@ -2368,8 +2359,7 @@ Custom editors and `ctx.ui.custom()` components receive `keybindings: Keybinding
 - Use `Text` with padding `(0, 0)`. The native shell handles padding.
 - Use `\n` for multi-line content.
 - Handle `isPartial` for streaming progress.
-- Use `renderRefreshIntervalMs` only for values that must change without a new partial result, and compute those values from absolute time.
-- Set `rendersOwnProgress` separately when the renderer replaces the native `Running…` row.
+- For time-driven renderers, self-schedule repaints with `context.state` timers and `context.invalidate()`, and compute displayed values from absolute time.
 - Support `expanded` for detail on demand.
 - Keep default view compact.
 - Read `context.args` in `renderResult` instead of copying args into `context.state`.
@@ -2542,17 +2532,10 @@ const choice = await ctx.ui.select("Pick one:", ["A", "B", "C"]);
 
 // Options can carry a muted description line, so the action and its
 // trade-off can be scanned separately. select() still resolves to the label.
-const action = await ctx.ui.select(
-  "Approve?",
-  [
-    { label: "Start executing", description: "keep full context" },
-    { label: "Compact, then execute", description: "best for long tasks" },
-  ],
-  {
-    subtitle: "Context now 29% full",   // muted line under the title
-    cancelHint: "go back",              // Describe what Esc actually does
-  },
-);
+const action = await ctx.ui.select("Approve?", [
+  { label: "Start executing", description: "keep full context" },
+  { label: "Compact, then execute", description: "best for long tasks" },
+]);
 
 // Confirm dialog
 const ok = await ctx.ui.confirm("Delete?", "This cannot be undone");

package/docs/settings.md

@@ -65,7 +65,7 @@ Use `/trust` in interactive mode to save a project trust decision for future ses
 | `outputPad` | number | `1` | Horizontal padding for user messages, assistant messages, and thinking (0 or 1) |
 | `autocompleteMaxVisible` | number | `5` | Max visible items in autocomplete dropdown (3-20) |
 | `showHardwareCursor` | boolean | `false` | Show the terminal cursor while TUI positions it for IME support |
-| `tuiMode` | string | `"regular"` | Interactive TUI mode: `"regular"` or experimental `"fullscreen"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
+| `tuiMode` | string | `"fullscreen"` | Interactive TUI mode: `"fullscreen"` or `"regular"`. Changes from `/settings` apply immediately; `--tui-mode` overrides this setting at startup |
 | `fullscreenScrollbar` | string | `"auto"` | Fullscreen transcript scrollbar: `"auto"` shows it temporarily while scrolling, `"always"` reserves the rightmost column and keeps it visible, and `"hidden"` hides it. Has no effect in regular TUI mode |
 
 For VS Code, include `--wait` so pi resumes after the editor exits:

package/docs/usage.md

@@ -37,7 +37,6 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | Command | Description |
 |---------|-------------|
 | `/login`, `/logout` | Manage OAuth or API-key credentials |
-| [`/biu`](bundled/extensions/biu.md) | Toggle the TUI-only Biu workflow; inside the mode, open its menu |
 | [`/llama`](llama-cpp.md) | Download, load, and unload llama.cpp router models |
 | `/model` | Switch models |
 | `/scoped-models` | Enable/disable models for Ctrl+P cycling |
@@ -234,7 +233,7 @@ pi --no-extensions -e ./my-extension.ts
 |--------|-------------|
 | `--system-prompt <text>` | Replace default prompt; context files and skills are still appended |
 | `--append-system-prompt <text>` | Append to system prompt |
-| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
+| `--tui-mode <mode>` | TUI mode: `fullscreen` (default) or `regular` |
 | `--verbose` | Force verbose startup |
 | `-a`, `--approve` | Trust project-local files for this run |
 | `-na`, `--no-approve` | Ignore project-local files for this run |

package/examples/extensions/README.md

@@ -43,12 +43,14 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `minimal-mode.ts` | Override built-in tool rendering for minimal display (only tool calls, no output in collapsed mode) |
 | `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
 | `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
+| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
 
 ### Commands & UI
 
 | Extension | Description |
 |-----------|-------------|
 | `preset.ts` | Named presets for model, thinking level, tools, and instructions via `--preset` flag and `/preset` command |
+| `plan-mode/` | Claude Code-style plan mode for read-only exploration with `/plan` command and step tracking |
 | `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
 | `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
 | `commands.ts` | Lists available slash commands, optionally filtered by source |

package/examples/extensions/plan-mode/README.md

@@ -0,0 +1,66 @@
+# Plan Mode Extension
+
+Read-only exploration mode for safe code analysis.
+
+## Features
+
+- **Built-in write tools disabled**: Disables edit/write while preserving other active tools
+- **Bash allowlist**: Only read-only bash commands are allowed
+- **Plan extraction**: Extracts numbered steps from `Plan:` sections
+- **Progress tracking**: Widget shows completion status during execution
+- **[DONE:n] markers**: Explicit step completion tracking
+- **Session persistence**: State survives session resume
+
+## Commands
+
+- `/plan` - Toggle plan mode
+- `/todos` - Show current plan progress
+- `Ctrl+Alt+P` - Toggle plan mode (shortcut)
+
+## Usage
+
+1. Enable plan mode with `/plan` or `--plan` flag
+2. Ask the agent to analyze code and create a plan
+3. The agent should output a numbered plan under a `Plan:` header:
+
+```
+Plan:
+1. First step description
+2. Second step description
+3. Third step description
+```
+
+4. Choose "Execute the plan" when prompted
+5. During execution, the agent marks steps complete with `[DONE:n]` tags
+6. Progress widget shows completion status
+
+## How It Works
+
+### Plan Mode (Read-Only)
+- Built-in edit/write tools disabled
+- Other active tools remain available
+- Bash commands filtered through allowlist
+- Agent creates a plan without making changes
+
+### Execution Mode
+- Full tool access restored
+- Agent executes steps in order
+- `[DONE:n]` markers track completion
+- Widget shows progress
+
+### Command Allowlist
+
+Safe commands (allowed):
+- File inspection: `cat`, `head`, `tail`, `less`, `more`
+- Search: `grep`, `find`, `rg`, `fd`
+- Directory: `ls`, `pwd`, `tree`
+- Git read: `git status`, `git log`, `git diff`, `git branch`
+- Package info: `npm list`, `npm outdated`, `yarn info`
+- System info: `uname`, `whoami`, `date`, `uptime`
+
+Blocked commands:
+- File modification: `rm`, `mv`, `cp`, `mkdir`, `touch`
+- Git write: `git add`, `git commit`, `git push`
+- Package install: `npm install`, `yarn add`, `pip install`
+- System: `sudo`, `kill`, `reboot`
+- Editors: `vim`, `nano`, `code`

package/examples/extensions/plan-mode/index.ts

@@ -0,0 +1,390 @@
+/**
+ * Plan Mode Extension
+ *
+ * Read-only exploration mode for safe code analysis.
+ * When enabled, built-in write tools are disabled.
+ *
+ * Features:
+ * - /plan command or Ctrl+Alt+P to toggle
+ * - Bash restricted to allowlisted read-only commands
+ * - Extracts numbered plan steps from "Plan:" sections
+ * - [DONE:n] markers to complete steps during execution
+ * - Progress tracking widget during execution
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@astralyn/pi";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import { Key } from "@earendil-works/pi-tui";
+import { extractTodoItems, isSafeCommand, markCompletedSteps, type TodoItem } from "./utils.ts";
+
+// Tools
+const PLAN_MODE_TOOLS = ["read", "bash", "grep", "find", "ls", "questionnaire"];
+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]);
+
+interface PlanModeState {
+	enabled: boolean;
+	todos?: TodoItem[];
+	executing?: boolean;
+	toolsBeforePlanMode?: string[];
+}
+
+// Type guard for assistant messages
+function isAssistantMessage(m: AgentMessage): m is AssistantMessage {
+	return m.role === "assistant" && Array.isArray(m.content);
+}
+
+// Extract text content from an assistant message
+function getTextContent(message: AssistantMessage): string {
+	return message.content
+		.filter((block): block is TextContent => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+export default function planModeExtension(pi: ExtensionAPI): void {
+	let planModeEnabled = false;
+	let executionMode = false;
+	let todoItems: TodoItem[] = [];
+	let toolsBeforePlanMode: string[] | undefined;
+
+	pi.registerFlag("plan", {
+		description: "Start in plan mode (read-only exploration)",
+		type: "boolean",
+		default: false,
+	});
+
+	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}`));
+		} else if (planModeEnabled) {
+			ctx.ui.setStatus("plan-mode", ctx.ui.theme.fg("warning", "⏸ plan"));
+		} else {
+			ctx.ui.setStatus("plan-mode", undefined);
+		}
+
+		// Widget showing todo list
+		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);
+		} 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)),
+			...PLAN_MODE_TOOLS,
+		]);
+	}
+
+	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));
+	}
+
+	function restoreNormalModeTools(): void {
+		pi.setActiveTools(toolsBeforePlanMode ?? getNormalModeTools(pi.getActiveTools()));
+		toolsBeforePlanMode = undefined;
+	}
+
+	function persistState(): void {
+		pi.appendEntry("plan-mode", {
+			enabled: planModeEnabled,
+			todos: todoItems,
+			executing: executionMode,
+			toolsBeforePlanMode,
+		});
+	}
+
+	function togglePlanMode(ctx: ExtensionContext): void {
+		planModeEnabled = !planModeEnabled;
+		executionMode = false;
+		todoItems = [];
+
+		if (planModeEnabled) {
+			enablePlanModeTools();
+			ctx.ui.notify("Plan mode enabled. Built-in write tools disabled.");
+		} else {
+			restoreNormalModeTools();
+			ctx.ui.notify("Plan mode disabled. Full access restored.");
+		}
+		updateStatus(ctx);
+		persistState();
+	}
+
+	pi.registerCommand("plan", {
+		description: "Toggle plan mode (read-only exploration)",
+		handler: async (_args, ctx) => togglePlanMode(ctx),
+	});
+
+	pi.registerCommand("todos", {
+		description: "Show current plan todo list",
+		handler: async (_args, ctx) => {
+			if (todoItems.length === 0) {
+				ctx.ui.notify("No todos. Create a plan first with /plan", "info");
+				return;
+			}
+			const list = todoItems.map((item, i) => `${i + 1}. ${item.completed ? "✓" : "○"} ${item.text}`).join("\n");
+			ctx.ui.notify(`Plan Progress:\n${list}`, "info");
+		},
+	});
+
+	pi.registerShortcut(Key.ctrlAlt("p"), {
+		description: "Toggle plan mode",
+		handler: async (ctx) => togglePlanMode(ctx),
+	});
+
+	// Block destructive bash commands in plan mode
+	pi.on("tool_call", async (event) => {
+		if (!planModeEnabled || event.toolName !== "bash") return;
+
+		const command = event.input.command as string;
+		if (!isSafeCommand(command)) {
+			return {
+				block: true,
+				reason: `Plan mode: command blocked (not allowlisted). Use /plan to disable plan mode first.\nCommand: ${command}`,
+			};
+		}
+	});
+
+	// Filter out stale plan mode context when not in plan mode
+	pi.on("context", async (event) => {
+		if (planModeEnabled) return;
+
+		return {
+			messages: event.messages.filter((m) => {
+				const msg = m as AgentMessage & { customType?: string };
+				if (msg.customType === "plan-mode-context") return false;
+				if (msg.role !== "user") return true;
+
+				const content = msg.content;
+				if (typeof content === "string") {
+					return !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 true;
+			}),
+		};
+	});
+
+	// Inject plan/execution context before agent starts
+	pi.on("before_agent_start", async () => {
+		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 the questionnaire tool.
+Use brave-search skill via bash for web research.
+
+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.`,
+					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.`,
+					display: false,
+				},
+			};
+		}
+	});
+
+	// Track progress after each turn
+	pi.on("turn_end", async (event, ctx) => {
+		if (!executionMode || todoItems.length === 0) return;
+		if (!isAssistantMessage(event.message)) return;
+
+		const text = getTextContent(event.message);
+		if (markCompletedSteps(text, todoItems) > 0) {
+			updateStatus(ctx);
+		}
+		persistState();
+	});
+
+	// Handle plan completion and plan mode UI
+	pi.on("agent_end", async (event, ctx) => {
+		// 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 },
+				);
+				executionMode = false;
+				todoItems = [];
+				updateStatus(ctx);
+				persistState(); // Save cleared state so resume doesn't restore old execution mode
+			}
+			return;
+		}
+
+		if (!planModeEnabled || !ctx.hasUI) return;
+
+		// Extract todos from last assistant message
+		const lastAssistant = [...event.messages].reverse().find(isAssistantMessage);
+		if (lastAssistant) {
+			const extracted = extractTodoItems(getTextContent(lastAssistant));
+			if (extracted.length > 0) {
+				todoItems = extracted;
+			}
+		}
+
+		if (todoItems.length === 0) return;
+		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 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;
+
+			planModeEnabled = false;
+			executionMode = true;
+			restoreNormalModeTools();
+			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" });
+			pi.sendMessage(
+				{ customType: "plan-mode-execute", content: execMessage, display: true },
+				{ triggerTurn: true, deliverAs: "followUp" },
+			);
+		} else if (choice === "Refine the plan") {
+			const refinement = await ctx.ui.editor("Refine the plan:", "");
+			if (refinement?.trim()) {
+				pi.sendMessage(planTodoListMessage, { deliverAs: "followUp" });
+				pi.sendUserMessage(refinement.trim(), { deliverAs: "followUp" });
+			}
+		}
+	});
+
+	// Restore state on session start/resume
+	pi.on("session_start", async (_event, ctx) => {
+		if (pi.getFlag("plan") === true) {
+			planModeEnabled = true;
+		}
+
+		const entries = ctx.sessionManager.getEntries();
+
+		// 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;
+		}
+
+		// On resume: re-scan messages to rebuild completion state
+		// Only scan messages AFTER the last "plan-mode-execute" to avoid picking up [DONE:n] from previous plans
+		const isResume = planModeEntry !== undefined;
+		if (isResume && executionMode && todoItems.length > 0) {
+			// 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") {
+					executeIndex = i;
+					break;
+				}
+			}
+
+			// Only scan messages after the execute marker
+			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)) {
+					messages.push(entry.message as AssistantMessage);
+				}
+			}
+			const allText = messages.map(getTextContent).join("\n");
+			markCompletedSteps(allText, todoItems);
+		}
+
+		if (planModeEnabled) {
+			enablePlanModeTools();
+		}
+		updateStatus(ctx);
+	});
+}