@librechat/agents 3.4.6 → 3.5.0

package/src/tools/__tests__/hitl.test.ts

@@ -1,4663 +0,0 @@
-import { z } from 'zod';
-import { tool } from '@langchain/core/tools';
-import { AIMessage, ToolMessage } from '@langchain/core/messages';
-import {
-  describe,
-  it,
-  expect,
-  jest,
-  afterEach,
-  beforeEach,
-} from '@jest/globals';
-import {
-  END,
-  START,
-  Command,
-  StateGraph,
-  MemorySaver,
-  isInterrupted,
-  MessagesAnnotation,
-} from '@langchain/langgraph';
-import type { Runnable, RunnableConfig } from '@langchain/core/runnables';
-import type { StructuredToolInterface } from '@langchain/core/tools';
-import type { BaseMessage } from '@langchain/core/messages';
-import type {
-  PreToolUseHookOutput,
-  PostToolUseHookOutput,
-  PostToolUseFailureHookOutput,
-  PostToolBatchEntry,
-  PostToolBatchHookInput,
-  PostToolBatchHookOutput,
-  RunStartHookOutput,
-  UserPromptSubmitHookOutput,
-} from '@/hooks';
-import type * as t from '@/types';
-import { Constants, Providers as providers, GraphEvents } from '@/common';
-import { HookRegistry, createToolPolicyHook } from '@/hooks';
-import * as events from '@/utils/events';
-import { askUserQuestion } from '@/hitl';
-import { ToolNode } from '../ToolNode';
-
-async function flushAsyncWork(): Promise<void> {
-  await Promise.resolve();
-  await new Promise<void>((resolve) => setImmediate(resolve));
-  await new Promise<void>((resolve) => setTimeout(resolve, 0));
-  await new Promise<void>((resolve) => setImmediate(resolve));
-  await Promise.resolve();
-}
-
-afterEach(async () => {
-  await flushAsyncWork();
-  jest.restoreAllMocks();
-  await flushAsyncWork();
-});
-
-/**
- * Schema-only tool stub. ToolNode in event-driven mode uses the schema
- * for binding/discovery but routes execution through the host via
- * `ON_TOOL_EXECUTE`, so the actual `func` here is never called.
- */
-function createSchemaStub(name: string): StructuredToolInterface {
-  return tool(async () => 'unused', {
-    name,
-    description: 'schema-only stub; host executes via ON_TOOL_EXECUTE',
-    schema: z.object({ command: z.string() }),
-  }) as unknown as StructuredToolInterface;
-}
-
-/**
- * Wires a fake host that responds to every `ON_TOOL_EXECUTE` event by
- * resolving the request promise with `mockResults`. Mirrors the pattern
- * used in `ToolNode.outputReferences.test.ts` so the event-driven path
- * actually returns ToolMessages without spinning up a real host.
- */
-function mockEventDispatch(mockResults: t.ToolExecuteResult[]): void {
-  jest
-    .spyOn(events, 'safeDispatchCustomEvent')
-    .mockImplementation(async (event, data) => {
-      if (event !== 'on_tool_execute') {
-        return;
-      }
-      const request = data as Record<string, unknown>;
-      if (typeof request.resolve === 'function') {
-        (request.resolve as (r: t.ToolExecuteResult[]) => void)(mockResults);
-      }
-    });
-}
-
-type MessagesUpdate = { messages: BaseMessage[] };
-type InterruptStateSnapshot = {
-  config?: RunnableConfig;
-  tasks?: Array<{
-    interrupts?: Array<{ id?: string }>;
-  }>;
-};
-type CompiledMessagesGraph = Runnable<unknown, { messages: BaseMessage[] }> & {
-  invoke(input: unknown, config?: RunnableConfig): Promise<unknown>;
-  getState?(
-    config: RunnableConfig
-  ): Promise<{ config?: RunnableConfig } | undefined>;
-  getStateHistory?(
-    config: RunnableConfig
-  ): AsyncIterableIterator<InterruptStateSnapshot>;
-};
-
-/** Factory for a minimal `agent → tools → END` graph wrapping the ToolNode. */
-function buildHITLGraph(
-  toolNode: ToolNode,
-  toolCalls: Array<{ id: string; name: string; args: Record<string, unknown> }>
-): CompiledMessagesGraph {
-  const toolCallIds = new Set(toolCalls.map((call) => call.id));
-  const builder = new StateGraph(MessagesAnnotation)
-    .addNode('agent', (state: { messages?: BaseMessage[] }): MessagesUpdate => {
-      /**
-       * Emit the AIMessage carrying tool_calls until this test graph
-       * actually has a matching ToolMessage in state. LangGraph usually
-       * resumes at the interrupted `tools` node, but under full-suite
-       * async callback pressure it can re-enter this tiny test graph from
-       * START while still carrying the resume value. A call-count based
-       * fake agent then returned "done" too early and made HITL resume
-       * assertions order-dependent. State is the stable contract here:
-       * no tool result means the tool node still needs work.
-       */
-      const hasMatchingToolResult =
-        state.messages?.some(
-          (message): boolean =>
-            message._getType() === 'tool' &&
-            toolCallIds.has((message as ToolMessage).tool_call_id)
-        ) === true;
-      if (!hasMatchingToolResult) {
-        return {
-          messages: [new AIMessage({ content: '', tool_calls: toolCalls })],
-        };
-      }
-      return { messages: [new AIMessage({ content: 'done' })] };
-    })
-    .addNode('tools', toolNode)
-    .addEdge(START, 'agent')
-    .addEdge('agent', 'tools')
-    .addEdge('tools', END);
-  return builder.compile({
-    checkpointer: new MemorySaver(),
-  }) as unknown as CompiledMessagesGraph;
-}
-
-function makeHookRegistry(
-  decision: 'allow' | 'deny' | 'ask',
-  reason?: string
-): HookRegistry {
-  const registry = new HookRegistry();
-  registry.register('PreToolUse', {
-    hooks: [
-      async (): Promise<PreToolUseHookOutput> => ({
-        decision,
-        ...(reason != null ? { reason } : {}),
-      }),
-    ],
-  });
-  return registry;
-}
-
-function resumeFromInterrupt<TResume>(
-  interrupted: unknown,
-  resume: TResume
-): Command {
-  if (isInterrupted<unknown>(interrupted)) {
-    const interruptId = interrupted.__interrupt__[0]?.id;
-    if (typeof interruptId === 'string' && interruptId.length > 0) {
-      return new Command({ resume: { [interruptId]: resume } });
-    }
-  }
-  return new Command({ resume });
-}
-
-async function resumeGraph<TResume>(
-  graph: CompiledMessagesGraph,
-  interrupted: unknown,
-  resume: TResume,
-  config: RunnableConfig
-): Promise<unknown> {
-  const interruptId = isInterrupted<unknown>(interrupted)
-    ? interrupted.__interrupt__[0]?.id
-    : undefined;
-  let checkpointConfig = config;
-  if (typeof interruptId === 'string' && graph.getStateHistory != null) {
-    for await (const snapshot of graph.getStateHistory(config)) {
-      const hasMatchingInterrupt =
-        snapshot.tasks?.some(
-          (task) =>
-            task.interrupts?.some(
-              (interrupt) => interrupt.id === interruptId
-            ) === true
-        ) === true;
-      if (hasMatchingInterrupt && snapshot.config != null) {
-        checkpointConfig = snapshot.config;
-        break;
-      }
-    }
-  } else {
-    checkpointConfig = (await graph.getState?.(config))?.config ?? config;
-  }
-  return graph.invoke(
-    resumeFromInterrupt(interrupted, resume),
-    checkpointConfig
-  );
-}
-
-describe('ToolNode HITL — `ask` decision raises interrupt() when humanInTheLoop is enabled', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('raises a tool_approval interrupt with the pending tool call payload', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'should-not-run', status: 'success' },
-    ]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask', 'review tool args'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'list /' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-1' } };
-
-    const result = await graph.invoke({ messages: [] }, config);
-
-    expect(isInterrupted<t.HumanInterruptPayload>(result)).toBe(true);
-    if (!isInterrupted<t.HumanInterruptPayload>(result)) {
-      throw new Error('expected interrupt');
-    }
-    const interrupts = result.__interrupt__;
-    expect(interrupts).toHaveLength(1);
-    const payload = interrupts[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval payload');
-    }
-    expect(payload.action_requests).toEqual([
-      {
-        tool_call_id: 'call_1',
-        name: 'echo',
-        arguments: { command: 'list /' },
-        description: 'review tool args',
-      },
-    ]);
-    expect(payload.review_configs).toEqual([
-      {
-        action_name: 'echo',
-        tool_call_id: 'call_1',
-        allowed_decisions: ['approve', 'reject', 'edit', 'respond'],
-      },
-    ]);
-  });
-
-  it('waits for approval before executing an explicit ask rule in bypass mode', async () => {
-    let toolExecuted = false;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        toolExecuted = true;
-        const request = data as {
-          resolve: (results: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([
-          { toolCallId: 'call_1', content: 'deleted', status: 'success' },
-        ]);
-      });
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        createToolPolicyHook({
-          mode: 'bypass',
-          ask: ['dangerous_*'],
-        }),
-      ],
-    });
-    const node = new ToolNode({
-      tools: [createSchemaStub('dangerous_tool')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    const graph = buildHITLGraph(node, [
-      {
-        id: 'call_1',
-        name: 'dangerous_tool',
-        args: { command: 'delete data' },
-      },
-    ]);
-    const config = {
-      configurable: { thread_id: 'thread-bypass-explicit-ask' },
-    };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    expect(isInterrupted<t.HumanInterruptPayload>(interrupted)).toBe(true);
-    expect(toolExecuted).toBe(false);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'approve' }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    expect(toolExecuted).toBe(true);
-    expect(
-      resumed.messages.some(
-        (message) =>
-          message._getType() === 'tool' &&
-          (message as ToolMessage).tool_call_id === 'call_1' &&
-          message.content === 'deleted'
-      )
-    ).toBe(true);
-  });
-
-  it('executes an unmatched tool without interruption in bypass mode', async () => {
-    let toolExecuted = false;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        toolExecuted = true;
-        const request = data as {
-          resolve: (results: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([
-          { toolCallId: 'call_1', content: 'read result', status: 'success' },
-        ]);
-      });
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        createToolPolicyHook({
-          mode: 'bypass',
-          ask: ['dangerous_*'],
-        }),
-      ],
-    });
-    const node = new ToolNode({
-      tools: [createSchemaStub('read_tool')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'read_tool', args: { command: 'read data' } },
-    ]);
-
-    const result = await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'thread-bypass-unmatched' } }
-    );
-
-    expect(isInterrupted(result)).toBe(false);
-    expect(toolExecuted).toBe(true);
-  });
-
-  it('resume with approve runs the tool through the host event path', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'host-result', status: 'success' },
-    ]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'do-it' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-approve' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    expect(isInterrupted(interrupted)).toBe(true);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'approve' }],
-      config
-    )) as {
-      messages: BaseMessage[];
-    };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].tool_call_id).toBe('call_1');
-    expect(toolMessages[0].content).toBe('host-result');
-    expect(toolMessages[0].status).not.toBe('error');
-  });
-
-  it('resume with reject blocks the tool and emits an error ToolMessage', async () => {
-    mockEventDispatch([]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'rm -rf /' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-reject' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'reject', reason: 'destructive command' }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain('destructive command');
-  });
-
-  it('resume with edit substitutes the tool input before invocation', async () => {
-    const capturedRequests: t.ToolCallRequest[] = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        capturedRequests.push(...request.toolCalls);
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'host-result',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-edit' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'edit', updatedInput: { command: 'patched' } }],
-      config
-    );
-
-    expect(capturedRequests).toHaveLength(1);
-    expect(capturedRequests[0].args).toEqual({ command: 'patched' });
-  });
-
-  it('resume with respond emits the user-supplied text as a successful ToolMessage and skips host execution', async () => {
-    const dispatchSpy = jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([]);
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'search' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-respond' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    const dispatchCallsBefore = dispatchSpy.mock.calls.filter(
-      ([event]) => event === 'on_tool_execute'
-    ).length;
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'respond', responseText: 'no relevant results' }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const dispatchCallsAfter = dispatchSpy.mock.calls.filter(
-      ([event]) => event === 'on_tool_execute'
-    ).length;
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].tool_call_id).toBe('call_1');
-    expect(toolMessages[0].content).toBe('no relevant results');
-    expect(toolMessages[0].status).not.toBe('error');
-    expect(dispatchCallsAfter).toBe(dispatchCallsBefore);
-  });
-
-  it('advertises respond in review_configs.allowed_decisions', async () => {
-    mockEventDispatch([]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    const config = {
-      configurable: { thread_id: 'thread-hitl-allowed-decisions' },
-    };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval payload');
-    }
-    expect(payload.review_configs[0].allowed_decisions).toEqual([
-      'approve',
-      'reject',
-      'edit',
-      'respond',
-    ]);
-  });
-
-  it('resume with a record keyed by tool_call_id is accepted', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'host-result', status: 'success' },
-    ]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'do-it' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-map' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      { call_1: { type: 'approve' } },
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].content).toBe('host-result');
-  });
-});
-
-describe('ToolNode HITL — opt-out (`humanInTheLoop: { enabled: false }`) is fail-closed', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('blocks the tool with a ToolMessage error and never raises an interrupt', async () => {
-    mockEventDispatch([]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask', 'HITL explicitly disabled'),
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'list /' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-optout' } };
-
-    const result = (await graph.invoke({ messages: [] }, config)) as {
-      messages: BaseMessage[];
-    };
-
-    expect(isInterrupted(result)).toBe(false);
-    const toolMessages = result.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'HITL explicitly disabled'
-    );
-  });
-
-  it('blocks the tool when `humanInTheLoop` is omitted (default-off)', async () => {
-    /**
-     * Default is OFF until host UIs (notably LibreChat) ship the
-     * approval-rendering affordances. With HITL omitted, an `ask`
-     * decision must collapse into a synchronous block — same fail-
-     * closed behavior as the explicit `{ enabled: false }` opt-out.
-     * This test guards against accidentally re-enabling the default-on
-     * path before the consumer ecosystem is ready.
-     */
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'host-result', status: 'success' },
-    ]);
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask', 'default-off-blocks'),
-      // humanInTheLoop intentionally omitted — should default to disabled
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'list /' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-default' } };
-
-    const out = (await graph.invoke({ messages: [] }, config)) as {
-      messages: BaseMessage[];
-    };
-    expect(isInterrupted<t.HumanInterruptPayload>(out)).toBe(false);
-    const toolMessages = out.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].tool_call_id).toBe('call_1');
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain('default-off-blocks');
-  });
-});
-
-describe('ToolNode HITL — multi-tool batches', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('bundles multiple ask decisions into a single interrupt and resolves per call', async () => {
-    const capturedRequests: t.ToolCallRequest[] = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        capturedRequests.push(...request.toolCalls);
-        request.resolve(
-          request.toolCalls.map(
-            (c): t.ToolExecuteResult => ({
-              toolCallId: c.id,
-              content: `ran:${c.name}`,
-              status: 'success',
-            })
-          )
-        );
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo'), createSchemaStub('cat')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([
-        ['call_1', 'step_call_1'],
-        ['call_2', 'step_call_2'],
-      ]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'one' } },
-      { id: 'call_2', name: 'cat', args: { command: 'two' } },
-    ]);
-    const config = { configurable: { thread_id: 'thread-hitl-batch' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    expect(isInterrupted<t.HumanInterruptPayload>(interrupted)).toBe(true);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval payload');
-    }
-    expect(payload.action_requests.map((r) => r.tool_call_id)).toEqual([
-      'call_1',
-      'call_2',
-    ]);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'approve' }, { type: 'reject', reason: 'too risky' }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(2);
-    const byId = new Map(toolMessages.map((m) => [m.tool_call_id, m]));
-    expect(byId.get('call_1')!.content).toBe('ran:echo');
-    expect(byId.get('call_1')!.status).not.toBe('error');
-    expect(byId.get('call_2')!.status).toBe('error');
-    expect(String(byId.get('call_2')!.content)).toContain('too risky');
-
-    expect(capturedRequests).toHaveLength(1);
-    expect(capturedRequests[0].id).toBe('call_1');
-  });
-});
-
-describe('Run integration — HITL fallback checkpointer + resume', () => {
-  beforeEach(() => {
-    jest.restoreAllMocks();
-  });
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('Run.create does NOT install a MemorySaver fallback by default (HITL is off until host UI ships)', async () => {
-    /**
-     * Default-off rationale: HITL ships the interrupt machinery but
-     * stays opt-in until host UIs (notably LibreChat) can render and
-     * resolve `tool_approval` interrupts. With HITL omitted, the SDK
-     * must NOT silently install a checkpointer — that would suggest
-     * the run can pause/resume when in fact the `ask` path will
-     * fail-closed. Plan of record: flip the default to ON in a future
-     * minor once the consumer ecosystem is ready.
-     */
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'hitl-default-run',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      // humanInTheLoop intentionally omitted — default is OFF
-    });
-
-    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
-  });
-
-  it('Run.create installs a MemorySaver fallback when HITL is explicitly enabled', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'hitl-explicit-run',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      humanInTheLoop: { enabled: true },
-    });
-
-    expect(run.Graph?.compileOptions?.checkpointer).toBeInstanceOf(MemorySaver);
-    expect(run.Graph?.humanInTheLoop?.enabled).toBe(true);
-  });
-
-  it('Run.create preserves a host-supplied checkpointer when HITL is explicitly enabled', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const hostCheckpointer = new MemorySaver();
-    const run = await Run.create<t.IState>({
-      runId: 'hitl-host-checkpointer',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-        compileOptions: { checkpointer: hostCheckpointer },
-      },
-      humanInTheLoop: { enabled: true },
-    });
-
-    expect(run.Graph?.compileOptions?.checkpointer).toBe(hostCheckpointer);
-  });
-
-  it('processStream defaults durability to "exit" when a checkpointer is active', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'durability-exit-default',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      humanInTheLoop: { enabled: true },
-    });
-    expect(run.Graph?.compileOptions?.checkpointer).toBeInstanceOf(MemorySaver);
-
-    const graph = new StateGraph(MessagesAnnotation)
-      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
-      .addEdge(START, 'noop')
-      .addEdge('noop', END)
-      .compile();
-    const spy = jest.spyOn(graph, 'streamEvents');
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      { version: 'v2', configurable: { thread_id: 't' } }
-    );
-
-    const streamedConfig = spy.mock.calls[0]?.[1] as
-      | t.RunStreamConfig
-      | undefined;
-    expect(streamedConfig?.durability).toBe('exit');
-  });
-
-  it('processStream respects an explicit caller durability over the checkpointer default', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'durability-explicit-override',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = new StateGraph(MessagesAnnotation)
-      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
-      .addEdge(START, 'noop')
-      .addEdge('noop', END)
-      .compile();
-    const spy = jest.spyOn(graph, 'streamEvents');
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      { version: 'v2', durability: 'sync', configurable: { thread_id: 't' } }
-    );
-
-    const streamedConfig = spy.mock.calls[0]?.[1] as
-      | t.RunStreamConfig
-      | undefined;
-    expect(streamedConfig?.durability).toBe('sync');
-  });
-
-  it('processStream leaves durability unset when no checkpointer is active', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'durability-no-checkpointer',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      // humanInTheLoop omitted — no checkpointer installed
-    });
-    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
-
-    const graph = new StateGraph(MessagesAnnotation)
-      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
-      .addEdge(START, 'noop')
-      .addEdge('noop', END)
-      .compile();
-    const spy = jest.spyOn(graph, 'streamEvents');
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      { version: 'v2', configurable: { thread_id: 't' } }
-    );
-
-    const streamedConfig = spy.mock.calls[0]?.[1] as
-      | t.RunStreamConfig
-      | undefined;
-    expect(streamedConfig?.durability).toBeUndefined();
-  });
-
-  it('defaults durability to "exit" when HITL installs the fallback checkpointer but caller compileOptions omit it', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'durability-hitl-fallback-compileopts',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-        // Caller compileOptions without a checkpointer: HITL adds a MemorySaver
-        // fallback while preserving the caller's remaining compile options.
-        compileOptions: { interruptBefore: [] },
-      },
-      humanInTheLoop: { enabled: true },
-    });
-    expect(run.Graph?.compileOptions?.checkpointer).toBeInstanceOf(MemorySaver);
-    expect(run.Graph?.compileOptions?.interruptBefore).toEqual([]);
-
-    const graph = new StateGraph(MessagesAnnotation)
-      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
-      .addEdge(START, 'noop')
-      .addEdge('noop', END)
-      .compile();
-    const spy = jest.spyOn(graph, 'streamEvents');
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      { version: 'v2', configurable: { thread_id: 't' } }
-    );
-
-    const streamedConfig = spy.mock.calls[0]?.[1] as
-      | t.RunStreamConfig
-      | undefined;
-    expect(streamedConfig?.durability).toBe('exit');
-  });
-
-  it('Run.resume forwards update + goto into the resume Command (langgraph 1.4.5)', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'hitl-resume-update-goto',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-    });
-
-    const spy = jest.spyOn(run, 'processStream').mockResolvedValue(undefined);
-
-    const decision = [{ type: 'approve' as const }];
-    const update = { messages: [new AIMessage('host-edit')] };
-    await run.resume(
-      decision,
-      { version: 'v1', configurable: { thread_id: 't' } },
-      undefined,
-      { update, goto: 'agent' }
-    );
-
-    const cmd = spy.mock.calls[0]?.[0] as Command;
-    expect(cmd).toBeInstanceOf(Command);
-    // No interrupt was captured, so the resume value passes through unscoped.
-    expect(cmd.resume).toEqual(decision);
-    expect(cmd.update).toEqual(update);
-    expect(cmd.goto).toEqual(['agent']); // langgraph normalizes goto to an array
-
-    // Backward-compat: omitting commandOptions leaves update unset, goto empty.
-    await run.resume(decision, {
-      version: 'v1',
-      configurable: { thread_id: 't' },
-    });
-    const cmd2 = spy.mock.calls[1]?.[0] as Command;
-    expect(cmd2.update).toBeUndefined();
-    expect(cmd2.goto).toEqual([]);
-  });
-
-  it('Run.resume restores a persisted interrupt before scoping a rebuilt resume', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const registry = new HookRegistry();
-    const persistedMatcher = {
-      hooks: [async (): Promise<PreToolUseHookOutput> => ({ decision: 'ask' })],
-    };
-    registry.registerSession(
-      'persisted-hook-session',
-      'PreToolUse',
-      persistedMatcher
-    );
-
-    const run = await Run.create<t.IState>({
-      runId: 'hitl-rebuilt-scope',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: {
-              modelName: 'gpt-4o-mini',
-              apiKey: 'test-key',
-            },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    const persistedState = {
-      config: {
-        configurable: {
-          thread_id: 'durable-thread',
-          checkpoint_id: 'interrupted-checkpoint',
-          checkpoint_ns: '',
-        },
-      },
-      tasks: [
-        {
-          interrupts: [
-            {
-              id: 'persisted-interrupt',
-              value: {
-                type: 'tool_approval',
-                hook_session_id: 'persisted-hook-session',
-              },
-            },
-          ],
-        },
-      ],
-    };
-    const getState = jest.fn(async (_config: RunnableConfig) => persistedState);
-    run.graphRunnable = { getState } as unknown as t.CompiledStateWorkflow;
-    const processSpy = jest
-      .spyOn(run, 'processStream')
-      .mockResolvedValue(undefined);
-    const callerConfig = {
-      version: 'v2' as const,
-      configurable: { thread_id: 'durable-thread' },
-    };
-    const decision = [{ type: 'approve' as const }];
-
-    await run.resume(decision, callerConfig);
-
-    expect(getState).toHaveBeenCalledWith(callerConfig);
-    const command = processSpy.mock.calls[0]?.[0] as Command;
-    expect(command.resume).toEqual({ 'persisted-interrupt': decision });
-    expect(processSpy.mock.calls[0]?.[1].configurable).toMatchObject({
-      thread_id: 'durable-thread',
-      checkpoint_id: 'interrupted-checkpoint',
-      checkpoint_ns: '',
-    });
-    expect(run.getInterrupt()).toMatchObject({
-      interruptId: 'persisted-interrupt',
-      threadId: 'durable-thread',
-      payload: {
-        type: 'tool_approval',
-        hook_session_id: 'persisted-hook-session',
-      },
-    });
-    expect(
-      registry.getMatchers('PreToolUse', 'persisted-hook-session')
-    ).toEqual([persistedMatcher]);
-    expect(registry.getMatchers('PreToolUse', run.id)).toEqual([
-      persistedMatcher,
-    ]);
-  });
-
-  it('re-exports langgraph HITL primitives from the SDK barrel for host use', async () => {
-    const indexExports = await import('@/index');
-    expect(indexExports.MemorySaver).toBe(MemorySaver);
-    expect(indexExports.Command).toBe(Command);
-    expect(indexExports.INTERRUPT).toBeDefined();
-    expect(typeof indexExports.interrupt).toBe('function');
-    expect(typeof indexExports.isInterrupted).toBe('function');
-    expect(typeof indexExports.BaseCheckpointSaver).toBe('function');
-  });
-
-  it('Run.create does not attach a checkpointer when HITL is explicitly disabled', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-
-    const run = await Run.create<t.IState>({
-      runId: 'hitl-optout-run',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      humanInTheLoop: { enabled: false },
-    });
-
-    expect(run.Graph?.compileOptions?.checkpointer).toBeUndefined();
-  });
-
-  it('Run.resume() drives the host all the way through the resume command path', async () => {
-    /** End-to-end on the Run wrapper: build a HITL graph that
-     * interrupts on first invoke, then drive resume via the Run's
-     * own `resume()` method (not raw graph.invoke + Command).
-     * Validates the full Run.resume → processStream(Command) path. */
-    let dispatchCount = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCount += 1;
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'host-result',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review',
-        }),
-      ],
-    });
-
-    const hexToolCallId = '0123456789abcdef0123456789abcdef';
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([[hexToolCallId, 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode(
-        'agent',
-        (): MessagesUpdate => ({
-          messages: [
-            new AIMessage({
-              content: '',
-              tool_calls: [
-                { id: hexToolCallId, name: 'echo', args: { command: 'x' } },
-              ],
-            }),
-          ],
-        })
-      )
-      .addNode('tools', node)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId: 'run-resume-direct',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    const callerConfig = {
-      configurable: { thread_id: 'run-resume-thread' },
-      version: 'v2' as const,
-    };
-
-    await run.processStream({ messages: [] }, callerConfig);
-    expect(run.getInterrupt()).toBeDefined();
-    expect(dispatchCount).toBe(0);
-
-    /** This is the API contract under test: Run.resume() with a
-     * tool_call_id-keyed decision map (not graph.invoke + Command).
-     * The tool_call_id intentionally looks like a LangGraph interrupt
-     * id; Run.resume must still wrap it under the real interrupt id. */
-    await run.resume({ [hexToolCallId]: { type: 'approve' } }, callerConfig);
-
-    expect(dispatchCount).toBe(1);
-    /** Resume completed naturally: interrupt cleared, no halt
-     * reason carried over from the previous pass. */
-    expect(run.getInterrupt()).toBeUndefined();
-    expect(run.getHaltReason()).toBeUndefined();
-  });
-
-  it('Run.resume() forwards `update` so langgraph applies the channel edit through streamEvents', async () => {
-    /** Executing proof (not a spy): interrupt on a tool, resume with an
-     * injected message via `update`, then read the committed checkpoint.
-     * langgraph 1.4.5 maps an INPUT resume Command through `mapCommand`
-     * (pregel/io.js), which applies resume AND update AND goto, so the
-     * injected message must land in the messages channel. */
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'host-result',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review',
-        }),
-      ],
-    });
-
-    const hexToolCallId = '0123456789abcdef0123456789abcdef';
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([[hexToolCallId, 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode(
-        'agent',
-        (): MessagesUpdate => ({
-          messages: [
-            new AIMessage({
-              content: '',
-              tool_calls: [
-                { id: hexToolCallId, name: 'echo', args: { command: 'x' } },
-              ],
-            }),
-          ],
-        })
-      )
-      .addNode('tools', node)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const { HumanMessage } = await import('@langchain/core/messages');
-    const run = await Run.create<t.IState>({
-      runId: 'run-resume-update',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    const callerConfig = {
-      configurable: { thread_id: 'run-resume-update-thread' },
-      version: 'v2' as const,
-    };
-
-    await run.processStream({ messages: [] }, callerConfig);
-    expect(run.getInterrupt()).toBeDefined();
-
-    const injected = new HumanMessage({ content: 'human-injected-on-resume' });
-    await run.resume(
-      { [hexToolCallId]: { type: 'approve' } },
-      callerConfig,
-      undefined,
-      { update: { messages: [injected] } }
-    );
-
-    expect(run.getInterrupt()).toBeUndefined();
-
-    const state = await graph.getState(callerConfig);
-    const contents = (state.values.messages as BaseMessage[]).map(
-      (m) => m.content
-    );
-    /** Proves langgraph honored `update` on the INPUT resume Command. */
-    expect(contents).toContain('human-injected-on-resume');
-    /** Resume itself still completed: the approved tool produced its result. */
-    expect(contents).toContain('host-result');
-  });
-
-  it('Run.getHaltReason() reports prompt_denied when UserPromptSubmit denies the prompt', async () => {
-    const registry = new HookRegistry();
-    registry.register('UserPromptSubmit', {
-      hooks: [
-        async (): Promise<UserPromptSubmitHookOutput> => ({
-          decision: 'deny',
-          reason: 'PII detected',
-        }),
-      ],
-    });
-
-    const { Run } = await import('@/run');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    const run = await Run.create<t.IState>({
-      runId: 'prompt-deny-haltreason',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const result = await run.processStream(
-      { messages: [new HM('please tell me their SSN')] },
-      { configurable: { thread_id: 'prompt-deny-thread' }, version: 'v2' }
-    );
-
-    /** Hook denied the prompt — run returns undefined AND
-     * `getHaltReason()` carries the reason so the host can
-     * distinguish "blocked" from "natural empty completion". */
-    expect(result).toBeUndefined();
-    expect(run.getHaltReason()).toBe('PII detected');
-  });
-
-  it('Run.getHaltReason() falls back to canonical prompt_denied when deny carries no reason', async () => {
-    const registry = new HookRegistry();
-    registry.register('UserPromptSubmit', {
-      hooks: [
-        async (): Promise<UserPromptSubmitHookOutput> => ({
-          decision: 'deny',
-        }),
-      ],
-    });
-
-    const { Run } = await import('@/run');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    const run = await Run.create<t.IState>({
-      runId: 'prompt-deny-canonical',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    await run.processStream(
-      { messages: [new HM('hello')] },
-      {
-        configurable: { thread_id: 'prompt-deny-canonical-thread' },
-        version: 'v2',
-      }
-    );
-
-    /** Hook returned `deny` without a reason — host gets the
-     * canonical 'prompt_denied' string so it can route on a stable
-     * discriminator. */
-    expect(run.getHaltReason()).toBe('prompt_denied');
-  });
-
-  it('Run.getHaltReason() reports prompt_requires_approval when UserPromptSubmit asks', async () => {
-    const registry = new HookRegistry();
-    registry.register('UserPromptSubmit', {
-      hooks: [
-        async (): Promise<UserPromptSubmitHookOutput> => ({
-          decision: 'ask',
-        }),
-      ],
-    });
-
-    const { Run } = await import('@/run');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    const run = await Run.create<t.IState>({
-      runId: 'prompt-ask-haltreason',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    await run.processStream(
-      { messages: [new HM('hello')] },
-      { configurable: { thread_id: 'prompt-ask-thread' }, version: 'v2' }
-    );
-
-    /** Default reason when the hook didn't supply one — host can
-     * route on the canonical string. */
-    expect(run.getHaltReason()).toBe('prompt_requires_approval');
-  });
-});
-
-describe('ToolNode HITL — additionalContext injection from hooks', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('injects PreToolUse + PostToolUse additionalContexts as a single HumanMessage', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'host-result', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'allow',
-          additionalContext: 'pre-context: be careful',
-        }),
-      ],
-    });
-    registry.register('PostToolUse', {
-      hooks: [
-        async (): Promise<PostToolUseHookOutput> => ({
-          additionalContext: 'post-context: tool ran',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'do' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'ctx-thread-1' } }
-    )) as { messages: BaseMessage[] };
-
-    const injected = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as { additional_kwargs?: { source?: string } }).additional_kwargs
-          ?.source === 'hook'
-    );
-    expect(injected).toBeDefined();
-    expect(String(injected!.content)).toContain('pre-context: be careful');
-    expect(String(injected!.content)).toContain('post-context: tool ran');
-  });
-
-  it('does not inject anything when no hook returns additionalContext', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'host-result', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({ decision: 'allow' }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'do' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'ctx-thread-2' } }
-    )) as { messages: BaseMessage[] };
-
-    const injected = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as { additional_kwargs?: { source?: string } }).additional_kwargs
-          ?.source === 'hook'
-    );
-    expect(injected).toBeUndefined();
-  });
-});
-
-describe('ToolNode HITL — PostToolBatch hook', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('fires once per dispatch with all entries (success + error mix), in batch order', async () => {
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([
-          { toolCallId: 'call_1', content: 'ok', status: 'success' },
-          {
-            toolCallId: 'call_2',
-            content: '',
-            status: 'error',
-            errorMessage: 'boom',
-          },
-        ]);
-      });
-
-    const registry = new HookRegistry();
-    let captured: PostToolBatchEntry[] | undefined;
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (input): Promise<PostToolBatchHookOutput> => {
-          captured = (input as PostToolBatchHookInput).entries;
-          return {};
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo'), createSchemaStub('cat')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([
-        ['call_1', 'step_1'],
-        ['call_2', 'step_2'],
-      ]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'a' } },
-      { id: 'call_2', name: 'cat', args: { command: 'b' } },
-    ]);
-    await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'batch-thread' } }
-    );
-
-    expect(captured).toBeDefined();
-    expect(captured!).toHaveLength(2);
-    expect(captured![0].toolUseId).toBe('call_1');
-    expect(captured![0].status).toBe('success');
-    expect(captured![0].toolOutput).toBe('ok');
-    expect(captured![1].toolUseId).toBe('call_2');
-    expect(captured![1].status).toBe('error');
-    expect(captured![1].error).toContain('boom');
-  });
-
-  it('a PostToolBatch additionalContext gets injected as a HumanMessage', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'ok', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (): Promise<PostToolBatchHookOutput> => ({
-          additionalContext: 'remember to format the response as JSON',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'a' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'batch-ctx-thread' } }
-    )) as { messages: BaseMessage[] };
-
-    const injected = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as { additional_kwargs?: { source?: string } }).additional_kwargs
-          ?.source === 'hook'
-    );
-    expect(injected).toBeDefined();
-    expect(String(injected!.content)).toContain('format the response as JSON');
-  });
-
-  it('PostToolBatch injectedMessages land as individual HumanMessages after the consolidated context', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'ok', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (): Promise<PostToolBatchHookOutput> => ({
-          additionalContext: 'batch convention',
-          injectedMessages: [
-            { role: 'user', content: 'steer one', source: 'steer' },
-            { role: 'user', content: 'steer two', source: 'steer' },
-          ],
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'a' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'batch-steer-thread' } }
-    )) as { messages: BaseMessage[] };
-
-    type KwargMessage = {
-      additional_kwargs?: { source?: string; role?: string };
-    };
-    const humanMessages = result.messages.filter(
-      (m) => m._getType() === 'human'
-    );
-    const contextIndex = humanMessages.findIndex(
-      (m) => (m as KwargMessage).additional_kwargs?.source === 'hook'
-    );
-    const steerMessages = humanMessages.filter(
-      (m) => (m as KwargMessage).additional_kwargs?.source === 'steer'
-    );
-
-    expect(contextIndex).toBeGreaterThanOrEqual(0);
-    expect(steerMessages).toHaveLength(2);
-    expect(String(steerMessages[0].content)).toBe('steer one');
-    expect(String(steerMessages[1].content)).toBe('steer two');
-    for (const steer of steerMessages) {
-      expect((steer as KwargMessage).additional_kwargs?.role).toBe('user');
-      expect(humanMessages.indexOf(steer)).toBeGreaterThan(contextIndex);
-    }
-    const toolIndex = result.messages.findIndex((m) => m._getType() === 'tool');
-    const firstSteerIndex = result.messages.indexOf(steerMessages[0]);
-    expect(firstSteerIndex).toBeGreaterThan(toolIndex);
-  });
-
-  it('PostToolBatch injectedMessages work without additionalContext', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'ok', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (): Promise<PostToolBatchHookOutput> => ({
-          injectedMessages: [
-            { role: 'user', content: 'solo steer', source: 'steer' },
-          ],
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'a' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'solo-steer-thread' } }
-    )) as { messages: BaseMessage[] };
-
-    type KwargMessage = {
-      additional_kwargs?: { source?: string; role?: string };
-    };
-    const consolidated = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as KwargMessage).additional_kwargs?.source === 'hook'
-    );
-    const steer = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as KwargMessage).additional_kwargs?.source === 'steer'
-    );
-    expect(consolidated).toBeUndefined();
-    expect(steer).toBeDefined();
-    expect(String(steer!.content)).toBe('solo steer');
-  });
-});
-
-describe('ToolNode HITL — per-hook allowedDecisions override', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('restricts the interrupt review_configs.allowed_decisions to the hook-supplied subset', async () => {
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          allowedDecisions: ['approve', 'reject'],
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    const interrupted = await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'allowed-thread' } }
-    );
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval');
-    }
-    expect(payload.review_configs[0].allowed_decisions).toEqual([
-      'approve',
-      'reject',
-    ]);
-  });
-});
-
-describe('Run — preventContinuation honored for pre-stream hooks', () => {
-  beforeEach(() => {
-    jest.restoreAllMocks();
-  });
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('returns undefined without invoking the graph when RunStart hook returns preventContinuation', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    const registry = new HookRegistry();
-    let runStartFired = false;
-    registry.register('RunStart', {
-      hooks: [
-        async (): Promise<RunStartHookOutput> => {
-          runStartFired = true;
-          return {
-            preventContinuation: true,
-            stopReason: 'pre-flight policy halted run',
-          };
-        },
-      ],
-    });
-
-    const run = await Run.create<t.IState>({
-      runId: 'pc-runstart',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const result = await run.processStream(
-      { messages: [new HM('hello')] },
-      {
-        configurable: { thread_id: 'pc-thread-1' },
-        version: 'v2',
-      }
-    );
-
-    expect(runStartFired).toBe(true);
-    expect(result).toBeUndefined();
-    /** Graph should not have been run — no messages added beyond the input. */
-    expect(run.getInterrupt()).toBeUndefined();
-  });
-
-  it('returns undefined when UserPromptSubmit hook returns preventContinuation', async () => {
-    const { Run } = await import('@/run');
-    const { Providers } = await import('@/common');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    const registry = new HookRegistry();
-    let promptFired = false;
-    registry.register('UserPromptSubmit', {
-      hooks: [
-        async (): Promise<UserPromptSubmitHookOutput> => {
-          promptFired = true;
-          return {
-            preventContinuation: true,
-            stopReason: 'rate limit reached',
-          };
-        },
-      ],
-    });
-
-    const run = await Run.create<t.IState>({
-      runId: 'pc-prompt',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: Providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const result = await run.processStream(
-      { messages: [new HM('hello')] },
-      {
-        configurable: { thread_id: 'pc-thread-2' },
-        version: 'v2',
-      }
-    );
-
-    expect(promptFired).toBe(true);
-    expect(result).toBeUndefined();
-  });
-});
-
-describe('Mid-flight preventContinuation halts the run after the current step', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('PostToolBatch hook with preventContinuation breaks the stream loop and skips Stop', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'ok', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    let stopFired = false;
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (): Promise<PostToolBatchHookOutput> => ({
-          preventContinuation: true,
-          stopReason: 'rate-limit policy halt',
-        }),
-      ],
-    });
-    registry.register('Stop', {
-      hooks: [
-        async (): Promise<Record<string, never>> => {
-          stopFired = true;
-          return {};
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('agent', () => ({
-        messages: [
-          new AIMessage({
-            content: '',
-            tool_calls: [
-              { id: 'call_1', name: 'echo', args: { command: 'x' } },
-            ],
-          }),
-        ],
-      }))
-      .addNode('tools', node)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId: 'halt-mid-flight-1',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-    /** Replace the SDK-built graph runnable with our handcrafted one so the
-     * PostToolBatch hook fires under a real LangGraph stream. */
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      {
-        configurable: { thread_id: 'halt-thread-1' },
-        version: 'v2',
-      }
-    );
-
-    expect(run.getHaltReason()).toBe('rate-limit policy halt');
-    expect(stopFired).toBe(false);
-  });
-
-  it('clears halt signal between processStream invocations', async () => {
-    const registry = new HookRegistry();
-    registry.register('RunStart', {
-      hooks: [
-        async (): Promise<RunStartHookOutput> => ({
-          preventContinuation: true,
-          stopReason: 'first run halted',
-        }),
-      ],
-    });
-
-    const { Run } = await import('@/run');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    const run = await Run.create<t.IState>({
-      runId: 'halt-clear-1',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    await run.processStream(
-      { messages: [new HM('first')] },
-      { configurable: { thread_id: 't-1' }, version: 'v2' }
-    );
-    /** RunStart preventContinuation is a pre-stream early return, but
-     * `processStream` should still have cleared the registry signal
-     * for this run id so a subsequent call starts fresh. */
-    expect(registry.getHaltSignal('halt-clear-1')).toBeUndefined();
-  });
-});
-
-describe('Async fire-and-forget hooks ignore decision/context fields', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('PreToolUse with `async: true` does not block the tool even when decision is `deny`', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'ran', status: 'success' },
-    ]);
-
-    let bgFired = false;
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => {
-          /** Side effect runs in background; agent doesn't wait. */
-          void Promise.resolve().then(() => {
-            bgFired = true;
-          });
-          return {
-            async: true,
-            decision: 'deny',
-            reason: 'this should be ignored',
-            additionalContext: 'this should also be ignored',
-          };
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'async-1' } }
-    )) as { messages: BaseMessage[] };
-
-    const toolMsg = result.messages.find(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMsg).toBeDefined();
-    /** Tool ran (no Blocked: prefix) — async output's `decision: 'deny'` was
-     * ignored as documented. */
-    expect(toolMsg!.status).not.toBe('error');
-    expect(toolMsg!.content).toBe('ran');
-    /** Background work runs even though we ignored the output. */
-    await new Promise((r) => setImmediate(r));
-    expect(bgFired).toBe(true);
-    /** No injected context message — `additionalContext` was also ignored. */
-    const injected = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as { additional_kwargs?: { source?: string } }).additional_kwargs
-          ?.source === 'hook'
-    );
-    expect(injected).toBeUndefined();
-  });
-
-  it('PostToolUse with `async: true` does not halt the run even when preventContinuation is set', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'ran', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    registry.register('PostToolUse', {
-      hooks: [
-        async (): Promise<PostToolUseHookOutput> => ({
-          async: true,
-          preventContinuation: true,
-          stopReason: 'should not halt',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'async-2' } }
-    );
-
-    /** preventContinuation was on an async output → ignored → no halt
-     * signal raised under any session id. The standalone graph here
-     * runs with `runId = ''` (no `config.configurable.run_id` set),
-     * so check that key explicitly. */
-    expect(registry.getHaltSignal('')).toBeUndefined();
-  });
-});
-
-describe('Codex review fixes', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('reruns live hooks while replaying a consumed event-tool approval', async () => {
-    let dispatchCalls = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCalls += 1;
-        const request = data as {
-          resolve: (results: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([
-          { toolCallId: 'call_event', content: 'ran', status: 'success' },
-        ]);
-      });
-
-    const registry = new HookRegistry();
-    let onceCalls = 0;
-    let liveCalls = 0;
-    registry.register('PreToolUse', {
-      once: true,
-      pattern: '^echo$',
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => {
-          onceCalls += 1;
-          return { decision: 'ask', reason: 'review once' };
-        },
-      ],
-    });
-    registry.register('PreToolUse', {
-      pattern: '^echo$',
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => {
-          liveCalls += 1;
-          return liveCalls === 1
-            ? { decision: 'allow' }
-            : { decision: 'deny', reason: 'policy changed before resume' };
-        },
-      ],
-    });
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-event-replay',
-      toolCallStepIds: new Map([['call_event', 'step_event']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    const graph = buildHITLGraph(node, [
-      { id: 'call_event', name: 'echo', args: { command: 'run' } },
-    ]);
-    const config = {
-      configurable: { thread_id: 'thread-event-hook-replay' },
-    };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    expect(isInterrupted(interrupted)).toBe(true);
-    const resumed = await graph.invoke(
-      new Command({ resume: [{ type: 'approve' }] }),
-      config
-    );
-
-    expect(onceCalls).toBe(1);
-    expect(liveCalls).toBe(2);
-    expect(dispatchCalls).toBe(0);
-    const messages = (resumed as { messages: ToolMessage[] }).messages;
-    const result = messages.find(
-      (message) =>
-        message instanceof ToolMessage && message.tool_call_id === 'call_event'
-    );
-    expect(result?.status).toBe('error');
-    expect(String(result?.content)).toContain('policy changed before resume');
-  });
-
-  it('preserves session-scoped hooks across HITL interrupt so the policy still fires on resume', async () => {
-    let dispatchCalls = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCalls += 1;
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'host-result',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const registry = new HookRegistry();
-    let preCallCount = 0;
-    /**
-     * Register the policy hook against the runId via `registerSession`
-     * (mirrors how a host scopes per-run policy without leaking it to
-     * concurrent runs). The fix under test: this matcher MUST still be
-     * present when `Run.resume()` re-runs the node so the policy
-     * decision applies the second time too.
-     */
-    const runId = 'session-hook-preserve';
-    registry.registerSession(runId, 'PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => {
-          preCallCount += 1;
-          return { decision: 'ask', reason: 'session policy' };
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode(
-        'agent',
-        (): MessagesUpdate => ({
-          messages: [
-            new AIMessage({
-              content: '',
-              tool_calls: [
-                { id: 'call_1', name: 'echo', args: { command: 'x' } },
-              ],
-            }),
-          ],
-        })
-      )
-      .addNode('tools', node)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId,
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    const callerConfig = {
-      configurable: { thread_id: 'session-thread-1' },
-      version: 'v2' as const,
-    };
-
-    await run.processStream({ messages: [] }, callerConfig);
-
-    /** Interrupt fired; one hook invocation so far. Session matcher
-     * MUST still be present — the regression was that finally cleared
-     * it, leaving the resume to bypass the policy entirely. */
-    expect(run.getInterrupt()).toBeDefined();
-    expect(run.getInterrupt()?.payload).toMatchObject({
-      type: 'tool_approval',
-      hook_session_id: runId,
-    });
-    expect(preCallCount).toBe(1);
-    expect(registry.hasHookFor('PreToolUse', runId)).toBe(true);
-    expect(dispatchCalls).toBe(0);
-
-    await run.resume([{ type: 'approve' }], callerConfig);
-
-    /** Hook fired AGAIN on resume — policy was actually applied a
-     * second time, not skipped. Tool then executed. */
-    expect(preCallCount).toBe(2);
-    expect(dispatchCalls).toBe(1);
-    /** After natural completion, session matchers ARE cleared so the
-     * next run on this registry starts clean. */
-    expect(registry.hasHookFor('PreToolUse', runId)).toBe(false);
-  });
-
-  it('persists the parent hook session when a direct subagent approval interrupts', async () => {
-    const runId = 'parent-subagent-policy';
-    const executeSubagent = jest.fn(async () => 'child result');
-    const subagentTool = tool(executeSubagent, {
-      name: Constants.SUBAGENT,
-      description: 'execute a child agent',
-      schema: z.object({
-        description: z.string(),
-        subagent_type: z.string(),
-      }),
-    }) as unknown as StructuredToolInterface;
-    const registry = new HookRegistry();
-    registry.registerSession(runId, 'PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'approve child delegation',
-        }),
-      ],
-    });
-    const node = new ToolNode({
-      tools: [subagentTool],
-      hookRegistry: registry,
-      directToolNames: new Set([Constants.SUBAGENT]),
-      humanInTheLoop: { enabled: true },
-    });
-    const graph = buildHITLGraph(node, [
-      {
-        id: 'call_subagent',
-        name: Constants.SUBAGENT,
-        args: { description: 'inspect logs', subagent_type: 'researcher' },
-      },
-    ]);
-
-    const interrupted = await graph.invoke(
-      { messages: [] },
-      {
-        configurable: {
-          thread_id: 'parent-subagent-thread',
-          run_id: runId,
-        },
-      }
-    );
-
-    if (!isInterrupted<t.ToolApprovalInterruptPayload>(interrupted)) {
-      throw new Error('expected a subagent approval interrupt');
-    }
-    expect(interrupted.__interrupt__[0].value).toMatchObject({
-      type: 'tool_approval',
-      hook_session_id: runId,
-      action_requests: [
-        { tool_call_id: 'call_subagent', name: Constants.SUBAGENT },
-      ],
-    });
-    expect(executeSubagent).not.toHaveBeenCalled();
-  });
-
-  it('denied tool in a deny+ask batch dispatches ON_RUN_STEP_COMPLETED exactly once across interrupt + resume', async () => {
-    const stepCompletedDispatches: string[] = [];
-    /** Spy on the underlying custom event dispatcher to capture every
-     * ON_RUN_STEP_COMPLETED event with its tool_call_id. Without the
-     * blockEntry deferral, this would record `call_a` twice for one
-     * logical denial (once before interrupt, once after resume
-     * re-execution). */
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
-          const payload = data as {
-            result?: { tool_call?: { id?: string } };
-          };
-          const id = payload.result?.tool_call?.id;
-          if (id != null) {
-            stepCompletedDispatches.push(id);
-          }
-          return;
-        }
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: `ran:${c.name}`,
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (input): Promise<PreToolUseHookOutput> => {
-          if (input.toolName === 'tool_a') {
-            return { decision: 'deny', reason: 'policy:a' };
-          }
-          return { decision: 'ask', reason: 'policy:b-needs-review' };
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('tool_a'), createSchemaStub('tool_b')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([
-        ['call_a', 'step_a'],
-        ['call_b', 'step_b'],
-      ]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_a', name: 'tool_a', args: { command: 'a' } },
-      { id: 'call_b', name: 'tool_b', args: { command: 'b' } },
-    ]);
-    const config = { configurable: { thread_id: 'dedup-thread' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    /** First pass: interrupt() threw, so the deferred denial side
-     * effects were not flushed. Zero step-completed events for the
-     * denied tool yet. */
-    expect(stepCompletedDispatches.filter((id) => id === 'call_a')).toEqual([]);
-
-    await resumeGraph(graph, interrupted, [{ type: 'approve' }], config);
-
-    /** After resume: the denied tool dispatches exactly once (deferred
-     * flush on the resume re-execution); the approved tool dispatches
-     * once via the normal execution path. */
-    expect(stepCompletedDispatches.filter((id) => id === 'call_a')).toEqual([
-      'call_a',
-    ]);
-    expect(stepCompletedDispatches.filter((id) => id === 'call_b')).toEqual([
-      'call_b',
-    ]);
-  });
-
-  it('enforces allowedDecisions on resume — host-submitted decision outside the allowlist is rejected', async () => {
-    const dispatchedToolNames: string[] = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        for (const c of request.toolCalls) {
-          dispatchedToolNames.push(c.name);
-        }
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'ran',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    /** Hook restricts to approve/reject only — edit/respond are
-     * forbidden. Even if a buggy or hostile host UI submits an
-     * `edit`, the SDK must fail closed instead of mutating the args
-     * and running the tool. */
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          allowedDecisions: ['approve', 'reject'],
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original' } },
-    ]);
-    const config = { configurable: { thread_id: 'allowed-enforce' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** Submit `edit` — outside the advertised allowlist. */
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'edit', updatedInput: { command: 'malicious' } }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    /** Tool was blocked; arg-mutation never reached the host. */
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'not in allowedDecisions'
-    );
-    expect(String(toolMessages[0].content)).toContain('approve');
-    expect(String(toolMessages[0].content)).toContain('reject');
-    expect(dispatchedToolNames).toEqual([]);
-  });
-
-  it('enforces allowedDecisions on resume — approved decision passes through when in the allowlist', async () => {
-    const dispatchedArgs: Array<Record<string, unknown>> = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        for (const c of request.toolCalls) {
-          dispatchedArgs.push(c.args);
-        }
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'ran',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          allowedDecisions: ['approve', 'reject'],
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original' } },
-    ]);
-    const config = { configurable: { thread_id: 'allowed-pass' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** Submit `approve` — explicitly in the allowlist. */
-    await resumeGraph(graph, interrupted, [{ type: 'approve' }], config);
-
-    expect(dispatchedArgs).toEqual([{ command: 'original' }]);
-  });
-
-  it('getInterrupt<T>() returns the captured payload typed as the host-asserted shape', async () => {
-    /**
-     * Custom graph node raises an interrupt with a payload shape the
-     * SDK doesn't know about. `run.getInterrupt<MyCustomPayload>()`
-     * returns the payload typed as the host's assertion — the SDK
-     * doesn't validate, it just transports.
-     */
-    interface MyCustomPayload {
-      type: 'custom_review';
-      diff: string;
-      reviewerHints: string[];
-    }
-
-    const langgraph = await import('@langchain/langgraph');
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('clarifier', () => {
-        langgraph.interrupt({
-          type: 'custom_review',
-          diff: '+ added line',
-          reviewerHints: ['check formatting'],
-        } satisfies MyCustomPayload);
-        return { messages: [] };
-      })
-      .addEdge(START, 'clarifier')
-      .addEdge('clarifier', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId: 'custom-interrupt',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      humanInTheLoop: { enabled: true },
-    });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      {
-        configurable: { thread_id: 'custom-interrupt-thread' },
-        version: 'v2',
-      }
-    );
-
-    const interrupt = run.getInterrupt<MyCustomPayload>();
-    expect(interrupt).toBeDefined();
-    expect(interrupt!.payload.type).toBe('custom_review');
-    expect(interrupt!.payload.diff).toBe('+ added line');
-    expect(interrupt!.payload.reviewerHints).toEqual(['check formatting']);
-  });
-
-  it('isToolApprovalInterrupt / isAskUserQuestionInterrupt narrow safely from `unknown` (defensive)', async () => {
-    const { isToolApprovalInterrupt, isAskUserQuestionInterrupt } =
-      await import('@/types/hitl');
-
-    /** The guards must accept arbitrary runtime values without throwing,
-     * since hosts can pass anything from custom interrupts. */
-    expect(isToolApprovalInterrupt(null as unknown)).toBe(false);
-    expect(isToolApprovalInterrupt(undefined as unknown)).toBe(false);
-    expect(isToolApprovalInterrupt('string' as unknown)).toBe(false);
-    expect(isToolApprovalInterrupt(42 as unknown)).toBe(false);
-    expect(isToolApprovalInterrupt({} as unknown)).toBe(false);
-    expect(isToolApprovalInterrupt({ type: 'something_else' } as unknown)).toBe(
-      false
-    );
-    expect(
-      isToolApprovalInterrupt({
-        type: 'tool_approval',
-        action_requests: [],
-        review_configs: [],
-      } as unknown)
-    ).toBe(true);
-
-    expect(isAskUserQuestionInterrupt(null as unknown)).toBe(false);
-    expect(
-      isAskUserQuestionInterrupt({ type: 'tool_approval' } as unknown)
-    ).toBe(false);
-    expect(
-      isAskUserQuestionInterrupt({
-        type: 'ask_user_question',
-        question: { question: 'why' },
-      } as unknown)
-    ).toBe(true);
-  });
-
-  it('hook returning ask + updatedInput rewrites args BEFORE the interrupt and BEFORE host execution', async () => {
-    const dispatchedArgs: Array<Record<string, unknown>> = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        for (const c of request.toolCalls) {
-          dispatchedArgs.push(c.args);
-        }
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'ran',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    /**
-     * Hook returns BOTH a sanitization rewrite AND `ask`. Real-world
-     * pattern: one matcher redacts secrets in the args, another
-     * matcher requires human approval. Both signals must apply.
-     */
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review redacted args',
-          updatedInput: { command: 'redacted-command' },
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original-secret' } },
-    ]);
-    const config = { configurable: { thread_id: 'ask-with-update' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval');
-    }
-    /** The interrupt payload surfaces the REWRITTEN args to the
-     * reviewer, not the original. Without the fix, the reviewer
-     * would see the secret. */
-    expect(payload.action_requests[0].arguments).toEqual({
-      command: 'redacted-command',
-    });
-
-    await resumeGraph(graph, interrupted, [{ type: 'approve' }], config);
-
-    /** And the host execution dispatches the rewritten args, not
-     * the original. Without the fix, the policy redaction would be
-     * silently dropped after approval. */
-    expect(dispatchedArgs).toEqual([{ command: 'redacted-command' }]);
-  });
-
-  it('captures interrupt even when payload is null (custom node calling interrupt(null))', async () => {
-    const langgraph = await import('@langchain/langgraph');
-
-    let stopFired = false;
-    const registry = new HookRegistry();
-    registry.register('Stop', {
-      hooks: [
-        async (): Promise<Record<string, never>> => {
-          stopFired = true;
-          return {};
-        },
-      ],
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('pauser', () => {
-        /** Custom node pauses without payload — valid use case (the
-         * pause itself is the signal; no metadata needed). */
-        langgraph.interrupt(null);
-        return { messages: [] };
-      })
-      .addEdge(START, 'pauser')
-      .addEdge('pauser', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId: 'null-payload-interrupt',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      {
-        configurable: { thread_id: 'null-payload-thread' },
-        version: 'v2',
-      }
-    );
-
-    /** Run was paused, NOT completed — getInterrupt returns a result
-     * (with the null payload preserved) and the Stop hook does not
-     * fire. Without the fix, both inversions held. */
-    const interrupt = run.getInterrupt<unknown>();
-    expect(interrupt).toBeDefined();
-    expect(interrupt!.payload).toBeNull();
-    expect(stopFired).toBe(false);
-  });
-
-  it('halt signal raised by run A does not bleed into a concurrent run B sharing the same registry', async () => {
-    /**
-     * One registry, two runs. RunStart hook for run A raises
-     * preventContinuation; run B has no halt signal. Without
-     * per-session scoping, run B's stream-loop poll would see A's
-     * signal and silently terminate. With scoping, each run reads
-     * only its own halt entry.
-     */
-    const registry = new HookRegistry();
-    let runStartFires = 0;
-    registry.register('RunStart', {
-      hooks: [
-        async (input): Promise<RunStartHookOutput> => {
-          runStartFires += 1;
-          /** Halt only run A, not run B. */
-          if (input.runId === 'run-a') {
-            return {
-              preventContinuation: true,
-              stopReason: 'A halted',
-            };
-          }
-          return {};
-        },
-      ],
-    });
-
-    const { Run } = await import('@/run');
-    const { HumanMessage: HM } = await import('@langchain/core/messages');
-
-    /** No-op graph so we never hit the real model. */
-    const makeNoopGraph = (): t.CompiledStateWorkflow => {
-      const builder = new StateGraph(MessagesAnnotation)
-        .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
-        .addEdge(START, 'noop')
-        .addEdge('noop', END);
-      return builder.compile() as unknown as t.CompiledStateWorkflow;
-    };
-
-    const makeRun = async (
-      runId: string
-    ): Promise<Awaited<ReturnType<typeof Run.create<t.IState>>>> => {
-      const r = await Run.create<t.IState>({
-        runId,
-        graphConfig: {
-          type: 'standard',
-          agents: [
-            {
-              agentId: 'a',
-              provider: providers.OPENAI,
-              clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-              instructions: 'noop',
-              maxContextTokens: 8000,
-            },
-          ],
-        },
-        hooks: registry,
-        humanInTheLoop: { enabled: false },
-      });
-      r.graphRunnable = makeNoopGraph();
-      return r;
-    };
-
-    const runA = await makeRun('run-a');
-    const runB = await makeRun('run-b');
-
-    /** Run A — its preventContinuation lands in the per-session halt
-     * map under key `'run-a'` and triggers a pre-stream early
-     * return. Note that the early-return path also clears its own
-     * halt signal in the same step, so run B can never observe it
-     * even momentarily. */
-    await runA.processStream(
-      { messages: [new HM('a')] },
-      { configurable: { thread_id: 'thread-a' }, version: 'v2' }
-    );
-    expect(runA.getHaltReason()).toBe('A halted');
-
-    /** Run B's signal must be undefined — A's halt is scoped to A's
-     * session id, and was cleared in A's pre-stream finally path. */
-    expect(registry.getHaltSignal('run-b')).toBeUndefined();
-    expect(registry.getHaltSignal('run-a')).toBeUndefined();
-
-    /** Run B — RunStart returns no halt, so processStream proceeds
-     * past the pre-stream gate, executes the no-op graph, and
-     * completes without halt. */
-    runStartFires = 0;
-    await runB.processStream(
-      { messages: [new HM('b')] },
-      { configurable: { thread_id: 'thread-b' }, version: 'v2' }
-    );
-    expect(runStartFires).toBe(1);
-    expect(runB.getHaltReason()).toBeUndefined();
-  });
-
-  it('review_configs entries carry tool_call_id so duplicate-tool batches map unambiguously', async () => {
-    mockEventDispatch([]);
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review',
-        }),
-      ],
-    });
-
-    /** Same tool name called twice in one batch — by-position
-     * mapping breaks down for hosts that reorder; tool_call_id
-     * lets the UI map review_configs → action_requests directly. */
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([
-        ['call_first', 'step_first'],
-        ['call_second', 'step_second'],
-      ]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_first', name: 'echo', args: { command: 'a' } },
-      { id: 'call_second', name: 'echo', args: { command: 'b' } },
-    ]);
-    const config = { configurable: { thread_id: 'duplicate-tool' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval');
-    }
-
-    /** Each review_config carries its own tool_call_id matching the
-     * action_request at the same index. UI can build a Map keyed by
-     * tool_call_id rather than relying on positional order. */
-    expect(payload.review_configs).toEqual([
-      {
-        action_name: 'echo',
-        tool_call_id: 'call_first',
-        allowed_decisions: ['approve', 'reject', 'edit', 'respond'],
-      },
-      {
-        action_name: 'echo',
-        tool_call_id: 'call_second',
-        allowed_decisions: ['approve', 'reject', 'edit', 'respond'],
-      },
-    ]);
-    /** And the action_requests carry the same ids — pairing is
-     * always derivable from id even when names collide. */
-    expect(payload.action_requests.map((r) => r.tool_call_id)).toEqual([
-      'call_first',
-      'call_second',
-    ]);
-  });
-
-  it('malformed edit decision (missing updatedInput) is blocked, not approved with garbage args', async () => {
-    let dispatchCount = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCount += 1;
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([]);
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original' } },
-    ]);
-    const config = { configurable: { thread_id: 'edit-malformed' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** `{ type: 'edit' }` with no updatedInput — same trust-boundary
-     * issue as malformed respond. Must fail closed, NOT pass undefined
-     * into applyInputOverride and approve a tool with garbage args. */
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'edit' } as unknown as t.ToolApprovalDecision],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'missing object updatedInput'
-    );
-    expect(String(toolMessages[0].content)).toContain('<missing>');
-    expect(dispatchCount).toBe(0);
-  });
-
-  it('malformed edit decision (non-object updatedInput) is blocked', async () => {
-    let dispatchCount = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCount += 1;
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([]);
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original' } },
-    ]);
-    const config = { configurable: { thread_id: 'edit-nonobject' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** `updatedInput: 'string'` — wire deserializer didn't enforce
-     * object shape; SDK must reject. */
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [
-        {
-          type: 'edit',
-          updatedInput: 'not-an-object' as unknown as Record<string, unknown>,
-        },
-      ],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'missing object updatedInput'
-    );
-    expect(String(toolMessages[0].content)).toContain('string');
-    expect(dispatchCount).toBe(0);
-  });
-
-  it('malformed edit decision (array updatedInput) is blocked — arrays are objects but not plain records', async () => {
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async () => {
-        return;
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'original' } },
-    ]);
-    const config = { configurable: { thread_id: 'edit-array' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [
-        {
-          type: 'edit',
-          updatedInput: [1, 2, 3] as unknown as Record<string, unknown>,
-        },
-      ],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain('array');
-  });
-
-  it('malformed respond decision (missing responseText) is blocked, not crashed', async () => {
-    let dispatchCount = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCount += 1;
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([]);
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    const config = { configurable: { thread_id: 'respond-malformed' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** Submit a `respond` decision with NO responseText — wire shape
-     * the SDK can't honor. Must fail closed (blockEntry path), NOT
-     * crash truncateToolResultContent on `undefined.length`. */
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'respond' } as unknown as t.ToolApprovalDecision],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'missing string responseText'
-    );
-    expect(String(toolMessages[0].content)).toContain('<missing>');
-    /** Tool was never dispatched — fail-closed worked. */
-    expect(dispatchCount).toBe(0);
-  });
-
-  it('malformed respond decision (non-string responseText) is blocked, not crashed', async () => {
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async () => {
-        return;
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    const config = { configurable: { thread_id: 'respond-nonstring' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** `responseText: 42` — wire deserializer didn't enforce string;
-     * SDK must reject without crashing. */
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [
-        {
-          type: 'respond',
-          responseText: 42 as unknown as string,
-        },
-      ],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'missing string responseText'
-    );
-    expect(String(toolMessages[0].content)).toContain('number');
-  });
-
-  it('respond decision truncates oversized text the same way real tool output is truncated', async () => {
-    mockEventDispatch([]);
-
-    /** Build a ToolNode with a tiny `maxToolResultChars` so the
-     * truncation kicks in for a 200-char response. Without the fix,
-     * the full string would land in the ToolMessage and PostToolBatch
-     * entry — bypassing the model context budget. */
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [async (): Promise<PreToolUseHookOutput> => ({ decision: 'ask' })],
-    });
-    let captured: PostToolBatchEntry | undefined;
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (input): Promise<PostToolBatchHookOutput> => {
-          captured = (input as PostToolBatchHookInput).entries[0];
-          return {};
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-      maxToolResultChars: 50,
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'x' } },
-    ]);
-    const config = { configurable: { thread_id: 'respond-truncate' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** 200-char response — well over the 50-char cap. */
-    const oversized = 'A'.repeat(200);
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'respond', responseText: oversized }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    /** The ToolMessage content is truncated; not the raw 200 chars. */
-    const content = String(toolMessages[0].content);
-    expect(content.length).toBeLessThan(oversized.length);
-    /** And the PostToolBatch entry sees the SAME truncated value
-     * — batch hooks observe what the model will actually see. */
-    expect(captured).toBeDefined();
-    expect(typeof captured!.toolOutput).toBe('string');
-    expect(captured!.toolOutput).toBe(content);
-  });
-
-  it('hook returning both ask + preventContinuation halts cleanly and clears session hooks', async () => {
-    mockEventDispatch([]);
-
-    const registry = new HookRegistry();
-    /** Session-scoped policy hook returns BOTH `ask` (which would
-     * raise an interrupt) AND `preventContinuation: true` (which
-     * raises a halt signal). The halt wins — no resume is expected,
-     * sessions must clear. */
-    const runId = 'ask-and-halt';
-    registry.registerSession(runId, 'PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          preventContinuation: true,
-          stopReason: 'policy halted ask',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode(
-        'agent',
-        (): MessagesUpdate => ({
-          messages: [
-            new AIMessage({
-              content: '',
-              tool_calls: [
-                { id: 'call_1', name: 'echo', args: { command: 'x' } },
-              ],
-            }),
-          ],
-        })
-      )
-      .addNode('tools', node)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId,
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    await run.processStream(
-      { messages: [] },
-      {
-        configurable: { thread_id: 'ask-and-halt-thread' },
-        version: 'v2',
-      }
-    );
-
-    /** Both signals landed: interrupt was captured AND halt fired. */
-    expect(run.getInterrupt()).toBeDefined();
-    expect(run.getHaltReason()).toBe('policy halted ask');
-    /** Session hooks MUST be cleared — no resume is expected on a
-     * halted run, even one that also captured an interrupt. */
-    expect(registry.hasHookFor('PreToolUse', runId)).toBe(false);
-  });
-
-  it('preserves Graph sidecars across HITL interrupt + resume so tool completions keep their step ids', async () => {
-    /**
-     * Regression test for the cleanup-vs-resume bug: previously
-     * `processStream` always called `Graph.clearHeavyState()` in its
-     * `finally` block AND `Graph.resetValues()` on entry, even when
-     * pausing on a HITL interrupt. That wiped `toolCallStepIds`,
-     * `_toolOutputRegistry`, and `sessions` between pause and resume,
-     * so the resumed `ToolNode` could no longer find the original
-     * step id and dispatched `ON_RUN_STEP_COMPLETED` with an empty id
-     * — the host's stream consumer would then drop the result.
-     *
-     * The fix is two gated cleanups:
-     *   - `clearHeavyState` skipped when `_interrupt != null && _haltedReason == null && !streamThrew`
-     *   - `resetValues` skipped when entering processStream via `Command` (resume)
-     *
-     * To exercise the SDK Graph's actual sidecar state (not a private
-     * test ToolNode), this test wires the custom ToolNode to share
-     * the SDK Graph's `toolCallStepIds` Map by reference. After the
-     * interrupt fires AND after the resume completes, the
-     * pre-populated entry must still be present.
-     */
-    const dispatchedStepIds: string[] = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
-          const payload = data as { result?: { id?: string } };
-          if (payload.result?.id != null) {
-            dispatchedStepIds.push(payload.result.id);
-          }
-          return;
-        }
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: 'host-result',
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review',
-        }),
-      ],
-    });
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId: 'sidecar-preserve',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    /** Wire the test ToolNode to share the SDK Graph's
-     * `toolCallStepIds` Map by reference — this is how the real
-     * StandardGraph builds its inner ToolNode at Graph.ts:587. */
-    const toolNode = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'a',
-      toolCallStepIds: run.Graph!.toolCallStepIds,
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    /** The agent node simulates `attemptInvoke`'s sidecar-population
-     * step: in a real run, the model invocation creates a run step
-     * and writes its id into `toolCallStepIds` before tools dispatch.
-     * Doing it here means the entry lands AFTER `processStream`'s
-     * `resetValues` (which fires once on entry) and BEFORE the
-     * ToolNode's hook + interrupt — exactly mirroring the production
-     * timing the cleanup gate has to preserve. */
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('agent', (): MessagesUpdate => {
-        run.Graph!.toolCallStepIds.set('call_1', 'step_real_id');
-        return {
-          messages: [
-            new AIMessage({
-              content: '',
-              tool_calls: [
-                { id: 'call_1', name: 'echo', args: { command: 'x' } },
-              ],
-            }),
-          ],
-        };
-      })
-      .addNode('tools', toolNode)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    const callerConfig = {
-      configurable: { thread_id: 'sidecar-thread' },
-      version: 'v2' as const,
-    };
-
-    await run.processStream({ messages: [] }, callerConfig);
-
-    /** After interrupt: sidecar entry MUST still be present. Without
-     * the fix, `clearHeavyState` in the `finally` block would have
-     * wiped this map. */
-    expect(run.getInterrupt()).toBeDefined();
-    expect(run.Graph!.toolCallStepIds.has('call_1')).toBe(true);
-    expect(run.Graph!.toolCallStepIds.get('call_1')).toBe('step_real_id');
-
-    /** Resume: without the resetValues gate, this would also wipe
-     * the map at the START of the second processStream invocation. */
-    await run.resume([{ type: 'approve' }], callerConfig);
-
-    /** After resume completes naturally: dispatch fired with the real
-     * step id (not an empty string from a wiped map). Without either
-     * fix, `dispatchedStepIds` would contain `''`. */
-    expect(dispatchedStepIds).toContain('step_real_id');
-    expect(dispatchedStepIds).not.toContain('');
-    /** And clearHeavyState DID fire on the natural-completion side
-     * — sidecar map is now empty after the resume settled. */
-    expect(run.Graph!.toolCallStepIds.size).toBe(0);
-  });
-
-  it('clears Graph sidecars on natural completion when no interrupt was raised', async () => {
-    /** Negative case: when no interrupt fires, `clearHeavyState`
-     * MUST run as before. This pins the gate so a future change
-     * doesn't accidentally preserve sidecars on natural completion
-     * (memory leak across runs). */
-    mockEventDispatch([]);
-
-    const { Run } = await import('@/run');
-    const run = await Run.create<t.IState>({
-      runId: 'sidecar-clear-natural',
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      humanInTheLoop: { enabled: false },
-    });
-
-    /** No-op graph — runs to completion without an interrupt. */
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('noop', (): MessagesUpdate => ({ messages: [] }))
-      .addEdge(START, 'noop')
-      .addEdge('noop', END);
-    const graph = builder.compile();
-    run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    /** Stash an entry so we can verify clearHeavyState wiped it. */
-    run.Graph!.toolCallStepIds.set('stale_call', 'stale_step');
-
-    await run.processStream(
-      { messages: [] },
-      {
-        configurable: { thread_id: 'sidecar-clear-thread' },
-        version: 'v2',
-      }
-    );
-
-    /** No interrupt → clearHeavyState ran → sidecar wiped. */
-    expect(run.getInterrupt()).toBeUndefined();
-    expect(run.Graph!.toolCallStepIds.size).toBe(0);
-  });
-
-  it('clears session hooks when the stream throws AFTER an interrupt is captured (stale interrupt)', async () => {
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async () => {
-        return;
-      });
-
-    const registry = new HookRegistry();
-    const runId = 'stream-error-after-interrupt';
-    registry.registerSession(runId, 'PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'session policy',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode(
-        'agent',
-        (): MessagesUpdate => ({
-          messages: [
-            new AIMessage({
-              content: '',
-              tool_calls: [
-                { id: 'call_1', name: 'echo', args: { command: 'x' } },
-              ],
-            }),
-          ],
-        })
-      )
-      .addNode('tools', node)
-      .addEdge(START, 'agent')
-      .addEdge('agent', 'tools')
-      .addEdge('tools', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const { Run } = await import('@/run');
-    /**
-     * Holder for forward-referencing the run inside the sentinel
-     * handler closure. The handler is constructed before `Run.create`
-     * runs (it's passed into `customHandlers`) but needs to read
-     * `run.getInterrupt()` at firing time.
-     */
-    const holder: {
-      run: Awaited<ReturnType<typeof Run.create<t.IState>>> | undefined;
-    } = { run: undefined };
-
-    /**
-     * Handler keyed to a chain-stream event that throws ONLY after the
-     * interrupt has been captured. The stream loop captures the
-     * interrupt on the chunk that carries `__interrupt__`, then
-     * dispatches to handlers in the same iteration — so the throw
-     * exits the loop with `_interrupt != null`. Without the
-     * `streamThrew` guard, the `finally` block would preserve session
-     * hooks on this stale interrupt.
-     */
-    const sentinelHandler = {
-      handle: async (): Promise<void> => {
-        if (holder.run?.getInterrupt() != null) {
-          throw new Error('post-interrupt handler failure');
-        }
-      },
-    };
-
-    holder.run = await Run.create<t.IState>({
-      runId,
-      graphConfig: {
-        type: 'standard',
-        agents: [
-          {
-            agentId: 'a',
-            provider: providers.OPENAI,
-            clientOptions: { modelName: 'gpt-4o-mini', apiKey: 'test-key' },
-            instructions: 'noop',
-            maxContextTokens: 8000,
-          },
-        ],
-      },
-      hooks: registry,
-      humanInTheLoop: { enabled: true },
-      customHandlers: {
-        [GraphEvents.CHAIN_STREAM]: sentinelHandler,
-        [GraphEvents.CHAIN_END]: sentinelHandler,
-      },
-    });
-    holder.run.graphRunnable = graph as unknown as t.CompiledStateWorkflow;
-
-    const callerConfig = {
-      configurable: { thread_id: 'stale-interrupt-thread' },
-      version: 'v2' as const,
-    };
-
-    await expect(
-      holder.run.processStream({ messages: [] }, callerConfig)
-    ).rejects.toThrow('post-interrupt handler failure');
-
-    /** Interrupt WAS captured on the run instance, but because the
-     * stream subsequently threw, session hooks must be cleared so the
-     * next run on this registry isn't poisoned by stale state. */
-    expect(holder.run.getInterrupt()).toBeDefined();
-    expect(registry.hasHookFor('PreToolUse', runId)).toBe(false);
-  });
-
-  it('mixed deny/ask/allow batch: deny short-circuits, allow runs immediately, ask interrupts; resume completes the asked tool', async () => {
-    const dispatchedToolNames: string[] = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        for (const c of request.toolCalls) {
-          dispatchedToolNames.push(c.name);
-        }
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: `ran:${c.name}`,
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    /**
-     * Per-tool policy hook: tool_a denied, tool_b asks, tool_c allowed.
-     * The hook is registered without a pattern so it fires once per
-     * tool call and dispatches by tool name.
-     */
-    const registry = new HookRegistry();
-    registry.register('PreToolUse', {
-      hooks: [
-        async (input): Promise<PreToolUseHookOutput> => {
-          if (input.toolName === 'tool_a') {
-            return { decision: 'deny', reason: 'policy:a' };
-          }
-          if (input.toolName === 'tool_b') {
-            return { decision: 'ask', reason: 'policy:b-needs-review' };
-          }
-          return { decision: 'allow' };
-        },
-      ],
-    });
-    /**
-     * Listen on PostToolBatch to verify the batch entry shape after
-     * resume reflects the final outcomes (deny + run + run), not
-     * stale state from the first pass.
-     */
-    const batchSnapshots: PostToolBatchEntry[][] = [];
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (input): Promise<PostToolBatchHookOutput> => {
-          batchSnapshots.push(
-            (input as PostToolBatchHookInput).entries.map((e) => ({ ...e }))
-          );
-          return {};
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [
-        createSchemaStub('tool_a'),
-        createSchemaStub('tool_b'),
-        createSchemaStub('tool_c'),
-      ],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([
-        ['call_a', 'step_a'],
-        ['call_b', 'step_b'],
-        ['call_c', 'step_c'],
-      ]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_a', name: 'tool_a', args: { command: 'a' } },
-      { id: 'call_b', name: 'tool_b', args: { command: 'b' } },
-      { id: 'call_c', name: 'tool_c', args: { command: 'c' } },
-    ]);
-    const config = { configurable: { thread_id: 'mixed-thread' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'tool_approval') {
-      throw new Error('expected tool_approval payload');
-    }
-    /** Only tool_b appears in the interrupt — deny short-circuited
-     * locally, allow was queued for dispatch but never reached it
-     * because `interrupt()` threw inside the same node first. LangGraph
-     * rolls back the entire node's effects on throw, so no host event
-     * fires for any tool until after resume. This is the safe
-     * semantic: partial execution while a human is being asked would
-     * leak side effects ahead of approval. */
-    expect(payload.action_requests).toHaveLength(1);
-    expect(payload.action_requests[0].tool_call_id).toBe('call_b');
-    expect(dispatchedToolNames).toEqual([]);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'approve' }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    /**
-     * After resume, all three tools have ToolMessages: tool_a blocked
-     * (deny), tool_b ran (host approved), tool_c ran (allow). The
-     * ToolNode re-executed from scratch, so both tool_b and tool_c
-     * dispatch in this pass.
-     */
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(3);
-    const byId = new Map(toolMessages.map((m) => [m.tool_call_id, m]));
-    expect(byId.get('call_a')!.status).toBe('error');
-    expect(String(byId.get('call_a')!.content)).toContain('policy:a');
-    expect(byId.get('call_b')!.status).not.toBe('error');
-    expect(byId.get('call_b')!.content).toBe('ran:tool_b');
-    expect(byId.get('call_c')!.status).not.toBe('error');
-    expect(byId.get('call_c')!.content).toBe('ran:tool_c');
-    /** Both approved tools dispatched on resume; tool_a (deny) never did. */
-    expect(new Set(dispatchedToolNames)).toEqual(new Set(['tool_b', 'tool_c']));
-    expect(dispatchedToolNames).not.toContain('tool_a');
-
-    /**
-     * PostToolBatch is dispatched at the bottom of `dispatchToolEvents`,
-     * after tool execution. On the FIRST pass `interrupt()` throws
-     * before reaching that line, so PostToolBatch does NOT fire for
-     * the interrupted pass. Only the resume pass yields a snapshot —
-     * carrying all three entries with their final outcomes (tool_a
-     * blocked by deny, tool_b approved + ran, tool_c approved + ran).
-     */
-    expect(batchSnapshots).toHaveLength(1);
-    const finalSnapshot = batchSnapshots[0];
-    /**
-     * Order assertion: entries must match the original toolCalls
-     * sequence (`call_a`, `call_b`, `call_c`) regardless of when each
-     * outcome was recorded — `call_a` was denied synchronously in the
-     * hook loop, `call_b` was approved through the resume branch,
-     * `call_c` was approved+executed via the host event path. Hooks
-     * correlating outcomes by position (per the API doc) depend on
-     * this stability.
-     */
-    expect(finalSnapshot.map((e) => e.toolUseId)).toEqual([
-      'call_a',
-      'call_b',
-      'call_c',
-    ]);
-    const byCallId = new Map(finalSnapshot.map((e) => [e.toolUseId, e]));
-    expect(byCallId.size).toBe(3);
-    expect(byCallId.get('call_a')!.status).toBe('error');
-    expect(byCallId.get('call_a')!.error).toContain('policy:a');
-    expect(byCallId.get('call_b')!.status).toBe('success');
-    expect(byCallId.get('call_b')!.toolOutput).toBe('ran:tool_b');
-    expect(byCallId.get('call_c')!.status).toBe('success');
-    expect(byCallId.get('call_c')!.toolOutput).toBe('ran:tool_c');
-  });
-
-  it('mixed respond + reject in the same resume: dispatches once each, batch entries in toolCalls order', async () => {
-    const stepCompletedDispatches: string[] = [];
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event === GraphEvents.ON_RUN_STEP_COMPLETED) {
-          const payload = data as {
-            result?: { tool_call?: { id?: string } };
-          };
-          const id = payload.result?.tool_call?.id;
-          if (id != null) {
-            stepCompletedDispatches.push(id);
-          }
-          return;
-        }
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([]);
-      });
-
-    const registry = new HookRegistry();
-    /** Both tools `ask`; the resume picks `respond` for one and
-     * `reject` for the other. Exercises the timing interaction
-     * between respond's immediate dispatch and reject's deferred
-     * flush in the same resume pass. */
-    registry.register('PreToolUse', {
-      hooks: [
-        async (): Promise<PreToolUseHookOutput> => ({
-          decision: 'ask',
-          reason: 'review',
-        }),
-      ],
-    });
-    const batchSnapshots: PostToolBatchEntry[][] = [];
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (input): Promise<PostToolBatchHookOutput> => {
-          batchSnapshots.push(
-            (input as PostToolBatchHookInput).entries.map((e) => ({ ...e }))
-          );
-          return {};
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [
-        createSchemaStub('respond_tool'),
-        createSchemaStub('reject_tool'),
-      ],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([
-        ['call_respond', 'step_respond'],
-        ['call_reject', 'step_reject'],
-      ]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_respond', name: 'respond_tool', args: { command: 'r' } },
-      { id: 'call_reject', name: 'reject_tool', args: { command: 'j' } },
-    ]);
-    const config = { configurable: { thread_id: 'mixed-respond-reject' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    /** First pass: interrupt fires before either dispatch path runs. */
-    expect(stepCompletedDispatches).toEqual([]);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [
-        { type: 'respond', responseText: 'fake answer' },
-        { type: 'reject', reason: 'no thanks' },
-      ],
-      config
-    )) as { messages: BaseMessage[] };
-
-    /** Each tool dispatched ON_RUN_STEP_COMPLETED exactly once on
-     * resume — respond via its immediate path, reject via the
-     * deferred flush. */
-    expect(
-      stepCompletedDispatches.filter((id) => id === 'call_respond')
-    ).toEqual(['call_respond']);
-    expect(
-      stepCompletedDispatches.filter((id) => id === 'call_reject')
-    ).toEqual(['call_reject']);
-
-    /** PostToolBatch fires once on the resume pass, with entries in
-     * the original toolCalls order (respond first, reject second)
-     * regardless of which dispatch path landed first into the Map. */
-    expect(batchSnapshots).toHaveLength(1);
-    expect(batchSnapshots[0].map((e) => e.toolUseId)).toEqual([
-      'call_respond',
-      'call_reject',
-    ]);
-    expect(batchSnapshots[0][0].status).toBe('success');
-    expect(batchSnapshots[0][0].toolOutput).toBe('fake answer');
-    expect(batchSnapshots[0][1].status).toBe('error');
-    expect(String(batchSnapshots[0][1].error)).toContain('no thanks');
-
-    /** ToolMessage state matches: success with response text, error with reason. */
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(2);
-    const byId = new Map(toolMessages.map((m) => [m.tool_call_id, m]));
-    expect(byId.get('call_respond')!.status).not.toBe('error');
-    expect(byId.get('call_respond')!.content).toBe('fake answer');
-    expect(byId.get('call_reject')!.status).toBe('error');
-    expect(String(byId.get('call_reject')!.content)).toContain('no thanks');
-  });
-
-  it('PostToolBatch entries preserve toolCalls order even when first call is denied and second is approved', async () => {
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve(
-          request.toolCalls.map((c) => ({
-            toolCallId: c.id,
-            content: `ran:${c.name}`,
-            status: 'success' as const,
-          }))
-        );
-      });
-
-    /**
-     * Two different orderings to verify the asserted order really
-     * tracks the input — not just incidental ordering from one path
-     * landing first.
-     */
-    const cases: Array<{
-      thread: string;
-      input: Array<{ id: string; name: string; args: Record<string, unknown> }>;
-      expected: string[];
-    }> = [
-      {
-        thread: 'order-deny-first',
-        input: [
-          { id: 'call_first', name: 'denied_tool', args: { command: 'a' } },
-          { id: 'call_second', name: 'allowed_tool', args: { command: 'b' } },
-        ],
-        expected: ['call_first', 'call_second'],
-      },
-      {
-        thread: 'order-approve-first',
-        input: [
-          { id: 'call_first', name: 'allowed_tool', args: { command: 'a' } },
-          { id: 'call_second', name: 'denied_tool', args: { command: 'b' } },
-        ],
-        expected: ['call_first', 'call_second'],
-      },
-    ];
-
-    for (const { thread, input, expected } of cases) {
-      const registry = new HookRegistry();
-      registry.register('PreToolUse', {
-        hooks: [
-          async (hookInput): Promise<PreToolUseHookOutput> => {
-            if (hookInput.toolName === 'denied_tool') {
-              return { decision: 'deny', reason: 'no' };
-            }
-            return { decision: 'allow' };
-          },
-        ],
-      });
-      const captured: PostToolBatchEntry[] = [];
-      registry.register('PostToolBatch', {
-        hooks: [
-          async (i): Promise<PostToolBatchHookOutput> => {
-            captured.push(...(i as PostToolBatchHookInput).entries);
-            return {};
-          },
-        ],
-      });
-
-      const node = new ToolNode({
-        tools: [
-          createSchemaStub('denied_tool'),
-          createSchemaStub('allowed_tool'),
-        ],
-        eventDrivenMode: true,
-        agentId: 'agent-x',
-        toolCallStepIds: new Map(input.map((c) => [c.id, `step_${c.id}`])),
-        hookRegistry: registry,
-        humanInTheLoop: { enabled: false },
-      });
-
-      const graph = buildHITLGraph(node, input);
-      await graph.invoke(
-        { messages: [] },
-        { configurable: { thread_id: thread } }
-      );
-
-      expect(captured.map((e) => e.toolUseId)).toEqual(expected);
-    }
-  });
-
-  it('fails closed when the host resume payload carries an unknown decision type', async () => {
-    /** Spy MUST be reachable inside Promise.resolve handlers — must not run after mock is restored. */
-    let dispatchCalls = 0;
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        dispatchCalls += 1;
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([]);
-      });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_call_1']]),
-      hookRegistry: makeHookRegistry('ask'),
-      humanInTheLoop: { enabled: true },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'sensitive' } },
-    ]);
-    const config = { configurable: { thread_id: 'unknown-decision' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-
-    /** Host sends a typo'd / malformed decision. Must NOT silently approve. */
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      [{ type: 'aproved' as 'approve' }],
-      config
-    )) as { messages: BaseMessage[] };
-
-    const toolMessages = resumed.messages.filter(
-      (m): m is ToolMessage => m._getType() === 'tool'
-    );
-    expect(toolMessages).toHaveLength(1);
-    expect(toolMessages[0].status).toBe('error');
-    expect(String(toolMessages[0].content)).toContain(
-      'Unknown approval decision type'
-    );
-    /** Tool was never dispatched — fail-closed worked. */
-    expect(dispatchCalls).toBe(0);
-  });
-
-  it('PostToolBatch entry sees the PostToolUse-rewritten output, not the original', async () => {
-    mockEventDispatch([
-      { toolCallId: 'call_1', content: 'raw-secret-1234', status: 'success' },
-    ]);
-
-    const registry = new HookRegistry();
-    /** PostToolUse redacts the output before the model sees it. */
-    registry.register('PostToolUse', {
-      hooks: [
-        async (): Promise<PostToolUseHookOutput> => ({
-          updatedOutput: 'raw-secret-[REDACTED]',
-        }),
-      ],
-    });
-    let batchEntries: PostToolBatchEntry[] | undefined;
-    registry.register('PostToolBatch', {
-      hooks: [
-        async (input): Promise<PostToolBatchHookOutput> => {
-          batchEntries = (input as PostToolBatchHookInput).entries;
-          return {};
-        },
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'fetch' } },
-    ]);
-    await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'batch-rewrite' } }
-    );
-
-    expect(batchEntries).toBeDefined();
-    expect(batchEntries).toHaveLength(1);
-    /** Batch hook sees the redacted value, not the raw secret. */
-    expect(batchEntries![0].toolOutput).toBe('raw-secret-[REDACTED]');
-    expect(batchEntries![0].toolOutput).not.toContain('raw-secret-1234');
-  });
-
-  it('PostToolUseFailure additionalContext is injected for the next model turn', async () => {
-    /** Force the host event dispatch to return an error so the failure path runs. */
-    jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async (event, data) => {
-        if (event !== 'on_tool_execute') {
-          return;
-        }
-        const request = data as {
-          toolCalls: t.ToolCallRequest[];
-          resolve: (r: t.ToolExecuteResult[]) => void;
-        };
-        request.resolve([
-          {
-            toolCallId: 'call_1',
-            content: '',
-            status: 'error',
-            errorMessage: 'network timeout',
-          },
-        ]);
-      });
-
-    const registry = new HookRegistry();
-    registry.register('PostToolUseFailure', {
-      hooks: [
-        async (): Promise<PostToolUseFailureHookOutput> => ({
-          additionalContext:
-            'Tool failed — suggest the user retry with a smaller batch size',
-        }),
-      ],
-    });
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo')],
-      eventDrivenMode: true,
-      agentId: 'agent-x',
-      toolCallStepIds: new Map([['call_1', 'step_1']]),
-      hookRegistry: registry,
-      humanInTheLoop: { enabled: false },
-    });
-
-    const graph = buildHITLGraph(node, [
-      { id: 'call_1', name: 'echo', args: { command: 'fetch' } },
-    ]);
-    const result = (await graph.invoke(
-      { messages: [] },
-      { configurable: { thread_id: 'failure-ctx' } }
-    )) as { messages: BaseMessage[] };
-
-    const injected = result.messages.find(
-      (m) =>
-        m._getType() === 'human' &&
-        (m as { additional_kwargs?: { source?: string } }).additional_kwargs
-          ?.source === 'hook'
-    );
-    expect(injected).toBeDefined();
-    expect(String(injected!.content)).toContain(
-      'suggest the user retry with a smaller batch size'
-    );
-  });
-});
-
-describe('AskUserQuestion — interrupt + resume', () => {
-  afterEach(() => {
-    jest.restoreAllMocks();
-  });
-
-  it('a node calling askUserQuestion() raises an ask_user_question interrupt and resumes with the answer', async () => {
-    const { askUserQuestion } = await import('@/hitl');
-
-    let resumedAnswer: string | undefined;
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('clarifier', () => {
-        const resolution = askUserQuestion({
-          question: 'Which environment?',
-          options: [
-            { label: 'Staging', value: 'staging' },
-            { label: 'Production', value: 'production' },
-          ],
-        });
-        resumedAnswer = resolution.answer;
-        return { messages: [] };
-      })
-      .addEdge(START, 'clarifier')
-      .addEdge('clarifier', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const config = { configurable: { thread_id: 'ask-q-thread' } };
-
-    const interrupted = (await graph.invoke({ messages: [] }, config)) as {
-      __interrupt__?: Array<{ id?: string; value?: t.HumanInterruptPayload }>;
-    };
-    expect(interrupted.__interrupt__).toBeDefined();
-    const payload = interrupted.__interrupt__![0].value!;
-    if (payload.type !== 'ask_user_question') {
-      throw new Error('expected ask_user_question');
-    }
-    expect(payload.question.question).toBe('Which environment?');
-    expect(payload.question.options).toHaveLength(2);
-
-    const resolution: t.AskUserQuestionResolution = { answer: 'production' };
-    await resumeGraph(
-      graph as unknown as CompiledMessagesGraph,
-      interrupted,
-      resolution,
-      config
-    );
-
-    expect(resumedAnswer).toBe('production');
-  });
-
-  it('carries multiSelect through the interrupt payload and resumes with the joined option values', async () => {
-    const { askUserQuestion } = await import('@/hitl');
-
-    let resumedAnswer: string | undefined;
-
-    const builder = new StateGraph(MessagesAnnotation)
-      .addNode('clarifier', () => {
-        const resolution = askUserQuestion({
-          question: 'Which environments?',
-          options: [
-            { label: 'Staging', value: 'staging' },
-            { label: 'Production', value: 'production' },
-          ],
-          multiSelect: true,
-        });
-        resumedAnswer = resolution.answer;
-        return { messages: [] };
-      })
-      .addEdge(START, 'clarifier')
-      .addEdge('clarifier', END);
-    const graph = builder.compile({ checkpointer: new MemorySaver() });
-
-    const config = { configurable: { thread_id: 'ask-q-multi-thread' } };
-
-    const interrupted = (await graph.invoke({ messages: [] }, config)) as {
-      __interrupt__?: Array<{ id?: string; value?: t.HumanInterruptPayload }>;
-    };
-    const payload = interrupted.__interrupt__![0].value!;
-    if (payload.type !== 'ask_user_question') {
-      throw new Error('expected ask_user_question');
-    }
-    expect(payload.question.multiSelect).toBe(true);
-    expect(payload.question.options).toHaveLength(2);
-
-    // Host joins the selected option values with ", ".
-    const resolution: t.AskUserQuestionResolution = {
-      answer: 'staging, production',
-    };
-    await resumeGraph(
-      graph as unknown as CompiledMessagesGraph,
-      interrupted,
-      resolution,
-      config
-    );
-
-    expect(resumedAnswer).toBe('staging, production');
-  });
-
-  it('a DIRECT tool in event-driven mode can raise ask_user_question from its body and resume with the answer as its ToolMessage', async () => {
-    /**
-     * The production host shape (e.g. LibreChat's `AgentInputs.graphTools`
-     * plumb): the run is event-driven (other tools are schema-only
-     * definitions dispatched to the host), but an interrupt-capable tool is
-     * supplied as a real instance and marked direct so it executes inside
-     * the Pregel task frame. Event dispatch must never see the call — a
-     * host-side handler runs outside the graph, where `interrupt()` throws.
-     */
-    const { askUserQuestion } = await import('@/hitl');
-
-    const dispatchSpy = jest
-      .spyOn(events, 'safeDispatchCustomEvent')
-      .mockImplementation(async () => {});
-
-    let bodyRuns = 0;
-    const askTool = tool(
-      async (input: { question: string }) => {
-        bodyRuns += 1;
-        const resolution = askUserQuestion(input);
-        return resolution.answer;
-      },
-      {
-        name: 'ask_user_question',
-        description: 'Ask the user a clarifying question.',
-        schema: z.object({ question: z.string() }),
-      }
-    ) as unknown as StructuredToolInterface;
-
-    const node = new ToolNode({
-      tools: [createSchemaStub('echo'), askTool],
-      toolMap: new Map([
-        ['echo', createSchemaStub('echo')],
-        ['ask_user_question', askTool],
-      ]),
-      eventDrivenMode: true,
-      agentId: 'agent-ask-direct',
-      toolCallStepIds: new Map([['call_ask_1', 'step_call_ask_1']]),
-      directToolNames: new Set(['ask_user_question']),
-    });
-
-    const graph = buildHITLGraph(node, [
-      {
-        id: 'call_ask_1',
-        name: 'ask_user_question',
-        args: { question: 'Which environment?' },
-      },
-    ]);
-    const config = { configurable: { thread_id: 'thread-ask-direct' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    expect(isInterrupted<t.HumanInterruptPayload>(interrupted)).toBe(true);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'ask_user_question') {
-      throw new Error('expected ask_user_question payload');
-    }
-    expect(payload.question.question).toBe('Which environment?');
-    expect(bodyRuns).toBe(1);
-
-    /** The interrupt came from the direct path — never dispatched to the host. */
-    const toolExecuteDispatches = dispatchSpy.mock.calls.filter(
-      ([event]) => event === 'on_tool_execute'
-    );
-    expect(toolExecuteDispatches).toHaveLength(0);
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      { answer: 'staging' } satisfies t.AskUserQuestionResolution,
-      config
-    )) as MessagesUpdate;
-
-    expect(bodyRuns).toBe(2); // body re-runs from the top on the resume pass
-    const toolMessage = resumed.messages.find(
-      (m): m is ToolMessage =>
-        m._getType() === 'tool' &&
-        (m as ToolMessage).tool_call_id === 'call_ask_1'
-    );
-    expect(toolMessage).toBeDefined();
-    expect(String(toolMessage!.content)).toBe('staging');
-  });
-
-  it('askUserQuestion surfaces the calling tool_call_id on the interrupt payload when the body supplies it', async () => {
-    /**
-     * LangChain stamps the full ToolCall onto the config a `tool(fn, …)`
-     * body receives, so the body can attribute its interrupt to the exact
-     * call. Hosts use `payload.tool_call_id` to stamp the question/answer
-     * onto the right content part when a model emits several ask calls in
-     * one turn — positional guessing mislabels the cards.
-     */
-    const askTool = tool(
-      async (input: { question: string }, config) => {
-        const resolution = askUserQuestion(input, {
-          toolCallId: config.toolCall?.id,
-        });
-        return resolution.answer;
-      },
-      {
-        name: 'ask_user_question',
-        description: 'Ask the user a clarifying question.',
-        schema: z.object({ question: z.string() }),
-      }
-    ) as unknown as StructuredToolInterface;
-
-    const node = new ToolNode({ tools: [askTool] });
-    const graph = buildHITLGraph(node, [
-      {
-        id: 'call_ask_id_1',
-        name: 'ask_user_question',
-        args: { question: 'Which region?' },
-      },
-    ]);
-    const config = { configurable: { thread_id: 'thread-ask-call-id' } };
-
-    const interrupted = await graph.invoke({ messages: [] }, config);
-    if (!isInterrupted<t.HumanInterruptPayload>(interrupted)) {
-      throw new Error('expected interrupt');
-    }
-    const payload = interrupted.__interrupt__[0].value!;
-    if (payload.type !== 'ask_user_question') {
-      throw new Error('expected ask_user_question payload');
-    }
-    expect(payload.tool_call_id).toBe('call_ask_id_1');
-    expect(payload.question.question).toBe('Which region?');
-
-    const resumed = (await resumeGraph(
-      graph,
-      interrupted,
-      { answer: 'us-east' } satisfies t.AskUserQuestionResolution,
-      config
-    )) as MessagesUpdate;
-    const toolMessage = resumed.messages.find(
-      (m): m is ToolMessage =>
-        m._getType() === 'tool' &&
-        (m as ToolMessage).tool_call_id === 'call_ask_id_1'
-    );
-    expect(String(toolMessage!.content)).toBe('us-east');
-  });
-
-  it('isAskUserQuestionInterrupt narrows the payload union correctly', async () => {
-    const { isAskUserQuestionInterrupt, isToolApprovalInterrupt } =
-      await import('@/types/hitl');
-
-    const askPayload: t.HumanInterruptPayload = {
-      type: 'ask_user_question',
-      question: { question: 'why?' },
-    };
-    const approvalPayload: t.HumanInterruptPayload = {
-      type: 'tool_approval',
-      action_requests: [],
-      review_configs: [],
-    };
-
-    expect(isAskUserQuestionInterrupt(askPayload)).toBe(true);
-    expect(isAskUserQuestionInterrupt(approvalPayload)).toBe(false);
-    expect(isToolApprovalInterrupt(approvalPayload)).toBe(true);
-    expect(isToolApprovalInterrupt(askPayload)).toBe(false);
-  });
-});