@narumitw/pi-plan-mode 0.13.1 → 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,9 +111,10 @@ 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-plan-mode",
-	"version": "0.13.1",
+	"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

@@ -1,7 +1,15 @@
 const PLAN_CONTEXT_MESSAGE_TYPE = "plan-mode-context";
 const PROPOSED_PLAN_MESSAGE_TYPE = "proposed-plan";
-const PROPOSED_PLAN_PATTERN = /<proposed_plan>\s*([\s\S]*?)\s*<\/proposed_plan>/i;
-const PROPOSED_PLAN_BLOCK_PATTERN = /<proposed_plan>\s*[\s\S]*?\s*<\/proposed_plan>/gi;
+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;
@@ -13,9 +21,23 @@ type TextBlock = {
 	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 match = PROPOSED_PLAN_PATTERN.exec(text);
-	return match?.[1]?.trim();
+	const result = parseProposedPlan(text);
+	return result.kind === "valid" ? result.plan : undefined;
 }
 
 export function latestAssistantText(messages: unknown) {

package/src/plan-mode.ts

@@ -1,7 +1,12 @@
-import type { ExtensionAPI, ExtensionContext, ToolInfo } from "@earendil-works/pi-coding-agent";
+import type {
+	ExtensionAPI,
+	ExtensionContext,
+	ToolInfo,
+} from "@earendil-works/pi-coding-agent";
 import {
 	extractProposedPlan,
 	latestAssistantText,
+	parseProposedPlan,
 	messageContainsInactivePlanModeArtifact,
 	messageContainsLegacyPlanModeContextArtifact,
 	stripProposedPlanBlocksFromMessage,
@@ -17,11 +22,19 @@ import {
 } from "./question-tool.js";
 import {
 	canSelectToolInPlanMode,
+	classifyPlanModeTool,
 	isBuiltinTool,
 	isSafeCommand,
 	readCommand,
 	SAFE_BUILTIN_PLAN_TOOLS,
 } from "./tool-policy.js";
+import {
+	configuredThinkingLevel,
+	PLAN_MODE_THINKING_LEVELS,
+	readPlanModeSettings,
+	type PlanModeFixedThinkingLevel,
+	type PlanModeSettings,
+} from "./settings.js";
 
 const STATE_ENTRY_TYPE = "plan-mode-state";
 const STATUS_KEY = "plan-mode";
@@ -43,6 +56,9 @@ interface PlanModeState {
 	awaitingAction: boolean;
 	selectedToolNames?: string[];
 	selectedToolKeys?: string[];
+	previousThinkingLevel?: PlanModeFixedThinkingLevel;
+	appliedThinkingLevel?: PlanModeFixedThinkingLevel;
+	manualThinkingLevel?: PlanModeFixedThinkingLevel;
 }
 
 type SessionEntry = {
@@ -70,6 +86,7 @@ const PLAN_COMMAND_COMPLETIONS: readonly CommandArgumentCompletion[] = [
 
 export default function planMode(pi: ExtensionAPI) {
 	let state: PlanModeState = { enabled: false, awaitingAction: false };
+	let settings: PlanModeSettings = { thinkingLevel: "inherit" };
 	let previousTools: string[] | undefined;
 
 	pi.registerFlag("plan", {
@@ -152,25 +169,65 @@ export default function planMode(pi: ExtensionAPI) {
 		},
 	});
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
+		settings = { thinkingLevel: "inherit" };
+		const loadedSettings = await readPlanModeSettings();
+		if (loadedSettings.kind === "loaded") settings = loadedSettings.settings;
+		else if (loadedSettings.kind === "invalid") {
+			ctx.ui.notify(`pi-plan-mode settings ignored: ${loadedSettings.reason}`, "warning");
+		}
 		restoreState(ctx);
 		if (pi.getFlag("plan") === true) state.enabled = true;
-		if (state.enabled) activatePlanModeTools();
-		else deactivatePlanModeQuestionTool();
+		if (state.enabled) {
+			activatePlanModeTools();
+			applyPlanThinkingLevel();
+		} else deactivatePlanModeQuestionTool();
 		updateUi(ctx);
 	});
 
+	pi.on("thinking_level_select", (event) => {
+		if (!state.enabled || !state.appliedThinkingLevel) return;
+		if (event.level !== state.appliedThinkingLevel) {
+			state = {
+				...state,
+				manualThinkingLevel: event.level,
+				previousThinkingLevel: undefined,
+				appliedThinkingLevel: undefined,
+			};
+			persistState();
+		}
+	});
+
 	pi.on("session_shutdown", (_event, ctx) => {
+		captureManualThinkingLevel();
 		persistState();
+		if (state.enabled) {
+			restoreTools();
+			restoreThinkingLevel();
+		}
 		clearUi(ctx);
 	});
 
 	pi.on("tool_call", async (event) => {
 		if (!state.enabled) return;
-		if (isBlockedBuiltinToolName(event.toolName)) {
+		if (event.toolName === "update_plan") {
+			return {
+				block: true,
+				reason:
+					"Plan mode blocks update_plan because it tracks execution progress rather than conversational planning.",
+			};
+		}
+		const calledTool = toolByName(event.toolName);
+		if (calledTool && classifyPlanModeTool(calledTool) === "blocked") {
 			return {
 				block: true,
-				reason: `Plan mode blocks built-in mutating tool '${event.toolName}'. Use /plan and choose implementation when the plan is ready.`,
+				reason: `Plan mode blocks built-in tool '${event.toolName}' because its policy class is blocked.`,
+			};
+		}
+		if (!calledTool && BLOCKED_BUILTIN_TOOLS.has(event.toolName)) {
+			return {
+				block: true,
+				reason: `Plan mode blocks built-in tool '${event.toolName}' because its metadata is unavailable.`,
 			};
 		}
 		if (event.toolName !== "bash" || !isBuiltinToolName(event.toolName)) return;
@@ -213,12 +270,16 @@ export default function planMode(pi: ExtensionAPI) {
 		if (!state.enabled) return;
 
 		const text = latestAssistantText(event.messages);
-		const proposedPlan = extractProposedPlan(text);
-		if (!proposedPlan) {
+		const parsedPlan = parseProposedPlan(text);
+		if (parsedPlan.kind !== "valid") {
+			if (parsedPlan.kind !== "absent") {
+				ctx.ui.notify(invalidPlanMessage(parsedPlan.kind), "warning");
+			}
 			persistState();
 			updateUi(ctx);
 			return;
 		}
+		const proposedPlan = parsedPlan.plan;
 
 		state = { ...state, latestPlan: proposedPlan, awaitingAction: true };
 		persistState();
@@ -244,6 +305,7 @@ export default function planMode(pi: ExtensionAPI) {
 		if (!state.enabled) previousTools = withoutPlanModeQuestionTool(safeGetActiveTools());
 		state = { ...state, enabled: true, awaitingAction: false };
 		activatePlanModeTools();
+		applyPlanThinkingLevel();
 		persistState();
 		updateUi(ctx);
 	}
@@ -254,20 +316,37 @@ export default function planMode(pi: ExtensionAPI) {
 		if (!wasEnabled) {
 			ctx.ui.notify("Plan mode enabled. I will explore and plan, but not modify files.", "info");
 		}
-		sendPlanModeUserMessage(prompt, ctx);
+		if (!sendPlanModeUserMessage(prompt, ctx) && !wasEnabled) exitPlanMode(ctx);
 	}
 
 	function exitPlanMode(ctx: ExtensionContext) {
 		const wasEnabled = state.enabled;
-		state = { ...state, enabled: false, latestPlan: undefined, awaitingAction: false };
-		if (wasEnabled) restoreTools();
+		state = {
+			...state,
+			enabled: false,
+			latestPlan: undefined,
+			awaitingAction: false,
+			manualThinkingLevel: undefined,
+		};
+		if (wasEnabled) {
+			restoreTools();
+			restoreThinkingLevel();
+			state = { ...state, manualThinkingLevel: undefined };
+		}
 		persistState();
 		updateUi(ctx);
 	}
 
 	function sendPlanModeUserMessage(message: string, ctx: ExtensionContext) {
-		if (ctx.isIdle()) pi.sendUserMessage(message);
-		else pi.sendUserMessage(message, { deliverAs: "followUp" });
+		try {
+			if (ctx.isIdle()) pi.sendUserMessage(message);
+			else pi.sendUserMessage(message, { deliverAs: "followUp" });
+			return true;
+		} catch (error: unknown) {
+			const detail = error instanceof Error ? error.message : String(error);
+			ctx.ui.notify(`Unable to send Plan-mode message: ${detail}`, "error");
+			return false;
+		}
 	}
 
 	function scheduleAfterCurrentAgentRun(task: () => Promise<void> | void) {
@@ -288,10 +367,16 @@ export default function planMode(pi: ExtensionAPI) {
 			return;
 		}
 
-		sendPlanModeUserMessage(
+		const sent = sendPlanModeUserMessage(
 			`Plan mode is now disabled. Full tool access is restored. Implement this proposed plan now:\n\n${plan}`,
 			ctx,
 		);
+		if (!sent) {
+			enterPlanMode(ctx);
+			state = { ...state, latestPlan: plan, awaitingAction: true };
+			persistState();
+			updateUi(ctx);
+		}
 	}
 
 	async function showPlanMenu(ctx: ExtensionContext) {
@@ -481,11 +566,58 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 
 	function restoreTools() {
-		const restoredTools = previousTools && previousTools.length > 0 ? previousTools : DEFAULT_TOOLS;
+		const restoredTools = previousTools ?? DEFAULT_TOOLS;
 		pi.setActiveTools(withoutPlanModeQuestionTool(restoredTools));
 		previousTools = undefined;
 	}
 
+	function applyPlanThinkingLevel() {
+		if (state.manualThinkingLevel) {
+			if (pi.getThinkingLevel() !== state.manualThinkingLevel) {
+				pi.setThinkingLevel(state.manualThinkingLevel);
+			}
+			return;
+		}
+		const configured = configuredThinkingLevel(settings);
+		if (!configured) {
+			state = {
+				...state,
+				previousThinkingLevel: undefined,
+				appliedThinkingLevel: undefined,
+			};
+			return;
+		}
+		const current = pi.getThinkingLevel();
+		if (!state.appliedThinkingLevel) state.previousThinkingLevel = current;
+		if (current !== configured) pi.setThinkingLevel(configured);
+		state.appliedThinkingLevel = pi.getThinkingLevel();
+	}
+
+	function captureManualThinkingLevel() {
+		if (!state.appliedThinkingLevel) return;
+		const current = pi.getThinkingLevel();
+		if (current === state.appliedThinkingLevel) return;
+		state = {
+			...state,
+			manualThinkingLevel: current,
+			previousThinkingLevel: undefined,
+			appliedThinkingLevel: undefined,
+		};
+	}
+
+	function restoreThinkingLevel() {
+		captureManualThinkingLevel();
+		const { appliedThinkingLevel, previousThinkingLevel } = state;
+		if (
+			appliedThinkingLevel &&
+			previousThinkingLevel &&
+			pi.getThinkingLevel() === appliedThinkingLevel
+		) {
+			pi.setThinkingLevel(previousThinkingLevel);
+		}
+		state = { ...state, appliedThinkingLevel: undefined, previousThinkingLevel: undefined };
+	}
+
 	function deactivatePlanModeQuestionTool() {
 		const activeTools = safeGetActiveTools();
 		const filteredTools = withoutPlanModeQuestionTool(activeTools);
@@ -507,18 +639,29 @@ export default function planMode(pi: ExtensionAPI) {
 	}
 
 	function restoreState(ctx: ExtensionContext) {
+		state = { enabled: false, awaitingAction: false };
 		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;
-		const enabled = entry.data.enabled ?? false;
+		if (!isRecord(entry?.data)) return;
+		const enabled = entry.data.enabled === true;
 		state = {
 			enabled,
-			latestPlan: enabled ? entry.data.latestPlan : undefined,
-			awaitingAction: enabled ? (entry.data.awaitingAction ?? false) : false,
-			selectedToolNames: entry.data.selectedToolNames,
-			selectedToolKeys: entry.data.selectedToolKeys,
+			latestPlan:
+				enabled && typeof entry.data.latestPlan === "string" ? entry.data.latestPlan : undefined,
+			awaitingAction: enabled && entry.data.awaitingAction === true,
+			selectedToolNames: stringArray(entry.data.selectedToolNames),
+			selectedToolKeys: stringArray(entry.data.selectedToolKeys),
+			previousThinkingLevel: enabled
+				? fixedThinkingLevel(entry.data.previousThinkingLevel)
+				: undefined,
+			appliedThinkingLevel: enabled
+				? fixedThinkingLevel(entry.data.appliedThinkingLevel)
+				: undefined,
+			manualThinkingLevel: enabled
+				? fixedThinkingLevel(entry.data.manualThinkingLevel)
+				: undefined,
 		};
 	}
 
@@ -562,12 +705,6 @@ export default function planMode(pi: ExtensionAPI) {
 		return `Tools: ${names.length > 0 ? names.join(", ") : "none"}`;
 	}
 
-	function isBlockedBuiltinToolName(toolName: string) {
-		if (!BLOCKED_BUILTIN_TOOLS.has(toolName)) return false;
-		const tool = toolByName(toolName);
-		return tool ? isBuiltinTool(tool) : true;
-	}
-
 	function isBuiltinToolName(toolName: string) {
 		const tool = toolByName(toolName);
 		return tool ? isBuiltinTool(tool) : toolName === "bash";
@@ -607,11 +744,11 @@ function formatToolChoice(tool: ToolInfo, selected: boolean, index: number) {
 }
 
 function toolPolicyLabel(tool: ToolInfo) {
-	if (isBuiltinTool(tool)) {
-		if (!SAFE_BUILTIN_PLAN_TOOLS.has(tool.name)) return "built-in blocked";
-		return tool.name === "bash" ? "built-in limited" : "built-in";
-	}
-	return `user risk: ${toolSourceLabel(tool)}`;
+	const policy = classifyPlanModeTool(tool);
+	if (policy === "read-only") return "built-in read-only";
+	if (policy === "limited") return "built-in limited";
+	if (policy === "blocked") return "built-in blocked";
+	return `user opt-in: ${toolSourceLabel(tool)}`;
 }
 
 function toolSourceLabel(tool: ToolInfo) {
@@ -624,6 +761,24 @@ function unique(values: string[]) {
 	return Array.from(new Set(values));
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function stringArray(value: unknown) {
+	return Array.isArray(value) && value.every((item): item is string => typeof item === "string")
+		? unique(value)
+		: undefined;
+}
+
+function fixedThinkingLevel(value: unknown): PlanModeFixedThinkingLevel | undefined {
+	return typeof value === "string" &&
+		value !== "inherit" &&
+		PLAN_MODE_THINKING_LEVELS.includes(value as (typeof PLAN_MODE_THINKING_LEVELS)[number])
+		? (value as PlanModeFixedThinkingLevel)
+		: undefined;
+}
+
 export function withRequiredPlanModeTools(toolNames: string[]) {
 	return unique([...withoutPlanModeQuestionTool(toolNames), PLAN_MODE_QUESTION_TOOL_NAME]);
 }
@@ -632,6 +787,24 @@ export function withoutPlanModeQuestionTool(toolNames: string[]) {
 	return toolNames.filter((toolName) => toolName !== PLAN_MODE_QUESTION_TOOL_NAME);
 }
 
-export { extractProposedPlan, latestAssistantText, stripProposedPlanBlocks, stripProposedPlanBlocksFromMessage } from "./message-transform.js";
+function invalidPlanMessage(kind: "empty" | "multiple" | "malformed" | "unclosed") {
+	const detail = {
+		empty: "the block is empty",
+		multiple: "more than one plan block was produced",
+		malformed: "the tags must be on their own lines",
+		unclosed: "the closing tag is missing",
+	}[kind];
+	return `Proposed plan is not ready: ${detail}. Continue Plan mode and produce one complete non-empty <proposed_plan> block.`;
+}
+
+export {
+	extractProposedPlan,
+	latestAssistantText,
+	parseProposedPlan,
+	stripProposedPlanBlocks,
+	stripProposedPlanBlocksFromMessage,
+} from "./message-transform.js";
+export { buildPlanModePrompt } from "./prompt.js";
 export { normalizePlanModeQuestionParams } from "./question-tool.js";
-export { canSelectToolInPlanMode, isSafeCommand } from "./tool-policy.js";
+export { normalizePlanModeSettings, readPlanModeSettings } from "./settings.js";
+export { canSelectToolInPlanMode, classifyPlanModeTool, isSafeCommand } from "./tool-policy.js";

package/src/prompt.ts

@@ -24,6 +24,7 @@ You are in Plan Mode, a Codex-like collaboration mode for producing a decision-c
 
 - Keep asking until you can clearly state the goal, success criteria, in/out of scope, constraints, current state, and key preferences/tradeoffs.
 - Bias toward questions over guessing: if a high-impact ambiguity remains, do not produce a proposed plan yet.
+- For an unanswered preference or tradeoff, use the recommended option only when it is low risk and record that default as an explicit assumption in the final plan.
 
 ## Phase 3 — Implementation chat
 
@@ -51,5 +52,7 @@ Only output the final plan when it is decision-complete and leaves no decisions
 ...
 </proposed_plan>
 
-Keep the proposed plan concise, human and agent digestible, and free of open decisions. Do not ask "should I proceed?" in the final output; the Plan-mode ready menu handles implementation, staying in Plan mode, or exit.`;
+Keep the proposed plan concise, human and agent digestible, and free of open decisions. Prefer grouped behavior-level changes over file-by-file or symbol-by-symbol inventories. Do not ask "should I proceed?" in the final output; the Plan-mode ready menu handles implementation, staying in Plan mode, or exit.
+
+Produce at most one <proposed_plan> block per turn. If the user requests revisions after a prior proposed plan, any new block must be a complete replacement. If there is not enough information for a complete replacement, continue planning without a block. If a follow-up only asks for clarification and does not change or challenge the plan, answer it and then reproduce the prior proposed plan unchanged.`;
 }

package/src/settings.ts

@@ -0,0 +1,68 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const PLAN_MODE_SETTINGS_FILE = "plan-mode.json";
+export const PLAN_MODE_THINKING_LEVELS = [
+	"inherit",
+	"off",
+	"minimal",
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+] as const;
+
+export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
+export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit">;
+export interface PlanModeSettings {
+	thinkingLevel: PlanModeThinkingLevel;
+}
+export type PlanModeSettingsLoadResult =
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string }
+	| { kind: "loaded"; settings: PlanModeSettings };
+
+export function normalizePlanModeSettings(value: unknown): PlanModeSettings | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const thinkingLevel = Object.hasOwn(value, "thinkingLevel")
+		? Reflect.get(value, "thinkingLevel")
+		: "inherit";
+	return PLAN_MODE_THINKING_LEVELS.includes(thinkingLevel as PlanModeThinkingLevel)
+		? { thinkingLevel: thinkingLevel as PlanModeThinkingLevel }
+		: undefined;
+}
+
+export async function readPlanModeSettings(
+	settingsPath = join(getAgentDir(), PLAN_MODE_SETTINGS_FILE),
+): Promise<PlanModeSettingsLoadResult> {
+	let contents: string;
+	try {
+		contents = await readFile(settingsPath, "utf8");
+	} catch (error: unknown) {
+		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid", reason: formatError(error) };
+	}
+	try {
+		const settings = normalizePlanModeSettings(JSON.parse(contents) as unknown);
+		return settings
+			? { kind: "loaded", settings }
+			: { kind: "invalid", reason: "invalid settings shape" };
+	} catch (error: unknown) {
+		return { kind: "invalid", reason: formatError(error) };
+	}
+}
+
+export function configuredThinkingLevel(
+	settings: PlanModeSettings,
+): PlanModeFixedThinkingLevel | undefined {
+	return settings.thinkingLevel === "inherit" ? undefined : settings.thinkingLevel;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}

package/src/tool-policy.ts

@@ -1,57 +1,86 @@
 import type { ToolInfo } from "@earendil-works/pi-coding-agent";
 
 export const SAFE_BUILTIN_PLAN_TOOLS = new Set(["read", "bash", "grep", "find", "ls"]);
+export type PlanModeToolPolicy = "read-only" | "limited" | "user-opt-in" | "blocked";
 
-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,
-];
+const BLOCKED_BUILTIN_TOOLS = new Set(["edit", "write"]);
+const MUTATING_COMMANDS = new Set([
+	"rm",
+	"rmdir",
+	"mv",
+	"cp",
+	"mkdir",
+	"touch",
+	"chmod",
+	"chown",
+	"chgrp",
+	"ln",
+	"tee",
+	"truncate",
+	"dd",
+	"sudo",
+	"su",
+	"kill",
+	"pkill",
+	"killall",
+	"reboot",
+	"shutdown",
+	"vim",
+	"vi",
+	"nano",
+	"emacs",
+	"code",
+	"subl",
+]);
+const READ_ONLY_COMMANDS = new Set([
+	"cat",
+	"head",
+	"tail",
+	"grep",
+	"find",
+	"ls",
+	"pwd",
+	"echo",
+	"printf",
+	"wc",
+	"sort",
+	"uniq",
+	"diff",
+	"file",
+	"stat",
+	"du",
+	"df",
+	"tree",
+	"which",
+	"whereis",
+	"type",
+	"printenv",
+	"uname",
+	"whoami",
+	"id",
+	"date",
+	"uptime",
+	"ps",
+	"jq",
+	"rg",
+	"fd",
+	"bat",
+	"eza",
+]);
 
 export function isBuiltinTool(tool: ToolInfo) {
 	return tool.sourceInfo.source === "builtin";
 }
 
+export function classifyPlanModeTool(tool: ToolInfo): PlanModeToolPolicy {
+	if (!isBuiltinTool(tool)) return "user-opt-in";
+	if (BLOCKED_BUILTIN_TOOLS.has(tool.name)) return "blocked";
+	if (tool.name === "bash") return "limited";
+	return SAFE_BUILTIN_PLAN_TOOLS.has(tool.name) ? "read-only" : "blocked";
+}
+
 export function canSelectToolInPlanMode(tool: ToolInfo) {
-	if (isBuiltinTool(tool)) return SAFE_BUILTIN_PLAN_TOOLS.has(tool.name);
-	return true;
+	return classifyPlanModeTool(tool) !== "blocked";
 }
 
 export function readCommand(input: unknown) {
@@ -60,8 +89,268 @@ export function readCommand(input: unknown) {
 }
 
 export function isSafeCommand(command: string) {
+	const segments = splitShellSegments(command);
+	return segments !== undefined && segments.length > 0 && segments.every(isSafeSegment);
+}
+
+function splitShellSegments(command: string): string[] | undefined {
 	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));
+	if (!trimmed || /[\n\r`]/.test(trimmed)) return undefined;
+
+	const segments: string[] = [];
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	let start = 0;
+	for (let index = 0; index < trimmed.length; index += 1) {
+		const character = trimmed[index];
+		if (escaped) {
+			escaped = false;
+			continue;
+		}
+		if (character === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			continue;
+		}
+		if (character === "'" || character === '"') {
+			quote = character;
+			continue;
+		}
+		if (character === ">" || character === "<" || character === "(" || character === ")") {
+			return undefined;
+		}
+		const next = trimmed[index + 1];
+		if (character === "&" && next !== "&") return undefined;
+		const separatorLength =
+			character === ";" || character === "|"
+				? next === character
+					? 2
+					: 1
+				: character === "&" && next === "&"
+					? 2
+					: 0;
+		if (separatorLength === 0) continue;
+		const segment = trimmed.slice(start, index).trim();
+		if (!segment) return undefined;
+		segments.push(segment);
+		index += separatorLength - 1;
+		start = index + 1;
+	}
+	if (quote || escaped) return undefined;
+	const finalSegment = trimmed.slice(start).trim();
+	if (!finalSegment) return undefined;
+	segments.push(finalSegment);
+	return segments;
+}
+
+function isSafeSegment(segment: string) {
+	if (/\$\(|\$\{|(^|\s)[A-Za-z_][A-Za-z0-9_]*=/.test(segment)) return false;
+	const tokens = shellWords(segment);
+	if (!tokens || tokens.length === 0) return false;
+	const command = tokens[0]?.toLowerCase();
+	if (!command || MUTATING_COMMANDS.has(command)) return false;
+	const args = tokens.slice(1);
+	if (!hasSafeArguments(command, args)) return false;
+	if (READ_ONLY_COMMANDS.has(command)) return true;
+	return isSafeStructuredCommand(command, args);
+}
+
+function shellWords(segment: string): string[] | undefined {
+	const words: string[] = [];
+	let word = "";
+	let quote: "'" | '"' | undefined;
+	let escaped = false;
+	for (const character of segment) {
+		if (escaped) {
+			word += character;
+			escaped = false;
+			continue;
+		}
+		if (character === "\\" && quote !== "'") {
+			escaped = true;
+			continue;
+		}
+		if (quote) {
+			if (character === quote) quote = undefined;
+			else word += character;
+			continue;
+		}
+		if (character === "'" || character === '"') quote = character;
+		else if (/\s/.test(character)) {
+			if (word) words.push(word);
+			word = "";
+		} else word += character;
+	}
+	if (quote || escaped) return undefined;
+	if (word) words.push(word);
+	return words;
+}
+
+function hasSafeArguments(command: string, args: string[]) {
+	const forbidden = new Set(["-i", "--in-place", "--fix", "--write", "-delete", "--delete"]);
+	if (args.some((argument) => forbidden.has(argument))) return false;
+	if (
+		command === "sed" &&
+		args.some(
+			(argument) =>
+				argument.startsWith("--in-place=") ||
+				(/^-[^-]+/.test(argument) && argument.slice(1).includes("i")),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "find" &&
+		args.some((argument) =>
+			["-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fprintf", "-fls"].includes(
+				argument,
+			),
+		)
+	) {
+		return false;
+	}
+	if (command === "date" && args.some((argument) => argument === "-s" || argument.startsWith("--set"))) {
+		return false;
+	}
+	if (
+		(command === "sort" || command === "tree") &&
+		args.some(
+			(argument) =>
+				argument === "-o" ||
+				(argument.startsWith("-o") && !argument.startsWith("--")) ||
+				argument.startsWith("--output"),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "sort" &&
+		args.some(
+			(argument) =>
+				argument === "-T" ||
+				(argument.startsWith("-T") && argument.length > 2) ||
+				argument.startsWith("--temporary-directory") ||
+				argument.startsWith("--compress-program"),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "diff" &&
+		args.some((argument) => argument === "--output" || argument.startsWith("--output="))
+	) {
+		return false;
+	}
+	if (command === "uniq" && args.filter((argument) => !argument.startsWith("-")).length > 1) {
+		return false;
+	}
+	if (
+		command === "fd" &&
+		args.some((argument) =>
+			["-x", "-X", "--exec", "--exec-batch"].some(
+				(flag) => argument === flag || argument.startsWith(`${flag}=`),
+			),
+		)
+	) {
+		return false;
+	}
+	if (
+		command === "rg" &&
+		args.some((argument) => argument === "--pre" || argument.startsWith("--pre="))
+	) {
+		return false;
+	}
+	if (
+		command === "bat" &&
+		args.some((argument) => argument === "--pager" || argument.startsWith("--pager="))
+	) {
+		return false;
+	}
+	return true;
+}
+
+function isSafeStructuredCommand(command: string, args: string[]) {
+	const subcommandIndex = args.findIndex((argument) => !argument.startsWith("-"));
+	const subcommand = args[subcommandIndex]?.toLowerCase();
+	const subcommandArgs = subcommandIndex >= 0 ? args.slice(subcommandIndex + 1) : [];
+	if (command === "sed") {
+		const script = args.find((argument) => !argument.startsWith("-"));
+		return (
+			Boolean(script) &&
+			(args.includes("-n") || args.some((argument) => /^-[^-]*n[^-]*$/.test(argument))) &&
+			/^\d+(,\d+)?p$/.test(script ?? "")
+		);
+	}
+	if (command === "git") {
+		if (!subcommand || !["status", "log", "diff", "show", "branch", "remote", "ls-files", "grep"].includes(subcommand)) return false;
+		if (subcommand === "branch" && subcommandArgs.some((argument) => !argument.startsWith("-"))) return false;
+		if (
+			subcommand === "branch" &&
+			subcommandArgs.some(
+				(argument) =>
+					[
+						"-d",
+						"-D",
+						"-m",
+						"-M",
+						"-c",
+						"-C",
+						"--delete",
+						"--move",
+						"--copy",
+						"--edit-description",
+						"--unset-upstream",
+					].includes(argument) || argument.startsWith("--set-upstream-to"),
+			)
+		)
+			return false;
+		if (subcommand === "remote") {
+			const action = subcommandArgs.find((argument) => !argument.startsWith("-"));
+			if (action && action !== "show" && action !== "get-url") return false;
+		}
+		if (
+			args.some(
+				(argument) =>
+					argument === "--output" ||
+					argument.startsWith("--output=") ||
+					argument === "--ext-diff" ||
+					argument === "--textconv" ||
+					argument === "--open-files-in-pager" ||
+					argument.startsWith("--open-files-in-pager=") ||
+					(subcommand === "grep" && (argument === "-O" || argument.startsWith("-O"))),
+			)
+		)
+			return false;
+		return true;
+	}
+	if (["node", "python", "python3", "tsc", "biome", "ruff", "ty"].includes(command)) {
+		if (args.includes("--version")) return true;
+		return (
+			command === "tsc" &&
+			args.includes("--noEmit") &&
+			!args.some(
+				(argument) =>
+					argument === "--incremental" ||
+					argument.startsWith("--incremental=") ||
+					argument === "--tsBuildInfoFile" ||
+					argument.startsWith("--tsBuildInfoFile=") ||
+					argument === "--generateTrace" ||
+					argument.startsWith("--generateTrace="),
+			)
+		);
+	}
+	if (command === "npm") {
+		if (subcommand === "audit" && subcommandArgs.includes("fix")) return false;
+		if (["list", "ls", "view", "info", "search", "outdated", "audit", "test"].includes(subcommand ?? "")) {
+			return true;
+		}
+		return subcommand === "run" && ["test", "check", "typecheck", "lint"].includes(args[1] ?? "");
+	}
+	if (["cargo", "go", "pytest", "vitest", "jest"].includes(command)) {
+		return ["test", "check"].includes(subcommand ?? "") || ["pytest", "vitest", "jest"].includes(command);
+	}
+	return false;
 }