@gavin-hu/my-pi-agent 0.16.0 → 0.17.0

package/extensions/plan/commands.ts

@@ -22,6 +22,7 @@ const ENABLED_NOTICE = `Plan mode enabled — ${READ_ONLY_SUMMARY}.`;
 const DISABLED_NOTICE = "Plan mode disabled — full access restored.";
 const REVIEW_PREFIX = "review";
 const LIST_PREFIX = "list";
+const CANCEL_PREFIX = "cancel";
 
 /** Notice text for the current mode; shared by `/plan` and the `Ctrl+Alt+P` shortcut. */
 export function planModeNotice(enabled: boolean): string {
@@ -49,6 +50,11 @@ function isListSubcommand(prompt: string): boolean {
 	return prompt.toLowerCase() === LIST_PREFIX;
 }
 
+/** Exact `cancel` leaves plan mode without approving; a longer sentence stays a task. */
+function isCancelSubcommand(prompt: string): boolean {
+	return prompt.toLowerCase() === CANCEL_PREFIX;
+}
+
 /**
  * Whether a command line is the reserved `review` subcommand. Bare `review`
  * always is; a path after it is, but `review the auth flow` stays a task, so a
@@ -167,18 +173,27 @@ export function registerCommands(
 ): void {
 	pi.registerCommand("plan", {
 		description:
-			"Toggle plan mode (read-only exploration), enter it with an optional task, list saved plans, or review one in the browser",
+			"Toggle plan mode (read-only exploration), enter it with an optional task, list saved plans, review one in the browser, or cancel planning without approving",
 		getArgumentCompletions: (prefix) => {
 			const text = prefix.trimStart();
 			if (text.includes(" ")) return null;
-			const subcommands = [LIST_PREFIX, REVIEW_PREFIX].filter((name) => name.startsWith(text));
+			const subcommands = [LIST_PREFIX, REVIEW_PREFIX, CANCEL_PREFIX].filter((name) => name.startsWith(text));
 			return subcommands.length > 0 ? subcommands.map((value) => ({ value, label: value })) : null;
 		},
 		handler: async (args, ctx) => {
 			const prompt = args.trim();
 
-			// `/plan list` and `/plan review [path]` are reserved subcommands;
-			// everything else is a task.
+			// `/plan list`, `/plan review [path]`, and `/plan cancel` are reserved
+			// subcommands; everything else is a task.
+			if (isCancelSubcommand(prompt)) {
+				if (!runtime.isEnabled()) {
+					ctx.ui.notify("Plan mode is already off.", "info");
+					return;
+				}
+				runtime.disable(ctx);
+				ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
+				return;
+			}
 			if (isListSubcommand(prompt)) {
 				await openPlanIndex(pi, runtime, web, ctx);
 				return;

package/extensions/plan/config.ts

@@ -0,0 +1,27 @@
+/**
+ * Config-file support for plan mode.
+ *
+ * The `plan` section of the shared `bytefly.json` (global then project, project
+ * wins). Only the approval offer is configurable; plan mode itself never depends
+ * on it.
+ */
+
+import { loadConfigSection } from "../../lib/config.ts";
+
+export interface PlanConfig {
+	/** Ask before recording an approved plan's objective as the session goal. */
+	goalPrompt: boolean;
+}
+
+export const DEFAULT_CONFIG: PlanConfig = { goalPrompt: true };
+
+/** Normalize one merged config object over the running base. */
+export function normalizeConfig(raw: Record<string, unknown> | undefined, base: PlanConfig): PlanConfig {
+	if (!raw) return base;
+	return { goalPrompt: typeof raw.goalPrompt === "boolean" ? raw.goalPrompt : base.goalPrompt };
+}
+
+/** Effective plan config from the shared `plan` section (defaults, global, project). */
+export function loadConfig(cwd: string): PlanConfig {
+	return loadConfigSection(cwd, "plan", DEFAULT_CONFIG, normalizeConfig);
+}

package/extensions/plan/plan-index.ts

@@ -25,7 +25,7 @@ import type { PlanSummary } from "./plans.ts";
 
 /** Rows the screen shows when the terminal height is unknown. */
 const DEFAULT_ROWS = 14;
-/** Fixed rows around the list: header, summary, blank, range, detail, hint, blank. */
+/** Fixed rows around the list: header, summary, blank, range, detail, hint, closing rule. */
 const CHROME = 7;
 /** Longest title a row draws before the trailing meta wins the column. */
 const TITLE_WIDTH = 56;
@@ -221,6 +221,8 @@ export class PlanIndexComponent implements Component {
 				: screenHint(theme, w, ["Esc close", { text: "Enter review", color: "accent" }, "r reload", "↑/↓", "g/G"]);
 
 		return dockListFrame({
+			theme,
+			width: w,
 			header: titleRule(theme, w, "Plan index"),
 			summary: this.summaryLine(w),
 			body,

package/extensions/plan/plans.ts

@@ -6,7 +6,9 @@
  * read the same artifact the model is working from and the plan survives
  * outside the conversation without a partial write ever being visible. Files
  * live under `<repo-root>/.pi/plans` (the worktree root inside a worktree), or
- * under `<agent-dir>/plans` outside a repository.
+ * under `<agent-dir>/plans` outside a repository. An extension tool sees the
+ * session cwd rather than the worktree the user entered, so the active worktree
+ * is applied before any path is resolved.
  *
  * The directory is self-ignoring: the first write drops a `.gitignore` with `*`
  * so plans never show up as untracked files or inside rewind snapshots,
@@ -29,6 +31,7 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { CONFIG_DIR_NAME, getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolveEffectiveCwd } from "../../lib/env.ts";
 import { repoRootFor } from "../../lib/git/index.ts";
 import { sanitizeLine } from "../../lib/format.ts";
 import { isInside, isInsideReal } from "../../lib/path.ts";
@@ -219,19 +222,32 @@ async function repoRoot(pi: ExtensionAPI, cwd: string): Promise<string | undefin
 
 export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date } = {}): PlanStore {
 	const now = options.now ?? (() => new Date());
-	// One `git rev-parse` per working directory; a worktree switch is a new cwd.
+	// One `git rev-parse` per effective root; a worktree switch changes that root.
 	const dirCache = new Map<string, string>();
 
+	/**
+	 * The root every path here is resolved against.
+	 *
+	 * A tool registered by an extension receives the session's cwd, not the
+	 * worktree the user entered: only the built-ins are re-rooted. The worktree
+	 * extension publishes its root in the environment, so this is where the two
+	 * meet, and it is applied before the git lookup, the relative path, and the
+	 * plan path resolution.
+	 */
+	const baseOf = (cwd: string): string => resolveEffectiveCwd(cwd);
+
 	const dirFor = async (cwd: string): Promise<string> => {
-		const cached = dirCache.get(cwd);
+		const base = baseOf(cwd);
+		const cached = dirCache.get(base);
 		if (cached) return cached;
-		const root = await repoRoot(pi, cwd);
+		const root = await repoRoot(pi, base);
 		const dir = root ? join(root, CONFIG_DIR_NAME, "plans") : join(getAgentDir(), "plans");
-		dirCache.set(cwd, dir);
+		dirCache.set(base, dir);
 		return dir;
 	};
 
 	const write = async (cwd: string, input: WritePlanInput): Promise<WrittenPlan> => {
+		const base = baseOf(cwd);
 		const title = input.title.trim();
 		if (!title) throw new Error("A plan title is required.");
 		const bytes = Buffer.byteLength(input.content, "utf-8");
@@ -239,13 +255,13 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 			throw new Error(`The plan is too large (${bytes} bytes; the limit is ${MAX_PLAN_BYTES}).`);
 		}
 
-		const dir = await dirFor(cwd);
+		const dir = await dirFor(base);
 		mkdirSync(dir, { recursive: true });
 		ensureIgnored(dir);
 
 		let path: string;
 		if (input.planPath) {
-			const resolved = resolve(cwd, input.planPath);
+			const resolved = resolve(base, input.planPath);
 			if (!isContainedPlan(dir, resolved)) {
 				throw new Error("plan_path must be a markdown plan file inside the plans directory.");
 			}
@@ -260,18 +276,19 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 		}
 
 		writeAtomic(path, input.content);
-		return { path, relativePath: relativeTo(cwd, path), title, content: input.content, bytes };
+		return { path, relativePath: relativeTo(base, path), title, content: input.content, bytes };
 	};
 
 	const read = async (cwd: string, planPath: string): Promise<StoredPlan | undefined> => {
-		const dir = await dirFor(cwd);
-		const resolved = resolve(cwd, planPath);
+		const base = baseOf(cwd);
+		const dir = await dirFor(base);
+		const resolved = resolve(base, planPath);
 		if (!isContainedPlan(dir, resolved) || !existsSync(resolved)) return undefined;
 		try {
 			const content = readFileSync(resolved, "utf-8");
 			return {
 				path: resolved,
-				relativePath: relativeTo(cwd, resolved),
+				relativePath: relativeTo(base, resolved),
 				content,
 				bytes: Buffer.byteLength(content, "utf-8"),
 			};
@@ -375,7 +392,8 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 	 * dotfile, or a file that vanishes mid-walk is simply not a plan.
 	 */
 	const index = async (cwd: string): Promise<PlanSummary[]> => {
-		const dir = await dirFor(cwd);
+		const base = baseOf(cwd);
+		const dir = await dirFor(base);
 		let names: string[];
 		try {
 			names = readdirSync(dir);
@@ -399,7 +417,7 @@ export function createPlanStore(pi: ExtensionAPI, options: { now?: () => Date }
 
 			const summary: PlanSummary = {
 				path,
-				relativePath: relativeTo(cwd, path),
+				relativePath: relativeTo(base, path),
 				title: planTitle(name),
 				modified: info.mtimeMs,
 				bytes: info.size,

package/extensions/plan/review.ts

@@ -44,7 +44,9 @@ export type ReviewDecision =
 			/** True when the request came from the browser, which is reported differently. */
 			fromBrowser: boolean;
 	  }
-	| { action: "keep"; plan: StoredPlan };
+	| { 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 {
@@ -69,12 +71,16 @@ export interface ReviewPlanOptions {
 /** Prompt shown by the dialog-based refine editor in non-TUI modes. */
 const REFINE_PROMPT = "Refine the plan — what should change? (Enter to save, Esc to cancel)";
 
+/**
+ * How long a remote review waits for its answer. Much longer than a plain dialog's
+ * bound, because the human has to read the plan first and a phone is a slow place
+ * to do it; an expiry here also ends plan mode, so it must not be easy to hit.
+ */
+export const PLAN_REVIEW_TIMEOUT_MS = 600_000;
+
 /** How much of one step the remote digest shows. */
 const DIGEST_STEP_CHARS = 90;
 
-/** The refinement request used when a browser save carried no comments. */
-const NO_BROWSER_COMMENTS = "See the review comments in the plan file.";
-
 /**
  * A one-message digest of the plan for a remote review.
  *
@@ -94,7 +100,13 @@ function planReviewDigest(content: string): string {
 		return `${index + 1}. ${shown}`;
 	});
 	const more = count > preview.length ? `… (${count - preview.length} more)` : "";
-	return [head, ...preview, more, "The full plan is attached above, or sent as text if the file failed."]
+	return [
+		head,
+		...preview,
+		more,
+		"Plan mode is on — write access is off. Choose “Exit plan mode” to leave without approving.",
+		"The full plan is attached above, or sent as text if the file failed.",
+	]
 		.filter((line) => line !== "")
 		.join("\n");
 }
@@ -135,12 +147,16 @@ async function askPlanReview(
 					"Approve and execute",
 					"Send the full plan",
 					"Refine the plan",
-					"Keep planning",
+					"Keep planning (stay in plan mode)",
+					"Exit plan mode (discard)",
 				]);
 				if (choice === "Approve and execute") return { action: "approve" };
 				if (choice === "Send the full plan") return { action: "send" };
 				if (choice === "Refine the plan") return { action: "refine" };
-				return { action: "keep" };
+				if (choice === "Keep planning (stay in plan mode)") return { action: "keep" };
+				// Dismissing the plan gate means leaving plan mode, not silently staying
+				// in it. The explicit Keep choice above is the only way to stay.
+				return { action: "cancel" };
 			},
 			// A remote turn gets the plan file up front, falling back to the full text;
 			// a local TUI turn ignores both and renders the component. The digest goes
@@ -149,6 +165,7 @@ async function askPlanReview(
 			file: sentFullText ? undefined : { path: plan.path, name: basename(plan.relativePath) },
 			body: plan.content,
 			note: sentFullText ? undefined : planReviewDigest(plan.content),
+			timeoutMs: PLAN_REVIEW_TIMEOUT_MS,
 		});
 		if (outcome.action !== "send") return outcome;
 		sentFullText = true;
@@ -209,6 +226,7 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 
 		if (choice.action === "approve") return { action: "approve", plan, comments: [] };
 		if (choice.action === "keep") return { action: "keep", plan };
+		if (choice.action === "cancel") return { action: "cancel", plan };
 		if (choice.action === "refine") {
 			const refinement = choice.refinement ?? (await ctx.ui.editor(REFINE_PROMPT, ""))?.trim();
 			// An empty or cancelled editor returns to the review screen instead of
@@ -231,13 +249,15 @@ export async function reviewPlan(options: ReviewPlanOptions): Promise<ReviewDeci
 		}
 		if (result.status === "approved") return { action: "approve", plan: result.plan, comments: result.annotations };
 		if (result.status === "saved") {
-			return {
-				action: "refine",
-				plan: result.plan,
-				refinement: feedbackSummary(result.annotations) || NO_BROWSER_COMMENTS,
-				comments: result.annotations,
-				fromBrowser: true,
-			};
+			// A save with no comments asks for nothing, so it returns to the screen the
+			// way an empty refine editor does, instead of reporting a refinement nobody
+			// wrote.
+			const refinement = feedbackSummary(result.annotations);
+			if (!refinement) {
+				plan = result.plan;
+				continue;
+			}
+			return { action: "refine", plan: result.plan, refinement, comments: result.annotations, fromBrowser: true };
 		}
 		// Cancelled or the tab closed: the file may have been rewritten underneath,
 		// so re-read it before showing the screen again.

package/extensions/plan/runtime.ts

@@ -32,6 +32,8 @@ import type { PlanModeEntry, ReviewBaselineEntry } 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. */
@@ -47,7 +49,7 @@ export const BASELINE_TYPE = "plan-baseline";
 const STATUS_NAME_LENGTH = 28;
 
 /** Tools plan mode activates itself; the guard permits only this extension's own. */
-const CONTROL_TOOLS = [EXIT_TOOL, WRITE_PLAN_TOOL];
+const CONTROL_TOOLS = [EXIT_TOOL, CANCEL_TOOL, WRITE_PLAN_TOOL];
 
 export interface PlanRuntime {
 	/** Whether plan mode is currently on. */

package/extensions/plan/steps.ts

@@ -23,34 +23,59 @@ export const MAX_STEPS = 50;
 export const MAX_STEP_LENGTH = 200;
 
 /**
- * The outline a plan is guided to follow. Guidance only: `write_plan` never
- * rejects or rewrites a plan that omits a section.
+ * The outline a plan is guided to follow: one job per section, and every example
+ * is the shape wanted rather than a description of it. `Visual` is the one
+ * 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
+ * rewrites a plan that omits a section, and a change with no visible surface drops
+ * `Visual`.
  */
 export const PLAN_OUTLINE = [
 	"# <Title>",
 	"",
 	"## Goal",
-	"What this change achieves, and what it deliberately does not.",
+	"One sentence: the outcome this change delivers, and what it deliberately does not do.",
 	"",
 	"## Context",
-	"The relevant code, constraints, and prior art.",
+	"- `src/load.ts:42` reads the config once at startup; that is the only caller.",
+	"- The file is user-editable, so a bad key must name the file and line.",
 	"",
 	"## Approach",
-	"The chosen approach and why; alternatives considered.",
+	"- Parse into a typed record in `parseConfig`; `load()` keeps the file read.",
+	"- Rejected: validating inside `load()`, because the test would need a filesystem.",
+	"",
+	"## Visual",
+	"A bad key at startup, before and after:",
+	"```",
+	"$ bun start",
+	'config.json:12: ignoring unknown key "timeout_ms"',
+	"```",
+	"",
+	"```",
+	"$ bun start",
+	'config.json:12: unknown key "timeout_ms" — did you mean "timeoutMs"?',
+	"```",
 	"",
 	"## Steps",
 	"- [ ] Add `parseConfig` in `src/config.ts`, with a test for a missing key",
-	"- [ ] Wire it into `load()` and document the failure in the README",
+	"  - `load()` is the only caller today; it keeps the file read.",
+	"- [ ] Report a bad key with its file and line, and note the rule in the README",
 	"",
 	"## Risks",
-	"What could go wrong and how it is mitigated.",
+	"- A missing key now fails at startup rather than on first use: name that in the README.",
+	"- Mitigated by the test in the first step.",
 	"",
 	"## Verification",
-	"How to prove it works: commands and checks.",
+	"```bash",
+	"bun test src/config.test.ts",
+	"bun run check",
+	"```",
 ].join("\n");
 
 /** The outline's section titles, in order, for documentation and tests. */
-export const PLAN_SECTIONS = ["Goal", "Context", "Approach", "Steps", "Risks", "Verification"] as const;
+export const PLAN_SECTIONS = ["Goal", "Context", "Approach", "Visual", "Steps", "Risks", "Verification"] as const;
 
 export interface PlanStep {
 	content: string;
@@ -233,11 +258,12 @@ const LIST_PREFIX = /^\s*(?:[-*+]|\d+[.)])\s+(?:\[[ xX]\]\s*)?/;
  * The plan's `Verification` section as one trailing checklist item, or
  * `undefined` when the plan has none.
  *
- * The section is prose ("commands and checks"), and a todo item is one line, so
- * the lines are stripped of list markers and inline emphasis and 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.
+ * The section is prose ("commands and checks") or a fenced block of them, and a
+ * todo item is one line, so the fence lines are dropped, the rest is stripped of
+ * 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.
  *
  * 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
@@ -252,6 +278,9 @@ export function verificationItem(plan: string): PlanStep | undefined {
 	const items = section.text
 		.split("\n")
 		.slice(1)
+		// A fenced block is how the outline asks for commands; its fence lines are
+		// punctuation, not a check, so only the commands inside it are carried.
+		.filter((line) => !FENCE.test(line))
 		.map((line) => plainText(line.replace(LIST_PREFIX, "")))
 		.filter(Boolean);
 	if (items.length === 0) return undefined;

package/extensions/plan/tools/cancel.ts

@@ -0,0 +1,79 @@
+/**
+ * The `cancel_plan_mode` tool registration.
+ *
+ * This is the escape hatch that does not need a plan file or a review dialog:
+ * when the user asks to leave planning, the model can restore write access
+ * without approving anything. The plan store is untouched; a later `/plan` can
+ * still review the saved artifact.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
+import { paint } from "../../../lib/tui/tokens.ts";
+import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
+import { CANCEL_TOOL, type PlanRuntime } from "../runtime.ts";
+import type { CancelPlanModeDetails } from "../types.ts";
+
+const CANCELLED_TEXT =
+	"Plan mode is off and write access is restored. The plan was not approved; no todo items or goal were recorded. " +
+	"Any saved plan file remains for a later review.";
+
+export function registerCancelTool(pi: ExtensionAPI, runtime: PlanRuntime): void {
+	pi.registerTool({
+		name: CANCEL_TOOL,
+		label: "Cancel plan mode",
+		description:
+			"Leave plan mode without approving a plan. Restores write access; no todo items or goal are recorded. " +
+			"Use when the user asks to exit, cancel, or abandon planning.",
+		promptSnippet: "Leave plan mode without approving the plan.",
+		promptGuidelines: [
+			"Call cancel_plan_mode when the user asks to leave or abandon planning without approving a plan.",
+		],
+		parameters: Type.Object({}),
+		defaultActive: false,
+		executionMode: "sequential",
+		// The mode change touches no files; like enter_plan_mode, it needs no
+		// destructive annotation.
+		annotations: { readOnlyHint: true, openWorldHint: false },
+
+		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+			if (!runtime.isEnabled()) {
+				return failedResult("Not in plan mode; there is nothing to cancel.", {
+					cancelled: false,
+				} satisfies CancelPlanModeDetails);
+			}
+			runtime.disable(ctx);
+			ctx.ui.notify("Plan mode off — full access restored. The plan was not approved.", "info");
+			return {
+				content: [{ type: "text", text: CANCELLED_TEXT }],
+				details: { cancelled: true } satisfies CancelPlanModeDetails,
+			};
+		},
+
+		renderCall(_args, theme, context) {
+			return callLine(theme, context?.lastComponent, CANCEL_TOOL, "left plan mode");
+		},
+
+		renderResult(result, options, theme, context) {
+			const text = reuseText(context?.lastComponent);
+			const outcome = detailsOrLine(
+				theme,
+				result,
+				options.expanded,
+				toolDetails<CancelPlanModeDetails>(result.details),
+			);
+			if ("line" in outcome) {
+				text.setText(outcome.line);
+				return text;
+			}
+			text.setText(
+				outcome.details.cancelled
+					? paint(theme, "warn", "Plan mode off — plan not approved")
+					: paint(theme, "meta", "Not in plan mode"),
+			);
+			return text;
+		},
+	});
+}

package/extensions/plan/tools/enter.ts

@@ -11,6 +11,8 @@ import { reuseText, toolDetails } from "../../../lib/tui/chrome.ts";
 import { GLYPHS } from "../../../lib/tui/glyphs.ts";
 import { paint } from "../../../lib/tui/tokens.ts";
 import { callLine, detailsOrLine } from "../../../lib/tui/tool.ts";
+import { failedResult } from "../../../lib/tool-result.ts";
+import { isRemoteTurn } from "../../../lib/interaction.ts";
 import { PLAN_CONSENT, READ_ONLY_SUMMARY } from "../../../lib/plan-entry.ts";
 import { ENTER_TOOL, type PlanRuntime } from "../runtime.ts";
 import type { EnterPlanModeDetails } from "../types.ts";
@@ -45,16 +47,10 @@ export function registerEnterTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 				};
 			}
 			if (!ctx.hasUI) {
-				return {
-					content: [
-						{
-							type: "text",
-							text: "No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
-						},
-					],
-					details: { entered: false, unavailable: true } satisfies EnterPlanModeDetails,
-					isError: true,
-				};
+				return failedResult(
+					"No interactive UI is available to confirm entering plan mode. Ask the user whether they want a plan.",
+					{ entered: false, unavailable: true } satisfies EnterPlanModeDetails,
+				);
 			}
 
 			const approved = await ctx.ui.confirm("Enter plan mode?", PLAN_CONSENT);
@@ -65,6 +61,10 @@ export function registerEnterTool(pi: ExtensionAPI, runtime: PlanRuntime): void
 				};
 			}
 			runtime.enable(ctx);
+			if (isRemoteTurn(ctx)) {
+				// The peer UI has no footer chip; say the mode and its exit in the chat.
+				ctx.ui.notify("Plan mode on — write access is off. Say “exit plan mode” to leave without approving.", "info");
+			}
 			return {
 				content: [{ type: "text", text: ENTERED_TEXT }],
 				details: { entered: true } satisfies EnterPlanModeDetails,