@librechat/agents 3.8.5 → 3.8.7

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

@@ -11,6 +11,7 @@ export declare const BashProgrammaticToolCallingDefinition: {
     readonly description: string;
     readonly schema: ProgrammaticToolCallingJsonSchema;
 };
+export declare function prepareBashProgrammaticCode(code: string): string;
 export declare function normalizeBashToolResultsForReplay(toolResults: t.PTCToolResult[]): t.PTCToolResult[];
 /**
  * Normalizes a tool name to a valid bash function identifier.

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

@@ -11,7 +11,7 @@ export declare const CODE_ARTIFACT_PATH_GUIDANCE = "Anything a later call needs
 export declare const BASH_SHELL_GUIDANCE = "Bash: multi-line files use heredoc/printf; run Python via python3 -c/heredoc, not bare Python.";
 export declare const TMP_SCRATCH_OUTPUT_REMINDER = "Note: /tmp files are same-call scratch only and were not persisted; use /mnt/data for files needed later.";
 export declare const FAILED_EXECUTION_FILE_REMINDER = "Note: any files written during this failed call were not registered for later calls; fix the error and rerun before relying on them.";
-export declare function appendTmpScratchReminder(output: string, code: string): string;
+export declare function appendTmpScratchReminder(output: string, code: string, reminder?: string): string;
 export declare function appendFailedExecutionFileReminder(output: string, code: string): string;
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";

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

@@ -1,3 +1,6 @@
 import type * as t from '@/types';
 export declare function stripCodeSessionFileSummary(output: string): string;
 export declare function appendCodeSessionFileSummary(output: string, files: t.FileRefs | undefined): string;
+/** Attached-worker artifacts are delivered out of execution-private scratch,
+ * not retained in the selected project or a reusable `/mnt/data` session. */
+export declare function appendExecutionArtifactFileSummary(output: string, files: t.FileRefs | undefined): string;

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

@@ -66,7 +66,7 @@ export declare function fetchSessionFiles(baseUrl: string, sessionId: string, sc
  * @param proxy - Optional HTTP proxy URL
  * @returns The parsed API response
  */
-export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string, authHeaders?: t.CodeApiAuthHeaders, executionProfile?: t.CodeApiExecutionProfile): Promise<t.ProgrammaticExecutionResponse>;
+export declare function makeRequest(endpoint: string, body: Record<string, unknown>, proxy?: string, authHeaders?: t.CodeApiAuthHeaders, executionProfile?: t.CodeApiExecutionProfile, signal?: AbortSignal): Promise<t.ProgrammaticExecutionResponse>;
 /**
  * Unwraps tool responses that may be formatted as tuples or content blocks.
  * MCP tools return [content, artifacts], we need to extract the raw data.
@@ -94,7 +94,7 @@ export declare function executeTools(toolCalls: t.PTCToolCall[], toolMap: t.Tool
  * @param response - The completed API response
  * @returns Tuple of [formatted string, artifact]
  */
-export declare function formatCompletedResponse(response: t.ProgrammaticExecutionResponse, sourceCode?: string): [string, t.ProgrammaticExecutionArtifact];
+export declare function formatCompletedResponse(response: t.ProgrammaticExecutionResponse, sourceCode?: string, filePersistence?: 'session' | 'execution'): [string, t.ProgrammaticExecutionArtifact];
 /**
  * Mirrors the Code API's programmatic Python wrapper (`wrapUserCodeInAsync`).
  *

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

@@ -21,6 +21,8 @@ type RunToolBatchContext<T = unknown> = {
     batchScopeId?: string;
     /** Batch-local sink for post-substitution args. */
     resolvedArgsByCallId?: ResolvedArgsByCallId;
+    /** File identities actually injected into each direct code call. */
+    codeSessionBaselineByCallId?: Map<string, ReadonlyMap<string, string>>;
     /**
      * Frozen pre-batch view of the tool-output registry. When supplied,
      * `runTool` resolves `{{tool…turn…}}` placeholders against this
@@ -161,6 +163,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * even where `agentId` (the subagent-scope marker) is undefined.
      */
     private executingAgentId?;
