@librechat/agents 3.1.76 → 3.1.77

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');
+  });
+});

package/src/hooks/createToolPolicyHook.ts

@@ -0,0 +1,184 @@
+/**
+ * Declarative `PreToolUse` hook factory. Lets hosts express common
+ * permission policies (allow / deny / ask lists + a global mode) without
+ * hand-rolling matching, precedence, and decision logic per-host.
+ *
+ * Maps directly to the Claude Code Agent SDK permission vocabulary
+ * (`allowed_tools` / `disallowed_tools` / `permissionMode`) so users of
+ * either SDK can think in the same terms. See the README's HITL section
+ * for the cross-walk and `docs/hooks-design-report.md` for the broader
+ * hook system context.
+ */
+
+import type { HookCallback, PreToolUseHookOutput, ToolDecision } from './types';
+
+/**
+ * Permission mode controlling how tool calls that match no rule are
+ * resolved. Mirrors Claude Code's `permissionMode`.
+ *
+ *   - `default`  — unmatched tools fall through to `'ask'` (interrupt).
+ *   - `dontAsk`  — unmatched tools are denied; the human is never
+ *                  prompted. Useful for headless / API agents where a
+ *                  silent denial is preferable to a hung interrupt.
+ *   - `bypass`   — every tool is approved, except those matching `deny`
+ *                  patterns. The kill switch you flip when you trust
+ *                  the agent and want to stop being asked. Equivalent to
+ *                  Claude Code's `bypassPermissions`.
+ */
+export type ToolPolicyMode = 'default' | 'dontAsk' | 'bypass';
+
+export interface ToolPolicyConfig {
+  /**
+   * Global mode applied to tools that don't match any rule.
+   * Defaults to `'default'` (ask the human).
+   */
+  mode?: ToolPolicyMode;
+  /**
+   * Tool name patterns that are auto-approved without a prompt.
+   * Patterns support glob `*` wildcards: `read_file`, `mcp:github:*`,
+   * `*search*`. Match is anchored (`^pattern$`).
+   */
+  allow?: readonly string[];
+  /**
+   * Tool name patterns that are blocked outright. Wins over `allow`
+   * and `ask`, and overrides `mode: 'bypass'` — a deny rule always
+   * holds, matching Claude Code's "deny rules are checked first" guarantee.
+   */
+  deny?: readonly string[];
+  /**
+   * Tool name patterns that always trigger human approval, regardless
+   * of `mode: 'default'` vs `'dontAsk'`. In `mode: 'bypass'` these are
+   * still bypassed (because that's what bypass means).
+   */
+  ask?: readonly string[];
+  /**
+   * Optional reason attached to the resulting `ask` / `deny` hook
+   * decision so the host UI can render why approval is required.
+   * The literal token `{tool}` is replaced with the tool name.
+   */
+  reason?: string;
+}
+
+/**
+ * Compile a glob string with `*` wildcards into a single anchored
+ * `RegExp`. Other regex metacharacters are escaped, so `read_file.md`
+ * matches the literal dot. Patterns are short (tool names), so we do
+ * not cache here — the registry's `matchesQuery` already caches its own
+ * regex compilations and our patterns are evaluated once per ToolNode
+ * batch, not once per stream chunk.
+ */
+function globToRegex(pattern: string): RegExp {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp('^' + escaped.replace(/\*/g, '.*') + '$');
+}
+
+/** Pre-compile a list of glob patterns into a single match function. */
+function compileMatchers(
+  patterns: readonly string[] | undefined
+): (toolName: string) => boolean {
+  if (patterns == null || patterns.length === 0) {
+    return () => false;
+  }
+  const regexes = patterns.map(globToRegex);
+  return (toolName: string): boolean => {
+    for (const regex of regexes) {
+      if (regex.test(toolName)) {
+        return true;
+      }
+    }
+    return false;
+  };
+}
+
+function formatReason(
+  template: string | undefined,
+  toolName: string
+): string | undefined {
+  if (template == null) {
+    return undefined;
+  }
+  return template.replace(/\{tool\}/g, toolName);
+}
+
+/**
+ * Build a `PreToolUse` hook callback that applies a declarative tool
+ * permission policy. Register it with a `HookRegistry` and the SDK's
+ * `humanInTheLoop` machinery handles the rest:
+ *
+ * ```ts
+ * const policyHook = createToolPolicyHook({
+ *   mode: 'default',
+ *   allow: ['read_*', 'grep', 'glob'],
+ *   deny:  ['delete_*'],
+ *   ask:   ['execute_*', 'mcp:*'],
+ * });
+ * registry.register('PreToolUse', { hooks: [policyHook] });
+ * ```
+ *
+ * Evaluation order matches Claude Code's permission flow:
+ *
+ *   1. `deny` rule match → `'deny'` (always wins, even in `bypass`).
+ *   2. `mode === 'bypass'` → `'allow'`.
+ *   3. `allow` rule match → `'allow'`.
+ *   4. `ask` rule match → `'ask'`.
+ *   5. `mode === 'dontAsk'` → `'deny'`.
+ *   6. fallthrough → `'ask'`.
+ *
+ * The returned callback is a single `HookCallback`, not a `HookMatcher` —
+ * register it under the matcher with the pattern you want (omit the
+ * pattern to fire on every tool call, which is the typical case since
+ * the policy itself does the filtering).
+ */
+export function createToolPolicyHook(
+  config: ToolPolicyConfig
+): HookCallback<'PreToolUse'> {
+  const denyMatcher = compileMatchers(config.deny);
+  const allowMatcher = compileMatchers(config.allow);
+  const askMatcher = compileMatchers(config.ask);
+  const mode: ToolPolicyMode = config.mode ?? 'default';
+  const reasonTemplate = config.reason;
+
+  return async (input): Promise<PreToolUseHookOutput> => {
+    const toolName = input.toolName;
+    const decision = decide(
+      toolName,
+      mode,
+      denyMatcher,
+      allowMatcher,
+      askMatcher
+    );
+    if (decision === 'allow') {
+      return { decision };
+    }
+    const reason = formatReason(reasonTemplate, toolName);
+    if (reason != null) {
+      return { decision, reason };
+    }
+    return { decision };
+  };
+}
+
+function decide(
+  toolName: string,
+  mode: ToolPolicyMode,
+  denyMatch: (n: string) => boolean,
+  allowMatch: (n: string) => boolean,
+  askMatch: (n: string) => boolean
+): ToolDecision {
+  if (denyMatch(toolName)) {
+    return 'deny';
+  }
+  if (mode === 'bypass') {
+    return 'allow';
+  }
+  if (allowMatch(toolName)) {
+    return 'allow';
+  }
+  if (askMatch(toolName)) {
+    return 'ask';
+  }
+  if (mode === 'dontAsk') {
+    return 'deny';
+  }
+  return 'ask';
+}

