@salesforce/sfdx-agent-harness-mastra 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -3,6 +3,12 @@
 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.25.0] - 2026-06-29
+
+### Features
+- **harness-mastra**: consult tool-approval policy resolver at gate sites @W-23090028 ([#622](https://github.com/forcedotcom/agentic-dx/pull/622))
+- **harness-mastra**: stable skill_bridge identity for capability-discovery meta-tools @W-23177289 ([#621](https://github.com/forcedotcom/agentic-dx/pull/621))
+
 ## [0.24.0] - 2026-06-24
 
 ### Chores

package/README.md

@@ -44,10 +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.                                                                                  |
 
 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
@@ -191,9 +193,33 @@ for await (const event of result.eventStream) {
 }
 ```
 
+### Tool-approval policy
+
+The harness gates harness-executed tools through the SDK's `resolveToolApprovalPolicy` (configure rules via
+`AgentConfig.toolPolicies` / `AgentConfig.defaultToolDecision` — see the SDK README). For each non-consumer tool the
+harness resolves a decision and acts on it:
+
+- **`allow`** — the tool runs without surfacing a `tool-approval-request`.
+- **`deny`** — the tool is refused and the model receives a `tool-result(isError=true)` so it can recover; no
+  `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
+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 `requireToolApproval: true` is set on a `chat()` call, the harness suspends the workflow on each
+When the approval gate is engaged and a tool resolves to `require-approval`, the harness suspends the workflow on each
 `tool-approval-request` and waits for the consumer to call `approveToolCall(...)` / `declineToolCall(...)` /
 `submitToolResult(...)`. To bound how long a pending approval can wait — for example, when a UI process crashes or a
 user walks away — the factory accepts a `toolApprovalTimeoutMs` option. It defaults to `600_000` (10 minutes) and

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export { MastraHarnessFactory, type MastraHarnessFactoryConfig } from './mastra-harness-factory.js';
 export type { MastraAgentHarness } from './mastra-harness.js';
+export { MASTRA_BUILT_IN_TOOL_NAMES, MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 export { type MastraAgentConfig, type MastraSkillSearchConfig, type MastraToolSearchConfig, type SkillSearchHandle, type ToolSearchHandle, } from './tool-search.js';

package/dist/index.js

@@ -3,6 +3,10 @@
  * See LICENSE.txt for license terms.
  */
 export { MastraHarnessFactory } from './mastra-harness-factory.js';
+// Harness-specific built-in tool-approval rules — the `tiers.harness` slice the
+// harness feeds `resolveToolApprovalPolicy`. Exported so consumers and tests can
+// inspect which Mastra built-ins the harness auto-approves.
+export { MASTRA_BUILT_IN_TOOL_NAMES, MASTRA_BUILT_IN_TOOL_POLICIES } from './mastra-built-in-policies.js';
 export {} from './tool-search.js';
 // Mastra drives requests through provider-native pass-through endpoints —
 // Bedrock-Anthropic, direct Anthropic Messages API, OpenAI Responses, and

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

@@ -1,7 +1,7 @@
 import type { Agent } from '@mastra/core/agent';
 import type { RequestContext } from '@mastra/core/request-context';
 import type { ChunkType } from '@mastra/core/stream';
-import { type ChatEvent, type McpToolAnnotations } from '@salesforce/sfdx-agent-sdk';
+import { type ChatEvent, type Decision as PolicyDecision, type McpToolAnnotations, type ToolInvocation } from '@salesforce/sfdx-agent-sdk';
 import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
 import type { LogBus } from '@salesforce/agentic-common';
 /**
@@ -36,35 +36,57 @@ export interface MastraApprovalCoordinatorOptions {
     requestContext: RequestContext;
     toolApprovalTimeoutMs: number;
     /**
-     * Approval-emission mode (#447). Defaults to `undefined` (no gating).
+     * Per-tool approval-decision callback (Phase 2a). When defined, gating is
+     * **active**: the harness passed `requireToolApproval: true` to Mastra so
+     * every non-consumer tool suspends with a `tool-call-approval` chunk, and
+     * the coordinator consults this callback to decide each one:
      *
-     * - `undefined`: stream is run without `requireToolApproval`. Mastra
-     *   suspends only on tools whose per-tool `requireApproval` is `true`
-     *   (consumer tools post-2c are `false` so they don't suspend; the
-     *   bridge's parker `execute` handles their lifecycle natively).
-     * - `'serial'`: stream runs with `requireToolApproval: true`. The
-     *   coordinator emits one `tool-approval-request` per natural
-     *   `tool-call-approval` chunk — Mastra serializes one approval per
-     *   suspension.
-     * - `'batch'`: same as serial except `tool-approval-request` is
-     *   front-loaded off the adapter's `tool-call` events so parallel
-     *   `tool_use` batches all surface their approval-requests on the
-     *   single per-turn stream.
+     * - `'allow'` → silent approve (no `tool-approval-request` ChatEvent; the
+     *   pump drives `agent.approveToolCall`).
+     * - `'deny'` → silent decline (no ChatEvent; the pump drives
+     *   `agent.declineToolCall`, which surfaces a `tool-result(isError=true)`
+     *   to the model so it can recover).
+     * - `'require-approval'` → emit a `tool-approval-request` and park
+     *   (front-loaded off `tool-call` when `batchApprovals`, else on the
+     *   natural `tool-call-approval` chunk).
      *
-     * Note: in approval mode, consumer-executed tools still bypass the
-     * approval gate (per the `StreamOptions.requireToolApproval` JSDoc) —
-     * the coordinator silently calls `agent.approveToolCall(id)` for them
-     * without surfacing a `tool-approval-request` ChatEvent.
+     * `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.
+     *
+     * The coordinator builds the {@link ToolInvocation} it passes here from the
+     * same identity sources it uses for event enrichment
+     * (`skillBridgeToolNames` + `lookupMcpToolMetadata`), so the identity that
+     * drives the decision can never drift from the one stamped on the emitted
+     * ChatEvent. The callback itself closes over `AgentConfig` +
+     * `MASTRA_BUILT_IN_TOOL_POLICIES` in the harness.
+     *
+     * Consumer-executed tools bypass this callback entirely — the structural
+     * `requireApproval: false` parker gate is their primary contract; they are
+     * silently auto-approved before the resolver is consulted.
+     */
+    lookupPolicy?: (invocation: ToolInvocation) => PolicyDecision;
+    /**
+     * When `true`, `require-approval` decisions are front-loaded off the
+     * adapter's `tool-call` events so parallel `tool_use` batches all surface
+     * their approval-requests on the single per-turn stream (the consumer
+     * 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
+     * {@link lookupPolicy} is `undefined` (gating off) or when no tool resolves
+     * to `require-approval`.
      */
-    mode?: 'serial' | 'batch';
+    batchApprovals?: boolean;
     /**
      * Set of tool names registered via `AgentConfig.tools`. The coordinator
      * uses this to route `tool-call-approval` chunks: if the toolName is in
      * the set, auto-approve silently (consumer tools bypass the gate); else
-     * surface a `tool-approval-request` ChatEvent and park.
+     * consult {@link lookupPolicy}.
      *
-     * Empty set when no consumer tools are configured — every approval
-     * chunk surfaces to the consumer in approval mode.
+     * Empty set when no consumer tools are configured.
      */
     consumerToolNames: ReadonlySet<string>;
     /**
@@ -74,6 +96,23 @@ export interface MastraApprovalCoordinatorOptions {
      * `tool-result` / `tool-approval-request` events.
      */
     lookupMcpToolMetadata?: MastraMcpToolMetadataLookup;
+    /**
+     * Capability-discovery meta-tool leaf names that are ACTIVE on this turn
+     * (#606). The harness populates this from the live
+     * `ToolSearchProcessor` / `SkillSearchProcessor` so it contains
+     * `search_tools` / `load_tool` only when tool-search is configured and
+     * `search_skills` / `load_skill` only when skill-search is configured.
+     *
+     * The coordinator stamps `serverName: SKILL_BRIDGE_SERVER_ID` onto
+     * `tool-call` / `tool-result` / `tool-approval-request` events for these
+     * leaves so the SDK's `mcp:skill_bridge:*` built-in rules auto-approve
+     * them, reaching parity with Claude's in-process `skill_bridge` MCP
+     * server. Gating on the ACTIVE set (not the leaf name alone) is the
+     * security boundary: a consumer-declared tool named `load_skill` with no
+     * `skillSearch` configured is never in this set, so it cannot inherit the
+     * exemption. Empty set when neither processor is active.
+     */
+    skillBridgeToolNames?: ReadonlySet<string>;
     logBus?: LogBus;
 }
 /**
@@ -82,10 +121,13 @@ export interface MastraApprovalCoordinatorOptions {
  * sink, single multi-source pump loop, and single set of teardown paths.
  *
  * Responsibilities:
- *  - Approval gating in `'serial'` / `'batch'` mode: emit
- *    `tool-approval-request` for non-consumer tools, drive
- *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the
- *    consumer settles.
+ *  - 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)`),
+ *    `require-approval` emits a `tool-approval-request` and drives
+ *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the consumer
+ *    settles. `batchApprovals` controls whether parallel `require-approval`
+ *    requests front-load onto one stream (#447).
  *  - Consumer-tool plumbing: every `AgentConfig.tools` entry has
  *    `requireApproval: false` and a Promise-returning `execute` that parks
  *    on the coordinator's `parkConsumerToolCall(...)`. Mastra natively
@@ -114,14 +156,27 @@ export declare class MastraApprovalCoordinator {
     private readonly memory;
     private readonly requestContext;
     private readonly toolApprovalTimeoutMs;
-    private readonly mode;
+    private readonly lookupPolicy?;
+    private readonly batchApprovals;
     private readonly consumerToolNames;
     private readonly lookupMcpToolMetadata?;
+    private readonly skillBridgeToolNames;
     private readonly adapter;
     /** Single per-turn sink. Issue #529 contract: one stream per turn. */
     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. */
@@ -352,6 +407,56 @@ 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
+     * emitted events ({@link maybeEnrich}). One helper feeds both so the
+     * identity that drives the approval decision can never drift from the one
+     * the consumer observes on the `tool-call` / `tool-result` /
+     * `tool-approval-request` ChatEvent.
+     *
+     * Three disjoint cases:
+     *
+     * - **Capability-discovery meta-tool active this turn (#606)** — wins first.
+     *   Gets the well-known `SKILL_BRIDGE_SERVER_ID` identity so the SDK's
+     *   `mcp:skill_bridge:*` built-in rules auto-approve it, matching Claude's
+     *   in-process skill-bridge MCP server. These tools are flat (un-namespaced),
+     *   so the chunk's `toolName` is already the bare leaf. This branch fires
+     *   even when the agent has no MCP servers (`lookupMcpToolMetadata` unset).
+     * - **Genuinely MCP-discovered tool** — recover the bare un-namespaced leaf
+     *   the SDK's `mcp` matcher compares against by stripping Mastra's
+     *   `${serverName}_` namespace prefix.
+     * - **Built-in / consumer / workspace tool** — bare name, no `serverName`.
+     *   Matches `{ type: 'builtin', name }` rules (e.g. the Mastra built-ins in
+     *   `MASTRA_BUILT_IN_TOOL_POLICIES`).
+     *
+     * The meta-tool and MCP-catalog identities are disjoint: a real MCP tool is
+     * never in `skillBridgeToolNames`, and a meta-tool is never in the catalog.
+     */
+    private buildToolInvocation;
+    /**
+     * 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.
+     */
+    private policyFor;
     private emitApprovalRequest;
     private armApprovalTimer;
     private cancelTimer;

package/dist/mastra-approval-coordinator.js

@@ -5,6 +5,16 @@
 import { AgentSDKError, AgentSDKErrorType, } from '@salesforce/sfdx-agent-sdk';
 import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
 import { MastraEventAdapter } from './mastra-event-adapter.js';
+import { SKILL_BRIDGE_SERVER_ID } from './skill-bridge.js';
+/**
+ * True when `serverName` identifies a genuinely MCP-discovered tool, as opposed
+ * to the synthetic `skill_bridge` identity stamped onto capability-discovery
+ * meta-tools (#606) or `undefined` for built-ins / consumer / workspace tools.
+ * Used to scope MCP-progress attribution to real MCP servers.
+ */
+function isRealMcpServer(serverName) {
+    return serverName !== undefined && serverName !== SKILL_BRIDGE_SERVER_ID;
+}
 function pickIdWithDecision(pendingIds, decisions) {
     for (const id of pendingIds) {
         if (decisions.has(id))
@@ -18,10 +28,13 @@ function pickIdWithDecision(pendingIds, decisions) {
  * sink, single multi-source pump loop, and single set of teardown paths.
  *
  * Responsibilities:
- *  - Approval gating in `'serial'` / `'batch'` mode: emit
- *    `tool-approval-request` for non-consumer tools, drive
- *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the
- *    consumer settles.
+ *  - 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)`),
+ *    `require-approval` emits a `tool-approval-request` and drives
+ *    `agent.approveToolCall(...)` / `declineToolCall(...)` when the consumer
+ *    settles. `batchApprovals` controls whether parallel `require-approval`
+ *    requests front-load onto one stream (#447).
  *  - Consumer-tool plumbing: every `AgentConfig.tools` entry has
  *    `requireApproval: false` and a Promise-returning `execute` that parks
  *    on the coordinator's `parkConsumerToolCall(...)`. Mastra natively
@@ -50,14 +63,27 @@ export class MastraApprovalCoordinator {
     memory;
     requestContext;
     toolApprovalTimeoutMs;
-    mode;
+    lookupPolicy;
+    batchApprovals;
     consumerToolNames;
     lookupMcpToolMetadata;
+    skillBridgeToolNames;
     adapter;
     /** Single per-turn sink. Issue #529 contract: one stream per turn. */
     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. */
@@ -149,9 +175,11 @@ export class MastraApprovalCoordinator {
         this.memory = opts.memory;
         this.requestContext = opts.requestContext;
         this.toolApprovalTimeoutMs = opts.toolApprovalTimeoutMs;
-        this.mode = opts.mode;
+        this.lookupPolicy = opts.lookupPolicy;
+        this.batchApprovals = opts.batchApprovals ?? false;
         this.consumerToolNames = opts.consumerToolNames;
         this.lookupMcpToolMetadata = opts.lookupMcpToolMetadata;
+        this.skillBridgeToolNames = opts.skillBridgeToolNames ?? new Set();
         this.adapter = new MastraEventAdapter(opts.logBus);
     }
     // ───────────────────────── lifecycle / sinks ────────────────────────────
@@ -314,6 +342,10 @@ 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 ───────────────────────────────
@@ -536,13 +568,16 @@ export class MastraApprovalCoordinator {
                 }
                 if (event.type === 'tool-call') {
                     this.toolCallArgs.set(event.toolCallId, event.args);
-                    // In batch mode, front-load `tool-approval-request` for
-                    // non-consumer tools so parallel tool_use blocks all
-                    // surface their approvals on the single per-turn
-                    // stream. Consumer tools always bypass the gate.
-                    if (this.mode === 'batch' &&
+                    // Batch mode (#447): front-load the `tool-approval-request`
+                    // for non-consumer tools whose policy is `require-approval`
+                    // so parallel tool_use blocks all surface their approvals on
+                    // the single per-turn stream. `allow` / `deny` need no
+                    // ChatEvent — they're applied silently at the suspension
+                    // chunk. Consumer tools always bypass the gate.
+                    if (this.batchApprovals &&
                         !this.consumerToolNames.has(event.toolName) &&
-                        !this.emittedApprovals.has(event.toolCallId)) {
+                        !this.emittedApprovals.has(event.toolCallId) &&
+                        this.policyFor(event.toolName) === 'require-approval') {
                         this.emitApprovalRequest(event.toolCallId, event.toolName, event.args);
                     }
                     this.routeEnriched(event);
@@ -567,10 +602,37 @@ export class MastraApprovalCoordinator {
                         // non-approval-mode consumer-tool flow.
                         this.settledByCoordinator.add(tc.toolCallId);
                         this.decisions.set(tc.toolCallId, { kind: 'approve' });
+                        continue;
                     }
-                    else if (this.mode === 'serial' && !this.emittedApprovals.has(tc.toolCallId)) {
-                        // Serial mode: emit on the natural chunk (didn't
-                        // pre-emit in tool-call routing).
+                    // Non-consumer tool: consult the policy resolver (Phase 2a).
+                    const decision = this.policyFor(tc.toolName);
+                    if (decision === 'allow') {
+                        // Silent approve — no `tool-approval-request` surfaces.
+                        // The pump drives `agent.approveToolCall` from the
+                        // buffered decision; the tool then executes natively
+                        // and its `tool-result` flows on the resumed stream.
+                        this.settledByCoordinator.add(tc.toolCallId);
+                        this.decisions.set(tc.toolCallId, { kind: 'approve' });
+                    }
+                    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
+                        // 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' });
+                    }
+                    else if (!this.batchApprovals && !this.emittedApprovals.has(tc.toolCallId)) {
+                        // require-approval, serial: emit on the natural chunk
+                        // (batch front-loaded it off the prior `tool-call`).
                         this.emitApprovalRequest(tc.toolCallId, tc.toolName, tc.args);
                     }
                     continue;
@@ -665,57 +727,137 @@ export class MastraApprovalCoordinator {
     routeEnriched(event) {
         if (this.aborted || this.disposed)
             return;
-        const enriched = this.maybeEnrich(event);
+        const enriched = this.policyDenyStamp(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 enriched (i.e. MCP-namespaced) tool-call;
-        // cleared on the matching tool-result. Non-MCP tools don't carry
-        // `serverName` (the lookup returns undefined) so this never fires
-        // for built-ins, consumer-declared tools, or workspace tools.
-        if (enriched.type === 'tool-call' && enriched.serverName !== undefined) {
+        // right `toolCallId`. Set on a genuinely MCP-discovered tool-call;
+        // cleared on the matching tool-result. Built-ins, consumer-declared
+        // tools, and workspace tools carry no `serverName` so this never
+        // fires for them.
+        //
+        // #606: the capability-discovery meta-tools now carry a `serverName`
+        // too (the synthetic `skill_bridge` identity), but they are NOT MCP
+        // tools and emit no `notifications/progress`. Excluding them keeps a
+        // real MCP server's progress notification from being mis-attributed to
+        // an interleaved meta-tool call.
+        if (enriched.type === 'tool-call' && isRealMcpServer(enriched.serverName)) {
             this.currentMcpToolCallId = enriched.toolCallId;
             this.toolNameForCallId.set(enriched.toolCallId, enriched.toolName);
         }
         else if (enriched.type === 'tool-result' &&
-            enriched.serverName !== undefined &&
+            isRealMcpServer(enriched.serverName) &&
             this.currentMcpToolCallId === enriched.toolCallId) {
             this.currentMcpToolCallId = null;
         }
         this.initial.push(enriched);
     }
     maybeEnrich(event) {
-        if (!this.lookupMcpToolMetadata)
-            return event;
         if (event.type !== 'tool-call' && event.type !== 'tool-result' && event.type !== 'tool-approval-request') {
             return event;
         }
         const toolName = event.type === 'tool-approval-request' ? event.toolCall.toolName : event.toolName;
-        const metadata = this.lookupMcpToolMetadata(toolName);
-        if (!metadata)
+        const invocation = this.buildToolInvocation(toolName);
+        // No serverName ⇒ built-in / consumer tool ⇒ nothing to stamp. The
+        // event keeps its Mastra-namespaced display `toolName`; enrichment only
+        // adds `serverName` / `annotations`.
+        if (invocation.serverName === undefined)
             return event;
+        const fields = {
+            serverName: invocation.serverName,
+            ...(invocation.annotations ? { annotations: invocation.annotations } : {}),
+        };
         if (event.type === 'tool-call') {
-            const out = {
-                ...event,
-                serverName: metadata.serverName,
-                ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
-            };
+            const out = { ...event, ...fields };
             return out;
         }
         if (event.type === 'tool-result') {
-            const out = {
-                ...event,
-                serverName: metadata.serverName,
-                ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
-            };
+            const out = { ...event, ...fields };
             return out;
         }
-        const out = {
-            ...event,
-            serverName: metadata.serverName,
-            ...(metadata.annotations ? { annotations: metadata.annotations } : {}),
-        };
+        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
+     * emitted events ({@link maybeEnrich}). One helper feeds both so the
+     * identity that drives the approval decision can never drift from the one
+     * the consumer observes on the `tool-call` / `tool-result` /
+     * `tool-approval-request` ChatEvent.
+     *
+     * Three disjoint cases:
+     *
+     * - **Capability-discovery meta-tool active this turn (#606)** — wins first.
+     *   Gets the well-known `SKILL_BRIDGE_SERVER_ID` identity so the SDK's
+     *   `mcp:skill_bridge:*` built-in rules auto-approve it, matching Claude's
+     *   in-process skill-bridge MCP server. These tools are flat (un-namespaced),
+     *   so the chunk's `toolName` is already the bare leaf. This branch fires
+     *   even when the agent has no MCP servers (`lookupMcpToolMetadata` unset).
+     * - **Genuinely MCP-discovered tool** — recover the bare un-namespaced leaf
+     *   the SDK's `mcp` matcher compares against by stripping Mastra's
+     *   `${serverName}_` namespace prefix.
+     * - **Built-in / consumer / workspace tool** — bare name, no `serverName`.
+     *   Matches `{ type: 'builtin', name }` rules (e.g. the Mastra built-ins in
+     *   `MASTRA_BUILT_IN_TOOL_POLICIES`).
+     *
+     * The meta-tool and MCP-catalog identities are disjoint: a real MCP tool is
+     * never in `skillBridgeToolNames`, and a meta-tool is never in the catalog.
+     */
+    buildToolInvocation(toolName) {
+        if (this.skillBridgeToolNames.has(toolName)) {
+            return { toolName, serverName: SKILL_BRIDGE_SERVER_ID };
+        }
+        const mcp = this.lookupMcpToolMetadata?.(toolName);
+        if (mcp) {
+            const bare = toolName.startsWith(`${mcp.serverName}_`)
+                ? toolName.slice(mcp.serverName.length + 1)
+                : toolName;
+            return {
+                toolName: bare,
+                serverName: mcp.serverName,
+                ...(mcp.annotations ? { annotations: mcp.annotations } : {}),
+            };
+        }
+        return { toolName };
+    }
+    /**
+     * 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.
+     */
+    policyFor(toolName) {
+        if (!this.lookupPolicy)
+            return 'require-approval';
+        return this.lookupPolicy(this.buildToolInvocation(toolName));
+    }
     emitApprovalRequest(toolCallId, toolName, args) {
         const event = {
             type: 'tool-approval-request',

package/dist/mastra-built-in-policies.d.ts

@@ -0,0 +1,53 @@
+import type { ToolPolicyRule } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Leaf names of the Mastra-injected built-in tools this harness auto-approves.
+ *
+ * These are the tools Mastra's runtime registers itself — distinct from the
+ * capability-discovery meta-tools (`search_tools` / `load_tool` /
+ * `search_skills` / `load_skill`), which carry the `skill_bridge` MCP identity
+ * and are auto-approved by the SDK's `mcp:skill_bridge:*` rules in
+ * `BUILT_IN_TOOL_POLICIES` (see `skill-bridge.ts`).
+ *
+ * - `updateWorkingMemory` — Mastra's working-memory write tool, registered when
+ *   `workingMemory.enabled` is set (the harness always enables it; see
+ *   ARCHITECTURE.md → "Memory Strategy"). Gating it would prompt the user every
+ *   time the agent updates its own scratchpad — pure friction with no security
+ *   value.
+ * - `skill` / `skill_search` / `skill_read` — Mastra's eager `SkillsProcessor`
+ *   workspace tools, registered when `skills` is set without `skillSearch` (the
+ *   eager path; see ARCHITECTURE.md → "Skill search"). These read skill bodies
+ *   the operator already vetted by configuring `skills`; gating them is the same
+ *   capability-discovery friction the `skill_bridge` meta-tools avoid on the
+ *   on-demand path.
+ *
+ * Each name here is the **wire `toolName`** the resolver matches against — the
+ * tools-map key Mastra registers the tool under, NOT its `createTool` `id`. The
+ * two differ for working memory: Mastra registers
+ * `{ updateWorkingMemory: createTool({ id: 'update-working-memory' }) }`, and
+ * its own approval-boundary checks key on the camelCase `toolName`
+ * (`@mastra/core`: `toolName !== 'updateWorkingMemory'`), so the matcher MUST use
+ * `updateWorkingMemory`, never the kebab-case `id`. (For the three skill tools
+ * the `id` and `toolName` coincide.) A wrong leaf name here is a silent no-op —
+ * the rule never matches and the user gets prompted anyway — so do NOT "correct"
+ * these to the `createTool` ids. The drift test in
+ * `test/mastra-built-in-policies.test.ts` pins only the shape (all `allow`, all
+ * `builtin` matchers), not the names; this caveat is the names' guard rail.
+ */
+export declare const MASTRA_BUILT_IN_TOOL_NAMES: readonly ["updateWorkingMemory", "skill", "skill_search", "skill_read"];
+/**
+ * Mastra harness-specific built-in tool-approval rules — the `tiers.harness`
+ * slice passed to `resolveToolApprovalPolicy`. Per the SDK's R4 layering
+ * invariant, harness-specific built-ins live here, not in the SDK's
+ * harness-agnostic `BUILT_IN_TOOL_POLICIES`.
+ *
+ * Frozen: adding an entry is a soft contract change consumers will have noticed;
+ * removing or modifying one is a breaking change. Every entry is an `allow`
+ * decision on a `builtin` matcher — Mastra's built-in tools carry no MCP
+ * `serverName`, so they match `{ type: 'builtin', name }`.
+ *
+ * Resolution order places this tier after the SDK built-ins and before consumer
+ * `toolPolicies`, so a consumer rule of the same matcher (e.g. an explicit
+ * `definePolicy({ skill: 'require-approval' })`) still wins via within-tier
+ * last-wins, and any `deny` anywhere wins via cross-tier deny-wins.
+ */
+export declare const MASTRA_BUILT_IN_TOOL_POLICIES: ReadonlyArray<ToolPolicyRule>;

package/dist/mastra-built-in-policies.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Leaf names of the Mastra-injected built-in tools this harness auto-approves.
+ *
+ * These are the tools Mastra's runtime registers itself — distinct from the
+ * capability-discovery meta-tools (`search_tools` / `load_tool` /
+ * `search_skills` / `load_skill`), which carry the `skill_bridge` MCP identity
+ * and are auto-approved by the SDK's `mcp:skill_bridge:*` rules in
+ * `BUILT_IN_TOOL_POLICIES` (see `skill-bridge.ts`).
+ *
+ * - `updateWorkingMemory` — Mastra's working-memory write tool, registered when
+ *   `workingMemory.enabled` is set (the harness always enables it; see
+ *   ARCHITECTURE.md → "Memory Strategy"). Gating it would prompt the user every
+ *   time the agent updates its own scratchpad — pure friction with no security
+ *   value.
+ * - `skill` / `skill_search` / `skill_read` — Mastra's eager `SkillsProcessor`
+ *   workspace tools, registered when `skills` is set without `skillSearch` (the
+ *   eager path; see ARCHITECTURE.md → "Skill search"). These read skill bodies
+ *   the operator already vetted by configuring `skills`; gating them is the same
+ *   capability-discovery friction the `skill_bridge` meta-tools avoid on the
+ *   on-demand path.
+ *
+ * Each name here is the **wire `toolName`** the resolver matches against — the
+ * tools-map key Mastra registers the tool under, NOT its `createTool` `id`. The
+ * two differ for working memory: Mastra registers
+ * `{ updateWorkingMemory: createTool({ id: 'update-working-memory' }) }`, and
+ * its own approval-boundary checks key on the camelCase `toolName`
+ * (`@mastra/core`: `toolName !== 'updateWorkingMemory'`), so the matcher MUST use
+ * `updateWorkingMemory`, never the kebab-case `id`. (For the three skill tools
+ * the `id` and `toolName` coincide.) A wrong leaf name here is a silent no-op —
+ * the rule never matches and the user gets prompted anyway — so do NOT "correct"
+ * these to the `createTool` ids. The drift test in
+ * `test/mastra-built-in-policies.test.ts` pins only the shape (all `allow`, all
+ * `builtin` matchers), not the names; this caveat is the names' guard rail.
+ */
+export const MASTRA_BUILT_IN_TOOL_NAMES = ['updateWorkingMemory', 'skill', 'skill_search', 'skill_read'];
+/**
+ * Mastra harness-specific built-in tool-approval rules — the `tiers.harness`
+ * slice passed to `resolveToolApprovalPolicy`. Per the SDK's R4 layering
+ * invariant, harness-specific built-ins live here, not in the SDK's
+ * harness-agnostic `BUILT_IN_TOOL_POLICIES`.
+ *
+ * Frozen: adding an entry is a soft contract change consumers will have noticed;
+ * removing or modifying one is a breaking change. Every entry is an `allow`
+ * decision on a `builtin` matcher — Mastra's built-in tools carry no MCP
+ * `serverName`, so they match `{ type: 'builtin', name }`.
+ *
+ * Resolution order places this tier after the SDK built-ins and before consumer
+ * `toolPolicies`, so a consumer rule of the same matcher (e.g. an explicit
+ * `definePolicy({ skill: 'require-approval' })`) still wins via within-tier
+ * last-wins, and any `deny` anywhere wins via cross-tier deny-wins.
+ */
+export const MASTRA_BUILT_IN_TOOL_POLICIES = Object.freeze(MASTRA_BUILT_IN_TOOL_NAMES.map((name) => ({
+    matcher: { type: 'builtin', name },
+    decision: 'allow',
+    source: 'built-in',
+})));
+//# sourceMappingURL=mastra-built-in-policies.js.map

package/dist/mastra-harness.d.ts

@@ -66,6 +66,14 @@ interface MastraAgentState {
     projectRoot: string;
     /** Mastra Agent instance. */
     agent: Agent;
+    /**
+     * The harness config applied to this agent (re-set on every `updateAgent`).
+     * Phase 2a reads `config.toolPolicies` / `config.defaultToolDecision` to
+     * build the per-stream policy resolver. Stored as the full config (not just
+     * fragments) so the resolver sees the agent's current policy without the
+     * harness threading individual fields through `MastraAgentState`.
+     */
+    config: HarnessAgentConfig;
     /**
      * The instructions string passed to the Mastra `Agent`'s constructor —
      * `config.instructions` after rule bodies have been composed in (see
@@ -405,6 +413,37 @@ export declare class MastraHarness implements MastraAgentHarness {
      *   the thread's `ActiveRun` entry. See ARCHITECTURE.md → "Tool Approval Flow → Abort
      *   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.
+     *
+     * 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`.
+     *
+     * When none are 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.
+     *
+     * `batchApprovals` is the serial-vs-batch emission axis: the explicit
+     * `StreamOptions.batchApprovals` OR the legacy `requireToolApproval: 'batch'`.
+     */
+    private buildPolicyGate;
     /**
      * Maps an SDK `MessagePart[]` into the single AI SDK v5 user `ModelMessage` that
      * `agent.stream()` accepts.

package/dist/mastra-harness.js

@@ -11,9 +11,11 @@ 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, } from '@salesforce/sfdx-agent-sdk';
+import { AgentSDKError, AgentSDKErrorType, DEFAULT_MAX_STEPS, McpServerStatus, resolveToolApprovalMode, resolveToolApprovalPolicy, } from '@salesforce/sfdx-agent-sdk';
 import { HarnessBusOwner, lowerStreamInput, mcpServerConfigEqual, } 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';
+import { SKILL_SEARCH_META_TOOL_NAMES, TOOL_SEARCH_META_TOOL_NAMES } from './skill-bridge.js';
 import { mapMastraToMessage, mapMessageToMastra, partToTranscriptText } from './mastra-message-mapper.js';
 import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/schema-compat';
 import { mapToolDefinitionsToMastraTools } from './mastra-tool-mapper.js';
@@ -251,6 +253,25 @@ function lookupMcpToolMetadata(mcpServers, namespacedToolName) {
     const annotations = best.serverState.tools[namespacedToolName]?.mcp?.annotations;
     return { serverName: best.serverName, ...(annotations ? { annotations } : {}) };
 }
+/**
+ * Build the set of capability-discovery meta-tool leaf names that are ACTIVE
+ * for a turn (#606). Tool-search injects `search_tools` / `load_tool`;
+ * skill-search injects `search_skills` / `load_skill`. The set drives the
+ * coordinator's `skill_bridge` identity stamp — and gating it on the live
+ * processors (not the leaf names alone) is what keeps a consumer-declared
+ * `load_skill` from inheriting the auto-approval exemption when `skillSearch`
+ * is not configured.
+ */
+function activeSkillBridgeToolNames(state) {
+    const names = new Set();
+    if (state.toolSearchProcessor)
+        for (const n of TOOL_SEARCH_META_TOOL_NAMES)
+            names.add(n);
+    if (state.skillSearchProcessor)
+        for (const n of SKILL_SEARCH_META_TOOL_NAMES)
+            names.add(n);
+    return names;
+}
 /**
  * Projects the namespaced Mastra `ToolAction` map for one MCP server into the
  * SDK's harness-agnostic `McpToolInfo[]` shape.
@@ -641,6 +662,7 @@ export class MastraHarness {
             this.activeAgents.set(agentId, {
                 projectRoot,
                 agent,
+                config,
                 composedInstructions,
                 validateFiles,
                 mcpServers: mcpServerStates,
@@ -1065,6 +1087,7 @@ export class MastraHarness {
             const previousWorkspace = state.mastraWorkspace;
             const previousSkillSearchProcessor = state.skillSearchProcessor;
             state.agent = newAgent;
+            state.config = config;
             state.composedInstructions = composedInstructions;
             state.validateFiles = validateFiles;
             state.mcpConfig = config.mcpServers;
@@ -1298,6 +1321,51 @@ export class MastraHarness {
      *   the thread's `ActiveRun` entry. See ARCHITECTURE.md → "Tool Approval Flow → Abort
      *   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.
+     *
+     * 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`.
+     *
+     * When none are 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.
+     *
+     * `batchApprovals` is the serial-vs-batch emission axis: the explicit
+     * `StreamOptions.batchApprovals` OR the legacy `requireToolApproval: 'batch'`.
+     */
+    buildPolicyGate(agentState, options, deprecatedMode) {
+        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;
+        if (!gatingActive) {
+            return { batchApprovals: false };
+        }
+        // Apply the deprecation bridge only when the gate engages purely from
+        // the legacy flag (no explicit policy of any kind).
+        const resolverConfig = !hasPolicy && legacyGating ? { ...config, defaultToolDecision: 'require-approval' } : config;
+        const lookupPolicy = (invocation) => resolveToolApprovalPolicy(invocation, resolverConfig, { harness: MASTRA_BUILT_IN_TOOL_POLICIES }).decision;
+        return { lookupPolicy, batchApprovals };
+    }
     /**
      * Maps an SDK `MessagePart[]` into the single AI SDK v5 user `ModelMessage` that
      * `agent.stream()` accepts.
@@ -1322,13 +1390,21 @@ export class MastraHarness {
     }
     async stream(agentId, threadId, message, options) {
         const agentState = this.getAgentStateOrThrow(agentId);
-        // Resolve the union-typed `requireToolApproval` to one of:
-        //   undefined → no gating (consumer tools still park via the bridge
-        //               execute handler — issue #529 step 2c Path A)
-        //   'serial'  → one approval per stream
-        //   'batch'   → parallel `tool_use` blocks surface all approvals
-        //               on one stream (#447)
-        const approvalMode = resolveToolApprovalMode(options?.requireToolApproval);
+        // 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);
+        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
         // route settle calls and accumulate listeners. Mode-flip safe: the
@@ -1366,10 +1442,13 @@ export class MastraHarness {
             requestContext: this.buildRequestContext(agentId, threadId),
             maxSteps: options?.maxSteps ?? DEFAULT_MAX_STEPS,
             abortSignal: options?.abortSignal,
-            // Only pass `requireToolApproval` when the consumer actually
-            // set it — Mastra is sensitive to the field's presence vs.
-            // explicit `false`.
-            ...(approvalMode !== undefined ? { requireToolApproval: true } : {}),
+            // Pass `requireToolApproval: true` to Mastra iff the gate is active
+            // so Mastra suspends every non-consumer tool with a
+            // `tool-call-approval` chunk and the coordinator can consult the
+            // policy resolver per tool. When inactive, omit it — Mastra is
+            // sensitive to the field's presence vs. explicit `false`, and
+            // omitting preserves today's no-suspend path.
+            ...(gatingActive ? { requireToolApproval: true } : {}),
         });
         // Issue #529 step 2c: every stream allocates a coordinator,
         // regardless of approval mode. The coordinator's pump loop owns
@@ -1381,9 +1460,11 @@ export class MastraHarness {
             memory: { thread: threadId, resource: this.agentResourceId(agentId) },
             requestContext: this.buildRequestContext(agentId, threadId),
             toolApprovalTimeoutMs: this.toolApprovalTimeoutMs,
-            mode: approvalMode,
+            ...(lookupPolicy ? { lookupPolicy } : {}),
+            batchApprovals,
             consumerToolNames: agentState.consumerToolNames,
             lookupMcpToolMetadata: (name) => lookupMcpToolMetadata(agentState.mcpServers, name),
+            skillBridgeToolNames: activeSkillBridgeToolNames(agentState),
             logBus: this.buses.getLogBus(),
         });
         agentState.coordinators.set(threadId, coordinator);

package/dist/mastra-tool-mapper.js

@@ -43,6 +43,17 @@ export function mapToolDefinitionsToMastraTools(tools, parkerLookup) {
             // JSDoc. 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
+            // hardcoded, never policy-derived. The coordinator's policy
+            // resolver is the SECONDARY gate, and the two must AGREE: the
+            // coordinator short-circuits consumer tools (by name, via
+            // `consumerToolNames`) to a silent auto-approve BEFORE it consults
+            // `resolveToolApprovalPolicy`, so a stray `toolPolicies` rule that
+            // happened to match a consumer tool can never flip it to
+            // `require-approval` / `deny`. Consumer-tool execution stays the
+            // consumer's responsibility via `submitToolResult`.
             requireApproval: false,
             execute: async (_inputData, context) => {
                 const toolCallId = readToolCallId(context);

package/dist/skill-bridge.d.ts

@@ -0,0 +1,32 @@
+import { SKILL_BRIDGE_SERVER_ID } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Stable harness identity for the capability-discovery meta-tools (#606).
+ *
+ * Mastra's `ToolSearchProcessor` injects `search_tools` / `load_tool` and its
+ * `SkillSearchProcessor` injects `search_skills` / `load_skill` as flat tools
+ * with no MCP `serverName`. Claude exposes the same four through its in-process
+ * `skill_bridge` MCP server, so the SDK's `mcp:skill_bridge:*` rules in
+ * `BUILT_IN_TOOL_POLICIES` match there but silently miss on Mastra.
+ *
+ * The harness closes that gap by stamping `serverName = SKILL_BRIDGE_SERVER_ID`
+ * onto these tools at the approval boundary — but ONLY for leaves whose
+ * originating processor is actually active on the turn (see
+ * {@link MastraApprovalCoordinator}'s `skillBridgeToolNames`). The identity is
+ * therefore anchored on `(serverId, leaf)` against tools the harness itself
+ * injected, never on the bare leaf name alone. A consumer-declared tool named
+ * `load_skill` (with no `skillSearch` configured) never enters the active set,
+ * so it cannot inherit the auto-approval exemption — the security hole that
+ * sank the host-side bare-leaf workaround in AFV PR #2455.
+ */
+/** Leaf names injected by Mastra's `ToolSearchProcessor` (no `autoLoad`). */
+export declare const TOOL_SEARCH_META_TOOL_NAMES: readonly ["search_tools", "load_tool"];
+/** Leaf names injected by Mastra's `SkillSearchProcessor`. */
+export declare const SKILL_SEARCH_META_TOOL_NAMES: readonly ["search_skills", "load_skill"];
+/**
+ * Every capability-discovery meta-tool leaf the harness gives the
+ * `skill_bridge` identity. Kept in lockstep with the SDK's `mcp:skill_bridge:*`
+ * rules in `BUILT_IN_TOOL_POLICIES` — a drift test in
+ * `test/skill-bridge.test.ts` asserts each name here has a matching SDK rule.
+ */
+export declare const SKILL_BRIDGE_META_TOOL_NAMES: readonly ["search_tools", "load_tool", "search_skills", "load_skill"];
+export { SKILL_BRIDGE_SERVER_ID };

package/dist/skill-bridge.js

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import { SKILL_BRIDGE_SERVER_ID } from '@salesforce/sfdx-agent-sdk';
+/**
+ * Stable harness identity for the capability-discovery meta-tools (#606).
+ *
+ * Mastra's `ToolSearchProcessor` injects `search_tools` / `load_tool` and its
+ * `SkillSearchProcessor` injects `search_skills` / `load_skill` as flat tools
+ * with no MCP `serverName`. Claude exposes the same four through its in-process
+ * `skill_bridge` MCP server, so the SDK's `mcp:skill_bridge:*` rules in
+ * `BUILT_IN_TOOL_POLICIES` match there but silently miss on Mastra.
+ *
+ * The harness closes that gap by stamping `serverName = SKILL_BRIDGE_SERVER_ID`
+ * onto these tools at the approval boundary — but ONLY for leaves whose
+ * originating processor is actually active on the turn (see
+ * {@link MastraApprovalCoordinator}'s `skillBridgeToolNames`). The identity is
+ * therefore anchored on `(serverId, leaf)` against tools the harness itself
+ * injected, never on the bare leaf name alone. A consumer-declared tool named
+ * `load_skill` (with no `skillSearch` configured) never enters the active set,
+ * so it cannot inherit the auto-approval exemption — the security hole that
+ * sank the host-side bare-leaf workaround in AFV PR #2455.
+ */
+/** Leaf names injected by Mastra's `ToolSearchProcessor` (no `autoLoad`). */
+export const TOOL_SEARCH_META_TOOL_NAMES = ['search_tools', 'load_tool'];
+/** Leaf names injected by Mastra's `SkillSearchProcessor`. */
+export const SKILL_SEARCH_META_TOOL_NAMES = ['search_skills', 'load_skill'];
+/**
+ * Every capability-discovery meta-tool leaf the harness gives the
+ * `skill_bridge` identity. Kept in lockstep with the SDK's `mcp:skill_bridge:*`
+ * rules in `BUILT_IN_TOOL_POLICIES` — a drift test in
+ * `test/skill-bridge.test.ts` asserts each name here has a matching SDK rule.
+ */
+export const SKILL_BRIDGE_META_TOOL_NAMES = [...TOOL_SEARCH_META_TOOL_NAMES, ...SKILL_SEARCH_META_TOOL_NAMES];
+export { SKILL_BRIDGE_SERVER_ID };
+//# sourceMappingURL=skill-bridge.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-harness-mastra",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Mastra-backed AgentHarness implementation for @salesforce/sfdx-agent-sdk",
   "type": "module",
   "main": "dist/index.js",
@@ -40,11 +40,11 @@
     "openai": "^6.0.0"
   },
   "peerDependencies": {
-    "@salesforce/sfdx-agent-sdk": "0.25.0"
+    "@salesforce/sfdx-agent-sdk": "0.26.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-sdk": "0.25.0",
+    "@salesforce/sfdx-agent-sdk": "0.26.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.20",