@salesforce/sfdx-agent-sdk 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+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.17.0] - 2026-06-09
+
+### Features
+- **release**: auto-generate per-package CHANGELOG.md on publish ([#567](https://github.com/forcedotcom/agentic-dx/pull/567))
+- unify tool-exposure policy under toolSearch.alwaysActive ([#566](https://github.com/forcedotcom/agentic-dx/pull/566))
+- add ClaudeAgentConfig.skillSearch + decouple Mastra skillSearch from toolSearch ([#563](https://github.com/forcedotcom/agentic-dx/pull/563))
+- **agent-sdk**: preserve MCP clients across updateAgentConfig ([#560](https://github.com/forcedotcom/agentic-dx/pull/560))
+- **agent-sdk,harness-claude,harness-mastra**: first-class tool-result redaction ([#546](https://github.com/forcedotcom/agentic-dx/pull/546))
+
+### Fixes
+- **harness-mastra**: honor MCPServerConfig.alwaysLoad when toolSearch is set ([#558](https://github.com/forcedotcom/agentic-dx/pull/558))
+
+### Chores
+- **deps-dev**: bump the eslint group across 1 directory with 2 updates ([#553](https://github.com/forcedotcom/agentic-dx/pull/553))
+- **deps-dev**: bump the dev-dependencies group across 1 directory with 4 updates ([#536](https://github.com/forcedotcom/agentic-dx/pull/536))
+- **deps-dev**: bump the vitest group across 1 directory with 3 updates ([#552](https://github.com/forcedotcom/agentic-dx/pull/552))
+

package/README.md

@@ -59,14 +59,19 @@ await manager.shutdown();
 
 ## API Reference
 
-### `createAgentManager<F>(storageRootFolder, harnessFactory, connectivityResolver?): Promise<AgentManager<H>>`
+### `createAgentManager<F>(storageRootFolder, harnessFactory, options?): Promise<AgentManager<H>>`
 
 Factory function that creates an `AgentManager` backed by the provided `HarnessFactory`. The `storageRootFolder` must be
 an existing directory and is used for persistent state (the harness's runtime data plus the SDK's per-agent identity
 files at `${storageRootFolder}/agents/<id>.json`). The SDK verifies that the constructed harness uses a supported
-protocol version, replays any persisted agents the harness can still serve, and returns the manager. The optional
-`connectivityResolver` overrides the default sf-CLI-based org resolution — used by e2e tests and custom-auth
-deployments; production callers leave it unset.
+protocol version, replays any persisted agents the harness can still serve, and returns the manager.
+
+The third-positional `options` bag carries per-manager opt-ins. Production callers typically leave it unset:
+
+| Option                 | Type                        | Purpose                                                                                                                                                                                                   |
+| ---------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connectivityResolver` | `AgentConnectivityResolver` | Overrides the default sf-CLI-based org resolution — used by e2e tests and custom-auth deployments.                                                                                                        |
+| `hooksForAgent`        | `HooksForAgent`             | Sync callback resolving a per-agent `AgentHooks` bag (today carries `onToolResult`). Invoked once per `createAgent`, boot-time restore, and `Agent.updateAgentConfig`. See "Tool-Result Redaction" below. |
 
 The harness type `H` is **inferred from the factory's `create()` return type**, so consumers don't pass an explicit type
 argument:
@@ -240,7 +245,6 @@ type MCPStdioServerConfig = {
   env?: Record<string, string>;
   enabled?: boolean;
   timeout?: number;
-  alwaysLoad?: boolean;
 };
 
 // Remote server (HTTP/SSE)
@@ -256,16 +260,13 @@ type MCPRemoteServerConfig = {
     maxReconnectionDelay?: number;
     reconnectionDelayGrowFactor?: number;
   };
-  alwaysLoad?: boolean;
 };
 ```
 
-**`alwaysLoad`** opts a server's tool surface out of the active runtime's tool-search deferral. Default (`undefined` /
-`false`) lets the runtime defer the server's tools behind a tool-search round-trip when the global tool surface is
-large; `true` registers every tool from this server with the model up-front. Useful for small, discovery-critical
-surfaces (≤ a few tools the model needs to find without prompting). The Claude harness honors the flag by stamping
-`_meta['anthropic/alwaysLoad'] = true` on each forwarded tool (equivalent to `defer_loading: false` on the Claude API).
-The Mastra harness eager-loads all MCP tools regardless, so the flag is a no-op there.
+**Tool-exposure policy** (which tools bypass the active runtime's tool-search deferral) is configured per-agent on the
+harness extension surface, not per-server here. See `MastraAgentConfig.toolSearch.alwaysActive` and
+`ClaudeAgentConfig.toolSearch.alwaysActive` for the entry shape that covers "all tools from server X", "tool Y on server
+X", and "tool Y from any source".
 
 **`reconnectionOptions`** tunes the HTTP MCP transport's retry / backoff behavior. Forwarded to the underlying SDK
 transport on both harnesses (Claude's `@modelcontextprotocol/sdk` `StreamableHTTPClientTransport` and Mastra's
@@ -768,6 +769,134 @@ When `requireToolApproval: true` is also set, consumer-executed tools bypass the
 `StreamOptions.requireToolApproval` JSDoc). They surface as a normal `tool-call` event without a preceding
 `tool-approval-request`. Built-in / MCP tools still gate normally.
 
+### Tool-Result Redaction
+
+Secrets in tool output (a live `accessToken` from `sf org list --json`, an API key in `Bash` stdout, a JWT in an MCP
+response) must be scrubbed **before** the result enters the model's context. Once the model has seen a value it can echo
+it in a reply, route it into a later tool call (`Bash` arg, file write), or send it to provider logs — nothing
+downstream (UI scrubbing, transcript redaction) can undo that.
+
+The SDK exposes a harness-agnostic redactor type and a per-agent hooks bag (`AgentHooks`). Pass a `hooksForAgent`
+callback to `createAgentManager`; the SDK invokes it once per agent install (`createAgent`, boot-time restore,
+`Agent.updateAgentConfig`), threads the resolved bag through to whichever harness you're using, and the harness wires
+`onToolResult` to its native seam (Claude Agent SDK `PostToolUse` hook, Mastra `processInputStep`). The same redactor
+function works on both harnesses.
+
+```ts
+import {
+  createAgentManager,
+  type AgentHooks,
+  type HooksForAgent,
+  type ToolResultRedactor,
+} from '@salesforce/sfdx-agent-sdk';
+
+// Optional: wrap your redactor so an exception substitutes a safe stub
+// instead of propagating. The SDK does NOT do this for you — see
+// "Throw policy" below.
+const REDACTION_FAILURE_STUB = '[redaction failed — original withheld]';
+
+const failClosed =
+  (inner: ToolResultRedactor): ToolResultRedactor =>
+  async (input) => {
+    try {
+      return await inner(input);
+    } catch (err) {
+      auditLog.warn('redaction-failed', { toolName: input.toolName, toolCallId: input.toolCallId, err });
+      return { output: REDACTION_FAILURE_STUB };
+    }
+  };
+
+const baseRedactor: ToolResultRedactor = ({ toolName, output }) => {
+  // Bash needs its native shape preserved (see "Bash gotcha" below).
+  if (toolName === 'Bash') {
+    const bash = output as { stdout: string; stderr: string; interrupted: boolean };
+    return { output: { ...bash, stdout: scrub(bash.stdout), stderr: scrub(bash.stderr) } };
+  }
+  // Pass-through for non-secret-bearing tools — return undefined.
+  if (!mayContainSecrets(toolName)) return;
+  return { output: scrubDeep(output) };
+};
+
+const hooksForAgent: HooksForAgent = (agentId, config): AgentHooks => ({
+  onToolResult: failClosed(baseRedactor),
+});
+
+const manager = await createAgentManager(storage, factory, { hooksForAgent });
+```
+
+#### `ToolResultRedactor`
+
+Sync-or-async callback invoked once per tool result before the model sees it. Returning `{ output }` replaces the value;
+returning `undefined` passes through unchanged.
+
+```ts
+type ToolResultRedactor = (
+  input: ToolResultRedactionInput,
+) => ToolResultRedactionResult | Promise<ToolResultRedactionResult>;
+
+type ToolResultRedactionInput = {
+  agentId: string;
+  threadId: string;
+  toolCallId: string;
+  toolName: string;
+  serverName?: string; // Originating MCP server when applicable.
+  output: unknown; // Raw upstream output, unmodified.
+  isError: boolean;
+};
+
+type ToolResultRedactionResult = { output: unknown } | undefined;
+```
+
+The redactor fires for every tool result type:
+
+- **Built-in tools** (`Bash`, `Read`, `Edit`, `Glob`, `Grep`, …) on Claude.
+- **MCP tools** on either harness (with `serverName` populated from the agent's MCP catalog).
+- **Consumer-executed tools** declared via `AgentConfig.tools` on either harness.
+
+#### `AgentHooks` and `HooksForAgent`
+
+`AgentHooks` is a forward-compatible bag — today it carries `onToolResult`; future hooks (`onToolCall`, `onStep`, …)
+will land on the same shape without churning factory configs. The SDK and harnesses treat unknown fields as opaque, so
+adding a new hook is non-breaking.
+
+```ts
+type AgentHooks = { onToolResult?: ToolResultRedactor };
+type HooksForAgent = (agentId: string, config: AgentConfig) => AgentHooks;
+```
+
+`hooksForAgent` is sync — the SDK does not await it. Consumers needing async setup (e.g. a remote feature flag
+controlling who gets redaction) pre-resolve before calling `createAgentManager`. The callback receives the agent's id
+and the persisted `AgentConfig`, so per-agent variation can branch on either.
+
+#### Audit / preserving the original
+
+The redactor receives the unmodified `output` at the call site. Consumers needing an audit trail of the original value
+log it themselves before returning the redaction. The SDK does not put the original on its telemetry bus or persist it
+anywhere — that would defeat the point.
+
+#### Throw policy
+
+The SDK does NOT own fail-closed semantics. If your redactor throws, the harness propagates: Claude routes through the
+Claude Agent SDK's `PostToolUse` hook-error path (which synthesizes `tool_result(is_error=true)` so the failure is
+observable); Mastra propagates from `processInputStep` and surfaces as an `error` ChatEvent on the consumer's
+eventStream. Either way, the original output never reaches the model. Wrap your redactor in `try`/`catch` (see the
+`failClosed` helper above) when you want a richer fail-closed substitute.
+
+#### Bash gotcha (Claude only)
+
+Claude's built-in `Bash` tool expects responses to keep the `{ stdout, stderr, interrupted }` shape. A bare-string
+return is rejected by the Claude Agent SDK and the original value leaks. The harness does NOT validate this — the
+redactor knows what tool it is redacting.
+
+For MCP tools, the replacement must be a valid `CallToolResult` shape (`{ content: [...], isError? }`). For
+consumer-executed tools, any shape the consumer accepts is fine.
+
+#### Composition with consumer-supplied hooks (Claude only)
+
+If you also register a `PostToolUse` hook via `ClaudeQueryDefaults.hooks.PostToolUse`, both your hook and the harness's
+redaction hook fire — the harness hook is appended **last** in `options.hooks.PostToolUse`, so its `updatedToolOutput`
+is what actually replaces the value the model sees.
+
 ### Connectivity Resolution
 
 #### `ResolvedConnectivity`
@@ -924,14 +1053,18 @@ This package publishes two ESM entry points:
 > see the subpath. Modern bundlers (Vite, esbuild, Webpack 5+, tsup, Rollup with `@rollup/plugin-node-resolve` v15+)
 > resolve it natively. This is a harness-author concern only; consumer applications never touch the subpath.
 
-| Export                        | Surface                                     | Role                                                                                                                                                                                                                                    |
-| ----------------------------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `HarnessFactory<H>`           | Type only on bare; value+type on `/harness` | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                        |
-| `AgentHarness`                | Type only on bare; type on `/harness`       | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                               |
-| `SUPPORTED_PROTOCOL_VERSIONS` | `/harness` only                             | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                  |
-| `HarnessBusOwner`             | `/harness` only                             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                            |
-| `lowerStreamInput`            | `/harness` only                             | Validates a `MessagePart[]` and lowers each input part to your runtime's content-block shape. Use it in `stream()` so multimodal caps and `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics match every other harness.   |
-| `GenSink<T>`                  | `/harness` only                             | Buffered async-generator wrapper for routing `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`. Single-iteration: calling `generator()` twice throws — sinks have one waiter slot and one buffer, two iterators race on both. |
+| Export                        | Surface                                     | Role                                                                                                                                                                                                                                                                                                                                                                |
+| ----------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `HarnessFactory<H>`           | Type only on bare; value+type on `/harness` | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                                                                                                                                                    |
+| `AgentHarness`                | Type only on bare; type on `/harness`       | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                                                                                                                                                           |
+| `SUPPORTED_PROTOCOL_VERSIONS` | `/harness` only                             | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                                                                                                                                              |
+| `HarnessBusOwner`             | `/harness` only                             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                                                                                                                                                        |
+| `lowerStreamInput`            | `/harness` only                             | Validates a `MessagePart[]` and lowers each input part to your runtime's content-block shape. Use it in `stream()` so multimodal caps and `MULTIMODAL_NOT_SUPPORTED` / `INVALID_MESSAGE_CONTENT` semantics match every other harness.                                                                                                                               |
+| `GenSink<T>`                  | `/harness` only                             | Buffered async-generator wrapper for routing `ChatEvent`s to a consumer's `ChatStreamResult.eventStream`. Single-iteration: calling `generator()` twice throws — sinks have one waiter slot and one buffer, two iterators race on both.                                                                                                                             |
+| `mcpServerConfigEqual`        | Bare specifier and `/harness`               | Structural deep-equality predicate over `MCPServerConfig`. Use inside `updateAgent` to decide which servers to preserve vs. cycle. Treats `enabled: undefined` and `enabled: true` as equal; compares URLs via `String(url)` (so `URL` instances and strings round-trip); `headers` and `env` are key-order-insensitive; `reconnectionOptions` compares field-wise. |
+| `AlwaysActiveEntry`           | `/harness` only                             | Entry shape consumed by per-harness `toolSearch.alwaysActive` extension fields. Three matching patterns: `{ serverName }` (server-wide), `{ serverName, toolName }` (precise), `{ toolName }` (cross-source). At least one of `serverName` / `toolName` must be present.                                                                                            |
+| `matchesAlwaysActive`         | `/harness` only                             | Predicate `(entries, serverName, toolName) → boolean` consulted per-tool when stamping always-load metadata or partitioning a tool-search pool. Use this instead of pattern-matching entries by hand so harness behavior stays uniform.                                                                                                                             |
+| `validateAlwaysActiveEntry`   | `/harness` only                             | Throws on a malformed entry (`{}`, both fields empty). Call once per entry at the harness boundary so a typo fails loud at config time rather than silently dropping the entry on every `stream()`.                                                                                                                                                                 |
 
 Minimal skeleton:
 

package/dist/agent-manager.d.ts

@@ -3,6 +3,7 @@ import { type AgentHarness, type ConfigOf } from './harness/agent-harness.js';
 import type { HarnessFactory } from './harness/harness-factory.js';
 import { type AgentConfig } from './harness/harness-config.js';
 import { type Agent } from './agent.js';
+import type { HooksForAgent } from './types/redaction.js';
 import type { TelemetryEventCallback } from './types/telemetry-events.js';
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
 /**
@@ -124,6 +125,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
     private readonly harness;
     private readonly agentIdGenerator;
     private readonly agentConnectivityResolver;
+    private readonly hooksForAgent;
     private readonly clock;
     private readonly identityStore;
     private readonly agents;
@@ -144,7 +146,7 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static __build<H extends AgentHarness>(harness: H, agentConnectivityResolver: AgentConnectivityResolver, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
+    static __build<H extends AgentHarness>(harness: H, agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, storageRootFolder: string, agentIdGenerator: UniqueIDGenerator, clock: Clock, logBus: LogBus): Promise<DefaultAgentManager<H>>;
     private init;
     shutdown(): Promise<void>;
     createAgent(projectRoot: string, config?: ConfigOf<H> & {
@@ -189,14 +191,25 @@ export declare class DefaultAgentManager<H extends AgentHarness = AgentHarness>
  * function returns; failures are queryable via
  * {@link AgentManager.getRestoreFailures}.
  *
- * The optional `connectivityResolver` overrides the default
- * `DefaultAgentConnectivityResolver` — used by e2e tests and custom-auth
- * deployments where the SDK should not run sf-CLI-based org resolution.
- * Production callers leave it unset.
+ * The optional third-positional `options` bag carries the SDK's per-manager
+ * opt-ins. Production callers typically leave it unset:
+ *
+ * - `connectivityResolver` — overrides the default
+ *   `DefaultAgentConnectivityResolver`; used by e2e tests and custom-auth
+ *   deployments where the SDK should not run sf-CLI-based org resolution.
+ * - `hooksForAgent` — sync callback resolving a per-agent
+ *   {@link AgentHooks} bag (today carries `onToolResult`); invoked once per
+ *   `createAgent`, boot-time restore, and `Agent.updateAgentConfig`. The
+ *   resolved bag threads through to `AgentHarness.createAgent`'s
+ *   `options.hooks` and reaches the harness's native seam (Claude
+ *   `PostToolUse`, Mastra `processInputStep`).
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
  *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
  *   version disagrees with the factory's.
  */
-export declare function createAgentManager<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, connectivityResolver?: AgentConnectivityResolver): Promise<AgentManager<H>>;
+export declare function createAgentManager<H extends AgentHarness = AgentHarness>(storageRootFolder: string, harnessFactory: HarnessFactory<H>, options?: {
+    connectivityResolver?: AgentConnectivityResolver;
+    hooksForAgent?: HooksForAgent;
+}): Promise<AgentManager<H>>;

package/dist/agent-manager.js

@@ -25,6 +25,7 @@ export class DefaultAgentManager {
     harness;
     agentIdGenerator;
     agentConnectivityResolver;
+    hooksForAgent;
     clock;
     identityStore;
     agents = new Map();
@@ -34,9 +35,10 @@ export class DefaultAgentManager {
     router;
     unroutedUnsubs;
     disposed = false;
-    constructor(harness, agentConnectivityResolver, identityStore, agentIdGenerator, clock, logBus) {
+    constructor(harness, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus) {
         this.harness = harness;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.hooksForAgent = hooksForAgent;
         this.identityStore = identityStore;
         this.agentIdGenerator = agentIdGenerator;
         this.clock = clock;
@@ -57,9 +59,9 @@ export class DefaultAgentManager {
      * is private, so this is the only way to obtain an instance, but
      * consumers should always go through {@link createAgentManager}.
      */
-    static async __build(harness, agentConnectivityResolver, storageRootFolder, agentIdGenerator, clock, logBus) {
+    static async __build(harness, agentConnectivityResolver, hooksForAgent, storageRootFolder, agentIdGenerator, clock, logBus) {
         const identityStore = new AgentIdentityStore(storageRootFolder, harness.harnessId, logBus);
-        const manager = new DefaultAgentManager(harness, agentConnectivityResolver, identityStore, agentIdGenerator, clock, logBus);
+        const manager = new DefaultAgentManager(harness, agentConnectivityResolver, hooksForAgent, identityStore, agentIdGenerator, clock, logBus);
         await manager.init();
         return manager;
     }
@@ -155,9 +157,10 @@ export class DefaultAgentManager {
             throw new Error(`projectRoot is not a directory: "${projectRoot}"`);
         }
         const runtime = await this.agentConnectivityResolver.resolve(projectRoot, config);
-        await this.harness.createAgent(agentId, projectRoot, runtime.llmGatewayClient, toHarnessConfig(config, runtime.orgJwt), options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : undefined);
+        const hooks = this.hooksForAgent?.(agentId, config) ?? {};
+        await this.harness.createAgent(agentId, projectRoot, runtime.llmGatewayClient, toHarnessConfig(config, runtime.orgJwt), { ...(options.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}), hooks });
         const agentSlice = this.router.registerAgent(agentId);
-        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
+        const agent = new DefaultAgent(this.harness, agentId, projectRoot, config, runtime.llmGatewayClient, runtime.orgConnection, runtime.orgJwt, this.agentConnectivityResolver, this.hooksForAgent, this.identityStore, this.router, agentSlice, { telemetry: this.telemetryBus, log: this.logBus }, this.clock, this.agentIdGenerator);
         this.agents.set(agentId, agent);
         this.telemetryBus.emit({
             type: 'agent-created',
@@ -262,17 +265,25 @@ export class DefaultAgentManager {
  * function returns; failures are queryable via
  * {@link AgentManager.getRestoreFailures}.
  *
- * The optional `connectivityResolver` overrides the default
- * `DefaultAgentConnectivityResolver` — used by e2e tests and custom-auth
- * deployments where the SDK should not run sf-CLI-based org resolution.
- * Production callers leave it unset.
+ * The optional third-positional `options` bag carries the SDK's per-manager
+ * opt-ins. Production callers typically leave it unset:
+ *
+ * - `connectivityResolver` — overrides the default
+ *   `DefaultAgentConnectivityResolver`; used by e2e tests and custom-auth
+ *   deployments where the SDK should not run sf-CLI-based org resolution.
+ * - `hooksForAgent` — sync callback resolving a per-agent
+ *   {@link AgentHooks} bag (today carries `onToolResult`); invoked once per
+ *   `createAgent`, boot-time restore, and `Agent.updateAgentConfig`. The
+ *   resolved bag threads through to `AgentHarness.createAgent`'s
+ *   `options.hooks` and reaches the harness's native seam (Claude
+ *   `PostToolUse`, Mastra `processInputStep`).
  *
  * @throws {AgentSDKError} `INCOMPATIBLE_HARNESS` when either the factory or
  *   the constructed harness reports a `protocolVersion` outside
  *   {@link SUPPORTED_PROTOCOL_VERSIONS}, or when the harness's reported
  *   version disagrees with the factory's.
  */
-export async function createAgentManager(storageRootFolder, harnessFactory, connectivityResolver) {
+export async function createAgentManager(storageRootFolder, harnessFactory, options) {
     let stats;
     try {
         stats = await stat(storageRootFolder);
@@ -306,8 +317,8 @@ export async function createAgentManager(storageRootFolder, harnessFactory, conn
             `advertised version ${factoryVersion} (SDK supports: ${SUPPORTED_PROTOCOL_VERSIONS.join(', ')}). ` +
             `Update the SDK or harness package.`, AgentSDKErrorType.INCOMPATIBLE_HARNESS);
     }
-    const agentConnectivityResolver = connectivityResolver ?? new DefaultAgentConnectivityResolver();
-    return DefaultAgentManager.__build(harness, agentConnectivityResolver, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
+    const agentConnectivityResolver = options?.connectivityResolver ?? new DefaultAgentConnectivityResolver();
+    return DefaultAgentManager.__build(harness, agentConnectivityResolver, options?.hooksForAgent, storageRootFolder, new UUIDGenerator(), new RealClock(), new LogBus());
 }
 function isSupportedProtocolVersion(version) {
     return (typeof version === 'number' &&

package/dist/agent.d.ts

@@ -7,6 +7,7 @@ import { type JSONWebToken, type LLMGatewayClient } from '@salesforce/llm-gatewa
 import { type AgentConnectivityResolver } from './agent-connectivity-resolver.js';
 import type { AgentIdentityStore } from './internal/agent-identity-store.js';
 import type { TelemetryRouter, TelemetrySlice } from './internal/telemetry-router.js';
+import type { HooksForAgent } from './types/redaction.js';
 import type { TelemetryBus, TelemetryEventCallback } from './types/telemetry-events.js';
 /**
  * Parent bus pair wired at construction time so an agent's events bubble upward into the manager's buses.
@@ -44,8 +45,13 @@ export interface Agent {
     /**
      * Request a reconnect of one MCP server on this agent without recycling
      * any other server, custom tool, instruction, or skill. Useful for
-     * recovering a single failed MCP server without paying the full
-     * `updateAgentConfig` destroy/recreate cost.
+     * recovering a single failed MCP server after a transport-level error
+     * (e.g. JWT-rotation timing on stdio servers, transient EOF on remote
+     * transports). For the diff-driven case — `Agent.updateAgentConfig`
+     * applying a new `MCPConfiguration` — the harness already preserves any
+     * server whose config is structurally unchanged and cycles only the
+     * changed/added/removed servers; an explicit `reconnectMcpServer` call
+     * is **not** required there.
      *
      * Throws if `serverName` is not configured on this agent or if the named
      * server is disabled (`enabled: false`).
@@ -132,6 +138,7 @@ export declare class DefaultAgent implements Agent {
     private orgConnection;
     private orgJwt;
     private readonly agentConnectivityResolver;
+    private readonly hooksForAgent;
     private readonly identityStore;
     private readonly sessions;
     private readonly sessionSliceUnregisters;
@@ -152,13 +159,17 @@ export declare class DefaultAgent implements Agent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
+     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
+     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
+     *     the consumer didn't pass a `hooksForAgent`.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
+    constructor(harness: AgentHarness, agentId: string, projectRoot: string, config: AgentConfig, llmGatewayClient: LLMGatewayClient, orgConnection: OrgConnection, orgJwt: JSONWebToken, agentConnectivityResolver: AgentConnectivityResolver, hooksForAgent: HooksForAgent | undefined, identityStore: AgentIdentityStore, router: TelemetryRouter, inbound: TelemetrySlice, parent: AgentParentBuses, clock?: Clock, idGenerator?: UniqueIDGenerator);
     /**
      * @requirements
      * - MUST return the agent's ID.
@@ -178,11 +189,17 @@ export declare class DefaultAgent implements Agent {
      * @requirements
      * - MUST merge the provided `config` with the internal `config` object.
      * - MUST guarantee that the `agentId` remains unchanged during the merge.
-     * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
-     * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
-     * - MUST persist the merged config via `this.identityStore.write(...)` after the harness recreate succeeds and
-     *   before the in-memory swaps, so a write failure rolls back through the same catch path as a recreate failure.
-     * - MUST preserve the previous in-memory config state if recreation or persistence fails.
+     * - MUST apply the merged config to the harness via `this.harness.updateAgent(...)` — a single primitive
+     *   that preserves any MCP client whose `MCPServerConfig` is structurally equal to the currently-applied one.
+     *   The destroy+recreate shape this method used pre-#541 closed every MCP client on a model-only or
+     *   instructions-only or org-connect-only change; the new shape preserves them and only cycles servers
+     *   that actually changed.
+     * - MUST persist the merged config via `this.identityStore.write(...)` after `harness.updateAgent` succeeds
+     *   and before the in-memory swaps, so a write failure rolls back through the same catch path as an
+     *   `updateAgent` failure.
+     * - MUST preserve the previous in-memory config state if `updateAgent` or persistence fails. Rollback
+     *   uses the same `harness.updateAgent` primitive against the previous config — the harness re-diffs
+     *   against its current (possibly partially-updated) state and reverts only the actual deltas.
      */
     updateAgentConfig(config?: AgentConfig, options?: {
         abortSignal?: AbortSignal;

package/dist/agent.js

@@ -21,6 +21,7 @@ export class DefaultAgent {
     orgConnection;
     orgJwt;
     agentConnectivityResolver;
+    hooksForAgent;
     identityStore;
     sessions = new Map();
     sessionSliceUnregisters = new Map();
@@ -41,13 +42,17 @@ export class DefaultAgent {
      * @param orgConnection - Authenticated org connection carrying identity and env inference.
      * @param orgJwt - Self-refreshing JWT for the resolved org (used for MCP auth injection).
      * @param agentConnectivityResolver - Used to re-resolve org connectivity when the org or model changes.
+     * @param hooksForAgent - Per-agent hooks resolver supplied by the SDK consumer at `createAgentManager` time. The
+     *     agent re-invokes it on every `updateAgentConfig` (with `nextConfig`, and again with `previousConfig` on the
+     *     rollback path) so the bag the harness sees always reflects the current persisted config. `undefined` when
+     *     the consumer didn't pass a `hooksForAgent`.
      * @param identityStore - SDK-owned persistence for the `{ agentId, projectRoot, AgentConfig }` triple. The agent
      *     calls `write()` on a successful `updateAgentConfig` so disk state and in-memory state stay in lockstep.
      * @param router - Telemetry router used to obtain session slices when sessions are created.
      * @param inbound - Router slice delivering harness events routed to this agent (non-session-scoped).
      * @param parent - Manager's bus pair; this agent forwards its events upward into them.
      */
-    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
+    constructor(harness, agentId, projectRoot, config, llmGatewayClient, orgConnection, orgJwt, agentConnectivityResolver, hooksForAgent, identityStore, router, inbound, parent, clock = new RealClock(), idGenerator = new UUIDGenerator()) {
         this.harness = harness;
         this.agentId = agentId;
         this.projectRoot = projectRoot;
@@ -56,6 +61,7 @@ export class DefaultAgent {
         this.orgConnection = orgConnection;
         this.orgJwt = orgJwt;
         this.agentConnectivityResolver = agentConnectivityResolver;
+        this.hooksForAgent = hooksForAgent;
         this.identityStore = identityStore;
         this.router = router;
         this.clock = clock;
@@ -100,11 +106,17 @@ export class DefaultAgent {
      * @requirements
      * - MUST merge the provided `config` with the internal `config` object.
      * - MUST guarantee that the `agentId` remains unchanged during the merge.
-     * - MUST destroy the existing agent in the harness by delegating to `this.harness.destroyAgent(this.getId())`.
-     * - MUST recreate the agent in the harness with the newly merged configuration by delegating to `this.harness.createAgent(...)`.
-     * - MUST persist the merged config via `this.identityStore.write(...)` after the harness recreate succeeds and
-     *   before the in-memory swaps, so a write failure rolls back through the same catch path as a recreate failure.
-     * - MUST preserve the previous in-memory config state if recreation or persistence fails.
+     * - MUST apply the merged config to the harness via `this.harness.updateAgent(...)` — a single primitive
+     *   that preserves any MCP client whose `MCPServerConfig` is structurally equal to the currently-applied one.
+     *   The destroy+recreate shape this method used pre-#541 closed every MCP client on a model-only or
+     *   instructions-only or org-connect-only change; the new shape preserves them and only cycles servers
+     *   that actually changed.
+     * - MUST persist the merged config via `this.identityStore.write(...)` after `harness.updateAgent` succeeds
+     *   and before the in-memory swaps, so a write failure rolls back through the same catch path as an
+     *   `updateAgent` failure.
+     * - MUST preserve the previous in-memory config state if `updateAgent` or persistence fails. Rollback
+     *   uses the same `harness.updateAgent` primitive against the previous config — the harness re-diffs
+     *   against its current (possibly partially-updated) state and reverts only the actual deltas.
      */
     async updateAgentConfig(config = {}, options) {
         this.assertNotDisposed();
@@ -129,13 +141,14 @@ export class DefaultAgent {
             // (If modelId is omitted, the resolver pinned the default at creation time.)
             nextClient.setModel(nextModel);
         }
-        await this.harness.destroyAgent(this.agentId);
-        let nextConfigRegistered = false;
         try {
-            await this.harness.createAgent(this.agentId, this.projectRoot, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), options);
-            nextConfigRegistered = true;
+            const nextHooks = this.hooksForAgent?.(this.agentId, nextConfig) ?? {};
+            await this.harness.updateAgent(this.agentId, nextClient, toHarnessConfig(nextConfig, nextOrgJwt), {
+                ...(options?.abortSignal !== undefined ? { abortSignal: options.abortSignal } : {}),
+                hooks: nextHooks,
+            });
             // Persist before the in-memory swaps so a write failure flows through the same
-            // catch block as a recreate failure: the rollback restores the harness with
+            // catch block as an updateAgent failure: the rollback re-runs updateAgent against
             // previousConfig and disk state remains the pre-update record.
             await this.identityStore.write(this.agentId, this.projectRoot, nextConfig);
             this.config = nextConfig;
@@ -158,15 +171,11 @@ export class DefaultAgent {
                 if (nextClient === previousClient) {
                     previousClient.setModel(previousModel);
                 }
-                // Clear nextConfig registration only when the harness recreate
-                // actually succeeded (identityStore.write-failure path) — the
-                // harness throws on unknown id, so calling destroyAgent on the
-                // harness-recreate-failure path would short-circuit the rollback
-                // createAgent below.
-                if (nextConfigRegistered) {
-                    await this.harness.destroyAgent(this.agentId);
-                }
-                await this.harness.createAgent(this.agentId, this.projectRoot, previousClient, toHarnessConfig(previousConfig, previousOrgJwt));
+                // Re-apply the previous config through the same primitive. The harness re-diffs
+                // against its current state — if updateAgent partially applied (e.g. some MCP
+                // servers were already cycled), reverting via updateAgent restores them too.
+                const previousHooks = this.hooksForAgent?.(this.agentId, previousConfig) ?? {};
+                await this.harness.updateAgent(this.agentId, previousClient, toHarnessConfig(previousConfig, previousOrgJwt), { hooks: previousHooks });
             }
             catch {
                 // Ignore restoration errors; rethrow the original failure.

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

@@ -4,6 +4,7 @@ import type { ChatStreamResult } from '../types/events.js';
 import type { Message, MessagePart } from '../types/messages.js';
 import type { TelemetryEventCallback } from '../types/telemetry-events.js';
 import type { ToolResultInfo } from '../types/tools.js';
+import type { AgentHooks } from '../types/redaction.js';
 import type { AgentConfig, HarnessAgentConfig, StreamOptions } from './harness-config.js';
 import type { LLMGatewayClient } from '@salesforce/llm-gateway-sdk';
 export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly [1];
@@ -105,10 +106,24 @@ export interface AgentHarness {
      * @param projectRoot - Project folder the agent is allowed to manipulate files from.
      * @param llmGatewayClient - Pre-configured LLM gateway client for this agent.
      * @param config - Engine-facing agent configuration (org resolution omitted).
-     * @param options - Optional execution options, including abort signals.
+     * @param options - Optional execution options.
+     *   - `abortSignal` — caller-side cancellation; harnesses thread it
+     *     through long-running install work (rules load, MCP discovery, …).
+     *   - `hooks` — per-agent {@link AgentHooks} bag, resolved by the SDK
+     *     from `createAgentManager`'s `hooksForAgent` callback. The bag is
+     *     opaque to the SDK; harnesses MUST store it on per-agent state and
+     *     route each recognized hook to their native seam (Claude
+     *     `PostToolUse`, Mastra `processInputStep`). Harnesses MUST IGNORE
+     *     hook fields they do not recognize (forward-compat). Harnesses
+     *     MUST NOT swallow hook throws — exceptions MUST propagate on the
+     *     native error path so the original tool output never leaks to the
+     *     model. The SDK does not own fail-closed semantics; consumers
+     *     wrap their hook bodies in `try`/`catch` themselves when they
+     *     want a richer fail-closed substitute.
      */
     createAgent(agentId: string, projectRoot: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
         abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
     }): Promise<void>;
     /**
      * Destroy an agent and release its resources (MCP connections, workspace, memory).
@@ -122,6 +137,81 @@ export interface AgentHarness {
      * @returns `true` after a real removal.
      */
     destroyAgent(agentId: string): Promise<boolean>;
+    /**
+     * Apply a new configuration to a registered agent without recycling MCP
+     * clients whose `MCPServerConfig` is structurally equal to the
+     * currently-applied one.
+     *
+     * This is the load-bearing primitive behind `Agent.updateAgentConfig`'s
+     * "don't blow up live MCP clients on a model-only / instructions-only /
+     * org-connect change" contract. Pre-#541 the SDK called
+     * `destroyAgent` + `createAgent` here, which closed every MCP client and
+     * forced the model to wait through the discovery wave again. With
+     * `updateAgent` the SDK calls one method and the harness preserves
+     * unchanged servers in place.
+     *
+     * Implementors MUST:
+     *
+     * - throw `AgentSDKError(AGENT_NOT_FOUND)` on unknown `agentId`,
+     *   matching the rest of the cross-harness contract.
+     * - preserve the in-memory MCP client (and its discovered tool catalog)
+     *   for any server name whose config is `mcpServerConfigEqual` to the
+     *   currently-applied one. No transport teardown, no `tools/list`
+     *   re-run, no per-server discovery telemetry.
+     * - cycle (disconnect-then-reconnect) any server whose config differs.
+     * - disconnect any server present in the currently-applied config but
+     *   absent from the next config, removing it from
+     *   `getMcpServerInfo()`'s output.
+     * - connect any server present in the next config but absent from the
+     *   currently-applied one, running discovery the same way `createAgent`
+     *   would (background, non-blocking; failures land on
+     *   `McpServerState.error`, not as a thrown rejection).
+     * - apply non-MCP changes — `instructions`, `model`, `tools`, `skills`,
+     *   `rules`, harness-specific extra-config fields surviving via
+     *   `toHarnessConfig`'s spread — atomically with the MCP diff. After
+     *   this resolves, the agent's effective config is the one passed in.
+     * - be idempotent on a no-op call at the MCP layer: when the next
+     *   config's `mcpServers` is deep-equal (per `mcpServerConfigEqual`) to
+     *   the currently-applied one, no server is cycled, no `tools/list` is
+     *   re-run, and no per-server discovery telemetry fires. Implementors
+     *   MAY rebuild non-MCP state (e.g. Mastra reconstructs its `Agent`
+     *   unconditionally) — that work is local and cheap; correct no-op
+     *   detection across `orgJwt` rotation, hook-bag closures, and
+     *   harness-specific extra-config fields is not.
+     * - write per-server state incrementally so a subsequent `updateAgent`
+     *   call (e.g. SDK rollback against `previousConfig`) sees the harness's
+     *   current truth, not a snapshot from the start of the failed update.
+     *
+     * Implementors MUST NOT:
+     *
+     * - touch persisted thread / session state. Sessions are config-
+     *   independent — `Agent.updateAgentConfig` does not invalidate them.
+     * - dispose in-flight stream coordinators. In-flight turns continue
+     *   executing against the agent state captured at stream-start; the
+     *   next `stream()` after this resolves uses the new state.
+     * - mutate `AgentConfig` or persist anything to disk. Persistence is
+     *   the SDK's responsibility (`AgentIdentityStore.write` is gated by
+     *   `Agent.updateAgentConfig` after this method resolves).
+     *
+     * @param agentId - ID of the agent to update.
+     * @param llmGatewayClient - LLM gateway client bound to the next config's org / model.
+     * @param config - Engine-facing agent configuration to apply.
+     * @param options - Optional execution options.
+     *   - `abortSignal` — caller-side cancellation; harnesses thread it
+     *     through long-running update work (rules load, MCP discovery, …).
+     *   - `hooks` — per-agent {@link AgentHooks} bag, resolved by the SDK
+     *     from `createAgentManager`'s `hooksForAgent` callback against the
+     *     incoming `nextConfig`. Same semantics as `createAgent.options.hooks`:
+     *     opaque to the SDK; harnesses store it on per-agent state and
+     *     re-route each recognized hook to its native seam. The bag is
+     *     re-resolved on every `updateAgent` so consumers can vary hooks by
+     *     config (and so a rollback `updateAgent(previousConfig)` restores
+     *     the prior hook bag too).
+     */
+    updateAgent(agentId: string, llmGatewayClient: LLMGatewayClient, config?: HarnessAgentConfig, options?: {
+        abortSignal?: AbortSignal;
+        hooks?: AgentHooks;
+    }): Promise<void>;
     /**
      * List the IDs of all currently registered agents.
      */

package/dist/harness/always-active.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Tool-exposure policy entry shape consumed by both
+ * {@link MastraAgentConfig.toolSearch.alwaysActive} and
+ * {@link ClaudeAgentConfig.toolSearch.alwaysActive}.
+ *
+ * One entry covers three matching patterns:
+ *
+ * | Entry shape | Matches |
+ * | --- | --- |
+ * | `{ serverName: 'X' }` | every tool advertised by server `X` (post-discovery expansion) |
+ * | `{ serverName: 'X', toolName: 'Y' }` | exactly tool `Y` on server `X` |
+ * | `{ toolName: 'Y' }` | any tool named `Y`, **regardless of source** — built-ins, workspace tools, consumer-declared tools, AND any MCP server's tool surface |
+ *
+ * The `{ toolName }` pattern is intentionally broad — it's the consumer's
+ * escape hatch for "I want this tool always-active and I don't care where it
+ * comes from." The `{ serverName, toolName }` form is the precise version for
+ * when ambiguity matters.
+ *
+ * **Validation rule:** at least one of `serverName` or `toolName` must be
+ * present. An empty `{}` is rejected at config time via
+ * {@link validateAlwaysActiveEntry} — a typo should fail loud, not silently
+ * match nothing (and definitely not silently match everything).
+ *
+ * Lives on the harness public surface (`@salesforce/sfdx-agent-sdk/harness`)
+ * because it's harness-implementation shape that both production harnesses
+ * share. Ready to graduate to `AgentConfig.toolSearch` on the SDK contract
+ * surface once a third harness exercises it — same graduation pattern PR
+ * #563 established for `skillSearch`.
+ */
+export type AlwaysActiveEntry = {
+    serverName: string;
+    toolName?: string;
+} | {
+    serverName?: undefined;
+    toolName: string;
+};
+/**
+ * Throws on an entry whose `serverName` AND `toolName` are both absent. Both
+ * harness boundaries call this on every entry before reading it so a typo
+ * (`{}` / `{ severName: 'X' }` with a misspelled key) fails loud at config
+ * time rather than silently dropping the entry — or worse, silently matching
+ * nothing while looking like it should match everything.
+ */
+export declare function validateAlwaysActiveEntry(entry: AlwaysActiveEntry): void;
+/**
+ * Returns `true` when `(serverName, toolName)` matches at least one entry in
+ * `entries`. Pure / deterministic; harnesses call it per-tool when building
+ * their tool catalogs.
+ *
+ * - `{ serverName: 'X' }` matches every tool from server X.
+ * - `{ serverName: 'X', toolName: 'Y' }` matches only `Y` on `X`.
+ * - `{ toolName: 'Y' }` matches `Y` from any source (built-ins, workspace,
+ *   consumer-declared tools, every connected MCP server).
+ *
+ * For tools without a server (built-ins, in-process workspace), pass
+ * `serverName: undefined`. The `{ toolName }`-only entries match those;
+ * `{ serverName: 'X' }` and `{ serverName: 'X', toolName: ... }` entries do
+ * not.
+ */
+export declare function matchesAlwaysActive(entries: readonly AlwaysActiveEntry[] | undefined, serverName: string | undefined, toolName: string): boolean;

package/dist/harness/always-active.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+/**
+ * Throws on an entry whose `serverName` AND `toolName` are both absent. Both
+ * harness boundaries call this on every entry before reading it so a typo
+ * (`{}` / `{ severName: 'X' }` with a misspelled key) fails loud at config
+ * time rather than silently dropping the entry — or worse, silently matching
+ * nothing while looking like it should match everything.
+ */
+export function validateAlwaysActiveEntry(entry) {
+    const serverName = entry.serverName;
+    const toolName = entry.toolName;
+    if ((typeof serverName !== 'string' || serverName.length === 0) &&
+        (typeof toolName !== 'string' || toolName.length === 0)) {
+        throw new Error('AlwaysActiveEntry must declare at least one of `serverName` or `toolName` (received: ' +
+            JSON.stringify(entry) +
+            ')');
+    }
+}
+/**
+ * Returns `true` when `(serverName, toolName)` matches at least one entry in
+ * `entries`. Pure / deterministic; harnesses call it per-tool when building
+ * their tool catalogs.
+ *
+ * - `{ serverName: 'X' }` matches every tool from server X.
+ * - `{ serverName: 'X', toolName: 'Y' }` matches only `Y` on `X`.
+ * - `{ toolName: 'Y' }` matches `Y` from any source (built-ins, workspace,
+ *   consumer-declared tools, every connected MCP server).
+ *
+ * For tools without a server (built-ins, in-process workspace), pass
+ * `serverName: undefined`. The `{ toolName }`-only entries match those;
+ * `{ serverName: 'X' }` and `{ serverName: 'X', toolName: ... }` entries do
+ * not.
+ */
+export function matchesAlwaysActive(entries, serverName, toolName) {
+    if (!entries || entries.length === 0)
+        return false;
+    for (const entry of entries) {
+        const entryServer = entry.serverName;
+        const entryTool = entry.toolName;
+        if (entryServer !== undefined) {
+            if (entryServer !== serverName)
+                continue;
+            if (entryTool === undefined)
+                return true; // server-wide
+            if (entryTool === toolName)
+                return true; // exact server+tool
+            continue;
+        }
+        // entryServer === undefined ⇒ entryTool MUST be defined (validated upstream)
+        if (entryTool === toolName)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=always-active.js.map

package/dist/harness/public.d.ts

@@ -43,7 +43,10 @@
  * not "harness vs. consumer."
  */
 export type { AgentHarness, HarnessFactory, WithAgentConfig, ConfigOf } from './index.js';
+export type { AgentHooks } from '../types/redaction.js';
 export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+export { mcpServerConfigEqual } from '../mcp-config.js';
 export { HarnessBusOwner } from './harness-bus-owner.js';
 export { lowerStreamInput, type InputMessagePart } from './stream-input.js';
 export { GenSink } from './gen-sink.js';
+export { matchesAlwaysActive, validateAlwaysActiveEntry, type AlwaysActiveEntry } from './always-active.js';

package/dist/harness/public.js

@@ -3,8 +3,10 @@
  * See LICENSE.txt for license terms.
  */
 export { SUPPORTED_PROTOCOL_VERSIONS } from './agent-harness.js';
+export { mcpServerConfigEqual } from '../mcp-config.js';
 // ── Harness-implementation helpers ──────────────────────────────────
 export { HarnessBusOwner } from './harness-bus-owner.js';
 export { lowerStreamInput } from './stream-input.js';
 export { GenSink } from './gen-sink.js';
+export { matchesAlwaysActive, validateAlwaysActiveEntry } from './always-active.js';
 //# sourceMappingURL=public.js.map

package/dist/index.d.ts

@@ -2,10 +2,11 @@ export type { Message, MessagePart, ImagePart, FilePart } from './types/messages
 export type { ChatEvent, StartEvent, TextDeltaEvent, ReasoningDeltaEvent, ToolCallEvent, ToolApprovalRequestEvent, ToolResultEvent, StepStartEvent, StepFinishEvent, ErrorEvent, FinishEvent, ChatStreamResult, } from './types/events.js';
 export type { ToolDefinition, ToolCallInfo, ToolResultInfo } from './types/tools.js';
 export type { ContextUsage, FinishReason, UsageMetadata } from './types/usage.js';
+export type { AgentHooks, HooksForAgent, ToolResultRedactor, ToolResultRedactionInput, ToolResultRedactionResult, } from './types/redaction.js';
 export type { AgentConfig, HarnessAgentConfig, StreamOptions, ToolApprovalMode } from './harness/harness-config.js';
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
 export type { MCPConfiguration, MCPServerConfig, MCPStdioServerConfig, MCPRemoteServerConfig, McpServerInfo, McpServerErrorCategory, McpServerErrorDetail, McpToolInfo, McpToolAnnotations, } from './mcp-config.js';
-export { McpServerStatus } from './mcp-config.js';
+export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel } from '@salesforce/llm-gateway-sdk';
 export type { ClaudeModelOverrides } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';

package/dist/index.js

@@ -3,7 +3,7 @@
  * See LICENSE.txt for license terms.
  */
 export { DEFAULT_MAX_STEPS, resolveToolApprovalMode } from './harness/harness-config.js';
-export { McpServerStatus } from './mcp-config.js';
+export { McpServerStatus, mcpServerConfigEqual } from './mcp-config.js';
 export { Model, ModelName, createClaudeModel } from '@salesforce/llm-gateway-sdk';
 export { inferSfApiEnv, SfApiEnv } from '@salesforce/agentic-common';
 // ── Agent Layer ─────────────────────────────────────────────────────

package/dist/mcp-config.d.ts

@@ -34,25 +34,6 @@ export type MCPStdioServerConfig = {
     enabled?: boolean;
     /** Timeout in milliseconds for individual requests to the server. */
     timeout?: number;
-    /**
-     * Opt the server's tool surface out of the active runtime's tool-search
-     * deferral. When `true`, every tool advertised by this server is
-     * registered with the model up-front instead of sitting behind a
-     * search/load round-trip. Useful for small, discovery-critical surfaces
-     * (e.g. ≤ 10 tools the model needs to find without prompting). Default
-     * (`undefined` / `false`): tools may be deferred when the active runtime
-     * enables tool search.
-     *
-     * **Harness behavior:**
-     * - **Claude harness** — sets `_meta['anthropic/alwaysLoad'] = true` on
-     *   each tool the bridge forwards, equivalent to
-     *   `defer_loading: false` on the API. Skill-bridge and consumer-tool
-     *   tools are always-load regardless of this flag (see
-     *   `@salesforce/sfdx-agent-harness-claude` ARCHITECTURE.md).
-     * - **Mastra harness** — no-op; Mastra eager-loads MCP tools at every
-     *   turn already, so there's no deferral to opt out of.
-     */
-    alwaysLoad?: boolean;
 };
 /** MCP server accessible over HTTP/SSE at a remote URL. */
 export type MCPRemoteServerConfig = {
@@ -91,11 +72,6 @@ export type MCPRemoteServerConfig = {
         /** Factor by which the reconnection delay grows after each attempt. Default `1.5`. */
         reconnectionDelayGrowFactor?: number;
     };
-    /**
-     * Opt the server's tool surface out of the active runtime's tool-search
-     * deferral. See {@link MCPStdioServerConfig.alwaysLoad}.
-     */
-    alwaysLoad?: boolean;
 };
 /** Connection status of a single MCP server. */
 export declare enum McpServerStatus {
@@ -260,6 +236,36 @@ export type McpServerErrorDetail = {
      */
     retriable: boolean;
 };
+/**
+ * Structural deep-equality predicate over {@link MCPServerConfig}. Returns
+ * `true` when two configs would behave identically at the harness layer —
+ * meaning a harness handed `b` while currently bound to `a` MUST be free to
+ * preserve its existing transport, client instance, and discovered tool
+ * catalog without cycling.
+ *
+ * Used by harnesses inside `AgentHarness.updateAgent` to decide which MCP
+ * servers to preserve vs. cycle when an agent's config changes. Exported so
+ * both production harnesses use the same equality and a third harness can
+ * adopt it without duplicating the rules.
+ *
+ * **Equality rules:**
+ * - Both `undefined` ⇒ `true`. Exactly one `undefined` ⇒ `false`.
+ * - `type` mismatch ⇒ `false` (the discriminated union splits stdio vs remote).
+ * - `enabled: undefined` and `enabled: true` compare equal — both type docs
+ *   declare `true` as the default.
+ * - Stdio: structural compare on `command`, `args` (order-sensitive),
+ *   `env` (key-order-insensitive), `timeout`.
+ * - Remote: `url` is compared via `String(url)` so `URL` instances and
+ *   strings round-trip; `headers` (key-order-insensitive); `timeout`,
+ *   `reconnectionOptions` (field-wise).
+ *
+ * Two configs that pass this predicate but produce different runtime tools
+ * (e.g. an upstream stdio server whose binary was overwritten on disk) are
+ * NOT detected here — the predicate compares declared config, not runtime
+ * state. Use `Agent.reconnectMcpServer(name)` to force a per-server cycle in
+ * that case.
+ */
+export declare function mcpServerConfigEqual(a: MCPServerConfig | undefined, b: MCPServerConfig | undefined): boolean;
 /** Runtime status of a configured MCP server, including its discovered tools. */
 export type McpServerInfo = {
     name: string;

package/dist/mcp-config.js

@@ -17,4 +17,102 @@ export var McpServerStatus;
      */
     McpServerStatus["Reconnecting"] = "reconnecting";
 })(McpServerStatus || (McpServerStatus = {}));
+/**
+ * Structural deep-equality predicate over {@link MCPServerConfig}. Returns
+ * `true` when two configs would behave identically at the harness layer —
+ * meaning a harness handed `b` while currently bound to `a` MUST be free to
+ * preserve its existing transport, client instance, and discovered tool
+ * catalog without cycling.
+ *
+ * Used by harnesses inside `AgentHarness.updateAgent` to decide which MCP
+ * servers to preserve vs. cycle when an agent's config changes. Exported so
+ * both production harnesses use the same equality and a third harness can
+ * adopt it without duplicating the rules.
+ *
+ * **Equality rules:**
+ * - Both `undefined` ⇒ `true`. Exactly one `undefined` ⇒ `false`.
+ * - `type` mismatch ⇒ `false` (the discriminated union splits stdio vs remote).
+ * - `enabled: undefined` and `enabled: true` compare equal — both type docs
+ *   declare `true` as the default.
+ * - Stdio: structural compare on `command`, `args` (order-sensitive),
+ *   `env` (key-order-insensitive), `timeout`.
+ * - Remote: `url` is compared via `String(url)` so `URL` instances and
+ *   strings round-trip; `headers` (key-order-insensitive); `timeout`,
+ *   `reconnectionOptions` (field-wise).
+ *
+ * Two configs that pass this predicate but produce different runtime tools
+ * (e.g. an upstream stdio server whose binary was overwritten on disk) are
+ * NOT detected here — the predicate compares declared config, not runtime
+ * state. Use `Agent.reconnectMcpServer(name)` to force a per-server cycle in
+ * that case.
+ */
+export function mcpServerConfigEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.type !== b.type)
+        return false;
+    if ((a.enabled ?? true) !== (b.enabled ?? true))
+        return false;
+    if (a.timeout !== b.timeout)
+        return false;
+    if (a.type === 'stdio' && b.type === 'stdio') {
+        if (a.command !== b.command)
+            return false;
+        if (!arraysEqual(a.args, b.args))
+            return false;
+        if (!recordsEqual(a.env, b.env))
+            return false;
+        return true;
+    }
+    if (a.type === 'remote' && b.type === 'remote') {
+        if (String(a.url) !== String(b.url))
+            return false;
+        if (!recordsEqual(a.headers, b.headers))
+            return false;
+        if (!reconnectionOptionsEqual(a.reconnectionOptions, b.reconnectionOptions))
+            return false;
+        return true;
+    }
+    return false;
+}
+function arraysEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return (a?.length ?? 0) === (b?.length ?? 0);
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return false;
+    }
+    return true;
+}
+function recordsEqual(a, b) {
+    if (a === b)
+        return true;
+    const aKeys = a ? Object.keys(a) : [];
+    const bKeys = b ? Object.keys(b) : [];
+    if (aKeys.length !== bKeys.length)
+        return false;
+    for (const k of aKeys) {
+        if (!Object.prototype.hasOwnProperty.call(b ?? {}, k))
+            return false;
+        if (a[k] !== b[k])
+            return false;
+    }
+    return true;
+}
+function reconnectionOptionsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return !a && !b;
+    return (a.maxRetries === b.maxRetries &&
+        a.initialReconnectionDelay === b.initialReconnectionDelay &&
+        a.maxReconnectionDelay === b.maxReconnectionDelay &&
+        a.reconnectionDelayGrowFactor === b.reconnectionDelayGrowFactor);
+}
 //# sourceMappingURL=mcp-config.js.map

package/dist/types/redaction.d.ts

@@ -0,0 +1,171 @@
+import type { AgentConfig } from '../harness/harness-config.js';
+/**
+ * Sync-or-async callback the harness invokes for every tool result before it
+ * enters the model's context. The redactor inspects the upstream output and
+ * either replaces it (returning `{ output }`) or passes it through unchanged
+ * (returning `undefined`).
+ *
+ * Wired per-agent via {@link HooksForAgent} on `createAgentManager`; the SDK
+ * surfaces it inside the harness through {@link AgentHooks.onToolResult} on
+ * `AgentHarness.createAgent`'s `options.hooks` bag. A single registration
+ * covers built-in tools (`Bash`, `Read`, `Edit`, …), MCP tools, and
+ * consumer-executed tools declared via {@link AgentConfig.tools}.
+ *
+ * ### Why this lives in the harness layer
+ *
+ * Once a tool result reaches the SDK boundary the model has already seen it —
+ * any value can then be echoed in the reply, routed into a later tool call
+ * (`Bash` arg, file write), or sent to provider logs. Redaction has to fire
+ * INSIDE the engine, before the result is folded into the model's next
+ * request. The SDK exposes a harness-agnostic shape; each harness wires its
+ * native seam (Claude Agent SDK `PostToolUse` hook,
+ * Mastra `processInputStep`).
+ *
+ * ### Audit / preserving the original
+ *
+ * The redactor sees the unmodified `output` at the call site. Consumers that
+ * need an audit trail of the original value MUST log it themselves before
+ * returning the redaction. The SDK does not put the original on its telemetry
+ * bus or persist it anywhere — that would defeat the point.
+ *
+ * ### Throw policy is the consumer's
+ *
+ * The SDK does not own fail-closed semantics. If the redactor throws, the
+ * harness re-throws on its native error path: Claude routes through the
+ * Claude Agent SDK's `PostToolUse` hook-error path (which synthesizes a
+ * `tool_result(is_error=true)`); Mastra propagates from `processInputStep`
+ * and surfaces as an `error` ChatEvent on the consumer's eventStream.
+ * Consumers requiring a richer fail-closed substitute wrap their redactor's
+ * body in `try`/`catch` themselves — see the SDK README's
+ * "Tool-Result Redaction" section for the recommended boilerplate.
+ *
+ * ### Tool-shape constraints
+ *
+ * The harness does NOT validate that the replacement `output` has the same
+ * shape as the original — the redactor knows what tool it is redacting and
+ * is responsible for honoring that tool's expected return shape. Notable
+ * cases:
+ *
+ * - **Claude built-in `Bash`** — the replacement MUST keep the
+ *   `{ stdout, stderr, interrupted }` shape. A bare-string return is rejected
+ *   by the Claude Agent SDK and the original leaks.
+ * - **MCP tools** — the replacement MUST be a valid MCP `CallToolResult`
+ *   shape (`{ content: [...], isError? }`).
+ * - **Consumer-executed tools** — replacement passes through unchanged to
+ *   `submitToolResult`, so any shape the consumer accepts is fine.
+ *
+ * ### Performance
+ *
+ * Both harnesses skip their per-result hook entirely when
+ * `hooks.onToolResult` is undefined, so the no-op overhead is exactly zero.
+ * When set, both engines await the redactor (sync redactors collapse to a
+ * microtask).
+ *
+ * @example
+ * ```ts
+ * const redactor: ToolResultRedactor = ({ toolName, output, isError }) => {
+ *     // Caller-side audit (consumer's responsibility — SDK does not log originals).
+ *     auditLog.write({ toolName, originalLength: JSON.stringify(output).length });
+ *
+ *     // Bash needs its native shape preserved.
+ *     if (toolName === 'Bash') {
+ *         const bash = output as { stdout: string; stderr: string; interrupted: boolean };
+ *         return { output: { ...bash, stdout: scrub(bash.stdout), stderr: scrub(bash.stderr) } };
+ *     }
+ *
+ *     // Other tools: walk the structured output and scrub field-by-field.
+ *     return { output: scrubDeep(output) };
+ * };
+ *
+ * const manager = await createAgentManager(storage, factory, {
+ *     hooksForAgent: () => ({ onToolResult: redactor }),
+ * });
+ * ```
+ */
+export type ToolResultRedactor = (input: ToolResultRedactionInput) => ToolResultRedactionResult | Promise<ToolResultRedactionResult>;
+/**
+ * Inputs the harness hands the {@link ToolResultRedactor} for each tool
+ * result. Carries enough identity for the redactor to decide what (if
+ * anything) to redact and to attribute audit log entries.
+ */
+export type ToolResultRedactionInput = {
+    /** Agent that produced the tool result. */
+    agentId: string;
+    /** Conversation thread the result belongs to. */
+    threadId: string;
+    /** Stable id linking this result to the originating `tool-call` event. */
+    toolCallId: string;
+    /** Tool name the model invoked. Built-in / consumer / namespaced MCP form depends on the harness. */
+    toolName: string;
+    /**
+     * Originating MCP server when the tool came from an MCP catalog.
+     * `undefined` for built-ins, consumer-executed tools, and Mastra workspace
+     * tools. Mirrors the enrichment on {@link ToolResultEvent.serverName}.
+     */
+    serverName?: string;
+    /**
+     * Raw upstream output, exactly as the engine received it. The redactor
+     * MUST treat this as input only — mutating it is undefined behavior.
+     */
+    output: unknown;
+    /** `true` when the tool execution failed (engine flagged the result as an error). */
+    isError: boolean;
+};
+/**
+ * Return value from a {@link ToolResultRedactor} invocation.
+ *
+ * - `{ output }` — replace the original with this value.
+ * - `undefined` — pass the original through unchanged.
+ *
+ * The function signature already permits "no return" (an arrow body that
+ * doesn't `return` resolves to `undefined`), so a separate `void` variant
+ * isn't needed in the value-type union.
+ *
+ * The replacement shape MUST match what the originating tool produces. See
+ * the tool-shape notes on {@link ToolResultRedactor} for the harness-specific
+ * constraints (notably the Claude `Bash` `{ stdout, stderr, interrupted }`
+ * requirement).
+ */
+export type ToolResultRedactionResult = {
+    output: unknown;
+} | undefined;
+/**
+ * Per-agent hook bag the SDK resolves once per agent install / update via
+ * {@link HooksForAgent} and threads through to the harness on
+ * `AgentHarness.createAgent`'s `options.hooks`. Today the bag carries one
+ * field; the shape is open so future hooks (e.g. `onToolCall`, `onStep`)
+ * can be added without churning `*HarnessFactoryConfig`s.
+ *
+ * Harnesses MUST treat this object as opaque: store it on per-agent state,
+ * route the hooks they recognize to their native seam, and IGNORE unknown
+ * fields (forward-compat). Harnesses MUST NOT swallow hook throws — an
+ * exception from a hook MUST propagate on the harness's native error path
+ * so the original value never leaks to the model.
+ *
+ * The SDK never reads, persists, or surfaces this bag on its telemetry bus.
+ */
+export type AgentHooks = {
+    /**
+     * Optional redactor invoked for every tool result before it enters the
+     * model's context. See {@link ToolResultRedactor}. Each harness routes
+     * this to its native seam (Claude `PostToolUse`, Mastra
+     * `processInputStep`); the SDK does not enforce fail-closed semantics.
+     */
+    onToolResult?: ToolResultRedactor;
+};
+/**
+ * Resolves a per-agent {@link AgentHooks} bag from the agent's id and the
+ * config the SDK currently has on file for that agent. Invoked by
+ * `AgentManager` once per agent install (`createAgent`, boot-time restore,
+ * `Agent.updateAgentConfig`); the resolved bag is handed to
+ * `AgentHarness.createAgent`'s `options.hooks`.
+ *
+ * The callback is sync — the SDK does not await. Consumers needing async
+ * setup (e.g. remote feature flags) pre-resolve before constructing the
+ * manager.
+ *
+ * Consumers with one global policy ignore both arguments and return the
+ * same bag every time; consumers wanting per-agent variation branch on
+ * `agentId` or fields of `config`.
+ */
+export type HooksForAgent = (agentId: string, config: AgentConfig) => AgentHooks;

package/dist/types/redaction.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+export {};
+//# sourceMappingURL=redaction.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/sfdx-agent-sdk",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Harness-agnostic agentic infrastructure for Salesforce developer experience tooling",
   "type": "module",
   "main": "dist/index.js",
@@ -36,31 +36,32 @@
     "dist",
     "!dist/**/*.map",
     "!dist/test",
+    "CHANGELOG.md",
     "LICENSE.txt"
   ],
   "dependencies": {
-    "@salesforce/agentic-common": "0.8.0",
-    "@salesforce/llm-gateway-sdk": "0.12.0"
+    "@salesforce/agentic-common": "0.9.0",
+    "@salesforce/llm-gateway-sdk": "0.13.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@salesforce/sfdx-agent-harness-claude": "0.12.0",
-    "@salesforce/sfdx-agent-harness-mastra": "0.15.0",
-    "@types/node": "^22.19.17",
-    "@vitest/coverage-istanbul": "^4.1.7",
-    "@vitest/eslint-plugin": "^1.6.17",
-    "eslint": "^10.4.0",
+    "@salesforce/sfdx-agent-harness-claude": "0.13.0",
+    "@salesforce/sfdx-agent-harness-mastra": "0.16.0",
+    "@types/node": "^22.19.19",
+    "@vitest/coverage-istanbul": "^4.1.8",
+    "@vitest/eslint-plugin": "^1.6.19",
+    "eslint": "^10.4.1",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-import-resolver-typescript": "^4.4.4",
+    "eslint-import-resolver-typescript": "^4.4.5",
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^18.0.1",
     "globals": "^17.6.0",
-    "lint-staged": "^17.0.5",
+    "lint-staged": "^17.0.7",
     "prettier": "^3.8.3",
     "rimraf": "^6.1.3",
-    "tsx": "^4.22.3",
+    "tsx": "^4.22.4",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.59.4",
+    "typescript-eslint": "^8.60.1",
     "vitest": "^4.1.7"
   },
   "engines": {