@librechat/agents 3.1.75 → 3.1.77-dev.1

package/src/graphs/Graph.ts

@@ -129,6 +129,13 @@ export abstract class Graph<
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
   hookRegistry: HookRegistry | undefined;
+  /**
+   * Run-scoped HITL configuration. When `humanInTheLoop?.enabled` is
+   * `true`, `ToolNode` raises a real `interrupt()` for `PreToolUse`
+   * `ask` decisions instead of treating them as a synchronous deny.
+   * Threaded from `RunConfig.humanInTheLoop`.
+   */
+  humanInTheLoop: t.HumanInTheLoopConfig | undefined;
   /**
    * Run-scoped config for the tool output reference registry. Threaded
    * from `RunConfig.toolOutputReferences` down into every ToolNode this
@@ -167,6 +174,7 @@ export abstract class Graph<
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
     this.hookRegistry = undefined;
+    this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
     /**
      * ToolNodes compiled from this graph captured the registry
@@ -399,12 +407,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   ): (string | number | undefined)[] {
     if (!metadata) return [];
 
+    const configurable = this.config?.configurable;
+    const runId =
+      (metadata.run_id as string | undefined) ??
+      (configurable?.run_id as string | undefined) ??
+      this.runId;
+    const threadId =
+      (metadata.thread_id as string | undefined) ??
+      (configurable?.thread_id as string | undefined) ??
+      runId;
+    const checkpointNs =
+      (metadata.checkpoint_ns as string | undefined) ??
+      (metadata.langgraph_checkpoint_ns as string | undefined) ??
+      '';
     const keyList = [
-      metadata.run_id as string,
-      metadata.thread_id as string,
+      runId,
+      threadId,
       metadata.langgraph_node as string,
       metadata.langgraph_step as number,
-      metadata.checkpoint_ns as string,
+      checkpointNs,
     ];
 
     const agentContext = this.getAgentContext(metadata);
@@ -566,6 +587,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
         hookRegistry: this.hookRegistry,
+        humanInTheLoop: this.humanInTheLoop,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,
@@ -1461,7 +1483,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       }),
     });
     const workflow = new StateGraph(StateAnnotation)
-      .addNode(this.defaultAgentId, agentNode, { ends: [END] })
+      .addNode(
+        this.defaultAgentId,
+        agentNode as Runnable<
+          t.AgentSubgraphState,
+          Partial<t.AgentSubgraphState>
+        >,
+        { ends: [END] }
+      )
       .addEdge(START, this.defaultAgentId)
       // LangGraph compile() types are overly strict for opt-in options
       .compile(this.compileOptions as unknown as never);

package/src/graphs/__tests__/composition.smoke.test.ts

@@ -0,0 +1,188 @@
+import { HumanMessage } from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type * as t from '@/types';
+import { MultiAgentGraph } from '../MultiAgentGraph';
+import { Constants, Providers } from '@/common';
+import { StandardGraph } from '../Graph';
+
+const makeAgent = (agentId: string): t.AgentInputs => ({
+  agentId,
+  provider: Providers.OPENAI,
+  instructions: `You are ${agentId}.`,
+});
+
+const makeConfig = (threadId: string): RunnableConfig => ({
+  configurable: {
+    thread_id: threadId,
+  },
+});
+
+const makeStreamConfig = (threadId: string): t.WorkflowValuesStreamConfig => ({
+  ...makeConfig(threadId),
+  streamMode: 'values' as const,
+});
+
+const getAiContents = (messages: t.BaseGraphState['messages']): string[] =>
+  messages
+    .filter((message) => message.getType() === 'ai')
+    .map((message) => message.content)
+    .filter((content): content is string => typeof content === 'string');
+
+const expectCompiledWorkflow = (
+  workflow: t.CompiledWorkflow | t.CompiledMultiAgentWorkflow
+): void => {
+  expect(typeof workflow.invoke).toBe('function');
+  expect(typeof workflow.stream).toBe('function');
+};
+
+describe('LangGraph composition smoke tests', () => {
+  it('compiles and invokes the standard single-agent graph', async () => {
+    const graph = new StandardGraph({
+      runId: 'standard-smoke',
+      agents: [makeAgent('agent')],
+    });
+    graph.overrideTestModel(['standard ok']);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('hello')] },
+      makeConfig('standard-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toEqual(['standard ok']);
+  });
+
+  it('streams values from the standard single-agent graph', async () => {
+    const graph = new StandardGraph({
+      runId: 'standard-stream-smoke',
+      agents: [makeAgent('agent')],
+    });
+    graph.overrideTestModel(['standard stream ok']);
+
+    const workflow = graph.createWorkflow();
+    const stream = (await workflow.stream(
+      { messages: [new HumanMessage('hello')] },
+      makeStreamConfig('standard-stream-smoke')
+    )) as AsyncIterable<t.BaseGraphState>;
+    const chunks: t.BaseGraphState[] = [];
+
+    for await (const chunk of stream) {
+      chunks.push(chunk);
+    }
+
+    expect(chunks.length).toBeGreaterThan(0);
+    expect(
+      chunks.some((chunk) =>
+        getAiContents(chunk.messages).includes('standard stream ok')
+      )
+    ).toBe(true);
+  });
+
+  it('compiles and invokes a multi-agent graph with one agent and no edges', async () => {
+    const graph = new MultiAgentGraph({
+      runId: 'multi-single-smoke',
+      agents: [makeAgent('A')],
+      edges: [],
+    });
+    graph.overrideTestModel(['multi ok']);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('hello')] },
+      makeConfig('multi-single-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toEqual(['multi ok']);
+  });
+
+  it('compiles and invokes direct sequential edges', async () => {
+    const graph = new MultiAgentGraph({
+      runId: 'direct-chain-smoke',
+      agents: [makeAgent('A'), makeAgent('B')],
+      edges: [{ from: 'A', to: 'B', edgeType: 'direct' }],
+    });
+    graph.overrideTestModel(['from A', 'from B']);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('start')] },
+      makeConfig('direct-chain-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toEqual(['from A', 'from B']);
+  });
+
+  it('compiles and invokes a handoff edge using graph-managed transfer tools', async () => {
+    const transferToolCall: ToolCall = {
+      id: 'call_transfer_to_B',
+      name: `${Constants.LC_TRANSFER_TO_}B`,
+      args: { instructions: 'Take over from here.' },
+      type: 'tool_call',
+    };
+    const graph = new MultiAgentGraph({
+      runId: 'handoff-smoke',
+      agents: [makeAgent('A'), makeAgent('B')],
+      edges: [{ from: 'A', to: 'B', edgeType: 'handoff' }],
+    });
+    graph.overrideTestModel(['routing to B', 'handoff complete'], undefined, [
+      transferToolCall,
+    ]);
+
+    const workflow = graph.createWorkflow();
+    expectCompiledWorkflow(workflow);
+
+    const result = await workflow.invoke(
+      { messages: [new HumanMessage('start')] },
+      makeConfig('handoff-smoke')
+    );
+
+    expect(getAiContents(result.messages)).toContain('handoff complete');
+  });
+
+  it('compiles fan-out/fan-in direct composition with prompt wrapping', () => {
+    const graph = new MultiAgentGraph({
+      runId: 'fan-in-smoke',
+      agents: [
+        makeAgent('root'),
+        makeAgent('left'),
+        makeAgent('right'),
+        makeAgent('final'),
+      ],
+      edges: [
+        { from: 'root', to: ['left', 'right'], edgeType: 'direct' },
+        {
+          from: ['left', 'right'],
+          to: 'final',
+          edgeType: 'direct',
+          prompt: 'Summarize these results:\n{results}',
+        },
+      ],
+    });
+
+    expectCompiledWorkflow(graph.createWorkflow());
+    expect(graph.getParallelGroupId('root')).toBeUndefined();
+    expect(graph.getParallelGroupId('left')).toBe(1);
+    expect(graph.getParallelGroupId('right')).toBe(1);
+    expect(graph.getParallelGroupId('final')).toBeUndefined();
+  });
+
+  it('compiles mixed handoff and direct routing from the same agent', () => {
+    const graph = new MultiAgentGraph({
+      runId: 'mixed-routing-smoke',
+      agents: [makeAgent('router'), makeAgent('handoff'), makeAgent('direct')],
+      edges: [
+        { from: 'router', to: 'handoff', edgeType: 'handoff' },
+        { from: 'router', to: 'direct', edgeType: 'direct' },
+      ],
+    });
+
+    expectCompiledWorkflow(graph.createWorkflow());
+  });
+});

package/src/hitl/askUserQuestion.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed convenience wrapper around LangGraph's `interrupt()` for the
+ * `ask_user_question` interrupt category. Lets a custom graph node
+ * (or a tool implementation) suspend execution to collect a free-form
+ * answer from the human, without the host having to assemble the
+ * interrupt payload by hand. The companion to `Run.resume(answer)` on
+ * the host side.
+ *
+ * AsyncLocalStorage anchoring: this helper does NOT call
+ * `runWithConfig` itself — it expects to be invoked from inside a
+ * LangGraph node where the framework has already established the
+ * runnable config. ToolNode is the one place in this codebase that
+ * needs the manual `runWithConfig` shim, because its
+ * `RunnableCallable.trace = false` skips the upstream tracing path
+ * that normally sets up the AsyncLocalStorage frame; ordinary user
+ * nodes (RunnableLambda, addNode callbacks) do not have that
+ * constraint.
+ */
+
+import { interrupt } from '@langchain/langgraph';
+import type {
+  AskUserQuestionRequest,
+  AskUserQuestionResolution,
+  AskUserQuestionInterruptPayload,
+} from '@/types/hitl';
+
+/**
+ * Suspend the current graph node to ask the human a question. Returns
+ * the host-supplied resolution after `Run.resume(resolution)` is
+ * called against a Run rebuilt with the same `thread_id` and
+ * checkpointer.
+ *
+ * On the FIRST call (no resume value available), `interrupt()` throws
+ * a `GraphInterrupt` that LangGraph catches; this function does not
+ * return — execution unwinds, the SDK persists the checkpoint, and
+ * the run completes with `run.getInterrupt()` returning a
+ * `RunInterruptResult` whose `payload` is an
+ * `AskUserQuestionInterruptPayload`.
+ *
+ * On RESUME, LangGraph re-runs the node from the start and this call
+ * returns the host's `AskUserQuestionResolution` directly.
+ *
+ * Hosts that prefer the raw `interrupt()` (e.g., to attach extra
+ * metadata) can construct an `AskUserQuestionInterruptPayload` and
+ * call `interrupt()` themselves — this helper is purely convenience.
+ *
+ * @example
+ * ```ts
+ * const builder = new StateGraph(MessagesAnnotation)
+ *   .addNode('clarifier', () => {
+ *     const { answer } = askUserQuestion({
+ *       question: 'Which environment should I deploy to?',
+ *       options: [
+ *         { label: 'Staging', value: 'staging' },
+ *         { label: 'Production', value: 'production' },
+ *       ],
+ *     });
+ *     return { messages: [new HumanMessage(`Use ${answer}`)] };
+ *   });
+ * ```
+ */
+export function askUserQuestion(
+  question: AskUserQuestionRequest
+): AskUserQuestionResolution {
+  const payload: AskUserQuestionInterruptPayload = {
+    type: 'ask_user_question',
+    question,
+  };
+  return interrupt<AskUserQuestionInterruptPayload, AskUserQuestionResolution>(
+    payload
+  );
+}

