@narumitw/pi-plan-mode 0.1.17

package/LICENSE

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

package/README.md

@@ -0,0 +1,110 @@
+# 🧭 pi-plan-mode — Codex-like Plan Mode for Pi
+
+[![npm](https://img.shields.io/npm/v/@narumitw/pi-plan-mode)](https://www.npmjs.com/package/@narumitw/pi-plan-mode) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
+
+`@narumitw/pi-plan-mode` adds a Codex-like `/plan` collaboration mode to Pi. Plan mode is for read-only exploration, clarifying questions, and a final implementation-ready `<proposed_plan>` block before any code mutation happens.
+
+Pi core intentionally does not ship a built-in plan mode; this package provides one as an independently installable extension.
+
+## ✨ Features
+
+- Adds `/plan` to enter or manage Plan mode.
+- Adds `--plan` to start a session in Plan mode.
+- Restricts active tools to read-only tools while Plan mode is active.
+- Blocks mutating bash commands such as `rm`, `git commit`, dependency installs, redirects, and editor launches.
+- Injects Codex-like Plan mode instructions: explore first, ask only non-discoverable questions, do not mutate files, and finish with `<proposed_plan>`.
+- Detects proposed plan blocks and prompts you to implement, revise, or stay in Plan mode.
+- Persists Plan mode state in the Pi session so resume restores the mode.
+
+## 📦 Install
+
+```bash
+pi install npm:@narumitw/pi-plan-mode
+```
+
+Try without installing permanently:
+
+```bash
+pi -e npm:@narumitw/pi-plan-mode
+```
+
+Try this package locally from the repository root:
+
+```bash
+pi -e ./extensions/pi-plan-mode
+```
+
+## 🚀 Usage
+
+```text
+/plan
+```
+
+When Plan mode is active, ask the agent to design the change. The agent may inspect files and run read-only commands, but it should not edit files or execute the implementation.
+
+A complete Plan mode answer should include exactly one block like this:
+
+```xml
+<proposed_plan>
+# Title
+
+## Summary
+...
+
+## Key Changes
+...
+
+## Test Plan
+...
+
+## Assumptions
+...
+</proposed_plan>
+```
+
+After a proposed plan is detected, `/plan` lets you choose whether to implement the plan, revise it, stay in Plan mode, or exit Plan mode.
+
+You can also exit directly:
+
+```text
+/plan exit
+```
+
+## 🧠 Codex-like behavior
+
+This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
+
+- Plan mode is a conversational collaboration mode, not TODO/progress tracking.
+- `update_plan`-style checklist use is discouraged while Plan mode is active.
+- The implementation boundary is explicit: Plan mode restores tools only after you choose to leave it.
+- Pi extension safety is approximated with active-tool restriction plus bash filtering, so it may be stricter or looser than Codex core in edge cases.
+
+## 🗂️ Package layout
+
+```txt
+extensions/pi-plan-mode/
+├── src/
+│   └── plan-mode.ts
+├── README.md
+├── LICENSE
+├── tsconfig.json
+└── package.json
+```
+
+The package exposes its Pi extension through `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/plan-mode.ts"]
+  }
+}
+```
+
+## 🔎 Keywords
+
+Pi extension, Pi coding agent, plan mode, Codex-like plan mode, AI coding workflow, read-only planning, implementation plan.
+
+## 📄 License
+
+MIT. See [`LICENSE`](./LICENSE).

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@narumitw/pi-plan-mode",
+	"version": "0.1.17",
+	"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
+	"type": "module",
+	"license": "MIT",
+	"private": false,
+	"keywords": [
+		"pi-package",
+		"pi-extension",
+		"pi",
+		"plan-mode",
+		"planning"
+	],
+	"files": [
+		"src",
+		"README.md",
+		"LICENSE"
+	],
+	"pi": {
+		"extensions": [
+			"./src/plan-mode.ts"
+		]
+	},
+	"scripts": {
+		"check": "biome check . && npm run typecheck",
+		"format": "biome check --write .",
+		"typecheck": "tsc --noEmit"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.14",
+		"@mariozechner/pi-coding-agent": "0.73.0",
+		"typescript": "6.0.3"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/narumiruna/pi-extensions",
+		"directory": "extensions/pi-plan-mode"
+	}
+}

package/src/plan-mode.ts

@@ -0,0 +1,374 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+const STATE_ENTRY_TYPE = "plan-mode-state";
+const STATUS_KEY = "plan-mode";
+const PLAN_WIDGET_KEY = "plan-mode-plan";
+const PLAN_CONTEXT_MARKER = "[CODEX-LIKE PLAN MODE ACTIVE]";
+const READ_ONLY_TOOLS = ["read", "bash"];
+const DEFAULT_TOOLS = ["read", "bash", "edit", "write"];
+const MUTATING_TOOLS = new Set(["edit", "write"]);
+const PROPOSED_PLAN_PATTERN = /<proposed_plan>\s*([\s\S]*?)\s*<\/proposed_plan>/i;
+
+interface PlanModeState {
+	enabled: boolean;
+	latestPlan?: string;
+	awaitingAction: boolean;
+}
+
+type SessionEntry = {
+	type?: string;
+	customType?: string;
+	data?: Partial<PlanModeState>;
+	message?: SessionMessage;
+};
+
+type SessionMessage = {
+	role?: string;
+	content?: unknown;
+};
+
+type TextBlock = {
+	type?: string;
+	text?: string;
+};
+
+const MUTATING_BASH_PATTERNS = [
+	/\brm\b/i,
+	/\brmdir\b/i,
+	/\bmv\b/i,
+	/\bcp\b/i,
+	/\bmkdir\b/i,
+	/\btouch\b/i,
+	/\bchmod\b/i,
+	/\bchown\b/i,
+	/\bchgrp\b/i,
+	/\bln\b/i,
+	/\btee\b/i,
+	/\btruncate\b/i,
+	/\bdd\b/i,
+	/(^|[^<])>(?!>)/,
+	/>>/,
+	/\bnpm\s+(install|uninstall|update|ci|link|publish|version)\b/i,
+	/\byarn\s+(add|remove|install|publish|upgrade)\b/i,
+	/\bpnpm\s+(add|remove|install|publish|update)\b/i,
+	/\bbun\s+(add|remove|install|update|publish)\b/i,
+	/\bpip\s+(install|uninstall)\b/i,
+	/\buv\s+(add|remove|sync|lock|pip\s+install)\b/i,
+	/\bgit\s+(add|commit|push|pull|merge|rebase|reset|checkout|switch|stash|cherry-pick|revert|tag|init|clone)\b/i,
+	/\bsudo\b/i,
+	/\bsu\b/i,
+	/\bkill\b/i,
+	/\bpkill\b/i,
+	/\bkillall\b/i,
+	/\breboot\b/i,
+	/\bshutdown\b/i,
+	/\bsystemctl\s+(start|stop|restart|enable|disable)\b/i,
+	/\bservice\s+\S+\s+(start|stop|restart)\b/i,
+	/\b(vim?|nano|emacs|code|subl)\b/i,
+];
+
+const SAFE_BASH_PATTERNS = [
+	/^\s*(cat|head|tail|less|more|grep|find|ls|pwd|echo|printf|wc|sort|uniq|diff|file|stat|du|df|tree|which|whereis|type|env|printenv|uname|whoami|id|date|uptime|ps|jq|awk|rg|fd|bat|eza)\b/i,
+	/^\s*sed\s+-n\b/i,
+	/^\s*git\s+(status|log|diff|show|branch|remote|config\s+--get|ls-files|grep)\b/i,
+	/^\s*npm\s+(list|ls|view|info|search|outdated|audit)\b/i,
+	/^\s*(node|python|python3|npm|tsc|biome|ruff|ty)\s+--version\b/i,
+];
+
+export default function planMode(pi: ExtensionAPI) {
+	let state: PlanModeState = { enabled: false, awaitingAction: false };
+	let previousTools: string[] | undefined;
+
+	pi.registerFlag("plan", {
+		description: "Start in Codex-like Plan mode",
+		type: "boolean",
+		default: false,
+	});
+
+	pi.registerCommand("plan", {
+		description: "Enter or manage Codex-like Plan mode",
+		handler: async (args, ctx) => {
+			const command = args.trim().toLowerCase();
+			if (command === "exit" || command === "off") {
+				exitPlanMode(ctx);
+				ctx.ui.notify("Plan mode disabled. Full tool access restored.", "info");
+				return;
+			}
+			if (!state.enabled) {
+				enterPlanMode(ctx);
+				ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
+				return;
+			}
+			await showPlanMenu(ctx);
+		},
+	});
+
+	pi.on("session_start", (_event, ctx) => {
+		restoreState(ctx);
+		if (pi.getFlag("plan") === true) state.enabled = true;
+		if (state.enabled) activateReadOnlyTools();
+		updateUi(ctx);
+	});
+
+	pi.on("session_shutdown", (_event, ctx) => {
+		persistState();
+		clearUi(ctx);
+	});
+
+	pi.on("tool_call", async (event) => {
+		if (!state.enabled) return;
+		if (MUTATING_TOOLS.has(event.toolName)) {
+			return {
+				block: true,
+				reason: `Plan mode blocks mutating tool '${event.toolName}'. Use /plan and choose implementation when the plan is ready.`,
+			};
+		}
+		if (event.toolName !== "bash") return;
+
+		const command = readCommand(event.input);
+		if (!isSafeCommand(command)) {
+			return {
+				block: true,
+				reason: `Plan mode blocks mutating or non-allowlisted bash commands.\nCommand: ${command}`,
+			};
+		}
+	});
+
+	pi.on("context", async (event) => {
+		if (state.enabled) return;
+		return {
+			messages: event.messages.filter((message: unknown) => !messageContainsPlanModeContext(message)),
+		};
+	});
+
+	pi.on("before_agent_start", () => {
+		if (!state.enabled) return;
+		return {
+			message: {
+				customType: "plan-mode-context",
+				content: buildPlanModePrompt(),
+				display: false,
+			},
+		};
+	});
+
+	pi.on("agent_end", async (event, ctx) => {
+		if (!state.enabled) return;
+
+		const text = latestAssistantText(event.messages);
+		const proposedPlan = extractProposedPlan(text);
+		if (!proposedPlan) {
+			persistState();
+			updateUi(ctx);
+			return;
+		}
+
+		state = { ...state, latestPlan: proposedPlan, awaitingAction: true };
+		persistState();
+		updateUi(ctx);
+		pi.sendMessage(
+			{
+				customType: "proposed-plan",
+				content: `**Proposed Plan**\n\n${proposedPlan}`,
+				display: true,
+			},
+			{ triggerTurn: false },
+		);
+
+		if (ctx.hasUI) await showPlanReadyMenu(ctx);
+	});
+
+	function enterPlanMode(ctx: ExtensionContext) {
+		if (!state.enabled) previousTools = safeGetActiveTools();
+		state = { ...state, enabled: true, awaitingAction: false };
+		activateReadOnlyTools();
+		persistState();
+		updateUi(ctx);
+	}
+
+	function exitPlanMode(ctx: ExtensionContext) {
+		state = { ...state, enabled: false, awaitingAction: false };
+		restoreTools();
+		persistState();
+		updateUi(ctx);
+	}
+
+	async function showPlanMenu(ctx: ExtensionContext) {
+		if (!ctx.hasUI) {
+			ctx.ui.notify(planStatusText(), "info");
+			return;
+		}
+
+		const choices = state.latestPlan
+			? ["Show latest proposed plan", "Implement this plan", "Stay in Plan mode", "Exit Plan mode"]
+			: ["Stay in Plan mode", "Exit Plan mode"];
+		const choice = await ctx.ui.select(planStatusText(), choices);
+		if (choice === "Show latest proposed plan") {
+			ctx.ui.notify(state.latestPlan ?? "No proposed plan yet.", "info");
+			return;
+		}
+		if (choice === "Implement this plan" || choice === "Exit Plan mode") {
+			exitPlanMode(ctx);
+			ctx.ui.notify("Plan mode disabled. Full tool access restored.", "info");
+			return;
+		}
+		updateUi(ctx);
+	}
+
+	async function showPlanReadyMenu(ctx: ExtensionContext) {
+		const choice = await ctx.ui.select("Proposed plan ready. What next?", [
+			"Implement this plan",
+			"Revise plan",
+			"Stay in Plan mode",
+		]);
+		if (choice === "Implement this plan") {
+			exitPlanMode(ctx);
+			ctx.ui.notify("Plan mode disabled. Ask me to implement the proposed plan when ready.", "info");
+			return;
+		}
+		if (choice === "Revise plan") {
+			const refinement = await ctx.ui.editor("Revise the plan", "");
+			if (refinement?.trim()) pi.sendUserMessage(refinement.trim());
+		}
+	}
+
+	function activateReadOnlyTools() {
+		previousTools ??= safeGetActiveTools();
+		pi.setActiveTools(READ_ONLY_TOOLS);
+	}
+
+	function restoreTools() {
+		pi.setActiveTools(previousTools && previousTools.length > 0 ? previousTools : DEFAULT_TOOLS);
+		previousTools = undefined;
+	}
+
+	function safeGetActiveTools() {
+		try {
+			return pi.getActiveTools();
+		} catch {
+			return DEFAULT_TOOLS;
+		}
+	}
+
+	function persistState() {
+		pi.appendEntry<PlanModeState>(STATE_ENTRY_TYPE, state);
+	}
+
+	function restoreState(ctx: ExtensionContext) {
+		const entries = ctx.sessionManager.getEntries() as SessionEntry[];
+		const entry = entries
+			.filter((candidate) => candidate.type === "custom" && candidate.customType === STATE_ENTRY_TYPE)
+			.pop();
+		if (!entry?.data) return;
+		state = {
+			enabled: entry.data.enabled ?? false,
+			latestPlan: entry.data.latestPlan,
+			awaitingAction: entry.data.awaitingAction ?? false,
+		};
+	}
+
+	function updateUi(ctx: ExtensionContext) {
+		ctx.ui.setStatus(STATUS_KEY, state.enabled ? "plan: active" : undefined);
+		if (state.enabled && state.latestPlan) {
+			ctx.ui.setWidget(PLAN_WIDGET_KEY, [
+				"Proposed plan ready",
+				"Use /plan to implement, revise, or exit Plan mode.",
+			]);
+		} else if (state.enabled) {
+			ctx.ui.setWidget(PLAN_WIDGET_KEY, ["Plan mode: read-only", "Produce a <proposed_plan> block."]);
+		} else {
+			ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
+		}
+	}
+
+	function clearUi(ctx: ExtensionContext) {
+		ctx.ui.setStatus(STATUS_KEY, undefined);
+		ctx.ui.setWidget(PLAN_WIDGET_KEY, undefined);
+	}
+
+	function planStatusText() {
+		if (!state.enabled) return "Plan mode is off.";
+		if (state.latestPlan) return "Plan mode is active and a proposed plan is ready.";
+		return "Plan mode is active. Explore, ask, and produce a <proposed_plan> block.";
+	}
+}
+
+function buildPlanModePrompt() {
+	return `${PLAN_CONTEXT_MARKER}
+You are in Plan Mode, a Codex-like collaboration mode for producing a decision-complete implementation plan.
+
+Mode rules:
+- Stay in Plan Mode until a developer or extension explicitly exits it.
+- Treat requests to implement as requests to plan the implementation; do not edit files or carry out the plan.
+- Use non-mutating exploration first: read files, search, inspect configuration, run read-only checks, and resolve discoverable facts before asking the user.
+- Ask the user only for preferences or tradeoffs that cannot be discovered from the repository.
+- Do not use update_plan/TODO tooling in Plan Mode; Plan Mode is conversational planning, not execution progress tracking.
+- Do not perform mutating actions: no edit/write tools, no patching, no formatting that rewrites files, no dependency installation, no commits, no migrations.
+- When the plan is decision-complete, output exactly one proposed plan block using:
+<proposed_plan>
+# Title
+
+## Summary
+...
+
+## Key Changes
+...
+
+## Test Plan
+...
+
+## Assumptions
+...
+</proposed_plan>
+- Keep the proposed plan concise, implementation-ready, and free of open decisions.`;
+}
+
+function readCommand(input: unknown) {
+	const command = input as { command?: unknown } | undefined;
+	return typeof command?.command === "string" ? command.command : "";
+}
+
+function isSafeCommand(command: string) {
+	const trimmed = command.trim();
+	if (!trimmed) return false;
+	if (MUTATING_BASH_PATTERNS.some((pattern) => pattern.test(trimmed))) return false;
+	return SAFE_BASH_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+function extractProposedPlan(text: string) {
+	const match = PROPOSED_PLAN_PATTERN.exec(text);
+	return match?.[1]?.trim();
+}
+
+function latestAssistantText(messages: unknown) {
+	if (!Array.isArray(messages)) return "";
+	for (const entry of [...messages].reverse()) {
+		const message = (entry as { message?: SessionMessage })?.message ?? (entry as SessionMessage);
+		if (message?.role !== "assistant") continue;
+		const text = messageText(message);
+		if (text) return text;
+	}
+	return "";
+}
+
+function messageContainsPlanModeContext(message: unknown) {
+	const candidate = message as { customType?: string; content?: unknown };
+	if (candidate.customType === "plan-mode-context") return true;
+	return contentText(candidate.content).includes(PLAN_CONTEXT_MARKER);
+}
+
+function messageText(message: SessionMessage) {
+	return contentText(message.content);
+}
+
+function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((block) => {
+			const textBlock = block as TextBlock;
+			return textBlock.type === "text" && typeof textBlock.text === "string" ? textBlock.text : "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}