one-code-extension 0.4.1 → 0.6.0

package/extensions/plan-mode/index.ts

@@ -13,31 +13,64 @@
  * turn puts the block on the queue before the turn's next request — until
  * 2026-09-05 the mid-turn requests ran with no plan reminder while every edit
  * was denied "see the plan-mode reminder" (STEERING-REVIEW-2026-09-05 M3) —
- * and on before_agent_start, which covers a session that STARTS in plan mode
- * before this extension has seen a context (defaultMode: "plan"; permissions'
- * session_start runs first) and runs after every extension's session_start,
- * so restoring a previous path from the session branch never races a fresh
- * allocation.
+ * and on session_start, after restoring a previous path and its baseline.
+ * A session that STARTS in plan mode must install the block before the first
+ * prompt is stamped: before_agent_start is already too late to anchor it to
+ * that prompt. before_agent_start also re-announces the existing state.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { registerFormTool } from "../lib/tool-variants.ts";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
 import { oneCodeStateDir } from "../lib/paths.ts";
 import { REMINDER_CHANNEL } from "../lib/reminders.ts";
+import { canShowCustomUi } from "../lib/headless-output.ts";
 import { ccToolRenderers, safeThemePaint } from "../lib/tui-render.ts";
+import { userDenialText } from "../lib/user-denial.ts";
 import type { PermissionMode } from "../permissions/matcher.ts";
 import { PERMISSION_STATUS_CHANNEL, type PermissionStatus } from "../permissions/modes.ts";
 import { buildPlanModeReminder } from "./reminder.ts";
 import { randomSlug } from "./slug.ts";
-import { clampOffset, decodeViewerKey, initialPlanChoice, type PlanChoice, renderPlanViewer, wrapPlanText } from "./viewer.ts";
+import { readState, recordState } from "../lib/ledger/state.ts";
 
-import { MODE_CHANNEL, PLAN_FILE_CHANNEL } from "../lib/plan-mode-channels.ts";
+/** A plan file larger than this is named after a compaction, not inlined: the model reads it when it needs it. */
+const PLAN_REFERENCE_CHARS = 40_000;
+
+/** The plan the summary replaced, re-attached after a compaction. */
+function planFileReferenceText(path: string, content: string): string {
+	if (content.length > PLAN_REFERENCE_CHARS) return `A plan file exists from plan mode at: ${path}\n\nIt is too large to include here (${content.length.toLocaleString("en-US")} characters); read it before continuing.\n\nIf this plan is relevant to the current work and not already complete, continue working on it.`;
+	return `A plan file exists from plan mode at: ${path}\n\nPlan contents:\n\n${content}\n\nIf this plan is relevant to the current work and not already complete, continue working on it.`;
+}
+
+import { PLAN_ENTRY_STATE, parsePlanRun, type PlanRun } from "./run-state.ts";
+import {
+	approvedPlanText,
+	ENTER_PLAN_MODE_DESCRIPTION,
+	enteredPlanModeText,
+	enterPlanModeDescription,
+	EXIT_PLAN_MODE_DESCRIPTION,
+	exitedPlanModeText,
+} from "./texts.ts";
+import { createMarkdownProse } from "../subagents/prose.ts";
+import type { ProseRenderer } from "../subagents/panel-render.ts";
+import {
+	clampOffset,
+	decodeViewerKey,
+	initialPlanChoice,
+	KEEP_PLANNING_QUESTION,
+	type PlanChoice,
+	planLines,
+	renderPlanViewer,
+	runPlanApproval,
+	selectPlanChoice,
+} from "./viewer.ts";
+
+import { MODE_CHANNEL, PLAN_FILE_CHANNEL, PLAN_FILE_ENTRY, planFileOnBranch, planFileRecords, type PlanFileRecord } from "../lib/plan-mode-channels.ts";
+import { panelUi } from "../lib/panel-focus.ts";
 export { MODE_CHANNEL, PLAN_FILE_CHANNEL };
-/** Session entry type persisting the allocated path across resume/branch. */
-const PLAN_FILE_ENTRY = "one-code:plan-mode-file";
 
 const PLANS_DIR = () => join(oneCodeStateDir(), "plans");
 
