@xynogen/pix-core 0.5.54 → 0.6.1

package/README.md

@@ -36,15 +36,10 @@ Pi activates extensions per installed package via each package's `pi.extensions`
 | `pix-grep` | `grep` — pattern search with FFF-prioritised results |
 | `pix-ls` | `ls` — directory listing as an icon tree |
 | `pix-bash` | `bash` — shell execution with framed output + exit-code summary |
+| `pix-powershell` | `powershell` — same rendering for Pi's optional Windows tool; inert unless you enable `powershell` |
 | `pix-todo` | `todo` — durable execution checklist |
 | `pix-ask` | `ask_user` — structured TUI questionnaire |
 
-**Shell integration**
-
-| Feature | Description |
-|---|---|
-| `$SHELL` respect | User `!` commands run through `$SHELL` instead of Pi's default `/bin/bash`. For zsh, `.zshrc` is sourced and aliases expand correctly via `eval`. Other non-bash shells get the shell redirect without rc wrapping. |
-
 **Shared data + behaviour**
 
 | Package | Description |
@@ -62,18 +57,22 @@ Pi activates extensions per installed package via each package's `pi.extensions`
 pi install npm:@xynogen/pix-core
 ```
 
-> Installs and activates the core pix UI/UX extensions in one command. Members are deduped if also installed directly.
+> Installs and activates every bundled pix package. A package that you also install directly loads only once.
 
 ## Full distro
 
-Source: [github.com/xynogen/pix-mono](https://github.com/xynogen/pix-mono)
-
-To install the complete pix suite (all packages + Pi itself):
+This package is part of [Pix](https://github.com/xynogen/pix-mono). The installer sets up Pi and the full distro. See [Install](https://github.com/xynogen/pix-mono#install) for the notes for each OS.
 
 ```bash
