claude-code-rust 0.12.0 → 0.12.2

package/agent-sdk/dist/bridge/message_handlers.js

@@ -2,13 +2,17 @@ import { asRecordOrNull } from "./shared.js";
 import { toPermissionMode, buildModeState, refreshSupportedModesForSession } from "./commands.js";
 import { writeEvent, emitSessionUpdate, emitConnectEvent, emitSessionReplacedEvent, } from "./events.js";
 import { TOOL_RESULT_TYPES, isToolSearchToolName, isToolSearchToolResultType, unwrapToolUseResult, } from "./tooling.js";
-import { emitToolCall, emitToolCallUpdate, emitPlanIfTodoWrite, emitToolResultUpdate, finalizeOpenToolCalls, emitToolProgressUpdate, emitToolSummaryUpdate, ensureToolCallVisible, resolveTaskToolUseId, toolAcceptsTaskLifecycle, taskProgressText, taskUpdatedFields, } from "./tool_calls.js";
+import { emitToolCall, emitToolCallUpdate, emitToolResultUpdate, finalizeOpenToolCalls, emitToolProgressUpdate, emitToolSummaryUpdate, ensureToolCallVisible, resolveTaskToolUseId, defersTaskNotificationCompletion, toolAcceptsTaskLifecycle, taskProgressText, taskUpdatedFields, } from "./tool_calls.js";
+import { applyTaskLifecycleState } from "./tasks.js";
+import { linkTaskToolUse, unlinkTaskToolUse } from "./task_links.js";
 import { emitAuthRequired, classifyTurnErrorKind, emitFastModeUpdateIfChanged } from "./error_classification.js";
 import { mapAvailableAgentsFromNames, emitAvailableAgentsIfChanged, refreshAvailableAgents } from "./agents.js";
-import { buildApiRetryUpdate, buildRateLimitUpdate, normalizeSettingsParseErrors, numberField, parseRuntimeSessionState, } from "./state_parsing.js";
+import { mapInitSlashCommands, mapSdkSlashCommands, updateAvailableCommands, } from "./available_commands.js";
+import { buildApiRetryUpdate, buildRateLimitUpdate, normalizeSettingsParseErrors, numberField, parseApiRetryError, parseRuntimeSessionState, } from "./state_parsing.js";
 import { looksLikeAuthRequired } from "./auth.js";
 import { emitCurrentModelUpdate, refreshCurrentModel, updateSessionId } from "./session_lifecycle.js";
 import { bridgeLogger, LOG_TARGETS } from "./logger.js";
