@librechat/agents 3.4.0 → 3.4.2

package/dist/esm/tools/subagent/SubagentExecutor.mjs

@@ -1,28 +1,223 @@
+import { SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY, SUBAGENT_RESUME_MANIFEST_CONFIG_KEY, attachSubagentResumeManifest, getSubagentResumeManifest } from "./SubagentReplay.mjs";
+import { composeAbortSignals } from "../../utils/misc.mjs";
 import "../../common/enum.mjs";
 import "../../common/index.mjs";
+import { stableStringify } from "../eagerEventExecution.mjs";
 import { StreamLimitExceededError } from "../../llm/streamLimits.mjs";
+import { SubagentDefinitionBindingError, SubagentExecutionRegistry, SubagentInvocationBindingError, SubagentSettlementBindingError, getSubagentApprovalExecutionScope } from "./SubagentExecutionRegistry.mjs";
+import "./runtimeLimits.mjs";
 import { executeHooks } from "../../hooks/executeHooks.mjs";
+import { TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY } from "../../hooks/types.mjs";
 import "../../hooks/index.mjs";
+import { createChildGraphPlan, isGraphSubagentConfig } from "./childGraphConfig.mjs";
 import { nanoid } from "nanoid";
 import { BaseCallbackHandler } from "@langchain/core/callbacks/base";
-import { HumanMessage } from "@langchain/core/messages";
+import { AIMessage, BaseMessage, HumanMessage, ToolMessage } from "@langchain/core/messages";
+import { Command, END, GraphInterrupt, INTERRUPT, MessagesAnnotation, START, StateGraph, copyCheckpoint, isGraphInterrupt, isInterrupted } from "@langchain/langgraph";
+import { AsyncLocalStorageProviderSingleton } from "@langchain/core/singletons";
+import { createHash } from "crypto";
 //#region src/tools/subagent/SubagentExecutor.ts