+# Linux / macOS
 curl -fsSL https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.sh | sh
 ```
 
+```powershell
+# Windows
+irm https://raw.githubusercontent.com/xynogen/pix-mono/main/scripts/install.ps1 | iex
+```
+
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-core",
-	"version": "0.5.54",
+	"version": "0.6.1",
 	"description": "Pi extension bundle — installs and activates all core pix-* extensions",
 	"type": "module",
 	"main": "src/extension.ts",
@@ -43,31 +43,32 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@xynogen/pix-runtime": "^0.10.2",
-		"@xynogen/pix-data": "^0.5.1",
-		"@xynogen/pix-pretty": "^1.27.0",
-		"@xynogen/pix-welcome": "^0.2.3",
-		"@xynogen/pix-footer": "^0.2.5",
-		"@xynogen/pix-diagnostics": "^0.3.2",
-		"@xynogen/pix-display": "^0.2.1",
-		"@xynogen/pix-prompts": "^0.5.1",
-		"@xynogen/pix-skills": "^0.8.8",
-		"@xynogen/pix-models": "^0.2.8",
-		"@xynogen/pix-update": "^0.2.2",
-		"@xynogen/pix-commands": "^0.6.6",
-		"@xynogen/pix-nudge": "^0.3.0",
-		"@xynogen/pix-read": "^0.4.0",
-		"@xynogen/pix-write": "^0.2.5",
-		"@xynogen/pix-edit": "^0.2.5",
-		"@xynogen/pix-find": "^0.3.1",
-		"@xynogen/pix-grep": "^0.3.1",
-		"@xynogen/pix-ls": "^0.3.1",
-		"@xynogen/pix-bash": "^0.2.7",
-		"@xynogen/pix-todo": "^0.4.1",
-		"@xynogen/pix-ask": "^0.2.30",
-		"@xynogen/pix-optimizer": "^1.2.0",
-		"@xynogen/pix-gate": "^0.3.2",
-		"@xynogen/pix-subagent": "^0.10.2"
+		"@xynogen/pix-runtime": "^0.12.2",
+		"@xynogen/pix-data": "^0.5.3",
+		"@xynogen/pix-pretty": "^1.29.0",
+		"@xynogen/pix-welcome": "^0.2.5",
+		"@xynogen/pix-footer": "^0.2.7",
+		"@xynogen/pix-diagnostics": "^0.3.5",
+		"@xynogen/pix-display": "^0.3.0",
+		"@xynogen/pix-prompts": "^0.5.4",
+		"@xynogen/pix-skills": "^0.9.1",
+		"@xynogen/pix-models": "^0.3.0",
+		"@xynogen/pix-update": "^0.2.4",
+		"@xynogen/pix-commands": "^0.6.8",
+		"@xynogen/pix-nudge": "^0.3.2",
+		"@xynogen/pix-read": "^0.4.2",
+		"@xynogen/pix-write": "^0.2.7",
+		"@xynogen/pix-edit": "^0.2.7",
+		"@xynogen/pix-find": "^0.3.3",
+		"@xynogen/pix-grep": "^0.3.3",
+		"@xynogen/pix-ls": "^0.3.3",
+		"@xynogen/pix-bash": "^0.2.9",
+		"@xynogen/pix-powershell": "^0.1.0",
+		"@xynogen/pix-todo": "^0.4.5",
+		"@xynogen/pix-ask": "^0.3.0",
+		"@xynogen/pix-optimizer": "^1.3.0",
+		"@xynogen/pix-gate": "^0.4.0",
+		"@xynogen/pix-subagent": "^0.10.5"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/src/compaction.ts

@@ -28,6 +28,7 @@
 import { complete } from "@earendil-works/pi-ai/compat";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+import { getErrorMessage } from "@xynogen/pix-pretty/utils";
 import { config } from "@xynogen/pix-runtime/config";
 import { compactionSection } from "@xynogen/pix-runtime/sections";
 
@@ -167,7 +168,7 @@ export default function registerCompaction(pi: ExtensionAPI): void {
 			};
 		} catch (error) {
 			if (signal.aborted) return;
-			const message = error instanceof Error ? error.message : String(error);
+			const message = getErrorMessage(error);
 			ctx.ui.notify(`Compaction failed (${message}); using built-in`, "error");
 			return;
 		}
@@ -251,7 +252,7 @@ export default function registerCompaction(pi: ExtensionAPI): void {
 					try {
 						pi.sendUserMessage(RESUME_NUDGE, { deliverAs: "followUp" });
 					} catch (err) {
-						const message = err instanceof Error ? err.message : String(err);
+						const message = getErrorMessage(err);
 						ctx.ui.notify(`Compaction: resume nudge skipped (${message})`, "warning");
 					}
 				}, 0);

package/src/defer-tools.ts

@@ -0,0 +1,32 @@
+/**
+ * Keep the prompt lean: only the core tools are declared up front. Every other
+ * `direct` tool a bundled member registers becomes `deferred`, and `tool_search`
+ * is activated so the model can find and load them on demand.
+ *
+ * It patches `registerTool` on pix-core's own `pi` object. Pi gives each
+ * extension its own API object, so tools of standalone installs and other
+ * extensions keep their declared exposure.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export const CORE_TOOLS: ReadonlySet<string> = new Set(["read", "bash", "edit", "write"]);
+const TOOL_SEARCH = "tool_search";
+
+export default function deferNonCoreTools(pi: ExtensionAPI): void {
+	const register = pi.registerTool.bind(pi);
+	pi.registerTool = (tool) =>
+		register(
+			CORE_TOOLS.has(tool.name) || (tool.exposure ?? "direct") !== "direct"
+				? tool
+				: { ...tool, exposure: "deferred" },
+		);
+
+	// Pi registers tool_search inactive. Without it, deferred tools are unreachable.
+	pi.on("session_start", () => {
+		const active = pi.getActiveTools();
+		if (active.includes(TOOL_SEARCH)) return;
+		if (!pi.getAllTools().some((t) => t.name === TOOL_SEARCH)) return;
+		pi.setActiveTools([...active, TOOL_SEARCH]);
+	});
+}

package/src/extension.ts

@@ -12,7 +12,6 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
 import registerAsk from "@xynogen/pix-ask";
 import registerBash from "@xynogen/pix-bash/extension";
 import registerCommands from "@xynogen/pix-commands/extension";
@@ -28,6 +27,7 @@ import registerLs from "@xynogen/pix-ls/extension";
 import registerModels from "@xynogen/pix-models/extension";
 import registerNudge from "@xynogen/pix-nudge/extension";
 import registerOptimizer from "@xynogen/pix-optimizer";
+import registerPowerShell from "@xynogen/pix-powershell/extension";
 import registerPretty from "@xynogen/pix-pretty";
 import registerPrompts from "@xynogen/pix-prompts/extension";
 import registerRead from "@xynogen/pix-read/extension";
@@ -39,11 +39,15 @@ import registerUpdate from "@xynogen/pix-update/extension";
 import registerWelcome from "@xynogen/pix-welcome/extension";
 import registerWrite from "@xynogen/pix-write/extension";
 import registerCompaction from "./compaction.ts";
+import deferNonCoreTools from "./defer-tools.ts";
+import registerPlanMode from "./plan-mode.ts";
 
 type PixExtension = (pi: ExtensionAPI) => void;
 
 // Compile-time boundary: every member must accept the Pi host contract.
 const MEMBERS = [
+	// Must run first: it wraps registerTool so non-core member tools register deferred.
+	deferNonCoreTools,
 	// pix-runtime owns pix.json (init/reload/flush) and the /pix settings command.
 	// It must run first so every config consumer below reads a live runtime.
 	registerRuntime,
@@ -70,6 +74,8 @@ const MEMBERS = [
 	registerGrep,
 	registerLs,
 	registerBash,
+	// No-op unless Windows AND the user enabled Pi's optional `powershell` tool.
+	registerPowerShell,
 	registerTodo,
 	registerAsk,
 	registerOptimizer,
@@ -78,61 +84,11 @@ const MEMBERS = [
 	// Custom compaction: replaces pi's built-in summary + trigger (reads
 	// compaction section; runs after runtime is live).
 	registerCompaction,
+	// /plan: plan manager modal. Plan mode (read + bash + write to .pi/plans) turns on
+	// for new/edit. Tab in an empty prompt, or ctrl+alt+p, toggles it.
+	registerPlanMode,
 ] satisfies readonly PixExtension[];
 
 export default function (pi: ExtensionAPI): void {
 	for (const register of MEMBERS) register(pi);
-
-	// ── Respect $SHELL for user ! commands ──────────────────────────────────
-	// Pi defaults to /bin/bash for ! commands. When the user's login shell
-	// differs (zsh, fish, nushell, …), redirect ! execution through $SHELL
-	// in interactive mode so aliases, functions, and rc config all work.
-	const userShell = process.env.SHELL;
-	if (userShell && !/\bbash$/.test(userShell)) {
-		const ops = createInteractiveShellOps(userShell);
-		pi.on("user_bash", () => ({ operations: ops }));
-	}
-}
-
-/**
- * Build BashOperations that run commands through the user's real shell with
- * rc files loaded and alias expansion enabled.
- *
- * Problem: `zsh -c "gss"` is non-interactive — it skips `.zshrc` and disables
- * alias expansion.  Even `zsh -c ". ~/.zshrc; gss"` fails because aliases
- * are resolved at parse-time, before `.zshrc` is sourced.
- *
- * Solution: source the rc file, then `eval` the command.  `eval` creates a
- * new parse boundary, so aliases defined by the source are available.
- */
-function createInteractiveShellOps(
-	shellPath: string,
-): import("@earendil-works/pi-coding-agent").BashOperations {
-	const inner = createLocalBashOperations({ shellPath });
-	const name = shellPath.split("/").pop() ?? "";
-	const home = process.env.HOME ?? "~";
-
-	return {
-		exec(command, cwd, options) {
-			return inner.exec(wrapForShell(name, home, command), cwd, options);
-		},
-	};
-}
-
-/**
- * Wrap a command so it runs inside the user's shell with rc and alias support.
- */
-function wrapForShell(shell: string, home: string, command: string): string {
-	if (shell === "zsh") {
-		// 1. source .zshrc for aliases/functions/PATH
-		// 2. eval to create a fresh parse boundary so aliases expand
-		return `. ${home}/.zshrc 2>/dev/null; eval ${escapeForShell(command)}`;
-	}
-	// Other shells: run as-is, rely on shellPath alone
-	return command;
-}
-
-/** Single-quote a string for safe shell embedding. */
-function escapeForShell(s: string): string {
-	return `'${s.replace(/'/g, "'\\''")}'`;
 }

