@salesforce/sfdx-agent-sdk 0.15.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

@@ -47,7 +47,8 @@ for await (const event of eventStream) {
     process.stdout.write(event.text);
   } else if (event.type === 'error') {
     console.error(event.error.message);
-    break;
+    // Don't break — the SDK invariant guarantees a synthetic
+    // `FinishEvent('error')` follows; the loop exits naturally next tick.
   }
 }
 
@@ -58,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:
@@ -152,31 +158,33 @@ 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.                                       |
-| `submitToolResult`  | `(toolResult: ToolResultInfo) => Promise<ChatStreamResult>`                           | Return a consumer-executed tool result and resume the stream.                 |
-| `approveToolCall`   | `(toolCallId: string, options?: { remember?: boolean }) => Promise<ChatStreamResult>` | Approve a pending tool call.                                                  |
-| `declineToolCall`   | `(toolCallId: string) => Promise<ChatStreamResult>`                                   | Decline a pending tool call.                                                  |
-| `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. 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.                                                                         |
 
 ### `ChatStreamResult`
 
-Returned by `chat()`, `submitToolResult()`, `approveToolCall()`, and `declineToolCall()`.
+Returned by `chat()`. The single `eventStream` covers the entire chat turn — including post-resume events from
+`submitToolResult` / `approveToolCall` / `declineToolCall`. Settle methods return `Promise<void>`; the consumer keeps
+iterating the same `eventStream` until it sees a terminal `finish` event.
 
-| Property      | Type                        | Description                             |
-| ------------- | --------------------------- | --------------------------------------- |
-| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream.            |
-| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens. |
+| Property      | Type                        | Description                                                                  |
+| ------------- | --------------------------- | ---------------------------------------------------------------------------- |
+| `eventStream` | `AsyncGenerator<ChatEvent>` | Full lifecycle event stream for the turn (one stream per `chat()` call).     |
+| `textStream`  | `AsyncGenerator<string>`    | Convenience stream of text-only tokens, derived from the same `eventStream`. |
 
 ### `ChatEvent`
 
@@ -237,7 +245,6 @@ type MCPStdioServerConfig = {
   env?: Record<string, string>;
   enabled?: boolean;
   timeout?: number;
-  alwaysLoad?: boolean;
 };
 
 // Remote server (HTTP/SSE)
@@ -253,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
@@ -560,17 +564,17 @@ try {
 
 #### Streaming method failures
 
-The four streaming methods on `ChatSession` — `chat()`, `submitToolResult()`, `approveToolCall()`, and
-`declineToolCall()` — share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
+`chat()` opens a turn; `submitToolResult()` / `approveToolCall()` / `declineToolCall()` are control messages on the
+existing turn. All four share a single failure contract. Subscribers registered via `subscribe()` are guaranteed to
 receive a terminal event for every turn:
 
-- **Pre-stream failure** (the harness rejects before producing a stream): subscribers receive an `ErrorEvent` followed
-  by a `FinishEvent(finishReason: 'error')`, and the returned promise then rejects with the original error. Wrap the
-  call in `try/catch` if you need to handle this in the caller.
-- **In-stream failure** (the stream yields an `error` event or the underlying generator throws): the `eventStream`
-  yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was already
-  emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The returned promise resolves normally;
-  iterate the stream to observe the failure.
+- **Pre-stream failure** (the harness rejects before producing a stream, or a settle call rejects before it routes the
+  decision): subscribers receive an `ErrorEvent` followed by a `FinishEvent(finishReason: 'error')`, and the returned
+  promise then rejects with the original error. Wrap the call in `try/catch` if you need to handle this in the caller.
+- **In-stream failure** (the active `eventStream` yields an `error` event or the underlying generator throws): the
+  stream yields the `ErrorEvent` (synthesizing one from a thrown exception if needed) and, if no `FinishEvent` was
+  already emitted, appends a synthetic `FinishEvent(finishReason: 'error')` at the end. The originating `chat()` promise
+  resolves normally; iterate the stream to observe the failure.
 - **Calling a disposed session** throws `AgentSDKError('DISPOSED')` synchronously without notifying subscribers.
 
 ### MCP Server Configuration
@@ -613,99 +617,286 @@ reparsing namespaced tool names. `annotations` is `undefined` when the source di
 `requireToolApproval` accepts a `boolean` (`true` is shorthand for `'serial'`) or one of the mode strings exposed via
 the `ToolApprovalMode` type alias (`'serial' | 'batch'`):
 
-- **`'serial'`** (the safe default) — each stream surfaces one `tool-approval-request` at a time. The next request, if
-  any, appears on the continuation stream returned by `approveToolCall` / `declineToolCall`. Works with both consumer
-  iterator patterns below.
-- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests surface on the same stream so
-  the consumer can render a batch-approval card. **Pattern A iterators only** — a `break`-on-first-approval loop will
-  miss the subsequent approvals and hang the chat. Opt into `'batch'` only after the consumer iterator collects all
-  approvals before settling.
+- **`'serial'`** (the safe default) — `tool-approval-request` events surface one at a time. The next request (if any)
+  arrives later on the same `eventStream` after the consumer settles the current one.
+- **`'batch'`** — when the model emits parallel `tool_use` blocks, all approval-requests for that batch surface on the
+  same `eventStream` together, so the consumer can render a batch-approval card. The consumer must gather all approvals
+  before settling — a `break`-on-first-approval loop will hang the turn because Mastra/Claude won't continue emitting
+  tool-results until the consumer has settled the entire batch.
 
 The SDK also exports `resolveToolApprovalMode(value)` — the canonical
 `boolean | ToolApprovalMode | undefined → ToolApprovalMode | undefined` normalizer harness implementations should use to
 dispatch (`undefined` / `false` → `undefined`, `true` → `'serial'`, strings pass through). Reject unknown strings via
 `throw` instead of reimplementing the boolean-vs-string branch — the helper's defensive throw catches `as any` consumers
-passing invalid values that would otherwise silently degrade to "approval gating on but no broker allocated."
+passing invalid values that would otherwise silently degrade to "approval gating on but no coordinator allocated."
+
+#### Single stream per turn
+
+Issue [#529](https://github.com/forcedotcom/agentic-dx/issues/529) settled the harness contract: **one `eventStream` per
+chat turn.** Settle calls (`approveToolCall` / `declineToolCall` / `submitToolResult`) return `Promise<void>` and behave
+as control messages on the existing turn; the post-resume events (`tool-result`, follow-up `text-delta`, `step-finish`,
+terminal `finish`) flow through the **same** `eventStream` the `chat()` call returned. The consumer should iterate that
+one stream until it sees a terminal `finish` event, calling `approveToolCall` / `declineToolCall` / `submitToolResult`
+in-line as approval-requests / consumer-tool-calls arrive.
 
-> **Glossary:** _Pattern A_ = "collect-all-then-settle" (iterate until natural park, gather all approval-requests, then
-> call `approveToolCall`/`declineToolCall`). _Pattern B_ = "return-on-first-approval" (settle the first approval
-> mid-iteration, then re-iterate the continuation stream). `'serial'` works with either; `'batch'` requires Pattern A.
+#### Pattern: settle in-line, continue iterating
 
-#### Pattern B — return on first approval (works with `'serial'`)
+The same shape works for `'serial'` and `'batch'` mode:
 
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
-  requireToolApproval: true, // or 'serial'
+  requireToolApproval: true, // or 'serial' / 'batch'
 });
 
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
     const approved = await promptUser(event);
-    const continuation = approved
-      ? await session.approveToolCall(event.toolCall.toolCallId)
-      : await session.declineToolCall(event.toolCall.toolCallId);
-    for await (const e of continuation.eventStream) {
-      // process continuation
+    if (approved) {
+      await session.approveToolCall(event.toolCall.toolCallId);
+    } else {
+      await session.declineToolCall(event.toolCall.toolCallId);
     }
-    break; // safe: serial mode surfaces at most one approval per stream
+    // Do NOT break — keep iterating; tool-result and follow-up text arrive on the same stream.
+  } else if (event.type === 'tool-call' && event.serverName === undefined && isConsumerTool(event.toolName)) {
+    // Consumer-executed tool: run locally, return the result via submitToolResult.
+    const result = await runLocally(event.args);
+    await session.submitToolResult({
+      toolCallId: event.toolCallId,
+      toolName: event.toolName,
+      result,
+    });
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
-#### Pattern A — collect all approvals, then settle (required for `'batch'`)
+#### Pattern variant: batch-collect approvals before settling
+
+Same single-stream loop, just gather the batch before deciding (useful for "approve these N tools?" UI cards under
+`requireToolApproval: 'batch'`):
 
 ```typescript
 const { eventStream } = await session.chat('Run the deployment', {
   requireToolApproval: 'batch',
 });
 
