@salesforce/sfdx-agent-sdk 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.34.0] - 2026-07-15
+
+### Features
+- **agent-sdk,harness-claude,harness-mastra**: per-model gateway config — geo-aware ids, thinking mode, param exclusion @W-23447370@ ([#672](https://github.com/forcedotcom/agentic-dx/pull/672))
+
+## [0.33.0] - 2026-07-14
+
+### Features
+- **agent-sdk,harness-mastra,harness-claude**: cross-harness conformance test suite @W-23372341@ ([#663](https://github.com/forcedotcom/agentic-dx/pull/663))
+- **sdk,harness-mastra,harness-claude**: delete deprecated tool-approval surfaces @W-23090034 ([#637](https://github.com/forcedotcom/agentic-dx/pull/637))
+
+### Fixes
+- **harness-mastra**: thread model maxOutputTokens instead of flooring max_tokens at 4096 @W-23413250@ ([#656](https://github.com/forcedotcom/agentic-dx/pull/656))
+
+### Chores
+- **deps-dev**: bump typescript-eslint from 8.62.1 to 8.63.0 in the dev-dependencies group across 1 directory ([#665](https://github.com/forcedotcom/agentic-dx/pull/665))
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#659](https://github.com/forcedotcom/agentic-dx/pull/659))
+- **deps-dev**: bump @vitest/eslint-plugin from 1.6.22 to 1.6.23 in the vitest group ([#660](https://github.com/forcedotcom/agentic-dx/pull/660))
+- **deps-dev**: bump the vitest group across 1 directory with 3 updates ([#655](https://github.com/forcedotcom/agentic-dx/pull/655))
+
 ## [0.32.0] - 2026-07-08
 
 ### Fixes

package/README.md

@@ -34,7 +34,7 @@ for (const failure of manager.getRestoreFailures()) {
 //    storage folder will replay this agent automatically.
 const agent = await manager.createAgent('/path/to/project', {
   agentId: 'developer-assistant',
-  modelId: 'llmgateway__OpenAIGPT5',
+  modelId: 'sfdc_ai__DefaultGPT5',
   instructions: 'You are a helpful Salesforce developer assistant.',
 });
 
@@ -232,33 +232,27 @@ function onApprovalRequest(event: ToolApprovalRequestEvent): Promise<boolean> {
 
 #### `AgentConfig`
 
-| Field                  | Type                 | Description                                                                                                                                                                                                                                                                                                                                  |
-| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `orgAlias?`            | `string`             | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                         |
-| `modelId?`             | `ModelName \| Model` | LLM model selector. Pass a `ModelName` enum value for an in-tree model (e.g. `'llmgateway__OpenAIGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` exported from this package.                                            |
-| `name?`                | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                                   |
-| `description?`         | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                                   |
-| `instructions?`        | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                           |
-| `tools?`               | `ToolDefinition[]`   | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                              |
-| `mcpServers?`          | `MCPConfiguration`   | MCP server connections.                                                                                                                                                                                                                                                                                                                      |
-| `skills?`              | `string[]`           | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                         |
-| `rules?`               | `string[]`           | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention.         |
-| `toolPolicies?`        | `ToolPolicyRule[]`   | Ordered per-tool approval rules resolved by `resolveToolApprovalPolicy` (cross-tier deny-wins / within-tier last-wins). Author directly or via `definePolicy(...)`. See "Tool Approval Policy" below. Has no effect until a harness wires the resolver (Phase 2); until then gating uses the deprecated `StreamOptions.requireToolApproval`. |
-| `defaultToolDecision?` | `Decision`           | Fallback decision when no rule matches. Defaults to `'allow'` (no policy ⇒ no gating). Set to `'require-approval'` for a fail-closed posture (recommended for catalogs with un-annotated MCP servers).                                                                                                                                       |
+| Field                  | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orgAlias?`            | `string`             | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                                                         |
+| `modelId?`             | `ModelName \| Model` | LLM model selector. Pass a `ModelName` enum value for an in-tree model (e.g. `'sfdc_ai__DefaultGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` exported from this package. Legacy pinned `llmgateway__*` ids still resolve via a back-compat alias map. |
+| `name?`                | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                                                                   |
+| `description?`         | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                                                                   |
+| `instructions?`        | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                                                           |
+| `tools?`               | `ToolDefinition[]`   | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                                                              |
+| `mcpServers?`          | `MCPConfiguration`   | MCP server connections.                                                                                                                                                                                                                                                                                                                                                      |
+| `skills?`              | `string[]`           | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                                                         |
+| `rules?`               | `string[]`           | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention.                                         |
+| `toolPolicies?`        | `ToolPolicyRule[]`   | Ordered per-tool approval rules resolved by `resolveToolApprovalPolicy` (cross-tier deny-wins / within-tier last-wins). Author directly or via `definePolicy(...)`. See "Tool Approval Policy" below.                                                                                                                                                                        |
+| `defaultToolDecision?` | `Decision`           | Fallback decision when no rule matches. Defaults to `'allow'` (no policy ⇒ no gating). Set to `'require-approval'` for a fail-closed posture (recommended for catalogs with un-annotated MCP servers).                                                                                                                                                                       |
 
 #### `StreamOptions`
 
-| Field                  | Type                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| ---------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `abortSignal?`         | `AbortSignal`                 | Abort the streaming operation.                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| `requireToolApproval?` | `boolean \| ToolApprovalMode` | **Deprecated.** Per-call all-or-nothing gating. Superseded by per-tool policy on `AgentConfig.toolPolicies`; the serial-vs-batch UX axis moved to `batchApprovals`. Kept functional for one release so harness PRs migrate independently. `true` / `'serial'` emits one approval per stream; `'batch'` surfaces parallel approvals on one stream (requires Pattern A iterators). See "Tool Approval Flow" below.                                   |
-| `batchApprovals?`      | `boolean`                     | When `true`, parallel approval-requests within a turn surface on the same stream so the consumer can render a batch approval card (requires Pattern A iterators — collect-all-then-settle). Defaults to `false` (serial). The self-documenting replacement for the UX half of the deprecated `requireToolApproval` enum; the gating half moves to `AgentConfig.toolPolicies`. No effect when no tool in the turn resolves to `'require-approval'`. |
-| `maxSteps?`            | `number`                      | Maximum number of LLM call steps the agent may take per `stream()` invocation. Each step is one LLM call (which may produce text, tool calls, or both). Must be `>= 1`. Defaults to `DEFAULT_MAX_STEPS` (1024) — high enough to be effectively unlimited for real tasks; the practical ceiling is the context window and cost. The constant is exported so consumers and harness authors share one source of truth.                                |
-
-`ToolApprovalMode` is the exported (deprecated) type alias `'serial' | 'batch'`. Pair with the (deprecated)
-`resolveToolApprovalMode(boolean | ToolApprovalMode | undefined)` to normalize consumer input the same way the SDK does
-internally (`undefined` / `false` → `undefined`, `true` → `'serial'`, strings pass through, unknown strings throw). New
-code should configure `AgentConfig.toolPolicies` and set `batchApprovals` for the UX axis instead.
+| Field             | Type          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| ----------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abortSignal?`    | `AbortSignal` | Abort the streaming operation.                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `batchApprovals?` | `boolean`     | When `true`, parallel approval-requests within a turn surface on the same stream so the consumer can render a batch approval card (requires Pattern A iterators — collect-all-then-settle). Defaults to `false` (serial). Controls only the serial-vs-batch emission UX; the gating on/off decision lives on `AgentConfig.toolPolicies` / `AgentConfig.defaultToolDecision`. No effect when no tool in the turn resolves to `'require-approval'`. |
+| `maxSteps?`       | `number`      | Maximum number of LLM call steps the agent may take per `stream()` invocation. Each step is one LLM call (which may produce text, tool calls, or both). Must be `>= 1`. Defaults to `DEFAULT_MAX_STEPS` (1024) — high enough to be effectively unlimited for real tasks; the practical ceiling is the context window and cost. The constant is exported so consumers and harness authors share one source of truth.                               |
 
 #### Tool Approval Policy
 
@@ -722,21 +716,16 @@ consumers can branch on tool hints (e.g. auto-approve `readOnlyHint`) or group b
 reparsing namespaced tool names. `annotations` is `undefined` when the source did not declare them (per the MCP spec);
 `serverName` is `undefined` when the tool is not from an MCP server.
 
-`requireToolApproval` accepts a `boolean` (`true` is shorthand for `'serial'`) or one of the mode strings exposed via
-the `ToolApprovalMode` type alias (`'serial' | 'batch'`):
-
-- **`'serial'`** (the safe default) — `tool-approval-request` events surface one at a time. The next request (if any)
-  arrives later on the same `eventStream` after the consumer settles the current one.
-- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests for that batch surface on the
-  same `eventStream` together, so the consumer can render a batch-approval card. The consumer must gather all approvals
-  before settling — a `break`-on-first-approval loop will hang the turn because Mastra/Claude won't continue emitting
-  tool-results until the consumer has settled the entire batch.
+Gating is configured on the agent via `AgentConfig.toolPolicies` / `AgentConfig.defaultToolDecision` (see "Tool Approval
+Policy" above). The per-call `StreamOptions.batchApprovals` flag controls only how the resulting `tool-approval-request`
+events are emitted:
 
-The SDK also exports `resolveToolApprovalMode(value)` — the canonical
-`boolean | ToolApprovalMode | undefined → ToolApprovalMode | undefined` normalizer harness implementations should use to
-dispatch (`undefined` / `false` → `undefined`, `true` → `'serial'`, strings pass through). Reject unknown strings via
-`throw` instead of reimplementing the boolean-vs-string branch — the helper's defensive throw catches `as any` consumers
-passing invalid values that would otherwise silently degrade to "approval gating on but no coordinator allocated."
+- **`batchApprovals: false`** (the safe default) — `tool-approval-request` events surface one at a time. The next
+  request (if any) arrives later on the same `eventStream` after the consumer settles the current one.
+- **`batchApprovals: true`** — when the model emits parallel `tool_use` blocks, all approval-requests for that batch
+  surface on the same `eventStream` together, so the consumer can render a batch-approval card. The consumer must gather
+  all approvals before settling — a `break`-on-first-approval loop will hang the turn because Mastra/Claude won't
+  continue emitting tool-results until the consumer has settled the entire batch.
 
 #### Single stream per turn
 
@@ -749,12 +738,12 @@ in-line as approval-requests / consumer-tool-calls arrive.
 
 #### Pattern: settle in-line, continue iterating
 
-The same shape works for `'serial'` and `'batch'` mode:
+The same shape works for serial and batch emission. Configure gating on the agent
+(`defaultToolDecision: 'require-approval'`, or per-tool `toolPolicies`); the `chat()` call needs no approval flag:
 
 ```typescript
-const { eventStream } = await session.chat('Run the deployment', {
-  requireToolApproval: true, // or 'serial' / 'batch'
-});
+// Agent configured with e.g. { defaultToolDecision: 'require-approval' }
+const { eventStream } = await session.chat('Run the deployment');
 
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
@@ -789,12 +778,13 @@ for await (const event of eventStream) {
 
 #### Pattern variant: batch-collect approvals before settling
 
-Same single-stream loop, just gather the batch before deciding (useful for "approve these N tools?" UI cards under
-`requireToolApproval: 'batch'`):
+Same single-stream loop, just gather the batch before deciding (useful for "approve these N tools?" UI cards). Set
+`batchApprovals: true` on the `chat()` call; gating itself stays on the agent's `toolPolicies` / `defaultToolDecision`:
 
 ```typescript
+// Agent configured with e.g. { defaultToolDecision: 'require-approval' }
 const { eventStream } = await session.chat('Run the deployment', {
-  requireToolApproval: 'batch',
+  batchApprovals: true,
 });
 
 const pendingBatch: ToolApprovalRequestEvent[] = [];
@@ -873,8 +863,8 @@ for await (const event of eventStream) {
 }
 ```
 
-When `requireToolApproval: true` is also set, consumer-executed tools bypass the approval gate by construction (per
-`StreamOptions.requireToolApproval` JSDoc). They surface as a normal `tool-call` event without a preceding
+When approval gating is active (via `AgentConfig.toolPolicies` / `defaultToolDecision`), consumer-executed tools bypass
+the approval gate by construction. They surface as a normal `tool-call` event without a preceding
 `tool-approval-request`. Built-in / MCP tools still gate normally.
 
 ### Tool-Result Redaction
@@ -1047,7 +1037,7 @@ The connectivity facts a harness needs to make an LLM request. Five fields. Auth
 | --------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `model`         | `Model`                                 | Capability descriptor used for pre-flight multimodal validation and SDK-side context-usage reporting.                                                                                                                                                                                                                |
 | `baseUrl`       | `string`                                | Provider-native or gateway base URL (no trailing slash, no path beyond the API root). Harnesses concat the wire-shape-specific path.                                                                                                                                                                                 |
-| `nativeModelId` | `string`                                | Wire id the provider SDK sets on the request body's `model` field. May differ from `model.name` (e.g. Anthropic-direct expects `claude-sonnet-4-6`; the Salesforce gateway expects `llmgateway__BedrockAnthropicClaude46Sonnet`).                                                                                    |
+| `nativeModelId` | `string`                                | Wire id the provider SDK sets on the request body's `model` field. May differ from `model.name` (e.g. Anthropic-direct expects `claude-sonnet-4-6`; the Salesforce gateway expects `sfdc_ai__DefaultBedrockAnthropicClaude46Sonnet`).                                                                                |
 | `providerHint`  | `ProviderHint`                          | Wire shape the harness should speak. The manager validates this against the harness's `supportedProviderHints` before any harness work begins; a harness only sees hints it recognizes.                                                                                                                              |
 | `getHeaders`    | `() => Promise<Record<string, string>>` | Returns the FULL header set (Authorization included) for the NEXT outbound request. **Per-call invocation contract.** Mastra harnesses MUST call this on every HTTP call (inside their fetch wrapper); Claude harnesses MUST call this once per subprocess spawn. Caching the returned map across requests is a bug. |
 
@@ -1094,7 +1084,7 @@ const manager = await createAgentManager('/path/to/storage', new MastraHarnessFa
 | `getApiKey`          | `() => string \| Promise<string>` | Returns the API key. Re-evaluated on every `resolve()` call, and the resulting `getHeaders()` re-invokes it on every header read so a rotating key source (env var, secret store, BYOK toggle) lands without reconstructing the resolver.                                       |
 | `baseUrl`            | `string`                          | Fully-qualified provider URL with API version segment (e.g. `https://api.openai.com/v1`, not `https://api.openai.com`).                                                                                                                                                         |
 | `providerHint`       | `ProviderHint`                    | Wire shape. Must be one a harness in the consumer's setup advertises via `HarnessFactory.supportedProviderHints`.                                                                                                                                                               |
-| `nativeModelIdFor?`  | `(model: Model) => string`        | Optional translator from canonical `model.name` to the endpoint-native model id. Direct-provider endpoints expect their own naming (`claude-sonnet-4-6`); gateway-shaped endpoints accept the canonical `llmgateway__*` id verbatim. Defaults to `model.name`.                  |
+| `nativeModelIdFor?`  | `(model: Model) => string`        | Optional translator from canonical `model.name` to the endpoint-native model id. Direct-provider endpoints expect their own naming (`claude-sonnet-4-6`); gateway-shaped endpoints accept the canonical `sfdc_ai__Default*` id verbatim. Defaults to `model.name`.              |
 | `connectionFactory?` | `OrgConnectionFactory`            | Optional. When supplied, the resolver mints an org connection + JWT alongside the api-key bag — the BYOK shape (api-key authenticates the LLM; org JWT authenticates MCP servers / identity). Without it, `orgConnection` and `orgJwt` are omitted from `ResolvedConnectivity`. |
 
 The resolver throws `AgentSDKError(NOT_SUPPORTED)` when `getApiKey()` returns empty / nullish so consumers see "the
@@ -1106,6 +1096,11 @@ header bag. **Reserved auth headers are not overridable**: the resolver spreads
 `Authorization` / `Content-Type` last, so a `Model` instance whose `customHeaders` includes an `Authorization` key
 silently shadows nothing — the resolver wins.
 
+`Model.excludedParameters` is an optional denylist of generation parameters the LLM Gateway rejects for the model.
+Harnesses consult it before forwarding a generation parameter — currently only `temperature`, which the gateway
+deprecated for Claude Opus 4.7+ and now rejects. A model that lists `temperature` (the in-tree Opus 4.7 / 4.8 models do)
+has it stripped from the request; leaving `excludedParameters` unset (the default) forwards every parameter unchanged.
+
 #### `HarnessAgentConfig`
 
 Harness-facing configuration derived from `AgentConfig`. Strips `orgAlias` (resolved above the harness) and adds:

package/dist/agent-connectivity-resolver.d.ts

@@ -90,11 +90,17 @@ export declare class DefaultAgentConnectivityResolver implements AgentConnectivi
  * its `name` — a programming error worth surfacing eagerly rather than silently
  * defaulting.
  *
- * **Scope:** This helper is for the Salesforce gateway path only — both
- * `llmgateway__BedrockAnthropic*` and `llmgateway__Anthropic*` prefixes go to the
- * gateway's Bedrock pass-through, so both collapse to `'bedrock-anthropic'`. A
- * consumer wanting direct-Anthropic auth (`providerHint: 'anthropic'`) drives that
- * path through {@link ApiKeyConnectivityResolver} with an explicit `providerHint`
+ * **Scope:** This helper is for the Salesforce gateway path only. It keys on the
+ * model FAMILY segment, not the namespace prefix, because the geo-aware
+ * `sfdc_ai__Default*` prefix is shared across families: `sfdc_ai__DefaultBedrockAnthropic*`
+ * is a Claude model that must reach the Bedrock pass-through, while
+ * `sfdc_ai__DefaultGPT*` is an OpenAI model that must reach the Responses endpoint.
+ * Matching on the bare `sfdc_ai__Default` prefix alone would mis-route every geo
+ * Claude id onto the OpenAI wire path (wire-observed 500/502 — W-23256760). Both
+ * `BedrockAnthropic*` and `Anthropic*` families collapse to `'bedrock-anthropic'`
+ * (the gateway's Bedrock pass-through) under either namespace prefix. A consumer
+ * wanting direct-Anthropic auth (`providerHint: 'anthropic'`) drives that path
+ * through {@link ApiKeyConnectivityResolver} with an explicit `providerHint`
  * argument, not through this resolver.
  *
  * Exported (module-path only, not on the public `index.ts` surface) so e2e test

package/dist/agent-connectivity-resolver.js

@@ -2,7 +2,7 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
-import { Model, ModelName, Models, createClaudeModel } from './models/index.js';
+import { Model, ModelName, Models, createClaudeModel, LEGACY_MODEL_ID_ALIASES, } from './models/index.js';
 import { createJWTFromConnection, RealOrgConnectionFactory, SfApiEnv, } from '@salesforce/agentic-common';
 // TODO(@W-22782317): Temporary workaround — only on prod orgs the LLM Gateway must
 // route requests through AgentforceVibes rather than the default VibesService. Remove once a
@@ -63,11 +63,17 @@ export class DefaultAgentConnectivityResolver {
  * its `name` — a programming error worth surfacing eagerly rather than silently
  * defaulting.
  *
- * **Scope:** This helper is for the Salesforce gateway path only — both
- * `llmgateway__BedrockAnthropic*` and `llmgateway__Anthropic*` prefixes go to the
- * gateway's Bedrock pass-through, so both collapse to `'bedrock-anthropic'`. A
- * consumer wanting direct-Anthropic auth (`providerHint: 'anthropic'`) drives that
- * path through {@link ApiKeyConnectivityResolver} with an explicit `providerHint`
+ * **Scope:** This helper is for the Salesforce gateway path only. It keys on the
+ * model FAMILY segment, not the namespace prefix, because the geo-aware
+ * `sfdc_ai__Default*` prefix is shared across families: `sfdc_ai__DefaultBedrockAnthropic*`
+ * is a Claude model that must reach the Bedrock pass-through, while
+ * `sfdc_ai__DefaultGPT*` is an OpenAI model that must reach the Responses endpoint.
+ * Matching on the bare `sfdc_ai__Default` prefix alone would mis-route every geo
+ * Claude id onto the OpenAI wire path (wire-observed 500/502 — W-23256760). Both
+ * `BedrockAnthropic*` and `Anthropic*` families collapse to `'bedrock-anthropic'`
+ * (the gateway's Bedrock pass-through) under either namespace prefix. A consumer
+ * wanting direct-Anthropic auth (`providerHint: 'anthropic'`) drives that path
+ * through {@link ApiKeyConnectivityResolver} with an explicit `providerHint`
  * argument, not through this resolver.
  *
  * Exported (module-path only, not on the public `index.ts` surface) so e2e test
@@ -77,16 +83,20 @@ export class DefaultAgentConnectivityResolver {
  */
 export function pickProviderHintForGatewayModel(model) {
     const name = model.name;
-    if (name.startsWith('llmgateway__BedrockAnthropic') || name.startsWith('llmgateway__Anthropic')) {
+    if (name.startsWith('llmgateway__BedrockAnthropic') ||
+        name.startsWith('llmgateway__Anthropic') ||
+        name.startsWith('sfdc_ai__DefaultBedrockAnthropic') ||
+        name.startsWith('sfdc_ai__DefaultAnthropic')) {
         return 'bedrock-anthropic';
     }
     if (name.startsWith('llmgateway__OpenAI') || name.startsWith('sfdc_ai__Default')) {
-        // `sfdc_ai__Default*` is the geo-aware OpenAI route (W-23256760): the
-        // gateway selects the regional deployment, but the wire shape is still
-        // OpenAI Responses, so it resolves to the same providerHint.
+        // `sfdc_ai__Default*` (minus the Anthropic families handled above) is the
+        // geo-aware OpenAI route (W-23256760): the gateway selects the regional
+        // deployment, but the wire shape is still OpenAI Responses, so it resolves
+        // to the same providerHint.
         return 'openai-responses';
     }
-    throw new Error(`Cannot infer providerHint for model "${name}". Salesforce gateway models must start with "llmgateway__BedrockAnthropic*", "llmgateway__OpenAI*", or "sfdc_ai__Default*".`);
+    throw new Error(`Cannot infer providerHint for model "${name}". Salesforce gateway models must start with "sfdc_ai__DefaultBedrockAnthropic*", "sfdc_ai__DefaultGPT*", or a legacy "llmgateway__BedrockAnthropic*" / "llmgateway__OpenAI*" id.`);
 }
 /**
  * Returns the Salesforce LLM Gateway base URL for the given environment.
@@ -168,12 +178,19 @@ function rehydratePersistedModel(persisted) {
     if (typeof obj.name !== 'string') {
         throw new Error(`Cannot resolve modelId: missing string "name" on persisted object.`);
     }
-    // If the persisted name matches an in-tree model, prefer the strict registry — the
-    // returned instance has the correct prototype and the canonical caps.
-    if (Object.values(ModelName).includes(obj.name)) {
+    // If the persisted name matches an in-tree model — a current `ModelName` value OR a
+    // legacy pinned id the alias map remaps (e.g. an `AgentConfig` written before the
+    // geo-aware rename) — prefer the strict registry, which returns an instance with the
+    // correct prototype and canonical caps. `getByName` consults the alias map itself.
+    if (Object.values(ModelName).includes(obj.name) || obj.name in LEGACY_MODEL_ID_ALIASES) {
         return Models.getByName(obj.name);
     }
-    if (!obj.name.startsWith('llmgateway__BedrockAnthropic')) {
+    // Escape-hatch rehydration (consumer-built Claude variants via createClaudeModel):
+    // accept both the geo-aware `sfdc_ai__DefaultBedrockAnthropic*` prefix and the legacy
+    // pinned `llmgateway__BedrockAnthropic*` prefix so instances persisted under either
+    // scheme rehydrate during the deprecation window.
+    if (!obj.name.startsWith('sfdc_ai__DefaultBedrockAnthropic') &&
+        !obj.name.startsWith('llmgateway__BedrockAnthropic')) {
         throw new Error(`Cannot rehydrate persisted model "${obj.name}". Only Bedrock-Anthropic Claude variants are supported via the consumer-built Model escape hatch.`);
     }
     return createClaudeModel(obj.name, {
@@ -183,7 +200,8 @@ function rehydratePersistedModel(persisted) {
         contextWindow: obj.contextWindow,
         supportsPromptCache: obj.supportsPromptCache,
         supportedFormats: obj.supportedFormats,
-        permittedParameters: obj.permittedParameters,
+        excludedParameters: obj.excludedParameters,
+        thinkingMode: obj.thinkingMode,
         customHeaders: obj.customHeaders,
     });
 }

package/dist/harness/harness-config.d.ts

@@ -75,17 +75,12 @@ export type AgentConfig = {
      * the common cases. Per-MCP-server policy is expressed here via
      * `{ matcher: { type: 'mcp', serverName } }` rules — `MCPServerConfig`
      * carries no policy fields.
-     *
-     * Has no effect until a harness wires the resolver into its gate site
-     * (Phase 2). Until then, harnesses gate via the deprecated
-     * {@link StreamOptions.requireToolApproval}.
      */
     toolPolicies?: ToolPolicyRule[];
     /**
      * Fallback decision for tool invocations that match no rule in
      * {@link toolPolicies} (or any built-in / harness tier). Defaults to
-     * `'allow'` for back-compat ("no policy ⇒ no gating," matching today's
-     * behavior when `requireToolApproval` is unset).
+     * `'allow'` ("no policy ⇒ no gating").
      *
      * Set to `'require-approval'` for a fail-closed posture — recommended for
      * tenants whose MCP catalog includes un-annotated servers, since
@@ -126,84 +121,12 @@ export type HarnessAgentConfig = Omit<AgentConfig, 'orgAlias'> & {
  * `test/harness/harness-config.test.ts` that asserts unknown fields survive.
  */
 export declare function toHarnessConfig(config: AgentConfig, orgJwt?: JSONWebToken): HarnessAgentConfig;
-/**
- * Approval-mode selector for `StreamOptions.requireToolApproval`.
- *
- * Distinguishes the legacy "serial" UX (one approval per stream;
- * consumer settles before the next is surfaced) from the parallel
- * "batch" UX (all approval-requests for a parallel `tool_use` batch
- * surface on the same stream so the consumer can render them as a
- * batch approval card). See `requireToolApproval` for the safety
- * note on choosing `batch`.
- *
- * @deprecated Tool-approval gating is moving to per-tool policy on
- *   {@link AgentConfig.toolPolicies}, resolved by `resolveToolApprovalPolicy`.
- *   The serial-vs-batch UX axis survives as {@link StreamOptions.batchApprovals}.
- *   Removed in a future major once harnesses and consumers have migrated.
- */
-export type ToolApprovalMode = 'serial' | 'batch';
-/**
- * Resolves `StreamOptions.requireToolApproval` to its canonical mode:
- * `undefined` (gating off), `'serial'`, or `'batch'`. Centralizes the
- * boolean-vs-string normalization so harnesses don't duplicate the
- * resolution logic.
- *
- * Semantics:
- * - `undefined` / `false` → `undefined` (no gating).
- * - `true` → `'serial'` (back-compat shorthand for the original `boolean` shape).
- * - `'serial'` → `'serial'` (explicit, equivalent to `true`).
- * - `'batch'` → `'batch'`.
- *
- * @deprecated Superseded by per-tool policy on {@link AgentConfig.toolPolicies}
- *   (resolved by `resolveToolApprovalPolicy`) plus {@link StreamOptions.batchApprovals}
- *   for the UX axis. Kept functional for one release so harness PRs can migrate
- *   independently; removed in a future major.
- */
-export declare function resolveToolApprovalMode(requireToolApproval: boolean | ToolApprovalMode | undefined): ToolApprovalMode | undefined;
 /**
  * Per-call options controlling streaming behavior.
  */
 export type StreamOptions = {
     /** Signal to abort the streaming operation. */
     abortSignal?: AbortSignal;
-    /**
-     * When set, the harness requires human approval before executing any
-     * native tool (e.g., MCP tools). The stream emits a `tool-approval-request`
-     * event and suspends until the consumer calls `approveToolCall()` or
-     * `declineToolCall()`.
-     *
-     * Accepts a `boolean` (back-compatible shorthand) or one of the
-     * approval-mode strings:
-     *
-     * - **`true` or `'serial'`** (the safe default): each chat-stream
-     *   surfaces ONE `tool-approval-request` at a time. The consumer
-     *   settles the approval; the next `tool-approval-request` (if any)
-     *   appears on the continuation stream. Identical to the SDK's
-     *   behavior before parallel-approval UX (#447) — safe for consumers
-     *   whose iterator returns on the first approval-request and
-     *   re-iterates the continuation (Pattern B).
-     *
-     * - **`'batch'`**: when the model emits parallel `tool_use` blocks, the
-     *   broker surfaces ALL approval-requests on the same stream so the
-     *   consumer can render a batch approval UI ("Approve these N tools?").
-     *   Consumers MUST iterate to natural park collecting approvals
-     *   (Pattern A); a `break`-on-first-approval loop will miss the
-     *   subsequent approvals on the same stream and the chat will hang.
-     *   Only opt into `'batch'` after the consumer's iterator collects all
-     *   approvals before settling.
-     *
-     * Does not affect consumer-executed tools (those defined via
-     * `AgentConfig.tools` without an execute handler) — the consumer
-     * already controls execution for those via `submitToolResult()`.
-     *
-     * @deprecated Per-call all-or-nothing gating is superseded by per-tool
-     *   policy on {@link AgentConfig.toolPolicies}. The serial-vs-batch UX axis
-     *   moved to {@link batchApprovals}. Kept functional for one release so
-     *   harness PRs can migrate independently; removed in a future major. New
-     *   code should configure `AgentConfig.toolPolicies` and, if a batch UX is
-     *   wanted, set `batchApprovals: true`.
-     */
-    requireToolApproval?: boolean | ToolApprovalMode;
     /**
      * When `true`, parallel approval-requests within a turn (the model emits
      * multiple `tool_use` blocks in one batch, more than one of which resolves
@@ -212,14 +135,12 @@ export type StreamOptions = {
      * natural park before settling.
      *
      * Defaults to `false` (serial: one approval-request at a time; the consumer
-     * settles before the next surfaces). Identical to pre-#447 behavior under
-     * `requireToolApproval: true`.
+     * settles before the next surfaces).
      *
      * Has no effect when no tool in the turn resolves to `'require-approval'` —
-     * there is nothing to batch. This is the self-documenting replacement for
-     * the UX half of the deprecated {@link requireToolApproval} enum; the
-     * "gating on/off" half moves to per-tool policy on
-     * {@link AgentConfig.toolPolicies}.
+     * there is nothing to batch. The "gating on/off" decision lives on per-tool
+     * policy in {@link AgentConfig.toolPolicies} / {@link AgentConfig.defaultToolDecision};
+     * this flag controls only the serial-vs-batch emission UX.
      */
     batchApprovals?: boolean;
     /**

package/dist/harness/harness-config.js

@@ -24,36 +24,6 @@ export function toHarnessConfig(config, orgJwt) {
     const { orgAlias: _, ...rest } = config;
     return { ...rest, orgJwt };
 }
-/**
- * Resolves `StreamOptions.requireToolApproval` to its canonical mode:
- * `undefined` (gating off), `'serial'`, or `'batch'`. Centralizes the
- * boolean-vs-string normalization so harnesses don't duplicate the
- * resolution logic.
- *
- * Semantics:
- * - `undefined` / `false` → `undefined` (no gating).
- * - `true` → `'serial'` (back-compat shorthand for the original `boolean` shape).
- * - `'serial'` → `'serial'` (explicit, equivalent to `true`).
- * - `'batch'` → `'batch'`.
- *
- * @deprecated Superseded by per-tool policy on {@link AgentConfig.toolPolicies}
- *   (resolved by `resolveToolApprovalPolicy`) plus {@link StreamOptions.batchApprovals}
- *   for the UX axis. Kept functional for one release so harness PRs can migrate
- *   independently; removed in a future major.
- */
-export function resolveToolApprovalMode(requireToolApproval) {
-    if (requireToolApproval === undefined || requireToolApproval === false)
-        return undefined;
-    if (requireToolApproval === true)
-        return 'serial';
-    if (requireToolApproval === 'serial' || requireToolApproval === 'batch')
-        return requireToolApproval;
-    // Defensive: an `as any` consumer could pass an unknown string. Without
-    // this guard the value flows through to harness checks, which then
-    // silently degrade to "approval gating on but no broker allocated" and
-    // the chat hangs without an error a consumer can debug.
-    throw new Error(`Invalid requireToolApproval value: ${JSON.stringify(requireToolApproval)}. Expected boolean, 'serial', or 'batch'.`);
-}
 /**
  * Default maximum steps for a single agent stream invocation.
  *

package/dist/harness/public.d.ts

@@ -37,10 +37,9 @@
  * counterparts live only here.
  *
  * Symbols that consumers and harnesses both need (`AgentConfig`,
- * `StreamOptions`, `DEFAULT_MAX_STEPS`, `resolveToolApprovalMode`,
- * `ChatEvent` types, `Message` types, `MCPConfiguration`, etc.) stay on
- * the bare specifier. The split is "harness-only" vs. "consumer-AND-harness",
- * not "harness vs. consumer."
+ * `StreamOptions`, `DEFAULT_MAX_STEPS`, `ChatEvent` types, `Message`
+ * types, `MCPConfiguration`, etc.) stay on the bare specifier. The split
+ * is "harness-only" vs. "consumer-AND-harness", not "harness vs. consumer."
  */
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './index.js';
 export type { AgentHooks } from '../types/redaction.js';

package/dist/index.d.ts

@@ -5,12 +5,12 @@ export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMa
 export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-resolver.js';
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentHooks, HooksForAgent, ToolResultRedactor, ToolResultRedactionInput, ToolResultRedactionResult, } from './types/redaction.js';
-export type { AgentConfig, HarnessAgentConfig, StreamOptions, ToolApprovalMode } from './harness/harness-config.js';
-export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
+export type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles } from './models/index.js';
-export type { ClaudeModelOverrides, MultimodalFile, SupportedFileFormat } from './models/index.js';
+export type { ClaudeModelOverrides, MultimodalFile, SupportedFileFormat, ThinkingMode } from './models/index.js';
 export { MimeType } from './models/index.js';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 export { type AgentManager, type RestoreFailure, createAgentManager } from './agent-manager.js';

package/dist/index.js

@@ -8,7 +8,7 @@
 // `resolveToolApprovalPolicy` into their gate sites (Phase 2); consumers author
 // `AgentConfig.toolPolicies` (directly or via `definePolicy`).
 export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
-export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
+export { DEFAULT_MAX_STEPS } from './harness/harness-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles } from './models/index.js';
 export { MimeType } from './models/index.js';

package/dist/models/claude-opus-4-5.d.ts

@@ -1,4 +1,4 @@
-import { Model, ModelName } from './model.js';
+import { Model, ModelName, type ThinkingMode } from './model.js';
 import { type SupportedFileFormat } from './types.js';
 export declare class ClaudeOpus45 extends Model {
     readonly name: ModelName;
@@ -7,5 +7,6 @@ export declare class ClaudeOpus45 extends Model {
     readonly maxOutputTokens: number;
     readonly contextWindow: number;
     readonly supportsPromptCache: boolean;
+    readonly thinkingMode: ThinkingMode;
     readonly supportedFormats: readonly SupportedFileFormat[];
 }

package/dist/models/claude-opus-4-5.js

@@ -12,6 +12,10 @@ export class ClaudeOpus45 extends Model {
     maxOutputTokens = 64000;
     contextWindow = 200000;
     supportsPromptCache = true;
+    // The Bedrock 4.5 backend accepts only the legacy `thinking.type: "enabled"`
+    // shape and rejects `"adaptive"` (which arrives with 4.6+). Verified on the
+    // wire; see the harness thinking-mode probe.
+    thinkingMode = 'enabled';
     supportedFormats = [
         { name: 'png', mimeType: MimeType.Png, maxBytesPerFile: 3.75 * 1024 * 1024 },
         { name: 'jpeg', mimeType: MimeType.Jpeg, maxBytesPerFile: 3.75 * 1024 * 1024 },

package/dist/models/claude-opus-4-6.d.ts

@@ -1,4 +1,4 @@
-import { Model, ModelName } from './model.js';
+import { Model, ModelName, type ThinkingMode } from './model.js';
 import { type SupportedFileFormat } from './types.js';
 export declare class ClaudeOpus46 extends Model {
     readonly name: ModelName;
@@ -7,5 +7,6 @@ export declare class ClaudeOpus46 extends Model {
     readonly maxOutputTokens: number;
     readonly contextWindow: number;
     readonly supportsPromptCache: boolean;
+    readonly thinkingMode: ThinkingMode;
     readonly supportedFormats: readonly SupportedFileFormat[];
 }

package/dist/models/claude-opus-4-6.js

@@ -13,6 +13,10 @@ export class ClaudeOpus46 extends Model {
     maxOutputTokens = 128_000;
     contextWindow = 1_000_000;
     supportsPromptCache = true;
+    // The Bedrock 4.6+ backend requires the `thinking.type: "adaptive"` shape and
+    // rejects the legacy `"enabled"`. Verified on the wire; see the harness
+    // thinking-mode probe.
+    thinkingMode = 'adaptive';
     supportedFormats = [
         { name: 'png', mimeType: MimeType.Png, maxBytesPerFile: 3.75 * 1024 * 1024 },
         { name: 'jpeg', mimeType: MimeType.Jpeg, maxBytesPerFile: 3.75 * 1024 * 1024 },