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

package/extensions/plan/commands.ts

@@ -2,7 +2,7 @@
  * Slash command for the plan-mode extension.
  *
  * `/plan` toggles plan mode, or enters it and sends an optional task;
- * `Ctrl+Alt+P` toggles too. Four subcommands are reserved: `/plan review [path]`
+ * Shift+Tab toggles too, through bytefly's editor. Four subcommands are reserved: `/plan review [path]`
  * opens a plan in the browser (and sends saved comments to the model as a
  * refinement), `/plan share [stop]` prints or revokes the link a teammate opens,
  * `/plan list` shows the plans directory, newest first with Enter opening a
@@ -15,11 +15,11 @@ import { READ_ONLY_SUMMARY } from "../../lib/plan-entry.ts";
 import { qrLines } from "../../lib/qr.ts";
 import { withRailsSuppressed } from "../../lib/rails.ts";
 import { feedbackSummary } from "./feedback.ts";
-import { PlanIndexComponent, formatPlanIndex } from "./plan-index.ts";
-import { runBrowserReview } from "./review.ts";
+import { runBrowserReview } from "./review-lazy.ts";
 import type { PlanRuntime } from "./runtime.ts";
 import type { PlanSummary } from "./plans.ts";
-import { createPlanWebReview, type PlanWebReview } from "./web.ts";
+import { createLazyPlanWebReview, NO_SERVER_DEPS } from "./web-lazy.ts";
+import type { PlanWebReview } from "./web.ts";
 
 const ENABLED_NOTICE = `Plan mode enabled — ${READ_ONLY_SUMMARY}.`;
 const DISABLED_NOTICE = "Plan mode disabled — full access restored.";
@@ -28,7 +28,7 @@ const SHARE_PREFIX = "share";
 const LIST_PREFIX = "list";
 const CANCEL_PREFIX = "cancel";
 
-/** Notice text for the current mode; shared by `/plan` and the `Ctrl+Alt+P` shortcut. */
+/** Notice text for the current mode; shared by `/plan` and the toggle request. */
 export function planModeNotice(enabled: boolean): string {
 	return enabled ? ENABLED_NOTICE : DISABLED_NOTICE;
 }
