pi-task-dispatcher 3.0.2 → 3.1.0

package/README.md

@@ -10,7 +10,7 @@ Each delegation runs in an isolated, in-memory Pi RPC session. After every cohes
 - **Enforced supervision:** a private parent-child IPC gate calls `ctx.abort()` after persisted tool results; pausing does not depend on the worker following a prompt.
 - **Explicit control:** continue, revise, recalculate, compact, checkpoint, cancel, or take over.
 - **Resumable context:** continuation uses the same in-memory worker session and completed tool results.
-- **Least privilege:** every start selects an exact isolated-worker tool allowlist; delegation tools and unrelated discovered extensions are unavailable to the worker. Pi's built-in `codemode` extension loads only when explicitly selected.
+- **Least privilege:** every start selects an exact isolated-worker tool allowlist; delegation tools and unrelated discovered extensions are unavailable to the worker. When explicitly selected, a runtime-temporary extension loads Pi's public native `codemode` factory in `only` mode; it is never injected otherwise.
 - **Model agnostic:** every role inherits Pi's active model and thinking level unless an explicit role override is configured.
 - **Formula-owned budgets:** the manager supplies semantic workload units, while the dispatcher calculates turn and time ceilings from workload, role, and delegated-model limits.
 - **Context insight:** boundary reports include worker context usage, compactions, turns, elapsed time, action counts, and recommendations.
@@ -19,11 +19,11 @@ Each delegation runs in an isolated, in-memory Pi RPC session. After every cohes
 
 ## Requirements
 
-- Pi 1.0.4 or later
+- Pi 1.1.0 or later
 - Node.js 22.19.0 or later
 - One active, authenticated Pi model; optional role-specific models must also be available and authenticated
 
-The supervision gate requires the parent Pi process and child Pi CLI to run under Node.js with an inherited IPC channel. The dispatcher fails closed when that boundary cannot be established; it does not fall back to prompt-only supervision. Worker processes disable ordinary extension discovery and load the generated supervision gate plus Pi's built-in `codemode` extension only when that tool was explicitly selected.
+The supervision gate requires the parent Pi process and child Pi CLI to run under Node.js with an inherited IPC channel. The dispatcher fails closed when that boundary cannot be established; it does not fall back to prompt-only supervision. Worker processes disable ordinary extension discovery and load the generated supervision gate plus a generated native codemode-only extension only when that tool was explicitly selected.
 
 ## Installation
 
@@ -89,7 +89,7 @@ A workload unit is intentionally semantic:
 
 At least one investigation, change, or verification unit is required.
 
-Isolated workers accept `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`, and `codemode` when the selected tools are also active in the main Pi session. `codemode` is loaded as an explicit Pi built-in while ordinary extension discovery remains disabled. Its scripts can call only the worker's callable tools and non-LLM model catalog; unrelated manager extensions and delegation tools remain unavailable.
+Isolated workers accept `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, `ls`, and `codemode` when the selected tools are also active in the main Pi session. If `codemode` is selected, the child generates a temporary extension using Pi's public `createCodemodeExtension({ mode: "only" })` API while ordinary extension discovery remains disabled. This makes `codemode` model-visible without exposing selected direct tools to the worker model; its scripts can still call those selected callable tools and the non-LLM model catalog. Unrelated manager extensions and delegation tools remain unavailable.
 
 The current formula derives planned work turns from those units, applies a role factor and a bounded scale based on the selected delegated model's own context window, reserves two additional turns for synthesis or recovery, then derives active execution time from calculated turns plus expected long-running time. Administrative ceilings always win. Formula inputs and results are returned in every state report so they can be reviewed and recalculated. Time spent paused for manager deliberation does not consume the active execution budget.
 
@@ -146,9 +146,10 @@ A paused result contains:
 - active elapsed time and turns against calculated budgets;
 - context tokens, context window, percentage, and compaction counts;
 - a recommended next decision;
-- bounded worker text, if any.
+- bounded model-facing worker text, if any;
+- a complete sanitized live presentation ledger in structured result details, including streamed assistant text and child-tool lifecycle/output placeholders without image base64.
 
-The TUI renders the same structured state as a compact block. Expanding the tool result reveals bounded worker text. The complete action ledger and worker text remain in result details for state reconstruction rather than being discarded by display truncation.
+The TUI renders the same structured state as a compact block plus the latest five visual rows of the presentation ledger. When older rows are omitted, Pi's native tool-expansion key hint appears; expanding the tool result reveals the complete captured presentation text, not the 5,000-character model-facing worker-text preview. The complete action ledger, presentation ledger, and worker text remain in result details for state reconstruction rather than being discarded by display truncation.
 
 After the first worker state, one unindented, dim footer status remains below Pi's primary report and updates across worker lifecycle states. It retains the newest state observed for every invoked role, with the most recently updated role first and each entry ordered as identity, context, model, and thinking—for example, `engineer-2 · 10.3%/32k • model-name • medium | mechanic-1 · 8.1%/128k • smaller-model • low`. Each percentage and window comes from that delegation's own fresh worker session; a continuation accumulates context in the same job, while a new delegation starts a new context. Current or latest action details appear in the delegation or manager block rather than the footer.
 
@@ -208,7 +209,7 @@ Version 3 intentionally ignores the version 2 fields `maxTurns`, `timeoutSeconds
 - Session shutdown or extension reload disposes the child and runtime-controlled temporary files.
 - Worker process failures reject pending RPC operations and produce a failed state.
 - Worker role instructions and the supervision gate exist only in a runtime-controlled temporary directory.
-- The selected built-in `codemode` extension may create runtime-temporary image outputs; the designer must persist requested outputs explicitly before completion.
+- The selected native codemode-only extension may create runtime-temporary image outputs; the designer must persist requested outputs explicitly before completion.
 - The worker uses `--no-session`; no worker session file is persisted.
 
 Process separation is not a security sandbox. Worker tools execute with the Pi host's operating-system permissions. Tool availability does not establish task scope or authorization.
