@gajae-code/coding-agent 0.8.2 → 0.9.1

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

@@ -16,6 +16,7 @@ import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { TtsrNotificationComponent } from "../../modes/components/ttsr-notification";
 import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext, TodoPhase } from "../../modes/types";
+import { completionNotifyDisabledByEnv } from "../../notifications/config";
 import { summaryFromMessage } from "../../notifications/helpers";
 import type { PlanApprovalDetails } from "../../plan-mode/approved-plan";
 import type { AgentSessionEvent } from "../../session/agent-session";
@@ -23,11 +24,22 @@ import { isSilentAbort, readPendingDisplayTag } from "../../session/messages";
 import type { ResolveToolDetails } from "../../tools/resolve";
 import { interruptHint } from "../shared";
 import { buildAbortDisplayMessage } from "../utils/abort-message";
+import { consumeInjectedOptimisticSignature } from "../utils/injected-user-submission";
 import { ringTerminalBell } from "../utils/terminal-bell";
+import { argsWithPartialJson } from "../utils/ui-helpers";
 
 type AgentSessionEventKind = AgentSessionEvent["type"];
 
 const IRC_MESSAGE_VISIBLE_TTL_MS = 10_000;
+
+/** Test-only performance counters for advisory baseline tests. */
+export const __eventControllerPerfCounters = {
+	messageUpdateContentVisits: 0,
+	reset(): void {
+		this.messageUpdateContentVisits = 0;
+	},
+};
+
 const COMPLETION_NOTIFY_COMMAND_TIMEOUT_MS = 10_000;
 
 interface CompletionNotifyPayload {
@@ -100,6 +112,8 @@ export class EventController {
 	#lastAssistantComponent: AssistantMessageComponent | undefined = undefined;
 	#idleCompactionTimer?: NodeJS.Timeout;
 	#ircExpiryTimers = new Map<string, NodeJS.Timeout>();
+	#toolIntentCache = new Map<string, { args: unknown; intent: string | undefined }>();
+	#thinkingContentIndices = new Set<number>();
 	#handlers: AgentSessionEventHandlers;
 
 	constructor(private ctx: InteractiveModeContext) {
@@ -279,12 +293,17 @@ export class EventController {
 			const signature = `${textContent}\u0000${imageCount}`;
 
 			this.#resetReadGroup();
-			const wasOptimistic = this.ctx.optimisticUserMessageSignature === signature;
+			const wasSingleOptimistic = this.ctx.optimisticUserMessageSignature === signature;
+			const wasInjectedOptimistic = !wasSingleOptimistic && consumeInjectedOptimisticSignature(this.ctx, signature);
+			const wasOptimistic = wasSingleOptimistic || wasInjectedOptimistic;
 			const wasLocallySubmitted = this.ctx.locallySubmittedUserSignatures.delete(signature) || wasOptimistic;
 			if (!wasOptimistic) {
 				this.ctx.addMessageToChat(event.message);
 			}
-			if (wasOptimistic) {
+			// Only clear the single local slot when IT matched; an injected match is
+			// consumed from the counting Map above and must not clobber a coexisting
+			// pending local optimistic signature.
+			if (wasSingleOptimistic) {
 				this.ctx.optimisticUserMessageSignature = undefined;
 			}
 
@@ -307,12 +326,14 @@ export class EventController {
 		} else if (event.message.role === "assistant") {
 			this.#lastThinkingCount = 0;
 			this.#resetReadGroup();
+			this.#toolIntentCache.clear();
+			this.#thinkingContentIndices.clear();
 			this.ctx.streamingComponent = new AssistantMessageComponent(undefined, this.ctx.hideThinkingBlock, () =>
 				this.ctx.ui.requestRender(),
 			);
 			this.ctx.streamingMessage = event.message;
 			this.ctx.chatContainer.addChild(this.ctx.streamingComponent);
-			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
+			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: true });
 			this.ctx.ui.requestRender();
 		}
 	}
@@ -375,46 +396,53 @@ export class EventController {
 	async #handleMessageUpdate(event: Extract<AgentSessionEvent, { type: "message_update" }>): Promise<void> {
 		if (this.ctx.streamingComponent && event.message.role === "assistant") {
 			this.ctx.streamingMessage = event.message;
-			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
-
-			const thinkingCount = this.ctx.streamingMessage.content.filter(
-				content => content.type === "thinking" && content.thinking.trim(),
-			).length;
-			if (thinkingCount > this.#lastThinkingCount) {
-				this.#resetReadGroup();
-				this.#lastThinkingCount = thinkingCount;
+			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: true });
+			const contentIndex = event.assistantMessageEvent?.contentIndex;
+			const changedContent =
+				typeof contentIndex === "number" && contentIndex >= 0
+					? this.ctx.streamingMessage.content[contentIndex]
+					: undefined;
+			const contentsToProcess = changedContent ? [changedContent] : this.ctx.streamingMessage.content;
+
+			if (changedContent?.type === "thinking" && changedContent.thinking.trim()) {
+				if (typeof contentIndex === "number") this.#thinkingContentIndices.add(contentIndex);
+				const thinkingCount = this.#thinkingContentIndices.size;
+				if (thinkingCount > this.#lastThinkingCount) {
+					this.#resetReadGroup();
+					this.#lastThinkingCount = thinkingCount;
+				}
+			} else if (!changedContent) {
+				const thinkingCount = this.ctx.streamingMessage.content.filter(
+					content => content.type === "thinking" && content.thinking.trim(),
+				).length;
+				if (thinkingCount > this.#lastThinkingCount) {
+					this.#resetReadGroup();
+					this.#lastThinkingCount = thinkingCount;
+				}
 			}
 
-			for (const content of this.ctx.streamingMessage.content) {
+			for (const content of contentsToProcess) {
+				__eventControllerPerfCounters.messageUpdateContentVisits += 1;
 				if (content.type !== "toolCall") continue;
 				if (content.name === "read") {
-					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;
-					}
+					if (!readArgsHaveTarget(content.arguments)) 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 {
+						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.
-				// Bash uses this to show inline env assignments during streaming instead of popping them in at completion.
-				const renderArgs =
-					"partialJson" in content
-						? { ...content.arguments, __partialJson: content.partialJson }
-						: content.arguments;
+				const renderArgs = argsWithPartialJson(
+					content.arguments,
+					"partialJson" in content ? content.partialJson : undefined,
+				);
 				if (!this.ctx.pendingTools.has(content.id)) {
 					this.#resetReadGroup();
 					this.ctx.chatContainer.addChild(new Text("", 0, 0));
@@ -437,32 +465,30 @@ export class EventController {
 					this.ctx.chatContainer.addChild(component);
 					this.ctx.pendingTools.set(content.id, component);
 				} else {
-					const component = this.ctx.pendingTools.get(content.id);
-					if (component) {
-						component.updateArgs(renderArgs, content.id);
-					}
+					this.ctx.pendingTools.get(content.id)?.updateArgs(renderArgs, content.id);
 				}
-			}
 
-			// Update working message with intent from streamed tool arguments
-			for (const content of this.ctx.streamingMessage.content) {
-				if (content.type !== "toolCall") continue;
 				const args = content.arguments;
 				if (!args || typeof args !== "object") continue;
+				let intent: string | undefined;
 				if (INTENT_FIELD in args) {
-					this.#updateWorkingMessageFromIntent(args[INTENT_FIELD]);
-					continue;
-				}
-				const tool = this.ctx.session.getToolByName(content.name);
-				if (typeof tool?.intent !== "function") continue;
-				try {
-					const derived = tool.intent(args as never)?.trim();
-					if (derived) {
-						this.#updateWorkingMessageFromIntent(derived);
+					intent = String(args[INTENT_FIELD]);
+				} else {
+					const cached = this.#toolIntentCache.get(content.id);
+					if (cached?.args === args) intent = cached.intent;
+					else {
+						const tool = this.ctx.session.getToolByName(content.name);
+						if (typeof tool?.intent === "function") {
+							try {
+								intent = tool.intent(args as never)?.trim();
+							} catch {
+								// intent function must never break the UI
+							}
+						}
+						this.#toolIntentCache.set(content.id, { args, intent });
 					}
-				} catch {
-					// intent function must never break the UI
 				}
+				if (intent) this.#updateWorkingMessageFromIntent(intent);
 			}
 
 			this.ctx.ui.requestRender();
@@ -495,9 +521,9 @@ export class EventController {
 				// display only — does NOT mutate the persisted message's stopReason
 				// (the marker on errorMessage drives replay-side suppression).
 				const msgWithoutAbort = { ...this.ctx.streamingMessage, stopReason: "stop" as const };
-				this.ctx.streamingComponent.updateContent(msgWithoutAbort);
+				this.ctx.streamingComponent.updateContent(msgWithoutAbort, { streaming: false });
 			} else {
-				this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
+				this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: false });
 			}
 
 			if (this.ctx.streamingMessage.stopReason !== "aborted" && this.ctx.streamingMessage.stopReason !== "error") {
@@ -941,6 +967,8 @@ export class EventController {
 	}
 
 	sendCompletionNotification(): void {
+		// Per-run hard opt-out (env, config-untouched, child-inheritable): GJC_NOTIFY=off.
+		if (completionNotifyDisabledByEnv(process.env)) return;
 		const isBackgrounded = this.ctx.isBackgrounded !== false;
 		const notify = settings.get("completion.notify");
 		if (notify === "off") return;

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

@@ -23,6 +23,7 @@ import { HookSelectorComponent } from "../../modes/components/hook-selector";
 import { getAvailableThemesWithPaths, getThemeByName, setTheme, type Theme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext } from "../../modes/types";
 import { setSessionTerminalTitle, setTerminalTitle } from "../../utils/title-generator";
+import { applyInjectedUserSubmission } from "../utils/injected-user-submission";
 import { classifyHookSelectorBellEvent, ringTerminalBell } from "../utils/terminal-bell";
 
 const MAX_WIDGET_LINES = 10;
@@ -954,7 +955,13 @@ export class ExtensionUiController {
 	}
 
 	#sendExtensionUserMessage: SendUserMessageHandler = (content, options) => {
-		this.ctx.session.sendUserMessage(content, options).catch((err: unknown) => {
+		// Compute queued BEFORE send: prompt() may flip session.isStreaming synchronously.
+		const queued = Boolean(options?.deliverAs) || this.ctx.session.isStreaming;
+		// Call send first so the busy/queued path finds the session queue populated
+		// (queueSteer/queueFollowUp push synchronously) before refreshing pending display.
+		const send = this.ctx.session.sendUserMessage(content, options);
+		applyInjectedUserSubmission(this.ctx, { content, queued });
+		send.catch((err: unknown) => {
 			this.ctx.showError(`Extension sendUserMessage failed: ${err instanceof Error ? err.message : String(err)}`);
 		});
 	};

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

@@ -18,6 +18,7 @@ import { copyToClipboard, readImageFromClipboard } from "../../utils/clipboard";
 import { getEditorCommand, openInEditor } from "../../utils/external-editor";
 import { ensureSupportedImageInput, ImageInputTooLargeError, loadImageInput } from "../../utils/image-loading";
 import { resizeImage } from "../../utils/image-resize";
+import { resolvePastedImagePath } from "../../utils/pasted-image-path";
 import { generateSessionTitle, setSessionTerminalTitle } from "../../utils/title-generator";
 import { type QueuedMessageMoveDirection, QueuedMessageSelectorComponent } from "../components/queued-message-selector";
 
@@ -26,8 +27,6 @@ interface Expandable {
 }
 
 const INTERACTIVE_ABORT_CLEANUP_TIMEOUT_MS = 5_000;
-const CLIPBOARD_TEMP_IMAGE_FILE_PATTERN = /^clipboard-\d{4}-\d{2}-\d{2}-\d{6}-[A-Za-z0-9]+\.(?:png|jpe?g|gif|webp)$/i;
-const MACOS_CLIPBOARD_TEMP_DIR_PATTERN = /^\/var\/folders\/[^/]+\/[^/]+\/T$/;
 
 function isExpandable(obj: unknown): obj is Expandable {
 	return typeof obj === "object" && obj !== null && "setExpanded" in obj && typeof obj.setExpanded === "function";
@@ -1061,10 +1060,15 @@ export class InputController {
 	}
 
 	handleTextPaste(text: string): boolean | Promise<boolean> {
-		const imagePath = this.#getPastedImagePathCandidate(text);
+		const imagePath = resolvePastedImagePath(text, { cwd: this.ctx.sessionManager.getCwd() });
 		return imagePath ? this.#attachPastedImagePath(imagePath) : false;
 	}
 
+	/**
+	 * Returns `false` on every failure path so the editor replays the original
+	 * bracketed paste — the raw path text must never be lost when attachment
+	 * is impossible (unsupported content, oversized image, load error).
+	 */
 	async #attachPastedImagePath(imagePath: string): Promise<boolean> {
 		try {
 			const image = await loadImageInput({
@@ -1073,8 +1077,8 @@ export class InputController {
 				autoResize: this.ctx.settings.get("images.autoResize"),
 			});
 			if (!image) {
-				this.ctx.showStatus("Unsupported pasted clipboard image file");
-				return true;
+				this.ctx.showStatus("Unsupported pasted image file");
+				return false;
 			}
 
 			this.ctx.pendingImages.push({
@@ -1089,22 +1093,13 @@ export class InputController {
 		} catch (error) {
 			if (error instanceof ImageInputTooLargeError) {
 				this.ctx.showStatus(error.message);
-				return true;
+				return false;
 			}
-			this.ctx.showStatus("Failed to attach pasted clipboard image");
-			return true;
+			this.ctx.showStatus("Failed to attach pasted image");
+			return false;
 		}
 	}
 
-	#getPastedImagePathCandidate(text: string): string | undefined {
-		const resolvedPath = path.resolve(text.trim());
-		const parentDir = path.dirname(resolvedPath);
-		const isClipboardTempPath =
-			(parentDir === "/tmp" || MACOS_CLIPBOARD_TEMP_DIR_PATTERN.test(parentDir)) &&
-			CLIPBOARD_TEMP_IMAGE_FILE_PATTERN.test(path.basename(resolvedPath));
-		return isClipboardTempPath ? resolvedPath : undefined;
-	}
-
 	#nextImagePlaceholder(): string {
 		return `[image ${this.ctx.pendingImages.length}]`;
 	}
@@ -1308,7 +1303,7 @@ export class InputController {
 		// If streaming, re-add the streaming component with updated visibility and re-render
 		if (this.ctx.streamingComponent && this.ctx.streamingMessage) {
 			this.ctx.streamingComponent.setHideThinkingBlock(this.ctx.hideThinkingBlock);
-			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage);
+			this.ctx.streamingComponent.updateContent(this.ctx.streamingMessage, { streaming: true });
 			this.ctx.chatContainer.addChild(this.ctx.streamingComponent);
 		}
 

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

@@ -88,6 +88,7 @@ import { SessionSelectorComponent } from "../components/session-selector";
 import { SettingsSelectorComponent } from "../components/settings-selector";
 import type { StatusLineSettings } from "../components/status-line";
 import { ThemeSelectorComponent } from "../components/theme-selector";
+import { ThinkingSelectorComponent } from "../components/thinking-selector";
 import { ToolExecutionComponent } from "../components/tool-execution";
 import { TreeSelectorComponent } from "../components/tree-selector";
 import { UserMessageSelectorComponent } from "../components/user-message-selector";
@@ -431,6 +432,46 @@ export class SelectorController {
 		});
 	}
 
+	showEffortSelector(): void {
+		const availableLevels = [
+			ThinkingLevel.Inherit,
+			ThinkingLevel.Off,
+			...this.ctx.session.getAvailableThinkingLevels(),
+		];
+
+		this.showSelector(done => {
+			const selector = new ThinkingSelectorComponent(
+				this.ctx.session.thinkingLevel,
+				availableLevels,
+				level => {
+					done();
+
+					const configuredDefault = this.ctx.settings.get("defaultThinkingLevel");
+					const levelToApply = level === ThinkingLevel.Inherit ? configuredDefault : level;
+					this.ctx.session.setThinkingLevel(levelToApply, false);
+					const effectiveLevel = this.ctx.session.thinkingLevel ?? ThinkingLevel.Off;
+					const requestedLabel =
+						level === ThinkingLevel.Inherit ? `${level} (configured default: ${configuredDefault})` : level;
+					const clampedSuffix =
+						effectiveLevel === levelToApply ? "" : ` Requested ${levelToApply}; effective ${effectiveLevel}.`;
+
+					this.ctx.statusLine.invalidate();
+					this.ctx.updateEditorBorderColor();
+					this.ctx.updateEditorTopBorder();
+					this.ctx.ui.requestRender();
+					this.ctx.showStatus(
+						`Reasoning effort set to ${requestedLabel}. Effective effort: ${effectiveLevel}.${clampedSuffix}`,
+					);
+				},
+				() => {
+					done();
+					this.ctx.ui.requestRender();
+				},
+			);
+			return { component: selector, focus: selector.getSelectList() };
+		});
+	}
+
 	showSettingsSelector(): void {
 		getAvailableThemes().then(availableThemes => {
 			this.showSelector(done => {

package/src/modes/interactive-mode.ts

@@ -118,7 +118,7 @@ import { UiHelpers } from "./utils/ui-helpers";
 
 const INTERACTIVE_ABORT_CLEANUP_TIMEOUT_MS = 5_000;
 const COMPOSER_NEWLINE_HINT = process.platform === "win32" ? "Alt+Enter/Ctrl+J" : "Shift+Enter/Ctrl+J";
-const DEFAULT_COMPOSER_PLACEHOLDER = `Type your message... ${COMPOSER_NEWLINE_HINT}: New line · Ctrl+C: Clear · Shift+Tab: Reasoning`;
+export const DEFAULT_COMPOSER_PLACEHOLDER = `Type your message... ${COMPOSER_NEWLINE_HINT}: New line · Ctrl+C: Clear · Ctrl+R: Search history · Shift+Tab: Reasoning`;
 const WELCOME_RESERVED_CONTAINER_CHILD_LIMIT = 8;
 const FRIENDLY_KEY_PARTS: Record<string, string> = {
 	alt: "Alt",
@@ -163,6 +163,7 @@ function configureDefaultComposerChrome(editor: CustomEditor): void {
 	editor.setInputPrefix(getDefaultInputPrefix());
 	editor.setPlaceholder(DEFAULT_COMPOSER_PLACEHOLDER);
 	editor.setPaddingX(1);
+	editor.setRightGutterWidth(1);
 	editor.setTopBorder(undefined);
 }
 
@@ -329,6 +330,7 @@ export class InteractiveMode implements InteractiveModeContext {
 	onInputCallback?: (input: SubmittedUserInput) => void;
 	optimisticUserMessageSignature: string | undefined = undefined;
 	locallySubmittedUserSignatures: Set<string> = new Set();
+	optimisticInjectedSignatures: Map<string, number> = new Map();
 	#pendingSubmittedInput: SubmittedUserInput | undefined;
 	#pendingSubmissionDispose: (() => void) | undefined;
 	lastSigintTime = 0;
@@ -1715,6 +1717,7 @@ export class InteractiveMode implements InteractiveModeContext {
 			planContent,
 			finalPlanFilePath: options.finalPlanFilePath,
 			contextPreserved: options.preserveContext === true,
+			tools: this.session.getActiveToolNames(),
 		});
 		await this.session.prompt(planModePrompt, { synthetic: true });
 	}
@@ -2206,6 +2209,7 @@ export class InteractiveMode implements InteractiveModeContext {
 				message => renderWorkingMessage(message, this.#getWorkingMessageAccent()),
 				this.#defaultWorkingMessage,
 				getSymbolTheme().spinnerFrames,
+				{ timeDependentColor: true },
 			);
 			this.statusContainer.addChild(this.loadingAnimation);
 		}
@@ -2363,6 +2367,11 @@ export class InteractiveMode implements InteractiveModeContext {
 		return this.#commandController.handleClearCommand();
 	}
 
+	handleContextClearCommand(): Promise<void> {
+		this.#prepareSessionSwitch();
+		return this.#commandController.handleContextClearCommand();
+	}
+
 	handleDropCommand(): Promise<void> {
 		this.#prepareSessionSwitch();
 		return this.#commandController.handleDropCommand();
@@ -2552,6 +2561,10 @@ export class InteractiveMode implements InteractiveModeContext {
 		this.#selectorController.showModelSelector(options);
 	}
 
+	showEffortSelector(): void {
+		this.#selectorController.showEffortSelector();
+	}
+
 	showProviderOnboarding(): void {
 		this.#selectorController.showProviderOnboarding();
 	}

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

@@ -22,8 +22,13 @@ import { type Theme, theme } from "../../modes/theme/theme";
 import type { AgentSession } from "../../session/agent-session";
 import { initializeExtensions } from "../runtime-init";
 import { dispatchRpcCommand } from "../shared/agent-wire/command-dispatch";
-import { AgentWireFrameSequencer, toAgentWireEventFrame } from "../shared/agent-wire/event-envelope";
-import { rpcError as error } from "../shared/agent-wire/responses";
+import {
+	AgentWireCompactEventEncoder,
+	AgentWireFrameSequencer,
+	toAgentWireCompactEventFrame,
+	toAgentWireEventFrame,
+} from "../shared/agent-wire/event-envelope";
+import { rpcError as error, rpcSuccess } from "../shared/agent-wire/responses";
 import { registerRpcSession, unregisterRpcSession } from "../shared/agent-wire/session-registry";
 import { defaultAuditPath, UnattendedAuditLog } from "../shared/agent-wire/unattended-audit";
 import { modelSupportsTokenCostMetrics, UnattendedSessionControlPlane } from "../shared/agent-wire/unattended-session";
@@ -168,15 +173,9 @@ function auditOutcomeFor(event: string): "accepted" | "rejected" | "denied" | "e
 	return "info";
 }
 
-export class RpcListenRefusedError extends Error {
-	constructor(socketPath: string) {
-		super(
-			`RPC --listen refused: a live server is already listening on ${socketPath}. ` +
-				"Stop it first or choose a different --listen path.",
-		);
-		this.name = "RpcListenRefusedError";
-	}
-}
+// Thrown by prepareRpcSocketPath when the --listen path has a live owner;
+// re-exported here because main.ts catches it at the RPC launch boundary.
+export { RpcListenRefusedError } from "./rpc-socket-security";
 
 /**
  * Probe whether a unix-domain socket path has a live server accepting
@@ -297,6 +296,7 @@ export async function runRpcMode(
 		output({ type: "ready" });
 	}
 	const emitRpcTitles = shouldEmitRpcTitles();
+	const rpcCapabilities = { compactMessageUpdate: false };
 	const decodeError = (err: unknown): string => (err instanceof Error ? err.message : String(err));
 
 	const pendingExtensionRequests = new Map<string, PendingExtensionRequest>();
@@ -636,8 +636,13 @@ export async function runRpcMode(
 	// Output all agent events as canonical agent-wire `event` frames (docs/rpc.md):
 	// { type:"event", protocol_version, session_id, seq, frame_id, payload:{ event_type, event } }.
 	const eventSequencer = new AgentWireFrameSequencer(session.sessionId);
+	const compactEventEncoder = new AgentWireCompactEventEncoder(eventSequencer);
 	session.subscribe(event => {
-		output(toAgentWireEventFrame(event, eventSequencer));
+		output(
+			rpcCapabilities.compactMessageUpdate
+				? toAgentWireCompactEventFrame(event, compactEventEncoder)
+				: toAgentWireEventFrame(event, eventSequencer),
+		);
 	});
 
 	// Handle a single command through the shared agent-wire dispatcher so RPC
@@ -710,6 +715,21 @@ export async function runRpcMode(
 				hostUriBridge.handleResult(parsed);
 				return;
 			}
+			if ((parsed as RpcCommand).type === "set_capabilities") {
+				// RPC has no startup handshake; clients negotiate optional event-shape capabilities
+				// with this explicit command. Defaults remain legacy/full-frame until accepted here.
+				const command = parsed as Extract<RpcCommand, { type: "set_capabilities" }>;
+				const requested = Array.isArray(command.capabilities) ? command.capabilities : [];
+				const acceptedCapabilities = requested.filter(capability => capability === "compact_message_update");
+				rpcCapabilities.compactMessageUpdate = acceptedCapabilities.includes("compact_message_update");
+				output(
+					rpcSuccess(command.id, "set_capabilities", {
+						acceptedCapabilities,
+						unsupported: requested.filter(capability => capability !== "compact_message_update"),
+					}),
+				);
+				return;
+			}
 			// Ordered commands run through a serial chain to preserve causal order; the
 			// reader never blocks, so cancellation commands stay responsive even while a
 			// long command is in flight (issue 13).

package/src/modes/rpc/rpc-socket-security.ts

@@ -9,6 +9,18 @@ export class RpcSocketSecurityError extends Error {
 	}
 }
 
+// The launch boundary in main.ts catches exactly this class to turn a
+// duplicate --listen into a clean stderr diagnostic + non-zero exit (issue 19).
+export class RpcListenRefusedError extends Error {
+	constructor(socketPath: string) {
+		super(
+			`RPC --listen refused: a live server is already listening on ${socketPath}. ` +
+				"Stop it first or choose a different --listen path.",
+		);
+		this.name = "RpcListenRefusedError";
+	}
+}
+
 const unsafeBits = 0o077;
 
 function currentUid(): number | undefined {
@@ -53,7 +65,7 @@ export async function prepareRpcSocketPath(socketPath: string): Promise<void> {
 	if (!existing.isSocket()) throw new RpcSocketSecurityError(`RPC socket path is not a socket: ${socketPath}`);
 	assertPrivateMode(existing.mode, socketPath);
 	if (await probeUnixSocketAlive(socketPath)) {
-		throw new RpcSocketSecurityError(`RPC socket path is live: ${socketPath}`);
+		throw new RpcListenRefusedError(socketPath);
 	}
 	await fs.unlink(socketPath);
 }

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

@@ -13,6 +13,7 @@ import type { SessionStats } from "../../session/agent-session";
 import type { TodoPhase } from "../../tools/todo-write";
 
 export type RpcGetStateInclude = "tools" | "dumpTools" | "systemPrompt";
+export type RpcCapability = "compact_message_update";
 
 // ============================================================================
 // RPC Commands (stdin)
@@ -33,6 +34,7 @@ export type RpcCommand =
 	| { id?: string; type: "set_host_tools"; tools: RpcHostToolDefinition[] }
 	| { id?: string; type: "set_host_uri_schemes"; schemes: RpcHostUriSchemeDefinition[] }
 	| { id?: string; type: "get_pending_workflow_gates" }
+	| { id?: string; type: "set_capabilities"; capabilities: RpcCapability[] }
 
 	// Model
 	| { id?: string; type: "set_model"; provider: string; modelId: string }
@@ -140,6 +142,13 @@ export type RpcResponse =
 			success: true;
 			data: { gates: RpcWorkflowGate[] };
 	  }
+	| {
+			id?: string;
+			type: "response";
+			command: "set_capabilities";
+			success: true;
+			data: { acceptedCapabilities: RpcCapability[]; unsupported: string[] };
+	  }
 
 	// Model
 	| {

package/src/modes/shared/agent-wire/command-validation.ts

@@ -130,6 +130,10 @@ export function isRpcCommand(value: unknown): value is RpcCommand {
 			return Array.isArray(value.tools) && value.tools.every(hostToolDefinition);
 		case "set_host_uri_schemes":
 			return Array.isArray(value.schemes) && value.schemes.every(hostUriScheme);
+		case "set_capabilities":
+			return (
+				Array.isArray(value.capabilities) && value.capabilities.every(capability => typeof capability === "string")
+			);
 		case "set_model":
 			return stringField(value, "provider") && stringField(value, "modelId");
 		case "set_thinking_level":

package/src/modes/shared/agent-wire/event-contract.ts

@@ -13,6 +13,8 @@
  * an `AgentSessionEvent` variant fails typecheck until it is registered, and so
  * conformance tests can assert fixture coverage equals the registry exactly.
  */
+
+import type { AssistantMessageEvent } from "@gajae-code/ai";
 import type { AgentSessionEvent } from "../../../session/agent-session";
 
 /** Wire protocol version. Bump on breaking envelope/semantic changes. */
@@ -68,6 +70,25 @@ export interface AgentWireEventPayload {
 	event_type: AgentWireEventType;
 	event: AgentSessionEvent;
 }
+export type AgentWireCompactAssistantMessageEvent = AssistantMessageEvent extends infer TEvent
+	? TEvent extends { type: string }
+		? Omit<TEvent, "partial" | "message" | "error">
+		: never
+	: never;
+
+export interface AgentWireCompactMessageUpdatePayload {
+	event_type: "message_update";
+	/** Compact RPC opt-in payload: delta-only update plus minimal routing metadata. */
+	compact: true;
+	message_id: string | null;
+	content_index: number | null;
+	assistantMessageEvent: AgentWireCompactAssistantMessageEvent;
+	/** Full message checkpoint, snapshotted synchronously when this frame is enqueued. */
+	checkpoint_message?: Extract<AgentSessionEvent, { type: "message_update" }>["message"];
+	checkpoint_reason?: "periodic";
+}
+
+export type AgentWireEventFramePayload = AgentWireEventPayload | AgentWireCompactMessageUpdatePayload;
 
 /**
  * Bounded observed-signal vocabulary surfaced to owner control planes. Mirrors
@@ -146,3 +167,4 @@ export interface AgentWireFrameEnvelope<TType extends AgentWireFrameType = Agent
 
 /** An `AgentSessionEvent` serialized into a versioned wire frame. */
 export type AgentWireEventFrame = AgentWireFrameEnvelope<"event", AgentWireEventPayload>;
+export type AgentWireCompactEventFrame = AgentWireFrameEnvelope<"event", AgentWireEventFramePayload>;