@librechat/agents 3.9.2 → 3.9.4

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

@@ -2,3 +2,4 @@ export * from './Graph';
 export * from './MultiAgentGraph';
 export * from './createGraph';
 export type * from './graphFactory';
+export { HandoffLimitError } from './handoff';

package/dist/types/messages/fading.d.ts

@@ -1,5 +1,10 @@
 import type { FadingTier } from '@/types/graph';
-export declare const FADING_TIER_VERSION = 1;
+/**
+ * Version 2: exchange width counts only the current turn. Version 1 tiers may
+ * have latched on history whose steps storage had merged into one assistant
+ * message, so they are discarded and re-derived once.
+ */
+export declare const FADING_TIER_VERSION = 2;
 /** Context pressure at which observation masking activates. */
 export declare const PRESSURE_THRESHOLD_MASKING = 0.8;
 /** Smallest token budget the ladder can shrink to; keeps the emergency floor near 200 chars. */
@@ -12,7 +17,7 @@ export type FadingSignals = {
     /** (pruningBudget − instruction tokens) ÷ calibrationRatio, in raw token space. */
     effectiveRawTokens: number;
     summarizationEnabled: boolean;
-    /** Largest number of parallel calls observed in one assistant exchange. */
+    /** Largest number of parallel calls in one assistant exchange of the current turn. */
     toolExchangeWidth?: number;
     /** Recovery paths force at least this rung on the current window's ladder. */
     minRung?: number;
@@ -29,6 +34,13 @@ export type FadingCaps = {
 /** Tier for a conversation that has never faded: the whole window, nothing masked. */
 export declare function createFadingTier(window: number): FadingTier;
 export declare function isFadingTier(value: unknown): value is FadingTier;
+/**
+ * A well-formed tier persisted before version 2. Stored snapshots that carry
+ * one (resume manifests, session files) stay valid; every consumer then drops
+ * it through `isFadingTier`, so the tier re-derives once instead of the
+ * snapshot being rejected as corrupt.
+ */
+export declare function isLegacyFadingTier(value: unknown): boolean;
 /** Deepest rung for a window: the point where the budget reaches its floor. */
 export declare function maxFadingRung(window: number): number;
 /** Token budget at a rung: the window halved per rung, never below the floor. */

package/dist/types/messages/prune.d.ts

@@ -250,6 +250,13 @@ export declare function preFlightTruncateToolResults(params: {
     indexTokenCountMap: Record<string, number | undefined>;
     tokenCounter: TokenCounter;
 }): number;
+/**
+ * Leads every shortened tool-call input. Fading only shortens calls already in
+ * history, which ran with their full input; a model that reads a shortened copy
+ * as a call that was cut off re-issues it, and a side-effecting tool (sending an
+ * email) then runs again. The note says what actually happened.
+ */
+export declare const TOOL_INPUT_ELISION_NOTE = "Completed call; input shortened to save context.";
 /**
  * Serializes one structured tool-call input as valid, bounded JSON without
  * invoking user-defined accessors or `toJSON`.

package/dist/types/openai/arguments.d.ts

@@ -0,0 +1,2 @@
+/** OpenAI-only compatibility import; validation belongs to the graph-safe utility. */
+export { serializeToolArguments } from '@/utils/acceptedToolArguments';

package/dist/types/openai/index.d.ts

@@ -73,3 +73,5 @@ export declare function createChatCompletionUsageChunk(context: OpenAIResponseCo
 export declare function writeOpenAISSE(writer: OpenAICompatibleWriter, data: OpenAIChatCompletionChunk | '[DONE]'): Promise<void>;
 export declare function createOpenAIHandlers(config: OpenAIHandlerConfig): Record<string, t.EventHandler>;
 export declare function sendOpenAIFinalChunk(config: OpenAIHandlerConfig, finishReason?: OpenAIChatCompletionChunkChoice['finish_reason']): Promise<void>;
+export { createOpenAIToolCallStream } from './toolProjection';
+export type { OpenAIToolCallStream, OpenAIToolCallStreamConfig, } from './toolProjection';

package/dist/types/openai/toolProjection.d.ts

@@ -0,0 +1,30 @@
+import type { OpenAIChatCompletionChunkChoice, OpenAIToolCall, OpenAIStreamTracker } from './index';
+import type { EventHandler } from '@/types';
+interface OpenAIToolCallStreamOptions {
+    /** Synchronous framing only. Async transport/backpressure is a separate boundary. */
+    emit?: (delta: OpenAIChatCompletionChunkChoice['delta']) => void;
+    signal?: AbortSignal;
+    /** Bound retained complete-before-publish output, not model execution. Default: 1024. */
+    maxToolCalls?: number;
+    /** UTF-8 bytes of serialized arguments, names and IDs retained across accepted responses. Default: 4 MiB. */
+    maxBufferedBytes?: number;
+}
+/** Streaming hosts share the finalizer's tracker; map-only hosts collect JSON output. */
+export type OpenAIToolCallStreamConfig = OpenAIToolCallStreamOptions & ({
+    tracker: OpenAIStreamTracker;
+    toolCalls?: never;
+    emit: NonNullable<OpenAIToolCallStreamOptions['emit']>;
+} | {
+    toolCalls: Map<number, OpenAIToolCall>;
+    tracker?: never;
+});
+export interface OpenAIToolCallStream {
+    /** Pass directly to Run.create({ customHandlers: stream.handlers }). */
+    handlers: Record<string, EventHandler>;
+    /** Publish only after the host verifies that the entire run completed successfully. */
+    finish: () => void;
+    abort: () => void;
+}
+/** Serializes finalized, accepted tool calls. No provider fragments or attempt inference. */
+export declare function createOpenAIToolCallStream(config: OpenAIToolCallStreamConfig): OpenAIToolCallStream;
+export {};

package/dist/types/run.d.ts

@@ -14,6 +14,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     private langfuse?;
     private toolOutputReferences?;
     private eagerEventToolExecution?;
+    private clientDelegatedToolNames?;
     private codeSessionToolNames?;
     private interruptingToolNames?;
     private toolExecution?;
@@ -60,6 +61,7 @@ export declare class Run<_T extends t.BaseGraphState> {
     /** Distinguishes sibling forks started from the same explicit checkpoint. */
     private checkpointForkSeq;
     private _haltedReason;
+    private _handoffOutcome?;
     private constructor();
     private createLegacyGraph;
     private createMultiAgentGraph;
@@ -216,6 +218,9 @@ export declare class Run<_T extends t.BaseGraphState> {
      * no halt reason.
      */
     getHaltReason(): string | undefined;
+    private getHandoffIncompleteReason;
+    /** Execution evidence only. The host must authorize and durably commit a candidate. */
+    getHandoffOutcome(): t.HandoffOutcome | undefined;
     /**
      * Resume a paused HITL run with the value the user (or whatever
      * decided the interrupt) supplied. The default `TResume` covers the

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

@@ -228,7 +228,8 @@ 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, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executionContext, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
+    private handoffRouting?;
+    constructor({ handoffRouting, tools, toolMap, name, tags, trace, runLangfuse, agentLangfuse, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executionContext, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, onToolCallsClaimed, }: t.ToolNodeConstructorParams);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     private withToolScope;
     /**

package/dist/types/types/graph.d.ts

@@ -4,8 +4,8 @@ import type { START, StateGraph, StateGraphArgs } from '@langchain/langgraph';
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
+import type { RunStep, ModelResponseEvent, ModelToolsClaimedEvent, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, CompactionSemanticIndex, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
-import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecutionConfig, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { SubagentTaskConfig } from '@/types/subagentTasks';
@@ -27,9 +27,47 @@ export type ClientCallbacks = {
 export type SystemCallbacks = {
     [K in keyof ClientCallbacks]: ClientCallbacks[K] extends ClientCallback<infer Args> ? (...args: Args) => void : never;
 };
+/** An executed, SDK-generated handoff, identified independently of stream events. */
+export interface HandoffTransition {
+    id: string;
+    sourceAgentId: string;
+    targetAgentId: string;
+    toolCallId: string;
+    scope: 'turn' | 'conversation';
+    /** Causal order: number of handoffs visible at this batch's input. */
+    depth: number;
+}
+/** Versioned graph checkpoint payload, scoped to one logical user turn. */
+export interface HandoffState {
+    version: 1;
+    executionId: string;
+    entryAgentId: string;
+    maxHandoffs?: number;
+    transitions: HandoffTransition[];
+    parallel: boolean;
+    /** False when resuming an older checkpoint without complete routing provenance. */
+    historyComplete?: boolean;
+}
+/** Only a candidate from a completed top-level run may be promoted by a host. */
+export type HandoffOutcome = {
+    executionId: string;
+    entryAgentId: string;
+    transitions: readonly HandoffTransition[];
+} & ({
+    status: 'candidate';
+    agentId: string;
+    transitionId: string;
+} | {
+    status: 'unchanged' | 'ambiguous';
+} | {
+    status: 'incomplete';
+    reason: string;
+});
 export type BaseGraphState = {
     messages: BaseMessage[];
     runStepState?: RunStepResumeState;
+    /** SDK-owned routing state; hosts must not synthesize it from messages. */
+    handoffState?: HandoffState;
     /**
      * The summary a summarize-only run produced. Kept in state because such a
      * run has no assistant reply: trace roots report it as the run's output
@@ -89,7 +127,7 @@ export interface ContextUsageEvent {
  * `RunConfig.fadingTiers[agentId]`.
  */
 export interface FadingTier {
-    v: 1;
+    v: 2;
     /** Token budget the caps derive from, in raw token space. Never grows;
      *  clamped to the current context window when seeded. */
     budgetTokens: number;
@@ -101,7 +139,7 @@ export interface FadingTier {
 /** Latched fading tiers keyed by agent ID. */
 export type FadingTiers = Record<string, FadingTier>;
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
+    handle(event: string, data: StreamEventData | ModelEndData | ModelResponseEvent | ModelToolsClaimedEvent | RunStep | RunStepDeltaEvent | RunStepClosedEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ContextUsageEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -253,6 +291,8 @@ export type StandardGraphInput = {
     agents: AgentInputs[];
     /** Execution backend used to resolve the effective tool registry. */
     toolExecution?: ToolExecutionConfig;
+    /** Trusted single-agent client delegation policy; mixed batches fail closed. */
+    clientDelegatedToolNames?: readonly string[];
     langfuse?: LangfuseConfig;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
@@ -316,6 +356,8 @@ export type GraphEdge = {
     condition?: (state: BaseGraphState) => boolean | string | string[];
     /** 'handoff' creates tools for dynamic routing, 'direct' creates direct edges, which also allow parallel execution */
     edgeType?: 'handoff' | 'direct';
+    /** Host may promote the destination after successful top-level completion. */
+    handoffScope?: 'turn' | 'conversation';
     /**
      * For direct edges: Optional prompt to add when transitioning through this edge.
      * String prompts can include variables like {results} which will be replaced with
@@ -337,13 +379,18 @@ export type GraphEdge = {
      */
     promptKey?: string;
 };
-export type GraphSubagentEdge = Omit<GraphEdge, 'edgeType' | 'condition' | 'promptKey'> & {
+export type GraphSubagentEdge = Omit<GraphEdge, 'edgeType' | 'condition' | 'promptKey' | 'handoffScope'> & {
     edgeType: 'direct';
     condition?: never;
     promptKey?: never;
+    handoffScope?: never;
 };
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
+    /** Explicit fresh-turn entry; absent preserves topology-inferred entry points. */
+    entryAgentId?: string;
+    /** Shared logical-turn handoff cap. Zero forbids handoffs; absent uses only recursion limits. */
+    maxHandoffs?: number;
     /** Captures the designated member's final AI turn in graph state. */
     resultAgentId?: string;
     /** Optional per-member Pregel budget when the outer graph has its own topology budget. */

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

@@ -101,8 +101,10 @@ export type MultiAgentGraphConfig = {
     compileOptions?: g.CompileOptions;
     agents: g.AgentInputs[];
     edges: g.GraphEdge[];
+    entryAgentId?: string;
+    maxHandoffs?: number;
 };
-export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type'> & {
+export type StandardGraphConfig = Omit<MultiAgentGraphConfig, 'edges' | 'type' | 'entryAgentId' | 'maxHandoffs'> & {
     type?: 'standard';
     signal?: AbortSignal;
 };
@@ -258,6 +260,11 @@ export type RunConfig = {
      */
     langfuse?: g.LangfuseConfig;
     customHandlers?: Record<string, g.EventHandler>;
+    /** Explicit client-owned tools for a single-agent graph. A batch mixing
+     * client and SDK/provider calls fails closed; omitted means SDK ownership.
+     * Hosts must register the corresponding model-facing tool schemas.
+     */
+    clientDelegatedToolNames?: readonly string[];
     /**
      * Receives token usage for every model call made inside subagent child
      * runs (including nested subagents). Child graphs execute via `invoke()`

package/dist/types/types/stream.d.ts

@@ -1,4 +1,4 @@
-import type { MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessage } from '@langchain/core/messages';
+import type { AIMessageChunk, MessageContentImageUrl, MessageContentText, ToolMessage, BaseMessage } from '@langchain/core/messages';
 import type { ToolCall, ToolCallChunk } from '@langchain/core/messages/tool';
 import type { LLMResult, Generation } from '@langchain/core/outputs';
 import type { Command } from '@langchain/langgraph';
@@ -8,6 +8,21 @@ import type { AssistantTextPhase } from '@/types/assistantPhase';
 import type { SummarizeCompleteEvent } from '@/types/summarize';
 import type { ToolEndEvent } from '@/types/tools';
 import { StepTypes, ContentTypes, GraphEvents } from '@/common/enum';
+/** One accepted model result, detached from execution state before host dispatch.
+ * Provider chunks, failed attempts and UI run-step events are not this contract. */
+export interface ModelResponseEvent {
+    type: 'model_response';
+    /** Graph-generated acceptance ID, not a provider ID or run-step index. */
+    id: string;
+    agentId: string;
+    /** Graph-state message identity used to correlate ToolNode ownership. */
+    messageId?: string;
+    toolCalls: ReadonlyArray<ToolCall>;
+    /** Same index as toolCalls. Only a trusted graph decision of 'client'
+     * permits this call on the OpenAI client wire; absence fails closed. */
+    toolCallDispositions: ReadonlyArray<'sdk' | 'provider' | 'client'>;
+    invalidToolCalls: ReadonlyArray<NonNullable<AIMessageChunk['invalid_tool_calls']>[number]>;
+}
 export type HandleLLMEnd = (output: LLMResult, runId: string, parentRunId?: string, tags?: string[]) => void;
 export type MetadataAggregatorResult = {
     handleLLMEnd: HandleLLMEnd;
@@ -442,3 +457,9 @@ export type ContentAggregatorResult = {
     contentParts: Array<MessageContentComplex | undefined>;
     aggregateContent: ContentAggregator;
 };
+/** Ownership, not successful completion. Interrupted/failed batches remain graph-owned. */
+export interface ModelToolsClaimedEvent {
+    type: 'model_tools_claimed';
+    agentId: string;
+    messageId: string;
+}

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

@@ -6,6 +6,7 @@ import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { LangfuseConfig, SubagentExecutionContext } from './graph';
 import type { PreparedSubagents } from '@/tools/preparedSubagents';
 import type { RunBreakerScope } from '@/llm/streamLimits';
+import type { HandoffRouting } from '@/graphs/handoff';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { HookRegistry } from '@/hooks';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
@@ -103,6 +104,8 @@ export type EagerEventToolCallChunkState = {
     sealedArgsFragment?: string;
 };
 export type ToolNodeOptions = {
+    /** @internal Admission shared by tool nodes belonging to one multi-agent graph. */
+    handoffRouting?: Pick<HandoffRouting, 'finalize'>;
     name?: string;
     tags?: string[];
     /** Enables LangChain/LangGraph tracing for this ToolNode. Defaults to false. */
@@ -290,6 +293,8 @@ export type ToolNodeOptions = {
     restoreRunStepResumeState?: (state?: RunStepResumeState, config?: RunnableConfig) => void;
     /** SDK-owned checkpoint snapshot for open run-step lifecycle state. */
     createRunStepResumeState?: () => RunStepResumeState;
+    /** Internal ownership bridge, awaited before ToolNode can execute a batch. */
+    onToolCallsClaimed?: (messageId: string, config: RunnableConfig) => Promise<void>;
 };
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
 export type ToolEndEvent = {

package/dist/types/utils/acceptedToolArguments.d.ts

@@ -0,0 +1,10 @@
+/** Encode JSON data, not arbitrary JS values. No getters, proxies or toJSON hooks run.
+ * Repeated references expand like JSON (and count against the budget); cycles fail.
+ * Limits bound output and traversal, including deeply nested/alias-heavy input.
+ */
+export declare function serializeToolArguments(value: unknown, maxBytes: number): string;
+/** Detach JSON data without encoding it. Unlike projection, invocation has no
+ * formatting budget: preserve shared references and traverse iteratively so a
+ * deep or alias-heavy object cannot expand exponentially during validation.
+ */
+export declare function cloneToolArguments(value: unknown): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.9.2",
+  "version": "3.9.4",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/common/enum.ts

@@ -7,6 +7,11 @@
 export enum GraphEvents {
   /* Custom Events */
 
+  /** Accepted graph model result, after fallback selection. Registry-only, not a provider callback. */
+  ON_MODEL_RESPONSE = 'on_model_response',
+  /** Registry-only: ToolNode has taken ownership of an accepted message's calls. */
+  ON_MODEL_TOOLS_CLAIMED = 'on_model_tools_claimed',
+
   /** [Custom] Agent update event in multi-agent graph/workflow */
   ON_AGENT_UPDATE = 'on_agent_update',
   /** [Custom] Delta event for run steps (message creation and tool calls) */

package/src/events.ts

@@ -8,7 +8,7 @@ import type { Logger } from 'winston';
 import type { MultiAgentGraph, StandardGraph } from '@/graphs';
 import type * as t from '@/types';
 import { dispatchesChatModelStream, SDK_STREAM_DISPATCH } from '@/stream';
-import { Constants } from '@/common';
+import { Constants, GraphEvents } from '@/common';
 
 export class HandlerRegistry {
   private handlers: Map<string, t.EventHandler> = new Map();
@@ -26,12 +26,23 @@ export function composeEventHandlers(
   ...handlerSets: Array<Record<string, t.EventHandler> | undefined>
 ): Record<string, t.EventHandler> {
   const composed: Partial<Record<string, t.EventHandler>> = {};
+  const acceptedObservers = new Map<string, t.EventHandler[]>();
 
   for (const handlerSet of handlerSets) {
     if (!handlerSet) {
       continue;
     }
     for (const [eventType, handler] of Object.entries(handlerSet)) {
+      if (
+        eventType === GraphEvents.ON_MODEL_RESPONSE ||
+        eventType === GraphEvents.ON_MODEL_TOOLS_CLAIMED
+      ) {
+        const observers = acceptedObservers.get(eventType) ?? [];
+        observers.push(handler);
+        acceptedObservers.set(eventType, observers);
+        composed[eventType] = handler;
+        continue;
+      }
       const previous = composed[eventType];
       if (previous === undefined) {
         composed[eventType] = handler;
@@ -61,6 +72,18 @@ export function composeEventHandlers(
     }
   }
 
+  for (const [eventType, observers] of acceptedObservers) {
+    composed[eventType] = {
+      handle: async (event, data, metadata, graph): Promise<void> => {
+        // Clone from the graph-owned snapshot, not from any preceding observer's
+        // possibly mutated argument tree. One bounded copy per observer.
+        for (const observer of observers) {
+          await observer.handle(event, structuredClone(data), metadata, graph);
+        }
+      },
+    };
+  }
+
   return composed as Record<string, t.EventHandler>;
 }
 

package/src/graphs/Graph.ts

@@ -38,6 +38,7 @@ import type {
 } from '@/graphs/graphFactory';
 import type { OverflowRecoveryPlan } from '@/llm/contextOverflowRecovery';
 import type { FallbackErrorContext } from '@/llm/invoke';
+import type { HandoffRouting } from './handoff';
 import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 import {
@@ -134,6 +135,10 @@ import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
+import {
+  InvalidModelToolCallError,
+  snapshotAcceptedModelResponse,
+} from './acceptedModelResponse';
 import {
   prepareProviderRequest,
   usesNativeOpenAIResponses,
@@ -185,6 +190,7 @@ import { getTruncationStopReason } from '@/llm/truncation';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
 import { createFakeStreamingLLM } from '@/llm/fake';
+import { handoffStateAnnotation } from './handoff';
 import { handleToolCalls } from '@/tools/handlers';
 import { isThinkingEnabled } from '@/llm/request';
 import { resolveMaxSeals } from '@/llm/preempt';
@@ -829,6 +835,8 @@ export abstract class Graph<
   callerSignal?: AbortSignal;
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
+  /** Explicit host policy. Never inferred from missing ToolNode claims. */
+  clientDelegatedToolNames?: ReadonlySet<string>;
   handlerRegistry: HandlerRegistry | undefined;
   /** Host registry retained only for forwarding tools from nested child graphs. */
   protected parentToolHandlerRegistry: HandlerRegistry | undefined;
@@ -1354,6 +1362,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   subagentUsageSink?: t.SubagentUsageSink;
   /** See {@link t.StandardGraphInput.subagentScope}. */
   subagentScope: boolean;
+  handoffRouting?: HandoffRouting;
   /** See {@link t.StandardGraphInput.subagentTasks}. */
   subagentTasks: t.SubagentTaskConfig | undefined;
   /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
@@ -1540,6 +1549,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       preemption,
       streamLimits,
       toolExecution,
+      clientDelegatedToolNames,
     }: t.StandardGraphInput,
     dependencies?: GraphFactoryDependencies
   ) {
@@ -1567,6 +1577,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.preemption = preemption;
     this.streamLimits = resolveStreamLimits(streamLimits);
     this.toolExecution = toolExecution;
+    if (clientDelegatedToolNames != null && clientDelegatedToolNames.length > 0) {
+      if (agents.length !== 1) {
+        throw new Error('Client tool delegation requires a single-agent graph');
+      }
+      if (clientDelegatedToolNames.some((name) => !name.trim())) {
+        throw new Error('Client delegated tool names must be nonempty');
+      }
+      this.clientDelegatedToolNames = new Set(clientDelegatedToolNames);
+    }
 
     if (agents.length === 0) {
       throw new Error('At least one agent configuration is required');
@@ -2830,6 +2849,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     currentToolMap?: t.ToolMap;
     agentContext?: AgentContext;
   }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState> {
+    const onToolCallsClaimed = async (
+      messageId: string,
+      config: RunnableConfig
+    ): Promise<void> => {
+      const handler = this.handlerRegistry?.getHandler(
+        GraphEvents.ON_MODEL_TOOLS_CLAIMED
+      );
+      if (handler == null) return;
+      await handler.handle(
+        GraphEvents.ON_MODEL_TOOLS_CLAIMED,
+        {
+          type: 'model_tools_claimed',
+          agentId: agentContext?.agentId ?? this.defaultAgentId,
+          messageId,
+        },
+        config.metadata,
+        this
+      );
+    };
     const toolDefinitions = agentContext?.toolDefinitions;
     const eventDrivenMode =
       toolDefinitions != null && toolDefinitions.length > 0;
@@ -2871,6 +2909,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }
 
       const node = new CustomToolNode<t.BaseGraphState>({
+        handoffRouting: this.handoffRouting,
         tools: allTools,
         toolMap: allToolMap,
         trace: traceToolNode,
@@ -2916,6 +2955,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           this.config = config;
           this.restoreRunStepResumeState(state);
         },
+        onToolCallsClaimed,
         createRunStepResumeState: (): t.RunStepResumeState =>
           this.createRunStepResumeState(),
         errorHandler: (data, metadata): Promise<boolean> =>
@@ -2960,6 +3000,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         : currentToolMap;
 
     const node = new CustomToolNode<t.BaseGraphState>({
+      handoffRouting: this.handoffRouting,
       tools: allTraditionalTools,
       toolMap: traditionalToolMap,
       trace: traceToolNode,
@@ -2997,6 +3038,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         this.config = config;
         this.restoreRunStepResumeState(state);
       },
+      onToolCallsClaimed,
       createRunStepResumeState: (): t.RunStepResumeState =>
         this.createRunStepResumeState(),
     });
@@ -4358,6 +4400,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * succeeding fallback would resolve a run the public contract says
          * must reject. Rethrow before any recovery path.
          */
+        if (primaryError instanceof InvalidModelToolCallError) {
+          throw primaryError;
+        }
         if (
           primaryError instanceof StreamLimitExceededError ||
           primaryError instanceof PreparedSubagentError
@@ -4698,6 +4743,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               })
           );
         } catch (fallbackError) {
+          if (fallbackError instanceof InvalidModelToolCallError) {
+            throw fallbackError;
+          }
           if (
             fallbackError instanceof StreamLimitExceededError ||
             fallbackError instanceof PreparedSubagentError
@@ -5002,6 +5050,36 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         this.preemptIncomplete = true;
       }
 
+      const responseHandler = this.handlerRegistry?.getHandler(
+        GraphEvents.ON_MODEL_RESPONSE
+      );
+      if (responseHandler != null && responseMessage?.getType() === 'ai') {
+        try {
+          // One graph-owned accepted result after all primary/fallback/overflow paths.
+          // No inference from provider chunks, run-step IDs, or attempt callback metadata.
+          invokeConfig.signal?.throwIfAborted();
+          const accepted = snapshotAcceptedModelResponse(
+            responseMessage as AIMessageChunk,
+            v4(),
+            agentId,
+            this.invokedToolIds,
+            this.clientDelegatedToolNames
+          );
+          // Awaited, registry-only: no trace replay, usage recording or side effects.
+          // Detached calls prevent a consumer from changing tools about to execute.
+          await responseHandler.handle(
+            GraphEvents.ON_MODEL_RESPONSE,
+            accepted,
+            metadata,
+            this
+          );
+          invokeConfig.signal?.throwIfAborted();
+        } catch (error) {
+          this.cleanupSignalListener();
+          throw error;
+        }
+      }
+
       this.cleanupSignalListener();
       return result;
     };
@@ -5434,6 +5512,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     ): Promise<Partial<t.AgentSubgraphState>> => {
       this.config = config;
       this.restoreRunStepResumeState(state.runStepState);
+      this.handoffRouting?.restore(state.handoffState);
       const result = await invoke();
       /** An ordinary run on a checkpointed thread inherits the last
        *  compaction's summary in state; it is not this run's output. */
@@ -5469,6 +5548,28 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       if (this.summarizeOnlyAgentId != null) {
         return END;
       }
+      const delegatedNames = this.clientDelegatedToolNames;
+      if (delegatedNames != null && delegatedNames.size > 0) {
+        const { messages } = state as t.BaseGraphState;
+        const last = messages[messages.length - 1] as AIMessageChunk | undefined;
+        const calls = last?.getType() === 'ai' ? last.tool_calls ?? [] : [];
+        if (calls.some((call) => delegatedNames.has(call.name))) {
+          if (
+            calls.some(
+              (call) =>
+                !delegatedNames.has(call.name) ||
+                (call.id != null && this.invokedToolIds?.has(call.id) === true)
+            ) ||
+            (last?.invalid_tool_calls?.length ?? 0) > 0 ||
+            getTruncationStopReason(last) != null
+          ) {
+            throw new InvalidModelToolCallError(
+              'Mixed client and graph-owned tool calls require separate model turns'
+            );
+          }
+          return END;
+        }
+      }
       const decision = toolsCondition(
         state as t.BaseGraphState,
         toolNode,
@@ -5512,6 +5613,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         default: () => undefined,
       }),
       runStepState: this.createRunStepStateAnnotation(),
+      handoffState: handoffStateAnnotation(),
     });
 
     const readChargeCredits = ():
@@ -5727,6 +5829,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         default: () => undefined,
       }),
       runStepState: this.createRunStepStateAnnotation(),
+      handoffState: handoffStateAnnotation(),
     });
     const compactingAgentNode = async (
       state: t.AgentSubgraphState,