@ai-sdk/harness-claude-code 1.0.97 → 1.0.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-claude-code",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,8 +26,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.93",
-    "@ai-sdk/provider-utils": "5.0.33",
+    "@ai-sdk/harness": "1.0.95",
+    "@ai-sdk/provider-utils": "5.0.34",
     "ws": "^8.21.0"
   },
   "peerDependencies": {

package/src/bridge/create-emit-stream-event.ts

@@ -21,8 +21,17 @@ export type ClaudeMessage = {
   event?: {
     type?: string;
     index?: number;
-    content_block?: { type?: string };
-    delta?: { type?: string; text?: string; thinking?: string };
+    content_block?: {
+      type?: string;
+      id?: string;
+      name?: string;
+    };
+    delta?: {
+      type?: string;
+      text?: string;
+      thinking?: string;
+      partial_json?: string;
+    };
   };
   message?: {
     content?: ReadonlyArray<MessageBlock>;
@@ -56,7 +65,7 @@ export type ClaudeStreamEventState = {
    */
   nativeToolCallNames: Map<string, string>;
   approvalRequestedToolUseIds: Set<string>;
-  partialBlocks: Map<number, { id: string; kind: 'text' | 'thinking' }>;
+  partialBlocks: Map<number, PartialBlock>;
   stepUsage: Record<string, unknown> | undefined;
   pendingStepToolUseIds: Set<string>;
   pendingStepUsage: Record<string, unknown> | undefined;
@@ -64,9 +73,8 @@ export type ClaudeStreamEventState = {
   /*
    * Tool-use ids that originated from the MCP server hosting user-supplied
    * tools. The MCP handler emits its own `tool-call`/`tool-result` pair with
-   * the user-facing tool name and a synthetic id, so the duplicate
-   * `tool_result` block Claude reports for the underlying native id must be
-   * suppressed.
+   * the user-facing tool name, so the duplicate `tool_result` block Claude
+   * reports for the underlying native id must be suppressed.
    */
   mcpToolUseIds: Set<string>;
   externalMcpToolUseIds: Set<string>;
@@ -74,6 +82,10 @@ export type ClaudeStreamEventState = {
   observedTerminalError: string | undefined;
 };
 
+type PartialBlock =
+  | { id: string; kind: 'text' | 'thinking' }
+  | { id: string; kind: 'tool-input' };
+
 export function createClaudeStreamEventState(): ClaudeStreamEventState {
   return {
     nativeToolCallNames: new Map(),
@@ -195,7 +207,12 @@ export function createEmitStreamEvent({
     }
 
     if (type === 'stream_event') {
-      handleStreamEvent(msg.event, state.partialBlocks, emit);
+      handleStreamEvent({
+        event: msg.event,
+        state,
+        send: emit,
+        toCommonName,
+      });
       return;
     }
 
@@ -371,13 +388,22 @@ function formatApiRetryWarning(msg: ClaudeMessage): string {
     : 'Claude Code API retry';
 }
 
-function handleStreamEvent(
-  event: ClaudeMessage['event'] | undefined,
-  partialBlocks: Map<number, { id: string; kind: 'text' | 'thinking' }>,
-  send: Emit,
-): void {
+const HOST_TOOL_PREFIX = 'mcp__harness-tools__';
+
+function handleStreamEvent({
+  event,
+  state,
+  send,
+  toCommonName,
+}: {
+  event: ClaudeMessage['event'] | undefined;
+  state: ClaudeStreamEventState;
+  send: Emit;
+  toCommonName: (nativeName: string) => string;
+}): void {
   if (!event || typeof event.index !== 'number') return;
   const index = event.index;
+  const partialBlocks = state.partialBlocks;
 
   if (event.type === 'content_block_start') {
     const blockType = event.content_block?.type;
@@ -389,6 +415,29 @@ function handleStreamEvent(
       const id = randomUUID();
       partialBlocks.set(index, { id, kind: 'thinking' });
       send({ type: 'reasoning-start', id });
+    } else if (
+      blockType === 'tool_use' &&
+      typeof event.content_block?.id === 'string' &&
+      typeof event.content_block.name === 'string'
+    ) {
+      const id = event.content_block.id;
+      const nativeName = event.content_block.name;
+      if (nativeName === 'StructuredOutput') {
+        return;
+      }
+      const hostToolName = nativeName.startsWith(HOST_TOOL_PREFIX)
+        ? nativeName.slice(HOST_TOOL_PREFIX.length)
+        : undefined;
+      const dynamic =
+        hostToolName === undefined && nativeName.startsWith('mcp__');
+      partialBlocks.set(index, { id, kind: 'tool-input' });
+      send({
+        type: 'tool-input-start',
+        id,
+        toolName: hostToolName ?? toCommonName(nativeName),
+        providerExecuted: hostToolName === undefined,
+        ...(dynamic ? { dynamic: true } : {}),
+      });
     }
     return;
   }
@@ -412,6 +461,16 @@ function handleStreamEvent(
         id: block.id,
         delta: event.delta.thinking,
       });
+    } else if (
+      block.kind === 'tool-input' &&
+      event.delta?.type === 'input_json_delta' &&
+      typeof event.delta.partial_json === 'string'
+    ) {
+      send({
+        type: 'tool-input-delta',
+        id: block.id,
+        delta: event.delta.partial_json,
+      });
     }
     return;
   }
@@ -422,8 +481,10 @@ function handleStreamEvent(
     partialBlocks.delete(index);
     if (block.kind === 'text') {
       send({ type: 'text-end', id: block.id });
-    } else {
+    } else if (block.kind === 'thinking') {
       send({ type: 'reasoning-end', id: block.id });
+    } else {
+      send({ type: 'tool-input-end', id: block.id });
     }
   }
 }

package/src/bridge/index.ts

@@ -125,13 +125,23 @@ const claudeSdk = claudeAgentSdk as any;
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const mcpModule = mcpServerModule as any;
 
+/**
+ * The Claude session id most recently reported by the SDK, captured from the
+ * message stream. Every turn in this bridge process may fork a new id (the
+ * SDK's `continue`/`resume` create a new session linked to the previous one),
+ * so the latest observation is the one a later resume must name.
+ */
+let lastClaudeSessionId: string | undefined;
+
 await runBridge<StartMessage>({
   bridgeType: 'claude-code',
   bridgeStateDir,
   onStart: runTurn,
-  // Claude Code's session state lives in the workdir on the sandbox filesystem
-  // (captured by the sandbox snapshot on stop); the resume payload is empty.
-  onStop: () => ({}),
+  // Claude Code's conversation state lives in the runtime's own store, keyed
+  // by working directory. The resume payload names the exact conversation so a
+  // later resume does not have to fall back to "most recent in this workdir".
+  onStop: () =>
+    lastClaudeSessionId == null ? {} : { claudeSessionId: lastClaudeSessionId },
 });
 
 type Emit = (msg: Record<string, unknown>) => void;
@@ -290,8 +300,18 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
         tool.name,
         tool.description ?? '',
         shape,
-        async (input: Record<string, unknown>) => {
-          const toolCallId = randomUUID();
+        async (
+          ...handlerArgs: [
+            Record<string, unknown>,
+            { requestId: string | number; _meta?: Record<string, unknown> },
+          ]
+        ) => {
+          const [input, extra] = handlerArgs;
+          const metadataToolCallId = extra._meta?.['claudecode/toolUseId'];
+          const toolCallId =
+            typeof metadataToolCallId === 'string'
+              ? metadataToolCallId
+              : randomUUID();
           emit({
             type: 'tool-call',
             toolCallId,
@@ -392,11 +412,24 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
           },
         ],
       },
-      // Continuation rule: the host can force-continue (resume after a
-      // cross-process detach) by setting `start.continue: true`; otherwise
-      // we continue every subsequent turn after the first one in this
-      // bridge process.
-      ...(start.continue === true || !turn.firstTurn ? { continue: true } : {}),
+      // Continuation rule, most specific first.
+      //
+      // `resumeSessionId` names the exact conversation and is what a
+      // cross-process resume should use: `continue` means "most recent thread
+      // in this workdir", which silently picks the wrong one once anything
+      // else has run there. The bridge also retains the id observed during its
+      // previous query, so every later query stays pinned to that conversation
+      // even when the host detached and reattached between turns. `resume` and
+      // `continue` are mutually exclusive in the SDK.
+      //
+      // Otherwise the host can force-continue by setting `start.continue`,
+      // and turns after the first fall back to the legacy cwd-based behavior
+      // when no exact id was observed.
+      ...((start.resumeSessionId ?? lastClaudeSessionId)
+        ? { resume: start.resumeSessionId ?? lastClaudeSessionId }
+        : start.continue === true || !turn.firstTurn
+          ? { continue: true }
+          : {}),
       ...permissionOptions,
       mcpServers,
       cwd: workdir,
@@ -460,6 +493,14 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
         queryInput.handleLifecycle(msg);
       }
 
+      // Every SDK message carries the session id of the conversation it
+      // belongs to. Track the latest so the stop payload and the terminal
+      // finish metadata name the exact conversation.
+      const sessionId = (msg as { session_id?: unknown }).session_id;
+      if (typeof sessionId === 'string' && sessionId.length > 0) {
+        lastClaudeSessionId = sessionId;
+      }
+
       emitStreamEvent(msg);
 
       if (type === 'result') {
@@ -559,8 +600,20 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
     type: 'finish',
     finishReason: { unified: 'stop', raw: 'stop' },
     totalUsage: turnUsage ?? streamEventState.stepUsage ?? defaultUsage(),
-    ...(totalCostUsd !== undefined
-      ? { harnessMetadata: { 'claude-code': { costUsd: totalCostUsd } } }
+    ...(totalCostUsd !== undefined || lastClaudeSessionId !== undefined
+      ? {
+          harnessMetadata: {
+            'claude-code': {
+              ...(totalCostUsd !== undefined ? { costUsd: totalCostUsd } : {}),
+              // The conversation this turn belongs to, resumable outside the
+              // SDK with `claude --resume <sessionId>` and captured by the
+              // adapter for exact cross-process resume.
+              ...(lastClaudeSessionId !== undefined
+                ? { sessionId: lastClaudeSessionId }
+                : {}),
+            },
+          },
+        }
       : {}),
   });
 }

package/src/claude-code-bootstrap.ts

@@ -51,19 +51,23 @@ export async function getClaudeCodeBootstrap(): Promise<HarnessV1Bootstrap> {
 }
 
 async function readBridgeAsset(name: string): Promise<string> {
-  const candidates = [
-    new URL(`./bridge/${name}`, import.meta.url),
-    new URL(`../bridge/${name}`, import.meta.url),
-  ];
-  let lastErr: unknown;
-  for (const url of candidates) {
-    try {
-      return await readFile(fileURLToPath(url), 'utf8');
-    } catch (err) {
-      const code = (err as NodeJS.ErrnoException).code;
-      if (code !== 'ENOENT') throw err;
-      lastErr = err;
-    }
-  }
-  throw lastErr ?? new Error(`bridge asset not found: ${name}`);
+  return readFile(
+    fileURLToPath(
+      resolveBridgeAssetUrl({
+        name,
+        moduleUrl: import.meta.url,
+      }),
+    ),
+    'utf8',
+  );
+}
+
+export function resolveBridgeAssetUrl({
+  name,
+  moduleUrl,
+}: {
+  name: string;
+  moduleUrl: string | URL;
+}): URL {
+  return new URL(`./bridge/${name}`, moduleUrl);
 }

package/src/claude-code-bridge-protocol.ts

@@ -42,6 +42,14 @@ export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   // Claude SDK so the in-workdir thread state is rehydrated. The host sets this
   // on the first prompt after a cross-process resume.
   continue: z.boolean().optional(),
+  // Exact conversation to resume, as the Claude SDK's `resume` option.
+  //
+  // Preferred over `continue` whenever the host knows which conversation it
+  // means: `continue` resolves to the most recent thread in the workdir, which
+  // is the wrong one as soon as anything else has run there since — including
+  // a resume that itself started a new thread. Mutually exclusive with
+  // `continue` in the SDK, so the bridge sends one or the other.
+  resumeSessionId: z.string().optional(),
 });
 
 export type StartMessage = z.infer<typeof startMessageSchema>;

package/src/claude-code-harness.ts

@@ -1,4 +1,3 @@
-import { randomBytes } from 'node:crypto';
 import { posix } from 'node:path';
 import {
   commonTool,
@@ -24,6 +23,7 @@ import {
   applyCredentialForwarding,
   classifyDiskLog,
   createSandboxCredentialEnvironment,
+  createBridgeToken,
   experimental_createBridgeUserMessageSubmitter,
   createBridgeErrorHandler,
   createBridgeStartupError,
@@ -37,6 +37,7 @@ import {
   shellQuote,
   warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
+  withBridgeToken,
   writeSkills as writeHarnessSkills,
 } from '@ai-sdk/harness/utils';
 import {
@@ -802,6 +803,17 @@ const claudeCodeBridgeCoordsSchema = z.object({
 const claudeCodeResumeStateSchema = z.looseObject({
   bridge: claudeCodeBridgeCoordsSchema.optional(),
   sandboxCredentialEnvironment: z.record(z.string(), z.string()).optional(),
+  /**
+   * The exact Claude conversation to rehydrate on resume. Written by the
+   * adapter on `doStop()`/`doDetach()`/`doSuspendTurn()` from the session id
+   * the bridge observed, so a resume names the conversation instead of
+   * relying on the SDK's `continue` flag — "most recent thread in this
+   * workdir" — which silently picks the wrong one once a second thread
+   * exists there. Hosts that captured the id themselves (it is surfaced as
+   * `harnessMetadata['claude-code'].sessionId` on `finish` parts) may also
+   * set it explicitly.
+   */
+  claudeSessionId: z.string().optional(),
 });
 
 type ClaudeCodeBridgeCoords = z.infer<typeof claudeCodeBridgeCoordsSchema>;
@@ -831,7 +843,6 @@ export function createClaudeCode(
     lifecycleStateSchema: claudeCodeResumeStateSchema,
     getBootstrap: getClaudeCodeBootstrap,
     doStart: async startOpts => {
-      const model = startOpts.model ?? settings.model;
       const sandboxSession = startOpts.sandboxSession;
       const toolSafeSandboxSession =
         getRestrictedSandboxSession(sandboxSession);
@@ -860,6 +871,7 @@ export function createClaudeCode(
         ? (lifecycleState?.data as {
             bridge?: ClaudeCodeBridgeCoords;
             sandboxCredentialEnvironment?: Record<string, string>;
+            claudeSessionId?: string;
           })
         : undefined;
       const coords = resumeData?.bridge;
@@ -921,6 +933,10 @@ export function createClaudeCode(
         defaultWorkingDirectory,
         BOOTSTRAP_DIR,
       );
+      // The conversation the host wants back, when it is known. Absent on
+      // state written before this field existed; those resumes fall back to
+      // the `continue` flag as before.
+      const resumeSessionId = resumeData?.claudeSessionId;
 
       const workDir = startOpts.sessionWorkDir;
       const sandboxHomeDir = await resolveSandboxHomeDir({
@@ -994,11 +1010,12 @@ export function createClaudeCode(
           return createSession({
             sessionId: startOpts.sessionId,
             channel: attachChannel,
+            ...(resumeSessionId ? { resumeSessionId } : {}),
             // The live bridge was spawned by another process; this one owns no
             // process handle. The session lifecycle method decides whether the
             // sandbox is left running, stopped, or destroyed.
             proc: undefined,
-            model,
+            model: settings.model,
             maxTurns: settings.maxTurns,
             env: sandboxClaudeEnvironment,
             thinking,
@@ -1053,7 +1070,7 @@ export function createClaudeCode(
       });
       const token =
         settings.mintBridgeToken == null
-          ? randomBytes(32).toString('hex')
+          ? createBridgeToken()
           : settings.mintBridgeToken(sandboxId!);
       const env = {
         BRIDGE_CHANNEL_TOKEN: token,
@@ -1149,13 +1166,14 @@ export function createClaudeCode(
         sessionId: startOpts.sessionId,
         channel,
         proc,
-        model,
+        model: settings.model,
         maxTurns: settings.maxTurns,
         env: sandboxClaudeEnvironment,
         thinking,
         effort: settings.effort,
         isResume: respawnStrategy !== undefined,
         continueOnFirstPrompt: respawnStrategy !== undefined,
+        ...(resumeSessionId ? { resumeSessionId } : {}),
         rerunContinue: respawnStrategy === 'rerun',
         bridgePort: boundPort,
         bridgeToken: token,
@@ -1451,18 +1469,6 @@ function webSocketMessageToString(raw: unknown): string {
   return String(raw);
 }
 
-function withBridgeToken({
-  endpoint,
-  token,
-}: {
-  endpoint: HarnessV1PortEndpoint;
-  token: string;
-}): HarnessV1PortEndpoint {
-  const bridgeUrl = new URL(endpoint.url);
-  bridgeUrl.searchParams.set('agent_bridge_token', token);
-  return { ...endpoint, url: bridgeUrl.toString() };
-}
-
 function sleep(ms: number): Promise<void> {
   return new Promise(resolve => {
     const timer = setTimeout(resolve, ms);
@@ -1486,6 +1492,7 @@ function createSession({
   effort,
   isResume,
   continueOnFirstPrompt,
+  resumeSessionId,
   rerunContinue,
   bridgePort,
   bridgeToken,
@@ -1510,6 +1517,12 @@ function createSession({
   effort: 'low' | 'medium' | 'high' | 'xhigh' | 'max' | undefined;
   isResume: boolean;
   continueOnFirstPrompt: boolean;
+  /**
+   * Exact conversation to rehydrate whenever a fresh SDK query starts. Takes
+   * precedence over the `continue` flag, which can only mean "most recent in
+   * this workdir".
+   */
+  resumeSessionId?: string;
   rerunContinue: boolean;
   bridgePort: number;
   bridgeToken: string;
@@ -1527,12 +1540,21 @@ function createSession({
   let stopPromise: Promise<void> | undefined;
   /*
    * Force the Claude SDK's `continue: true` on the first prompt only when the
-   * bridge was respawned (rerun/replay): a fresh bridge process treats its
-   * first turn as new, so it must be told to rehydrate the workdir thread. An
-   * `attach`ed bridge is already past its first turn and continues on its own.
+   * bridge was respawned without an exact conversation id (rerun/replay): a
+   * fresh bridge process treats its first turn as new, so it must be told to
+   * rehydrate the workdir thread. Exact ids are sent independently of this
+   * fallback on every fresh query.
    */
   let pendingResumeFlag = continueOnFirstPrompt;
 
+  /*
+   * The Claude conversation this session currently embodies. Seeded from the
+   * resume state and updated from every `finish` part's metadata — each turn
+   * may fork a new id, so the latest observation is the one a later
+   * stop/detach must record for exact resume.
+   */
+  let lastClaudeSessionId = resumeSessionId;
+
   /*
    * Wire the channel into one turn's worth of events and return the control
    * surface. Shared by `doPromptTurn` (which sends a `start` afterwards) and
@@ -1588,6 +1610,9 @@ function createSession({
       'reasoning-start',
       'reasoning-delta',
       'reasoning-end',
+      'tool-input-start',
+      'tool-input-delta',
+      'tool-input-end',
       'tool-call',
       'tool-approval-request',
       'tool-result',
@@ -1603,6 +1628,14 @@ function createSession({
     }
     unsubs.push(
       channel.on('finish', msg => {
+        const metadata = (
+          msg as {
+            harnessMetadata?: { 'claude-code'?: { sessionId?: unknown } };
+          }
+        ).harnessMetadata?.['claude-code']?.sessionId;
+        if (typeof metadata === 'string' && metadata.length > 0) {
+          lastClaudeSessionId = metadata;
+        }
         forward(msg);
         settleSuccess();
       }),
@@ -1683,7 +1716,6 @@ function createSession({
   return {
     sessionId,
     isResume,
-    modelId: model,
     doPromptTurn: async promptOpts => {
       if (
         promptOpts.responseFormat?.type === 'json' &&
@@ -1730,7 +1762,7 @@ function createSession({
         ...(promptOpts.instructions
           ? { instructions: promptOpts.instructions }
           : {}),
-        model,
+        model: promptOpts.model ?? model,
         maxTurns,
         ...(env !== undefined ? { env } : {}),
         thinking,
@@ -1742,7 +1774,11 @@ function createSession({
         ...(permissionMode ? { permissionMode } : {}),
         ...(builtinToolFiltering ? { builtinToolFiltering } : {}),
         ...(debug ? { debug } : {}),
-        ...(pendingResumeFlag ? { continue: true } : {}),
+        ...(lastClaudeSessionId
+          ? { resumeSessionId: lastClaudeSessionId }
+          : pendingResumeFlag
+            ? { continue: true }
+            : {}),
       };
       pendingResumeFlag = false;
       channel.send(startMessage);
@@ -1809,7 +1845,7 @@ function createSession({
           ...(continueOpts.instructions
             ? { instructions: continueOpts.instructions }
             : {}),
-          model,
+          model: continueOpts.model ?? model,
           maxTurns,
           ...(env !== undefined ? { env } : {}),
           thinking,
@@ -1821,7 +1857,9 @@ function createSession({
           ...(permissionMode ? { permissionMode } : {}),
           ...(builtinToolFiltering ? { builtinToolFiltering } : {}),
           ...(debug ? { debug } : {}),
-          continue: true,
+          ...(lastClaudeSessionId
+            ? { resumeSessionId: lastClaudeSessionId }
+            : { continue: true }),
         });
       }
 
@@ -1863,6 +1901,9 @@ function createSession({
             lastSeenEventId,
             ...(sandboxId == null ? {} : { sandboxId }),
           },
+          ...(lastClaudeSessionId
+            ? { claudeSessionId: lastClaudeSessionId }
+            : {}),
         },
       };
       return payload;
@@ -1974,7 +2015,13 @@ function createSession({
         type: 'resume-session',
         harnessId: 'claude-code',
         specificationVersion: 'harness-v1',
+        // The bridge's stop reply carries the session id it observed; the
+        // adapter's own record backfills it when the reply predates the
+        // field or the channel was already closed.
         data: {
+          ...(lastClaudeSessionId
+            ? { claudeSessionId: lastClaudeSessionId }
+            : {}),
           ...lifecycleData,
           ...(sandboxCredentialEnvironment == null
             ? {}
@@ -2013,6 +2060,9 @@ function createSession({
             lastSeenEventId,
             ...(sandboxId == null ? {} : { sandboxId }),
           },
+          ...(lastClaudeSessionId
+            ? { claudeSessionId: lastClaudeSessionId }
+            : {}),
         },
       };
       return payload;