@salesforce/sfdx-agent-sdk 0.24.0 → 0.26.0

package/dist/chat-session.js

@@ -31,6 +31,16 @@ export class DefaultChatSession {
      * are stale and should not bleed into the next turn).
      */
     toolStartMs = new Map();
+    /**
+     * Tracks the `(toolName, serverName?)` of every tool call currently awaiting
+     * approval, keyed by `toolCallId`. Populated when a `tool-approval-request`
+     * ChatEvent flows through {@link wrapEventStream}; read by
+     * {@link approveToolCall} / {@link declineToolCall} when `remember: true` so
+     * the appended policy rule carries the right matcher. An entry is removed
+     * once its approval settles (or the turn ends), so a `remember` settle for an
+     * unknown / already-settled `toolCallId` throws `TOOL_CALL_NOT_FOUND`.
+     */
+    pendingApprovalsByToolCallId = new Map();
     /**
      * Live getter for the agent's currently-bound model's context window.
      * Called by {@link getContextUsage} so reads reflect the model in
@@ -38,6 +48,14 @@ export class DefaultChatSession {
      * (an `Agent.updateAgentConfig()` swap can change it mid-life).
      */
     getContextWindow;
+    /**
+     * Persists a `'remember'` policy rule on behalf of a settle call with
+     * `{ remember: true }`. Injected by {@link DefaultAgent}; `undefined` only
+     * in unit tests that construct a session without the persister, in which
+     * case a `remember: true` settle is treated as a one-shot (no write). See
+     * {@link RememberedRulePersister}.
+     */
+    persistRememberedRule;
     /**
      * Last per-step usage reading observed on this session. Initialized
      * to `{}` (every token field undefined) so {@link getContextUsage}
@@ -57,16 +75,17 @@ export class DefaultChatSession {
      * @param parent - Parent agent's buses; this session forwards its events upward into them.
      * @param getContextWindow - Live getter for the agent's currently-bound model's `contextWindow`.
      *   Called by `getContextUsage()` so reads stay correct across `Agent.updateAgentConfig()` model swaps.
-     * @param clock - Source of monotonic timestamps for telemetry events. Defaults to `RealClock`.
-     * @param idGenerator - Source of message ids for `addContext()`. Defaults to `UUIDGenerator`.
+     * @param deps - Optional injected dependencies ({@link ChatSessionDeps}): `clock`, `idGenerator`,
+     *   `persistRememberedRule`. Each has a production default; tests override only what they need.
      */
-    constructor(harness, agentId, threadId, inbound, parent, getContextWindow, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, threadId, inbound, parent, getContextWindow, deps = {}) {
         this.harness = harness;
         this.agentId = agentId;
         this.threadId = threadId;
         this.getContextWindow = getContextWindow;
-        this.clock = clock;
-        this.idGenerator = idGenerator;
+        this.clock = deps.clock ?? new RealClock();
+        this.idGenerator = deps.idGenerator ?? new UUIDGenerator();
+        this.persistRememberedRule = deps.persistRememberedRule;
         this.inboundUnsubs = [inbound.telemetry.forwardTo(this.telemetryBus), inbound.log.forwardTo(this.logBus)];
         this.parentUnsubs = [this.telemetryBus.forwardTo(parent.telemetry), this.logBus.forwardTo(parent.log)];
     }
@@ -185,7 +204,7 @@ export class DefaultChatSession {
                     // would lose tracking for tool-calls whose tool-result lands on a later
                     // continuation stream. Only terminal `FinishReason`s end the turn.
                     if (event.finishReason !== 'tool-calls') {
-                        this.toolStartMs.clear();
+                        this.clearPerTurnTracking();
                     }
                 }
                 if (event.type === 'error')
@@ -204,9 +223,8 @@ export class DefaultChatSession {
             this.chatEventBus.emit(finishEvent);
             yield finishEvent;
             // Match the natural-finish branch: every terminal `finish` clears the
-            // tool-start tracking map so a stale entry can't pair with an unrelated
-            // tool-result on the next turn.
-            this.toolStartMs.clear();
+            // per-turn tracking maps.
+            this.clearPerTurnTracking();
         }
         const finishedAt = this.clock.now();
         const durationMs = finishedAt.getTime() - startedAt.getTime();
