@falai/agent 2.4.2 → 2.5.0

package/dist/utils/retry.d.ts

@@ -5,6 +5,63 @@ export interface RetryOptions<T> {
     onRetry?: (attempt: number, error: unknown) => void;
     onFailure?: (error: unknown) => boolean;
 }
+/** Provider timeout (ms) + retry count, after defaults are applied. */
+export interface RetryConfig {
+    timeout: number;
+    retries: number;
+}
+/**
+ * Normalize a provider's optional retry config against the defaults. `timeout`
+ * uses `||` (a 0ms timeout is degenerate — it aborts every call immediately — so
+ * fall back to the default), while `retries` uses `??` so an explicit
+ * `retries: 0` (disable retries) is honored rather than treated as unset. Single
+ * definition so this distinction can't drift between providers.
+ */
+export declare function resolveRetryConfig(input?: {
+    timeout?: number;
+    retries?: number;
+}): RetryConfig;
 export declare function retry<T>(options: RetryOptions<T>): Promise<T>;
-export declare const withTimeoutAndRetry: <T>(operation: () => Promise<T>, timeoutMs?: number, maxRetries?: number, operationName?: string) => Promise<T>;
+/**
+ * Combine abort signals into one that aborts as soon as any input aborts.
+ * `undefined` inputs are skipped, so a caller can pass an optional caller-signal
+ * alongside a required per-attempt one. Returns the sole signal when only one is
+ * present (no wrapper), or `undefined` when none are.
+ *
+ * Prefers the platform `AbortSignal.any`, which cleans up its listeners via weak
+ * refs — so merging onto a long-lived caller signal that's reused across many
+ * calls can't accumulate listeners. Falls back to a manual controller on older
+ * runtimes (< Node 20.3); there the listeners live until a source aborts or is
+ * garbage-collected, which is fine for the usual per-request signal.
+ */
+export declare function combineAbortSignals(...signals: Array<AbortSignal | undefined>): AbortSignal | undefined;
+export declare const withTimeoutAndRetry: <T>(operation: (signal: AbortSignal) => Promise<T>, timeoutMs?: number, maxRetries?: number, operationName?: string) => Promise<T>;
+export interface StreamRetryOptions {
+    /** Maximum number of retries after the first attempt. Defaults to 3. */
+    maxRetries?: number;
+    /** Backoff before the next attempt, in ms. Defaults to capped exponential. */
+    delay?: (attempt: number) => number;
+    /** Label used in retry logs. */
+    operationName?: string;
+    /**
+     * Max ms to wait for the *first* chunk (time-to-first-token) before treating
+     * the attempt as failed. Guards a provider that opens a stream and then
+     * stalls. Only the first chunk is bounded — later chunks are unbounded so a
+     * long but healthy stream is never cut off. `0`/omitted disables the deadline.
+     */
+    firstChunkTimeoutMs?: number;
+}
+/**
+ * Streaming analog of {@link withTimeoutAndRetry}. Re-runs an async-generator
+ * factory as long as it fails *before yielding its first chunk* — an empty
+ * completion that throws "No response", an error while establishing the stream,
+ * or (with `firstChunkTimeoutMs`) a stall before the first token. Once any chunk
+ * has been yielded the stream is committed and further errors propagate, so a
+ * retry can never double-emit deltas the consumer has already received.
+ *
+ * This mirrors the non-streaming path, where the provider throws on an empty
+ * completion inside `withTimeoutAndRetry` and is retried on the same model
+ * before the caller falls through to backup models.
+ */
+export declare function withStreamRetry<T>(factory: (signal: AbortSignal) => AsyncGenerator<T>, options?: StreamRetryOptions): AsyncGenerator<T>;
 //# sourceMappingURL=retry.d.ts.map

