claude-code-rust 0.14.4 → 0.14.6

package/README.md

@@ -8,12 +8,12 @@ A native Rust terminal interface for Claude Code. Drop-in replacement for Anthro
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)
 
 <p align="center">
-  <img src="assets/banner.png" alt="Claude Code Rust running a Read tool call with syntax-highlighted output" width="900">
+  <img src="assets/demo.gif" alt="Claude Code Rust explaining the terminal problems its native Rust interface solves" width="900">
 </p>
 
 ## About
 
-Claude Code Rust replaces the stock Claude Code terminal interface with a native Rust binary built on [Ratatui](https://ratatui.rs/). It connects to the same Claude API through a local Agent SDK bridge. Core Claude Code functionality - tool calls, file editing, terminal commands, and permissions - works unchanged.
+Claude Code Rust replaces the stock Claude Code terminal interface with a native Rust binary built on [Ratatui](https://ratatui.rs/). It connects to the same Claude API through a local Agent SDK bridge. Core Claude Code functionality works unchanged, including tool calls, file editing, terminal commands, and permissions.
 
 ## Prerequisite
 
@@ -52,13 +52,13 @@ claude-rs
 Full documentation is available at [srothgan.github.io/claude-code-rust](https://srothgan.github.io/claude-code-rust/).
 
 > [!NOTE]
-> **Agent SDK billing unchanged.** Anthropic has paused the previously announced Agent SDK credit change. For now nothing changes: Claude Agent SDK usage — including `claude -p` and third-party apps like this one — still draws from your normal Claude subscription limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan).
+> **Agent SDK billing unchanged.** Anthropic has paused the previously announced Agent SDK credit change. For now nothing changes: Claude Agent SDK usage (including `claude -p` and third-party apps like this one) still draws from your normal Claude subscription limits. See [Use the Claude Agent SDK with your Claude plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan).
 
 ## Why
 
 The stock Claude Code TUI runs on Node.js with React Ink, which renders by redrawing full frames over raw ANSI escape codes. This causes real, widely-reported problems:
 
-- **Flickering**: The whole view is redrawn on every status update, causing constant flicker — bad enough to crash editors' integrated terminals during long sessions
+- **Flickering**: The whole view is redrawn on every status update, causing constant flicker (bad enough to crash editors' integrated terminals during long sessions)
 - **CPU**: Sustained high CPU even when idle, and runaway loops that spawn multiple background processes
 - **Memory**: 200-400MB baseline (and climbing with conversation length) vs ~20-50MB for a native binary
 - **Resize**: Window resizing leaves duplicated frames in scrollback, loses lines when shrinking, and can garble the display
@@ -66,7 +66,7 @@ The stock Claude Code TUI runs on Node.js with React Ink, which renders by redra
 - **Scrollback**: Hijacks the terminal's native scrollback, erasing history you can no longer scroll back to
 - **Paste**: Large pastes can flood stdout and freeze the terminal
 
-Claude Code Rust addresses these with a native terminal UI that uses diffed, direct terminal control via Crossterm and Ratatui -- no full-frame redraws and no React Ink rendering loop.
+Claude Code Rust addresses these with a native terminal UI that uses diffed, direct terminal control via Crossterm and Ratatui, with no full-frame redraws and no React Ink rendering loop.
 
 ## Documentation
 
@@ -96,9 +96,9 @@ This project is licensed under the [Apache License 2.0](LICENSE). Apache-2.0 was
 
 This project is not affiliated with, endorsed by, or supported by Anthropic.
 
-A quick note on where this project stands, since I know people worry about this kind of thing: claude-code-rust is a terminal UI that I wrote from scratch in Rust. It is not a fork, copy or port of the latest Claude Code source leak -- it talks to Anthropic's official [Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/agent-sdk) as a runtime dependency instead, the same way any other third-party tool would. No Anthropic source code was read or used as reference at any point during development.
+A quick note on where this project stands, since I know people worry about this kind of thing: claude-code-rust is a terminal UI that I wrote from scratch in Rust. It is not a fork, copy or port of the latest Claude Code source leak. It talks to Anthropic's official [Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/agent-sdk) as a runtime dependency instead, the same way any other third-party tool would. No Anthropic source code was read or used as reference at any point during development.
 
-The project authenticates through your existing Claude Code account via the Agent SDK, and the Agent SDK's terms allow building on top of it. Billing, credits, limits, and overage behavior are controlled by Anthropic, including any future changes Anthropic may make to how Agent SDK usage is metered. Other community projects do the same. As far as I can tell, using this project is fine -- but I am a single maintainer, not a lawyer. If anything changes on Anthropic's end, I will update this section and adjust the project accordingly.
+The project authenticates through your existing Claude Code account via the Agent SDK, and the Agent SDK's terms allow building on top of it. Billing, credits, limits, and overage behavior are controlled by Anthropic, including any future changes Anthropic may make to how Agent SDK usage is metered. Other community projects do the same. As far as I can tell, using this project is fine, but I am a single maintainer, not a lawyer. If anything changes on Anthropic's end, I will update this section and adjust the project accordingly.
 
 This project's source code is licensed under [Apache-2.0](LICENSE). The Agent SDK itself is proprietary and governed by [Anthropic's Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms).
 

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

@@ -1,3 +1,4 @@
+import { writeEvent } from "./events.js";
 import { bridgeLogger, LOG_TARGETS } from "./logger.js";
 export async function dispatchCancelTurnCommand(command, deps) {
     const session = deps.sessionById(command.session_id);
@@ -9,6 +10,11 @@ export async function dispatchCancelTurnCommand(command, deps) {
     const stillQueued = Array.isArray(receipt?.still_queued)
         ? receipt.still_queued.filter((entry) => typeof entry === "string")
         : [];
+    writeEvent({
+        event: "turn_interrupt_receipt",
+        session_id: command.session_id,
+        still_queued: stillQueued,
+    }, deps.requestId);
     if (stillQueued.length > 0) {
         bridgeLogger.info({
             target: LOG_TARGETS.APP_SESSION,

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

@@ -1,7 +1,7 @@
 import { buildModeState, markModeUnavailableForSession, permissionModeFailureLooksUnsupported, refreshSupportedModesForSession, toPermissionMode, } from "./commands.js";
 import { dispatchCancelTurnCommand } from "./command_dispatch.js";
 import { emitFastModeUpdate } from "./error_classification.js";
-import { emitSessionUpdate, slashError } from "./events.js";
+import { emitSessionUpdate, slashError, writeEvent } from "./events.js";
 import { bridgeLogger, LOG_TARGETS } from "./logger.js";
 import { emitCurrentModelUpdate, refreshCurrentModel, sessionById, shouldInvalidateResolvedRuntimeModel, } from "./session_lifecycle.js";
 export async function handleSessionControlCommand(command, requestId, deps) {
@@ -38,12 +38,38 @@ export async function handleSessionControlCommand(command, requestId, deps) {
 function handlePrompt(command, requestId, deps) {
     const session = requireSession(command.session_id, requestId);
     if (!session) {
+        writeEvent({
+            event: "user_message_rejected",
+            session_id: command.session_id,
+            message_uuid: command.message_uuid,
+            reason: "unknown session",
+        }, requestId);
         return;
     }
     const message = deps.buildPromptUserMessage(command, session.sessionId);
-    if (message) {
-        session.input.enqueue(message);
+    if (!message) {
+        writeEvent({
+            event: "user_message_rejected",
+            session_id: session.sessionId,
+            message_uuid: command.message_uuid,
+            reason: "prompt contained no supported content",
+        }, requestId);
+        return;
+    }
+    if (!session.input.enqueue(message)) {
+        writeEvent({
+            event: "user_message_rejected",
+            session_id: session.sessionId,
+            message_uuid: command.message_uuid,
+            reason: "session input is closed",
+        }, requestId);
+        return;
     }
+    writeEvent({
+        event: "user_message_queued",
+        session_id: session.sessionId,
+        message_uuid: command.message_uuid,
+    }, requestId);
 }
 async function setModel(command, requestId) {
     const session = requireSession(command.session_id, requestId);

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

@@ -107,7 +107,7 @@ async function getContextUsage(command, requestId) {
         return;
     }
     try {
-        const usage = await session.query.getContextUsage();
+        const usage = await session.query.getContextUsage({ detail: "summary" });
         if (typeof usage.model === "string" && usage.model.trim().length > 0) {
             session.resolvedRuntimeModelId = usage.model.trim();
             refreshCurrentModel(session, true);

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

@@ -262,6 +262,7 @@ export function parseCommandEnvelope(line) {
                 return {
                     command: "prompt",
                     session_id: expectString(raw, "session_id", "prompt"),
+                    message_uuid: expectString(raw, "message_uuid", "prompt"),
                     chunks: parsePromptChunks(raw, "prompt"),
                 };
             case "cancel_turn":

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

@@ -39,6 +39,7 @@ export function classifyTurnErrorKind(subtype, errors, assistantError) {
             return "plan_limit";
         case "authentication_failed":
             return "auth_required";
+        case "account_on_hold":
         case "oauth_org_not_allowed":
             return "account_access";
         case "model_not_found":

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

@@ -81,6 +81,7 @@ function taskSystemMetadata(msg, patch) {
     for (const key of [
         "error",
         "is_backgrounded",
+        "spawn_depth",
         "request_id",
         "subagent_type",
         "task_description",

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

@@ -146,6 +146,10 @@ function eventToolCallId(event) {
         case "mcp_auth_redirect":
         case "mcp_operation_error":
         case "mcp_set_servers_result":
+        case "user_message_queued":
+        case "user_message_started":
+        case "user_message_rejected":
+        case "turn_interrupt_receipt":
         case "turn_complete":
         case "turn_error":
         case "slash_error":
@@ -199,6 +203,7 @@ function protocolEventLevel(event) {
         case "elicitation_request":
         case "elicitation_complete":
         case "mcp_auth_redirect":
+        case "user_message_started":
         case "turn_complete":
             return "trace";
         case "sessions_listed":
@@ -209,6 +214,9 @@ function protocolEventLevel(event) {
         case "rewind_result":
         case "runtime_reload_completed":
         case "mcp_set_servers_result":
+        case "user_message_queued":
+        case "user_message_rejected":
+        case "turn_interrupt_receipt":
         case "mcp_snapshot":
             return "debug";
     }

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

@@ -289,6 +289,7 @@ export async function handleMcpSetServersCommand(session, command, requestId) {
         logMcpFailure("mcp_servers_set_failed", "failed to update MCP server configuration", command.session_id, message, requestId, { server_count: Object.keys(command.servers).length });
         emitMcpOperationError(command.session_id, { operation: "set-servers", message }, requestId);
         slashError(command.session_id, `failed to set MCP servers: ${message}`, requestId);
+        await handleMcpStatusCommand(session, requestId, "mcp_set_servers");
     }
 }
 export async function handleMcpAuthenticateCommand(session, command, requestId) {

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

@@ -2,7 +2,7 @@ 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, parseToolNonExecutionMetadata, } from "./tooling.js";
-import { emitToolCall, emitToolCallUpdate, emitToolResultUpdate, finalizeOpenToolCalls, emitToolProgressUpdate, emitToolSummaryUpdate, ensureToolCallVisible, resolveTaskToolUseId, defersTaskNotificationCompletion, toolAcceptsTaskLifecycle, taskProgressText, taskUpdatedFields, } from "./tool_calls.js";
+import { emitToolCall, emitToolCallUpdate, emitToolResultUpdate, finalizeOpenToolCalls, emitToolProgressUpdate, emitToolSummaryUpdate, ensureToolCallVisible, resolveTaskToolUseId, defersTaskNotificationCompletion, toolAcceptsTaskLifecycle, toolAcceptsTerminalTaskNotification, toolPreservesTaskNotificationOutput, taskProgressText, taskUpdatedFields, } from "./tool_calls.js";
 import { applyBackgroundTasksChanged, applyTaskLifecycleState, } from "./tasks.js";
 import { linkTaskToolUse, unlinkTaskToolUse } from "./task_links.js";
 import { emitAuthRequired, classifyTurnErrorKind, emitFastModeUpdate, emitFastModeUpdateIfChanged, setFastModeSnapshotIfChanged, } from "./error_classification.js";
@@ -13,6 +13,7 @@ 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";
+import { appendResourceLinks } from "./resource_links.js";
 export function textFromPrompt(command) {
     const chunks = command.chunks ?? [];
     return chunks
@@ -64,6 +65,11 @@ function sdkTaskMetadata(msg) {
     const summary = status && typeof msg.summary === "string" && msg.summary.length > 0
         ? msg.summary
         : undefined;
+    const spawnDepth = typeof msg.spawn_depth === "number" &&
+        Number.isSafeInteger(msg.spawn_depth) &&
+        msg.spawn_depth > 0
+        ? msg.spawn_depth
+        : undefined;
     const taskMetadata = {
         ...(metadata.requestId ? { request_id: metadata.requestId } : {}),
         ...(metadata.subagentType ? { subagent_type: metadata.subagentType } : {}),
@@ -80,6 +86,11 @@ function sdkTaskMetadata(msg) {
         ...(summary ? { summary } : {}),
         ...(status ? { terminal_status: status } : {}),
         ...(typeof msg.blocked === "boolean" ? { blocked: msg.blocked } : {}),
+        ...(typeof msg.is_backgrounded === "boolean"
+            ? { is_backgrounded: msg.is_backgrounded }
+            : {}),
+        ...(typeof msg.ambient === "boolean" ? { ambient: msg.ambient } : {}),
+        ...(spawnDepth !== undefined ? { spawn_depth: spawnDepth } : {}),
     };
     return Object.keys(taskMetadata).length > 0 ? taskMetadata : undefined;
 }
@@ -89,6 +100,44 @@ function sdkMessageOriginKind(msg) {
         : null;
     return typeof origin?.kind === "string" ? origin.kind : undefined;
 }
+function diagnosticToken(value) {
+    return typeof value === "string" && /^[a-z][a-z0-9_-]{0,63}$/i.test(value)
+        ? value
+        : undefined;
+}
+export function sdkMessageDiagnosticFields(msg) {
+    const event = asRecordOrNull(msg.event);
+    const delta = asRecordOrNull(event?.delta);
+    const uuidFields = Object.fromEntries(Object.entries(msg).filter(([key, value]) => key.toLowerCase().includes("uuid") && typeof value === "string"));
+    const hasParentToolUseId = Object.hasOwn(msg, "parent_tool_use_id");
+    const parentToolUseId = trimmedStringField(msg, "parent_tool_use_id");
+    return {
+        sdk_type: typeof msg.type === "string" ? msg.type : undefined,
+        sdk_subtype: typeof msg.subtype === "string" ? msg.subtype : undefined,
+        sdk_uuid: trimmedStringField(msg, "uuid"),
+        user_message_uuid: trimmedStringField(msg, "user_message_uuid"),
+        parent_tool_use_id: parentToolUseId,
+        parent_tool_use_scope: !hasParentToolUseId
+            ? "absent"
+            : msg.parent_tool_use_id === null
+                ? "root"
+                : parentToolUseId
+                    ? "child"
+                    : "other",
+        request_id: trimmedStringField(msg, "request_id"),
+        origin_kind: sdkMessageOriginKind(msg),
+        inner_event_type: diagnosticToken(event?.type),
+        inner_delta_type: diagnosticToken(delta?.type),
+        lifecycle_status: diagnosticToken(msg.status),
+        lifecycle_state: diagnosticToken(msg.state),
+        lifecycle_operation: diagnosticToken(msg.operation),
+        lifecycle_reason: diagnosticToken(msg.reason),
+        sdk_keys: Object.keys(msg).sort(),
+        ...(Object.keys(uuidFields).length > 0
+            ? { sdk_uuid_fields: uuidFields }
+            : {}),
+    };
+}
 function externalMessageUpdateFromSdkUser(msg) {
     const origin = asRecordOrNull(msg.origin);
     if (!origin) {
@@ -140,6 +189,9 @@ function externalMessageUpdateFromSdkUser(msg) {
                 origin.verifiedPeerPid >= 0
                 ? { verified_peer_pid: origin.verifiedPeerPid }
                 : {}),
+            ...(origin.fromMode === "bypass" || origin.fromMode === "prompting"
+                ? { from_mode: origin.fromMode }
+                : {}),
         },
     };
 }
@@ -168,6 +220,9 @@ function logSdkMessageOrigin(session, msg) {
             origin_verified_peer_pid: typeof origin?.verifiedPeerPid === "number"
                 ? origin.verifiedPeerPid
                 : undefined,
+            origin_from_mode: origin?.fromMode === "bypass" || origin?.fromMode === "prompting"
+                ? origin.fromMode
+                : undefined,
         },
     });
 }
@@ -475,7 +530,10 @@ export function handleTaskSystemMessage(session, subtype, msg) {
         return true;
     }
     const toolCall = ensureToolCallVisible(session, toolUseId, "Agent", {});
-    if (!toolAcceptsTaskLifecycle(toolCall)) {
+    const acceptsLifecycle = toolAcceptsTaskLifecycle(toolCall);
+    const acceptsTerminalNotification = subtype === "task_notification" &&
+        toolAcceptsTerminalTaskNotification(toolCall);
+    if (!acceptsLifecycle && !acceptsTerminalNotification) {
         if (taskId) {
             unlinkTaskToolUse(session, taskId);
         }
@@ -561,12 +619,16 @@ export function handleTaskSystemMessage(session, subtype, msg) {
     if (messageTaskMetadata) {
         fields.task_metadata = messageTaskMetadata;
     }
-    if (summary) {
+    if (summary && !toolPreservesTaskNotificationOutput(toolCall)) {
         fields.raw_output = summary;
         fields.content = [
             { type: "content", content: { type: "text", text: summary } },
         ];
     }
+    const contentWithResourceLinks = appendResourceLinks(fields.content, msg.resource_links);
+    if (contentWithResourceLinks !== undefined) {
+        fields.content = contentWithResourceLinks;
+    }
     if (Object.keys(fields).length > 0) {
         emitToolCallUpdate(session, toolUseId, fields, "task_notification");
     }
@@ -850,6 +912,27 @@ export function handleAssistantMessage(session, message) {
     const content = Array.isArray(messageObject.content)
         ? messageObject.content
         : [];
+    if (asRecordOrNull(message.context_usage)) {
+        const markdown = content
+            .flatMap((block) => {
+            const record = asRecordOrNull(block);
+            return record?.type === "text" &&
+                typeof record.text === "string" &&
+                record.text.trim().length > 0
+                ? [record.text]
+                : [];
+        })
+            .join("\n\n");
+        if (markdown.length > 0) {
+            emitSessionUpdate(session.sessionId, {
+                type: "agent_message_chunk",
+                content: { type: "text", text: markdown },
+                ...(assistantMessageUuid
+                    ? { source_message_uuid: assistantMessageUuid }
+                    : {}),
+            });
+        }
+    }
     for (const block of content) {
         if (!block || typeof block !== "object") {
             continue;
@@ -872,6 +955,40 @@ export function handleAssistantMessage(session, message) {
         }
     }
 }
+function emitUserMessageStarted(session, message, source) {
+    const messageUuid = trimmedStringField(message, "user_message_uuid");
+    if (!messageUuid) {
+        return;
+    }
+    emitUserMessageStartedForUuid(session, messageUuid, source);
+}
+function emitUserMessageStartedForUuid(session, messageUuid, source) {
+    writeEvent({
+        event: "user_message_started",
+        session_id: session.sessionId,
+        message_uuid: messageUuid,
+        source,
+    });
+}
+function handleCommandLifecycleMessage(session, message) {
+    const state = trimmedStringField(message, "state");
+    const commandUuid = trimmedStringField(message, "command_uuid");
+    if (state !== "started") {
+        return;
+    }
+    if (!commandUuid) {
+        bridgeLogger.warn({
+            target: LOG_TARGETS.BRIDGE_SDK,
+            eventName: "sdk_command_lifecycle_start_invalid",
+            message: "SDK command lifecycle start omitted its command UUID",
+            outcome: "ignored",
+            sessionId: session.sessionId,
+            fields: sdkMessageDiagnosticFields(message),
+        });
+        return;
+    }
+    emitUserMessageStartedForUuid(session, commandUuid, "command_lifecycle");
+}
 function messageToolUseResult(message) {
     if (Object.hasOwn(message, "toolUseResult")) {
         return message.toolUseResult;
@@ -924,8 +1041,13 @@ export function handleUserToolResultBlocks(session, message) {
     return handled;
 }
 export function handleResultMessage(session, message) {
+    if (message.parent_tool_use_id === null ||
+        message.parent_tool_use_id === undefined) {
+        emitUserMessageStarted(session, message, "result");
+    }
     emitFastModeUpdateIfChanged(session, message.fast_mode_state, message.fast_mode_disabled_reason);
     const terminalReason = terminalReasonFromValue(message.terminal_reason);
+    const queuedTurnCount = nonNegativeIntegerField(message, "queued_turn_count");
     const subtype = typeof message.subtype === "string" ? message.subtype : "";
     if (subtype === "success") {
         session.lastAssistantError = undefined;
@@ -933,6 +1055,9 @@ export function handleResultMessage(session, message) {
         writeEvent({
             event: "turn_complete",
             session_id: session.sessionId,
+            ...(queuedTurnCount !== undefined
+                ? { queued_turn_count: queuedTurnCount }
+                : {}),
             ...(terminalReason ? { terminal_reason: terminalReason } : {}),
         });
         return;
@@ -977,6 +1102,9 @@ export function handleResultMessage(session, message) {
         event: "turn_error",
         session_id: session.sessionId,
         message: errors.length > 0 ? errors.join("\n") : fallback,
+        ...(queuedTurnCount !== undefined
+            ? { queued_turn_count: queuedTurnCount }
+            : {}),
         error_kind: errorKind,
         ...(subtype ? { sdk_result_subtype: subtype } : {}),
         ...(assistantError ? { assistant_error: assistantError } : {}),
@@ -1370,6 +1498,10 @@ export function handleSdkMessage(session, message) {
         return;
     }
     if (type === "stream_event") {
+        if (msg.parent_tool_use_id === null ||
+            msg.parent_tool_use_id === undefined) {
+            emitUserMessageStarted(session, msg, "stream_event");
+        }
         if (msg.event && typeof msg.event === "object") {
             const parentToolUseId = typeof msg.parent_tool_use_id === "string"
                 ? msg.parent_tool_use_id
@@ -1544,10 +1676,29 @@ export function handleSdkMessage(session, message) {
         if (msg.error === "authentication_failed") {
             emitAuthRequired(session);
         }
+        if (msg.parent_tool_use_id === null ||
+            msg.parent_tool_use_id === undefined) {
+            emitUserMessageStarted(session, msg, "assistant");
+        }
         handleAssistantMessage(session, msg);
         return;
     }
     if (type === "result") {
         handleResultMessage(session, msg);
+        return;
+    }
+    // Bundled Claude Code 2.1.258 emits this runtime frame even though the
+    // corresponding SDK 0.3.258 TypeScript union does not declare it.
+    if (type === "command_lifecycle") {
+        handleCommandLifecycleMessage(session, msg);
+        return;
     }
+    bridgeLogger.debug({
+        target: LOG_TARGETS.BRIDGE_SDK,
+        eventName: "sdk_message_unhandled",
+        message: "SDK message ignored by explicit top-level fallback policy",
+        outcome: "ignored",
+        sessionId: session.sessionId,
+        fields: sdkMessageDiagnosticFields(msg),
+    });
 }

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

@@ -0,0 +1,102 @@
+import { asRecordOrNull } from "./shared.js";
+const MAX_RESOURCE_LINKS = 50;
+const MAX_RESOURCE_LINK_BYTES = 64 * 1024;
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0
+        ? value.trim()
+        : undefined;
+}
+function jsonValue(value) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value) ? value : undefined;
+    }
+    if (Array.isArray(value)) {
+        const entries = [];
+        for (const entry of value) {
+            const parsed = jsonValue(entry);
+            if (parsed === undefined) {
+                return undefined;
+            }
+            entries.push(parsed);
+        }
+        return entries;
+    }
+    const record = asRecordOrNull(value);
+    if (!record) {
+        return undefined;
+    }
+    const parsed = [];
+    for (const [key, entry] of Object.entries(record)) {
+        const value = jsonValue(entry);
+        if (value === undefined) {
+            return undefined;
+        }
+        parsed.push([key, value]);
+    }
+    return Object.fromEntries(parsed);
+}
+function resourceLinkContent(value) {
+    const link = asRecordOrNull(value);
+    const uri = nonEmptyString(link?.uri);
+    const name = nonEmptyString(link?.name);
+    if (!link || !uri || !name) {
+        return undefined;
+    }
+    const title = nonEmptyString(link.title);
+    const description = nonEmptyString(link.description);
+    const mimeType = nonEmptyString(link.mimeType);
+    const size = typeof link.size === "number" &&
+        Number.isSafeInteger(link.size) &&
+        link.size >= 0
+        ? link.size
+        : undefined;
+    const annotationsValue = link.annotations === undefined ? undefined : jsonValue(link.annotations);
+    const annotations = asRecordOrNull(annotationsValue);
+    if (link.annotations !== undefined && !annotations) {
+        return undefined;
+    }
+    return {
+        type: "resource_link",
+        uri,
+        name,
+        ...(title ? { title } : {}),
+        ...(description ? { description } : {}),
+        ...(mimeType ? { mime_type: mimeType } : {}),
+        ...(size !== undefined ? { size } : {}),
+        ...(annotations ? { annotations } : {}),
+    };
+}
+export function resourceLinkContents(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const links = [];
+    let serializedBytes = 2;
+    for (const entry of value) {
+        if (links.length >= MAX_RESOURCE_LINKS) {
+            break;
+        }
+        const link = resourceLinkContent(entry);
+        if (!link) {
+            continue;
+        }
+        const linkBytes = Buffer.byteLength(JSON.stringify(link));
+        const separatorBytes = links.length > 0 ? 1 : 0;
+        if (serializedBytes + separatorBytes + linkBytes >
+            MAX_RESOURCE_LINK_BYTES) {
+            continue;
+        }
+        serializedBytes += separatorBytes + linkBytes;
+        links.push(link);
+    }
+    return links;
+}
+export function appendResourceLinks(content, value) {
+    const links = resourceLinkContents(value);
+    return links.length > 0 ? [...(content ?? []), ...links] : content;
+}

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

@@ -344,6 +344,9 @@ export async function createSession(params) {
             history_update_count: historyUpdateCount,
             stale_session_count: staleSessionCount,
             stale_session_before_register_count: staleSessionBeforeRegisterCount,
+            sdk_debug_enabled: enableSdkDebug,
+            sdk_debug_file_configured: Boolean(sdkDebugFile),
+            sdk_spawn_debug_enabled: enableSpawnDebug,
         },
     });
     try {
@@ -608,7 +611,7 @@ export async function awaitSessionInitialization(session) {
         // the protocol barrier proving that startup messages have reached the SDK; yield
         // once more so the bridge's query consumer can process the already-enqueued result.
         try {
-            await session.query.getContextUsage();
+            await session.query.getContextUsage({ detail: "summary" });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -762,6 +765,9 @@ function systemPromptFromLaunchSettings(launchSettings) {
         type: "preset",
         preset: "claude_code",
         append: appendLines.join(" "),
+        // Keep the prompt prefix stable across resume. Updated host language or guard text
+        // intentionally takes effect after SDK compaction or in a new session.
+        snapshot: true,
     };
 }
 export function buildQueryOptions(params) {
@@ -802,11 +808,15 @@ export function buildQueryOptions(params) {
         },
         spawnClaudeCodeProcess: (options) => {
             const command = resolveClaudeCodeSpawnCommand(options.command);
-            const spawnOptions = { ...options, command };
+            const env = { ...options.env };
+            if (env.CLAUDE_CODE_ENABLE_TODO_TOOLS === undefined) {
+                env.CLAUDE_CODE_ENABLE_TODO_TOOLS = "1";
+            }
+            const spawnOptions = { ...options, command, env };
             logSdkProcessSpawnStarted(spawnOptions, params.enableSpawnDebug);
             const child = spawnChild(command, options.args, {
                 cwd: options.cwd,
-                env: options.env,
+                env,
                 signal: options.signal,
                 stdio: ["pipe", "pipe", "pipe"],
                 windowsHide: true,
@@ -945,8 +955,7 @@ export function buildQueryOptions(params) {
         // the CLI emits `request_user_dialog` and the host renders the chooser below.
         supportedDialogKinds: [REFUSAL_FALLBACK_DIALOG_KIND],
         // Host policy for `request_user_dialog` control requests. Unknown kinds are
-        // logged and answered `{ behavior: "cancelled" }` (the spec-required answer
-        // for unrecognized kinds). For `refusal_fallback_prompt`, we surface an
+        // logged and left unsettled by returning `null`. For `refusal_fallback_prompt`, we surface an
         // interactive chooser in the TUI and route the user's decision back to the
         // CLI as `{ behavior: "completed", result: <choice> }` (or cancelled on
         // decline/abort/teardown).
@@ -955,15 +964,15 @@ export function buildQueryOptions(params) {
                 bridgeLogger.warn({
                     target: LOG_TARGETS.APP_SESSION,
                     eventName: "user_dialog_received",
-                    message: "request_user_dialog received for unknown kind; cancelled",
-                    outcome: "cancelled",
+                    message: "request_user_dialog received for unknown kind; unsupported",
+                    outcome: "unsupported",
                     sessionId: params.sessionIdForLogs(),
                     ...(typeof request.toolUseID === "string"
                         ? { toolCallId: request.toolUseID }
                         : {}),
                     fields: { dialog_kind: request.dialogKind },
                 });
-                return { behavior: "cancelled" };
+                return null;
             }
             const payload = normalizeRefusalFallbackPayload(request.payload);
             const requestId = options.requestId;

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

@@ -10,14 +10,15 @@ export class AsyncQueue {
     closed = false;
     enqueue(item) {
         if (this.closed) {
-            return;
+            return false;
         }
         const waiter = this.waiters.shift();
         if (waiter) {
             waiter({ value: item, done: false });
-            return;
+            return true;
         }
         this.items.push(item);
+        return true;
     }
     close() {
         if (this.closed) {

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

@@ -77,6 +77,7 @@ export function parseRuntimeSessionState(value) {
 export function parseApiRetryError(value) {
     switch (value) {
         case "authentication_failed":
+        case "account_on_hold":
         case "oauth_org_not_allowed":
         case "billing_error":
         case "rate_limit":

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

@@ -831,6 +831,7 @@ function lifecycleMetadata(msg) {
     for (const key of [
         "error",
         "is_backgrounded",
+        "spawn_depth",
         "request_id",
         "subagent_type",
         "task_description",
@@ -843,6 +844,7 @@ function lifecycleMetadata(msg) {
         "total_paused_ms",
         "blocked",
         "parent_agent_id",
+        "ambient",
     ]) {
         copyValue(msg, key);
         copyValue(patch, key);
@@ -911,6 +913,7 @@ export function applyBackgroundTasksChanged(session, msg) {
         }
         const taskType = nonEmptyString(task.task_type);
         const description = nonEmptyString(task.description);
+        const ambient = typeof task.ambient === "boolean" ? task.ambient : undefined;
         return {
             task_id: taskId,
             subject: description ?? taskType ?? taskId,
@@ -921,6 +924,7 @@ export function applyBackgroundTasksChanged(session, msg) {
             metadata: {
                 [BACKGROUND_TASK_METADATA_KEY]: true,
                 ...(taskType ? { task_type: taskType } : {}),
+                ...(ambient !== undefined ? { ambient } : {}),
             },
         };
     })

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

@@ -4,6 +4,7 @@ import { asRecordOrNull } from "./shared.js";
 import { applyTaskToolResult } from "./tasks.js";
 import { activeTaskIdForToolUse, linkTaskToolUse, unlinkTaskToolUse, } from "./task_links.js";
 import { applyToolNonExecutionMetadata, backgroundToolLaunchTaskIdFromResult, buildToolResultFields, createToolCall, } from "./tooling.js";
+import { appendResourceLinks } from "./resource_links.js";
 const TOOL_SUMMARY_TOOL_NAMES = new Set([
     "Agent",
     "Task",
@@ -62,6 +63,16 @@ export function toolAcceptsTaskLifecycle(base) {
     const baseToolName = toolName(base);
     return Boolean(baseToolName && TASK_LIFECYCLE_TOOL_NAMES.has(baseToolName));
 }
+export function toolAcceptsTerminalTaskNotification(base) {
+    const baseToolName = toolName(base);
+    return Boolean(baseToolName &&
+        (TASK_LIFECYCLE_TOOL_NAMES.has(baseToolName) ||
+            baseToolName === "Bash" ||
+            baseToolName.startsWith("mcp__")));
+}
+export function toolPreservesTaskNotificationOutput(base) {
+    return toolName(base) === "Bash";
+}
 export function defersTaskNotificationCompletion(base) {
     const baseToolName = toolName(base);
     return baseToolName === "Agent" || baseToolName === "Task";
@@ -353,6 +364,11 @@ export function emitToolResultUpdate(session, toolUseId, isError, rawContent, ra
     const base = session.toolCalls.get(toolUseId);
     const baseToolName = toolNameFromMeta(base?.meta) ?? "";
     const fields = buildToolResultFields(isError, rawContent, base, rawResult, taskTitleContext(session, baseToolName, asRecordOrNull(base?.raw_input) ?? {}));
+    const resultRecord = asRecordOrNull(rawResult);
+    const contentWithResourceLinks = appendResourceLinks(fields.content, resultRecord?.resourceLinks);
+    if (contentWithResourceLinks !== undefined) {
+        fields.content = contentWithResourceLinks;
+    }
     applyToolNonExecutionMetadata(fields, nonExecutionMetadata);
     if (!isError && !nonExecutionMetadata) {
         const taskId = backgroundToolLaunchTaskIdFromResult(baseToolName, rawResult, rawContent);
@@ -374,7 +390,7 @@ export function finalizeOpenToolCalls(session, status) {
         if (toolCall.status !== "pending" && toolCall.status !== "in_progress") {
             continue;
         }
-        if (toolAcceptsTaskLifecycle(toolCall) &&
+        if (toolAcceptsTerminalTaskNotification(toolCall) &&
             activeTaskIdForToolUse(session, toolUseId)) {
             continue;
         }

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

@@ -627,9 +627,14 @@ function extractToolOutputMetadata(toolName, rawResult, rawContent) {
             const artifactRead = asRecordOrNull(candidate.artifactRead);
             const slug = nonEmptyString(artifactRead?.slug);
             const ver = nonEmptyString(artifactRead?.ver);
-            if (slug && ver) {
+            const seeded = artifactRead?.seeded === false ? false : undefined;
+            if (slug) {
                 const webFetchMetadata = {
-                    artifact_read: { slug, ver },
+                    artifact_read: {
+                        slug,
+                        ...(ver ? { ver } : {}),
+                        ...(seeded === false ? { seeded } : {}),
+                    },
                 };
                 metadata.web_fetch = webFetchMetadata;
                 break;
@@ -838,49 +843,87 @@ function editDiffFromInput(rawInput) {
         },
     ];
 }
-function writeDiffFromResult(rawContent) {
-    const candidates = Array.isArray(rawContent) ? rawContent : [rawContent];
+function boundedDisplayText(value, maxCharacters = 240) {
+    return value.length > maxCharacters
+        ? `${value.slice(0, maxCharacters - 3)}...`
+        : value;
+}
+function writeResultPresentation(rawContent) {
+    const candidates = resultRecordCandidates(rawContent, undefined);
+    const parsed = parseJsonCandidate(rawContent);
+    if (parsed !== undefined) {
+        candidates.push(...resultRecordCandidates(parsed, undefined));
+    }
     for (const candidate of candidates) {
-        const record = asRecordOrNull(candidate);
-        if (!record) {
-            continue;
-        }
+        const record = candidate;
         const filePath = typeof record.filePath === "string"
             ? record.filePath
             : typeof record.file_path === "string"
                 ? record.file_path
                 : "";
-        const content = typeof record.content === "string" ? record.content : "";
+        const content = typeof record.content === "string" ? record.content : undefined;
         const originalRaw = "originalFile" in record
             ? record.originalFile
             : "original_file" in record
                 ? record.original_file
                 : undefined;
-        const gitDiff = asRecordOrNull(record.gitDiff);
+        const gitDiff = asRecordOrNull(record.gitDiff ?? record.git_diff);
         const repository = typeof gitDiff?.repository === "string" &&
             gitDiff.repository.trim().length > 0
             ? gitDiff.repository.trim()
             : undefined;
-        if (!filePath || !content || originalRaw === undefined) {
+        if (!filePath || originalRaw === undefined) {
             continue;
         }
-        const original = typeof originalRaw === "string"
-            ? originalRaw
-            : originalRaw === null
-                ? ""
-                : "";
-        return [
-            {
-                type: "diff",
-                old_path: filePath,
-                new_path: filePath,
-                old: original,
-                new: content,
-                ...(repository ? { repository } : {}),
-            },
-        ];
+        if (originalRaw === null) {
+            if (record.type === "create" && content !== undefined) {
+                return {
+                    kind: "diff",
+                    content: [
+                        {
+                            type: "diff",
+                            old_path: filePath,
+                            new_path: filePath,
+                            old: "",
+                            new: content,
+                            ...(repository ? { repository } : {}),
+                        },
+                    ],
+                };
+            }
+            return {
+                kind: "text",
+                text: record.type === "create"
+                    ? `Created ${boundedDisplayText(filePath)}; the written content was unavailable, so a diff could not be displayed.`
+                    : `Updated ${boundedDisplayText(filePath)}; the previous content was unavailable, so a diff could not be displayed.`,
+            };
+        }
+        if (content === undefined) {
+            continue;
+        }
+        if (typeof originalRaw === "string") {
+            if (originalRaw === content) {
+                return {
+                    kind: "text",
+                    text: `No changes to ${boundedDisplayText(filePath)}.`,
+                };
+            }
+            return {
+                kind: "diff",
+                content: [
+                    {
+                        type: "diff",
+                        old_path: filePath,
+                        new_path: filePath,
+                        old: originalRaw,
+                        new: content,
+                        ...(repository ? { repository } : {}),
+                    },
+                ],
+            };
+        }
     }
-    return [];
+    return undefined;
 }
 function editDiffFromResult(rawResult, rawInput) {
     const input = asRecordOrNull(rawInput);
@@ -1736,7 +1779,11 @@ function hasConcreteReplField(record) {
         "stderr" in record ||
         "registeredTools" in record ||
         "images" in record ||
-        "documents" in record);
+        "documents" in record ||
+        "imagesOmitted" in record ||
+        "imagePagesFailed" in record ||
+        "imagePagesFailedOmitted" in record ||
+        "documentsOmitted" in record);
 }
 function isReplWrapperRecord(record) {
     const nestedResult = asRecordOrNull(record.result);
@@ -1796,6 +1843,46 @@ function replResultFields(toolName, rawResult, rawContent) {
         if (Array.isArray(candidate.documents) && candidate.documents.length > 0) {
             lines.push(`Documents: ${candidate.documents.length}`);
         }
+        const imagesOmitted = nonNegativeInteger(candidate.imagesOmitted);
+        if (imagesOmitted !== undefined && imagesOmitted > 0) {
+            lines.push(`Images omitted: ${imagesOmitted}`);
+        }
+        const failedPages = Array.isArray(candidate.imagePagesFailed)
+            ? candidate.imagePagesFailed
+            : [];
+        const failedPageLimit = 20;
+        let renderedFailedPages = 0;
+        let locallyOmittedFailedPages = 0;
+        for (const value of failedPages) {
+            const failedPage = asRecordOrNull(value);
+            const page = nonNegativeInteger(failedPage?.page);
+            if (!failedPage || page === undefined) {
+                continue;
+            }
+            if (renderedFailedPages >= failedPageLimit) {
+                locallyOmittedFailedPages += 1;
+                continue;
+            }
+            const file = nonEmptyString(failedPage.file);
+            const error = nonEmptyString(failedPage.error);
+            const context = [
+                file ? `file ${boundedDisplayText(file)}` : undefined,
+                error ? boundedDisplayText(error) : undefined,
+            ]
+                .filter((value) => value !== undefined)
+                .join(": ");
+            lines.push(`Failed image page: ${page}${context ? ` (${context})` : ""}`);
+            renderedFailedPages += 1;
+        }
+        const upstreamFailedPagesOmitted = nonNegativeInteger(candidate.imagePagesFailedOmitted) ?? 0;
+        const failedPagesOmitted = upstreamFailedPagesOmitted + locallyOmittedFailedPages;
+        if (failedPagesOmitted > 0) {
+            lines.push(`Failed image pages omitted: ${failedPagesOmitted}`);
+        }
+        const documentsOmitted = nonNegativeInteger(candidate.documentsOmitted);
+        if (documentsOmitted !== undefined && documentsOmitted > 0) {
+            lines.push(`Documents omitted: ${documentsOmitted}`);
+        }
         return { output: lines.length > 0 ? lines.join("\n") : undefined, failed };
     }
     return undefined;
@@ -1982,6 +2069,20 @@ function workflowResultFields(toolName, rawResult, rawContent) {
     return undefined;
 }
 function backgroundLaunchResultFields(toolName, rawResult, rawContent) {
+    if (isShellToolName(toolName)) {
+        const record = findShellResultRecord(rawResult, rawContent);
+        const taskId = typeof record?.backgroundTaskId === "string"
+            ? record.backgroundTaskId.trim()
+            : "";
+        if (record && taskId) {
+            return {
+                output: buildShellDisplayOutput(record),
+                taskId,
+                failed: false,
+                keepRunning: true,
+            };
+        }
+    }
     return (monitorResultFields(toolName, rawResult, rawContent) ??
         workflowResultFields(toolName, rawResult, rawContent));
 }
@@ -2295,9 +2396,16 @@ export function buildToolResultFields(isError, rawContent, base, rawResult, _con
         }
     }
     if (!isError && toolName === "Write") {
-        const structuredDiff = writeDiffFromResult(rawContent);
-        if (structuredDiff.length > 0) {
-            fields.content = structuredDiff;
+        const presentation = writeResultPresentation(rawContent);
+        if (presentation?.kind === "diff") {
+            fields.content = presentation.content;
+            return fields;
+        }
+        if (presentation?.kind === "text") {
+            fields.raw_output = presentation.text;
+            fields.content = [
+                { type: "content", content: { type: "text", text: presentation.text } },
+            ];
             return fields;
         }
         const inputDiff = writeDiffFromInput(base?.raw_input);

package/agent-sdk/dist/bridge.js

@@ -167,6 +167,7 @@ export function buildPromptUserMessage(command, sessionId) {
     }
     return {
         type: "user",
+        uuid: command.message_uuid,
         session_id: sessionId,
         parent_tool_use_id: null,
         origin: { kind: "human" },
@@ -194,7 +195,7 @@ export function emitAgentConfigOptionUpdate(sessionId, agent) {
         value: agent,
     });
 }
-const EXPECTED_AGENT_SDK_VERSION = "0.3.227";
+const EXPECTED_AGENT_SDK_VERSION = "0.3.258";
 const require = createRequire(import.meta.url);
 export function resolveInstalledAgentSdkVersion() {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-rust",
-  "version": "0.14.4",
+  "version": "0.14.6",
   "description": "Claude Code Rust - native Rust terminal interface for Claude Code",
   "keywords": [
     "cli",
@@ -33,15 +33,15 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "0.3.227"
+    "@anthropic-ai/claude-agent-sdk": "0.3.258"
   },
   "optionalDependencies": {
-    "@srothgan/claude-code-rust-darwin-arm64": "0.14.4",
-    "@srothgan/claude-code-rust-darwin-x64": "0.14.4",
-    "@srothgan/claude-code-rust-linux-x64-gnu": "0.14.4",
-    "@srothgan/claude-code-rust-linux-arm64-gnu": "0.14.4",
-    "@srothgan/claude-code-rust-win32-x64-msvc": "0.14.4",
-    "@srothgan/claude-code-rust-win32-arm64-msvc": "0.14.4"
+    "@srothgan/claude-code-rust-darwin-arm64": "0.14.6",
+    "@srothgan/claude-code-rust-darwin-x64": "0.14.6",
+    "@srothgan/claude-code-rust-linux-x64-gnu": "0.14.6",
+    "@srothgan/claude-code-rust-linux-arm64-gnu": "0.14.6",
+    "@srothgan/claude-code-rust-win32-x64-msvc": "0.14.6",
+    "@srothgan/claude-code-rust-win32-arm64-msvc": "0.14.6"
   },
   "engines": {
     "node": ">=24"