@librechat/agents 3.1.77 → 3.1.78-dev.0

package/dist/esm/tools/ToolNode.mjs

@@ -12,7 +12,19 @@ import { RunnableCallable } from '../utils/run.mjs';
 import 'ai-tokenizer';
 import 'zod-to-json-schema';
 import { executeHooks } from '../hooks/executeHooks.mjs';
+import '../hooks/createWorkspacePolicyHook.mjs';
 import { ToolOutputReferenceRegistry, buildReferenceKey } from './toolOutputReferences.mjs';
+import './local/CompileCheckTool.mjs';
+import 'path';
+import 'fs/promises';
+import './local/LocalCodingTools.mjs';
+import './local/LocalExecutionEngine.mjs';
+import '@langchain/core/tools';
+import './CodeExecutor.mjs';
+import './BashExecutor.mjs';
+import './local/LocalProgrammaticToolCalling.mjs';
+import { resolveLocalToolRegistry, resolveLocalExecutionTools } from './local/resolveLocalExecutionTools.mjs';
+import './local/attachments.mjs';
 
 /**
  * Helper to check if a value is a Send object
@@ -158,6 +170,17 @@ class ToolNode extends RunnableCallable {
     toolUsageCount;
     /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
     toolCallTurns = new Map();
+    /**
+     * `call.id → turn` map dedicated to the direct-path lifecycle so the
+     * turn assigned on first entry is REUSED on LangGraph resume.
+     * Distinct from `toolCallTurns` (which is cleared at the start of
+     * every `run()` to keep per-batch event-dispatch metadata fresh) —
+     * the direct path needs stability across re-entries triggered by
+     * `interrupt()` resumes (Codex P2 #30). Cleared with the rest of
+     * the per-Run state in `clearHeavyState`-equivalent flushes when
+     * the Run ends.
+     */
+    directPathTurns = new Map();
     /** Tool registry for filtering (lazy computation of programmatic maps) */
     toolRegistry;
     /** Cached programmatic tools (computed once on first PTC call) */
