@ai-sdk/harness-claude-code 1.0.96 → 1.0.98

package/src/claude-code-harness.ts

@@ -90,6 +90,8 @@ export type ClaudeCodeHarnessSettings = {
   /**
    * Anthropic model id the underlying `claude` CLI should use. Leaving this
    * unset defers to the CLI's default.
+   *
+   * @deprecated Use `model` on `HarnessAgent` instead.
    */
   readonly model?: string;
   /**
@@ -800,6 +802,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>;
@@ -857,6 +870,7 @@ export function createClaudeCode(
         ? (lifecycleState?.data as {
             bridge?: ClaudeCodeBridgeCoords;
             sandboxCredentialEnvironment?: Record<string, string>;
+            claudeSessionId?: string;
           })
         : undefined;
       const coords = resumeData?.bridge;
@@ -918,8 +932,16 @@ 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({
+        sandbox: toolSafeSandboxSession,
+        abortSignal: startOpts.abortSignal,
+      });
       const sessionDataDir = `${defaultWorkingDirectory}/.agent-runs/${startOpts.sessionId}`;
       const bridgeStateDir = `${sessionDataDir}/bridge`;
       const timeoutMs = settings.startupTimeoutMs ?? 120_000;
@@ -987,6 +1009,7 @@ 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.
@@ -1006,7 +1029,8 @@ export function createClaudeCode(
             debug: startOpts.observability?.debug,
             permissionMode: startOpts.permissionMode,
             builtinToolFiltering: startOpts.builtinToolFiltering,
-            skills: startOpts.skills ?? [],
+            sandbox: toolSafeSandboxSession,
+            sandboxHomeDir,
             mcpServers: settings.mcpServers,
             supportsUserMessageResponses: () => supportsUserMessageResponses,
           });
@@ -1039,13 +1063,6 @@ export function createClaudeCode(
         }
       }
 
-      const sandboxHomeDir =
-        startOpts.skills && startOpts.skills.length > 0
-          ? await resolveSandboxHomeDir({
-              sandbox: toolSafeSandboxSession,
-              abortSignal: startOpts.abortSignal,
-            })
-          : undefined;
       const port = resolveBridgePort({
         sandboxSession,
         override: settings.port,
@@ -1057,35 +1074,21 @@ export function createClaudeCode(
       const env = {
         BRIDGE_CHANNEL_TOKEN: token,
         BRIDGE_WS_PORT: String(port),
-        ...(sandboxHomeDir ? { HOME: sandboxHomeDir } : {}),
         ...(respawnStrategy === 'replay'
           ? { BRIDGE_REPLAY_FROM_DISK: '1' }
           : {}),
       };
 
       /*
-       * On a fresh start the workdir, skill files, and bridge-state directory
-       * must be created. On any resume they already exist in the
-       * sandbox snapshot, so skip the rewrite. The env is sent fresh on every
-       * spawn — `BRIDGE_CHANNEL_TOKEN` rotates per start.
+       * On a fresh start the workdir and bridge-state directory must be
+       * created. The env is sent fresh on every spawn —
+       * `BRIDGE_CHANNEL_TOKEN` rotates per start.
        */
       if (respawnStrategy === undefined) {
         await toolSafeSandboxSession.run({
           command: `mkdir -p ${shellQuote(workDir)} ${shellQuote(bridgeStateDir)}`,
           abortSignal: startOpts.abortSignal,
         });
-
-        if (startOpts.skills && startOpts.skills.length > 0) {
-          if (!sandboxHomeDir) {
-            throw new Error('Unable to resolve sandbox HOME directory.');
-          }
-          await writeClaudeCodeSkills({
-            sandbox: toolSafeSandboxSession,
-            homeDir: sandboxHomeDir,
-            skills: startOpts.skills,
-            abortSignal: startOpts.abortSignal,
-          });
-        }
       }
 
       await markBridgeStarting({
@@ -1169,6 +1172,7 @@ export function createClaudeCode(
         effort: settings.effort,
         isResume: respawnStrategy !== undefined,
         continueOnFirstPrompt: respawnStrategy !== undefined,
+        ...(resumeSessionId ? { resumeSessionId } : {}),
         rerunContinue: respawnStrategy === 'rerun',
         bridgePort: boundPort,
         bridgeToken: token,
@@ -1177,7 +1181,8 @@ export function createClaudeCode(
         debug: startOpts.observability?.debug,
         permissionMode: startOpts.permissionMode,
         builtinToolFiltering: startOpts.builtinToolFiltering,
-        skills: startOpts.skills ?? [],
+        sandbox: toolSafeSandboxSession,
+        sandboxHomeDir,
         mcpServers: settings.mcpServers,
         supportsUserMessageResponses: () => supportsUserMessageResponses,
       });
@@ -1498,6 +1503,7 @@ function createSession({
   effort,
   isResume,
   continueOnFirstPrompt,
+  resumeSessionId,
   rerunContinue,
   bridgePort,
   bridgeToken,
@@ -1506,7 +1512,8 @@ function createSession({
   debug,
   permissionMode,
   builtinToolFiltering,
-  skills,
+  sandbox,
+  sandboxHomeDir,
   mcpServers,
   supportsUserMessageResponses,
 }: {
@@ -1521,6 +1528,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;
@@ -1529,7 +1542,8 @@ function createSession({
   debug: HarnessV1DebugConfig | undefined;
   permissionMode: HarnessV1PermissionMode | undefined;
   builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
-  skills: ReadonlyArray<HarnessV1Skill>;
+  sandbox: SandboxSession;
+  sandboxHomeDir: string;
   mcpServers: Record<string, unknown> | undefined;
   supportsUserMessageResponses: () => boolean;
 }): HarnessV1Session {
@@ -1537,12 +1551,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
@@ -1598,6 +1621,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',
@@ -1613,6 +1639,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();
       }),
@@ -1693,7 +1727,6 @@ function createSession({
   return {
     sessionId,
     isResume,
-    modelId: model,
     doPromptTurn: async promptOpts => {
       if (
         promptOpts.responseFormat?.type === 'json' &&
@@ -1705,11 +1738,27 @@ function createSession({
           harnessId: 'claude-code',
         });
       }
+      await writeClaudeCodeSkills({
+        sandbox,
+        homeDir: sandboxHomeDir,
+        skills: promptOpts.skills,
+        abortSignal: promptOpts.abortSignal,
+      });
       const control = wireTurn({
         emit: promptOpts.emit,
         abortSignal: promptOpts.abortSignal,
       });
 
+      /*
+       * A signal that was already aborted has settled the turn inside
+       * `wireTurn`. Sending `start` anyway would run a full unattended turn
+       * in the bridge — consuming tokens and possibly acting on the
+       * workspace — after the caller has already observed the abort.
+       */
+      if (promptOpts.abortSignal?.aborted) {
+        return control;
+      }
+
       const startMessage = {
         type: 'start' as const,
         prompt: extractUserText(promptOpts.prompt),
@@ -1724,19 +1773,23 @@ function createSession({
         ...(promptOpts.instructions
           ? { instructions: promptOpts.instructions }
           : {}),
-        model,
+        model: promptOpts.model ?? model,
         maxTurns,
         ...(env !== undefined ? { env } : {}),
         thinking,
         ...(effort !== undefined ? { effort } : {}),
-        ...(skills.length > 0
-          ? { skills: skills.map(skill => skill.name) }
+        ...(promptOpts.skills.length > 0
+          ? { skills: promptOpts.skills.map(skill => skill.name) }
           : {}),
         ...(mcpServers == null ? {} : { mcpServers }),
         ...(permissionMode ? { permissionMode } : {}),
         ...(builtinToolFiltering ? { builtinToolFiltering } : {}),
         ...(debug ? { debug } : {}),
-        ...(pendingResumeFlag ? { continue: true } : {}),
+        ...(lastClaudeSessionId
+          ? { resumeSessionId: lastClaudeSessionId }
+          : pendingResumeFlag
+            ? { continue: true }
+            : {}),
       };
       pendingResumeFlag = false;
       channel.send(startMessage);
@@ -1754,6 +1807,12 @@ function createSession({
           harnessId: 'claude-code',
         });
       }
+      await writeClaudeCodeSkills({
+        sandbox,
+        homeDir: sandboxHomeDir,
+        skills: continueOpts.skills,
+        abortSignal: continueOpts.abortSignal,
+      });
       const control = wireTurn({
         emit: continueOpts.emit,
         abortSignal: continueOpts.abortSignal,
@@ -1772,7 +1831,9 @@ function createSession({
        * recomputed. This is the rare bridge-died fallback; the common slice path
        * is `attach`.
        */
-      if (rerunContinue) {
+      // Same as `doPromptTurn`: an already-aborted signal settled the turn in
+      // `wireTurn`, so don't re-drive the thread nobody is waiting on.
+      if (rerunContinue && !continueOpts.abortSignal?.aborted) {
         pendingResumeFlag = false;
         channel.send({
           type: 'start' as const,
@@ -1795,19 +1856,21 @@ function createSession({
           ...(continueOpts.instructions
             ? { instructions: continueOpts.instructions }
             : {}),
-          model,
+          model: continueOpts.model ?? model,
           maxTurns,
           ...(env !== undefined ? { env } : {}),
           thinking,
           ...(effort !== undefined ? { effort } : {}),
-          ...(skills.length > 0
-            ? { skills: skills.map(skill => skill.name) }
+          ...(continueOpts.skills.length > 0
+            ? { skills: continueOpts.skills.map(skill => skill.name) }
             : {}),
           ...(mcpServers == null ? {} : { mcpServers }),
           ...(permissionMode ? { permissionMode } : {}),
           ...(builtinToolFiltering ? { builtinToolFiltering } : {}),
           ...(debug ? { debug } : {}),
-          continue: true,
+          ...(lastClaudeSessionId
+            ? { resumeSessionId: lastClaudeSessionId }
+            : { continue: true }),
         });
       }
 
@@ -1849,6 +1912,9 @@ function createSession({
             lastSeenEventId,
             ...(sandboxId == null ? {} : { sandboxId }),
           },
+          ...(lastClaudeSessionId
+            ? { claudeSessionId: lastClaudeSessionId }
+            : {}),
         },
       };
       return payload;
@@ -1960,7 +2026,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
             ? {}
@@ -1999,6 +2071,9 @@ function createSession({
             lastSeenEventId,
             ...(sandboxId == null ? {} : { sandboxId }),
           },
+          ...(lastClaudeSessionId
+            ? { claudeSessionId: lastClaudeSessionId }
+            : {}),
         },
       };
       return payload;