@narumitw/pi-plan-mode 0.17.2 → 0.20.0

package/README.md

@@ -12,7 +12,7 @@ Pi core intentionally does not ship a built-in plan mode; this package provides
 - Adds `--plan` to start a session in Plan mode.
 - Enables built-in read-only tools by default while Plan mode is active.
 - Disables extension and custom tools by default, with a `/plan tools` selector for explicit user-risk opt-in.
-- Blocks `update_plan`, mutating built-in tools, and unsafe shell forms such as writes, substitutions, background jobs, dependency installs, and mutating Git commands.
+- Blocks `update_plan`, mutating built-in tools, and unsafe `bash` forms such as writes, substitutions, background jobs, dependency installs, and mutating Git commands.
 - Injects Codex-like Plan mode instructions: explore first, ask decision questions for high-impact ambiguity, do not mutate files, and finalize only when decision-complete.
 - Adds required `plan_mode_question` and `plan_mode_complete` tools for structured questions and completion.
 - Presents the complete plan and prompts you to implement, stay in Plan mode, or exit and discard it.
@@ -58,7 +58,7 @@ When Plan mode is active, ask the agent to design the change. The agent may insp
 
 By default, Plan mode manages only Pi's built-in tools: `read`, limited `bash`, available read-only built-ins such as `grep`, `find`, and `ls`, plus the required `plan_mode_question` and `plan_mode_complete` tools. Built-in `edit` and `write` are blocked. `update_plan` is also blocked because it tracks execution progress rather than conversational planning. Extension and custom tools are disabled by default because Pi tools do not expose standardized mutability metadata; enable them from `/plan tools` only when you accept the risk for that session. For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
 
-Limited `bash` uses a fail-closed policy. It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`. It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands. Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted. This is extension-level risk reduction, not an OS sandbox.
+Limited `bash` uses a fail-closed policy, including when an extension overrides the canonical `bash` tool name. It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`. It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands. Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted. This is extension-level risk reduction, not an OS sandbox.
 
 `plan_mode_question` follows Codex's `request_user_input` pattern: the agent can ask 1-3 concise questions, each with meaningful options and a free-form Other path. If you cancel or no interactive UI is available, the agent should ask a concise plain-text question or proceed only with a clearly stated low-risk assumption instead of prematurely producing a final plan.
 
@@ -102,7 +102,7 @@ Create `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-m
 
 `defaultPlanTools` defines the initial tool selection when a session has no stored `/plan tools` selection. Omit it to keep the available safe built-ins as the default. An explicit empty array is valid and enables only the required `plan_mode_question` and `plan_mode_complete` tools.
 
-Tool names must be non-empty strings; duplicates are removed in first-seen order. Unknown, unavailable, and Plan-mode-blocked names are ignored when tools are activated. A tool registered after Plan mode is already active is not added automatically; re-enter Plan mode or reopen `/plan tools` to reapply the selection. Non-built-in tools named in this global setting are an explicit user-risk opt-in, just like selecting them with `/plan tools`. Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
+Tool names must be non-empty strings; duplicates are removed in first-seen order. Unknown, unavailable, and Plan-mode-blocked names are ignored when tools are activated. A tool registered after Plan mode is already active is not added automatically; re-enter Plan mode or reopen `/plan tools` to reapply the selection. Non-built-in tools named in this global setting are an explicit user-risk opt-in, just like selecting them with `/plan tools`. Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead. An effective tool named `bash` remains subject to the limited-shell policy regardless of its source metadata.
 
 A selection made with `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes. The global setting remains the baseline for fresh sessions and sessions without an explicit selection.
 
@@ -160,7 +160,7 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
 - The agent completes with a standalone `plan_mode_complete` tool call instead of relying on semantic prose detection.
 - `update_plan` checklist use is blocked while Plan mode is active.
 - The implementation boundary is explicit: Plan mode restores tools before starting implementation, choosing implementation immediately triggers a normal agent turn with full tool access, and plain exit/off discards the stored plan.
-- Pi extension safety is approximated with tool classification and fail-closed bash filtering; non-built-in tools remain user-selected at user risk because Pi does not expose standardized tool mutability metadata.
+- Pi extension safety is approximated with tool classification and fail-closed filtering for every effective tool named `bash`; other non-built-in tools remain user-selected at user risk because Pi does not expose standardized tool mutability metadata.
 - Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
 
 ## 🗂️ Package layout

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-plan-mode",
-	"version": "0.17.2",
+	"version": "0.20.0",
 	"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
 	"type": "module",
 	"license": "MIT",