-const requests: ToolApprovalRequestEvent[] = [];
+const pendingBatch: ToolApprovalRequestEvent[] = [];
+
 for await (const event of eventStream) {
   if (event.type === 'tool-approval-request') {
-    requests.push(event); // do NOT break — collect the whole parallel batch
+    pendingBatch.push(event);
+    // Heuristic: settle the batch on a quiet window OR after the expected count.
+    // Don't break — the harness needs us to settle so it can continue.
+    continue;
   }
-  if (event.type === 'finish' || event.type === 'error') break;
-}
-
-// Render a batch-approval card; settle each decision.
-const decisions = await promptUserForBatch(requests);
-let continuation: ChatStreamResult | undefined;
-for (const event of requests) {
-  continuation = decisions.get(event.toolCall.toolCallId)
-    ? await session.approveToolCall(event.toolCall.toolCallId)
-    : await session.declineToolCall(event.toolCall.toolCallId);
-}
-if (continuation) {
-  for await (const e of continuation.eventStream) {
-    // process the model's follow-up turn
+  if (event.type === 'tool-call') {
+    // The harness emits `tool-approval-request` BEFORE `tool-call` in batch mode.
+    // Once we see a tool-call, the batch for this assistant message is complete.
+    if (pendingBatch.length > 0) {
+      const decisions = await promptUserForBatch(pendingBatch);
+      await Promise.all(
+        pendingBatch.map((req) =>
+          decisions.get(req.toolCall.toolCallId)
+            ? session.approveToolCall(req.toolCall.toolCallId)
+            : session.declineToolCall(req.toolCall.toolCallId),
+        ),
+      );
+      pendingBatch.length = 0;
+    }
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
-#### `textStream` and `'batch'` mode
-
-`ChatStreamResult.textStream` is empty on the initial stream when `requireToolApproval: 'batch'` surfaces approval
-requests — the model emitted `tool_use` blocks, not text. Read text deltas from the continuation stream returned by
-`approveToolCall` / `declineToolCall` (the model's follow-up turn after tool execution).
+> **AsyncIterator gotcha:** the `for await` loop is the supported way to drain `eventStream`. If you instead drive the
+> iterator manually (`iter.next()`), call **at most one** `next()` at a time and `await` the result before the next
+> call. Calling `iter.next()` twice without awaiting the first orphans the first request — JS settles `.next()` calls
+> FIFO, so the next yielded value satisfies the orphaned request and is invisible to the caller. Stick to `for await`
+> unless you have a specific reason not to.
 
 ### Consumer-Executed Tools
 
+Tools declared via `AgentConfig.tools` (no `execute` function) run on the consumer side: the model emits a `tool-call`
+event, the consumer runs the tool locally, then calls `session.submitToolResult(...)` to feed the result back.
+`submitToolResult` returns `Promise<void>`; the model's follow-up turn (and any subsequent `tool-call`s) flows through
+the same `eventStream`:
+
 ```typescript
+const { eventStream } = await session.chat('Look up the customer record for tenant T-42.');
+
 for await (const event of eventStream) {
-  if (event.type === 'tool-call' && event.toolName === 'my-tool') {
+  if (event.type === 'tool-call' && event.toolName === 'lookup_customer') {
     const result = await runLocally(event.args);
-    const continuation = await session.submitToolResult({
+    await session.submitToolResult({
       toolCallId: event.toolCallId,
       toolName: event.toolName,
       result,
     });
-    for await (const e of continuation.eventStream) {
-      // process continuation
-    }
+    // Do NOT break — the model's follow-up turn (text, more tool-calls, finish) arrives on the same stream.
+  } else if (event.type === 'text-delta') {
+    process.stdout.write(event.text);
+  } else if (event.type === 'finish') {
+    // Don't break on `'error'` directly — the SDK invariant guarantees an
+    // `error` event is followed by a synthetic `FinishEvent('error')` so
+    // the loop exits naturally on the next iteration. Breaking on `error`
+    // would finalize the iterator before the synthetic `finish` lands and
+    // bypass any per-turn cleanup the harness wires onto the source's
+    // close/return path.
+    break;
   }
 }
 ```
 
+When `requireToolApproval: true` is also set, consumer-executed tools bypass the approval gate by construction (per
+`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`
@@ -843,15 +1034,37 @@ The SDK ships no harness implementation. Consumers pick one by passing a `Harnes
 [`@salesforce/sfdx-agent-harness-mastra`](../sfdx-agent-harness-mastra); additional harnesses can ship as independent
 npm packages that depend on this SDK as a `peerDependency`.
 
-Harness authors implement two interfaces and can compose one helper class, all exported from this package:
-
-| Export                        | Role                                                                                                                                                                                                                                  |
-| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `HarnessFactory<H>`           | Construct a harness of type `H` bound to a storage root. Declares `harnessId` and `protocolVersion`. Default `H = AgentHarness`.                                                                                                      |
-| `AgentHarness`                | Runtime contract: agent / thread / stream / tool / message lifecycle. Declares its own `harnessId` and `protocolVersion`.                                                                                                             |
-| `SUPPORTED_PROTOCOL_VERSIONS` | Readonly list of harness protocol versions this SDK accepts. `createAgentManager` checks both the factory and the constructed harness.                                                                                                |
-| `HarnessBusOwner`             | Composition helper owning telemetry + log buses with `dispose()` semantics. Reuse it instead of reimplementing bus plumbing.                                                                                                          |
-| `lowerStreamInput`            | 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. |
+### Two import surfaces
+
+This package publishes two ESM entry points:
+
+- **`@salesforce/sfdx-agent-sdk`** — consumer surface. Everything an application calling `createAgentManager` needs:
+  `Agent`, `ChatSession`, `ChatEvent`, `MessagePart`, `AgentConfig`, `AgentSDKError`, etc. The harness contract
+  interfaces (`AgentHarness`, `HarnessFactory`, `WithAgentConfig`, `ConfigOf`) also appear here as **type-only**
+  references so consumer code can write `AgentManager<H extends AgentHarness>` without reaching into the
+  harness-implementation surface.
+- **`@salesforce/sfdx-agent-sdk/harness`** — harness-implementation surface. Harness authors import the contract types
+  and the helpers from here. Consumer applications cannot reach these symbols from the bare specifier — the bundler / TS
+  resolver errors at the import site, which is the right outcome for any consumer who reaches for a primitive they don't
+  need.
+
+> **Build-tool requirement:** the `/harness` subpath is resolved via the `package.json` `exports` field, which requires
+> `moduleResolution: "node16" | "nodenext" | "bundler"` in `tsconfig.json`. Legacy `"node"` resolution silently won't
+> 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.                                                                                                                             |
+| `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:
 
@@ -861,7 +1074,7 @@ import {
   type HarnessFactory,
   HarnessBusOwner,
   SUPPORTED_PROTOCOL_VERSIONS,
-} from '@salesforce/sfdx-agent-sdk';
+} from '@salesforce/sfdx-agent-sdk/harness';
 
 class MyHarness implements AgentHarness {
   readonly harnessId = 'my-harness';