@@ -126,7 +126,8 @@ async function reviewInBrowser(
 	const file = path ? await runtime.plans.read(ctx.cwd, path) : await runtime.plans.latest(ctx.cwd);
 	if (!file) {
 		if (path) ctx.ui.notify(`Plan review: no plan file at ${path}`, "error");
-		else ctx.ui.notify("Plan review: no plan to review; write one with write_plan or pass a path.", "warning");
+		else
+			ctx.ui.notify("Plan review: no plan to review; write one with `plan` action `write` or pass a path.", "warning");
 		return;
 	}
 	// The server is loopback-only, so a remote turn cannot drive it.
@@ -161,7 +162,7 @@ async function reviewInBrowser(
 		return;
 	}
 	const message = runtime.isEnabled()
-		? `The user reviewed the plan ${result.plan.relativePath} in the browser and left feedback:\n${summary}\nStay in plan mode, revise the plan (write_plan, reusing plan_path), then call exit_plan_mode again.`
+		? `The user reviewed the plan ${result.plan.relativePath} in the browser and left feedback:\n${summary}\nStay in plan mode, revise the plan (\`plan\` action \`write\`, reusing plan_path), then call \`plan\` action \`exit\` again.`
 		: `The user reviewed the plan ${result.plan.relativePath} in the browser and left feedback:\n${summary}\nUpdate the plan file to address the feedback.`;
 	if (ctx.isIdle()) await pi.sendUserMessage(message);
 	else await pi.sendUserMessage(message, { deliverAs: "followUp" });
@@ -187,6 +188,7 @@ async function openPlanIndex(
 	const summaries = await summarise();
 
 	if (ctx.mode !== "tui") {
+		const { formatPlanIndex } = await import("./plan-index.ts");
 		ctx.ui.notify(formatPlanIndex(summaries, dir), "info");
 		return;
 	}
@@ -195,6 +197,7 @@ async function openPlanIndex(
 	let selected: (PlanSummary | undefined) | undefined;
 	// A dock list shares the editor slot with the goal and todo rails, so it takes
 	// the dock to itself for as long as it is open, like the other list screens.
+	const { PlanIndexComponent } = await import("./plan-index.ts");
 	await withRailsSuppressed(pi, () =>
 		ctx.ui.custom<void>((tui, theme, _keybindings, done) => {
 			const component = new PlanIndexComponent({
@@ -219,7 +222,7 @@ async function openPlanIndex(
 export function registerCommands(
 	pi: ExtensionAPI,
 	runtime: PlanRuntime,
-	web: PlanWebReview = createPlanWebReview(runtime.plans),
+	web: PlanWebReview = createLazyPlanWebReview(runtime.plans, NO_SERVER_DEPS),
 ): void {
 	pi.registerCommand("plan", {
 		description:
@@ -259,7 +262,7 @@ export function registerCommands(
 				return;
 			}
 
-			// No task: toggle, exactly like Ctrl+Alt+P.
+			// No task: toggle, exactly like Shift+Tab.
 			if (!prompt) {
 				runtime.toggle(ctx);
 				ctx.ui.notify(planModeNotice(runtime.isEnabled()), "info");

package/extensions/plan/feedback.ts

@@ -43,6 +43,13 @@ export interface PlanAnnotation {
 	 * guess, and the page says so instead of presenting a guess as her own anchor.
 	 */
 	moved?: true;
+	/**
+	 * Set when the note is settled: its writer, or the owner, decided it needs no action, or
+	 * the revision answered it. The comment stays in the file — it is the record of the
+	 * question — and a review sends it flagged, so the model reads what is closed without
+	 * treating it as new.
+	 */
+	resolved?: true;
 }
 
 /** Most annotations one save may carry. */
@@ -59,10 +66,10 @@ export type AuthorClaim = { name: string } | { status: number; message: string }
 
 /**
  * A stored feedback line, capturing whether a refinement moved it, its author, and its
- * comment. The flag is inside the marker tag rather than the comment, so the text a
+ * comment. The flags are inside the marker tag rather than the comment, so the text a
  * reviewer wrote stays exactly what she typed.
  */
-const MARKER_LINE = /^\s*>\s*\[!REVIEW(\s+moved)?\]\s?(.*)$/;
+const MARKER_LINE = /^\s*>\s*\[!REVIEW((?:\s+(?:moved|resolved))*)\]\s?(.*)$/;
 /** The author prefix inside a marker body (`@alice: note`). */
 const AUTHOR_PREFIX = /^@([^:]{1,40}):\s?(.*)$/;
 
@@ -133,6 +140,8 @@ interface StoredMarker {
 	author: string;
 	/** Whether a refinement carried this comment off the text it was written on. */
 	moved: boolean;
+	/** Whether the note is settled: it stays in the file, and is no longer an open question. */
+	resolved: boolean;
 }
 
 /** The plan body without markers, plus the markers that were removed from it. */
@@ -151,17 +160,28 @@ function scanMarkers(plan: string): { clean: string; markers: StoredMarker[] } {
 		const authored = AUTHOR_PREFIX.exec(body);
 		const author = authored ? normalizeAuthor(authored[1]) : "";
 		const comment = (authored ? authored[2] : body).trim();
-		if (comment) markers.push({ at: clean.length - 1, comment, author, moved: match[1] !== undefined });
+		// The tag carries a set of flags, not one keyword: a note can be carried off its text
+		// and settled in the same write, and an older build reading it still finds the comment.
+		const flags = new Set((match[1] ?? "").trim().split(/\s+/).filter(Boolean));
+		if (comment) {
+			markers.push({
+				at: clean.length - 1,
+				comment,
+				author,
+				moved: flags.has("moved"),
+				resolved: flags.has("resolved"),
+			});
+		}
 	});
 	return { clean: clean.join("\n"), markers };
 }
 
 /** One marker line in its stored form. */
-function markerLine(author: string, comment: string, moved = false): string {
+function markerLine(author: string, comment: string, moved = false, resolved = false): string {
 	const body = sanitizeLine(comment);
-	// The flag rides inside the tag, where it cannot be confused with the comment: after
-	// the closing bracket, a comment that begins "moved …" would read as the flag.
-	const tag = moved ? "[!REVIEW moved]" : REVIEW_MARKER;
+	// The flags ride inside the tag, in a fixed order, where they cannot be confused with the
+	// comment: after the closing bracket, a comment that begins "moved …" would read as one.
+	const tag = moved || resolved ? `[!REVIEW${moved ? " moved" : ""}${resolved ? " resolved" : ""}]` : REVIEW_MARKER;
 	return author ? `> ${tag} @${author}: ${body}` : `> ${tag} ${body}`;
 }
 
@@ -236,6 +256,7 @@ export function readFeedback(plan: string): FeedbackRead {
 		};
 		if (marker.author) annotation.author = marker.author;
 		if (marker.moved) annotation.moved = true;
+		if (marker.resolved) annotation.resolved = true;
 		return annotation;
 	});
 	return { body: clean, blocks, annotations };
@@ -249,15 +270,21 @@ export function parseFeedback(plan: string): PlanAnnotation[] {
 /** Sanitized, non-empty comments with the anchor they land on. */
 function storableComments(
 	annotations: readonly PlanAnnotation[],
-): Array<{ anchor: number; comment: string; moved: boolean }> {
-	const items: Array<{ anchor: number; comment: string; moved: boolean }> = [];
+): Array<{ anchor: number; comment: string; moved: boolean; resolved: boolean }> {
+	const items: Array<{ anchor: number; comment: string; moved: boolean; resolved: boolean }> = [];
 	for (const annotation of annotations) {
 		const comment = sanitizeLine(annotation.comment);
 		if (comment.length === 0 || comment.length > MAX_COMMENT_LENGTH) continue;
 		// Editing a moved note's text does not put it back on its old block, so the fact
 		// that a refinement placed it where it sits survives the save: the page posts back
-		// the annotation it was handed, flag included, and this keeps it.
-		items.push({ anchor: annotation.anchor, comment, moved: annotation.moved === true });
+		// the annotation it was handed, flags included, and this keeps them. Settling is the
+		// writer's own decision of the same kind.
+		items.push({
+			anchor: annotation.anchor,
+			comment,
+			moved: annotation.moved === true,
+			resolved: annotation.resolved === true,
+		});
 	}
 	return items;
 }
@@ -272,13 +299,16 @@ export function formatFeedback(plan: string, annotations: PlanAnnotation[], opti
 	const { clean, markers } = scanMarkers(plan);
 	const kept = markers
 		.filter((marker) => marker.author !== author)
-		.map((marker) => ({ at: marker.at, line: markerLine(marker.author, marker.comment, marker.moved) }));
+		.map((marker) => ({
+			at: marker.at,
+			line: markerLine(marker.author, marker.comment, marker.moved, marker.resolved),
+		}));
 	const blocks = planBlocks(clean);
 	const added = storableComments(annotations).map((item) => ({
 		// A marker beside a block, never after a blank line: an anchor that names
 		// blank space is written where the page can read it back as a thread.
 		at: contentBlockAt(blocks, item.anchor)?.end ?? -1,
-		line: markerLine(author, item.comment, item.moved),
+		line: markerLine(author, item.comment, item.moved, item.resolved),
 	}));
 	return compose(clean, [...kept, ...added]);
 }
@@ -452,7 +482,9 @@ export function carryFeedback(previous: string, next: string): string {
 		// The flag means "this note is no longer on the text it was written about", so it
 		// is decided by the carry in hand: a block whose text survived proves the anchor,
 		// and anything after that is a guess the page has to admit to.
-		const keep = (moved: boolean): string => markerLine(marker.author, marker.comment, moved);
+		// Settling is the note's own history, not the carry's decision: a moved note that was
+		// resolved stays settled, and one whose text survived stays as it was.
+		const keep = (moved: boolean): string => markerLine(marker.author, marker.comment, moved, marker.resolved);
 		if (block === undefined) return { at: tail, line: keep(true) };
 		if (block.kind !== "blank") {
 			const match = queues.get(blockKey(block))?.shift();
@@ -503,13 +535,17 @@ export function feedbackSummary(annotations: PlanAnnotation[]): string {
 			// the plan owner chose, so it is normalized like every other author.
 			author: normalizeAuthor(annotation.author),
 			comment: sanitizeLine(annotation.comment),
+			resolved: annotation.resolved === true,
 		}))
 		.filter((item) => item.comment.length > 0);
 	return items
 		.map((item, index) => {
 			const who = item.author ? `@${item.author}: ` : "";
 			const where = item.quote ? `On "${item.quote}": ` : "";
-			return `${index + 1}. ${who}${where}${item.comment}`;
+			// A settled note is still sent — it is the record of the question — but saying so
+			// is what stops the model from answering it a second time.
+			const settled = item.resolved ? " (resolved)" : "";
+			return `${index + 1}. ${who}${where}${item.comment}${settled}`;
 		})
 		.join("\n");
 }
@@ -531,12 +567,22 @@ export function coerceAnnotations(value: unknown): PlanAnnotation[] | undefined
 		if (typeof record.comment !== "string") return undefined;
 		if (record.quote !== undefined && typeof record.quote !== "string") return undefined;
 		if (record.author !== undefined && typeof record.author !== "string") return undefined;
+		if (record.resolved !== undefined && typeof record.resolved !== "boolean") return undefined;
 		const comment = sanitizeLine(record.comment);
 		if (comment.length > MAX_COMMENT_LENGTH) return undefined;
 		if (comment.length === 0) continue;
 		const quote = typeof record.quote === "string" ? sanitizeLine(record.quote).slice(0, MAX_QUOTE_LENGTH) : undefined;
 		const author = normalizeAuthor(record.author);
-		annotations.push({ anchor, comment, ...(quote ? { quote } : {}), ...(author ? { author } : {}) });
+		// A note a refinement carried onto another block keeps saying so when the page posts
+		// it back, and a settled note keeps saying that too: only this body knows either.
+		annotations.push({
+			anchor,
+			comment,
+			...(quote ? { quote } : {}),
+			...(author ? { author } : {}),
+			...(record.moved === true ? { moved: true } : {}),
+			...(record.resolved === true ? { resolved: true } : {}),
+		});
 	}
 	return annotations;
 }

package/extensions/plan/format.ts

@@ -5,10 +5,16 @@
  * the cap diagnosis, the preview, and the merge summary in one place.
  */
 
-import { SET_PLAN_STEPS_TOOL } from "./runtime.ts";
 import { MAX_STEP_LENGTH, MAX_STEPS, type PlanStep, type StepUpdate } from "./steps.ts";
 import type { TodoMerge } from "./todos.ts";
 
+/**
+ * How every message names the tick-off call. One spelling, because the tool is now
+ * one verb among five and a message that still spelled the old name would teach the
+ * model a tool that no longer exists.
+ */
+export const TICK_CALL = "`plan` action `steps`";
+
 /** Lines of plan shown in an unexpanded result. */
 const PREVIEW_LINES = 8;
 
@@ -80,7 +86,7 @@ export function mergeSummary(merged: TodoMerge, steps: PlanStep[]): string {
 		merged.deferred > 0 ? `${merged.deferred} deferred, list full` : "",
 	].filter(Boolean);
 	const suffix = notes.length > 0 ? ` (${notes.join(", ")})` : "";
-	const tick = `Tick each one off in the file with ${SET_PLAN_STEPS_TOOL} as you finish it, passing the step's text as \`expected\`.`;
+	const tick = `Tick each one off in the file with ${TICK_CALL} as you finish it, passing the step's text as \`expected\`.`;
 	const touched =
 		merged.stale > 0
 			? ` ${merged.stale} older item${merged.stale === 1 ? "" : "s"} no longer match${merged.stale === 1 ? "es" : ""} this plan but ${merged.stale === 1 ? "was" : "were"} left alone: ${merged.stale === 1 ? "it was" : "they were"} started or finished, so check ${merged.stale === 1 ? "it" : "them"} yourself.`

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,29 +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/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]";
@@ -62,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.`,
 	];
@@ -91,7 +90,12 @@ export default function planMode(pi: ExtensionAPI): void {
 	if (!isExtensionEnabled("plan")) return;
 	const policy = createPlanPolicy(pi);
 	const runtime = createPlanRuntime(pi, policy, { entryPath: extensionEntryPath() });
-	const web = createPlanWebReview(runtime.plans);
+	/** The session this review serves as; its prefix lands on that session's one server. */
+	let sessionId = "";
+	const web = createLazyPlanWebReview(runtime.plans, {
+		mount: (spec) => requestMount(pi, spec),
+		session: () => sessionId,
+	});
 
 	registerTools(pi, runtime, web);
 	registerCommands(pi, runtime, web);
@@ -102,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));
@@ -155,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
@@ -177,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}`;
@@ -195,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}`;
 		}
@@ -208,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++) {