+    private readonly executionContext?;
     private executingAgentName?;
     private rootAgentId?;
     private rootAgentName?;
@@ -225,7 +228,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, toolDefinitions, getDiscoveredToolNames, sessions, codeSessionKey, eventDrivenMode, eagerEventToolExecution, eagerEventToolExecutions, eagerEventToolUsageCount, eagerEventToolSuppressions, agentId, executingAgentId, executingAgentName, rootAgentId, rootAgentName, directToolNames, interruptingToolNames, codeSessionToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, getBreakerSignal, getRunScope, preparedSubagents, restoreRunStepResumeState, createRunStepResumeState, }: t.ToolNodeConstructorParams);
+    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);
     invoke(input: any, options?: Partial<RunnableConfig>): Promise<any>;
     private withToolScope;
     /**
@@ -411,6 +414,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      *  paths derive the runtime session hint identically. */
     private resolveRuntimeSessionHint;
     private storeCodeSessionFromResults;
+    private retainCodeSessionInputsFromRequests;
     /**
      * Post-processes standard runTool outputs: dispatches ON_RUN_STEP_COMPLETED
      * and stores code session context. Mirrors the completion handling in
@@ -531,7 +535,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * invocations cannot race on shared mutable state.
      */
     private executeViaEvent;
-    protected run(input: any, config: RunnableConfig, referenceReplay?: {
+    protected run(input: T, config: RunnableConfig, referenceReplay?: {
         state?: ToolOutputReferenceState;
     }): Promise<T>;
     private isSendInput;

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

@@ -1,7 +1,7 @@
 import { BaseMessage } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentTaskConfig, SubagentTaskRuntime, SubagentUsageSink, TokenCounter } from '@/types';
+import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentContextAdapter, SubagentContextResult, SubagentTaskConfig, SubagentTaskRuntime, SubagentUsageSink, TokenCounter } from '@/types';
 import type { SubagentResumeManifest, SettledSubagentToolOutput } from './SubagentReplay';
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -71,11 +71,11 @@ export type SubagentExecuteParams = {
     /** Host-restored child transcript for a fresh continuation run. @internal */
     initialMessages?: BaseMessage[];
 };
