@ai-sdk/harness-acp 1.0.38 → 1.0.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.38",
+  "version": "1.0.39",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.100",
+    "@ai-sdk/harness": "1.0.101",
     "@ai-sdk/provider-utils": "5.0.36",
     "ws": "^8.21.0"
   },

package/src/acp-harness.ts

@@ -1,9 +1,17 @@
-import type { HarnessV1, HarnessV1PortEndpoint } from '@ai-sdk/harness';
+import {
+  HARNESS_V1_BUILTIN_TOOLS,
+  type HarnessV1,
+  type HarnessV1PortEndpoint,
+} from '@ai-sdk/harness';
 import type { ToolSet } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import type { ACPClientApp } from './acp-auth';
 import type { ACPToolCall } from './acp-tool-call';
-import { createACPV1, type ACPV1Settings } from './v1';
+import {
+  createACPV1,
+  type ACPAskUserQuestionsSettings,
+  type ACPV1Settings,
+} from './v1';
 import {
   acpColdSessionStateSchema,
   acpTurnStartConfigSchema,
@@ -15,7 +23,12 @@ const ACP_CLIENT_APP = {
   version: VERSION,
 } as const satisfies ACPClientApp;
 
-export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
+export type ACPHarnessSettings<
+  TBuiltinTools extends ToolSet = {},
+  TAskUserQuestions extends ACPAskUserQuestionsSettings | undefined =
+    | ACPAskUserQuestionsSettings
+    | undefined,
+> = {
   readonly builtinTools?: TBuiltinTools;
   /**
    * MCP server definitions keyed by server name. Each definition uses the
@@ -61,6 +74,7 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
   readonly outputSchemaMapping?: ACPV1Settings['outputSchemaMapping'];
+  readonly askUserQuestions?: TAskUserQuestions;
   readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
   readonly session?: ACPV1Settings['session'];
   readonly mintBridgeToken?: ACPV1Settings['mintBridgeToken'];
@@ -117,9 +131,22 @@ const acpResumeStateSchema = z.object({
 
 type ACPBridgeCoords = z.infer<typeof acpBridgeCoordsSchema>;
 
-export function createACP<TBuiltinTools extends ToolSet = {}>(
-  settings: ACPHarnessSettings<TBuiltinTools>,
-): HarnessV1<TBuiltinTools> {
+type ACPHarnessTools<
+  TBuiltinTools extends ToolSet,
+  TAskUserQuestions,
+> = TBuiltinTools &
+  ([TAskUserQuestions] extends [undefined]
+    ? {}
+    : {
+        askUserQuestions: typeof HARNESS_V1_BUILTIN_TOOLS.askUserQuestions;
+      });
+
+export function createACP<
+  TBuiltinTools extends ToolSet = {},
+  TAskUserQuestions extends ACPAskUserQuestionsSettings | undefined = undefined,
+>(
+  settings: ACPHarnessSettings<TBuiltinTools, TAskUserQuestions>,
+): HarnessV1<ACPHarnessTools<TBuiltinTools, TAskUserQuestions>> {
   if (
     (settings.credentialEnv == null) !==
     (settings.credentialBrokering == null)
@@ -143,10 +170,17 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
   switch (version) {
     case 'v1': {
       const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
+      const builtinTools =
+        settings.askUserQuestions == null
+          ? (settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools))
+          : {
+              ...(settings.builtinTools ??
+                (ACP_BUILTIN_TOOLS as TBuiltinTools)),
+              askUserQuestions: HARNESS_V1_BUILTIN_TOOLS.askUserQuestions,
+            };
       return createACPV1({
         settings,
-        builtinTools:
-          settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),
+        builtinTools,
         port: settings.port,
         portEndpoint: settings.portEndpoint,
         startupTimeoutMs: settings.startupTimeoutMs,
@@ -154,7 +188,7 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
         lifecycleStateSchema: acpResumeStateSchema satisfies z.ZodType<{
           bridge?: ACPBridgeCoords;
         }>,
-      });
+      }) as HarnessV1<ACPHarnessTools<TBuiltinTools, TAskUserQuestions>>;
     }
     default:
       throw new Error(

package/src/index.ts

@@ -20,6 +20,7 @@ export type {
   ACPToolKind,
 } from './acp-tool-call';
 export type {
+  ACPAskUserQuestionsSettings,
   ACPCredentialBrokering,
   ACPAuthentication,
   ACPInstallCommandSource,

package/src/v1/acp-v1-bridge-protocol.ts

@@ -199,6 +199,7 @@ const coldRestoreSchema = z.object({
 
 const acpToolCallCandidateSchema = z.object({
   type: z.literal('acp-tool-call-candidate'),
+  requestId: z.string(),
   toolCall: z.custom<ACPToolCall>(
     value =>
       value != null &&
@@ -208,9 +209,23 @@ const acpToolCallCandidateSchema = z.object({
   ),
 });
 
+const acpQuestionRequestSchema = z.object({
+  type: z.literal('acp-question-request'),
+  requestId: z.string(),
+  nativeRequest: z.unknown(),
+  nativeToolCall: acpToolCallCandidateSchema.shape.toolCall.optional(),
+});
+
+const acpQuestionResolvedSchema = z.object({
+  type: z.literal('acp-question-resolved'),
+  requestId: z.string(),
+});
+
 export const outboundMessageSchema = z.union([
   harnessV1BridgeOutboundMessageSchema,
   acpToolCallCandidateSchema,
+  acpQuestionRequestSchema,
+  acpQuestionResolvedSchema,
 ]);
 export type OutboundMessage = z.infer<typeof outboundMessageSchema>;
 

package/src/v1/acp-v1-harness.ts

@@ -37,6 +37,7 @@ import {
   asSchema,
   type Experimental_SandboxProcess,
   type Experimental_SandboxSession as SandboxSession,
+  type ToolResultPart,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
 import { WebSocket } from 'ws';
@@ -81,6 +82,7 @@ import {
   prependACPInstructionGuidance,
 } from './acp-v1-prompt';
 import type {
+  ACPAskUserQuestionsSettings,
   ACPInstructionMapping,
   ACPModelMapping,
   ACPOutputSchemaMapping,
@@ -442,6 +444,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
               outputSchemaMapping: settings.outputSchemaMapping,
+              askUserQuestions: settings.askUserQuestions,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
@@ -615,6 +618,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               sandboxProviderEnvironment == null ? undefined : {},
             sessionMeta: settings.session?.meta,
             clientCapabilities: settings.clientCapabilities,
+            askUserQuestionsRequestMethod:
+              settings.askUserQuestions?.requestMethod,
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -732,6 +737,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
         outputSchemaMapping: settings.outputSchemaMapping,
+        askUserQuestions: settings.askUserQuestions,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
@@ -1045,6 +1051,7 @@ function createSession({
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
+  askUserQuestions,
   debug,
   implementationIdentity,
   authenticationProfile,
@@ -1081,6 +1088,7 @@ function createSession({
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
   outputSchemaMapping: ACPOutputSchemaMapping | undefined;
+  askUserQuestions: ACPAskUserQuestionsSettings | undefined;
   debug: HarnessV1DebugConfig | undefined;
   implementationIdentity: string;
   authenticationProfile: ACPAuthenticationProfileIdentity;
@@ -1114,6 +1122,14 @@ function createSession({
   let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
+  const bufferedQuestionResults = new Map<
+    string,
+    {
+      readonly output: unknown;
+      readonly isError?: boolean;
+      readonly toolResult: ToolResultPart;
+    }
+  >();
 
   const markTurnFinished = () => {
     turnInFlight = false;
@@ -1154,6 +1170,14 @@ function createSession({
       | undefined;
     const dynamicToolCalls = new Map<string, boolean>();
     const toolCallClassificationErrors = new Map<string, unknown>();
+    const activeQuestionRequests = new Map<
+      string,
+      {
+        readonly requestId: string;
+        readonly nativeRequest: unknown;
+      }
+    >();
+    const questionToolCallIdsByRequestId = new Map<string, string>();
     const subscriptions: Array<() => void> = [];
     const forward = (event: HarnessV1StreamPart) => {
       if (event.type === 'text-start' || event.type === 'reasoning-start') {
@@ -1220,12 +1244,120 @@ function createSession({
     subscriptions.push(
       channel.on('acp-tool-call-candidate', event => {
         try {
+          const suppress =
+            askUserQuestions?.isNativeToolCall?.({
+              nativeToolCall: event.toolCall,
+            }) === true;
           dynamicToolCalls.set(
             event.toolCall.toolCallId,
             isMcpToolCall?.(event.toolCall) === true,
           );
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: { suppress },
+          });
         } catch (error) {
           toolCallClassificationErrors.set(event.toolCall.toolCallId, error);
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: { suppress: false },
+          });
+        }
+      }),
+    );
+    subscriptions.push(
+      channel.on('acp-question-request', event => {
+        if (askUserQuestions == null) {
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: { type: 'unhandled' },
+          });
+          return;
+        }
+        try {
+          const nativeToolCall = askUserQuestions.fromNativeRequest({
+            nativeRequest: event.nativeRequest,
+            nativeToolCall: event.nativeToolCall,
+          });
+          if (nativeToolCall == null) {
+            channel.send({
+              type: 'tool-result',
+              toolCallId: event.requestId,
+              output: { type: 'unhandled' },
+            });
+            return;
+          }
+          if (
+            nativeToolCall.toolName !== 'askUserQuestions' ||
+            nativeToolCall.providerExecuted !== false
+          ) {
+            throw new Error(
+              `${harnessId} ACP askUserQuestions.fromNativeRequest must return a client-executed askUserQuestions tool call.`,
+            );
+          }
+
+          const toolCall = withNativeQuestionRequest({
+            harnessId,
+            nativeRequest: event.nativeRequest,
+            toolCall: nativeToolCall,
+          });
+          const bufferedResult = takeBufferedQuestionResult({
+            bufferedQuestionResults,
+            toolCallId: toolCall.toolCallId,
+            nativeRequest: event.nativeRequest,
+            matchesNativeRequest: askUserQuestions.matchesNativeRequest,
+            harnessId,
+          });
+          activeQuestionRequests.set(toolCall.toolCallId, {
+            requestId: event.requestId,
+            nativeRequest: event.nativeRequest,
+          });
+          questionToolCallIdsByRequestId.set(
+            event.requestId,
+            toolCall.toolCallId,
+          );
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: {
+              type: 'handled',
+              toolCallId: toolCall.toolCallId,
+            },
+          });
+
+          if (bufferedResult == null) {
+            forward(toolCall);
+            return;
+          }
+          channel.send({
+            type: 'tool-result',
+            toolCallId: toolCall.toolCallId,
+            output: askUserQuestions.toNativeResponse({
+              nativeRequest: event.nativeRequest,
+              toolResult: bufferedResult.toolResult,
+            }),
+            isError: bufferedResult.isError,
+            toolResult: bufferedResult.toolResult,
+          });
+        } catch (error) {
+          closeForwardedBlock();
+          forward({ type: 'error', error });
+          try {
+            channel.send({ type: 'abort' });
+          } catch {}
+          settle({ error });
+        }
+      }),
+    );
+    subscriptions.push(
+      channel.on('acp-question-resolved', event => {
+        const toolCallId = questionToolCallIdsByRequestId.get(event.requestId);
+        if (toolCallId != null) {
+          activeQuestionRequests.delete(toolCallId);
+          questionToolCallIdsByRequestId.delete(event.requestId);
         }
       }),
     );
@@ -1315,11 +1447,52 @@ function createSession({
         });
       },
       submitToolResult: async input => {
+        if (
+          askUserQuestions != null &&
+          input.toolResult?.toolName === 'askUserQuestions'
+        ) {
+          const activeRequest = activeQuestionRequests.get(input.toolCallId);
+          if (activeRequest == null) {
+            const previousNativeRequest =
+              input.toolResult.providerOptions?.[harnessId]?.nativeRequest;
+            if (!lossyRerun && previousNativeRequest !== undefined) {
+              channel.send({
+                type: 'tool-result',
+                toolCallId: input.toolCallId,
+                output: askUserQuestions.toNativeResponse({
+                  nativeRequest: previousNativeRequest,
+                  toolResult: input.toolResult,
+                }),
+                isError: input.isError,
+                toolResult: input.toolResult,
+              });
+              return;
+            }
+            bufferedQuestionResults.set(input.toolCallId, {
+              output: input.output,
+              ...(input.isError == null ? {} : { isError: input.isError }),
+              toolResult: input.toolResult,
+            });
+            return;
+          }
+          channel.send({
+            type: 'tool-result',
+            toolCallId: input.toolCallId,
+            output: askUserQuestions.toNativeResponse({
+              nativeRequest: activeRequest.nativeRequest,
+              toolResult: input.toolResult,
+            }),
+            isError: input.isError,
+            toolResult: input.toolResult,
+          });
+          return;
+        }
         channel.send({
           type: 'tool-result',
           toolCallId: input.toolCallId,
           output: input.output,
           isError: input.isError,
+          toolResult: input.toolResult,
         });
       },
       done,
@@ -1682,6 +1855,78 @@ function isCompletePermissionModeMapping({
   );
 }
 
+function withNativeQuestionRequest({
+  harnessId,
+  nativeRequest,
+  toolCall,
+}: {
+  harnessId: string;
+  nativeRequest: unknown;
+  toolCall: Extract<HarnessV1StreamPart, { type: 'tool-call' }>;
+}): Extract<HarnessV1StreamPart, { type: 'tool-call' }> {
+  const harnessMetadata = toolCall.providerMetadata?.[harnessId];
+  return {
+    ...toolCall,
+    providerMetadata: {
+      ...toolCall.providerMetadata,
+      [harnessId]: {
+        ...(harnessMetadata ?? {}),
+        nativeRequest,
+      } as NonNullable<
+        Extract<HarnessV1StreamPart, { type: 'tool-call' }>['providerMetadata']
+      >[string],
+    },
+  };
+}
+
+function takeBufferedQuestionResult({
+  bufferedQuestionResults,
+  toolCallId,
+  nativeRequest,
+  matchesNativeRequest,
+  harnessId,
+}: {
+  bufferedQuestionResults: Map<
+    string,
+    {
+      readonly output: unknown;
+      readonly isError?: boolean;
+      readonly toolResult: ToolResultPart;
+    }
+  >;
+  toolCallId: string;
+  nativeRequest: unknown;
+  matchesNativeRequest:
+    | ACPAskUserQuestionsSettings['matchesNativeRequest']
+    | undefined;
+  harnessId: string;
+}):
+  | {
+      readonly output: unknown;
+      readonly isError?: boolean;
+      readonly toolResult: ToolResultPart;
+    }
+  | undefined {
+  const exact = bufferedQuestionResults.get(toolCallId);
+  if (exact != null) {
+    bufferedQuestionResults.delete(toolCallId);
+    return exact;
+  }
+  if (matchesNativeRequest == null) return undefined;
+  for (const [bufferedToolCallId, buffered] of bufferedQuestionResults) {
+    const previousNativeRequest =
+      buffered.toolResult.providerOptions?.[harnessId]?.nativeRequest;
+    if (
+      previousNativeRequest !== undefined &&
+      matchesNativeRequest({ previousNativeRequest, nativeRequest })
+    ) {
+      bufferedQuestionResults.delete(bufferedToolCallId);
+      return buffered;
+    }
+  }
+  return undefined;
+}
+
 function isPermissionModeMappingValue({
   value,
 }: {

package/src/v1/acp-v1-settings.ts

@@ -3,7 +3,9 @@ import type {
   HarnessV1CredentialForwarding,
   HarnessV1PermissionMode,
   HarnessV1RequestTransformation,
+  HarnessV1StreamPart,
 } from '@ai-sdk/harness';
+import type { ToolResultPart } from '@ai-sdk/provider-utils';
 import type { ACPToolCall } from '../acp-tool-call';
 
 export type ACPSerializablePrimitive = string | number | boolean | null;
@@ -129,6 +131,25 @@ export type ACPOutputSchemaMapping = {
   readonly path: ReadonlyArray<string>;
 };
 
+export type ACPAskUserQuestionsSettings = {
+  readonly requestMethod: string;
+  readonly isNativeToolCall?: (options: {
+    nativeToolCall: ACPToolCall;
+  }) => boolean;
+  readonly fromNativeRequest: (options: {
+    nativeRequest: unknown;
+    nativeToolCall?: ACPToolCall;
+  }) => Extract<HarnessV1StreamPart, { type: 'tool-call' }> | null;
+  readonly toNativeResponse: (options: {
+    nativeRequest: unknown;
+    toolResult: ToolResultPart;
+  }) => unknown;
+  readonly matchesNativeRequest?: (options: {
+    previousNativeRequest: unknown;
+    nativeRequest: unknown;
+  }) => boolean;
+};
+
 export type ACPV1Settings = {
   readonly version?: 'v1';
   readonly harnessId: string;
@@ -179,6 +200,7 @@ export type ACPV1Settings = {
    * below the ACP session prompt's `_meta` field.
    */
   readonly outputSchemaMapping?: ACPOutputSchemaMapping;
+  readonly askUserQuestions?: ACPAskUserQuestionsSettings;
   readonly permissionModeMapping?: ACPPermissionModeMapping;
   readonly session?: {
     readonly meta?: Readonly<Record<string, ACPSerializableValue>>;

package/src/v1/bridge/acp-v1-bridge-environment.ts

@@ -60,6 +60,7 @@ export type ACPBridgeConfiguration = {
   readonly providerEnvironment?: Readonly<Record<string, string>>;
   readonly sessionMeta?: Readonly<Record<string, ACPSerializableValue>>;
   readonly clientCapabilities?: Readonly<Record<string, ACPSerializableValue>>;
+  readonly askUserQuestionsRequestMethod?: string;
 };
 
 const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
@@ -68,6 +69,7 @@ const bridgeConfigurationSchema: z.ZodType<ACPBridgeConfiguration> = z.object({
   providerEnvironment: z.record(z.string(), z.string()).optional(),
   sessionMeta: serializableRecordSchema.optional(),
   clientCapabilities: serializableRecordSchema.optional(),
+  askUserQuestionsRequestMethod: z.string().optional(),
 });
 
 export function createACPBridgeEnvironment({
@@ -76,6 +78,7 @@ export function createACPBridgeEnvironment({
   providerEnvironment,
   sessionMeta,
   clientCapabilities,
+  askUserQuestionsRequestMethod,
 }: ACPBridgeConfiguration): Record<string, string> {
   return {
     [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
@@ -84,6 +87,9 @@ export function createACPBridgeEnvironment({
       ...(providerEnvironment == null ? {} : { providerEnvironment }),
       ...(sessionMeta == null ? {} : { sessionMeta }),
       ...(clientCapabilities == null ? {} : { clientCapabilities }),
+      ...(askUserQuestionsRequestMethod == null
+        ? {}
+        : { askUserQuestionsRequestMethod }),
     }),
   };
 }

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

@@ -51,6 +51,8 @@ export function createEmitStreamEvent({
     order: number;
   }) => void;
   removeHostToolCorrelationInvocation: (options: { token: string }) => void;
+  suppressToolCall: (options: { toolCallId: string }) => void;
+  getToolCall: (options: { toolCallId: string }) => ACPToolCall | undefined;
 } {
   const translator = createACPStreamTranslator({
     emit,
@@ -100,5 +102,9 @@ export function createEmitStreamEvent({
     hostToolResult: translator.hostToolResult,
     registerHostToolCorrelationInvocation: correlation.registerInvocation,
     removeHostToolCorrelationInvocation: correlation.removeInvocation,
+    suppressToolCall: correlation.suppressToolCall,
+    getToolCall: ({ toolCallId }) =>
+      correlation.getToolCall({ toolCallId }) ??
+      translator.getToolCall({ toolCallId }),
   };
 }

package/src/v1/bridge/host-tool-correlation.ts

@@ -2,6 +2,7 @@ import type {
   ActiveSessionMessage,
   ToolCallUpdate,
 } from '@agentclientprotocol/sdk';
+import type { ACPToolCall } from '../../acp-tool-call';
 
 type SessionUpdateMessage = Extract<
   ActiveSessionMessage,
@@ -55,6 +56,8 @@ export function createHostToolCorrelation({
     order: number;
   }): void;
   claimHostToolPermission(options: { toolCall: ToolCallUpdate }): boolean;
+  suppressToolCall(options: { toolCallId: string }): void;
+  getToolCall(options: { toolCallId: string }): ACPToolCall | undefined;
   flush(): void;
   removeInvocation(options: { token: string }): void;
   close(): void;
@@ -63,6 +66,7 @@ export function createHostToolCorrelation({
   const candidates = new Map<string, CorrelationCandidate>();
   const suppressedToolCallIds = new Set<string>();
   const releasedToolCallIds = new Set<string>();
+  const observedToolCalls = new Map<string, ACPToolCall>();
   let nextCandidateOrder = 0;
   let buffered: BufferedUpdate[] = [];
   let flushTimer: ReturnType<typeof setTimeout> | undefined;
@@ -155,6 +159,13 @@ export function createHostToolCorrelation({
       }
 
       const toolCallId = message.update.toolCallId;
+      observedToolCalls.set(
+        toolCallId,
+        mergeObservedToolCall({
+          previous: observedToolCalls.get(toolCallId),
+          update: message.update,
+        }),
+      );
       if (suppressedToolCallIds.has(toolCallId)) {
         if (isTerminalToolUpdate(message)) {
           suppressedToolCallIds.delete(toolCallId);
@@ -242,6 +253,8 @@ export function createHostToolCorrelation({
       suppressToolCallUpdate({ toolCallId: toolCall.toolCallId });
       return true;
     },
+    suppressToolCall: suppressToolCallUpdate,
+    getToolCall: ({ toolCallId }) => observedToolCalls.get(toolCallId),
     flush,
     removeInvocation: ({ token }) => {
       deleteInvocation({ invocations, token });
@@ -257,10 +270,31 @@ export function createHostToolCorrelation({
       candidates.clear();
       suppressedToolCallIds.clear();
       releasedToolCallIds.clear();
+      observedToolCalls.clear();
     },
   };
 }
 
+function mergeObservedToolCall({
+  previous,
+  update,
+}: {
+  previous: ACPToolCall | undefined;
+  update: ToolCallUpdate;
+}): ACPToolCall {
+  return {
+    toolCallId: update.toolCallId,
+    title: update.title ?? previous?.title ?? `Tool ${update.toolCallId}`,
+    ...(update.kind == null ? {} : { kind: update.kind }),
+    ...(update.status == null ? {} : { status: update.status }),
+    ...(update.content == null ? {} : { content: update.content }),
+    ...(update.locations == null ? {} : { locations: update.locations }),
+    ...(update.rawInput === undefined ? {} : { rawInput: update.rawInput }),
+    ...(update.rawOutput === undefined ? {} : { rawOutput: update.rawOutput }),
+    ...(update._meta === undefined ? {} : { _meta: update._meta }),
+  };
+}
+
 function hasPortableEvidence({
   candidate,
   invocation,