@@ -29,8 +29,8 @@
 	},
 	"devDependencies": {
 		"@biomejs/biome": "2.5.3",
-		"@earendil-works/pi-coding-agent": "0.80.6",
-		"typescript": "6.0.3"
+		"@earendil-works/pi-coding-agent": "0.80.10",
+		"typescript": "7.0.2"
 	},
 	"repository": {
 		"type": "git",

package/src/plan-mode.ts

@@ -23,8 +23,10 @@ import {
 	planModeQuestionAnswered,
 	planModeQuestionCancelled,
 } from "./question-tool.js";
+import { showPersistentSelector } from "./selector-ui.js";
 import {
 	configuredThinkingLevel,
+	type PlanModeFixedThinkingLevel,
 	type PlanModeSettings,
 	readPlanModeSettings,
 } from "./settings.js";
@@ -46,6 +48,20 @@ const BLOCKED_BUILTIN_TOOLS = new Set(["edit", "write"]);
 const DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
 const TOOL_SELECTOR_PAGE_SIZE = 10;
 
+type AgentSettledHandler = (event: unknown, ctx: ExtensionContext) => unknown;
+
+function onAgentSettled(pi: ExtensionAPI, handler: AgentSettledHandler) {
+	(
+		pi as unknown as {
+			on(event: "agent_settled", callback: AgentSettledHandler): void;
+		}
+	).on("agent_settled", handler);
+}
+
+function setPlanThinkingLevel(pi: ExtensionAPI, level: PlanModeFixedThinkingLevel) {
+	(pi.setThinkingLevel as unknown as (level: PlanModeFixedThinkingLevel) => void)(level);
+}
+
 interface CommandArgumentCompletion {
 	value: string;
 	label: string;
@@ -58,6 +74,10 @@ interface ReadyPresentationIntent {
 	source: PlanCompletionSource;
 }
 
+type PlanToolSelectorValue =
+	| { kind: "tool"; tool: ToolInfo }
+	| { kind: "action"; action: "previous" | "next" | "done" };
+
 const PLAN_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 	{ value: "show", label: "show", description: "Show the completed plan" },
 	{ value: "finalize", label: "finalize", description: "Request a completed plan" },
@@ -256,7 +276,8 @@ export default function planMode(pi: ExtensionAPI) {
 				reason: `Plan mode blocks built-in tool '${event.toolName}' because its metadata is unavailable.`,
 			};
 		}
-		if (event.toolName !== "bash" || !isBuiltinToolName(event.toolName)) return;
+		// Built-in-compatible overrides retain the canonical name but replace its source metadata.
+		if (event.toolName !== "bash") return;
 
 		const command = readCommand(event.input);
 		if (!isSafeCommand(command, settings.safeSubcommands)) {
@@ -316,7 +337,7 @@ export default function planMode(pi: ExtensionAPI) {
 		acceptCompletedPlan(parsedPlan.plan, "legacy_proposed_plan", ctx);
 	});
 
-	pi.on("agent_settled", async (_event, ctx) => {
+	onAgentSettled(pi, async (_event, ctx) => {
 		const intent = readyPresentationIntent;
 		if (!intent || !readyPresentationIsCurrent(intent)) return;
 		if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
@@ -547,6 +568,56 @@ export default function planMode(pi: ExtensionAPI) {
 			return;
 		}
 
+		const tools = selectableTools();
+		const pageCount = toolSelectorPageCount(tools);
+		let pageIndex = 0;
+		const customHandled = await showPersistentSelector(
+			ctx,
+			() => {
+				pageIndex = Math.min(pageIndex, pageCount - 1);
+				const pageStart = pageIndex * TOOL_SELECTOR_PAGE_SIZE;
+				const pageTools = tools.slice(pageStart, pageStart + TOOL_SELECTOR_PAGE_SIZE);
+				const selectedNames = planModeSelectedNames(tools);
+				const rows: Array<{ value: PlanToolSelectorValue; label: string }> = pageTools.map(
+					(tool, index) => ({
+						value: { kind: "tool", tool },
+						label: formatToolChoice(tool, selectedNames.has(tool.name), pageStart + index),
+					}),
+				);
+				if (pageIndex > 0) {
+					rows.push({ value: { kind: "action", action: "previous" }, label: "Previous page" });
+				}
+				if (pageIndex < pageCount - 1) {
+					rows.push({ value: { kind: "action", action: "next" }, label: "Next page" });
+				}
+				rows.push({ value: { kind: "action", action: "done" }, label: "Done" });
+				return {
+					title: `Plan-mode tools (${pageIndex + 1}/${pageCount}). Non-built-in tools run at user risk.`,
+					rows,
+				};
+			},
+			(value) => {
+				if (value.kind === "action") {
+					if (value.action === "done") return "close";
+					pageIndex += value.action === "previous" ? -1 : 1;
+					return "reset";
+				}
+				if (!canSelectToolInPlanMode(value.tool)) {
+					ctx.ui.notify(`${value.tool.name} is blocked in Plan mode.`, "warning");
+					return "stay";
+				}
+				togglePlanModeTool(value.tool, tools, ctx);
+				return "stay";
+			},
+		);
+		if (!customHandled) await showDialogToolSelector(ctx);
+
+		applyPlanModeTools();
+		persistState();
+		updateUi(ctx);
+	}
+
+	async function showDialogToolSelector(ctx: ExtensionContext) {
 		let pageIndex = 0;
 		while (true) {
 			const tools = selectableTools();
@@ -570,7 +641,7 @@ export default function planMode(pi: ExtensionAPI) {
 				`Plan-mode tools (${pageIndex + 1}/${pageCount}). Non-built-in tools run at user risk.`,
 				[...choices, ...navigationChoices],
 			);
-			if (!choice || choice === doneChoice) break;
+			if (!choice || choice === doneChoice) return;
 			if (choice === previousChoice) {
 				pageIndex = Math.max(0, pageIndex - 1);
 				continue;
@@ -579,28 +650,24 @@ export default function planMode(pi: ExtensionAPI) {
 				pageIndex = Math.min(pageCount - 1, pageIndex + 1);
 				continue;
 			}
-
-			const selectedIndex = choices.indexOf(choice);
-			const tool = pageTools[selectedIndex];
+			const tool = pageTools[choices.indexOf(choice)];
 			if (!tool) continue;
 			if (!canSelectToolInPlanMode(tool)) {
 				ctx.ui.notify(`${tool.name} is blocked in Plan mode.`, "warning");
 				continue;
 			}
-
-			const nextSelectedNames = planModeSelectedNames(tools);
-			if (nextSelectedNames.has(tool.name)) nextSelectedNames.delete(tool.name);
-			else nextSelectedNames.add(tool.name);
-
-			state = {
-				...state,
-				selectedToolNames: filterAvailableSelectedNames(Array.from(nextSelectedNames), tools),
-			};
-			applyPlanModeTools();
-			persistState();
-			updateUi(ctx);
+			togglePlanModeTool(tool, tools, ctx);
 		}
+	}
 
+	function togglePlanModeTool(tool: ToolInfo, tools: ToolInfo[], ctx: ExtensionContext) {
+		const nextSelectedNames = planModeSelectedNames(tools);
+		if (nextSelectedNames.has(tool.name)) nextSelectedNames.delete(tool.name);
+		else nextSelectedNames.add(tool.name);
+		state = {
+			...state,
+			selectedToolNames: filterAvailableSelectedNames(Array.from(nextSelectedNames), tools),
+		};
 		applyPlanModeTools();
 		persistState();
 		updateUi(ctx);
@@ -697,7 +764,7 @@ export default function planMode(pi: ExtensionAPI) {
 	function applyPlanThinkingLevel() {
 		if (state.manualThinkingLevel) {
 			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
-				pi.setThinkingLevel(state.manualThinkingLevel);
+				setPlanThinkingLevel(pi, state.manualThinkingLevel);
 			}
 			return;
 		}
@@ -712,7 +779,7 @@ export default function planMode(pi: ExtensionAPI) {
 		}
 		const current = pi.getThinkingLevel();
 		if (!state.appliedThinkingLevel) state.previousThinkingLevel = current;
-		if (current !== configured) pi.setThinkingLevel(configured);
+		if (current !== configured) setPlanThinkingLevel(pi, configured);
 		state.appliedThinkingLevel = pi.getThinkingLevel();
 	}
 
@@ -736,7 +803,7 @@ export default function planMode(pi: ExtensionAPI) {
 			previousThinkingLevel &&
 			pi.getThinkingLevel() === appliedThinkingLevel
 		) {
-			pi.setThinkingLevel(previousThinkingLevel);
+			setPlanThinkingLevel(pi, previousThinkingLevel);
 		}
 		state = { ...state, appliedThinkingLevel: undefined, previousThinkingLevel: undefined };
 	}
@@ -806,11 +873,6 @@ export default function planMode(pi: ExtensionAPI) {
 		return `Tools: ${names.length > 0 ? names.join(", ") : "none"}`;
 	}
 
-	function isBuiltinToolName(toolName: string) {
-		const tool = toolByName(toolName);
-		return tool ? isBuiltinTool(tool) : toolName === "bash";
-	}
-
 	function toolByName(toolName: string) {
 		return safeGetAllTools().find((candidate) => candidate.name === toolName);
 	}

package/src/selector-ui.ts

@@ -0,0 +1,95 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface PersistentSelectorRow<T> {
+	value: T;
+	label: string;
+}
+
+export interface PersistentSelectorView<T> {
+	title: string;
+	rows: PersistentSelectorRow<T>[];
+	help?: string;
+}
+
+export type PersistentSelectorActivation = "stay" | "reset" | "close";
+
+export async function showPersistentSelector<T>(
+	ctx: ExtensionContext,
+	getView: () => PersistentSelectorView<T>,
+	onActivate: (value: T) => PersistentSelectorActivation,
+): Promise<boolean> {
+	const result = await ctx.ui.custom<"closed" | undefined>((tui, theme, keybindings, done) => {
+		let selectedIndex = 0;
+		const currentView = () => {
+			const view = getView();
+			selectedIndex = Math.min(selectedIndex, Math.max(0, view.rows.length - 1));
+			return view;
+		};
+		const moveSelection = (delta: number) => {
+			const { rows } = currentView();
+			if (rows.length === 0) return;
+			selectedIndex = (selectedIndex + delta + rows.length) % rows.length;
+		};
+		const activateSelectedRow = () => {
+			const row = currentView().rows[selectedIndex];
+			if (!row) return;
+			const action = onActivate(row.value);
+			if (action === "reset") selectedIndex = 0;
+			else if (action === "close") done("closed");
+		};
+
+		return {
+			invalidate() {},
+			render(width: number) {
+				const view = currentView();
+				return [
+					theme.fg("accent", theme.bold(clipLine(view.title, width))),
+					"",
+					...view.rows.map((row, index) => {
+						const prefix = index === selectedIndex ? "› " : "  ";
+						const line = clipLine(`${prefix}${row.label}`, width);
+						return index === selectedIndex ? theme.fg("accent", line) : line;
+					}),
+					"",
+					theme.fg(
+						"dim",
+						clipLine(view.help ?? "↑↓ navigate • Enter/Space toggle • Esc close", width),
+					),
+				];
+			},
+			handleInput(data: string) {
+				if (keybindings.matches(data, "tui.select.up")) {
+					moveSelection(-1);
+					tui.requestRender();
+					return;
+				}
+				if (keybindings.matches(data, "tui.select.down")) {
+					moveSelection(1);
+					tui.requestRender();
+					return;
+				}
+				if (keybindings.matches(data, "tui.select.pageUp")) {
+					selectedIndex = 0;
+					tui.requestRender();
+					return;
+				}
+				if (keybindings.matches(data, "tui.select.pageDown")) {
+					selectedIndex = Math.max(0, currentView().rows.length - 1);
+					tui.requestRender();
+					return;
+				}
+				if (keybindings.matches(data, "tui.select.confirm") || data === " ") {
+					activateSelectedRow();
+					tui.requestRender();
+					return;
+				}
+				if (keybindings.matches(data, "tui.select.cancel")) done("closed");
+			},
+		};
+	});
+	return result === "closed";
+}
+
+function clipLine(value: string, width: number) {
+	return Array.from(value).slice(0, Math.max(0, width)).join("");
+}