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

package/README.md

@@ -34,7 +34,7 @@ internal architecture, see [ARCHITECTURE.md](ARCHITECTURE.md).
 | Export                                           | Kind      | Description                                                                                                                                                          |
 | ------------------------------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `ClaudeHarnessFactory`                           | class     | `HarnessFactory` that produces a Claude-backed `AgentHarness` bound to a storage root.                                                                               |
-| `ClaudeHarnessFactoryConfig`                     | interface | Configuration for `ClaudeHarnessFactory` (`resolver`, `permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`).                                          |
+| `ClaudeHarnessFactoryConfig`                     | interface | Configuration for `ClaudeHarnessFactory` (`resolver`, `permissionMode`, optional `queryDefaults`, `toolApprovalTimeoutMs`, `bypassApprovalTools`).                   |
 | `ClaudeHarnessPermissionMode`                    | type      | Narrowed permission mode: `'bypassPermissions' \| 'acceptEdits' \| 'plan'`.                                                                                          |
 | `ClaudeTransportResolver`                        | interface | Strategy for resolving transport env, auth, and native model ID for the subprocess.                                                                                  |
 | `ClaudeTransportResolverResult`                  | type      | Return type of `ClaudeTransportResolver.resolve()` (`env` + `nativeModelId`).                                                                                        |
@@ -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
 
@@ -144,10 +142,12 @@ const harnessFactory = new ClaudeHarnessFactory({
   resolver: new SalesforceBedrockClaudeTransportResolver({
     // Pick the gateway URL for your environment — e.g. test:
     gatewayBaseUrl: 'https://test.api.salesforce.com/ai/gpt/v1',
-    // Optional: gateway model id → native Bedrock id translation.
-    modelIdMap: {
-      llmgateway__BedrockAnthropicClaude46Sonnet: 'anthropic.claude-sonnet-4-6',
-    },
+    // No `modelIdMap` needed in the common case: the LLM Gateway's invoke API
+    // accepts the gateway-prefixed canonical id (`llmgateway__Bedrock*`) for
+    // every Anthropic Claude model, and the SDK's `Model.name` is already that
+    // canonical id, so the resolver's default passthrough is correct. Set the
+    // map only if your consumer needs to translate to a different shape (e.g.
+    // a self-hosted Bedrock proxy that expects the bare-native ids).
     // Optional: override the `x-client-feature-id` header. Defaults to `orgJwt.getFeatureId()`.
     featureId: 'EinsteinGptForDevelopers',
     // Optional: getter for the `x-aip-user-ctx-tag` header. Invoked on every `resolve()`;
@@ -223,6 +223,106 @@ const harnessFactory = new ClaudeHarnessFactory({
 });
 ```
 
+### Suppressing Claude built-ins for cross-harness consumer tools
+
+Claude's subprocess ships built-in tools the model can invoke without the host wiring them up — `AskUserQuestion`,
+`Bash`, `Read`, `WebSearch`, etc. When a consumer registers an equivalent **cross-harness** tool via `AgentConfig.tools`
+(which works on both Mastra and Claude), the model can wind up choosing the Claude built-in over the consumer tool,
+breaking parity with Mastra. Pass `disallowedTools` through `queryDefaults` to keep the model's choice deterministic
+across harnesses.
+
+`disallowedTools` flows through to the Claude SDK verbatim (it's a field on the SDK's `Options` shape that
+`ClaudeQueryDefaults` does not strip). It blocks the model from emitting `tool_use` for the named built-ins entirely.
+
+```ts
+import { createAgentManager } from '@salesforce/sfdx-agent-sdk';
+import { ClaudeHarnessFactory, SalesforceBedrockClaudeTransportResolver } from '@salesforce/sfdx-agent-harness-claude';
+
+const harnessFactory = new ClaudeHarnessFactory({
+  resolver: new SalesforceBedrockClaudeTransportResolver({ gatewayBaseUrl: '...' }),
+  permissionMode: 'bypassPermissions',
+  // Suppress the built-in `AskUserQuestion` so the cross-harness consumer
+  // tool below is the only ask-the-user surface the model sees on Claude
+  // (matching what Mastra consumers experience by default).
+  queryDefaults: {
+    disallowedTools: ['AskUserQuestion'],
+  },
+});
+
+const manager = await createAgentManager('/path/to/storage', harnessFactory);
+const agent = await manager.createAgent(projectRoot, {
+  instructions: '...',
+  tools: [
+    {
+      name: 'ask_user_choice',
+      description: 'Ask the human user a multiple-choice question and wait for the answer.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          question: { type: 'string' },
+          options: { type: 'array', items: { type: 'string' } },
+        },
+        required: ['question', 'options'],
+      },
+    },
+  ],
+});
+
+// In your event loop, answer the consumer tool's `tool-call` via
+// `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
+consumers who prefer to drive the built-in directly, see "Bypassing the approval gate for specific tools" below.
+
+### Bypassing the approval gate for specific tools
+
+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
+  // 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 differently.
+
+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 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.)
+
 ## Development
 
 See [DEVELOPING.md](DEVELOPING.md) for build, test, and packaging instructions.

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;
+}