@@ -242,13 +260,17 @@ export class DefaultChatSession {
      *   `tool-approval-requested` by `toolCallId` and observe the failure on the chat-stream contract.
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
-     * - The `options.remember` flag is consumer-only metadata — the harness does not use it.
+     * - WHEN `options.remember` is `true`, MUST append an `'allow'` `'remember'` rule to the agent's
+     *   `toolPolicies` and persist it via the injected persister BEFORE delegating the settle to the
+     *   harness, so a persistence failure surfaces as the settle's rejection and the decision is durable
+     *   before the tool runs. Throws `TOOL_CALL_NOT_FOUND` if `toolCallId` has no pending approval.
      */
-    async approveToolCall(toolCallId, _options) {
+    async approveToolCall(toolCallId, options) {
         this.assertNotDisposed();
         // issue #529 contract change: see `submitToolResult` for the rationale.
         // Settle is a control message on the existing turn; events flow on
         // the chat()-returned stream.
+        const policyWritten = await this.maybePersistRememberedRule(toolCallId, 'allow', options?.remember === true);
         try {
             await this.harness.approveToolCall(this.agentId, this.threadId, toolCallId);
         }
@@ -256,7 +278,8 @@ export class DefaultChatSession {
             this.notifySettleRejection(err);
             throw err;
         }
-        this.emitToolApprovalResolved(toolCallId, true);
+        this.pendingApprovalsByToolCallId.delete(toolCallId);
+        this.emitToolApprovalResolved(toolCallId, true, policyWritten);
     }
     /**
      * @requirements
@@ -268,10 +291,13 @@ export class DefaultChatSession {
      *   and intentionally skip approval-resolved emission.
      * - MUST notify listeners with `ErrorEvent` + `FinishEvent` and re-throw if the harness throws
      *   before returning a stream result.
+     * - WHEN `options.remember` is `true`, MUST append a `'deny'` `'remember'` rule and persist it
+     *   BEFORE delegating the settle to the harness — symmetric with {@link approveToolCall}.
      */
-    async declineToolCall(toolCallId) {
+    async declineToolCall(toolCallId, options) {
         this.assertNotDisposed();
         // issue #529 contract change: see `submitToolResult` for the rationale.
+        const policyWritten = await this.maybePersistRememberedRule(toolCallId, 'deny', options?.remember === true);
         try {
             await this.harness.declineToolCall(this.agentId, this.threadId, toolCallId);
         }
@@ -279,7 +305,8 @@ export class DefaultChatSession {
             this.notifySettleRejection(err);
             throw err;
         }
-        this.emitToolApprovalResolved(toolCallId, false);
+        this.pendingApprovalsByToolCallId.delete(toolCallId);
+        this.emitToolApprovalResolved(toolCallId, false, policyWritten);
     }
     /**
      * @requirements
@@ -408,7 +435,7 @@ export class DefaultChatSession {
         this.logBus.dispose();
         this.disposed = true;
     }
-    emitToolApprovalResolved(toolCallId, approved) {
+    emitToolApprovalResolved(toolCallId, approved, policyWritten) {
         this.telemetryBus.emit({
             type: 'tool-approval-resolved',
             timestamp: this.clock.now(),
@@ -416,8 +443,22 @@ export class DefaultChatSession {
             threadId: this.threadId,
             toolCallId,
             approved,
+            ...(policyWritten ? { policyWritten: true } : {}),
         });
     }
+    /**
+     * Clears the per-turn tracking maps at a terminal `finish`. Both maps are
+     * scoped to one logical chat turn: `toolStartMs` pairs `tool-call` with
+     * `tool-result` for `tool-execution-completed.durationMs`, and
+     * `pendingApprovalsByToolCallId` lets a `remember` settle build the right
+     * matcher. A stale entry surviving into the next turn would mispair a
+     * duration or remember the wrong tool, so the two clears must always fire
+     * together — hence one helper rather than two call sites.
+     */
+    clearPerTurnTracking() {
+        this.toolStartMs.clear();
+        this.pendingApprovalsByToolCallId.clear();
+    }
     /**
      * Derives `tool-execution-*` and `tool-approval-requested` telemetry from `ChatEvent`s as
      * they pass through the stream wrapper. Centralizing the derivation here keeps every harness
@@ -466,6 +507,15 @@ export class DefaultChatSession {
             });
         }
         else if (event.type === 'tool-approval-request') {
+            // Record the (toolName, serverName?) so a later settle with
+            // `remember: true` can build the right matcher for the persisted
+            // rule. Drained on settle, and on every terminal `finish` (see
+            // `wrapEventStream`) so a stale entry can't be remembered after the
+            // turn that requested it has ended.
+            this.pendingApprovalsByToolCallId.set(event.toolCall.toolCallId, {
+                toolName: event.toolCall.toolName,
+                ...(event.serverName ? { serverName: event.serverName } : {}),
+            });
             this.telemetryBus.emit({
                 type: 'tool-approval-requested',
                 timestamp: this.clock.now(),
@@ -478,6 +528,34 @@ export class DefaultChatSession {
             });
         }
     }
+    /**
+     * If `remember` is requested, builds the matcher for the pending approval
+     * referenced by `toolCallId` and persists a `'remember'` rule with the
+     * given `decision` via the injected {@link RememberedRulePersister}, BEFORE
+     * the caller settles with the harness. Returns whether a rule was written.
+     *
+     * - A `remember` settle for a `toolCallId` with no pending approval throws
+     *   `TOOL_CALL_NOT_FOUND` — the same outcome as settling an unknown id, and
+     *   the correct outcome for a consumer-executed tool (never gated, so never
+     *   in the pending map).
+     * - When no persister was injected (unit-test construction), `remember`
+     *   degrades to a one-shot settle: no write, returns `false`.
+     */
+    async maybePersistRememberedRule(toolCallId, decision, remember) {
+        if (!remember)
+            return false;
+        const ref = this.pendingApprovalsByToolCallId.get(toolCallId);
+        if (!ref) {
+            throw new AgentSDKError(`No pending tool approval found with id: "${toolCallId}"`, AgentSDKErrorType.TOOL_CALL_NOT_FOUND);
+        }
+        if (!this.persistRememberedRule)
+            return false;
+        const matcher = ref.serverName !== undefined
+            ? { type: 'mcp', serverName: ref.serverName, toolName: ref.toolName }
+            : { type: 'builtin', name: ref.toolName };
+        await this.persistRememberedRule({ matcher, decision, source: 'remember' });
+        return true;
+    }
     /**
      * Emits a `chat-stream-started` telemetry event and returns the `startedAt` timestamp the
      * caller threads through to the stream wrapper / pre-stream error notifier so terminal

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

@@ -1,4 +1,4 @@
-import type { ToolDefinition } from '../types/tools.js';
+import type { Decision, ToolDefinition, ToolPolicyRule } from '../types/tools.js';
 import type { MCPConfiguration } from '../mcp-config.js';
 import type { JSONWebToken } from '@salesforce/agentic-common';
 import type { Model, ModelName } from '../models/index.js';
@@ -59,6 +59,39 @@ export type AgentConfig = {
      * opaquely.
      */
     rules?: string[];
+    /**
+     * Ordered list of tool-approval rules. For each harness-executed tool call,
+     * `resolveToolApprovalPolicy` walks this list (concatenated after the SDK's
+     * `BUILT_IN_TOOL_POLICIES`, the harness's built-in array, and any harness
+     * factory rules) and returns a {@link Decision} via **cross-tier deny-wins /
+     * within-tier last-wins** precedence: any `'deny'` in any tier wins;
+     * otherwise the last matching non-deny rule decides. A later consumer rule
+     * beats an earlier one, and a `'remember'` rule appended by
+     * `approveToolCall(id, { remember: true })` beats an earlier built-in
+     * `'require-approval'` of the same matcher.
+     *
+     * Author rules with the structured {@link ToolPolicyRule} shape, or the
+     * `definePolicy({ Bash: 'deny', 'mcp:sfdx': 'require-approval' })` helper for
+     * the common cases. Per-MCP-server policy is expressed here via
+     * `{ matcher: { type: 'mcp', serverName } }` rules — `MCPServerConfig`
+     * carries no policy fields.
+     *
+     * Has no effect until a harness wires the resolver into its gate site
+     * (Phase 2). Until then, harnesses gate via the deprecated
+     * {@link StreamOptions.requireToolApproval}.
+     */
+    toolPolicies?: ToolPolicyRule[];
+    /**
+     * Fallback decision for tool invocations that match no rule in
+     * {@link toolPolicies} (or any built-in / harness tier). Defaults to
+     * `'allow'` for back-compat ("no policy ⇒ no gating," matching today's
+     * behavior when `requireToolApproval` is unset).
+     *
+     * Set to `'require-approval'` for a fail-closed posture — recommended for
+     * tenants whose MCP catalog includes un-annotated servers, since
+     * annotation-matcher rules don't fire on tools with no annotations.
+     */
+    defaultToolDecision?: Decision;
 };
 /**
  * Harness-facing configuration for creating/updating an agent.
@@ -102,6 +135,11 @@ export declare function toHarnessConfig(config: AgentConfig, orgJwt?: JSONWebTok
  * surface on the same stream so the consumer can render them as a
  * batch approval card). See `requireToolApproval` for the safety
  * note on choosing `batch`.
+ *
+ * @deprecated Tool-approval gating is moving to per-tool policy on
+ *   {@link AgentConfig.toolPolicies}, resolved by `resolveToolApprovalPolicy`.
+ *   The serial-vs-batch UX axis survives as {@link StreamOptions.batchApprovals}.
+ *   Removed in a future major once harnesses and consumers have migrated.
  */
 export type ToolApprovalMode = 'serial' | 'batch';
 /**
@@ -115,6 +153,11 @@ export type ToolApprovalMode = 'serial' | 'batch';
  * - `true` → `'serial'` (back-compat shorthand for the original `boolean` shape).
  * - `'serial'` → `'serial'` (explicit, equivalent to `true`).
  * - `'batch'` → `'batch'`.
+ *
+ * @deprecated Superseded by per-tool policy on {@link AgentConfig.toolPolicies}
+ *   (resolved by `resolveToolApprovalPolicy`) plus {@link StreamOptions.batchApprovals}
+ *   for the UX axis. Kept functional for one release so harness PRs can migrate
+ *   independently; removed in a future major.
  */
 export declare function resolveToolApprovalMode(requireToolApproval: boolean | ToolApprovalMode | undefined): ToolApprovalMode | undefined;
 /**
@@ -152,8 +195,33 @@ export type StreamOptions = {
      * Does not affect consumer-executed tools (those defined via
      * `AgentConfig.tools` without an execute handler) — the consumer
      * already controls execution for those via `submitToolResult()`.
+     *
+     * @deprecated Per-call all-or-nothing gating is superseded by per-tool
+     *   policy on {@link AgentConfig.toolPolicies}. The serial-vs-batch UX axis
+     *   moved to {@link batchApprovals}. Kept functional for one release so
+     *   harness PRs can migrate independently; removed in a future major. New
+     *   code should configure `AgentConfig.toolPolicies` and, if a batch UX is
+     *   wanted, set `batchApprovals: true`.
      */
     requireToolApproval?: boolean | ToolApprovalMode;
+    /**
+     * When `true`, parallel approval-requests within a turn (the model emits
+     * multiple `tool_use` blocks in one batch, more than one of which resolves
+     * to `'require-approval'`) surface on the same stream so the consumer can
+     * render a batch approval card. The consumer's iterator MUST drain to
+     * natural park before settling.
+     *
+     * Defaults to `false` (serial: one approval-request at a time; the consumer
+     * settles before the next surfaces). Identical to pre-#447 behavior under
+     * `requireToolApproval: true`.
+     *
+     * Has no effect when no tool in the turn resolves to `'require-approval'` —
+     * there is nothing to batch. This is the self-documenting replacement for
+     * the UX half of the deprecated {@link requireToolApproval} enum; the
+     * "gating on/off" half moves to per-tool policy on
+     * {@link AgentConfig.toolPolicies}.
+     */
+    batchApprovals?: boolean;
     /**
      * Maximum number of LLM call steps the agent may take per `stream()` invocation.
      * Each step is one LLM call (which may produce text, tool calls, or both).

package/dist/harness/harness-config.js

@@ -35,6 +35,11 @@ export function toHarnessConfig(config, orgJwt) {
  * - `true` → `'serial'` (back-compat shorthand for the original `boolean` shape).
  * - `'serial'` → `'serial'` (explicit, equivalent to `true`).
  * - `'batch'` → `'batch'`.
+ *
+ * @deprecated Superseded by per-tool policy on {@link AgentConfig.toolPolicies}
+ *   (resolved by `resolveToolApprovalPolicy`) plus {@link StreamOptions.batchApprovals}
+ *   for the UX axis. Kept functional for one release so harness PRs can migrate
+ *   independently; removed in a future major.
  */
 export function resolveToolApprovalMode(requireToolApproval) {
     if (requireToolApproval === undefined || requireToolApproval === false)

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export type { Message, MessagePart, ImagePart, FilePart } from './types/messages.js';
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolCallDeltaEvent, ToolApprovalRequestEvent, ToolResultEvent, ToolProgressEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
-export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools.js';
+export type { Decision, ToolDefinition, ToolCallInfo, ToolMatcher, ToolPolicyRule, ToolResultInfo, } from './types/tools.js';
+export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
+export type { ResolverResult, ResolverTiers, ToolInvocation } from './policy-resolver.js';
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
 export type { AgentHooks, HooksForAgent, ToolResultRedactor, ToolResultRedactionInput, ToolResultRedactionResult, } from './types/redaction.js';
 export type { AgentConfig, HarnessAgentConfig, StreamOptions, ToolApprovalMode } from './harness/harness-config.js';
@@ -21,7 +23,7 @@ export type { LlmRequestEvent, LlmResponseEvent, WireCommunicationEvent, WireCom
 export { WireCommunicationFileWriter, type WireCommunicationEmitter, type WireCommunicationFileWriterOptions, } from './wire-communication-file-writer.js';
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './harness/index.js';
 export { AgentSDKError, AgentSDKErrorType } from './errors.js';
-export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
+export type { AgentCreatedEvent, AgentDestroyedEvent, ChatStreamCompletedEvent, ChatStreamErrorEvent, ChatStreamStartedEvent, ChatStreamTrigger, McpServerDiscoveryCompletedEvent, McpServerDiscoveryFailedEvent, McpServerDiscoveryStartedEvent, McpServerStatusChangedEvent, SessionCreatedEvent, SessionDestroyedEvent, TelemetryEvent, TelemetryEventCallback, ToolApprovalPolicyResolvedEvent, ToolApprovalRequestedEvent, ToolApprovalResolvedEvent, ToolExecutionCompletedEvent, ToolExecutionStartedEvent, } from './types/telemetry-events.js';
 export type { LogLevel, LogRecord, Unsubscribe } from '@salesforce/agentic-common';
 export { resolveMcpServerHeaders } from './mcp-auth.js';
 export type { OrgConnection, OrgConnectionFactory } from '@salesforce/agentic-common';

package/dist/index.js

@@ -2,6 +2,12 @@
  * Copyright 2026, Salesforce, Inc. All rights reserved.
  * See LICENSE.txt for license terms.
  */
+// ── Tool-approval policy ─────────────────────────────────────────────
+// The resolver, the SDK-shipped cross-harness rule set, the matcher, the
+// ergonomics helper, and the well-known skill-bridge serverId. Harnesses wire
+// `resolveToolApprovalPolicy` into their gate sites (Phase 2); consumers author
+// `AgentConfig.toolPolicies` (directly or via `definePolicy`).
+export { BUILT_IN_TOOL_POLICIES, SKILL_BRIDGE_SERVER_ID, definePolicy, matcherMatches, resolveToolApprovalPolicy, } from './policy-resolver.js';
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel, Models, validateMultimodalFiles } from './models/index.js';

package/dist/policy-resolver.d.ts

@@ -0,0 +1,126 @@
+import type { McpToolAnnotations } from './mcp-config.js';
+import type { AgentConfig } from './harness/harness-config.js';
+import type { Decision, ToolMatcher, ToolPolicyRule } from './types/tools.js';
+/**
+ * Well-known MCP server identity for the capability-discovery meta-tools
+ * (`search_tools`, `load_tool`, `search_skills`, `load_skill`). Both harnesses
+ * expose these tools through this serverId — Claude via its in-process
+ * skill-bridge MCP server, Mastra gains it as a Phase 2a prerequisite
+ * ([#606](https://github.com/forcedotcom/agentic-dx/issues/606)). The
+ * `mcp:skill_bridge:*` rules in {@link BUILT_IN_TOOL_POLICIES} anchor on this
+ * constant so operator-side rule authors and harness implementations share one
+ * identity rather than each hard-coding the string.
+ */
+export declare const SKILL_BRIDGE_SERVER_ID = "skill_bridge";
+/**
+ * A single tool invocation the resolver decides on. The harness strips its own
+ * tool-name namespacing before constructing this — `serverName` / `toolName`
+ * are the un-namespaced MCP pair, `toolName` alone is the built-in name.
+ */
+export type ToolInvocation = {
+    /** The bare tool name (un-namespaced for MCP tools). */
+    toolName: string;
+    /** Originating MCP server name; `undefined` for built-in / consumer tools. */
+    serverName?: string;
+    /** Discovered MCP annotations, when the server declared them. */
+    annotations?: McpToolAnnotations;
+};
+/**
+ * Optional rule tiers supplied by the harness layer.
+ *
+ * The shape extends additively when future tiers ship: a future
+ * `tiers.managed` slot will sit between consumer rules and `'remember'` rules
+ * without reshaping this type or the resolver signature.
+ */
+export type ResolverTiers = {
+    /** Harness-shipped built-in rules (e.g. `MASTRA_BUILT_IN_TOOL_POLICIES`). */
+    harness?: ReadonlyArray<ToolPolicyRule>;
+    /**
+     * Synthetic rules from harness factory inputs during a deprecation window.
+     * Today: Claude's `bypassApprovalTools` translation. Empty after Phase 4.
+     */
+    factory?: ReadonlyArray<ToolPolicyRule>;
+};
+/** The outcome of resolving a tool invocation against the concatenated rule list. */
+export type ResolverResult = {
+    /** The resolved decision. */
+    decision: Decision;
+    /**
+     * The rule that drove the decision: the last `'deny'` when the decision is
+     * `'deny'`, otherwise the last matching non-deny rule. `undefined` when no
+     * rule matched and the decision came from `defaultToolDecision`.
+     */
+    matchedRule?: ToolPolicyRule;
+    /** Every matching rule, in resolved-list order. Debug verbosity for sinks. */
+    allMatchedRules?: ToolPolicyRule[];
+};
+/**
+ * Cross-harness tool-approval rules shipped with the SDK. Frozen — adding
+ * entries is a soft contract change consumers will have noticed; removing or
+ * modifying an entry is a breaking change.
+ *
+ * Per the R4 layering invariant, this array holds **only harness-agnostic
+ * rules** — rules meaningful regardless of which harness is loaded. Harness-
+ * specific built-ins (Claude's `Bash`, Mastra's `updateWorkingMemory`) live in
+ * the respective harness package's `<HARNESS>_BUILT_IN_TOOL_POLICIES` array.
+ */
+export declare const BUILT_IN_TOOL_POLICIES: ReadonlyArray<ToolPolicyRule>;
+/**
+ * Tests a single matcher against a tool invocation. Pure; one switch on
+ * `matcher.type`.
+ *
+ * - `'builtin'` matches when the invocation has no `serverName` and its
+ *   `toolName` equals the matcher name. (MCP tools always carry a `serverName`,
+ *   so a built-in matcher never matches one even if the bare names collide.)
+ * - `'mcp'` matches an invocation that has a `serverName`, optionally narrowed
+ *   by the matcher's `serverName` / `toolName` (each `undefined` field is a
+ *   wildcard).
+ * - `'mcp-annotation'` matches an MCP invocation whose `annotations` carry
+ *   every hint set on the matcher. An invocation with no annotations never
+ *   matches.
+ */
+export declare function matcherMatches(matcher: ToolMatcher, invocation: ToolInvocation): boolean;
+/**
+ * Resolves the approval decision for a tool invocation.
+ *
+ * Concatenates the four rule tiers in precedence order
+ * `[...BUILT_IN_TOOL_POLICIES, ...tiers.harness, ...tiers.factory, ...agentConfig.toolPolicies]`
+ * and applies **cross-tier deny-wins / within-tier last-wins**:
+ *
+ * - If any matching rule is a `'deny'`, the decision is `'deny'` and
+ *   `matchedRule` is the **last** `'deny'` (closest-to-consumer — most useful
+ *   for "why was my tool blocked" debugging).
+ * - Otherwise, the **last** matching non-deny rule decides.
+ * - If nothing matched, the decision is `agentConfig.defaultToolDecision`, or
+ *   `'allow'` when that is unset (back-compat: "no policy ⇒ no gating").
+ *
+ * **Pure function** — no I/O, no logging, no side effects. The unmatched-rule
+ * `LogBus.warn` is the harness's responsibility (after observing
+ * `matchedRule === undefined`), keeping the resolver dependency-free and
+ * trivially testable.
+ */
+export declare function resolveToolApprovalPolicy(invocation: ToolInvocation, agentConfig: AgentConfig, tiers?: ResolverTiers): ResolverResult;
+/**
+ * Compresses the common policy cases into a `ToolPolicyRule[]` with
+ * `source: 'agent-config'`. Each key is a tool selector, each value its
+ * {@link Decision}:
+ *
+ * ```ts
+ * definePolicy({
+ *     Bash: 'deny',                  // builtin matcher
+ *     'mcp:sfdx': 'require-approval', // every tool from the 'sfdx' MCP server
+ *     'mcp:sfdx/list_orgs': 'allow',  // one tool from the 'sfdx' server
+ * });
+ * ```
+ *
+ * Key grammar:
+ * - `'<name>'` → `{ type: 'builtin', name }`.
+ * - `'mcp:<server>'` → `{ type: 'mcp', serverName }`.
+ * - `'mcp:<server>/<tool>'` → `{ type: 'mcp', serverName, toolName }`.
+ *
+ * Consumers needing `mcp-annotation` matchers, the bare `{ type: 'mcp' }`
+ * server-agnostic wildcard, or any tool name containing `/` must author the
+ * structured {@link ToolPolicyRule} form directly — the shorthand intentionally
+ * covers only the simple `builtin` and `mcp:server[/tool]` cases.
+ */
+export declare function definePolicy(spec: Record<string, Decision>): ToolPolicyRule[];

package/dist/policy-resolver.js

@@ -0,0 +1,175 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Well-known MCP server identity for the capability-discovery meta-tools
+ * (`search_tools`, `load_tool`, `search_skills`, `load_skill`). Both harnesses
+ * expose these tools through this serverId — Claude via its in-process
+ * skill-bridge MCP server, Mastra gains it as a Phase 2a prerequisite
+ * ([#606](https://github.com/forcedotcom/agentic-dx/issues/606)). The
+ * `mcp:skill_bridge:*` rules in {@link BUILT_IN_TOOL_POLICIES} anchor on this
+ * constant so operator-side rule authors and harness implementations share one
+ * identity rather than each hard-coding the string.
+ */
+export const SKILL_BRIDGE_SERVER_ID = 'skill_bridge';
+/**
+ * Cross-harness tool-approval rules shipped with the SDK. Frozen — adding
+ * entries is a soft contract change consumers will have noticed; removing or
+ * modifying an entry is a breaking change.
+ *
+ * Per the R4 layering invariant, this array holds **only harness-agnostic
+ * rules** — rules meaningful regardless of which harness is loaded. Harness-
+ * specific built-ins (Claude's `Bash`, Mastra's `updateWorkingMemory`) live in
+ * the respective harness package's `<HARNESS>_BUILT_IN_TOOL_POLICIES` array.
+ */
+export const BUILT_IN_TOOL_POLICIES = Object.freeze([
+    // MCP annotation-driven defaults. Under within-tier last-wins, a consumer
+    // rule appended later beats these — so a "remember: allow" on a
+    // destructiveHint tool actually takes effect.
+    { matcher: { type: 'mcp-annotation', destructiveHint: true }, decision: 'require-approval', source: 'built-in' },
+    { matcher: { type: 'mcp-annotation', readOnlyHint: true }, decision: 'allow', source: 'built-in' },
+    // Capability-discovery meta-tools — exposed by both harnesses through the
+    // well-known SKILL_BRIDGE_SERVER_ID MCP serverId (Mastra gains this
+    // identity per #606). Closes the consumer pain that motivated AFV PR #2455.
+    {
+        matcher: { type: 'mcp', serverName: SKILL_BRIDGE_SERVER_ID, toolName: 'search_tools' },
+        decision: 'allow',
+        source: 'built-in',
+    },
+    {
+        matcher: { type: 'mcp', serverName: SKILL_BRIDGE_SERVER_ID, toolName: 'load_tool' },
+        decision: 'allow',
+        source: 'built-in',
+    },
+    {
+        matcher: { type: 'mcp', serverName: SKILL_BRIDGE_SERVER_ID, toolName: 'search_skills' },
+        decision: 'allow',
+        source: 'built-in',
+    },
+    {
+        matcher: { type: 'mcp', serverName: SKILL_BRIDGE_SERVER_ID, toolName: 'load_skill' },
+        decision: 'allow',
+        source: 'built-in',
+    },
+]);
+/**
+ * Tests a single matcher against a tool invocation. Pure; one switch on
+ * `matcher.type`.
+ *
+ * - `'builtin'` matches when the invocation has no `serverName` and its
+ *   `toolName` equals the matcher name. (MCP tools always carry a `serverName`,
+ *   so a built-in matcher never matches one even if the bare names collide.)
+ * - `'mcp'` matches an invocation that has a `serverName`, optionally narrowed
+ *   by the matcher's `serverName` / `toolName` (each `undefined` field is a
+ *   wildcard).
+ * - `'mcp-annotation'` matches an MCP invocation whose `annotations` carry
+ *   every hint set on the matcher. An invocation with no annotations never
+ *   matches.
+ */
+export function matcherMatches(matcher, invocation) {
+    switch (matcher.type) {
+        case 'builtin':
+            return invocation.serverName === undefined && invocation.toolName === matcher.name;
+        case 'mcp':
+            return (invocation.serverName !== undefined &&
+                (matcher.serverName === undefined || invocation.serverName === matcher.serverName) &&
+                (matcher.toolName === undefined || invocation.toolName === matcher.toolName));
+        case 'mcp-annotation': {
+            if (invocation.serverName === undefined || invocation.annotations === undefined)
+                return false;
+            const { readOnlyHint, destructiveHint } = matcher;
+            if (readOnlyHint !== undefined && invocation.annotations.readOnlyHint !== readOnlyHint)
+                return false;
+            if (destructiveHint !== undefined && invocation.annotations.destructiveHint !== destructiveHint)
+                return false;
+            // At least one hint must be set on the matcher for it to mean
+            // anything — an empty annotation matcher matching every annotated
+            // tool would be a footgun. Treat a hint-less matcher as a non-match.
+            return readOnlyHint !== undefined || destructiveHint !== undefined;
+        }
+    }
+}
+/**
+ * Resolves the approval decision for a tool invocation.
+ *
+ * Concatenates the four rule tiers in precedence order
+ * `[...BUILT_IN_TOOL_POLICIES, ...tiers.harness, ...tiers.factory, ...agentConfig.toolPolicies]`
+ * and applies **cross-tier deny-wins / within-tier last-wins**:
+ *
+ * - If any matching rule is a `'deny'`, the decision is `'deny'` and
+ *   `matchedRule` is the **last** `'deny'` (closest-to-consumer — most useful
+ *   for "why was my tool blocked" debugging).
+ * - Otherwise, the **last** matching non-deny rule decides.
+ * - If nothing matched, the decision is `agentConfig.defaultToolDecision`, or
+ *   `'allow'` when that is unset (back-compat: "no policy ⇒ no gating").
+ *
+ * **Pure function** — no I/O, no logging, no side effects. The unmatched-rule
+ * `LogBus.warn` is the harness's responsibility (after observing
+ * `matchedRule === undefined`), keeping the resolver dependency-free and
+ * trivially testable.
+ */
+export function resolveToolApprovalPolicy(invocation, agentConfig, tiers) {
+    const allRules = [
+        ...BUILT_IN_TOOL_POLICIES,
+        ...(tiers?.harness ?? []),
+        ...(tiers?.factory ?? []),
+        ...(agentConfig.toolPolicies ?? []),
+    ];
+    const matched = allRules.filter((rule) => matcherMatches(rule.matcher, invocation));
+    // Cross-tier deny-wins: any 'deny' anywhere wins. Report the last one.
+    const denyRules = matched.filter((rule) => rule.decision === 'deny');
+    if (denyRules.length > 0) {
+        return { decision: 'deny', matchedRule: denyRules[denyRules.length - 1], allMatchedRules: matched };
+    }
+    // Within-tier last-wins: the last matching non-deny rule decides.
+    if (matched.length > 0) {
+        const last = matched[matched.length - 1];
+        return { decision: last.decision, matchedRule: last, allMatchedRules: matched };
+    }
+    // Nothing matched — fall back to the agent's default (or 'allow').
+    return { decision: agentConfig.defaultToolDecision ?? 'allow' };
+}
+/**
+ * Compresses the common policy cases into a `ToolPolicyRule[]` with
+ * `source: 'agent-config'`. Each key is a tool selector, each value its
+ * {@link Decision}:
+ *
+ * ```ts
+ * definePolicy({
+ *     Bash: 'deny',                  // builtin matcher
+ *     'mcp:sfdx': 'require-approval', // every tool from the 'sfdx' MCP server
+ *     'mcp:sfdx/list_orgs': 'allow',  // one tool from the 'sfdx' server
+ * });
+ * ```
+ *
+ * Key grammar:
+ * - `'<name>'` → `{ type: 'builtin', name }`.
+ * - `'mcp:<server>'` → `{ type: 'mcp', serverName }`.
+ * - `'mcp:<server>/<tool>'` → `{ type: 'mcp', serverName, toolName }`.
+ *
+ * Consumers needing `mcp-annotation` matchers, the bare `{ type: 'mcp' }`
+ * server-agnostic wildcard, or any tool name containing `/` must author the
+ * structured {@link ToolPolicyRule} form directly — the shorthand intentionally
+ * covers only the simple `builtin` and `mcp:server[/tool]` cases.
+ */
+export function definePolicy(spec) {
+    return Object.entries(spec).map(([key, decision]) => ({
+        matcher: parsePolicyKey(key),
+        decision,
+        source: 'agent-config',
+    }));
+}
+/** Parses a {@link definePolicy} key into its structured {@link ToolMatcher}. */
+function parsePolicyKey(key) {
+    if (!key.startsWith('mcp:')) {
+        return { type: 'builtin', name: key };
+    }
+    const rest = key.slice('mcp:'.length);
+    const slash = rest.indexOf('/');
+    if (slash === -1) {
+        return { type: 'mcp', serverName: rest };
+    }
+    return { type: 'mcp', serverName: rest.slice(0, slash), toolName: rest.slice(slash + 1) };
+}
+//# sourceMappingURL=policy-resolver.js.map