-export type SubagentExecuteResult = {
-    content: string;
-    messages: BaseMessage[];
+export type SubagentExecuteResult = SubagentContextResult & {
     /** Tagged internal failure; foreground callers retain the legacy content. */
     error?: string;
+    /** Completed child work whose host projection must be retried without re-execution. */
+    retryableDelivery?: true;
 };
 /**
  * Factory that constructs a child graph for subagent execution. Injected
@@ -160,6 +160,7 @@ export type SubagentExecutorOptions = {
     usageSink?: SubagentUsageSink;
     /** Host-owned process-local task namespace for detached execution. */
     taskConfig?: SubagentTaskConfig;
+    subagentContext?: SubagentContextAdapter;
 };
 export declare class SubagentExecutor {
     private readonly configs;
@@ -187,6 +188,7 @@ export declare class SubagentExecutor {
     private readonly createDetachedChildGraphFactory?;
     private readonly usageSink?;
     private readonly taskConfig?;
+    private readonly subagentContext?;
     private readonly executions;
     private replayCheckpointWorkflow?;
     private readonly resolveParentHandlerRegistry?;
@@ -266,6 +268,7 @@ export declare class SubagentExecutor {
     private persistChildCheckpointMarker;
     execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
     private executeOnce;
+    private completeHostContext;
     /**
      * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
      * parent's handler registry. Silent no-op when no parent registry is set.

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

@@ -12,6 +12,8 @@ export interface SettledToolBatchResult {
     output: BaseMessage | Command;
     additionalContexts: string[];
     resolvedArgs?: Record<string, unknown>;
+    /** Code-session identities injected into this completed direct call. */
+    codeSessionBaseline?: Array<[string, string]>;
     completionHandled?: boolean;
     referenceContent?: string;
     turn?: number;

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

@@ -278,6 +278,8 @@ export type StandardGraphInput = {
      * do not inherit it, keeping background nesting disabled for the MVP.
      */
     subagentTasks?: SubagentTaskConfig;
+    /** Host-owned context and result projection for each isolated child execution. */
+    subagentContext?: SubagentContextAdapter;
     /**
      * True when this graph IS a subagent child run (set by `SubagentExecutor`
      * when it constructs the child graph). Drives the hook-input `agentId`
@@ -499,6 +501,32 @@ export interface SubagentExecutionContext {
     readonly depth: number;
     readonly ancestry: readonly SubagentAncestryEntry[];
 }
+/** Trusted identity supplied before a child can access host-owned resources. */
+export interface SubagentContextInput {
+    executionContext: SubagentExecutionContext;
+    parentThreadId?: string;
+    memberAgentIds: readonly string[];
+    signal: AbortSignal;
+    resumed: boolean;
+}
+export interface PreparedSubagentContext {
+    /** Added to the initial child input; checkpoint recovery does not add them again. */
+    messages?: BaseMessage[];
+    /** Host configuration; SDK execution and checkpoint identities remain authoritative. */
+    configurable?: RunnableConfig['configurable'];
+    /** Each entry replaces that member's inherited code partition and initial sessions. */
+    agentSessions?: Readonly<Record<string, Pick<AgentInputs, 'codeSessionKey' | 'initialSessions'>>>;
+}
+export interface SubagentContextResult {
+    content: string;
+    messages: BaseMessage[];
+}
+export interface SubagentContextAdapter {
+    /** Reauthorizes reconstructed executions; durable work must be idempotent by child run ID. */
+    prepare(input: SubagentContextInput): Promise<PreparedSubagentContext>;
+    /** Projects durable references into the result returned to the parent. */
+    complete?(input: SubagentContextInput, result: SubagentContextResult): Promise<Pick<SubagentContextResult, 'content'>>;
+}
 /**
  * Wrapper event emitted when a subagent's child graph dispatches activity.
  * Lets hosts show subagent progress in a UI surface separate from the parent

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

@@ -272,6 +272,8 @@ export type RunConfig = {
      * Omit to preserve foreground-only subagent behavior.
      */
     subagentTasks?: SubagentTaskConfig;
+    /** Authorizes and supplies host-owned context to isolated child runs. */
+    subagentContext?: g.SubagentContextAdapter;
     /**
      * Pre-constructed hook registry for this run. Hooks fire at lifecycle
      * points in `processStream` (RunStart, UserPromptSubmit, Stop,

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

@@ -3,10 +3,10 @@ import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { MessageContentComplex, RunStepResumeState, ToolErrorData } from './stream';
 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 { HumanInTheLoopConfig } from './hitl';
-import type { LangfuseConfig } from './graph';
 import type { HookRegistry } from '@/hooks';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
@@ -63,6 +63,7 @@ export type EagerEventToolExecution = {
     toolName: string;
     args: Record<string, unknown>;
     request: ToolCallRequest;
+    codeSessionBaselineByName?: ReadonlyMap<string, string>;
     promise: Promise<EagerEventToolExecutionOutcome>;
     /**
      * True when the streaming eager path already emitted the user-visible
@@ -139,6 +140,8 @@ export type ToolNodeOptions = {
     /** ID of the agent that owns this tool node, surfaced to hooks as `executingAgentId`
      * so a batch can be attributed to a specific agent even where `agentId` is undefined. */
     executingAgentId?: string;
+    /** SDK-owned identity of the child execution, independent of reusable agent IDs. */
+    executionContext?: SubagentExecutionContext;
     /** Name of the agent that owns this tool node, used for active Langfuse attribution. */
     executingAgentName?: string;
     /** Root graph-agent identity retained alongside the currently executing tool owner. */
@@ -466,6 +469,8 @@ export type ExecuteResult = {
     stdout: string;
     stderr: string;
     files?: FileRefs;
+    /** Persisted input paths explicitly removed during this execution. */
+    deleted_files?: string[];
     artifact_delivery?: ArtifactDeliveryFailure;
     /**
      * Durable runtime session id echoed by a stateful Code API backend
@@ -529,6 +534,10 @@ export type ToolCallRequest = {
         session_id: string;
         files?: CodeEnvFile[];
     };
+    /** Request-time execution session used to detect host session refreshes. */
+    codeSessionBaselineId?: string;
+    /** Preserve request-provisioned code inputs after an eager identity mismatch. */
+    retainCodeSessionInputs?: true;
     /**
      * Stable runtime session hint for stateful sandbox sessions. Orthogonal to
      * `codeSessionContext` (which threads the transient exec-session for file
@@ -550,6 +559,8 @@ export type CallerCapabilityProjectionSnapshot = {
 };
 /** Batch request containing ALL tool calls for a graph step */
 export type ToolExecuteBatchRequest = {
+    /** SDK-owned child lineage. Unset for tools in the root graph. */
+    executionContext?: SubagentExecutionContext;
     /** All tool calls from the AIMessage */
     toolCalls: ToolCallRequest[];
     /** User ID for context */
@@ -1134,6 +1145,7 @@ export type ProgrammaticHookContext = {
     runId: string;
     threadId?: string;
     agentId?: string;
+    executionContext?: SubagentExecutionContext;
     executingAgentId?: string;
 };
 /** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
@@ -1225,6 +1237,8 @@ export type ProgrammaticExecutionResponse = {
     stdout?: string;
     stderr?: string;
     files?: FileRefs;
+    /** Persisted input paths explicitly removed during this execution. */
+    deleted_files?: string[];
     artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
@@ -1239,15 +1253,23 @@ export type ProgrammaticExecutionArtifact = {
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     files?: FileRefs;
+    /** Persisted input paths explicitly removed during this execution. */
+    deleted_files?: string[];
     artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';
 };
 /** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
-export type BashExecutionToolParams = CodeExecutionToolParams;
+export type BashExecutionToolParams = undefined | (Exclude<CodeExecutionToolParams, undefined> & {
+    /** Trusted attached-workspace identifier selected by the host. */
+    workspaceId?: string;
+});
 /** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
-export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams & {
+    /** Trusted attached-workspace identifier selected by the host. */
+    workspaceId?: string;
+};
 /**
  * Initialization parameters for the PTC tool
  */
@@ -1294,6 +1316,8 @@ export type CodeExecutionArtifact = {
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     files?: FileRefs;
+    /** Persisted input paths explicitly removed during this execution. */
+    deleted_files?: string[];
     artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.8.5",
+  "version": "3.8.7",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"
@@ -159,7 +159,7 @@
   "description": "",
   "repository": {
     "type": "git",
-    "url": "https://github.com/danny-avila/agents"
+    "url": "https://github.com/LibreChat-AI/agents"
   },
   "author": "Danny Avila",
   "license": "MIT",

package/src/common/constants.ts

@@ -1,3 +1,6 @@
+/** Host context preparation and trusted subagent execution identity are supported. */
+export const SUBAGENT_CONTEXT_VERSION = 1;
+
 /**
  * Anthropic direct API tool schema overhead multiplier.
  * Empirically calibrated against real MCP tool sets (29 tools).

package/src/graphs/Graph.ts

@@ -133,10 +133,18 @@ import {
   annotateMessagesForLLM,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
+import {
+  prepareProviderRequest,
+  usesNativeOpenAIResponses,
+} from '@/llm/prepareProviderRequest';
 import {
   resolveLangfuseRuntimeScope,
   withLangfuseRuntimeScope,
 } from '@/langfuseRuntimeScope';
+import {
+  ManualSummarizationSkippedError,
+  shouldTriggerSummarization,
+} from '@/summarization';
 import {
   getToolContentCharLength,
   serializeToolContentBounded,
@@ -150,6 +158,11 @@ import {
   PreparedSubagents,
   PreparedSubagentError,
 } from '@/tools/preparedSubagents';
+import {
+  createRemoveAllMessage,
+  messagesStateReducer,
+} from '@/messages/reducer';
+import { createToolHistoryPreparation } from '@/messages/toolHistoryProjection';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
@@ -157,29 +170,16 @@ import { SUBAGENT_REPLAY_CONTROLLER } from '@/tools/subagent/SubagentReplay';
 import { applyGraphRuntimeConfig } from '@/graphs/applyGraphRuntimeConfig';
 import { isFadingTier, isInformativeFadingTier } from '@/messages/fading';
 import { createContextPressureMeter } from '@/llm/contextPressureMeter';
-import { createToolHistoryPreparation } from '@/messages/toolHistoryProjection';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
-import {
-  prepareProviderRequest,
-  usesNativeOpenAIResponses,
-} from '@/llm/prepareProviderRequest';
 import { createCloudflareCodingToolBundle } from '@/tools/cloudflare';
 import { calculateMaxToolCallInputChars } from '@/utils/truncation';
 import { prepareToolsForPromptCache } from '@/llm/promptCacheTools';
 import { providerRequiresStrictAlternation } from '@/llm/providers';
 import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { initializeLangfuseTracing } from '@/instrumentation';
-import {
-  ManualSummarizationSkippedError,
-  shouldTriggerSummarization,
-} from '@/summarization';
 import { isRunStepResumeState } from '@/tools/runStepResume';
 import { resolveLocalToolsForBinding } from '@/tools/local';
 import { createSummarizeNode } from '@/summarization/node';
-import {
-  createRemoveAllMessage,
-  messagesStateReducer,
-} from '@/messages/reducer';
 import { getTruncationStopReason } from '@/llm/truncation';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { AgentContext } from '@/agents/AgentContext';
@@ -1356,7 +1356,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /** See {@link t.StandardGraphInput.subagentTasks}. */
   subagentTasks: t.SubagentTaskConfig | undefined;
   /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
-  private readonly subagentExecutionContext?: t.SubagentExecutionContext;
+  readonly subagentExecutionContext?: t.SubagentExecutionContext;
+  private readonly subagentContext?: t.SubagentContextAdapter;
   /** See {@link t.StandardGraphInput.preemption}. */
   preemption?: t.StreamPreemption;
   /**
@@ -1534,6 +1535,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       subagentTasks,
       subagentScope,
       subagentExecutionContext,
+      subagentContext,
       preemption,
       streamLimits,
       toolExecution,
@@ -1560,6 +1562,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.subagentTasks = subagentTasks;
     this.subagentScope = subagentScope === true;
     this.subagentExecutionContext = subagentExecutionContext;
+    this.subagentContext = subagentContext;
     this.preemption = preemption;
     this.streamLimits = resolveStreamLimits(streamLimits);
     this.toolExecution = toolExecution;
@@ -2881,6 +2884,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         // run_id); `executingAgentId` always identifies the owning agent.
         agentId: this.subagentScope ? agentContext?.agentId : undefined,
         executingAgentId: agentContext?.agentId,
+        executionContext: this.subagentExecutionContext,
         executingAgentName: agentContext?.name,
         rootAgentId: this.defaultAgentId,
         rootAgentName: this.agentContexts.get(this.defaultAgentId)?.name,
@@ -2965,6 +2969,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       // hooks can attribute the batch even at the top level.
       agentId: this.subagentScope ? agentContext?.agentId : undefined,
       executingAgentId: agentContext?.agentId,
+      executionContext: this.subagentExecutionContext,
       executingAgentName: agentContext?.name,
       rootAgentId: this.defaultAgentId,
       rootAgentName: this.agentContexts.get(this.defaultAgentId)?.name,
@@ -4627,7 +4632,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                       fallbackProvider,
                       fallbackClientOptions
                     );
-                    let projection: ReturnType<typeof measureProviderPayload> | undefined;
+                    let projection:
+                      | ReturnType<typeof measureProviderPayload>
+                      | undefined;
                     const request = prepareProviderRequest({
                       model: fallbackModel,
                       messages: cached,
@@ -4644,7 +4651,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                       },
                     });
                     if (projection == null) {
-                      throw new Error('Fallback preparation did not measure its payload');
+                      throw new Error(
+                        'Fallback preparation did not measure its payload'
+                      );
                     }
                     return { request, projection };
                   };
@@ -4664,8 +4673,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                   if (!projection.fits) {
                     const compacted = compactSyntheticProviderContext(
                       servingFallbackMessages,
-                      (candidate) =>
-                        prepareFallback(candidate).projection
+                      (candidate) => prepareFallback(candidate).projection
                     );
                     if (compacted !== servingFallbackMessages) {
                       preparedFallbackRequest = prepareFallback(compacted);
@@ -5025,6 +5033,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         runId,
         threadId: configurable?.thread_id as string | undefined,
         agentId: this.subagentScope ? agentId : undefined,
+        executionContext: this.subagentExecutionContext,
         executingAgentId: agentId,
         sealCount: this.preemptSealCount,
       },
@@ -5247,6 +5256,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           tokenCounter: agentContext.tokenCounter,
           usageSink: this.subagentUsageSink,
           taskConfig: this.subagentTasks,
+          subagentContext: this.subagentContext,
           streamLimits: this.streamLimits,
           humanInTheLoop: this.humanInTheLoop,
           checkpointer: this.compileOptions?.checkpointer,
@@ -5343,6 +5353,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               });
             }
             const result = await executor.execute(executeParams);
+            if (result.retryableDelivery === true) {
+              throw new Error(result.content);
+            }
             return result.content;
           },
           buildSubagentToolParams(executableConfigs, {
@@ -5527,6 +5540,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             },
             runId: this.runId,
             isMultiAgent: this.isMultiAgentGraph(),
+            getSubagentExecutionContext: () => this.subagentExecutionContext,
             hookRegistry: this.hookRegistry,
             getToolsForBinding: (
               provider: t.ProviderName,

package/src/hooks/types.ts

@@ -1,5 +1,6 @@
 // src/hooks/types.ts
 import type { BaseMessage } from '@langchain/core/messages';
+import type { SubagentExecutionContext } from '@/types/graph';
 import type { InjectedMessage } from '@/types/tools';
 
 /**
@@ -57,6 +58,8 @@ export type StopDecision = 'continue' | 'block';
  *   hook to a specific agent regardless of subagent scope.
  */
 export interface BaseHookInput {
+  /** SDK-owned child lineage, including distinct identities for concurrent self-spawns. */
+  executionContext?: SubagentExecutionContext;
   runId: string;
   threadId?: string;
   agentId?: string;

package/src/run.ts

@@ -37,11 +37,6 @@ import {
   DEFAULT_MAX_STOP_CONTINUATIONS,
   DEFAULT_RECURSION_LIMIT,
 } from '@/common';
-import {
-  requireValidSubagentResumeManifest,
-  SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
-  SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
-} from '@/tools/subagent/SubagentReplay';
 import {
   ACTIVITY_PHASE_LABEL_PROMPT,
   ACTIVITY_LABEL_PROMPT,
@@ -57,12 +52,23 @@ import {
   isLangfuseCallbackHandler,
   withLangfuseAttributes,
 } from '@/langfuse';
+import {
+  requireValidSubagentResumeManifest,
+  SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
+  SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
+} from '@/tools/subagent/SubagentReplay';
 import {
   REASONING_LABEL_PROMPT,
   buildReasoningLabelTraceSeed,
   buildReasoningLabelPrompt,
   normalizeReasoningLabel,
 } from '@/prompts/reasoningLabel';
+import {
+  TOOL_BATCH_REPLAY_KEY,
+  restoreToolReplayConfig,
+  stripToolBatchReplayState,
+  getPublicToolInterruptPayload,
+} from '@/tools/toolBatchReplay';
 import {
   hasToolOutputTracingConfig,
   resolveLangfuseConfig,
@@ -72,12 +78,6 @@ import {
   cloneToolApprovalInterruptPayload,
   TOOL_APPROVAL_REVIEW_CONFIG_KEY,
 } from '@/hitl/approvalReview';
-import {
-  TOOL_BATCH_REPLAY_KEY,
-  restoreToolReplayConfig,
-  stripToolBatchReplayState,
-  getPublicToolInterruptPayload,
-} from '@/tools/toolBatchReplay';
 import {
   resolveLangfuseDestinationKey,
   resolveLangfuseTraceAnchorParent,
@@ -474,6 +474,7 @@ export class Run<_T extends t.BaseGraphState> {
   private maxStopContinuations: number;
   private streamLimits?: t.StreamLimits;
   private subagentTasks?: t.SubagentTaskConfig;
+  private subagentContext?: t.SubagentContextAdapter;
   private indexTokenCountMap?: Record<string, number>;
   calibrationRatio: number = 1;
   fadingTier?: t.FadingTier;
@@ -556,6 +557,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.toolExecution = config.toolExecution;
     this.subagentUsageSink = config.subagentUsageSink;
     this.subagentTasks = config.subagentTasks;
+    this.subagentContext = config.subagentContext;
     this.preemption = config.preemption;
     this.maxStopContinuations = resolveMaxStopContinuations(
       config.maxStopContinuations
@@ -654,6 +656,7 @@ export class Run<_T extends t.BaseGraphState> {
         fadingTiers: this.fadingTiers,
         subagentUsageSink: this.subagentUsageSink,
         subagentTasks: this.subagentTasks,
+        subagentContext: this.subagentContext,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
         toolExecution: this.toolExecution,
@@ -696,6 +699,7 @@ export class Run<_T extends t.BaseGraphState> {
         fadingTiers: this.fadingTiers,
         subagentUsageSink: this.subagentUsageSink,
         subagentTasks: this.subagentTasks,
+        subagentContext: this.subagentContext,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
         toolExecution: this.toolExecution,
@@ -1283,7 +1287,11 @@ export class Run<_T extends t.BaseGraphState> {
       );
       const publicPayload = stripRunStepResumeState(this._interrupt?.payload);
       if (config.configurable != null) {
-        restoreToolReplayConfig(config.configurable, this._interrupt?.interruptId, publicPayload);
+        restoreToolReplayConfig(
+          config.configurable,
+          this._interrupt?.interruptId,
+          publicPayload
+        );
       }
       if (graph.getStopContinuationExecutionId() === '') {
         graph.startStopContinuationExecution(nanoid());
@@ -2015,8 +2023,11 @@ export class Run<_T extends t.BaseGraphState> {
     await this.restoreInterruptFromCheckpoint(callerConfig, resumeUpdate);
     const interrupt = this._interrupt;
     const replayPayload = stripRunStepResumeState(interrupt?.payload);
-    const resumeManifest = requireValidSubagentResumeManifest(replayPayload) ??
-      requireValidSubagentResumeManifest(stripToolBatchReplayState(replayPayload));
+    const resumeManifest =
+      requireValidSubagentResumeManifest(replayPayload) ??
+      requireValidSubagentResumeManifest(
+        stripToolBatchReplayState(replayPayload)
+      );
     const resumeConfigurable = { ...callerConfig.configurable };
     delete resumeConfigurable[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
     delete resumeConfigurable[TOOL_BATCH_REPLAY_KEY];
@@ -2027,7 +2038,11 @@ export class Run<_T extends t.BaseGraphState> {
       resumeConfigurable[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY] = resumeManifest;
     }
     const publicPayload = stripRunStepResumeState(interrupt?.payload);
-    restoreToolReplayConfig(resumeConfigurable, interrupt?.interruptId, publicPayload);
+    restoreToolReplayConfig(
+      resumeConfigurable,
+      interrupt?.interruptId,
+      publicPayload
+    );
     const manifestConfig = {
       ...callerConfig,
       configurable: resumeConfigurable,