@@ -220,7 +221,7 @@ npm run check
 npm run test:gate
 ```
 
-`check` runs static release invariants and deterministic fake-RPC lifecycle and renderer scenarios. The fake child verifies all role registrations, pause/resume, output-limit recovery, usage deltas, nested codemode usage accounting, media metadata without base64 retention, persistent per-role footer state, full action-ledger retention, intercepted prompts, missing-boundary failure, fail-closed timeouts, pre-aborted operations, partial argument rendering, stable repeated rendering, and manager-state transitions without a model request.
+`check` runs static release invariants and deterministic fake-RPC lifecycle and renderer scenarios. The fake child verifies all role registrations, pause/resume, output-limit recovery, usage deltas, native codemode-only loading and nested direct-tool usage accounting, media metadata without base64 retention, streaming assistant/tool replacement semantics, five-visual-row previews with native expansion hints, complete expanded presentation beyond the 5,000-character model preview, persistent per-role footer state, full action-ledger retention, intercepted prompts, missing-boundary failure, fail-closed timeouts, pre-aborted operations, partial argument rendering, stable repeated rendering, and manager-state transitions without a model request.
 
-`test:gate` performs a small live model integration check with the active parent model exported by Pi through `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`, falling back to Pi's configured default when those values are unavailable; it contains no provider or model assumption. Optional `PI_TASK_DISPATCHER_GATE_MODEL` and `PI_TASK_DISPATCHER_GATE_THINKING` overrides are available for explicit test matrices. The probe verifies selective built-in `codemode` loading, a private pause after its completed tool batch, and subsequent completion in the same in-memory child. It requires configured credentials and therefore is not a hermetic unit test.
+`test:gate` performs a small live model integration check with the active parent model exported by Pi through `PI_PROVIDER`, `PI_MODEL`, and `PI_REASONING_LEVEL`, falling back to Pi's configured default when those values are unavailable; it contains no provider or model assumption. Optional `PI_TASK_DISPATCHER_GATE_MODEL` and `PI_TASK_DISPATCHER_GATE_THINKING` overrides are available for explicit test matrices. The probe verifies generated native codemode-only loading, a codemode script calling an explicitly selected direct `read` tool, a private pause after that completed batch, and subsequent completion in the same in-memory child. It requires configured credentials and therefore is not a hermetic unit test.
 

package/extensions/task-dispatcher.ts

@@ -10,8 +10,10 @@ import {
 	type ExtensionAPI,
 	type ExtensionToolContext,
 	getAgentDir,
+	keyHint,
+	truncateToVisualLines,
 } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import { stripTerminalSequences, Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 type Role = "mechanic" | "assistant" | "engineer" | "designer";
@@ -99,6 +101,17 @@ interface WorkerAction {
 	mediaOutputs?: WorkerMediaOutput[];
 }
 
+/** Keep one replaceable presentation record for each assistant response or child tool lifecycle. */
+interface WorkerPresentationEntry {
+	sequence: number;
+	id: string;
+	kind: "assistant" | "tool";
+	label: string;
+	status: "streaming" | "running" | "completed" | "failed";
+	text: string;
+	parentToolCallId?: string;
+}
+
 interface ContextMetrics {
 	tokens?: number;
 	contextWindow: number;
@@ -135,6 +148,8 @@ interface WorkerSnapshot {
 	recentActions: WorkerAction[];
 	actionLedger: WorkerAction[];
 	workerText: string;
+	/** Complete sanitized delegate activity retained only in structured tool details for UI expansion. */
+	presentationText: string;
 	workerTextDisplay: string;
 	workerTextTruncated: boolean;
 	diagnostic?: string;
@@ -142,6 +157,21 @@ interface WorkerSnapshot {
 	usage: UsageTotals;
 }
 
+/** Retain only RPC content fields needed for text presentation and image metadata extraction. */
+interface RpcContent {
+	type?: string;
+	text?: string;
+	data?: string;
+	mimeType?: string;
+}
+
+/** Model the result fields shared by partial and authoritative tool RPC events. */
+interface RpcToolResult {
+	content?: RpcContent[];
+	usage?: EventUsage;
+	estimatedTokensAfter?: number;
+}
+
 interface ParsedEvent {
 	id?: string;
 	type?: string;
@@ -154,14 +184,11 @@ interface ParsedEvent {
 	aborted?: boolean;
 	errorMessage?: string;
 	willRetry?: boolean;
-	result?: {
-		content?: Array<{ type?: string; text?: string; data?: string; mimeType?: string }>;
-		usage?: EventUsage;
-		estimatedTokensAfter?: number;
-	};
+	result?: RpcToolResult;
+	partialResult?: RpcToolResult;
 	message?: {
 		role?: string;
-		content?: Array<{ type?: string; text?: string }>;
+		content?: RpcContent[];
 		usage?: EventUsage;
 		stopReason?: string;
 		errorMessage?: string;
@@ -178,6 +205,7 @@ interface ParsedEvent {
 	parentToolCallId?: string;
 	args?: unknown;
 	isError?: boolean;
+	durationMs?: number;
 }
 
 interface GateBoundaryMessage {
@@ -195,6 +223,8 @@ const CONFIG_PATH = TEST_MODE && process.env.PI_TASK_DISPATCHER_CONFIG_PATH
 const WORKER_ENV = "PI_TASK_DISPATCHER_WORKER";
 const WIDGET_ID = "pi-task-dispatcher-worker";
 const MODEL_TEXT_LIMIT = 5_000;
+const PRESENTATION_PREVIEW_ROWS = 5;
+const PRESENTATION_UPDATE_THROTTLE_MS = 100;
 const STDERR_LIMIT = 16_000;
 const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh", "max"]);
 const ROLES: Role[] = ["mechanic", "assistant", "engineer", "designer"];
@@ -345,10 +375,17 @@ function headTail(text: string, limit = MODEL_TEXT_LIMIT): { text: string; trunc
 	};
 }
 
+/** Remove terminal controls from child-provided text before it enters a structured snapshot or renderer. */
+function sanitizePresentationText(value: unknown): string {
+	if (typeof value !== "string") return "";
+	return stripTerminalSequences(value)
+		.replace(/\r\n?/g, "\n")
+		.replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "");
+}
+
 /** Keep one-line task and activity clues compact without introducing multiline omission markers. */
 function compactLine(value: unknown, limit = 180): string {
-	if (typeof value !== "string") return "Preparing delegation…";
-	const normalized = value.replaceAll(/\s+/g, " ").trim();
+	const normalized = sanitizePresentationText(value).replaceAll(/\s+/g, " ").trim();
 	if (!normalized) return "Preparing delegation…";
 	return normalized.length <= limit ? normalized : `${normalized.slice(0, Math.max(1, limit - 1))}…`;
 }
@@ -449,21 +486,53 @@ function getDirectPiInvocation(args: string[]): { command: string; args: string[
 /** Render a bounded activity label without embedding bulky command content. */
 function formatActivity(name: string, args: unknown): string {
 	if (name === "bash" && isRecord(args) && typeof args.command === "string") {
-		return `$ ${headTail(args.command, 140).text.replaceAll("\n", " ")}`;
+		return `$ ${headTail(sanitizePresentationText(args.command), 140).text.replaceAll("\n", " ")}`;
 	}
-	if (isRecord(args) && typeof args.path === "string") return `${name} ${args.path}`;
-	return name;
+	if (isRecord(args) && typeof args.path === "string") return `${name} ${sanitizePresentationText(args.path)}`;
+	return sanitizePresentationText(name) || "tool";
 }
 
 /** Extract a text-only assistant report from one finalized RPC message. */
 function assistantText(event: ParsedEvent): string {
 	return (event.message?.content ?? [])
-		.filter((part) => part.type === "text" && part.text)
-		.map((part) => part.text as string)
+		.filter((part) => part.type === "text" && typeof part.text === "string")
+		.map((part) => sanitizePresentationText(part.text))
+		.filter(Boolean)
 		.join("\n")
 		.trim();
 }
 
+/** Extract text and image placeholders without retaining image base64 in state or rendered output. */
+function presentationResult(result: RpcToolResult | undefined): { text: string; mediaOutputs: WorkerMediaOutput[] } {
+	const text: string[] = [];
+	const mediaOutputs: WorkerMediaOutput[] = [];
+	// Inspect content block types without persisting image payloads or redundant partial snapshots.
+	for (const part of result?.content ?? []) {
+		if (part.type === "text" && typeof part.text === "string") {
+			const value = sanitizePresentationText(part.text);
+			if (value) text.push(value);
+			continue;
+		}
+		if (part.type !== "image") continue;
+		const mimeType = sanitizePresentationText(part.mimeType) || "image";
+		const bytes = typeof part.data === "string" ? Buffer.from(part.data, "base64").length : 0;
+		if (typeof part.data === "string") mediaOutputs.push({ mimeType, bytes });
+		text.push(bytes > 0 ? `[image ${mimeType} · ${bytes} bytes]` : `[image ${mimeType}]`);
+	}
+	return { text: text.join("\n"), mediaOutputs };
+}
+
+/** Build the native codemode extension in only mode so selected direct tools stay script-callable but model-hidden. */
+function codemodeOnlySource(): string {
+	return `/** Load Pi's public codemode factory without loading discovered extensions. */
+import { createCodemodeExtension, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+const codemodeOnly = createCodemodeExtension({ mode: "only" });
+export default function codemodeOnlyExtension(pi: ExtensionAPI): void {
+	codemodeOnly(pi);
+}
+`;
+}
+
 /** Build the worker-only gate extension that stops the agent loop after persisted tool results. */
 function gateSource(): string {
 	return `/** Pause this worker after each persisted tool batch so only the parent dispatcher can resume it. */
@@ -520,6 +589,11 @@ class WorkerJob {
 	private requestSequence = 0;
 	private actionSequence = 0;
 	private completionSequence = 0;
+	private presentationSequence = 0;
+	private readonly presentationEntries: WorkerPresentationEntry[] = [];
+	private readonly presentationById = new Map<string, WorkerPresentationEntry>();
+	private readonly assistantTextBlocks = new Map<number, string>();
+	private activeAssistantPresentation: WorkerPresentationEntry | undefined;
 	private activeActions = new Map<string, WorkerAction>();
 	private pendingRequests = new Map<string, { resolve: (event: ParsedEvent) => void; reject: (error: Error) => void }>();
 	private settleWaiter: { resolve: () => void; reject: (error: Error) => void } | undefined;
@@ -530,6 +604,7 @@ class WorkerJob {
 	private activeElapsedMs = 0;
 	private activeStartedAt: number | undefined;
 	private progressCallback: ((snapshot: WorkerSnapshot) => void) | undefined;
+	private progressUpdate: ReturnType<typeof setTimeout> | undefined;
 	private pausedLease: ReturnType<typeof setTimeout> | undefined;
 	private closePromise: Promise<void> | undefined;
 
@@ -566,8 +641,12 @@ class WorkerJob {
 		this.temporaryDirectory = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-task-dispatcher-"));
 		const rolePromptPath = path.join(this.temporaryDirectory, `${this.role}.md`);
 		const gatePath = path.join(this.temporaryDirectory, "supervision-gate.ts");
+		const codemodeOnlyPath = path.join(this.temporaryDirectory, "codemode-only.ts");
 		await fs.promises.writeFile(rolePromptPath, ROLE_PROMPTS[this.role], { encoding: "utf8", mode: 0o600 });
 		await fs.promises.writeFile(gatePath, gateSource(), { encoding: "utf8", mode: 0o600 });
+		if (this.tools.includes("codemode")) {
+			await fs.promises.writeFile(codemodeOnlyPath, codemodeOnlySource(), { encoding: "utf8", mode: 0o600 });
+		}
 
 		const args = [
 			"--mode", "rpc",
@@ -577,7 +656,7 @@ class WorkerJob {
 			"--thinking", this.thinking,
 			...(this.tools.length > 0 ? ["--tools", this.tools.join(",")] : ["--no-tools"]),
 			"--append-system-prompt", rolePromptPath,
-			...(this.tools.includes("codemode") ? ["--extension", "builtin:codemode"] : []),
+			...(this.tools.includes("codemode") ? ["--extension", codemodeOnlyPath] : []),
 			"--extension", gatePath,
 		];
 		const invocation = getDirectPiInvocation(args);
@@ -681,6 +760,7 @@ class WorkerJob {
 	/** Return a stable state projection without exposing process handles or raw RPC records. */
 	snapshot(): WorkerSnapshot {
 		const display = headTail(this.workerText);
+		const presentationText = this.presentationText();
 		const completed = this.actions.filter((action) => action.status === "completed").length;
 		const failed = this.actions.filter((action) => action.status === "failed").length;
 		const currentAction = [...this.actions].reverse().find((action) => action.status === "running");
@@ -714,6 +794,7 @@ class WorkerJob {
 			recentActions,
 			actionLedger: this.actions.map((action) => ({ ...action, mediaOutputs: action.mediaOutputs?.map((output) => ({ ...output })) })),
 			workerText: this.workerText,
+			presentationText,
 			workerTextDisplay: display.text,
 			workerTextTruncated: display.truncated,
 			diagnostic: this.diagnostic,
@@ -726,6 +807,8 @@ class WorkerJob {
 	async dispose(): Promise<void> {
 		if (this.closePromise) return await this.closePromise;
 		this.clearPausedLease();
+		if (this.progressUpdate) clearTimeout(this.progressUpdate);
+		this.progressUpdate = undefined;
 		this.closePromise = (async () => {
 			const child = this.child;
 			if (child && child.exitCode === null && child.signalCode === null) {
@@ -789,7 +872,7 @@ class WorkerJob {
 		});
 	}
 
-	/** Reduce one complete JSONL record into requests, activity, usage, and settlement state. */
+	/** Reduce one complete JSONL record into requests, activity, usage, presentation, and settlement state. */
 	private processLine(line: string): void {
 		if (!line.trim()) return;
 		let event: ParsedEvent;
@@ -806,7 +889,20 @@ class WorkerJob {
 			}
 			return;
 		}
+		if (event.type === "message_start" && event.message?.role === "assistant") {
+			this.beginAssistantPresentation();
+			this.emitProgress();
+			return;
+		}
+		if (event.type === "message_update" && event.assistantMessageEvent) {
+			this.updateAssistantPresentation(event.assistantMessageEvent);
+			this.scheduleProgressUpdate();
+			return;
+		}
 		if (event.type === "message_end" && event.message?.role === "assistant") {
+			const text = assistantText(event);
+			this.completeAssistantPresentation(text);
+			if (text) this.workerText = text;
 			const stopReason = event.message.stopReason;
 			const gateAbort =
 				(stopReason === "aborted" || stopReason === "error") &&
@@ -815,10 +911,9 @@ class WorkerJob {
 				this.turns++;
 				this.lastStopReason = stopReason;
 				addUsage(this.usage, event.message.usage ?? event.usage);
-				const text = assistantText(event);
-				if (text) this.workerText = text;
-				if (event.message.errorMessage) this.diagnostic = event.message.errorMessage;
+				if (event.message.errorMessage) this.diagnostic = sanitizePresentationText(event.message.errorMessage);
 			}
+			this.emitProgress();
 			return;
 		}
 		if (event.type === "tool_execution_start" && event.toolCallId && event.toolName) {
@@ -834,23 +929,36 @@ class WorkerJob {
 			};
 			this.actions.push(action);
 			this.activeActions.set(action.toolCallId, action);
+			this.ensureToolPresentation(event.toolCallId, event.toolName, event.args, event.parentToolCallId);
 			this.emitProgress();
 			return;
 		}
+		if (event.type === "tool_execution_update" && event.toolCallId && event.toolName) {
+			const entry = this.ensureToolPresentation(event.toolCallId, event.toolName, event.args, event.parentToolCallId);
+			entry.status = "running";
+			entry.text = presentationResult(event.partialResult).text;
+			this.scheduleProgressUpdate();
+			return;
+		}
 		if (event.type === "tool_execution_end" && event.toolCallId) {
+			const result = presentationResult(event.result);
 			const action = this.activeActions.get(event.toolCallId);
+			const entry = this.ensureToolPresentation(
+				event.toolCallId,
+				event.toolName ?? action?.toolName ?? "tool",
+				event.args,
+				event.parentToolCallId ?? action?.parentToolCallId,
+			);
+			entry.status = event.isError ? "failed" : "completed";
+			entry.text = result.text;
 			if (action) {
 				action.status = event.isError ? "failed" : "completed";
 				action.endedAt = Date.now();
 				action.completionSequence = ++this.completionSequence;
-				const mediaOutputs = (event.result?.content ?? []).flatMap((part) =>
-					part.type === "image" && typeof part.mimeType === "string" && typeof part.data === "string"
-						? [{ mimeType: part.mimeType, bytes: Buffer.from(part.data, "base64").length }]
-						: []
-				);
-				if (mediaOutputs.length > 0) {
-					action.mediaOutputs = mediaOutputs;
-					action.label += ` · ${mediaOutputs.length} image${mediaOutputs.length === 1 ? "" : "s"}`;
+				if (result.mediaOutputs.length > 0) {
+					action.mediaOutputs = result.mediaOutputs;
+					action.label += ` · ${result.mediaOutputs.length} image${result.mediaOutputs.length === 1 ? "" : "s"}`;
+					entry.label = action.label;
 				}
 				this.activeActions.delete(event.toolCallId);
 			}
@@ -873,6 +981,96 @@ class WorkerJob {
 		if (event.type === "agent_settled") this.settleWaiter?.resolve();
 	}
 
+	/** Start a replaceable assistant entry so streamed deltas never duplicate retained presentation text. */
+	private beginAssistantPresentation(): WorkerPresentationEntry {
+		if (this.activeAssistantPresentation) return this.activeAssistantPresentation;
+		this.assistantTextBlocks.clear();
+		const entry: WorkerPresentationEntry = {
+			sequence: ++this.presentationSequence,
+			id: `assistant-${this.presentationSequence}`,
+			kind: "assistant",
+			label: "assistant",
+			status: "streaming",
+			text: "",
+		};
+		this.presentationEntries.push(entry);
+		this.presentationById.set(entry.id, entry);
+		this.activeAssistantPresentation = entry;
+		return entry;
+	}
+
+	/** Apply JSON/RPC assistant text deltas and completed-block replacements by content index. */
+	private updateAssistantPresentation(update: NonNullable<ParsedEvent["assistantMessageEvent"]>): void {
+		if (!new Set(["text_start", "text_delta", "text_end"]).has(update.type ?? "")) return;
+		const entry = this.beginAssistantPresentation();
+		const index = typeof update.contentIndex === "number" ? update.contentIndex : 0;
+		if (update.type === "text_start") this.assistantTextBlocks.set(index, "");
+		else if (update.type === "text_delta") {
+			this.assistantTextBlocks.set(index, `${this.assistantTextBlocks.get(index) ?? ""}${sanitizePresentationText(update.delta)}`);
+		} else {
+			// JSON/RPC text_end content is authoritative for this streamed block.
+			this.assistantTextBlocks.set(index, sanitizePresentationText(update.content));
+		}
+		entry.text = [...this.assistantTextBlocks.entries()]
+			.sort(([left], [right]) => left - right)
+			.map(([, value]) => value)
+			.filter(Boolean)
+			.join("\n")
+			.trim();
+	}
+
+	/** Replace the live assistant entry with the authoritative final assistant message. */
+	private completeAssistantPresentation(text: string): void {
+		const entry = this.activeAssistantPresentation ?? (text ? this.beginAssistantPresentation() : undefined);
+		if (!entry) return;
+		entry.text = text;
+		entry.status = "completed";
+		this.assistantTextBlocks.clear();
+		this.activeAssistantPresentation = undefined;
+	}
+
+	/** Reuse one ordered presentation record per tool call while preserving child-call relationships. */
+	private ensureToolPresentation(toolCallId: string, toolName: string, args: unknown, parentToolCallId?: string): WorkerPresentationEntry {
+		const id = `tool-${toolCallId}`;
+		const existing = this.presentationById.get(id);
+		if (existing) return existing;
+		const action = this.activeActions.get(toolCallId);
+		const entry: WorkerPresentationEntry = {
+			sequence: ++this.presentationSequence,
+			id,
+			kind: "tool",
+			label: action?.label ?? formatActivity(toolName, args),
+			status: "running",
+			text: "",
+			parentToolCallId,
+		};
+		this.presentationEntries.push(entry);
+		this.presentationById.set(id, entry);
+		return entry;
+	}
+
+	/** Format retained presentation entries from their latest state without retaining repeated partial snapshots. */
+	private presentationText(): string {
+		return this.presentationEntries
+			.map((entry) => {
+				if (entry.kind === "assistant") {
+					if (!entry.text) return "";
+					return `${entry.status === "streaming" ? "assistant streaming" : "assistant"}:\n${entry.text}`;
+				}
+				const kind = entry.parentToolCallId ? "child tool" : "tool";
+				const lines = [`${kind} start: ${entry.label}`];
+				if (entry.status === "running") {
+					if (entry.text) lines.push(`${kind} update: ${entry.label}`, entry.text);
+				} else {
+					lines.push(`${kind} ${entry.status}: ${entry.label}`);
+					if (entry.text) lines.push(entry.text);
+				}
+				return lines.join("\n");
+			})
+			.filter(Boolean)
+			.join("\n\n");
+	}
+
 	/** Execute one or more supervised action batches while respecting calculated ceilings. */
 	private async runStages(
 		initialMessage: string,
@@ -1082,8 +1280,19 @@ class WorkerJob {
 		if (directory) await fs.promises.rm(directory, { recursive: true, force: true });
 	}
 
+	/** Coalesce token and partial-result bursts before rebuilding and serializing the complete snapshot. */
+	private scheduleProgressUpdate(): void {
+		if (this.progressUpdate) return;
+		this.progressUpdate = setTimeout(() => {
+			this.progressUpdate = undefined;
+			this.emitProgress();
+		}, PRESENTATION_UPDATE_THROTTLE_MS);
+	}
+
 	/** Refresh the partial tool block with elapsed time and the latest active command. */
 	private emitProgress(): void {
+		if (this.progressUpdate) clearTimeout(this.progressUpdate);
+		this.progressUpdate = undefined;
 		try {
 			this.progressCallback?.(this.snapshot());
 		} catch {
@@ -1172,6 +1381,15 @@ function formatElapsed(durationMs: number): string {
 	return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
 }
 
+/** Use Pi's configured expansion binding when interactive UI state exists, with a harmless noninteractive render fallback. */
+function expansionHint(theme: any): string {
+	try {
+		return keyHint("app.tools.expand", "to expand");
+	} catch {
+		return theme.fg("muted", "to expand");
+	}
+}
+
 /** Format one bounded state report for both model consumption and non-TUI modes. */
 function formatSnapshot(snapshot: WorkerSnapshot): string {
 	const context = snapshot.context.percent === undefined
@@ -1233,29 +1451,144 @@ function renderArgumentSummary(value: unknown): { task: string; workload: string
 	return { task: compactLine(value.task), workload: `${tools} tools · ${investigation}/${change}/${verification} I/C/V units` };
 }
 
-/** Create a wrapping component whose text can reflect shared renderer state after execution updates. */
-function dynamicText(build: () => string): { render(width: number): string[]; invalidate(): void } {
-	const text = new Text("", 0, 0);
-	let currentText: string | undefined;
-	return {
-		render(width) {
-			let nextText: string;
-			try {
-				nextText = build();
-			} catch {
-				nextText = "Preparing delegation…";
-			}
-			// Text.setText() invalidates the TUI, so call it only when observable content changed.
-			if (nextText !== currentText) {
-				currentText = nextText;
-				text.setText(nextText);
+/** Reuse dynamic text components while changing their source only outside the TUI render cycle. */
+class DynamicTextComponent {
+	private readonly text = new Text("", 0, 0);
+	private currentText: string | undefined;
+	private build: () => string;
+
+	constructor(build: () => string) {
+		this.build = build;
+	}
+
+	setBuild(build: () => string): void {
+		this.build = build;
+	}
+
+	render(width: number): string[] {
+		let nextText: string;
+		try {
+			nextText = this.build();
+		} catch {
+			nextText = "Preparing delegation…";
+		}
+		// Text.setText() invalidates the TUI, so call it only when observable content changed.
+		if (nextText !== this.currentText) {
+			this.currentText = nextText;
+			this.text.setText(nextText);
+		}
+		return this.text.render(width);
+	}
+
+	invalidate(): void {
+		this.text.invalidate();
+	}
+}
+
+/** Reuse the call-renderer component from Pi's context instead of allocating one for every update. */
+function dynamicText(context: any, build: () => string, stateKey = "callComponent"): Component {
+	const state = rendererState(context);
+	const previous = context.lastComponent;
+	const component = previous instanceof DynamicTextComponent
+		? previous
+		: state[stateKey] instanceof DynamicTextComponent
+			? state[stateKey] as DynamicTextComponent
+			: new DynamicTextComponent(build);
+	component.setBuild(build);
+	state[stateKey] = component;
+	return component;
+}
+
+/** Render the full presentation ledger with Pi's native visual-row truncation and expansion hint. */
+class DelegateResultComponent {
+	private snapshot: WorkerSnapshot | undefined;
+	private expanded = false;
+	private isPartial = false;
+	private standalone = false;
+	private theme: any = undefined;
+	private signature = "";
+	private cachedWidth: number | undefined;
+	private cachedLines: string[] | undefined;
+
+	update(snapshot: WorkerSnapshot, expanded: boolean, isPartial: boolean, theme: any, standalone: boolean): void {
+		const presentation = snapshot.presentationText ?? "";
+		const signature = [
+			snapshot.jobId,
+			snapshot.status,
+			snapshot.taskDisplay,
+			snapshot.phase,
+			snapshot.sequence,
+			snapshot.turns,
+			snapshot.durationMs,
+			snapshot.currentActivity ?? "",
+			snapshot.actionCounts.completed,
+			snapshot.actionCounts.failed,
+			snapshot.recommendation,
+			presentation,
+			expanded,
+			isPartial,
+			standalone,
+		].join("\u0000");
+		if (this.signature === signature && this.theme === theme) return;
+		this.snapshot = snapshot;
+		this.expanded = expanded;
+		this.isPartial = isPartial;
+		this.standalone = standalone;
+		this.theme = theme;
+		this.signature = signature;
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
+
+	render(width: number): string[] {
+		if (this.cachedWidth === width && this.cachedLines) return this.cachedLines;
+		const snapshot = this.snapshot;
+		if (!snapshot) return [];
+		const color = snapshot.status === "paused" ? "warning" : snapshot.status === "completed" ? "success" : isTerminal(snapshot.status) && snapshot.status !== "completed" ? "error" : "accent";
+		const latestActivity = snapshot.currentActivity ?? snapshot.recentActions.at(-1)?.label;
+		const activityLabel = snapshot.currentActivity ? "Now" : "Last";
+		const header = [
+			this.standalone ? this.theme.fg(color, this.theme.bold(`${snapshot.jobId}: ${snapshot.status}`)) : "",
+			this.standalone ? this.theme.fg("muted", `Task: ${snapshot.taskDisplay}`) : "",
+			latestActivity ? this.theme.fg(snapshot.currentActivity ? "warning" : "muted", `${activityLabel}: ${latestActivity}`) : "",
+			this.theme.fg("dim", `${snapshot.phase} · boundary ${snapshot.sequence} · turn ${snapshot.turns}/${snapshot.budget.turns}`),
+			this.theme.fg("muted", `${snapshot.actionCounts.completed} actions complete · ${snapshot.actionCounts.failed} failed · ${formatContext(snapshot)}`),
+			this.theme.fg("accent", snapshot.recommendation),
+		].filter(Boolean).join("\n");
+		const lines = new Text(header, 0, 0).render(width);
+		const presentation = snapshot.presentationText ?? "";
+		if (presentation) {
+			// Reapply styling per line because Pi resets terminal attributes at every rendered row.
+			const styledPresentation = presentation
+				.split("\n")
+				.map((line) => this.theme.fg("dim", line))
+				.join("\n");
+			if (this.expanded) {
+				lines.push("", ...new Text(styledPresentation, 0, 0).render(width));
+			} else {
+				const preview = truncateToVisualLines(styledPresentation, PRESENTATION_PREVIEW_ROWS, width, 0, "end");
+				if (preview.visualLines.length > 0) {
+					lines.push("");
+					if (preview.skippedCount > 0) {
+						const hint = this.theme.fg("muted", `… ${preview.skippedCount} earlier visual rows omitted (`)
+							+ expansionHint(this.theme)
+							+ this.theme.fg("muted", ")");
+						lines.push(truncateToWidth(hint, width, "..."));
+					}
+					lines.push(...preview.visualLines);
+				}
 			}
-			return text.render(width);
-		},
-		invalidate() {
-			text.invalidate();
-		},
-	};
+		}
+		lines.push(this.theme.fg("dim", `${this.isPartial ? "Elapsed" : "Took"}: ${formatElapsed(snapshot.durationMs)}`));
+		this.cachedWidth = width;
+		this.cachedLines = lines;
+		return lines;
+	}
+
+	invalidate(): void {
+		this.cachedWidth = undefined;
+		this.cachedLines = undefined;
+	}
 }
 
 /** Render only nonredundant result details; the shared call header owns identity, task, and status. */
@@ -1266,25 +1599,20 @@ function renderWorkerResult(
 	theme: any,
 	context: any,
 	standalone = false,
-): Text {
+): Component {
 	const snapshot = result.details as WorkerSnapshot | undefined;
-	if (!snapshot) return new Text(theme.fg(isPartial ? "warning" : "muted", result.content[0]?.text ?? "Delegation state unavailable"), 0, 0);
-	rendererState(context).snapshot = snapshot;
-	const color = snapshot.status === "paused" ? "warning" : snapshot.status === "completed" ? "success" : isTerminal(snapshot.status) && snapshot.status !== "completed" ? "error" : "accent";
-	const elapsedLabel = isPartial ? "Elapsed" : "Took";
-	const latestActivity = snapshot.currentActivity ?? snapshot.recentActions.at(-1)?.label;
-	const activityLabel = snapshot.currentActivity ? "Now" : "Last";
-	const lines = [
-		standalone ? theme.fg(color, theme.bold(`${snapshot.jobId}: ${snapshot.status}`)) : "",
-		standalone ? theme.fg("muted", `Task: ${snapshot.taskDisplay}`) : "",
-		latestActivity ? theme.fg(snapshot.currentActivity ? "warning" : "muted", `${activityLabel}: ${latestActivity}`) : "",
-		theme.fg("dim", `${snapshot.phase} · boundary ${snapshot.sequence} · turn ${snapshot.turns}/${snapshot.budget.turns}`),
-		theme.fg("muted", `${snapshot.actionCounts.completed} actions complete · ${snapshot.actionCounts.failed} failed · ${formatContext(snapshot)}`),
-		theme.fg("accent", snapshot.recommendation),
-		expanded && snapshot.workerTextDisplay ? `\n${snapshot.workerTextDisplay}` : "",
-		theme.fg("dim", `${elapsedLabel}: ${formatElapsed(snapshot.durationMs)}`),
-	].filter(Boolean);
-	return new Text(lines.join("\n"), 0, 0);
+	if (!snapshot) return dynamicText(context, () => theme.fg(isPartial ? "warning" : "muted", result.content[0]?.text ?? "Delegation state unavailable"), "resultTextComponent");
+	const state = rendererState(context);
+	state.snapshot = snapshot;
+	const previous = context.lastComponent;
+	const component = previous instanceof DelegateResultComponent
+		? previous
+		: state.resultComponent instanceof DelegateResultComponent
+			? state.resultComponent as DelegateResultComponent
+			: new DelegateResultComponent();
+	component.update(snapshot, expanded, isPartial, theme, standalone);
+	state.resultComponent = component;
+	return component;
 }
 
 /** Package a snapshot as bounded model content plus complete machine-readable details. */
@@ -1326,7 +1654,7 @@ function registerDelegate(pi: ExtensionAPI, role: Role): void {
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 		renderCall(args, theme, context) {
 			const expectedId = `${role}-${nextJobIndex}`;
-			return dynamicText(() => {
+			return dynamicText(context, () => {
 				const snapshot = rendererState(context).snapshot as WorkerSnapshot | undefined;
 				const current = renderArgumentSummary(context.args ?? args);
 				const id = snapshot?.jobId ?? expectedId;
@@ -1388,7 +1716,7 @@ function registerControl(pi: ExtensionAPI): void {
 		executionMode: "sequential",
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 		renderCall(args, theme, context) {
-			return dynamicText(() => {
+			return dynamicText(context, () => {
 				const snapshot = rendererState(context).snapshot as WorkerSnapshot | undefined;
 				const current = isRecord(context.args) ? context.args : isRecord(args) ? args : {};
 				const jobId = typeof current.jobId === "string" ? current.jobId : "delegation";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-task-dispatcher",
-  "version": "3.0.2",
+  "version": "3.1.0",
   "description": "Run configurable Pi worker models as supervised, observable, resumable jobs.",
   "type": "module",
   "keywords": [

package/tests/fake-rpc-check.mjs

@@ -94,7 +94,10 @@ try {
 	assert.match(partialRender, /Elapsed:/);
 	assert.equal(statusUpdates.at(-1)?.text, "engineer-1 · 11.0%/1k • active-model • medium");
 	const resultComponent = start.renderResult(result, { expanded: false, isPartial: false }, theme, renderContext);
-	const firstRender = resultComponent.render(100).join("\n");
+	renderContext.lastComponent = resultComponent;
+	const reusedResultComponent = start.renderResult(result, { expanded: false, isPartial: false }, theme, renderContext);
+	assert.equal(reusedResultComponent, resultComponent, "The result renderer did not reuse Pi's last component.");
+	const firstRender = reusedResultComponent.render(100).join("\n");
 	assert.match(firstRender, /Took:/);
 	assert.doesNotMatch(firstRender, /Elapsed:/);
 	for (let index = 0; index < 1_000; index++) {
@@ -124,7 +127,7 @@ try {
 	assert.match(managerCall.render(100).join("\n"), /manager: engineer-1 → completed/);
 	assert.doesNotMatch(managerCall.render(100).join("\n"), /continue\/completed/);
 
-	// The designer must load only the selected built-in codemode extension and account nested usage once.
+	// The designer must load only the selected native codemode-only extension and account nested usage once.
 	await writeFile(configPath, JSON.stringify({ designer: { model: "media-provider/media-model", thinking: "high" } }), "utf8");
 	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "codemode";
 	result = await designerStart.execute("start-designer", { task: "fake image job", tools: ["read", "codemode"], workload }, undefined, undefined, context);
@@ -158,6 +161,57 @@ try {
 	assert.match(statusUpdates.at(-1)?.text ?? "", /designer-2.*\|.*engineer-1/);
 	await writeFile(configPath, "{}\n", "utf8");
 
+	// Streaming RPC updates must replace their partial text, preserve full UI details, and keep model output bounded.
+	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "presentation";
+	const presentationUpdates = [];
+	result = await start.execute(
+		"start-presentation",
+		{ task: "fake presentation job", tools: ["read"], workload },
+		undefined,
+		(update) => presentationUpdates.push(update.details?.presentationText ?? ""),
+		context,
+	);
+	assert(presentationUpdates.some((text) => text.includes("stream delta that must be replaced")), "Live assistant stream text was not presented.");
+	assert(presentationUpdates.some((text) => text.includes("partial read result that must be replaced")), "Live tool partial text was not presented.");
+	assert.equal(result.isError, false);
+	assert.equal(result.details.status, "paused");
+	assert.match(result.details.presentationText, /authoritative first assistant message/);
+	assert.match(result.details.presentationText, /tool start: read presentation\.txt/);
+	assert.match(result.details.presentationText, /tool completed: read presentation\.txt/);
+	assert.match(result.details.presentationText, /final read result six red/);
+	assert.doesNotMatch(result.details.presentationText, /stream delta that must be replaced|stream block that must be replaced|partial read result that must be replaced/);
+	assert.doesNotMatch(result.details.presentationText, /\u001b/, "Presentation text must not retain terminal control sequences.");
+	const presentationRenderContext = { args: {}, state: {}, invalidate() { rendererInvalidations++; }, cwd: projectRoot };
+	const collapsedComponent = start.renderResult(result, { expanded: false, isPartial: false }, theme, presentationRenderContext);
+	presentationRenderContext.lastComponent = collapsedComponent;
+	const collapsed = collapsedComponent.render(100).join("\n");
+	assert.match(collapsed, /earlier visual rows omitted/);
+	assert.match(collapsed, /to expand/);
+	assert.match(collapsed, /final read result six red/);
+	assert.doesNotMatch(collapsed, /authoritative first assistant message/, "Collapsed output must retain only the latest visual rows.");
+
+	result = await control.execute(
+		"continue-presentation",
+		{ jobId: result.details.jobId, action: "continue", actionBatches: 1 },
+		undefined,
+		undefined,
+		context,
+	);
+	assert.equal(result.isError, false);
+	assert.equal(result.details.status, "completed");
+	assert(result.details.workerTextDisplay.length <= 5_000, "Model-facing worker text was not bounded.");
+	assert(result.details.presentationText.length > 5_000, "Structured presentation text was unexpectedly bounded.");
+	assert.match(result.details.presentationText, /MIDDLE-ONLY-IN-EXPANDED-PRESENTATION/);
+	assert.doesNotMatch(result.content[0].text, /MIDDLE-ONLY-IN-EXPANDED-PRESENTATION/, "Model-facing state exposed the omitted middle of a long report.");
+	const expandedComponent = control.renderResult(result, { expanded: true, isPartial: false }, theme, presentationRenderContext);
+	presentationRenderContext.lastComponent = expandedComponent;
+	const expanded = expandedComponent.render(100).join("\n");
+	assert.match(expanded, /MIDDLE-ONLY-IN-EXPANDED-PRESENTATION/);
+	assert.match(expanded, /latest-presentation-marker/);
+	const reusedExpandedComponent = control.renderResult(result, { expanded: true, isPartial: false }, theme, presentationRenderContext);
+	assert.equal(reusedExpandedComponent, expandedComponent, "Expanded renderer state was not reused.");
+	assert.equal(reusedExpandedComponent.render(100).join("\n"), expanded, "Repeated expanded rendering changed output.");
+
 	// A tool-free output-limit stop must preserve the session so the manager can recover the report.
 	process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO = "length";
 	result = await start.execute("start-length", { task: "fake truncated job", tools: ["read"], workload }, undefined, undefined, context);

package/tests/fake-rpc-worker.mjs

@@ -1,6 +1,6 @@
 /** Deterministic JSONL/IPC worker used only by the dispatcher's lifecycle tests. */
 
-import { appendFile } from "node:fs/promises";
+import { appendFile, readFile } from "node:fs/promises";
 import readline from "node:readline";
 
 const scenario = process.env.PI_TASK_DISPATCHER_FAKE_SCENARIO ?? "normal";
@@ -54,17 +54,91 @@ readline.createInterface({ input: process.stdin }).on("line", async (line) => {
 		return;
 	}
 
-	if (scenario === "codemode" && promptCount === 1) {
+	if (promptCount === 1) {
 		const toolsIndex = process.argv.indexOf("--tools");
 		const selectedTools = toolsIndex >= 0 ? process.argv[toolsIndex + 1]?.split(",") ?? [] : [];
 		const extensionValues = process.argv.flatMap((argument, index) => argument === "--extension" ? [process.argv[index + 1]] : []);
-		if (!selectedTools.includes("codemode") || !extensionValues.includes("builtin:codemode")) {
-			send({ type: "response", id: command.id, command: command.type, success: false, error: "codemode was not isolated and loaded" });
+		if (scenario === "normal" && extensionValues.some((value) => value?.endsWith("codemode-only.ts"))) {
+			send({ type: "response", id: command.id, command: command.type, success: false, error: "codemode extension was injected without explicit selection" });
 			return;
 		}
+		if (scenario === "codemode") {
+			const nativeCodemodePath = extensionValues.find((value) => value?.endsWith("codemode-only.ts"));
+			let nativeCodemodeSource = "";
+			try {
+				if (nativeCodemodePath) nativeCodemodeSource = await readFile(nativeCodemodePath, "utf8");
+			} catch {
+				// The failed source check below reports a deterministic fake-RPC error.
+			}
+			if (
+				!selectedTools.includes("codemode")
+				|| extensionValues.includes("builtin:codemode")
+				|| !nativeCodemodePath
+				|| !nativeCodemodeSource.includes('createCodemodeExtension({ mode: "only" })')
+				|| !nativeCodemodeSource.includes('from "@earendil-works/pi-coding-agent"')
+			) {
+				send({ type: "response", id: command.id, command: command.type, success: false, error: "native codemode-only extension was not isolated and loaded" });
+				return;
+			}
+		}
 	}
 
 	send({ type: "response", id: command.id, command: command.type, success: true, data: { disposition: "started" } });
+	if (scenario === "presentation") {
+		if (promptCount === 1) {
+			send({ type: "message_start", message: { role: "assistant" } });
+			send({ type: "message_update", assistantMessageEvent: { type: "text_start", contentIndex: 0 } });
+			send({ type: "message_update", assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "stream delta that must be replaced" } });
+			// Keep the fake stream active long enough to exercise the dispatcher's coalesced live update.
+			await new Promise((resolve) => setTimeout(resolve, 150));
+			send({ type: "message_update", assistantMessageEvent: { type: "text_end", contentIndex: 0, content: "stream block that must be replaced" } });
+			send({
+				type: "message_end",
+				message: { role: "assistant", stopReason: "toolUse", content: [{ type: "text", text: "authoritative first assistant message" }], usage: usage(10, 2) },
+			});
+			send({ type: "tool_execution_start", toolCallId: "fake-presentation-read", toolName: "read", args: { path: "presentation.txt" } });
+			send({
+				type: "tool_execution_update",
+				toolCallId: "fake-presentation-read",
+				toolName: "read",
+				args: { path: "presentation.txt" },
+				partialResult: { content: [{ type: "text", text: "partial read result that must be replaced" }] },
+			});
+			// Keep the partial tool result observable before the authoritative result replaces it.
+			await new Promise((resolve) => setTimeout(resolve, 150));
+			send({
+				type: "tool_execution_end",
+				toolCallId: "fake-presentation-read",
+				toolName: "read",
+				isError: false,
+				result: {
+					content: [{ type: "text", text: "final read result one\nfinal read result two\nfinal read result three\nfinal read result four\nfinal read result five\nfinal read result six \u001b[31mred\u001b[0m" }],
+					usage: usage(3, 1),
+				},
+			});
+			process.send?.({ type: "task_dispatcher_boundary", turnIndex: 0, toolResults: 1 });
+			send({ type: "message_end", message: { role: "assistant", stopReason: "error", errorMessage: "This operation was aborted", content: [] } });
+			send({ type: "agent_settled" });
+			return;
+		}
+		const longReport = [
+			"presentation opening",
+			"A".repeat(2_600),
+			"MIDDLE-ONLY-IN-EXPANDED-PRESENTATION",
+			"B".repeat(4_000),
+			"latest-presentation-marker",
+		].join("\n");
+		send({ type: "message_start", message: { role: "assistant" } });
+		send({ type: "message_update", assistantMessageEvent: { type: "text_start", contentIndex: 0 } });
+		send({ type: "message_update", assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "partial final assistant text" } });
+		send({ type: "message_update", assistantMessageEvent: { type: "text_end", contentIndex: 0, content: "replaced final assistant text" } });
+		send({
+			type: "message_end",
+		message: { role: "assistant", stopReason: "stop", content: [{ type: "text", text: longReport }], usage: usage(5, 3) },
+		});
+		send({ type: "agent_settled" });
+		return;
+	}
 	if (scenario === "length" && promptCount === 1) {
 		send({
 			type: "message_end",

package/tests/gate-probe.mjs

@@ -22,6 +22,8 @@ async function resolvePiCli() {
 const cliPath = await resolvePiCli();
 const temporaryDirectory = await mkdtemp(path.join(tmpdir(), "pi-task-dispatcher-gate-probe-"));
 const gatePath = path.join(temporaryDirectory, "gate.ts");
+const codemodeOnlyPath = path.join(temporaryDirectory, "codemode-only.ts");
+const readProbePath = path.join(temporaryDirectory, "codemode-read-probe.txt");
 let child;
 
 try {
@@ -43,6 +45,18 @@ export default function (pi: ExtensionAPI): void {
 `,
 		"utf8",
 	);
+	// Use Pi's public factory so only codemode is model-visible while selected direct tools remain script-callable.
+	await writeFile(
+		codemodeOnlyPath,
+		`import { createCodemodeExtension, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+const codemodeOnly = createCodemodeExtension({ mode: "only" });
+export default function codemodeOnlyExtension(pi: ExtensionAPI): void {
+	codemodeOnly(pi);
+}
+`,
+		"utf8",
+	);
+	await writeFile(readProbePath, "native-codemode-only-read-ready\n", "utf8");
 
 	// Prefer explicit test overrides, then the active parent Pi model exported in PI_* variables.
 	const activeModel = process.env.PI_TASK_DISPATCHER_GATE_MODEL
@@ -55,9 +69,9 @@ export default function (pi: ExtensionAPI): void {
 		"--no-session",
 		"--no-extensions",
 		"--tools",
-		"codemode",
+		"codemode,read",
 		"--extension",
-		"builtin:codemode",
+		codemodeOnlyPath,
 		"--extension",
 		gatePath,
 	];
@@ -94,11 +108,11 @@ export default function (pi: ExtensionAPI): void {
 	});
 	child.on("message", (message) => boundaries.push(message));
 
-	// Run one codemode batch and require the gate to settle before a productive follow-up turn.
+	// Run one codemode batch that invokes the selected direct read tool from the script, then require the gate to settle.
 	child.stdin.write(`${JSON.stringify({
 		id: "probe-1",
 		type: "prompt",
-		message: "Call codemode exactly once with the raw JavaScript source: text('pi-task-dispatcher-codemode-ready')\nDo not use any other tool and do not add other script statements.",
+		message: `Call codemode exactly once. In its JavaScript source, call await tools.read({ path: ${JSON.stringify(readProbePath)} }); and then call text("pi-task-dispatcher-codemode-ready"). Do not call tools directly and do not make any other tool calls.`,
 	})}\n`);
 	await Promise.race([
 		settled,
@@ -112,7 +126,13 @@ export default function (pi: ExtensionAPI): void {
 		throw new Error("The first run did not execute the expected tool-use turn.");
 	}
 	if (!events.some((event) => event.type === "tool_execution_end" && event.toolName === "codemode" && !event.isError)) {
-		throw new Error("The isolated worker did not complete the selected built-in codemode tool.");
+		throw new Error("The isolated worker did not complete the selected native codemode tool.");
+	}
+	if (!events.some((event) => event.type === "tool_execution_end" && event.toolName === "read" && event.parentToolCallId)) {
+		throw new Error("The codemode script could not call the explicitly selected direct read tool.");
+	}
+	if (events.some((event) => event.type === "tool_execution_start" && event.toolName === "read" && !event.parentToolCallId)) {
+		throw new Error("The worker called read directly instead of routing it through codemode-only mode.");
 	}
 
 	// Continue in the same in-memory RPC session and require a normal final answer without another tool batch.
@@ -123,7 +143,7 @@ export default function (pi: ExtensionAPI): void {
 	child.stdin.write(`${JSON.stringify({
 		id: "probe-2",
 		type: "prompt",
-		message: "Continue from the completed codemode result. Do not call tools. Report only the exact marker produced by the script.",
+		message: "Continue from the completed native codemode result. Do not call tools. Report only the exact marker produced by the script.",
 	})}\n`);
 	await Promise.race([
 		settled,
@@ -139,7 +159,7 @@ export default function (pi: ExtensionAPI): void {
 		.trim();
 	if (!finalText.includes("pi-task-dispatcher-codemode-ready")) throw new Error(`Unexpected continuation output: ${finalText}`);
 
-	console.log(JSON.stringify({ firstBoundaryCount, firstAssistantMessages: firstAssistantMessages.length, finalText }, null, 2));
+	console.log(JSON.stringify({ firstBoundaryCount, firstAssistantMessages: firstAssistantMessages.length, finalText, nativeCodemodeOnly: true }, null, 2));
 	if (stderr.trim()) console.error(stderr.trim());
 } finally {
 	// Close the reusable child and remove only the runtime-controlled probe directory.

package/tests/static-check.mjs

@@ -27,7 +27,9 @@ for (const required of [
 	"delegate_designer",
 	"delegate_control",
 	"delegate_status",
-	"builtin:codemode",
+	"codemode-only.ts",
+	"createCodemodeExtension",
+	'mode: "only"',
 	"task_dispatcher_boundary",
 	"without an enforced IPC boundary",
 	"--no-extensions",
@@ -35,9 +37,21 @@ for (const required of [
 	"set_auto_compaction",
 	"get_session_stats",
 	"renderResult",
+	"truncateToVisualLines",
+	"truncateToWidth",
+	'keyHint("app.tools.expand", "to expand")',
+	"stripTerminalSequences",
+	"message_update",
+	"tool_execution_update",
+	"PRESENTATION_UPDATE_THROTTLE_MS",
+	"context.lastComponent",
 ]) {
 	if (!source.includes(required)) throw new Error(`Missing supervised-protocol marker: ${required}`);
 }
 
-if (!String(packageJson.version).startsWith("3.")) throw new Error(`Expected a v3 package version, found ${packageJson.version}`);
+if (packageJson.version !== "3.1.0") throw new Error(`Expected release version 3.1.0, found ${packageJson.version}`);
+if (source.includes("builtin:codemode")) throw new Error("The dispatcher must not load codemode through a built-in extension selector.");
+if (!gateProbe.includes("createCodemodeExtension") || !gateProbe.includes('mode: "only"')) {
+	throw new Error("The live gate probe does not exercise the native codemode-only extension.");
+}
 console.log(`Static supervised-protocol checks passed for ${packageJson.name}@${packageJson.version}.`);