package/dist/utils/retry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAED,wBAAsB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BnE;AAED,eAAO,MAAM,mBAAmB,GAAU,CAAC,EACzC,WAAW,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,YAAW,MAAc,EACzB,aAAY,MAAU,EACtB,gBAAe,MAAuB,KACrC,OAAO,CAAC,CAAC,CA8CX,CAAC"}
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACnC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACpD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;CACzC;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB;AAOD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,EAAE;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,WAAW,CAKd;AAED,wBAAsB,KAAK,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA8BnE;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,SAAS,CAAC,GACzC,WAAW,GAAG,SAAS,CAgBzB;AAED,eAAO,MAAM,mBAAmB,GAAU,CAAC,EACzC,WAAW,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAC9C,YAAW,MAAc,EACzB,aAAY,MAAU,EACtB,gBAAe,MAAuB,KACrC,OAAO,CAAC,CAAC,CAiDX,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,gCAAgC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAuB,eAAe,CAAC,CAAC,EACtC,OAAO,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,cAAc,CAAC,CAAC,CAAC,EACnD,OAAO,GAAE,kBAAuB,GAC/B,cAAc,CAAC,CAAC,CAAC,CAwDnB"}

package/dist/utils/retry.js

@@ -2,6 +2,23 @@
  * Retry utility with exponential backoff
  */
 import { logger } from './logger';
