@librechat/agents 3.2.59 → 3.2.61

package/dist/types/graphs/Graph.d.ts

@@ -82,6 +82,14 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      */
     eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
     codeSessionToolNames: string[] | undefined;
+    /**
+     * Run-scoped names of tools whose in-process body may raise a LangGraph
+     * `interrupt()` (e.g. `ask_user_question`). Threaded from
+     * `RunConfig.interruptingToolNames` into every ToolNode this graph
+     * compiles so a mid-batch interrupt cannot double-execute non-idempotent
+     * siblings on resume. See {@link t.ToolNodeOptions.interruptingToolNames}.
+     */
+    interruptingToolNames: string[] | undefined;
     eagerEventToolExecutions: Map<string, t.EagerEventToolExecution>;
     eagerEventToolUsageCount: Map<string, number>;
     private eagerEventToolUsageCountsByAgentId;
@@ -253,14 +261,24 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     dispatchRunStep(stepKey: string, stepDetails: t.StepDetails, metadata?: Record<string, unknown>): Promise<string>;
     /**
      * Static version of handleToolCallError to avoid creating strong references
-     * that prevent garbage collection
+     * that prevent garbage collection.
+     *
+     * Returns whether the error completion event was actually dispatched. A
+     * tool can error before this graph instance has a run step for the call —
+     * on a resume pass the interrupted batch re-executes IMMEDIATELY on graph
+     * re-entry, before any step replay has registered `toolCallStepIds` (a
+     * fast-failing tool, e.g. a schema-validation reject, loses that race).
+     * That is a caller-recoverable condition, not an invariant violation: the
+     * ToolNode falls back to its normal completion dispatch for the error
+     * ToolMessage when this returns `false`, so throwing here would only
+     * replace a recoverable miss with a lost completion event and a scary log.
      */
