@oh-my-pi/pi-coding-agent 14.9.8 → 15.0.0

package/src/modes/acp/acp-client-bridge.ts

@@ -0,0 +1,152 @@
+/**
+ * ACP-side `ClientBridge` implementation. Wraps `AgentSideConnection` so the
+ * `read`/`write`/`bash`/`edit` tools (and the permission gate in
+ * `AgentSession`) can route through the client when it advertises the
+ * relevant capabilities at `initialize` time.
+ */
+import type {
+	PermissionOption as AcpPermissionOption,
+	TerminalHandle as AcpTerminalHandle,
+	AgentSideConnection,
+	ClientCapabilities,
+	RequestPermissionRequest,
+	ToolCallUpdate,
+} from "@agentclientprotocol/sdk";
+import type {
+	ClientBridge,
+	ClientBridgeCapabilities,
+	ClientBridgeCreateTerminalParams,
+	ClientBridgePermissionOption,
+	ClientBridgePermissionOutcome,
+	ClientBridgePermissionToolCall,
+	ClientBridgeTerminalHandle,
+} from "../../session/client-bridge";
+
+export function createAcpClientBridge(
+	connection: AgentSideConnection,
+	sessionId: string,
+	clientCapabilities: ClientCapabilities | undefined,
+): ClientBridge {
+	const capabilities: ClientBridgeCapabilities = {
+		readTextFile: clientCapabilities?.fs?.readTextFile === true,
+		writeTextFile: clientCapabilities?.fs?.writeTextFile === true,
+		terminal: clientCapabilities?.terminal === true,
+		// Permission requests are always usable on the connection; gating is
+		// the agent's policy choice rather than a client capability.
+		requestPermission: true,
+	};
+
+	const bridge: ClientBridge = { capabilities };
+
+	if (capabilities.readTextFile) {
+		bridge.readTextFile = async params => {
+			const response = await connection.readTextFile({
+				sessionId,
+				path: params.path,
+				...(typeof params.line === "number" ? { line: params.line } : {}),
+				...(typeof params.limit === "number" ? { limit: params.limit } : {}),
+			});
+			return response.content;
+		};
+	}
+
+	if (capabilities.writeTextFile) {
+		bridge.writeTextFile = async params => {
+			await connection.writeTextFile({
+				sessionId,
+				path: params.path,
+				content: params.content,
+			});
+		};
+	}
+
+	if (capabilities.terminal) {
+		bridge.createTerminal = (params: ClientBridgeCreateTerminalParams) =>
+			createTerminalHandle(connection, sessionId, params);
+	}
+
+	bridge.requestPermission = (toolCall, options, signal) =>
+		requestPermission(connection, sessionId, toolCall, options, signal);
+
+	return bridge;
+}
+
+async function createTerminalHandle(
+	connection: AgentSideConnection,
+	sessionId: string,
+	params: ClientBridgeCreateTerminalParams,
+): Promise<ClientBridgeTerminalHandle> {
+	const handle = await connection.createTerminal({
+		sessionId,
+		command: params.command,
+		...(params.args ? { args: params.args } : {}),
+		...(params.env ? { env: params.env } : {}),
+		...(params.cwd ? { cwd: params.cwd } : {}),
+		...(typeof params.outputByteLimit === "number" ? { outputByteLimit: params.outputByteLimit } : {}),
+	});
+	return wrapTerminalHandle(handle);
+}
+
+function wrapTerminalHandle(handle: AcpTerminalHandle): ClientBridgeTerminalHandle {
+	return {
+		terminalId: handle.id,
+		async currentOutput() {
+			const out = await handle.currentOutput();
+			return {
+				output: out.output,
+				truncated: out.truncated,
+				exitStatus: out.exitStatus ?? null,
+			};
+		},
+		async waitForExit() {
+			const status = await handle.waitForExit();
+			return { exitCode: status.exitCode ?? null, signal: status.signal ?? null };
+		},
+		async kill() {
+			await handle.kill();
+		},
+		async release() {
+			await handle.release();
+		},
+	};
+}
+
+async function requestPermission(
+	connection: AgentSideConnection,
+	sessionId: string,
+	toolCall: ClientBridgePermissionToolCall,
+	options: ClientBridgePermissionOption[],
+	signal: AbortSignal | undefined,
+): Promise<ClientBridgePermissionOutcome> {
+	const update: ToolCallUpdate = {
+		toolCallId: toolCall.toolCallId,
+		title: toolCall.title,
+		...(toolCall.kind ? { kind: toolCall.kind as ToolCallUpdate["kind"] } : {}),
+		...(toolCall.rawInput !== undefined ? { rawInput: toolCall.rawInput } : {}),
+		...(toolCall.locations ? { locations: toolCall.locations } : {}),
+	};
+	const acpOptions: AcpPermissionOption[] = options.map(option => ({
+		optionId: option.optionId,
+		name: option.name,
+		kind: option.kind,
+	}));
+	const request: RequestPermissionRequest = {
+		sessionId,
+		toolCall: update,
+		options: acpOptions,
+	};
+	if (signal?.aborted) {
+		return { outcome: "cancelled" };
+	}
+	const response = await connection.requestPermission(request);
+	const outcome = response.outcome;
+	if (outcome.outcome === "cancelled") {
+		return { outcome: "cancelled" };
+	}
+	const matched = options.find(option => option.optionId === outcome.optionId);
+	return {
+		outcome: "selected",
+		optionId: outcome.optionId,
+		...(matched ? { kind: matched.kind } : {}),
+	};
+}

