@oh-my-pi/pi-coding-agent 15.8.2 → 15.9.0

package/src/modes/components/transcript-container.ts

@@ -0,0 +1,91 @@
+import { type Component, Container, TERMINAL } from "@oh-my-pi/pi-tui";
+
+const kSnapshot = Symbol("transcript.frozenRender");
+
+interface FrozenRender {
+	width: number;
+	lines: string[];
+	generation: number;
+}
+
+interface SnapshotCarrier {
+	[kSnapshot]?: FrozenRender;
+}
+
+/**
+ * Transcript container that freezes the rendered output of every block except
+ * the bottom-most (live) one on terminals where committed native scrollback is
+ * immutable.
+ *
+ * On ED3-risk terminals with an unobservable viewport (ghostty/kitty/iTerm2/…)
+ * the renderer cannot clear saved lines (`\x1b[3J` may yank a reader) or query
+ * whether the user has scrolled, so any block that re-lays-out *after* it has
+ * scrolled past the viewport leaves a stale duplicate above the live region
+ * (a finalized assistant message re-wrapping, a tool preview collapsing to its
+ * compact result, a late async tool completion). The renderer's only safe move
+ * for such an offscreen edit is to not repaint — which is correct only if the
+ * committed region never changes underneath it.
+ *
+ * This container provides that guarantee: a block's render is snapshotted while
+ * it is the live (bottom-most) block, and once a newer block is appended it
+ * replays the snapshot instead of recomputing. Mutations after a block leaves
+ * live are intentionally deferred until the next checkpoint {@link thaw} (prompt
+ * submit → native-scrollback rebuild), where the whole transcript is replayed
+ * and any drift reconciles safely. On terminals that can rebuild history this
+ * freezing is unnecessary, so it renders every block live for full fidelity.
+ */
+export class TranscriptContainer extends Container {
+	// Bumped to invalidate every block's snapshot at once; a snapshot is only
+	// honored when its stored generation still matches.
+	#generation = 0;
+
+	override invalidate(): void {
+		// A theme/global invalidation forces a full recompute on the rebuild that
+		// follows; retire every snapshot.
+		this.#generation++;
+		super.invalidate();
+	}
+
+	override clear(): void {
+		this.#generation++;
+		super.clear();
+	}
+
+	/**
+	 * Retire all frozen snapshots so the next render reflects each block's current
+	 * state. Call at reconciliation checkpoints (prompt submit) where the whole
+	 * transcript is replayed into native scrollback and any drift a frozen block
+	 * accumulated is reconciled.
+	 */
+	thaw(): void {
+		this.#generation++;
+	}
+
+	override render(width: number): string[] {
+		width = Math.max(1, width);
+		if (!TERMINAL.eagerEraseScrollbackRisk) return super.render(width);
+
+		const lines: string[] = [];
+		const liveIndex = this.children.length - 1;
+		for (let i = 0; i < this.children.length; i++) {
+			const child = this.children[i]! as Component & SnapshotCarrier;
+			if (i !== liveIndex) {
+				const snapshot = child[kSnapshot];
+				// Replay the block's last render from while it was live. A stale
+				// generation (post-thaw) or width mismatch (resize in flight, an
+				// explicit rebuild that reconciles history anyway) recomputes instead.
+				if (snapshot && snapshot.generation === this.#generation && snapshot.width === width) {
+					lines.push(...snapshot.lines);
+					continue;
+				}
+			}
+			const rendered = child.render(width);
+			// Cache every block's latest render. While a block is live this keeps its
+			// snapshot current; the frame it stops being live the cache already holds
+			// its final live render, so nothing recomputes underneath it.
+			child[kSnapshot] = { width, lines: rendered, generation: this.#generation };
+			lines.push(...rendered);
+		}
+		return lines;
+	}
+}

package/src/modes/controllers/event-controller.ts

@@ -282,6 +282,7 @@ export class EventController {
 				this.ctx.hideThinkingBlock,
 				() => this.ctx.ui.requestRender(),
 				this.ctx.session.extensionRunner?.getAssistantThinkingRenderers(),
+				this.ctx.ui.imageBudget,
 			);
 			this.ctx.streamingMessage = event.message;
 			this.ctx.chatContainer.addChild(this.ctx.streamingComponent);
@@ -586,18 +587,18 @@ export class EventController {
 				this.ctx.ui.requestRender();
 			}
 		}