-    static handleToolCallErrorStatic(graph: StandardGraph, data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<void>;
+    static handleToolCallErrorStatic(graph: StandardGraph, data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<boolean>;
     /**
      * Instance method that delegates to the static method
      * Kept for backward compatibility
      */
-    handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<void>;
+    handleToolCallError(data: t.ToolErrorData, metadata?: Record<string, unknown>): Promise<boolean>;
     dispatchRunStepDelta(id: string, delta: t.ToolCallDelta, metadata?: Record<string, unknown>): Promise<void>;
     dispatchMessageDelta(id: string, delta: t.MessageDelta, metadata?: Record<string, unknown>): Promise<void>;
     dispatchReasoningDelta: (stepId: string, delta: t.ReasoningDelta, metadata?: Record<string, unknown>) => Promise<void>;

package/dist/types/run.d.ts

@@ -14,6 +14,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private toolOutputReferences?;
     private eagerEventToolExecution?;
     private codeSessionToolNames?;
+    private interruptingToolNames?;
     private toolExecution?;
     private subagentUsageSink?;
     private indexTokenCountMap?;

package/dist/types/tools/ToolNode.d.ts

@@ -67,6 +67,13 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private agentLangfuse?;
     toolCallStepIds?: Map<string, string>;
     errorHandler?: t.ToolNodeConstructorParams['errorHandler'];
+    /**
+     * Tool call ids whose `errorHandler` did NOT dispatch the error completion
+     * event (it returned `false` or threw). The output loop must dispatch the
+     * completion for these itself — skipping them there would strand the
+     * client's tool-call part without a terminal event.
+     */
+    private undispatchedToolErrors;
     private toolUsageCount;
     /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
     private toolCallTurns;
@@ -108,6 +115,21 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private executingAgentId?;
     /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
     private directToolNames?;
+    /**
+     * Tool names whose in-process body may raise a LangGraph `interrupt()`
+     * mid-execution (e.g. `ask_user_question`). Used only to REORDER within
+     * the direct group: a tool named here that is *already* direct (a real
+     * in-process graphTool — the only kind whose body can reach
+     * `interrupt()`) is scheduled ahead of its non-interrupting direct
+     * siblings, so a mid-body interrupt unwinds the ToolNode before a
+     * non-idempotent sibling executes and LangGraph's resume-time batch
+     * re-execution can't double it. This set is deliberately NOT folded
+     * into direct classification: a name that resolves to a schema-only
+     * event stub (an inherited `toolDefinition` with no executable
+     * instance) stays event-dispatched — forcing it direct would invoke
+     * the stub, which throws. See {@link t.ToolNodeOptions.interruptingToolNames}.
+     */
+    private interruptingToolNames?;
     /**
      * File checkpointer extracted from the local coding tool bundle when
      * `toolExecution.local.fileCheckpointing === true`. Exposed via
@@ -147,7 +169,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, agentId, executingAgentId, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
@@ -385,6 +407,40 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * The original role is preserved in additional_kwargs for downstream consumers.
      */
     private convertInjectedMessages;
+    /**
+     * Execute a group of direct (in-process) tool calls with interrupt-safe
+     * ordering, returning outputs aligned 1:1 with `directCalls`.
+     *
+     * Fast path (the common case): when no call in the group is in
+     * `interruptingToolNames`, this is a single `Promise.all` — byte-for-byte
+     * the prior behavior, so ordinary batches are unaffected.
+     *
+     * Interrupt-safe path: when the group contains an interrupting tool (e.g.
+     * `ask_user_question`, whose body raises a LangGraph `interrupt()` to
+     * collect a human answer), the interrupting calls run as their own awaited
+     * group **first**; only after they all settle without interrupting do the
+     * remaining (potentially non-idempotent) siblings run. If an interrupting
+     * call throws a `GraphInterrupt`, the `await` below rejects and unwinds the
+     * whole ToolNode *before* any non-interrupting sibling has started — so a
+     * sibling with real side effects (send_email, billing) never executes on
+     * the first pass. On the resume pass LangGraph re-runs the batch from the
+     * top; the interrupting tool resolves with the host's answer instead of
+     * throwing, and the siblings execute for the FIRST time, exactly once.
+     *
+     * Without this ordering, a flat `Promise.all` starts every sibling
+     * concurrently, so a non-idempotent sibling can complete its side effect
+     * before the interrupt unwinds and then run a SECOND time on resume — the
+     * duplicate side effect this method exists to prevent. Interrupting tools
+     * are expected to be side-effect-free (they only suspend), so running them
+     * as a group and re-running them on resume is harmless.
+     *
+     * `batchIndices[i]` is `directCalls[i]`'s position within the parent
+     * ToolNode batch (used for `{{tool<i>turn<n>}}` registration); it is
+     * preserved regardless of execution order. `baseContext` carries the
+     * batch-scoped fields every call shares; `batchIndex` is filled in
+     * per-call here.
+     */
+    private runDirectBatchInterruptSafe;
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
      * Injected messages are placed AFTER ToolMessages to respect provider

package/dist/types/types/hitl.d.ts

@@ -134,6 +134,13 @@ export interface AskUserQuestionRequest {
      * UI allows it. Omit to require a free-form answer.
      */
     options?: AskUserQuestionOption[];
+    /**
+     * When `true`, the host UI may let the user pick several options; the
+     * resulting `AskUserQuestionResolution.answer` is the selected option
+     * values joined by `", "`. When omitted or `false`, hosts render a
+     * single-select picker. Only meaningful alongside `options`.
+     */
+    multiSelect?: boolean;
 }
 /**
  * Structured payload the SDK passes to `interrupt()` when an agent (or
@@ -157,9 +164,10 @@ export type HumanInterruptPayload = ToolApprovalInterruptPayload | AskUserQuesti
 export interface AskUserQuestionResolution {
     /**
      * The human's answer. Free-form text, or — when `options` were
-     * provided — one of the option `value`s. Hosts may also send any
-     * structured object their custom UI defines; see the host docs for
-     * what your downstream consumer expects.
+     * provided — one of the option `value`s (or, when the request set
+     * `multiSelect`, several option `value`s joined by `", "`). Hosts may
+     * also send any structured object their custom UI defines; see the
+     * host docs for what your downstream consumer expects.
      */
     answer: string;
 }
@@ -257,6 +265,44 @@ export declare function isAskUserQuestionInterrupt(payload: unknown): payload is
  * an interrupt. This applies equally to direct tools (handoffs,
  * subagents) and to event tools.
  *
+ * ### Guarding non-idempotent siblings via `interruptingToolNames`
+ *
+ * The "must be idempotent" rule above is unavoidable in the general
+ * case, but the SDK can protect siblings against the one interrupt
+ * shape it can predict: a tool whose *body* raises `interrupt()`
+ * mid-execution — the `ask_user_question` shape, where the tool
+ * suspends the run to collect a human answer. Declare such tools in
+ * `RunConfig.interruptingToolNames`
+ * ({@link ToolNodeOptions.interruptingToolNames}) and the ToolNode
+ * schedules them, within each batch, **ahead of** their
+ * non-interrupting direct siblings. When one interrupts, the batch
+ * unwinds before any declared-safe sibling has run, so the sibling
+ * executes exactly once (on resume) instead of twice. Empirically:
+ *
+ *   - A **direct** sibling sharing the interrupter's in-process
+ *     `Promise.all` is the only shape that double-executes; declaring
+ *     the interrupter closes it.
+ *   - An **event-dispatched** sibling is already safe without any
+ *     config: the ToolNode awaits the whole direct group (where the
+ *     body interrupt unwinds) before it dispatches event tools, so a
+ *     dispatched sibling never runs on the first pass.
+ *
+ * This is a *scheduling* guard, not full resume idempotency: it only
+ * covers tools that interrupt from their own body and only protects
+ * siblings scheduled after them. It does not retroactively make a
+ * `PreToolUse` `'ask'` gate on tool B stop tool A (already executed)
+ * from re-running — unless B is itself declared interrupting, so it
+ * runs first. Tools with side effects should still be written
+ * idempotent as defense in depth.
+ *
+ * The guard only REORDERS the direct group — declaring a name does not
+ * force it onto the direct path. The interrupting tool must already be a
+ * real in-process graphTool (the only kind whose body can reach
+ * `interrupt()`). A name that resolves to a schema-only event stub (an
+ * inherited `toolDefinition` with no executable instance, e.g. in a
+ * self-spawned child that scrubs `graphTools`) stays event-dispatched
+ * and the ordering is a no-op for it.
+ *
  * ## Note on idempotency
  *
  * Same root cause as the resume re-execution above: LangGraph

package/dist/types/types/run.d.ts

@@ -179,6 +179,27 @@ export type RunConfig = {
      * the SDK stays name-agnostic.
      */
     codeSessionToolNames?: string[];
+    /**
+     * Names of host tools whose in-process body may raise a LangGraph
+     * `interrupt()` mid-execution — the canonical example is an
+     * `ask_user_question` tool that suspends the run to collect a human
+     * answer. Within a single tool-call batch, a named tool that is a real
+     * in-process graphTool (the only kind whose body can reach `interrupt()`;
+     * graphTools are auto-marked direct) is scheduled **ahead of** its
+     * non-interrupting direct siblings. That ordering guarantees a mid-body
+     * interrupt unwinds the tool batch before a non-idempotent sibling
+     * (send_email, billing) executes, so the sibling cannot run once on the
+     * first pass and AGAIN when LangGraph re-runs the interrupted batch on
+     * resume.
+     *
+     * This only reorders the direct group — it does NOT force a name onto
+     * the direct path. A name that is only an inherited event `toolDefinition`
+     * (schema-only stub, e.g. in a self-spawned child) stays event-dispatched;
+     * the guard applies only to tools that are independently direct.
+     * Host-declared so the SDK stays name-agnostic; omit to keep the prior
+     * (unguarded) behavior.
+     */
+    interruptingToolNames?: string[];
     /**
      * Selects the execution backend for built-in code tools. Omit this to keep
      * the remote LibreChat Code API sandbox. Set `{ engine: 'local' }` to run

package/dist/types/types/tools.d.ts

@@ -82,7 +82,15 @@ export type ToolNodeOptions = {
     handleToolErrors?: boolean;
     loadRuntimeTools?: ToolRefGenerator;
     toolCallStepIds?: Map<string, string>;
-    errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<void>;
+    /**
+     * Dispatches the error completion event for a failed tool call. Returns
+     * whether the event was actually dispatched — `false` (e.g. no run step is
+     * registered for the call yet, which happens when a tool fails fast on a
+     * resume pass) tells the ToolNode to fall back to its own completion
+     * dispatch for the error ToolMessage. A `void` resolution is treated as
+     * dispatched for backward compatibility.
+     */
+    errorHandler?: (data: ToolErrorData, metadata?: Record<string, unknown>) => Promise<boolean | void>;
     /** Tool registry for lazy computation of programmatic tools and tool search */
     toolRegistry?: LCToolRegistry;
     /** Reference to Graph's sessions map for automatic session injection */
@@ -98,6 +106,34 @@ export type ToolNodeOptions = {
     executingAgentId?: string;
     /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
     directToolNames?: Set<string>;
+    /**
+     * Tool names whose in-process body may raise a LangGraph `interrupt()`
+     * mid-execution — e.g. an `ask_user_question` tool that suspends the
+     * run to collect a human answer.
+     *
+     * Within a single tool-call batch, a named tool that is *already*
+     * direct (a real in-process graphTool — the only kind whose body can
+     * reach `interrupt()`; graphTools are auto-marked direct by the graph)
+     * is executed as its own awaited group **before** its non-interrupting
+     * direct siblings. If it interrupts, the ToolNode unwinds before any
+     * sibling runs, so a non-idempotent sibling (send_email, billing)
+     * cannot execute once on the first pass and AGAIN when LangGraph re-runs
+     * the interrupted batch on resume.
+     *
+     * This set only REORDERS the direct group; it does NOT promote a name
+     * into it. A name that resolves to a schema-only event stub (an
+     * inherited `toolDefinition` with no executable instance — e.g. in a
+     * self-spawned child that scrubs `graphTools`) stays event-dispatched.
+     * Forcing such a name direct would invoke the stub, which throws
+     * "should not be invoked directly in event-driven mode". For the guard
+     * to apply, the interrupting tool must independently be direct.
+     *
+     * Opt-in and empty by default: when unset (or when no direct batch call
+     * matches), direct-batch execution is byte-for-byte unchanged. See the
+     * "Resume re-execution" section of {@link HumanInTheLoopConfig} for the
+     * batch re-execution contract this guards against.
+     */
+    interruptingToolNames?: Set<string>;
     /** Opt-in eager execution for event-driven tool calls. */
     eagerEventToolExecution?: EagerEventToolExecutionConfig;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.2.59",
+  "version": "3.2.61",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -208,7 +208,7 @@
     "fast-xml-parser": "5.7.2",
     "ajv": "6.14.0",
     "minimatch": "3.1.4",
-    "@opentelemetry/core": "^2.8.0",
+    "@opentelemetry/core": "^2.9.0",
     "js-yaml": "^4.2.0"
   },
   "dependencies": {
@@ -230,8 +230,8 @@
     "@langfuse/langchain": "^5.4.1",
     "@langfuse/otel": "^5.4.1",
     "@langfuse/tracing": "^5.4.1",
-    "@opentelemetry/context-async-hooks": "2.7.1",
-    "@opentelemetry/sdk-node": "^0.218.0",
+    "@opentelemetry/context-async-hooks": "^2.9.0",
+    "@opentelemetry/sdk-node": "^0.220.0",
     "@scarf/scarf": "^1.4.0",
     "@types/diff": "^7.0.2",
     "ai-tokenizer": "^1.0.6",

package/src/graphs/Graph.ts

@@ -609,6 +609,14 @@ export abstract class Graph<
    */
   eagerEventToolExecution: t.EagerEventToolExecutionConfig | undefined;
   codeSessionToolNames: string[] | undefined;
+  /**
+   * Run-scoped names of tools whose in-process body may raise a LangGraph
+   * `interrupt()` (e.g. `ask_user_question`). Threaded from
+   * `RunConfig.interruptingToolNames` into every ToolNode this graph
+   * compiles so a mid-batch interrupt cannot double-execute non-idempotent
+   * siblings on resume. See {@link t.ToolNodeOptions.interruptingToolNames}.
+   */
+  interruptingToolNames: string[] | undefined;
   eagerEventToolExecutions: Map<string, t.EagerEventToolExecution> = new Map();
   eagerEventToolUsageCount: Map<string, number> = new Map();
   private eagerEventToolUsageCountsByAgentId: Map<string, Map<string, number>> =
@@ -658,6 +666,7 @@ export abstract class Graph<
     this.toolOutputReferences = undefined;
     this.eagerEventToolExecution = undefined;
     this.codeSessionToolNames = undefined;
+    this.interruptingToolNames = undefined;
     this.eagerEventToolExecutions.clear();
     this.clearEagerEventToolUsageCounts();
     this.eagerEventToolCallChunks.clear();
@@ -1277,11 +1286,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         ),
         toolExecution: this.toolExecution,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
+        interruptingToolNames:
+          this.interruptingToolNames != null &&
+          this.interruptingToolNames.length > 0
+            ? new Set(this.interruptingToolNames)
+            : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,
         toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
         fileCheckpointer: this.getOrCreateFileCheckpointer(),
-        errorHandler: (data, metadata): Promise<void> =>
+        errorHandler: (data, metadata): Promise<boolean> =>
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       });
       this.registerCompiledToolNode(node);