+import { emitMcpSnapshotFromStatuses } from "./mcp.js";
 export function textFromPrompt(command) {
     const chunks = command.chunks ?? [];
     return chunks
@@ -30,6 +34,68 @@ const SUPPORTED_IMAGE_MIME_TYPES = new Set([
     "image/gif",
     "image/webp",
 ]);
+function sdkCorrelationMetadata(msg) {
+    return {
+        requestId: typeof msg.request_id === "string" ? msg.request_id : undefined,
+        subagentType: typeof msg.subagent_type === "string" ? msg.subagent_type : undefined,
+        taskDescription: typeof msg.task_description === "string" ? msg.task_description : undefined,
+    };
+}
+function sdkTaskMetadata(msg) {
+    const metadata = sdkCorrelationMetadata(msg);
+    const taskType = typeof msg.task_type === "string" && msg.task_type.length > 0 ? msg.task_type : undefined;
+    const workflowName = typeof msg.workflow_name === "string" && msg.workflow_name.length > 0 ? msg.workflow_name : undefined;
+    const prompt = typeof msg.prompt === "string" && msg.prompt.length > 0 ? msg.prompt : undefined;
+    const outputFile = typeof msg.output_file === "string" && msg.output_file.length > 0 ? msg.output_file : undefined;
+    const status = typeof msg.status === "string" && msg.status.length > 0 ? msg.status : undefined;
+    const summary = status && typeof msg.summary === "string" && msg.summary.length > 0 ? msg.summary : undefined;
+    const taskMetadata = {
+        ...(metadata.requestId ? { request_id: metadata.requestId } : {}),
+        ...(metadata.subagentType ? { subagent_type: metadata.subagentType } : {}),
+        ...(metadata.taskDescription ? { task_description: metadata.taskDescription } : {}),
+        ...(taskType ? { task_type: taskType } : {}),
+        ...(workflowName ? { workflow_name: workflowName } : {}),
+        ...(prompt ? { prompt } : {}),
+        ...(outputFile ? { output_file: outputFile } : {}),
+        ...(summary ? { summary } : {}),
+        ...(status ? { terminal_status: status } : {}),
+    };
+    return Object.keys(taskMetadata).length > 0 ? taskMetadata : undefined;
+}
+function sdkMessageOriginKind(msg) {
+    const origin = msg.origin && typeof msg.origin === "object" ? msg.origin : null;
+    return typeof origin?.kind === "string" ? origin.kind : undefined;
+}
+function logSdkMessageOrigin(session, msg) {
+    const originKind = sdkMessageOriginKind(msg);
+    if (!originKind) {
+        return;
+    }
+    bridgeLogger.debug({
+        target: LOG_TARGETS.APP_SESSION,
+        eventName: "sdk_message_origin_observed",
+        message: "SDK message origin observed",
+        outcome: originKind === "auto-continuation" ? "accepted" : "observed",
+        sessionId: session.sessionId,
+        fields: {
+            message_type: typeof msg.type === "string" ? msg.type : undefined,
+            origin_kind: originKind,
+        },
+    });
+}
+function emitSystemNoticeUpdate(session, severity, message) {
+    const trimmed = message.trim();
+    if (!trimmed) {
+        return;
+    }
+    emitSessionUpdate(session.sessionId, { type: "system_notice_update", severity, message: trimmed });
+}
+function notificationSeverity(priority) {
+    return priority === "high" || priority === "immediate" ? "warning" : "info";
+}
+function isTerminalToolStatus(status) {
+    return status === "completed" || status === "failed" || status === "killed";
+}
 /** Fast check that a string looks like valid base64 (non-empty, correct charset & padding). */
 function isValidBase64(data) {
     if (!data)
@@ -98,12 +164,13 @@ export function handleTaskSystemMessage(session, subtype, msg) {
         subtype !== "task_progress" &&
         subtype !== "task_updated" &&
         subtype !== "task_notification") {
-        return;
+        return false;
     }
     const taskId = typeof msg.task_id === "string" ? msg.task_id : "";
     const explicitToolUseId = typeof msg.tool_use_id === "string" ? msg.tool_use_id : "";
+    const messageTaskMetadata = sdkTaskMetadata(msg);
     if (taskId && explicitToolUseId) {
-        session.taskToolUseIds.set(taskId, explicitToolUseId);
+        linkTaskToolUse(session, taskId, explicitToolUseId);
     }
     const toolUseId = resolveTaskToolUseId(session, msg);
     bridgeLogger.debug({
@@ -142,6 +209,7 @@ export function handleTaskSystemMessage(session, subtype, msg) {
         });
     }
     if (!toolUseId) {
+        applyTaskLifecycleState(session, subtype, msg);
         if (subtype === "task_updated" && taskId) {
             bridgeLogger.debug({
                 target: LOG_TARGETS.APP_TOOL,
@@ -152,46 +220,54 @@ export function handleTaskSystemMessage(session, subtype, msg) {
                 fields: { task_id: taskId, subtype },
             });
         }
-        return;
+        return true;
     }
     const toolCall = ensureToolCallVisible(session, toolUseId, "Agent", {});
     if (!toolAcceptsTaskLifecycle(toolCall)) {
         if (taskId) {
-            session.taskToolUseIds.delete(taskId);
+            unlinkTaskToolUse(session, taskId);
         }
-        return;
+        return true;
     }
+    applyTaskLifecycleState(session, subtype, msg);
     if (toolCall.status === "pending") {
         emitToolCallUpdate(session, toolUseId, { status: "in_progress" }, "progress");
     }
     if (subtype === "task_started") {
         const description = typeof msg.description === "string" ? msg.description : "";
         if (!description) {
-            return;
+            return true;
         }
-        emitToolCallUpdate(session, toolUseId, {
+        const fields = {
             status: "in_progress",
             raw_output: description,
             content: [{ type: "content", content: { type: "text", text: description } }],
-        }, "task_started");
-        return;
+            ...(messageTaskMetadata ? { task_metadata: messageTaskMetadata } : {}),
+        };
+        emitToolCallUpdate(session, toolUseId, fields, "task_started");
+        return true;
     }
     if (subtype === "task_progress") {
         const progress = taskProgressText(msg);
         if (!progress) {
-            return;
+            return true;
         }
-        emitToolCallUpdate(session, toolUseId, {
+        const fields = {
             status: "in_progress",
             raw_output: progress,
             content: [{ type: "content", content: { type: "text", text: progress } }],
-        }, "task_progress");
-        return;
+            ...(messageTaskMetadata ? { task_metadata: messageTaskMetadata } : {}),
+        };
+        emitToolCallUpdate(session, toolUseId, fields, "task_progress");
+        return true;
     }
     if (subtype === "task_updated") {
         const fields = taskUpdatedFields(msg);
+        if (messageTaskMetadata) {
+            fields.task_metadata = { ...(fields.task_metadata ?? {}), ...messageTaskMetadata };
+        }
         if (Object.keys(fields).length === 0) {
-            return;
+            return true;
         }
         bridgeLogger.debug({
             target: LOG_TARGETS.APP_TOOL,
@@ -209,20 +285,117 @@ export function handleTaskSystemMessage(session, subtype, msg) {
             },
         });
         emitToolCallUpdate(session, toolUseId, fields, "task_updated");
-        return;
+        if (taskId && isTerminalToolStatus(fields.status)) {
+            unlinkTaskToolUse(session, taskId);
+        }
+        return true;
     }
     const status = typeof msg.status === "string" ? msg.status : "";
     const summary = typeof msg.summary === "string" ? msg.summary : "";
     const finalStatus = status === "completed" ? "completed" : status === "stopped" ? "killed" : "failed";
-    const fields = { status: finalStatus };
+    const deferCompletion = finalStatus === "completed" && defersTaskNotificationCompletion(toolCall);
+    const fields = deferCompletion ? {} : { status: finalStatus };
+    if (messageTaskMetadata) {
+        fields.task_metadata = messageTaskMetadata;
+    }
     if (summary) {
         fields.raw_output = summary;
         fields.content = [{ type: "content", content: { type: "text", text: summary } }];
     }
-    emitToolCallUpdate(session, toolUseId, fields, "task_notification");
-    if (taskId) {
-        session.taskToolUseIds.delete(taskId);
+    if (Object.keys(fields).length > 0) {
+        emitToolCallUpdate(session, toolUseId, fields, "task_notification");
+    }
+    if (taskId && !deferCompletion) {
+        unlinkTaskToolUse(session, taskId);
+    }
+    return true;
+}
+function stringField(msg, field) {
+    const value = msg[field];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function nullableStringField(msg, field) {
+    const value = msg[field];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function sourceMessageUuid(msg) {
+    return stringField(msg, "uuid");
+}
+function dedupeMessageUuids(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const seen = new Set();
+    const uuids = [];
+    for (const entry of value) {
+        if (typeof entry !== "string" || !entry) {
+            continue;
+        }
+        if (seen.has(entry)) {
+            continue;
+        }
+        seen.add(entry);
+        uuids.push(entry);
+    }
+    return uuids;
+}
+function emitTranscriptRetraction(session, messageUuids, reason, metadata = {}) {
+    const deduped = dedupeMessageUuids(messageUuids);
+    if (deduped.length === 0) {
+        return false;
     }
+    emitSessionUpdate(session.sessionId, {
+        type: "transcript_retraction",
+        message_uuids: deduped,
+        reason,
+        ...(metadata.requestId ? { request_id: metadata.requestId } : {}),
+        ...(metadata.trigger ? { trigger: metadata.trigger } : {}),
+        ...(metadata.direction ? { direction: metadata.direction } : {}),
+        ...(metadata.originalModel ? { original_model: metadata.originalModel } : {}),
+        ...(metadata.fallbackModel ? { fallback_model: metadata.fallbackModel } : {}),
+        ...(metadata.apiRefusalCategory ? { api_refusal_category: metadata.apiRefusalCategory } : {}),
+        ...(metadata.apiRefusalExplanation ? { api_refusal_explanation: metadata.apiRefusalExplanation } : {}),
+        ...(metadata.content ? { content: metadata.content } : {}),
+    });
+    return true;
+}
+function handleFallbackRetractionMessage(session, subtype, msg) {
+    if (subtype !== "model_refusal_fallback" && subtype !== "model_fallback") {
+        return false;
+    }
+    const reason = subtype === "model_fallback" ? "model_fallback" : "model_refusal_fallback";
+    const messageUuids = dedupeMessageUuids(msg.retracted_message_uuids);
+    const metadata = {
+        requestId: nullableStringField(msg, "request_id"),
+        trigger: stringField(msg, "trigger"),
+        direction: stringField(msg, "direction"),
+        originalModel: stringField(msg, "original_model"),
+        fallbackModel: stringField(msg, "fallback_model"),
+        apiRefusalCategory: nullableStringField(msg, "api_refusal_category"),
+        apiRefusalExplanation: nullableStringField(msg, "api_refusal_explanation"),
+        content: stringField(msg, "content"),
+    };
+    const emitted = emitTranscriptRetraction(session, messageUuids, reason, metadata);
+    bridgeLogger.info({
+        target: LOG_TARGETS.APP_SESSION,
+        eventName: "sdk_model_fallback_received",
+        message: "SDK model fallback retraction received",
+        outcome: emitted ? "success" : "observed",
+        sessionId: session.sessionId,
+        requestId: metadata.requestId,
+        count: messageUuids.length,
+        fields: {
+            sdk_subtype: subtype,
+            trigger: metadata.trigger,
+            direction: metadata.direction,
+            original_model: metadata.originalModel,
+            fallback_model: metadata.fallbackModel,
+            api_refusal_category: metadata.apiRefusalCategory,
+            has_api_refusal_explanation: metadata.apiRefusalExplanation !== undefined,
+            has_content: metadata.content !== undefined,
+        },
+    });
+    return true;
 }
 function logContentBlockLinkage(session, blockType, toolUseId, toolName, linkage) {
     if (!toolUseId && !linkage?.parentToolUseId) {
@@ -274,14 +447,22 @@ export function handleContentBlock(session, block, linkage) {
     if (blockType === "text") {
         const text = typeof block.text === "string" ? block.text : "";
         if (text) {
-            emitSessionUpdate(session.sessionId, { type: "agent_message_chunk", content: { type: "text", text } });
+            emitSessionUpdate(session.sessionId, {
+                type: "agent_message_chunk",
+                content: { type: "text", text },
+                ...(linkage?.sourceMessageUuid ? { source_message_uuid: linkage.sourceMessageUuid } : {}),
+            });
         }
         return;
     }
     if (blockType === "thinking") {
         const text = typeof block.thinking === "string" ? block.thinking : "";
         if (text) {
-            emitSessionUpdate(session.sessionId, { type: "agent_thought_chunk", content: { type: "text", text } });
+            emitSessionUpdate(session.sessionId, {
+                type: "agent_thought_chunk",
+                content: { type: "text", text },
+                ...(linkage?.sourceMessageUuid ? { source_message_uuid: linkage.sourceMessageUuid } : {}),
+            });
         }
         return;
     }
@@ -296,8 +477,7 @@ export function handleContentBlock(session, block, linkage) {
             return;
         }
         logContentBlockLinkage(session, blockType, toolUseId, name, linkage);
-        emitPlanIfTodoWrite(session, name, input);
-        emitToolCall(session, toolUseId, name, input, linkage?.parentToolUseId ?? null);
+        emitToolCall(session, toolUseId, name, input, linkage?.parentToolUseId ?? null, linkage?.metadata, linkage?.sourceMessageUuid);
         return;
     }
     if (TOOL_RESULT_TYPES.has(blockType)) {
@@ -310,16 +490,17 @@ export function handleContentBlock(session, block, linkage) {
         }
         logContentBlockLinkage(session, blockType, toolUseId, undefined, linkage);
         const isError = Boolean(block.is_error);
-        emitToolResultUpdate(session, toolUseId, isError, block.content, block);
+        emitToolResultUpdate(session, toolUseId, isError, block.content, block, linkage?.sourceMessageUuid);
     }
 }
-export function handleStreamEvent(session, event, parentToolUseId) {
+export function handleStreamEvent(session, event, parentToolUseId, sourceMessageUuid) {
     const eventType = typeof event.type === "string" ? event.type : "";
     if (eventType === "content_block_start") {
         if (event.content_block && typeof event.content_block === "object") {
             handleContentBlock(session, event.content_block, {
                 source: "stream_event",
                 parentToolUseId,
+                sourceMessageUuid,
             });
         }
         return;
@@ -333,22 +514,33 @@ export function handleStreamEvent(session, event, parentToolUseId) {
         if (deltaType === "text_delta") {
             const text = typeof delta.text === "string" ? delta.text : "";
             if (text) {
-                emitSessionUpdate(session.sessionId, { type: "agent_message_chunk", content: { type: "text", text } });
+                emitSessionUpdate(session.sessionId, {
+                    type: "agent_message_chunk",
+                    content: { type: "text", text },
+                    ...(sourceMessageUuid ? { source_message_uuid: sourceMessageUuid } : {}),
+                });
             }
         }
         else if (deltaType === "thinking_delta") {
             const text = typeof delta.thinking === "string" ? delta.thinking : "";
             if (text) {
-                emitSessionUpdate(session.sessionId, { type: "agent_thought_chunk", content: { type: "text", text } });
+                emitSessionUpdate(session.sessionId, {
+                    type: "agent_thought_chunk",
+                    content: { type: "text", text },
+                    ...(sourceMessageUuid ? { source_message_uuid: sourceMessageUuid } : {}),
+                });
             }
         }
     }
 }
 export function handleAssistantMessage(session, message) {
+    const assistantMessageUuid = sourceMessageUuid(message);
+    emitTranscriptRetraction(session, dedupeMessageUuids(message.supersedes), "assistant_supersedes");
     const assistantError = typeof message.error === "string" ? message.error : "";
     if (assistantError.length > 0) {
-        session.lastAssistantError = assistantError;
+        session.lastAssistantError = parseApiRetryError(assistantError);
     }
+    const metadata = sdkCorrelationMetadata(message);
     const messageObject = message.message && typeof message.message === "object"
         ? message.message
         : null;
@@ -367,18 +559,33 @@ export function handleAssistantMessage(session, message) {
             blockType === "mcp_tool_use" ||
             TOOL_RESULT_TYPES.has(blockType)) {
             const parentToolUseId = typeof message.parent_tool_use_id === "string" ? message.parent_tool_use_id : undefined;
-            handleContentBlock(session, blockRecord, { source: "assistant", parentToolUseId });
+            handleContentBlock(session, blockRecord, {
+                source: "assistant",
+                parentToolUseId,
+                metadata,
+                sourceMessageUuid: assistantMessageUuid,
+            });
         }
     }
 }
+function messageToolUseResult(message) {
+    if (Object.hasOwn(message, "toolUseResult")) {
+        return message.toolUseResult;
+    }
+    if (Object.hasOwn(message, "tool_use_result")) {
+        return message.tool_use_result;
+    }
+    return undefined;
+}
 export function handleUserToolResultBlocks(session, message) {
     const messageObject = message.message && typeof message.message === "object"
         ? message.message
         : null;
     if (!messageObject) {
-        return;
+        return false;
     }
     const content = Array.isArray(messageObject.content) ? messageObject.content : [];
+    let handled = false;
     for (const block of content) {
         if (!block || typeof block !== "object") {
             continue;
@@ -387,9 +594,23 @@ export function handleUserToolResultBlocks(session, message) {
         const blockType = typeof blockRecord.type === "string" ? blockRecord.type : "";
         if (TOOL_RESULT_TYPES.has(blockType)) {
             const parentToolUseId = typeof message.parent_tool_use_id === "string" ? message.parent_tool_use_id : undefined;
-            handleContentBlock(session, blockRecord, { source: "user", parentToolUseId });
+            const toolUseId = typeof blockRecord.tool_use_id === "string" ? blockRecord.tool_use_id : "";
+            if (!toolUseId) {
+                continue;
+            }
+            handled = true;
+            if (isHiddenToolResult(session, toolUseId, blockType)) {
+                continue;
+            }
+            logContentBlockLinkage(session, blockType, toolUseId, undefined, {
+                source: "user",
+                parentToolUseId,
+                sourceMessageUuid: sourceMessageUuid(message),
+            });
+            emitToolResultUpdate(session, toolUseId, Boolean(blockRecord.is_error), blockRecord.content, messageToolUseResult(message) ?? blockRecord, sourceMessageUuid(message));
         }
     }
+    return handled;
 }
 export function handleResultMessage(session, message) {
     emitFastModeUpdateIfChanged(session, message.fast_mode_state);
@@ -419,6 +640,7 @@ export function handleResultMessage(session, message) {
     finalizeOpenToolCalls(session, "failed");
     const errorKind = classifyTurnErrorKind(subtype, errors, assistantError);
     const fallback = subtype ? `turn failed: ${subtype}` : "turn failed";
+    const apiErrorStatus = numberField(message, "api_error_status", "apiErrorStatus");
     writeEvent({
         event: "turn_error",
         session_id: session.sessionId,
@@ -426,6 +648,7 @@ export function handleResultMessage(session, message) {
         error_kind: errorKind,
         ...(subtype ? { sdk_result_subtype: subtype } : {}),
         ...(assistantError ? { assistant_error: assistantError } : {}),
+        ...(apiErrorStatus !== undefined ? { api_error_status: apiErrorStatus } : {}),
         ...(terminalReason ? { terminal_reason: terminalReason } : {}),
     });
     session.lastAssistantError = undefined;
@@ -452,8 +675,96 @@ function terminalReasonFromValue(value) {
 export function handleSdkMessage(session, message) {
     const msg = message;
     const type = typeof msg.type === "string" ? msg.type : "";
+    logSdkMessageOrigin(session, msg);
     if (type === "system") {
         const subtype = typeof msg.subtype === "string" ? msg.subtype : "";
+        if (handleFallbackRetractionMessage(session, subtype, msg)) {
+            return;
+        }
+        if (subtype === "commands_changed") {
+            updateAvailableCommands(session, "commands_changed", mapSdkSlashCommands(msg.commands));
+            return;
+        }
+        if (subtype === "notification") {
+            const text = typeof msg.text === "string" ? msg.text : "";
+            emitSystemNoticeUpdate(session, notificationSeverity(msg.priority), text);
+            return;
+        }
+        if (subtype === "mirror_error") {
+            const error = typeof msg.error === "string" ? msg.error : "";
+            const key = asRecordOrNull(msg.key);
+            bridgeLogger.warn({
+                target: LOG_TARGETS.APP_SESSION,
+                eventName: "sdk_mirror_error_received",
+                message: "SDK transcript mirror error received",
+                outcome: "failure",
+                sessionId: session.sessionId,
+                fields: {
+                    error_message: error || undefined,
+                    project_key: typeof key?.projectKey === "string" ? key.projectKey : undefined,
+                    mirror_session_id: typeof key?.sessionId === "string" ? key.sessionId : undefined,
+                    subpath: typeof key?.subpath === "string" ? key.subpath : undefined,
+                },
+            });
+            return;
+        }
+        if (subtype === "plugin_install") {
+            const status = typeof msg.status === "string" ? msg.status : "";
+            const name = typeof msg.name === "string" ? msg.name : "";
+            const error = typeof msg.error === "string" ? msg.error : "";
+            bridgeLogger.info({
+                target: LOG_TARGETS.BRIDGE_SDK,
+                eventName: "sdk_plugin_install_received",
+                message: "SDK plugin install event received",
+                outcome: status === "failed" ? "failure" : status || "observed",
+                sessionId: session.sessionId,
+                fields: {
+                    plugin_status: status || undefined,
+                    plugin_name: name || undefined,
+                    error_message: error || undefined,
+                },
+            });
+            if (status === "failed") {
+                const subject = name ? ` ${name}` : "";
+                const suffix = error ? `: ${error}` : ".";
+                emitSystemNoticeUpdate(session, "warning", `Plugin install failed${subject}${suffix}`);
+            }
+            return;
+        }
+        if (subtype === "permission_denied") {
+            bridgeLogger.info({
+                target: LOG_TARGETS.BRIDGE_PERMISSION,
+                eventName: "sdk_permission_denied_received",
+                message: "SDK permission denied event received",
+                outcome: "denied",
+                sessionId: session.sessionId,
+                toolCallId: typeof msg.tool_use_id === "string" ? msg.tool_use_id : undefined,
+                fields: {
+                    tool_name: typeof msg.tool_name === "string" ? msg.tool_name : undefined,
+                    agent_id: typeof msg.agent_id === "string" ? msg.agent_id : undefined,
+                    decision_reason_type: typeof msg.decision_reason_type === "string" ? msg.decision_reason_type : undefined,
+                    decision_reason: typeof msg.decision_reason === "string" ? msg.decision_reason : undefined,
+                    denial_message: typeof msg.message === "string" ? msg.message : undefined,
+                },
+            });
+            return;
+        }
+        if (subtype === "memory_recall" || subtype === "thinking_tokens") {
+            bridgeLogger.debug({
+                target: LOG_TARGETS.BRIDGE_SDK,
+                eventName: "sdk_system_message_log_only",
+                message: "SDK system message handled with log-only policy",
+                outcome: "ignored",
+                sessionId: session.sessionId,
+                fields: {
+                    sdk_subtype: subtype,
+                    memory_count: Array.isArray(msg.memories) ? msg.memories.length : undefined,
+                    estimated_tokens: typeof msg.estimated_tokens === "number" ? msg.estimated_tokens : undefined,
+                    estimated_tokens_delta: typeof msg.estimated_tokens_delta === "number" ? msg.estimated_tokens_delta : undefined,
+                },
+            });
+            return;
+        }
         if (subtype === "api_retry") {
             const update = buildApiRetryUpdate(msg);
             if (update) {
@@ -502,12 +813,10 @@ export function handleSdkMessage(session, message) {
                 }
             }
             if (Array.isArray(msg.slash_commands)) {
-                const commands = msg.slash_commands
-                    .filter((entry) => typeof entry === "string")
-                    .map((name) => ({ name, description: "", input_hint: undefined }));
-                if (commands.length > 0) {
-                    emitSessionUpdate(session.sessionId, { type: "available_commands_update", commands });
-                }
+                updateAvailableCommands(session, "init_slash_commands", mapInitSlashCommands(msg.slash_commands));
+            }
+            if (Array.isArray(msg.mcp_servers)) {
+                emitMcpSnapshotFromStatuses(session, msg.mcp_servers, "init");
             }
             if (session.lastAvailableAgentsSignature === undefined && Array.isArray(msg.agents)) {
                 emitAvailableAgentsIfChanged(session, mapAvailableAgentsFromNames(msg.agents));
@@ -515,12 +824,8 @@ export function handleSdkMessage(session, message) {
             void session.query
                 .supportedCommands()
                 .then((commands) => {
-                const mapped = commands.map((command) => ({
-                    name: command.name,
-                    description: command.description ?? "",
-                    input_hint: command.argumentHint ?? undefined,
-                }));
-                emitSessionUpdate(session.sessionId, { type: "available_commands_update", commands: mapped });
+                const mapped = mapSdkSlashCommands(commands);
+                updateAvailableCommands(session, "supportedCommands", mapped);
             })
                 .catch(() => {
                 // Best-effort only; slash commands from init were already emitted.
@@ -544,6 +849,9 @@ export function handleSdkMessage(session, message) {
             if (msg.status === "compacting") {
                 emitSessionUpdate(session.sessionId, { type: "session_status_update", status: "compacting" });
             }
+            else if (msg.status === "requesting") {
+                emitSessionUpdate(session.sessionId, { type: "session_status_update", status: "requesting" });
+            }
             else if (msg.status === null) {
                 emitSessionUpdate(session.sessionId, { type: "session_status_update", status: "idle" });
             }
@@ -572,6 +880,7 @@ export function handleSdkMessage(session, message) {
                 emitSessionUpdate(session.sessionId, {
                     type: "agent_message_chunk",
                     content: { type: "text", text: content },
+                    ...(sourceMessageUuid(msg) ? { source_message_uuid: sourceMessageUuid(msg) } : {}),
                 });
             }
             return;
@@ -591,7 +900,19 @@ export function handleSdkMessage(session, message) {
             });
             return;
         }
-        handleTaskSystemMessage(session, subtype, msg);
+        if (handleTaskSystemMessage(session, subtype, msg)) {
+            return;
+        }
+        bridgeLogger.debug({
+            target: LOG_TARGETS.BRIDGE_SDK,
+            eventName: "sdk_system_message_unhandled",
+            message: "SDK system message ignored by explicit fallback policy",
+            outcome: "ignored",
+            sessionId: session.sessionId,
+            fields: {
+                sdk_subtype: subtype || undefined,
+            },
+        });
         return;
     }
     if (type === "prompt_suggestion") {
@@ -624,14 +945,17 @@ export function handleSdkMessage(session, message) {
     if (type === "stream_event") {
         if (msg.event && typeof msg.event === "object") {
             const parentToolUseId = typeof msg.parent_tool_use_id === "string" ? msg.parent_tool_use_id : undefined;
-            handleStreamEvent(session, msg.event, parentToolUseId);
+            handleStreamEvent(session, msg.event, parentToolUseId, sourceMessageUuid(msg));
         }
         return;
     }
     if (type === "tool_progress") {
         const toolUseId = typeof msg.tool_use_id === "string" ? msg.tool_use_id : "";
         const toolName = typeof msg.tool_name === "string" ? msg.tool_name : "Tool";
-        if (isHiddenToolUse(session, toolUseId, toolName)) {
+        const taskId = typeof msg.task_id === "string" ? msg.task_id : "";
+        const taskToolUseId = taskId ? session.taskToolUseIds.get(taskId) ?? "" : "";
+        const resolvedToolUseId = taskToolUseId || toolUseId;
+        if (isHiddenToolUse(session, resolvedToolUseId, toolName)) {
             return;
         }
         bridgeLogger.debug({
@@ -640,16 +964,17 @@ export function handleSdkMessage(session, message) {
             message: "SDK tool progress linkage observed",
             outcome: typeof msg.parent_tool_use_id === "string" ? "child" : "root_or_unknown",
             sessionId: session.sessionId,
-            toolCallId: toolUseId || undefined,
+            toolCallId: resolvedToolUseId || undefined,
             fields: {
                 tool_name: toolName,
                 tool_use_id: toolUseId || undefined,
                 parent_tool_use_id: typeof msg.parent_tool_use_id === "string" ? msg.parent_tool_use_id : undefined,
-                task_id: typeof msg.task_id === "string" ? msg.task_id : undefined,
+                task_id: taskId || undefined,
+                task_resolved_tool_use_id: taskToolUseId || undefined,
             },
         });
-        if (toolUseId) {
-            emitToolProgressUpdate(session, toolUseId, toolName);
+        if (resolvedToolUseId) {
+            emitToolProgressUpdate(session, resolvedToolUseId, toolName);
         }
         return;
     }
@@ -671,6 +996,23 @@ export function handleSdkMessage(session, message) {
     if (type === "rate_limit_event") {
         const rateLimitInfo = asRecordOrNull(msg.rate_limit_info);
         const update = buildRateLimitUpdate(msg.rate_limit_info);
+        const rawIsUsingOverage = typeof rateLimitInfo?.isUsingOverage === "boolean" ? rateLimitInfo.isUsingOverage : undefined;
+        const rawOverageInUse = typeof rateLimitInfo?.overageInUse === "boolean" ? rateLimitInfo.overageInUse : undefined;
+        if (rawIsUsingOverage !== undefined &&
+            rawOverageInUse !== undefined &&
+            rawIsUsingOverage !== rawOverageInUse) {
+            bridgeLogger.warn({
+                target: LOG_TARGETS.APP_SESSION,
+                eventName: "sdk_rate_limit_overage_spelling_conflict",
+                message: "SDK rate limit overage booleans conflict",
+                outcome: "using_overageInUse",
+                sessionId: session.sessionId,
+                fields: {
+                    raw_is_using_overage: rawIsUsingOverage,
+                    raw_overage_in_use: rawOverageInUse,
+                },
+            });
+        }
         bridgeLogger.debug({
             target: LOG_TARGETS.APP_SESSION,
             eventName: "sdk_rate_limit_event_received",
@@ -684,7 +1026,8 @@ export function handleSdkMessage(session, message) {
                 raw_resets_at: numberField(rateLimitInfo ?? {}, "resetsAt"),
                 raw_overage_status: typeof rateLimitInfo?.overageStatus === "string" ? rateLimitInfo.overageStatus : undefined,
                 raw_overage_resets_at: numberField(rateLimitInfo ?? {}, "overageResetsAt"),
-                raw_is_using_overage: typeof rateLimitInfo?.isUsingOverage === "boolean" ? rateLimitInfo.isUsingOverage : undefined,
+                raw_is_using_overage: rawIsUsingOverage,
+                raw_overage_in_use: rawOverageInUse,
                 raw_surpassed_threshold: numberField(rateLimitInfo ?? {}, "surpassedThreshold"),
                 parsed_status: update?.status,
                 parsed_rate_limit_type: update?.rate_limit_type,
@@ -712,14 +1055,15 @@ export function handleSdkMessage(session, message) {
         return;
     }
     if (type === "user") {
-        handleUserToolResultBlocks(session, msg);
+        const handledBlocks = handleUserToolResultBlocks(session, msg);
         const toolUseId = typeof msg.parent_tool_use_id === "string" ? msg.parent_tool_use_id : "";
-        if (toolUseId && "tool_use_result" in msg) {
+        const rawToolUseResult = messageToolUseResult(msg);
+        if (!handledBlocks && toolUseId && rawToolUseResult !== undefined) {
             if (session.hiddenToolUseIds.has(toolUseId)) {
                 return;
             }
-            const parsed = unwrapToolUseResult(msg.tool_use_result);
-            emitToolResultUpdate(session, toolUseId, parsed.isError, parsed.content, msg.tool_use_result);
+            const parsed = unwrapToolUseResult(rawToolUseResult);
+            emitToolResultUpdate(session, toolUseId, parsed.isError, parsed.content, rawToolUseResult, sourceMessageUuid(msg));
         }
         return;
     }