@salesforce/sfdx-agent-harness-mastra 0.31.0 → 0.33.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 All notable changes to `@salesforce/sfdx-agent-harness-mastra` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.33.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.32.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-conformance**: static version instead of -dev.N so release check passes @W-23446682@ ([#670](https://github.com/forcedotcom/agentic-dx/pull/670))
+- **harness-mastra**: thread model maxOutputTokens instead of flooring max_tokens at 4096 @W-23413250@ ([#656](https://github.com/forcedotcom/agentic-dx/pull/656))
+- **harness-mastra**: synthesize deny tool-result for @mastra/core 1.49 ([#653](https://github.com/forcedotcom/agentic-dx/pull/653))
+
+### 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**: bump the mastra group across 1 directory with 4 updates ([#661](https://github.com/forcedotcom/agentic-dx/pull/661))
+- **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.31.0] - 2026-07-08
 
 ### Fixes

package/README.md

@@ -44,12 +44,12 @@ Linux and macOS release the handle eagerly; the retry options are no-ops on thos
 
 ### Core
 
-| Export                          | Kind      | Description                                                                                                                                                 |
-| ------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `MastraHarnessFactory`          | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                     |
-| `MastraHarnessFactoryConfig`    | interface | Configuration for `MastraHarnessFactory` (`toolApprovalTimeoutMs?`).                                                                                       |
+| Export                          | Kind      | Description                                                                                                                                                                                                                              |
+| ------------------------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `MastraHarnessFactory`          | class     | `HarnessFactory` that produces a Mastra-backed `AgentHarness` bound to a storage root.                                                                                                                                                   |
+| `MastraHarnessFactoryConfig`    | interface | Configuration for `MastraHarnessFactory` (`toolApprovalTimeoutMs?`).                                                                                                                                                                     |
 | `MASTRA_BUILT_IN_TOOL_POLICIES` | const     | Frozen `ReadonlyArray<ToolPolicyRule>` the harness feeds the SDK's `resolveToolApprovalPolicy` as the `tiers.harness` slice — `allow` rules for Mastra's built-in `updateWorkingMemory` / `skill` / `skill_search` / `skill_read` tools. |
-| `MASTRA_BUILT_IN_TOOL_NAMES`    | const     | The four built-in tool leaf names `MASTRA_BUILT_IN_TOOL_POLICIES` covers.                                                                                  |
+| `MASTRA_BUILT_IN_TOOL_NAMES`    | const     | The four built-in tool leaf names `MASTRA_BUILT_IN_TOOL_POLICIES` covers.                                                                                                                                                                |
 
 Connectivity (model + provider auth) is supplied by the SDK's `AgentConnectivityResolver`. Use the bundled
 `DefaultAgentConnectivityResolver` for the standard Salesforce LLM Gateway path, or `ApiKeyConnectivityResolver` for
@@ -58,11 +58,10 @@ on `ModelConnectivityInfo.providerHint` internally to pick the right pass-throug
 
 #### HTTPS proxy routing
 
-The harness honors `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` (either casing) via
-`@salesforce/agentic-common`'s `resolveProxyDispatcher()`. When either proxy var is set at factory `create()` time, the
-harness wraps every in-process `fetch` call site (LLM gateway language-model builders + MCP remote transports) with an
-undici-backed routing function — no `globalThis` mutation. When no proxy env is set, `fetch` runs unwrapped (zero
-overhead).
+The harness honors `HTTPS_PROXY` / `HTTP_PROXY` / `NO_PROXY` (either casing) via `@salesforce/agentic-common`'s
+`resolveProxyDispatcher()`. When either proxy var is set at factory `create()` time, the harness wraps every in-process
+`fetch` call site (LLM gateway language-model builders + MCP remote transports) with an undici-backed routing function —
+no `globalThis` mutation. When no proxy env is set, `fetch` runs unwrapped (zero overhead).
 
 **Snapshot timing.** `HTTPS_PROXY` / `HTTP_PROXY` are captured at `create()` time and pinned for the harness's lifetime;
 `NO_PROXY` is re-evaluated per request. Set the proxy env vars before constructing the factory's first harness.
@@ -204,19 +203,14 @@ harness resolves a decision and acts on it:
   `tool-approval-request` surfaces.
 - **`require-approval`** — a `tool-approval-request` is emitted and the workflow suspends until the consumer settles.
 
-Gating is **opt-in**: it engages only when the agent's config sets `toolPolicies` or `defaultToolDecision`, or the
-`chat()` call sets the deprecated `requireToolApproval` or `batchApprovals`. With none configured, tools run without
-gating (no suspension), matching the SDK's "no policy ⇒ no gating" default. The harness adds
-`MASTRA_BUILT_IN_TOOL_POLICIES` (Mastra's `updateWorkingMemory` / `skill` / `skill_search` / `skill_read` built-ins) and
-the SDK's `skill_bridge` meta-tool rules as `allow` defaults, so capability-discovery never prompts. Consumer-executed
-tools (`AgentConfig.tools`) always bypass the gate — their execution is the consumer's responsibility via
-`submitToolResult`. Set `StreamOptions.batchApprovals: true` to surface parallel `require-approval` requests on one
+Gating is **opt-in**: it engages only when the agent's config sets `toolPolicies` or `defaultToolDecision`. With neither
+configured, tools run without gating (no suspension), matching the SDK's "no policy ⇒ no gating" default. The harness
+adds `MASTRA_BUILT_IN_TOOL_POLICIES` (Mastra's `updateWorkingMemory` / `skill` / `skill_search` / `skill_read`
+built-ins) and the SDK's `skill_bridge` meta-tool rules as `allow` defaults, so capability-discovery never prompts.
+Consumer-executed tools (`AgentConfig.tools`) always bypass the gate — their execution is the consumer's responsibility
+via `submitToolResult`. Set `StreamOptions.batchApprovals: true` to surface parallel `require-approval` requests on one
 stream for a batch-approval UI.
 
-> `StreamOptions.requireToolApproval` is **deprecated** — superseded by per-tool `AgentConfig.toolPolicies`. It still
-> works for one release: a truthy value engages all-or-nothing gating (every non-consumer tool requires approval), and
-> `'batch'` maps onto `batchApprovals`.
-
 ### Tool approval timeout
 
 When the approval gate is engaged and a tool resolves to `require-approval`, the harness suspends the workflow on each

package/dist/mastra-approval-coordinator.d.ts

@@ -50,10 +50,10 @@ export interface MastraApprovalCoordinatorOptions {
      *   (front-loaded off `tool-call` when `batchApprovals`, else on the
      *   natural `tool-call-approval` chunk).
      *
-     * `undefined` means gating is **off** (the consumer configured no policy
-     * and no `requireToolApproval` / `batchApprovals`): the harness does not
-     * pass `requireToolApproval`, Mastra suspends nothing, and this callback is
-     * never consulted — today's no-gating behavior.
+     * `undefined` means gating is **off** (the consumer configured no
+     * `toolPolicies` / `defaultToolDecision`): the harness does not pass
+     * `requireToolApproval` to Mastra, Mastra suspends nothing, and this
+     * callback is never consulted — the SDK's no-gating behavior.
      *
      * The coordinator builds the {@link ToolInvocation} it passes here from the
      * same identity sources it uses for event enrichment
@@ -74,8 +74,7 @@ export interface MastraApprovalCoordinatorOptions {
      * iterates to natural park). When `false`, each `require-approval` surfaces
      * on its natural `tool-call-approval` suspension chunk — one at a time.
      *
-     * Replaces the serial/batch role of the deprecated
-     * `StreamOptions.requireToolApproval` enum (#447). No effect when
+     * Read from `StreamOptions.batchApprovals` (#447). No effect when
      * {@link lookupPolicy} is `undefined` (gating off) or when no tool resolves
      * to `require-approval`.
      */
@@ -123,7 +122,8 @@ export interface MastraApprovalCoordinatorOptions {
  * Responsibilities:
  *  - Policy-driven approval gating (Phase 2a): for each non-consumer tool,
  *    consult `lookupPolicy` — `allow` silently approves, `deny` silently
- *    declines (Mastra synthesizes a `tool-result(isError=true)`),
+ *    declines (the coordinator synthesizes a `tool-result(isError=true)` and
+ *    drives `agent.declineToolCall` so the model sees the failed call),
  *    `require-approval` emits a `tool-approval-request` and drives
  *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the consumer
  *    settles. `batchApprovals` controls whether parallel `require-approval`
@@ -166,17 +166,6 @@ export declare class MastraApprovalCoordinator {
     private readonly initial;
     /** Buffered consumer decisions keyed by `toolCallId`. */
     private readonly decisions;
-    /**
-     * ToolCallIds the policy resolver decided `'deny'` (Phase 2a). The pump
-     * drives `agent.declineToolCall` for these, and Mastra emits a native
-     * `tool-result` on the resumed stream with `isError: false` + the text
-     * "Tool call was not approved by the user". The SDK `Decision` contract
-     * requires a denied tool to surface as `tool-result(isError=true)`, so the
-     * coordinator re-stamps `isError: true` on the matching result as it routes
-     * (see {@link routeEnriched}). Tracked separately from consumer-driven
-     * declines, which keep Mastra's native shape.
-     */
-    private readonly policyDeniedIds;
     /** ToolCallIds for which a `tool-approval-request` ChatEvent has been emitted. */
     private readonly emittedApprovals;
     /** ToolCallIds the consumer has settled. Rejects double-settle. */
@@ -407,18 +396,6 @@ export declare class MastraApprovalCoordinator {
      */
     private routeEnriched;
     private maybeEnrich;
-    /**
-     * Re-stamp `isError: true` on the `tool-result` for a policy-denied tool
-     * call (Phase 2a). When the resolver returns `'deny'`, the coordinator
-     * drives `agent.declineToolCall`; Mastra emits a native `tool-result` with
-     * `isError: false` and the text "Tool call was not approved by the user".
-     * The SDK `Decision` contract requires a denied tool to surface as
-     * `tool-result(isError=true)` so consumers and the model treat it as a
-     * failed call, not a successful one — so we flip the flag exactly once, on
-     * the matching result. Consumer-driven declines (not policy denials) are not
-     * in `policyDeniedIds` and keep Mastra's native shape.
-     */
-    private policyDenyStamp;
     /**
      * Build the {@link ToolInvocation} the policy resolver matches against, and
      * the single source of the `serverName` / `annotations` identity stamped on
@@ -450,11 +427,10 @@ export declare class MastraApprovalCoordinator {
      * Resolve the approval decision for a non-consumer tool via the harness-
      * supplied {@link MastraApprovalCoordinatorOptions.lookupPolicy} callback.
      * Falls back to `'require-approval'` when no policy callback is wired — a
-     * defensive default so a future caller that passes `requireToolApproval`
-     * without a resolver surfaces the request rather than silently allowing.
-     * In practice this fallback is unreachable: gating is active iff
-     * `lookupPolicy` is defined, and only then does Mastra suspend non-consumer
-     * tools.
+     * defensive default so a future caller that activates gating without a
+     * resolver surfaces the request rather than silently allowing. In practice
+     * this fallback is unreachable: gating is active iff `lookupPolicy` is
+     * defined, and only then does Mastra suspend non-consumer tools.
      */
     private policyFor;
     private emitApprovalRequest;

package/dist/mastra-approval-coordinator.js

@@ -22,6 +22,13 @@ function pickIdWithDecision(pendingIds, decisions) {
     }
     return undefined;
 }
+/**
+ * Result text the coordinator stamps on the synthesized `tool-result` for a
+ * policy-denied tool call. Matches the text Mastra folds into the model's
+ * context on decline ("Tool call was not approved by the user") so the
+ * consumer-facing event and the model's transcript stay consistent.
+ */
+const POLICY_DENIED_RESULT_TEXT = 'Tool call was not approved by the user';
 /**
  * Per-`(agentId, threadId)` coordinator that subsumes the pre-#529
  * `MastraStreamBroker` + `activeRuns` pair into one object owning a single
@@ -30,7 +37,8 @@ function pickIdWithDecision(pendingIds, decisions) {
  * Responsibilities:
  *  - Policy-driven approval gating (Phase 2a): for each non-consumer tool,
  *    consult `lookupPolicy` — `allow` silently approves, `deny` silently
- *    declines (Mastra synthesizes a `tool-result(isError=true)`),
+ *    declines (the coordinator synthesizes a `tool-result(isError=true)` and
+ *    drives `agent.declineToolCall` so the model sees the failed call),
  *    `require-approval` emits a `tool-approval-request` and drives
  *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the consumer
  *    settles. `batchApprovals` controls whether parallel `require-approval`
@@ -73,17 +81,6 @@ export class MastraApprovalCoordinator {
     initial = new GenSink();
     /** Buffered consumer decisions keyed by `toolCallId`. */
     decisions = new Map();
-    /**
-     * ToolCallIds the policy resolver decided `'deny'` (Phase 2a). The pump
-     * drives `agent.declineToolCall` for these, and Mastra emits a native
-     * `tool-result` on the resumed stream with `isError: false` + the text
-     * "Tool call was not approved by the user". The SDK `Decision` contract
-     * requires a denied tool to surface as `tool-result(isError=true)`, so the
-     * coordinator re-stamps `isError: true` on the matching result as it routes
-     * (see {@link routeEnriched}). Tracked separately from consumer-driven
-     * declines, which keep Mastra's native shape.
-     */
-    policyDeniedIds = new Set();
     /** ToolCallIds for which a `tool-approval-request` ChatEvent has been emitted. */
     emittedApprovals = new Set();
     /** ToolCallIds the consumer has settled. Rejects double-settle. */
@@ -342,10 +339,6 @@ export class MastraApprovalCoordinator {
         this.initial.push({ type: 'finish', finishReason: 'error' });
         this.initial.end();
         this.pendingSuspendIds.clear();
-        // The turn is over; any deny re-stamp that never landed (the declined
-        // tool-result will never arrive now) is moot. Clear so the set doesn't
-        // outlive the turn.
-        this.policyDeniedIds.clear();
         this.runTeardownCallbacks();
     }
     // ───────────────────────── settle methods ───────────────────────────────
@@ -592,9 +585,9 @@ export class MastraApprovalCoordinator {
                     this.pendingSuspendIds.add(tc.toolCallId);
                     sawSuspension = true;
                     if (this.consumerToolNames.has(tc.toolName)) {
-                        // Consumer tools bypass the gate per the
-                        // StreamOptions.requireToolApproval JSDoc. Auto-
-                        // approve silently — no ChatEvent surfaces, and the
+                        // Consumer tools bypass the approval gate by
+                        // construction. Auto-approve silently — no ChatEvent
+                        // surfaces, and the
                         // pump loop drives `agent.approveToolCall` when it
                         // picks up the buffered decision. After Mastra
                         // resumes, the bridge `execute` parker runs and
@@ -616,19 +609,36 @@ export class MastraApprovalCoordinator {
                     }
                     else if (decision === 'deny') {
                         // Silent decline — no `tool-approval-request` surfaces.
-                        // The pump drives `agent.declineToolCall`; Mastra emits a
-                        // native `tool-result` on the resumed stream (with
-                        // `isError: false` + "Tool call was not approved by the
-                        // user") so the model can recover. We mark the id
-                        // `policyDeniedIds` so `routeEnriched` re-stamps that
-                        // result `isError: true` to honor the SDK `Decision`
-                        // contract. The un-emitted approval is marked
+                        // The pump drives `agent.declineToolCall` so Mastra folds
+                        // the denial into the model's context (persisted as the
+                        // `role: 'tool'` message "Tool call was not approved by the
+                        // user"), letting the model recover on the resume stream.
+                        //
+                        // We synthesize the consumer-facing `tool-result(isError=true)`
+                        // ourselves rather than relying on Mastra to emit one:
+                        // @mastra/core 1.49 no longer emits a standalone
+                        // `tool-result` chunk on the decline-resume `fullStream`
+                        // (the denial text lives only inside the persisted
+                        // `messages.all` payload embedded in `step-finish`), so the
+                        // old "re-stamp Mastra's native result" path never fired and
+                        // the SDK `Decision` contract "a denied tool surfaces as
+                        // `tool-result(isError=true)`" was silently broken. Routing
+                        // it here — immediately after the already-routed `tool-call`
+                        // and before the decline resume — keeps the natural
+                        // tool-call → tool-result ordering the SDK telemetry deriver
+                        // matches on. The un-emitted approval is marked
                         // coordinator-settled so a (spurious) consumer
                         // `approveToolCall` for this id is a no-op rather than a
                         // TOOL_CALL_NOT_FOUND throw.
                         this.settledByCoordinator.add(tc.toolCallId);
-                        this.policyDeniedIds.add(tc.toolCallId);
                         this.decisions.set(tc.toolCallId, { kind: 'decline' });
+                        this.routeEnriched({
+                            type: 'tool-result',
+                            toolCallId: tc.toolCallId,
+                            toolName: tc.toolName,
+                            result: POLICY_DENIED_RESULT_TEXT,
+                            isError: true,
+                        });
                     }
                     else if (!this.batchApprovals && !this.emittedApprovals.has(tc.toolCallId)) {
                         // require-approval, serial: emit on the natural chunk
@@ -727,7 +737,7 @@ export class MastraApprovalCoordinator {
     routeEnriched(event) {
         if (this.aborted || this.disposed)
             return;
-        const enriched = this.policyDenyStamp(this.maybeEnrich(event));
+        const enriched = this.maybeEnrich(event);
         // Issue #591: track in-flight MCP tool call so progress notifications
         // arriving via `progress.onUpdate(...)` can be attributed to the
         // right `toolCallId`. Set on a genuinely MCP-discovered tool-call;
@@ -782,29 +792,6 @@ export class MastraApprovalCoordinator {
         const out = { ...event, ...fields };
         return out;
     }
-    /**
-     * Re-stamp `isError: true` on the `tool-result` for a policy-denied tool
-     * call (Phase 2a). When the resolver returns `'deny'`, the coordinator
-     * drives `agent.declineToolCall`; Mastra emits a native `tool-result` with
-     * `isError: false` and the text "Tool call was not approved by the user".
-     * The SDK `Decision` contract requires a denied tool to surface as
-     * `tool-result(isError=true)` so consumers and the model treat it as a
-     * failed call, not a successful one — so we flip the flag exactly once, on
-     * the matching result. Consumer-driven declines (not policy denials) are not
-     * in `policyDeniedIds` and keep Mastra's native shape.
-     */
-    policyDenyStamp(event) {
-        if (event.type !== 'tool-result' || !this.policyDeniedIds.has(event.toolCallId)) {
-            return event;
-        }
-        // One-shot: clear so a later same-id result (shouldn't happen, but be
-        // safe) isn't mislabeled, and the set doesn't grow unbounded.
-        this.policyDeniedIds.delete(event.toolCallId);
-        if (event.isError)
-            return event;
-        const out = { ...event, isError: true };
-        return out;
-    }
     /**
      * Build the {@link ToolInvocation} the policy resolver matches against, and
      * the single source of the `serverName` / `annotations` identity stamped on
@@ -852,11 +839,10 @@ export class MastraApprovalCoordinator {
      * Resolve the approval decision for a non-consumer tool via the harness-
      * supplied {@link MastraApprovalCoordinatorOptions.lookupPolicy} callback.
      * Falls back to `'require-approval'` when no policy callback is wired — a
-     * defensive default so a future caller that passes `requireToolApproval`
-     * without a resolver surfaces the request rather than silently allowing.
-     * In practice this fallback is unreachable: gating is active iff
-     * `lookupPolicy` is defined, and only then does Mastra suspend non-consumer
-     * tools.
+     * defensive default so a future caller that activates gating without a
+     * resolver surfaces the request rather than silently allowing. In practice
+     * this fallback is unreachable: gating is active iff `lookupPolicy` is
+     * defined, and only then does Mastra suspend non-consumer tools.
      */
     policyFor(toolName) {
         if (!this.lookupPolicy)

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

@@ -2,7 +2,7 @@ import type { HarnessFactory, ProviderHint } from '@salesforce/sfdx-agent-sdk';
 import { type MastraAgentHarness } from './mastra-harness.js';
 export interface MastraHarnessFactoryConfig {
     /**
-     * How long to wait for a `requireToolApproval` consumer to call
+     * How long to wait for a consumer to call
      * `approveToolCall` / `declineToolCall` before auto-denying via
      * `agent.abortRunStream(...)` and yielding a synthetic `error`
      * (`code: 'tool-approval-timeout'`) + `finish` (`finishReason: 'error'`)

package/dist/mastra-harness.d.ts

@@ -122,9 +122,8 @@ interface MastraAgentState {
     coordinators: Map<string, MastraApprovalCoordinator>;
     /**
      * Names of consumer-executed tools registered via `AgentConfig.tools`.
-     * The coordinator uses this set to bypass the approval gate for them
-     * (per the `StreamOptions.requireToolApproval` JSDoc) — when Mastra
-     * suspends on a `tool-call-approval` for a name in this set the
+     * The coordinator uses this set to bypass the approval gate for them —
+     * when Mastra suspends on a `tool-call-approval` for a name in this set the
      * coordinator silently calls `agent.approveToolCall(...)` and never
      * surfaces a `tool-approval-request` ChatEvent.
      */
@@ -424,31 +423,16 @@ export declare class MastraHarness implements MastraAgentHarness {
      *   during pending approval (#409)".
      */
     /**
-     * Phase 2a: decide whether the approval gate engages this turn and, if so,
-     * build the per-tool policy resolver the coordinator consults.
+     * Decide whether the approval gate engages this turn and, if so, build the
+     * per-tool policy resolver the coordinator consults.
      *
-     * Gating is **opt-in**. It engages when the consumer set any of:
-     *  - `config.toolPolicies` (non-empty),
-     *  - `config.defaultToolDecision`,
-     *  - the deprecated `StreamOptions.requireToolApproval` (any non-`false`
-     *    value — `deprecatedMode` is `'serial'`/`'batch'`/`undefined`), or
-     *  - `StreamOptions.batchApprovals: true`.
+     * Gating is **opt-in**. It engages when the consumer set either:
+     *  - `config.toolPolicies` (non-empty), or
+     *  - `config.defaultToolDecision`.
      *
-     * When none are set, returns `{ lookupPolicy: undefined }` — the caller
+     * When neither is set, returns `{ lookupPolicy: undefined }` — the caller
      * omits `requireToolApproval` from Mastra's `stream()` and tools run free
-     * (today's behavior).
-     *
-     * **Deprecation bridge.** When the gate engages *only* because the deprecated
-     * `requireToolApproval` was truthy (no `toolPolicies`, no
-     * `defaultToolDecision`), the effective default must be `'require-approval'`
-     * — legacy all-or-none — not the resolver's `'allow'` default, or the old
-     * behavior would silently flip to "auto-approve everything." We apply this
-     * by resolving against a shallow-overridden config carrying
-     * `defaultToolDecision: 'require-approval'`. Built-in allow-rules
-     * (skill_bridge meta-tools, the Mastra built-ins) and any consumer
-     * `toolPolicies` still win over the default via within-tier last-wins /
-     * cross-tier deny-wins, so the capability-discovery meta-tools stay
-     * auto-approved even under legacy gating.
+     * (the SDK's "no policy ⇒ no gating" back-compat invariant).
      *
      * **Live config read (#638).** `lookupPolicy` reads `agentState.config` on
      * every call rather than closing over a snapshot taken at stream start. A
@@ -459,22 +443,14 @@ export declare class MastraHarness implements MastraAgentHarness {
      * that persisted the rule. Reading live makes the remembered decision
      * auto-resolve subsequent matching tool calls within the same turn.
      *
-     * Two decisions stay **frozen at stream start** and MUST NOT be recomputed
-     * live:
-     *  - `gatingActive` — the turn either told Mastra to suspend tools
-     *    (`requireToolApproval: true`) or it didn't; gating cannot begin
-     *    mid-turn. The closure is built (and returned) iff gating engaged now.
-     *  - `applyLegacyBridge` (`!hasPolicy && legacyGating`) — whether the
-     *    deprecation bridge injects `defaultToolDecision: 'require-approval'`.
-     *    If this were recomputed live, the FIRST remembered rule would flip
-     *    `hasPolicy` false→true, turn the bridge OFF mid-turn, and silently drop
-     *    the effective default back to the resolver's `'allow'` — auto-approving
-     *    every remaining legacy-gated tool. Freezing the boolean and applying it
-     *    to the live config preserves legacy all-or-none semantics while still
-     *    honoring any rule the turn appends.
+     * `gatingActive` stays **frozen at stream start** — the turn either told
+     * Mastra to suspend tools (`requireToolApproval: true`) or it didn't; gating
+     * cannot begin mid-turn. The closure is built (and returned) iff gating
+     * engaged now.
      *
-     * `batchApprovals` is the serial-vs-batch emission axis: the explicit
-     * `StreamOptions.batchApprovals` OR the legacy `requireToolApproval: 'batch'`.
+     * `batchApprovals` is the serial-vs-batch emission axis, read straight off
+     * `StreamOptions.batchApprovals`. It has no effect when the gate is inactive
+     * (nothing resolves to `'require-approval'`, so there is nothing to batch).
      */
     private buildPolicyGate;
     /**

package/dist/mastra-harness.js

@@ -11,7 +11,7 @@ import { SkillSearchProcessor, ToolSearchProcessor } from '@mastra/core/processo
 import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY, RequestContext } from '@mastra/core/request-context';
 import { LibSQLStore } from '@mastra/libsql';
 import { MCPClient } from '@mastra/mcp';
-import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, resolveToolApprovalMode, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
+import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
 import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, mergeToolResultsIntoAssistant, splitToolResultsIntoToolMessages, } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraApprovalCoordinator } from './mastra-approval-coordinator.js';
 import { MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
@@ -1339,31 +1339,16 @@ export class MastraHarness {
      *   during pending approval (#409)".
      */
     /**
-     * Phase 2a: decide whether the approval gate engages this turn and, if so,
-     * build the per-tool policy resolver the coordinator consults.
+     * Decide whether the approval gate engages this turn and, if so, build the
+     * per-tool policy resolver the coordinator consults.
      *
-     * Gating is **opt-in**. It engages when the consumer set any of:
-     *  - `config.toolPolicies` (non-empty),
-     *  - `config.defaultToolDecision`,
-     *  - the deprecated `StreamOptions.requireToolApproval` (any non-`false`
-     *    value — `deprecatedMode` is `'serial'`/`'batch'`/`undefined`), or
-     *  - `StreamOptions.batchApprovals: true`.
+     * Gating is **opt-in**. It engages when the consumer set either:
+     *  - `config.toolPolicies` (non-empty), or
+     *  - `config.defaultToolDecision`.
      *
-     * When none are set, returns `{ lookupPolicy: undefined }` — the caller
+     * When neither is set, returns `{ lookupPolicy: undefined }` — the caller
      * omits `requireToolApproval` from Mastra's `stream()` and tools run free
-     * (today's behavior).
-     *
-     * **Deprecation bridge.** When the gate engages *only* because the deprecated
-     * `requireToolApproval` was truthy (no `toolPolicies`, no
-     * `defaultToolDecision`), the effective default must be `'require-approval'`
-     * — legacy all-or-none — not the resolver's `'allow'` default, or the old
-     * behavior would silently flip to "auto-approve everything." We apply this
-     * by resolving against a shallow-overridden config carrying
-     * `defaultToolDecision: 'require-approval'`. Built-in allow-rules
-     * (skill_bridge meta-tools, the Mastra built-ins) and any consumer
-     * `toolPolicies` still win over the default via within-tier last-wins /
-     * cross-tier deny-wins, so the capability-discovery meta-tools stay
-     * auto-approved even under legacy gating.
+     * (the SDK's "no policy ⇒ no gating" back-compat invariant).
      *
      * **Live config read (#638).** `lookupPolicy` reads `agentState.config` on
      * every call rather than closing over a snapshot taken at stream start. A
@@ -1374,47 +1359,27 @@ export class MastraHarness {
      * that persisted the rule. Reading live makes the remembered decision
      * auto-resolve subsequent matching tool calls within the same turn.
      *
-     * Two decisions stay **frozen at stream start** and MUST NOT be recomputed
-     * live:
-     *  - `gatingActive` — the turn either told Mastra to suspend tools
-     *    (`requireToolApproval: true`) or it didn't; gating cannot begin
-     *    mid-turn. The closure is built (and returned) iff gating engaged now.
-     *  - `applyLegacyBridge` (`!hasPolicy && legacyGating`) — whether the
-     *    deprecation bridge injects `defaultToolDecision: 'require-approval'`.
-     *    If this were recomputed live, the FIRST remembered rule would flip
-     *    `hasPolicy` false→true, turn the bridge OFF mid-turn, and silently drop
-     *    the effective default back to the resolver's `'allow'` — auto-approving
-     *    every remaining legacy-gated tool. Freezing the boolean and applying it
-     *    to the live config preserves legacy all-or-none semantics while still
-     *    honoring any rule the turn appends.
+     * `gatingActive` stays **frozen at stream start** — the turn either told
+     * Mastra to suspend tools (`requireToolApproval: true`) or it didn't; gating
+     * cannot begin mid-turn. The closure is built (and returned) iff gating
+     * engaged now.
      *
-     * `batchApprovals` is the serial-vs-batch emission axis: the explicit
-     * `StreamOptions.batchApprovals` OR the legacy `requireToolApproval: 'batch'`.
+     * `batchApprovals` is the serial-vs-batch emission axis, read straight off
+     * `StreamOptions.batchApprovals`. It has no effect when the gate is inactive
+     * (nothing resolves to `'require-approval'`, so there is nothing to batch).
      */
-    buildPolicyGate(agentState, options, deprecatedMode) {
+    buildPolicyGate(agentState, options) {
         const config = agentState.config;
-        const hasPolicy = (config.toolPolicies?.length ?? 0) > 0 || config.defaultToolDecision !== undefined;
-        const legacyGating = deprecatedMode !== undefined;
-        const batchApprovals = options?.batchApprovals === true || deprecatedMode === 'batch';
-        const gatingActive = hasPolicy || legacyGating || batchApprovals;
+        const gatingActive = (config.toolPolicies?.length ?? 0) > 0 || config.defaultToolDecision !== undefined;
         if (!gatingActive) {
             return { batchApprovals: false };
         }
-        // Freeze the deprecation-bridge decision at stream start (see JSDoc) —
-        // whether to inject `defaultToolDecision: 'require-approval'` must not
-        // change when a mid-turn remember rule flips `hasPolicy`.
-        const applyLegacyBridge = !hasPolicy && legacyGating;
-        const lookupPolicy = (invocation) => {
-            // Read the config live so a mid-turn `updateAgentConfig` (e.g. a
-            // remembered rule) is honored for the rest of this turn.
-            const liveConfig = agentState.config;
-            const resolverConfig = applyLegacyBridge
-                ? { ...liveConfig, defaultToolDecision: 'require-approval' }
-                : liveConfig;
-            return resolveToolApprovalPolicy(invocation, resolverConfig, { harness: MASTRA_BUILT_IN_TOOL_POLICIES })
-                .decision;
-        };
-        return { lookupPolicy, batchApprovals };
+        const lookupPolicy = (invocation) => 
+        // Read the config live so a mid-turn `updateAgentConfig` (e.g. a
+        // remembered rule) is honored for the rest of this turn (#638).
+        resolveToolApprovalPolicy(invocation, agentState.config, { harness: MASTRA_BUILT_IN_TOOL_POLICIES })
+            .decision;
+        return { lookupPolicy, batchApprovals: options?.batchApprovals === true };
     }
     /**
      * Maps an SDK `MessagePart[]` into the single AI SDK v5 user `ModelMessage` that
@@ -1440,20 +1405,14 @@ export class MastraHarness {
     }
     async stream(agentId, threadId, message, options) {
         const agentState = this.getAgentStateOrThrow(agentId);
-        // Phase 2a: resolve whether the approval gate engages this turn, and if
-        // so, build the per-tool policy resolver the coordinator consults.
-        //
-        // `resolveToolApprovalMode` still validates the deprecated
-        // `requireToolApproval` union (throws on garbage) and tells us whether
-        // the consumer asked for batch UX (`'batch'`). The gate is **opt-in**:
-        // it engages only when the consumer configured `toolPolicies`,
-        // `defaultToolDecision`, the deprecated `requireToolApproval`, or
-        // `batchApprovals`. With none set, behavior is unchanged from today —
-        // no suspension, no resolver, tools run free (the SDK's "no policy ⇒ no
-        // gating" back-compat invariant), avoiding a suspend/resume round-trip
-        // per tool call.
-        const deprecatedMode = resolveToolApprovalMode(options?.requireToolApproval);
-        const { lookupPolicy, batchApprovals } = this.buildPolicyGate(agentState, options, deprecatedMode);
+        // Resolve whether the approval gate engages this turn, and if so, build
+        // the per-tool policy resolver the coordinator consults. The gate is
+        // **opt-in**: it engages only when the consumer configured
+        // `toolPolicies` or `defaultToolDecision`. With neither set, behavior is
+        // unchanged — no suspension, no resolver, tools run free (the SDK's "no
+        // policy ⇒ no gating" back-compat invariant), avoiding a suspend/resume
+        // round-trip per tool call.
+        const { lookupPolicy, batchApprovals } = this.buildPolicyGate(agentState, options);
         const gatingActive = lookupPolicy !== undefined;
         // Dispose any coordinator the prior turn on this thread allocated.
         // Without this a stale coordinator from the prior turn would still

package/dist/mastra-tool-mapper.js

@@ -39,10 +39,10 @@ export function mapToolDefinitionsToMastraTools(tools, parkerLookup) {
             description: tool.description ?? '',
             inputSchema: ensureJsonSchemaMarker(tool.inputSchema),
             // Issue #529 step 2c (Path A) — consumer tools bypass the
-            // approval gate per the StreamOptions.requireToolApproval
-            // JSDoc. With `requireApproval: false`, Mastra parks the
-            // agentic run on the parker Promise without suspending the
-            // workflow. The coordinator handles the parker lifecycle.
+            // approval gate by construction. With `requireApproval: false`,
+            // Mastra parks the agentic run on the parker Promise without
+            // suspending the workflow. The coordinator handles the parker
+            // lifecycle.
             //
             // Phase 2a dual-enforcement contract: this `requireApproval: false`
             // is the PRIMARY, structural gate for consumer tools — it is

package/dist/pass-through-anthropic.js

@@ -4,7 +4,7 @@
  */
 import { AnthropicBedrock } from '@anthropic-ai/bedrock-sdk';
 import Anthropic from '@anthropic-ai/sdk';
-import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, mapAnthropicFinishReason, mapAnthropicUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapAnthropicFinishReason, mapAnthropicUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl for the Salesforce LLM Gateway's
  * `/invoke-with-response-stream` (Bedrock-Anthropic pass-through) endpoint.
@@ -143,15 +143,24 @@ async function buildAnthropicRequest(ctx, options) {
     const tools = translateToolsToAnthropic(options);
     const commonParams = {
         model: info.nativeModelId,
-        max_tokens: options.maxOutputTokens ?? DEFAULT_MAX_TOKENS,
+        // Precedence: an explicit per-request `maxOutputTokens` wins; otherwise
+        // thread the bound model's published cap (`info.model.maxOutputTokens`)
+        // so large completions aren't silently truncated at the 4096 floor
+        // (W-23413250). `DEFAULT_MAX_TOKENS` is only the last-resort fallback for
+        // a model shape that somehow lacks the cap — Bedrock requires the field,
+        // so this path must always yield a number.
+        max_tokens: options.maxOutputTokens ?? info.model.maxOutputTokens ?? DEFAULT_MAX_TOKENS,
         messages,
     };
     if (system !== undefined)
         commonParams.system = system;
     if (tools.length > 0)
         commonParams.tools = tools;
-    if (options.temperature !== undefined)
+    // The gateway deprecated `temperature` for Claude Opus 4.7+ and rejects the
+    // request if it's present; drop it when the bound model excludes it.
+    if (options.temperature !== undefined && !isParameterExcluded(info.model, 'temperature')) {
         commonParams.temperature = options.temperature;
+    }
     if (options.stopSequences !== undefined)
         commonParams.stop_sequences = [...options.stopSequences];
     return { client, commonParams };

package/dist/pass-through-openai-chat-completions.js

@@ -3,7 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import OpenAI from 'openai';
-import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
  * `chat.completions.create({ stream: true })` against an OpenAI-compatible
@@ -62,7 +62,11 @@ async function buildRequest(ctx, options) {
         model: info.nativeModelId,
         messages,
         ...(tools.length > 0 ? { tools } : {}),
-        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+        // The gateway deprecated `temperature` for Claude Opus 4.7+ and rejects
+        // the request if it's present; drop it when the bound model excludes it.
+        ...(options.temperature !== undefined && !isParameterExcluded(info.model, 'temperature')
+            ? { temperature: options.temperature }
+            : {}),
         ...(options.maxOutputTokens !== undefined ? { max_tokens: options.maxOutputTokens } : {}),
         ...(options.stopSequences !== undefined && options.stopSequences.length > 0
             ? { stop: [...options.stopSequences] }

package/dist/pass-through-openai.js

@@ -3,7 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 import OpenAI from 'openai';
-import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, mapOpenAIFinishReason, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
+import { TextSpanLifecycle, createGatewayFetch, isEmptyUsage, isParameterExcluded, mapOpenAIFinishReason, mapOpenAIUsage, toolResultOutputToString, } from './v3-stream-mapping.js';
 /**
  * Builds the in-process `LanguageModelV3` impl that drives the `openai` SDK's
  * `responses.create({ stream: true })` against the Salesforce LLM Gateway's
@@ -63,7 +63,11 @@ async function buildOpenAIRequest(ctx, options) {
         input,
         ...(instructions !== undefined ? { instructions } : {}),
         ...(tools.length > 0 ? { tools } : {}),
-        ...(options.temperature !== undefined ? { temperature: options.temperature } : {}),
+        // The gateway deprecated `temperature` for Claude Opus 4.7+ and rejects
+        // the request if it's present; drop it when the bound model excludes it.
+        ...(options.temperature !== undefined && !isParameterExcluded(info.model, 'temperature')
+            ? { temperature: options.temperature }
+            : {}),
         ...(options.maxOutputTokens !== undefined ? { max_output_tokens: options.maxOutputTokens } : {}),
     };
     return { client, commonParams };

package/dist/v3-stream-mapping.d.ts

@@ -1,5 +1,6 @@
 import type { LanguageModelV3FinishReason, LanguageModelV3StreamPart, LanguageModelV3ToolResultOutput, LanguageModelV3Usage } from '@ai-sdk/provider';
 import { Clock } from '@salesforce/agentic-common';
+import type { Model } from '@salesforce/sfdx-agent-sdk';
 /**
  * Shared V3 helpers for the Mastra harness's `LanguageModelV3` implementations
  * — stream-shaping primitives, finish-reason / usage mappers, prompt-translation
@@ -11,6 +12,21 @@ import { Clock } from '@salesforce/agentic-common';
  * the lifecycle invariants those parts have to honor — drift between any two
  * paths is a TS compile error rather than a silent wire-shape divergence.
  */
+/**
+ * Whether a generation parameter must be stripped from the outbound request
+ * for this model.
+ *
+ * `Model.excludedParameters` is a denylist of generation parameters the LLM
+ * Gateway rejects for the model. The pass-through builders consult it before
+ * forwarding a parameter — today only `temperature`, which the gateway
+ * deprecated for Claude Opus 4.7+ and now rejects. A model that lists a
+ * parameter here has it dropped from the request.
+ *
+ * `undefined` (the default) means nothing is excluded — every parameter the
+ * harness would send is forwarded. Only models that need to suppress a
+ * deprecated parameter declare `excludedParameters`.
+ */
+export declare function isParameterExcluded(model: Model, parameter: string): boolean;
 /**
  * Encodes the AI SDK V3 text-span lifecycle (`text-start` / `text-delta` /
  * `text-end`) and the rotation that must happen around tool calls.

package/dist/v3-stream-mapping.js

@@ -14,6 +14,23 @@ import { Clock, RealClock } from '@salesforce/agentic-common';
  * the lifecycle invariants those parts have to honor — drift between any two
  * paths is a TS compile error rather than a silent wire-shape divergence.
  */
+/**
+ * Whether a generation parameter must be stripped from the outbound request
+ * for this model.
+ *
+ * `Model.excludedParameters` is a denylist of generation parameters the LLM
+ * Gateway rejects for the model. The pass-through builders consult it before
+ * forwarding a parameter — today only `temperature`, which the gateway
+ * deprecated for Claude Opus 4.7+ and now rejects. A model that lists a
+ * parameter here has it dropped from the request.
+ *
+ * `undefined` (the default) means nothing is excluded — every parameter the
+ * harness would send is forwarded. Only models that need to suppress a
+ * deprecated parameter declare `excludedParameters`.
+ */
+export function isParameterExcluded(model, parameter) {
+    return model.excludedParameters?.includes(parameter) ?? false;
+}
 /**
  * Encodes the AI SDK V3 text-span lifecycle (`text-start` / `text-delta` /
  * `text-end`) and the rotation that must happen around tool calls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.31.0",
+  "version": "0.33.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "showcoverage": "open ./coverage/lcov-report/index.html",
-    "test": "tsc --build ./test/tsconfig.json && vitest run --coverage"
+    "test": "tsc --build ./test/tsconfig.json && vitest run --coverage",
+    "test:conformance": "tsc --build ./test/tsconfig.json && vitest run test/conformance"
   },
   "license": "SEE LICENSE IN LICENSE.txt",
   "files": [
@@ -31,35 +32,36 @@
     "@ai-sdk/provider": "^3.0.10",
     "@anthropic-ai/bedrock-sdk": "^0.32.0",
     "@anthropic-ai/sdk": "^0.106.0",
-    "@mastra/core": "^1.49.0",
-    "@mastra/libsql": "^1.15.0",
-    "@mastra/mcp": "^1.13.0",
-    "@mastra/memory": "^1.22.1",
+    "@mastra/core": "^1.50.1",
+    "@mastra/libsql": "^1.15.1",
+    "@mastra/mcp": "^1.13.1",
+    "@mastra/memory": "^1.22.2",
     "@mastra/schema-compat": "^1.2.11",
     "@salesforce/agentic-common": "0.13.0",
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.32.0"
+    "@salesforce/sfdx-agent-sdk": "0.34.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.32.0",
+    "@salesforce/harness-conformance": "0.0.1",
+    "@salesforce/sfdx-agent-sdk": "0.34.0",
     "@types/node": "^22.20.0",
-    "@vitest/coverage-istanbul": "^4.1.8",
-    "@vitest/eslint-plugin": "^1.6.20",
-    "eslint": "^10.6.0",
+    "@vitest/coverage-istanbul": "^4.1.10",
+    "@vitest/eslint-plugin": "^1.6.23",
+    "eslint": "^10.7.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
-    "eslint-plugin-n": "^18.2.1",
+    "eslint-plugin-n": "^18.2.2",
     "globals": "^17.6.0",
     "lint-staged": "^17.0.7",
     "prettier": "^3.9.4",
     "rimraf": "^6.1.3",
     "tsx": "^4.23.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.62.1",
+    "typescript-eslint": "^8.63.0",
     "vitest": "^4.1.8"
   },
   "engines": {