+const DEFAULT_RETRY_CONFIG = {
+    timeout: 60000,
+    retries: 3,
+};
+/**
+ * Normalize a provider's optional retry config against the defaults. `timeout`
+ * uses `||` (a 0ms timeout is degenerate — it aborts every call immediately — so
+ * fall back to the default), while `retries` uses `??` so an explicit
+ * `retries: 0` (disable retries) is honored rather than treated as unset. Single
+ * definition so this distinction can't drift between providers.
+ */
+export function resolveRetryConfig(input) {
+    return {
+        timeout: input?.timeout || DEFAULT_RETRY_CONFIG.timeout,
+        retries: input?.retries ?? DEFAULT_RETRY_CONFIG.retries,
+    };
+}
 export async function retry(options) {
     const { operation, maxRetries, delay, onRetry, onFailure } = options;
     let lastError;
@@ -28,6 +45,38 @@ export async function retry(options) {
     // eslint-disable-next-line @typescript-eslint/only-throw-error
     throw lastError ?? new Error("Operation failed");
 }
+/** Capped exponential backoff (1s, 2s, 4s, … max 5s) shared by the retry helpers. */
+const defaultBackoff = (attempt) => Math.min(1000 * Math.pow(2, attempt), 5000);
+/**
+ * Combine abort signals into one that aborts as soon as any input aborts.
+ * `undefined` inputs are skipped, so a caller can pass an optional caller-signal
+ * alongside a required per-attempt one. Returns the sole signal when only one is
+ * present (no wrapper), or `undefined` when none are.
+ *
+ * Prefers the platform `AbortSignal.any`, which cleans up its listeners via weak
+ * refs — so merging onto a long-lived caller signal that's reused across many
+ * calls can't accumulate listeners. Falls back to a manual controller on older
+ * runtimes (< Node 20.3); there the listeners live until a source aborts or is
+ * garbage-collected, which is fine for the usual per-request signal.
+ */
+export function combineAbortSignals(...signals) {
+    const present = signals.filter((s) => s != null);
+    if (present.length <= 1)
+        return present[0];
+    if (typeof AbortSignal.any === "function")
+        return AbortSignal.any(present);
+    const controller = new AbortController();
+    for (const signal of present) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener("abort", () => controller.abort(signal.reason), {
+            once: true,
+        });
+    }
+    return controller.signal;
+}
 export const withTimeoutAndRetry = async (operation, timeoutMs = 60000, maxRetries = 3, operationName = "AI operation") => {
     const createTimeoutOperation = () => async () => {
         const controller = new AbortController();
@@ -35,8 +84,11 @@ export const withTimeoutAndRetry = async (operation, timeoutMs = 60000, maxRetri
             controller.abort();
         }, timeoutMs);
         try {
+            // Hand the operation the timeout signal so the in-flight upstream call is
+            // actually cancelled when the deadline fires — otherwise the abandoned
+            // attempt keeps running while the retry stacks a second concurrent call.
             const result = await Promise.race([
-                operation(),
+                operation(controller.signal),
                 new Promise((_, reject) => {
                     controller.signal.addEventListener("abort", () => {
                         reject(new Error(`Operation timed out after ${timeoutMs}ms`));
@@ -54,11 +106,11 @@ export const withTimeoutAndRetry = async (operation, timeoutMs = 60000, maxRetri
     return retry({
         operation: createTimeoutOperation(),
         maxRetries,
-        delay: (attempt) => Math.min(1000 * Math.pow(2, attempt), 5000),
+        delay: defaultBackoff,
         onRetry: (attempt, error) => {
             const message = error instanceof Error ? error.message : String(error);
             logger.error(`[${operationName}] Failed attempt ${attempt + 1}:`, message);
-            const delay = Math.min(1000 * Math.pow(2, attempt), 5000);
+            const delay = defaultBackoff(attempt);
             logger.debug(`[${operationName}] Retrying in ${delay}ms...`);
             logger.debug(`[${operationName}] Attempt ${attempt + 2}/${maxRetries + 1}`);
         },
@@ -68,4 +120,74 @@ export const withTimeoutAndRetry = async (operation, timeoutMs = 60000, maxRetri
         },
     });
 };
+/** Reject if `next` hasn't settled within `timeoutMs`; always clears its timer. */
+function raceFirstChunk(next, timeoutMs, operationName) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`[${operationName}] Stream timed out: no first chunk within ${timeoutMs}ms`)), timeoutMs);
+    });
+    return Promise.race([next, timeout]).finally(() => clearTimeout(timer));
+}
+/**
+ * Streaming analog of {@link withTimeoutAndRetry}. Re-runs an async-generator
+ * factory as long as it fails *before yielding its first chunk* — an empty
+ * completion that throws "No response", an error while establishing the stream,
+ * or (with `firstChunkTimeoutMs`) a stall before the first token. Once any chunk
+ * has been yielded the stream is committed and further errors propagate, so a
+ * retry can never double-emit deltas the consumer has already received.
+ *
+ * This mirrors the non-streaming path, where the provider throws on an empty
+ * completion inside `withTimeoutAndRetry` and is retried on the same model
+ * before the caller falls through to backup models.
+ */
+export async function* withStreamRetry(factory, options = {}) {
+    const { maxRetries = 3, delay = defaultBackoff, operationName = "AI stream", firstChunkTimeoutMs, } = options;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        // One controller per attempt: aborting it on abandon cancels the upstream
+        // SDK call so a retry can't stack a second concurrent stream.
+        const controller = new AbortController();
+        const iterator = factory(controller.signal);
+        let yielded = false;
+        let completed = false;
+        try {
+            // Drive the iterator by hand so the first chunk can be raced against a
+            // deadline; for-await would give no hook for that.
+            for (;;) {
+                const result = !yielded && firstChunkTimeoutMs
+                    ? await raceFirstChunk(iterator.next(), firstChunkTimeoutMs, operationName)
+                    : await iterator.next();
+                if (result.done) {
+                    completed = true;
+                    return;
+                }
+                yielded = true;
+                yield result.value;
+            }
+        }
+        catch (error) {
+            // Can't retry once deltas are out, and don't retry past the budget.
+            if (yielded || attempt === maxRetries) {
+                throw error;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error(`[${operationName}] Failed attempt ${attempt + 1}:`, message);
+            const delayMs = delay(attempt);
+            logger.debug(`[${operationName}] Retrying in ${delayMs}ms... (attempt ${attempt + 2}/${maxRetries + 1})`);
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+        finally {
+            // Abandoning an attempt (first-chunk timeout, pre-yield error before a
+            // retry, or a consumer that breaks early): abort the upstream SDK call
+            // first so it's actually torn down — not left running while we retry —
+            // then dispose the iterator. Aborting also unblocks a stalled
+            // iterator.next() so return() can run the generator's cleanup. Both are
+            // fire-and-forget: a wedged generator's return() may never settle, so we
+            // must not await it.
+            if (!completed) {
+                controller.abort();
+                void iterator.return?.(undefined)?.catch(() => undefined);
+            }
+        }
+    }
+}
 //# sourceMappingURL=retry.js.map

package/dist/utils/retry.js.map

@@ -1 +1 @@
-{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/utils/retry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@falai/agent",
-  "version": "2.4.2",
+  "version": "2.5.0",
   "description": "Conversational state engine for TypeScript where the AI understands, but the code is in control",
   "type": "module",
   "main": "./dist/cjs/index.js",

package/src/core/PersistenceManager.ts

@@ -42,6 +42,24 @@ export class PersistenceManager<TData = Record<string, unknown>> {
     this.messageRepository = config.adapter.messageRepository;
   }
 
+  /**
+   * Reject a non-string id before it reaches a repository query filter.
+   *
+   * SECURITY: session/user ids flow into adapter query VALUE positions (e.g.
+   * Mongo `findOne({ id })`). A non-string value such as `{ $ne: null }` —
+   * trivially produced by an HTTP body or an Express `?id[$ne]=` query — would
+   * be interpreted by a NoSQL driver as query operators, turning an equality
+   * lookup into an operator query (cross-tenant read / mass delete). Callers
+   * type these as `string`, but that guarantee is erased at runtime, so we
+   * enforce it here: the single layer every public session/user lookup funnels
+   * through.
+   */
+  private assertScalarId(value: unknown, label: string): asserts value is string {
+    if (typeof value !== "string" || value.length === 0) {
+      throw new Error(`${label} must be a non-empty string`);
+    }
+  }
+
   /**
    * Create a new session
    */
@@ -67,6 +85,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
    * Get session by ID
    */
   async getSession(sessionId: string): Promise<SessionData<TData> | null> {
+    this.assertScalarId(sessionId, "Session ID");
     return await this.sessionRepository.findById(sessionId);
   }
 
@@ -80,6 +99,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
         "userId must be provided or configured in PersistenceConfig"
       );
     }
+    this.assertScalarId(effectiveUserId, "User ID");
     return await this.sessionRepository.findActiveByUserId(effectiveUserId);
   }
 
@@ -96,6 +116,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
         "userId must be provided or configured in PersistenceConfig"
       );
     }
