@gavin-hu/my-pi-agent 0.21.0 → 0.22.0

package/extensions/plan/git-bash.ts

@@ -202,6 +202,119 @@ function checkFlagAndPositional(rest: string[], spec: RestCheck, label: string):
 	return { ok: true };
 }
 
+/** `git config` flags that write the file, each of which the guard refuses by name. */
+const CONFIG_WRITE_FLAGS = new Set([
+	"--add",
+	"--edit",
+	"-e",
+	"--remove-section",
+	"--rename-section",
+	"--replace-all",
+	"--unset",
+	"--unset-all",
+]);
+
+/** `git config` flags whose value is the next token, or the part after `=`. */
+const CONFIG_VALUE_FLAGS = new Set([
+	"--get",
+	"--get-all",
+	"--get-regexp",
+	"--get-urlmatch",
+	"--get-color",
+	"--get-colorbool",
+	"--default",
+	"--file",
+	"-f",
+	"--type",
+	"--blob",
+]);
+
+/** `git config` flags that select or shape a read without taking a value. */
+const CONFIG_READ_FLAGS = new Set([
+	"--list",
+	"-l",
+	"--show-origin",
+	"--show-scope",
+	"--name-only",
+	"--null",
+	"-z",
+	"--local",
+	"--global",
+	"--system",
+	"--worktree",
+	"--includes",
+	"--no-includes",
+	"--bool",
+	"--int",
+	"--bool-or-int",
+	"--path",
+]);
+
+/** `git config` flags that ask for a value rather than only shaping the output. */
+const CONFIG_GET_FLAGS = new Set([
+	"--get",
+	"--get-all",
+	"--get-regexp",
+	"--get-urlmatch",
+	"--get-color",
+	"--get-colorbool",
+]);
+
+/**
+ * `git config` reads only, by allowlist.
+ *
+ * Asking whether a read flag appeared *anywhere* let every write through beside one:
+ * `git config --show-scope --replace-all core.fsmonitor /tmp/hook.sh` wrote `.git/config`
+ * from inside plan mode, and the `git status` that followed ran the hook. Each flag is now
+ * one this guard knows, a write action is refused by name, positionals are at most one, and
+ * the only forms left are the ones git reads with: `--get*`, `--list`, or one bare name.
+ */
+function checkConfig(rest: string[]): GitCommandVerdict {
+	const tokens = rest.map(unquote);
+	const positionals: string[] = [];
+	let reads = false;
+	for (let index = 0; index < tokens.length; index += 1) {
+		const token = tokens[index] ?? "";
+		if (!token.startsWith("-")) {
+			positionals.push(token);
+			continue;
+		}
+		const [flag = "", inline] = token.split("=", 2);
+		if (CONFIG_WRITE_FLAGS.has(flag)) {
+			return {
+				ok: false,
+				reason: `"git config ${flag}" writes .git/config; "git config" may only read while planning.`,
+			};
+		}
+		if (!CONFIG_READ_FLAGS.has(flag) && !CONFIG_VALUE_FLAGS.has(flag)) {
+			return { ok: false, reason: `"git config" flag "${token}" is not a read-only option.` };
+		}
+		if (!CONFIG_VALUE_FLAGS.has(flag)) {
+			if (flag === "--list" || flag === "-l") reads = true;
+			continue;
+		}
+		if (CONFIG_GET_FLAGS.has(flag)) reads = true;
+		if (inline !== undefined) continue;
+		const value = tokens[index + 1];
+		// A flag is not a value: reading `--replace-all` as `--get`'s key would refuse nothing
+		// and leave git to act on it, so the value is refused rather than guessed.
+		if (value === undefined || value.startsWith("-")) {
+			return { ok: false, reason: `"git config ${flag}" needs a value, and plan mode does not guess one.` };
+		}
+		index += 1;
+	}
+	if (positionals.length > 1) {
+		return { ok: false, reason: '"git config <name> <value>" writes .git/config; plan mode reads config only.' };
+	}
+	if (!reads && positionals.length !== 1) {
+		return {
+			ok: false,
+			reason: '"git config" may only read; use "git config <name>", --get, --get-all, --get-regexp, or --list.',
+		};
+	}
+	return { ok: true };
+}
+
 /** Subcommand-specific read-only rules; the rest only pass the option denylist. */
 function checkRest(subcommand: string, rest: string[]): GitCommandVerdict {
 	switch (subcommand) {
@@ -219,22 +332,8 @@ function checkRest(subcommand: string, rest: string[]): GitCommandVerdict {
 				reason: `"git remote ${first}" can change a remote; use "git remote -v" or "git remote show".`,
 			};
 		}
-		case "config": {
-			const hasReadFlag = rest.some((raw) => {
-				const token = unquote(raw);
-				return (
-					token.startsWith("--get") ||
-					token === "--list" ||
-					token === "-l" ||
-					token === "--show-origin" ||
-					token === "--show-scope"
-				);
-			});
-			if (!hasReadFlag) {
-				return { ok: false, reason: '"git config" may only read; add --get, --get-all, --get-regexp, or --list.' };
-			}
-			return { ok: true };
-		}
+		case "config":
+			return checkConfig(rest);
 		case "stash": {
 			const [first] = rest.map(unquote);
 			if (first === "list" || first === "show") return { ok: true };

package/extensions/plan/index.ts

@@ -5,11 +5,12 @@
  * active set or blocked: write and edit are hidden, bash is limited to a single
  * read-only git command, powershell is blocked, and everything else that mutates
  * (worktree, MCP tools) is blocked. `subagent` stays active but is forced
- * read-only. The one permitted write is `write_plan`,
- * which saves the plan in the agent directory. The model investigates, saves the
- * plan, and calls `exit_plan_mode` to read the file back and ask for approval.
+ * read-only. The one permitted write is the `plan` tool's `write` action, which
+ * saves the plan in the agent directory. The model investigates, saves the plan,
+ * and calls `plan` action `exit` to read the file back and ask for approval.
  *
- * Toggle with `/plan`, `Ctrl+Alt+P`, or start with `--plan`. The state is
+ * Toggle with `/plan` (or Shift+Tab, which bytefly's editor binds), or start with
+ * `--plan`. The state is
  * persisted as a custom session entry, so it follows the active branch.
  *
  * Load with:  pi --extension ./extensions/plan
@@ -17,30 +18,27 @@
 
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
 import { fileURLToPath } from "node:url";
-import { hasPathInput } from "./path-guard.ts";
 import { isExtensionEnabled } from "../../lib/env.ts";
-import { requestMount } from "../../lib/http/index.ts";
+import { requestMount } from "../../lib/http/mount.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { lastGoal, isPursuedGoal, type PublishedGoal } from "../../lib/goal-state.ts";
-import { READ_ONLY_SUMMARY, PLAN_ENTER_REQUEST, type PlanEnterRequest } from "../../lib/plan-entry.ts";
-import { isBoardRead } from "../../lib/policy.ts";
 import {
-	ASK_USER_QUESTION_TOOL,
-	BOARD_READ_ACTION,
-	BOARD_TOOL,
-	SUBAGENT_READ_ONLY_PARAM,
-	SUBAGENT_TOOL,
-} from "../../lib/tool-names.ts";
+	READ_ONLY_SUMMARY,
+	PLAN_ENTER_REQUEST,
+	PLAN_TOGGLE_REQUEST,
+	type PlanModeRequest,
+} from "../../lib/plan-entry.ts";
+import { isBoardRead } from "../../lib/policy.ts";
+import { boardWriteRefusal } from "../../lib/board/actions.ts";
+import { ASK_USER_QUESTION_TOOL, BOARD_TOOL, SUBAGENT_READ_ONLY_PARAM, SUBAGENT_TOOL } from "../../lib/tool-names.ts";
 import { clip } from "../../lib/tui/columns.ts";
 import { STATUS_KEYS } from "../../lib/tui/glyphs.ts";
 import { planModeNotice, registerCommands } from "./commands.ts";
-import { checkReadOnlyGit } from "./git-bash.ts";
 import { createPlanPolicy, BASH_BLOCKED_GUIDANCE, BLOCKED_GUIDANCE, PLAN_SAFE_TOOLS } from "./policy.ts";
 import { createPlanRuntime } from "./runtime.ts";
 import { registerTools } from "./tools.ts";
-import { createPlanWebReview } from "./web.ts";
+import { createLazyPlanWebReview } from "./web-lazy.ts";
 
 /** Marker embedded in the injected prompt and used to filter stale context. */
 export const PLAN_MODE_MARKER = "[PLAN MODE ACTIVE]";
@@ -63,7 +61,7 @@ export function planModeContext(goal?: PublishedGoal | null): string {
 		"",
 		`- Do not modify anything except the plan file: while planning, ${READ_ONLY_SUMMARY}.`,
 		"- bash is git-only: read-only git commands chain with && or ; — no pipes, redirection, or substitution, and no powershell. The cwd is already the project root, so skip cd, and read files with read, grep, find, and ls.",
-		"- Investigate and design a concrete plan, then save it with write_plan and call exit_plan_mode with the returned plan_path for approval.",
+		"- Investigate and design a concrete plan, then save it with `plan` action `write` and call `plan` action `exit` with the returned plan_path for approval.",
 		"- Delegate broad exploration with subagent.",
 		`- To choose between approaches, ask with ${ASK_USER_QUESTION_TOOL} before finalizing.`,
 	];
@@ -94,7 +92,7 @@ export default function planMode(pi: ExtensionAPI): void {
 	const runtime = createPlanRuntime(pi, policy, { entryPath: extensionEntryPath() });
 	/** The session this review serves as; its prefix lands on that session's one server. */
 	let sessionId = "";
-	const web = createPlanWebReview(runtime.plans, {
+	const web = createLazyPlanWebReview(runtime.plans, {
 		mount: (spec) => requestMount(pi, spec),
 		session: () => sessionId,
 	});
@@ -108,33 +106,36 @@ export default function planMode(pi: ExtensionAPI): void {
 		default: false,
 	});
 
-	pi.registerShortcut(Key.ctrlAlt("p"), {
-		description: "Toggle plan mode",
-		handler: (ctx) => {
-			runtime.toggle(ctx);
-			ctx.ui.notify(planModeNotice(runtime.isEnabled()), "info");
-		},
-	});
-
-	// Another extension that offers plan mode (the goal workflow) asks on this
-	// channel instead of calling a tool it cannot reach from a command context. It
-	// owns the user's answer; enabling here must therefore not ask again.
+	// Another extension asks on these channels instead of calling a tool it cannot
+	// reach from a command or editor context: `goal` offers plan mode as a phase, and
+	// bytefly's editor binds Shift+Tab to the toggle. The asker owns the user's answer,
+	// so enabling here must not ask again, and a toggle answers with the state it left.
 	const unsubscribes: Array<() => void> = [];
-	const listenForEntryRequests = (): void => {
+	const listenForRequests = (): void => {
 		for (const unsubscribe of unsubscribes) unsubscribe();
 		unsubscribes.length = 0;
-		unsubscribes.push(
-			pi.events.on(PLAN_ENTER_REQUEST, (data) => {
-				const request = data as Partial<PlanEnterRequest> | undefined;
-				if (!request?.ctx || typeof request.respond !== "function") return;
-				if (!runtime.isEnabled()) runtime.enable(request.ctx);
-				request.respond(true);
-			}),
-		);
+		const listen = (channel: string, handle: (request: PlanModeRequest) => void): void => {
+			unsubscribes.push(
+				pi.events.on(channel, (data) => {
+					const request = data as Partial<PlanModeRequest> | undefined;
+					if (!request?.ctx || typeof request.respond !== "function") return;
+					handle(request as PlanModeRequest);
+				}),
+			);
+		};
+		listen(PLAN_ENTER_REQUEST, (request) => {
+			if (!runtime.isEnabled()) runtime.enable(request.ctx);
+			request.respond(true);
+		});
+		listen(PLAN_TOGGLE_REQUEST, (request) => {
+			runtime.toggle(request.ctx);
+			request.ctx.ui.notify(planModeNotice(runtime.isEnabled()), "info");
+			request.respond(runtime.isEnabled());
+		});
 	};
 
 	pi.on("session_start", (_event, ctx) => {
-		listenForEntryRequests();
+		listenForRequests();
 		runtime.restore(ctx);
 	});
 	pi.on("session_tree", (_event, ctx) => runtime.restore(ctx));
@@ -161,12 +162,12 @@ export default function planMode(pi: ExtensionAPI): void {
 	 * proceed. Two layers: the policy (readers, `readOnlyHint`, deny list), then
 	 * the path backstop (a hint on a path-carrying tool is only a claim).
 	 */
-	const blockedReason = (toolName: string, input: unknown): string | undefined => {
-		// Plan-owned tools are the sanctioned exception: `write_plan` saves the
-		// artifact, `exit_plan_mode` presents it, `cancel_plan_mode` restores access,
-		// and `enter_plan_mode` answers "already" to a call that was in flight when
-		// plan mode came on. The source-path check keeps a same-named tool from
-		// another extension from borrowing the exemption.
+	const blockedReason = async (toolName: string, input: unknown): Promise<string | undefined> => {
+		// Plan's own tool is the sanctioned exception: it is the mode's vocabulary —
+		// `write` saves the artifact, `exit` presents it, `cancel` restores access, and
+		// `enter` answers "already" — so its actions decide for themselves whether they
+		// apply, and each refuses outside its mode. The source-path check keeps a
+		// same-named tool from another extension from borrowing the exemption.
 		if (runtime.isOwnTool(toolName)) return undefined;
 		// `subagent` stays active, but only as read-only delegation. The flag is
 		// forced in place (the child enforces it through `--tools`), so the model
@@ -183,12 +184,10 @@ export default function planMode(pi: ExtensionAPI): void {
 		}
 		// `board` stays active so planning can read the board it is about to add cards
 		// to. The action is the truth here, not the annotation: the same tool writes, so
-		// `readOnlyHint` cannot say it, and every verb but the read is refused by name.
+		// `readOnlyHint` cannot say it, and every verb but the reads are refused by name.
 		if (toolName === BOARD_TOOL) {
 			if (isBoardRead(input)) return undefined;
-			const action = (input as { action?: unknown } | undefined)?.action;
-			const verb = typeof action === "string" && action.trim() !== "" ? action.trim() : "board";
-			return `Plan mode: \`${verb}\` changes the board — only \`${BOARD_READ_ACTION}\` reads it. ${BLOCKED_GUIDANCE}`;
+			return boardWriteRefusal((input as { action?: unknown } | undefined)?.action, BLOCKED_GUIDANCE);
 		}
 		const blocked = policy.check(toolName);
 		if (blocked) return `Plan mode: ${blocked.reason}`;
@@ -201,9 +200,11 @@ export default function planMode(pi: ExtensionAPI): void {
 			if (typeof command !== "string" || command.trim() === "") {
 				return `Plan mode: an empty bash command is not allowed. ${BASH_BLOCKED_GUIDANCE}`;
 			}
+			const { checkReadOnlyGit } = await import("./git-bash.ts");
 			const verdict = checkReadOnlyGit(command);
 			if (!verdict.ok) return `Plan mode: ${verdict.reason} ${BASH_BLOCKED_GUIDANCE}`;
 		}
+		const { hasPathInput } = await import("./path-guard.ts");
 		if (hasPathInput(input) && !PLAN_SAFE_TOOLS.includes(toolName)) {
 			return `Plan mode: "${toolName}" takes a file path and is not a known reader. ${BLOCKED_GUIDANCE}`;
 		}
@@ -214,9 +215,9 @@ export default function planMode(pi: ExtensionAPI): void {
 	// above hides most of these; this is the second layer for tools already
 	// declared in an in-flight request, and the guard for tools we did not know
 	// about when the extension loaded (MCP servers, future extensions).
-	pi.on("tool_call", (event) => {
+	pi.on("tool_call", async (event) => {
 		if (!runtime.isEnabled()) return undefined;
-		const reason = blockedReason(event.toolName, event.input);
+		const reason = await blockedReason(event.toolName, event.input);
 		return reason ? { block: true, reason } : undefined;
 	});
 

package/extensions/plan/plan-index.ts

@@ -90,7 +90,7 @@ function footprintText(summaries: readonly PlanSummary[], nowMs: number): string
 export function formatPlanIndex(summaries: readonly PlanSummary[], dir: string, now: number = Date.now()): string {
 	const where = sanitizeLine(shortenPath(dir));
 	if (summaries.length === 0) {
-		return `No plans in ${where} yet; write_plan saves one there.`;
+		return `No plans in ${where} yet; \`plan\` action \`write\` saves one there.`;
 	}
 	const lines = summaries.map(
 		(summary) =>
@@ -241,7 +241,9 @@ export class PlanIndexComponent implements Component {
 
 		const body: string[] = [];
 		if (this.summaries.length === 0) {
-			body.push(...emptyState(theme, w, { label: "No plans yet. write_plan saves one in the agent directory." }));
+			body.push(
+				...emptyState(theme, w, { label: "No plans yet. `plan` action `write` saves one in the agent directory." }),
+			);
 		} else {
 			const { start, end } = this.cursor.window(this.summaries.length);
 			for (let index = start; index < end; index++) {

package/extensions/plan/plans.ts

@@ -33,13 +33,12 @@ import {
 	unlinkSync,
 	writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { join } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolveEffectiveCwd } from "../../lib/env.ts";
 import { keepRevision, writeAtomic } from "./plan-files.ts";
 import { sanitizeLine, shortenPath } from "../../lib/format.ts";
-import { isInside, isInsideReal } from "../../lib/path.ts";
+import { isContainedPlan, isPlanFileName, plansDirFor, resolvePlanArg } from "../../lib/plans/paths.ts";
 import { repoKeyFor } from "../../lib/repo-key.ts";
 import { carryFeedback, formatFeedback, normalizeAuthor, type PlanAnnotation } from "./feedback.ts";
 import { extractPlanSteps, matchesStepText, setStepStatuses, type StepUpdate } from "./steps.ts";
@@ -48,14 +47,6 @@ import { extractPlanSteps, matchesStepText, setStepStatuses, type StepUpdate } f
 export const MAX_PLAN_BYTES = 256 * 1024;
 /** Longest slug derived from a plan title. */
 const MAX_SLUG_LENGTH = 60;
-/** The agent-directory entry plans are filed under. */
-const PLANS_DIRNAME = "plans";
-
-/** The plan store: `<agent-dir>/plans`, or `<agent-dir>/plans/<key>` inside a repository. */
-function plansDir(agentDir: string, key?: string): string {
-	return key === undefined ? join(agentDir, PLANS_DIRNAME) : join(agentDir, PLANS_DIRNAME, key);
-}
-
 /** A plan read from disk. */
 export interface StoredPlan {
 	/** Absolute path. */
@@ -160,46 +151,6 @@ export function stamp(date: Date): string {
 	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}`;
 }
 
-/** A plan file name: markdown and not a dotfile, so the self-ignore file is never a target. */
-function isPlanFileName(path: string): boolean {
-	const name = basename(path);
-	return name.toLowerCase().endsWith(".md") && !name.startsWith(".");
-}
-
-/**
- * Whether `path` may be read, written, or deleted as a plan. Beyond lexical
- * containment (shared with the other path guards through `lib/path.ts`), this
- * rejects dotfiles (including the directory's own `.gitignore`) and resolves
- * symlinks, so a link placed inside the plans directory cannot redirect a read
- * or write outside it.
- */
-function isContainedPlan(dir: string, path: string): boolean {
-	if (!isInside(dir, path) || !isPlanFileName(path)) return false;
-	try {
-		// A symlink itself must never be the target; a missing file is a new plan.
-		if (lstatSync(path).isSymbolicLink()) return false;
-	} catch {
-		// Missing (ENOENT) is expected; any other error falls through to the
-		// real-path check, which rejects the path if it cannot be resolved.
-	}
-	return isInsideReal(dir, dirname(path));
-}
-
-/**
- * Resolve a `plan_path` argument against the store.
- *
- * A plan lives outside the project, so a path relative to the working directory
- * can no longer name one. Absolute paths and the `~/…` form the tools display are
- * accepted, and a bare name resolves inside the store — which is what a reader of
- * a tool result has in hand.
- */
-function resolvePlanArg(dir: string, planPath: string): string {
-	const text = planPath.trim();
-	if (text === "~") return homedir();
-	if (text.startsWith("~/") || text.startsWith(`~${sep}`)) return resolve(homedir(), text.slice(2));
-	return isAbsolute(text) ? resolve(text) : resolve(dir, text);
-}
-
 function uniquePath(dir: string, base: string): string {
 	const taken = (candidate: string): boolean => {
 		try {
@@ -300,7 +251,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 		const cached = dirCache.get(base);
 		if (cached) return cached;
 		const repo = await repoKeyFor(pi, base);
-		const dir = plansDir(getAgentDir(), repo.fromGit ? repo.key : undefined);
+		const dir = plansDirFor(getAgentDir(), repo);
 		dirCache.set(base, { dir, root: repo.fromGit ? repo.root : undefined });
 		if (repo.fromGit) {
 			// The keyed directory is the store; a store an older version left in the
@@ -387,7 +338,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 
 	const setSteps = async (cwd: string, planPath: string, updates: StepUpdate[]): Promise<StoredPlan> => {
 		const plan = await read(cwd, planPath);
-		if (!plan) throw new Error("No plan file there; pass a plan_path written by write_plan.");
+		if (!plan) throw new Error("No plan file there; pass a plan_path written by `plan` action `write`.");
 		const steps = extractPlanSteps(plan.content);
 		const total = steps.length;
 		const outOfRange = updates.find(
@@ -433,7 +384,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 		options: { author?: string } = {},
 	): Promise<StoredPlan> => {
 		const plan = await read(cwd, planPath);
-		if (!plan) throw new Error("No plan file there; pass a plan_path written by write_plan.");
+		if (!plan) throw new Error("No plan file there; pass a plan_path written by `plan` action `write`.");
 		const author = normalizeAuthor(options.author);
 		// An untagged entry is the writer's own; one tagged with a different name is
 		// another writer's comment, so it is dropped rather than re-signed.

package/extensions/plan/policy.ts

@@ -25,8 +25,6 @@ import {
 	WEB_SEARCH_TOOL,
 } from "../../lib/tool-names.ts";
 
-import { ENTER_TOOL } from "./runtime.ts";
-
 /**
  * Tools that stay available while planning: structured readers (documents
  * included), the trackers, the git-only `bash`, and the known web/question
@@ -53,23 +51,23 @@ export const PLAN_SAFE_TOOLS = [
  */
 export const PLAN_ALLOWED_TOOLS = [...PLAN_SAFE_TOOLS, SUBAGENT_TOOL, BOARD_TOOL];
 /**
- * Tools always blocked while planning, even when annotated read-only.
- * `enter_plan_mode` is denied so it stays hidden while planning; the guard exempts
- * plan's own registration so a call already in flight can still answer "already".
+ * Tools always blocked while planning, even when annotated read-only. The `plan`
+ * tool is not one of them: plan mode keeps it active in both modes, because its
+ * actions are the mode's own verbs and each one refuses outside its mode.
  */
-const ALWAYS_BLOCKED_TOOLS = ["write", "edit", ENTER_TOOL];
+const ALWAYS_BLOCKED_TOOLS = ["write", "edit"];
 
 /** Shown when a tool call is refused while planning. */
-export const BLOCKED_GUIDANCE = "Call exit_plan_mode and get approval before using it.";
+export const BLOCKED_GUIDANCE = "Call `plan` action `exit` and get approval before using it.";
 
 /** Appended to a refused `bash` call; names the readers and the exit hatch. */
 export const BASH_BLOCKED_GUIDANCE =
-	"Use the read, grep, find, and ls tools for files, or call exit_plan_mode and get approval before using other shell commands.";
+	"Use the read, grep, find, and ls tools for files, or call `plan` action `exit` and get approval before using other shell commands.";
 
 /**
  * Build plan mode's read-only policy: known readers and the plan/goal trackers
- * are allowed, write/edit/shell/`enter_plan_mode` are always blocked, and every
- * other tool must carry the MCP `readOnlyHint` to pass.
+ * are allowed, write/edit and the shells are always blocked, and every other tool
+ * must carry the MCP `readOnlyHint` to pass.
  */
 export function createPlanPolicy(pi: ExtensionAPI): ReadOnlyPolicy {
 	return createReadOnlyPolicy({

package/extensions/plan/review-lazy.ts

@@ -0,0 +1,85 @@
+/**
+ * The plan review gate, loaded when a review actually asks a human.
+ *
+ * `review.ts` owns the loop, the TUI screen (`tui.ts`), the compact remote prompt,
+ * and the baseline rule — about 1,000 lines that registration never needs:
+ * `/plan review` and the `plan` tool's `exit` action are the only two doors in. Both import this
+ * module instead, so the loop loads once, on the first review of the session.
+ *
+ * The types stay here rather than in `review.ts` because a type import is erased:
+ * the `plan` tool declares its `exit` details from them at registration time.
+ */
+
+import type { ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import type { SectionDigest } from "./plan-text.ts";
+import type { PlanStore, StoredPlan } from "./plans.ts";
+import type { PlanAnnotation } from "./feedback.ts";
+import type { PlanReviewResult, PlanReviewSession, PlanWebReview } from "./web.ts";
+
+/** A choice from the review screen, with the refinement the screen carried, if any. */
+export interface PlanReviewChoice {
+	action: "approve" | "refine" | "keep" | "cancel";
+	refinement?: string;
+}
+
+/** What a review decided, and the plan state it decided on. */
+export type ReviewDecision =
+	| { action: "approve"; plan: StoredPlan; comments: PlanAnnotation[] }
+	| {
+			action: "refine";
+			plan: StoredPlan;
+			/** The refinement request: the saved comments, or what the user typed. */
+			refinement: string;
+			comments: PlanAnnotation[];
+			/** True when the request came from the browser, which is reported differently. */
+			fromBrowser: boolean;
+	  }
+	| { action: "keep"; plan: StoredPlan }
+	/** Leave plan mode without approving; the plan file stays for a later review. */
+	| { action: "cancel"; plan: StoredPlan };
+
+/** What the previous review showed, so this one can mark what changed. */
+export interface ReviewBaselines {
+	/** The sections the last review of `path` showed, when this branch has one. */
+	reviewed(path: string): SectionDigest[] | undefined;
+	/** Remember what a review just showed, as a session entry on this branch. */
+	markReviewed(path: string, content: string): void;
+}
+
+/** Everything one review needs: whom to ask, where to ask, and what to compare against. */
+export interface ReviewPlanOptions {
+	ctx: ExtensionToolContext;
+	web: PlanWebReview;
+	/** Re-read the plan after a browser review that may have changed it. */
+	plans: PlanStore;
+	baselines: ReviewBaselines;
+	plan: StoredPlan;
+	/** Aborting the turn closes the browser server. */
+	signal?: AbortSignal;
+}
+
+/** The review module, as the loader returns it. */
+export type ReviewModule = typeof import("./review.ts");
+
+/** How a review reaches its implementation; production uses the dynamic import. */
+export type ReviewLoader = () => Promise<ReviewModule>;
+
+/** Ask the human about `plan` and return one decision, loading the gate on first use. */
+export async function reviewPlan(options: ReviewPlanOptions, load?: ReviewLoader): Promise<ReviewDecision> {
+	const review = await (load ?? (() => import("./review.ts")))();
+	return review.reviewPlan(options);
+}
+
+/** The browser-only review `/plan review` opens, loaded on first use. */
+export async function runBrowserReview(
+	web: PlanWebReview,
+	cwd: string,
+	plan: StoredPlan,
+	options: Parameters<ReviewModule["runBrowserReview"]>[3],
+	load?: ReviewLoader,
+): Promise<PlanReviewResult | undefined> {
+	const review = await (load ?? (() => import("./review.ts")))();
+	return review.runBrowserReview(web, cwd, plan, options);
+}
+
+export type { PlanReviewSession };

package/extensions/plan/review.ts

@@ -4,7 +4,7 @@
  * A review has three presentations — the scrollable TUI screen, a dialog-only
  * editor, and a remote turn's compact editor prompt — and one optional browser
  * server. This module owns the loop that switches between
- * them, so `exit_plan_mode` and `/plan review` share one lifecycle and only map
+ * them, so the `plan` tool's `exit` action and `/plan review` share one lifecycle and only map
  * the returned {@link ReviewDecision} to their own result.
  *
  * It also owns the review baseline: a review marks the content the human was
@@ -118,7 +118,7 @@ async function askPlanReview(
 
 /** How a browser review may decide, and what to report when it opens. */
 export interface BrowserReviewOptions {
-	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	/** Whether the browser may approve the plan (only the `plan` tool's `exit` flow). */
 	canApprove: boolean;
 	/** The section digests the previous review showed, for the changed markers. */
 	baseline?: SectionDigest[];