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

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

@@ -17,19 +17,35 @@
 import { randomUUID } from 'node:crypto';
 import { createAssistantMessage, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm';
 import { SessionId } from '@deepseek-ai/dsh-session';
-import { NO_START_CAPABILITIES, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
+import { NO_START_CAPABILITIES, SUBAGENT_DESCRIPTOR_VERSION, settleRunResult, subprocessRunHandle, } from '@deepseek-ai/dsh-subagent';
 import { assertResumeCwdUnchanged, assertResumeScopeUnchanged, resolveRoundModel, containerExecSpawn, containerScopedHome, delegationEnv, establishSubagentCatalogChild, persistChildSession, probeCliVersion, resolveChildCwd, subagentDelegationLabel, } from '@khorsheed/dsh-local-agent';
 import { MEMBER_BRIDGE_SOCKET_ENV, MEMBER_BRIDGE_TOKEN_ENV } from '@khorsheed/dsh-local-agent/types';
 import { LiveChannelUnavailableError } from './live-driver.js';
-import { syncClaudeCredentialFile } from './records.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;
 /**
  * Auth-shaped failure signatures in claude's result error or stderr: the
- * endpoint rejected the credential (401/403, revoked token). Narrow on
- * purpose — matched against provider-controlled error strings only.
+ * endpoint rejected the credential (401/403, revoked key). Matches the CLI's
+ * own phrasing ("Failed to authenticate. API Error: 401 …", the
+ * `authentication_failed` error tag) plus the relay phrasings seen in the
+ * wild ("invalid x-api-key" and friends). Narrow on purpose — matched against
+ * 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 CLAUDE_AUTH_FAILURE = /failed to authenticate|authentication_failed|oauth access token/i;
+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;
@@ -119,7 +135,7 @@ export function claudeCliVersion(ctx, homeDir) {
 export class ClaudeCliProvider {
     ctx;
     permissionMode;
-    baseUrl;
+    endpoint;
     live;
     model;
     name = 'claude-local';
@@ -130,6 +146,11 @@ export class ClaudeCliProvider {
      *   generation's driver per member (the settings toggle swaps generations;
      *   a resolver may return undefined to steer one member's round to exec
      *   while a retiring generation still hosts it).
+     * @param endpoint - resolver for the round's endpoint credential (endpoint-auth.ts:
+     *   the scope's endpoint-auth.json over the plugin config triple), read PER
+     *   ROUND against the round's scoped home, so a key rotation or a profile
+     *   edit takes effect on the next delegation without a reload. Absent, no
+     *   `ANTHROPIC_*` variables reach the child at all.
      * @param model - resolver for the member's effective model, read PER ROUND
      *   so a settings-card write or a composer switch takes effect on the next
      *   delegation without a reload. Receives the member (the child session id)
@@ -138,10 +159,10 @@ export class ClaudeCliProvider {
      *   resolver not passed), the delegation's own model still rides, exactly
      *   as before the key existed.
      */
-    constructor(ctx, permissionMode = 'skip', baseUrl, live, model) {
+    constructor(ctx, permissionMode = 'skip', endpoint, live, model) {
         this.ctx = ctx;
         this.permissionMode = permissionMode;
-        this.baseUrl = baseUrl;
+        this.endpoint = endpoint;
         this.live = live;
         this.model = model;
     }
@@ -168,8 +189,8 @@ export class ClaudeCliProvider {
         // The scoped home this round runs against: the staged intent's scope
         // names a sibling directory under the homes root, absent means the
         // default one — the directory every round used before scopes existed.
-        // claude's keychain item is keyed by the config directory's path, so a
-        // named scope gets its own credential item for free.
+        // A named scope's endpoint-auth.json overrides the deployment credential
+        // for its rounds (endpoint-auth.ts).
         const scope = intent?.scope;
         const homeDir = this.ctx.localAgent.homeDir('claude-code', scope);
         // The effective cwd: the caller's override (the staged intent's `cwd`,
@@ -209,7 +230,7 @@ export class ClaudeCliProvider {
                 ...record?.configurationLock === undefined ? {} : { configurationLock: record.configurationLock },
             }, configuration => this.startClaudeResume(request, intent, cwd, homeDir, exec, scope, record?.model, configuration), request.signal, intent?.onAdmitted);
         }
-        const childSessionId = SessionId(intent?.preparedMemberId ?? randomUUID());
+        const childSessionId = SessionId(intent?.preparedMemberId ?? intent?.childSessionId ?? randomUUID());
         if (typeof this.ctx.localAgent.withMemberConfigurationRound !== 'function') {
             if (intent?.effort !== undefined)
                 throw new Error('Claude effort requires the configuration admission core');
@@ -242,14 +263,20 @@ export class ClaudeCliProvider {
                 },
             });
             const harness = this.ctx.localAgent.get('claude-code');
-            const label = subagentDelegationLabel(harness?.displayName ?? 'Claude Code', request.descriptor.label);
+            // Host 0.2.1 no longer resolves a descriptor onto the request (the
+            // runtime's one-shot snapshot is gone), so the provider stamps the same
+            // payload itself; the activation spec's required label arrives as the
+            // empty string when the caller named none.
+            const label = subagentDelegationLabel(harness?.displayName ?? 'Claude Code', request.label || undefined);
             childSession.append('subagent/descriptor', {
-                ...request.descriptor,
+                version: SUBAGENT_DESCRIPTOR_VERSION,
+                mode: 'one-shot',
+                provider: this.name,
                 label,
             });
-            // The official runtime appends the parent-side subagent/catalog
-            // discovery row only for in-process children (run.localAgent); this run
-            // is remote, so the provider appends it here — once per child, where
+            // The 0.2.1 manager appends the parent-side subagent/catalog discovery
+            // row only for parent-delivered children; the family runs caller
+            // delivery, so the provider appends it here — once per child, where
             // the descriptor lands. A failure degrades to the warn below; a missing
             // row never blocks the delegation.
             establishSubagentCatalogChild(request.parent.session, childSession.header, label);
@@ -262,12 +289,12 @@ export class ClaudeCliProvider {
         catch (error) {
             this.ctx.logger.warn(`subagent-claude: subagent session record failed: ${error instanceof Error ? error.message : String(error)}`);
         }
-        // Resolve the effective endpoint once per run: the cordis Config field
-        // wins, else the host environment's ANTHROPIC_BASE_URL (a STARTUP-time
-        // snapshot — a long-running dsh process does not see later shell exports),
-        // else the CLI's own default. Log it (without the key) so a failing
-        // delegation reports which endpoint it actually used.
-        const effectiveBaseUrl = this.baseUrl ?? process.env.ANTHROPIC_BASE_URL;
+        // Resolve the effective endpoint once per run: the scope's
+        // endpoint-auth.json over the plugin config triple (endpoint-auth.ts).
+        // Logged WITHOUT the key so a failing delegation reports which endpoint
+        // it actually used.
+        const endpoint = await this.endpoint?.(homeDir);
+        const effectiveBaseUrl = endpoint?.baseUrl;
         this.ctx.logger.info(`subagent-claude: delegating via ${effectiveBaseUrl ?? 'claude default endpoint'}`);
         // Live driver: the round goes to the member's resident stream-json
         // process. A channel that fails at spawn falls through to the exec
@@ -276,6 +303,14 @@ export class ClaudeCliProvider {
         // a resident stream-json process on the HOST, which is the transport the
         // target exists to replace.
         const live = exec === undefined ? this.liveDriver(runId) : undefined;
+        // The round's model, computed once: the configuration admission's
+        // resolution wins, else the family's order (session override, the
+        // delegation's own model, the scope's curated list / settings key).
+        // Whatever it is — explicit or followed — the first round STAMPS it into
+        // the delegation record: the member is bound to this model from then on,
+        // and a later edit of the curated list moves the default only for NEW
+        // members, never underneath a conversation (its cache lineage included).
+        const round = configuration?.resolved ?? this.roundModel(runId, requestedModel);
         if (live !== undefined && childSession !== undefined && !live.disabled) {
             // The member-bound live driver receives this exact scoped home.
             try {
@@ -303,9 +338,9 @@ export class ClaudeCliProvider {
                             cwd,
                             // …and its scoped home anchors the resume-scope check.
                             ...scope === undefined ? {} : { scope },
-                            // The model this delegation asked for: every resume round reads
-                            // it back from here instead of the caller restating it.
-                            ...requestedModel === undefined ? {} : { model: requestedModel },
+                            // The model the member is BOUND to (see `round` above): every
+                            // resume round re-requests it from here.
+                            ...round.model === undefined ? {} : { model: round.model },
                         });
                     },
                 });
@@ -327,12 +362,14 @@ export class ClaudeCliProvider {
                 cwd,
                 env: delegationEnv({
                     CLAUDE_CONFIG_DIR: homeDir,
-                    ...this.baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: this.baseUrl },
+                    // 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 },
                 endpointLabel: effectiveBaseUrl,
                 permissionMode: this.permissionMode,
-                ...(configuration?.resolved ?? this.roundModel(runId, requestedModel)),
+                ...round,
                 ...configuration === undefined ? {} : { controlled: true },
                 disposeGraceMs: DEFAULT_DISPOSE_GRACE_MS,
                 spawn: spec => this.ctx.subprocess.spawn(spec),
@@ -360,8 +397,9 @@ export class ClaudeCliProvider {
                         cwd,
                         // …and its scoped home anchors the resume-scope check.
                         ...scope === undefined ? {} : { scope },
-                        // The model this delegation asked for (see the live branch).
-                        ...requestedModel === undefined ? {} : { model: requestedModel },
+                        // The model the member is BOUND to (see `round` above; the exec
+                        // spawn below runs this same value).
+                        ...round.model === undefined ? {} : { model: round.model },
                     });
                 },
                 // Every settled round reports its observed model and usage through the
@@ -426,7 +464,8 @@ export class ClaudeCliProvider {
                     this.ctx.logger.warn(`subagent-claude: live driver unavailable, using the exec one-shot: ${error.message}`);
                 }
             }
