@salesforce/sfdx-agent-sdk 0.25.0 → 0.27.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to `@salesforce/sfdx-agent-sdk` are documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.27.0] - 2026-06-29
+
+### Fixes
+- **harness-claude**: make multi-file skills reachable via load_skill @W-23231661 ([#627](https://github.com/forcedotcom/agentic-dx/pull/627))
+
+## [0.26.0] - 2026-06-29
+
+### Features
+- **harness-claude**: consult tool-approval policy resolver at gate sites @W-23090029 ([#624](https://github.com/forcedotcom/agentic-dx/pull/624))
+- **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))
+- **agent-sdk**: tool-approval policy resolver, types, and remember persistence @W-23090026 ([#620](https://github.com/forcedotcom/agentic-dx/pull/620))
+
 ## [0.25.0] - 2026-06-24
 
 ### Chores

package/README.md

@@ -159,22 +159,22 @@ keeps unparameterized call sites working.
 
 A single conversation thread.
 
-| Method              | Signature                                                                 | Description                                                                                                                |
-| ------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                 |
-| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.        |
-| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream. |
-| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. Control message on the existing turn — post-resume events flow on the same stream.            |
-| `declineToolCall`   | `(toolCallId: string) => Promise<void>`                                   | Decline a pending tool call. Control message on the existing turn — post-resume events flow on the same stream.            |
-| `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                              |
-| `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                       |
-| `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                              |
-| `addContext`        | `(message: string \| Message[]) => Promise<void>`                         | Inject context without triggering an LLM response.                                                                         |
-| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                          | Register a real-time event listener.                                                                                       |
-| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                          | Remove a listener.                                                                                                         |
-| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                       | Subscribe to telemetry scoped to this session.                                                                             |
-| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                  | Subscribe to logs scoped to this session.                                                                                  |
-| `dispose`           | `() => void`                                                              | Release session-level event resources. Idempotent.                                                                         |
+| Method              | Signature                                                                 | Description                                                                                                                                                                                     |
+| ------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getId`             | `() => string`                                                            | Session/thread identifier.                                                                                                                                                                      |
+| `chat`              | `(message: string, options?: ChatOptions) => Promise<ChatStreamResult>`   | Send a message and stream the response. The returned `eventStream` is the single iterator for the entire chat turn.                                                                             |
+| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<void>`                           | Return a consumer-executed tool result. Control message on the existing turn — post-resume events flow on the same stream.                                                                      |
+| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Approve a pending tool call. `{ remember: true }` ("Allow always") appends an `allow` rule to `AgentConfig.toolPolicies` and persists it before settling. Control message on the existing turn. |
+| `declineToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<void>` | Decline a pending tool call. `{ remember: true }` ("Deny always") appends a `deny` rule and persists it before settling. Control message on the existing turn.                                  |
+| `getMessageHistory` | `() => Promise<Message[]>`                                                | Retrieve all messages in chronological order.                                                                                                                                                   |
+| `clearHistory`      | `() => Promise<void>`                                                     | Delete all messages.                                                                                                                                                                            |
+| `getContextUsage`   | `() => ContextUsage`                                                      | Snapshot of how much of the model's context window the most recent turn used.                                                                                                                   |
+| `addContext`        | `(message: string \| Message[]) => Promise<void>`                         | Inject context without triggering an LLM response.                                                                                                                                              |
+| `subscribe`         | `(callback: (event: ChatEvent) => void) => void`                          | Register a real-time event listener.                                                                                                                                                            |
+| `unsubscribe`       | `(callback: (event: ChatEvent) => void) => void`                          | Remove a listener.                                                                                                                                                                              |
+| `onTelemetry`       | `(callback: TelemetryEventCallback) => Unsubscribe`                       | Subscribe to telemetry scoped to this session.                                                                                                                                                  |
+| `onLog`             | `(callback: (record: LogRecord) => void) => Unsubscribe`                  | Subscribe to logs scoped to this session.                                                                                                                                                       |
+| `dispose`           | `() => void`                                                              | Release session-level event resources. Idempotent.                                                                                                                                              |
 
 ### `ChatStreamResult`
 
@@ -232,30 +232,97 @@ function onApprovalRequest(event: ToolApprovalRequestEvent): Promise<boolean> {
 
 #### `AgentConfig`
 
-| Field           | Type                 | Description                                                                                                                                                                                                                                                                                                                          |
-| --------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `orgAlias?`     | `string`             | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                 |
-| `modelId?`      | `ModelName \| Model` | LLM model selector. Pass a `ModelName` enum value for an in-tree model (e.g. `'llmgateway__OpenAIGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` exported from this package.                                    |
-| `name?`         | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                           |
-| `description?`  | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                           |
-| `instructions?` | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                   |
-| `tools?`        | `ToolDefinition[]`   | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                      |
-| `mcpServers?`   | `MCPConfiguration`   | MCP server connections.                                                                                                                                                                                                                                                                                                              |
-| `skills?`       | `string[]`           | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                 |
-| `rules?`        | `string[]`           | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention. |
+| Field                  | Type                 | Description                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `orgAlias?`            | `string`             | Salesforce org alias or username. Falls back to project/default org.                                                                                                                                                                                                                                                                         |
+| `modelId?`             | `ModelName \| Model` | LLM model selector. Pass a `ModelName` enum value for an in-tree model (e.g. `'llmgateway__OpenAIGPT5'`), or a pre-built `Model` instance to opt into a Bedrock-Anthropic Claude variant the SDK has not yet released — see `createClaudeModel(gatewayId, overrides)` exported from this package.                                            |
+| `name?`                | `string`             | Human-readable agent name.                                                                                                                                                                                                                                                                                                                   |
+| `description?`         | `string`             | Agent purpose description.                                                                                                                                                                                                                                                                                                                   |
+| `instructions?`        | `string`             | System instructions for the agent.                                                                                                                                                                                                                                                                                                           |
+| `tools?`               | `ToolDefinition[]`   | Consumer-executed tool schemas.                                                                                                                                                                                                                                                                                                              |
+| `mcpServers?`          | `MCPConfiguration`   | MCP server connections.                                                                                                                                                                                                                                                                                                                      |
+| `skills?`              | `string[]`           | Each entry is either an individual skill folder (containing `SKILL.md`) or a parent folder containing skill subfolders. Relative and absolute paths supported; forms can be mixed in the same array.                                                                                                                                         |
+| `rules?`               | `string[]`           | Each entry is either an individual `.md` rule file or a directory of `.md` rule files (scanned one level deep, alphabetical, non-`.md` skipped). Bodies are composed verbatim into the agent's effective system prompt; YAML frontmatter is optional and stripped if present. Matches Claude Code's `.claude/rules/*.md` convention.         |
+| `toolPolicies?`        | `ToolPolicyRule[]`   | Ordered per-tool approval rules resolved by `resolveToolApprovalPolicy` (cross-tier deny-wins / within-tier last-wins). Author directly or via `definePolicy(...)`. See "Tool Approval Policy" below. Has no effect until a harness wires the resolver (Phase 2); until then gating uses the deprecated `StreamOptions.requireToolApproval`. |
+| `defaultToolDecision?` | `Decision`           | Fallback decision when no rule matches. Defaults to `'allow'` (no policy ⇒ no gating). Set to `'require-approval'` for a fail-closed posture (recommended for catalogs with un-annotated MCP servers).                                                                                                                                       |
 
 #### `StreamOptions`
 
-| Field                  | Type                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| ---------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `abortSignal?`         | `AbortSignal`                 | Abort the streaming operation.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| `requireToolApproval?` | `boolean \| ToolApprovalMode` | Gates native tool execution behind a `tool-approval-request` event. `true` / `'serial'` (the default) emits one approval per stream — safe for any iterator pattern. `'batch'` opts into parallel-approval UX: when the model emits parallel `tool_use` blocks, all approvals surface on the same stream so the consumer can render a batch approval card. **`'batch'` requires Pattern A iterators** (collect-all-approvals-then-settle); a `break`-on-first-approval loop will hang. See "Tool Approval Flow" below. |
-| `maxSteps?`            | `number`                      | Maximum number of LLM call steps the agent may take per `stream()` invocation. Each step is one LLM call (which may produce text, tool calls, or both). Must be `>= 1`. Defaults to `DEFAULT_MAX_STEPS` (1024) — high enough to be effectively unlimited for real tasks; the practical ceiling is the context window and cost. The constant is exported so consumers and harness authors share one source of truth.                                                                                                    |
+| Field                  | Type                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| ---------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abortSignal?`         | `AbortSignal`                 | Abort the streaming operation.                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| `requireToolApproval?` | `boolean \| ToolApprovalMode` | **Deprecated.** Per-call all-or-nothing gating. Superseded by per-tool policy on `AgentConfig.toolPolicies`; the serial-vs-batch UX axis moved to `batchApprovals`. Kept functional for one release so harness PRs migrate independently. `true` / `'serial'` emits one approval per stream; `'batch'` surfaces parallel approvals on one stream (requires Pattern A iterators). See "Tool Approval Flow" below.                                   |
+| `batchApprovals?`      | `boolean`                     | When `true`, parallel approval-requests within a turn surface on the same stream so the consumer can render a batch approval card (requires Pattern A iterators — collect-all-then-settle). Defaults to `false` (serial). The self-documenting replacement for the UX half of the deprecated `requireToolApproval` enum; the gating half moves to `AgentConfig.toolPolicies`. No effect when no tool in the turn resolves to `'require-approval'`. |
+| `maxSteps?`            | `number`                      | Maximum number of LLM call steps the agent may take per `stream()` invocation. Each step is one LLM call (which may produce text, tool calls, or both). Must be `>= 1`. Defaults to `DEFAULT_MAX_STEPS` (1024) — high enough to be effectively unlimited for real tasks; the practical ceiling is the context window and cost. The constant is exported so consumers and harness authors share one source of truth.                                |
 
-`ToolApprovalMode` is the exported type alias `'serial' | 'batch'` — useful when typing a settings struct that drives
-`requireToolApproval`. Pair with `resolveToolApprovalMode(boolean | ToolApprovalMode | undefined)` (also exported) to
-normalize consumer input the same way the SDK does internally (`undefined` / `false` → `undefined`, `true` → `'serial'`,
-strings pass through, unknown strings throw).
+`ToolApprovalMode` is the exported (deprecated) type alias `'serial' | 'batch'`. Pair with the (deprecated)
+`resolveToolApprovalMode(boolean | ToolApprovalMode | undefined)` to normalize consumer input the same way the SDK does
+internally (`undefined` / `false` → `undefined`, `true` → `'serial'`, strings pass through, unknown strings throw). New
+code should configure `AgentConfig.toolPolicies` and set `batchApprovals` for the UX axis instead.
+
+#### Tool Approval Policy
+
+Per-tool approval is configured on the agent, not per `chat()` call. `AgentConfig.toolPolicies` is an ordered list of
+`ToolPolicyRule`s; for each harness-executed tool call the harness consults `resolveToolApprovalPolicy(...)`, a pure
+function exported from this package.
+
+```typescript
+export type Decision = 'allow' | 'deny' | 'require-approval';
+
+export type ToolMatcher =
+  | { type: 'builtin'; name: string } // harness built-in (e.g. Claude `Bash`)
+  | { type: 'mcp'; serverName?: string; toolName?: string } // MCP tool(s); omitted fields are wildcards
+  | { type: 'mcp-annotation'; readOnlyHint?: boolean; destructiveHint?: boolean }; // by discovered annotation
+
+export type ToolPolicyRule = {
+  matcher: ToolMatcher;
+  decision: Decision;
+  source?: 'built-in' | 'agent-config' | 'remember'; // advisory provenance; ignored by the resolver
+};
+```
+
+**Resolution — cross-tier deny-wins / within-tier last-wins.** The resolver concatenates four tiers in precedence order
+— `[...BUILT_IN_TOOL_POLICIES, ...harness, ...factory, ...AgentConfig.toolPolicies]` — then: any matching `'deny'` in
+any tier wins; otherwise the last matching non-deny rule decides; if nothing matched, the result is
+`AgentConfig.defaultToolDecision ?? 'allow'`. So a later rule overrides an earlier one of the same matcher (a consumer
+rule beats a built-in), but no consumer rule can override a `deny`.
+
+**Built-in rules.** `BUILT_IN_TOOL_POLICIES` (exported, frozen) ships cross-harness rules only: MCP-annotation defaults
+(`destructiveHint ⇒ require-approval`, `readOnlyHint ⇒ allow`) and the `skill_bridge` capability-discovery meta-tools
+(anchored on the exported `SKILL_BRIDGE_SERVER_ID`). Harness-specific built-ins (Claude's `Bash`, Mastra's
+`updateWorkingMemory`) live in the harness packages' `<HARNESS>_BUILT_IN_TOOL_POLICIES` arrays, not here.
+
+**`definePolicy` helper.** Compresses the common cases into a `ToolPolicyRule[]` (`source: 'agent-config'`):
+
+```typescript
+import { definePolicy } from '@salesforce/sfdx-agent-sdk';
+
+const config: AgentConfig = {
+  defaultToolDecision: 'require-approval', // fail-closed
+  toolPolicies: 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
+  }),
+};
+```
+
+`definePolicy` covers `builtin` and `mcp:server[/tool]` keys only — author the structured `ToolPolicyRule` form for
+`mcp-annotation` matchers, the bare `{ type: 'mcp' }` wildcard, or tool names containing `/`.
+
+**AG-UI button mapping.** The settle methods grow a symmetric, honored `remember` flag:
+
+| AG-UI button | SDK call                                  | Effect                                                   |
+| ------------ | ----------------------------------------- | -------------------------------------------------------- |
+| Allow        | `approveToolCall(id)`                     | Settle only.                                             |
+| Allow always | `approveToolCall(id, { remember: true })` | Append an `allow` `remember` rule, persist, then settle. |
+| Deny         | `declineToolCall(id)`                     | Settle only.                                             |
+| Deny always  | `declineToolCall(id, { remember: true })` | Append a `deny` `remember` rule, persist, then settle.   |
+
+With `{ remember: true }` the SDK derives the matcher from the pending `tool-approval-request`'s
+`(toolName, serverName?)`, appends a `source: 'remember'` rule to `AgentConfig.toolPolicies`, and persists it via
+`updateAgentConfig` **before** settling — so the decision survives a restart and a persistence failure surfaces as the
+settle's rejection. A `remember` settle for a `toolCallId` with no pending approval throws `TOOL_CALL_NOT_FOUND`.
 
 #### `MCPConfiguration`
 

package/dist/agent.js

@@ -332,10 +332,19 @@ export class DefaultAgent {
         // `contextWindow`; #507's decoupling work must preserve that, so this
         // access is contractually safe.
         const getContextWindow = () => this.modelConnectivityInfo.model.contextWindow;
+        // Persists a `'remember'` policy rule for an `approveToolCall` /
+        // `declineToolCall` settle with `{ remember: true }`. Reads `this.config`
+        // live (so concurrent sessions and prior remembers compound correctly)
+        // and forwards a `toolPolicies`-only partial — `updateAgentConfig` skips
+        // connectivity re-resolution when neither `orgAlias` nor `modelId` is
+        // present, so an "Allow always" click never re-mints the org JWT.
+        const persistRememberedRule = async (rule) => {
+            await this.updateAgentConfig({ toolPolicies: [...(this.config.toolPolicies ?? []), rule] });
+        };
         const session = new DefaultChatSession(this.harness, this.agentId, threadId, slice, {
             telemetry: this.telemetryBus,
             log: this.logBus,
-        }, getContextWindow, this.clock, this.idGenerator);
+        }, getContextWindow, { clock: this.clock, idGenerator: this.idGenerator, persistRememberedRule });
         this.sessions.set(threadId, session);
         this.sessionSliceUnregisters.set(threadId, () => this.router.unregisterSession(threadId));
         this.telemetryBus.emit({

package/dist/chat-session.d.ts

@@ -5,12 +5,42 @@ import type { TelemetrySlice } from './internal/telemetry-router.js';
 import type { ChatEvent, ChatStreamResult } from './types/events.js';
 import type { Message, MessagePart } from './types/messages.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
-import type { ToolResultInfo } from './types/tools.js';
+import type { ToolPolicyRule, ToolResultInfo } from './types/tools.js';
 import type { ContextUsage } from './types/usage.js';
 /**
  * Options for a single chat interaction.
  */
 export type ChatOptions = StreamOptions;
+/**
+ * Persists a `'remember'` tool-policy rule appended by a settle call with
+ * `{ remember: true }`. Injected by {@link DefaultAgent} so the session can
+ * write through to the agent's config (and the SDK-owned identity store)
+ * without holding an `Agent` reference. The implementation reads the agent's
+ * current `toolPolicies`, appends `rule`, and calls `updateAgentConfig` with a
+ * `toolPolicies`-only partial so no connectivity re-resolution is triggered.
+ */
+export type RememberedRulePersister = (rule: ToolPolicyRule) => Promise<void>;
+/**
+ * Optional injected dependencies for a {@link DefaultChatSession}. Bundled into
+ * one trailing bag (rather than a growing tail of positional params) so a new
+ * dependency is a one-field addition here plus a one-line spread at the
+ * construction site, not a positional append every caller must match.
+ *
+ * Every field is optional with a production default resolved in the
+ * constructor — tests override only what they need.
+ */
+export type ChatSessionDeps = {
+    /** Source of monotonic timestamps for telemetry events. Defaults to `RealClock`. */
+    clock?: Clock;
+    /** Source of message ids for `addContext()`. Defaults to `UUIDGenerator`. */
+    idGenerator?: UniqueIDGenerator;
+    /**
+     * Persists a `'remember'` policy rule for a settle call with `{ remember: true }`.
+     * Supplied by `DefaultAgent`; omitted in unit tests, where a `remember: true` settle
+     * then behaves as a one-shot with no write. See {@link RememberedRulePersister}.
+     */
+    persistRememberedRule?: RememberedRulePersister;
+};
 /**
  * Parent bus pair used to wire upward forwarding at construction time.
  */
@@ -99,10 +129,14 @@ export interface ChatSession {
      *
      * @param toolCallId - ID of the pending tool call to approve.
      * @param options - Optional approval metadata.
-     * @param options.remember - When `true`, signals that the consumer wants to
-     *   persist this approval decision (e.g., "always allow this tool").
-     *   The harness does not implement the persistence — the consumer manages
-     *   its own permission cache. Borrowed from OpenCode's `once/always/reject` model.
+     * @param options.remember - When `true` ("Allow always"), the SDK appends a
+     *   `{ decision: 'allow', source: 'remember' }` rule to the agent's
+     *   `toolPolicies` (matching this tool) and persists it via
+     *   `updateAgentConfig` **before** settling the approval, so the decision
+     *   survives a restart. Throws `TOOL_CALL_NOT_FOUND` if `toolCallId` does
+     *   not match a pending `tool-approval-request` (e.g. a consumer-executed
+     *   tool, which is never gated). When `false`/omitted, the approval is a
+     *   one-shot settle with no persistence.
      */
     approveToolCall(toolCallId: string, options?: {
         remember?: boolean;
@@ -118,8 +152,17 @@ export interface ChatSession {
      * `ErrorEvent` + `FinishEvent` on the chat stream before the rejection.
      *
      * @param toolCallId - ID of the pending tool call to decline.
+     * @param options - Optional decline metadata.
+     * @param options.remember - When `true` ("Deny always"), the SDK appends a
+     *   `{ decision: 'deny', source: 'remember' }` rule to the agent's
+     *   `toolPolicies` (matching this tool) and persists it via
+     *   `updateAgentConfig` **before** settling the decline. Symmetric with
+     *   {@link approveToolCall}'s `remember`. Throws `TOOL_CALL_NOT_FOUND` if
+     *   `toolCallId` does not match a pending `tool-approval-request`.
      */
-    declineToolCall(toolCallId: string): Promise<void>;
+    declineToolCall(toolCallId: string, options?: {
+        remember?: boolean;
+    }): Promise<void>;
     /**
      * Retrieve message history for this session.
      *
@@ -200,6 +243,16 @@ export declare class DefaultChatSession implements ChatSession {
      * are stale and should not bleed into the next turn).
      */
     private readonly toolStartMs;
+    /**
+     * 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`.
+     */
+    private readonly pendingApprovalsByToolCallId;
     /**
      * Live getter for the agent's currently-bound model's context window.
      * Called by {@link getContextUsage} so reads reflect the model in
@@ -207,6 +260,14 @@ export declare class DefaultChatSession implements ChatSession {
      * (an `Agent.updateAgentConfig()` swap can change it mid-life).
      */
     private readonly 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}.
+     */
+    private readonly persistRememberedRule;
     /**
      * Last per-step usage reading observed on this session. Initialized
      * to `{}` (every token field undefined) so {@link getContextUsage}
@@ -226,10 +287,10 @@ export declare class DefaultChatSession implements ChatSession {
      * @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: AgentHarness, agentId: string, threadId: string, inbound: TelemetrySlice, parent: ChatSessionParentBuses, getContextWindow: () => number, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, threadId: string, inbound: TelemetrySlice, parent: ChatSessionParentBuses, getContextWindow: () => number, deps?: ChatSessionDeps);
     getId(): string;
     /**
      * @requirements
@@ -290,9 +351,12 @@ export declare class DefaultChatSession implements ChatSession {
      *   `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.
      */
-    approveToolCall(toolCallId: string, _options?: {
+    approveToolCall(toolCallId: string, options?: {
         remember?: boolean;
     }): Promise<void>;
     /**
@@ -305,8 +369,12 @@ export declare class DefaultChatSession implements ChatSession {
      *   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}.
      */
-    declineToolCall(toolCallId: string): Promise<void>;
+    declineToolCall(toolCallId: string, options?: {
+        remember?: boolean;
+    }): Promise<void>;
     /**
      * @requirements
      * - MUST delegate to `this.harness.getMessages()`, passing `this.agentId` and `this.threadId`.
@@ -364,6 +432,16 @@ export declare class DefaultChatSession implements ChatSession {
     onLog(callback: (record: LogRecord) => void): Unsubscribe;
     dispose(): void;
     private emitToolApprovalResolved;
+    /**
+     * 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.
+     */
+    private clearPerTurnTracking;
     /**
      * 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
@@ -379,6 +457,20 @@ export declare class DefaultChatSession implements ChatSession {
      * `tool-execution-started`.
      */
     private deriveToolTelemetry;
+    /**
+     * 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`.
+     */
+    private maybePersistRememberedRule;
     /**
      * 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/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

package/dist/types/telemetry-events.d.ts

@@ -1,5 +1,6 @@
 import type { EventBus } from '@salesforce/agentic-common';
 import type { McpServerErrorDetail, McpServerStatus, McpToolAnnotations } from '../mcp-config.js';
+import type { Decision, ToolPolicyRule } from './tools.js';
 import type { UsageMetadata } from './usage.js';
 /**
  * Telemetry events emitted by the Agent SDK.
@@ -85,6 +86,46 @@ export type ToolApprovalResolvedEvent = Base<'tool-approval-resolved'> & {
     threadId: string;
     toolCallId: string;
     approved: boolean;
+    /**
+     * `true` when the settle's `remember` flag triggered an
+     * `updateAgentConfig` call that appended a `'remember'` policy rule.
+     * Absent / `false` when the settle did not persist a rule.
+     */
+    policyWritten?: boolean;
+};
+/**
+ * Emitted by a harness on every harness-executed tool call, after
+ * `resolveToolApprovalPolicy` decides and before any gate work happens.
+ * Lets telemetry sinks answer "why did this tool prompt / not prompt / get
+ * denied?" by reading the rule that fired.
+ *
+ * Emitted by the harness layer (Phase 2), not the SDK — the SDK exports the
+ * variant so the public `TelemetryEvent` union is complete before the harness
+ * PRs land.
+ */
+export type ToolApprovalPolicyResolvedEvent = Base<'tool-approval-policy-resolved'> & {
+    agentId: string;
+    threadId: string;
+    toolCallId: string;
+    toolName: string;
+    /** Originating MCP server name, when the tool was discovered through MCP. */
+    serverName?: string;
+    /** The resolved decision. */
+    decision: Decision;
+    /**
+     * The rule that drove the decision under cross-tier-deny-wins /
+     * within-tier-last-wins precedence (the last `'deny'` when denied, else the
+     * last matching non-deny rule). `undefined` when no rule matched and the
+     * resolver fell back to `defaultToolDecision ?? 'allow'`; the harness emits
+     * a `LogBus.warn` in that case.
+     */
+    matchedRule?: ToolPolicyRule;
+    /**
+     * Every matching rule in resolved-list order. Optional debug verbosity for
+     * sinks that surface "remembered allow overridden by built-in deny"
+     * scenarios; most consumers use {@link matchedRule}.
+     */
+    allMatchedRules?: ToolPolicyRule[];
 };
 export type McpServerDiscoveryStartedEvent = Base<'mcp-server-discovery-started'> & {
     agentId: string;
@@ -137,7 +178,7 @@ export type McpServerStatusChangedEvent = Base<'mcp-server-status-changed'> & {
     /** Populated when `nextStatus === 'error'`. */
     error?: string;
 };
-export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent;
+export type TelemetryEvent = AgentCreatedEvent | AgentDestroyedEvent | SessionCreatedEvent | SessionDestroyedEvent | ChatStreamStartedEvent | ChatStreamCompletedEvent | ChatStreamErrorEvent | ToolExecutionStartedEvent | ToolExecutionCompletedEvent | ToolApprovalRequestedEvent | ToolApprovalResolvedEvent | ToolApprovalPolicyResolvedEvent | McpServerDiscoveryStartedEvent | McpServerDiscoveryCompletedEvent | McpServerDiscoveryFailedEvent | McpServerStatusChangedEvent;
 export type TelemetryEventCallback = (event: TelemetryEvent) => void;
 export type TelemetryBus = EventBus<TelemetryEvent>;
 export {};

package/dist/types/tools.d.ts

@@ -46,6 +46,89 @@ export type ToolDefinition = {
      */
     annotations?: McpToolAnnotations;
 };
+/**
+ * The policy decision for a single tool invocation.
+ *
+ * - `'allow'` — the harness executes the tool without pausing.
+ * - `'deny'` — the harness refuses the call and synthesizes a
+ *   `tool-result(isError=true)` so the model can recover; no
+ *   `tool-approval-request` surfaces.
+ * - `'require-approval'` — the harness emits a `tool-approval-request`
+ *   and suspends until the consumer settles via `approveToolCall` /
+ *   `declineToolCall`.
+ */
+export type Decision = 'allow' | 'deny' | 'require-approval';
+/**
+ * Structured matcher selecting which tool invocations a {@link ToolPolicyRule}
+ * applies to.
+ *
+ * The three shapes cover every tool category a harness gates:
+ *
+ * - `'builtin'` — harness-built-in tools (e.g. Claude's `Bash` / `Edit`;
+ *   Mastra's `updateWorkingMemory`). Names are **harness-specific**, so a
+ *   `'builtin'` rule applies asymmetrically across harnesses — `Bash` matches
+ *   on Claude and is a no-op on Mastra. A `'builtin'` matcher matches only when
+ *   the invocation has no `serverName` (MCP tools carry one).
+ * - `'mcp'` — MCP-discovered tools. Both `serverName` and `toolName` are
+ *   optional: omitting `toolName` matches every tool from the given server;
+ *   omitting `serverName` matches every tool from every MCP server; omitting
+ *   both matches every MCP tool (a server-agnostic catch-all). MCP rules are
+ *   **portable** — the same rule fires on both harnesses for the same tool.
+ * - `'mcp-annotation'` — matches any MCP tool whose discovered
+ *   {@link McpToolAnnotations} carry the specified hint(s). Every field set on
+ *   the matcher must equal the corresponding field on the discovered
+ *   annotation (logical AND across set fields). A tool with no annotations does
+ *   **not** match — the resolver falls through. This is fail-open by default;
+ *   tenants needing fail-closed for un-annotated MCP servers set
+ *   {@link AgentConfig.defaultToolDecision} to `'require-approval'`.
+ *
+ * There is intentionally no `consumer` matcher. Consumer-declared tools (those
+ * in {@link AgentConfig.tools} without an `execute`) are gated structurally at
+ * the harness boundary and never reach the resolver, so a matcher variant for
+ * them would be API surface for an unreachable case.
+ */
+export type ToolMatcher = {
+    type: 'builtin';
+    name: string;
+} | {
+    type: 'mcp';
+    serverName?: string;
+    toolName?: string;
+} | {
+    type: 'mcp-annotation';
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+};
+/**
+ * One entry in an agent's tool-approval policy list.
+ *
+ * Resolution concatenates the SDK's `BUILT_IN_TOOL_POLICIES`, the harness's
+ * built-in array, any harness factory rules, and `AgentConfig.toolPolicies`,
+ * then applies **cross-tier deny-wins / within-tier last-wins** precedence (see
+ * `resolveToolApprovalPolicy`).
+ */
+export type ToolPolicyRule = {
+    /** Selects which tool invocations this rule applies to. */
+    matcher: ToolMatcher;
+    /** The decision to apply when {@link matcher} matches. */
+    decision: Decision;
+    /**
+     * Where this rule originated. Advisory metadata only — the resolver
+     * **ignores** `source` when computing a decision; telemetry surfaces it so
+     * operators can answer "which tier fired."
+     *
+     * - `'built-in'` — shipped by the SDK's `BUILT_IN_TOOL_POLICIES` or a
+     *   harness package's `<HARNESS>_BUILT_IN_TOOL_POLICIES` array.
+     * - `'agent-config'` — authored by whoever wrote the `AgentConfig`. The
+     *   default when unset on a consumer-supplied rule.
+     * - `'remember'` — written by `approveToolCall(id, { remember: true })` /
+     *   `declineToolCall(id, { remember: true })`.
+     *
+     * v1 ships these three values. A future tenant-managed-policy tier will add
+     * `'managed'` to this union; that widening is strictly additive.
+     */
+    source?: 'built-in' | 'agent-config' | 'remember';
+};
 /**
  * Base shape for a tool call.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.25.0",
+  "version": "0.27.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -44,8 +44,8 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.21.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.24.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.23.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.26.0",
     "@types/node": "^22.20.0",
     "@vitest/coverage-istanbul": "^4.1.8",
     "@vitest/eslint-plugin": "^1.6.20",