@oh-my-pi/pi-coding-agent 15.10.0 → 15.10.1

package/src/modes/utils/copy-targets.ts

@@ -9,6 +9,15 @@ export interface CodeBlock {
 	code: string;
 }
 
+/** A blockquote block: a maximal run of `>`-prefixed lines from markdown. */
+export interface QuoteBlock {
+	/** Block body with each line's `>` marker (and one optional space) removed. */
+	text: string;
+}
+
+/** A drillable block within an assistant message, in document order. */
+export type MessageBlock = ({ kind: "code" } & CodeBlock) | ({ kind: "quote" } & QuoteBlock);
+
 /** A runnable command found in the transcript. */
 export interface LastCommand {
 	kind: "bash" | "eval";
@@ -23,7 +32,7 @@ export interface LastCommand {
  * `children` to drill into.
  */
 export interface CopyTarget {
-	/** Stable identifier (e.g. "msg:1", "msg:1:code:0", "msg:1:all", "cmd:1"). */
+	/** Stable id (e.g. "msg:1", "msg:1:code:0", "msg:1:quote:0", "msg:1:all", "cmd:1"). */
 	id: string;
 	label: string;
 	/** Dim annotation: line/block counts, language, or tool name. */
@@ -49,17 +58,73 @@ export interface CopySource {
 /** Cap on how many recent assistant messages the picker lists. */
 const MAX_MESSAGES = 50;
 
-const CODE_BLOCK_RE = /^```([^\n]*)\n([\s\S]*?)^```/gm;
+const OPEN_FENCE_RE = /^```([^\n]*)$/;
+const CLOSE_FENCE_RE = /^```/;
+const QUOTE_LINE_RE = /^>(.*)$/;
 
-/** Extract fenced code blocks from assistant markdown, in document order. */
-export function extractCodeBlocks(text: string): CodeBlock[] {
-	const blocks: CodeBlock[] = [];
-	for (const match of text.matchAll(CODE_BLOCK_RE)) {
-		blocks.push({ lang: match[1].trim(), code: match[2].replace(/\n$/, "") });
+/**
+ * Split assistant markdown into drillable blocks — fenced code and `>`-quoted
+ * runs — in document order. Fences mask their bodies, so a `>` line inside a
+ * code block is never mistaken for a quote. An unclosed fence is treated as
+ * ordinary text, matching the fenced-block grammar.
+ */
+export function extractBlocks(text: string): MessageBlock[] {
+	const blocks: MessageBlock[] = [];
+	const lines = text.split("\n");
+	let quote: string[] | undefined;
+	const flushQuote = () => {
+		if (quote) {
+			blocks.push({ kind: "quote", text: quote.join("\n") });
+			quote = undefined;
+		}
+	};
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		const open = OPEN_FENCE_RE.exec(line);
+		if (open) {
+			let close = -1;
+			for (let k = i + 1; k < lines.length; k++) {
+				if (CLOSE_FENCE_RE.test(lines[k]!)) {
+					close = k;
+					break;
+				}
+			}
+			if (close !== -1) {
+				flushQuote();
+				blocks.push({ kind: "code", lang: open[1].trim(), code: lines.slice(i + 1, close).join("\n") });
+				i = close;
+				continue;
+			}
+		}
+
+		const quoted = QUOTE_LINE_RE.exec(line);
+		if (quoted) {
+			// Strip the `>` marker plus one optional following space.
+			quote ??= [];
+			quote.push(quoted[1].startsWith(" ") ? quoted[1].slice(1) : quoted[1]);
+		} else {
+			flushQuote();
+		}
 	}
+	flushQuote();
 	return blocks;
 }
 
+/** Extract fenced code blocks from assistant markdown, in document order. */
+export function extractCodeBlocks(text: string): CodeBlock[] {
+	return extractBlocks(text)
+		.filter((b): b is { kind: "code" } & CodeBlock => b.kind === "code")
+		.map(b => ({ lang: b.lang, code: b.code }));
+}
+
+/** Extract `>`-quoted blocks from assistant markdown, in document order. */
+export function extractQuoteBlocks(text: string): QuoteBlock[] {
+	return extractBlocks(text)
+		.filter((b): b is { kind: "quote" } & QuoteBlock => b.kind === "quote")
+		.map(b => ({ text: b.text }));
+}
+
 function extractEvalCode(args: unknown): { code: string; language: string } | undefined {
 	if (!args || typeof args !== "object") return undefined;
 	const cells = (args as { cells?: unknown }).cells;
@@ -136,42 +201,83 @@ function firstLine(text: string): string {
 	return text.trim().replace(/\s+/g, " ");
 }
 
-/** Build the target node for one assistant message: a leaf when it has no code
- * blocks, otherwise a group exposing the full message, each block, and "all". */
+/** "<n> lines · <c> code · <q> quote" — omitting block kinds that are absent. */
+function blockSummaryHint(text: string, codeCount: number, quoteCount: number): string {
+	const parts = [pluralLines(text)];
+	if (codeCount > 0) parts.push(`${codeCount} code`);
+	if (quoteCount > 0) parts.push(`${quoteCount} quote`);
+	return parts.join(" · ");
+}
+
+/** Build the target node for one assistant message: a leaf when it has no
+ * drillable blocks, otherwise a group exposing the full message plus each
+ * fenced code block and `>`-quoted block (de-prefixed) as a child target. */
 function messageTarget(text: string, rank: number): CopyTarget {
 	const id = `msg:${rank}`;
 	const label = firstLine(text);
-	const blocks = extractCodeBlocks(text);
-	const hint = blocks.length > 0 ? `${pluralLines(text)} · ${blocks.length} code` : pluralLines(text);
+	const blocks = extractBlocks(text);
 	const messageCopy = rank === 1 ? "Copied last message to clipboard" : "Copied message to clipboard";
 
 	if (blocks.length === 0) {
-		return { id, label, hint, preview: text, content: text, copyMessage: messageCopy };
+		return { id, label, hint: pluralLines(text), preview: text, content: text, copyMessage: messageCopy };
+	}
+
+	// The message node itself copies the full message; each block is a child
+	// copy target you can drill into, kept in document order.
+	const children: CopyTarget[] = [];
+	const codeBlocks: CodeBlock[] = [];
+	const quoteBlocks: QuoteBlock[] = [];
+	for (const block of blocks) {
+		if (block.kind === "code") {
+			const j = codeBlocks.length;
+			codeBlocks.push(block);
+			children.push({
+				id: `${id}:code:${j}`,
+				label: `Block ${j + 1}`,
+				hint: blockHint(block),
+				preview: block.code,
+				language: block.lang || undefined,
+				content: block.code,
+				copyMessage: `Copied code block ${j + 1} to clipboard`,
+			});
+		} else {
+			const j = quoteBlocks.length;
+			quoteBlocks.push(block);
+			children.push({
+				id: `${id}:quote:${j}`,
+				label: `Quote ${j + 1}`,
+				hint: pluralLines(block.text),
+				preview: block.text,
+				content: block.text,
+				copyMessage: `Copied quote block ${j + 1} to clipboard`,
+			});
+		}
 	}
 
-	// The message node itself copies the full message; its code blocks are
-	// child copy targets you can expand into.
-	const children: CopyTarget[] = blocks.map((block, j) => ({
-		id: `${id}:code:${j}`,
-		label: `Block ${j + 1}`,
-		hint: blockHint(block),
-		preview: block.code,
-		language: block.lang || undefined,
-		content: block.code,
-		copyMessage: `Copied code block ${j + 1} to clipboard`,
-	}));
-	if (blocks.length > 1) {
-		const combined = blocks.map(b => b.code).join("\n\n");
+	if (codeBlocks.length > 1) {
+		const combined = codeBlocks.map(b => b.code).join("\n\n");
 		children.push({
 			id: `${id}:all`,
-			label: `All ${blocks.length} blocks`,
+			label: `All ${codeBlocks.length} blocks`,
+			hint: pluralLines(combined),
+			preview: combined,
+			content: combined,
+			copyMessage: `Copied ${codeBlocks.length} code blocks to clipboard`,
+		});
+	}
+	if (quoteBlocks.length > 1) {
+		const combined = quoteBlocks.map(b => b.text).join("\n\n");
+		children.push({
+			id: `${id}:all-quotes`,
+			label: `All ${quoteBlocks.length} quotes`,
 			hint: pluralLines(combined),
 			preview: combined,
 			content: combined,
-			copyMessage: `Copied ${blocks.length} code blocks to clipboard`,
+			copyMessage: `Copied ${quoteBlocks.length} quote blocks to clipboard`,
 		});
 	}
 
+	const hint = blockSummaryHint(text, codeBlocks.length, quoteBlocks.length);
 	return { id, label, hint, preview: text, content: text, copyMessage: messageCopy, children };
 }
 

package/src/modes/utils/ui-helpers.ts

@@ -17,6 +17,7 @@ import {
 } from "../../modes/components/read-tool-group";
 import { SkillMessageComponent } from "../../modes/components/skill-message";
 import { ToolExecutionComponent } from "../../modes/components/tool-execution";
+import { TranscriptBlock } from "../../modes/components/transcript-container";
 import { UserMessageComponent } from "../../modes/components/user-message";
 import { materializeImageReferenceLinksSync } from "../../modes/image-references";
 import { theme } from "../../modes/theme/theme";
@@ -24,6 +25,7 @@ import type { CompactionQueuedMessage, InteractiveModeContext } from "../../mode
 import {
 	type CustomMessage,
 	isSilentAbort,
+	resolveAbortLabel,
 	SKILL_PROMPT_MESSAGE_TYPE,
 	type SkillPromptDetails,
 } from "../../session/messages";
@@ -73,9 +75,6 @@ export class UiHelpers {
 	 * we update the previous status line instead of appending new ones to avoid log spam.
 	 */
 	showStatus(message: string, options?: { dim?: boolean }): void {
-		if (this.ctx.isBackgrounded) {
-			return;
-		}
 		const children = this.ctx.chatContainer.children;
 		const last = children.length > 0 ? children[children.length - 1] : undefined;
 		const secondLast = children.length > 1 ? children[children.length - 2] : undefined;
@@ -90,11 +89,9 @@ export class UiHelpers {
 
 		const spacer = new Spacer(1);
 		const text = new Text(rendered, 1, 0);
-		this.ctx.chatContainer.addChild(spacer);
-		this.ctx.chatContainer.addChild(text);
+		this.ctx.present([spacer, text]);
 		this.ctx.lastStatusSpacer = spacer;
 		this.ctx.lastStatusText = text;
-		this.ctx.ui.requestRender();
 	}
 
 	addMessageToChat(
@@ -153,6 +150,7 @@ export class UiHelpers {
 											durationMs: details?.durationMs,
 										},
 									];
+						const block = new TranscriptBlock();
 						for (const job of jobs) {
 							const jobId = job.jobId ?? "unknown";
 							const typeLabel = job.type ? `[${job.type}]` : "[job]";
@@ -165,8 +163,9 @@ export class UiHelpers {
 							]
 								.filter(Boolean)
 								.join(" ");
-							this.ctx.chatContainer.addChild(new Text(line, 1, 0));
+							block.addChild(new Text(line, 1, 0));
 						}
+						this.ctx.chatContainer.addChild(block);
 						break;
 					}
 					if (message.customType === SKILL_PROMPT_MESSAGE_TYPE) {
@@ -206,19 +205,18 @@ export class UiHelpers {
 							body = details?.body ?? "";
 							arrow = `${from} ⇨ ${to}`;
 						}
-						const components: Component[] = [];
+						const block = new TranscriptBlock();
 						const header = `${theme.fg("accent", `[IRC] ${arrow}`)}`;
 						const headerComponent = new Text(header, 1, 0);
-						this.ctx.chatContainer.addChild(headerComponent);
-						components.push(headerComponent);
+						block.addChild(headerComponent);
 						if (body) {
 							for (const line of body.split("\n")) {
 								const lineComponent = new Text(theme.fg("muted", `  ${line}`), 0, 0);
-								this.ctx.chatContainer.addChild(lineComponent);
-								components.push(lineComponent);
+								block.addChild(lineComponent);
 							}
 						}
-						return components;
+						this.ctx.chatContainer.addChild(block);
+						return [block];
 					}
 					const renderer = this.ctx.session.extensionRunner?.getMessageRenderer(message.customType);
 					// Both HookMessage and CustomMessage have the same structure, cast for compatibility
@@ -229,14 +227,12 @@ export class UiHelpers {
 				break;
 			}
 			case "compactionSummary": {
-				this.ctx.chatContainer.addChild(new Spacer(1));
 				const component = new CompactionSummaryMessageComponent(message);
 				component.setExpanded(this.ctx.toolOutputExpanded);
 				this.ctx.chatContainer.addChild(component);
 				break;
 			}
 			case "branchSummary": {
-				this.ctx.chatContainer.addChild(new Spacer(1));
 				const component = new BranchSummaryMessageComponent(message);
 				component.setExpanded(this.ctx.toolOutputExpanded);
 				this.ctx.chatContainer.addChild(component);
@@ -244,6 +240,7 @@ export class UiHelpers {
 			}
 			case "fileMention": {
 				// Render compact file mention display
+				const block = new TranscriptBlock();
 				for (const file of message.files) {
 					let suffix: string;
 					if (file.skippedReason === "tooLarge") {
@@ -260,8 +257,9 @@ export class UiHelpers {
 						"accent",
 						file.path,
 					)} ${theme.fg("dim", suffix)}`;
-					this.ctx.chatContainer.addChild(new Text(text, 0, 0));
+					block.addChild(new Text(text, 0, 0));
 				}
+				if (block.children.length > 0) this.ctx.chatContainer.addChild(block);
 				break;
 			}
 			case "user":
@@ -338,18 +336,21 @@ export class UiHelpers {
 				if (assistantComponent) {
 					assistantComponent.setUsageInfo(message.usage);
 				}
-				readGroup = null;
+				const hasVisibleAssistantContent = message.content.some(
+					content =>
+						(content.type === "text" && content.text.trim().length > 0) ||
+						(content.type === "thinking" && content.thinking.trim().length > 0),
+				);
+				if (hasVisibleAssistantContent) {
+					readGroup?.finalize();
+					readGroup = null;
+				}
 				const isAbortedSilently = message.stopReason === "aborted" && isSilentAbort(message.errorMessage);
 				const hasErrorStop =
 					!isAbortedSilently && (message.stopReason === "aborted" || message.stopReason === "error");
 				const errorMessage = hasErrorStop
 					? message.stopReason === "aborted"
-						? (() => {
-								const retryAttempt = this.ctx.session.retryAttempt;
-								return retryAttempt > 0
-									? `Aborted after ${retryAttempt} retry attempt${retryAttempt > 1 ? "s" : ""}`
-									: "Operation aborted";
-							})()
+						? resolveAbortLabel(message.errorMessage, this.ctx.session.retryAttempt)
 						: message.errorMessage || "Error"
 					: null;
 
@@ -391,6 +392,7 @@ export class UiHelpers {
 						continue;
 					}
 
+					readGroup?.finalize();
 					readGroup = null;
 					const tool = this.ctx.session.getToolByName(content.name);
 					const renderArgs =
@@ -478,6 +480,10 @@ export class UiHelpers {
 			}
 		}
 
+		// The trailing read run has no following break to close it; finalize so the
+		// rebuilt group commits to native scrollback like every other historical block.
+		readGroup?.finalize();
+
 		// Render deferred messages (compaction summaries) at the bottom so they're visible
 		for (const message of deferredMessages) {
 			this.ctx.addMessageToChat(message, options);
@@ -490,8 +496,15 @@ export class UiHelpers {
 	renderInitialMessages(prebuiltContext?: SessionContext, options: RenderInitialMessagesOptions = {}): void {
 		// This path is used to rebuild the visible chat transcript (e.g. after custom/debug UI).
 		// Clear existing rendered chat first to avoid duplicating the full session in the container.
+		// On a non-preserving rebuild the existing blocks are discarded for good, so
+		// dispose them (stopping any live timers/subscriptions) before clearing. When
+		// preserving, the same instances are re-added below, so detach without dispose.
 		const preservedChatChildren = options.preserveExistingChat ? this.ctx.chatContainer.children : undefined;
-		this.ctx.chatContainer.clear();
+		if (preservedChatChildren) {
+			this.ctx.chatContainer.clear();
+		} else {
+			this.ctx.resetTranscript();
+		}
 		this.ctx.pendingMessagesContainer.clear();
 		this.ctx.pendingBashComponents = [];
 		this.ctx.pendingPythonComponents = [];
@@ -527,9 +540,6 @@ export class UiHelpers {
 	}
 
 	clearEditor(): void {
-		if (this.ctx.isBackgrounded) {
-			return;
-		}
 		this.ctx.editor.setText("");
 		this.ctx.pendingImages = [];
 		this.ctx.pendingImageLinks = [];
@@ -538,29 +548,17 @@ export class UiHelpers {
 	}
 
 	showError(errorMessage: string): void {
-		if (this.ctx.isBackgrounded) {
-			process.stderr.write(`Error: ${errorMessage}\n`);
-			return;
-		}
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(theme.fg("error", `Error: ${errorMessage}`), 1, 0)]);
 	}
 
 	showWarning(warningMessage: string): void {
-		if (this.ctx.isBackgrounded) {
-			process.stderr.write(`Warning: ${warningMessage}\n`);
-			return;
-		}
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0));
-		this.ctx.ui.requestRender();
+		this.ctx.present([new Spacer(1), new Text(theme.fg("warning", `Warning: ${warningMessage}`), 1, 0)]);
 	}
 
 	showNewVersionNotification(newVersion: string): void {
-		this.ctx.chatContainer.addChild(new Spacer(1));
-		this.ctx.chatContainer.addChild(new DynamicBorder(text => theme.fg("warning", text)));
-		this.ctx.chatContainer.addChild(
+		const block = new TranscriptBlock();
+		block.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+		block.addChild(
 			new Text(
 				theme.bold(theme.fg("warning", "Update Available")) +
 					"\n" +
@@ -570,8 +568,8 @@ export class UiHelpers {
 				0,
 			),
 		);
-		this.ctx.chatContainer.addChild(new DynamicBorder(text => theme.fg("warning", text)));
-		this.ctx.ui.requestRender();
+		block.addChild(new DynamicBorder(text => theme.fg("warning", text)));
+		this.ctx.present(block);
 	}
 
 	updatePendingMessagesDisplay(): void {

package/src/plan-mode/approved-plan.ts

@@ -1,15 +1,12 @@
-import * as fs from "node:fs/promises";
-import { isEnoent } from "@oh-my-pi/pi-utils";
-import { resolveLocalUrlToPath } from "../internal-urls";
-import { normalizeLocalScheme } from "../tools/path-utils";
 import { ToolError } from "../tools/tool-errors";
 
 /** Shape forwarded from the plan-mode resolve handler to InteractiveMode's
  *  approval popup. Populated by the standing handler that the resolve tool
- *  dispatches to when the agent submits `resolve { action: "apply" }`. */
+ *  dispatches to when the agent submits `resolve { action: "apply" }`.
+ *  `planFilePath` is the agent-chosen `local://<slug>-plan.md` artifact — it is
+ *  never renamed on approval, so links to it stay valid for the session. */
 export interface PlanApprovalDetails {
 	planFilePath: string;
-	finalPlanFilePath: string;
 	title: string;
 	planExists: boolean;
 }
@@ -110,54 +107,80 @@ export function humanizePlanTitle(title: string): string {
 	return spaced.charAt(0).toUpperCase() + spaced.slice(1);
 }
 
-interface RenameApprovedPlanFileOptions {
-	planFilePath: string;
-	finalPlanFilePath: string;
-	getArtifactsDir: () => string | null;
-	getSessionId: () => string | null;
+/** The `local://` URL a plan slug maps to. The agent writes the plan here and
+ *  passes the slug to `resolve`; the file is never renamed, so this URL — and
+ *  any hyperlink to it — stays valid for the life of the session. */
+export function planFileUrlForSlug(slug: string): string {
+	return `local://${slug}-plan.md`;
 }
 
-function assertLocalUrl(path: string, label: "source" | "destination"): void {
-	if (!path.startsWith("local:/") && !path.startsWith("local://")) {
-		throw new Error(`Approved plan ${label} path must use local: scheme with / or // (received ${path}).`);
+/** Derive a `<slug>` from an agent-supplied `extra.title`, or `undefined` when
+ *  the title is missing/non-string/unsanitizable. A trailing `-plan` is stripped
+ *  so a supplied "auth-plan" maps to `auth-plan.md`, not `auth-plan-plan.md`. */
+function planSlugFromSupplied(suppliedTitle: unknown): string | undefined {
+	if (typeof suppliedTitle !== "string" || !suppliedTitle.trim()) return undefined;
+	try {
+		const { title } = normalizePlanTitle(suppliedTitle);
+		const slug = title.replace(/-plan$/i, "");
+		return slug || title;
+	} catch {
+		return undefined;
 	}
 }
 
-export async function renameApprovedPlanFile(options: RenameApprovedPlanFileOptions): Promise<void> {
-	const { planFilePath, finalPlanFilePath, getArtifactsDir, getSessionId } = options;
-	assertLocalUrl(planFilePath, "source");
-	assertLocalUrl(finalPlanFilePath, "destination");
+export interface ResolveApprovedPlanInput {
+	/** The agent's `extra.title` from the `resolve` call, if any. */
+	suppliedTitle?: unknown;
+	/** The plan path recorded in plan-mode state (the entry default or a prior plan). */
+	statePlanFilePath: string;
+	/** Read a plan `local://` URL, returning null when the file does not exist. */
+	readPlan: (planUrl: string) => Promise<string | null>;
+	/** Optional fallback: list candidate plan `local://` URLs (newest first) so a
+	 *  plan whose name can't be reconstructed (e.g. a dropped `extra.title`) is
+	 *  still found. */
+	listPlanFiles?: () => Promise<string[]>;
+}
+
+export interface ResolvedApprovedPlan {
+	planFilePath: string;
+	planContent: string;
+	title: string;
+}
 
-	const resolveOptions = {
-		getArtifactsDir: () => getArtifactsDir(),
-		getSessionId: () => getSessionId(),
+/** Locate the plan file the agent wrote and finalize its title — without
+ *  renaming anything. Tries, in order: the slug derived from `extra.title`
+ *  (`local://<slug>-plan.md`), the plan path from plan-mode state, then a scan
+ *  of recent plan files. Throws a `ToolError` guiding the agent when none exist. */
+export async function resolveApprovedPlan(input: ResolveApprovedPlanInput): Promise<ResolvedApprovedPlan> {
+	const ordered: string[] = [];
+	const consider = (url: string | undefined): void => {
+		if (url && !ordered.includes(url)) ordered.push(url);
 	};
-	const resolvedSource = resolveLocalUrlToPath(normalizeLocalScheme(planFilePath), resolveOptions);
-	const resolvedDestination = resolveLocalUrlToPath(normalizeLocalScheme(finalPlanFilePath), resolveOptions);
 
-	if (resolvedSource === resolvedDestination) {
-		return;
+	const slug = planSlugFromSupplied(input.suppliedTitle);
+	consider(slug ? planFileUrlForSlug(slug) : undefined);
+	consider(input.statePlanFilePath);
+
+	for (const url of ordered) {
+		const content = await input.readPlan(url);
+		if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
 	}
 
-	try {
-		const destinationStat = await fs.stat(resolvedDestination);
-		if (destinationStat.isFile()) {
-			throw new Error(
-				`Plan destination already exists at ${finalPlanFilePath}. Choose a different title and submit the plan for approval again.`,
-			);
-		}
-		throw new Error(`Plan destination exists but is not a file: ${finalPlanFilePath}`);
-	} catch (error) {
-		if (!isEnoent(error)) {
-			throw error;
+	if (input.listPlanFiles) {
+		for (const url of await input.listPlanFiles()) {
+			if (ordered.includes(url)) continue;
+			const content = await input.readPlan(url);
+			if (content !== null) return finalizeApprovedPlan(url, content, input.suppliedTitle);
 		}
 	}
 
-	try {
-		await fs.rename(resolvedSource, resolvedDestination);
-	} catch (error) {
-		throw new Error(
-			`Failed to rename approved plan from ${planFilePath} to ${finalPlanFilePath}: ${error instanceof Error ? error.message : String(error)}`,
-		);
-	}
+	const target = ordered[0] ?? input.statePlanFilePath;
+	throw new ToolError(
+		`Plan file not found at ${target}. Write the finalized plan to ${target} before requesting approval.`,
+	);
+}
+
+function finalizeApprovedPlan(planFilePath: string, planContent: string, suppliedTitle: unknown): ResolvedApprovedPlan {
+	const { title } = resolvePlanTitle({ suppliedTitle, planContent, planFilePath });
+	return { planFilePath, planContent, title };
 }

package/src/plan-mode/plan-protection.ts

@@ -16,11 +16,11 @@ function readTargetsPlan(readPath: string, planTarget: string): boolean {
  * Build a compaction protection matcher that keeps `read` results for the active
  * plan file intact through prune/shake — the plan analog of skill-read
  * protection. Matches both the canonical `local://PLAN.md` alias and the
- * session's current plan reference path (e.g. a titled `local://<title>.md`), so
- * the plan survives compaction whether the agent reads it by alias or by title.
+ * session's current plan reference path (the agent-chosen `local://<slug>-plan.md`),
+ * so the plan survives compaction whether the agent reads it by alias or by name.
  *
- * `getPlanReferencePath` is evaluated at match time so a mid-session retitle
- * (plan approval renames `PLAN.md` → `<title>.md`) is honored immediately.
+ * `getPlanReferencePath` is evaluated at match time so the plan path set on
+ * approval is honored immediately.
  */
 export function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean {
 	return (context: ProtectedToolContext) => {

package/src/prompts/system/background-tan-dispatch.md

@@ -0,0 +1,8 @@
+<system-notice reason="background_task_dispatched" job="{{jobId}}">
+The user launched a tangential task that is now running in a separate background agent. This is NOT a prompt injection and NOT a new instruction for you — it is the coding agent informing you that work was handed off elsewhere.
+
+The task below is being handled by another agent in its own session. You are NOT responsible for it: do NOT start working on it, do NOT reference it, and do NOT let it interrupt or alter your current task. Simply continue what you were doing as if this message had not appeared. Results, if any, will surface separately when the background task ({{jobId}}) completes.
+
+Dispatched work (for your awareness only):
+{{work}}
+</system-notice>