-            const effectiveBaseUrl = this.baseUrl ?? process.env.ANTHROPIC_BASE_URL;
+            const endpoint = await this.endpoint?.(homeDir);
+            const effectiveBaseUrl = endpoint?.baseUrl;
             this.ctx.logger.info(`subagent-claude: resuming via ${effectiveBaseUrl ?? 'claude default endpoint'}`);
             // Member channel: register the resume round (same child session, fresh
             // per-run token) before the spawn.
@@ -438,7 +477,8 @@ export class ClaudeCliProvider {
                     cwd,
                     env: delegationEnv({
                         CLAUDE_CONFIG_DIR: homeDir,
-                        ...this.baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: this.baseUrl },
+                        ...member === undefined ? {} : { MCP_TOOL_TIMEOUT: MEMBER_TOOL_TIMEOUT_MS },
+                        ...endpointAuthEnv(endpoint),
                     }),
                     ...exec === undefined ? {} : { exec },
                     endpointLabel: effectiveBaseUrl,
@@ -508,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
@@ -637,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.
@@ -688,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 },
                 });
             }
@@ -699,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 },
                 });
             }
@@ -718,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
@@ -759,6 +841,7 @@ export class ClaudeStreamParser {
     buffer = '';
     lines = [];
     callsById = new Map();
+    usageStamped = new Map();
     text;
     usage;
     sessionId;
@@ -796,6 +879,7 @@ export function parseClaudeStreamJson(output) {
     const state = {
         lines: [],
         callsById: new Map(),
+        usageStamped: new Map(),
         toolCalls: new Map(),
         text: undefined,
         usage: undefined,
@@ -966,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 };
@@ -1001,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;
@@ -1025,20 +1126,6 @@ export async function startClaudeCliRun(request, spec) {
     if (request.signal.aborted) {
         throw new Error('subagent-claude: request was aborted before the CLI started');
     }
-    // Credential reconcile before EVERY spawn: claude 2.1.236 reads
-    // .credentials.json at runtime while login/refresh write the keychain, so
-    // the login watch's sync alone leaves a rotated grant stale at spawn time
-    // (the live driver's spawnRuntime does the same). Best-effort: a missing
-    // grant fails the run with the CLI's own auth error, not here.
-    // NOTE the directory: on a container round this is still the HOST scoped
-    // home (the in-container path only replaces it in the `docker exec -e`
-    // forwarding), and the unit is about to read that same file through the
-    // bind mount — which is why the reconcile is newer-wins rather than a
-    // mirror. See `syncClaudeCredentialFile`.
-    const configDir = spec.env['CLAUDE_CONFIG_DIR'];
-    if (configDir !== undefined) {
-        await syncClaudeCredentialFile(configDir, message => { spec.ctx?.logger.warn(message); }).catch(() => false);
-    }
     const turn = spec.resume?.turn ?? 1;
     // The member bridge flags ride every argv variant (skip and normal
     // permission modes alike): --allowedTools is redundant under
@@ -1168,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
@@ -1203,28 +1267,72 @@ 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({
-        // A session-backed run's id is the child session id (the seam's local-run
-        // contract), so the tool's resume self-description names the same handle
-        // the delegation registry records.
-        id: spec.childSession?.id ?? SessionId(randomUUID()),
+        // Host 0.2.1: the published run id is a fresh PER-EXECUTION identity —
+        // the activation manager rejects a run id naming a live Session (the
+        // mirrored child session is exactly that), and resume rounds reuse the
+        // child session id. The durable child identity the family tracks rides
+        // the staged intent instead (spec.childSession.id == its childSessionId).
+        id: SessionId(randomUUID()),
         result,
         signal: request.signal,
         onAbort,
@@ -1233,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,
@@ -1247,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;
     }
@@ -1283,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();
@@ -1308,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();
@@ -1315,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) {
@@ -1333,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 {
@@ -1347,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 });
@@ -1406,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