package/src/hooks/executeHooks.ts

@@ -255,6 +255,19 @@ function applyUpdatedOutput(
   agg.updatedOutput = output.updatedOutput;
 }
 
+function applyAllowedDecisions(
+  agg: AggregatedHookResult,
+  output: HookOutput
+): void {
+  if (
+    !('allowedDecisions' in output) ||
+    output.allowedDecisions === undefined
+  ) {
+    return;
+  }
+  agg.allowedDecisions = output.allowedDecisions;
+}
+
 function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
   const agg = freshResult();
   for (const outcome of outcomes) {
@@ -268,11 +281,21 @@ function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
     if (output === null) {
       continue;
     }
+    /**
+     * Skip fire-and-forget outputs entirely: the agent has already
+     * moved on, so an async hook cannot influence the run. Background
+     * work inside the hook body still runs (we don't cancel it), it
+     * just doesn't fold into the aggregate result.
+     */
+    if (output.async === true) {
+      continue;
+    }
     applyContext(agg, output);
     applyStopFlag(agg, output);
     applyDecision(agg, output);
     applyUpdatedInput(agg, output);
     applyUpdatedOutput(agg, output);
+    applyAllowedDecisions(agg, output);
   }
   return agg;
 }
@@ -371,5 +394,31 @@ export async function executeHooks(
 
   const outcomes = await Promise.all(tasks);
   reportErrors(outcomes, event, logger);
-  return fold(outcomes);
+  const aggregated = fold(outcomes);
+  /**
+   * Centralized `preventContinuation` propagation: when any hook (across
+   * any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,
+   * etc.) returns `preventContinuation: true`, raise a halt signal on
+   * the registry scoped to the run's `sessionId`. `Run.processStream`
+   * polls the signal between stream events using its own id and exits
+   * cleanly, skipping the `Stop` hook (since the run is being halted,
+   * not naturally completing).
+   *
+   * First-write-wins per session inside the registry — a halt already
+   * raised by an earlier hook in the same run is preserved so the
+   * original `reason` / `source` are not clobbered. Hooks fired
+   * without a `sessionId` cannot raise a halt (there's no run for the
+   * loop to poll under), which is fine: every in-tree callsite passes
+   * `sessionId: runId`. Pre-stream callsites in `Run.processStream`
+   * still read `preventContinuation` directly off the result for an
+   * early return because they have not yet entered the stream loop.
+   */
+  if (aggregated.preventContinuation === true && sessionId !== undefined) {
+    registry.haltRun(
+      sessionId,
+      aggregated.stopReason ?? 'preventContinuation',
+      event
+    );
+  }
+  return aggregated;
 }

package/src/hooks/index.ts

@@ -7,6 +7,7 @@
 // `createSummarizeNode` (PreCompact, PostCompact), and
 // `SubagentExecutor.execute` (SubagentStart, SubagentStop).
 export { HookRegistry } from './HookRegistry';
+export type { HookHaltSignal } from './HookRegistry';
 export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
 export {
   matchesQuery,
@@ -14,6 +15,8 @@ export {
   MAX_PATTERN_LENGTH,
   MAX_CACHE_SIZE,
 } from './matchers';
+export { createToolPolicyHook } from './createToolPolicyHook';
+export type { ToolPolicyMode, ToolPolicyConfig } from './createToolPolicyHook';
 export { HOOK_EVENTS } from './types';
 export type {
   HookEvent,
@@ -34,6 +37,8 @@ export type {
   PreToolUseHookInput,
   PostToolUseHookInput,
   PostToolUseFailureHookInput,
+  PostToolBatchHookInput,
+  PostToolBatchEntry,
   PermissionDeniedHookInput,
   SubagentStartHookInput,
   SubagentStopHookInput,
@@ -46,6 +51,7 @@ export type {
   PreToolUseHookOutput,
   PostToolUseHookOutput,
   PostToolUseFailureHookOutput,
+  PostToolBatchHookOutput,
   PermissionDeniedHookOutput,
   SubagentStartHookOutput,
   SubagentStopHookOutput,