package/src/plan-modal.ts

@@ -0,0 +1,194 @@
+/**
+ * Plan manager overlay for `/plan` — one framed modal (pix-pretty frameModal)
+ * with three views: plan list, plan detail, and delete confirm. Create and
+ * edit hand off to the model through the prompt bar.
+ * The modal only returns a decision; plan-mode.ts performs it visibly.
+ */
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type KeybindingsManager,
+	matchesKey,
+	type SelectItem,
+	SelectList,
+	type TUI,
+} from "@earendil-works/pi-tui";
+import {
+	frameModal,
+	MIN_MODAL_HEIGHT,
+	ModalPager,
+	modalWidth,
+	selectListTheme,
+	terminalModalHeight,
+} from "@xynogen/pix-pretty/modal-frame";
+import type { Plan } from "./plan-mode.ts";
+
+export type PlanModalResult =
+	| { kind: "execute"; plan: Plan }
+	| { kind: "delete"; plan: Plan }
+	| { kind: "edit"; plan: Plan }
+	| { kind: "new" }
+	| { kind: "toggle" };
+
+const LIST_ROWS = 10;
+
+type View = "list" | "plan" | "confirm";
+
+export class PlanModal {
+	private view: View = "list";
+	private plan: Plan | undefined;
+	private readonly pager = new ModalPager();
+	private readonly list: SelectList;
+	private actions: SelectList | undefined;
+
+	constructor(
+		private readonly plans: Plan[],
+		private readonly planDir: string,
+		private readonly planMode: boolean,
+		private readonly tui: TUI,
+		private readonly theme: Theme,
+		private readonly kb: KeybindingsManager,
+		private readonly done: (result: PlanModalResult | undefined) => void,
+	) {
+		const items: SelectItem[] = [
+			{
+				value: "new",
+				label: "+ New plan",
+				description: "Plan mode on + plan guide in the prompt bar",
+			},
+			...plans.map((p, i) => ({ value: String(i), label: p.title, description: p.description })),
+		];
+		this.list = new SelectList(items, LIST_ROWS, selectListTheme(theme));
+		this.list.onSelect = (item) => {
+			const plan = plans[Number(item.value)];
+			if (item.value === "new") done({ kind: "new" });
+			else if (plan) this.openPlan(plan);
+		};
+		this.list.onCancel = () => done(undefined);
+	}
+
+	private selectedPlan(): Plan | undefined {
+		return this.plans[Number(this.list.getSelectedItem()?.value)];
+	}
+
+	private edit(plan: Plan): void {
+		this.done({ kind: "edit", plan });
+	}
+
+	private go(view: View): void {
+		this.view = view;
+		this.pager.reset();
+	}
+
+	private actionList(
+		items: string[],
+		onSelect: (value: string) => void,
+		onCancel: () => void,
+	): SelectList {
+		const list = new SelectList(
+			items.map((v) => ({ value: v, label: v })),
+			items.length,
+			selectListTheme(this.theme),
+		);
+		list.onSelect = (item) => onSelect(item.value);
+		list.onCancel = onCancel;
+		return list;
+	}
+
+	private openPlan(plan: Plan): void {
+		this.plan = plan;
+		this.actions = this.actionList(
+			["Execute", "Edit", "Delete", "Back"],
+			(v) => {
+				if (v === "Execute") this.done({ kind: "execute", plan });
+				else if (v === "Edit") this.edit(plan);
+				else if (v === "Delete") this.confirmDelete(plan);
+				else this.go("list");
+			},
+			() => this.go("list"),
+		);
+		this.go("plan");
+	}
+
+	private confirmDelete(plan: Plan): void {
+		this.plan = plan;
+		this.actions = this.actionList(
+			["Delete", "Cancel"],
+			(v) => (v === "Delete" ? this.done({ kind: "delete", plan }) : this.openPlan(plan)),
+			() => this.openPlan(plan),
+		);
+		this.go("confirm");
+	}
+
+	handleInput(data: string): void {
+		if (this.view === "list") this.handleListInput(data);
+		else if (!this.pager.handleInput(data, this.kb, true)) this.actions?.handleInput(data);
+		this.tui.requestRender();
+	}
+
+	private handleListInput(data: string): void {
+		const plan = this.selectedPlan();
+		if (matchesKey(data, "t")) this.done({ kind: "toggle" });
+		else if (plan && matchesKey(data, "d")) this.confirmDelete(plan);
+		else if (plan && matchesKey(data, "e")) this.edit(plan);
+		else this.list.handleInput(data);
+	}
+
+	render(width: number): string[] {
+		const t = this.theme;
+		const mw = modalWidth(width);
+		const inner = mw - 4;
+		const title = (s: string) => t.fg("accent", t.bold(s));
+		const hint = (s: string) => t.fg("muted", s);
+		const rule = t.fg("muted", "─".repeat(inner));
+		let header: string[];
+		let body: string[];
+		let footer: string[];
+
+		if (this.view === "list") {
+			header = [
+				title("Plans"),
+				hint(
+					`${this.plans.length} saved · ${this.planDir} · plan mode ${this.planMode ? "on" : "off"}`,
+				),
+			];
+			body = this.list.render(inner);
+			footer = [
+				rule,
+				hint("↑↓ choose • enter open • e edit • d delete • t toggle mode • esc close"),
+			];
+		} else {
+			const plan = this.plan as Plan;
+			const confirm = this.view === "confirm";
+			header = [
+				confirm ? t.fg("warning", t.bold(`Delete ${plan.file}?`)) : title(plan.title),
+				...(plan.description ? [t.fg("dim", plan.description)] : []),
+				hint(`${this.planDir}/${plan.file}`),
+			];
+			body = plan.body.split("\n");
+			footer = [
+				rule,
+				...(this.actions?.render(inner) ?? []),
+				hint("↑↓ choose • ←→/PgUp/PgDn scroll • enter select • esc back"),
+			];
+		}
+
+		const result = frameModal({
+			width: mw,
+			maxHeight: terminalModalHeight(this.tui.terminal?.rows),
+			minHeight: MIN_MODAL_HEIGHT,
+			header,
+			body,
+			footer,
+			bodyOffset: this.pager.bodyOffset,
+			color: (s) => t.fg("accent", s),
+			bg: (s) => t.bg("customMessageBg", s),
+			fg: (s) => t.fg("text", s),
+			overflowLine: ({ page, totalPages }) => hint(`←→/PgUp/PgDn scroll • ${page}/${totalPages}`),
+		});
+		this.pager.sync(result);
+		return result.lines;
+	}
+
+	invalidate(): void {}
+}

