@librechat/agents 3.6.3 → 3.6.4

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

@@ -0,0 +1,45 @@
+import type { SubagentTaskClaim, SubagentTaskControlCommand, SubagentTaskControlResult, SubagentTaskSnapshot, SubagentTaskStartRequest, SubagentTaskStartResult, SubagentTaskStore } from '@/types';
+export interface InMemorySubagentTaskStoreOptions {
+    completedTtlMs?: number;
+    maxControlMessageChars?: number;
+    maxControlsPerTask?: number;
+    maxErrorChars?: number;
+    maxResultChars?: number;
+    maxRunningPerScope?: number;
+    maxRunningTotal?: number;
+    maxTasksPerScope?: number;
+    maxTasksTotal?: number;
+    taskTimeoutMs?: number;
+}
+/**
+ * Bounded process-local task ownership for detached subagents. Terminal tasks
+ * keep only a bounded claimable result: the child graph, checkpoint, and full
+ * transcript are released. Hosts that need later child-chat continuation may
+ * replace this store and persist the canonical messages returned by `run`.
+ * This default deliberately makes no restart or cross-replica durability
+ * claim.
+ */
+export declare class InMemorySubagentTaskStore implements SubagentTaskStore {
+    private readonly buckets;
+    private readonly options;
+    private runningTasks;
+    private totalTasks;
+    constructor(options?: InMemorySubagentTaskStoreOptions);
+    start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
+    get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
+    list(scopeId: string): SubagentTaskSnapshot[];
+    claim(scopeId: string, taskId: string): SubagentTaskClaim;
+    control(scopeId: string, taskId: string, command: SubagentTaskControlCommand): SubagentTaskControlResult;
+    private getBucket;
+    private find;
+    private makeRoom;
+    private makeGlobalRoom;
+    private sweepBucket;
+    private removeTask;
+    private dropEmptyBucket;
+    private scheduleExpiry;
+    private clearTaskExpiry;
+    private clearTaskTimeout;
+    private finishWithError;
+    private createRuntime;
+}

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

@@ -1,12 +1,12 @@
 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, SubagentUsageSink, TokenCounter } from '@/types';
+import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentTaskConfig, SubagentTaskRuntime, SubagentUsageSink, TokenCounter } from '@/types';
 import type { SubagentResumeManifest, SettledSubagentToolOutput } from './SubagentReplay';
-import type { HookRegistry } from '@/hooks';
 import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