@@ -55,48 +88,126 @@ export default function planModeExtension(pi: ExtensionAPI) {
 	/** The last mode broadcast by permissions; undefined until the first status arrives. */
 	let currentMode: string | undefined;
 	/**
-	 * The mode the session was in when it entered plan mode, offered first on
-	 * exit (Claude Code's ExitPlanMode restores `prePlanMode`). Unknown for a
-	 * session that STARTED in plan mode — the first status seen is plan itself —
-	 * so that session gets the fixed list. Until 2026-09-05 the exit could only
-	 * escalate: a default-mode session that planned was offered auto
-	 * (PERMISSIONS-REVIEW-2026-09-05 M4).
+	 * The live mode the last switch into plan mode came from. It is recorded on
+	 * the branch only when that switch begins a run (`refresh` finds no run
+	 * recorded for the branch's plan file). A switch that merely restores a run,
+	 * permissions following a /tree to a branch in plan mode, keeps the branch's
+	 * own value, since the live mode before it belongs to the abandoned branch.
 	 */
-	let modeBeforePlan: PermissionMode | undefined;
-	let planFilePath: string | undefined;
+	let enteredFrom: PermissionMode | undefined;
+	/** Whether the session can enter bypassPermissions, as permissions last said: the exit offers it back only then. */
+	let bypassAvailable = false;
 
-	/** Restore the branch's plan file, else allocate a fresh slug. */
-	const ensurePlanFile = (ctx: ExtensionContext): string => {
-		if (planFilePath) return planFilePath;
-
-		for (const entry of ctx.sessionManager.getBranch()) {
-			if (entry.type !== "custom" || entry.customType !== PLAN_FILE_ENTRY) continue;
-			const path = (entry.data as { path?: unknown } | undefined)?.path;
-			if (typeof path === "string") planFilePath = path;
-		}
-		if (planFilePath) return planFilePath;
+	/**
+	 * The current run as the branch recorded it when plan mode came on: its plan
+	 * file, whether that file existed then (which picks Claude Code's "Plan File
+	 * Info" line, fixed for the run so the sticky block stays byte-identical turn
+	 * after turn, plan-mode/reminder.ts), and the mode it came from, offered
+	 * first on exit (Claude Code's ExitPlanMode restores `prePlanMode`). Read
+	 * from the branch every time, never kept here, so a /reload, a resume and a
+	 * /tree each see the run of the branch they land on. Until 2026-09-05 the
+	 * exit could only escalate: a default-mode session that planned was offered
+	 * auto (PERMISSIONS-REVIEW-2026-09-05 M4).
+	 */
+	const runOnBranch = (ctx: ExtensionContext, path: string): PlanRun | undefined => parsePlanRun(readState(ctx, PLAN_ENTRY_STATE), path);
+	/** Record the current run on the branch, for `runOnBranch` to read back. */
+	const recordRun = (path: string, run: PlanRun) => recordState(pi, PLAN_ENTRY_STATE, { path, ...run });
 
+	const freshPlanPath = (): string => {
 		let path = join(PLANS_DIR(), `${randomSlug()}.md`);
 		for (let attempt = 0; attempt < 5 && existsSync(path); attempt++) {
 			path = join(PLANS_DIR(), `${randomSlug()}.md`);
 		}
-		planFilePath = path;
-		pi.appendEntry(PLAN_FILE_ENTRY, { path });
 		return path;
 	};
 
-	/** Re-announce path + reminder; every-turn re-emits replace by key. */
-	const refresh = (ctx: ExtensionContext) => {
+	/**
+	 * A fork's own copy of the plan another session recorded, as Claude Code
+	 * gives a forked session, so the two sessions never overwrite each other's plan
+	 * (decisions/modes.md). The copy this session already made of it, on any
+	 * of its branches, is reused. The run moves to the copy with the mode it
+	 * came from, and says whether the copy exists (the parent's run may have
+	 * begun before its plan did).
+	 */
+	const forkPlanFile = (ctx: ExtensionContext, parent: PlanFileRecord, sessionId: string): string => {
+		const made = planFileRecords(ctx.sessionManager.getEntries()).find((r) => r.sessionId === sessionId && r.copiedFrom === parent.path);
+		const path = made?.path ?? freshPlanPath();
+		if (!made && existsSync(parent.path)) {
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				copyFileSync(parent.path, path);
+			} catch (error) {
+				if (ctx.hasUI) ctx.ui.notify(`Could not copy the plan at ${parent.path} for this fork (${(error as Error).message}); its plan starts empty at ${path}.`, "warning");
+			}
+		}
+		const run = runOnBranch(ctx, parent.path);
+		pi.appendEntry(PLAN_FILE_ENTRY, { path, sessionId, copiedFrom: parent.path } satisfies PlanFileRecord);
+		// The standing block names the new path anyway, so it also says whether the copy exists.
+		if (run) recordRun(path, { ...run, existed: existsSync(path) });
+		return path;
+	};
+
+	/**
+	 * The branch's plan file, else a fresh slug recorded on the branch. A
+	 * record another session made (a fork copies its parent's entries) gets
+	 * this session's own copy, and so does a record that names no session (an
+	 * older session's): only a record this session made is its own.
+	 * Never cached: on /tree, permissions' session_tree switches the mode (and
+	 * this extension refreshes) before this extension's own session_tree runs,
+	 * so a cached path would be the abandoned branch's.
+	 */
+	const ensurePlanFile = (ctx: ExtensionContext, onBranch = planFileRecords(ctx.sessionManager.getBranch()).at(-1)): string => {
+		const sessionId = ctx.sessionManager.getSessionId();
+		if (onBranch?.sessionId === sessionId) return onBranch.path;
+		if (onBranch) return forkPlanFile(ctx, onBranch, sessionId);
+
+		const path = freshPlanPath();
+		pi.appendEntry(PLAN_FILE_ENTRY, { path, sessionId } satisfies PlanFileRecord);
+		return path;
+	};
+
+	/** A branch that names a plan file owns it before anything reads it: a fork copies its parent's now. */
+	const ownPlanFile = (ctx: ExtensionContext) => {
+		const onBranch = planFileRecords(ctx.sessionManager.getBranch()).at(-1);
+		if (onBranch?.path) ensurePlanFile(ctx, onBranch);
+	};
+
+	/** Re-announce path + reminder; a re-emit replaces the sticky state by key. */
+	const refresh = (ctx: ExtensionContext, toolCallId?: string) => {
 		const path = ensurePlanFile(ctx);
+		let run = runOnBranch(ctx, path);
+		if (!run) {
+			// A run begins: record what it began with.
+			run = { existed: existsSync(path), ...(enteredFrom ? { modeBeforePlan: enteredFrom } : {}) };
+			recordRun(path, run);
+		}
 		pi.events.emit(PLAN_FILE_CHANNEL, { path });
 		pi.events.emit(REMINDER_CHANNEL, {
-			text: buildPlanModeReminder(path),
-			scope: "every-turn",
+			text: buildPlanModeReminder(path, run.existed),
 			key: "permission-mode",
 			placement: "sticky-append",
+			toolCallId,
 		});
 	};
 
+	/**
+	 * pi-tui's Markdown renderer for the approval dialog, loaded on first use.
+	 * A failed load is not cached (the theme may not be ready yet); the dialog
+	 * then wraps the plan as plain text.
+	 */
+	let markdownLoad: Promise<ProseRenderer | undefined> | undefined;
+	const planMarkdown = (): Promise<ProseRenderer | undefined> =>
+		(markdownLoad ??= createMarkdownProse().catch(() => {
+			markdownLoad = undefined;
+			return undefined;
+		}));
+
+	/** Plan approvals the user dismissed without words: the turn stops once pi records their result. */
+	const abortAfterResult = new Set<string>();
+	pi.on("tool_execution_end", (event, ctx) => {
+		if (abortAfterResult.delete(event.toolCallId)) ctx.abort();
+	});
+
 	/** The last context seen, for a refresh triggered off the bus (no ctx of its own). */
 	let lastCtx: ExtensionContext | undefined;
 
@@ -105,18 +216,32 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		if (typeof status?.mode !== "string") return;
 		const previous = currentMode;
 		currentMode = status.mode;
-		if (currentMode === "plan" && previous !== "plan") modeBeforePlan = previous as PermissionMode | undefined;
-		// Entering plan mode mid-turn: permissions' setMode has just dropped the
+		bypassAvailable = status.bypassAvailable === true;
+		// Unknown for a session that STARTED in plan mode (the first status seen
+		// is plan itself): a run it begins offers the fixed list on exit.
+		if (currentMode === "plan" && previous !== "plan") enteredFrom = previous as PermissionMode | undefined;
+		// The run ended: the next entry decides afresh.
+		if (previous === "plan" && currentMode !== "plan") recordState(pi, PLAN_ENTRY_STATE, null);
+		// Entering plan mode mid-turn: permissions' setMode has just closed the
 		// shared "permission-mode" key (before broadcasting this status, so this
 		// re-add is not undone) and will announce the change on the next tool
 		// result; the standing block has to be back on the queue for that same
 		// request. The path is announced over PLAN_FILE_CHANNEL inside refresh,
 		// synchronously, so setMode's announcement can name it.
-		if (currentMode === "plan" && previous !== "plan" && lastCtx) refresh(lastCtx);
+		if (currentMode === "plan" && previous !== "plan" && lastCtx) refresh(lastCtx, status.toolCallId);
 	});
 
 	pi.on("session_start", (_event, ctx) => {
 		lastCtx = ctx;
+		ownPlanFile(ctx);
+		if (currentMode === "plan") refresh(ctx);
+	});
+	// The plan file and its run follow the branch (both are read from it): a
+	// /tree switch takes the selected branch's, or allocates one there.
+	pi.on("session_tree", (_event, ctx) => {
+		lastCtx = ctx;
+		ownPlanFile(ctx);
+		if (currentMode === "plan") refresh(ctx);
 	});
 
 	pi.on("before_agent_start", (_event, ctx) => {
@@ -124,42 +249,69 @@ export default function planModeExtension(pi: ExtensionAPI) {
 		if (currentMode === "plan") refresh(ctx);
 	});
 
-	pi.registerTool({
-		name: "enter_plan_mode",
-		label: "Enter plan mode",
-		...ccToolRenderers("Enter plan mode"),
-		description:
-			"Enter plan mode: read-only investigation to design an approach before changing anything. Most tasks do not need it.\n" +
-			"For a small or clearly-scoped change, act directly instead. Enter plan mode only for multi-file work whose design is genuinely unclear, or when the user asks for a plan. In plan mode only read-only tools are available, plus one writable file: the plan file whose path you are told, where you build the plan incrementally.",
-		parameters: Type.Object({}),
-		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-			pi.events.emit(MODE_CHANNEL, { mode: "plan" });
-			// setMode broadcasts synchronously over the status channel, so the
-			// listener above has already installed the block and announced the
-			// path (or the mode was plan already and both stand); name the file in
-			// the tool result too so the model can start writing this same turn.
-			const path = ensurePlanFile(ctx);
-			return {
-				content: [
-					{
-						type: "text",
-						text: `Entered plan mode. Only read-only tools are available, except for your plan file at ${path} — build your plan there incrementally, then call exit_plan_mode to request approval.`,
-					},
-				],
-				details: { planFilePath: path },
-			};
-		},
+	// A compaction summarizes the plan away and opens an epoch, where nothing
+	// above has to stay byte-stable (R3-M20). The plan file is re-attached
+	// whenever one exists, plan mode or not, as Claude Code does; in plan mode
+	// the run is recorded again, so the new epoch's block says whether the file
+	// exists now.
+	pi.on("session_compact", (_event, ctx) => {
+		lastCtx = ctx;
+		const path = planFileOnBranch(ctx.sessionManager.getBranch());
+		if (!path) return;
+		if (currentMode === "plan") {
+			recordRun(path, { ...runOnBranch(ctx, path), existed: existsSync(path) });
+			refresh(ctx);
+		}
+		let content = "";
+		try {
+			content = existsSync(path) ? readFileSync(path, "utf8") : "";
+		} catch {
+			// The re-attach is best effort, like the other post-compaction restores:
+			// an unreadable path (a directory, no permission) attaches nothing.
+		}
+		if (!content.trim()) return;
+		pi.events.emit(REMINDER_CHANNEL, { text: planFileReferenceText(path, content), placement: "user-prepend", orTail: true, untilCompaction: true });
 	});
 
+	/**
+	 * enter_plan_mode's description follows the model's tier: Claude Code's,
+	 * which prefers plan mode, on frontier and workhorse, and One Code's, which
+	 * says most tasks do not need it, on cheap and tiny (`texts.ts`, through the
+	 * shared lib/tool-variants.ts). A re-registration keeps the tool's active
+	 * state, so the deferred tool stays deferred, and it sets no prompt snippet,
+	 * so the system prompt never moves with it.
+	 */
+	registerFormTool(
+		pi,
+		defineTool({
+			name: "enter_plan_mode",
+			label: "Enter plan mode",
+			...ccToolRenderers("Enter plan mode"),
+			description: ENTER_PLAN_MODE_DESCRIPTION,
+			parameters: Type.Object({}),
+			async execute(toolCallId, _params, _signal, _onUpdate, ctx) {
+				pi.events.emit(MODE_CHANNEL, { mode: "plan", toolCallId });
+				// setMode broadcasts synchronously over the status channel, so the
+				// listener above has already installed the block and announced the
+				// path (or the mode was plan already and both stand); name the file in
+				// the tool result too so the model can start writing this same turn.
+				const path = ensurePlanFile(ctx);
+				return {
+					content: [{ type: "text", text: enteredPlanModeText(path) }],
+					details: { planFilePath: path },
+				};
+			},
+		}),
+		enterPlanModeDescription,
+	);
+
 	pi.registerTool({
 		name: "exit_plan_mode",
 		label: "Exit plan mode",
 		...ccToolRenderers("Exit plan mode"),
-		description:
-			"Signal that planning is complete and ask the user to approve the plan.\n" +
-			"Takes no parameters: the plan is read from the plan file named in the plan-mode reminder, which you must have written before calling this. The user reviews that file's contents.",
+		description: EXIT_PLAN_MODE_DESCRIPTION,
 		parameters: Type.Object({}),
-		async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+		async execute(toolCallId, _params, signal, _onUpdate, ctx) {
 			// Guard the out-of-sequence call: without this, a cold exit_plan_mode
 			// (never entered plan mode) allocates a fresh empty plan file and blames
 			// "the plan file is empty" — a plausible but wrong cause a weak model
@@ -213,11 +365,15 @@ export default function planModeExtension(pi: ExtensionAPI) {
 			// The mode the session was in before planning leads the list (Claude
 			// Code restores it), then auto mode when a classifier model is reachable —
 			// the same gate the mode cycle uses (permissions/index.ts autoInCycle) —
-			// and the fixed choices. Each approving choice carries the mode it
-			// switches to; the final "Keep planning" choice has none and leaves the
-			// session in plan mode.
+			// and the fixed choices. A bypass before planning is offered back only
+			// when this session can grant it (a resume without the bypass flag
+			// cannot, and the request would land in default). Each approving
+			// choice carries the mode it switches to; the final "Keep planning"
+			// choice has none and leaves the session in plan mode.
 			const autoAvailable = ctx.modelRegistry.getAvailable().length > 0;
-			const restore = modeBeforePlan && (modeBeforePlan !== "auto" || autoAvailable) ? modeBeforePlan : undefined;
+			const modeBeforePlan = runOnBranch(ctx, path)?.modeBeforePlan;
+			const offerable = (mode: PermissionMode) => (mode !== "auto" || autoAvailable) && (mode !== "bypassPermissions" || bypassAvailable);
+			const restore = modeBeforePlan && offerable(modeBeforePlan) ? modeBeforePlan : undefined;
 			const fixedModes: PermissionMode[] = [...(autoAvailable ? (["auto"] as const) : []), "acceptEdits", "default"];
 			const options: { label: string; mode?: PermissionMode; restore?: boolean }[] = [
 				...(restore ? [{ label: `Approve — back to ${MODE_NAMES[restore]} (the mode before planning)`, mode: restore, restore: true }] : []),
@@ -226,11 +382,30 @@ export default function planModeExtension(pi: ExtensionAPI) {
 			];
 			const choices = options.map((o) => o.label);
 
-			const choice = await ctx.ui.custom<PlanChoice | null>((tui, theme, _keybindings, done) => {
+			// The plan renders as Markdown, like assistant text in the transcript.
+			const prose = canShowCustomUi(ctx) ? await planMarkdown() : undefined;
+			const planRef = {};
+			const markdown = prose ? (text: string, width: number) => prose(planRef, text, width) : undefined;
+
+			// The scroll position and the highlighted choice outlive one showing: a
+			// blank keep-planning answer reopens the dialog where the user left it.
+			const maxVisible = 12;
+			let offset = 0;
+			let selected: PlanChoice = initialPlanChoice(options);
+			const showDialog = (): Promise<PlanChoice | null> => !canShowCustomUi(ctx) ? selectPlanChoice(ctx.ui, plan, path, choices, signal) : panelUi(pi.events, ctx.ui).custom<PlanChoice | null>((tui, theme, _keybindings, close) => {
+				// An aborted turn closes the dialog as a cancel; a choice or a cancel
+				// drops the abort listener. Either way the dialog settles once.
+				let settled = false;
+				const onAbort = () => done(null);
+				const done = (choice: PlanChoice | null) => {
+					if (settled) return;
+					settled = true;
+					signal?.removeEventListener("abort", onAbort);
+					close(choice);
+				};
+				if (signal?.aborted) queueMicrotask(onAbort);
+				else signal?.addEventListener("abort", onAbort, { once: true });
 				const paint = safeThemePaint(theme);
-				const maxVisible = 12;
-				let offset = 0;
-				let selected: PlanChoice = initialPlanChoice(options);
 				let lineCount = 0;
 				// The dialog stays open while exit_plan_mode runs, so pi's working
 				// spinner drives ~8 frames a second — and re-wrapping the whole plan
@@ -243,7 +418,7 @@ export default function planModeExtension(pi: ExtensionAPI) {
 				let wrapped: { width: number; lines: string[] } | undefined;
 				let frame: { key: string; lines: string[] } | undefined;
 				const wrapAt = (wrapWidth: number): string[] => {
-					if (wrapped?.width !== wrapWidth) wrapped = { width: wrapWidth, lines: wrapPlanText(plan, wrapWidth) };
+					if (wrapped?.width !== wrapWidth) wrapped = { width: wrapWidth, lines: planLines(plan, wrapWidth, markdown) };
 					return wrapped.lines;
 				};
 				return {
@@ -274,29 +449,38 @@ export default function planModeExtension(pi: ExtensionAPI) {
 					},
 				};
 			});
+			const decision = await runPlanApproval(
+				options,
+				showDialog,
+				() => ctx.ui.input(KEEP_PLANNING_QUESTION, undefined, { signal }),
+				signal,
+			);
 
-			const picked = choice != null ? options[choice] : undefined;
+			const picked = decision.kind === "approve" ? options[decision.index] : undefined;
 			if (picked?.mode) {
-				pi.events.emit(MODE_CHANNEL, { mode: picked.mode });
+				pi.events.emit(MODE_CHANNEL, { mode: picked.mode, toolCallId });
+				// Claude Code's exit reminder, queued from execute so it is written
+				// into this result after the mode notice.
+				pi.events.emit(REMINDER_CHANNEL, { text: exitedPlanModeText(path), toolCallId });
 				return {
-					content: [
-						{
-							type: "text",
-							text: `Plan approved by the user. You may now implement it. The approved plan stays at ${path} for reference.`,
-						},
-					],
+					content: [{ type: "text", text: approvedPlanText(path, plan) }],
 					details: { plan, approved: true },
 				};
 			}
 
+			// Rejected: Claude Code's rejection text. With the user's words the model
+			// acts on them and keeps planning; without (Esc) the turn stops, as a
+			// reasonless permission rejection does (permissions/index.ts): `terminate`
+			// ends pi's loop after the batch, and the abort waits for the recorded
+			// result so the run ends as the user's interrupt.
+			const feedback = decision.kind === "reject" ? decision.feedback : undefined;
+			const stop = !feedback;
+			if (stop) abortAfterResult.add(toolCallId);
 			return {
-				content: [
-					{
-						type: "text",
-						text: "The user did not approve the plan. Stay in plan mode; refine the plan file based on their feedback.",
-					},
-				],
-				details: { plan, approved: false },
+				content: [{ type: "text", text: userDenialText(feedback) }],
+				details: { plan, approved: false, ...(feedback ? { feedback } : {}) },
+				isError: true,
+				...(stop ? { terminate: true } : {}),
 			};
 		},
 	});

package/extensions/plan-mode/reminder.ts

@@ -1,30 +1,98 @@
 /**
- * Plan-mode reminder text (pure). Byte-identical for a given plan-file path,
- * whether or not the file exists yet: the block is a sticky-append reminder
- * carried by every user message since plan mode came on, and the queue keeps
- * that anchor only while the re-emitted text is unchanged. A text that flipped
- * when the file appeared re-anchored the block and re-cached every message
- * between entering plan mode and the first write (CACHE-REVIEW-2026-09-04 M2).
+ * Plan-mode reminder text (pure): Claude Code's plan-mode instructions, the
+ * five-phase workflow, with One Code's tool and agent names. The block is a
+ * sticky-append reminder carried by every user message since plan mode came
+ * on, and the queue keeps that anchor only while the re-emitted text is
+ * unchanged, so the text must not flip while the mode lasts: a text that
+ * flipped when the file appeared re-anchored the block and re-cached every
+ * message between entering plan mode and the first write
+ * (CACHE-REVIEW-2026-09-04 M2). Claude Code's own "Plan File Info" line
+ * depends on whether the plan file exists; the caller decides that once, when
+ * plan mode comes on (`planExists`), and keeps it until the mode ends.
  *
- * Adapted from Claude Code's plan-mode system message: the plan lives in a
- * file the model builds incrementally — the one writable path in plan mode —
- * and exit_plan_mode reads that file rather than taking the plan as a
- * parameter. Claude Code's own text does vary with the file's existence; ours
- * folds both states into one sentence so the cached prefix survives.
+ * Claude Code puts this text in a system message on the models that take one
+ * and in a reminder elsewhere; One Code delivers it through the reminder
+ * queue's plan-mode placement either way.
  */
 
-export function buildPlanModeReminder(filePath: string): string {
-	const fileLine = `Build your plan at ${filePath} with the write/edit tools — create it if it does not exist yet, then edit it incrementally rather than rewriting it from scratch. Do not present the plan as chat text.`;
+/** Claude Code's "Plan File Info" line, for a plan file that exists or not yet. */
+export function planFileInfo(filePath: string, planExists: boolean): string {
+	return planExists
+		? `A plan file already exists at ${filePath}. You can read it and make incremental edits using the edit tool.`
+		: `No plan file exists yet. You should create your plan at ${filePath} using the write tool.`;
+}
+
+export function buildPlanModeReminder(filePath: string, planExists = false): string {
+	const fileInfo = planFileInfo(filePath, planExists);
 	return [
-		`Plan mode is active. You may only use read-only tools; edit and write are blocked everywhere except one file. ${fileLine}`,
+		"Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.",
+		"",
+		"## Plan File Info:",
+		fileInfo,
+		"You should build your plan incrementally by writing to or editing this file. NOTE that this is the only file you are allowed to edit - other than this you are only allowed to take READ-ONLY actions.",
+		"",
+		"## Plan Workflow",
+		"",
+		"### Phase 1: Initial Understanding",
+		"Goal: Gain a comprehensive understanding of the user's request by reading through code and asking them questions. Critical: In this phase you should only use the explore subagent type.",
+		"",
+		"1. Focus on understanding the user's request and the code associated with their request. Actively search for existing functions, utilities, and patterns that can be reused — avoid proposing new code when suitable implementations already exist.",
+		"",
+		"2. **Launch up to 3 explore agents IN PARALLEL** (single message, multiple tool calls) to efficiently explore the codebase.",
+		"   - Use 1 agent when the task is isolated to known files, the user provided specific file paths, or you're making a small targeted change.",
+		"   - Use multiple agents when: the scope is uncertain, multiple areas of the codebase are involved, or you need to understand existing patterns before planning.",
+		"   - Quality over quantity - 3 agents maximum, but you should try to use the minimum number of agents necessary (usually just 1)",
+		"   - If using multiple agents: Provide each agent with a specific search focus or area to explore. Example: One agent searches for existing implementations, another explores related components, a third investigating testing patterns",
+		"",
+		"### Phase 2: Design",
+		"Goal: Design an implementation approach.",
+		"",
+		"Launch plan agent(s) to design the implementation based on the user's intent and your exploration results from Phase 1.",
+		"",
+		"You can launch up to 3 agent(s) in parallel.",
+		"",
+		"**Guidelines:**",
+		"- **Default**: Launch at least 1 plan agent for most tasks - it helps validate your understanding and consider alternatives",
+		"- **Skip agents**: Only for truly trivial tasks (typo fixes, single-line changes, simple renames)",
+		"- **Multiple agents**: Use up to 3 agents for complex tasks that benefit from different perspectives",
+		"",
+		"Examples of when to use multiple agents:",
+		"- The task touches multiple parts of the codebase",
+		"- It's a large refactor or architectural change",
+		"- There are many edge cases to consider",
+		"- You'd benefit from exploring different approaches",
+		"",
+		"Example perspectives by task type:",
+		"- New feature: simplicity vs performance vs maintainability",
+		"- Bug fix: root cause vs workaround vs prevention",
+		"- Refactoring: minimal change vs clean architecture",
+		"",
+		"In the agent prompt:",
+		"- Provide comprehensive background context from Phase 1 exploration including filenames and code path traces",
+		"- Describe requirements and constraints",
+		"- Request a detailed implementation plan",
+		"",
+		"### Phase 3: Review",
+		"Goal: Review the plan(s) from Phase 2 and ensure alignment with the user's intentions.",
+		"1. Read the critical files you identified during exploration to deepen your understanding",
+		"2. Ensure that the plans align with the user's original request",
+		"3. Use ask_user_question to clarify any remaining questions with the user",
+		"",
+		"### Phase 4: Final Plan",
+		"Goal: Write your final plan to the plan file (the only file you can edit).",
+		"- Begin with a **Context** section: explain why this change is being made — the problem or need it addresses, what prompted it, and the intended outcome",
+		"- Include only your recommended approach, not all alternatives",
+		"- Ensure that the plan file is concise enough to scan quickly, but detailed enough to execute effectively",
+		"- Name the critical files to be modified. For changes that repeat a pattern across many files, describe the pattern once and list a few representative paths — do not enumerate every file or line number",
+		"- Reference existing functions and utilities you found that should be reused, with their file paths",
+		"- Include a verification section describing how to test the changes end-to-end (run the code, use MCP tools, run tests)",
+		"",
+		"### Phase 5: Call exit_plan_mode",
+		"At the very end of your turn, once you have asked the user questions and are happy with your final plan file - you should always call exit_plan_mode to indicate to the user that you are done planning.",
+		"This is critical - your turn should only end with either using the ask_user_question tool OR calling exit_plan_mode. Do not stop unless it's for these 2 reasons",
 		"",
-		"Workflow:",
-		'1. Explore: delegate broad reconnaissance to the `Agent` tool with `subagent_type: "explore"` (up to 3 in parallel) rather than reading everything yourself.',
-		'2. Design: delegate the implementation strategy to the `Agent` tool with `subagent_type: "plan"` once exploration has mapped the ground.',
-		"3. Review the critical files yourself, and call `ask_user_question` for any decision you cannot make on the user's behalf.",
-		`4. Write the final plan to ${filePath}: a Context section explaining why, your recommended approach (not several options), the critical files named, existing utilities to reuse, and a verification section.`,
-		"5. Call `exit_plan_mode` to ask the user to approve the plan. It reads the plan file directly — you do not pass the plan as a parameter. If `exit_plan_mode` is not in your active tools, load it first with tool_search (`select:exit_plan_mode`).",
+		"**Important:** Use ask_user_question ONLY to clarify requirements or choose between approaches. Use exit_plan_mode to request plan approval. Do NOT ask about plan approval in any other way - no text questions, no ask_user_question. Phrases like \"Is this plan okay?\", \"Should I proceed?\", \"How does this plan look?\", \"Any changes before we start?\", or similar MUST use exit_plan_mode.",
 		"",
-		"End every plan-mode turn with either `ask_user_question` or `exit_plan_mode`. Never ask for plan approval in chat text.",
+		"NOTE: At any point in time through this workflow you should feel free to ask the user questions or clarifications using the ask_user_question tool. Don't make large assumptions about user intent. The goal is to present a well researched plan to the user, and tie any loose ends before implementation begins.",
 	].join("\n");
 }

package/extensions/plan-mode/run-state.ts

@@ -0,0 +1,26 @@
+/**
+ * A plan-mode run as the branch records it (pure, no pi imports): its plan
+ * file's path, whether that file existed when the run began, and the mode the
+ * run came from. plan-mode/index.ts reads and writes the record.
+ */
+import type { PermissionMode } from "../permissions/matcher.ts";
+import { normalizePermissionMode } from "../permissions/settings.ts";
+
+/** The `one-code:state` key of the current plan-mode run. */
+export const PLAN_ENTRY_STATE = "plan-mode:entry";
+
+/** A plan-mode run as the branch records it, beside its plan file's path. */
+export type PlanRun = { existed: boolean; modeBeforePlan?: PermissionMode };
+
+/**
+ * The run `stored` records for the plan file at `path`, or undefined when it
+ * records another file or is malformed. A mode it came from that is unknown,
+ * or plan itself, is dropped: the exit then offers its fixed list.
+ */
+export function parsePlanRun(stored: unknown, path: string): PlanRun | undefined {
+	const record = stored as { path?: unknown; existed?: unknown; modeBeforePlan?: unknown } | null | undefined;
+	if (record?.path !== path || typeof record.existed !== "boolean") return undefined;
+	const mode = normalizePermissionMode(record.modeBeforePlan);
+	const before = mode !== "plan" ? mode : undefined;
+	return { existed: record.existed, ...(before ? { modeBeforePlan: before } : {}) };
+}