@salesforce/sfdx-agent-harness-claude 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to `@salesforce/sfdx-agent-harness-claude` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.18.0] - 2026-06-19
+
+### Features
+- **BREAKING** Major refactor to Unify Connectivity via ModelConnectivityInfo @W-22782317 ([#607](https://github.com/forcedotcom/agentic-dx/pull/607))
+
+### Chores
+- **deps-dev**: bump @vitest/eslint-plugin from 1.6.19 to 1.6.20 in the vitest group across 1 directory ([#601](https://github.com/forcedotcom/agentic-dx/pull/601))
+- **deps-dev**: bump eslint from 10.4.1 to 10.5.0 in the eslint group across 1 directory ([#600](https://github.com/forcedotcom/agentic-dx/pull/600))
+- **deps-dev**: bump @types/node from 22.19.20 to 22.19.21 in the dev-dependencies group ([#599](https://github.com/forcedotcom/agentic-dx/pull/599))
+
 ## [0.17.0] - 2026-06-15
 
 ### Fixes

package/README.md

@@ -15,37 +15,39 @@ npm install @salesforce/sfdx-agent-sdk @salesforce/sfdx-agent-harness-claude
 ## Quick start
 
 ```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory, DirectClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+import { createAgentManager, DefaultAgentConnectivityResolver } from '@salesforce/sfdx-agent-sdk';
+import { ClaudeHarnessFactory } from '@salesforce/sfdx-agent-harness-claude';
 
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new DirectClaudeTransportResolver(() => process.env.ANTHROPIC_API_KEY!),
   permissionMode: 'bypassPermissions',
 });
 
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
+const manager = await createAgentManager('/path/to/storage', harnessFactory, {
+  connectivityResolver: new DefaultAgentConnectivityResolver(),
+});
 ```
 
+Connectivity (gateway URL, JWT, headers, native model id) is resolved by an `AgentConnectivityResolver` on the SDK and
+handed to the harness as a `ModelConnectivityInfo` bag. The harness factory itself owns harness-only concerns
+(permission mode, tool-approval timeout, bypass list, query defaults). For BYOK / direct-Anthropic / LLMG-Express
+deployments use `ApiKeyConnectivityResolver`; for non-Salesforce hosts implement your own resolver. See the
+[`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full resolver surface.
+
 See the [`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md) for the full consumer-facing API. For
 internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 
 ## Public API
 
-| Export                                           | Kind      | Description                                                                                                                                                          |
-| ------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ClaudeHarnessFactory`                           | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                               |
-| `ClaudeHarnessFactoryConfig`                     | interface | Configuration for `ClaudeHarnessFactory` (`resolver`, `permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `bypassApprovalTools`).                   |
-| `ClaudeHarnessPermissionMode`                    | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                          |
-| `ClaudeAgentHarness`                             | type      | Branded `AgentHarness` subtype carrying the Claude-specific config inference. Inferred at `manager.createAgent` automatically — annotation rarely needed.            |
-| `ClaudeAgentConfig`                              | type      | `AgentConfig` extended with Claude-only fields (`skillSearch`, `toolSearch`).                                                                                        |
-| `ClaudeSkillSearchConfig`                        | type      | Shape of `ClaudeAgentConfig.skillSearch` (`topK`). Opts the in-process `skill_bridge` MCP server into search-on-demand mode.                                         |
-| `ClaudeToolSearchConfig`                         | type      | Shape of `ClaudeAgentConfig.toolSearch` (`alwaysActive`). Stamps `_meta['anthropic/alwaysLoad']` on matching tools so they bypass Claude tool-search deferral.       |
-| `ClaudeTransportResolver`                        | interface | Strategy for resolving transport env, auth, and native model ID for the subprocess.                                                                                  |
-| `ClaudeTransportResolverResult`                  | type      | Return type of `ClaudeTransportResolver.resolve()` (`env` + `nativeModelId`).                                                                                        |
-| `ClaudeQueryDefaults`                            | type      | Consumer-overridable defaults for the Claude `query()` call (excludes `model`).                                                                                      |
-| `DirectClaudeTransportResolver`                  | class     | Resolver for direct Anthropic API access (sets `ANTHROPIC_API_KEY`). Suitable for local dev with a personal API key; not the production path.                        |
-| `SalesforceBedrockClaudeTransportResolver`       | class     | Resolver that routes the Claude subprocess through the Salesforce LLM Gateway's Bedrock proxy. Canonical production path for Salesforce developer-tooling consumers. |
-| `SalesforceBedrockClaudeTransportResolverConfig` | interface | Configuration for `SalesforceBedrockClaudeTransportResolver` (`gatewayBaseUrl`, optional `modelIdMap`, `appContext`, `featureId`, `ideContext`).                     |
+| Export                        | Kind      | Description                                                                                                                                                    |
+| ----------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ClaudeHarnessFactory`        | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                         |
+| `ClaudeHarnessFactoryConfig`  | interface | Configuration for `ClaudeHarnessFactory` (`permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `bypassApprovalTools`).                         |
+| `ClaudeHarnessPermissionMode` | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                    |
+| `ClaudeAgentHarness`          | type      | Branded `AgentHarness` subtype carrying the Claude-specific config inference. Inferred at `manager.createAgent` automatically — annotation rarely needed.      |
+| `ClaudeAgentConfig`           | type      | `AgentConfig` extended with Claude-only fields (`skillSearch`, `toolSearch`).                                                                                  |
+| `ClaudeSkillSearchConfig`     | type      | Shape of `ClaudeAgentConfig.skillSearch` (`topK`). Opts the in-process `skill_bridge` MCP server into search-on-demand mode.                                   |
+| `ClaudeToolSearchConfig`      | type      | Shape of `ClaudeAgentConfig.toolSearch` (`alwaysActive`). Stamps `_meta['anthropic/alwaysLoad']` on matching tools so they bypass Claude tool-search deferral. |
+| `ClaudeQueryDefaults`         | type      | Consumer-overridable defaults for the Claude `query()` call (excludes `model`).                                                                                |
 
 ### Permission modes
 
@@ -201,65 +203,25 @@ afterwards.
 > (which `break` does inside `for await`) finalizes the harness's source generator before the terminal event can reach
 > you. Settle in-line and keep iterating; the loop exits naturally when the terminal `finish` arrives.
 
-### Using the Salesforce Bedrock resolver
-
-The canonical production path for Salesforce developer-tooling consumers. Routes the Claude subprocess through the
-Salesforce LLM Gateway's Bedrock proxy using an org JWT for auth.
-
-```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory, SalesforceBedrockClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+### Connectivity (gateway URL, auth, native model id)
 
-const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new SalesforceBedrockClaudeTransportResolver({
-    // Pick the gateway URL for your environment — e.g. test:
-    gatewayBaseUrl: 'https://test.api.salesforce.com/ai/gpt/v1',
-    // No `modelIdMap` needed in the common case: the LLM Gateway's invoke API
-    // accepts the gateway-prefixed canonical id (`llmgateway__Bedrock*`) for
-    // every Anthropic Claude model, and the SDK's `Model.name` is already that
-    // canonical id, so the resolver's default passthrough is correct. Set the
-    // map only if your consumer needs to translate to a different shape (e.g.
-    // a self-hosted Bedrock proxy that expects the bare-native ids).
-    // Optional: override the `x-client-feature-id` header. Defaults to `orgJwt.getFeatureId()`.
-    featureId: 'EinsteinGptForDevelopers',
-    // Optional: getter for the `x-aip-user-ctx-tag` header. Invoked on every `resolve()`;
-    // returning `undefined` (or omitting the option) drops the header. Use when the tag is
-    // derived from post-JWT-mint state that changes between turns.
-    ideContext: () => orgEntitlement.ideUserContext,
-  }),
-  permissionMode: 'bypassPermissions',
-});
+The Claude harness reads connectivity per-spawn from a `ModelConnectivityInfo` bag the SDK hands it. The bag carries the
+gateway base URL, the native model id (e.g. `anthropic.claude-sonnet-4-6`), the provider hint (`bedrock-anthropic` or
+`anthropic`), and a `getHeaders()` callback the harness invokes once per subprocess spawn. JWT rotation rides on that
+callback — the next `stream()` call reads the rotated JWT through the same closure without rebuilding anything.
 
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
-```
+The SDK ships two bundled resolvers and a documented extension point — see the
+[`@salesforce/sfdx-agent-sdk` README](../sfdx-agent-sdk/README.md):
 
-JWT refresh works the same as elsewhere in the harness: each `resolve()` call eagerly reads `orgJwt.getValue()` /
-`orgJwt.getTenantKey()` and freezes the result into the static subprocess headers. `Agent.updateAgentConfig({})` runs
-`harness.updateAgent`, the resolver re-reads the fresh JWT on the next `stream()`, and the next subprocess spawns with
-the new headers — connected MCP clients are preserved through the rotation.
+- **`DefaultAgentConnectivityResolver`** — Salesforce-org gateway path. Targets the LLM Gateway's pass-through Bedrock
+  endpoint (`/invoke-with-response-stream`) using an org JWT.
+- **`ApiKeyConnectivityResolver`** — direct-Anthropic / OpenAI-direct / LLMG-Express. Constructor takes
+  `{ getApiKey, baseUrl, providerHint, ... }`.
+- **Custom `AgentConnectivityResolver`** — for deployments neither bundled resolver covers, implement the SDK's
+  `AgentConnectivityResolver` interface and pass it to `createAgentManager({ ..., connectivityResolver })`.
 
-### Using a custom resolver
-
-For deployment topologies neither built-in resolver covers (alternative gateways, custom auth flows, etc.), implement
-the `ClaudeTransportResolver` interface directly.
-
-```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory } from '@salesforce/sfdx-agent-harness-claude';
-import type { ClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
-
-const resolver: ClaudeTransportResolver = {
-  async resolve(orgJwt, modelId) {
-    return {
-      env: { ANTHROPIC_API_KEY: '...' },
-      nativeModelId: 'anthropic.claude-sonnet-4-6',
-    };
-  },
-};
-
-const harnessFactory = new ClaudeHarnessFactory({ resolver, permissionMode: 'bypassPermissions' });
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
-```
+The harness factory itself takes no resolver, gateway URL, or auth field — those concerns live entirely on the
+connectivity resolver.
 
 ### Per-server MCP reconnect (eager semantics)
 
@@ -287,7 +249,6 @@ reject.
 
 ```ts
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new DirectClaudeTransportResolver(() => process.env.ANTHROPIC_API_KEY!),
   permissionMode: 'bypassPermissions',
   queryDefaults: {
     maxTurns: 5,
@@ -307,11 +268,10 @@ across harnesses.
 `ClaudeQueryDefaults` does not strip). It blocks the model from emitting `tool_use` for the named built-ins entirely.
 
 ```ts
-import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
-import { ClaudeHarnessFactory, SalesforceBedrockClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+import { createAgentManager, DefaultAgentConnectivityResolver } from '@salesforce/sfdx-agent-sdk';
+import { ClaudeHarnessFactory } from '@salesforce/sfdx-agent-harness-claude';
 
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new SalesforceBedrockClaudeTransportResolver({ gatewayBaseUrl: '...' }),
   permissionMode: 'bypassPermissions',
   // Suppress the built-in `AskUserQuestion` so the cross-harness consumer
   // tool below is the only ask-the-user surface the model sees on Claude
@@ -321,7 +281,9 @@ const harnessFactory = new ClaudeHarnessFactory({
   },
 });
 
-const manager = await createAgentManager('/path/to/storage', harnessFactory);
+const manager = await createAgentManager('/path/to/storage', harnessFactory, {
+  connectivityResolver: new DefaultAgentConnectivityResolver(),
+});
 const agent = await manager.createAgent(projectRoot, {
   instructions: '...',
   tools: [
@@ -360,7 +322,6 @@ additional tool names out of the gate.
 
 ```ts
 const harnessFactory = new ClaudeHarnessFactory({
-  resolver: new SalesforceBedrockClaudeTransportResolver({ gatewayBaseUrl: '...' }),
   permissionMode: 'bypassPermissions',
   // Even when `requireToolApproval: true`, calls to these tools bypass the
   // PreToolUse hook. They still emit `tool-call` / `tool-result` ChatEvents,

package/dist/claude-harness-factory.d.ts

@@ -1,5 +1,4 @@
-import type { HarnessFactory } from '@salesforce/sfdx-agent-sdk';
-import type { ClaudeTransportResolver } from './claude-transport-resolver.js';
+import type { HarnessFactory, ProviderHint } from '@salesforce/sfdx-agent-sdk';
 import type { ClaudeQueryDefaults } from './claude-query-options-builder.js';
 import { type ClaudeAgentHarness } from './claude-harness.js';
 /**
@@ -13,7 +12,6 @@ import { type ClaudeAgentHarness } from './claude-harness.js';
  */
 export type ClaudeHarnessPermissionMode = 'bypassPermissions' | 'acceptEdits' | 'plan';
 export interface ClaudeHarnessFactoryConfig {
-    resolver: ClaudeTransportResolver;
     permissionMode: ClaudeHarnessPermissionMode;
     queryDefaults?: ClaudeQueryDefaults;
     /**
@@ -42,6 +40,14 @@ export declare class ClaudeHarnessFactory implements HarnessFactory<ClaudeAgentH
     private readonly config;
     readonly harnessId = "claude";
     readonly protocolVersion = 1;
+    /**
+     * The Claude CLI binary speaks Anthropic-shaped protocols only — both the
+     * Bedrock pass-through (`'bedrock-anthropic'`) and direct Anthropic API
+     * (`'anthropic'`). Routing it at a non-Anthropic model is a programming
+     * error caught at `createAgent` / `updateAgentConfig` by the manager's
+     * G8 validation.
+     */
+    readonly supportedProviderHints: readonly ProviderHint[];
     constructor(config: ClaudeHarnessFactoryConfig);
     create(storageRootFolder: string): Promise<ClaudeAgentHarness>;
 }

package/dist/claude-harness-factory.js

@@ -10,11 +10,19 @@ export class ClaudeHarnessFactory {
     config;
     harnessId = 'claude';
     protocolVersion = 1;
+    /**
+     * The Claude CLI binary speaks Anthropic-shaped protocols only — both the
+     * Bedrock pass-through (`'bedrock-anthropic'`) and direct Anthropic API
+     * (`'anthropic'`). Routing it at a non-Anthropic model is a programming
+     * error caught at `createAgent` / `updateAgentConfig` by the manager's
+     * G8 validation.
+     */
+    supportedProviderHints = ['anthropic', 'bedrock-anthropic'];
     constructor(config) {
         this.config = config;
     }
     async create(storageRootFolder) {
-        const envBuilder = new ClaudeQueryEnvBuilder(this.config.resolver, storageRootFolder);
+        const envBuilder = new ClaudeQueryEnvBuilder(storageRootFolder);
         const permissionDefaults = {
             permissionMode: this.config.permissionMode,
             ...(this.config.permissionMode === 'bypassPermissions'

package/dist/claude-harness-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-harness-factory.js","sourceRoot":"","sources":["../src/claude-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA2B,MAAM,qBAAqB,CAAC;AAa7E,MAAM,gCAAgC,GAAG,OAAO,CAAC;AA6BjD,MAAM,OAAO,oBAAoB;IAIA;IAHpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAE7B,YAA6B,MAAkC;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,MAAM,UAAU,GAAG,IAAI,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;QACtF,MAAM,kBAAkB,GAAG;YACvB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;YAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,mBAAmB;gBAClD,CAAC,CAAC,EAAE,+BAA+B,EAAE,IAAa,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACZ,CAAC;QACF,iEAAiE;QACjE,iEAAiE;QACjE,iEAAiE;QACjE,0DAA0D;QAC1D,kBAAkB;QAClB,MAAM,cAAc,GAAG,IAAI,yBAAyB,CAChD,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EACvD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,EAAE,CAAC,CACjD,CAAC;QACF,OAAO,IAAI,aAAa,CACpB,UAAU,EACV,cAAc,EACd,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,gCAAgC,EACrE,iBAAiB,CACpB,CAAC;IACN,CAAC;CACJ"}
+{"version":3,"file":"claude-harness-factory.js","sourceRoot":"","sources":["../src/claude-harness-factory.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,EAAE,aAAa,EAA2B,MAAM,qBAAqB,CAAC;AAa7E,MAAM,gCAAgC,GAAG,OAAO,CAAC;AA4BjD,MAAM,OAAO,oBAAoB;IAYA;IAXpB,SAAS,GAAG,QAAQ,CAAC;IACrB,eAAe,GAAG,CAAC,CAAC;IAC7B;;;;;;OAMG;IACM,sBAAsB,GAA4B,CAAC,WAAW,EAAE,mBAAmB,CAAC,CAAC;IAE9F,YAA6B,MAAkC;QAAlC,WAAM,GAAN,MAAM,CAA4B;IAAG,CAAC;IAEnE,KAAK,CAAC,MAAM,CAAC,iBAAyB;QAClC,MAAM,UAAU,GAAG,IAAI,qBAAqB,CAAC,iBAAiB,CAAC,CAAC;QAChE,MAAM,kBAAkB,GAAG;YACvB,cAAc,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;YAC1C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,cAAc,KAAK,mBAAmB;gBAClD,CAAC,CAAC,EAAE,+BAA+B,EAAE,IAAa,EAAE;gBACpD,CAAC,CAAC,EAAE,CAAC;SACZ,CAAC;QACF,iEAAiE;QACjE,iEAAiE;QACjE,iEAAiE;QACjE,0DAA0D;QAC1D,kBAAkB;QAClB,MAAM,cAAc,GAAG,IAAI,yBAAyB,CAChD,EAAE,GAAG,kBAAkB,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,EACvD,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,IAAI,EAAE,CAAC,CACjD,CAAC;QACF,OAAO,IAAI,aAAa,CACpB,UAAU,EACV,cAAc,EACd,IAAI,CAAC,MAAM,CAAC,qBAAqB,IAAI,gCAAgC,EACrE,iBAAiB,CACpB,CAAC;IACN,CAAC;CACJ"}

package/dist/claude-harness.d.ts

@@ -1,8 +1,7 @@
 import { type Clock, type LogRecord, type UniqueIDGenerator, type Unsubscribe } from '@salesforce/agentic-common';
-import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo } from '@salesforce/sfdx-agent-sdk';
+import { type AgentHarness, type ChatStreamResult, type HarnessAgentConfig, type McpServerInfo, type Message, type MessagePart, type ModelConnectivityInfo, type StreamOptions, type TelemetryEventCallback, type ToolResultInfo, type WireCommunicationEventCallback } from '@salesforce/sfdx-agent-sdk';
 import { type AgentHooks, type WithAgentConfig } from '@salesforce/sfdx-agent-sdk/harness';
 import type { ClaudeAgentConfig } from './claude-config.js';
-import { type LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 import type { ClaudeQueryEnvBuilder } from './claude-query-env-builder.js';
 import type { ClaudeQueryOptionsBuilder } from './claude-query-options-builder.js';
 import { buildMcpClients } from './mcp-client-factory.js';
@@ -71,13 +70,52 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      * collaborators on this constructor.
      */
     private readonly mcpClientFactory;
+    private readonly storageRootFolder;
     private shuttingDown;
     constructor(envBuilder: ClaudeQueryEnvBuilder, optionsBuilder: ClaudeQueryOptionsBuilder, toolApprovalTimeoutMs: number, storageRootFolder: string, idGenerator?: UniqueIDGenerator, clock?: Clock, sessionStore?: DiskBackedSessionStore, mcpClientFactory?: typeof buildMcpClients, threadContextStore?: ThreadContextStore);
     private coordinatorKey;
+    /**
+     * Returns a per-thread debug-log file path under the SDK storage root when a
+     * wire-communication consumer is subscribed; otherwise `undefined`. Callers pass the
+     * returned path as `query({ options: { debugFile } })` so the Claude subprocess writes
+     * its debug log to a file we own — and emit a `WireMonitoringNotSupportedEvent`
+     * pointing at the path immediately, before the subprocess starts.
+     *
+     * The path is **per-thread** (not per-turn): turns within the same conversation share
+     * a single file, accumulating wire data via the SDK's append-on-write behavior. A
+     * banner line written by {@link writeTurnBanner} delimits each turn within the file.
+     *
+     * Listener-count gating: relies on the wire-communication chain
+     * (`harness.wireBus → router slice → manager.wireBus`) being wired with
+     * `forwardWhileSubscribed`, so a consumer-less manager leaves
+     * `wireBus.listenerCount === 0` and this method returns `undefined` (no file written,
+     * no debug overhead in the subprocess).
+     */
+    private maybeAllocateWireDebugLogPath;
+    /**
+     * Append a turn-start banner to the per-thread wire-debug log file so consumers
+     * grepping the accumulated content can find each turn's boundary. The Claude SDK
+     * appends to `debugFile` across `query()` calls with no separator of its own; this
+     * banner makes turn boundaries explicit and version-stable.
+     */
+    private writeTurnBanner;
     shutdown(): Promise<void>;
     onTelemetry(callback: TelemetryEventCallback): Unsubscribe;
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
-    createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    /**
+     * The Claude harness emits `WireMonitoringNotSupportedEvent` (one per stream) when at
+     * least one consumer is subscribed at stream-start. The Claude Agent SDK runs the model
+     * client in a subprocess with no programmatic seam for HTTP-level monitoring, so per-call
+     * `LlmRequestEvent` / `LlmResponseEvent` (Mastra's contract) are not produced here;
+     * instead, the harness writes the subprocess's debug log to a file under the SDK storage
+     * root and points at it from the event's `message` field.
+     *
+     * **Subscribe-before-stream**: subscriptions added mid-stream miss the in-flight
+     * subprocess on Claude — the listener-count check happens once at `stream()` start. The
+     * next subprocess spawn (next `chat()` call) will pick up the subscriber.
+     */
+    onWireCommunication(callback: WireCommunicationEventCallback): Unsubscribe;
+    createAgent(agentId: string, projectRoot: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;
@@ -146,7 +184,7 @@ export declare class ClaudeHarness implements ClaudeAgentHarness {
      * `state.threads` is intentionally untouched — sessions are config-
      * independent, so an `updateAgent` cannot invalidate them.
      */
-    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+    updateAgent(agentId: string, modelConnectivityInfo: ModelConnectivityInfo, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
         hooks?: AgentHooks;
     }): Promise<void>;

package/dist/claude-harness.js

@@ -2,11 +2,12 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { realpath } from 'node:fs/promises';
+import { appendFile, mkdir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
 import { RealClock, UUIDGenerator, backfillCreatedAt, buildSummaryPrompt, getErrorMessage, isAbortError, } from '@salesforce/agentic-common';
 import { AgentSDKError, AgentSDKErrorType, McpServerStatus, resolveToolApprovalMode, } from '@salesforce/sfdx-agent-sdk';
 import { HarnessBusOwner, lowerStreamInput, matchesAlwaysActive, mcpServerConfigEqual, validateAlwaysActiveEntry, } from '@salesforce/sfdx-agent-sdk/harness';
-import { validateMultimodalFiles } from '@salesforce/llm-gateway-sdk';
+import { validateMultimodalFiles } from '@salesforce/sfdx-agent-sdk';
 import { deleteSession, forkSession, getSessionMessages, listSessions, query, } from '@anthropic-ai/claude-agent-sdk';
 import { ClaudeEventAdapter, mapSessionMessageContent } from './claude-event-adapter.js';
 import { ClaudeApprovalCoordinator } from './claude-approval-coordinator.js';
@@ -94,6 +95,7 @@ export class ClaudeHarness {
      * collaborators on this constructor.
      */
     mcpClientFactory;
+    storageRootFolder;
     shuttingDown = false;
     constructor(envBuilder, optionsBuilder, toolApprovalTimeoutMs, storageRootFolder, idGenerator = new UUIDGenerator(), clock = new RealClock(), sessionStore, mcpClientFactory = buildMcpClients, threadContextStore) {
         this.envBuilder = envBuilder;
@@ -101,6 +103,7 @@ export class ClaudeHarness {
         this.toolApprovalTimeoutMs = toolApprovalTimeoutMs;
         this.idGenerator = idGenerator;
         this.clock = clock;
+        this.storageRootFolder = storageRootFolder;
         // Default to the disk-backed store rooted at the harness's storage
         // folder. The SDK's `InMemorySessionStore` is only suitable for tests —
         // it loses every transcript on harness shutdown, breaking restart
@@ -114,6 +117,60 @@ export class ClaudeHarness {
     coordinatorKey(agentId, threadId) {
         return `${agentId}::${threadId}`;
     }
+    /**
+     * Returns a per-thread debug-log file path under the SDK storage root when a
+     * wire-communication consumer is subscribed; otherwise `undefined`. Callers pass the
+     * returned path as `query({ options: { debugFile } })` so the Claude subprocess writes
+     * its debug log to a file we own — and emit a `WireMonitoringNotSupportedEvent`
+     * pointing at the path immediately, before the subprocess starts.
+     *
+     * The path is **per-thread** (not per-turn): turns within the same conversation share
+     * a single file, accumulating wire data via the SDK's append-on-write behavior. A
+     * banner line written by {@link writeTurnBanner} delimits each turn within the file.
+     *
+     * Listener-count gating: relies on the wire-communication chain
+     * (`harness.wireBus → router slice → manager.wireBus`) being wired with
+     * `forwardWhileSubscribed`, so a consumer-less manager leaves
+     * `wireBus.listenerCount === 0` and this method returns `undefined` (no file written,
+     * no debug overhead in the subprocess).
+     */
+    async maybeAllocateWireDebugLogPath(agentId, threadId) {
+        if (!this.buses.hasWireCommunicationSubscribers()) {
+            return undefined;
+        }
+        const dir = join(this.storageRootFolder, 'claude-debug-logs');
+        try {
+            await mkdir(dir, { recursive: true });
+        }
+        catch (err) {
+            this.buses.getLogBus()?.warn?.('Failed to create claude-debug-logs directory', { dir }, err);
+            return undefined;
+        }
+        return join(dir, `${agentId}__${threadId}.log`);
+    }
+    /**
+     * Append a turn-start banner to the per-thread wire-debug log file so consumers
+     * grepping the accumulated content can find each turn's boundary. The Claude SDK
+     * appends to `debugFile` across `query()` calls with no separator of its own; this
+     * banner makes turn boundaries explicit and version-stable.
+     */
+    async writeTurnBanner(filePath, agentId, threadId) {
+        const stamp = this.clock.now().toISOString();
+        const banner = '\n' +
+            '============================================================\n' +
+            `# Turn started: ${stamp}\n` +
+            `# Agent:        ${agentId}\n` +
+            `# Thread:       ${threadId}\n` +
+            '============================================================\n' +
+            '\n';
+        try {
+            await appendFile(filePath, banner);
+        }
+        catch (err) {
+            // Best-effort — failing to write the banner is not worth aborting a turn for.
+            this.buses.getLogBus()?.warn?.('Failed to append wire-debug turn banner', { filePath }, err);
+        }
+    }
     async shutdown() {
         if (this.shuttingDown)
             return;
@@ -146,7 +203,22 @@ export class ClaudeHarness {
     onLog(callback) {
         return this.buses.onLog(callback);
     }
-    async createAgent(agentId, projectRoot, llmGatewayClient, config = {}, options) {
+    /**
+     * The Claude harness emits `WireMonitoringNotSupportedEvent` (one per stream) when at
+     * least one consumer is subscribed at stream-start. The Claude Agent SDK runs the model
+     * client in a subprocess with no programmatic seam for HTTP-level monitoring, so per-call
+     * `LlmRequestEvent` / `LlmResponseEvent` (Mastra's contract) are not produced here;
+     * instead, the harness writes the subprocess's debug log to a file under the SDK storage
+     * root and points at it from the event's `message` field.
+     *
+     * **Subscribe-before-stream**: subscriptions added mid-stream miss the in-flight
+     * subprocess on Claude — the listener-count check happens once at `stream()` start. The
+     * next subprocess spawn (next `chat()` call) will pick up the subscriber.
+     */
+    onWireCommunication(callback) {
+        return this.buses.onWireCommunication(callback);
+    }
+    async createAgent(agentId, projectRoot, modelConnectivityInfo, config = {}, options) {
         if (this.agents.has(agentId)) {
             throw new Error(`Agent with id "${agentId}" is already registered`);
         }
@@ -274,8 +346,12 @@ export class ClaudeHarness {
         this.agents.set(agentId, {
             projectRoot: resolvedProjectRoot,
             config,
+            modelConnectivityInfo,
             rulesAppend,
-            model: llmGatewayClient.getModel(),
+            // The bag's `model` is the canonical model object the resolver
+            // produced (with caps, supportedFormats, customHeaders). Used
+            // for pre-flight multimodal validation.
+            model: modelConnectivityInfo.model,
             skillMap,
             skillSearch,
             toolSearch,
@@ -506,7 +582,7 @@ export class ClaudeHarness {
      * `state.threads` is intentionally untouched — sessions are config-
      * independent, so an `updateAgent` cannot invalidate them.
      */
-    async updateAgent(agentId, llmGatewayClient, config = {}, options) {
+    async updateAgent(agentId, modelConnectivityInfo, config = {}, options) {
         const agent = this.agents.get(agentId);
         if (!agent) {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
@@ -561,7 +637,8 @@ export class ClaudeHarness {
         agent.skillMap = skillMap;
         agent.skillSearch = skillSearch;
         agent.toolSearch = toolSearch;
-        agent.model = llmGatewayClient.getModel();
+        agent.modelConnectivityInfo = modelConnectivityInfo;
+        agent.model = modelConnectivityInfo.model;
         agent.config = config;
         agent.hooks = options?.hooks ?? {};
     }
@@ -793,10 +870,7 @@ export class ClaudeHarness {
      *     `canUseTool` broker — the task is text-in / text-out.
      */
     async summarize(agent, prompt) {
-        if (!agent.config.orgJwt) {
-            throw new Error('Agent has no orgJwt configured');
-        }
-        const { env, nativeModelId } = await this.envBuilder.build(agent.config.orgJwt, agent.model.name);
+        const { env, nativeModelId } = await this.envBuilder.build(agent.modelConnectivityInfo);
         const summaryConfig = {
             orgJwt: agent.config.orgJwt,
             // The role declaration + summarization imperative + the
@@ -955,18 +1029,15 @@ export class ClaudeHarness {
         if (!agentState) {
             throw new AgentSDKError(`No Agent found with id: "${agentId}"`, AgentSDKErrorType.AGENT_NOT_FOUND);
         }
-        const { projectRoot, config, rulesAppend, model } = agentState;
+        const { projectRoot, config, rulesAppend } = agentState;
         const threadState = agentState.threads.get(threadId);
-        if (!config.orgJwt) {
-            throw new Error(`Agent "${agentId}" has no orgJwt configured`);
-        }
         // Build (and pre-stream-validate) the query prompt. A plain string passes through; a
         // MessagePart[] is validated against the model's capabilities and lowered to a single
         // Anthropic user message carrying text / image / document content blocks. Validation runs
         // synchronously here so failures reject the `stream()` promise (pre-stream contract) rather
         // than surfacing mid-iteration.
         const prompt = typeof message === 'string' ? message : this.buildMultimodalPrompt(agentState, message);
-        const { env, nativeModelId } = await this.envBuilder.build(config.orgJwt, model.name);
+        const { env, nativeModelId } = await this.envBuilder.build(agentState.modelConnectivityInfo);
         // Pass the underlying claudeSessionId to the Claude SDK, NOT the
         // user-facing threadId. They equal each other for legacy threads
         // but diverge after `clearMessages()` (see issue #511 / ThreadState
@@ -1114,6 +1185,49 @@ export class ClaudeHarness {
                 claudeSessionId: threadState.claudeSessionId,
             });
         }
+        // Wire-communication monitoring on Claude (subscriber-gated): the Claude Agent SDK runs
+        // the model client in a subprocess with no programmatic HTTP-interception seam, so we
+        // can't emit per-call `LlmRequestEvent` / `LlmResponseEvent` like Mastra does. When a
+        // consumer is subscribed to the wire-communication channel at stream-start, we instead
+        // tell the subprocess to write its debug log to a file under the SDK storage root
+        // (one file per thread — turns within the same conversation accumulate via the SDK's
+        // append behavior) and emit a single `WireMonitoringNotSupportedEvent` per stream
+        // pointing at the file. The listener-count check propagates back through
+        // `forwardWhileSubscribed` (manager bus → router slice → harness bus), so this is
+        // essentially free when nobody is listening.
+        const wireDebugLogPath = await this.maybeAllocateWireDebugLogPath(agentId, threadId);
+        if (wireDebugLogPath !== undefined) {
+            options.debugFile = wireDebugLogPath;
+            // Write a turn-banner so consumers grepping the accumulated file can find each
+            // turn's start. The Claude SDK appends to `debugFile` across `query()` calls
+            // with no separator of its own, so without this banner the boundary between
+            // turns is implicit (the de-facto "first line" of every subprocess is
+            // `[DEBUG] MDM settings load completed in Xms` — easy to miss and SDK-version
+            // dependent).
+            await this.writeTurnBanner(wireDebugLogPath, agentId, threadId);
+            try {
+                this.buses.emitWireCommunication({
+                    type: 'wire-monitoring-not-supported',
+                    timestamp: this.clock.now(),
+                    harnessId: this.harnessId,
+                    message: `The Claude harness cannot emit per-call wire-communication events: ` +
+                        `the Claude Agent SDK runs the model client in a subprocess with no ` +
+                        `programmatic seam for monitoring HTTP traffic. The subprocess's debug ` +
+                        `log (which contains the underlying request/response data in the Claude ` +
+                        `CLI / Anthropic SDK debug format) is being written to:\n\n` +
+                        `${wireDebugLogPath}\n\n` +
+                        `One file per thread; subsequent turns of this thread append to the same ` +
+                        `file. Each turn starts with a banner line ` +
+                        `\`# Turn started: <ISO timestamp>\` so boundaries are greppable. The ` +
+                        `file is left in place; the consumer is responsible for retention and ` +
+                        `cleanup.`,
+                });
+            }
+            catch (err) {
+                if (!isDisposedError(err))
+                    throw err;
+            }
+        }
         const queryResult = query({ prompt, options });
         if (threadState) {
             threadState.hasStreamed = true;