-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 = 5e3;
 const TEXT_DELTA_CONTENT_TYPE = `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, event) {
+	let timeout;
+	try {
+		return await Promise.race([Promise.resolve().then(() => handler.handle("on_subagent_update", event)).then(() => true, () => true), new Promise((resolve) => {
+			timeout = setTimeout(() => resolve(false), SUBAGENT_UPDATE_HANDLER_TIMEOUT_MS);
+		})]);
+	} finally {
+		if (timeout != null) clearTimeout(timeout);
+	}
+}
 const HOOK_FALLBACK = Object.freeze({
 	additionalContexts: [],
 	injectedMessages: [],
 	errors: []
 });
+function isResumeExecutionCompatible(resumeExecution, subagentType, executableConfig, hasPersistedTypeEvidence = false) {
+	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;
+}
+function getSubagentTypeFromArgs(args) {
+	if (!isObjectLike(args)) return;
+	return asNonEmptyString(args.subagent_type);
+}
+function getSubagentDescriptionFromArgs(args) {
+	if (!isObjectLike(args)) return;
+	const description = args.description;
+	return typeof description === "string" && description.trim().length > 0 ? description : void 0;
+}
+function getSubagentType(call) {
+	return getSubagentTypeFromArgs(call.args);
+}
 const LANGGRAPH_RUNTIME_CONFIG_PREFIX = "__pregel_";
+const LANGGRAPH_RESUME_MAP_CONFIG_KEY = "__pregel_resume_map";
 const LANGGRAPH_CHECKPOINT_CONFIG_KEYS = new Set([
 	"checkpoint_id",
 	"checkpoint_map",
 	"checkpoint_ns"
 ]);
+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";
+const DEFAULT_SUBAGENT_DESCRIPTION = "No task description provided";
+function isCheckpointSaver(value) {
+	if (value == null || typeof value !== "object") return false;
+	const candidate = value;
+	return typeof candidate.getTuple === "function" && typeof candidate.list === "function" && typeof candidate.put === "function" && typeof candidate.putWrites === "function" && typeof candidate.deleteThread === "function";
+}
+function isSubagentCheckpointMarker(value) {
+	if (value == null || typeof value !== "object") return false;
+	const marker = value;
+	return marker.version === 1 && marker.lifecycleComplete === true && typeof marker.parentToolCallId === "string" && (marker.hookSessionId == null || typeof marker.hookSessionId === "string") && (marker.childRunId == null || typeof marker.childRunId === "string") && (marker.settledOutput == null || isPersistedToolOutput(marker.settledOutput));
+}
+function isPersistedToolOutput(value) {
+	if (value == null || typeof value !== "object") return false;
+	const output = value;
+	const contentIsValid = typeof output.content === "string" || Array.isArray(output.content);
+	const statusIsValid = output.status == null || output.status === "success" || output.status === "error";
+	const contextsAreValid = Array.isArray(output.additionalContexts) && output.additionalContexts.every((context) => typeof context === "string");
+	const resolvedArgsAreValid = output.resolvedArgs == null || typeof output.resolvedArgs === "object" && !Array.isArray(output.resolvedArgs);
+	return contentIsValid && typeof output.toolCallId === "string" && output.additionalKwargs != null && typeof output.additionalKwargs === "object" && output.responseMetadata != null && typeof output.responseMetadata === "object" && statusIsValid && contextsAreValid && resolvedArgsAreValid && (output.referenceContent == null || typeof output.referenceContent === "string");
+}
+function getSubagentCheckpointMarker(messages, parentToolCallId) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const marker = messages[i].additional_kwargs[SUBAGENT_CHECKPOINT_MARKER_KEY];
+		if (isSubagentCheckpointMarker(marker) && marker.parentToolCallId === parentToolCallId) return marker;
+	}
+}
+function getSubagentHookSessionId(messages) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const sessionId = messages[i].additional_kwargs[SUBAGENT_HOOK_SESSION_KEY];
+		if (typeof sessionId === "string" && sessionId.length > 0) return sessionId;
+	}
+}
+function getSubagentRunId(messages) {
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const runId = messages[i].additional_kwargs[SUBAGENT_RUN_ID_KEY];
+		if (typeof runId === "string" && runId.length > 0) return runId;
+		const marker = messages[i].additional_kwargs[SUBAGENT_CHECKPOINT_MARKER_KEY];
+		if (isSubagentCheckpointMarker(marker) && marker.childRunId != null && marker.childRunId.length > 0) return marker.childRunId;
+	}
+}
+function isSubagentCheckpointMarkerMessage(message) {
+	return isSubagentCheckpointMarker(message.additional_kwargs[SUBAGENT_CHECKPOINT_MARKER_KEY]);
+}
+function createSubagentCheckpointMarkerMessage(marker) {
+	return new AIMessage({
+		content: "",
+		additional_kwargs: { [SUBAGENT_CHECKPOINT_MARKER_KEY]: marker }
+	});
+}
+function getCheckpointMessages(value) {
+	return Array.isArray(value) ? value.filter(BaseMessage.isInstance) : [];
+}
+function getConfigurableString(config, key) {
+	const value = config?.configurable?.[key];
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function getTupleMessages(tuple) {
+	return getCheckpointMessages(tuple?.checkpoint.channel_values.messages);
+}
+function getCheckpointReference(tuple) {
+	const configurable = tuple?.config.configurable;
+	const threadId = configurable?.thread_id;
+	const checkpointId = configurable?.checkpoint_id;
+	const checkpointNs = configurable?.checkpoint_ns ?? "";
+	if (typeof threadId !== "string" || threadId.length === 0 || typeof checkpointId !== "string" || checkpointId.length === 0 || typeof checkpointNs !== "string") return;
+	return {
+		threadId,
+		checkpointId,
+		checkpointNs
+	};
+}
+function serializeToolOutput(settled) {
+	const { output } = settled;
+	return {
+		content: output.content,
+		toolCallId: output.tool_call_id,
+		...output.id == null ? {} : { id: output.id },
+		...output.name == null ? {} : { name: output.name },
+		...output.status == null ? {} : { status: output.status },
+		additionalKwargs: output.additional_kwargs,
+		responseMetadata: output.response_metadata,
+		...output.metadata == null ? {} : { metadata: output.metadata },
+		additionalContexts: settled.additionalContexts,
+		...settled.resolvedArgs == null ? {} : { resolvedArgs: settled.resolvedArgs },
+		...settled.referenceContent == null ? {} : { referenceContent: settled.referenceContent }
+	};
+}
+function getSettlementFingerprint(output) {
+	return createHash("sha256").update(stableStringify(output)).digest("hex");
+}
+function deserializeToolOutput(output) {
+	return {
+		output: new ToolMessage({
+			content: output.content,
+			tool_call_id: output.toolCallId,
+			...output.id == null ? {} : { id: output.id },
+			...output.name == null ? {} : { name: output.name },
+			...output.status == null ? {} : { status: output.status },
+			additional_kwargs: output.additionalKwargs,
+			response_metadata: output.responseMetadata,
+			...output.metadata == null ? {} : { metadata: output.metadata }
+		}),
+		additionalContexts: output.additionalContexts,
+		...output.resolvedArgs == null ? {} : { resolvedArgs: output.resolvedArgs },
+		...output.referenceContent == null ? {} : { referenceContent: output.referenceContent }
+	};
+}
+function isToolApprovalPayload(value) {
+	return value != null && typeof value === "object" && value.type === "tool_approval";
+}
+function addSubagentScope(interrupts, scope, resumeManifest) {
+	return interrupts.map((childInterrupt) => {
+		let payload = childInterrupt.value;
+		if (isToolApprovalPayload(payload)) payload = {
+			...childInterrupt.value,
+			subagent: childInterrupt.value.subagent ?? scope
+		};
+		return {
+			...childInterrupt,
+			value: resumeManifest == null ? payload : attachSubagentResumeManifest(payload, resumeManifest)
+		};
+	});
+}
+function getChildResumeMap(pendingInterrupts, parentConfigurable) {
+	const resumeMap = parentConfigurable?.[LANGGRAPH_RESUME_MAP_CONFIG_KEY];
+	if (resumeMap == null || typeof resumeMap !== "object") return;
+	const parentResumeMap = resumeMap;
+	const childResumeMap = {};
+	for (const childInterrupt of pendingInterrupts) {
+		const interruptId = childInterrupt.id;
+		if (typeof interruptId === "string" && Object.prototype.hasOwnProperty.call(parentResumeMap, interruptId)) childResumeMap[interruptId] = parentResumeMap[interruptId];
+	}
+	return Object.keys(childResumeMap).length > 0 ? childResumeMap : void 0;
+}
+function getPersistedInterrupts(snapshot) {
+	const interrupts = [];
+	for (const task of snapshot.tasks) for (const pendingInterrupt of task.interrupts) interrupts.push(pendingInterrupt);
+	return interrupts;
+}
+function getPersistedMessages(snapshot) {
+	if (snapshot.values == null || typeof snapshot.values !== "object") return;
+	const values = snapshot.values;
+	if (!Array.isArray(values.messages) || values.messages.length === 0) return;
+	const messages = values.messages.filter((message) => !isSubagentCheckpointMarkerMessage(message));
+	return messages.length > 0 ? messages : void 0;
+}
+function createReplayCheckpointWorkflow(checkpointer) {
+	return new StateGraph(MessagesAnnotation).addNode(SUBAGENT_REPLAY_NODE, (state) => state).addEdge(START, SUBAGENT_REPLAY_NODE).addEdge(SUBAGENT_REPLAY_NODE, END).compile({ checkpointer });
+}
 var SubagentExecutor = class {
 	configs;
 	parentSignal;
@@ -37,12 +232,18 @@ var SubagentExecutor = class {
 	hookRegistry;
 	parentRunId;
 	parentAgentId;
+	executionContext;
 	langfuse;
 	tokenCounter;
 	streamLimits;
+	humanInTheLoop;
+	checkpointer;
 	maxDepth;
 	createChildGraph;
+	createChildGraphByKind;
 	usageSink;
+	executions;
+	replayCheckpointWorkflow;
 	resolveParentHandlerRegistry;
 	constructor(options) {
 		this.configs = options.configs;
@@ -51,11 +252,25 @@ var SubagentExecutor = class {
 		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;
+		this.humanInTheLoop = options.humanInTheLoop;
+		this.checkpointer = isCheckpointSaver(options.checkpointer) ? options.checkpointer : void 0;
+		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") this.resolveParentHandlerRegistry = rawRegistry;
@@ -69,16 +284,501 @@ var SubagentExecutor = class {
 	/** 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). */
-	composeChildSignal(breaker) {
-		const child = breaker.signal;
-		if (this.parentSignal == null || this.parentSignal === child) return child;
-		return AbortSignal.any([this.parentSignal, child]);
+	composeChildSignal(breaker, executionSignal) {
+		return composeAbortSignals(composeAbortSignals(this.parentSignal, breaker.signal), executionSignal) ?? breaker.signal;
 	}
 	/** Snapshot of the parent's registry at the moment a subagent is dispatched. */
 	getParentHandlerRegistry() {
 		return this.resolveParentHandlerRegistry?.();
 	}
-	async execute(params) {
+	bindExecutionDefinition(execution, binding, authority) {
+		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. */
+	resolveExecutionConfig(config, execution, context) {
+		if (isGraphSubagentConfig(config) || config.agentInputs != null) return Promise.resolve(config);
+		const resolver = config.resolveAgentInputs;
+		const configId = config.configId;
+		return execution.resolveConfig(() => resolveAgentInputsWithSignal(() => 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 ? void 0 : sanitizeResolverConfigurable(context.parentConfigurable)
+		}), context.childSignal).then((agentInputs) => ({
+			...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
+	* checkpoint fork, while the persisted child run ID remains stable for
+	* activity and usage correlation across the interrupt boundary.
+	*/
+	async resolveChildExecutionIdentity(execution) {
+		return execution.resolveIdentity(async () => {
+			const preparation = await this.createChildExecutionIdentity(execution);
+			const { identity } = preparation;
+			return {
+				identity,
+				lease: preparation.lease,
+				commit: (lease) => {
+					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) => {
+					await preparation.rollback?.(lease);
+				}
+			};
+		});
+	}
+	async createChildExecutionIdentity(execution) {
+		const { baseChildThreadId, branchChildThreadId, currentChildRunId, explicitResumeAttempt, resumeAttemptId } = execution.address;
+		if (this.humanInTheLoop?.enabled !== true || this.checkpointer == null) return this.prepareIdentity(execution, {
+			childRunId: currentChildRunId,
+			childThreadId: baseChildThreadId,
+			approvalExecutionScope: currentChildRunId
+		});
+		const { resumeExecution } = execution;
+		if (resumeExecution != null) {
+			const approvalExecutionScope = getSubagentApprovalExecutionScope(resumeExecution.childRunId, resumeAttemptId);
+			const identity = {
+				childRunId: resumeExecution.childRunId,
+				childThreadId: branchChildThreadId,
+				approvalExecutionScope
+			};
+			const lease = this.executions.beginIdentityPreparation(execution, identity);
+			await this.prepareCheckpointFork(resumeExecution.checkpoints, branchChildThreadId, lease);
+			let previousApprovals = [];
+			let approvalsMutated = false;
+			return {
+				identity,
+				lease,
+				commit: (currentLease) => {
+					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 () => {
+						hookRegistry.restorePendingToolApprovals(approvalExecutionScope, approvalExecutionScope, previousApprovals);
+					});
+					approvalsMutated = approvalsChanged && !approvalReplayCreatesScope;
+					hookRegistry.restorePendingToolApprovals(approvalExecutionScope, approvalExecutionScope, resumeExecution.approvalReplays);
+				},
+				rollback: async (currentLease) => {
+					if (approvalsMutated && currentLease.ownsApprovalScope && this.hookRegistry != null) this.hookRegistry.restorePendingToolApprovals(approvalExecutionScope, approvalExecutionScope, previousApprovals);
+				}
+			};
+		}
+		const branchTuple = await this.checkpointer.getTuple({ configurable: { thread_id: branchChildThreadId } });
+		if (branchTuple != null) {
+			const childRunId = getSubagentRunId(getTupleMessages(branchTuple)) ?? currentChildRunId;
+			return this.prepareIdentity(execution, {
+				childRunId,
+				childThreadId: branchChildThreadId,
+				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 (!explicitResumeAttempt && (persistedChildRunId == null || persistedChildRunId === currentChildRunId)) {
+			const childRunId = persistedChildRunId ?? currentChildRunId;
+			return this.prepareIdentity(execution, {
+				childRunId,
+				childThreadId: baseChildThreadId,
+				approvalExecutionScope: getSubagentApprovalExecutionScope(childRunId, resumeAttemptId)
+			});
+		}
+		const sourceCheckpoints = await this.getLatestCheckpointSnapshot(baseChildThreadId);
+		if (sourceCheckpoints.length === 0) throw new Error(`Cannot fork subagent checkpoint thread "${baseChildThreadId}" without a checkpoint ID.`);
+		const childRunId = persistedChildRunId ?? currentChildRunId;
+		const identity = {
+			childRunId,
+			childThreadId: branchChildThreadId,
+			approvalExecutionScope: getSubagentApprovalExecutionScope(childRunId, resumeAttemptId)
+		};
+		const lease = this.executions.beginIdentityPreparation(execution, identity);
+		await this.prepareCheckpointFork(sourceCheckpoints, branchChildThreadId, lease);
+		return {
+			identity,
+			lease
+		};
+	}
+	prepareIdentity(execution, identity) {
+		return {
+			identity,
+			lease: this.executions.beginIdentityPreparation(execution, identity)
+		};
+	}
+	async prepareCheckpointFork(sources, targetThreadId, lease) {
+		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);
+		}
+	}
+	async checkpointThreadExists(threadId) {
+		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. */
+	async getLatestCheckpointSnapshot(threadId) {
+		if (this.checkpointer == null) return [];
+		const checkpointsByNamespace = /* @__PURE__ */ new Map();
+		for await (const tuple of this.checkpointer.list({ configurable: { thread_id: threadId } })) {
+			const checkpoint = getCheckpointReference(tuple);
+			const current = checkpoint == null ? void 0 : checkpointsByNamespace.get(checkpoint.checkpointNs);
+			if (checkpoint != null && (current == null || checkpoint.checkpointId.localeCompare(current.checkpointId) > 0)) checkpointsByNamespace.set(checkpoint.checkpointNs, checkpoint);
+		}
+		return [...checkpointsByNamespace.values()].sort((left, right) => left.checkpointNs.localeCompare(right.checkpointNs));
+	}
+	/** Copies exact checkpoint lineages, including pending task writes. */
+	async forkCheckpointSnapshot(sources, targetThreadId) {
+		if (this.checkpointer == null || sources.length === 0 || sources.every((source) => source.threadId === targetThreadId)) return;
+		for (const source of sources) {
+			const tuples = [];
+			const visited = /* @__PURE__ */ new Set();
+			let tuple = await this.checkpointer.getTuple({ configurable: {
+				thread_id: source.threadId,
+				checkpoint_ns: source.checkpointNs,
+				checkpoint_id: source.checkpointId
+			} });
+			if (tuple == null) throw new Error(`Subagent checkpoint "${source.checkpointId}" is unavailable.`);
+			for (;;) {
+				const reference = getCheckpointReference(tuple);
+				if (reference == null) throw new Error("Subagent checkpoint lineage contains an invalid tuple.");
+				if (reference.threadId !== source.threadId || reference.checkpointNs !== source.checkpointNs) throw new Error("Subagent checkpoint lineage escapes its source namespace.");
+				const lineageKey = JSON.stringify([
+					reference.threadId,
+					reference.checkpointNs,
+					reference.checkpointId
+				]);
+				if (visited.has(lineageKey)) throw new Error("Subagent checkpoint lineage contains a cycle.");
+				visited.add(lineageKey);
+				tuples.push(tuple);
+				if (tuple.parentConfig == null) break;
+				tuple = await this.checkpointer.getTuple(tuple.parentConfig);
+				if (tuple == null) throw new Error("Subagent checkpoint lineage is incomplete.");
+			}
+			tuples.reverse();
+			for (const lineageTuple of tuples) {
+				const checkpointNs = getConfigurableString(lineageTuple.config, "checkpoint_ns") ?? "";
+				const parentCheckpointId = getConfigurableString(lineageTuple.parentConfig, "checkpoint_id");
+				const storedConfig = await this.checkpointer.put({ configurable: {
+					thread_id: targetThreadId,
+					checkpoint_ns: checkpointNs,
+					...parentCheckpointId == null ? {} : { checkpoint_id: parentCheckpointId }
+				} }, copyCheckpoint(lineageTuple.checkpoint), lineageTuple.metadata ?? {
+					source: "fork",
+					step: -1,
+					parents: {}
+				}, lineageTuple.checkpoint.channel_versions);
+				const writesByTask = /* @__PURE__ */ new Map();
+				for (const [taskId, channel, value] of lineageTuple.pendingWrites ?? []) {
+					let writes = writesByTask.get(taskId);
+					if (writes == null) {
+						writes = [];
+						writesByTask.set(taskId, writes);
+					}
+					writes.push([channel, value]);
+				}
+				for (const [taskId, writes] of writesByTask) await this.checkpointer.putWrites(storedConfig, writes, taskId);
+			}
+		}
+	}
+	async createResumeManifest(records) {
+		if (this.checkpointer == null) return;
+		const executions = [];
+		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 configuredHookSessionId = activeRun?.invokeConfig?.configurable?.run_id;
+			const hookSessionId = typeof configuredHookSessionId === "string" && configuredHookSessionId.length > 0 ? configuredHookSessionId : this.parentRunId;
+			const approvalReplays = this.hookRegistry?.snapshotPendingToolApprovals(identity.approvalExecutionScope, identity.approvalExecutionScope) ?? [];
+			const descendant = activeRun?.pendingInterrupts.map((pendingInterrupt) => getSubagentResumeManifest(pendingInterrupt.value)).find((manifest) => manifest != null);
+			const graphState = activeRun?.graph.createSubagentResumeState(hookSessionId) ?? {
+				toolCallSteps: [],
+				toolSessions: [],
+				toolNodes: [],
+				eagerToolUsage: [],
+				eagerToolSuppressions: []
+			};
+			executions.push({
+				parentToolCallId,
+				childRunId: identity.childRunId,
+				...binding?.subagentType == null ? {} : { subagentType: binding.subagentType },
+				...binding?.configId == null ? {} : { configId: binding.configId },
+				approvalExecutionScope: identity.approvalExecutionScope,
+				checkpoints,
+				graphState,
+				approvalReplays,
+				...descendant == null ? {} : { descendant }
+			});
+		}
+		if (executions.length === 0) return;
+		return {
+			version: 1,
+			executions
+		};
+	}
+	getResumeManifest(parentToolCallIds, config) {
+		return this.createResumeManifest(this.executions.selectForResume({
+			parentToolCallIds,
+			config
+		}));
+	}
+	getChildCheckpointThreadIds() {
+		return this.executions.getCheckpointThreadIds((activeRun) => this.getGraphChildCheckpointThreadIds(activeRun.graph));
+	}
+	resetCheckpointThreadIds() {
+		this.executions.resetCheckpointThreadIds();
+	}
+	getGraphChildCheckpointThreadIds(graph) {
+		return graph.getChildCheckpointThreadIds?.() ?? [];
+	}
+	clearChildGraph(graph) {
+		this.executions.rememberCheckpointThread(...this.getGraphChildCheckpointThreadIds(graph));
+		graph.clearHeavyState();
+	}
+	clearHeavyState() {
+		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 = void 0;
+	}
+	async getResumeCheckpointMarker(resumeExecution, parentToolCallId) {
+		if (this.checkpointer == null) return;
+		let fallback;
+		for (const checkpoint of resumeExecution.checkpoints) {
+			const messages = getTupleMessages(await this.checkpointer.getTuple({ configurable: {
+				thread_id: checkpoint.threadId,
+				checkpoint_ns: checkpoint.checkpointNs,
+				checkpoint_id: checkpoint.checkpointId
+			} }));
+			const marker = getSubagentCheckpointMarker(messages, parentToolCallId);
+			if (marker?.settledOutput != null) return {
+				marker,
+				messages
+			};
+			if (marker != null && fallback == null) fallback = {
+				marker,
+				messages
+			};
+		}
+		return fallback;
+	}
+	async getSettledToolOutput(call, config) {
+		const parentToolCallId = call.id;
+		if (this.humanInTheLoop?.enabled !== true || this.checkpointer == null || parentToolCallId == null || parentToolCallId === "") return;
+		const parentConfigurable = config.configurable;
+		const threadId = parentConfigurable?.thread_id;
+		const execution = this.executions.open({
+			threadId: typeof threadId === "string" ? threadId : void 0,
+			parentToolCallId,
+			parentConfigurable
+		});
+		const { resumeExecution } = execution;
+		const inProcessSettledOutput = execution.settledOutput;
+		if (inProcessSettledOutput != null) {
+			const persistedSubagentType = getSubagentTypeFromArgs(inProcessSettledOutput.resolvedArgs);
+			const subagentType = persistedSubagentType ?? execution.binding?.subagentType ?? getSubagentType(call);
+			if (!isResumeExecutionCompatible(resumeExecution, subagentType, subagentType == null ? void 0 : this.configs.get(subagentType), persistedSubagentType != null)) return;
+			return deserializeToolOutput(inProcessSettledOutput);
+		}
+		let resumeCheckpoint;
+		if (resumeExecution != null) resumeCheckpoint = await this.getResumeCheckpointMarker(resumeExecution, parentToolCallId);
+		let marker = resumeCheckpoint?.marker;
+		let messages = resumeCheckpoint?.messages ?? [];
+		let persistedSubagentType = getSubagentTypeFromArgs(marker?.settledOutput?.resolvedArgs);
+		let subagentType = persistedSubagentType ?? resumeExecution?.subagentType ?? getSubagentType(call);
+		let executableConfig = subagentType == null ? void 0 : this.configs.get(subagentType);
+		if (!isResumeExecutionCompatible(resumeExecution, subagentType, executableConfig, persistedSubagentType != null)) {
+			this.executions.remove(execution);
+			return;
+		}
+		const { childThreadId } = await this.resolveChildExecutionIdentity(execution);
+		if (marker == null) {
+			messages = getCheckpointMessages((await this.checkpointer.getTuple({ configurable: { thread_id: childThreadId } }))?.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;
+			}
+		}
+		const configId = executableConfig?.configId;
+		if (!this.bindExecutionDefinition(execution, {
+			...subagentType == null ? {} : { subagentType },
+			...configId == null ? {} : { configId }
+		}, persistedSubagentType != null || resumeExecution?.subagentType != null ? "effective" : "provisional")) return;
+		const persistedHookSessionId = marker?.hookSessionId ?? getSubagentHookSessionId(messages);
+		const currentHookSessionId = parentConfigurable?.run_id;
+		if (persistedHookSessionId != null && typeof currentHookSessionId === "string" && currentHookSessionId.length > 0) this.hookRegistry?.copySession(persistedHookSessionId, currentHookSessionId);
+		return marker?.settledOutput == null ? void 0 : deserializeToolOutput(marker.settledOutput);
+	}
+	async persistSettledToolOutput(call, config, settled) {
+		const parentToolCallId = call.id;
+		const checkpointer = this.checkpointer;
+		if (this.humanInTheLoop?.enabled !== true || checkpointer == null || parentToolCallId == null || parentToolCallId === "") return;
+		const parentConfigurable = config.configurable;
+		const threadId = parentConfigurable?.thread_id;
+		const execution = this.executions.open({
+			threadId: typeof threadId === "string" ? threadId : void 0,
+			parentToolCallId,
+			parentConfigurable
+		});
+		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) ?? "No task description provided";
+		const subagentType = resolvedSubagentType ?? execution.binding?.subagentType ?? getSubagentType(call);
+		const executableConfig = subagentType == null ? void 0 : 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);
+		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 () => {
+				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);
+			});
+		} catch (error) {
+			if (error instanceof SubagentDefinitionBindingError || error instanceof SubagentInvocationBindingError || error instanceof SubagentSettlementBindingError) return;
+			throw error;
+		}
+	}
+	async persistChildCheckpointMarker(activeChildRun, parentToolCallId, settledOutput) {
+		if (this.humanInTheLoop?.enabled !== true || activeChildRun.workflow.updateState == null || activeChildRun.invokeConfig == null) return;
+		await activeChildRun.workflow.updateState(activeChildRun.invokeConfig, { messages: [createSubagentCheckpointMarkerMessage({
+			version: 1,
+			parentToolCallId,
+			lifecycleComplete: true,
+			hookSessionId: typeof activeChildRun.invokeConfig.configurable?.run_id === "string" ? activeChildRun.invokeConfig.configurable.run_id : this.parentRunId,
+			childRunId: activeChildRun.childRunId,
+			...settledOutput == null ? {} : { settledOutput }
+		})] }, activeChildRun.checkpointNodeId);
+	}
+	execute(params) {
+		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;
+		}
+	}
+	async executeOnce(params, execution, executableConfig) {
 		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
@@ -88,39 +788,51 @@ var SubagentExecutor = class {
 		* 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);
-		if (!config) return {
-			content: `Error: Unknown subagent type "${subagentType}". Available types: ${[...this.configs.keys()].join(", ")}`,
-			messages: []
-		};
-		if (this.maxDepth <= 0) return {
-			content: "Error: Maximum subagent nesting depth exceeded.",
+		const childSignal = this.composeChildSignal(childBreaker, params.signal);
+		const { parentToolCallId: executionSuffix } = execution.address;
+		const { resumeExecution } = execution;
+		if (!isResumeExecutionCompatible(resumeExecution, subagentType, executableConfig)) {
+			this.executions.remove(execution);
+			return {
+				content: SUBAGENT_CONFIG_CHANGED_MESSAGE,
+				messages: []
+			};
+		}
+		let identity;
+		try {
+			identity = await this.resolveChildExecutionIdentity(execution);
+			execution.assertUsable(childSignal);
+		} catch (error) {
+			if (error instanceof StreamLimitExceededError) throw error;
+			return {
+				content: SUBAGENT_RESOLUTION_ERROR_MESSAGE,
+				messages: []
+			};
+		}
+		const { childRunId, childThreadId, approvalExecutionScope } = identity;
+		if (!this.bindExecutionDefinition(execution, {
+			subagentType,
+			...executableConfig.configId == null ? {} : { configId: executableConfig.configId }
+		}, "effective")) return {
+			content: SUBAGENT_CONFIG_CHANGED_MESSAGE,
 			messages: []
 		};
-		const childAgentId = config.agentInputs.agentId || `${this.parentAgentId ?? "agent"}_sub_${nanoid(8)}`;
-		if (this.hookRegistry?.hasHookFor("SubagentStart", this.parentRunId) === true) {
-			const hookResult = await executeHooks({
-				registry: this.hookRegistry,
-				input: {
-					hook_event_name: "SubagentStart",
-					runId: this.parentRunId,
-					threadId,
-					parentAgentId: this.parentAgentId,
-					agentId: childAgentId,
-					agentType: subagentType,
-					inputs: [new HumanMessage(description)]
-				},
-				sessionId: this.parentRunId,
-				matchQuery: subagentType
-			}).catch(() => HOOK_FALLBACK);
-			/**
-			* `ask` is treated identically to `deny` in the subagent context:
-			* subagents are non-interactive, so there is no prompt path for `ask`.
-			* Both decisions block execution and return a "Blocked" tool result.
-			*/
-			if (hookResult.decision === "deny" || hookResult.decision === "ask") return {
-				content: `Blocked: ${hookResult.reason ?? "Blocked by hook"}`,
+		const completedChildResult = execution.completedResult;
+		if (completedChildResult != null) return completedChildResult;
+		let config;
+		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: SUBAGENT_RESOLUTION_ERROR_MESSAGE,
 				messages: []
 			};
 		}
@@ -136,18 +848,47 @@ var SubagentExecutor = class {
 		* recoverable "no tools" path for registry-but-no-handler configs.
 		*/
 		const hasToolExecuteHandler = parentRegistry?.getHandler("on_tool_execute") != null;
-		const childInputs = buildChildInputs(config, childAgentId, this.maxDepth, hasToolExecuteHandler);
-		const childRunId = `${this.parentRunId}_sub_${nanoid(8)}`;
-		const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
+		const childPlan = createChildGraphPlan({
+			config,
+			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 = {
+			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 memberRecursionLimit = (config.maxTurns ?? 25) * 3;
+		const recursionLimit = memberRecursionLimit * (childPlan.kind === "graph" ? childPlan.agents.length : 1);
 		const hostUsageSink = this.usageSink;
-		const childGraph = this.createChildGraph({
+		let subagentUsageSink;
+		if (hostUsageSink != null) subagentUsageSink = (event) => hostUsageSink({
+			...event,
+			runId: this.executionContext.rootRunId
+		});
+		const cachedChildRun = execution.activeRun;
+		const childGraphInput = {
 			runId: childRunId,
 			signal: childSignal,
-			agents: [childInputs],
+			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)
@@ -155,39 +896,52 @@ var SubagentExecutor = class {
 			* 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 ? void 0 : (event) => hostUsageSink({
-				...event,
-				runId: this.parentRunId
-			})
-		});
+			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;
 		if (forwardingEnabled) forwarding = this.createForwarderCallback({
 			parentRegistry,
 			subagentType,
+			subagentKind: childPlan.kind,
 			subagentAgentId: childAgentId,
 			childRunId,
-			parentToolCallId
-		});
-		const forwarder = forwarding?.handler;
-		if (forwarder) await this.emitSubagentUpdate(parentRegistry, {
-			childRunId,
-			subagentType,
-			subagentAgentId: childAgentId,
 			parentToolCallId,
-			phase: "start",
-			label: `Subagent "${subagentType}" started`
+			executionContext: childExecutionContext
 		});
+		const forwarder = forwarding?.handler;
+		let childAlreadyStarted = execution.started;
+		let childAlreadyCompleted = execution.completed;
 		let result;
+		let recoveredComplete = false;
+		let recoveredInProgress = false;
 		try {
-			const workflow = childGraph.createWorkflow();
+			const workflow = cachedChildRun?.workflow ?? childGraph.createWorkflow();
+			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`
@@ -217,54 +971,149 @@ var SubagentExecutor = class {
 			if (this.usageSink) callbackHandlers.push(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
 			}));
 			const callbacks = callbackHandlers;
 			/**
-			* Inherit the parent's host `configurable` — host-set fields
-			* (`requestBody`, `user`, `userMCPAuthMap`, etc.) AND the run-
-			* identity fields (`run_id`, `parent_run_id`, `thread_id`) all
-			* propagate. LangGraph's own runtime keys are excluded because the
-			* child graph creates its own scratchpad/checkpoint/abort plumbing.
-			*
-			* Run-identity propagation is intentional and matches the
-			* convention this executor itself already uses for `SubagentStart`
-			* / `SubagentStop` hooks (`sessionId: this.parentRunId`): the
-			* subagent runs under the parent's session scope, not its own.
-			* Forwarding `run_id` / `parent_run_id` / `thread_id` makes
-			* `ToolNode`'s hook lookups (`hasHookFor(eventName, runId)`),
-			* `ToolOutputReferenceRegistry` keying, and trace lineage all
-			* resolve to the parent's session for tools dispatched from the
-			* subagent — so `PreToolUse` / `PostToolUse` hooks the host
-			* registered against the parent's run fire for subagent tool
-			* calls too. "Same run" matches the user-perceptual mental model.
+			* Inherit the parent's host `configurable` while binding LangGraph's
+			* checkpoint identity to a stable child id derived from the durable
+			* parent thread and checkpoint fork. The parent thread id cannot be
+			* reused here: parent and child share one checkpointer when nested HITL
+			* is enabled, and root checkpoint namespaces are normalized by
+			* LangGraph, so a shared `thread_id` would collide with the parent.
 			*
-			* `thread_id` falls back to `childRunId` only when the parent
-			* didn't supply one (legacy behavior preserved for hosts that
-			* never set thread_id).
-			*
-			* NOTE: a future revision will likely make this configurable per
-			* spawn type — e.g. a background / async subagent that runs after
-			* the parent's run completes wants isolation, not inheritance.
-			* For now the inheritance path matches LibreChat's primary use
-			* case (synchronous subagents within a single user turn).
+			* `run_id` still propagates as the parent run id, which is the key used
+			* for session-scoped hook lookup. Child hook inputs therefore retain
+			* the parent policy scope while their `threadId` truthfully identifies
+			* the independently checkpointed child execution.
 			*/
 			const inheritedConfigurable = sanitizeChildConfigurable(params.parentConfigurable);