-		// Update todo display when todo_write tool completes
-		if (event.toolName === "todo_write" && !event.isError) {
+		// Update todo display when todo tool completes
+		if (event.toolName === "todo" && !event.isError) {
 			const details = event.result.details as { phases?: TodoPhase[] } | undefined;
 			if (details?.phases) {
 				this.ctx.setTodos(details.phases);
 			}
-		} else if (event.toolName === "todo_write" && event.isError) {
+		} else if (event.toolName === "todo" && event.isError) {
 			const textContent = event.result.content.find(
 				(content: { type: string; text?: string }) => content.type === "text",
 			)?.text;
 			this.ctx.showWarning(
-				`Todo update failed${textContent ? `: ${textContent}` : ". Progress may be stale until todo_write succeeds."}`,
+				`Todo update failed${textContent ? `: ${textContent}` : ". Progress may be stale until todo succeeds."}`,
 			);
 		}
 		if (event.toolName === "resolve" && !event.isError) {
@@ -847,9 +848,13 @@ export class EventController {
 		const last = this.ctx.session.getLastAssistantMessage?.();
 		if (last?.stopReason === "aborted" || last?.stopReason === "error") return;
 
-		const title = this.ctx.sessionManager.getSessionName();
-		const message = title ? `${title}: Complete` : "Complete";
-		TERMINAL.sendNotification(message);
+		const sessionName = this.ctx.sessionManager.getSessionName();
+		TERMINAL.sendNotification({
+			title: sessionName || "Oh My Pi",
+			body: "Complete",
+			type: "completion",
+			actions: "focus",
+		});
 	}
 
 	async handleBackgroundEvent(event: AgentSessionEvent): Promise<void> {

package/src/modes/controllers/extension-ui-controller.ts

@@ -625,6 +625,9 @@ export class ExtensionUiController {
 				tui: this.ctx.ui,
 				outline: dialogOptions?.outline,
 				disabledIndices: dialogOptions?.disabledIndices,
+				selectionMarker: dialogOptions?.selectionMarker,
+				checkedIndices: dialogOptions?.checkedIndices,
+				markableCount: dialogOptions?.markableCount,
 				maxVisible,
 				slider: extra?.slider,
 			},

package/src/modes/controllers/todo-command-controller.ts

@@ -8,7 +8,7 @@ import {
 	type TodoItem,
 	type TodoPhase,
 	USER_TODO_EDIT_CUSTOM_TYPE,
-} from "../../tools/todo-write";
+} from "../../tools/todo";
 import { copyToClipboard } from "../../utils/clipboard";
 import { getEditorCommand, openInEditor } from "../../utils/external-editor";
 import type { InteractiveModeContext } from "../types";

package/src/modes/interactive-mode.ts

@@ -28,6 +28,8 @@ import {
 	Markdown,
 	ProcessTerminal,
 	Spacer,
+	setTerminalTextSizing,
+	TERMINAL,
 	Text,
 	TUI,
 	visibleWidth,
@@ -84,7 +86,7 @@ import type { LspStartupServerInfo } from "../tools";
 import { normalizeLocalScheme } from "../tools/path-utils";
 import { setAutoQaConsentHandler } from "../tools/report-tool-issue";
 import { type ResolveToolDetails, runResolveInvocation } from "../tools/resolve";
-import { formatPhaseDisplayName, selectStickyTodoWindow, todoMatchesAnyDescription } from "../tools/todo-write";
+import { formatPhaseDisplayName, selectStickyTodoWindow, todoMatchesAnyDescription } from "../tools/todo";
 import { ToolError } from "../tools/tool-errors";
 import type { EventBus } from "../utils/event-bus";
 import { getEditorCommand, openInEditor } from "../utils/external-editor";
@@ -100,6 +102,7 @@ import type { HookInputComponent } from "./components/hook-input";
 import type { HookSelectorComponent, HookSelectorSlider } from "./components/hook-selector";
 import { StatusLineComponent } from "./components/status-line";
 import type { ToolExecutionHandle } from "./components/tool-execution";
+import { TranscriptContainer } from "./components/transcript-container";
 import { WelcomeComponent, type LspServerInfo as WelcomeLspServerInfo } from "./components/welcome";
 import { BtwController } from "./controllers/btw-controller";
 import { CommandController } from "./controllers/command-controller";
@@ -255,7 +258,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	historyStorage?: HistoryStorage;
 
 	ui: TUI;
-	chatContainer: Container;
+	chatContainer: TranscriptContainer;
 	pendingMessagesContainer: Container;
 	statusContainer: Container;
 	todoContainer: Container;
@@ -390,7 +393,12 @@ export class InteractiveMode implements InteractiveModeContext {
 
 		this.ui = new TUI(new ProcessTerminal(), settings.get("showHardwareCursor"));
 		this.ui.setClearOnShrink(settings.get("clearOnShrink"));
-		this.chatContainer = new Container();
+		this.ui.setMaxInlineImages(settings.get("tui.maxInlineImages"));
+		// OSC 66 text-sizing is Kitty-only; resolve the setting against the terminal's
+		// capability (`TERMINAL.textSizing` defaults on for Kitty) so it stays off
+		// unless the user opts in, and never emits raw escapes on other terminals.
+		setTerminalTextSizing(settings.get("tui.textSizing") && TERMINAL.textSizing);
+		this.chatContainer = new TranscriptContainer();
 		this.pendingMessagesContainer = new Container();
 		this.statusContainer = new Container();
 		this.todoContainer = new Container();
@@ -915,6 +923,10 @@ export class InteractiveMode implements InteractiveModeContext {
 			this.#pendingSubmissionDispose = undefined;
 		}
 		this.editor.setText("");
+		// Reconciliation checkpoint: the rebuild below replays the whole transcript
+		// into native scrollback, so retire frozen block snapshots and let every
+		// block render its current state.
+		this.chatContainer.thaw();
 		this.ui.refreshNativeScrollbackIfDirty({ allowUnknownViewport: true });
 		this.ensureLoadingAnimation();
 		this.ui.requestRender();
@@ -1001,7 +1013,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		} else {
 			const accentEnabled = !isSettingsInitialized() || settings.get("statusLine.sessionAccent") !== false;
 			const sessionName = accentEnabled ? this.sessionManager.getSessionName() : undefined;
-			const hex = sessionName ? getSessionAccentHex(sessionName) : undefined;
+			const hex = sessionName ? getSessionAccentHex(sessionName, theme.accentSurfaceLuminance) : undefined;
 			const ansi = getSessionAccentAnsi(hex);
 			if (ansi) {
 				this.editor.borderColor = (str: string) => `${ansi}${str}\x1b[39m`;
@@ -1060,7 +1072,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	 * Auto-complete any pending/in_progress todo whose content matches a
 	 * subagent that has finished successfully. Fires on every observer
 	 * `onChange` so the visual state stays in sync with subagent lifecycle
-	 * without requiring the agent to issue a follow-up `todo_write`. Failed
+	 * without requiring the agent to issue a follow-up `todo`. Failed
 	 * and aborted subagents are intentionally NOT auto-completed — those
 	 * stay open so the user (or the next agent turn) can decide what to do.
 	 *
@@ -2495,7 +2507,7 @@ export class InteractiveMode implements InteractiveModeContext {
 		const accentEnabled = !isSettingsInitialized() || settings.get("statusLine.sessionAccent") !== false;
 		const sessionName = accentEnabled ? this.sessionManager.getSessionName() : undefined;
 		if (!sessionName) return undefined;
-		const hex = getSessionAccentHex(sessionName);
+		const hex = getSessionAccentHex(sessionName, theme.accentSurfaceLuminance);
 		const main = getSessionAccentAnsi(hex);
 		const dim = getSessionAccentAnsi(adjustHsv(hex, { s: 0.55, v: 0.65 }));
 		return main && dim ? { main, dim } : undefined;

package/src/modes/print-mode.ts

@@ -9,6 +9,7 @@ import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
 import { logger, sanitizeText } from "@oh-my-pi/pi-utils";
 import type { AgentSession } from "../session/agent-session";
 import { isSilentAbort } from "../session/messages";
+import { flushTelemetryExport } from "../telemetry-export";
 import { initializeExtensions } from "./runtime-init";
 
 /**
@@ -83,6 +84,10 @@ export async function runPrintMode(session: AgentSession, options: PrintModeOpti
 				!isSilentAbort(assistantMsg.errorMessage)
 			) {
 				const errorLine = sanitizeText(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);
+				// Flush before this hard exit — it bypasses the awaited postmortem.quit()
+				// in main(), and the postmortem `exit` handler can't await, so the error
+				// spans would otherwise stay buffered in the batch processor and drop.
+				await flushTelemetryExport();
 				const flushed = process.stderr.write(`${errorLine}\n`);
 				if (flushed) {
 					process.exit(1);

package/src/modes/rpc/rpc-types.ts

@@ -10,7 +10,7 @@ import type { Effort, ImageContent, Model } from "@oh-my-pi/pi-ai";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ContextUsage } from "../../extensibility/extensions/types";
 import type { SessionStats } from "../../session/agent-session";
-import type { TodoPhase } from "../../tools/todo-write";
+import type { TodoPhase } from "../../tools/todo";
 
 // ============================================================================
 // RPC Commands (stdin)

package/src/modes/theme/theme.ts

@@ -10,7 +10,7 @@ import {
 	supportsLanguage as nativeSupportsLanguage,
 } from "@oh-my-pi/pi-natives";
 import type { EditorTheme, MarkdownTheme, SelectListTheme, SymbolTheme } from "@oh-my-pi/pi-tui";
-import { adjustHsv, getCustomThemesDir, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import { adjustHsv, colorLuma, getCustomThemesDir, isEnoent, logger, relativeLuminance } from "@oh-my-pi/pi-utils";
 import chalk from "chalk";
 import * as z from "zod/v4";
 // Embed theme JSON files at build time
@@ -136,6 +136,9 @@ export type SymbolKey =
 	// Checkboxes
 	| "checkbox.checked"
 	| "checkbox.unchecked"
+	// Radio (single-choice)
+	| "radio.selected"
+	| "radio.unselected"
 	// Text Formatting
 	| "format.bullet"
 	| "format.dash"
@@ -302,6 +305,9 @@ const UNICODE_SYMBOLS: SymbolMap = {
 	// Checkboxes
 	"checkbox.checked": "☑",
 	"checkbox.unchecked": "☐",
+	// Radio (single-choice)
+	"radio.selected": "◉",
+	"radio.unselected": "○",
 	// Formatting
 	"format.bullet": "•",
 	"format.dash": "—",
@@ -559,6 +565,11 @@ const NERD_SYMBOLS: SymbolMap = {
 	"checkbox.checked": "\uf14a",
 	// pick:  | alt: 
 	"checkbox.unchecked": "\uf096",
+	// Radio (single-choice)
+	// pick:  (fa-dot-circle-o) | alt:  ◉
+	"radio.selected": "\uf192",
+	// pick:  (fa-circle-o) | alt:  ○
+	"radio.unselected": "\uf10c",
 	// pick:  | alt:   •
 	"format.bullet": "\uf111",
 	// pick: – | alt: — ― -
@@ -731,6 +742,8 @@ const ASCII_SYMBOLS: SymbolMap = {
 	// Checkboxes
 	"checkbox.checked": "[x]",
 	"checkbox.unchecked": "[ ]",
+	"radio.selected": "(o)",
+	"radio.unselected": "( )",
 	"format.bullet": "*",
 	"format.dash": "-",
 	"format.bracketLeft": "[",
@@ -1277,6 +1290,16 @@ export class Theme {
 	#bgColors: Record<ThemeBg, string>;
 	#symbols: SymbolMap;
 	#spinnerFramesOverrides: Partial<Record<SpinnerType, string[]>>;
+	/**
+	 * Perceptual luma (0..1) of the status-line background — used to classify the
+	 * theme light/dark. Undefined when it can't be resolved. Classified against the
+	 * status line (the surface session accents render on) rather than the chat bubble
+	 * (`userMessageBg`), which some themes (e.g. `porcelain`) style dark on an
+	 * otherwise-light theme.
+	 */
+	readonly statusLineLuminance: number | undefined;
+	/** WCAG relative luminance of the status-line background — basis for accent contrast. */
+	readonly #statusLineContrastLuminance: number | undefined;
 
 	constructor(
 		fgColors: Record<ThemeColor, string | number>,
@@ -1286,6 +1309,8 @@ export class Theme {
 		symbolOverrides: Partial<Record<SymbolKey, string>>,
 		spinnerFramesOverrides: Partial<Record<SpinnerType, string[]>> = {},
 	) {
+		this.statusLineLuminance = colorLuma(bgColors.statusLineBg);
+		this.#statusLineContrastLuminance = relativeLuminance(bgColors.statusLineBg);
 		this.#fgColors = {} as Record<ThemeColor, string>;
 		for (const [key, value] of Object.entries(fgColors) as [ThemeColor, string | number][]) {
 			this.#fgColors[key] = fgAnsi(value, mode);
@@ -1307,6 +1332,19 @@ export class Theme {
 		this.#spinnerFramesOverrides = spinnerFramesOverrides;
 	}
 
+	/** True when the active theme has a light status-line background. */
+	get isLight(): boolean {
+		return this.statusLineLuminance !== undefined && this.statusLineLuminance > 0.5;
+	}
+
+	/**
+	 * Surface luminance to size session accents against on light themes; undefined on
+	 * dark themes so accents stay vivid. Pass straight to `getSessionAccentHex`.
+	 */
+	get accentSurfaceLuminance(): number | undefined {
+		return this.isLight ? this.#statusLineContrastLuminance : undefined;
+	}
+
 	fg(color: ThemeColor, text: string): string {
 		const ansi = this.#fgColors[color];
 		if (!ansi) throw new Error(`Unknown theme color: ${color}`);
@@ -1570,6 +1608,13 @@ export class Theme {
 		};
 	}
 
+	get radio() {
+		return {
+			selected: this.#symbols["radio.selected"],
+			unselected: this.#symbols["radio.unselected"],
+		};
+	}
+
 	get format() {
 		return {
 			bullet: this.#symbols["format.bullet"],
@@ -2312,13 +2357,8 @@ export function isLightTheme(themeName?: string): boolean {
 	}
 	try {
 		const resolved = resolveVarRefs(themeJson.colors.userMessageBg, themeJson.vars ?? {});
-		if (typeof resolved !== "string" || !resolved.startsWith("#") || resolved.length !== 7) return false;
-		const r = parseInt(resolved.slice(1, 3), 16) / 255;
-		const g = parseInt(resolved.slice(3, 5), 16) / 255;
-		const b = parseInt(resolved.slice(5, 7), 16) / 255;
-		// Relative luminance (ITU-R BT.709)
-		const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
-		return luminance > 0.5;
+		const luminance = colorLuma(resolved);
+		return luminance !== undefined && luminance > 0.5;
 	} catch {
 		return false;
 	}

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

@@ -267,6 +267,7 @@ export class UiHelpers {
 					this.ctx.hideThinkingBlock,
 					() => this.ctx.ui.requestRender(),
 					this.ctx.session.extensionRunner?.getAssistantThinkingRenderers(),
+					this.ctx.ui.imageBudget,
 				);
 				this.ctx.chatContainer.addChild(assistantComponent);
 				break;

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

@@ -0,0 +1,37 @@
+import { isEnoent } from "@oh-my-pi/pi-utils";
+import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
+
+/** The session's active plan, resolved for handoff into a subagent's context. */
+export interface OverallPlanReference {
+	/** The `local://` reference path (e.g. `local://my-feature.md`), kept for display. */
+	path: string;
+	/** The full plan markdown, as written to disk. */
+	content: string;
+}
+
+/**
+ * Load the session's active overall plan for subagent handoff.
+ *
+ * Returns the plan referenced by `planReferencePath` when it exists on disk with
+ * non-empty content, or `undefined` when there is no plan (the file is absent or
+ * empty). This mirrors `AgentSession.#buildPlanReferenceMessage`'s gating so a
+ * subagent sees exactly the plan the main agent treats as its active reference.
+ *
+ * Callers MUST skip this during plan mode itself — read-only plan exploration
+ * uses a different prompt and a draft plan should not be handed off as approved.
+ */
+export async function loadOverallPlanReference(
+	planReferencePath: string,
+	localProtocolOptions: LocalProtocolOptions,
+): Promise<OverallPlanReference | undefined> {
+	const resolved = resolveLocalUrlToPath(planReferencePath, localProtocolOptions);
+	let content: string;
+	try {
+		content = await Bun.file(resolved).text();
+	} catch (error) {
+		if (isEnoent(error)) return undefined;
+		throw error;
+	}
+	if (!content.trim()) return undefined;
+	return { path: planReferencePath, content };
+}

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

@@ -0,0 +1,31 @@
+import { getReadToolPath, type ProtectedToolContext } from "@oh-my-pi/pi-agent-core/compaction/tool-protection";
+import { normalizeLocalScheme } from "../tools/path-utils";
+
+/** Canonical plan alias every session's `local://` root resolves. */
+const LOCAL_PLAN_ALIAS = "local://PLAN.md";
+
+/** True when `readPath` targets `planTarget`, ignoring `local:/` vs `local://`
+ *  scheme spelling and any trailing read selector (`:1-50`, `:raw`, …). */
+function readTargetsPlan(readPath: string, planTarget: string): boolean {
+	const read = normalizeLocalScheme(readPath);
+	const target = normalizeLocalScheme(planTarget);
+	return read === target || read.startsWith(`${target}:`);
+}
+
+/**
+ * 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.
+ *
+ * `getPlanReferencePath` is evaluated at match time so a mid-session retitle
+ * (plan approval renames `PLAN.md` → `<title>.md`) is honored immediately.
+ */
+export function createPlanReadMatcher(getPlanReferencePath: () => string): (context: ProtectedToolContext) => boolean {
+	return (context: ProtectedToolContext) => {
+		const path = getReadToolPath(context);
+		if (path === undefined) return false;
+		return readTargetsPlan(path, LOCAL_PLAN_ALIAS) || readTargetsPlan(path, getPlanReferencePath());
+	};
+}

package/src/priority.json

@@ -18,6 +18,10 @@
 		"gpt-5.1-codex",
 		"gpt-5.1",
 		"codex",
+		"opus-4.8",
+		"opus-4-8",
+		"opus-4.7",
+		"opus-4-7",
 		"opus-4.6",
 		"opus-4-6",
 		"opus-4.5",

package/src/prompts/goals/goal-continuation.md

@@ -16,7 +16,7 @@ This is an autonomous continuation. The objective persists across turns; do not
 
 Before calling `goal({op:"complete"})`, you MUST perform a completion audit against the current repo state:
 
-1. **Restate the objective as concrete deliverables.** What files, behaviors, tests, gates, or artifacts must exist for the objective to be true? Write them down (todo_write, or in your reasoning).
+1. **Restate the objective as concrete deliverables.** What files, behaviors, tests, gates, or artifacts must exist for the objective to be true? Write them down (todo, or in your reasoning).
 2. **Map each deliverable to evidence.** For every requirement, identify the authoritative source that would prove it: a file's contents, a command's output, a test's pass status, a PR/issue state.
 3. **Inspect the actual current state.** Read the files. Run the commands. Check the tests. Do not rely on memory of earlier work in this session — the repo may have changed.
 4. **Match verification scope to claim scope.** A narrow check (one file passes its unit test) does not prove a broad claim (the feature works end-to-end).

package/src/prompts/system/eager-todo.md

@@ -1,13 +1,13 @@
 <system-reminder>
 Before substantive work, create a phased todo.
 
-You MUST call `todo_write` first in this turn.
+You MUST call `todo` first in this turn.
 You MUST initialize the todo list with a single `init` op.
 You MUST cover the entire request from investigation through implementation and verification — not just the next immediate step.
 Task descriptions MUST be specific. A future turn MUST execute them without re-planning.
 You MUST keep task `content` to a short label (5-10 words). Put file paths, implementation steps, and specifics in `details`.
 You MUST keep exactly one task `in_progress` and all later tasks `pending`.
 
-After `todo_write` succeeds, continue the request in the same turn.
-Do not call `todo_write` again unless task state materially changed.
+After `todo` succeeds, continue the request in the same turn.
+Do not call `todo` again unless task state materially changed.
 </system-reminder>

package/src/prompts/system/orchestrate-notice.md

@@ -2,12 +2,12 @@
 The user's message above is an **orchestration request**. Execute it as the orchestrator under the contract below. This contract overrides any default tendency to yield early, narrate, or do the work yourself.
 
 <role>
-You decompose, dispatch, verify, and iterate. Substantial and parallelizable work goes through `task` subagents — that is the whole point of orchestrating. But you are not forbidden from touching the tree: a trivial, self-contained edit is yours to make directly when spawning a subagent for it would cost more than the edit itself. Your tool budget is: reading for planning, `task` for dispatch, `edit`/`write` for trivial inline fixes only, verification (`bun check`, `bun test`, `lsp diagnostics`), git via `bash`, and `todo_write` for tracking.
+You decompose, dispatch, verify, and iterate. Substantial and parallelizable work goes through `task` subagents — that is the whole point of orchestrating. But you are not forbidden from touching the tree: a trivial, self-contained edit is yours to make directly when spawning a subagent for it would cost more than the edit itself. Your tool budget is: reading for planning, `task` for dispatch, `edit`/`write` for trivial inline fixes only, verification (`bun check`, `bun test`, `lsp diagnostics`), git via `bash`, and `todo` for tracking.
 </role>
 
 <rules>
 1. **Do not yield until everything is closed.** A phase finishing is *not* a yield point — launch the next phase in the same turn. Stop only when every requested item is verifiably done, or you hit a concrete [blocked] state that genuinely requires the user.
-2. **Enumerate the full surface before dispatching.** If the request references audits, plans, checklists, phase lists, or file lists, expand them into a flat set of items in `todo_write`. "Most of them" or "the important ones" is failure. Re-read the source documents — do not work from memory.
+2. **Enumerate the full surface before dispatching.** If the request references audits, plans, checklists, phase lists, or file lists, expand them into a flat set of items in `todo`. "Most of them" or "the important ones" is failure. Re-read the source documents — do not work from memory.
 3. **Parallelize maximally; never launch a one-off task.** Every set of edits with disjoint file scope MUST ship as one `task` batch — fan the work as wide as it decomposes. A single-task batch for divisible work is a failure: split it. If you are about to dispatch exactly one subagent, stop — either there is more to run alongside it (find it and batch them) or the change is small enough to make inline yourself (do it). Serialize only when one subagent produces a contract (types, schema, shared module) the next consumes — and state the dependency when you do.
 4. **Each `task` assignment is self-contained.** Subagents have no shared context. Spell out: target files (≤3–5 explicit paths, no globs), the change with APIs and patterns, edge cases, and observable acceptance criteria. Do not assume they read the same plan you did.
 5. **Verify after every phase before launching the next.** Run the appropriate gate: `bun check` for types, package-scoped `bun test` for behavior, `lsp diagnostics` for changed files. If a phase introduced breakage, dispatch fix-up subagents *before* moving on. Never declare a phase done on a red tree.
@@ -20,12 +20,12 @@ You decompose, dispatch, verify, and iterate. Substantial and parallelizable wor
 
 <workflow>
 1. **Ingest.** Read every referenced file (audits, plans, prior agent output, current branch state). Run `git status` to see uncommitted changes.
-2. **Plan.** Materialize the full work surface in `todo_write` as ordered phases. Within each phase, list the parallelizable units.
+2. **Plan.** Materialize the full work surface in `todo` as ordered phases. Within each phase, list the parallelizable units.
 3. **Dispatch phase.** Launch all parallel `task` subagents in one call. Wait for the batch.
 4. **Verify phase.** Run the gates. On failure, dispatch fix-up subagents and re-verify. Do not advance with a red gate.
 5. **Commit phase** (if applicable). Focused message naming the phase.
-6. **Advance.** Mark the phase done in `todo_write`, immediately start the next phase. No summary message between phases — keep going.
-7. **Final verification.** When the last phase is green, run the full gate set once more and confirm every `todo_write` item is closed. Then yield with a terse status, not a recap.
+6. **Advance.** Mark the phase done in `todo`, immediately start the next phase. No summary message between phases — keep going.
+7. **Final verification.** When the last phase is green, run the full gate set once more and confirm every `todo` item is closed. Then yield with a terse status, not a recap.
 </workflow>
 
 <anti-patterns>

package/src/prompts/system/plan-mode-approved.md

@@ -1,28 +1,25 @@
-<critical>
-Plan approved. You MUST execute it now.
-</critical>
-
-Finalized plan artifact: `{{finalPlanFilePath}}`
+Plan approved.
 {{#if contextPreserved}}
-Context preserved. Use conversation history when useful; the finalized plan is the source of truth if it conflicts with earlier exploration.
-{{else}}
-Execution may be in fresh context. Treat the finalized plan as the source of truth.
+- Context preserved. Use conversation history when useful; this plan is the source of truth if it conflicts with earlier exploration.
 {{/if}}
 
-## Plan
-
-{{planContent}}
-
 <instruction>
-You MUST execute this plan step by step from `{{finalPlanFilePath}}`. You have full tool access.
+You MUST execute this plan step by step. You have full tool access.
 You MUST verify each step before proceeding to the next.
-{{#has tools "todo_write"}}
-Before execution, initialize todo tracking with `todo_write`.
-After each completed step, immediately update `todo_write`.
-If `todo_write` fails, fix the payload and retry before continuing.
+{{#has tools "todo"}}
+Before execution, initialize todo tracking with `todo`.
+After each completed step, immediately update `todo`.
+If `todo` fails, fix the payload and retry before continuing.
 {{/has}}
+The plan path is for subagent handoff only. You already have the plan; NEVER read it.
 </instruction>
 
+The full plan is injected below. You MUST execute it now:
+
+<plan path="{{finalPlanFilePath}}">
+{{planContent}}
+</plan>
+
 <critical>
 You MUST keep going until complete. This matters.
 </critical>

package/src/prompts/system/plan-mode-reference.md

@@ -1,14 +1,11 @@
 ## Existing Plan
 
-Plan file from previous session: `{{planFilePath}}`
-
-<details>
-<summary>Plan contents</summary>
-
+<plan path="{{planFilePath}}">
 {{planContent}}
-</details>
+</plan>
 
 <instruction>
 If this plan is relevant to current work and not complete, you MUST continue executing it.
 If the plan is stale or unrelated, you MUST ignore it.
+The plan path is for subagent handoff only. You already have the plan; NEVER read it.
 </instruction>

package/src/prompts/system/subagent-system-prompt.md

@@ -10,6 +10,17 @@ CONTEXT
 {{context}}
 {{/if}}
 
+{{#if planReference}}
+PLAN
+===================================
+
+This session is executing an approved plan. Your assignment above is one part of it — use the plan to understand how your piece fits the whole and to stay consistent with decisions already made. Where the plan and your specific assignment conflict, the assignment wins. The plan path is for reference; you already have its full contents below, so NEVER re-read it.
+
+<plan path="{{planReferencePath}}">
+{{planReference}}
+</plan>
+{{/if}}
+
 COOP
 ===================================
 

package/src/prompts/system/workflow-notice.md

@@ -62,7 +62,7 @@ Scale to the ask: "find any bugs" → a few finders, single-vote verify. "thorou
 </patterns>
 
 <execution>
-- Decompose the surface first; capture it in `todo_write` when it spans phases.
+- Decompose the surface first; capture it in `todo` when it spans phases.
 - Prefer `schema=` for any agent whose output you branch on.
 - After a fan-out returns, YOU own correctness: read the artifacts, run the gate, verify before acting. Subagents do the legwork; they don't get the last word.
 - Keep going until the task is closed — a returned fan-out is a step, not a stopping point.