package/src/modes/acp/acp-event-mapper.ts

@@ -6,10 +6,24 @@ import type {
 	ToolKind,
 } from "@agentclientprotocol/sdk";
 import type { AgentSessionEvent } from "../../session/agent-session";
+import { resolveToCwd } from "../../tools/path-utils";
 import type { TodoStatus } from "../../tools/todo-write";
 
+interface MessageProgress {
+	textEmitted: boolean;
+	thoughtEmitted: boolean;
+}
+
 interface AcpEventMapperOptions {
 	getMessageId?: (message: unknown) => string | undefined;
+	getMessageProgress?: (message: unknown) => MessageProgress | undefined;
+	/**
+	 * Session cwd. Tool call locations sent to ACP clients must be absolute
+	 * (the editor host needs them to open or focus files). When provided,
+	 * the mapper resolves raw `path`/`file`/etc. args against this cwd
+	 * before emitting `ToolCallLocation` entries.
+	 */
+	cwd?: string;
 }
 
 interface ContentArrayContainer {
@@ -127,6 +141,8 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 	switch (event.type) {
 		case "message_update":
 			return mapAssistantMessageUpdate(event, sessionId, options);
+		case "message_end":
+			return mapAssistantMessageEnd(event, sessionId, options);
 		case "tool_execution_start": {
 			const update: SessionUpdate = {
 				sessionUpdate: "tool_call",
@@ -136,14 +152,16 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 				status: "pending",
 				rawInput: event.args,
 			};
-			const locations = extractToolLocations(event.args);
+			const locations = extractToolLocations(event.args, options.cwd);
 			if (locations.length > 0) {
 				update.locations = locations;
 			}
 			return [toSessionNotification(sessionId, update)];
 		}
 		case "tool_execution_update": {
-			const content = extractToolCallContent(event.partialResult);
+			const terminalContent = extractTerminalToolCallContent(event.partialResult);
+			const otherContent = terminalContent.length > 0 ? [] : extractToolCallContent(event.partialResult);
+			const content = [...terminalContent, ...otherContent];
 			const update: SessionUpdate = {
 				sessionUpdate: "tool_call_update",
 				toolCallId: event.toolCallId,
@@ -153,10 +171,17 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 			if (content.length > 0) {
 				update.content = content;
 			}
+			const locations = extractToolLocations(event.args, options.cwd);
+			if (locations.length > 0) {
+				update.locations = locations;
+			}
 			return [toSessionNotification(sessionId, update)];
 		}
 		case "tool_execution_end": {
-			const content = extractToolCallContent(event.result);
+			const diffContent = extractDiffToolCallContent(event.result);
+			const terminalContent = extractTerminalToolCallContent(event.result);
+			const otherContent = extractToolCallContent(event.result);
+			const content = [...diffContent, ...terminalContent, ...otherContent];
 			const update: SessionUpdate = {
 				sessionUpdate: "tool_call_update",
 				toolCallId: event.toolCallId,
@@ -166,6 +191,10 @@ export function mapAgentSessionEventToAcpSessionUpdates(
 			if (content.length > 0) {
 				update.content = content;
 			}
+			const locations = extractToolLocationsFromResult(event.result, options.cwd);
+			if (locations.length > 0) {
+				update.locations = locations;
+			}
 			return [toSessionNotification(sessionId, update)];
 		}
 		case "todo_reminder": {
@@ -194,14 +223,31 @@ function mapAssistantMessageUpdate(
 
 	let sessionUpdate: "agent_message_chunk" | "agent_thought_chunk";
 	let text: string;
+	const progress = options.getMessageProgress?.(event.message);
 	switch (event.assistantMessageEvent.type) {
 		case "text_delta":
 			sessionUpdate = "agent_message_chunk";
 			text = event.assistantMessageEvent.delta;
+			if (text.length > 0 && progress) {
+				progress.textEmitted = true;
+			}
 			break;
 		case "thinking_delta":
 			sessionUpdate = "agent_thought_chunk";
 			text = event.assistantMessageEvent.delta;
+			if (text.length > 0 && progress) {
+				progress.thoughtEmitted = true;
+			}
+			break;
+		case "done":
+			if (progress?.textEmitted) {
+				return [];
+			}
+			sessionUpdate = "agent_message_chunk";
+			text = extractAssistantMessageText(event.assistantMessageEvent.message);
+			if (text.length > 0 && progress) {
+				progress.textEmitted = true;
+			}
 			break;
 		case "error":
 			sessionUpdate = "agent_message_chunk";
@@ -224,6 +270,33 @@ function mapAssistantMessageUpdate(
 	];
 }
 
+function mapAssistantMessageEnd(
+	event: Extract<AgentSessionEvent, { type: "message_end" }>,
+	sessionId: string,
+	options: AcpEventMapperOptions,
+): SessionNotification[] {
+	if (!isAssistantMessage(event.message)) {
+		return [];
+	}
+	const progress = options.getMessageProgress?.(event.message);
+	if (!progress || progress.textEmitted) {
+		return [];
+	}
+	const text = extractAssistantMessageText(event.message);
+	if (text.length === 0) {
+		return [];
+	}
+	progress.textEmitted = true;
+	const messageId = options.getMessageId?.(event.message);
+	return [
+		toSessionNotification(sessionId, {
+			sessionUpdate: "agent_message_chunk",
+			content: { type: "text", text },
+			messageId,
+		}),
+	];
+}
+
 function toSessionNotification(sessionId: string, update: SessionUpdate): SessionNotification {
 	return { sessionId, update };
 }
@@ -257,26 +330,104 @@ function buildToolTitle(toolName: string, args: unknown, intent: string | undefi
 	return toolName;
 }
 
-function extractToolLocations(args: unknown): ToolCallLocation[] {
+/**
+ * Resolve a single raw path against cwd for an ACP location. When `cwd` is
+ * omitted we pass the value through unchanged (callers without session
+ * context, e.g. some legacy entry points and tests); the ACP-side caller
+ * always supplies cwd so notifications carry absolute paths.
+ */
+function toAcpLocationPath(value: string, cwd?: string): string {
+	if (!cwd) return value;
+	try {
+		return resolveToCwd(value, cwd);
+	} catch {
+		return value;
+	}
+}
+
+function extractToolLocations(args: unknown, cwd?: string): ToolCallLocation[] {
 	const locations: ToolCallLocation[] = [];
-	const path = extractStringProperty<PathContainer>(args, "path");
-	if (path) {
+	const seen = new Set<string>();
+	const pushPath = (raw: string | undefined) => {
+		if (!raw) return;
+		const path = toAcpLocationPath(raw, cwd);
+		if (seen.has(path)) return;
+		seen.add(path);
 		locations.push({ path });
-	}
+	};
 
-	const oldPath = extractStringProperty<OldPathContainer>(args, "oldPath");
-	if (oldPath && oldPath !== path) {
-		locations.push({ path: oldPath });
-	}
+	pushPath(extractStringProperty<PathContainer>(args, "path"));
+	pushPath(extractStringProperty<OldPathContainer>(args, "oldPath"));
+	pushPath(extractStringProperty<NewPathContainer>(args, "newPath"));
 
-	const newPath = extractStringProperty<NewPathContainer>(args, "newPath");
-	if (newPath && newPath !== path && newPath !== oldPath) {
-		locations.push({ path: newPath });
-	}
+	return locations;
+}
 
+/** Pull locations from a tool result's details (e.g. EditToolDetails.perFileResults[].path). */
+function extractToolLocationsFromResult(result: unknown, cwd?: string): ToolCallLocation[] {
+	if (typeof result !== "object" || result === null) return [];
+	const details = (result as { details?: unknown }).details;
+	if (typeof details !== "object" || details === null) return [];
+	const direct = extractToolLocations(details, cwd);
+	const perFile = (details as { perFileResults?: unknown }).perFileResults;
+	if (!Array.isArray(perFile)) {
+		return direct;
+	}
+	const seen = new Set(direct.map(loc => loc.path));
+	const locations = [...direct];
+	for (const entry of perFile) {
+		const raw = extractStringProperty<PathContainer>(entry, "path");
+		if (!raw) continue;
+		const path = toAcpLocationPath(raw, cwd);
+		if (seen.has(path)) continue;
+		seen.add(path);
+		locations.push({ path });
+	}
 	return locations;
 }
 
+/** Emit a `diff` ToolCallContent for each per-file edit result that carries oldText/newText. */
+function extractDiffToolCallContent(result: unknown): ToolCallContent[] {
+	if (typeof result !== "object" || result === null) return [];
+	const details = (result as { details?: unknown }).details;
+	if (typeof details !== "object" || details === null) return [];
+	const blocks: ToolCallContent[] = [];
+	const perFile = (details as { perFileResults?: unknown }).perFileResults;
+	const entries: unknown[] = Array.isArray(perFile) ? perFile : [details];
+	for (const entry of entries) {
+		const block = buildDiffContent(entry);
+		if (block) blocks.push(block);
+	}
+	return blocks;
+}
+
+function buildDiffContent(entry: unknown): ToolCallContent | undefined {
+	if (typeof entry !== "object" || entry === null) return undefined;
+	const candidate = entry as { path?: unknown; oldText?: unknown; newText?: unknown; isError?: unknown };
+	if (candidate.isError === true) return undefined;
+	const path = typeof candidate.path === "string" && candidate.path.length > 0 ? candidate.path : undefined;
+	if (!path) return undefined;
+	const oldText = typeof candidate.oldText === "string" ? candidate.oldText : undefined;
+	const newText = typeof candidate.newText === "string" ? candidate.newText : undefined;
+	if (oldText === undefined && newText === undefined) return undefined;
+	return {
+		type: "diff",
+		path,
+		oldText: oldText ?? null,
+		newText: newText ?? "",
+	};
+}
+
+/** Emit a `terminal` ToolCallContent when a tool result carries a `details.terminalId` (e.g. bash routed through ACP terminal/*). */
+function extractTerminalToolCallContent(result: unknown): ToolCallContent[] {
+	if (typeof result !== "object" || result === null) return [];
+	const details = (result as { details?: unknown }).details;
+	if (typeof details !== "object" || details === null) return [];
+	const terminalId = (details as { terminalId?: unknown }).terminalId;
+	if (typeof terminalId !== "string" || terminalId.length === 0) return [];
+	return [{ type: "terminal", terminalId }];
+}
+
 function extractToolCallContent(value: unknown): ToolCallContent[] {
 	const richContent = extractStructuredToolCallContent(value);
 	const fallbackText = extractReadableText(value);
@@ -479,6 +630,20 @@ function extractReadableText(value: unknown): string | undefined {
 	return normalizeText(serialized);
 }
 
+function extractAssistantMessageText(value: unknown): string {
+	if (typeof value !== "object" || value === null || !("content" in value)) {
+		return "";
+	}
+	const content = (value as ContentArrayContainer).content;
+	if (!Array.isArray(content)) {
+		return "";
+	}
+	return content
+		.map(block => extractStructuredText(block))
+		.filter((chunk): chunk is string => typeof chunk === "string" && chunk.length > 0)
+		.join("\n");
+}
+
 function extractStructuredText(value: unknown): string | undefined {
 	const text = extractStringProperty<TextLikeContent>(value, "text");
 	if (!text) {

package/src/modes/acp/terminal-auth.ts

@@ -0,0 +1,37 @@
+export const ACP_TERMINAL_AUTH_FLAG = "--acp-terminal-auth";
+
+export interface AcpTerminalAuthArgs {
+	args: string[];
+	terminalAuth: boolean;
+}
+
+export function prepareAcpTerminalAuthArgs(rawArgs: readonly string[]): AcpTerminalAuthArgs {
+	const withoutAuthFlag: string[] = [];
+	let terminalAuth = false;
+	for (const arg of rawArgs) {
+		if (arg === ACP_TERMINAL_AUTH_FLAG) {
+			terminalAuth = true;
+			continue;
+		}
+		withoutAuthFlag.push(arg);
+	}
+
+	if (!terminalAuth) {
+		return { args: withoutAuthFlag, terminalAuth: false };
+	}
+
+	const args: string[] = [];
+	for (let i = 0; i < withoutAuthFlag.length; i++) {
+		const arg = withoutAuthFlag[i];
+		if (arg === "--mode") {
+			i++;
+			continue;
+		}
+		if (arg.startsWith("--mode=")) {
+			continue;
+		}
+		args.push(arg);
+	}
+
+	return { args, terminalAuth: true };
+}

package/src/modes/components/read-tool-group.ts

@@ -1,10 +1,38 @@
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Container, Text } from "@oh-my-pi/pi-tui";
+import { InternalUrlRouter } from "../../internal-urls";
 import { getLanguageFromPath, theme } from "../../modes/theme/theme";
+import { splitPathAndSel } from "../../tools/path-utils";
 import { PREVIEW_LIMITS, shortenPath } from "../../tools/render-utils";
 import { renderCodeCell } from "../../tui";
 import type { ToolExecutionHandle } from "./tool-execution";
 
+/**
+ * Read calls whose target is resolved through {@link InternalUrlRouter} are
+ * rendered as full tool executions (not collapsed into the read group) so the
+ * resolved content is visible. `path` is the canonical arg; `file_path` is the
+ * legacy alias still tolerated by the read tool schema.
+ */
+function readArgsTarget(args: unknown): string | undefined {
+	if (!args || typeof args !== "object" || Array.isArray(args)) return undefined;
+	const record = args as Record<string, unknown>;
+	return typeof record.path === "string"
+		? record.path
+		: typeof record.file_path === "string"
+			? record.file_path
+			: undefined;
+}
+
+export function readArgsHaveTarget(args: unknown): boolean {
+	return readArgsTarget(args) !== undefined;
+}
+
+export function readArgsTargetInternalUrl(args: unknown): boolean {
+	const target = readArgsTarget(args);
+	if (!target) return false;
+	return InternalUrlRouter.instance().canHandle(target);
+}
+
 type ReadRenderArgs = {
 	path?: string;
 	file_path?: string;
@@ -174,7 +202,7 @@ export class ReadToolGroupComponent extends Container implements ToolExecutionHa
 	 * When expanded: shows full content.
 	 */
 	#addContentPreview(entry: ReadEntry): void {
-		const lang = getLanguageFromPath(entry.path);
+		const lang = getLanguageFromPath(splitPathAndSel(entry.path).path);
 		const filePath = shortenPath(entry.path);
 		const correctionSuffix = entry.correctedFrom ? ` (corrected from ${shortenPath(entry.correctedFrom)})` : "";
 		const title = filePath ? `Read ${filePath}${correctionSuffix}` : "Read";

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

@@ -37,6 +37,7 @@ import { buildHotkeysMarkdown } from "../../modes/utils/hotkeys-markdown";
 import { buildToolsMarkdown } from "../../modes/utils/tools-markdown";
 import type { AsyncJobSnapshotItem } from "../../session/agent-session";
 import type { AuthStorage } from "../../session/auth-storage";
+import { CompactionCancelledError, type CompactionOutcome } from "../../session/compaction";
 import type { NewSessionOptions } from "../../session/session-manager";
 import { outputMeta } from "../../tools/output-meta";
 import { resolveToCwd, stripOuterDoubleQuotes } from "../../tools/path-utils";
@@ -1071,16 +1072,16 @@ export class CommandController {
 		this.ctx.ui.requestRender();
 	}
 
-	async handleCompactCommand(customInstructions?: string): Promise<void> {
+	async handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome> {
 		const entries = this.ctx.sessionManager.getEntries();
 		const messageCount = entries.filter(e => e.type === "message").length;
 
 		if (messageCount < 2) {
 			this.ctx.showWarning("Nothing to compact (no messages yet)");
-			return;
+			return "ok";
 		}
 
-		await this.executeCompaction(customInstructions, false);
+		return this.executeCompaction(customInstructions, false);
 	}
 
 	async handleSkillCommand(skillPath: string, args: string): Promise<void> {
@@ -1098,7 +1099,10 @@ export class CommandController {
 		}
 	}
 
-	async executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto = false): Promise<void> {
+	async executeCompaction(
+		customInstructionsOrOptions?: string | CompactOptions,
+		isAuto = false,
+	): Promise<CompactionOutcome> {
 		if (this.ctx.loadingAnimation) {
 			this.ctx.loadingAnimation.stop();
 			this.ctx.loadingAnimation = undefined;
@@ -1122,6 +1126,7 @@ export class CommandController {
 		this.ctx.statusContainer.addChild(compactingLoader);
 		this.ctx.ui.requestRender();
 
+		let outcome: CompactionOutcome = "ok";
 		try {
 			const instructions = typeof customInstructionsOrOptions === "string" ? customInstructionsOrOptions : undefined;
 			const options =
@@ -1135,10 +1140,12 @@ export class CommandController {
 			this.ctx.statusLine.invalidate();
 			this.ctx.updateEditorTopBorder();
 		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			if (message === "Compaction cancelled" || (error instanceof Error && error.name === "AbortError")) {
+			if (error instanceof CompactionCancelledError) {
+				outcome = "cancelled";
 				this.ctx.showError("Compaction cancelled");
 			} else {
+				outcome = "failed";
+				const message = error instanceof Error ? error.message : String(error);
 				this.ctx.showError(`Compaction failed: ${message}`);
 			}
 		} finally {
@@ -1147,6 +1154,7 @@ export class CommandController {
 			this.ctx.editor.onEscape = originalOnEscape;
 		}
 		await this.ctx.flushCompactionQueue({ willRetry: false });
+		return outcome;
 	}
 
 	async handleHandoffCommand(customInstructions?: string): Promise<void> {

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

@@ -3,7 +3,11 @@ import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
 import { type Component, Loader, TERMINAL, Text } from "@oh-my-pi/pi-tui";
 import { settings } from "../../config/settings";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
-import { ReadToolGroupComponent } from "../../modes/components/read-tool-group";
+import {
+	ReadToolGroupComponent,
+	readArgsHaveTarget,
+	readArgsTargetInternalUrl,
+} from "../../modes/components/read-tool-group";
 import { TodoReminderComponent } from "../../modes/components/todo-reminder";
 import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { TtsrNotificationComponent } from "../../modes/components/ttsr-notification";
@@ -274,16 +278,25 @@ export class EventController {
 			for (const content of this.ctx.streamingMessage.content) {
 				if (content.type !== "toolCall") continue;
 				if (content.name === "read") {
-					this.#trackReadToolCall(content.id, content.arguments);
-					const component = this.ctx.pendingTools.get(content.id);
-					if (component) {
-						component.updateArgs(content.arguments, content.id);
-					} else {
-						const group = this.#getReadGroup();
-						group.updateArgs(content.arguments, content.id);
-						this.ctx.pendingTools.set(content.id, group);
+					if (!readArgsHaveTarget(content.arguments)) {
+						// Args still streaming — defer until path is parseable so we can route to the
+						// read group (regular files) vs ToolExecutionComponent (internal URLs).
+						// Creating either component now would lock the read into the wrong shape.
+						continue;
 					}
-					continue;
+					if (!readArgsTargetInternalUrl(content.arguments)) {
+						this.#trackReadToolCall(content.id, content.arguments);
+						const component = this.ctx.pendingTools.get(content.id);
+						if (component) {
+							component.updateArgs(content.arguments, content.id);
+						} else {
+							const group = this.#getReadGroup();
+							group.updateArgs(content.arguments, content.id);
+							this.ctx.pendingTools.set(content.id, group);
+						}
+						continue;
+					}
+					// Internal URL read falls through to ToolExecutionComponent below.
 				}
 
 				// Preserve the raw partial JSON for renderers that need to surface fields before the JSON object closes.
@@ -384,7 +397,7 @@ export class EventController {
 	async #handleToolExecutionStart(event: Extract<AgentSessionEvent, { type: "tool_execution_start" }>): Promise<void> {
 		this.#updateWorkingMessageFromIntent(event.intent);
 		if (!this.ctx.pendingTools.has(event.toolCallId)) {
-			if (event.toolName === "read") {
+			if (event.toolName === "read" && readArgsHaveTarget(event.args) && !readArgsTargetInternalUrl(event.args)) {
 				this.#trackReadToolCall(event.toolCallId, event.args);
 				const component = this.ctx.pendingTools.get(event.toolCallId);
 				if (component) {

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

@@ -119,7 +119,10 @@ export class ExtensionUiController {
 			abort: () => this.ctx.session.abort(),
 			hasPendingMessages: () => this.ctx.session.queuedMessageCount > 0,
 			shutdown: () => {
-				// Signal shutdown request (will be handled by main loop)
+				// Defer the actual teardown to the main loop, which calls
+				// `checkShutdownRequested()` at idle boundaries so any queued
+				// steering / follow-up messages drain first (see issue #1020).
+				this.ctx.shutdownRequested = true;
 			},
 			getContextUsage: () => this.ctx.session.getContextUsage(),
 			compact: instructionsOrOptions => this.#compactSession(instructionsOrOptions),
@@ -356,7 +359,10 @@ export class ExtensionUiController {
 			abort: () => this.ctx.session.abort(),
 			hasPendingMessages: () => this.ctx.session.queuedMessageCount > 0,
 			shutdown: () => {
-				// Signal shutdown request (will be handled by main loop)
+				// Defer the actual teardown to the main loop, which calls
+				// `checkShutdownRequested()` at idle boundaries so any queued
+				// steering / follow-up messages drain first (see issue #1020).
+				this.ctx.shutdownRequested = true;
 			},
 			getContextUsage: () => this.ctx.session.getContextUsage(),
 			compact: instructionsOrOptions => this.#compactSession(instructionsOrOptions),