@salesforce/sfdx-agent-harness-claude 0.11.0 → 0.13.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `@salesforce/sfdx-agent-harness-claude` are documented in this file.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.13.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-claude,harness-mastra**: align event/log payload shapes ([#562](https://github.com/forcedotcom/agentic-dx/pull/562))
+
+### Chores
+- **harness-claude,harness-mastra**: re-enable monorepoLintPack at four offender sites ([#561](https://github.com/forcedotcom/agentic-dx/pull/561))
+- **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))
+- **deps**: bump @anthropic-ai/claude-agent-sdk from 0.3.148 to 0.3.160 ([#540](https://github.com/forcedotcom/agentic-dx/pull/540))
+

package/README.md

@@ -36,6 +36,10 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 | `ClaudeHarnessFactory`                           | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                               |
 | `ClaudeHarnessFactoryConfig`                     | interface | Configuration for `ClaudeHarnessFactory` (`resolver`, `permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `bypassApprovalTools`).                   |
 | `ClaudeHarnessPermissionMode`                    | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                          |
+| `ClaudeAgentHarness`                             | type      | Branded `AgentHarness` subtype carrying the Claude-specific config inference. Inferred at `manager.createAgent` automatically — annotation rarely needed.            |
+| `ClaudeAgentConfig`                              | type      | `AgentConfig` extended with Claude-only fields (`skillSearch`, `toolSearch`).                                                                                        |
+| `ClaudeSkillSearchConfig`                        | type      | Shape of `ClaudeAgentConfig.skillSearch` (`topK`). Opts the in-process `skill_bridge` MCP server into search-on-demand mode.                                         |
+| `ClaudeToolSearchConfig`                         | type      | Shape of `ClaudeAgentConfig.toolSearch` (`alwaysActive`). Stamps `_meta['anthropic/alwaysLoad']` on matching tools so they bypass Claude tool-search deferral.       |
 | `ClaudeTransportResolver`                        | interface | Strategy for resolving transport env, auth, and native model ID for the subprocess.                                                                                  |
 | `ClaudeTransportResolverResult`                  | type      | Return type of `ClaudeTransportResolver.resolve()` (`env` + `nativeModelId`).                                                                                        |
 | `ClaudeQueryDefaults`                            | type      | Consumer-overridable defaults for the Claude `query()` call (excludes `model`).                                                                                      |
@@ -57,6 +61,74 @@ provide. For human-in-the-loop gating, set `StreamOptions.requireToolApproval: t
 installs a `PreToolUse` SDK hook for that turn that gates every tool call through the SDK's `tool-approval-request` flow
 regardless of the factory-pinned permission mode.
 
+### Skill search
+
+`AgentConfig.skills` is a cross-harness field; both Mastra and Claude surface configured skills to the model. By default
+the Claude harness exposes the catalog via the in-process `skill_bridge` MCP server's `load_skill` tool, whose
+description enumerates skill names and descriptions so the model can pick directly. That shape is the right call at
+small N (no extra round-trip).
+
+For larger catalogs, set `ClaudeAgentConfig.skillSearch` to switch the same in-process server into a
+`search_skills(query) → topK` + `load_skill(name)` shape. The catalog is dropped from `load_skill`'s description so it
+never sits in the prompt at rest, and the model is forced to discover skills via search. The opt-in field mirrors
+`MastraAgentConfig.skillSearch` so cross-harness consumers configure the on-demand path the same way on both harnesses.
+
+```ts
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  skills: ['/path/to/skills'],
+  skillSearch: { topK: 5 }, // ranked, on-demand discovery; defaults to 5 if omitted
+});
+```
+
+`skillSearch.topK` is advisory; defaults to 5. The ranker is an in-tree TF-style scorer with name-match boost — no
+embedder dependency, no external service, deterministic across runs (alphabetical tie-break). The model sees both
+`mcp__skill_bridge__search_skills` and `mcp__skill_bridge__load_skill` in its tool catalog and the existing always-load
+meta keeps both tools exempt from Claude tool-search deferral.
+
+When `skillSearch` is unset (the default), the existing description-enumeration behavior is preserved unchanged.
+
+### Tool-exposure policy (`toolSearch.alwaysActive`)
+
+The Claude Agent SDK enables tool-search deferral once the active tool surface crosses a threshold (≈ tens of tools);
+once on, individual tools are hidden behind a `tool_search → load → invoke` round-trip until the model asks for them. On
+the Salesforce LLM Gateway's Bedrock-Sonnet path that round-trip can stall the turn (see `ARCHITECTURE.md` →
+`_meta['anthropic/alwaysLoad']`). To pin specific tools into the model's catalog regardless of how the surrounding
+surface grows, list them on `ClaudeAgentConfig.toolSearch.alwaysActive`:
+
+```ts
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  mcpServers: {
+    sfdx: { type: 'stdio', command: '...' },
+    other: { type: 'stdio', command: '...' },
+  },
+  toolSearch: {
+    alwaysActive: [
+      { serverName: 'sfdx' }, // every tool from this server (post-discovery)
+      { serverName: 'other', toolName: 'lookup_account' }, // exactly one tool
+      { toolName: 'resume_tool_operation' }, // any tool by this name, regardless of source
+    ],
+  },
+});
+```
+
+Each entry covers one of three patterns:
+
+| Entry shape                          | Matches                                                                |
+| ------------------------------------ | ---------------------------------------------------------------------- |
+| `{ serverName: 'X' }`                | every tool advertised by server `X`                                    |
+| `{ serverName: 'X', toolName: 'Y' }` | exactly tool `Y` on server `X`                                         |
+| `{ toolName: 'Y' }`                  | any tool named `Y` regardless of source (built-ins, workspace, MCP, …) |
+
+At least one of `serverName` / `toolName` must be present — empty `{}` rejects at config time. Mirrors
+`MastraAgentConfig.toolSearch.alwaysActive` so cross-harness consumers configure tool-exposure policy the same way on
+both harnesses.
+
+**Caveat — Claude built-ins:** the Claude SDK has no host-side hook for stamping `_meta['anthropic/alwaysLoad']` on
+built-in tools (`Bash`, `Read`, `Edit`, …). A `{ toolName: 'Bash' }` entry today is a no-op on built-ins and only takes
+effect when a tool by that name comes from a configured MCP server or consumer-declared `AgentConfig.tools`.
+
 ### Multimodal input
 
 `chatSession.chat()` / harness `stream()` accept a `MessagePart[]` carrying `image` (PNG/JPEG) and `file` (PDF) parts
@@ -68,22 +140,24 @@ mirror the gateway SDK's conservative limits so a file behaves identically here
 
 ### Tool approval
 
-When `StreamOptions.requireToolApproval: true` is set on `chatSession.send()`/`stream()`, the harness installs a
-`PreToolUse` hook that:
+When `StreamOptions.requireToolApproval: true` is set on `chatSession.chat()`, the harness installs a `PreToolUse` hook
+that:
 
-1. Emits a `tool-approval-request` event on `ChatStreamResult.eventStream` carrying
+1. Emits a `tool-approval-request` event on the `chat()`-returned `eventStream` carrying
    `{ toolCall: { toolCallId, toolName, args } }`.
-2. Suspends the stream (the `eventStream` ends after the request event) until the consumer calls
-   `chatSession.approveToolCall(toolCallId)` or `chatSession.declineToolCall(toolCallId)`.
-3. Returns a new `ChatStreamResult` whose stream carries the tool's outcome and the model's follow-up:
-   - On **approve**: the resulting `tool-result`, then the model's follow-up `text-delta` events, then `finish`.
-   - On **decline**: a synthetic `tool-result` with `isError: true`, then the model's acknowledgement `text-delta`
-     events, then `finish`. The decline does **not** abort the assistant turn — the model receives the denial and can
-     react. The decline message is hard-coded to `'User declined the tool call.'`; there is no consumer-supplied reason
-     (matching the SDK's `declineToolCall` signature).
-
-Single-tool approve and decline, parallel batches (with per-tool sink routing and progressive disclosure), approval
-timeout enforcement, `abortSignal` propagation, and shutdown/`destroyThread` cleanup are supported today.
+2. Parks the SDK hook Promise until the consumer calls `chatSession.approveToolCall(toolCallId)` or
+   `chatSession.declineToolCall(toolCallId)`. Settle methods return `Promise<void>`.
+3. Continues delivering events on the **same** `eventStream` after the consumer settles — the resulting `tool-result`,
+   the model's follow-up `text-delta` events, and the terminal `finish` all arrive on that one stream. The consumer
+   keeps iterating until it sees `finish`.
+   - On **approve**: the SDK's `tool_use` runs and the `tool-result` lands on the stream.
+   - On **decline**: the SDK synthesizes a `tool_result` with `isError: true`, the model receives the denial and emits
+     an acknowledgement, then `finish`. The decline does **not** abort the assistant turn. The decline message is
+     hard-coded to `'User declined the tool call.'`.
+
+This is the post-#529 single-stream-per-turn contract — see the SDK README's "Tool Approval Flow" for consumer-facing
+patterns. Single-tool approve / decline, parallel batches (`requireToolApproval: 'batch'`), approval-timeout
+enforcement, `abortSignal` propagation, and shutdown / `destroyThread` cleanup all share that contract.
 
 #### Abort signal
 
@@ -91,8 +165,7 @@ When `StreamOptions.abortSignal` fires during an active turn with `requireToolAp
 
 - All pending permission Promises reject with an `AbortError`.
 - The underlying Claude subprocess is killed (existing `AbortController` wiring).
-- Every open per-turn stream — the initial sink and any per-tool continuation sinks for already-approved tools whose
-  `tool-result` hasn't arrived yet — ends with an `error` event (`code: 'aborted'`, `error.name === 'AbortError'`)
+- The single per-turn `eventStream` ends with an `error` event (`code: 'aborted'`, `error.name === 'AbortError'`)
   followed by a `finish` event (`finishReason: 'error'`). The `'error'` finish reason is used because the SDK's
   `FinishReason` type has no `'aborted'` value; the preceding `error` event carries the abort identity.
 
@@ -101,12 +174,12 @@ If the signal is already aborted when `stream()` is called, `stream()` throws sy
 
 #### Shutdown and thread teardown
 
-Calling `harness.shutdown()` disposes every tracked broker (across all agents and threads). For each pending approval,
-the parked Promise rejects with an `AgentSDKError` whose `type` is `'DISPOSED'`; each open per-turn stream ends with a
-single `error` event (no `finish`) and the underlying Claude subprocess is killed. Calling
-`destroyThread(agentId, threadId)` performs the same cleanup but only for the broker associated with that
-`(agentId, threadId)` pair — brokers on other threads are untouched. Both entry points are idempotent (the harness's
-`shuttingDown` guard prevents double-dispose; the broker's `disposed` flag does the same).
+Calling `harness.shutdown()` disposes every tracked coordinator (across all agents and threads). For each pending
+approval, the parked Promise rejects with an `AgentSDKError` whose `type` is `'DISPOSED'`; the per-turn `eventStream`
+ends with a single `error` event (no `finish`) and the underlying Claude subprocess is killed. Calling
+`destroyThread(agentId, threadId)` performs the same cleanup but only for the coordinator associated with that
+`(agentId, threadId)` pair — coordinators on other threads are untouched. Both entry points are idempotent (the
+harness's `shuttingDown` guard prevents double-dispose; the coordinator's `disposed` flag does the same).
 
 #### Approval timeout
 
@@ -115,21 +188,18 @@ Each pending approval is auto-denied after `ClaudeHarnessFactoryConfig.toolAppro
 
 - The parked `PreToolUse` hook Promise resolves with `permissionDecision: 'deny'` plus `decision: 'block'` so the
   agentic loop terminates instead of letting the model retry the timed-out call.
-- An `error` event with `code: 'tool-approval-timeout'` is emitted on the consumer's currently-active per-turn stream,
+- An `error` event with `code: 'tool-approval-timeout'` is emitted on the consumer's currently-iterating `eventStream`,
   then that stream ends.
-- Any subsequent `approveToolCall` / `declineToolCall` for the timed-out tool throws because the pending approval is no
-  longer registered.
+- Any subsequent `approveToolCall` / `declineToolCall` for the timed-out tool throws because the coordinator marks every
+  emitted approval as auto-resolved during teardown.
 
 Calling `approveToolCall` or `declineToolCall` before the timeout cancels the timer — no spurious error event surfaces
 afterwards.
 
-> **Consumer pattern:** to observe the timeout (or `abort` / `dispose`) error on the initial-turn `eventStream`, iterate
-> the stream to its natural end rather than `break`ing out after the `tool-approval-request` event. Calling
-> `iterator.return()` (which `break` does inside `for await`) finalizes the harness's source generator before the
-> terminal event can reach you. Iterate with side-effect
-> (`if (event.type === 'tool-approval-request') approval = event`) and let the loop exit when the stream ends. Consumers
-> that hand off to a continuation sink via `approveToolCall` / `declineToolCall` can use either pattern — terminal
-> events on the continuation flow normally.
+> **Consumer pattern:** to observe the timeout (or `abort` / `dispose`) error on the `eventStream`, iterate the stream
+> to its natural end rather than `break`ing out after the `tool-approval-request` event. Calling `iterator.return()`
+> (which `break` does inside `for await`) finalizes the harness's source generator before the terminal event can reach
+> you. Settle in-line and keep iterating; the loop exits naturally when the terminal `finish` arrives.
 
 ### Using the Salesforce Bedrock resolver
 
@@ -165,8 +235,8 @@ const manager = await createAgentManager('/path/to/storage', harnessFactory);
 
 JWT refresh works the same as elsewhere in the harness: each `resolve()` call eagerly reads `orgJwt.getValue()` /
 `orgJwt.getTenantKey()` and freezes the result into the static subprocess headers. `Agent.updateAgentConfig({})` runs
-`harness.destroyAgent` + `createAgent`, the resolver re-reads the fresh JWT on the next `stream()`, and the next
-subprocess spawns with the new headers.
+`harness.updateAgent`, the resolver re-reads the fresh JWT on the next `stream()`, and the next subprocess spawns with
+the new headers — connected MCP clients are preserved through the rotation.
 
 ### Using a custom resolver
 
@@ -271,9 +341,11 @@ const agent = await manager.createAgent(projectRoot, {
 });
 
 // In your event loop, answer the consumer tool's `tool-call` via
-// `session.submitToolResult({ toolCallId, toolName, result })`. This pattern
-// composes with `requireToolApproval: true` (#516) — the approval broker
-// emits a `tool-approval-request` for the consumer tool first.
+// `session.submitToolResult({ toolCallId, toolName, result })`. Consumer
+// tools never reach the approval gate (the harness adds the consumer-tool
+// wire prefix to `bypassApprovalTools` automatically — see #529 step 2b).
+// They surface as a normal `tool-call` event with no preceding
+// `tool-approval-request`, even when `requireToolApproval: true`.
 ```
 
 This is the recommended pattern when the consumer wants identical behavior across Mastra and Claude. For Claude-only
@@ -281,39 +353,62 @@ consumers who prefer to drive the built-in directly, see "Bypassing the approval
 
 ### Bypassing the approval gate for specific tools
 
-When `requireToolApproval: true` is set, every tool call reaches the broker by default — including built-ins like
-`AskUserQuestion` whose UX a consumer may want to drive directly off the `tool-call` event without a synthetic
-`tool-approval-request` round-trip. `ClaudeHarnessFactoryConfig.bypassApprovalTools` opts specific tool names out of the
-gate.
+When `requireToolApproval: true` is set, every built-in / MCP tool call reaches the coordinator's `PreToolUse` hook by
+default — including Claude built-ins like `AskUserQuestion`. (Consumer-declared tools from `AgentConfig.tools[i]`
+already bypass automatically — see "Tool approval" above.) `ClaudeHarnessFactoryConfig.bypassApprovalTools` opts
+additional tool names out of the gate.
 
 ```ts
 const harnessFactory = new ClaudeHarnessFactory({
   resolver: new SalesforceBedrockClaudeTransportResolver({ gatewayBaseUrl: '...' }),
   permissionMode: 'bypassPermissions',
   // Even when `requireToolApproval: true`, calls to these tools bypass the
-  // broker. They still emit `tool-call` / `tool-result` ChatEvents, so the
-  // consumer can drive their UX off the `tool-call` directly.
-  bypassApprovalTools: ['AskUserQuestion'],
+  // PreToolUse hook. They still emit `tool-call` / `tool-result` ChatEvents,
+  // so the consumer can drive their UX off the `tool-call` directly.
+  bypassApprovalTools: [
+    'AskUserQuestion', // Claude built-in
+    'ask_user_tool', // consumer-declared (also bypassed automatically; listing here is harmless)
+  ],
 });
 ```
 
+Tool names use the **consumer-facing** form — the bare `AgentConfig.tools[i].name` for consumer-declared tools, the
+SDK-built-in name for Claude built-ins (no `mcp__<bridge>__` prefix needed). The harness expands each entry into the
+underlying wire-prefixed form (`mcp__sfdx-agent-sdk-consumer-tools__<name>`) where applicable so consumer tools bypass
+correctly without consumers needing to know the internal namespacing.
+
 `bypassApprovalTools` is encoded as a negative-lookahead regex on the SDK `PreToolUse` hook's `matcher` field, so
 non-matching tools fall through to the SDK's permission cache and run natively under the factory-pinned
 `permissionMode`. The flag is Claude-only by design; Mastra has no equivalent because its approval pipeline gates
-consumer-declared tools, not provider built-ins.
+consumer-declared tools differently.
 
-> **Scope:** intended for Claude built-ins (e.g. `AskUserQuestion`) the consumer drives off `tool-call` directly.
-> Putting a consumer-tool name (e.g. `mcp__sfdx-agent-sdk-consumer-tools__<tool>`) in this list is unsupported —
-> consumer tools are routed through the approval broker's sink coordinator under composition mode (#516), and bypassing
-> them disconnects that wiring. To suppress consumer tools, omit them from `AgentConfig.tools` instead.
+For bypassed consumer tools, the chat stream emits the `tool-call` ChatEvent and a synthetic `finish('tool-calls')` on
+the same `eventStream` (the SDK contract for client-side tools — see `ToolDefinition` JSDoc). The consumer runs the tool
+locally and calls `submitToolResult` with the result; the agent loop continues on the same `eventStream` (post-#529
+single-stream-per-turn contract).
 
 > **Note:** `permissionMode: 'plan'` denies mutating built-ins (`Edit`, `Write`, `Bash`, …) at the SDK's permission
 > cache rather than running them natively. Bypassing such a tool with `bypassApprovalTools` does not "unlock" it under
 > plan mode — the SDK still denies it. Plan mode applies to the whole subprocess; this flag only chooses whether the
-> harness's broker gets a say.
+> harness's coordinator gets a say.
+
+When `bypassApprovalTools` is undefined or empty (default), every built-in / MCP tool call reaches the coordinator — no
+behavior change for existing consumers. (Consumer-declared tools always bypass.)
+
+### Tool-result redaction
+
+Tool-result redaction is configured at the manager layer, not the factory. Pass a `hooksForAgent` callback to
+`createAgentManager`; the SDK threads the resolved `AgentHooks` bag through `createAgent`'s `options.hooks`, and the
+Claude harness wires `hooks.onToolResult` to the Claude Agent SDK's `PostToolUse` hook (`updatedToolOutput`)
+automatically. The same `ToolResultRedactor` works on the Mastra harness. See the SDK README → "Tool-Result Redaction"
+for the full pattern (including a `failClosed(...)` wrapper consumers can use to substitute a safe stub on throw).
+
+**Bash gotcha.** Claude's built-in `Bash` tool requires the `{ stdout, stderr, interrupted }` shape on the redactor's
+replacement output. A bare-string return is rejected by the Claude Agent SDK and the original leaks. The harness does
+NOT validate this — the redactor knows what tool it's redacting.
 
-When `bypassApprovalTools` is undefined or empty (default), every tool call reaches the approval broker — no behavior
-change for existing consumers.
+If you also register your own `PostToolUse` hooks via `queryDefaults.hooks.PostToolUse`, both fire — the harness's hook
+is appended **last** in the list so its `updatedToolOutput` has final say over the value the model sees.
 
 ## Development
 

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

@@ -0,0 +1,205 @@
+import type { HookCallback, SDKMessage } from '@anthropic-ai/claude-agent-sdk';
+import { type ChatEvent } from '@salesforce/sfdx-agent-sdk';
+import { GenSink } from '@salesforce/sfdx-agent-sdk/harness';
+import type { ClaudeEventAdapter, McpToolMetadataLookup } from './claude-event-adapter.js';
+export interface ClaudeApprovalCoordinatorOptions {
+    adapter: ClaudeEventAdapter;
+    toolApprovalTimeoutMs: number;
+    abortController: AbortController;
+    /**
+     * Optional lookup that resolves an MCP server name + annotations from a
+     * Claude-namespaced tool name (`mcp__<server>__<tool>`). When present,
+     * `tool-approval-request` events the coordinator pushes from
+     * {@link preToolUseHook} carry `serverName` + `annotations` for
+     * MCP-bridged tools — matching the enrichment the adapter applies to
+     * `tool-call` / `tool-result` events.
+     */
+    lookupMcpToolMetadata?: McpToolMetadataLookup;
+    /**
+     * Approval-emission mode (#447). Defaults to `'serial'` when omitted.
+     *
+     * - `'serial'`: emit `tool-approval-request` only when the SDK's
+     *   `PreToolUse` hook fires for that tool — one at a time. Identical
+     *   to behavior before parallel-approval UX. Safe for consumers
+     *   whose iterator returns on the first approval-request.
+     * - `'batch'`: front-load `tool-approval-request` emission off the
+     *   adapter's `tool-call` events so parallel `tool_use` batches
+     *   surface all approvals on the same stream. Consumers MUST iterate
+     *   to natural park collecting approvals.
+     */
+    mode?: 'serial' | 'batch';
+    /**
+     * Logical bridge server name for the consumer-tools bridge. The
+     * coordinator strips this prefix on `tool-call` / `tool-result`
+     * ChatEvents before forwarding them to the consumer so the
+     * `ToolCallEvent.toolName === AgentConfig.tools[i].name` cross-harness
+     * contract holds.
+     *
+     * When omitted, the coordinator skips consumer-tool bookkeeping
+     * entirely — used by tests that drive the approval path without any
+     * consumer tools registered.
+     */
+    consumerToolsBridgeName?: string;
+}
+export declare class ClaudeApprovalCoordinator {
+    private readonly adapter;
+    private readonly toolApprovalTimeoutMs;
+    private readonly abortController;
+    private readonly lookupMcpToolMetadata?;
+    private readonly mode;
+    private readonly consumerToolBridgePrefix;
+    /** Single per-turn sink. Issue #529 contract: one stream per turn. */
+    private readonly initial;
+    /** Parked `PreToolUse` hook promises, keyed by `toolCallId`. */
+    private readonly pendingApprovals;
+    /** Buffered consumer decisions, keyed by `toolCallId`. */
+    private readonly decisions;
+    /** ToolCallIds for which a `tool-approval-request` has been emitted. */
+    private readonly emittedApprovals;
+    /** ToolCallIds the consumer has settled. Rejects double-settle. */
+    private readonly consumerSettled;
+    /**
+     * ToolCallIds the coordinator auto-resolved (timeout / abort / dispose).
+     * A subsequent settle for these ids rejects with "already auto-resolved".
+     */
+    private readonly settledByCoordinator;
+    /** Args from the adapter's `tool-call` ChatEvent, keyed by `toolCallId`. */
+    private readonly toolCallArgs;
+    /**
+     * Consumer-tool: tool-call events pump has seen but no parker invocation
+     * for yet. FIFO list per tool name. Empirically the Claude subprocess
+     * emits the assistant's `tool_use` block (rendered as `tool-call`) BEFORE
+     * dispatching the MCP `tools/call` to the bridge handler.
+     */
+    private readonly recentToolCallsByName;
+    /** Reverse lookup `toolCallId → toolName` for entries in {@link recentToolCallsByName}. */
+    private readonly recentToolCallNameById;
+    /** Consumer-tool: parker invocations awaiting a `tool-call` arrival. FIFO list per tool name. */
+    private readonly waitingParkersByName;
+    /** Consumer-tool: bound parkers, keyed by `toolCallId`. `submitToolResult` resolves these. */
+    private readonly pendingByToolCallId;
+    /** Consumer-tool: results submitted before the bridge handler parked. Keyed by `toolCallId`. */
+    private readonly preSubmittedByToolCallId;
+    /**
+     * Callbacks invoked exactly once when the coordinator tears down
+     * (`abort` / `dispose` / pump exit, whichever fires first). Used by
+     * the harness to detach the consumer-AbortSignal listener.
+     */
+    private readonly teardownCallbacks;
+    private disposed;
+    private aborted;
+    /**
+     * Set on entry to {@link teardown} so re-entry from any reason
+     * (`abort` / `dispose` / `timeout` / `pump-error`) is a no-op. The
+     * timeout path in particular calls `abortController.abort()` which
+     * causes the pump iterator to throw — without this guard the pump's
+     * catch block would observe `!aborted && !disposed` and fire a second
+     * teardown. Side effects in `teardown` are idempotent today
+     * (`pendingApprovals` clear, ended-sink push no-ops, `teardownCallbacks`
+     * set cleared on first run, `AbortController.abort` itself is
+     * idempotent), but a single guard is cheaper than auditing every
+     * future addition.
+     */
+    private tornDown;
+    constructor(opts: ClaudeApprovalCoordinatorOptions);
+    initialSink(): GenSink<ChatEvent>;
+    onTeardown(callback: () => void): void;
+    private runTeardownCallbacks;
+    start(query: AsyncIterable<SDKMessage>): void;
+    abort(): void;
+    dispose(): void;
+    /**
+     * Single teardown path for abort / dispose / approval-timeout /
+     * pump-error. Marks every emitted approval `settledByCoordinator`
+     * (so a subsequent `approve` / `decline` rejects with
+     * "already auto-resolved"), drains every parked `PreToolUse` hook
+     * Promise and per-id timer, rejects every parked consumer-tool
+     * parker, pushes the synthetic terminal pair on the sink, aborts
+     * the subprocess via the injected controller, and fires teardown
+     * callbacks.
+     *
+     * The `reason` parameter changes two things:
+     *  - `'dispose'` pushes an error event only, no `finish` (matches
+     *    pre-#529 dispose contract: disposal is consumer-triggered,
+     *    not a normal turn end).
+     *  - `'timeout'` resolves every parked hook with `decision: 'block'`
+     *    so the agentic loop ends politely; the other reasons reject
+     *    parked hooks with the underlying error so the SDK surfaces
+     *    each as a tool failure.
+     *
+     * Mirrors the Mastra coordinator's `teardown` so the pump-throw /
+     * abort / dispose / timeout paths can't drift out of step on either
+     * harness — the audit's Finding #1 (pump-throw drain hygiene) is
+     * the regression this single-source teardown discipline pins.
+     */
+    private teardown;
+    /**
+     * The Claude SDK's `PreToolUse` hook. Fires before the SDK's per-tool /
+     * per-arg permission cache (which the deprecated `canUseTool` route hit
+     * AFTER the cache, so ~70% of tool calls slipped past the gate — see
+     * #484).
+     *
+     * Consumer-executed tools never reach this hook because the options
+     * builder unconditionally bypasses the consumer-tool wire prefix in the
+     * matcher (#529 step 2b decouple). That keeps the parker path the
+     * single source of truth for consumer-tool lifecycle and lets this
+     * hook focus on built-in / external-MCP tool gating.
+     */
+    readonly preToolUseHook: HookCallback;
+    private emitApprovalRequest;
+    private enrichmentFor;
+    private handleApprovalTimeout;
+    approve(toolCallId: string): void;
+    decline(toolCallId: string): void;
+    private settlePending;
+    /**
+     * Parker callback the in-process consumer-tools MCP bridge handler
+     * invokes when the Claude subprocess calls `tools/call` for a
+     * consumer-declared tool. Returns a Promise the consumer settles via
+     * {@link submitToolResult}.
+     *
+     * Three-way ladder:
+     *  1. A `tool-call` event with `toolCallId` already routed AND a result
+     *     has been pre-submitted under that id → resolve immediately.
+     *  2. A `tool-call` event already routed (no pre-submit) → bind under
+     *     `toolCallId` so the eventual `submitToolResult` resolves us.
+     *  3. Neither → queue under `toolName` (FIFO); the next `tool-call`
+     *     for that name binds to us.
+     */
+    readonly parkConsumerToolCall: (call: {
+        toolName: string;
+        args: Record<string, unknown>;
+    }) => Promise<{
+        result: unknown;
+        isError?: boolean;
+    }>;
+    /**
+     * Settle a parked consumer-tool call. Issue #529 contract: returns
+     * `void`; post-resume events flow through the same `initial` sink the
+     * consumer is iterating from `chat()`.
+     */
+    submitToolResult(toolCallId: string, result: unknown, isError?: boolean): void;
+    private failAllPendingConsumerCalls;
+    private pump;
+    private route;
+    /**
+     * Strip the consumer-tool bridge prefix on `tool-call` / `tool-result`
+     * events and FIFO-bind `toolCallId`s for parker matching. Returns
+     * `undefined` if no rewrite is needed.
+     */
+    private maybeRewriteForConsumerTool;
+    /**
+     * FIFO-bind a freshly-seen consumer-tool `toolCallId` to whichever queued
+     * state already exists for `strippedToolName`. Three-way ladder:
+     *
+     *  1. A parker is already waiting (bridge handler arrived first) →
+     *     pair the parker against this `toolCallId`.
+     *  2. Neither parker nor pre-submitted → record the `toolCallId` against
+     *     the name so the next parker invocation for that name binds to it.
+     *
+     * (Pre-submit-before-tool-call is impossible: `submitToolResult`
+     * requires a `toolCallId` the consumer received from a prior
+     * `tool-call` event.)
+     */
+    private bindToolCallId;
+}