@khorsheed/dsh-local-agent-claude-code 0.2.0-rc.3 → 0.2.0

package/lib/types/claude-cli-provider.js

@@ -22,6 +22,14 @@ import { assertResumeCwdUnchanged, assertResumeScopeUnchanged, resolveRoundModel
 import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from '@khorsheed/dsh-local-agent/types';
 import { LiveChannelUnavailableError } from './live-driver.js';
 import { endpointAuthEnv } from './endpoint-auth.js';
+/**
+ * The synthesized result for a call whose result the stream never recorded
+ * (a settle-pass fold after a kill or a truncated stream). The released-log
+ * contract resolves every advertised call before its step closes, so an
+ * interrupted call folds with this error result. Shared verbatim with the
+ * kimi provider (`KIMI_INTERRUPTED_TOOL_RESULT`) so the family reads one text.
+ */
+export const CLAUDE_INTERRUPTED_TOOL_RESULT = '（工具调用被中断，未能记录返回结果）';
 /** Default POSIX grace between subprocess termination tiers. */
 export const DEFAULT_DISPOSE_GRACE_MS = 3_000;
 /**
@@ -33,6 +41,11 @@ export const DEFAULT_DISPOSE_GRACE_MS = 3_000;
  * provider-controlled error strings only.
  */
 export const CLAUDE_AUTH_FAILURE = /failed to authenticate|authentication_failed|oauth access token|invalid (x-api-key|api key|authentication token)|api error: 40[13]/i;
+/**
+ * The MCP tool-call bound for a member's claude process (`MCP_TOOL_TIMEOUT`,
+ * ms): a bridge call may wait up to 30 minutes for the human's answer.
+ */
+export const MEMBER_TOOL_TIMEOUT_MS = String(30 * 60_000);
 /** Register one member run with the channel; see {@link ClaudeMemberRunHandle}. */
 export function registerClaudeMemberRun(ctx, childSessionId, parentSessionId) {
     const registry = ctx.localAgent;
@@ -349,6 +362,8 @@ export class ClaudeCliProvider {
                 cwd,
                 env: delegationEnv({
                     CLAUDE_CONFIG_DIR: homeDir,
+                    // A bridge call may wait for the human (see MEMBER_TOOL_TIMEOUT_MS).
+                    ...member === undefined ? {} : { MCP_TOOL_TIMEOUT: MEMBER_TOOL_TIMEOUT_MS },
                     ...endpointAuthEnv(endpoint),
                 }),
                 ...exec === undefined ? {} : { exec },
@@ -462,6 +477,7 @@ export class ClaudeCliProvider {
                     cwd,
                     env: delegationEnv({
                         CLAUDE_CONFIG_DIR: homeDir,
+                        ...member === undefined ? {} : { MCP_TOOL_TIMEOUT: MEMBER_TOOL_TIMEOUT_MS },
                         ...endpointAuthEnv(endpoint),
                     }),
                     ...exec === undefined ? {} : { exec },
@@ -532,6 +548,19 @@ export function textTask(prompt) {
     }
     return texts.join('\n');
 }
+/** Group the lines of one API call (consecutive lines sharing a message id).
+ * Lines without an id stay singleton units (the pre-grouping shape). */
+export function groupClaudeTranscriptLines(lines) {
+    const groups = [];
+    for (const line of lines) {
+        const last = groups[groups.length - 1];
+        if (line.messageId !== undefined && last !== undefined && last[0]?.messageId === line.messageId)
+            last.push(line);
+        else
+            groups.push([line]);
+    }
+    return groups;
+}
 /**
  * Fold a tool-call counter into the settled shape: `{count, byName}` with the
  * per-name values summing to `count`. An empty map yields undefined — a
@@ -661,13 +690,20 @@ function foldClaudeStreamLine(state, raw) {
     if (event.type !== 'assistant' && event.type !== 'user')
         return;
     const blocks = event.message?.content ?? [];
+    const linesBefore = state.lines.length;
+    const messageId = event.type === 'assistant' && typeof event.message?.id === 'string' ? event.message.id : undefined;
     for (const [blockIndex, block] of blocks.entries()) {
         if (typeof block !== 'object' || block === null)
             continue;
         const record = block;
-        const identity = event.type === 'assistant' && typeof event.message?.id === 'string'
-            ? { streamId: `${event.message.id}:${blockIndex}` } : {};
+        const identity = messageId !== undefined
+            ? { streamId: `${messageId}:${blockIndex}`, messageId } : {};
         const kind = record['type'];
+        // A user event's text is the CLI's own injection (a Skill's body, a slash
+        // command's output, an interrupt notice) — never the model's answer; the
+        // round's prompt is mirrored separately as the user message.
+        if (kind === 'text' && event.type === 'user')
+            continue;
         if (kind === 'text' && typeof record['text'] === 'string' && record['text'].trim() !== '') {
             state.lines.push({ kind: 'text', text: record['text'], ...identity });
             // The final assistant text block is the run output.
@@ -712,6 +748,7 @@ function foldClaudeStreamLine(state, raw) {
                     id: id ?? `claude-tool-${state.lines.length}`,
                     name: 'ApplyPatch',
                     args: edit.args,
+                    ...messageId === undefined ? {} : { messageId },
                     ...edit.patch === undefined ? {} : { result: edit.patch },
                 });
             }
@@ -723,6 +760,7 @@ function foldClaudeStreamLine(state, raw) {
                     // The server-side tools surface under the local tools' card names
                     // (web_search is the same activity the local WebSearch tool runs).
                     name: kind === 'server_tool_use' ? SERVER_TOOL_CARD_NAMES[name] ?? name : name,
+                    ...messageId === undefined ? {} : { messageId },
                     ...detail === undefined ? {} : { args: detail },
                 });
             }
@@ -742,6 +780,26 @@ function foldClaudeStreamLine(state, raw) {
             }
         }
     }
+    // Claude reports the call's own usage inline on every assistant event
+    // (cache buckets included). One API call arrives as one event PER BLOCK,
+    // each repeating the message's usage: stamp it on the call's LAST folded
+    // line and lift it off the line it previously rode, so a multi-block call
+    // still accounts exactly once. The terminal `result` event's round total
+    // stays on `state.usage` for the run accounting.
+    if (event.type === 'assistant' && event.message?.usage !== undefined && state.lines.length > linesBefore) {
+        const lastIndex = state.lines.length - 1;
+        const last = state.lines[lastIndex];
+        if (messageId !== undefined) {
+            const previous = state.usageStamped.get(messageId);
+            if (previous !== undefined && previous !== lastIndex) {
+                const { usage: _cleared, ...rest } = state.lines[previous];
+                state.lines[previous] = rest;
+            }
+        }
+        state.lines[lastIndex] = { ...last, usage: usageFromClaude(event.message.usage) };
+        if (messageId !== undefined)
+            state.usageStamped.set(messageId, lastIndex);
+    }
 }
 /**
  * Merge a tool result into its call line: pair by tool_use_id when the stream
@@ -783,6 +841,7 @@ export class ClaudeStreamParser {
     buffer = '';
     lines = [];
     callsById = new Map();
+    usageStamped = new Map();
     text;
     usage;
     sessionId;
@@ -820,6 +879,7 @@ export function parseClaudeStreamJson(output) {
     const state = {
         lines: [],
         callsById: new Map(),
+        usageStamped: new Map(),
         toolCalls: new Map(),
         text: undefined,
         usage: undefined,
@@ -990,26 +1050,43 @@ function serverToolResultText(record) {
     }
     return undefined;
 }
-/** Flatten a tool_result content payload (string or block array) to text. */
+/**
+ * Flatten a tool_result content payload (string or block array) to text.
+ * Beyond `text` blocks, ToolSearch answers with `tool_reference` blocks — one
+ * per discovered tool — which list as the found tool names; dropping them
+ * stranded the call (no result recorded) and it settled as a phantom
+ * interrupted failure.
+ */
 function toolResultText(content) {
     if (typeof content === 'string')
         return content;
     if (!Array.isArray(content))
         return undefined;
     return content
-        .filter((block) => typeof block === 'object' && block !== null && block.type === 'text'
-        && typeof block.text === 'string')
-        .map(block => block.text ?? '')
+        .map((block) => {
+        if (typeof block !== 'object' || block === null)
+            return undefined;
+        const record = block;
+        if (record.type === 'text' && typeof record.text === 'string')
+            return record.text;
+        if (record.type === 'tool_reference' && typeof record.tool_name === 'string')
+            return record.tool_name;
+        return undefined;
+    })
+        .filter((text) => text !== undefined)
         .join('\n');
 }
 /**
  * Map claude's usage payload onto the shared usage contract. Claude's
  * `input_tokens` is the uncached input; cache reads and cache creation are
  * reported separately, so each maps to its own bucket with no subtraction.
+ * When the payload carries ANY cache field, `cacheReadTokens` is always
+ * written (0 when the read counter is absent or zero) — a reader can then
+ * tell "no hits" from "not reported".
  * @param usage - the raw claude usage object.
  * @returns the shared usage record.
  */
-function usageFromClaude(usage) {
+export function usageFromClaude(usage) {
     const raw = usage;
     if (raw === undefined || typeof raw !== 'object')
         return { inputTokens: 0, outputTokens: 0 };
@@ -1025,8 +1102,8 @@ function usageFromClaude(usage) {
         inputTokens: input ?? 0,
         outputTokens: output ?? 0,
     };
-    if (cacheRead !== undefined && cacheRead > 0)
-        usageRecord.cacheReadTokens = cacheRead;
+    if (cacheRead !== undefined || cacheWrite !== undefined)
+        usageRecord.cacheReadTokens = cacheRead ?? 0;
     if (cacheWrite !== undefined && cacheWrite > 0)
         usageRecord.cacheWriteTokens = cacheWrite;
     return usageRecord;
@@ -1178,34 +1255,11 @@ export async function startClaudeCliRun(request, spec) {
     }).then((settled) => {
         // A completed round proves the scoped credential is live — the endpoint
         // answered. Reported here rather than from the mirror so it lands whether
-        // or not the round is session-backed.
+        // or not the round is session-backed. The turn boundary is NOT appended
+        // here: it lands after the post-exit settle mirror (below), so every
+        // mirrored step precedes turn/end in the stored log.
         if (settled.stopReason === 'completed')
             spec.onAuthSuccess?.();
-        // Every terminal path closes the turn so the timing window never stays
-        // open on a failed or cancelled run. The turn/end timestamp is the real
-        // settle moment; an in-stream error result or a non-zero exit settles
-        // 'error', a locally cancelled run 'aborted'.
-        if (spec.childSession !== undefined) {
-            if (settled.stopReason === 'completed') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
-            }
-            else if (settled.stopReason === 'aborted') {
-                spec.childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
-            }
-            else {
-                const parsed = parseClaudeStreamJson(output);
-                spec.childSession.append('turn/end', {
-                    turn,
-                    reason: {
-                        kind: 'error',
-                        error: {
-                            message: parsed.error ?? `claude -p exited with code ${String(exitCode)}`,
-                            code: 'UNKNOWN',
-                        },
-                    },
-                });
-            }
-        }
         return settled;
     });
     // After the child EXITS — however it ended (completed, killed by dispose, or
@@ -1213,22 +1267,64 @@ export async function startClaudeCliRun(request, spec) {
     // subagent session, so a cancelled round still preserves its partial work
     // (thinking, tool calls with results, replies) and real token usage. The
     // session id is recorded even on abort so the partial session stays
-    // resumable. Waits for the settle chain first (so turn/end is already
-    // appended) AND for the process to actually exit (so stdout is drained).
-    void result.then(() => child.done).then(() => {
+    // resumable. Waits for the settle chain first AND for the process to
+    // actually exit (so stdout is drained). The turn closes AFTER the settle
+    // mirror, still behind the mirror queue: every mirrored step must land
+    // before turn/end — the released-log reader rejects a step outside an open
+    // turn on every cold read. The run's `result` still settles at its own
+    // moment (abort latency unchanged); only the boundary moved.
+    void result.then(() => child.done).then(async () => {
+        // The seam's collected buffers are complete at process exit; the
+        // streamed variables can lag `done` by a tick.
+        const drainedStdout = child.collected.stdout?.readFrom(0).text || output;
         // Auth detection runs post-exit: streams are drained by then, so a fast
         // failure's output is complete (a settle-time read could race the flush).
         if (spec.onAuthFailure !== undefined) {
-            // The seam's collected buffers are complete at process exit; the
-            // streamed variables can lag `done` by a tick.
             const drainedStderr = child.collected.stderr?.readFrom(0).text || stderr;
-            const drainedStdout = child.collected.stdout?.readFrom(0).text || output;
             const authDetail = `${parseClaudeStreamJson(drainedStdout).error ?? ''}\n${drainedStderr}`;
             if (CLAUDE_AUTH_FAILURE.test(authDetail)) {
                 spec.onAuthFailure(authDetail.split('\n').find(line => line.trim() !== '') ?? 'auth failure');
             }
         }
-        return mirrorClaudeAfterExit(spec, task, turn, output, liveMirror);
+        await mirrorClaudeAfterExit(spec, task, turn, drainedStdout, liveMirror);
+        const closeTurn = async () => {
+            if (spec.childSession === undefined)
+                return;
+            const childSession = spec.childSession;
+            const settled = await result;
+            // Every terminal path closes the turn so the timing window never stays
+            // open on a failed or cancelled run. An in-stream error result or a
+            // non-zero exit settles 'error', a locally cancelled run 'aborted'.
+            if (settled.stopReason === 'completed') {
+                childSession.append('turn/end', { turn, reason: { kind: 'completed' } });
+            }
+            else if (settled.stopReason === 'aborted') {
+                childSession.append('turn/end', { turn, reason: { kind: 'aborted', reason: { kind: 'parent' } } });
+            }
+            else {
+                childSession.append('turn/end', {
+                    turn,
+                    reason: {
+                        kind: 'error',
+                        error: {
+                            message: parseClaudeStreamJson(drainedStdout).error ?? `claude -p exited with code ${String(exitCode)}`,
+                            code: 'UNKNOWN',
+                        },
+                    },
+                });
+            }
+            if (spec.ctx !== undefined) {
+                await persistChildSession(spec.ctx, childSession).catch((error) => {
+                    spec.ctx?.logger.warn(`subagent-claude: turn/end persistence failed: ${thrown(error).message}`);
+                });
+            }
+        };
+        // Behind the live mirror's queue so a flush in flight cannot interleave
+        // (mirrorClaudeAfterExit already enqueued its own pass there).
+        if (liveMirror === undefined)
+            await closeTurn();
+        else
+            await liveMirror.enqueue(closeTurn);
     }, () => { });
     return Promise.resolve(subprocessRunHandle({
         // Host 0.2.1: the published run id is a fresh PER-EXECUTION identity —
@@ -1245,6 +1341,27 @@ export async function startClaudeCliRun(request, spec) {
     }));
 }
 /** One assistant-role message event, attributed to the claude route. */
+/**
+ * Write the round's request/header when the config differs from the child
+ * log's last one (the host logs changed snapshots, not per-call duplicates):
+ * the first write is `initial`, a differing one `change`, an identical one
+ * skipped. Context Lens reads the child log's config from these headers.
+ */
+export function appendClaudeRequestHeader(childSession, config) {
+    const serialized = JSON.stringify(config);
+    let last;
+    for (const event of childSession.snapshotEvents()) {
+        if (event.type === 'request/header') {
+            last = JSON.stringify(event.data.header?.config);
+        }
+    }
+    if (last === serialized)
+        return;
+    childSession.append('request/header', {
+        header: { config },
+        reason: last === undefined ? 'initial' : 'change',
+    });
+}
 export function assistantEvent(blocks) {
     return createAssistantMessage({
         content: blocks,
@@ -1259,31 +1376,49 @@ export function assistantEvent(blocks) {
  * the real-time view renders nothing (only a full rebuild, which mints step
  * drafts from the explicit coordinates, recovers it). Tool cards escape that
  * fate only because their definition does not consult the step location.
+ *
+ * A tool line folds the native lifecycle inside its one step: an assistant
+ * message advertising the tool-call block, the `tool/call`, and its
+ * `tool/result` — the released-log reader pairs call and result against the
+ * advertisement and resolves every advertised call before the step closes, so
+ * a line whose result the stream has not recorded yet must NOT reach this
+ * fold mid-round (the callers hold there; the result merges into the call's
+ * line in place, so a later pass sees it). A line still unresulted at settle
+ * folds with the interrupted placeholder ({@link CLAUDE_INTERRUPTED_TOOL_RESULT}).
  */
 export function appendClaudeTranscriptLine(childSession, turn, step, line, usage) {
+    // The line's own per-call usage (stamped by the fold from the assistant
+    // event's inline report) wins; the caller's round total is the fallback for
+    // a stream that named none.
+    const lineUsage = line.usage ?? usage;
     childSession.append('step/start', { turn, step });
     if (line.kind === 'tool') {
-        // Native tool card: the call event now, the result event when the stream
-        // already carries it. Tool lines never carry the round's usage — the
-        // callers attach usage to the round's last non-tool line.
+        // A tool-only call's usage rides the advertising assistant/message (the
+        // tool/call and tool/result events themselves have no usage slot).
+        const args = line.args ?? '';
+        childSession.append('assistant/message', {
+            turn,
+            step,
+            message: assistantEvent([{ type: 'tool-call', id: line.id, name: line.name, arguments: args }]),
+            stream: [],
+            ...lineUsage === undefined ? {} : { usage: lineUsage },
+        }, { surfaceOp: 'append' });
         const call = childSession.append('tool/call', {
             turn,
             step,
             callId: line.id,
             name: line.name,
-            arguments: line.args ?? '',
+            arguments: args,
         });
-        if (line.result !== undefined) {
-            childSession.append('tool/result', {
-                turn,
-                step,
-                message: createToolResultMessage({
-                    callId: line.id,
-                    content: [{ type: 'text', text: line.result }],
-                    isError: false,
-                }),
-            }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
-        }
+        childSession.append('tool/result', {
+            turn,
+            step,
+            message: createToolResultMessage({
+                callId: line.id,
+                content: [{ type: 'text', text: line.result ?? CLAUDE_INTERRUPTED_TOOL_RESULT }],
+                isError: line.result === undefined,
+            }),
+        }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
         childSession.append('step/end', { turn, step });
         return;
     }
@@ -1295,24 +1430,64 @@ export function appendClaudeTranscriptLine(childSession, turn, step, line, usage
         step,
         message: assistantEvent(blocks),
         stream: [],
-        ...usage === undefined ? {} : { usage },
+        ...lineUsage === undefined ? {} : { usage: lineUsage },
     }, { surfaceOp: 'append' });
     childSession.append('step/end', { turn, step });
 }
-/**
- * Fold one transcript line into the run's child session as one assistant step.
- */
-function appendClaudeLine(spec, turn, step, line, usage) {
-    if (spec.childSession === undefined)
-        return;
-    appendClaudeTranscriptLine(spec.childSession, turn, step, line, usage);
-}
 /** The delta-progress text for one transcript line. */
 export function claudeLineText(line) {
     return line.kind === 'tool'
         ? `[工具 ${line.name}]${line.args !== undefined ? ` ${line.args}` : ''}${line.result !== undefined ? ` → ${line.result}` : ''}`
         : line.text;
 }
+/**
+ * Fold one API call (a message-id group) into the child session as ONE
+ * assistant step: a single assistant/message carrying the call's reasoning,
+ * text and tool-call blocks (the host's own mixed-content shape), then each
+ * call's native lifecycle, then step/end. The call's usage rides the message
+ * once — the group's own per-call stamp wins over the round-total fallback.
+ */
+export function appendClaudeTranscriptGroup(childSession, turn, step, group, usage) {
+    const lineUsage = group.map(line => line.usage).find(value => value !== undefined) ?? usage;
+    const blocks = [];
+    for (const line of group) {
+        if (line.kind === 'think')
+            blocks.push({ type: 'reasoning', text: line.text });
+        else if (line.kind === 'text')
+            blocks.push({ type: 'text', text: line.text });
+        else
+            blocks.push({ type: 'tool-call', id: line.id, name: line.name, arguments: line.args ?? '' });
+    }
+    childSession.append('step/start', { turn, step });
+    childSession.append('assistant/message', {
+        turn,
+        step,
+        message: assistantEvent(blocks),
+        stream: [],
+        ...lineUsage === undefined ? {} : { usage: lineUsage },
+    }, { surfaceOp: 'append' });
+    for (const line of group) {
+        if (line.kind !== 'tool')
+            continue;
+        const call = childSession.append('tool/call', {
+            turn,
+            step,
+            callId: line.id,
+            name: line.name,
+            arguments: line.args ?? '',
+        });
+        childSession.append('tool/result', {
+            turn,
+            step,
+            message: createToolResultMessage({
+                callId: line.id,
+                content: [{ type: 'text', text: line.result ?? CLAUDE_INTERRUPTED_TOOL_RESULT }],
+                isError: line.result === undefined,
+            }),
+        }, { surfaceOp: 'append', sourceEventSeqs: [call.seq] });
+    }
+    childSession.append('step/end', { turn, step });
+}
 /** Create the per-run live mirror over the incremental parser. */
 function createClaudeLiveMirror(spec, task, turn) {
     const parser = new ClaudeStreamParser();
@@ -1320,6 +1495,7 @@ function createClaudeLiveMirror(spec, task, turn) {
     const ctx = spec.ctx;
     let mirrored = 0;
     let userMirrored = false;
+    let headerWritten = false;
     let lastTodos;
     let todoSkewWarned = false;
     let queue = Promise.resolve();
@@ -1327,7 +1503,11 @@ function createClaudeLiveMirror(spec, task, turn) {
         get mirroredLines() { return mirrored; },
         get userMirrored() { return userMirrored; },
         enqueue(task) {
-            queue = queue.then(task);
+            // A failed task must not poison the queue for the passes that still owe
+            // writes (the settle mirror, the turn boundary): heal the tail before
+            // chaining. The returned promise still carries THIS task's rejection to
+            // its own caller.
+            queue = queue.catch(() => { }).then(task);
             return queue;
         },
         push(chunk) {
@@ -1345,8 +1525,32 @@ function createClaudeLiveMirror(spec, task, turn) {
                 todoSkewWarned = true;
                 ctx.logger.warn('subagent-claude: a TodoWrite call missed the documented input shape; folded as a plain tool line');
             }
-            const upto = parser.completed ? parser.lines.length : parser.lines.length - 1;
-            if (upto <= mirrored)
+            // The fold window: every GROUP but the volatile last one — plus a HOLD
+            // at the first group with an unresulted tool line (the released-log
+            // reader resolves every advertised call before step/end; the result
+            // merges into the call's line in place, so the next push retries from
+            // here and sees it). A completed parser never holds: a result that will
+            // never arrive folds as the interrupted placeholder.
+            const groups = groupClaudeTranscriptLines(parser.lines);
+            const groupStarts = [];
+            let totalLines = 0;
+            for (const group of groups) {
+                groupStarts.push(totalLines);
+                totalLines += group.length;
+            }
+            let uptoGroups = parser.completed ? groups.length : groups.length - 1;
+            if (!parser.completed) {
+                for (let scan = 0; scan < uptoGroups; scan += 1) {
+                    if (groupStarts[scan] < mirrored)
+                        continue;
+                    if (groups[scan].some(line => line.kind === 'tool' && line.result === undefined)) {
+                        uptoGroups = scan;
+                        break;
+                    }
+                }
+            }
+            const upto = groupStarts[uptoGroups] ?? totalLines;
+            if (upto <= mirrored && userMirrored)
                 return;
             void mirror.enqueue(async () => {
                 try {
@@ -1359,26 +1563,43 @@ function createClaudeLiveMirror(spec, task, turn) {
                         }), { surfaceOp: 'append' });
                         localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: task });
                     }
-                    // The usage rides the last NON-tool line (tool events carry no
-                    // usage slot); a stream ending on a tool line would otherwise drop
-                    // the round's accounting. When that carrier was mirrored in an
-                    // earlier flush (before the usage was knowable), the accounting is
-                    // lost — host 0.1.5 has no usage-backfill event.
+                    if (!headerWritten) {
+                        // The launch facts plus the init event's observed model are the
+                        // child log's request config (claude's wire never carries
+                        // effort) — Context Lens reads request/header instead of showing
+                        // 未记录. The header contract requires a model: without one (a
+                        // stream that errored before init) nothing is recorded.
+                        const observedModel = parser.model ?? spec.model;
+                        if (observedModel !== undefined) {
+                            headerWritten = true;
+                            appendClaudeRequestHeader(childSession, {
+                                provider: 'claude-local',
+                                model: observedModel,
+                                ...spec.controlled ? { reasoningEffort: (spec.effort ?? 'auto') } : {},
+                            });
+                        }
+                    }
+                    // Fallback carrier only: when the fold stamped per-call usage onto
+                    // any line, the round total never joins the log (a sum would double
+                    // count); otherwise it rides the last group with a non-tool line as
+                    // before. A carrier mirrored in an earlier flush (before the usage
+                    // was knowable) loses the accounting — host 0.1.5 has no
+                    // usage-backfill event.
                     let carrier = -1;
-                    if (parser.completed && parser.usage !== undefined) {
-                        for (let scan = 0; scan < parser.lines.length; scan += 1) {
-                            if (parser.lines[scan]?.kind !== 'tool')
+                    if (parser.completed && parser.usage !== undefined && !parser.lines.some(line => line.usage !== undefined)) {
+                        for (let scan = 0; scan < groups.length; scan += 1) {
+                            if (groups[scan].some(line => line.kind !== 'tool'))
                                 carrier = scan;
                         }
                     }
-                    for (let index = mirrored; index < upto; index += 1) {
-                        const line = parser.lines[index];
-                        if (line === undefined)
+                    for (let scan = 0; scan < uptoGroups; scan += 1) {
+                        if (groupStarts[scan] < mirrored)
                             continue;
-                        const usage = index === carrier ? parser.usage : undefined;
-                        appendClaudeLine(spec, turn, index + 1, line, usage);
-                        mirrored = index + 1;
-                        localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: claudeLineText(line) });
+                        const group = groups[scan];
+                        appendClaudeTranscriptGroup(childSession, turn, scan + 1, group, scan === carrier ? parser.usage : undefined);
+                        mirrored = groupStarts[scan] + group.length;
+                        for (const line of group)
+                            localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: claudeLineText(line) });
                     }
                     await persistChildSession(ctx, childSession);
                     localAgent?.reportRunProgress(childSession.id, { kind: 'mirror', mirroredLines: mirrored });
@@ -1418,21 +1639,33 @@ async function appendClaudeResponse(spec, task, turn, parsed, fromLines = 0, use
         }), { surfaceOp: 'append' });
         localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: task });
     }
-    // The round's usage rides the last NON-tool line: tool activity folds to
-    // `tool/call`/`tool/result` events (which carry no usage slot), and a kill
-    // mid-tool ends the transcript with a tool line.
-    let usageIndex = -1;
-    for (let index = 0; index < parsed.lines.length; index += 1) {
-        if (parsed.lines[index]?.kind !== 'tool')
-            usageIndex = index;
+    // Fallback carrier only: the round total rides the last group with a
+    // non-tool line when the stream named no per-call usage; groups the fold
+    // stamped with their call's inline usage keep their own.
+    const groups = groupClaudeTranscriptLines(parsed.lines);
+    const groupStarts = [];
+    let totalLines = 0;
+    for (const group of groups) {
+        groupStarts.push(totalLines);
+        totalLines += group.length;
     }
-    let step = fromLines + 1;
-    for (const line of parsed.lines.slice(fromLines)) {
-        appendClaudeLine(spec, turn, step, line, step - 1 === usageIndex ? parsed.usage : undefined);
-        localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: claudeLineText(line) });
-        step += 1;
+    let carrier = -1;
+    if (!parsed.lines.some(line => line.usage !== undefined)) {
+        for (let scan = 0; scan < groups.length; scan += 1) {
+            if (groups[scan].some(line => line.kind !== 'tool'))
+                carrier = scan;
+        }
+    }
+    for (let scan = 0; scan < groups.length; scan += 1) {
+        if (groupStarts[scan] < fromLines)
+            continue;
+        const group = groups[scan];
+        appendClaudeTranscriptGroup(childSession, turn, scan + 1, group, scan === carrier ? parsed.usage : undefined);
+        for (const line of group)
+            localAgent?.reportRunProgress(childSession.id, { kind: 'delta', text: claudeLineText(line) });
     }
-    if (parsed.usage !== undefined && usageIndex !== -1 && usageIndex < fromLines) {
+    const carrierLine = carrier === -1 ? -1 : (groupStarts[carrier] ?? -1);
+    if (parsed.usage !== undefined && carrierLine !== -1 && carrierLine < fromLines) {
         // The carrier line went out through the live mirror before the usage was
         // knowable. Host 0.1.5 has no usage-backfill event (the per-chunk event is
         // gone and appended messages are immutable), so the round's accounting is

package/lib/types/client/icons.d.ts

@@ -1,6 +1,6 @@
 /**
  * Generated by scripts/sync-icon-artwork.mts from @deepseek-ai/dsh-client-ui-primitives
- * (v0.1.7-rc.1, harness 46a7f68b09) — do not edit by hand. The 0.1.5 and rc.1 host lines
+ * (v0.2.1-rc.1, harness 1600d8a1e1) — do not edit by hand. The 0.1.5 and rc.1 host lines
  * share no icon export name, so the rc.1 artwork is inlined here: pure SVG,
  * no host runtime identity, identical on every line. Re-run the generator
  * after adding an icon import or bumping the harness checkout.