package/src/hitl/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Human-in-the-loop helpers. Type definitions live in `@/types/hitl`
+ * and re-export from the top-level types barrel; runtime helpers (like
+ * `askUserQuestion()`) live here.
+ */
+
+export { askUserQuestion } from './askUserQuestion';

package/src/hooks/HookRegistry.ts

@@ -13,6 +13,20 @@ import type { HookEvent, HookMatcher } from './types';
  */
 type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 
+/**
+ * Snapshot of a halt request raised by a hook returning
+ * `preventContinuation: true`. The SDK's run loop polls for this between
+ * stream events and exits cleanly when set, skipping the `Stop` hook
+ * (the run is being halted, not naturally completing). One per registry
+ * instance — the first hook to halt wins; subsequent halts are ignored
+ * so the original reason isn't clobbered.
+ */
+export interface HookHaltSignal {
+  reason: string;
+  /** Event of the hook that triggered the halt (for diagnostics). */
+  source: HookEvent;
+}
+
 /**
  * Run-scoped storage for hook matchers with an additional layer for
  * session-scoped matchers that should be cleaned up between sessions.
@@ -34,6 +48,18 @@ type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 export class HookRegistry {
   private readonly global: MatcherBucket = {};
   private readonly sessions: Map<string, MatcherBucket> = new Map();
+  /**
+   * Per-session halt signals. Scoped by `sessionId` (= the run id the
+   * hook fired under) so a host that shares one registry across
+   * concurrent runs cannot leak `preventContinuation` from one run
+   * into another. Without scoping, a halt raised by run A's hook
+   * would trip run B's stream-loop poll on the next iteration —
+   * silently terminating an unrelated run.
+   *
+   * Map storage mirrors the reasoning above for session matchers:
+   * O(1) insertion in hot paths, no spread-on-write.
+   */
+  private readonly haltSignals: Map<string, HookHaltSignal> = new Map();
 
   /**
    * Register a matcher for the lifetime of this registry (= one Run).
@@ -125,6 +151,51 @@ export class HookRegistry {
     this.sessions.delete(sessionId);
   }
 
+  /**
+   * Raise a halt signal scoped to `sessionId` (= the run id the hook
+   * fired under). The SDK's run loop polls for this between stream
+   * events with the run's own id. First-write-wins per session: a
+   * halt already raised by an earlier hook in the same run is
+   * preserved so the original `reason` / `source` aren't overwritten.
+   *
+   * Per-session scoping is critical when hosts share one registry
+   * across concurrent runs (e.g. a global policy registered once and
+   * reused). Without it, a `preventContinuation` from run A would
+   * trip run B's stream-loop poll on the next iteration and silently
+   * terminate an unrelated run.
+   *
+   * Called by the SDK after `executeHooks` returns an aggregate with
+   * `preventContinuation: true`. Hosts can also call it directly from
+   * inside a hook callback if they want to halt without going through
+   * the aggregated return value, but `preventContinuation` is the
+   * canonical path.
+   */
+  haltRun(sessionId: string, reason: string, source: HookEvent): void {
+    if (this.haltSignals.has(sessionId)) {
+      return;
+    }
+    this.haltSignals.set(sessionId, { reason, source });
+  }
+
+  /**
+   * Returns the halt signal raised by hooks running under `sessionId`,
+   * or `undefined` if no hook in that run has halted. Polled by
+   * `Run.processStream` between stream events using the run's own id.
+   */
+  getHaltSignal(sessionId: string): HookHaltSignal | undefined {
+    return this.haltSignals.get(sessionId);
+  }
+
+  /**
+   * Clears the halt signal for `sessionId`. Called by
+   * `Run.processStream` in its `finally` block so a subsequent
+   * invocation of the same Run (e.g. resume) starts with a fresh
+   * halt state. No-op when no signal exists for that session.
+   */
+  clearHaltSignal(sessionId: string): void {
+    this.haltSignals.delete(sessionId);
+  }
+
   /** True if at least one matcher exists for `event` (global + session). */
   hasHookFor(event: HookEvent, sessionId?: string): boolean {
     if (readList(this.global, event).length > 0) {

package/src/hooks/__tests__/createToolPolicyHook.test.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect } from '@jest/globals';
+import type {
+  HookCallback,
+  PreToolUseHookInput,
+  PreToolUseHookOutput,
+} from '../types';
+import { createToolPolicyHook } from '../createToolPolicyHook';
+
+const baseInput: Omit<PreToolUseHookInput, 'toolName'> = {
+  hook_event_name: 'PreToolUse',
+  runId: 'r-1',
+  toolInput: {},
+  toolUseId: 'call-1',
+  stepId: 'step-1',
+  turn: 0,
+};
+
+async function callHook(
+  hook: HookCallback<'PreToolUse'>,
+  toolName: string
+): Promise<PreToolUseHookOutput> {
+  const signal = new AbortController().signal;
+  return await hook({ ...baseInput, toolName }, signal);
+}
+
+describe('createToolPolicyHook — default mode', () => {
+  it('asks for tools that match no rule', async () => {
+    const hook = createToolPolicyHook({ mode: 'default' });
+    expect((await callHook(hook, 'unknown_tool')).decision).toBe('ask');
+  });
+
+  it('allows tools that match an allow pattern', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_file', 'grep'],
+    });
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+    expect((await callHook(hook, 'grep')).decision).toBe('allow');
+    expect((await callHook(hook, 'write_file')).decision).toBe('ask');
+  });
+
+  it('denies tools that match a deny pattern', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      deny: ['delete_*'],
+    });
+    expect((await callHook(hook, 'delete_file')).decision).toBe('deny');
+    expect((await callHook(hook, 'read_file')).decision).toBe('ask');
+  });
+
+  it('asks tools that match an ask pattern (redundant in default mode but explicit)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_code')).decision).toBe('ask');
+  });
+});
+
+describe('createToolPolicyHook — dontAsk mode', () => {
+  it('denies tools that match no rule (no human prompt)', async () => {
+    const hook = createToolPolicyHook({ mode: 'dontAsk' });
+    expect((await callHook(hook, 'unknown_tool')).decision).toBe('deny');
+  });
+
+  it('still allows tools that match an allow pattern', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'dontAsk',
+      allow: ['read_*'],
+    });
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+    expect((await callHook(hook, 'write_file')).decision).toBe('deny');
+  });
+
+  it('still asks tools that match an explicit ask pattern (overrides dontAsk default)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'dontAsk',
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_code')).decision).toBe('ask');
+    expect((await callHook(hook, 'unknown_tool')).decision).toBe('deny');
+  });
+});
+
+describe('createToolPolicyHook — bypass mode', () => {
+  it('allows everything by default', async () => {
+    const hook = createToolPolicyHook({ mode: 'bypass' });
+    expect((await callHook(hook, 'anything')).decision).toBe('allow');
+    expect((await callHook(hook, 'execute_code')).decision).toBe('allow');
+  });
+
+  it('still denies tools that match a deny pattern (deny always wins)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'bypass',
+      deny: ['delete_*'],
+    });
+    expect((await callHook(hook, 'delete_file')).decision).toBe('deny');
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+  });
+
+  it('overrides explicit ask patterns (bypass means stop asking)', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'bypass',
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_code')).decision).toBe('allow');
+  });
+});
+
+describe('createToolPolicyHook — pattern matching', () => {
+  it('matches glob `*` wildcards', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['mcp:github:*'],
+    });
+    expect((await callHook(hook, 'mcp:github:create_issue')).decision).toBe(
+      'allow'
+    );
+    expect((await callHook(hook, 'mcp:github:list_repos')).decision).toBe(
+      'allow'
+    );
+    expect((await callHook(hook, 'mcp:slack:post')).decision).toBe('ask');
+  });
+
+  it('matches exact tool names', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_file'],
+    });
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+    expect((await callHook(hook, 'read_file_lines')).decision).toBe('ask');
+  });
+
+  it('escapes regex metacharacters in literal portions', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['tool.with.dots'],
+    });
+    expect((await callHook(hook, 'tool.with.dots')).decision).toBe('allow');
+    /** A literal regex `.` would also match `tool_with_dots`; glob shouldn't. */
+    expect((await callHook(hook, 'tool_with_dots')).decision).toBe('ask');
+  });
+
+  it('matches wildcards in the middle and end', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      ask: ['*search*'],
+    });
+    expect((await callHook(hook, 'web_search')).decision).toBe('ask');
+    expect((await callHook(hook, 'searcher')).decision).toBe('ask');
+    expect((await callHook(hook, 'read_file')).decision).toBe('ask'); // default mode
+    /** Confirm the ask path tagged it (not the fallthrough): explicit ask hits before mode fallthrough. */
+  });
+});
+
+describe('createToolPolicyHook — precedence', () => {
+  it('deny wins over allow', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_*'],
+      deny: ['read_secret'],
+    });
+    expect((await callHook(hook, 'read_secret')).decision).toBe('deny');
+    expect((await callHook(hook, 'read_file')).decision).toBe('allow');
+  });
+
+  it('deny wins over bypass mode', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'bypass',
+      deny: ['delete_*'],
+    });
+    expect((await callHook(hook, 'delete_file')).decision).toBe('deny');
+    expect((await callHook(hook, 'anything_else')).decision).toBe('allow');
+  });
+
+  it('allow wins over ask in default mode', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['execute_safe'],
+      ask: ['execute_*'],
+    });
+    expect((await callHook(hook, 'execute_safe')).decision).toBe('allow');
+    expect((await callHook(hook, 'execute_dangerous')).decision).toBe('ask');
+  });
+});
+
+describe('createToolPolicyHook — reason', () => {
+  it('attaches the configured reason to ask and deny decisions', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      deny: ['delete_*'],
+      reason: 'Tool {tool} requires manual review',
+    });
+    const denied = await callHook(hook, 'delete_file');
+    expect(denied.decision).toBe('deny');
+    expect(denied.reason).toBe('Tool delete_file requires manual review');
+
+    const asked = await callHook(hook, 'unknown_tool');
+    expect(asked.decision).toBe('ask');
+    expect(asked.reason).toBe('Tool unknown_tool requires manual review');
+  });
+
+  it('omits the reason field for allow decisions', async () => {
+    const hook = createToolPolicyHook({
+      mode: 'default',
+      allow: ['read_*'],
+      reason: 'never seen',
+    });
+    const result = await callHook(hook, 'read_file');
+    expect(result.decision).toBe('allow');
+    expect(result.reason).toBeUndefined();
+  });
+
+  it('does not add a reason field when no template is configured', async () => {
+    const hook = createToolPolicyHook({ mode: 'dontAsk' });
+    const result = await callHook(hook, 'unknown_tool');
+    expect(result.decision).toBe('deny');
+    expect(result.reason).toBeUndefined();
+  });
+});
+
+describe('createToolPolicyHook — registry integration', () => {
+  it('works when registered as a PreToolUse hook (round-trip via executeHooks)', async () => {
+    const { HookRegistry, executeHooks } = await import('../index');
+    const registry = new HookRegistry();
+    registry.register('PreToolUse', {
+      hooks: [
+        createToolPolicyHook({
+          mode: 'default',
+          allow: ['read_file'],
+          deny: ['delete_*'],
+          reason: 'review {tool}',
+        }),
+      ],
+    });
+
+    const allow = await executeHooks({
+      registry,
+      input: { ...baseInput, toolName: 'read_file' },
+      matchQuery: 'read_file',
+    });
+    expect(allow.decision).toBe('allow');
+
+    const deny = await executeHooks({
+      registry,
+      input: { ...baseInput, toolName: 'delete_file' },
+      matchQuery: 'delete_file',
+    });
+    expect(deny.decision).toBe('deny');
+    expect(deny.reason).toBe('review delete_file');
+
+    const ask = await executeHooks({
+      registry,
+      input: { ...baseInput, toolName: 'mystery_tool' },
+      matchQuery: 'mystery_tool',
+    });
+    expect(ask.decision).toBe('ask');
+  });
+});