@ai-sdk/harness-acp 1.0.24 → 1.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.24",
+  "version": "1.0.28",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,9 +26,9 @@
     }
   },
   "dependencies": {
-    "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.86",
-    "@ai-sdk/provider-utils": "5.0.29"
+    "@ai-sdk/harness": "1.0.90",
+    "@ai-sdk/provider-utils": "5.0.32",
+    "ws": "^8.21.0"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"
@@ -38,10 +38,10 @@
     "@modelcontextprotocol/sdk": "1.29.0",
     "@types/node": "22.19.19",
     "@types/ws": "^8.5.13",
+    "@vercel/ai-tsconfig": "0.0.0",
     "tsup": "^8.5.1",
     "typescript": "5.8.3",
-    "zod": "3.25.76",
-    "@vercel/ai-tsconfig": "0.0.0"
+    "zod": "3.25.76"
   },
   "engines": {
     "node": ">=22"

package/src/acp-harness.ts

@@ -40,6 +40,12 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly forwardEnv?: ACPV1Settings['forwardEnv'];
   readonly credentialEnv?: ACPV1Settings['credentialEnv'];
   readonly credentialBrokering?: ACPV1Settings['credentialBrokering'];
+  /**
+   * Customizes each credential value before it is forwarded into a sandbox
+   * process. This does not restrict which credentials the harness adapter can
+   * discover, read, or otherwise access in the host process.
+   */
+  readonly credentialForwarding?: ACPV1Settings['credentialForwarding'];
   readonly env?: ACPV1Settings['env'];
   readonly authentication?: ACPV1Settings['authentication'];
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
@@ -79,6 +85,7 @@ const acpResumeStateSchema = z.object({
         .optional(),
     })
     .optional(),
+  sandboxCredentialEnvironment: z.record(z.string(), z.string()).optional(),
   acpSessionId: z.string().optional(),
   bridge: acpBridgeCoordsSchema.optional(),
   coldSession: acpColdSessionStateSchema.optional(),

package/src/v1/acp-bootstrap.ts

@@ -7,6 +7,7 @@ import {
   createImplementationManifest,
   getImplementationInstallScript,
   getImplementationLockfile,
+  getImplementationWorkspaceFile,
   type ACPImplementation,
 } from './implementation';
 
@@ -40,6 +41,9 @@ export function createACPBootstrap({
       const implementationLock = getImplementationLockfile({
         implementation,
       });
+      const implementationWorkspace = getImplementationWorkspaceFile({
+        implementation,
+      });
       const implementationInstallScript = getImplementationInstallScript({
         implementation,
       });
@@ -80,6 +84,14 @@ export function createACPBootstrap({
                   content: implementationLock,
                 },
               ]),
+          ...(implementationWorkspace == null
+            ? []
+            : [
+                {
+                  path: `${bootstrapDir}/implementation/pnpm-workspace.yaml`,
+                  content: implementationWorkspace,
+                },
+              ]),
           ...(implementationInstallScript == null
             ? []
             : [

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

@@ -32,6 +32,18 @@ export type ACPBuiltinToolMapping = {
    */
   readonly nativeName?: HarnessV1BuiltinTool['nativeName'];
 
+  /**
+   * Stable prefix of the display title emitted by an ACP implementation.
+   * Used only when the implementation omits a programmatic tool name.
+   */
+  readonly title?: HarnessV1BuiltinTool['title'];
+
+  /**
+   * Broad capability category used to compare a built-in with the ACP tool
+   * kind when resolving unnamed calls.
+   */
+  readonly toolUseKind?: HarnessV1BuiltinTool['toolUseKind'];
+
   /**
    * JSON Schema used to identify tool calls when an ACP implementation does
    * not provide a programmatic tool name. It is optional because built-in
@@ -43,6 +55,8 @@ export type ACPBuiltinToolMapping = {
 const builtinToolSchema: z.ZodType<ACPBuiltinToolMapping> = z.object({
   toolName: z.string(),
   nativeName: z.string().optional(),
+  title: z.string().optional(),
+  toolUseKind: z.enum(['readonly', 'edit', 'bash']).optional(),
   inputSchema: z.json().optional(),
 });
 

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

@@ -14,14 +14,15 @@ import {
 } from '@ai-sdk/harness';
 import { HarnessBridgeCapabilityUnsupportedError } from '@ai-sdk/harness/bridge';
 import {
+  applyCredentialForwarding,
   createBridgeErrorHandler,
   createBridgeStartupError,
+  createSandboxCredentialEnvironment,
   classifyDiskLog,
   drainBridgeProcessStream,
   forwardBridgeProcessStream,
   getRestrictedSandboxSession,
   markBridgeStarting,
-  maskSandboxCredentials,
   resolveSandboxDefaultWorkingDirectory,
   resolveSandboxHomeDir,
   SandboxChannel,
@@ -82,6 +83,7 @@ import type {
   ACPOutputSchemaMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
+  ACPProfileValue,
   ACPSerializableValue,
   ACPV1Settings,
 } from './acp-v1-settings';
@@ -235,6 +237,25 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           sandboxSession,
           abortSignal: startOptions.abortSignal,
         });
+      const continueFrom =
+        startOptions.continueFrom ?? startOptions.resumeFrom?.continueFrom;
+      const lifecycleState = continueFrom ?? startOptions.resumeFrom;
+      const isContinue = continueFrom != null;
+      const isResume = lifecycleState != null;
+      const lifecycleData =
+        lifecycleState != null
+          ? (lifecycleState.data as unknown as ACPLifecycleData)
+          : undefined;
+      if (lifecycleData != null && lifecycleState != null) {
+        validateACPLifecycleCompatibility({
+          harnessId: settings.harnessId,
+          lifecycleHarnessId: lifecycleState.harnessId,
+          implementationIdentity,
+          authenticationProfile,
+          lifecycleData,
+          sandboxId,
+        });
+      }
       const implementationEnvironment = resolveImplementationEnvironment({
         implementation,
         env,
@@ -243,6 +264,25 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       let sandboxProviderAuthenticationEnvironment =
         resolvedProviderAuthentication.env;
       let sandboxProviderEnvironment: Record<string, string> | undefined;
+      const credentialEnvironmentVariables = [
+        ...new Set([
+          ...(settings.credentialEnv ?? []),
+          'AI_GATEWAY_API_KEY',
+          'VERCEL_OIDC_TOKEN',
+        ]),
+      ];
+      const credentialForwardingEnvironmentVariables = [
+        ...new Set([
+          ...credentialEnvironmentVariables,
+          ...resolveACPProviderCredentialEnvironmentVariables({
+            providerAuthentication:
+              resolvedProviderAuthentication.providerAuthentication,
+          }),
+        ]),
+      ];
+      let sandboxCredentialEnvironment:
+        | Readonly<Record<string, string>>
+        | undefined;
 
       if (
         settings.credentialBrokering != null &&
@@ -253,44 +293,55 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           resolvedProviderAuthentication,
           clientApp,
         });
-        const credentialEnvironmentVariables = [
-          ...new Set([
-            ...(settings.credentialEnv ?? []),
-            'AI_GATEWAY_API_KEY',
-            'VERCEL_OIDC_TOKEN',
-          ]),
-        ];
+        const brokeringEnvironment = {
+          ...implementationEnvironment,
+          ...providerEnvironment,
+        };
+        sandboxCredentialEnvironment =
+          lifecycleData?.sandboxCredentialEnvironment ??
+          (await createSandboxCredentialEnvironment({
+            environment: brokeringEnvironment,
+            credentialEnvironmentVariables:
+              credentialForwardingEnvironmentVariables,
+            credentialForwarding: settings.credentialForwarding,
+          }));
+        sandboxImplementationEnvironment = {
+          ...brokeringEnvironment,
+          ...sandboxCredentialEnvironment,
+        };
         const requestTransformations = settings.credentialBrokering({
-          env: {
-            ...implementationEnvironment,
-            ...providerEnvironment,
-          },
+          env: brokeringEnvironment,
+          sandboxEnv: sandboxImplementationEnvironment,
         });
         if (requestTransformations.length > 0) {
           await sandboxSession.addRequestTransformations(
             requestTransformations,
           );
         }
-        sandboxImplementationEnvironment = maskSandboxCredentials({
-          environment: implementationEnvironment,
-          credentialEnvironmentVariables,
-        });
-
-        /*
-         * Gateway profiles are resolved on the host twice: real values feed
-         * the transformation callback, while the bridge receives only a
-         * structurally equivalent environment with credential placeholders.
-         * Resolving the profile inside the sandbox would require serializing
-         * the Gateway credential into the bridge process environment.
-         */
-        sandboxProviderEnvironment = maskSandboxCredentials({
-          environment: resolveProviderEnvironment({
-            resolvedProviderAuthentication,
-            clientApp,
-            gatewayApiKey: 'AI_GATEWAY_API_KEY',
-          }),
-          credentialEnvironmentVariables,
+        sandboxProviderEnvironment =
+          resolvedProviderAuthentication.providerAuthentication?.type ===
+          'ai-gateway'
+            ? {}
+            : undefined;
+      } else if (settings.credentialBrokering != null) {
+        warnCredentialBrokeringUnavailable();
+      }
+      if (
+        settings.credentialForwarding != null &&
+        sandboxProviderEnvironment == null &&
+        resolvedProviderAuthentication.providerAuthentication?.type ===
+          'ai-gateway'
+      ) {
+        sandboxProviderEnvironment = resolveProviderEnvironment({
+          resolvedProviderAuthentication,
+          clientApp,
         });
+      }
+      if (sandboxProviderEnvironment != null) {
+        sandboxImplementationEnvironment = {
+          ...sandboxImplementationEnvironment,
+          ...sandboxProviderEnvironment,
+        };
         sandboxProviderAuthenticationEnvironment = Object.fromEntries(
           Object.entries(resolvedProviderAuthentication.env).filter(
             ([key]) =>
@@ -298,8 +349,6 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               key !== 'AI_SDK_ACP_GATEWAY_BASE_URL',
           ),
         );
-      } else if (settings.credentialBrokering != null) {
-        warnCredentialBrokeringUnavailable();
       }
       const resolvedBridgeDir = posix.resolve(
         defaultWorkingDirectory,
@@ -318,25 +367,6 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         sessionId: startOptions.sessionId,
       });
       const bridgeStateDir = `${privateSessionDir}/bridge`;
-      const continueFrom =
-        startOptions.continueFrom ?? startOptions.resumeFrom?.continueFrom;
-      const lifecycleState = continueFrom ?? startOptions.resumeFrom;
-      const isContinue = continueFrom != null;
-      const isResume = lifecycleState != null;
-      const lifecycleData =
-        lifecycleState != null
-          ? (lifecycleState.data as unknown as ACPLifecycleData)
-          : undefined;
-      if (lifecycleData != null && lifecycleState != null) {
-        validateACPLifecycleCompatibility({
-          harnessId: settings.harnessId,
-          lifecycleHarnessId: lifecycleState.harnessId,
-          implementationIdentity,
-          authenticationProfile,
-          lifecycleData,
-          sandboxId,
-        });
-      }
       const skills = startOptions.skills ?? [];
       const skillsFingerprint = createACPSkillsFingerprint({ skills });
       const shouldMaterializeSkills = shouldMaterializeACPSkills({
@@ -441,6 +471,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               turnStartConfig: lifecycleData.turnStartConfig,
               recoveryStatus: lifecycleData.recovery,
               restoration: lifecycleData.restoration,
+              sandboxCredentialEnvironment,
               replayOnly: false,
               lossyRerun: false,
             });
@@ -521,6 +552,15 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         }
       }
 
+      const forwardedImplementationEnvironment =
+        sandboxCredentialEnvironment == null
+          ? await applyCredentialForwarding({
+              environment: sandboxImplementationEnvironment,
+              credentialEnvironmentVariables:
+                credentialForwardingEnvironmentVariables,
+              credentialForwarding: settings.credentialForwarding,
+            })
+          : sandboxImplementationEnvironment;
       const port = resolveBridgePort({
         sandboxSession,
         override: portOverride,
@@ -549,12 +589,13 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           ` --implementation-dir ${shellQuote(resolvedImplementationDir)}` +
           ` --bridge-type ${shellQuote(settings.harnessId)}`,
         env: {
-          ...sandboxImplementationEnvironment,
+          ...forwardedImplementationEnvironment,
           ...createACPBridgeEnvironment({
             authentication: settings.authentication,
             providerAuthentication:
               resolvedProviderAuthentication.providerAuthentication,
-            providerEnvironment: sandboxProviderEnvironment,
+            providerEnvironment:
+              sandboxProviderEnvironment == null ? undefined : {},
             sessionMeta: settings.session?.meta,
           }),
           ...sandboxProviderAuthenticationEnvironment,
@@ -712,6 +753,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
           coldRestoration == null
             ? lifecycleData?.restoration
             : { method: coldRestoration },
+        sandboxCredentialEnvironment,
         replayOnly: respawnStrategy?.mode === 'disk-replay',
         lossyRerun: respawnStrategy?.mode === 'lossy-rerun',
       });
@@ -722,13 +764,11 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
 function resolveProviderEnvironment({
   resolvedProviderAuthentication,
   clientApp,
-  gatewayApiKey,
 }: {
   resolvedProviderAuthentication: ReturnType<
     typeof resolveACPProviderAuthentication
   >;
   clientApp: ACPClientApp;
-  gatewayApiKey?: string;
 }): Record<string, string> {
   if (
     resolvedProviderAuthentication.providerAuthentication?.type !== 'ai-gateway'
@@ -739,12 +779,10 @@ function resolveProviderEnvironment({
     providerAuthentication:
       resolvedProviderAuthentication.providerAuthentication,
     gateway: {
-      apiKey:
-        gatewayApiKey ??
-        requireResolvedEnvironmentValue({
-          environment: resolvedProviderAuthentication.env,
-          name: 'AI_SDK_ACP_GATEWAY_API_KEY',
-        }),
+      apiKey: requireResolvedEnvironmentValue({
+        environment: resolvedProviderAuthentication.env,
+        name: 'AI_SDK_ACP_GATEWAY_API_KEY',
+      }),
       baseUrl: requireResolvedEnvironmentValue({
         environment: resolvedProviderAuthentication.env,
         name: 'AI_SDK_ACP_GATEWAY_BASE_URL',
@@ -755,6 +793,40 @@ function resolveProviderEnvironment({
   });
 }
 
+function resolveACPProviderCredentialEnvironmentVariables({
+  providerAuthentication,
+}: {
+  providerAuthentication: ReturnType<
+    typeof resolveACPProviderAuthentication
+  >['providerAuthentication'];
+}): string[] {
+  if (providerAuthentication?.type !== 'ai-gateway') return [];
+
+  return Object.entries(providerAuthentication.env)
+    .filter(([, value]) => containsACPProviderCredential({ value }))
+    .map(([name]) => name);
+}
+
+function containsACPProviderCredential({
+  value,
+}: {
+  value: ACPProfileValue;
+}): boolean {
+  if (Array.isArray(value)) {
+    return value.some(item => containsACPProviderCredential({ value: item }));
+  }
+  if (value == null || typeof value !== 'object') return false;
+  if ('$source' in value) {
+    return (
+      value.$source === 'gateway-api-key' ||
+      value.$source === 'gateway-authorization'
+    );
+  }
+  return Object.values(value).some(item =>
+    containsACPProviderCredential({ value: item }),
+  );
+}
+
 function requireResolvedEnvironmentValue({
   environment,
   name,
@@ -984,6 +1056,7 @@ function createSession({
   turnStartConfig: turnStartConfigAtStart,
   recoveryStatus,
   restoration,
+  sandboxCredentialEnvironment,
   replayOnly,
   lossyRerun,
 }: {
@@ -1016,6 +1089,7 @@ function createSession({
   turnStartConfig: ACPTurnStartConfig | undefined;
   recoveryStatus: ACPLifecycleData['recovery'];
   restoration: ACPLifecycleData['restoration'];
+  sandboxCredentialEnvironment: Readonly<Record<string, string>> | undefined;
   replayOnly: boolean;
   lossyRerun: boolean;
 }): HarnessV1Session {
@@ -1271,6 +1345,9 @@ function createSession({
   }): ACPLifecycleData => ({
     implementationIdentity,
     authenticationProfile,
+    ...(sandboxCredentialEnvironment == null
+      ? {}
+      : { sandboxCredentialEnvironment }),
     ...(latestACPSessionId == null ? {} : { acpSessionId: latestACPSessionId }),
     ...(bridge == null ? {} : { bridge }),
     ...(latestTurnStartConfig == null
@@ -1583,6 +1660,22 @@ export function serializeBuiltinTools({
       typeof tool.nativeName === 'string'
         ? tool.nativeName
         : undefined;
+    const title =
+      tool != null &&
+      typeof tool === 'object' &&
+      'title' in tool &&
+      typeof tool.title === 'string'
+        ? tool.title
+        : undefined;
+    const toolUseKind =
+      tool != null &&
+      typeof tool === 'object' &&
+      'toolUseKind' in tool &&
+      (tool.toolUseKind === 'readonly' ||
+        tool.toolUseKind === 'edit' ||
+        tool.toolUseKind === 'bash')
+        ? tool.toolUseKind
+        : undefined;
     let inputSchema: ACPBuiltinToolMapping['inputSchema'];
     if (
       tool != null &&
@@ -1599,6 +1692,8 @@ export function serializeBuiltinTools({
     return {
       toolName,
       ...(nativeName == null ? {} : { nativeName }),
+      ...(title == null ? {} : { title }),
+      ...(toolUseKind == null ? {} : { toolUseKind }),
       ...(inputSchema == null ? {} : { inputSchema }),
     };
   });

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

@@ -21,6 +21,7 @@ export type ACPBridgeCoordinates = {
 export type ACPLifecycleData = ACPPromptGuidanceLifecycleState & {
   readonly implementationIdentity: string;
   readonly authenticationProfile?: ACPAuthenticationProfileIdentity;
+  readonly sandboxCredentialEnvironment?: Readonly<Record<string, string>>;
   readonly acpSessionId?: string;
   readonly bridge?: ACPBridgeCoordinates;
   readonly coldSession?: ACPColdSessionState;

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

@@ -1,4 +1,5 @@
 import type {
+  HarnessV1CredentialForwarding,
   HarnessV1PermissionMode,
   HarnessV1RequestTransformation,
 } from '@ai-sdk/harness';
@@ -45,6 +46,8 @@ export type ACPNpmLockedSource = {
   readonly type: 'npm-locked';
   readonly packageJson: string;
   readonly pnpmLockYaml: string;
+  /** Optional pnpm workspace configuration required by the locked install. */
+  readonly pnpmWorkspaceYaml?: string;
 };
 
 export type ACPInstallCommandSource = {
@@ -73,8 +76,10 @@ export type ACPProviderAuthentication = {
 
 export type ACPCredentialBrokering = ({
   env,
+  sandboxEnv,
 }: {
   env: Readonly<Record<string, string>>;
+  sandboxEnv?: Readonly<Record<string, string>>;
 }) => ReadonlyArray<HarnessV1RequestTransformation>;
 
 export type ACPPermissionModeTarget =
@@ -125,6 +130,12 @@ export type ACPV1Settings = {
   readonly forwardEnv?: ReadonlyArray<string>;
   readonly credentialEnv?: ReadonlyArray<string>;
   readonly credentialBrokering?: ACPCredentialBrokering;
+  /**
+   * Customizes each credential value before it is forwarded into a sandbox
+   * process. This does not restrict which credentials the harness adapter can
+   * discover, read, or otherwise access in the host process.
+   */
+  readonly credentialForwarding?: HarnessV1CredentialForwarding;
   /**
    * Runtime environment values that are safe to persist in bootstrap and
    * lifecycle compatibility identity.

package/src/v1/bridge/index.ts

@@ -38,7 +38,10 @@ import {
   type HostToolRelay,
   type HostToolRelayTurn,
 } from './host-tool-relay';
-import { refreshHostToolCatalog } from './refresh-host-tool-catalog';
+import {
+  promptAndRefreshInitialHostToolCatalog,
+  refreshHostToolCatalog,
+} from './refresh-host-tool-catalog';
 import { createACPPermissionController } from './permission-controller';
 import { configureACPPermissionMode } from './permission-mode';
 import {
@@ -130,8 +133,12 @@ await runBridge<StartMessage>({
 });
 
 async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
+  let initialHostToolCatalogRefreshRequired: boolean;
   try {
-    await ensureSession({ start, turn });
+    ({ initialHostToolCatalogRefreshRequired } = await ensureSession({
+      start,
+      turn,
+    }));
   } catch (error) {
     if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) throw error;
     throw createACPBridgeError({
@@ -149,6 +156,10 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
       'ACP session initialization did not start stderr monitoring.',
     );
   }
+  const activeHostToolRelay = hostToolRelay;
+  if (activeHostToolRelay == null) {
+    throw new Error('The host tool MCP relay is unavailable.');
+  }
   if (start.recoveryMode?.type === 'lossy-rerun') {
     const marker = {
       type: 'acp-recovery',
@@ -260,15 +271,35 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
     removeCorrelationInvocation:
       emitStreamEvent.removeHostToolCorrelationInvocation,
   };
-  hostToolRelay?.bindTurn({ turn: relayTurn });
+  activeHostToolRelay.bindTurn({ turn: relayTurn });
   try {
     const promptMeta = createOutputSchemaPromptMeta({ start });
-    void promptActiveSession({
-      session: activeSession,
-      agent: connection!.agent,
-      prompt: start.prompt,
-      meta: promptMeta,
-    });
+    const startPrompt = () =>
+      promptActiveSession({
+        session: activeSession,
+        agent: connection!.agent,
+        prompt: start.prompt,
+        meta: promptMeta,
+      });
+    if (initialHostToolCatalogRefreshRequired) {
+      try {
+        await promptAndRefreshInitialHostToolCatalog({
+          startPrompt,
+          relay: activeHostToolRelay,
+          tools: start.tools ?? [],
+          harnessId: bridgeType,
+          timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,
+        });
+      } catch (error) {
+        if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) {
+          catalogRefreshError = error;
+        }
+        sessionConfigurationFailure = { error };
+        throw error;
+      }
+    } else {
+      void startPrompt();
+    }
     if (turn.abortSignal.aborted) {
       await cancel();
     } else {
@@ -316,7 +347,7 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
   } finally {
     permissionController.cancelAll();
     activePermissionController = undefined;
-    hostToolRelay?.unbindTurn({ turn: relayTurn });
+    activeHostToolRelay.unbindTurn({ turn: relayTurn });
   }
 }
 
@@ -326,7 +357,7 @@ async function ensureSession({
 }: {
   start: StartMessage;
   turn: BridgeTurn;
-}): Promise<void> {
+}): Promise<{ initialHostToolCatalogRefreshRequired: boolean }> {
   if (sessionConfigurationFailure != null) {
     throw sessionConfigurationFailure.error;
   }
@@ -364,7 +395,7 @@ async function ensureSession({
       }
       throw error;
     }
-    return;
+    return { initialHostToolCatalogRefreshRequired: false };
   }
 
   const clientApp = resolveClientApp();
@@ -558,12 +589,6 @@ async function ensureSession({
       .start();
   }
   try {
-    await refreshHostToolCatalog({
-      relay: hostToolRelay,
-      tools,
-      harnessId: bridgeType,
-      timeoutMs: CATALOG_REFRESH_TIMEOUT_MS,
-    });
     if (start.permissionModeMapping != null) {
       await configureACPPermissionMode({
         agent: connection.agent,
@@ -588,6 +613,7 @@ async function ensureSession({
     sessionId: createdSession.sessionId,
   });
   sessionConfigurationFingerprint = fingerprint;
+  return { initialHostToolCatalogRefreshRequired: tools.length > 0 };
 }
 
 function createExternalMcpServers({