-import type { HandlerRegistry } from '@/events';
+import { HookRegistry } from '@/hooks';
+import { HandlerRegistry } from '@/events';
 export { buildChildInputs, isGraphSubagentConfig, normalizeSubagentConfigs, normalizeSubagentConfigEntries, resolveSubagentConfigs, resolveSubagentConfigEntries, } from './childGraphConfig';
 export declare const DEFAULT_SUBAGENT_DESCRIPTION = "No task description provided";
 export type SubagentExecuteParams = {
@@ -62,10 +62,16 @@ export type SubagentExecuteParams = {
      * rather than sharing parent's host context.
      */
     parentConfigurable?: Record<string, unknown>;
+    /** Dedicated hook session used by a detached task. @internal */
+    hookSessionId?: string;
+    /** Process-local task controls consumed by the child graph. @internal */
+    taskRuntime?: SubagentTaskRuntime;
 };
 export type SubagentExecuteResult = {
     content: string;
     messages: BaseMessage[];
+    /** Tagged internal failure; foreground callers retain the legacy content. */
+    error?: string;
 };
 /**
  * Factory that constructs a child graph for subagent execution. Injected
@@ -121,6 +127,11 @@ export type SubagentExecutorOptions = {
     /** Preferred polymorphic child constructor. The legacy standard-only
      * factory remains required for source compatibility. */
     createChildGraphByKind?: GraphFactory;
+    /**
+     * Captures a child-graph factory and its run-scoped host dependencies
+     * synchronously, before a detached task can outlive parent cleanup.
+     */
+    createDetachedChildGraphFactory?: (parentHandlerRegistry: HandlerRegistry) => GraphFactory;
     /**
      * Parent's event handler registry. When provided, child-graph events are
      * forwarded through this registry so hosts can:
@@ -143,6 +154,8 @@ export type SubagentExecutorOptions = {
      * nested subagents report through the same sink.
      */
     usageSink?: SubagentUsageSink;
+    /** Host-owned process-local task namespace for detached execution. */
+    taskConfig?: SubagentTaskConfig;
 };
 export declare class SubagentExecutor {
     private readonly configs;
@@ -167,7 +180,9 @@ export declare class SubagentExecutor {
     private readonly maxDepth;
     private readonly createChildGraph;
     private readonly createChildGraphByKind?;
+    private readonly createDetachedChildGraphFactory?;
     private readonly usageSink?;
+    private readonly taskConfig?;
     private readonly executions;
     private replayCheckpointWorkflow?;
     private readonly resolveParentHandlerRegistry?;
@@ -181,6 +196,14 @@ export declare class SubagentExecutor {
     private composeChildSignal;
     /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
     private getParentHandlerRegistry;
+    /**
+     * Starts one independently-owned executor behind the configured task store.
+     * The parent ToolNode receives the handle synchronously; the detached clone
+     * is not registered on the parent graph, so end-of-turn cleanup cannot
+     * invalidate or clear a child that intentionally outlives that turn.
+     */
+    executeInBackground(params: SubagentExecuteParams): string;
+    private executeDetached;
     private bindExecutionDefinition;
     /** Resolve one lazy descriptor per stable child execution. Concurrent
      * duplicate dispatches share the same in-flight resolution; HITL re-entry

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

@@ -1,2 +1,4 @@
 export { DEFAULT_SUBAGENT_DESCRIPTION, SubagentExecutor, filterSubagentResult, filterGraphSubagentResult, isGraphSubagentConfig, normalizeSubagentConfigs, normalizeSubagentConfigEntries, resolveSubagentConfigs, resolveSubagentConfigEntries, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
 export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';
+export { InMemorySubagentTaskStore } from './InMemorySubagentTaskStore';
+export type { InMemorySubagentTaskStoreOptions } from './InMemorySubagentTaskStore';

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

@@ -9,6 +9,7 @@ import type { RunStep, RunStepDeltaEvent, RunStepResumeState, RunStepClosedEvent
 import type { ToolMap, ToolSessionMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
+import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
 /** Interface for bound model with stream and invoke methods */
@@ -239,6 +240,12 @@ export type StandardGraphInput = {
      * they already flow through the registry's `CHAT_MODEL_END` handler.
      */
     subagentUsageSink?: SubagentUsageSink;
+    /**
+     * Optional host-owned process-local task namespace for detached subagents.
+     * Presence enables `run_in_background` on the subagent tool. Child graphs
+     * do not inherit it, keeping background nesting disabled for the MVP.
+     */
+    subagentTasks?: SubagentTaskConfig;
     /**
      * True when this graph IS a subagent child run (set by `SubagentExecutor`
      * when it constructs the child graph). Drives the hook-input `agentId`
@@ -250,10 +257,10 @@ export type StandardGraphInput = {
      */
     subagentScope?: boolean;
     /**
-     * Cooperative preemption, forwarded from `RunConfig.preemption`. Only ever
-     * set on the top-level graph: a steer targets the conversation, so subagent
-     * children must run to completion and `buildChildInputs` does not propagate
-     * this field.
+     * Cooperative preemption, forwarded from `RunConfig.preemption`. Ordinary
+     * child graphs do not inherit it. Detached subagent tasks may receive their
+     * own internal parent-control source so an interrupt can reuse the same
+     * provider-safe sealing path without targeting the top-level conversation.
      */
     preemption?: StreamPreemption;
     /**

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

@@ -5,6 +5,7 @@ export * from './messages';
 export * from './run';
 export * from './skill';
 export * from './stream';
+export * from './subagentTasks';
 export * from './tools';
 export * from './summarize';
 export * from './activityLabel';

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

@@ -4,6 +4,7 @@ import type { BaseMessage } from '@langchain/core/messages';
 import type { StructuredTool } from '@langchain/core/tools';
 import type * as z from 'zod';
 import type { ToolSessionMap, ToolExecutionConfig, ToolOutputReferencesConfig, EagerEventToolExecutionConfig } from '@/types/tools';
+import type { SubagentTaskConfig } from '@/types/subagentTasks';
 import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 import type * as s from '@/types/stream';
@@ -215,6 +216,11 @@ export type RunConfig = {
      * the registered `CHAT_MODEL_END` handler as usual.
      */
     subagentUsageSink?: g.SubagentUsageSink;
+    /**
+     * Trusted process-local task namespace for detached subagent execution.
+     * Omit to preserve foreground-only subagent behavior.
+     */
+    subagentTasks?: SubagentTaskConfig;
     /**
      * Pre-constructed hook registry for this run. Hooks fire at lifecycle
      * points in `processStream` (RunStart, UserPromptSubmit, Stop,

package/dist/types/types/subagentTasks.d.ts

@@ -0,0 +1,140 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type { SubagentUpdateEvent } from './graph';
+import type { InjectedMessage } from './tools';
+/** Terminal and in-flight states for a detached subagent task. */
+export type SubagentTaskStatus = 'running' | 'completed' | 'error' | 'cancelled';
+/** Where a pending parent message may enter the child run. */
+export type SubagentTaskBoundary = 'preempt' | 'tool' | 'turn';
+/** Parent-to-child control operations accepted while a task is running. */
+export type SubagentTaskControlCommand = {
+    action: 'steer' | 'queue' | 'interrupt';
+    message: string;
+} | {
+    action: 'cancel';
+} | {
+    action: 'cancel_message';
+    controlId: string;
+};
+/** Small, payload-free progress view safe to retain between parent turns. */
+export interface SubagentTaskProgress {
+    phase: SubagentUpdateEvent['phase'];
+    at: number;
+    eventCount: number;
+    label?: string;
+}
+/** Read-only task metadata. Results are exposed only through `claim`. */
+export interface SubagentTaskSnapshot {
+    /** Handle for this child-conversation execution within its trusted scope. */
+    taskId: string;
+    subagentType: string;
+    status: SubagentTaskStatus;
+    createdAt: number;
+    updatedAt: number;
+    resultAvailable: boolean;
+    resultClaimed: boolean;
+    pendingControls: number;
+    progress?: SubagentTaskProgress;
+    error?: string;
+}
+export type SubagentTaskClaim = {
+    status: 'running';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'completed';
+    task: SubagentTaskSnapshot;
+    result: string;
+} | {
+    status: 'error';
+    task: SubagentTaskSnapshot;
+    error: string;
+} | {
+    status: 'cancelled';
+    task: SubagentTaskSnapshot;
+    error: string;
+} | {
+    status: 'claimed';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'not_found';
+};
+export type SubagentTaskControlResult = {
+    status: 'accepted';
+    task: SubagentTaskSnapshot;
+    controlId?: string;
+} | {
+    status: 'cancelled';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'not_running';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'not_found';
+} | {
+    status: 'control_not_found';
+    task: SubagentTaskSnapshot;
+} | {
+    status: 'invalid';
+    message: string;
+};
+/**
+ * Child-side view supplied to one detached execution. It intentionally owns
+ * only cancellation, bounded message drains, and payload-free progress — no
+ * request/response object or host transport can leak into retained task state.
+ */
+export interface SubagentTaskRuntime {
+    readonly taskId: string;
+    readonly signal: AbortSignal;
+    shouldPreempt(): boolean;
+    drain(boundary: SubagentTaskBoundary): InjectedMessage[];
+    closeTurn(): {
+        closed: boolean;
+        messages: InjectedMessage[];
+    };
+    reportProgress(event: SubagentUpdateEvent): void;
+}
+export interface SubagentTaskStartRequest {
+    scopeId: string;
+    idempotencyKey: string;
+    /** Stable hash of model-writable inputs used to reject conflicting replays. */
+    requestFingerprint?: string;
+    subagentType: string;
+    /**
+     * Starts one ephemeral execution lease. The canonical child transcript is
+     * returned so a host-owned store may persist it for a later fresh run;
+     * retaining a graph/checkpoint after terminal completion is unnecessary.
+     */
+    run(runtime: SubagentTaskRuntime): Promise<{
+        content: string;
+        messages?: BaseMessage[];
+    }>;
+}
+export type SubagentTaskStartResult = {
+    accepted: true;
+    isNew: boolean;
+    task: SubagentTaskSnapshot;
+} | {
+    accepted: false;
+    reason: 'capacity';
+} | {
+    accepted: false;
+    reason: 'conflict';
+    task: SubagentTaskSnapshot;
+};
+/**
+ * Host-replaceable store contract used by the SDK's subagent tool. The store
+ * should normally outlive individual `Run` instances. Durable hosts may
+ * persist the transcript returned by `run` under the task/conversation
+ * lineage and start a fresh execution for a later turn.
+ */
+export interface SubagentTaskStore {
+    start(request: SubagentTaskStartRequest): SubagentTaskStartResult;
+    get(scopeId: string, taskId: string): SubagentTaskSnapshot | undefined;
+    list(scopeId: string): SubagentTaskSnapshot[];
+    claim(scopeId: string, taskId: string): SubagentTaskClaim;
+    control(scopeId: string, taskId: string, command: SubagentTaskControlCommand): SubagentTaskControlResult;
+}
+/** Trusted, host-selected task namespace. It is never model-writable. */
+export interface SubagentTaskConfig {
+    store: SubagentTaskStore;
+    scopeId: string;
+}

package/package.json

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

package/src/graphs/Graph.ts

@@ -1312,6 +1312,8 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   subagentUsageSink?: t.SubagentUsageSink;
   /** See {@link t.StandardGraphInput.subagentScope}. */
   subagentScope: boolean;
+  /** See {@link t.StandardGraphInput.subagentTasks}. */
+  subagentTasks: t.SubagentTaskConfig | undefined;
   /** See {@link t.StandardGraphInput.subagentExecutionContext}. */
   private readonly subagentExecutionContext?: t.SubagentExecutionContext;
   /** See {@link t.StandardGraphInput.preemption}. */
@@ -1445,6 +1447,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       indexTokenCountMap,
       calibrationRatio,
       subagentUsageSink,
+      subagentTasks,
       subagentScope,
       subagentExecutionContext,
       preemption,
@@ -1469,6 +1472,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     this.signal = signal;
     this.langfuse = langfuse;
     this.subagentUsageSink = subagentUsageSink;
+    this.subagentTasks = subagentTasks;
     this.subagentScope = subagentScope === true;
     this.subagentExecutionContext = subagentExecutionContext;
     this.preemption = preemption;
@@ -1695,8 +1699,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * budget is taken by {@link claimPreemptSeal} once the accumulated chunk is
    * known to be safe, so a chunk that cannot seal never spends budget.
    *
-   * Subagent scopes never seal: a steer targets the top-level conversation,
-   * and a child run must finish so its parent sees a complete result.
+   * Ordinary subagent scopes never receive `preemption`. A detached child may
+   * receive a dedicated parent-control preemption source, in which case the
+   * same provider-safe seal path is intentionally reused inside that child.
    */
   /** Internal seal preconditions only — no host callback, no side effects. */
   private canClaimPreemptSeal(): boolean {
@@ -1710,7 +1715,6 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     const runId =
       (this.config?.configurable?.run_id as string | undefined) ?? this.runId;
     return (
-      !this.subagentScope &&
       this.preemption != null &&
       !this.preemptSealInFlight &&
       this.preemptSealBudgetUsed < resolveMaxSeals(this.preemption.maxSeals) &&
@@ -4769,19 +4773,12 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         }
         const getParentHandlerRegistry = (): HandlerRegistry | undefined =>
           this.handlerRegistry ?? this.parentToolHandlerRegistry;
-        const createConfiguredChildGraph: GraphFactory = (request) => {
-          const childGraph = this.graphFactory(request);
-          if (this.subagentModelOverride != null) {
-            childGraph.overrideModel = this.subagentModelOverride;
-            childGraph.setSubagentModelOverride(this.subagentModelOverride);
-          }
-          const childHandlerRegistry = createChildHandlerRegistry(
-            getParentHandlerRegistry()
-          );
-          // Pure execution-ordering hint (unlike `humanInTheLoop`). It only
-          // reorders tools already in the child's direct group; it does not
-          // force a schema-only event tool onto the direct execution path.
-          applyGraphRuntimeConfig(childGraph, {
+        const snapshotChildGraphFactory = (
+          parentHandlerRegistry: HandlerRegistry | undefined
+        ): GraphFactory => {
+          const graphFactory = this.graphFactory;
+          const subagentModelOverride = this.subagentModelOverride;
+          const runtimeConfig = {
             hookRegistry: this.hookRegistry,
             humanInTheLoop: this.humanInTheLoop,
             toolOutputReferences: this.toolOutputReferences,
@@ -4789,18 +4786,33 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             codeSessionToolNames: this.codeSessionToolNames,
             interruptingToolNames: this.interruptingToolNames,
             toolExecution: this.toolExecution,
-          });
-          if (this.humanInTheLoop?.enabled === true) {
-            childGraph.compileOptions = {
-              checkpointer: this.compileOptions?.checkpointer,
-            };
-          }
-          childGraph.parentToolHandlerRegistry = childHandlerRegistry;
-          childGraph.eventToolExecutionAvailable =
-            childHandlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
-            null;
-          return childGraph;
+          };
+          const checkpointer = this.compileOptions?.checkpointer;
+          return (request): StandardGraph => {
+            const childGraph = graphFactory(request);
+            if (subagentModelOverride != null) {
+              childGraph.overrideModel = subagentModelOverride;
+              childGraph.setSubagentModelOverride(subagentModelOverride);
+            }
+            const childHandlerRegistry = createChildHandlerRegistry(
+              parentHandlerRegistry
+            );
+            // Pure execution-ordering hint (unlike `humanInTheLoop`). It only
+            // reorders tools already in the child's direct group; it does not
+            // force a schema-only event tool onto the direct execution path.
+            applyGraphRuntimeConfig(childGraph, runtimeConfig);
+            if (runtimeConfig.humanInTheLoop?.enabled === true) {
+              childGraph.compileOptions = { checkpointer };
+            }
+            childGraph.parentToolHandlerRegistry = childHandlerRegistry;
+            childGraph.eventToolExecutionAvailable =
+              childHandlerRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) !=
+              null;
+            return childGraph;
+          };
         };
+        const createConfiguredChildGraph: GraphFactory = (request) =>
+          snapshotChildGraphFactory(getParentHandlerRegistry())(request);
         const executor = new SubagentExecutor({
           configs: new Map(
             executableConfigs.map((config) => [config.type, config])
@@ -4820,6 +4832,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           langfuse: this.langfuse,
           tokenCounter: agentContext.tokenCounter,
           usageSink: this.subagentUsageSink,
+          taskConfig: this.subagentTasks,
           streamLimits: this.streamLimits,
           humanInTheLoop: this.humanInTheLoop,
           checkpointer: this.compileOptions?.checkpointer,
@@ -4830,6 +4843,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               input,
             }),
           createChildGraphByKind: createConfiguredChildGraph,
+          createDetachedChildGraphFactory: (
+            parentHandlerRegistry
+          ): GraphFactory =>
+            snapshotChildGraphFactory(parentHandlerRegistry),
         });
         this.registerSubagentExecutor(executor);
 
@@ -4837,6 +4854,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const input = rawInput as {
             description?: string;
             subagent_type?: string;
+            run_in_background?: boolean;
           };
           const description =
             typeof input.description === 'string' &&
@@ -4869,7 +4887,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const batchScope = config.configurable?.[
             RUN_BREAKER_SCOPE_CONFIG_KEY
           ] as RunBreakerScope | undefined;
-          const result = await executor.execute({
+          const executeParams = {
             description,
             subagentType,
             threadId,
@@ -4885,9 +4903,15 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             parentConfigurable: config.configurable as
               | Record<string, unknown>
               | undefined,
-          });
+          };
+          if (input.run_in_background === true) {
+            return executor.executeInBackground(executeParams);
+          }
+          const result = await executor.execute(executeParams);
           return result.content;
-        }, buildSubagentToolParams(executableConfigs));
+        }, buildSubagentToolParams(executableConfigs, {
+          background: this.subagentTasks != null,
+        }));
         const replayableSubagentTool = subagentTool as typeof subagentTool &
           ReplayableSubagentTool;
         replayableSubagentTool[SUBAGENT_REPLAY_CONTROLLER] = {

package/src/hooks/HookRegistry.ts

@@ -6,6 +6,7 @@ import type {
   ToolApprovalReplaySnapshot,
   AggregatedHookResult,
 } from './types';
+import { HOOK_EVENTS } from './types';
 
 function serializeApprovalKey(key: ToolApprovalReplayKey): string {
   return JSON.stringify([key.executionScope, key.agentId, key.toolUseId]);
@@ -227,6 +228,23 @@ export class HookRegistry {
     }
   }
 
+  /**
+   * Takes an isolated policy snapshot for work that may outlive the source
+   * run. Global and source-session matchers become global to the returned
+   * task-local registry, so parent cleanup and one-shot hook consumption
+   * cannot mutate the detached child (or vice versa). Runtime halt signals
+   * and pending approvals are intentionally not copied.
+   */
+  forkSession(sourceSessionId: string): HookRegistry {
+    const fork = new HookRegistry();
+    for (const event of HOOK_EVENTS) {
+      for (const matcher of this.getMatchers(event, sourceSessionId)) {
+        fork.register(event, matcher);
+      }
+    }
+    return fork;
+  }
+
   getPendingToolApproval(
     sessionId: string,
     key: ToolApprovalReplayKey

package/src/run.ts

@@ -296,6 +296,7 @@ export class Run<_T extends t.BaseGraphState> {
   private subagentUsageSink?: t.SubagentUsageSink;
   private preemption?: t.StreamPreemption;
   private streamLimits?: t.StreamLimits;
+  private subagentTasks?: t.SubagentTaskConfig;
   private indexTokenCountMap?: Record<string, number>;
   calibrationRatio: number = 1;
   graphRunnable?: t.CompiledStateWorkflow;
@@ -363,6 +364,7 @@ export class Run<_T extends t.BaseGraphState> {
     this.interruptingToolNames = config.interruptingToolNames;
     this.toolExecution = config.toolExecution;
     this.subagentUsageSink = config.subagentUsageSink;
+    this.subagentTasks = config.subagentTasks;
     this.preemption = config.preemption;
     this.streamLimits = config.streamLimits;
 
@@ -455,6 +457,7 @@ export class Run<_T extends t.BaseGraphState> {
         indexTokenCountMap: this.indexTokenCountMap,
         calibrationRatio: this.calibrationRatio,
         subagentUsageSink: this.subagentUsageSink,
+        subagentTasks: this.subagentTasks,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
       },
@@ -493,6 +496,7 @@ export class Run<_T extends t.BaseGraphState> {
         indexTokenCountMap: this.indexTokenCountMap,
         calibrationRatio: this.calibrationRatio,
         subagentUsageSink: this.subagentUsageSink,
+        subagentTasks: this.subagentTasks,
         preemption: this.preemption,
         streamLimits: this.streamLimits,
       },

package/src/tools/SubagentTool.ts

@@ -27,6 +27,9 @@ const DESCRIPTION_PROP_DESCRIPTION =
 const SUBAGENT_TYPE_PROP_DESCRIPTION =
   'Which subagent type to delegate to. Must be one of the available types.';
 
+const RUN_IN_BACKGROUND_PROP_DESCRIPTION =
+  'Set true to start the subagent as a detached process-local task and return a background_task_id immediately. Poll the host background-task tool to collect its result. The task can outlive this turn but does not survive a process restart.';
+
 export const SubagentToolSchema = {
   type: 'object',
   properties: {
@@ -54,7 +57,10 @@ export const SubagentToolDefinition: LCTool = {
  * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
  * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
  */
-export function buildSubagentToolParams(configs: SubagentConfig[]): {
+export function buildSubagentToolParams(
+  configs: SubagentConfig[],
+  options: { background?: boolean } = {}
+): {
   name: string;
   schema: JsonSchemaType;
   description: string;
@@ -79,10 +85,22 @@ export function buildSubagentToolParams(configs: SubagentConfig[]): {
           enum: types,
           description: `${SUBAGENT_TYPE_PROP_DESCRIPTION} Available: ${types.join(', ')}.`,
         },
+        ...(options.background === true
+          ? {
+            run_in_background: {
+              type: 'boolean',
+              description: RUN_IN_BACKGROUND_PROP_DESCRIPTION,
+            },
+          }
+          : {}),
       },
       required: ['description', 'subagent_type'],
     },
-    description: `${SubagentToolDescription}\n\nAvailable types:\n${typeDescriptions}`,
+    description: `${SubagentToolDescription}${
+      options.background === true
+        ? '\n\nBACKGROUND EXECUTION:\n- Set run_in_background to true when you do not need the result immediately. The call returns a background_task_id; use the host background-task tools to poll, steer, queue, interrupt, or cancel it.'
+        : ''
+    }\n\nAvailable types:\n${typeDescriptions}`,
   };
 }