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

package/README.md

@@ -68,22 +68,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 +93,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 +102,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 +116,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
 
@@ -271,9 +269,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 +281,47 @@ 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 tool call reaches the approval broker — no behavior
-change for existing consumers.
+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.)
 
 ## 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;
+}