@librechat/agents 3.1.77-dev.1 → 3.1.78-dev.0

package/src/tools/ToolNode.ts

@@ -25,6 +25,7 @@ import type {
   ToolOutputResolveView,
   PreResolvedArgsMap,
   ResolvedArgsByCallId,
+  ResolveResult,
 } from '@/tools/toolOutputReferences';
 import type {
   HookRegistry,
@@ -45,6 +46,10 @@ import {
   buildReferenceKey,
   ToolOutputReferenceRegistry,
 } from '@/tools/toolOutputReferences';
+import {
+  resolveLocalToolRegistry,
+  resolveLocalExecutionTools,
+} from '@/tools/local';
 
 /**
  * Per-call batch context for `runTool`. Bundles every optional
@@ -60,6 +65,36 @@ type RunToolBatchContext = {
   batchScopeId?: string;
   /** Batch-local sink for post-substitution args. */
   resolvedArgsByCallId?: ResolvedArgsByCallId;
+  /**
+   * Frozen pre-batch view of the tool-output registry. When supplied,
+   * `runTool` resolves `{{tool…turn…}}` placeholders against this
+   * snapshot instead of the live registry, so a slow `PreToolUse`
+   * hook on one direct call cannot cause a sibling's just-registered
+   * output to leak into this call's args mid-batch (Codex P1 #18 —
+   * `Promise.all`-induced ordering would otherwise be observable).
+   */
+  preBatchSnapshot?: ToolOutputResolveView;
+  /**
+   * Pre-incremented per-tool usage counter. Set by
+   * `runDirectToolWithLifecycleHooks` so PreToolUse hooks observe
+   * the same `turn` the tool will actually execute under (Codex P2
+   * #27 — without this, parallel direct calls of the same tool in
+   * one Promise.all batch all read `turn=N` for the hook but
+   * actually executed as `turn=N`, `N+1`, `N+2`). When supplied,
+   * `runTool` skips its own counter increment.
+   */
+  usageCount?: number;
+  /**
+   * Per-batch sink for `additionalContext` strings returned by
+   * direct-path PreToolUse / PostToolUse / PostToolUseFailure hooks.
+   * The caller in `run()` materializes the accumulated strings as a
+   * `HumanMessage` appended to outputs so the next model turn sees
+   * them — same shape as the event-driven path's `injected[]`.
+   * Codex P2 #39: pre-fix the direct path called `executeHooks` and
+   * discarded `additionalContexts`, silently breaking the hook API
+   * contract for hosts relying on it for policy / recovery guidance.
+   */
+  additionalContextsSink?: string[];
 };
 
 /**
@@ -272,6 +307,17 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private toolUsageCount: Map<string, number>;
   /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
   private toolCallTurns: Map<string, number> = 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.
+   */
+  private directPathTurns: Map<string, number> = new Map();
   /** Tool registry for filtering (lazy computation of programmatic maps) */
   private toolRegistry?: t.LCToolRegistry;
   /** Cached programmatic tools (computed once on first PTC call) */
@@ -284,6 +330,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   private agentId?: string;
   /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
   private directToolNames?: Set<string>;
+  /**
+   * 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.
+   */
+  private fileCheckpointer?: t.LocalFileCheckpointer;
   /** Maximum characters allowed in a single tool result before truncation. */
   private maxToolResultChars: number;
   /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
@@ -306,6 +359,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * ToolNode building its own.
    */
   private toolOutputRegistry?: ToolOutputReferenceRegistry;
