@librechat/agents 3.1.68 → 3.1.71-dev.0

package/dist/esm/tools/ToolNode.mjs

@@ -1,6 +1,6 @@
-import { isBaseMessage, ToolMessage, isAIMessage } from '@langchain/core/messages';
+import { isBaseMessage, ToolMessage, HumanMessage, isAIMessage } from '@langchain/core/messages';
 import { isCommand, isGraphInterrupt, Command, Send, END } from '@langchain/langgraph';
-import { Constants, GraphEvents } from '../common/enum.mjs';
+import { Constants, CODE_EXECUTION_TOOLS, GraphEvents } from '../common/enum.mjs';
 import 'nanoid';
 import '../messages/core.mjs';
 import { calculateMaxToolResultChars, truncateToolResultContent } from '../utils/truncation.mjs';
@@ -9,6 +9,8 @@ import 'uuid';
 import { RunnableCallable } from '../utils/run.mjs';
 import 'ai-tokenizer';
 import 'zod-to-json-schema';
+import { executeHooks } from '../hooks/executeHooks.mjs';
+import { ToolOutputReferenceRegistry, annotateToolOutputWithReference, buildReferenceKey } from './toolOutputReferences.mjs';
 
 /**
  * Helper to check if a value is a Send object
@@ -16,6 +18,32 @@ import 'zod-to-json-schema';
 function isSend(value) {
     return value instanceof Send;
 }
+/** Merges code execution session context into the sessions map. */
+function updateCodeSession(sessions, sessionId, files) {
+    const newFiles = files ?? [];
+    const existingSession = sessions.get(Constants.EXECUTE_CODE);
+    const existingFiles = existingSession?.files ?? [];
+    if (newFiles.length > 0) {
+        const filesWithSession = newFiles.map((file) => ({
+            ...file,
+            session_id: sessionId,
+        }));
+        const newFileNames = new Set(filesWithSession.map((f) => f.name));
+        const filteredExisting = existingFiles.filter((f) => !newFileNames.has(f.name));
+        sessions.set(Constants.EXECUTE_CODE, {
+            session_id: sessionId,
+            files: [...filteredExisting, ...filesWithSession],
+            lastUpdated: Date.now(),
+        });
+    }
+    else {
+        sessions.set(Constants.EXECUTE_CODE, {
+            session_id: sessionId,
+            files: existingFiles,
+            lastUpdated: Date.now(),
+        });
+    }
+}
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 class ToolNode extends RunnableCallable {
     toolMap;
@@ -41,7 +69,29 @@ class ToolNode extends RunnableCallable {
     directToolNames;
     /** Maximum characters allowed in a single tool result before truncation. */
     maxToolResultChars;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, }) {
+    /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
+    hookRegistry;
+    /**
+     * Registry of tool outputs keyed by `tool<idx>turn<turn>`.
+     *
+     * Populated only when `toolOutputReferences.enabled` is true. The
+     * registry owns the run-scoped state (turn counter, last-seen runId,
+     * warn-once memo, stored outputs), so sharing a single instance
+     * across multiple ToolNodes in a run lets cross-agent `{{…}}`
+     * references resolve — which is why multi-agent graphs pass the
+     * *same* instance to every ToolNode they compile rather than each
+     * ToolNode building its own.
+     */
+    toolOutputRegistry;
+    /**
+     * Monotonic counter used to mint a unique scope id for anonymous
+     * batches (ones invoked without a `run_id` in
+     * `config.configurable`). Each such batch gets its own registry
+     * partition so concurrent anonymous invocations can't delete each
+     * other's in-flight state.
+     */
+    anonBatchCounter = 0;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, toolOutputReferences, toolOutputRegistry, }) {
         super({ name, tags, func: (input, config) => this.run(input, config) });
         this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
         this.toolCallStepIds = toolCallStepIds;
@@ -56,6 +106,38 @@ class ToolNode extends RunnableCallable {
         this.directToolNames = directToolNames;
         this.maxToolResultChars =
             maxToolResultChars ?? calculateMaxToolResultChars(maxContextTokens);
+        this.hookRegistry = hookRegistry;
+        /**
+         * Precedence: an explicitly passed `toolOutputRegistry` instance
+         * wins over a config object so a host (`Graph`) can share one
+         * registry across many ToolNodes. When only the config is
+         * provided (direct ToolNode usage), build a local registry so
+         * the feature still works without graph-level plumbing. Registry
+         * caps are intentionally decoupled from `maxToolResultChars`:
+         * the registry stores the raw untruncated output so a later
+         * `{{…}}` substitution pipes the full payload into the next
+         * tool, even when the LLM saw a truncated preview.
+         */
+        if (toolOutputRegistry != null) {
+            this.toolOutputRegistry = toolOutputRegistry;
+        }
+        else if (toolOutputReferences?.enabled === true) {
+            this.toolOutputRegistry = new ToolOutputReferenceRegistry({
+                maxOutputSize: toolOutputReferences.maxOutputSize,
+                maxTotalSize: toolOutputReferences.maxTotalSize,
+            });
+        }
+    }
+    /**
+     * Returns the run-scoped tool output registry, or `undefined` when
+     * the feature is disabled.
+     *
+     * @internal Exposed for test observation only. Host code should rely
+     * on `{{tool<i>turn<n>}}` substitution at tool-invocation time and
+     * not mutate the registry directly.
+     */
+    _unsafeGetToolOutputRegistry() {
+        return this.toolOutputRegistry;
     }
     /**
      * Returns cached programmatic tools, computing once on first access.
@@ -87,31 +169,89 @@ class ToolNode extends RunnableCallable {
         return new Map(this.toolUsageCount); // Return a copy
     }
     /**
-     * Runs a single tool call with error handling
+     * Runs a single tool call with error handling.
+     *
+     * `batchIndex` is the tool's position within the current ToolNode
+     * batch and, together with `this.currentTurn`, forms the key used to
+     * register the output for future `{{tool<idx>turn<turn>}}`
+     * substitutions. Omit when no registration should occur.
      */
-    async runTool(call, config) {
+    async runTool(call, config, batchContext = {}) {
+        const { batchIndex, turn, batchScopeId, resolvedArgsByCallId } = batchContext;
         const tool = this.toolMap.get(call.name);
+        const registry = this.toolOutputRegistry;
+        /**
+         * Precompute the reference key once per call — captured locally
+         * so concurrent `invoke()` calls on the same ToolNode cannot race
+         * on a shared turn field.
+         */
+        const refKey = registry != null && batchIndex != null && turn != null
+            ? buildReferenceKey(batchIndex, turn)
+            : undefined;
+        /**
+         * Hoisted outside the try so the catch branch can append
+         * `[unresolved refs: …]` to error messages — otherwise the LLM
+         * only sees a generic error when it references a bad key, losing
+         * the self-correction signal this feature is meant to provide.
+         */
+        let unresolvedRefs = [];
+        /**
+         * Use the caller-provided `batchScopeId` when threaded from
+         * `run()` (so anonymous batches get their own unique scope).
+         * Fall back to the config's `run_id` when runTool is invoked
+         * from a context that doesn't thread it — that still preserves
+         * the runId-based partitioning for named runs.
+         */
+        const runId = batchScopeId ?? config.configurable?.run_id;
         try {
             if (tool === undefined) {
                 throw new Error(`Tool "${call.name}" not found.`);
             }
-            const turn = this.toolUsageCount.get(call.name) ?? 0;
-            this.toolUsageCount.set(call.name, turn + 1);
+            /**
+             * `usageCount` is the per-tool-name invocation index that
+             * web-search and other tools observe via `invokeParams.turn`.
+             * It is intentionally distinct from the outer `turn` parameter
+             * (the batch turn used for ref keys); the latter is captured
+             * before the try block when constructing `refKey`.
+             */
+            const usageCount = this.toolUsageCount.get(call.name) ?? 0;
+            this.toolUsageCount.set(call.name, usageCount + 1);
             if (call.id != null && call.id !== '') {
-                this.toolCallTurns.set(call.id, turn);
+                this.toolCallTurns.set(call.id, usageCount);
+            }
+            let args = call.args;
+            if (registry != null) {
+                const { resolved, unresolved } = registry.resolve(runId, args);
+                args = resolved;
+                unresolvedRefs = unresolved;
+                /**
+                 * Expose the post-substitution args to downstream completion
+                 * events so audit logs / host-side `ON_RUN_STEP_COMPLETED`
+                 * handlers observe what actually ran, not the `{{…}}`
+                 * template. Only string/object args are worth recording.
+                 */
+                if (resolvedArgsByCallId != null &&
+                    call.id != null &&
+                    call.id !== '' &&
+                    resolved !== call.args &&
+                    typeof resolved === 'object') {
+                    resolvedArgsByCallId.set(call.id, resolved);
+                }
             }
-            const args = call.args;
             const stepId = this.toolCallStepIds?.get(call.id);
             // Build invoke params - LangChain extracts non-schema fields to config.toolCall
+            // `turn` here is the per-tool usage count (matches what tools have
+            // observed historically via config.toolCall.turn — e.g. web search).
             let invokeParams = {
                 ...call,
                 args,
                 type: 'tool_call',
                 stepId,
-                turn,
+                turn: usageCount,
             };
             // Inject runtime data for special tools (becomes available at config.toolCall)
-            if (call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
+            if (call.name === Constants.PROGRAMMATIC_TOOL_CALLING ||
+                call.name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING) {
                 const { toolMap, toolDefs } = this.getProgrammaticTools();
                 invokeParams = {
                     ...invokeParams,
@@ -134,8 +274,7 @@ class ToolNode extends RunnableCallable {
              * session_id is always injected when available (even without tracked files)
              * so the CodeExecutor can fall back to the /files endpoint for session continuity.
              */
-            if (call.name === Constants.EXECUTE_CODE ||
-                call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
+            if (CODE_EXECUTION_TOOLS.has(call.name)) {
                 const codeSession = this.sessions?.get(Constants.EXECUTE_CODE);
                 if (codeSession?.session_id != null && codeSession.session_id !== '') {
                     invokeParams = {
@@ -153,19 +292,72 @@ class ToolNode extends RunnableCallable {
                 }
             }
             const output = await tool.invoke(invokeParams, config);
-            if ((isBaseMessage(output) && output._getType() === 'tool') ||
-                isCommand(output)) {
+            if (isCommand(output)) {
                 return output;
             }
-            else {
-                const rawContent = typeof output === 'string' ? output : JSON.stringify(output);
-                return new ToolMessage({
-                    status: 'success',
-                    name: tool.name,
-                    content: truncateToolResultContent(rawContent, this.maxToolResultChars),
-                    tool_call_id: call.id,
-                });
+            if (isBaseMessage(output) && output._getType() === 'tool') {
+                const toolMsg = output;
+                const isError = toolMsg.status === 'error';
+                if (isError) {
+                    /**
+                     * Error ToolMessages bypass registration/annotation but must
+                     * still carry the unresolved-refs hint so the LLM can
+                     * self-correct when its reference key caused the failure.
+                     */
+                    if (unresolvedRefs.length > 0 &&
+                        typeof toolMsg.content === 'string') {
+                        toolMsg.content = this.applyOutputReference(runId, toolMsg.content, toolMsg.content, undefined, unresolvedRefs);
+                    }
+                    return toolMsg;
+                }
+                if (this.toolOutputRegistry != null || unresolvedRefs.length > 0) {
+                    if (typeof toolMsg.content === 'string') {
+                        const rawContent = toolMsg.content;
+                        const llmContent = truncateToolResultContent(rawContent, this.maxToolResultChars);
+                        toolMsg.content = this.applyOutputReference(runId, llmContent, rawContent, refKey, unresolvedRefs);
+                    }
+                    else {
+                        /**
+                         * Non-string content (multi-part content blocks — text +
+                         * image). Known limitation: we cannot register under a
+                         * reference key because there's no canonical serialized
+                         * form. Warn once per tool per run when the caller
+                         * intended to register.
+                         *
+                         * Still surface unresolved-ref warnings so the LLM gets
+                         * the self-correction signal that the string and error
+                         * paths already emit. Prepended as a leading text block
+                         * to keep the original content ordering intact.
+                         */
+                        if (unresolvedRefs.length > 0 && Array.isArray(toolMsg.content)) {
+                            const warningBlock = {
+                                type: 'text',
+                                text: `[unresolved refs: ${unresolvedRefs.join(', ')}]`,
+                            };
+                            toolMsg.content = [
+                                warningBlock,
+                                ...toolMsg.content,
+                            ];
+                        }
+                        if (refKey != null &&
+                            this.toolOutputRegistry.claimWarnOnce(runId, call.name)) {
+                            // eslint-disable-next-line no-console
+                            console.warn(`[ToolNode] Skipping tool output reference for "${call.name}": ` +
+                                'ToolMessage content is not a string (further occurrences for this tool in the same run are suppressed).');
+                        }
+                    }
+                }
+                return toolMsg;
             }
+            const rawContent = typeof output === 'string' ? output : JSON.stringify(output);
+            const truncated = truncateToolResultContent(rawContent, this.maxToolResultChars);
+            const content = this.applyOutputReference(runId, truncated, rawContent, refKey, unresolvedRefs);
+            return new ToolMessage({
+                status: 'success',
+                name: tool.name,
+                content,
+                tool_call_id: call.id,
+            });
         }
         catch (_e) {
             const e = _e;
@@ -208,14 +400,52 @@ class ToolNode extends RunnableCallable {
                     });
                 }
             }
+            let errorContent = `Error: ${e.message}\n Please fix your mistakes.`;
+            if (unresolvedRefs.length > 0) {
+                errorContent = this.applyOutputReference(runId, errorContent, errorContent, undefined, unresolvedRefs);
+            }
             return new ToolMessage({
                 status: 'error',
-                content: `Error: ${e.message}\n Please fix your mistakes.`,
+                content: errorContent,
                 name: call.name,
                 tool_call_id: call.id ?? '',
             });
         }
     }
+    /**
+     * Finalizes the LLM-visible content for a tool call and (when a
+     * `refKey` is provided) registers the full, raw output under that
+     * key.
+     *
+     * @param llmContent  The content string the LLM will see. This is
+     *   the already-truncated, post-hook view; the annotation is
+     *   applied on top of it.
+     * @param registryContent  The full, untruncated output to store in
+     *   the registry so `{{tool<i>turn<n>}}` substitutions deliver the
+     *   complete payload. Ignored when `refKey` is undefined.
+     * @param refKey  Precomputed `tool<i>turn<n>` key, or undefined when
+     *   the output is not to be registered (errors, disabled feature,
+     *   unavailable batch/turn).
+     * @param unresolved  Placeholder keys that did not resolve; appended
+     *   as `[unresolved refs: …]` so the LLM can self-correct.
+     *
+     * `refKey` is passed in (rather than built from `this.currentTurn`)
+     * so parallel `invoke()` calls on the same ToolNode cannot race on
+     * the shared turn field.
+     */
+    applyOutputReference(runId, llmContent, registryContent, refKey, unresolved) {
+        if (this.toolOutputRegistry != null && refKey != null) {
+            this.toolOutputRegistry.set(runId, refKey, registryContent);
+        }
+        /**
+         * `annotateToolOutputWithReference` handles both the ref-key and
+         * unresolved-refs cases together so JSON-object outputs stay
+         * parseable: unresolved refs land in an `_unresolved_refs` field
+         * instead of as a trailing text line that would break
+         * `JSON.parse` for downstream consumers.
+         */
+        return annotateToolOutputWithReference(llmContent, refKey, unresolved);
+    }
     /**
      * Builds code session context for injection into event-driven tool calls.
      * Mirrors the session injection logic in runTool() for direct execution.
@@ -244,7 +474,7 @@ class ToolNode extends RunnableCallable {
      * Extracts code execution session context from tool results and stores in Graph.sessions.
      * Mirrors the session storage logic in handleRunToolCompletions for direct execution.
      */
-    storeCodeSessionFromResults(results, requests) {
+    storeCodeSessionFromResults(results, requestMap) {
         if (!this.sessions) {
             return;
         }
@@ -253,38 +483,17 @@ class ToolNode extends RunnableCallable {
             if (result.status !== 'success' || result.artifact == null) {
                 continue;
             }
-            const request = requests.find((r) => r.id === result.toolCallId);
-            if (request?.name !== Constants.EXECUTE_CODE &&
-                request?.name !== Constants.PROGRAMMATIC_TOOL_CALLING) {
+            const request = requestMap.get(result.toolCallId);
+            if (!request?.name ||
+                (!CODE_EXECUTION_TOOLS.has(request.name) &&
+                    request.name !== Constants.SKILL_TOOL)) {
                 continue;
             }
             const artifact = result.artifact;
             if (artifact?.session_id == null || artifact.session_id === '') {
                 continue;
             }
-            const newFiles = artifact.files ?? [];
-            const existingSession = this.sessions.get(Constants.EXECUTE_CODE);
-            const existingFiles = existingSession?.files ?? [];
-            if (newFiles.length > 0) {
-                const filesWithSession = newFiles.map((file) => ({
-                    ...file,
-                    session_id: artifact.session_id,
-                }));
-                const newFileNames = new Set(filesWithSession.map((f) => f.name));
-                const filteredExisting = existingFiles.filter((f) => !newFileNames.has(f.name));
-                this.sessions.set(Constants.EXECUTE_CODE, {
-                    session_id: artifact.session_id,
-                    files: [...filteredExisting, ...filesWithSession],
-                    lastUpdated: Date.now(),
-                });
-            }
-            else {
-                this.sessions.set(Constants.EXECUTE_CODE, {
-                    session_id: artifact.session_id,
-                    files: existingFiles,
-                    lastUpdated: Date.now(),
-                });
-            }
+            updateCodeSession(this.sessions, artifact.session_id, artifact.files);
         }
     }
     /**
@@ -295,8 +504,12 @@ class ToolNode extends RunnableCallable {
      * By handling completions here in graph context (rather than in the
      * stream consumer via ToolEndHandler), the race between the stream
      * consumer and graph execution is eliminated.
+     *
+     * @param resolvedArgsByCallId  Per-batch resolved-args sink populated
+     *   by `runTool`. Threaded as a local map (instead of instance state)
+     *   so concurrent batches cannot read each other's entries.
      */
-    handleRunToolCompletions(calls, outputs, config) {
+    handleRunToolCompletions(calls, outputs, config, resolvedArgsByCallId) {
         for (let i = 0; i < calls.length; i++) {
             const call = calls[i];
             const output = outputs[i];
@@ -311,35 +524,10 @@ class ToolNode extends RunnableCallable {
             if (toolMessage.status === 'error' && this.errorHandler != null) {
                 continue;
             }
-            // Store code session context from tool results
-            if (this.sessions &&
-                (call.name === Constants.EXECUTE_CODE ||
-                    call.name === Constants.PROGRAMMATIC_TOOL_CALLING)) {
+            if (this.sessions && CODE_EXECUTION_TOOLS.has(call.name)) {
                 const artifact = toolMessage.artifact;
                 if (artifact?.session_id != null && artifact.session_id !== '') {
-                    const newFiles = artifact.files ?? [];
-                    const existingSession = this.sessions.get(Constants.EXECUTE_CODE);
-                    const existingFiles = existingSession?.files ?? [];
-                    if (newFiles.length > 0) {
-                        const filesWithSession = newFiles.map((file) => ({
-                            ...file,
-                            session_id: artifact.session_id,
-                        }));
-                        const newFileNames = new Set(filesWithSession.map((f) => f.name));
-                        const filteredExisting = existingFiles.filter((f) => !newFileNames.has(f.name));
-                        this.sessions.set(Constants.EXECUTE_CODE, {
-                            session_id: artifact.session_id,
-                            files: [...filteredExisting, ...filesWithSession],
-                            lastUpdated: Date.now(),
-                        });
-                    }
-                    else {
-                        this.sessions.set(Constants.EXECUTE_CODE, {
-                            session_id: artifact.session_id,
-                            files: existingFiles,
-                            lastUpdated: Date.now(),
-                        });
-                    }
+                    updateCodeSession(this.sessions, artifact.session_id, artifact.files);
                 }
             }
             // Dispatch ON_RUN_STEP_COMPLETED via custom event (same path as dispatchToolEvents)
@@ -350,10 +538,17 @@ class ToolNode extends RunnableCallable {
             const contentString = typeof toolMessage.content === 'string'
                 ? toolMessage.content
                 : JSON.stringify(toolMessage.content);
+            /**
+             * Prefer the post-substitution args when a `{{…}}` placeholder
+             * was resolved in `runTool`. This keeps
+             * `ON_RUN_STEP_COMPLETED.tool_call.args` consistent with what
+             * the tool actually received rather than leaking the template.
+             */
+            const effectiveArgs = resolvedArgsByCallId?.get(toolCallId) ?? call.args;
             const tool_call = {
-                args: typeof call.args === 'string'
-                    ? call.args
-                    : JSON.stringify(call.args ?? {}),
+                args: typeof effectiveArgs === 'string'
+                    ? effectiveArgs
+                    : JSON.stringify(effectiveArgs ?? {}),
                 name: call.name,
                 id: toolCallId,
                 output: contentString,
@@ -372,113 +567,415 @@ class ToolNode extends RunnableCallable {
     /**
      * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
      * Core logic for event-driven execution, separated from output shaping.
+     *
+     * Hook lifecycle (when `hookRegistry` is set):
+     * 1. **PreToolUse** fires per call in parallel before dispatch. Denied
+     *    calls produce error ToolMessages and fire **PermissionDenied**;
+     *    surviving calls proceed with optional `updatedInput`.
+     * 2. Surviving calls are dispatched to the host via `ON_TOOL_EXECUTE`.
+     * 3. **PostToolUse** / **PostToolUseFailure** fire per result. Post hooks
+     *    can replace tool output via `updatedOutput`.
+     * 4. Injected messages from results are collected and returned alongside
+     *    ToolMessages (appended AFTER to respect provider ordering).
      */
-    async dispatchToolEvents(toolCalls, config) {
-        const requests = toolCalls.map((call) => {
-            const turn = this.toolUsageCount.get(call.name) ?? 0;
-            this.toolUsageCount.set(call.name, turn + 1);
-            const request = {
-                id: call.id,
-                name: call.name,
-                args: call.args,
-                stepId: this.toolCallStepIds?.get(call.id),
-                turn,
-            };
-            if (call.name === Constants.EXECUTE_CODE ||
-                call.name === Constants.PROGRAMMATIC_TOOL_CALLING) {
-                request.codeSessionContext = this.getCodeSessionContext();
+    async dispatchToolEvents(toolCalls, config, batchContext = {}) {
+        const { batchIndices, turn, batchScopeId, preResolvedArgs, preBatchSnapshot, } = batchContext;
+        const runId = config.configurable?.run_id ?? '';
+        /**
+         * Registry-facing scope id — prefers the caller-threaded
+         * `batchScopeId` so anonymous batches target their own unique
+         * bucket and don't step on concurrent anonymous invocations.
+         * Hooks and event payloads keep using the empty-string coerced
+         * `runId` for backward compat.
+         */
+        const registryRunId = batchScopeId ?? config.configurable?.run_id;
+        const threadId = config.configurable?.thread_id;
+        const registry = this.toolOutputRegistry;
+        const unresolvedByCallId = new Map();
+        const preToolCalls = toolCalls.map((call, i) => {
+            const originalArgs = call.args;
+            let resolvedArgs = originalArgs;
+            /**
+             * When the caller provided a pre-resolved map (the mixed
+             * direct+event path snapshots event args synchronously before
+             * awaiting directs so they can't accidentally resolve
+             * same-turn direct outputs), use those entries verbatim instead
+             * of re-resolving against a registry that may have changed
+             * since the batch started.
+             */
+            const pre = call.id != null ? preResolvedArgs?.get(call.id) : undefined;
+            if (pre != null) {
+                resolvedArgs = pre.resolved;
+                if (pre.unresolved.length > 0 && call.id != null) {
+                    unresolvedByCallId.set(call.id, pre.unresolved);
+                }
             }
-            return request;
-        });
-        const results = await new Promise((resolve, reject) => {
-            const request = {
-                toolCalls: requests,
-                userId: config.configurable?.user_id,
-                agentId: this.agentId,
-                configurable: config.configurable,
-                metadata: config.metadata,
-                resolve,
-                reject,
+            else if (registry != null) {
+                const { resolved, unresolved } = registry.resolve(registryRunId, originalArgs);
+                resolvedArgs = resolved;
+                if (unresolved.length > 0 && call.id != null) {
+                    unresolvedByCallId.set(call.id, unresolved);
+                }
+            }
+            return {
+                call,
+                stepId: this.toolCallStepIds?.get(call.id) ?? '',
+                args: resolvedArgs,
+                batchIndex: batchIndices?.[i],
             };
-            safeDispatchCustomEvent(GraphEvents.ON_TOOL_EXECUTE, request, config);
         });
-        this.storeCodeSessionFromResults(results, requests);
-        return results.map((result) => {
-            const request = requests.find((r) => r.id === result.toolCallId);
-            const toolName = request?.name ?? 'unknown';
-            const stepId = this.toolCallStepIds?.get(result.toolCallId) ?? '';
-            if (!stepId) {
-                // eslint-disable-next-line no-console
-                console.warn(`[ToolNode] toolCallStepIds missing entry for toolCallId=${result.toolCallId} (tool=${toolName}). ` +
-                    'This indicates a race between the stream consumer and graph execution. ' +
-                    `Map size: ${this.toolCallStepIds?.size ?? 0}`);
-            }
-            let toolMessage;
-            let contentString;
-            if (result.status === 'error') {
-                contentString = `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`;
-                toolMessage = new ToolMessage({
-                    status: 'error',
-                    content: contentString,
-                    name: toolName,
-                    tool_call_id: result.toolCallId,
-                });
+        const messageByCallId = new Map();
+        const approvedEntries = [];
+        const HOOK_FALLBACK = Object.freeze({
+            additionalContexts: [],
+            errors: [],
+        });
+        if (this.hookRegistry?.hasHookFor('PreToolUse', runId) === true) {
+            const preResults = await Promise.all(preToolCalls.map((entry) => executeHooks({
+                registry: this.hookRegistry,
+                input: {
+                    hook_event_name: 'PreToolUse',
+                    runId,
+                    threadId,
+                    agentId: this.agentId,
+                    toolName: entry.call.name,
+                    toolInput: entry.args,
+                    toolUseId: entry.call.id,
+                    stepId: entry.stepId,
+                    turn: this.toolUsageCount.get(entry.call.name) ?? 0,
+                },
+                sessionId: runId,
+                matchQuery: entry.call.name,
+            }).catch(() => HOOK_FALLBACK)));
+            for (let i = 0; i < preToolCalls.length; i++) {
+                const hookResult = preResults[i];
+                const entry = preToolCalls[i];
+                const isDenied = hookResult.decision === 'deny' || hookResult.decision === 'ask';
+                if (isDenied) {
+                    const reason = hookResult.reason ?? 'Blocked by hook';
+                    const contentString = `Blocked: ${reason}`;
+                    messageByCallId.set(entry.call.id, new ToolMessage({
+                        status: 'error',
+                        content: contentString,
+                        name: entry.call.name,
+                        tool_call_id: entry.call.id,
+                    }));
+                    this.dispatchStepCompleted(entry.call.id, entry.call.name, entry.args, contentString, config);
+                    if (this.hookRegistry.hasHookFor('PermissionDenied', runId)) {
+                        executeHooks({
+                            registry: this.hookRegistry,
+                            input: {
+                                hook_event_name: 'PermissionDenied',
+                                runId,
+                                threadId,
+                                agentId: this.agentId,
+                                toolName: entry.call.name,
+                                toolInput: entry.args,
+                                toolUseId: entry.call.id,
+                                reason,
+                            },
+                            sessionId: runId,
+                            matchQuery: entry.call.name,
+                        }).catch(() => {
+                            /* PermissionDenied is observational — swallow errors */
+                        });
+                    }
+                    continue;
+                }
+                if (hookResult.updatedInput != null) {
+                    /**
+                     * Re-resolve after PreToolUse replaces the input: a hook may
+                     * introduce new `{{tool<i>turn<n>}}` placeholders (e.g., by
+                     * copying user-supplied text) that the pre-hook pass never
+                     * saw. Re-running the resolver on the hook-rewritten args
+                     * keeps substitution and the unresolved-refs record in sync
+                     * with what the tool will actually receive.
+                     */
+                    if (registry != null) {
+                        /**
+                         * Mixed direct+event batches must use the pre-batch
+                         * snapshot so a hook-introduced placeholder cannot
+                         * accidentally resolve to a same-turn direct output that
+                         * has just registered. Pure event batches don't have a
+                         * snapshot and resolve against the live registry — safe
+                         * because no event-side registrations have happened yet.
+                         */
+                        const view = preBatchSnapshot ?? {
+                            resolve: (args) => registry.resolve(registryRunId, args),
+                        };
+                        const { resolved, unresolved } = view.resolve(hookResult.updatedInput);
+                        entry.args = resolved;
+                        if (entry.call.id != null) {
+                            if (unresolved.length > 0) {
+                                unresolvedByCallId.set(entry.call.id, unresolved);
+                            }
+                            else {
+                                unresolvedByCallId.delete(entry.call.id);
+                            }
+                        }
+                    }
+                    else {
+                        entry.args = hookResult.updatedInput;
+                    }
+                }
+                approvedEntries.push(entry);
             }
-            else {
-                const rawContent = typeof result.content === 'string'
-                    ? result.content
-                    : JSON.stringify(result.content);
-                contentString = truncateToolResultContent(rawContent, this.maxToolResultChars);
-                toolMessage = new ToolMessage({
-                    status: 'success',
-                    name: toolName,
-                    content: contentString,
-                    artifact: result.artifact,
-                    tool_call_id: result.toolCallId,
-                });
+        }
+        else {
+            approvedEntries.push(...preToolCalls);
+        }
+        const injected = [];
+        const batchIndexByCallId = new Map();
+        if (approvedEntries.length > 0) {
+            const requests = approvedEntries.map((entry) => {
+                const turn = this.toolUsageCount.get(entry.call.name) ?? 0;
+                this.toolUsageCount.set(entry.call.name, turn + 1);
+                if (entry.batchIndex != null && entry.call.id != null) {
+                    batchIndexByCallId.set(entry.call.id, entry.batchIndex);
+                }
+                const request = {
+                    id: entry.call.id,
+                    name: entry.call.name,
+                    args: entry.args,
+                    stepId: entry.stepId,
+                    turn,
+                };
+                if (CODE_EXECUTION_TOOLS.has(entry.call.name) ||
+                    entry.call.name === Constants.SKILL_TOOL) {
+                    request.codeSessionContext = this.getCodeSessionContext();
+                }
+                return request;
+            });
+            const requestMap = new Map(requests.map((r) => [r.id, r]));
+            const results = await new Promise((resolve, reject) => {
+                const batchRequest = {
+                    toolCalls: requests,
+                    userId: config.configurable?.user_id,
+                    agentId: this.agentId,
+                    configurable: config.configurable,
+                    metadata: config.metadata,
+                    resolve,
+                    reject,
+                };
+                safeDispatchCustomEvent(GraphEvents.ON_TOOL_EXECUTE, batchRequest, config);
+            });
+            this.storeCodeSessionFromResults(results, requestMap);
+            const hasPostHook = this.hookRegistry?.hasHookFor('PostToolUse', runId) === true;
+            const hasFailureHook = this.hookRegistry?.hasHookFor('PostToolUseFailure', runId) === true;
+            for (const result of results) {
+                if (result.injectedMessages && result.injectedMessages.length > 0) {
+                    try {
+                        injected.push(...this.convertInjectedMessages(result.injectedMessages));
+                    }
+                    catch (e) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[ToolNode] Failed to convert injectedMessages for toolCallId=${result.toolCallId}:`, e instanceof Error ? e.message : e);
+                    }
+                }
+                const request = requestMap.get(result.toolCallId);
+                const toolName = request?.name ?? 'unknown';
+                let contentString;
+                let toolMessage;
+                if (result.status === 'error') {
+                    contentString = `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`;
+                    /**
+                     * Error results bypass registration/annotation but must still
+                     * carry the unresolved-refs hint so the LLM can self-correct
+                     * when its reference key caused the failure.
+                     */
+                    const unresolved = unresolvedByCallId.get(result.toolCallId) ?? [];
+                    if (unresolved.length > 0) {
+                        contentString = this.applyOutputReference(registryRunId, contentString, contentString, undefined, unresolved);
+                    }
+                    toolMessage = new ToolMessage({
+                        status: 'error',
+                        content: contentString,
+                        name: toolName,
+                        tool_call_id: result.toolCallId,
+                    });
+                    if (hasFailureHook) {
+                        await executeHooks({
+                            registry: this.hookRegistry,
+                            input: {
+                                hook_event_name: 'PostToolUseFailure',
+                                runId,
+                                threadId,
+                                agentId: this.agentId,
+                                toolName,
+                                toolInput: request?.args ?? {},
+                                toolUseId: result.toolCallId,
+                                error: result.errorMessage ?? 'Unknown error',
+                                stepId: request?.stepId,
+                                turn: request?.turn,
+                            },
+                            sessionId: runId,
+                            matchQuery: toolName,
+                        }).catch(() => {
+                            /* PostToolUseFailure is observational — swallow errors */
+                        });
+                    }
+                }
+                else {
+                    let registryRaw = typeof result.content === 'string'
+                        ? result.content
+                        : JSON.stringify(result.content);
+                    contentString = truncateToolResultContent(registryRaw, this.maxToolResultChars);
+                    if (hasPostHook) {
+                        const hookResult = await executeHooks({
+                            registry: this.hookRegistry,
+                            input: {
+                                hook_event_name: 'PostToolUse',
+                                runId,
+                                threadId,
+                                agentId: this.agentId,
+                                toolName,
+                                toolInput: request?.args ?? {},
+                                toolOutput: result.content,
+                                toolUseId: result.toolCallId,
+                                stepId: request?.stepId,
+                                turn: request?.turn,
+                            },
+                            sessionId: runId,
+                            matchQuery: toolName,
+                        }).catch(() => undefined);
+                        if (hookResult?.updatedOutput != null) {
+                            const replaced = typeof hookResult.updatedOutput === 'string'
+                                ? hookResult.updatedOutput
+                                : JSON.stringify(hookResult.updatedOutput);
+                            registryRaw = replaced;
+                            contentString = truncateToolResultContent(replaced, this.maxToolResultChars);
+                        }
+                    }
+                    const batchIndex = batchIndexByCallId.get(result.toolCallId);
+                    const unresolved = unresolvedByCallId.get(result.toolCallId) ?? [];
+                    const refKey = this.toolOutputRegistry != null &&
+                        batchIndex != null &&
+                        turn != null
+                        ? buildReferenceKey(batchIndex, turn)
+                        : undefined;
+                    contentString = this.applyOutputReference(registryRunId, contentString, registryRaw, refKey, unresolved);
+                    toolMessage = new ToolMessage({
+                        status: 'success',
+                        name: toolName,
+                        content: contentString,
+                        artifact: result.artifact,
+                        tool_call_id: result.toolCallId,
+                    });
+                }
+                this.dispatchStepCompleted(result.toolCallId, toolName, request?.args ?? {}, contentString, config, request?.turn);
+                messageByCallId.set(result.toolCallId, toolMessage);
             }
-            const tool_call = {
-                args: typeof request?.args === 'string'
-                    ? request.args
-                    : JSON.stringify(request?.args ?? {}),
-                name: toolName,
-                id: result.toolCallId,
-                output: contentString,
-                progress: 1,
-            };
-            const runStepCompletedData = {
-                result: {
-                    id: stepId,
-                    index: request?.turn ?? 0,
-                    type: 'tool_call',
-                    tool_call,
+        }
+        const toolMessages = toolCalls
+            .map((call) => messageByCallId.get(call.id))
+            .filter((m) => m != null);
+        return { toolMessages, injected };
+    }
+    dispatchStepCompleted(toolCallId, toolName, args, output, config, turn) {
+        const stepId = this.toolCallStepIds?.get(toolCallId) ?? '';
+        if (!stepId) {
+            // eslint-disable-next-line no-console
+            console.warn(`[ToolNode] toolCallStepIds missing entry for toolCallId=${toolCallId} (tool=${toolName}). ` +
+                'This indicates a race between the stream consumer and graph execution. ' +
+                `Map size: ${this.toolCallStepIds?.size ?? 0}`);
+        }
+        safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, {
+            result: {
+                id: stepId,
+                index: turn ?? this.toolUsageCount.get(toolName) ?? 0,
+                type: 'tool_call',
+                tool_call: {
+                    args: JSON.stringify(args),
+                    name: toolName,
+                    id: toolCallId,
+                    output,
+                    progress: 1,
                 },
+            },
+        }, config);
+    }
+    /**
+     * Converts InjectedMessage instances to LangChain HumanMessage objects.
+     * Both 'user' and 'system' roles become HumanMessage to avoid provider
+     * rejections (Anthropic/Google reject non-leading SystemMessages).
+     * The original role is preserved in additional_kwargs for downstream consumers.
+     */
+    convertInjectedMessages(messages) {
+        const converted = [];
+        for (const msg of messages) {
+            const additional_kwargs = {
+                role: msg.role,
             };
-            safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_COMPLETED, runStepCompletedData, config);
-            return toolMessage;
-        });
+            if (msg.isMeta != null)
+                additional_kwargs.isMeta = msg.isMeta;
+            if (msg.source != null)
+                additional_kwargs.source = msg.source;
+            if (msg.skillName != null)
+                additional_kwargs.skillName = msg.skillName;
+            converted.push(new HumanMessage({ content: msg.content, additional_kwargs }));
+        }
+        return converted;
     }
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
-     * Used in event-driven mode where the host handles actual tool execution.
+     * Injected messages are placed AFTER ToolMessages to respect provider
+     * message ordering (AIMessage tool_calls must be immediately followed
+     * by their ToolMessage results).
+     *
+     * `batchIndices` mirrors `toolCalls` and carries each call's position
+     * within the parent batch. `turn` is the per-`run()` batch index
+     * captured locally by the caller. Both are threaded so concurrent
+     * invocations cannot race on shared mutable state.
      */
     async executeViaEvent(toolCalls, config, 
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    input) {
-        const outputs = await this.dispatchToolEvents(toolCalls, config);
+    input, batchContext = {}) {
+        const { toolMessages, injected } = await this.dispatchToolEvents(toolCalls, config, batchContext);
+        const outputs = [...toolMessages, ...injected];
         return (Array.isArray(input) ? outputs : { messages: outputs });
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async run(input, config) {
         this.toolCallTurns.clear();
+        /**
+         * Per-batch local map for resolved (post-substitution) args.
+         * Lives on the stack so concurrent `run()` calls on the same
+         * ToolNode cannot read or wipe each other's entries.
+         */
+        const resolvedArgsByCallId = new Map();
+        /**
+         * Claim this batch's turn synchronously from the registry (or
+         * fall back to 0 when the feature is disabled). The registry is
+         * partitioned by scope id so overlapping batches cannot
+         * overwrite each other's state even under a shared registry.
+         *
+         * For anonymous callers (no `run_id` in config), mint a unique
+         * per-batch scope id so two concurrent anonymous invocations
+         * don't target the same bucket. The scope is threaded down to
+         * every subsequent registry call on this batch.
+         */
+        const incomingRunId = config.configurable?.run_id;
+        const batchScopeId = incomingRunId ?? `\0anon-${this.anonBatchCounter++}`;
+        const turn = this.toolOutputRegistry?.nextTurn(batchScopeId) ?? 0;
         let outputs;
         if (this.isSendInput(input)) {
             const isDirectTool = this.directToolNames?.has(input.lg_tool_call.name);
             if (this.eventDrivenMode && isDirectTool !== true) {
-                return this.executeViaEvent([input.lg_tool_call], config, input);
+                return this.executeViaEvent([input.lg_tool_call], config, input, {
+                    batchIndices: [0],
+                    turn,
+                    batchScopeId,
+                });
             }
-            outputs = [await this.runTool(input.lg_tool_call, config)];
-            this.handleRunToolCompletions([input.lg_tool_call], outputs, config);
+            outputs = [
+                await this.runTool(input.lg_tool_call, config, {
+                    batchIndex: 0,
+                    turn,
+                    batchScopeId,
+                    resolvedArgsByCallId,
+                }),
+            ];
+            this.handleRunToolCompletions([input.lg_tool_call], outputs, config, resolvedArgsByCallId);
         }
         else {
             let messages;
@@ -523,25 +1020,100 @@ class ToolNode extends RunnableCallable {
                         false));
             }) ?? [];
             if (this.eventDrivenMode && filteredCalls.length > 0) {
+                const filteredIndices = filteredCalls.map((_, idx) => idx);
                 if (!this.directToolNames || this.directToolNames.size === 0) {
-                    return this.executeViaEvent(filteredCalls, config, input);
+                    return this.executeViaEvent(filteredCalls, config, input, {
+                        batchIndices: filteredIndices,
+                        turn,
+                        batchScopeId,
+                    });
+                }
+                const directEntries = [];
+                const eventEntries = [];
+                for (let i = 0; i < filteredCalls.length; i++) {
+                    const call = filteredCalls[i];
+                    const entry = { call, batchIndex: i };
+                    if (this.directToolNames.has(call.name)) {
+                        directEntries.push(entry);
+                    }
+                    else {
+                        eventEntries.push(entry);
+                    }
+                }
+                const directCalls = directEntries.map((e) => e.call);
+                const directIndices = directEntries.map((e) => e.batchIndex);
+                const eventCalls = eventEntries.map((e) => e.call);
+                const eventIndices = eventEntries.map((e) => e.batchIndex);
+                /**
+                 * Snapshot the event calls' args against the *pre-batch*
+                 * registry state synchronously, before any await runs. The
+                 * directs are then awaited first (preserving fail-fast
+                 * semantics — a thrown error in a direct tool, e.g. with
+                 * `handleToolErrors=false` or a `GraphInterrupt`, aborts
+                 * before we dispatch any event-driven tools to the host).
+                 * Because the event args were captured pre-await, they stay
+                 * isolated from same-turn direct outputs that register
+                 * during the await.
+                 */
+                const preResolvedEventArgs = new Map();
+                /**
+                 * Take a frozen snapshot of the registry state before any
+                 * direct registrations land. The snapshot resolves
+                 * placeholders against this point-in-time view, so a
+                 * `PreToolUse` hook later rewriting event args via
+                 * `updatedInput` can introduce placeholders that resolve
+                 * cross-batch (against prior runs) without ever picking up
+                 * same-turn direct outputs.
+                 */
+                const preBatchSnapshot = this.toolOutputRegistry?.snapshot(batchScopeId);
+                if (preBatchSnapshot != null) {
+                    for (const entry of eventEntries) {
+                        if (entry.call.id != null) {
+                            const { resolved, unresolved } = preBatchSnapshot.resolve(entry.call.args);
+                            preResolvedEventArgs.set(entry.call.id, {
+                                resolved: resolved,
+                                unresolved,
+                            });
+                        }
+                    }
                 }
-                const directCalls = filteredCalls.filter((c) => this.directToolNames.has(c.name));
-                const eventCalls = filteredCalls.filter((c) => !this.directToolNames.has(c.name));
                 const directOutputs = directCalls.length > 0
-                    ? await Promise.all(directCalls.map((call) => this.runTool(call, config)))
+                    ? await Promise.all(directCalls.map((call, i) => this.runTool(call, config, {
+                        batchIndex: directIndices[i],
+                        turn,
+                        batchScopeId,
+                        resolvedArgsByCallId,
+                    })))
                     : [];
                 if (directCalls.length > 0 && directOutputs.length > 0) {
-                    this.handleRunToolCompletions(directCalls, directOutputs, config);
+                    this.handleRunToolCompletions(directCalls, directOutputs, config, resolvedArgsByCallId);
                 }
-                const eventOutputs = eventCalls.length > 0
-                    ? await this.dispatchToolEvents(eventCalls, config)
-                    : [];
-                outputs = [...directOutputs, ...eventOutputs];
+                const eventResult = eventCalls.length > 0
+                    ? await this.dispatchToolEvents(eventCalls, config, {
+                        batchIndices: eventIndices,
+                        turn,
+                        batchScopeId,
+                        preResolvedArgs: preResolvedEventArgs,
+                        preBatchSnapshot,
+                    })
+                    : {
+                        toolMessages: [],
+                        injected: [],
+                    };
+                outputs = [
+                    ...directOutputs,
+                    ...eventResult.toolMessages,
+                    ...eventResult.injected,
+                ];
             }
             else {
-                outputs = await Promise.all(filteredCalls.map((call) => this.runTool(call, config)));
-                this.handleRunToolCompletions(filteredCalls, outputs, config);
+                outputs = await Promise.all(filteredCalls.map((call, i) => this.runTool(call, config, {
+                    batchIndex: i,
+                    turn,
+                    batchScopeId,
+                    resolvedArgsByCallId,
+                })));
+                this.handleRunToolCompletions(filteredCalls, outputs, config, resolvedArgsByCallId);
             }
         }
         if (!outputs.some(isCommand)) {