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

package/extensions/plan/plan-text.ts

@@ -17,6 +17,7 @@ import { createHash } from "node:crypto";
 import { stripControlChars } from "../../lib/format.ts";
 import { displayFeedback, stripFeedback } from "./feedback.ts";
 import { extractSections, sectionKeys, type PlanSection } from "./sections.ts";
+import { planBlocks } from "./blocks.ts";
 
 /** Spaces a tab expands to; the terminal's own tab stops are not width-modelled. */
 const TAB_WIDTH = 4;
@@ -27,6 +28,14 @@ export interface SectionDigest {
 	title: string;
 	/** SHA-256 of the section's normalized text, heading included. */
 	digest: string;
+	/**
+	 * Short digests of this section's content blocks, in order.
+	 *
+	 * Absent in a baseline a build before block marks wrote, which is why every reader
+	 * treats it as optional: a section with no block digests marks nothing, and the page
+	 * says it cannot compare at that depth rather than reading as "nothing changed".
+	 */
+	blocks?: string[];
 }
 
 /**
@@ -60,6 +69,17 @@ function digestOf(text: string): string {
 	return createHash("sha256").update(text.trim()).digest("hex");
 }
 
+/**
+ * A short, stable digest of one block's lines.
+ *
+ * Short because it is persisted once per content block in a session entry: eight hex
+ * characters tell two blocks apart for the length of one review, which is all a change
+ * mark needs, and keep a long plan's baseline small enough to sit in the branch.
+ */
+export function blockDigest(lines: readonly string[]): string {
+	return digestOf(lines.join("\n")).slice(0, 8);
+}
+
 /**
  * A short, stable id for one plan text. The review page keys this tab's unsaved
  * draft on it, so a draft is restored for the plan it was written against and
@@ -74,9 +94,103 @@ export function sectionDigests(content: string): SectionDigest[] {
 	return extractSections(reviewText(content)).map((section) => ({
 		title: section.title,
 		digest: digestOf(section.text),
+		// Blank blocks are separators, not content: a plan that gained a blank line has not
+		// changed, and a digest per separator would say it had.
+		blocks: planBlocks(section.text)
+			.filter((block) => block.kind !== "blank")
+			.map((block) => blockDigest(block.lines)),
 	}));
 }
 
+/** Where the blocks changed, in the document the page is about to render. */
+export interface BlockChangeMarks {
+	/** Absolute 0-based start lines of the blocks that are new or edited. */
+	starts: number[];
+	/** Content blocks each section no longer holds, keyed by the section's heading line. */
+	removed: Record<number, number>;
+	/**
+	 * Whether the baseline carried block digests at all.
+	 *
+	 * False for a baseline a build before block marks wrote: section marks still mean
+	 * something, block marks cannot, and the page says which instead of drawing nothing.
+	 */
+	compared: boolean;
+}
+
+/**
+ * Where the blocks changed since the baseline, as the rendered document numbers them.
+ *
+ * The pages marks what it draws, so every line here is a line of `current`: a section's
+ * blocks are numbered from its own heading, which is why the section's line is added
+ * back. Sections are paired the way {@link changedSections} pairs them — by occurrence,
+ * so a second `## Notes` is never compared with the first — and a section the baseline
+ * never held is all new: every block in it marks, because adding or renaming a heading is
+ * a refinement rather than a reason to refuse the comparison. Only a baseline section
+ * written before block digests is beyond comparing at that depth, and it alone clears
+ * `compared`.
+ */
+export function blockChangeMarks(baseline: readonly SectionDigest[] | undefined, current: string): BlockChangeMarks {
+	const sections = extractSections(reviewText(current));
+	if (baseline === undefined) return { starts: [], removed: {}, compared: false };
+	const before = new Map<string, SectionDigest>();
+	sectionKeys(baseline).forEach((key, at) => {
+		const section = baseline[at];
+		if (section !== undefined) before.set(key, section);
+	});
+	const starts: number[] = [];
+	const removed: Record<number, number> = {};
+	let compared = true;
+	sectionKeys(sections).forEach((key, at) => {
+		const section = sections[at];
+		if (section === undefined) return;
+		const prior = before.get(key);
+		if (prior !== undefined && prior.blocks === undefined) {
+			compared = false;
+			return;
+		}
+		const mine = planBlocks(section.text).filter((block) => block.kind !== "blank");
+		// An unheld section pairs with no blocks, so every block in it is new.
+		const priorBlocks = new Set(prior?.blocks ?? []);
+		for (const block of mine) {
+			if (!priorBlocks.has(blockDigest(block.lines))) starts.push(section.line + block.start);
+		}
+		const shrunk = Math.max(0, (prior?.blocks?.length ?? 0) - mine.length);
+		if (shrunk > 0) removed[section.line] = shrunk;
+	});
+	return { starts, removed, compared };
+}
+
+/** What one section's blocks look like against the baseline's. */
+export interface BlockMarks {
+	/** Indexes, among the section's content blocks, of the blocks that are new or edited. */
+	changed: number[];
+	/** How many content blocks the section no longer holds: the part it shrank by. */
+	removed: number;
+}
+
+/**
+ * Mark the blocks a section gained or edited since the baseline.
+ *
+ * Membership rather than position: a block is changed when its digest is not among the
+ * baseline's, so an inserted step marks itself and leaves every block after it alone —
+ * the index-by-index pairing a diff would use would mark the whole rest of the section.
+ * A block that left cannot be drawn in place, so the section reports how much shorter it
+ * has become instead — the shrinkage, not the set difference, so an edited block reads
+ * as one change rather than as one removal beside one addition.
+ *
+ * An absent or blockless baseline marks nothing: a build before block marks wrote no
+ * block digests, and claiming every block changed would be a worse lie than saying the
+ * comparison cannot be made at that depth.
+ */
+export function changedBlocks(prior: readonly string[] | undefined, current: readonly string[]): BlockMarks {
+	if (prior === undefined) return { changed: [], removed: 0 };
+	const before = new Set(prior);
+	return {
+		changed: current.flatMap((digest, index) => (before.has(digest) ? [] : [index])),
+		removed: Math.max(0, prior.length - current.length),
+	};
+}
+
 /** Whether two baselines describe the same content, section for section. */
 export function sameSections(a: readonly SectionDigest[], b: readonly SectionDigest[]): boolean {
 	if (a.length !== b.length) return false;

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[];

package/extensions/plan/runtime.ts

@@ -2,18 +2,18 @@
  * Session-scoped state and tool gating for plan mode.
  *
  * Enabling plan mode removes every tool the policy does not consider read-only
- * from the active set and activates the plan-mode control tools: `exit_plan_mode`
- * (present the plan for approval) and `write_plan` (save the plan artifact under
- * the plans directory). Disabling restores exactly what it hid. The enabled flag is
- * persisted as a custom session entry so `/resume` and `/tree` follow the
- * branch, and it is also mirrored into the footer status. The review baseline
- * travels the same way, as one digest per heading section, so the changed-section
- * markers survive a resume too.
+ * from the active set, and keeps the one `plan` tool active in both modes: its
+ * actions are what ask to enter, save the artifact under the plans directory,
+ * present it, tick it, and leave. Disabling restores exactly what it hid. The
+ * enabled flag is persisted as a custom session entry so `/resume` and `/tree`
+ * follow the branch, and it is also mirrored into the footer status. The review
+ * baseline travels the same way, as one digest per heading section, so the
+ * changed-section markers survive a resume too.
  *
- * `write_plan` is the one sanctioned write while planning. The read-only guard
- * in `index.ts` permits plan's own tools only when the registered tool is this
- * extension's (matched by source path), so a same-named tool from another
- * extension cannot borrow the exemption.
+ * The `plan` tool's `write` action is the one sanctioned write while planning. The
+ * read-only guard in `index.ts` permits that tool only when the registered one is
+ * this extension's (matched by source path), so a same-named tool from another
+ * extension cannot borrow the exemption, and each action refuses outside its mode.
  */
 
 import { basename, resolve } from "node:path";
@@ -23,23 +23,25 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { sanitizeLine } from "../../lib/format.ts";
 import { PLAN_MODE_ENTRY_TYPE } from "../../lib/plan-state.ts";
 import type { ReadOnlyPolicy } from "../../lib/policy.ts";
-import { PLAN_ENTER_TOOL } from "../../lib/tool-names.ts";
+import { PLAN_TOOL as PLAN_TOOL_NAME } from "../../lib/tool-names.ts";
 import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
-import { paint } from "../../lib/tui/tokens.ts";
 import { createPlanStore, type PlanStore } from "./plans.ts";
 import { sameSections, sectionDigests, type SectionDigest } from "./plan-text.ts";
 import type { PlanModeEntry, ReviewBaselineEntry, SeededStepsEntry } from "./types.ts";
 
-/** Tool the model calls to leave plan mode after approval. */
-export const EXIT_TOOL = "exit_plan_mode";
-/** Tool the model calls to leave plan mode without approving. */
-export const CANCEL_TOOL = "cancel_plan_mode";
-/** Tool the model calls to ask to enter plan mode. */
-export const ENTER_TOOL = PLAN_ENTER_TOOL;
-/** Tool the model calls to save the plan artifact. */
-export const WRITE_PLAN_TOOL = "write_plan";
-/** Tool the model calls to keep an approved plan's steps current. */
-export const SET_PLAN_STEPS_TOOL = "set_plan_steps";
+/** The one model-facing tool: every planning verb is one of its actions. */
+export const PLAN_TOOL = PLAN_TOOL_NAME;
+
+/**
+ * The verbs of the one `plan` tool, in the order the schema offers them.
+ *
+ * One action tool rather than five tools, so every verb shares a name and a
+ * registration; the order is the one the description walks them in.
+ */
+export const PLAN_ACTIONS = ["enter", "write", "exit", "steps", "cancel"] as const;
+
+/** One verb of the `plan` tool. */
+export type PlanAction = (typeof PLAN_ACTIONS)[number];
 /** Custom-entry type used for plan-mode state. */
 export const STATE_TYPE = PLAN_MODE_ENTRY_TYPE;
 /** Custom-entry type used for a plan's review baseline. */
@@ -50,16 +52,13 @@ export const SEEDED_TYPE = "plan-seeded";
 /** Longest plan-file basename shown in the footer chip. */
 const STATUS_NAME_LENGTH = 28;
 
-/** Tools plan mode activates itself. */
-const CONTROL_TOOLS = [EXIT_TOOL, CANCEL_TOOL, WRITE_PLAN_TOOL];
-
 /**
- * Tools the read-only guard exempts when this extension registered them.
- * `enter_plan_mode` is here only so a call already in flight when plan mode came on
- * is answered by the tool ("already in plan mode"); the policy still denies it, so
- * it stays hidden while planning.
+ * The one tool plan mode keeps in the active set in both modes. Every other tool
+ * follows the policy, which is about writing files and cannot answer for a tool
+ * whose actions are the mode's own verbs: hiding it while planning would hide the
+ * way to write the plan and the way out.
  */
-const OWNED_TOOLS = [...CONTROL_TOOLS, ENTER_TOOL];
+const MODE_TOOLS = [PLAN_TOOL];
 
 export interface PlanRuntime {
 	/** Whether plan mode is currently on. */
@@ -69,9 +68,9 @@ export interface PlanRuntime {
 	toggle(ctx: ExtensionContext): void;
 	/** Restore state from the branch and the `--plan` flag. */
 	restore(ctx: ExtensionContext): void;
-	/** Plan-file storage for `write_plan` and `exit_plan_mode`. */
+	/** Plan-file storage for the `write` and `exit` actions. */
 	plans: PlanStore;
-	/** Whether `toolName` is one of plan's own tools (not a same-named impostor) the read-only guard exempts. */
+	/** Whether `toolName` is the `plan` tool (not a same-named impostor) the read-only guard exempts. */
 	isOwnTool(toolName: string): boolean;
 	/** Path of the most recently written plan, for the footer chip. */
 	lastPlanPath(): string | undefined;
@@ -100,9 +99,19 @@ function readSections(value: unknown): SectionDigest[] | undefined {
 	if (!Array.isArray(value)) return undefined;
 	const sections: SectionDigest[] = [];
 	for (const raw of value) {
-		const section = raw as { title?: unknown; digest?: unknown } | null | undefined;
+		const section = raw as { title?: unknown; digest?: unknown; blocks?: unknown } | null | undefined;
 		if (typeof section?.title !== "string" || typeof section.digest !== "string") return undefined;
-		sections.push({ title: section.title, digest: section.digest });
+		// Branch data is untrusted, so the block digests are kept only when they are a list
+		// of strings: a baseline written before block marks simply has none, and one that
+		// holds something else is read at section depth rather than repaired.
+		const blocks = Array.isArray(section.blocks)
+			? section.blocks.filter((entry): entry is string => typeof entry === "string")
+			: undefined;
+		sections.push(
+			blocks === undefined
+				? { title: section.title, digest: section.digest }
+				: { title: section.title, digest: section.digest, blocks },
+		);
 	}
 	return sections;
 }
@@ -185,6 +194,9 @@ export function createPlanRuntime(
 	// Tools plan mode deactivated, so disabling restores exactly those and does
 	// not re-activate a tool another extension intentionally hid.
 	let removedForPlan: string[] = [];
+	// Mode tools this enable had to activate, so disabling puts the user's own
+	// active set back instead of widening it.
+	let addedForPlan: string[] = [];
 
 	const plans = createPlanStore(pi);
 
@@ -194,7 +206,7 @@ export function createPlanRuntime(
 	 * is rejected.
 	 */
 	const isOwnTool = (toolName: string): boolean => {
-		if (!OWNED_TOOLS.includes(toolName)) return false;
+		if (toolName !== PLAN_TOOL) return false;
 		const info = pi.getAllTools().find((tool) => tool.name === toolName);
 		const source = info?.sourceInfo?.path;
 		return source === undefined || options.entryPath === undefined || samePath(source, options.entryPath);
@@ -202,7 +214,7 @@ export function createPlanRuntime(
 
 	/** Tools plan mode would hide from the current active set. */
 	const captureHidden = (): string[] => [
-		...new Set(pi.getActiveTools().filter((name) => !policy.isAllowed(name) && !CONTROL_TOOLS.includes(name))),
+		...new Set(pi.getActiveTools().filter((name) => !policy.isAllowed(name) && !MODE_TOOLS.includes(name))),
 	];
 
 	/**
@@ -214,12 +226,18 @@ export function createPlanRuntime(
 		const active = pi.getActiveTools();
 		if (enabled) {
 			// Keep only tools the policy considers safe to expose while read-only
-			// (structured readers and the plan/goal trackers) plus the control tools.
-			pi.setActiveTools([...new Set([...active.filter((name) => policy.isAllowed(name)), ...CONTROL_TOOLS])]);
+			// (structured readers and the plan/goal trackers), plus the `plan` tool
+			// itself, whose actions are the mode's own vocabulary.
+			addedForPlan = MODE_TOOLS.filter((name) => !active.includes(name));
+			pi.setActiveTools([...new Set([...active.filter((name) => policy.isAllowed(name)), ...MODE_TOOLS])]);
 			return;
 		}
+		// A mode tool this enable had to activate goes back to how the user left it,
+		// rather than staying active because the mode needed it for a while.
+		const kept = active.filter((name) => !addedForPlan.includes(name));
+		addedForPlan = [];
 		const restored = addHidden ? removedForPlan : [];
-		pi.setActiveTools([...new Set([...active.filter((name) => !CONTROL_TOOLS.includes(name)), ...restored])]);
+		pi.setActiveTools([...new Set([...kept, ...restored])]);
 		removedForPlan = [];
 	};
 
@@ -227,7 +245,9 @@ export function createPlanRuntime(
 		lastPlanPath ? `${GLYPHS.plan} plan · ${statusName(lastPlanPath)}` : `${GLYPHS.plan} plan`;
 
 	const setStatus = (ctx: ExtensionContext): void => {
-		ctx.ui.setStatus(STATUS_KEYS.planMode, enabled ? paint(ctx.ui.theme, "warn", statusText()) : undefined);
+		// Published unstyled: the chip's text is what a footer without bytefly shows, and
+		// bytefly's mode segment paints the mode by role instead of reading this pill.
+		ctx.ui.setStatus(STATUS_KEYS.planMode, enabled ? statusText() : undefined);
 	};
 
 	const setEnabled = (next: boolean, ctx: ExtensionContext | undefined, persist: boolean): void => {

package/extensions/plan/sections.ts

@@ -2,7 +2,7 @@
  * Plan-document sections (pure).
  *
  * One fence-aware scan of a plan's markdown: the review screen navigates by
- * section, `set_plan_steps` looks up `## Steps`, a carried comment finds the
+ * section, the `plan` tool's `steps` action looks up `## Steps`, a carried comment finds the
  * block it belongs to, and the browser outline lists the same headings. A second
  * scanner would disagree about a heading inside a fence, so every reader goes
  * through this module.

package/extensions/plan/steps.ts

@@ -31,7 +31,7 @@ export const MAX_STEP_LENGTH = 200;
  * section that carries the end state — the same surface before and after when the
  * change alters one that already exists, one frame when it is new — in a fence
  * that stays untagged unless every line is code, so the reviewer sees the result
- * before the steps that build it. Guidance only: `write_plan` never rejects or
+ * before the steps that build it. Guidance only: the `write` action never rejects or
  * rewrites a plan that omits a section, and a change with no visible surface drops
  * `Visual`.
  */
@@ -268,7 +268,7 @@ const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
  * list markers and inline emphasis, and the lines are joined with `; `, prefixed
  * with `Verify:` and elided like a long step. The item is deliberately *not* a
  * plan step: it is not in the `Steps` section, so it must not count against the
- * step cap or appear in `set_plan_steps` numbering.
+ * step cap or appear in the `steps` action's numbering.
  *
  * A plan with no `Steps` heading feeds its shallowest list as steps (the older
  * rule), so that list already covers the verification bullets; appending a
@@ -297,7 +297,7 @@ export function extractPlanSteps(plan: string): PlanStep[] {
 	return topLevelItems(plan).map((item) => ({ content: elide(item.step.content), status: item.step.status }));
 }
 
-/** The full cost of a plan's step list, for the warning `write_plan` reports. */
+/** The full cost of a plan's step list, for the warning the `write` action reports. */
 export interface PlanStepSummary {
 	/** Top-level items in the step list, before the {@link MAX_STEPS} cap. */
 	total: number;

package/extensions/plan/todos.ts

@@ -44,7 +44,7 @@ export interface TodoMerge {
 /** Fallback list cap when the registered todo tool does not advertise one. */
 export const DEFAULT_TODO_MAX = 50;
 
-/** What the tick-time mirror did for one `set_plan_steps` batch. */
+/** What the tick-time mirror did for one `steps` batch. */
 export interface TodoMirror {
 	/** The list after the matching items were brought in line with the plan. */
 	todos: ExistingTodo[];