@narumitw/pi-plan-mode 0.13.0 → 0.14.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 mutating built-in tools and bash commands such as `rm`, `git commit`, dependency installs, redirects, and editor launches.
+- Blocks `update_plan`, mutating built-in tools, and unsafe shell 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 finish with `<proposed_plan>` only when decision-complete.
 - Adds a required `plan_mode_question` tool so the agent can ask structured Plan-mode questions before finalizing a plan.
 - Detects proposed plan blocks and prompts you to implement, stay in Plan mode, or exit and discard the plan.
@@ -49,7 +49,9 @@ Use `/plan` to enter Plan mode before writing your planning prompt. Use `/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. It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
 
-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` tool. Built-in `edit` and `write` are blocked. 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 `biome_lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
+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` tool. 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, command substitution, 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.
 
@@ -75,7 +77,9 @@ A complete Plan mode answer should appear only after the agent has resolved disc
 </proposed_plan>
 ```
 
-After a proposed plan is detected, `/plan` lets you choose whether to implement the plan, stay in Plan mode, or exit Plan mode. Choosing implementation disables Plan mode, restores full tool access, and immediately starts an implementation turn with the proposed plan. Choosing Stay keeps the plan ready while you decide what to do next; to revise the plan, choose Stay and type your revision feedback in the normal prompt. When that next Plan-mode turn starts, the previous plan is no longer treated as the latest implementable plan unless the agent produces an updated `<proposed_plan>`. Choosing exit/off disables Plan mode and discards the proposed plan so it is not carried into later non-plan turns.
+The tags must be on their own lines and the block must be non-empty, complete, and unique within the response. Empty, malformed, unclosed, or multiple blocks keep Plan mode active and produce a warning so the plan can be corrected.
+
+After a valid proposed plan is detected, `/plan` lets you choose whether to implement the plan, stay in Plan mode, or exit Plan mode. Choosing implementation disables Plan mode, restores full tool access, and immediately starts an implementation turn with the proposed plan. Choosing Stay keeps the plan ready while you decide what to do next; to revise the plan, choose Stay and type your revision feedback in the normal prompt. When that next Plan-mode turn starts, the previous plan is no longer treated as the latest implementable plan unless the agent produces an updated `<proposed_plan>`. Choosing exit/off disables Plan mode and discards the proposed plan so it is not carried into later non-plan turns.
 
 While Plan mode is enabled, the extension also publishes a compact status for Pi statuslines. With `@narumitw/pi-statusline`, this appears in the extension status area:
 
@@ -88,6 +92,18 @@ You can also exit directly. Direct exit discards the latest proposed plan instea
 /plan exit
 ```
 
+## ⚙️ Thinking level
+
+Plan mode inherits Pi's current thinking level by default. To request a fixed level only while Plan mode is active, create `$PI_CODING_AGENT_DIR/plan-mode.json` (normally `~/.pi/agent/plan-mode.json`):
+
+```json
+{
+  "thinkingLevel": "medium"
+}
+```
+
+Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved. The settings file is optional, is read at session start, and never changes Pi's default setting. Invalid settings produce a warning and fall back to `inherit`.
+
 ## 🧠 Codex-like behavior
 
 This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
@@ -95,23 +111,25 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
 - Plan mode is a conversational collaboration mode, not TODO/progress tracking.
 - `/plan <prompt>` follows Codex behavior by switching to Plan mode before submitting the inline prompt.
 - The agent should use `plan_mode_question` for important non-discoverable preferences or tradeoffs before finalizing.
-- `update_plan`-style checklist use is discouraged while Plan mode is active.
+- `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 proposed plan.
-- Pi extension safety is approximated with built-in tool restriction plus bash filtering; non-built-in tools are user-selected at user risk because Plan mode does not classify extension/custom tool behavior.
+- 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.
+- Unlike native Codex, Pi detects complete plan blocks after the turn rather than streaming protocol-level Plan items, and it cannot provide sandbox-level enforcement.
 
 ## 🗂️ Package layout
 
 ```txt
 extensions/pi-plan-mode/
 ├── src/
