@fgv/ts-extras 5.1.0-37 → 5.1.0-39

package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.d.ts

@@ -40,6 +40,15 @@ interface IToolCallResult {
  * (all block types in original stream order) and appends a user turn
  * with `tool_result` blocks for each executed tool call.
  *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `tool_result.tool_use_id` is drawn from — and validated against — the set of
+ * assistant `tool_use.id`s actually present in the accumulation buffer. The id
+ * is NEVER derived from the tool name: a tool name can never match a `toolu_*`
+ * id, so a name fallback produces exactly the "malformed identifier" the
+ * provider rejects. If any tool result cannot be correlated to a buffered
+ * `tool_use` block with a non-empty id, the build fails loud (naming the tool)
+ * rather than emitting a malformed continuation.
+ *
  * **Constraint (E3):** The returned continuation does NOT include a forced
  * `tool_choice` field. When thinking is active, Anthropic rejects
  * `tool_choice: { type: 'any' }` and `tool_choice: { type: 'tool', ... }`
@@ -48,7 +57,7 @@ interface IToolCallResult {
  *
  * @internal
  */
-export declare function buildAnthropicContinuation(accBuffer: Map<number, IAccumulatedBlock>, toolResults: IToolCallResult[]): IAiClientToolContinuation;
+export declare function buildAnthropicContinuation(accBuffer: Map<number, IAccumulatedBlock>, toolResults: IToolCallResult[], logger?: Logging.ILogger): Result<IAiClientToolContinuation>;
 /**
  * Builds the OpenAI / xAI Responses API follow-up input items for a
  * client-tool round-trip.
@@ -57,9 +66,16 @@ export declare function buildAnthropicContinuation(accBuffer: Map<number, IAccum
  * `function_call_output` items (the harness execution result), one pair
  * per executed tool call.
  *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `function_call_output.call_id` is drawn from — and validated against — the
+ * set of `function_call.call_id`s in the accumulation map. It is NEVER derived
+ * from the tool name (the OpenAI parity of the Anthropic `tool_use_id` fix). A
+ * missing / empty / unmatched call id fails the build loud rather than emitting
+ * a continuation the provider would reject.
+ *
  * @internal
  */
-export declare function buildOpenAiContinuation(calls: Map<string, IAccumulatedFunctionCall>, toolResults: IToolCallResult[]): IAiClientToolContinuation;
+export declare function buildOpenAiContinuation(calls: Map<string, IAccumulatedFunctionCall>, toolResults: IToolCallResult[], logger?: Logging.ILogger): Result<IAiClientToolContinuation>;
 /**
  * Builds the Gemini follow-up contents for a client-tool round-trip.
  *
@@ -67,9 +83,42 @@ export declare function buildOpenAiContinuation(calls: Map<string, IAccumulatedF
  * user turn with `functionResponse` parts (correlation by tool name, since
  * Gemini does not assign call IDs).
  *
+ * When thinking is enabled, Gemini stamps an opaque `thoughtSignature` on each
+ * `functionCall` part and requires it echoed back, verbatim, as a sibling of
+ * `functionCall` on the continuation's model turn — otherwise the follow-up is
+ * rejected with "Function call is missing a thought_signature in functionCall
+ * parts". The captured signature (see {@link IAccumulatedGeminiFunctionCall})
+ * is replayed here only when present; the key is omitted entirely when thinking
+ * was disabled. See https://ai.google.dev/gemini-api/docs/thought-signatures.
+ *
  * @internal
  */
 export declare function buildGeminiContinuation(calls: IAccumulatedGeminiFunctionCall[], toolResults: IToolCallResult[]): IAiClientToolContinuation;
+/**
+ * Decision returned by an {@link IExecuteClientToolTurnParams.onBeforeToolExecute}
+ * gate for a single client-tool call.
+ *
+ * @remarks
+ * - `{ action: 'proceed' }` — run the tool's `execute` normally.
+ * - `{ action: 'deny', reason }` — do NOT run `execute`; a synthesized tool-result
+ *   carrying `reason` is fed into the continuation exactly like a normal result so
+ *   the model can react, and a `client-tool-result` event is emitted for the call.
+ *   The turn continues.
+ *
+ * A gate that wants to signal a hard error (as opposed to a deliberate deny) should
+ * return `Result.fail` (or reject) from the callback. Note this is NOT the same as a
+ * `tool.execute` failure: an `execute` failure yields an `isError` tool-result and the
+ * **turn continues**, whereas a gate `fail`/reject **terminates the turn** — it fails
+ * `nextTurn` (and emits an inline `error` event) rather than synthesizing a deny.
+ *
+ * @public
+ */
+export type IToolExecutionDecision = {
+    readonly action: 'proceed';
+} | {
+    readonly action: 'deny';
+    readonly reason: string;
+};
 /**
  * Parameters for {@link AiAssist.executeClientToolTurn}.
  *
@@ -112,7 +161,10 @@ export interface IExecuteClientToolTurnParams extends IChatRequest {
      * normalized-message path strips provider-native fields.
      */
     readonly continuationMessages?: ReadonlyArray<JsonObject>;
-    /** Temperature (default: 0.7). */
+    /**
+     * Sampling temperature. Sent to the provider only when explicitly provided; omitted otherwise
+     * so the provider's own default applies (current-gen models reject a caller-supplied default).
+     */
     readonly temperature?: number;
     /** Server-side tools to include. */
     readonly tools?: ReadonlyArray<AiServerToolConfig>;
@@ -136,6 +188,22 @@ export interface IExecuteClientToolTurnParams extends IChatRequest {
     readonly resolvedThinking?: IResolvedThinkingConfig;
     /** Resolved model string (pre-resolved by the caller). When omitted, uses the descriptor's default model. */
     readonly model?: string;
+    /**
+     * Optional host gate invoked for each client-tool call **after** the model's raw
+     * args have been validated against the tool's `parametersSchema` and **before**
+     * `tool.execute(...)` runs. The full `tool` (including `tool.config.annotations`)
+     * and the validated `args` are passed so gate logic can key off a tool's behavior
+     * annotations (e.g. deny a `destructiveHint` call pending confirmation).
+     *
+     * Returning `{ action: 'proceed' }` (or omitting the callback) runs `execute`
+     * normally. Returning `{ action: 'deny', reason }` skips `execute` and synthesizes
+     * a denial tool-result carrying `reason` into the continuation (the model sees the
+     * denial and can react); **the turn continues**. A callback that returns `Result.fail`
+     * or rejects is a hard error that **terminates the turn** (fails `nextTurn` + emits an
+     * inline `error` event) — distinct from a `tool.execute` failure, which continues the
+     * turn with an `isError` result. A deny must therefore be explicit.
+     */
+    readonly onBeforeToolExecute?: (tool: IAiClientTool, args: unknown) => Promise<Result<IToolExecutionDecision>>;
 }
 /**
  * Return value of {@link AiAssist.executeClientToolTurn}.
@@ -155,6 +223,17 @@ export interface IExecuteClientToolTurnResult {
      */
     readonly nextTurn: Promise<Result<IAiClientToolTurnResult>>;
 }
+/**
+ * True when a request would combine Gemini built-in grounding (a `web_search`
+ * server tool) with client (function) tools — a combination Gemini's
+ * `generateContent` API rejects with HTTP 400 (`INVALID_ARGUMENT`). Callers gate
+ * on `descriptor.apiFormat === 'gemini'` before consulting this; other providers
+ * accept the mix. Kept as a pure predicate so the conflict rule is unit-testable
+ * without a live stream.
+ *
+ * @internal
+ */
+export declare function hasGeminiToolConflict(tools: ReadonlyArray<AiServerToolConfig> | undefined, clientTools: ReadonlyArray<IAiClientTool>): boolean;
 /**
  * Orchestrates a single client-tool streaming turn for any supported provider.
  *

package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clientToolContinuationBuilder.d.ts","sourceRoot":"","sources":["../../../../src/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"clientToolContinuationBuilder.d.ts","sourceRoot":"","sources":["../../../../src/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.ts"],"names":[],"mappings":"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"}

package/lib/packlets/ai-assist/streamingAdapters/clientToolContinuationBuilder.js

@@ -42,6 +42,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildAnthropicContinuation = buildAnthropicContinuation;
 exports.buildOpenAiContinuation = buildOpenAiContinuation;
 exports.buildGeminiContinuation = buildGeminiContinuation;
+exports.hasGeminiToolConflict = hasGeminiToolConflict;
 exports.executeClientToolTurn = executeClientToolTurn;
 /**
  * Per-provider continuation message builders and the `executeClientToolTurn`
@@ -70,6 +71,19 @@ const gemini_1 = require("./gemini");
 // ============================================================================
 // Anthropic continuation builder
 // ============================================================================
+/**
+ * Returns `true` when `id` is a usable correlation id — present and non-empty.
+ *
+ * `??` is NOT sufficient for this check: an empty string is a *bad* id (a
+ * `tool_use_id: ''` is rejected by Anthropic as a "malformed identifier") but
+ * `'' ?? fallback` yields `''`, silently passing the empty id through. Every id
+ * correlation in this module must use this predicate, never `??`.
+ *
+ * @internal
+ */
+function isUsableId(id) {
+    return id !== undefined && id.length > 0;
+}
 /**
  * Builds the Anthropic follow-up messages for a client-tool round-trip.
  *
@@ -77,6 +91,15 @@ const gemini_1 = require("./gemini");
  * (all block types in original stream order) and appends a user turn
  * with `tool_result` blocks for each executed tool call.
  *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `tool_result.tool_use_id` is drawn from — and validated against — the set of
+ * assistant `tool_use.id`s actually present in the accumulation buffer. The id
+ * is NEVER derived from the tool name: a tool name can never match a `toolu_*`
+ * id, so a name fallback produces exactly the "malformed identifier" the
+ * provider rejects. If any tool result cannot be correlated to a buffered
+ * `tool_use` block with a non-empty id, the build fails loud (naming the tool)
+ * rather than emitting a malformed continuation.
+ *
  * **Constraint (E3):** The returned continuation does NOT include a forced
  * `tool_choice` field. When thinking is active, Anthropic rejects
  * `tool_choice: { type: 'any' }` and `tool_choice: { type: 'tool', ... }`
@@ -85,11 +108,14 @@ const gemini_1 = require("./gemini");
  *
  * @internal
  */
-function buildAnthropicContinuation(accBuffer, toolResults) {
+function buildAnthropicContinuation(accBuffer, toolResults, logger) {
     // Reconstruct the assistant turn from the ordered accumulation buffer.
     // Sort by buffer key (SSE index) to restore original stream order.
     const sortedKeys = Array.from(accBuffer.keys()).sort((a, b) => a - b);
     const assistantContent = [];
+    // The set of assistant tool_use ids — the single source of truth every
+    // tool_result.tool_use_id must be drawn from.
+    const bufferedToolUseIds = new Set();
     for (const key of sortedKeys) {
         const block = accBuffer.get(key);
         /* c8 ignore next 1 - defensive: key always exists in map since we iterate its keys */
@@ -114,6 +140,12 @@ function buildAnthropicContinuation(accBuffer, toolResults) {
             }
         }
         else if (block.type === 'tool_use') {
+            // A buffered tool_use with an empty id can never be referenced by a valid
+            // tool_result; emitting it would corrupt the assistant turn. Fail loud.
+            if (!isUsableId(block.id)) {
+                return (0, ts_utils_1.fail)(`Anthropic continuation: buffered tool_use block for tool '${block.name}' has an empty id; ` +
+                    `cannot build a valid continuation`);
+            }
             let parsedInput;
             try {
                 /* c8 ignore next 1 - defensive: argsBuffer is JSON-parsed in the adapter before emitting client-tool-call-done */
@@ -124,6 +156,7 @@ function buildAnthropicContinuation(accBuffer, toolResults) {
                 parsedInput = {};
             }
             /* c8 ignore stop */
+            bufferedToolUseIds.add(block.id);
             assistantContent.push({
                 type: 'tool_use',
                 id: block.id,
@@ -132,20 +165,36 @@ function buildAnthropicContinuation(accBuffer, toolResults) {
             });
         }
     }
-    // Build user turn with tool_result blocks for each tool call.
-    const userContent = toolResults.map((r) => {
-        var _a;
+    // Build user turn with tool_result blocks for each tool call. Correlate each
+    // result to a buffered tool_use id — the SAME id that keys the assistant
+    // tool_use block — and fail loud on a missing / empty / mismatched id. A
+    // missing callId is a bug to surface, not paper over with a name fallback.
+    const userContent = [];
+    for (const r of toolResults) {
+        if (!isUsableId(r.callId)) {
+            return (0, ts_utils_1.fail)(`Anthropic continuation: tool '${r.toolName}' result has no call id (missing or empty); ` +
+                `cannot correlate it to an assistant tool_use block`);
+        }
+        if (!bufferedToolUseIds.has(r.callId)) {
+            return (0, ts_utils_1.fail)(`Anthropic continuation: tool '${r.toolName}' call id '${r.callId}' does not match any ` +
+                `buffered assistant tool_use block id`);
+        }
         const block = {
             type: 'tool_result',
             // eslint-disable-next-line @typescript-eslint/naming-convention
-            tool_use_id: (_a = r.callId) !== null && _a !== void 0 ? _a : r.toolName,
+            tool_use_id: r.callId,
             content: r.result
         };
-        if (r.isError) {
-            return Object.assign(Object.assign({}, block), { is_error: true });
-        }
-        return block;
-    });
+        userContent.push(r.isError ? Object.assign(Object.assign({}, block), { is_error: true }) : block);
+    }
+    // Decisive diagnostic: the tool_use.id ↔ tool_result.tool_use_id pairing for
+    // the outgoing continuation. A failing turn is field-confirmable by capturing
+    // this line (the pairing is by construction matched here — divergence fails
+    // loud above, before reaching this point).
+    if (logger) {
+        const pairing = toolResults.map((r) => `${r.toolName}:${r.callId}`).join(', ');
+        logger.detail(`ai-assist:anthropic-continuation tool_use.id↔tool_result.tool_use_id [${pairing}]`);
+    }
     const assistantMessage = {
         role: 'assistant',
         content: assistantContent
@@ -154,7 +203,7 @@ function buildAnthropicContinuation(accBuffer, toolResults) {
         role: 'user',
         content: userContent
     };
-    return {
+    return (0, ts_utils_1.succeed)({
         messages: [assistantMessage, userMessage],
         toolCallsSummary: toolResults.map((r) => ({
             toolName: r.toolName,
@@ -163,7 +212,7 @@ function buildAnthropicContinuation(accBuffer, toolResults) {
             result: r.result,
             isError: r.isError
         }))
-    };
+    });
 }
 // ============================================================================
 // OpenAI / xAI Responses API continuation builder
@@ -176,17 +225,25 @@ function buildAnthropicContinuation(accBuffer, toolResults) {
  * `function_call_output` items (the harness execution result), one pair
  * per executed tool call.
  *
+ * **Single source of truth for the id (id-correlation fix).** Each
+ * `function_call_output.call_id` is drawn from — and validated against — the
+ * set of `function_call.call_id`s in the accumulation map. It is NEVER derived
+ * from the tool name (the OpenAI parity of the Anthropic `tool_use_id` fix). A
+ * missing / empty / unmatched call id fails the build loud rather than emitting
+ * a continuation the provider would reject.
+ *
  * @internal
  */
-function buildOpenAiContinuation(calls, toolResults) {
-    var _a;
+function buildOpenAiContinuation(calls, toolResults, logger) {
     const items = [];
     // Emit function_call items for each call (model's side). Per the Responses API spec
     // (ResponseFunctionToolCall), `call_id` is the required correlation field — it must
     // match the matching function_call_output's `call_id` below. The optional `id` field
     // is the output-item id (`fc_*`) used to reference the streamed item; we omit it
     // because it is not load-bearing for input items.
+    const bufferedCallIds = new Set();
     for (const [callId, call] of calls) {
+        bufferedCallIds.add(callId);
         items.push({
             type: 'function_call',
             call_id: callId,
@@ -194,15 +251,31 @@ function buildOpenAiContinuation(calls, toolResults) {
             arguments: call.argsBuffer
         });
     }
-    // Emit function_call_output items (harness execution results).
+    // Emit function_call_output items (harness execution results). Correlate each
+    // to a buffered function_call call_id — never the tool name — and fail loud on
+    // a missing / empty / mismatched id.
     for (const r of toolResults) {
+        if (!isUsableId(r.callId)) {
+            return (0, ts_utils_1.fail)(`OpenAI continuation: tool '${r.toolName}' result has no call id (missing or empty); ` +
+                `cannot correlate it to a function_call item`);
+        }
+        if (!bufferedCallIds.has(r.callId)) {
+            return (0, ts_utils_1.fail)(`OpenAI continuation: tool '${r.toolName}' call id '${r.callId}' does not match any ` +
+                `accumulated function_call call_id`);
+        }
         items.push({
             type: 'function_call_output',
-            call_id: (_a = r.callId) !== null && _a !== void 0 ? _a : r.toolName,
+            call_id: r.callId,
             output: r.result
         });
     }
-    return {
+    // Decisive diagnostic: the function_call.call_id ↔ function_call_output.call_id
+    // pairing for the outgoing continuation (matched by construction here).
+    if (logger) {
+        const pairing = toolResults.map((r) => `${r.toolName}:${r.callId}`).join(', ');
+        logger.detail(`ai-assist:openai-continuation function_call.call_id↔output.call_id [${pairing}]`);
+    }
+    return (0, ts_utils_1.succeed)({
         messages: items,
         toolCallsSummary: toolResults.map((r) => ({
             toolName: r.toolName,
@@ -211,7 +284,7 @@ function buildOpenAiContinuation(calls, toolResults) {
             result: r.result,
             isError: r.isError
         }))
-    };
+    });
 }
 // ============================================================================
 // Gemini continuation builder
@@ -223,16 +296,23 @@ function buildOpenAiContinuation(calls, toolResults) {
  * user turn with `functionResponse` parts (correlation by tool name, since
  * Gemini does not assign call IDs).
  *
+ * When thinking is enabled, Gemini stamps an opaque `thoughtSignature` on each
+ * `functionCall` part and requires it echoed back, verbatim, as a sibling of
+ * `functionCall` on the continuation's model turn — otherwise the follow-up is
+ * rejected with "Function call is missing a thought_signature in functionCall
+ * parts". The captured signature (see {@link IAccumulatedGeminiFunctionCall})
+ * is replayed here only when present; the key is omitted entirely when thinking
+ * was disabled. See https://ai.google.dev/gemini-api/docs/thought-signatures.
+ *
  * @internal
  */
 function buildGeminiContinuation(calls, toolResults) {
-    // Model turn: functionCall parts for each call.
-    const modelParts = calls.map((call) => ({
-        functionCall: {
+    // Model turn: functionCall parts for each call. Replay the part-level
+    // thoughtSignature as a sibling of functionCall only when present.
+    const modelParts = calls.map((call) => (Object.assign({ functionCall: {
             name: call.name,
             args: call.args
-        }
-    }));
+        } }, (call.thoughtSignature !== undefined ? { thoughtSignature: call.thoughtSignature } : {}))));
     // User turn: functionResponse parts for each executed result.
     // Correlation is by name since Gemini has no call IDs.
     const userParts = toolResults.map((r) => ({
@@ -263,6 +343,20 @@ function buildGeminiContinuation(calls, toolResults) {
 // ============================================================================
 // executeClientToolTurn
 // ============================================================================
+/**
+ * True when a request would combine Gemini built-in grounding (a `web_search`
+ * server tool) with client (function) tools — a combination Gemini's
+ * `generateContent` API rejects with HTTP 400 (`INVALID_ARGUMENT`). Callers gate
+ * on `descriptor.apiFormat === 'gemini'` before consulting this; other providers
+ * accept the mix. Kept as a pure predicate so the conflict rule is unit-testable
+ * without a live stream.
+ *
+ * @internal
+ */
+function hasGeminiToolConflict(tools, clientTools) {
+    var _a;
+    return clientTools.length > 0 && ((_a = tools === null || tools === void 0 ? void 0 : tools.some((t) => t.type === 'web_search')) !== null && _a !== void 0 ? _a : false);
+}
 /**
  * Orchestrates a single client-tool streaming turn for any supported provider.
  *
@@ -285,7 +379,7 @@ function buildGeminiContinuation(calls, toolResults) {
  * @public
  */
 function executeClientToolTurn(params) {
-    const { descriptor, apiKey, system, messages, continuationMessages, temperature, tools, clientTools, signal, logger, resolvedThinking, model, endpoint } = params;
+    const { descriptor, apiKey, system, messages, continuationMessages, temperature, tools, clientTools, signal, logger, resolvedThinking, model, endpoint, onBeforeToolExecute } = params;
     const splitResult = (0, chatRequestBuilders_1.splitChatRequest)(system, messages);
     if (splitResult.isFailure()) {
         return (0, ts_utils_1.fail)(splitResult.message);
@@ -308,11 +402,18 @@ function executeClientToolTurn(params) {
     // This is the fix for P1-1: client tools were never sent to the provider because
     // the adapters only received `tools` (server tools). Both must coexist per design §2.5.
     const effectiveTools = clientTools.length > 0 ? [...(tools !== null && tools !== void 0 ? tools : []), ...clientTools.map((t) => t.config)] : tools;
-    const effectiveTemperature = temperature !== null && temperature !== void 0 ? temperature : 0.7;
-    const resolvedModel = model !== null && model !== void 0 ? model : (0, model_1.resolveModel)(descriptor.defaultModel);
-    if (resolvedModel.length === 0) {
-        return (0, ts_utils_1.fail)(`provider "${descriptor.id}": no model resolved; pass model or set descriptor.defaultModel`);
+    // Gemini pre-flight: its generateContent API HTTP-400s (INVALID_ARGUMENT) when
+    // built-in grounding (`web_search`) and function calling (client tools) are
+    // combined in one request. Fail fast with a clear, actionable message rather
+    // than letting the opaque wire 400 surface. Other providers accept the mix.
+    if (descriptor.apiFormat === 'gemini' && hasGeminiToolConflict(tools, clientTools)) {
+        return (0, ts_utils_1.fail)('executeClientToolTurn: Gemini cannot combine web_search grounding with client (function) tools in the same request; send one or the other');
+    }
+    const modelResult = (0, model_1.resolveProviderModel)(descriptor, model);
+    if (modelResult.isFailure()) {
+        return (0, ts_utils_1.fail)(modelResult.message);
     }
+    const resolvedModel = modelResult.value;
     const baseUrlResult = (0, endpoint_1.resolveEffectiveBaseUrl)(descriptor, endpoint);
     if (baseUrlResult.isFailure()) {
         return (0, ts_utils_1.fail)(baseUrlResult.message);
@@ -332,13 +433,13 @@ function executeClientToolTurn(params) {
     const streamPromise = (() => {
         switch (descriptor.apiFormat) {
             case 'anthropic':
-                return (0, anthropic_1.callAnthropicStream)(config, prompt, head, effectiveTemperature, effectiveTools, logger, signal, resolvedThinking, anthropicBuffer, continuationMessages);
+                return (0, anthropic_1.callAnthropicStream)(config, prompt, head, temperature, effectiveTools, logger, signal, resolvedThinking, anthropicBuffer, continuationMessages);
             case 'openai':
                 return (0, openaiResponses_1.callOpenAiResponsesStream)(config, prompt, 
                 /* c8 ignore next 1 - defensive: openai path requires tools; empty array fallback unreachable in practice */
-                effectiveTools !== null && effectiveTools !== void 0 ? effectiveTools : [], head, effectiveTemperature, logger, signal, resolvedThinking, openAiCallMap, continuationMessages);
+                effectiveTools !== null && effectiveTools !== void 0 ? effectiveTools : [], head, temperature, logger, signal, resolvedThinking, openAiCallMap, continuationMessages);
             case 'gemini':
-                return (0, gemini_1.callGeminiStream)(config, prompt, head, effectiveTemperature, effectiveTools, logger, signal, resolvedThinking, geminiCalls, continuationMessages);
+                return (0, gemini_1.callGeminiStream)(config, prompt, head, temperature, effectiveTools, logger, signal, resolvedThinking, geminiCalls, continuationMessages);
             /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
             default: {
                 const _exhaustive = descriptor.apiFormat;
@@ -424,6 +525,45 @@ function executeClientToolTurn(params) {
                             toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
                             continue;
                         }
+                        // Host gate: run after arg-validation, before execute. A `deny` decision
+                        // synthesizes a denial tool-result and continues the turn; a `fail`/reject
+                        // from the gate itself is a hard error (mirrors an execute failure), never
+                        // a silent deny.
+                        if (onBeforeToolExecute !== undefined) {
+                            const decisionResult = (yield __await((0, ts_utils_1.captureAsyncResult)(async () => onBeforeToolExecute(tool, validationResult.value)))).onSuccess((decision) => decision);
+                            if (decisionResult.isFailure()) {
+                                const errMsg = `${toolName} (callId=${callId}): ${decisionResult.message}`;
+                                const resultEvent = {
+                                    type: 'client-tool-result',
+                                    toolName,
+                                    callId,
+                                    result: errMsg,
+                                    isError: true
+                                };
+                                yield yield __await(resultEvent);
+                                // Gate-fail is a hard, turn-terminating error (unlike a non-fatal `deny`, whose
+                                // generator continues). Emit an explicit `error` event so a consumer watching only
+                                // `events` sees the fatal failure inline and can distinguish it from a deny — matching
+                                // the stream-open / continuation hard-error paths.
+                                yield yield __await({ type: 'error', message: errMsg });
+                                toolResults.push({ toolName, callId, args, result: errMsg, isError: true });
+                                resolveNextTurn((0, ts_utils_1.fail)(errMsg));
+                                return yield __await(void 0);
+                            }
+                            if (decisionResult.value.action === 'deny') {
+                                const denialMsg = `${toolName} (callId=${callId}): tool execution denied: ${decisionResult.value.reason}`;
+                                const resultEvent = {
+                                    type: 'client-tool-result',
+                                    toolName,
+                                    callId,
+                                    result: denialMsg,
+                                    isError: true
+                                };
+                                yield yield __await(resultEvent);
+                                toolResults.push({ toolName, callId, args, result: denialMsg, isError: true });
+                                continue;
+                            }
+                        }
                         const executeResult = yield __await((0, ts_utils_1.captureAsyncResult)(async () => tool.execute(validationResult.value)));
                         const executionResult = executeResult.isSuccess()
                             ? executeResult.value
@@ -505,16 +645,18 @@ function executeClientToolTurn(params) {
                 resolveNextTurn((0, ts_utils_1.succeed)({ continuation: undefined, truncated, fullText }));
                 return yield __await(void 0);
             }
-            let continuation;
+            let continuationResult;
             switch (descriptor.apiFormat) {
                 case 'anthropic':
-                    continuation = buildAnthropicContinuation(anthropicBuffer, toolResults);
+                    continuationResult = buildAnthropicContinuation(anthropicBuffer, toolResults, logger);
                     break;
                 case 'openai':
-                    continuation = buildOpenAiContinuation(openAiCallMap, toolResults);
+                    continuationResult = buildOpenAiContinuation(openAiCallMap, toolResults, logger);
                     break;
                 case 'gemini':
-                    continuation = buildGeminiContinuation(geminiCalls, toolResults);
+                    // Gemini correlates by tool name by design (no call ids) — its builder
+                    // cannot mis-key and stays non-fallible.
+                    continuationResult = (0, ts_utils_1.succeed)(buildGeminiContinuation(geminiCalls, toolResults));
                     break;
                 /* c8 ignore next 5 - defensive coding: exhaustive switch guaranteed by TypeScript */
                 default: {
@@ -523,6 +665,16 @@ function executeClientToolTurn(params) {
                     return yield __await(void 0);
                 }
             }
+            // A bad id-correlation fails loud here rather than emitting a malformed
+            // continuation the provider would reject as a "malformed identifier". Mirror
+            // the stream-open-failure path above: surface an `error` event so a consumer
+            // iterating `events` sees the failure inline, not only via `nextTurn`.
+            if (continuationResult.isFailure()) {
+                resolveNextTurn((0, ts_utils_1.fail)(continuationResult.message));
+                yield yield __await({ type: 'error', message: continuationResult.message });
+                return yield __await(void 0);
+            }
+            let continuation = continuationResult.value;
             // Prepend inbound continuationMessages so the returned continuation is cumulative.
             // A consumer that does `tail = outcome.continuation.messages` (replace) is then
             // correct for all N rounds — messages always contains the full wire tail from