@@ -170,6 +193,13 @@ class ToolNode extends RunnableCallable {
     agentId;
     /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
     directToolNames;
+    /**
+     * File checkpointer extracted from the local coding tool bundle when
+     * `toolExecution.local.fileCheckpointing === true`. Exposed via
+     * {@link getFileCheckpointer}. Undefined when checkpointing is off
+     * or the local coding suite isn't bound to this node.
+     */
+    fileCheckpointer;
     /** Maximum characters allowed in a single tool result before truncation. */
     maxToolResultChars;
     /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
@@ -192,6 +222,8 @@ class ToolNode extends RunnableCallable {
      * ToolNode building its own.
      */
     toolOutputRegistry;
+    /** Run-scoped selection for swapping remote code tools to local executors. */
+    toolExecution;
     /**
      * Monotonic counter used to mint a unique scope id for anonymous
      * batches (ones invoked without a `run_id` in
@@ -200,7 +232,7 @@ class ToolNode extends RunnableCallable {
      * other's in-flight state.
      */
     anonBatchCounter = 0;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, }) {
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }) {
         super({ name, tags, func: (input, config) => this.run(input, config) });
         this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
         this.toolCallStepIds = toolCallStepIds;
@@ -208,7 +240,7 @@ class ToolNode extends RunnableCallable {
         this.loadRuntimeTools = loadRuntimeTools;
         this.errorHandler = errorHandler;
         this.toolUsageCount = new Map();
-        this.toolRegistry = toolRegistry;
+        this.toolRegistry = resolveLocalToolRegistry({ toolRegistry, toolExecution });
         this.sessions = sessions;
         this.eventDrivenMode = eventDrivenMode ?? false;
         this.agentId = agentId;
@@ -217,6 +249,14 @@ class ToolNode extends RunnableCallable {
             maxToolResultChars ?? calculateMaxToolResultChars(maxContextTokens);
         this.hookRegistry = hookRegistry;
         this.humanInTheLoop = humanInTheLoop;
+        this.toolExecution = toolExecution;
+        // Caller-provided checkpointer wins. Graphs use this to share a
+        // single per-Run instance across every ToolNode they compile so
+        // `Run.rewindFiles()` reaches the same snapshot store regardless
+        // of which agent's tool batch ran. Falls through to the bundle's
+        // auto-created one when undefined (direct ToolNode construction).
+        this.fileCheckpointer = fileCheckpointer;
+        this.applyToolExecutionOverrides();
         /**
          * Precedence: an explicitly passed `toolOutputRegistry` instance
          * wins over a config object so a host (`Graph`) can share one
@@ -249,6 +289,57 @@ class ToolNode extends RunnableCallable {
     _unsafeGetToolOutputRegistry() {
         return this.toolOutputRegistry;
     }
+    /**
+     * Replaces known remote Code API tools with local-process tools when
+     * `RunConfig.toolExecution.engine === 'local'`. In event-driven mode those
+     * names are also marked direct so the SDK executes them locally instead of
+     * dispatching the batch to a host-side remote sandbox handler. When the
+     * local coding suite is enabled, this also injects file/search/edit tools.
+     */
+    applyToolExecutionOverrides() {
+        const resolved = resolveLocalExecutionTools({
+            toolMap: this.toolMap,
+            toolExecution: this.toolExecution,
+            fileCheckpointer: this.fileCheckpointer,
+        });
+        this.toolMap = resolved.toolMap;
+        if (resolved.fileCheckpointer != null) {
+            this.fileCheckpointer = resolved.fileCheckpointer;
+        }
+        if (resolved.directToolNames.size === 0) {
+            return;
+        }
+        this.directToolNames = new Set([
+            ...(this.directToolNames ?? new Set()),
+            ...resolved.directToolNames,
+        ]);
+        this.programmaticCache = undefined;
+    }
+    /**
+     * Returns the per-Run file checkpointer when
+     * `toolExecution.local.fileCheckpointing === true`. Hosts call
+     * `rewind()` on the returned object to restore captured pre-write
+     * file contents — the standard "undo a tool batch" pattern. Returns
+     * undefined when checkpointing is disabled or the local coding suite
+     * isn't bound. Manual review (finding E): without this getter, the
+     * config flag was a silent no-op outside of direct
+     * `createLocalCodingToolBundle()` use.
+     */
+    getFileCheckpointer() {
+        return this.fileCheckpointer;
+    }
+    /**
+     * Flush the per-Run direct-path turn cache. Called by the Graph at
+     * end-of-Run via `clearHeavyState`. The map intentionally survives
+     * `run()` re-entry so an interrupt + resume reuses the original
+     * slot (Codex P2 #30), but it would otherwise grow linearly with
+     * tool calls and could collide across Runs if a provider reused
+     * call IDs (Codex P2 #33). Hosts can also call this directly if
+     * they reuse a ToolNode across batches outside of a Graph.
+     */
+    clearDirectPathTurns() {
+        this.directPathTurns.clear();
+    }
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -287,9 +378,16 @@ class ToolNode extends RunnableCallable {
      * substitutions. Omit when no registration should occur.
      */
     async runTool(call, config, batchContext = {}) {
-        const { batchIndex, turn, batchScopeId, resolvedArgsByCallId } = batchContext;
+        const { batchIndex, turn, batchScopeId, resolvedArgsByCallId, preBatchSnapshot, } = batchContext;
         const tool = this.toolMap.get(call.name);
         const registry = this.toolOutputRegistry;
+        let resolveFn;
+        if (preBatchSnapshot != null) {
+            resolveFn = (_runId, args) => preBatchSnapshot.resolve(args);
+        }
+        else if (registry != null) {
+            resolveFn = (runIdArg, args) => registry.resolve(runIdArg, args);
+        }
         /**
          * Precompute the reference key once per call — captured locally
          * so concurrent `invoke()` calls on the same ToolNode cannot race
@@ -323,15 +421,25 @@ class ToolNode extends RunnableCallable {
              * 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`.
+             *
+             * Prefer the value `runDirectToolWithLifecycleHooks` already
+             * incremented (Codex P2 #27) — its hook wants the SAME turn
+             * the tool will execute under. When called from a path that
+             * doesn't pre-increment (event dispatch, the no-hooks
+             * shortcut), do the read+increment here.
              */
-            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, usageCount);
-            }
+            const usageCount = batchContext.usageCount ??
+                (() => {
+                    const next = this.toolUsageCount.get(call.name) ?? 0;
+                    this.toolUsageCount.set(call.name, next + 1);
+                    if (call.id != null && call.id !== '') {
+                        this.toolCallTurns.set(call.id, next);
+                    }
+                    return next;
+                })();
             let args = call.args;
-            if (registry != null) {
-                const { resolved, unresolved } = registry.resolve(runId, args);
+            if (resolveFn != null) {
+                const { resolved, unresolved } = resolveFn(runId, args);
                 args = resolved;
                 unresolvedRefs = unresolved;
                 /**
@@ -367,6 +475,19 @@ class ToolNode extends RunnableCallable {
                     ...invokeParams,
                     toolMap,
                     toolDefs,
+                    // Plumb the hook context into the programmatic-tool path so
+                    // inner tool calls made via the in-process bridge can run
+                    // through `PreToolUse` (deny / updatedInput) before reaching
+                    // the underlying tool. Without this, `run_tools_with_code`
+                    // bypassed every PreToolUse hook the host registered for
+                    // the tools it dispatches — including HITL gates on
+                    // `write_file` / `edit_file` (manual review finding A).
+                    hookContext: {
+                        registry: this.hookRegistry,
+                        runId: config.configurable?.run_id ?? '',
+                        threadId: config.configurable?.thread_id,
+                        agentId: this.agentId,
+                    },
                 };
             }
             else if (call.name === Constants.TOOL_SEARCH) {
@@ -396,6 +517,7 @@ class ToolNode extends RunnableCallable {
                             session_id: file.session_id ?? codeSession.session_id,
                             id: file.id,
                             name: file.name,
+                            ...(file.entity_id != null ? { entity_id: file.entity_id } : {}),
                         }));
                         invokeParams._injected_files = fileRefs;
                     }
@@ -533,6 +655,428 @@ class ToolNode extends RunnableCallable {
             });
         }
     }
+    /**
+     * Runs a single in-process tool call with the same lifecycle hooks
+     * the event-dispatch path fires (`PreToolUse`, `PermissionDenied`,
+     * `PostToolUse`, `PostToolUseFailure`). Used for any tool whose
+     * implementation lives in the SDK process — i.e. every entry in
+     * `directToolNames` — so host-supplied policy hooks gate
+     * direct-invoked tools the same way they gate dispatched ones.
+     *
+     * Fast path: when the registry has none of the relevant events
+     * registered for this run, falls through to `runTool` with zero
+     * extra work. The hook list is also checked via
+     * `hasHookFor(event, runId)`, which performs the registry's own
+     * O(1) shortcut.
+     *
+     * Hook semantics intentionally mirror `dispatchToolEvents` for the
+     * single-call case:
+     *   - `PreToolUse` returning `decision: 'deny'` synthesizes an error
+     *     `ToolMessage` and fires `PermissionDenied` (observational).
+     *   - `PreToolUse` returning `decision: 'ask'`:
+     *     • When `humanInTheLoop.enabled === true`: raises a real
+     *       `tool_approval` interrupt for this single tool call (the
+     *       same payload shape the event path produces). On resume:
+     *       `approve` runs the tool, `reject` blocks via
+     *       `blockDirectCall`, `respond` returns the host-supplied
+     *       `responseText` as a synthetic success ToolMessage,
+     *       `edit` re-runs with edited args. LangGraph re-enters
+     *       ToolNode.run from the start on resume; the hook fires
+     *       again and the resume value distinguishes "first ask" from
+     *       "second pass with decision".
+     *     • When HITL is off: collapses to a fail-closed deny (matches
+     *       the rest of the SDK's HITL-disabled default). One-time
+     *       warning logged so hosts notice the gap.
+     *   - `PreToolUse.updatedInput` is applied to the call before
+     *     `runTool` runs; placeholder resolution inside `runTool` is
+     *     idempotent on already-resolved args.
+     *   - `PostToolUse.updatedOutput` replaces the returned
+     *     `ToolMessage` content (preserving id/name/status).
+     *   - `PostToolUseFailure` fires when `runTool` returns a
+     *     `ToolMessage` whose `status === 'error'`. Observational only;
+     *     the error message stays the source of truth.
+     *
+     * `PostToolBatch` aggregation across direct + dispatched outcomes is
+     * a separate concern: `dispatchToolEvents` accumulates batch entries
+     * locally and fires `PostToolBatch` at the end of its scope. Wiring
+     * direct-call entries into that aggregation crosses the two paths'
+     * scopes and is left to a follow-up.
+     */
+    async runDirectToolWithLifecycleHooks(call, config, batchContext = {}) {
+        const runId = config.configurable?.run_id ?? '';
+        const hookRegistry = this.hookRegistry;
+        const hasPreHook = hookRegistry?.hasHookFor('PreToolUse', runId) === true;
+        const hasPostHook = hookRegistry?.hasHookFor('PostToolUse', runId) === true;
+        const hasFailureHook = hookRegistry?.hasHookFor('PostToolUseFailure', runId) === true;
+        if (hookRegistry == null ||
+            (!hasPreHook && !hasPostHook && !hasFailureHook)) {
+            return this.runTool(call, config, batchContext);
+        }
+        const threadId = config.configurable?.thread_id;
+        const registryRunId = batchContext.batchScopeId ??
+            config.configurable?.run_id;
+        // Slot reservation, synchronous, before any await:
+        //   1. If this call.id already has a recorded turn (from a prior
+        //      entry that asked / interrupted), REUSE it. LangGraph
+        //      re-runs the entire ToolNode on resume, so the same call
+        //      can hit this code multiple times — incrementing on each
+        //      pass would push the eventual approved execution to
+        //      `turn=N` instead of `turn=0` (Codex P2 #30: the fix from
+        //      P2 #27 over-incremented across re-entries).
+        //   2. Otherwise reserve the next slot from the counter. Done
+        //      synchronously so concurrent same-tool calls in a single
+        //      Promise.all batch get distinct turns (the original P2 #27
+        //      requirement still holds).
+        // Net: turns are stable per call.id across interrupt/resume,
+        // unique per call within a batch.
+        let usageCount;
+        // Look in the resume-stable map first; fall back to the
+        // per-batch one. (`directPathTurns` is set on first entry and
+        // survives `run()`'s clear, so a resume sees the original
+        // assignment.)
+        const cachedTurn = call.id != null && call.id !== ''
+            ? this.directPathTurns.get(call.id) ??
+                this.toolCallTurns.get(call.id)
+            : undefined;
+        if (cachedTurn != null) {
+            usageCount = cachedTurn;
+        }
+        else {
+            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, usageCount);
+                // Dedicated direct-path map that SURVIVES `run()`'s
+                // toolCallTurns.clear() — so a re-entry triggered by
+                // LangGraph interrupt resume reuses this slot instead of
+                // re-incrementing. Codex P2 #30.
+                this.directPathTurns.set(call.id, usageCount);
+            }
+        }
+        const turn = usageCount;
+        const stepId = this.toolCallStepIds?.get(call.id ?? '') ?? '';
+        // Use the caller-threaded snapshot when available (P1 #18) so the
+        // value the PreToolUse hook observes matches the value the
+        // (later-awaited) `runTool` will actually run with — both are
+        // anchored to the pre-batch registry state.
+        let resolvedArgs = call.args;
+        if (batchContext.preBatchSnapshot != null) {
+            const { resolved } = batchContext.preBatchSnapshot.resolve(call.args);
+            resolvedArgs = resolved;
+        }
+        else if (this.toolOutputRegistry != null) {
+            const { resolved } = this.toolOutputRegistry.resolve(registryRunId, call.args);
+            resolvedArgs = resolved;
+        }
+        let effectiveCall = call;
+        if (hasPreHook) {
+            const preResult = await executeHooks({
+                registry: hookRegistry,
+                input: {
+                    hook_event_name: 'PreToolUse',
+                    runId,
+                    threadId,
+                    agentId: this.agentId,
+                    toolName: call.name,
+                    toolInput: resolvedArgs,
+                    toolUseId: call.id ?? '',
+                    stepId,
+                    turn,
+                },
+                sessionId: runId,
+                matchQuery: call.name,
+            }).catch(() => undefined);
+            if (preResult != null) {
+                // Forward any additionalContext strings hooks returned into
+                // the per-batch sink so the caller materializes them as a
+                // HumanMessage for the next model turn — same shape as the
+                // event-driven path's `injected[]`. Codex P2 #39.
+                if (batchContext.additionalContextsSink != null &&
+                    preResult.additionalContexts.length > 0) {
+                    batchContext.additionalContextsSink.push(...preResult.additionalContexts);
+                }
+                // Apply any input rewrite first — `ask`-with-`updatedInput` is
+                // a valid combination (one matcher sanitises args, another asks
+                // for approval); the reviewer should see the sanitised args.
+                if (preResult.updatedInput != null) {
+                    effectiveCall = {
+                        ...call,
+                        args: preResult.updatedInput,
+                    };
+                }
+                if (preResult.decision === 'deny') {
+                    return this.blockDirectCall({
+                        call,
+                        resolvedArgs,
+                        reason: preResult.reason ?? 'Blocked by hook',
+                        hookRegistry,
+                        runId,
+                        threadId,
+                    });
+                }
+                if (preResult.decision === 'ask') {
+                    if (this.humanInTheLoop?.enabled !== true) {
+                        // Fail-closed: no HITL UI configured, so we can't actually
+                        // ask. Logged once via the existing helper.
+                        const reason = this.resolveAskDecisionForDirectTool(preResult.reason, call.name);
+                        return this.blockDirectCall({
+                            call,
+                            resolvedArgs,
+                            reason,
+                            hookRegistry,
+                            runId,
+                            threadId,
+                        });
+                    }
+                    // Raise a single-tool tool_approval interrupt. LangGraph
+                    // throws on the first execution (host gets the interrupt)
+                    // and returns the resume value on re-entry. Because direct
+                    // tools re-enter the entire ToolNode.run on resume, the
+                    // PreToolUse hook fires AGAIN — which is fine: the hook is
+                    // expected to be deterministic, and the resume value is what
+                    // distinguishes "first call asking" from "second call after
+                    // approve/reject". We anchor `interrupt()` against the
+                    // node's RunnableConfig the same way `dispatchToolEvents`
+                    // does (ToolNode disables LangSmith tracing, so the
+                    // AsyncLocalStorage frame must be re-established here).
+                    const askEntry = {
+                        entry: {
+                            call: effectiveCall,
+                            args: effectiveCall.args,
+                            stepId,
+                        },
+                        reason: preResult.reason,
+                        allowedDecisions: preResult.allowedDecisions,
+                    };
+                    const payload = buildToolApprovalInterruptPayload([askEntry]);
+                    const resumeValue = AsyncLocalStorageProviderSingleton.runWithConfig(config, () => interrupt(payload));
+                    const decisionByCallId = normalizeApprovalDecisions([call.id], resumeValue);
+                    const decision = decisionByCallId.get(call.id) ?? {
+                        type: 'reject',
+                        reason: 'No decision provided for tool approval',
+                    };
+                    const declaredType = decision.type;
+                    if (preResult.allowedDecisions != null &&
+                        (typeof declaredType !== 'string' ||
+                            !preResult.allowedDecisions.includes(declaredType))) {
+                        return this.blockDirectCall({
+                            call,
+                            resolvedArgs,
+                            reason: `Decision "${typeof declaredType === 'string' ? declaredType : '<missing>'}" not in allowedDecisions [${preResult.allowedDecisions.join(', ')}] — failing closed`,
+                            hookRegistry,
+                            runId,
+                            threadId,
+                        });
+                    }
+                    if (decision.type === 'reject') {
+                        return this.blockDirectCall({
+                            call,
+                            resolvedArgs,
+                            reason: decision.reason ??
+                                preResult.reason ??
+                                'Rejected by user',
+                            hookRegistry,
+                            runId,
+                            threadId,
+                        });
+                    }
+                    if (decision.type === 'respond') {
+                        const responseText = decision
+                            .responseText;
+                        if (typeof responseText !== 'string') {
+                            return this.blockDirectCall({
+                                call,
+                                resolvedArgs,
+                                reason: 'Approval payload `respond` was missing a string `responseText`',
+                                hookRegistry,
+                                runId,
+                                threadId,
+                            });
+                        }
+                        return new ToolMessage({
+                            status: 'success',
+                            content: responseText,
+                            name: call.name,
+                            tool_call_id: call.id ?? '',
+                        });
+                    }
+                    if (decision.type === 'edit') {
+                        // Mirror the event-driven path's validation
+                        // (see `dispatchToolEvents`'s edit branch). The wire
+                        // field is `updatedInput`, NOT `args` — hosts following
+                        // the documented `ToolApprovalDecision` shape were
+                        // silently ignored before, so the tool ran with the
+                        // original (un-edited) arguments. Fail closed on
+                        // malformed payloads instead of falling through with
+                        // undefined args.
+                        const updatedInput = decision
+                            .updatedInput;
+                        if (updatedInput === null ||
+                            typeof updatedInput !== 'object' ||
+                            Array.isArray(updatedInput)) {
+                            return new ToolMessage({
+                                status: 'error',
+                                content: 'Decision "edit" missing object updatedInput — failing closed.',
+                                name: call.name,
+                                tool_call_id: call.id ?? '',
+                            });
+                        }
+                        effectiveCall = {
+                            ...call,
+                            args: updatedInput,
+                        };
+                        // fall through to executing the edited call
+                    }
+                    // 'approve' (or 'edit' after applying edits) → fall through
+                }
+            }
+        }
+        const output = await this.runTool(effectiveCall, config, {
+            ...batchContext,
+            usageCount,
+        });
+        if (!(output instanceof ToolMessage)) {
+            return output;
+        }
+        if (output.status === 'error' && hasFailureHook) {
+            // Await the failure hook (instead of fire-and-forget) so we
+            // can capture additionalContexts before returning. The hook is
+            // still observational w.r.t. the tool result itself — we don't
+            // mutate `output`, just plumb the contexts. Codex P2 #39.
+            const failureResult = await executeHooks({
+                registry: hookRegistry,
+                input: {
+                    hook_event_name: 'PostToolUseFailure',
+                    runId,
+                    threadId,
+                    agentId: this.agentId,
+                    toolName: call.name,
+                    toolInput: effectiveCall.args,
+                    toolUseId: call.id ?? '',
+                    error: typeof output.content === 'string'
+                        ? output.content
+                        : JSON.stringify(output.content),
+                    stepId,
+                    turn,
+                },
+                sessionId: runId,
+                matchQuery: call.name,
+            }).catch(() => undefined);
+            if (failureResult != null &&
+                batchContext.additionalContextsSink != null &&
+                failureResult.additionalContexts.length > 0) {
+                batchContext.additionalContextsSink.push(...failureResult.additionalContexts);
+            }
+            return output;
+        }
+        if (output.status !== 'error' && hasPostHook) {
+            const postResult = await executeHooks({
+                registry: hookRegistry,
+                input: {
+                    hook_event_name: 'PostToolUse',
+                    runId,
+                    threadId,
+                    agentId: this.agentId,
+                    toolName: call.name,
+                    toolInput: effectiveCall.args,
+                    toolOutput: output.content,
+                    toolUseId: call.id ?? '',
+                    stepId,
+                    turn,
+                },
+                sessionId: runId,
+                matchQuery: call.name,
+            }).catch(() => undefined);
+            // Forward additionalContexts from the PostToolUse hook into
+            // the per-batch sink (Codex P2 #39).
+            if (postResult != null &&
+                batchContext.additionalContextsSink != null &&
+                postResult.additionalContexts.length > 0) {
+                batchContext.additionalContextsSink.push(...postResult.additionalContexts);
+            }
+            if (postResult?.updatedOutput != null) {
+                const replaced = typeof postResult.updatedOutput === 'string'
+                    ? postResult.updatedOutput
+                    : JSON.stringify(postResult.updatedOutput);
+                // Keep the tool-output registry in sync with what the model
+                // actually sees. Without this, `runTool` already registered
+                // the PRE-hook content under `_refKey`, and a later
+                // `{{tool<i>turn<n>}}` substitution would deliver the stale
+                // pre-hook bytes while the model (and downstream tools)
+                // observed the post-hook replacement. Read `_refKey` /
+                // `_refScope` straight off the message metadata that
+                // `recordOutputReference` stamped — no need to re-derive
+                // (and we couldn't, for anonymous-batch synthetic scopes).
+                const refMeta = output.additional_kwargs;
+                const refKey = refMeta?._refKey;
+                const refScope = refMeta?._refScope;
+                if (this.toolOutputRegistry != null && refKey != null) {
+                    this.toolOutputRegistry.set(refScope, refKey, replaced);
+                }
+                return new ToolMessage({
+                    status: output.status,
+                    name: output.name,
+                    content: replaced,
+                    artifact: output.artifact,
+                    tool_call_id: output.tool_call_id,
+                    additional_kwargs: output.additional_kwargs,
+                });
+            }
+        }
+        return output;
+    }
+    /**
+     * `ask` decisions on direct-path tools collapse to fail-closed deny
+     * only when `humanInTheLoop.enabled !== true` (i.e. there's no host
+     * UI configured to actually prompt the user). Logged once per process
+     * so the gap is visible. When HITL IS enabled, `ask` raises a real
+     * LangGraph `interrupt()` instead — see `runDirectToolWithLifecycleHooks`.
+     */
+    askDirectWarningEmitted = false;
+    resolveAskDecisionForDirectTool(reason, toolName) {
+        if (!this.askDirectWarningEmitted) {
+            this.askDirectWarningEmitted = true;
+            // eslint-disable-next-line no-console
+            console.warn(`[ToolNode] PreToolUse returned 'ask' for direct-path tool "${toolName}" but ` +
+                'humanInTheLoop is not enabled — failing closed. Set humanInTheLoop.enabled=true ' +
+                'to raise a tool_approval interrupt the host can resolve.');
+        }
+        return reason ?? 'Blocked by hook';
+    }
+    /**
+     * Synthesize a Blocked ToolMessage AND fire `PermissionDenied`
+     * (observational) for a direct-path tool call. Centralised so the
+     * deny path looks identical whether the block came from `'deny'` or
+     * from a fail-closed/`'reject'`/policy-violation path.
+     */
+    blockDirectCall(args) {
+        const { call, resolvedArgs, reason, hookRegistry, runId, threadId } = args;
+        if (hookRegistry.hasHookFor('PermissionDenied', runId) === true) {
+            executeHooks({
+                registry: hookRegistry,
+                input: {
+                    hook_event_name: 'PermissionDenied',
+                    runId,
+                    threadId,
+                    agentId: this.agentId,
+                    toolName: call.name,
+                    toolInput: resolvedArgs,
+                    toolUseId: call.id ?? '',
+                    reason,
+                },
+                sessionId: runId,
+                matchQuery: call.name,
+            }).catch(() => {
+                /* observational */
+            });
+        }
+        return new ToolMessage({
+            status: 'error',
+            content: `Blocked: ${reason}`,
+            name: call.name,
+            tool_call_id: call.id ?? '',
+        });
+    }
     /**
      * Registers the full, raw output under `refKey` (when provided) and
      * builds the per-message ref metadata stamped onto the resulting
@@ -597,6 +1141,7 @@ class ToolNode extends RunnableCallable {
                 session_id: file.session_id ?? codeSession.session_id,
                 id: file.id,
                 name: file.name,
+                ...(file.entity_id != null ? { entity_id: file.entity_id } : {}),
             }));
         }
         return context;
@@ -615,7 +1160,8 @@ class ToolNode extends RunnableCallable {
                 continue;
             }
             const request = requestMap.get(result.toolCallId);
-            if (!request?.name ||
+            if (request?.name == null ||
+                request.name === '' ||
                 (!CODE_EXECUTION_TOOLS.has(request.name) &&
                     request.name !== Constants.SKILL_TOOL)) {
                 continue;
@@ -1527,15 +2073,37 @@ class ToolNode extends RunnableCallable {
                     batchScopeId,
                 });
             }
-            outputs = [
-                await this.runTool(input.lg_tool_call, config, {
-                    batchIndex: 0,
-                    turn,
-                    batchScopeId,
-                    resolvedArgsByCallId,
-                }),
-            ];
-            this.handleRunToolCompletions([input.lg_tool_call], outputs, config, resolvedArgsByCallId);
+            // Same per-batch sink the message-state branches use so
+            // direct-path PreToolUse/PostToolUse/Failure additionalContexts
+            // surface here too. Codex P2 [44] — round 14 added the sink to
+            // both message-state branches but missed this Send-input
+            // branch, so direct tools dispatched via Send (a supported
+            // input shape) still silently dropped hook context.
+            const directAdditionalContexts = [];
+            const sendOutput = await this.runDirectToolWithLifecycleHooks(input.lg_tool_call, config, {
+                batchIndex: 0,
+                turn,
+                batchScopeId,
+                resolvedArgsByCallId,
+                additionalContextsSink: directAdditionalContexts,
+            });
+            outputs =
+                directAdditionalContexts.length > 0
+                    ? [
+                        sendOutput,
+                        new HumanMessage({
+                            content: directAdditionalContexts.join('\n\n'),
+                            // Match the event-driven path's marker so hosts /
+                            // model-side annotators treat this as system intent
+                            // rather than ordinary user text. Codex P2 [46].
+                            additional_kwargs: { role: 'system', source: 'hook' },
+                        }),
+                    ]
+                    : [sendOutput];
+            this.handleRunToolCompletions([input.lg_tool_call], 
+            // Pass only the tool output to completion handling; the
+            // HumanMessage isn't a tool result.
+            [sendOutput], config, resolvedArgsByCallId);
         }
         else {
             let messages;
@@ -1566,6 +2134,7 @@ class ToolNode extends RunnableCallable {
                 const { tools, toolMap } = this.loadRuntimeTools(aiMessage.tool_calls ?? []);
                 this.toolMap =
                     toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+                this.applyToolExecutionOverrides();
                 this.programmaticCache = undefined; // Invalidate cache on toolMap change
             }
             const filteredCalls = aiMessage.tool_calls?.filter((call) => {
@@ -1637,12 +2206,19 @@ class ToolNode extends RunnableCallable {
                         }
                     }
                 }
+                // Per-batch sink for direct-path hook additionalContexts
+                // (Codex P2 #39). Materialized as a HumanMessage at end-of-
+                // batch so the next model turn sees the injected context,
+                // matching the event path's `injected[]` shape.
+                const directAdditionalContexts = [];
                 const directOutputs = directCalls.length > 0
-                    ? await Promise.all(directCalls.map((call, i) => this.runTool(call, config, {
+                    ? await Promise.all(directCalls.map((call, i) => this.runDirectToolWithLifecycleHooks(call, config, {
                         batchIndex: directIndices[i],
                         turn,
                         batchScopeId,
                         resolvedArgsByCallId,
+                        preBatchSnapshot,
+                        additionalContextsSink: directAdditionalContexts,
                     })))
                     : [];
                 if (directCalls.length > 0 && directOutputs.length > 0) {
@@ -1660,20 +2236,56 @@ class ToolNode extends RunnableCallable {
                         toolMessages: [],
                         injected: [],
                     };
+                const directInjected = directAdditionalContexts.length > 0
+                    ? [
+                        new HumanMessage({
+                            content: directAdditionalContexts.join('\n\n'),
+                            // System-role metadata to match the event-driven
+                            // path so policy/recovery guidance is treated
+                            // consistently regardless of whether the tool ran
+                            // direct or dispatched. Codex P2 [46].
+                            additional_kwargs: { role: 'system', source: 'hook' },
+                        }),
+                    ]
+                    : [];
                 outputs = [
                     ...directOutputs,
                     ...eventResult.toolMessages,
+                    ...directInjected,
                     ...eventResult.injected,
                 ];
             }
             else {
-                outputs = await Promise.all(filteredCalls.map((call, i) => this.runTool(call, config, {
+                // Same per-batch pre-snapshot as the mixed path, applied to
+                // the all-direct case so `Promise.all`-induced ordering can't
+                // leak a sibling's just-registered output into a sister
+                // call's args mid-await (Codex P1 #18).
+                const preBatchSnapshot = this.toolOutputRegistry?.snapshot(batchScopeId);
+                const directAdditionalContexts = [];
+                const toolOutputs = await Promise.all(filteredCalls.map((call, i) => this.runDirectToolWithLifecycleHooks(call, config, {
                     batchIndex: i,
                     turn,
                     batchScopeId,
                     resolvedArgsByCallId,
+                    preBatchSnapshot,
+                    additionalContextsSink: directAdditionalContexts,
                 })));
-                this.handleRunToolCompletions(filteredCalls, outputs, config, resolvedArgsByCallId);
+                this.handleRunToolCompletions(filteredCalls, toolOutputs, config, resolvedArgsByCallId);
+                // Append accumulated additionalContexts as a single
+                // HumanMessage so the next model turn sees them. Codex P2 #39.
+                outputs =
+                    directAdditionalContexts.length > 0
+                        ? [
+                            ...toolOutputs,
+                            new HumanMessage({
+                                content: directAdditionalContexts.join('\n\n'),
+                                // Same system-role marker the event-driven path
+                                // uses so direct vs dispatched is invisible to
+                                // downstream consumers. Codex P2 [46].
+                                additional_kwargs: { role: 'system', source: 'hook' },
+                            }),
+                        ]
+                        : toolOutputs;
             }
         }
         if (!outputs.some(isCommand)) {