+    this.assertScalarId(effectiveUserId, "User ID");
     return await this.sessionRepository.findByUserId(effectiveUserId, limit);
   }
 
@@ -170,6 +191,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
     sessionId: string,
     limit?: number
   ): Promise<MessageData[]> {
+    this.assertScalarId(sessionId, "Session ID");
     return await this.messageRepository.findBySessionId(sessionId, limit);
   }
 
@@ -186,6 +208,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
         "userId must be provided or configured in PersistenceConfig"
       );
     }
+    this.assertScalarId(effectiveUserId, "User ID");
     return await this.messageRepository.findByUserId(effectiveUserId, limit);
   }
 
@@ -193,6 +216,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
    * Delete a session and all its messages
    */
   async deleteSession(sessionId: string): Promise<boolean> {
+    this.assertScalarId(sessionId, "Session ID");
     // Delete all messages first
     await this.messageRepository.deleteBySessionId(sessionId);
 
@@ -260,9 +284,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
     sessionStep: SessionState<TData>
   ): Promise<SessionData<TData> | null> {
     // Validate input parameters
-    if (!sessionId || typeof sessionId !== 'string') {
-      throw new Error('Session ID must be a non-empty string');
-    }
+    this.assertScalarId(sessionId, "Session ID");
 
     if (!sessionStep || typeof sessionStep !== 'object') {
       throw new Error('Session step must be a valid object');
@@ -307,9 +329,10 @@ export class PersistenceManager<TData = Record<string, unknown>> {
       } else {
         saved = await this.sessionRepository.create({
           id: sessionId,
-          userId: persistenceData.collectedData.metadata?.userId
-            ? JSON.stringify(persistenceData.collectedData.metadata?.userId)
-            : this.config.userId,
+          // Owner is the authenticated principal from config — never derived
+          // from collectedData.metadata (model/user-influenced state), which
+          // would let collected data mis-attribute a session's tenant.
+          userId: this.config.userId,
           status: "active",
           currentFlow: persistenceData.currentFlow,
           currentStep: persistenceData.currentStep,
@@ -342,6 +365,7 @@ export class PersistenceManager<TData = Record<string, unknown>> {
   async loadSessionState(
     sessionId: string
   ): Promise<SessionState<TData> | null> {
+    this.assertScalarId(sessionId, "Session ID");
     const sessionData = await this.sessionRepository.findById(sessionId);
 
     if (!sessionData) {

package/src/core/ResponseModal.ts

@@ -1243,6 +1243,10 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             // Stream chunks with unified tool handling
             for await (const chunk of stream) {
                 let toolCalls: Array<{ toolName: string; arguments: Record<string, unknown> }> | undefined = undefined;
+                // Final message/structured may be replaced by a forced post-tool
+                // response (see runStreamingBatch / gap: tools-ran-but-no-text).
+                let finalAccumulated = chunk.accumulated;
+                let finalStructured = chunk.structured;
 
                 // Extract tool calls from AI response on final chunk
                 if (chunk.done && chunk.structured?.toolCalls) {
@@ -1265,9 +1269,18 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     });
                     session = batchResult.session;
                     toolCalls = batchResult.toolCalls;
+
+                    // Tools ran but the model produced no result-aware text — use
+                    // the forced closing message so we never emit the bare
+                    // preamble (or an empty message) as the final response.
+                    if (batchResult.finalMessage) {
+                        finalAccumulated = batchResult.finalMessage;
+                        finalStructured = batchResult.structured ?? finalStructured;
+                    }
                 }
 
-                // Extract collected data on final chunk
+                // Extract collected data on final chunk (from the model's own
+                // structured output for this step, not the forced follow-up)
                 if (chunk.done && chunk.structured && nextStep.collect) {
                     session = await this.collectDataFromResponse({
                         result: { structured: chunk.structured },
@@ -1283,7 +1296,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 // - session.currentStep: reflects the executed step
                 yield {
                     delta: chunk.delta,
-                    accumulated: chunk.accumulated,
+                    accumulated: finalAccumulated,
                     done: chunk.done,
                     session,
                     toolCalls,
@@ -1291,7 +1304,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     executedSteps: chunk.done ? [{ id: nextStep.id, flowId: selectedFlow.id }] : undefined,
                     stoppedReason: chunk.done ? 'needs_input' : undefined,
                     metadata: chunk.metadata,
-                    structured: chunk.structured,
+                    structured: finalStructured,
                     appliedInstructions: chunk.done ? appliedInstructions : undefined,
                 };
             }

package/src/core/SessionManager.ts

@@ -59,6 +59,13 @@ export class SessionManager<TData = unknown> {
    * Works for sessionIds that exist, don't exist, or auto-generated IDs
    */
   async getOrCreate(sessionId?: string): Promise<SessionState<TData>> {
+    // SECURITY: a non-string sessionId (e.g. `{ $ne: null }` from an HTTP body
+    // or `?sessionId[$ne]=` query) forwarded into a NoSQL query becomes an
+    // operator clause. Reject it at the entry point; `undefined` is allowed and
+    // auto-generates an id, and an empty string keeps its fall-back semantics.
+    if (sessionId !== undefined && typeof sessionId !== "string") {
+      throw new Error("sessionId must be a string");
+    }
     // Use provided sessionId or fall back to default
     const effectiveSessionId = sessionId || this.defaultSessionId;
 

package/src/core/StreamingToolExecutor.ts

@@ -19,6 +19,7 @@ import type {
     Tool,
     TrackedTool,
 } from "../types/tool";
+import { evaluateToolGates } from "./toolGates";
 
 /** Options for the StreamingToolExecutor */
 interface StreamingToolExecutorOptions {
@@ -221,6 +222,17 @@ export class StreamingToolExecutor<TContext = unknown, TData = unknown> {
         const batchAbortController = this.siblingAbortController;
 
         try {
+            // Pre-execution gates (validateInput → checkPermissions), shared with
+            // ToolManager.executeTool. These MUST run on the streaming path too:
+            // when a gate denies, the handler is NOT invoked. Run before any abort
+            // wiring so a denial returns cleanly with nothing to unwind.
+            const gateDenial = await evaluateToolGates(tool, toolCall.arguments, this.toolContext);
+            if (gateDenial) {
+                tracked.results.push(gateDenial);
+                tracked.status = "completed";
+                return;
+            }
+
             // Create a combined abort signal from parent + sibling
             const toolAbortController = new AbortController();
             const abortTool = () => {