-│   └── plan-mode.ts
+│   ├── plan-mode.ts  # Pi entrypoint and mode state
+│   └── *.ts          # Package-local prompt, policy, question, and message modules
 ├── README.md
 ├── LICENSE
 ├── tsconfig.json
 └── package.json
 ```
 
-The package exposes its Pi extension through `package.json`:
+Only `plan-mode.ts` is a Pi entrypoint; the other source modules are internal. The package exposes its Pi extension through `package.json`:
 
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-plan-mode",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
 	"type": "module",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.2",
+		"@biomejs/biome": "2.5.3",
 		"@earendil-works/pi-coding-agent": "0.80.3",
 		"typescript": "6.0.3"
 	},

package/src/message-transform.ts

@@ -0,0 +1,120 @@
+const PLAN_CONTEXT_MESSAGE_TYPE = "plan-mode-context";
+const PROPOSED_PLAN_MESSAGE_TYPE = "proposed-plan";
+const PROPOSED_PLAN_PATTERN = /^<proposed_plan>[\t ]*\r?\n([\s\S]*?)\r?\n<\/proposed_plan>[\t ]*$/gm;
+const PROPOSED_PLAN_BLOCK_PATTERN = /^<proposed_plan>[\t ]*\r?\n[\s\S]*?\r?\n<\/proposed_plan>[\t ]*$/gm;
+
+export type ProposedPlanParseResult =
+	| { kind: "absent" }
+	| { kind: "valid"; plan: string }
+	| { kind: "empty" }
+	| { kind: "multiple" }
+	| { kind: "malformed" }
+	| { kind: "unclosed" };
+
+type SessionMessage = {
+	role?: string;
+	content?: unknown;
+};
+
+type TextBlock = {
+	type?: string;
+	text?: string;
+};
+
+export function parseProposedPlan(text: string): ProposedPlanParseResult {
+	const openingCount = text.match(/<proposed_plan>/gi)?.length ?? 0;
+	const closingCount = text.match(/<\/proposed_plan>/gi)?.length ?? 0;
+	if (openingCount === 0 && closingCount === 0) return { kind: "absent" };
+	if (openingCount > 1 || closingCount > 1) return { kind: "multiple" };
+	if (openingCount === 1 && closingCount === 0) return { kind: "unclosed" };
+	if (openingCount !== 1 || closingCount !== 1) return { kind: "malformed" };
+
+	const matches = Array.from(text.matchAll(PROPOSED_PLAN_PATTERN));
+	if (matches.length !== 1) return { kind: "malformed" };
+	const plan = matches[0]?.[1]?.trim() ?? "";
+	return plan ? { kind: "valid", plan } : { kind: "empty" };
+}
+
+export function extractProposedPlan(text: string) {
+	const result = parseProposedPlan(text);
+	return result.kind === "valid" ? result.plan : undefined;
+}
+
+export 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 "";
+}
+
+export function messageContainsLegacyPlanModeContextArtifact(message: unknown) {
+	return unwrapSessionMessage(message).customType === PLAN_CONTEXT_MESSAGE_TYPE;
+}
+
+export function messageContainsInactivePlanModeArtifact(message: unknown) {
+	return unwrapSessionMessage(message).customType === PROPOSED_PLAN_MESSAGE_TYPE;
+}
+
+export function stripProposedPlanBlocksFromMessage<T>(message: T): T {
+	const candidate = unwrapSessionMessage(message);
+	if (candidate.role !== "assistant") return message;
+
+	const content = stripProposedPlanBlocksFromContent(candidate.content);
+	if (content === candidate.content) return message;
+
+	if (isSessionMessageEntry(message)) {
+		return { ...message, message: { ...candidate, content } };
+	}
+	return { ...candidate, content } as T;
+}
+
+function unwrapSessionMessage(message: unknown) {
+	const entry = message as { message?: unknown };
+	return (entry.message ?? message) as { role?: string; customType?: string; content?: unknown };
+}
+
+function isSessionMessageEntry<T>(message: T): message is T & { message: SessionMessage } {
+	return typeof message === "object" && message !== null && "message" in message;
+}
+
+function stripProposedPlanBlocksFromContent(content: unknown) {
+	if (typeof content === "string") return stripProposedPlanBlocks(content);
+	if (!Array.isArray(content)) return content;
+
+	let changed = false;
+	const nextContent = content.map((block) => {
+		const textBlock = block as TextBlock;
+		if (textBlock.type !== "text" || typeof textBlock.text !== "string") return block;
+
+		const text = stripProposedPlanBlocks(textBlock.text);
+		if (text === textBlock.text) return block;
+
+		changed = true;
+		return { ...textBlock, text };
+	});
+	return changed ? nextContent : content;
+}
+
+export function stripProposedPlanBlocks(text: string) {
+	return text.replace(PROPOSED_PLAN_BLOCK_PATTERN, "");
+}
+
+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");
+}