@@ -1330,12 +1344,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // agent so hooks can attribute the batch even at the top level.
       executingAgentId: agentContext?.agentId,
       toolCallStepIds: this.toolCallStepIds,
-      errorHandler: (data, metadata): Promise<void> =>
+      errorHandler: (data, metadata): Promise<boolean> =>
         StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       toolRegistry: agentContext?.toolRegistry,
       sessions: this.sessions,
       toolExecution: this.toolExecution,
       codeSessionToolNames: this.codeSessionToolNames,
+      interruptingToolNames:
+        this.interruptingToolNames != null &&
+        this.interruptingToolNames.length > 0
+          ? new Set(this.interruptingToolNames)
+          : undefined,
       hookRegistry: this.hookRegistry,
       humanInTheLoop: this.humanInTheLoop,
       maxContextTokens: agentContext?.maxContextTokens,
@@ -2361,6 +2380,17 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             childGraph.toolOutputReferences = this.toolOutputReferences;
             childGraph.eagerEventToolExecution = this.eagerEventToolExecution;
             childGraph.codeSessionToolNames = this.codeSessionToolNames;
+            // Pure execution-ordering hint (unlike `humanInTheLoop` above).
+            // It ONLY reorders tools already in the child's direct group;
+            // it does not force a name onto the direct path (that fold-in
+            // was removed — Codex review of #294). So for a self-spawned
+            // child that scrubs inherited `graphTools` (keeping only the
+            // event `toolDefinition` / schema-only stub for a name like
+            // `ask_user_question`), the name isn't in the child's direct
+            // group and this is a no-op — the stub is still dispatched via
+            // ON_TOOL_EXECUTE, never invoked directly. Where the child DOES
+            // have the executable graphTool, the guard correctly applies.
+            childGraph.interruptingToolNames = this.interruptingToolNames;
             childGraph.toolExecution = this.toolExecution;
             childGraph.eventToolExecutionAvailable =
               this.handlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
