@librechat/agents 3.4.1 → 3.4.2

package/src/tools/subagent/SubagentExecutor.ts

@@ -1,4 +1,5 @@
 import { nanoid } from 'nanoid';
+import { createHash } from 'crypto';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { AsyncLocalStorageProviderSingleton } from '@langchain/core/singletons';
 import {
@@ -34,6 +35,8 @@ import type {
   AgentInputs,
   BaseGraphState,
   CompiledStateWorkflow,
+  EventHandler,
+  MultiAgentGraphState,
   HumanInTheLoopConfig,
   InjectedMessage,
   MessageDeltaEvent,
@@ -42,9 +45,14 @@ import type {
   RunStep,
   RunStepDeltaEvent,
   StandardGraphInput,
+  ExecutableSubagentConfigEntry,
   ResolvedSubagentConfig,
+  ResolvedSubagentConfigEntry,
+  SubagentExecutionContext,
+  SubagentResolveConfigurable,
+  SubagentResolveRequestContext,
+  SubagentResolveUserContext,
   StepCompleted,
-  SubagentConfig,
   SubagentUpdateEvent,
   SubagentUpdatePhase,
   SubagentUsageSink,
@@ -55,16 +63,34 @@ import type {
   ToolApprovalDecision,
   ToolApprovalDecisionMap,
 } from '@/types';
+import type {
+  PreparedSubagentExecutionIdentity,
+  SubagentDefinitionBinding,
+  SubagentExecutionIdentity,
+  SubagentExecutionPreparationLease,
+  SubagentExecutionRecord,
+} from './SubagentExecutionRegistry';
 import type {
   SubagentResumeExecution,
   SubagentResumeManifest,
   SubagentCheckpointReference,
   SettledSubagentToolOutput,
 } from './SubagentReplay';
-import type { AggregatedHookResult, HookRegistry } from '@/hooks';
-import type { AgentContext } from '@/agents/AgentContext';
+import type {
+  AggregatedHookResult,
+  HookRegistry,
+  ToolApprovalReplaySnapshot,
+} from '@/hooks';
+import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HandlerRegistry } from '@/events';
+import {
+  getSubagentApprovalExecutionScope,
+  SubagentDefinitionBindingError,
+  SubagentExecutionRegistry,
+  SubagentInvocationBindingError,
+  SubagentSettlementBindingError,
+} from './SubagentExecutionRegistry';
 import {
   getSubagentResumeManifest,
   attachSubagentResumeManifest,
@@ -76,6 +102,10 @@ import {
   StreamLimitExceededError,
   RUN_BREAKER_SCOPE_CONFIG_KEY,
 } from '@/llm/streamLimits';
+import {
+  DEFAULT_SUBAGENT_MAX_TURNS,
+  SUBAGENT_RECURSION_MULTIPLIER,
+} from './runtimeLimits';
 import {
   ContentTypes,
   Constants,
@@ -87,12 +117,59 @@ import {
   executeHooks,
   TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY,
 } from '@/hooks';
+import {
+  createChildGraphPlan,
+  isGraphSubagentConfig,
+} from './childGraphConfig';
+import { stableStringify } from '@/tools/eagerEventExecution';
+import { composeAbortSignals } from '@/utils/misc';
+
+export {
+  buildChildInputs,
+  isGraphSubagentConfig,
+  normalizeSubagentConfigs,
+  normalizeSubagentConfigEntries,
+  resolveSubagentConfigs,
+  resolveSubagentConfigEntries,
+} from './childGraphConfig';
 
-const DEFAULT_MAX_TURNS = 25;
-const RECURSION_MULTIPLIER = 3;
 const ERROR_MESSAGE_MAX_CHARS = 200;
-const MAX_PENDING_SUBAGENT_UPDATES = 64;
+const MAX_QUEUED_SUBAGENT_UPDATES = 64;
+const SUBAGENT_UPDATE_HANDLER_TIMEOUT_MS = 5_000;
 const TEXT_DELTA_CONTENT_TYPE = `${ContentTypes.TEXT}_delta`;
+const SUBAGENT_RESOLUTION_ERROR_MESSAGE =
+  'Subagent error: Unable to initialize the selected subagent.';
+const SUBAGENT_CONFIG_CHANGED_MESSAGE =
+  'Subagent error: Subagent configuration changed since this execution was paused.';
+const SUBAGENT_INVOCATION_CHANGED_MESSAGE =
+  'Subagent error: Subagent invocation changed for this execution.';
+
+async function dispatchObservationalSubagentUpdate(
+  handler: EventHandler,
+  event: SubagentUpdateEvent
+): Promise<boolean> {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      Promise.resolve()
+        .then(() => handler.handle(GraphEvents.ON_SUBAGENT_UPDATE, event))
+        .then(
+          () => true,
+          () => true
+        ),
+      new Promise<boolean>((resolve) => {
+        timeout = setTimeout(
+          () => resolve(false),
+          SUBAGENT_UPDATE_HANDLER_TIMEOUT_MS
+        );
+      }),
+    ]);
+  } finally {
+    if (timeout != null) {
+      clearTimeout(timeout);
+    }
+  }
+}
 
 const HOOK_FALLBACK: AggregatedHookResult = Object.freeze({
   additionalContexts: [] as string[],
@@ -201,6 +278,7 @@ type QueuedSubagentUpdate = {
   eventName: string;
   phase: SubagentUpdatePhase;
   data: unknown;
+  memberAgentId?: string;
 };
 
 type ForwarderCallback = {
@@ -212,7 +290,7 @@ type StatefulCompiledWorkflow = Omit<CompiledStateWorkflow, 'invoke'> & {
   invoke(
     input: BaseGraphState | Command | null,
     config?: RunnableConfig
-  ): Promise<BaseGraphState>;
+  ): Promise<MultiAgentGraphState>;
   getState(config: RunnableConfig): Promise<StateSnapshot>;
   updateState?(
     config: RunnableConfig,
@@ -235,6 +313,7 @@ type ActiveChildRun = {
   pendingInterrupts: Interrupt[];
   invokeConfig?: RunnableConfig;
   childAgentId: string;
+  checkpointNodeId: string;
   childRunId: string;
 };
 
@@ -261,18 +340,54 @@ type SubagentCheckpointMarker = {
   settledOutput?: PersistedToolOutput;
 };
 
-type ChildExecutionIdentity = {
-  childRunId: string;
-  childThreadId: string;
-  approvalExecutionScope: string;
-  resumeExecution?: SubagentResumeExecution;
-};
+function isResumeExecutionCompatible(
+  resumeExecution: SubagentResumeExecution | undefined,
+  subagentType: string | undefined,
+  executableConfig: ExecutableSubagentConfigEntry | undefined,
+  hasPersistedTypeEvidence = false
+): boolean {
+  if (resumeExecution == null) {
+    return true;
+  }
+  if (
+    subagentType == null ||
+    executableConfig == null ||
+    resumeExecution.configId !== executableConfig.configId
+  ) {
+    return false;
+  }
+  if (resumeExecution.subagentType != null) {
+    return resumeExecution.subagentType === subagentType;
+  }
+  if (hasPersistedTypeEvidence) {
+    return true;
+  }
+  return (
+    isGraphSubagentConfig(executableConfig) ||
+    executableConfig.agentInputs != null
+  );
+}
 
-type ChildExecutionIdentityParams = {
-  threadId?: string;
-  parentToolCallId: string;
-  parentConfigurable?: Record<string, unknown>;
-};
+function getSubagentTypeFromArgs(args: unknown): string | undefined {
+  if (!isObjectLike(args)) {
+    return undefined;
+  }
+  return asNonEmptyString((args as { subagent_type?: unknown }).subagent_type);
+}
+
+function getSubagentDescriptionFromArgs(args: unknown): string | undefined {
+  if (!isObjectLike(args)) {
+    return undefined;
+  }
+  const description = (args as { description?: unknown }).description;
+  return typeof description === 'string' && description.trim().length > 0
+    ? description
+    : undefined;
+}
+
+function getSubagentType(call: ToolCall): string | undefined {
+  return getSubagentTypeFromArgs(call.args);
+}
 
 const LANGGRAPH_RUNTIME_CONFIG_PREFIX = '__pregel_';
 const LANGGRAPH_RESUME_MAP_CONFIG_KEY = '__pregel_resume_map';
@@ -285,6 +400,7 @@ const SUBAGENT_CHECKPOINT_MARKER_KEY = '__librechat_subagent_checkpoint';
 const SUBAGENT_HOOK_SESSION_KEY = '__librechat_subagent_hook_session';
 const SUBAGENT_RUN_ID_KEY = '__librechat_subagent_run_id';
 const SUBAGENT_REPLAY_NODE = 'subagent-replay';
+export const DEFAULT_SUBAGENT_DESCRIPTION = 'No task description provided';
 
 function isCheckpointSaver(value: unknown): value is BaseCheckpointSaver {
   if (value == null || typeof value !== 'object') {
@@ -480,6 +596,10 @@ function serializeToolOutput(
   };
 }
 
+function getSettlementFingerprint(output: PersistedToolOutput): string {
+  return createHash('sha256').update(stableStringify(output)).digest('hex');
+}
+
 function deserializeToolOutput(
   output: PersistedToolOutput
 ): SettledSubagentToolOutput {
@@ -504,61 +624,6 @@ function deserializeToolOutput(
   };
 }
 
-function getParentCheckpointFork(
-  configurable: Record<string, unknown> | undefined
-): string {
-  const checkpointId = configurable?.checkpoint_id;
-  return typeof checkpointId === 'string' && checkpointId.length > 0
-    ? checkpointId
-    : 'root';
-}
-
-function getResumeAttemptId(
-  configurable: Record<string, unknown> | undefined,
-  fallback: string
-): string {
-  const attemptId = configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
-  return typeof attemptId === 'string' && attemptId.length > 0
-    ? attemptId
-    : fallback;
-}
-
-function getApprovalExecutionScope(
-  childRunId: string,
-  resumeAttemptId: string
-): string {
-  return `subagent-approval:${Buffer.from(
-    JSON.stringify([childRunId, resumeAttemptId])
-  ).toString('base64url')}`;
-}
-
-function getChildThreadId(args: {
-  parentRunId: string;
-  parentAgentId?: string;
-  threadId?: string;
-  parentToolCallId: string;
-  parentConfigurable?: Record<string, unknown>;
-  branchId?: string;
-}): string {
-  const durableParentId = args.threadId ?? args.parentRunId;
-  const parentFork = getParentCheckpointFork(args.parentConfigurable);
-  const parentBatch =
-    args.parentConfigurable?.[SUBAGENT_PARENT_BATCH_CONFIG_KEY];
-  const identity = [
-    durableParentId,
-    parentFork,
-    args.parentAgentId ?? 'agent',
-    args.parentToolCallId,
-    typeof parentBatch === 'string' && parentBatch.length > 0
-      ? parentBatch
-      : 'batch',
-  ];
-  if (args.branchId != null) {
-    identity.push(args.branchId);
-  }
-  return `subagent:${Buffer.from(JSON.stringify(identity)).toString('base64url')}`;
-}
-
 function isToolApprovalPayload(
   value: unknown
 ): value is ToolApprovalInterruptPayload {
@@ -575,12 +640,13 @@ function addSubagentScope(
   resumeManifest?: SubagentResumeManifest
 ): Interrupt[] {
   return interrupts.map((childInterrupt) => {
-    const payload = isToolApprovalPayload(childInterrupt.value)
-      ? {
+    let payload = childInterrupt.value;
+    if (isToolApprovalPayload(payload)) {
+      payload = {
         ...childInterrupt.value,
         subagent: childInterrupt.value.subagent ?? scope,
-      }
-      : childInterrupt.value;
+      };
+    }
     return {
       ...childInterrupt,
       value:
@@ -656,6 +722,8 @@ export type SubagentExecuteParams = {
   description: string;
   subagentType: string;
   threadId?: string;
+  /** Signal attached to this specific parent tool invocation. */
+  signal?: AbortSignal;
   /**
    * Breaker controller captured at the parent TOOL BATCH's entry, before
    * PreToolUse hooks. Preferred over the live scope accessor: a graph reset
@@ -720,7 +788,7 @@ export type SubagentExecuteResult = {
 export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
 
 export type SubagentExecutorOptions = {
-  configs: Map<string, ResolvedSubagentConfig>;
+  configs: ReadonlyMap<string, ExecutableSubagentConfigEntry>;
   parentSignal?: AbortSignal;
   /** Run-scoped breaker abort shared by every executor of one graph, so a
    * child tripping a stream limit stops subagents running under OTHER
@@ -736,6 +804,8 @@ export type SubagentExecutorOptions = {
   hookRegistry?: HookRegistry;
   parentRunId: string;
   parentAgentId?: string;
+  /** Root identity, policy session, and lineage inherited by a child graph. */
+  executionContext?: SubagentExecutionContext;
   langfuse?: StandardGraphInput['langfuse'];
   tokenCounter?: TokenCounter;
   /**
@@ -760,6 +830,9 @@ export type SubagentExecutorOptions = {
    * module dependency.
    */
   createChildGraph: ChildGraphFactory;
+  /** Preferred polymorphic child constructor. The legacy standard-only
+   * factory remains required for source compatibility. */
+  createChildGraphByKind?: GraphFactory;
   /**
    * Parent's event handler registry. When provided, child-graph events are
    * forwarded through this registry so hosts can:
@@ -784,8 +857,15 @@ export type SubagentExecutorOptions = {
   usageSink?: SubagentUsageSink;
 };
 
+type DurableExecutionRecord = SubagentExecutionRecord<
+  SubagentExecuteResult,
+  ResolvedSubagentConfig,
+  ActiveChildRun,
+  PersistedToolOutput
+>;
+
 export class SubagentExecutor {
-  private readonly configs: Map<string, ResolvedSubagentConfig>;
+  private readonly configs: ReadonlyMap<string, ExecutableSubagentConfigEntry>;
   private readonly parentSignal?: AbortSignal;
   /** Aborted when a child trips a stream circuit breaker: parallel sibling
    * subagents run concurrently on the parent's signal, and rejecting the
@@ -798,6 +878,7 @@ export class SubagentExecutor {
   private readonly hookRegistry?: HookRegistry;
   private readonly parentRunId: string;
   private readonly parentAgentId?: string;
+  private readonly executionContext: SubagentExecutionContext;
   private readonly langfuse?: StandardGraphInput['langfuse'];
   private readonly tokenCounter?: TokenCounter;
   private readonly streamLimits?: StandardGraphInput['streamLimits'];
@@ -805,22 +886,14 @@ export class SubagentExecutor {
   private readonly checkpointer?: BaseCheckpointSaver;
   private readonly maxDepth: number;
   private readonly createChildGraph: ChildGraphFactory;
+  private readonly createChildGraphByKind?: GraphFactory;
   private readonly usageSink?: SubagentUsageSink;
-  private readonly checkpointThreadIds = new Set<string>();
-  private readonly startedChildRuns = new Set<string>();
-  private readonly completedChildRuns = new Set<string>();
-  private readonly completedChildResults = new Map<
-    string,
-    SubagentExecuteResult
-  >();
-  private readonly childExecutionIdentities = new Map<
-    string,
-    Pick<
-      ChildExecutionIdentity,
-      'childRunId' | 'childThreadId' | 'approvalExecutionScope'
-    >
-  >();
-  private readonly activeChildRuns = new Map<string, ActiveChildRun>();
+  private readonly executions: SubagentExecutionRegistry<
+    SubagentExecuteResult,
+    ResolvedSubagentConfig,
+    ActiveChildRun,
+    PersistedToolOutput
+  >;
   private replayCheckpointWorkflow?: ReplayCheckpointWorkflow;
   private readonly resolveParentHandlerRegistry?: () =>
     | HandlerRegistry
@@ -833,6 +906,12 @@ export class SubagentExecutor {
     this.hookRegistry = options.hookRegistry;
     this.parentRunId = options.parentRunId;
     this.parentAgentId = options.parentAgentId;
+    this.executionContext = options.executionContext ?? {
+      rootRunId: options.parentRunId,
+      hookSessionId: options.parentRunId,
+      depth: 0,
+      ancestry: [],
+    };
     this.langfuse = options.langfuse;
     this.tokenCounter = options.tokenCounter;
     this.streamLimits = options.streamLimits;
@@ -840,8 +919,15 @@ export class SubagentExecutor {
     this.checkpointer = isCheckpointSaver(options.checkpointer)
       ? options.checkpointer
       : undefined;
+    this.executions = new SubagentExecutionRegistry({
+      parentRunId: options.parentRunId,
+      parentAgentId: options.parentAgentId,
+      durable:
+        options.humanInTheLoop?.enabled === true && this.checkpointer != null,
+    });
     this.maxDepth = options.maxDepth ?? 1;
     this.createChildGraph = options.createChildGraph;
+    this.createChildGraphByKind = options.createChildGraphByKind;
     this.usageSink = options.usageSink;
     const rawRegistry = options.parentHandlerRegistry;
     if (typeof rawRegistry === 'function') {
@@ -860,12 +946,17 @@ export class SubagentExecutor {
   /** One signal that fires on the parent's abort or the breaker abort,
    * collapsed to a single signal when possible (mirrors
    * `composeAbortSignals` in Graph.ts). */
-  private composeChildSignal(breaker: AbortController): AbortSignal {
-    const child = breaker.signal;
-    if (this.parentSignal == null || this.parentSignal === child) {
-      return child;
-    }
-    return AbortSignal.any([this.parentSignal, child]);
+  private composeChildSignal(
+    breaker: AbortController,
+    executionSignal?: AbortSignal
+  ): AbortSignal {
+    const parentAndBreaker = composeAbortSignals(
+      this.parentSignal,
+      breaker.signal
+    );
+    return (
+      composeAbortSignals(parentAndBreaker, executionSignal) ?? breaker.signal
+    );
   }
 
   /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
@@ -873,6 +964,74 @@ export class SubagentExecutor {
     return this.resolveParentHandlerRegistry?.();
   }
 
+  private bindExecutionDefinition(
+    execution: DurableExecutionRecord,
+    binding: SubagentDefinitionBinding,
+    authority: 'provisional' | 'effective'
+  ): boolean {
+    try {
+      execution.bindDefinition(binding, authority);
+      return true;
+    } catch (error) {
+      if (error instanceof SubagentDefinitionBindingError) {
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  /** Resolve one lazy descriptor per stable child execution. Concurrent
+   * duplicate dispatches share the same in-flight resolution; HITL re-entry
+   * on this executor reuses the resolved config until the child settles. */
+  private resolveExecutionConfig(
+    config: ExecutableSubagentConfigEntry,
+    execution: DurableExecutionRecord,
+    context: {
+      childRunId: string;
+      childSignal: AbortSignal;
+      threadId?: string;
+      parentToolCallId?: string;
+      parentConfigurable?: Record<string, unknown>;
+    }
+  ): Promise<ResolvedSubagentConfigEntry> {
+    if (isGraphSubagentConfig(config) || config.agentInputs != null) {
+      return Promise.resolve(config as ResolvedSubagentConfigEntry);
+    }
+    const resolver = config.resolveAgentInputs;
+    const configId = config.configId;
+    return execution.resolveConfig(
+      (): Promise<ResolvedSubagentConfig> =>
+        resolveAgentInputsWithSignal(
+          (): Promise<AgentInputs> =>
+            resolver({
+              descriptor: {
+                type: config.type,
+                name: config.name,
+                description: config.description,
+                configId,
+              },
+              executionId: context.childRunId,
+              parentRunId: this.parentRunId,
+              parentAgentId: this.parentAgentId,
+              parentToolCallId: context.parentToolCallId,
+              threadId: context.threadId,
+              signal: context.childSignal,
+              configurable:
+                context.parentConfigurable == null
+                  ? undefined
+                  : sanitizeResolverConfigurable(context.parentConfigurable),
+            }),
+          context.childSignal
+        ).then(
+          (agentInputs): ResolvedSubagentConfig => ({
+            ...config,
+            agentInputs,
+          })
+        ),
+      context.childSignal
+    );
+  }
+
   /**
    * Keeps the original child thread as an immutable resume source once a
    * different parent Run reconstructs it. Each rebuilt parent gets a private
@@ -880,60 +1039,138 @@ export class SubagentExecutor {
    * activity and usage correlation across the interrupt boundary.
    */
   private async resolveChildExecutionIdentity(
-    params: ChildExecutionIdentityParams
-  ): Promise<ChildExecutionIdentity> {
-    const currentChildRunId = `${this.parentRunId}_sub_${params.parentToolCallId}`;
-    const resumeAttemptId = getResumeAttemptId(
-      params.parentConfigurable,
-      this.parentRunId
-    );
-    const baseChildThreadId = getChildThreadId({
-      parentRunId: this.parentRunId,
-      parentAgentId: this.parentAgentId,
-      threadId: params.threadId,
-      parentToolCallId: params.parentToolCallId,
-      parentConfigurable: params.parentConfigurable,
+    execution: DurableExecutionRecord
+  ): Promise<SubagentExecutionIdentity> {
+    return execution.resolveIdentity(async () => {
+      const preparation = await this.createChildExecutionIdentity(execution);
+      const { identity } = preparation;
+      return {
+        identity,
+        lease: preparation.lease,
+        commit: (lease): void => {
+          const { resumeExecution } = execution;
+          if (resumeExecution != null) {
+            this.executions.retireResumeSources(
+              execution,
+              new Set(
+                resumeExecution.checkpoints.map(
+                  (checkpoint) => checkpoint.threadId
+                )
+              ),
+              (source) => {
+                if (source.activeRun != null) {
+                  this.clearChildGraph(source.activeRun.graph);
+                }
+                if (source.identity != null) {
+                  this.hookRegistry?.clearSession(
+                    source.identity.approvalExecutionScope
+                  );
+                }
+              }
+            );
+          }
+          preparation.commit?.(lease);
+          if (
+            this.humanInTheLoop?.enabled === true &&
+            this.checkpointer != null
+          ) {
+            this.executions.rememberCheckpointThread(identity.childThreadId);
+          }
+        },
+        rollback: async (lease): Promise<void> => {
+          await preparation.rollback?.(lease);
+        },
+      };
     });
+  }
+
+  private async createChildExecutionIdentity(
+    execution: DurableExecutionRecord
+  ): Promise<PreparedSubagentExecutionIdentity> {
+    const {
+      baseChildThreadId,
+      branchChildThreadId,
+      currentChildRunId,
+      explicitResumeAttempt,
+      resumeAttemptId,
+    } = execution.address;
     if (this.humanInTheLoop?.enabled !== true || this.checkpointer == null) {
-      return {
+      return this.prepareIdentity(execution, {
         childRunId: currentChildRunId,
         childThreadId: baseChildThreadId,
         approvalExecutionScope: currentChildRunId,
-      };
+      });
     }
 
-    const resumeManifest = getSubagentResumeManifest(params.parentConfigurable);
-    const resumeExecution = resumeManifest?.executions.find(
-      (execution) => execution.parentToolCallId === params.parentToolCallId
-    );
-    const branchChildThreadId = getChildThreadId({
-      parentRunId: this.parentRunId,
-      parentAgentId: this.parentAgentId,
-      threadId: params.threadId,
-      parentToolCallId: params.parentToolCallId,
-      parentConfigurable: params.parentConfigurable,
-      branchId: resumeAttemptId,
-    });
+    const { resumeExecution } = execution;
     if (resumeExecution != null) {
-      const approvalExecutionScope = getApprovalExecutionScope(
+      const approvalExecutionScope = getSubagentApprovalExecutionScope(
         resumeExecution.childRunId,
         resumeAttemptId
       );
-      await this.forkCheckpointSnapshot(
-        resumeExecution.checkpoints,
-        branchChildThreadId
-      );
-      this.hookRegistry?.restorePendingToolApprovals(
-        approvalExecutionScope,
-        approvalExecutionScope,
-        resumeExecution.approvalReplays
-      );
-      this.checkpointThreadIds.add(branchChildThreadId);
-      return {
+      const identity = {
         childRunId: resumeExecution.childRunId,
         childThreadId: branchChildThreadId,
         approvalExecutionScope,
-        resumeExecution,
+      };
+      const lease = this.executions.beginIdentityPreparation(
+        execution,
+        identity
+      );
+      await this.prepareCheckpointFork(
+        resumeExecution.checkpoints,
+        branchChildThreadId,
+        lease
+      );
+      let previousApprovals: ToolApprovalReplaySnapshot[] = [];
+      let approvalsMutated = false;
+      return {
+        identity,
+        lease,
+        commit: (currentLease): void => {
+          const hookRegistry = this.hookRegistry;
+          if (hookRegistry == null) {
+            return;
+          }
+          previousApprovals = hookRegistry.snapshotPendingToolApprovals(
+            approvalExecutionScope,
+            approvalExecutionScope
+          );
+          const approvalReplayCreatesScope =
+            previousApprovals.length === 0 &&
+            resumeExecution.approvalReplays.length > 0;
+          const approvalsChanged =
+            previousApprovals.length > 0 ||
+            resumeExecution.approvalReplays.length > 0;
+          if (approvalReplayCreatesScope) {
+            currentLease.markApprovalScopeCreated(async (): Promise<void> => {
+              hookRegistry.restorePendingToolApprovals(
+                approvalExecutionScope,
+                approvalExecutionScope,
+                previousApprovals
+              );
+            });
+          }
+          approvalsMutated = approvalsChanged && !approvalReplayCreatesScope;
+          hookRegistry.restorePendingToolApprovals(
+            approvalExecutionScope,
+            approvalExecutionScope,
+            resumeExecution.approvalReplays
+          );
+        },
+        rollback: async (currentLease): Promise<void> => {
+          if (
+            approvalsMutated &&
+            currentLease.ownsApprovalScope &&
+            this.hookRegistry != null
+          ) {
+            this.hookRegistry.restorePendingToolApprovals(
+              approvalExecutionScope,
+              approvalExecutionScope,
+              previousApprovals
+            );
+          }
+        },
       };
     }
 
@@ -943,37 +1180,46 @@ export class SubagentExecutor {
     if (branchTuple != null) {
       const childRunId =
         getSubagentRunId(getTupleMessages(branchTuple)) ?? currentChildRunId;
-      this.checkpointThreadIds.add(branchChildThreadId);
-      return {
+      return this.prepareIdentity(execution, {
         childRunId,
         childThreadId: branchChildThreadId,
-        approvalExecutionScope: getApprovalExecutionScope(
+        approvalExecutionScope: getSubagentApprovalExecutionScope(
           childRunId,
           resumeAttemptId
         ),
-      };
+      });
     }
 
     const baseTuple = await this.checkpointer.getTuple({
       configurable: { thread_id: baseChildThreadId },
     });
+    if (baseTuple == null) {
+      return this.prepareIdentity(execution, {
+        childRunId: currentChildRunId,
+        childThreadId: explicitResumeAttempt
+          ? branchChildThreadId
+          : baseChildThreadId,
+        approvalExecutionScope: getSubagentApprovalExecutionScope(
+          currentChildRunId,
+          resumeAttemptId
+        ),
+      });
+    }
     const persistedChildRunId = getSubagentRunId(getTupleMessages(baseTuple));
     if (
-      baseTuple == null ||
-      persistedChildRunId == null ||
-      persistedChildRunId === currentChildRunId
+      !explicitResumeAttempt &&
+      (persistedChildRunId == null || persistedChildRunId === currentChildRunId)
     ) {
-      this.checkpointThreadIds.add(baseChildThreadId);
-      return {
-        childRunId: persistedChildRunId ?? currentChildRunId,
+      const childRunId = persistedChildRunId ?? currentChildRunId;
+      return this.prepareIdentity(execution, {
+        childRunId,
         childThreadId: baseChildThreadId,
-        approvalExecutionScope: getApprovalExecutionScope(
-          persistedChildRunId ?? currentChildRunId,
+        approvalExecutionScope: getSubagentApprovalExecutionScope(
+          childRunId,
           resumeAttemptId
         ),
-      };
+      });
     }
-
     const sourceCheckpoints =
       await this.getLatestCheckpointSnapshot(baseChildThreadId);
     if (sourceCheckpoints.length === 0) {
@@ -981,16 +1227,77 @@ export class SubagentExecutor {
         `Cannot fork subagent checkpoint thread "${baseChildThreadId}" without a checkpoint ID.`
       );
     }
-    await this.forkCheckpointSnapshot(sourceCheckpoints, branchChildThreadId);
-    this.checkpointThreadIds.add(branchChildThreadId);
-    return {
-      childRunId: persistedChildRunId,
+    const childRunId = persistedChildRunId ?? currentChildRunId;
+    const identity = {
+      childRunId,
       childThreadId: branchChildThreadId,
-      approvalExecutionScope: getApprovalExecutionScope(
-        persistedChildRunId,
+      approvalExecutionScope: getSubagentApprovalExecutionScope(
+        childRunId,
         resumeAttemptId
       ),
     };
+    const lease = this.executions.beginIdentityPreparation(execution, identity);
+    await this.prepareCheckpointFork(
+      sourceCheckpoints,
+      branchChildThreadId,
+      lease
+    );
+    return {
+      identity,
+      lease,
+    };
+  }
+
+  private prepareIdentity(
+    execution: DurableExecutionRecord,
+    identity: SubagentExecutionIdentity
+  ): PreparedSubagentExecutionIdentity {
+    return {
+      identity,
+      lease: this.executions.beginIdentityPreparation(execution, identity),
+    };
+  }
+
+  private async prepareCheckpointFork(
+    sources: ReadonlyArray<SubagentCheckpointReference>,
+    targetThreadId: string,
+    lease: SubagentExecutionPreparationLease
+  ): Promise<void> {
+    const checkpointer = this.checkpointer;
+    try {
+      if (
+        checkpointer == null ||
+        sources.length === 0 ||
+        sources.every((source) => source.threadId === targetThreadId)
+      ) {
+        lease.assertOwned();
+        return;
+      }
+      const targetExists = await this.checkpointThreadExists(targetThreadId);
+      lease.assertOwned();
+      if (!targetExists) {
+        lease.markCheckpointCreated(() =>
+          checkpointer.deleteThread(targetThreadId)
+        );
+      }
+      await this.forkCheckpointSnapshot(sources, targetThreadId);
+      lease.assertOwned();
+    } catch (error) {
+      return lease.rollback(error);
+    }
+  }
+
+  private async checkpointThreadExists(threadId: string): Promise<boolean> {
+    if (this.checkpointer == null) {
+      return false;
+    }
+    for await (const _tuple of this.checkpointer.list(
+      { configurable: { thread_id: threadId } },
+      { limit: 1 }
+    )) {
+      return true;
+    }
+    return false;
   }
 
   /** Captures one exact checkpoint head per namespace for a child thread. */
@@ -1130,28 +1437,26 @@ export class SubagentExecutor {
   }
 
   private async createResumeManifest(
-    parentToolCallIds?: ReadonlySet<string>
+    records: ReadonlyArray<DurableExecutionRecord>
   ): Promise<SubagentResumeManifest | undefined> {
     if (this.checkpointer == null) {
       return undefined;
     }
     const executions: SubagentResumeExecution[] = [];
-    for (const [parentToolCallId, identity] of this.childExecutionIdentities) {
-      if (
-        parentToolCallIds != null &&
-        !parentToolCallIds.has(parentToolCallId)
-      ) {
+    for (const record of records) {
+      const { identity, binding, activeRun } = record.snapshot;
+      if (identity == null) {
         continue;
       }
+      const { parentToolCallId } = record.address;
       const checkpoints = await this.getLatestCheckpointSnapshot(
         identity.childThreadId
       );
       if (checkpoints.length === 0) {
         continue;
       }
-      const activeChildRun = this.activeChildRuns.get(identity.childThreadId);
       const configuredHookSessionId =
-        activeChildRun?.invokeConfig?.configurable?.run_id;
+        activeRun?.invokeConfig?.configurable?.run_id;
       const hookSessionId =
         typeof configuredHookSessionId === 'string' &&
         configuredHookSessionId.length > 0
@@ -1162,12 +1467,12 @@ export class SubagentExecutor {
           identity.approvalExecutionScope,
           identity.approvalExecutionScope
         ) ?? [];
-      const descendant = activeChildRun?.pendingInterrupts
+      const descendant = activeRun?.pendingInterrupts
         .map((pendingInterrupt) =>
           getSubagentResumeManifest(pendingInterrupt.value)
         )
         .find((manifest) => manifest != null);
-      const graphState = activeChildRun?.graph.createSubagentResumeState(
+      const graphState = activeRun?.graph.createSubagentResumeState(
         hookSessionId
       ) ?? {
         toolCallSteps: [],
@@ -1179,6 +1484,10 @@ export class SubagentExecutor {
       executions.push({
         parentToolCallId,
         childRunId: identity.childRunId,
+        ...(binding?.subagentType == null
+          ? {}
+          : { subagentType: binding.subagentType }),
+        ...(binding?.configId == null ? {} : { configId: binding.configId }),
         approvalExecutionScope: identity.approvalExecutionScope,
         checkpoints,
         graphState,
@@ -1196,25 +1505,22 @@ export class SubagentExecutor {
   }
 
   getResumeManifest(
-    parentToolCallIds?: ReadonlySet<string>
+    parentToolCallIds?: ReadonlySet<string>,
+    config?: RunnableConfig
   ): Promise<SubagentResumeManifest | undefined> {
-    return this.createResumeManifest(parentToolCallIds);
+    return this.createResumeManifest(
+      this.executions.selectForResume({ parentToolCallIds, config })
+    );
   }
 
   getChildCheckpointThreadIds(): string[] {
-    const threadIds = new Set(this.checkpointThreadIds);
-    for (const activeChildRun of this.activeChildRuns.values()) {
-      for (const threadId of this.getGraphChildCheckpointThreadIds(
-        activeChildRun.graph
-      )) {
-        threadIds.add(threadId);
-      }
-    }
-    return [...threadIds];
+    return this.executions.getCheckpointThreadIds((activeRun) =>
+      this.getGraphChildCheckpointThreadIds(activeRun.graph)
+    );
   }
 
   resetCheckpointThreadIds(): void {
-    this.checkpointThreadIds.clear();
+    this.executions.resetCheckpointThreadIds();
   }
 
   private getGraphChildCheckpointThreadIds(graph: StandardGraph): string[] {
@@ -1225,25 +1531,54 @@ export class SubagentExecutor {
   }
 
   private clearChildGraph(graph: StandardGraph): void {
-    for (const threadId of this.getGraphChildCheckpointThreadIds(graph)) {
-      this.checkpointThreadIds.add(threadId);
-    }
+    this.executions.rememberCheckpointThread(
+      ...this.getGraphChildCheckpointThreadIds(graph)
+    );
     graph.clearHeavyState();
   }
 
   clearHeavyState(): void {
-    for (const activeChildRun of this.activeChildRuns.values()) {
-      this.clearChildGraph(activeChildRun.graph);
+    this.executions.clear((record) => {
+      if (record.activeRun != null) {
+        this.clearChildGraph(record.activeRun.graph);
+      }
+      if (record.identity != null) {
+        this.hookRegistry?.clearSession(record.identity.approvalExecutionScope);
+      }
+    });
+    this.replayCheckpointWorkflow = undefined;
+  }
+
+  private async getResumeCheckpointMarker(
+    resumeExecution: SubagentResumeExecution,
+    parentToolCallId: string
+  ): Promise<
+    { marker: SubagentCheckpointMarker; messages: BaseMessage[] } | undefined
+  > {
+    if (this.checkpointer == null) {
+      return undefined;
     }
-    this.activeChildRuns.clear();
-    this.completedChildResults.clear();
-    for (const identity of this.childExecutionIdentities.values()) {
-      this.hookRegistry?.clearSession(identity.approvalExecutionScope);
+    let fallback:
+      | { marker: SubagentCheckpointMarker; messages: BaseMessage[] }
+      | undefined;
+    for (const checkpoint of resumeExecution.checkpoints) {
+      const tuple = await this.checkpointer.getTuple({
+        configurable: {
+          thread_id: checkpoint.threadId,
+          checkpoint_ns: checkpoint.checkpointNs,
+          checkpoint_id: checkpoint.checkpointId,
+        },
+      });
+      const messages = getTupleMessages(tuple);
+      const marker = getSubagentCheckpointMarker(messages, parentToolCallId);
+      if (marker?.settledOutput != null) {
+        return { marker, messages };
+      }
+      if (marker != null && fallback == null) {
+        fallback = { marker, messages };
+      }
     }
-    this.childExecutionIdentities.clear();
-    this.startedChildRuns.clear();
-    this.completedChildRuns.clear();
-    this.replayCheckpointWorkflow = undefined;
+    return fallback;
   }
 
   async getSettledToolOutput(
@@ -1263,25 +1598,109 @@ export class SubagentExecutor {
       | Record<string, unknown>
       | undefined;
     const threadId = parentConfigurable?.thread_id;
-    const { childRunId, childThreadId, approvalExecutionScope } =
-      await this.resolveChildExecutionIdentity({
-        threadId: typeof threadId === 'string' ? threadId : undefined,
-        parentToolCallId,
-        parentConfigurable,
-      });
-    this.childExecutionIdentities.set(parentToolCallId, {
-      childRunId,
-      childThreadId,
-      approvalExecutionScope,
-    });
-    this.checkpointThreadIds.add(childThreadId);
-    const checkpoint = await this.checkpointer.getTuple({
-      configurable: { thread_id: childThreadId },
+    const execution = this.executions.open({
+      threadId: typeof threadId === 'string' ? threadId : undefined,
+      parentToolCallId,
+      parentConfigurable,
     });
-    const messages = getCheckpointMessages(
-      checkpoint?.checkpoint.channel_values.messages
+    const { resumeExecution } = execution;
+    const inProcessSettledOutput = execution.settledOutput;
+    if (inProcessSettledOutput != null) {
+      const persistedSubagentType = getSubagentTypeFromArgs(
+        inProcessSettledOutput.resolvedArgs
+      );
+      const subagentType =
+        persistedSubagentType ??
+        execution.binding?.subagentType ??
+        getSubagentType(call);
+      const executableConfig =
+        subagentType == null ? undefined : this.configs.get(subagentType);
+      if (
+        !isResumeExecutionCompatible(
+          resumeExecution,
+          subagentType,
+          executableConfig,
+          persistedSubagentType != null
+        )
+      ) {
+        return undefined;
+      }
+      return deserializeToolOutput(inProcessSettledOutput);
+    }
+    let resumeCheckpoint:
+      | { marker: SubagentCheckpointMarker; messages: BaseMessage[] }
+      | undefined;
+    if (resumeExecution != null) {
+      resumeCheckpoint = await this.getResumeCheckpointMarker(
+        resumeExecution,
+        parentToolCallId
+      );
+    }
+    let marker = resumeCheckpoint?.marker;
+    let messages = resumeCheckpoint?.messages ?? [];
+    let persistedSubagentType = getSubagentTypeFromArgs(
+      marker?.settledOutput?.resolvedArgs
     );
-    const marker = getSubagentCheckpointMarker(messages, parentToolCallId);
+    let subagentType =
+      persistedSubagentType ??
+      resumeExecution?.subagentType ??
+      getSubagentType(call);
+    let executableConfig =
+      subagentType == null ? undefined : this.configs.get(subagentType);
+    if (
+      !isResumeExecutionCompatible(
+        resumeExecution,
+        subagentType,
+        executableConfig,
+        persistedSubagentType != null
+      )
+    ) {
+      this.executions.remove(execution);
+      return undefined;
+    }
+    const { childThreadId } =
+      await this.resolveChildExecutionIdentity(execution);
+    if (marker == null) {
+      const checkpoint = await this.checkpointer.getTuple({
+        configurable: { thread_id: childThreadId },
+      });
+      messages = getCheckpointMessages(
+        checkpoint?.checkpoint.channel_values.messages
+      );
+      marker = getSubagentCheckpointMarker(messages, parentToolCallId);
+      persistedSubagentType = getSubagentTypeFromArgs(
+        marker?.settledOutput?.resolvedArgs
+      );
+      if (persistedSubagentType != null) {
+        subagentType = persistedSubagentType;
+        executableConfig = this.configs.get(subagentType);
+      }
+      if (
+        !isResumeExecutionCompatible(
+          resumeExecution,
+          subagentType,
+          executableConfig,
+          persistedSubagentType != null
+        )
+      ) {
+        this.executions.remove(execution);
+        return undefined;
+      }
+    }
+    const configId = executableConfig?.configId;
+    const bound = this.bindExecutionDefinition(
+      execution,
+      {
+        ...(subagentType == null ? {} : { subagentType }),
+        ...(configId == null ? {} : { configId }),
+      },
+      persistedSubagentType != null || resumeExecution?.subagentType != null
+        ? 'effective'
+        : 'provisional'
+    );
+    if (!bound) {
+      return undefined;
+    }
     const persistedHookSessionId =
       marker?.hookSessionId ?? getSubagentHookSessionId(messages);
     const currentHookSessionId = parentConfigurable?.run_id;
@@ -1306,9 +1725,10 @@ export class SubagentExecutor {
     settled: SettledSubagentToolOutput
   ): Promise<void> {
     const parentToolCallId = call.id;
+    const checkpointer = this.checkpointer;
     if (
       this.humanInTheLoop?.enabled !== true ||
-      this.checkpointer == null ||
+      checkpointer == null ||
       parentToolCallId == null ||
       parentToolCallId === ''
     ) {
@@ -1318,52 +1738,117 @@ export class SubagentExecutor {
       | Record<string, unknown>
       | undefined;
     const threadId = parentConfigurable?.thread_id;
-    const { childRunId, childThreadId, approvalExecutionScope } =
-      await this.resolveChildExecutionIdentity({
-        threadId: typeof threadId === 'string' ? threadId : undefined,
-        parentToolCallId,
-        parentConfigurable,
-      });
-    this.childExecutionIdentities.set(parentToolCallId, {
-      childRunId,
-      childThreadId,
-      approvalExecutionScope,
+    const execution = this.executions.open({
+      threadId: typeof threadId === 'string' ? threadId : undefined,
+      parentToolCallId,
+      parentConfigurable,
     });
-    this.checkpointThreadIds.add(childThreadId);
-    const activeChildRun = this.activeChildRuns.get(childThreadId);
+    const { resumeExecution } = execution;
+    const resolvedSubagentType = getSubagentTypeFromArgs(settled.resolvedArgs);
+    const resolvedDescription = getSubagentDescriptionFromArgs(
+      settled.resolvedArgs
+    );
+    const boundInvocation = execution.invocation;
+    if (
+      boundInvocation != null &&
+      resolvedDescription != null &&
+      resolvedDescription !== boundInvocation.description
+    ) {
+      return;
+    }
+    const description =
+      boundInvocation?.description ??
+      resolvedDescription ??
+      getSubagentDescriptionFromArgs(call.args) ??
+      DEFAULT_SUBAGENT_DESCRIPTION;
+    const subagentType =
+      resolvedSubagentType ??
+      execution.binding?.subagentType ??
+      getSubagentType(call);
+    const executableConfig =
+      subagentType == null ? undefined : this.configs.get(subagentType);
+    const configId =
+      resolvedSubagentType == null
+        ? (execution.binding?.configId ??
+          executableConfig?.configId ??
+          resumeExecution?.configId)
+        : executableConfig?.configId;
+    if (subagentType == null) {
+      return;
+    }
+    if (
+      !isResumeExecutionCompatible(
+        resumeExecution,
+        subagentType,
+        executableConfig
+      )
+    ) {
+      this.executions.remove(execution);
+      return;
+    }
     const persistedOutput = serializeToolOutput(settled);
-    if (activeChildRun != null) {
-      await this.persistChildCheckpointMarker(
-        activeChildRun,
-        parentToolCallId,
-        persistedOutput
+    const invocation = boundInvocation ?? {
+      description,
+      subagentType,
+      ...(configId == null ? {} : { configId }),
+    };
+    try {
+      await execution.settle(
+        {
+          definitionAuthority:
+            resolvedSubagentType == null ? 'provisional' : 'effective',
+          fingerprint: getSettlementFingerprint(persistedOutput),
+          invocation,
+          subagentType,
+          ...(configId == null ? {} : { configId }),
+        },
+        persistedOutput,
+        async (): Promise<void> => {
+          const { childRunId, childThreadId } =
+            await this.resolveChildExecutionIdentity(execution);
+          const activeChildRun = execution.activeRun;
+          if (activeChildRun != null) {
+            await this.persistChildCheckpointMarker(
+              activeChildRun,
+              parentToolCallId,
+              persistedOutput
+            );
+            this.clearChildGraph(activeChildRun.graph);
+            return;
+          }
+          this.replayCheckpointWorkflow ??=
+            createReplayCheckpointWorkflow(checkpointer);
+          await this.replayCheckpointWorkflow.updateState(
+            { configurable: { thread_id: childThreadId } },
+            {
+              messages: [
+                createSubagentCheckpointMarkerMessage({
+                  version: 1,
+                  parentToolCallId,
+                  lifecycleComplete: true,
+                  hookSessionId:
+                    typeof parentConfigurable?.run_id === 'string'
+                      ? parentConfigurable.run_id
+                      : this.parentRunId,
+                  childRunId,
+                  settledOutput: persistedOutput,
+                }),
+              ],
+            },
+            SUBAGENT_REPLAY_NODE
+          );
+        }
       );
-      this.clearChildGraph(activeChildRun.graph);
-      this.activeChildRuns.delete(childThreadId);
-      return;
+    } catch (error) {
+      if (
+        error instanceof SubagentDefinitionBindingError ||
+        error instanceof SubagentInvocationBindingError ||
+        error instanceof SubagentSettlementBindingError
+      ) {
+        return;
+      }
+      throw error;
     }
-    this.replayCheckpointWorkflow ??= createReplayCheckpointWorkflow(
-      this.checkpointer
-    );
-    await this.replayCheckpointWorkflow.updateState(
-      { configurable: { thread_id: childThreadId } },
-      {
-        messages: [
-          createSubagentCheckpointMarkerMessage({
-            version: 1,
-            parentToolCallId,
-            lifecycleComplete: true,
-            hookSessionId:
-              typeof parentConfigurable?.run_id === 'string'
-                ? parentConfigurable.run_id
-                : this.parentRunId,
-            childRunId,
-            settledOutput: persistedOutput,
-          }),
-        ],
-      },
-      SUBAGENT_REPLAY_NODE
-    );
   }
 
   private async persistChildCheckpointMarker(
@@ -1396,11 +1881,83 @@ export class SubagentExecutor {
           }),
         ],
       },
-      activeChildRun.childAgentId
+      activeChildRun.checkpointNodeId
     );
   }
 
-  async execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult> {
+  execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult> {
+    const executableConfig = this.configs.get(params.subagentType);
+    if (executableConfig == null) {
+      const available = [...this.configs.keys()].join(', ');
+      return Promise.resolve({
+        content: `Error: Unknown subagent type "${params.subagentType}". Available types: ${available}`,
+        messages: [],
+      });
+    }
+    if (this.maxDepth <= 0) {
+      return Promise.resolve({
+        content: 'Error: Maximum subagent nesting depth exceeded.',
+        messages: [],
+      });
+    }
+    if (
+      isGraphSubagentConfig(executableConfig) &&
+      this.humanInTheLoop?.enabled === true
+    ) {
+      return Promise.resolve({
+        content:
+          'Error: Human-in-the-loop execution is not yet supported for graph subagents.',
+        messages: [],
+      });
+    }
+    if (
+      this.humanInTheLoop?.enabled === true &&
+      (params.parentToolCallId == null || params.parentToolCallId === '')
+    ) {
+      return Promise.resolve({
+        content:
+          'Error: Resumable subagent execution requires a parent tool call ID.',
+        messages: [],
+      });
+    }
+    const execution = this.executions.open({
+      threadId: params.threadId,
+      parentToolCallId: params.parentToolCallId ?? nanoid(8),
+      parentConfigurable: params.parentConfigurable,
+    });
+    try {
+      return execution.execute(
+        {
+          description: params.description,
+          subagentType: params.subagentType,
+          ...(executableConfig.configId == null
+            ? {}
+            : { configId: executableConfig.configId }),
+        },
+        () => this.executeOnce(params, execution, executableConfig)
+      );
+    } catch (error) {
+      if (error instanceof SubagentDefinitionBindingError) {
+        return Promise.resolve({
+          content: SUBAGENT_CONFIG_CHANGED_MESSAGE,
+          messages: [],
+        });
+      }
+      if (error instanceof SubagentInvocationBindingError) {
+        return Promise.resolve({
+          content: SUBAGENT_INVOCATION_CHANGED_MESSAGE,
+          messages: [],
+        });
+      }
+      throw error;
+    }
+  }
+
+  private async executeOnce(
+    params: SubagentExecuteParams,
+    execution: DurableExecutionRecord,
+    executableConfig: ExecutableSubagentConfigEntry
+  ): Promise<SubagentExecuteResult> {
     const { description, subagentType, threadId, parentToolCallId } = params;
     /** Captured ONCE per execution, preferring the controller the parent
      * tool batch captured at ITS entry (before PreToolUse hooks): a failed
@@ -1410,61 +1967,75 @@ export class SubagentExecutor {
      * new run's breaker from an old child's stream-limit breach. Signal and
      * trip target both bind to this capture. */
     const childBreaker = params.breaker ?? this.resolveBreakerController();
-    const childSignal = this.composeChildSignal(childBreaker);
-    const config = this.configs.get(subagentType);
+    const childSignal = this.composeChildSignal(childBreaker, params.signal);
 
-    if (!config) {
-      const available = [...this.configs.keys()].join(', ');
+    const { parentToolCallId: executionSuffix } = execution.address;
+    const { resumeExecution } = execution;
+    if (
+      !isResumeExecutionCompatible(
+        resumeExecution,
+        subagentType,
+        executableConfig
+      )
+    ) {
+      this.executions.remove(execution);
       return {
-        content: `Error: Unknown subagent type "${subagentType}". Available types: ${available}`,
+        content: SUBAGENT_CONFIG_CHANGED_MESSAGE,
         messages: [],
       };
     }
-
-    if (this.maxDepth <= 0) {
+    let identity: SubagentExecutionIdentity;
+    try {
+      identity = await this.resolveChildExecutionIdentity(execution);
+      execution.assertUsable(childSignal);
+    } catch (error) {
+      if (error instanceof StreamLimitExceededError) {
+        throw error;
+      }
       return {
-        content: 'Error: Maximum subagent nesting depth exceeded.',
+        content: SUBAGENT_RESOLUTION_ERROR_MESSAGE,
         messages: [],
       };
     }
+    const { childRunId, childThreadId, approvalExecutionScope } = identity;
+    const bound = this.bindExecutionDefinition(
+      execution,
+      {
+        subagentType,
+        ...(executableConfig.configId == null
+          ? {}
+          : { configId: executableConfig.configId }),
+      },
+      'effective'
+    );
+    if (!bound) {
+      return { content: SUBAGENT_CONFIG_CHANGED_MESSAGE, messages: [] };
+    }
+    const completedChildResult = execution.completedResult;
+    if (completedChildResult != null) {
+      return completedChildResult;
+    }
 
-    if (
-      this.humanInTheLoop?.enabled === true &&
-      (parentToolCallId == null || parentToolCallId === '')
-    ) {
+    let config: ResolvedSubagentConfigEntry;
+    try {
+      config = await this.resolveExecutionConfig(executableConfig, execution, {
+        childRunId,
+        childSignal,
+        threadId,
+        parentToolCallId,
+        parentConfigurable: params.parentConfigurable,
+      });
+      execution.assertUsable(childSignal);
+    } catch (error) {
+      if (error instanceof StreamLimitExceededError) {
+        throw error;
+      }
       return {
-        content:
-          'Error: Resumable subagent execution requires a parent tool call ID.',
+        content: SUBAGENT_RESOLUTION_ERROR_MESSAGE,
         messages: [],
       };
     }
 
-    const executionSuffix = parentToolCallId ?? nanoid(8);
-    const {
-      childRunId,
-      childThreadId,
-      approvalExecutionScope,
-      resumeExecution,
-    } = await this.resolveChildExecutionIdentity({
-      threadId,
-      parentToolCallId: executionSuffix,
-      parentConfigurable: params.parentConfigurable,
-    });
-    this.childExecutionIdentities.set(executionSuffix, {
-      childRunId,
-      childThreadId,
-      approvalExecutionScope,
-    });
-    const childExecutionKey = childThreadId;
-    const childAgentId =
-      config.agentInputs.agentId ||
-      `${this.parentAgentId ?? 'agent'}_sub_${executionSuffix}`;
-    const completedChildResult =
-      this.completedChildResults.get(childExecutionKey);
-    if (completedChildResult != null) {
-      return completedChildResult;
-    }
-
     const parentRegistry = this.getParentHandlerRegistry();
     const forwardingEnabled = parentRegistry != null;
     /**
@@ -1478,79 +2049,121 @@ export class SubagentExecutor {
      */
     const hasToolExecuteHandler =
       parentRegistry?.getHandler(GraphEvents.ON_TOOL_EXECUTE) != null;
-    const childInputs = buildChildInputs(
+    const childPlan = createChildGraphPlan({
       config,
-      childAgentId,
-      this.maxDepth,
-      /* keepToolDefinitions */ hasToolExecuteHandler
-    );
-    const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+      executionSuffix,
+      parentAgentId: this.parentAgentId,
+      parentMaxDepth: this.maxDepth,
+      keepToolDefinitions: hasToolExecuteHandler,
+    });
+    const childAgentId = childPlan.subjectAgentId;
+    const currentHookSessionId =
+      asNonEmptyString(params.parentConfigurable?.run_id) ??
+      this.executionContext.hookSessionId;
+    const childExecutionContext: SubagentExecutionContext = {
+      rootRunId: this.executionContext.rootRunId,
+      hookSessionId: currentHookSessionId,
+      depth: this.executionContext.depth + 1,
+      ancestry: [
+        ...this.executionContext.ancestry,
+        {
+          subagentRunId: childRunId,
+          subagentType,
+          subagentKind: childPlan.kind,
+          subagentAgentId: childAgentId,
+          parentRunId: this.parentRunId,
+          parentAgentId: this.parentAgentId,
+          parentToolCallId,
+        },
+      ],
+    };
+    const maxTurns = config.maxTurns ?? DEFAULT_SUBAGENT_MAX_TURNS;
+    const memberRecursionLimit = maxTurns * SUBAGENT_RECURSION_MULTIPLIER;
+    const recursionLimit =
+      memberRecursionLimit *
+      (childPlan.kind === 'graph' ? childPlan.agents.length : 1);
 
     const hostUsageSink = this.usageSink;
-    const cachedChildRun = this.activeChildRuns.get(childExecutionKey);
-    const childGraph =
-      cachedChildRun?.graph ??
-      this.createChildGraph({
-        runId: childRunId,
-        signal: childSignal,
-        agents: [childInputs],
-        langfuse: this.langfuse,
-        tokenCounter: this.tokenCounter,
-        streamLimits: this.streamLimits,
-        subagentScope: true,
-        /**
-         * Forwarded so the child graph's own `SubagentExecutor` (created in
-         * its `createAgentNode` when `allowNested` keeps subagentConfigs)
-         * reports nested-child usage through the same host sink. Each nesting
-         * level attaches its own capture callback — `workflow.invoke` replaces
-         * the inherited callback chain, so a single top-level handler would
-         * never see grandchild model calls.
-         *
-         * The wrapper rewrites `runId` to THIS executor's parent run: nested
-         * executors emit with their own `parentRunId` (a `*_sub_*` child id),
-         * and each wrapper layer rewrites upward, so by the time an event
-         * reaches the host sink its `runId` is the ROOT run — hosts keying
-         * billing by run id never see intermediate child run ids there
-         * (`subagentRunId` still identifies the emitting child).
-         */
-        subagentUsageSink:
-          hostUsageSink == null
-            ? undefined
-            : /** Returns the host sink's result so async sinks stay awaited
-               *  through every wrapper layer. */
-            (event): void | Promise<void> =>
-              hostUsageSink({ ...event, runId: this.parentRunId }),
+    let subagentUsageSink: SubagentUsageSink | undefined;
+    if (hostUsageSink != null) {
+      subagentUsageSink = (event): void | Promise<void> =>
+        hostUsageSink({
+          ...event,
+          runId: this.executionContext.rootRunId,
+        });
+    }
+    const cachedChildRun = execution.activeRun;
+    const childGraphInput: StandardGraphInput = {
+      runId: childRunId,
+      signal: childSignal,
+      agents: childPlan.agents,
+      langfuse: this.langfuse,
+      tokenCounter: this.tokenCounter,
+      streamLimits: this.streamLimits,
+      subagentScope: true,
+      subagentExecutionContext: childExecutionContext,
+      /**
+       * Forwarded so the child graph's own `SubagentExecutor` (created in
+       * its `createAgentNode` when `allowNested` keeps subagentConfigs)
+       * reports nested-child usage through the same host sink. Each nesting
+       * level attaches its own capture callback — `workflow.invoke` replaces
+       * the inherited callback chain, so a single top-level handler would
+       * never see grandchild model calls.
+       */
+      subagentUsageSink,
+    };
+    let childGraph = cachedChildRun?.graph;
+    if (childGraph == null && childPlan.kind === 'graph') {
+      if (this.createChildGraphByKind == null) {
+        return {
+          content:
+            'Error: Graph subagent execution requires a polymorphic child graph factory.',
+          messages: [],
+        };
+      }
+      childGraph = this.createChildGraphByKind({
+        kind: 'multi-agent',
+        input: {
+          ...childGraphInput,
+          edges: childPlan.edges,
+          resultAgentId: childPlan.resultAgentId,
+          memberRecursionLimit,
+        },
       });
+    }
+    childGraph ??= this.createChildGraph(childGraphInput);
     let forwarding: ForwarderCallback | undefined;
     if (forwardingEnabled) {
       forwarding = this.createForwarderCallback({
         parentRegistry: parentRegistry!,
         subagentType,
+        subagentKind: childPlan.kind,
         subagentAgentId: childAgentId,
         childRunId,
         parentToolCallId,
+        executionContext: childExecutionContext,
       });
     }
     const forwarder = forwarding?.handler;
-    let childAlreadyStarted = this.startedChildRuns.has(childExecutionKey);
-    let childAlreadyCompleted = this.completedChildRuns.has(childExecutionKey);
+    let childAlreadyStarted = execution.started;
+    let childAlreadyCompleted = execution.completed;
 
-    let result: { messages: BaseMessage[] } | undefined;
+    let result: MultiAgentGraphState | undefined;
     let recoveredComplete = false;
     let recoveredInProgress = false;
     try {
       const workflow = (cachedChildRun?.workflow ??
         childGraph.createWorkflow()) as StatefulCompiledWorkflow;
-      const activeChildRun = cachedChildRun ?? {
-        graph: childGraph,
-        workflow,
-        pendingInterrupts: [],
-        childAgentId,
-        childRunId,
-      };
-      if (cachedChildRun == null) {
-        this.activeChildRuns.set(childExecutionKey, activeChildRun);
-      }
+      const activeChildRun = execution.activate(
+        cachedChildRun ?? {
+          graph: childGraph,
+          workflow,
+          pendingInterrupts: [],
+          childAgentId,
+          checkpointNodeId: childPlan.checkpointNodeId,
+          childRunId,
+        }
+      );
       /**
        * When `parentHandlerRegistry` is provided (forwarding mode), attach a
        * lightweight callback that intercepts the child's `on_custom_event`
@@ -1584,11 +2197,12 @@ export class SubagentExecutor {
           createUsageCaptureHandler({
             sink: this.usageSink,
             subagentType,
+            subagentKind: childPlan.kind,
             subagentRunId: childRunId,
             subagentAgentId: childAgentId,
             parentRunId: this.parentRunId,
-            provider: config.agentInputs.provider,
-            fallbackModel: extractConfiguredModel(config.agentInputs),
+            executionContext: childExecutionContext,
+            memberInputs: childPlan.memberInputs,
           })
         );
       }
@@ -1608,46 +2222,35 @@ export class SubagentExecutor {
        */
       const inheritedConfigurable: Record<string, unknown> =
         sanitizeChildConfigurable(params.parentConfigurable);
-      const resumeAttemptId = getResumeAttemptId(
-        params.parentConfigurable,
-        this.parentRunId
-      );
-      const currentHookSessionId =
-        typeof inheritedConfigurable.run_id === 'string' &&
-        inheritedConfigurable.run_id.length > 0
-          ? inheritedConfigurable.run_id
-          : this.parentRunId;
+      const { resumeAttemptId } = execution.address;
       if (cachedChildRun == null && resumeExecution != null) {
         childGraph.restoreSubagentResumeState(
           resumeExecution.graphState,
           currentHookSessionId
         );
       }
+      const childConfigurable: Record<string, unknown> = {
+        ...inheritedConfigurable,
+      };
+      if (this.humanInTheLoop?.enabled === true) {
+        childConfigurable[TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY] =
+          approvalExecutionScope;
+      }
+      if (resumeExecution?.descendant != null) {
+        childConfigurable[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY] =
+          resumeExecution.descendant;
+        childConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY] = resumeAttemptId;
+      }
+      childConfigurable.thread_id =
+        this.humanInTheLoop?.enabled === true
+          ? childThreadId
+          : (inheritedConfigurable.thread_id ?? childRunId);
       const childInvokeConfig = {
-        recursionLimit: maxTurns * RECURSION_MULTIPLIER,
+        recursionLimit,
         signal: childSignal,
         callbacks,
         runName: `subagent:${subagentType}`,
-        configurable: {
-          ...inheritedConfigurable,
-          ...(this.humanInTheLoop?.enabled === true
-            ? {
-              [TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY]:
-                  approvalExecutionScope,
-            }
-            : {}),
-          ...(resumeExecution?.descendant == null
-            ? {}
-            : {
-              [SUBAGENT_RESUME_MANIFEST_CONFIG_KEY]:
-                  resumeExecution.descendant,
-              [SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY]: resumeAttemptId,
-            }),
-          thread_id:
-            this.humanInTheLoop?.enabled === true
-              ? childThreadId
-              : (inheritedConfigurable.thread_id ?? childRunId),
-        },
+        configurable: childConfigurable,
       };
       activeChildRun.invokeConfig = childInvokeConfig;
       if (cachedChildRun == null && this.humanInTheLoop?.enabled === true) {
@@ -1669,12 +2272,12 @@ export class SubagentExecutor {
         const persistedInterrupts = getPersistedInterrupts(persistedState);
         if (persistedInterrupts.length > 0) {
           activeChildRun.pendingInterrupts = persistedInterrupts;
-          this.startedChildRuns.add(childExecutionKey);
+          execution.markStarted();
           childAlreadyStarted = true;
         } else if (persistedState.next.length > 0) {
           recoveredInProgress = true;
           childAlreadyStarted = true;
-          this.startedChildRuns.add(childExecutionKey);
+          execution.markStarted();
         } else if (persistedState.next.length === 0) {
           const persistedMessages = getPersistedMessages(persistedState);
           if (persistedMessages != null) {
@@ -1686,7 +2289,7 @@ export class SubagentExecutor {
             recoveredComplete = true;
             childAlreadyStarted = true;
             childAlreadyCompleted = marker?.lifecycleComplete === true;
-            this.startedChildRuns.add(childExecutionKey);
+            execution.markStarted();
           }
         }
       }
@@ -1722,54 +2325,59 @@ export class SubagentExecutor {
 
         if (
           !childAlreadyStarted &&
-          this.hookRegistry?.hasHookFor('SubagentStart', this.parentRunId) ===
-            true
+          this.hookRegistry?.hasHookFor(
+            'SubagentStart',
+            currentHookSessionId
+          ) === true
         ) {
           const hookResult = await executeHooks({
             registry: this.hookRegistry,
             input: {
               hook_event_name: 'SubagentStart',
-              runId: this.parentRunId,
+              runId: currentHookSessionId,
               threadId,
               parentAgentId: this.parentAgentId,
               agentId: childAgentId,
               agentType: subagentType,
               inputs: [new HumanMessage(description)],
             },
-            sessionId: this.parentRunId,
+            sessionId: currentHookSessionId,
             matchQuery: subagentType,
           }).catch((): AggregatedHookResult => HOOK_FALLBACK);
 
           if (hookResult.decision === 'deny' || hookResult.decision === 'ask') {
             this.clearChildGraph(childGraph);
-            this.activeChildRuns.delete(childExecutionKey);
+            execution.releaseActiveRun();
+            this.executions.remove(execution);
             return {
               content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
               messages: [],
             };
           }
         }
-        this.startedChildRuns.add(childExecutionKey);
+        execution.markStarted();
 
         if (forwarder && !childAlreadyStarted) {
           await this.emitSubagentUpdate(parentRegistry!, {
             childRunId,
             subagentType,
+            subagentKind: childPlan.kind,
             subagentAgentId: childAgentId,
             parentToolCallId,
+            executionContext: childExecutionContext,
             phase: 'start',
             label: `Subagent "${subagentType}" started`,
           });
         }
 
-        let childResult: BaseGraphState;
+        let childResult: MultiAgentGraphState;
         if (this.humanInTheLoop?.enabled === true) {
           /** Execute as an independently checkpointed root instead of inheriting
            * the parent's Pregel namespace. Parent decisions are routed explicitly
            * by interrupt id, so concurrent children keep isolated resume state. */
           childResult = await AsyncLocalStorageProviderSingleton.runWithConfig(
             childInvokeConfig,
-            (): Promise<BaseGraphState> =>
+            (): Promise<MultiAgentGraphState> =>
               workflow.invoke(childInput, childInvokeConfig)
           );
         } else {
@@ -1781,18 +2389,19 @@ export class SubagentExecutor {
         if (childInterrupts != null && childInterrupts.length > 0) {
           throw new GraphInterrupt(childInterrupts);
         }
-        result = { messages: childResult.messages };
+        result = childResult;
       }
     } catch (error) {
       if (isGraphInterrupt(error)) {
-        const activeChildRun = this.activeChildRuns.get(childExecutionKey);
+        const activeChildRun = execution.activeRun;
         if (activeChildRun != null) {
           activeChildRun.pendingInterrupts = error.interrupts;
+          execution.markInterrupted();
         }
         const resumeManifest =
           activeChildRun == null || parentToolCallId == null
             ? undefined
-            : await this.createResumeManifest();
+            : await this.createResumeManifest([execution]);
         await forwarding?.drain();
         throw new GraphInterrupt(
           addSubagentScope(
@@ -1823,15 +2432,17 @@ export class SubagentExecutor {
         await this.emitSubagentUpdate(parentRegistry!, {
           childRunId,
           subagentType,
+          subagentKind: childPlan.kind,
           subagentAgentId: childAgentId,
           parentToolCallId,
+          executionContext: childExecutionContext,
           phase: 'error',
           label: `Subagent "${subagentType}" errored: ${errorMessage}`,
           data: { message: errorMessage },
         });
       }
       this.clearChildGraph(childGraph);
-      this.activeChildRuns.delete(childExecutionKey);
+      execution.markFailed();
       /**
        * A tripped stream circuit breaker is a safety abort, not a recoverable
        * subagent failure: converting it into a tool result would let the
@@ -1851,11 +2462,15 @@ export class SubagentExecutor {
     if (result == null) {
       throw new Error('Subagent completed without producing graph state.');
     }
-    const filteredContent = filterSubagentResult(result.messages);
+    const filteredContent =
+      childPlan.kind === 'graph'
+        ? filterGraphSubagentResult(result, childPlan.resultAgentId)
+        : filterSubagentResult(result.messages);
 
     if (
       !childAlreadyCompleted &&
-      this.hookRegistry?.hasHookFor('SubagentStop', this.parentRunId) === true
+      this.hookRegistry?.hasHookFor('SubagentStop', currentHookSessionId) ===
+        true
     ) {
       /**
        * Awaited (not fire-and-forget) for deterministic test synchronization
@@ -1867,13 +2482,13 @@ export class SubagentExecutor {
         registry: this.hookRegistry,
         input: {
           hook_event_name: 'SubagentStop',
-          runId: this.parentRunId,
+          runId: currentHookSessionId,
           threadId,
           agentId: childAgentId,
           agentType: subagentType,
           messages: result.messages,
         },
-        sessionId: this.parentRunId,
+        sessionId: currentHookSessionId,
         matchQuery: subagentType,
       }).catch(() => {
         /* SubagentStop is observational — swallow errors */
@@ -1885,14 +2500,16 @@ export class SubagentExecutor {
       await this.emitSubagentUpdate(parentRegistry!, {
         childRunId,
         subagentType,
+        subagentKind: childPlan.kind,
         subagentAgentId: childAgentId,
         parentToolCallId,
+        executionContext: childExecutionContext,
         phase: 'stop',
         label: `Subagent "${subagentType}" finished`,
       });
     }
     if (!childAlreadyCompleted) {
-      const activeChildRun = this.activeChildRuns.get(childExecutionKey);
+      const activeChildRun = execution.activeRun;
       if (activeChildRun != null && parentToolCallId != null) {
         await this.persistChildCheckpointMarker(
           activeChildRun,
@@ -1900,7 +2517,6 @@ export class SubagentExecutor {
         );
       }
     }
-    this.completedChildRuns.add(childExecutionKey);
 
     this.clearChildGraph(childGraph);
 
@@ -1908,7 +2524,7 @@ export class SubagentExecutor {
       content: filteredContent,
       messages: result.messages,
     };
-    this.completedChildResults.set(childExecutionKey, completedResult);
+    execution.markCompleted(completedResult);
     return completedResult;
   }
 
@@ -1922,8 +2538,11 @@ export class SubagentExecutor {
     args: {
       childRunId: string;
       subagentType: string;
+      subagentKind: 'agent' | 'graph';
       subagentAgentId: string;
+      memberAgentId?: string;
       parentToolCallId?: string;
+      executionContext: SubagentExecutionContext;
       phase: SubagentUpdatePhase;
       data?: unknown;
       label?: string;
@@ -1934,22 +2553,23 @@ export class SubagentExecutor {
       return;
     }
     const event: SubagentUpdateEvent = {
-      runId: this.parentRunId,
+      runId: args.executionContext.rootRunId,
+      parentRunId: this.parentRunId,
       subagentRunId: args.childRunId,
       subagentType: args.subagentType,
+      subagentKind: args.subagentKind,
       subagentAgentId: args.subagentAgentId,
+      memberAgentId: args.memberAgentId,
       parentAgentId: this.parentAgentId,
       parentToolCallId: args.parentToolCallId,
+      depth: args.executionContext.depth,
+      ancestry: args.executionContext.ancestry,
       phase: args.phase,
       data: args.data,
       label: args.label,
       timestamp: new Date().toISOString(),
     };
-    try {
-      await handler.handle(GraphEvents.ON_SUBAGENT_UPDATE, event);
-    } catch {
-      /* observational — swallow */
-    }
+    await dispatchObservationalSubagentUpdate(handler, event);
   }
 
   /**
@@ -1967,60 +2587,72 @@ export class SubagentExecutor {
   private createForwarderCallback(args: {
     parentRegistry: HandlerRegistry;
     subagentType: string;
+    subagentKind: 'agent' | 'graph';
     subagentAgentId: string;
     childRunId: string;
     parentToolCallId?: string;
+    executionContext: SubagentExecutionContext;
   }): ForwarderCallback {
     const {
       parentRegistry,
       subagentType,
+      subagentKind,
       subagentAgentId,
       childRunId,
       parentToolCallId,
+      executionContext,
     } = args;
-    const parentRunId = this.parentRunId;
+    const immediateParentRunId = this.parentRunId;
     const parentAgentId = this.parentAgentId;
 
     const wrap = async (
       eventName: string,
       phase: SubagentUpdatePhase,
-      data: unknown
-    ): Promise<void> => {
+      data: unknown,
+      memberAgentId?: string
+    ): Promise<boolean> => {
       const handler = parentRegistry.getHandler(GraphEvents.ON_SUBAGENT_UPDATE);
       if (!handler) {
-        return;
-      }
-      try {
-        const event: SubagentUpdateEvent = {
-          runId: parentRunId,
-          subagentRunId: childRunId,
-          subagentType,
-          subagentAgentId,
-          parentAgentId,
-          parentToolCallId,
-          phase,
-          data: sanitizeForwardedSubagentUpdateData(eventName, data),
-          label: summarizeEvent(eventName, data),
-          timestamp: new Date().toISOString(),
-        };
-        await handler.handle(GraphEvents.ON_SUBAGENT_UPDATE, event);
-      } catch {
-        /* observational — swallow */
+        return true;
       }
+      const event: SubagentUpdateEvent = {
+        runId: executionContext.rootRunId,
+        parentRunId: immediateParentRunId,
+        subagentRunId: childRunId,
+        subagentType,
+        subagentKind,
+        subagentAgentId,
+        memberAgentId,
+        parentAgentId,
+        parentToolCallId,
+        depth: executionContext.depth,
+        ancestry: executionContext.ancestry,
+        phase,
+        data: sanitizeForwardedSubagentUpdateData(eventName, data),
+        label: summarizeEvent(eventName, data),
+        timestamp: new Date().toISOString(),
+      };
+      return dispatchObservationalSubagentUpdate(handler, event);
     };
 
     const queuedUpdates: QueuedSubagentUpdate[] = [];
     let drainPromise: Promise<void> | undefined;
+    let queueOpen = true;
 
     const enqueue = (update: QueuedSubagentUpdate): void => {
-      if (queuedUpdates.length >= MAX_PENDING_SUBAGENT_UPDATES) {
+      if (!queueOpen) {
+        return;
+      }
+      if (queuedUpdates.length >= MAX_QUEUED_SUBAGENT_UPDATES) {
         const dropIndex = queuedUpdates.findIndex((queued) =>
-          isDroppableSubagentUpdatePhase(queued.phase)
+          isLowPrioritySubagentUpdatePhase(queued.phase)
         );
         if (dropIndex >= 0) {
           queuedUpdates.splice(dropIndex, 1);
-        } else if (isDroppableSubagentUpdatePhase(update.phase)) {
+        } else if (isLowPrioritySubagentUpdatePhase(update.phase)) {
           return;
+        } else {
+          queuedUpdates.shift();
         }
       }
       queuedUpdates.push(update);
@@ -2037,7 +2669,16 @@ export class SubagentExecutor {
           if (update == null) {
             continue;
           }
-          await wrap(update.eventName, update.phase, update.data);
+          const handlerSettled = await wrap(
+            update.eventName,
+            update.phase,
+            update.data,
+            update.memberAgentId
+          );
+          if (!handlerSettled) {
+            queueOpen = false;
+            queuedUpdates.length = 0;
+          }
         }
       })();
       try {
@@ -2053,17 +2694,23 @@ export class SubagentExecutor {
     const scheduleWrap = (
       eventName: string,
       phase: SubagentUpdatePhase,
-      data: unknown
+      data: unknown,
+      memberAgentId?: string
     ): void => {
-      enqueue({ eventName, phase, data });
+      enqueue({ eventName, phase, data, memberAgentId });
       void drain();
     };
 
     const handler = BaseCallbackHandler.fromMethods({
       [Callback.CUSTOM_EVENT]: async (
         eventName: string,
-        data: unknown
+        data: unknown,
+        _runId?: string,
+        _tags?: string[],
+        metadata?: Record<string, unknown>
       ): Promise<void> => {
+        const memberAgentId =
+          asNonEmptyString(metadata?.agentId) ?? getEventAgentId(data);
         if (eventName === GraphEvents.ON_TOOL_EXECUTE) {
           const toolHandler = parentRegistry.getHandler(
             GraphEvents.ON_TOOL_EXECUTE
@@ -2078,28 +2725,28 @@ export class SubagentExecutor {
            * We also surface a short notice in the subagent-update stream so
            * the UI can show "calling <tool>" for each tool the child spawns.
            */
-          scheduleWrap(eventName, 'run_step', data);
+          scheduleWrap(eventName, 'run_step', data, memberAgentId);
           return;
         }
 
         if (eventName === GraphEvents.ON_RUN_STEP) {
-          scheduleWrap(eventName, 'run_step', data);
+          scheduleWrap(eventName, 'run_step', data, memberAgentId);
           return;
         }
         if (eventName === GraphEvents.ON_RUN_STEP_DELTA) {
-          scheduleWrap(eventName, 'run_step_delta', data);
+          scheduleWrap(eventName, 'run_step_delta', data, memberAgentId);
           return;
         }
         if (eventName === GraphEvents.ON_RUN_STEP_COMPLETED) {
-          scheduleWrap(eventName, 'run_step_completed', data);
+          scheduleWrap(eventName, 'run_step_completed', data, memberAgentId);
           return;
         }
         if (eventName === GraphEvents.ON_MESSAGE_DELTA) {
-          scheduleWrap(eventName, 'message_delta', data);
+          scheduleWrap(eventName, 'message_delta', data, memberAgentId);
           return;
         }
         if (eventName === GraphEvents.ON_REASONING_DELTA) {
-          scheduleWrap(eventName, 'reasoning_delta', data);
+          scheduleWrap(eventName, 'reasoning_delta', data, memberAgentId);
           return;
         }
       },
@@ -2134,29 +2781,25 @@ export class SubagentExecutor {
 function createUsageCaptureHandler(args: {
   sink: SubagentUsageSink;
   subagentType: string;
+  subagentKind: 'agent' | 'graph';
   subagentRunId: string;
   subagentAgentId: string;
   parentRunId: string;
-  /**
-   * Child config's provider enum — the default tag when a call carries no
-   * `INVOKED_PROVIDER` metadata (hosts key pricing/cache semantics off it).
-   */
-  provider?: string;
-  /**
-   * Child config's model, used when a call carries neither `ls_model_name`
-   * nor `INVOKED_MODEL` metadata.
-   */
-  fallbackModel?: string;
+  executionContext: SubagentExecutionContext;
+  memberInputs: ReadonlyMap<string, AgentInputs>;
 }): BaseCallbackHandler {
   const {
     sink,
     subagentType,
+    subagentKind,
     subagentRunId,
     subagentAgentId,
     parentRunId,
-    provider,
-    fallbackModel,
+    executionContext,
+    memberInputs,
   } = args;
+  const defaultMember =
+    memberInputs.size === 1 ? memberInputs.entries().next().value : undefined;
   /**
    * Per-call attribution keyed by LangChain callback runId. `model` joins
    * `ls_model_name` (provider-reported) with `INVOKED_MODEL` (stamped by
@@ -2168,7 +2811,7 @@ function createUsageCaptureHandler(args: {
    */
   const callInfoByCallId = new Map<
     string,
-    { model?: string; provider?: string }
+    { model?: string; provider?: string; memberAgentId?: string }
   >();
   const handler = BaseCallbackHandler.fromMethods({
     handleChatModelStart: (
@@ -2186,18 +2829,30 @@ function createUsageCaptureHandler(args: {
       const callProvider = asNonEmptyString(
         metadata?.[Constants.INVOKED_PROVIDER]
       );
-      if (callModel != null || callProvider != null) {
+      const memberAgentId = asNonEmptyString(metadata?.agentId);
+      if (callModel != null || callProvider != null || memberAgentId != null) {
         callInfoByCallId.set(runId, {
           model: callModel,
           provider: callProvider,
+          memberAgentId,
         });
       }
     },
     handleLLMEnd: async (output: LLMResult, runId: string): Promise<void> => {
       const callInfo = callInfoByCallId.get(runId);
       callInfoByCallId.delete(runId);
-      const model = callInfo?.model ?? fallbackModel;
-      const callProvider = callInfo?.provider ?? provider;
+      const observedMemberAgentId = callInfo?.memberAgentId;
+      const memberAgentId =
+        observedMemberAgentId != null && memberInputs.has(observedMemberAgentId)
+          ? observedMemberAgentId
+          : defaultMember?.[0];
+      const memberInput =
+        (memberAgentId == null ? undefined : memberInputs.get(memberAgentId)) ??
+        defaultMember?.[1];
+      const model =
+        callInfo?.model ??
+        (memberInput == null ? undefined : extractConfiguredModel(memberInput));
+      const callProvider = callInfo?.provider ?? memberInput?.provider;
       for (const generationGroup of output.generations) {
         /**
          * At most ONE event per generation group: each group is one
@@ -2227,9 +2882,14 @@ function createUsageCaptureHandler(args: {
               model,
               provider: callProvider,
               subagentType,
+              subagentKind,
               subagentRunId,
               subagentAgentId,
-              runId: parentRunId,
+              memberAgentId,
+              parentRunId,
+              depth: executionContext.depth,
+              ancestry: executionContext.ancestry,
+              runId: executionContext.rootRunId,
             });
           } catch {
             /* observational — a throwing/rejecting host sink must not break the child run */
@@ -2255,6 +2915,19 @@ function asNonEmptyString(value: unknown): string | undefined {
   return typeof value === 'string' && value !== '' ? value : undefined;
 }
 
+function getEventAgentId(data: unknown): string | undefined {
+  if (data == null || typeof data !== 'object') {
+    return undefined;
+  }
+  const event = data as {
+    agentId?: unknown;
+    result?: { agentId?: unknown };
+  };
+  return (
+    asNonEmptyString(event.agentId) ?? asNonEmptyString(event.result?.agentId)
+  );
+}
+
 /**
  * Best-effort read of the configured model from a subagent's client
  * options. Providers disagree on the key (`model` vs `modelName`), and the
@@ -2276,6 +2949,63 @@ function extractConfiguredModel(agentInputs: AgentInputs): string | undefined {
   return undefined;
 }
 
+function sanitizeResolverConfigurable(
+  parentConfigurable: Record<string, unknown>
+): SubagentResolveConfigurable | undefined {
+  const configurable = sanitizeChildConfigurable(parentConfigurable);
+  const requestBody = createResolveRequestContext(configurable.requestBody);
+  const user = createResolveUserContext(configurable.user);
+  const userId = asNonEmptyString(configurable.user_id) ?? user?.id;
+  if (requestBody == null && user == null && userId == null) {
+    return undefined;
+  }
+  return {
+    ...(requestBody == null ? {} : { requestBody }),
+    ...(user == null ? {} : { user }),
+    ...(userId == null ? {} : { user_id: userId }),
+  };
+}
+
+function createResolveRequestContext(
+  value: unknown
+): SubagentResolveRequestContext | undefined {
+  if (!isObjectLike(value)) {
+    return undefined;
+  }
+  const source = value as SubagentResolveRequestContext;
+  const conversationId = asNonEmptyString(source.conversationId);
+  const messageId = asNonEmptyString(source.messageId);
+  const parentMessageId = asNonEmptyString(source.parentMessageId);
+  if (conversationId == null && messageId == null && parentMessageId == null) {
+    return undefined;
+  }
+  return {
+    ...(conversationId == null ? {} : { conversationId }),
+    ...(messageId == null ? {} : { messageId }),
+    ...(parentMessageId == null ? {} : { parentMessageId }),
+  };
+}
+
+function createResolveUserContext(
+  value: unknown
+): SubagentResolveUserContext | undefined {
+  if (!isObjectLike(value)) {
+    return undefined;
+  }
+  const source = value as SubagentResolveUserContext;
+  const id = asNonEmptyString(source.id);
+  const role = asNonEmptyString(source.role);
+  const tenantId = asNonEmptyString(source.tenantId);
+  if (id == null && role == null && tenantId == null) {
+    return undefined;
+  }
+  return {
+    ...(id == null ? {} : { id }),
+    ...(role == null ? {} : { role }),
+    ...(tenantId == null ? {} : { tenantId }),
+  };
+}
+
 function sanitizeChildConfigurable(
   parentConfigurable: Record<string, unknown> | undefined
 ): Record<string, unknown> {
@@ -2296,6 +3026,7 @@ function isLangGraphRuntimeConfigKey(key: string): boolean {
     key === SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY ||
     key === SUBAGENT_RESUME_MANIFEST_CONFIG_KEY ||
     key === SUBAGENT_PARENT_BATCH_CONFIG_KEY ||
+    key === TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY ||
     /** The parent batch's breaker scope must not leak into the child
      * workflow's configurable — children own separate controllers. */
     key === RUN_BREAKER_SCOPE_CONFIG_KEY
@@ -2327,7 +3058,7 @@ export function sanitizeForwardedSubagentUpdateData(
   return undefined;
 }
 
-function isDroppableSubagentUpdatePhase(phase: SubagentUpdatePhase): boolean {
+function isLowPrioritySubagentUpdatePhase(phase: SubagentUpdatePhase): boolean {
   return (
     phase === 'message_delta' ||
     phase === 'reasoning_delta' ||
@@ -2643,6 +3374,24 @@ export function summarizeEvent(eventName: string, data: unknown): string {
   return eventName;
 }
 
+/**
+ * Reads only the result member captured by MultiAgentGraph. Worker output is
+ * never used as a fallback when the designated result member is textless.
+ */
+export function filterGraphSubagentResult(
+  state: MultiAgentGraphState,
+  resultAgentId: string
+): string {
+  const result = state.subagentResult;
+  if (result == null || result.agentId !== resultAgentId) {
+    return `Error: Graph subagent result agent "${resultAgentId}" did not produce a result.`;
+  }
+  if (result.message == null) {
+    return 'Task completed';
+  }
+  return filterSubagentResult([result.message]);
+}
+
 /**
  * Walk messages from last to first, returning the text content of the most
  * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
@@ -2741,113 +3490,46 @@ export function filterSubagentResult(messages: BaseMessage[]): string {
   return 'Task completed';
 }
 
-/**
- * Resolve self-spawn configs by filling in agentInputs from the parent context.
- * Returns configs with agentInputs guaranteed present. Throws on duplicate
- * `type` values to prevent silent config shadowing.
- */
-export function resolveSubagentConfigs(
-  configs: SubagentConfig[],
-  parentContext: AgentContext
-): ResolvedSubagentConfig[] {
-  const resolved = configs
-    .map((config) => {
-      if (config.agentInputs != null) {
-        return config as ResolvedSubagentConfig;
-      }
-      if (config.self !== true || parentContext._sourceInputs == null) {
-        return null;
-      }
-      return {
-        ...config,
-        agentInputs: { ...parentContext._sourceInputs },
-      } as ResolvedSubagentConfig;
-    })
-    .filter((c): c is ResolvedSubagentConfig => c != null);
-
-  const seenTypes = new Set<string>();
-  for (const config of resolved) {
-    if (seenTypes.has(config.type)) {
-      throw new Error(
-        `Duplicate subagent type "${config.type}". Each SubagentConfig must have a unique "type" field.`
-      );
-    }
-    seenTypes.add(config.type);
+function truncateErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  if (message.length <= ERROR_MESSAGE_MAX_CHARS) {
+    return message;
   }
-
-  return resolved;
+  return `${message.slice(0, ERROR_MESSAGE_MAX_CHARS)}...`;
 }
 
-/**
- * Build child AgentInputs from a resolved config, stripping nesting and
- * (optionally) event-driven fields. When `allowNested: true`, the child's
- * `maxSubagentDepth` is decremented so that depth is consumed as the call
- * chain deepens across graph boundaries — the parent's executor-level check
- * alone cannot see into the child graph's separate executor.
- *
- * When `keepToolDefinitions` is `true`, the child retains the parent's
- * `toolDefinitions` so event-driven tools remain usable. This is only safe
- * when the caller has wired a forwarder for `ON_TOOL_EXECUTE` to a
- * registered handler — otherwise the child will hang on tool dispatch.
- *
- * @remarks Advanced utility: exported primarily for testing and by
- * {@link SubagentExecutor}. Host applications configuring subagents should
- * not need to call this directly — it is invoked internally when a subagent
- * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
- * child's decremented `maxSubagentDepth` on the returned inputs) is the
- * mechanism that bounds nesting across graph boundaries; callers must
- * respect it.
- */
-export function buildChildInputs(
-  config: ResolvedSubagentConfig,
-  childAgentId: string,
-  parentMaxDepth: number,
-  keepToolDefinitions: boolean = false
-): AgentInputs {
-  const { agentInputs } = config;
-  const childInputs: AgentInputs = {
-    ...agentInputs,
-    agentId: childAgentId,
-    toolDefinitions: keepToolDefinitions
-      ? agentInputs.toolDefinitions
-      : undefined,
-    /**
-     * Subagents run in an isolated context by contract. Parent-run-scoped
-     * fields that would otherwise survive the shallow-spread clone — the
-     * cross-run conversation summary and the prior-turn tool-discovery
-     * set — are cleared here so the child starts fresh. Host applications
-     * that want a subagent to see parent context must thread it in
-     * explicitly (e.g. via the `description` argument to the subagent
-     * tool), not via inherited state.
-     */
-    initialSummary: undefined,
-    discoveredTools: undefined,
-    /**
-     * Host-supplied direct tools are scrubbed from INHERITED configs only.
-     * A self-spawn config's `agentInputs` is a shallow spread of the parent's
-     * `_sourceInputs`, so without this a parent-scoped graph tool (e.g. an
-     * interrupt-raising ask_user_question) would silently become available to
-     * the child. An EXPLICIT child config that lists its own `graphTools` is a
-     * deliberate host choice and keeps them (Codex #289 P2); with HITL enabled,
-     * those tools use the shared checkpointer and can pause and resume safely.
-     */
-    graphTools: config.self === true ? undefined : agentInputs.graphTools,
-  };
-
-  if (config.allowNested === true) {
-    childInputs.maxSubagentDepth = Math.max(0, parentMaxDepth - 1);
-  } else {
-    childInputs.subagentConfigs = undefined;
-    childInputs.maxSubagentDepth = undefined;
+function resolveAgentInputsWithSignal(
+  resolve: () => Promise<AgentInputs>,
+  signal: AbortSignal
+): Promise<AgentInputs> {
+  if (signal.aborted) {
+    return Promise.reject(getAbortReason(signal));
   }
 
-  return childInputs;
+  return new Promise<AgentInputs>((resolvePromise, rejectPromise) => {
+    const cleanup = (): void => signal.removeEventListener('abort', onAbort);
+    const onAbort = (): void => {
+      cleanup();
+      rejectPromise(getAbortReason(signal));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    Promise.resolve()
+      .then(resolve)
+      .then(
+        (agentInputs) => {
+          cleanup();
+          resolvePromise(agentInputs);
+        },
+        (error: unknown) => {
+          cleanup();
+          rejectPromise(error);
+        }
+      );
+  });
 }
 
-function truncateErrorMessage(error: unknown): string {
-  const message = error instanceof Error ? error.message : String(error);
-  if (message.length <= ERROR_MESSAGE_MAX_CHARS) {
-    return message;
-  }
-  return `${message.slice(0, ERROR_MESSAGE_MAX_CHARS)}...`;
+function getAbortReason(signal: AbortSignal): Error {
+  return signal.reason instanceof Error
+    ? signal.reason
+    : new Error('Subagent resolution aborted.');
 }