+  /** Run-scoped selection for swapping remote code tools to local executors. */
+  private toolExecution?: t.ToolExecutionConfig;
   /**
    * Monotonic counter used to mint a unique scope id for anonymous
    * batches (ones invoked without a `run_id` in
@@ -335,6 +390,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     humanInTheLoop,
     toolOutputReferences,
     toolOutputRegistry,
+    toolExecution,
+    fileCheckpointer,
   }: t.ToolNodeConstructorParams) {
     super({ name, tags, func: (input, config) => this.run(input, config) });
     this.toolMap = toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
@@ -343,7 +400,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     this.loadRuntimeTools = loadRuntimeTools;
     this.errorHandler = errorHandler;
     this.toolUsageCount = new Map<string, number>();
-    this.toolRegistry = toolRegistry;
+    this.toolRegistry = resolveLocalToolRegistry({ toolRegistry, toolExecution });
     this.sessions = sessions;
     this.eventDrivenMode = eventDrivenMode ?? false;
     this.agentId = agentId;
@@ -352,6 +409,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       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
@@ -387,6 +452,62 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     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.
+   */
+  private applyToolExecutionOverrides(): void {
+    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<string>()),
+      ...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(): t.LocalFileCheckpointer | undefined {
+    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(): void {
+    this.directPathTurns.clear();
+  }
+
   /**
    * Returns cached programmatic tools, computing once on first access.
    * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -434,10 +555,35 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     config: RunnableConfig,
     batchContext: RunToolBatchContext = {}
   ): Promise<BaseMessage | Command> {
-    const { batchIndex, turn, batchScopeId, resolvedArgsByCallId } =
-      batchContext;
+    const {
+      batchIndex,
+      turn,
+      batchScopeId,
+      resolvedArgsByCallId,
+      preBatchSnapshot,
+    } = batchContext;
     const tool = this.toolMap.get(call.name);
     const registry = this.toolOutputRegistry;
+    /**
+     * Prefer the caller-provided snapshot when present — `run()`
+     * captures one synchronously per batch so direct-path placeholder
+     * resolution stays isolated from same-turn sibling outputs even
+     * when a slow `PreToolUse` hook lets siblings finish first.
+     * Falls back to the live registry for callers that didn't thread
+     * a snapshot (anonymous direct invokes, legacy paths).
+     */
+    type ResolveFn = <T>(
+      runIdArg: string | undefined,
+      args: T
+    ) => ResolveResult<T>;
+    let resolveFn: ResolveFn | undefined;
+    if (preBatchSnapshot != null) {
+      resolveFn = <T>(_runId: string | undefined, args: T): ResolveResult<T> =>
+        preBatchSnapshot.resolve(args);
+    } else if (registry != null) {
+      resolveFn = <T>(runIdArg: string | undefined, args: T): ResolveResult<T> =>
+        registry.resolve(runIdArg, args);
+    }
     /**
      * Precompute the reference key once per call — captured locally
      * so concurrent `invoke()` calls on the same ToolNode cannot race
@@ -473,15 +619,26 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        * 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 ??
+        ((): number => {
+          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;
         /**
@@ -526,6 +683,19 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           ...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 as string | undefined) ?? '',
+            threadId: config.configurable?.thread_id as string | undefined,
+            agentId: this.agentId,
+          },
         };
       } else if (call.name === Constants.TOOL_SEARCH) {
         invokeParams = {
@@ -558,6 +728,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               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;
           }
@@ -725,6 +896,511 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     }
   }
 
+  /**
+   * 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.
+   */
+  private async runDirectToolWithLifecycleHooks(
+    call: ToolCall,
+    config: RunnableConfig,
+    batchContext: RunToolBatchContext = {}
+  ): Promise<BaseMessage | Command> {
+    const runId = (config.configurable?.run_id as string | undefined) ?? '';
+    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 as string | undefined;
+    const registryRunId =
+      batchContext.batchScopeId ??
+      (config.configurable?.run_id as string | undefined);
+    // 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: number;
+    // 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 as Record<string, unknown>;
+    if (batchContext.preBatchSnapshot != null) {
+      const { resolved } = batchContext.preBatchSnapshot.resolve(call.args);
+      resolvedArgs = resolved as Record<string, unknown>;
+    } else if (this.toolOutputRegistry != null) {
+      const { resolved } = this.toolOutputRegistry.resolve(
+        registryRunId,
+        call.args
+      );
+      resolvedArgs = resolved as Record<string, unknown>;
+    }
+
+    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 as Record<string, unknown>,
+          };
+        }
+
+        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: AskEntry = {
+            entry: {
+              call: effectiveCall,
+              args: effectiveCall.args as Record<string, unknown>,
+              stepId,
+            },
+            reason: preResult.reason,
+            allowedDecisions: preResult.allowedDecisions,
+          };
+          const payload = buildToolApprovalInterruptPayload([askEntry]);
+          const resumeValue = AsyncLocalStorageProviderSingleton.runWithConfig(
+            config,
+            () =>
+              interrupt<
+                t.ToolApprovalInterruptPayload,
+                t.ToolApprovalDecision[] | t.ToolApprovalDecisionMap
+              >(payload)
+          );
+          const decisionByCallId = normalizeApprovalDecisions(
+            [call.id!],
+            resumeValue
+          );
+          const decision = decisionByCallId.get(call.id!) ?? {
+            type: 'reject' as const,
+            reason: 'No decision provided for tool approval',
+          };
+          const declaredType = (decision as { type?: unknown }).type;
+
+          if (
+            preResult.allowedDecisions != null &&
+            (typeof declaredType !== 'string' ||
+              !preResult.allowedDecisions.includes(
+                declaredType as t.ToolApprovalDecisionType
+              ))
+          ) {
+            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 as { responseText?: unknown })
+              .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 as { updatedInput?: unknown })
+              .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 as Record<string, unknown>,
+            };
+            // 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 as Record<string, unknown>,
+          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 as Record<string, unknown>,
+          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 as
+          | t.ToolMessageRefMetadata
+          | undefined;
+        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`.
+   */
+  private askDirectWarningEmitted = false;
+  private resolveAskDecisionForDirectTool(
+    reason: string | undefined,
+    toolName: string
+  ): string {
+    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.
+   */
+  private blockDirectCall(args: {
+    call: ToolCall;
+    resolvedArgs: Record<string, unknown>;
+    reason: string;
+    hookRegistry: HookRegistry;
+    runId: string;
+    threadId: string | undefined;
+  }): ToolMessage {
+    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
@@ -797,6 +1473,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         session_id: file.session_id ?? codeSession.session_id,
         id: file.id,
         name: file.name,
+        ...(file.entity_id != null ? { entity_id: file.entity_id } : {}),
       }));
     }
 
@@ -823,7 +1500,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
       const request = requestMap.get(result.toolCallId);
       if (
-        !request?.name ||
+        request?.name == null ||
+        request.name === '' ||
         (!CODE_EXECUTION_TOOLS.has(request.name) &&
           request.name !== Constants.SKILL_TOOL)
       ) {
@@ -1992,17 +2670,42 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           batchScopeId,
         });
       }
-      outputs = [
-        await this.runTool(input.lg_tool_call, config, {
+      // 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: string[] = [];
+      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],
-        outputs,
+        // Pass only the tool output to completion handling; the
+        // HumanMessage isn't a tool result.
+        [sendOutput],
         config,
         resolvedArgsByCallId
       );
@@ -2043,6 +2746,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         );
         this.toolMap =
           toolMap ?? new Map(tools.map((tool) => [tool.name, tool]));
+        this.applyToolExecutionOverrides();
         this.programmaticCache = undefined; // Invalidate cache on toolMap change
       }
 
@@ -2131,15 +2835,22 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           }
         }
 
+        // 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: string[] = [];
         const directOutputs: (BaseMessage | Command)[] =
           directCalls.length > 0
             ? await Promise.all(
               directCalls.map((call, i) =>
-                this.runTool(call, config, {
+                this.runDirectToolWithLifecycleHooks(call, config, {
                   batchIndex: directIndices[i],
                   turn,
                   batchScopeId,
                   resolvedArgsByCallId,
+                  preBatchSnapshot,
+                  additionalContextsSink: directAdditionalContexts,
                 })
               )
             )
@@ -2168,28 +2879,66 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
               injected: [] as BaseMessage[],
             };
 
+        const directInjected: BaseMessage[] =
+          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(
+        // 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: string[] = [];
+        const toolOutputs = await Promise.all(
           filteredCalls.map((call, i) =>
-            this.runTool(call, config, {
+            this.runDirectToolWithLifecycleHooks(call, config, {
               batchIndex: i,
               turn,
               batchScopeId,
               resolvedArgsByCallId,
+              preBatchSnapshot,
+              additionalContextsSink: directAdditionalContexts,
             })
           )
         );
         this.handleRunToolCompletions(
           filteredCalls,
-          outputs,
+          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;
       }
     }