@librechat/agents 3.4.0 → 3.4.2

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

@@ -164,6 +164,102 @@ describe('HookRegistry', () => {
       expect(registry.hasHookFor('PreToolUse', 'run-a')).toBe(true);
       expect(registry.hasHookFor('PreToolUse', 'run-b')).toBe(false);
     });
+
+    it('copies session policy without consuming the source or sibling branches', () => {
+      const registry = new HookRegistry();
+      const matcher = makePreToolUseMatcher('subagent');
+      registry.registerSession('source', 'PreToolUse', matcher);
+
+      registry.copySession('source', 'branch-a');
+      registry.copySession('source', 'branch-b');
+
+      expect(registry.getMatchers('PreToolUse', 'source')).toEqual([matcher]);
+      expect(registry.getMatchers('PreToolUse', 'branch-a')).toEqual([matcher]);
+      expect(registry.getMatchers('PreToolUse', 'branch-b')).toEqual([matcher]);
+
+      registry.clearSession('branch-a');
+      expect(registry.getMatchers('PreToolUse', 'source')).toEqual([matcher]);
+      expect(registry.getMatchers('PreToolUse', 'branch-b')).toEqual([matcher]);
+    });
+
+    it('copies pending one-shot approvals and clears them with the target session', () => {
+      const registry = new HookRegistry();
+      const approval = {
+        decision: 'ask' as const,
+        reason: 'review tool',
+        additionalContexts: [],
+        injectedMessages: [],
+        errors: [],
+      };
+      const key = {
+        executionScope: 'child-a',
+        agentId: 'researcher',
+        toolUseId: 'call_1',
+      };
+      const siblingKey = { ...key, executionScope: 'child-b' };
+      registry.setPendingToolApproval('source', key, approval);
+      registry.setPendingToolApproval('source', siblingKey, {
+        ...approval,
+        reason: 'review sibling',
+      });
+
+      registry.copySession('source', 'branch');
+
+      expect(registry.getPendingToolApproval('source', key)).toBe(approval);
+      expect(registry.getPendingToolApproval('branch', key)).toBe(approval);
+      expect(
+        registry.getPendingToolApproval('branch', siblingKey)?.reason
+      ).toBe('review sibling');
+      registry.clearPendingToolApproval('branch', key);
+      expect(registry.getPendingToolApproval('branch', key)).toBeUndefined();
+      expect(
+        registry.getPendingToolApproval('branch', siblingKey)?.reason
+      ).toBe('review sibling');
+      const checkpointSnapshot = registry.snapshotPendingToolApprovals(
+        'source',
+        'child-a'
+      );
+      expect(checkpointSnapshot).toEqual([{ key, result: approval }]);
+      registry.clearSession('branch');
+      expect(
+        registry.getPendingToolApproval('branch', siblingKey)
+      ).toBeUndefined();
+      expect(registry.getPendingToolApproval('source', key)).toBe(approval);
+      registry.setPendingToolApproval('restored', key, {
+        ...approval,
+        reason: 'stale approval',
+      });
+      registry.setPendingToolApproval('restored', siblingKey, {
+        ...approval,
+        reason: 'preserved sibling',
+      });
+      registry.restorePendingToolApprovals(
+        'restored',
+        'child-a',
+        checkpointSnapshot
+      );
+      expect(registry.getPendingToolApproval('restored', key)).toBe(approval);
+      expect(
+        registry.getPendingToolApproval('restored', siblingKey)?.reason
+      ).toBe('preserved sibling');
+      registry.restorePendingToolApprovals('restored', 'child-b', []);
+      expect(
+        registry.getPendingToolApproval('restored', siblingKey)
+      ).toBeUndefined();
+
+      const branchKey = { ...key, executionScope: 'child-a-attempt-2' };
+      registry.restorePendingToolApprovals(
+        'restored',
+        branchKey.executionScope,
+        checkpointSnapshot
+      );
+      expect(registry.getPendingToolApproval('restored', branchKey)).toBe(
+        approval
+      );
+      expect(registry.getPendingToolApproval('restored', key)).toBe(approval);
+      registry.clearPendingToolApproval('restored', branchKey);
+      expect(registry.getPendingToolApproval('restored', key)).toBe(approval);
+    });
   });
 
   describe('session isolation under parallel registration', () => {

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

@@ -764,6 +764,166 @@ describe('executeHooks', () => {
   });
 
   describe('once: true self-removal', () => {
+    it('replays a one-shot approval until the tool decision is consumed', async () => {
+      const registry = new HookRegistry();
+      let calls = 0;
+      registry.registerSession('run-1', 'PreToolUse', {
+        once: true,
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            calls += 1;
+            return { decision: 'ask', reason: 'review once' };
+          },
+        ],
+      });
+      const options = {
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+        sessionId: 'run-1',
+        onceReplayKey: {
+          executionScope: 'child-a',
+          agentId: 'researcher',
+          toolUseId: 'call_1',
+        },
+      };
+
+      await executeHooks(options);
+      const replay = await executeHooks(options);
+
+      expect(replay).toMatchObject({
+        decision: 'ask',
+        reason: 'review once',
+      });
+      expect(calls).toBe(1);
+      expect(registry.getMatchers('PreToolUse', 'run-1')).toHaveLength(0);
+
+      const sibling = await executeHooks({
+        ...options,
+        onceReplayKey: {
+          ...options.onceReplayKey,
+          executionScope: 'child-b',
+        },
+      });
+      expect(sibling.decision).toBeUndefined();
+
+      registry.clearPendingToolApproval('run-1', options.onceReplayKey);
+      const afterDecision = await executeHooks(options);
+      expect(afterDecision.decision).toBeUndefined();
+      expect(calls).toBe(1);
+    });
+
+    it('replays only one-shot contributions while rerunning ordinary hooks', async () => {
+      const registry = new HookRegistry();
+      let onceCalls = 0;
+      let ordinaryCalls = 0;
+      let ordinaryDecision: 'allow' | 'deny' = 'allow';
+      registry.registerSession('run-1', 'PreToolUse', {
+        once: true,
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            onceCalls += 1;
+            return {
+              decision: 'ask',
+              reason: 'review once',
+              additionalContext: 'once-context',
+            };
+          },
+        ],
+      });
+      registry.registerSession('run-1', 'PreToolUse', {
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            ordinaryCalls += 1;
+            return {
+              decision: ordinaryDecision,
+              reason: `ordinary-${ordinaryDecision}`,
+              additionalContext: `ordinary-${ordinaryCalls}`,
+            };
+          },
+        ],
+      });
+      const options = {
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+        sessionId: 'run-1',
+        onceReplayKey: {
+          executionScope: 'child-a',
+          agentId: 'researcher',
+          toolUseId: 'call_1',
+        },
+      };
+
+      const first = await executeHooks(options);
+      ordinaryDecision = 'deny';
+      const replay = await executeHooks(options);
+
+      expect(first.decision).toBe('ask');
+      expect(replay).toMatchObject({
+        decision: 'deny',
+        reason: 'ordinary-deny',
+        additionalContexts: ['once-context', 'ordinary-2'],
+      });
+      expect(onceCalls).toBe(1);
+      expect(ordinaryCalls).toBe(2);
+      expect(
+        registry.getPendingToolApproval('run-1', options.onceReplayKey)
+      ).toBeUndefined();
+    });
+
+    it('retains a consumed one-shot rewrite when an ordinary hook asks', async () => {
+      const registry = new HookRegistry();
+      let onceCalls = 0;
+      let ordinaryCalls = 0;
+      registry.registerSession('run-1', 'PreToolUse', {
+        once: true,
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            onceCalls += 1;
+            return {
+              decision: 'allow',
+              updatedInput: { command: 'sanitized' },
+            };
+          },
+        ],
+      });
+      registry.registerSession('run-1', 'PreToolUse', {
+        hooks: [
+          async (): Promise<PreToolUseHookOutput> => {
+            ordinaryCalls += 1;
+            return { decision: 'ask', reason: 'ordinary approval' };
+          },
+        ],
+      });
+      const options = {
+        registry,
+        input: preToolUseInput('Bash'),
+        matchQuery: 'Bash',
+        sessionId: 'run-1',
+        onceReplayKey: {
+          executionScope: 'child-a',
+          agentId: 'researcher',
+          toolUseId: 'call_1',
+        },
+      };
+
+      const first = await executeHooks(options);
+      const replay = await executeHooks(options);
+
+      expect(first).toMatchObject({
+        decision: 'ask',
+        updatedInput: { command: 'sanitized' },
+      });
+      expect(replay).toMatchObject({
+        decision: 'ask',
+        reason: 'ordinary approval',
+        updatedInput: { command: 'sanitized' },
+      });
+      expect(onceCalls).toBe(1);
+      expect(ordinaryCalls).toBe(2);
+    });
+
     it('removes the matcher after a successful fire', async () => {
       const registry = new HookRegistry();
       let calls = 0;

package/src/hooks/executeHooks.ts

@@ -8,6 +8,7 @@ import type {
   ToolDecision,
   StopDecision,
   HookCallback,
+  ToolApprovalReplayKey,
   AggregatedHookResult,
 } from './types';
 import type { HookRegistry } from './HookRegistry';
@@ -28,6 +29,10 @@ export interface ExecuteHooksOptions {
   sessionId?: string;
   /** Query string matched against each matcher's pattern (tool name, etc.). */
   matchQuery?: string;
+  /** Stable tool-call key for replaying consumed one-shot contributions. */
+  onceReplayKey?: ToolApprovalReplayKey;
+  /** Storage scope for replay state when it must outlive or branch from the hook session. */
+  onceReplaySessionId?: string;
   /** Parent AbortSignal — combined with per-hook timeout into the hook signal. */
   signal?: AbortSignal;
   /** Default per-hook timeout; overridden by `matcher.timeout` when present. */
@@ -301,12 +306,79 @@ function applyAllowedDecisions(
   agg.allowedDecisions = output.allowedDecisions;
 }
 
-function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
-  const agg = freshResult();
+function applyAggregatedResult(
+  target: AggregatedHookResult,
+  source: AggregatedHookResult
+): void {
+  target.additionalContexts.push(...source.additionalContexts);
+  target.injectedMessages.push(...source.injectedMessages);
+  target.errors.push(...source.errors);
+  if (source.decision != null) {
+    applyToolDecision(target, source.decision, source.reason);
+  }
+  if (source.stopDecision != null) {
+    applyStopDecision(target, source.stopDecision, source.reason);
+  }
+  if (source.updatedInput != null) {
+    target.updatedInput = source.updatedInput;
+  }
+  if (source.updatedOutput !== undefined) {
+    target.updatedOutput = source.updatedOutput;
+  }
+  if (source.allowedDecisions != null) {
+    target.allowedDecisions = source.allowedDecisions;
+  }
+  if (source.preventContinuation === true) {
+    target.preventContinuation = true;
+    target.stopReason ??= source.stopReason;
+  }
+}
+
+function combineAggregatedResults(
+  first: AggregatedHookResult | undefined,
+  second: AggregatedHookResult
+): AggregatedHookResult {
+  if (first == null) {
+    return second;
+  }
+  const combined = freshResult();
+  applyAggregatedResult(combined, first);
+  applyAggregatedResult(combined, second);
+  return combined;
+}
+
+function createPendingApprovalReplay(
+  approvalResult: AggregatedHookResult,
+  pendingApproval: AggregatedHookResult | undefined,
+  onceContribution: AggregatedHookResult
+): AggregatedHookResult {
+  const replay = freshResult();
+  if (pendingApproval != null) {
+    applyAggregatedResult(replay, pendingApproval);
+  }
+  applyAggregatedResult(replay, onceContribution);
+  replay.decision = 'ask';
+  replay.reason = approvalResult.reason;
+  if (approvalResult.allowedDecisions == null) {
+    delete replay.allowedDecisions;
+  } else {
+    replay.allowedDecisions = approvalResult.allowedDecisions;
+  }
+  return replay;
+}
+
+function fold(outcomes: readonly HookOutcome[]): {
+  aggregated: AggregatedHookResult;
+  onceReplayContribution?: AggregatedHookResult;
+} {
+  const aggregated = freshResult();
+  const onceContribution = freshResult();
+  let hasOnceContribution = false;
   for (const outcome of outcomes) {
+    const isOnceMatcher = outcome.matcher.once === true;
     if (outcome.error !== null) {
       if (outcome.matcher.internal !== true) {
-        agg.errors.push(outcome.error);
+        aggregated.errors.push(outcome.error);
       }
       continue;
     }
@@ -323,15 +395,28 @@ function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
     if (output.async === true) {
       continue;
     }
-    applyContext(agg, output);
-    applyInjectedMessages(agg, output);
-    applyStopFlag(agg, output);
-    applyDecision(agg, output);
-    applyUpdatedInput(agg, output);
-    applyUpdatedOutput(agg, output);
-    applyAllowedDecisions(agg, output);
-  }
-  return agg;
+    const targets = isOnceMatcher
+      ? [aggregated, onceContribution]
+      : [aggregated];
+    if (isOnceMatcher) {
+      hasOnceContribution = true;
+    }
+    for (const target of targets) {
+      applyContext(target, output);
+      applyInjectedMessages(target, output);
+      applyStopFlag(target, output);
+      applyDecision(target, output);
+      applyUpdatedInput(target, output);
+      applyUpdatedOutput(target, output);
+      applyAllowedDecisions(target, output);
+    }
+  }
+  return {
+    aggregated,
+    ...(hasOnceContribution
+      ? { onceReplayContribution: onceContribution }
+      : {}),
+  };
 }
 
 /**
@@ -396,14 +481,21 @@ export async function executeHooks(
     input,
     sessionId,
     matchQuery,
+    onceReplayKey,
+    onceReplaySessionId,
     signal,
     timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,
     logger,
   } = opts;
   const event = input.hook_event_name;
+  const replaySessionId = onceReplaySessionId ?? sessionId;
+  const pendingApproval =
+    event === 'PreToolUse' && replaySessionId != null && onceReplayKey != null
+      ? registry.getPendingToolApproval(replaySessionId, onceReplayKey)
+      : undefined;
   const matchers = registry.getMatchers(event, sessionId);
   if (matchers.length === 0) {
-    return freshResult();
+    return pendingApproval ?? freshResult();
   }
 
   // --- SYNC CRITICAL SECTION: once-matcher removal must complete before any await ---
@@ -424,12 +516,38 @@ export async function executeHooks(
   }
   // --- END SYNC CRITICAL SECTION ---
   if (tasks.length === 0) {
-    return freshResult();
+    return pendingApproval ?? freshResult();
   }
 
   const outcomes = (await Promise.all(tasks)).flat();
   reportErrors(outcomes, event, logger);
-  const aggregated = fold(outcomes);
+  const { aggregated: liveResult, onceReplayContribution } = fold(outcomes);
+  const aggregated = combineAggregatedResults(pendingApproval, liveResult);
+  if (
+    event === 'PreToolUse' &&
+    aggregated.decision === 'ask' &&
+    onceReplayContribution != null &&
+    replaySessionId != null &&
+    onceReplayKey != null
+  ) {
+    registry.setPendingToolApproval(
+      replaySessionId,
+      onceReplayKey,
+      createPendingApprovalReplay(
+        aggregated,
+        pendingApproval,
+        onceReplayContribution
+      )
+    );
+  } else if (
+    event === 'PreToolUse' &&
+    aggregated.decision !== 'ask' &&
+    pendingApproval != null &&
+    replaySessionId != null &&
+    onceReplayKey != null
+  ) {
+    registry.clearPendingToolApproval(replaySessionId, onceReplayKey);
+  }
   /**
    * Centralized `preventContinuation` propagation: when any hook (across
    * any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,

package/src/hooks/index.ts

@@ -42,7 +42,7 @@ export type {
   WorkspacePolicyConfig,
   PathExtractor,
 } from './createWorkspacePolicyHook';
-export { HOOK_EVENTS } from './types';
+export { HOOK_EVENTS, TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY } from './types';
 export type {
   HookEvent,
   HookInput,
@@ -56,6 +56,8 @@ export type {
   BaseHookOutput,
   ToolDecision,
   StopDecision,
+  ToolApprovalReplayKey,
+  ToolApprovalReplaySnapshot,
   AggregatedHookResult,
   RunStartHookInput,
   UserPromptSubmitHookInput,

package/src/hooks/types.ts

@@ -27,6 +27,9 @@ export const HOOK_EVENTS = [
   'PostCompact',
 ] as const;
 
+export const TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY =
+  '__librechat_tool_approval_execution_scope';
+
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 
 /** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
@@ -393,6 +396,19 @@ export interface PreToolUseHookOutput extends BaseHookOutput {
   allowedDecisions?: ReadonlyArray<'approve' | 'reject' | 'edit' | 'respond'>;
 }
 
+/** Stable identity for replaying a consumed one-shot tool approval. */
+export interface ToolApprovalReplayKey {
+  executionScope: string;
+  agentId: string;
+  toolUseId: string;
+}
+
+/** Checkpoint-safe copy of a consumed one-shot approval contribution. */
+export interface ToolApprovalReplaySnapshot {
+  key: ToolApprovalReplayKey;
+  result: AggregatedHookResult;
+}
+
 export interface PostToolUseHookOutput extends BaseHookOutput {
   /**
    * Replacement tool output. Flows through the aggregated result so the