@@ -2715,32 +2745,38 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
   /**
    * Static version of handleToolCallError to avoid creating strong references
-   * that prevent garbage collection
+   * that prevent garbage collection.
+   *
+   * Returns whether the error completion event was actually dispatched. A
+   * tool can error before this graph instance has a run step for the call —
+   * on a resume pass the interrupted batch re-executes IMMEDIATELY on graph
+   * re-entry, before any step replay has registered `toolCallStepIds` (a
+   * fast-failing tool, e.g. a schema-validation reject, loses that race).
+   * That is a caller-recoverable condition, not an invariant violation: the
+   * ToolNode falls back to its normal completion dispatch for the error
+   * ToolMessage when this returns `false`, so throwing here would only
+   * replace a recoverable miss with a lost completion event and a scary log.
    */
   static async handleToolCallErrorStatic(
     graph: StandardGraph,
     data: t.ToolErrorData,
     metadata?: Record<string, unknown>
-  ): Promise<void> {
-    if (!graph.config) {
-      throw new Error('No config provided');
-    }
-
+  ): Promise<boolean> {
     if (!data.id) {
       console.warn('No Tool ID provided for Tool Error');
-      return;
+      return false;
     }
 
     const stepId = graph.toolCallStepIds.get(data.id) ?? '';
     if (!stepId) {
-      throw new Error(`No stepId found for tool_call_id ${data.id}`);
+      return false;
     }
 
     const { name, input: args, error } = data;
 
     const runStep = graph.getRunStep(stepId);
     if (!runStep) {
-      throw new Error(`No run step found for stepId ${stepId}`);
+      return false;
     }
 
     const tool_call: t.ProcessedToolCall = {
@@ -2751,21 +2787,31 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       progress: 1,
     };
 
-    await graph.handlerRegistry
-      ?.getHandler(GraphEvents.ON_RUN_STEP_COMPLETED)
-      ?.handle(
-        GraphEvents.ON_RUN_STEP_COMPLETED,
-        {
-          result: {
-            id: stepId,
-            index: runStep.index,
-            type: 'tool_call',
-            tool_call,
-          } as t.ToolCompleteEvent,
-        },
-        metadata,
-        graph
-      );
+    // No registered ON_RUN_STEP_COMPLETED handler ⇒ nothing was dispatched.
+    // Report `false` so the ToolNode runs its own fallback dispatch; returning
+    // `true` here would silently drop the error completion for hosts that wire
+    // completions through callback-based custom events instead of a handler.
+    const handler = graph.handlerRegistry?.getHandler(
+      GraphEvents.ON_RUN_STEP_COMPLETED
+    );
+    if (!handler) {
+      return false;
+    }
+
+    await handler.handle(
+      GraphEvents.ON_RUN_STEP_COMPLETED,
+      {
+        result: {
+          id: stepId,
+          index: runStep.index,
+          type: 'tool_call',
+          tool_call,
+        } as t.ToolCompleteEvent,
+      },
+      metadata,
+      graph
+    );
+    return true;
   }
 
   /**
@@ -2775,8 +2821,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   async handleToolCallError(
     data: t.ToolErrorData,
     metadata?: Record<string, unknown>
-  ): Promise<void> {
-    await StandardGraph.handleToolCallErrorStatic(this, data, metadata);
+  ): Promise<boolean> {
+    return StandardGraph.handleToolCallErrorStatic(this, data, metadata);
   }
 
   async dispatchRunStepDelta(

package/src/run.ts

@@ -128,6 +128,7 @@ export class Run<_T extends t.BaseGraphState> {
   private toolOutputReferences?: t.ToolOutputReferencesConfig;
   private eagerEventToolExecution?: t.EagerEventToolExecutionConfig;
   private codeSessionToolNames?: string[];
+  private interruptingToolNames?: string[];
   private toolExecution?: t.ToolExecutionConfig;
   private subagentUsageSink?: t.SubagentUsageSink;
   private indexTokenCountMap?: Record<string, number>;
@@ -184,6 +185,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.toolOutputReferences = config.toolOutputReferences;
     this.eagerEventToolExecution = config.eagerEventToolExecution;
     this.codeSessionToolNames = config.codeSessionToolNames;
+    this.interruptingToolNames = config.interruptingToolNames;
     this.toolExecution = config.toolExecution;
     this.subagentUsageSink = config.subagentUsageSink;
 
@@ -271,6 +273,7 @@ export class Run<_T extends t.BaseGraphState> {
     standardGraph.toolOutputReferences = this.toolOutputReferences;
     standardGraph.eagerEventToolExecution = this.eagerEventToolExecution;
     standardGraph.codeSessionToolNames = this.codeSessionToolNames;
+    standardGraph.interruptingToolNames = this.interruptingToolNames;
     standardGraph.toolExecution = this.toolExecution;
     this.Graph = standardGraph;
     return standardGraph.createWorkflow();
@@ -301,6 +304,7 @@ export class Run<_T extends t.BaseGraphState> {
     multiAgentGraph.toolOutputReferences = this.toolOutputReferences;
     multiAgentGraph.eagerEventToolExecution = this.eagerEventToolExecution;
     multiAgentGraph.codeSessionToolNames = this.codeSessionToolNames;
+    multiAgentGraph.interruptingToolNames = this.interruptingToolNames;
     multiAgentGraph.toolExecution = this.toolExecution;
     this.Graph = multiAgentGraph;
     return multiAgentGraph.createWorkflow();