-			result = await workflow.invoke({ messages: [new HumanMessage(description)] }, {
-				recursionLimit: maxTurns * RECURSION_MULTIPLIER,
+			const { resumeAttemptId } = execution.address;
+			if (cachedChildRun == null && resumeExecution != null) childGraph.restoreSubagentResumeState(resumeExecution.graphState, currentHookSessionId);
+			const childConfigurable = { ...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,
 				signal: childSignal,
 				callbacks,
 				runName: `subagent:${subagentType}`,
-				configurable: {
-					thread_id: childRunId,
-					...inheritedConfigurable
+				configurable: childConfigurable
+			};
+			activeChildRun.invokeConfig = childInvokeConfig;
+			if (cachedChildRun == null && this.humanInTheLoop?.enabled === true) {
+				/** Rehydrate child-owned interrupt state when a host rebuilds Run
+				* around the same durable checkpointer after a process boundary. */
+				const persistedState = await workflow.getState(childInvokeConfig);
+				const checkpointMessages = getCheckpointMessages(persistedState.values?.messages);
+				const persistedHookSessionId = getSubagentHookSessionId(checkpointMessages);
+				if (persistedHookSessionId != null) this.hookRegistry?.copySession(persistedHookSessionId, currentHookSessionId);
+				const persistedInterrupts = getPersistedInterrupts(persistedState);
+				if (persistedInterrupts.length > 0) {
+					activeChildRun.pendingInterrupts = persistedInterrupts;
+					execution.markStarted();
+					childAlreadyStarted = true;
+				} else if (persistedState.next.length > 0) {
+					recoveredInProgress = true;
+					childAlreadyStarted = true;
+					execution.markStarted();
+				} else if (persistedState.next.length === 0) {
+					const persistedMessages = getPersistedMessages(persistedState);
+					if (persistedMessages != null) {
+						const marker = getSubagentCheckpointMarker(checkpointMessages, executionSuffix);
+						result = { messages: persistedMessages };
+						recoveredComplete = true;
+						childAlreadyStarted = true;
+						childAlreadyCompleted = marker?.lifecycleComplete === true;
+						execution.markStarted();
+					}
 				}
-			});
+			}
+			if (!recoveredComplete) {
+				const childResumeMap = getChildResumeMap(activeChildRun.pendingInterrupts, params.parentConfigurable);
+				if (activeChildRun.pendingInterrupts.length > 0 && childResumeMap == null) throw new GraphInterrupt(activeChildRun.pendingInterrupts);
+				let childInput;
+				if (childResumeMap != null) childInput = new Command({ resume: childResumeMap });
+				else if (recoveredInProgress) childInput = null;
+				else childInput = { messages: [new HumanMessage({
+					content: description,
+					additional_kwargs: {
+						[SUBAGENT_HOOK_SESSION_KEY]: currentHookSessionId,
+						[SUBAGENT_RUN_ID_KEY]: childRunId
+					}
+				})] };
+				if (!childAlreadyStarted && this.hookRegistry?.hasHookFor("SubagentStart", currentHookSessionId) === true) {
+					const hookResult = await executeHooks({
+						registry: this.hookRegistry,
+						input: {
+							hook_event_name: "SubagentStart",
+							runId: currentHookSessionId,
+							threadId,
+							parentAgentId: this.parentAgentId,
+							agentId: childAgentId,
+							agentType: subagentType,
+							inputs: [new HumanMessage(description)]
+						},
+						sessionId: currentHookSessionId,
+						matchQuery: subagentType
+					}).catch(() => HOOK_FALLBACK);
+					if (hookResult.decision === "deny" || hookResult.decision === "ask") {
+						this.clearChildGraph(childGraph);
+						execution.releaseActiveRun();
+						this.executions.remove(execution);
+						return {
+							content: `Blocked: ${hookResult.reason ?? "Blocked by hook"}`,
+							messages: []
+						};
+					}
+				}
+				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;
+				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, () => workflow.invoke(childInput, childInvokeConfig));
+				else childResult = await workflow.invoke(childInput, childInvokeConfig);
+				const childInterrupts = isInterrupted(childResult) ? childResult[INTERRUPT] : void 0;
+				if (childInterrupts != null && childInterrupts.length > 0) throw new GraphInterrupt(childInterrupts);
+				result = childResult;
+			}
 		} catch (error) {
+			if (isGraphInterrupt(error)) {
+				const activeChildRun = execution.activeRun;
+				if (activeChildRun != null) {
+					activeChildRun.pendingInterrupts = error.interrupts;
+					execution.markInterrupted();
+				}
+				const resumeManifest = activeChildRun == null || parentToolCallId == null ? void 0 : await this.createResumeManifest([execution]);
+				await forwarding?.drain();
+				throw new GraphInterrupt(addSubagentScope(error.interrupts, {
+					run_id: childRunId,
+					agent_id: childAgentId,
+					subagent_type: subagentType,
+					parent_tool_call_id: parentToolCallId
+				}, resumeManifest));
+			}
 			/** Aborted before any observational work below: parallel siblings — in
 			* this executor and, via the graph-scoped breaker, under other
 			* parallel agent nodes — stream on the composed child signal, and
@@ -279,14 +1128,17 @@ var SubagentExecutor = class {
 				await this.emitSubagentUpdate(parentRegistry, {
 					childRunId,
 					subagentType,
+					subagentKind: childPlan.kind,
 					subagentAgentId: childAgentId,
 					parentToolCallId,
+					executionContext: childExecutionContext,
 					phase: "error",
 					label: `Subagent "${subagentType}" errored: ${errorMessage}`,
 					data: { message: errorMessage }
 				});
 			}
-			childGraph.clearHeavyState();
+			this.clearChildGraph(childGraph);
+			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
@@ -300,8 +1152,9 @@ var SubagentExecutor = class {
 				messages: []
 			};
 		}
-		const filteredContent = filterSubagentResult(result.messages);
-		if (this.hookRegistry?.hasHookFor("SubagentStop", this.parentRunId) === true)
+		if (result == null) throw new Error("Subagent completed without producing graph state.");
+		const filteredContent = childPlan.kind === "graph" ? filterGraphSubagentResult(result, childPlan.resultAgentId) : filterSubagentResult(result.messages);
+		if (!childAlreadyCompleted && this.hookRegistry?.hasHookFor("SubagentStop", currentHookSessionId) === true)
  /**
 		* Awaited (not fire-and-forget) for deterministic test synchronization
 		* and consistency with PostCompact. The parent is already waiting on the
@@ -312,31 +1165,39 @@ var SubagentExecutor = class {
 			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(() => {});
-		if (forwarding) {
+		if (forwarding && !childAlreadyCompleted) {
 			await forwarding.drain();
 			await this.emitSubagentUpdate(parentRegistry, {
 				childRunId,
 				subagentType,
+				subagentKind: childPlan.kind,
 				subagentAgentId: childAgentId,
 				parentToolCallId,
+				executionContext: childExecutionContext,
 				phase: "stop",
 				label: `Subagent "${subagentType}" finished`
 			});
 		}
-		childGraph.clearHeavyState();
-		return {
+		if (!childAlreadyCompleted) {
+			const activeChildRun = execution.activeRun;
+			if (activeChildRun != null && parentToolCallId != null) await this.persistChildCheckpointMarker(activeChildRun, parentToolCallId);
+		}
+		this.clearChildGraph(childGraph);
+		const completedResult = {
 			content: filteredContent,
 			messages: result.messages
 		};
+		execution.markCompleted(completedResult);
+		return completedResult;
 	}
 	/**
 	* Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
@@ -346,21 +1207,23 @@ var SubagentExecutor = class {
 	async emitSubagentUpdate(parentRegistry, args) {
 		const handler = parentRegistry.getHandler("on_subagent_update");
 		if (!handler) return;
-		const event = {
-			runId: this.parentRunId,
+		await dispatchObservationalSubagentUpdate(handler, {
+			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: (/* @__PURE__ */ new Date()).toISOString()
-		};
-		try {
-			await handler.handle("on_subagent_update", event);
-		} catch {}
+		});
 	}
 	/**
 	* Builds a BaseCallbackHandler that intercepts the child graph's custom
@@ -375,35 +1238,40 @@ var SubagentExecutor = class {
 	*     cares about; host apps can extend by registering more phases).
 	*/
 	createForwarderCallback(args) {
-		const { parentRegistry, subagentType, subagentAgentId, childRunId, parentToolCallId } = args;
-		const parentRunId = this.parentRunId;
+		const { parentRegistry, subagentType, subagentKind, subagentAgentId, childRunId, parentToolCallId, executionContext } = args;
+		const immediateParentRunId = this.parentRunId;
 		const parentAgentId = this.parentAgentId;
-		const wrap = async (eventName, phase, data) => {
+		const wrap = async (eventName, phase, data, memberAgentId) => {
 			const handler = parentRegistry.getHandler("on_subagent_update");
-			if (!handler) return;
-			try {
-				const event = {
-					runId: parentRunId,
-					subagentRunId: childRunId,
-					subagentType,
-					subagentAgentId,
-					parentAgentId,
-					parentToolCallId,
-					phase,
-					data: sanitizeForwardedSubagentUpdateData(eventName, data),
-					label: summarizeEvent(eventName, data),
-					timestamp: (/* @__PURE__ */ new Date()).toISOString()
-				};
-				await handler.handle("on_subagent_update", event);
-			} catch {}
+			if (!handler) return true;
+			return dispatchObservationalSubagentUpdate(handler, {
+				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: (/* @__PURE__ */ new Date()).toISOString()
+			});
 		};
 		const queuedUpdates = [];
 		let drainPromise;
+		let queueOpen = true;
 		const enqueue = (update) => {
-			if (queuedUpdates.length >= MAX_PENDING_SUBAGENT_UPDATES) {
-				const dropIndex = queuedUpdates.findIndex((queued) => isDroppableSubagentUpdatePhase(queued.phase));
+			if (!queueOpen) return;
+			if (queuedUpdates.length >= MAX_QUEUED_SUBAGENT_UPDATES) {
+				const dropIndex = queuedUpdates.findIndex((queued) => isLowPrioritySubagentUpdatePhase(queued.phase));
 				if (dropIndex >= 0) queuedUpdates.splice(dropIndex, 1);
-				else if (isDroppableSubagentUpdatePhase(update.phase)) return;
+				else if (isLowPrioritySubagentUpdatePhase(update.phase)) return;
+				else queuedUpdates.shift();
 			}
 			queuedUpdates.push(update);
 		};
@@ -416,7 +1284,10 @@ var SubagentExecutor = class {
 				while (queuedUpdates.length > 0) {
 					const update = queuedUpdates.shift();
 					if (update == null) continue;
-					await wrap(update.eventName, update.phase, update.data);
+					if (!await wrap(update.eventName, update.phase, update.data, update.memberAgentId)) {
+						queueOpen = false;
+						queuedUpdates.length = 0;
+					}
 				}
 			})();
 			try {
@@ -426,15 +1297,17 @@ var SubagentExecutor = class {
 				if (queuedUpdates.length > 0) await drain();
 			}
 		};
-		const scheduleWrap = (eventName, phase, data) => {
+		const scheduleWrap = (eventName, phase, data, memberAgentId) => {
 			enqueue({
 				eventName,
 				phase,
-				data
+				data,
+				memberAgentId
 			});
 			drain();
 		};
-		const handler = BaseCallbackHandler.fromMethods({ ["handleCustomEvent"]: async (eventName, data) => {
+		const handler = BaseCallbackHandler.fromMethods({ ["handleCustomEvent"]: async (eventName, data, _runId, _tags, metadata) => {
+			const memberAgentId = asNonEmptyString(metadata?.agentId) ?? getEventAgentId(data);
 			if (eventName === "on_tool_execute") {
 				const toolHandler = parentRegistry.getHandler("on_tool_execute");
 				if (toolHandler) await toolHandler.handle("on_tool_execute", data);
@@ -442,27 +1315,27 @@ var SubagentExecutor = class {
 				* 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 === "on_run_step") {
-				scheduleWrap(eventName, "run_step", data);
+				scheduleWrap(eventName, "run_step", data, memberAgentId);
 				return;
 			}
 			if (eventName === "on_run_step_delta") {
-				scheduleWrap(eventName, "run_step_delta", data);
+				scheduleWrap(eventName, "run_step_delta", data, memberAgentId);
 				return;
 			}
 			if (eventName === "on_run_step_completed") {
-				scheduleWrap(eventName, "run_step_completed", data);
+				scheduleWrap(eventName, "run_step_completed", data, memberAgentId);
 				return;
 			}
 			if (eventName === "on_message_delta") {
-				scheduleWrap(eventName, "message_delta", data);
+				scheduleWrap(eventName, "message_delta", data, memberAgentId);
 				return;
 			}
 			if (eventName === "on_reasoning_delta") {
-				scheduleWrap(eventName, "reasoning_delta", data);
+				scheduleWrap(eventName, "reasoning_delta", data, memberAgentId);
 				return;
 			}
 		} });
@@ -496,7 +1369,8 @@ var SubagentExecutor = class {
 * `subagentUsageSink` on the child graph's input.
 */
 function createUsageCaptureHandler(args) {
-	const { sink, subagentType, subagentRunId, subagentAgentId, parentRunId, provider, fallbackModel } = args;
+	const { sink, subagentType, subagentKind, subagentRunId, subagentAgentId, parentRunId, executionContext, memberInputs } = args;
+	const defaultMember = memberInputs.size === 1 ? memberInputs.entries().next().value : void 0;
 	/**
 	* Per-call attribution keyed by LangChain callback runId. `model` joins
 	* `ls_model_name` (provider-reported) with `INVOKED_MODEL` (stamped by
@@ -511,16 +1385,21 @@ function createUsageCaptureHandler(args) {
 		handleChatModelStart: (_llm, _messages, runId, _parentRunId, _extraParams, _tags, metadata) => {
 			const callModel = asNonEmptyString(metadata?.ls_model_name) ?? asNonEmptyString(metadata?.["__invoked_model"]);
 			const callProvider = asNonEmptyString(metadata?.["__invoked_provider"]);
-			if (callModel != null || callProvider != null) callInfoByCallId.set(runId, {
+			const memberAgentId = asNonEmptyString(metadata?.agentId);
+			if (callModel != null || callProvider != null || memberAgentId != null) callInfoByCallId.set(runId, {
 				model: callModel,
-				provider: callProvider
+				provider: callProvider,
+				memberAgentId
 			});
 		},
 		handleLLMEnd: async (output, runId) => {
 			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 ? void 0 : memberInputs.get(memberAgentId)) ?? defaultMember?.[1];
+			const model = callInfo?.model ?? (memberInput == null ? void 0 : 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
@@ -545,9 +1424,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 {}
 				break;
@@ -568,6 +1452,11 @@ function createUsageCaptureHandler(args) {
 function asNonEmptyString(value) {
 	return typeof value === "string" && value !== "" ? value : void 0;
 }
+function getEventAgentId(data) {
+	if (data == null || typeof data !== "object") return;
+	const event = data;
+	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
@@ -578,12 +1467,50 @@ function extractConfiguredModel(agentInputs) {
 	if (typeof clientOptions?.model === "string" && clientOptions.model !== "") return clientOptions.model;
 	if (typeof clientOptions?.modelName === "string" && clientOptions.modelName !== "") return clientOptions.modelName;
 }
+function sanitizeResolverConfigurable(parentConfigurable) {
+	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;
+	return {
+		...requestBody == null ? {} : { requestBody },
+		...user == null ? {} : { user },
+		...userId == null ? {} : { user_id: userId }
+	};
+}
+function createResolveRequestContext(value) {
+	if (!isObjectLike(value)) return;
+	const source = value;
+	const conversationId = asNonEmptyString(source.conversationId);
+	const messageId = asNonEmptyString(source.messageId);
+	const parentMessageId = asNonEmptyString(source.parentMessageId);
+	if (conversationId == null && messageId == null && parentMessageId == null) return;
+	return {
+		...conversationId == null ? {} : { conversationId },
+		...messageId == null ? {} : { messageId },
+		...parentMessageId == null ? {} : { parentMessageId }
+	};
+}
+function createResolveUserContext(value) {
+	if (!isObjectLike(value)) return;
+	const source = value;
+	const id = asNonEmptyString(source.id);
+	const role = asNonEmptyString(source.role);
+	const tenantId = asNonEmptyString(source.tenantId);
+	if (id == null && role == null && tenantId == null) return;
+	return {
+		...id == null ? {} : { id },
+		...role == null ? {} : { role },
+		...tenantId == null ? {} : { tenantId }
+	};
+}
 function sanitizeChildConfigurable(parentConfigurable) {
 	if (parentConfigurable == null) return {};
 	return Object.fromEntries(Object.entries(parentConfigurable).filter(([key]) => !isLangGraphRuntimeConfigKey(key)));
 }
 function isLangGraphRuntimeConfigKey(key) {
-	return key.startsWith(LANGGRAPH_RUNTIME_CONFIG_PREFIX) || LANGGRAPH_CHECKPOINT_CONFIG_KEYS.has(key) || key === "lc_run_breaker_scope";
+	return key.startsWith(LANGGRAPH_RUNTIME_CONFIG_PREFIX) || LANGGRAPH_CHECKPOINT_CONFIG_KEYS.has(key) || key === "__librechat_subagent_resume_attempt" || key === "__librechat_subagent_resume_manifest" || key === "__librechat_subagent_parent_batch" || key === "__librechat_tool_approval_execution_scope" || key === "lc_run_breaker_scope";
 }
 function sanitizeForwardedSubagentUpdateData(eventName, data) {
 	if (eventName === "on_tool_execute") return sanitizeToolExecuteUpdateData(data);
@@ -593,7 +1520,7 @@ function sanitizeForwardedSubagentUpdateData(eventName, data) {
 	if (eventName === "on_message_delta") return sanitizeMessageDeltaUpdateData(data);
 	if (eventName === "on_reasoning_delta") return sanitizeReasoningDeltaUpdateData(data);
 }
-function isDroppableSubagentUpdatePhase(phase) {
+function isLowPrioritySubagentUpdatePhase(phase) {
 	return phase === "message_delta" || phase === "reasoning_delta" || phase === "run_step_delta";
 }
 function sanitizeToolExecuteUpdateData(data) {
@@ -762,6 +1689,16 @@ function summarizeEvent(eventName, data) {
 	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.
+*/
+function filterGraphSubagentResult(state, resultAgentId) {
+	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,
 * redacted_thinking, tool_result) are stripped. If the last AIMessage is
@@ -818,89 +1755,33 @@ function filterSubagentResult(messages) {
 	}
 	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.
-*/
-function resolveSubagentConfigs(configs, parentContext) {
-	const resolved = configs.map((config) => {
-		if (config.agentInputs != null) return config;
-		if (config.self !== true || parentContext._sourceInputs == null) return null;
-		return {
-			...config,
-			agentInputs: { ...parentContext._sourceInputs }
-		};
-	}).filter((c) => c != null);
-	const seenTypes = /* @__PURE__ */ new Set();
-	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);
-	}
-	return resolved;
-}
-/**
-* 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.
-*/
-function buildChildInputs(config, childAgentId, parentMaxDepth, keepToolDefinitions = false) {
-	const { agentInputs } = config;
-	const childInputs = {
-		...agentInputs,
-		agentId: childAgentId,
-		toolDefinitions: keepToolDefinitions ? agentInputs.toolDefinitions : void 0,
-		/**
-		* 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: void 0,
-		discoveredTools: void 0,
-		/**
-		* 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, which needs the parent's
-		* checkpointer — child graphs compile without one) would silently leak
-		* into the child and deterministically throw `No checkpointer set`. An
-		* EXPLICIT child config that lists its own `graphTools` is a deliberate
-		* host choice and keeps them (Codex #289 P2).
-		*/
-		graphTools: config.self === true ? void 0 : agentInputs.graphTools
-	};
-	if (config.allowNested === true) childInputs.maxSubagentDepth = Math.max(0, parentMaxDepth - 1);
-	else {
-		childInputs.subagentConfigs = void 0;
-		childInputs.maxSubagentDepth = void 0;
-	}
-	return childInputs;
-}
 function truncateErrorMessage(error) {
 	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 resolveAgentInputsWithSignal(resolve, signal) {
+	if (signal.aborted) return Promise.reject(getAbortReason(signal));
+	return new Promise((resolvePromise, rejectPromise) => {
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		const onAbort = () => {
+			cleanup();
+			rejectPromise(getAbortReason(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		Promise.resolve().then(resolve).then((agentInputs) => {
+			cleanup();
+			resolvePromise(agentInputs);
+		}, (error) => {
+			cleanup();
+			rejectPromise(error);
+		});
+	});
+}
+function getAbortReason(signal) {
+	return signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("Subagent resolution aborted.");
+}
 //#endregion
-export { SubagentExecutor, buildChildInputs, filterSubagentResult, resolveSubagentConfigs, summarizeEvent };
+export { DEFAULT_SUBAGENT_DESCRIPTION, SubagentExecutor, filterGraphSubagentResult, filterSubagentResult, summarizeEvent };
 
 //# sourceMappingURL=SubagentExecutor.mjs.map