package/src/plan-mode.ts

@@ -0,0 +1,266 @@
+/**
+ * pix-core plan mode — `/plan` opens a modal to manage saved plans in
+ * `<cwd>/.pi/plans/*.md`. Plan mode turns on when the user starts a new plan or
+ * edits one from the modal. Shift+Tab, or ctrl+alt+p, toggles it by hand.
+ * Tab in an empty prompt cycles the thinking level (Pi's default Shift+Tab action).
+ *
+ * While plan mode is on:
+ *   - active tools shrink to `read` + `write` + `bash` (previous set restored on exit);
+ *   - `write` may only target `.pi/plans/` (tool_call guard, visible block);
+ *   - no hidden prompt: "+ New plan" pastes PLAN_GUIDE into the prompt bar as a chip (sent as <paste>).
+ *
+ * Plan file format: YAML-ish frontmatter (`title`, `description`) + markdown
+ * body (the plan itself). Executing a plan sends a normal, visible user
+ * message — no hidden automation.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { CustomEditor, isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey } from "@earendil-works/pi-tui";
+import { chipTag } from "@xynogen/pix-pretty/chips";
+import { icon } from "@xynogen/pix-pretty/icon-catalog";
+import { modalOverlayOptions } from "@xynogen/pix-pretty/modal-frame";
+import { projectDir } from "@xynogen/pix-runtime/paths";
+import { PlanModal, type PlanModalResult } from "./plan-modal.ts";
+
+// ponytail: bash is not sandboxed here; PLAN_GUIDE asks for read-only use and pix-gate
+// still guards destructive commands. Add an allowlist guard if the model abuses it.
+const PLAN_TOOLS = ["read", "write", "bash"];
+const PLAN_DIR = `${projectDir()}/plans`; // "/" so prompts and hints read the same on Windows
+const STATE_ENTRY = "pix-plan-mode";
+
+// Visible guide: /plan → "+ New plan" pastes this into the prompt bar as a chip for the user
+// to read, edit, and send. Nothing is injected into the system prompt.
+export const PLAN_GUIDE = `[PLAN MODE] Write an implementation plan. Do not change project code.
+Explore with \`read\` and read-only \`bash\` (git log/status/diff, ls, rg, --help). Never use bash to edit, install, commit, or delete.
+Save ONE plan with \`write\` to \`.pi/plans/YYYY-MM-DD-<feature-name>.md\` (writes elsewhere are blocked).
+
+Format:
+---
+title: <Feature name>
+description: <One sentence: what this builds and why>
+---
+# <Feature Name> Implementation Plan
+**Goal:** <one sentence>
+**Architecture:** <2-3 sentences>
+**Tech Stack:** <key technologies>
+---
+### Task N: <Component Name>
+**Files:** Create/Modify/Test with exact paths
+**Step 1: Write the failing test** — exact test code
+**Step 2: Run test to verify it fails** — exact command + expected FAIL output
+**Step 3: Write minimal implementation** — exact code
+**Step 4: Run test to verify it passes** — exact command + expected PASS
+**Step 5: Commit** — \`git commit -m "feat: ..."\`
+
+Rules: exact file paths, complete code, exact commands with expected output, bite-sized steps (2-5 min each), TDD first, DRY, YAGNI. Never git-add the plan.
+When done, say: "Plan saved to <path>. Use /plan to run it."
+The goal follows this guide.`;
+
+export interface Plan {
+	file: string;
+	title: string;
+	description: string;
+	body: string;
+}
+
+/** Parse `---\ntitle: …\ndescription: …\n---\nbody`. Missing frontmatter → file name as title. */
+export function parsePlan(file: string, text: string): Plan {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+	const meta = m?.[1] ?? "";
+	const field = (k: string) => new RegExp(`^${k}:\\s*(.*)$`, "m").exec(meta)?.[1]?.trim() ?? "";
+	return {
+		file,
+		title: field("title") || file.replace(/\.md$/, ""),
+		description: field("description"),
+		body: m ? (m[2] ?? "") : text,
+	};
+}
+
+/** True when `path` (relative to cwd or absolute) resolves inside `<cwd>/.pi/plans/`. */
+export function isPlanPath(cwd: string, path: string): boolean {
+	const rel = relative(resolve(cwd, PLAN_DIR), resolve(cwd, path));
+	return rel !== "" && !rel.startsWith("..") && !isAbsolute(rel);
+}
+
+function listPlans(cwd: string): Plan[] {
+	const dir = resolve(cwd, PLAN_DIR);
+	let files: string[];
+	try {
+		files = readdirSync(dir).filter((f) => f.endsWith(".md"));
+	} catch {
+		return [];
+	}
+	return files
+		.sort()
+		.reverse()
+		.map((f) => parsePlan(f, readFileSync(join(dir, f), "utf-8")));
+}
+
+/**
+ * Shift+Tab toggles plan mode. Tab cycles the thinking level, but only in an empty
+ * prompt with no autocomplete list open. Any text keeps Tab for Pi's completion.
+ * The thinking cycle reuses Pi's own `app.thinking.cycle` handler (status line included).
+ */
+export function attachModeKeys(editor: CustomEditor, toggleMode: () => void): void {
+	const handleInput = editor.handleInput.bind(editor);
+	editor.handleInput = (data: string) => {
+		if (matchesKey(data, "shift+tab")) {
+			toggleMode();
+			return;
+		}
+		if (matchesKey(data, "tab") && editor.getText() === "" && !editor.isShowingAutocomplete()) {
+			editor.actionHandlers.get("app.thinking.cycle")?.();
+			return;
+		}
+		handleInput(data);
+	};
+}
+
+/** Footer status: plan mode shows its icon and label, normal mode shows only its icon. */
+export function modeStatus(
+	on: boolean,
+	fg: (role: "warning" | "muted", text: string) => string,
+): string {
+	return on ? fg("warning", icon("mode.plan")) : fg("muted", icon("mode.normal"));
+}
+
+export default function registerPlanMode(pi: ExtensionAPI): void {
+	let enabled = false;
+	let toolsBefore: string[] | undefined;
+
+	function apply(ctx: ExtensionContext, on: boolean): void {
+		if (on && !enabled) {
+			toolsBefore = pi.getActiveTools();
+			pi.setActiveTools(PLAN_TOOLS);
+			mkdirSync(resolve(ctx.cwd, PLAN_DIR), { recursive: true });
+		} else if (!on && enabled) {
+			if (toolsBefore) pi.setActiveTools(toolsBefore);
+			toolsBefore = undefined;
+		}
+		const changed = enabled !== on;
+		enabled = on;
+		ctx.ui.setStatus(
+			"plan",
+			modeStatus(on, (r, t) => ctx.ui.theme.fg(r, t)),
+		);
+		pi.appendEntry(STATE_ENTRY, { enabled, toolsBefore });
+		if (changed) {
+			ctx.ui.notify(
+				on
+					? "Plan mode on: read + bash + write (.pi/plans only)."
+					: "Plan mode off: tools restored.",
+			);
+		}
+	}
+
+	async function openModal(ctx: ExtensionContext): Promise<void> {
+		let requestRender = () => {};
+		const result = await ctx.ui.custom<PlanModalResult | undefined>(
+			(tui, theme, kb, done) => {
+				requestRender = () => tui.requestRender();
+				return new PlanModal(listPlans(ctx.cwd), PLAN_DIR, enabled, tui, theme, kb, done);
+			},
+			{ overlay: true, overlayOptions: modalOverlayOptions() },
+		);
+		if (!result) return;
+		if (result.kind === "toggle") {
+			apply(ctx, !enabled);
+			return openModal(ctx);
+		}
+		if (result.kind === "new") {
+			apply(ctx, true);
+			// pix-display turns <prompt name="plan"> into a "prompt" chip and sends
+			// the tag verbatim, so the model sees the guide and the user sees a chip.
+			// pix-display adds the trailing space after the chip.
+			ctx.ui.setEditorText("");
+			ctx.ui.pasteToEditor(chipTag.prompt("plan", PLAN_GUIDE));
+			// pasteToEditor does not repaint; without this the chip waits for the next
+			// unrelated render (footer tick, keypress), which felt like a 2 s lag.
+			requestRender();
+			return;
+		}
+		const path = join(PLAN_DIR, result.plan.file);
+		if (result.kind === "edit") {
+			// The model edits the file. The chip holds the instruction + path; the user
+			// types only the change after it.
+			apply(ctx, true);
+			ctx.ui.setEditorText("");
+			ctx.ui.pasteToEditor(
+				chipTag.prompt(
+					"plan-edit",
+					`Edit the plan in \`${path}\` with \`write\`. Keep its title/description header. Apply the change the user gives after this tag.`,
+				),
+			);
+			requestRender();
+			return;
+		}
+		if (result.kind === "delete") {
+			rmSync(resolve(ctx.cwd, path));
+			ctx.ui.notify(`Deleted ${path}`, "info");
+			return openModal(ctx);
+		}
+		apply(ctx, false);
+		pi.sendUserMessage(`Execute the plan in \`${path}\`. Follow its tasks in order.`);
+	}
+
+	pi.registerCommand("plan", {
+		description: "Manage saved plans (.pi/plans): new, execute, edit, delete, toggle plan mode",
+		handler: async (_args, ctx) => openModal(ctx),
+	});
+
+	pi.registerShortcut(Key.ctrlAlt("p"), {
+		description: "Toggle plan mode",
+		handler: (ctx) => apply(ctx, !enabled),
+	});
+
+	// ponytail: registerShortcut("tab") runs before the editor and would break Pi's
+	// Tab autocomplete. Wrap the editor so Tab acts only when the prompt is empty.
+	pi.on("session_start", (_event, ctx) => {
+		if (ctx.mode !== "tui") return;
+		const previous = ctx.ui.getEditorComponent();
+		ctx.ui.setEditorComponent((tui, theme, kb) => {
+			const editor = previous?.(tui, theme, kb) ?? new CustomEditor(tui, theme, kb);
+			if (editor instanceof CustomEditor) attachModeKeys(editor, () => apply(ctx, !enabled));
+			return editor;
+		});
+	});
+
+	pi.on("tool_call", async (event, ctx) => {
+		if (!enabled) return;
+		if (!PLAN_TOOLS.includes(event.toolName)) {
+			return {
+				block: true,
+				reason:
+					"Plan mode: only read, bash, and write are allowed. Toggle off with Shift+Tab or ctrl+alt+p.",
+			};
+		}
+		if (isToolCallEventType("write", event) && !isPlanPath(ctx.cwd, event.input.path)) {
+			return {
+				block: true,
+				reason: `Plan mode: write only inside ${PLAN_DIR}/. Got: ${event.input.path}`,
+			};
+		}
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		const entry = ctx.sessionManager
+			.getEntries()
+			.filter(
+				(e: { type: string; customType?: string }) =>
+					e.type === "custom" && e.customType === STATE_ENTRY,
+			)
+			.pop() as { data?: { enabled?: boolean; toolsBefore?: string[] } } | undefined;
+		if (entry?.data?.enabled) {
+			toolsBefore = entry.data.toolsBefore;
+			enabled = true;
+			pi.setActiveTools(PLAN_TOOLS);
+		}
+		ctx.ui.setStatus(
+			"plan",
+			modeStatus(enabled, (r, t) => ctx.ui.theme.fg(r, t)),
+		);
+	});
+}