@librechat/agents 3.9.5 → 3.9.7

package/src/tools/ToolNode.ts

@@ -130,8 +130,10 @@ import {
 } from '@/tools/local';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
+import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { attachRunStepResumeState } from '@/tools/runStepResume';
+import { isBackgroundDenyMode } from '@/types/hitl';
 
 function stripToolApprovalReviewConfig(
   configurable: Record<string, unknown> | undefined
@@ -1948,6 +1950,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           // they dispatch — including HITL gates on `write_file` / `edit_file`.
           hookContext: {
             registry: this.hookRegistry,
+            failClosedOnHookError:
+              isBackgroundDenyMode(this.humanInTheLoop),
             runId: (config.configurable?.run_id as string | undefined) ?? '',
             threadId: config.configurable?.thread_id as string | undefined,
             agentId: this.agentId,
@@ -2201,9 +2205,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           });
         }
       }
-      const errorContent = truncateToolResultContent(
-        `Error: ${e.message}\n Please fix your mistakes.`,
-        this.maxToolResultChars
+      const errorContent = formatToolErrorContent(
+        e.message,
+        this.maxToolResultChars,
+        config.signal,
+        e
       );
       const refMeta =
         unresolvedRefs.length > 0
@@ -2538,11 +2544,18 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             onceReplayKey: approvalReplayKey,
             onceReplaySessionId: approvalReplaySessionId,
           }).catch((): AggregatedHookResult | undefined =>
-            approvalReviewEvidence == null
+            approvalReviewEvidence == null &&
+            !isBackgroundDenyMode(this.humanInTheLoop)
               ? undefined
               : {
                 decision: 'deny',
-                reason: 'Approval policy could not be evaluated on resume',
+                reason:
+                  isBackgroundDenyMode(this.humanInTheLoop)
+                    ? 'Approval policy could not be evaluated'
+                    : 'Approval policy could not be evaluated on resume',
+                ...(isBackgroundDenyMode(this.humanInTheLoop)
+                  ? { hasHookFailures: true }
+                  : {}),
                 additionalContexts: [],
                 injectedMessages: [],
                 errors: [],
@@ -2579,6 +2592,26 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           };
         }
 
+        if (
+          preResult.hasHookFailures === true &&
+          isBackgroundDenyMode(this.humanInTheLoop)
+        ) {
+          return persistOutput(
+            this.blockDirectCall({
+              call,
+              resolvedArgs,
+              reason: this.backgroundApprovalReason(
+                call.name,
+                'Approval policy could not be evaluated'
+              ),
+              hookRegistry,
+              runId,
+              threadId,
+            }),
+            effectiveCall.args as Record<string, unknown>
+          );
+        }
+
         if (preResult.decision === 'deny') {
           return persistOutput(
             this.blockDirectCall({
@@ -2618,12 +2651,14 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
 
         if (preResult.decision === 'ask' || reviewedApproval != null) {
           if (this.humanInTheLoop?.enabled !== true) {
-            // Fail-closed: no HITL UI configured, so we can't actually
-            // ask. Logged once via the existing helper.
-            const reason = this.resolveAskDecisionForDirectTool(
-              preResult.reason,
-              call.name
-            );
+            // Fail closed when there is no foreground approval channel.
+            const reason =
+              isBackgroundDenyMode(this.humanInTheLoop)
+                ? this.backgroundApprovalReason(call.name, preResult.reason)
+                : this.resolveAskDecisionForDirectTool(
+                  preResult.reason,
+                  call.name
+                );
             return persistOutput(
               this.blockDirectCall({
                 call,
@@ -3005,6 +3040,13 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
    * LangGraph `interrupt()` instead — see `runDirectToolWithLifecycleHooks`.
    */
   private askDirectWarningEmitted = false;
+  private backgroundApprovalReason(toolName: string, reason?: string): string {
+    return (
+      `Approval required for "${toolName}"; unavailable in a background subagent. ` +
+      `Ask the parent to run it in the foreground.${reason == null ? '' : ` Reason: ${reason}`}`
+    );
+  }
+
   private resolveAskDecisionForDirectTool(
     reason: string | undefined,
     toolName: string
@@ -3623,7 +3665,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
                 matchQuery: entry.call.name,
                 onceReplayKey: approvalReplayKey,
                 onceReplaySessionId: approvalReplaySessionId,
-              }).catch((): AggregatedHookResult => HOOK_FALLBACK);
+              }).catch((): AggregatedHookResult =>
+                isBackgroundDenyMode(this.humanInTheLoop)
+                  ? { ...HOOK_FALLBACK, hasHookFailures: true }
+                  : HOOK_FALLBACK
+              );
             })
           );
 
@@ -3790,6 +3836,20 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           batchAdditionalContexts.push(ctx);
         }
 
+        if (
+          hookResult.hasHookFailures === true &&
+          isBackgroundDenyMode(this.humanInTheLoop)
+        ) {
+          blockEntry(
+            entry,
+            this.backgroundApprovalReason(
+              entry.call.name,
+              'Approval policy could not be evaluated'
+            )
+          );
+          continue;
+        }
+
         if (hookResult.decision === 'deny') {
           blockEntry(entry, hookResult.reason ?? 'Blocked by hook');
           continue;
@@ -3807,7 +3867,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
            * JSDoc for the full rationale and the migration plan.
            */
           if (this.humanInTheLoop?.enabled !== true) {
-            blockEntry(entry, hookResult.reason ?? 'Blocked by hook');
+            blockEntry(
+              entry,
+              isBackgroundDenyMode(this.humanInTheLoop)
+                ? this.backgroundApprovalReason(
+                  entry.call.name,
+                  hookResult.reason
+                )
+                : (hookResult.reason ?? 'Blocked by hook')
+            );
             continue;
           }
           /**
@@ -4461,9 +4529,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         let finalToolOutput: unknown = result.content;
 
         if (result.status === 'error') {
-          contentString = truncateToolResultContent(
-            `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`,
-            this.maxToolResultChars
+          contentString = formatToolErrorContent(
+            result.errorMessage,
+            this.maxToolResultChars,
+            config.signal
           );
           /**
            * Error results bypass registration but stamp the
@@ -4977,9 +5046,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
   ): Promise<boolean> {
     const output =
       result.status === 'error'
-        ? truncateToolResultContent(
-          `Error: ${result.errorMessage ?? 'Unknown error'}\n Please fix your mistakes.`,
-          this.maxToolResultChars
+        ? formatToolErrorContent(
+          result.errorMessage,
+          this.maxToolResultChars,
+          config.signal
         )
         : serializeToolOutputWithinLimits(
           result.content,

package/src/tools/local/LocalProgrammaticToolCalling.ts

@@ -225,6 +225,15 @@ export async function applyPreToolUseHooksForBridge(
     sessionId: hookContext.runId,
     matchQuery: toolName,
   }).catch(() => undefined);
+  if (
+    hookContext.failClosedOnHookError === true &&
+    (result == null || result.hasHookFailures === true)
+  ) {
+    return {
+      input: toolInput,
+      denyReason: `Approval policy could not be evaluated for "${toolName}" in a background subagent. Ask the parent to run it in the foreground.`,
+    };
+  }
   if (result == null) {
     return { input: toolInput };
   }
@@ -236,10 +245,13 @@ export async function applyPreToolUseHooksForBridge(
     return {
       input: nextInput,
       denyReason:
-        result.reason ??
-        (result.decision === 'ask'
-          ? `Tool "${toolName}" requires human approval; bridge cannot raise an interrupt — denying.`
-          : `Tool "${toolName}" denied by PreToolUse hook.`),
+        result.decision === 'ask' &&
+        hookContext.failClosedOnHookError === true
+          ? `Approval required for "${toolName}"; unavailable in a background subagent. Ask the parent to run it in the foreground.${result.reason == null ? '' : ` Reason: ${result.reason}`}`
+          : (result.reason ??
+            (result.decision === 'ask'
+              ? `Tool "${toolName}" requires human approval; bridge cannot raise an interrupt — denying.`
+              : `Tool "${toolName}" denied by PreToolUse hook.`)),
     };
   }
   return { input: nextInput };

package/src/tools/subagent/SubagentExecutor.ts

@@ -13,6 +13,7 @@ import {
   END,
   GraphInterrupt,
   INTERRUPT,
+  MemorySaver,
   MessagesAnnotation,
   START,
   StateGraph,
@@ -141,9 +142,10 @@ import { seedAgentInitialSessions } from '@/utils/toolSessions';
 import { stableStringify } from '@/tools/eagerEventExecution';
 import { convertInjectedMessages } from '@/messages/injected';
 import { resolveClientOptionsModel } from '@/llm/request';
+import { isBackgroundDenyMode } from '@/types/hitl';
 import { composeAbortSignals } from '@/utils/misc';
-import { sleep } from '@/utils/run';
 import { HandlerRegistry } from '@/events';
+import { sleep } from '@/utils/run';
 
 export {
   buildChildInputs,
@@ -875,6 +877,27 @@ function createSubagentFailure(
   return { content, messages: [], error };
 }
 
+function excludeBackgroundQuestionTool(agentInputs: AgentInputs): void {
+  const questionTool = 'ask_user_question';
+  agentInputs.tools = agentInputs.tools?.filter(
+    (tool) => !('name' in tool) || tool.name !== questionTool
+  );
+  agentInputs.graphTools = agentInputs.graphTools?.filter(
+    (tool) => tool.name !== questionTool
+  );
+  agentInputs.toolDefinitions = agentInputs.toolDefinitions?.filter(
+    (tool) => tool.name !== questionTool
+  );
+  if (agentInputs.toolMap?.has(questionTool) === true) {
+    agentInputs.toolMap = new Map(agentInputs.toolMap);
+    agentInputs.toolMap.delete(questionTool);
+  }
+  if (agentInputs.toolRegistry?.has(questionTool) === true) {
+    agentInputs.toolRegistry = new Map(agentInputs.toolRegistry);
+    agentInputs.toolRegistry.delete(questionTool);
+  }
+}
+
 /**
  * Factory that constructs a child graph for subagent execution. Injected
  * rather than imported so that `SubagentExecutor` does not have a runtime
@@ -1106,7 +1129,10 @@ export class SubagentExecutor {
         message: 'Maximum subagent nesting depth exceeded.',
       });
     }
-    if (this.humanInTheLoop?.enabled === true) {
+    if (
+      this.humanInTheLoop?.enabled === true &&
+      this.humanInTheLoop.backgroundPausePolicy === 'reject'
+    ) {
       return JSON.stringify({
         status: 'rejected',
         message:
@@ -1292,6 +1318,15 @@ export class SubagentExecutor {
       usageSink: this.usageSink,
       subagentContext: this.subagentContext,
       streamLimits: this.streamLimits,
+      humanInTheLoop:
+        this.humanInTheLoop?.enabled === true ||
+        this.humanInTheLoop?.backgroundPausePolicy === 'deny'
+          ? {
+            enabled: false,
+            backgroundPausePolicy: 'deny',
+            backgroundDeny: true,
+          }
+          : this.humanInTheLoop,
       maxDepth: this.maxDepth,
       createChildGraph:
         detachedGraphFactory == null
@@ -1338,6 +1373,27 @@ export class SubagentExecutor {
       if (result.error != null) {
         throw new Error(result.error);
       }
+      if (this.humanInTheLoop?.enabled === true) {
+        const deniedTools = new Set<string>();
+        for (const message of result.messages) {
+          if (
+            message instanceof ToolMessage &&
+            message.status === 'error' &&
+            typeof message.content === 'string' &&
+            message.content.startsWith('Blocked: Approval required for "') &&
+            message.name != null
+          ) {
+            deniedTools.add(message.name);
+            if (deniedTools.size >= 10) break;
+          }
+        }
+        if (deniedTools.size > 0) {
+          return {
+            ...result,
+            content: `${result.content}\nBackground approval denied for: ${[...deniedTools].join(', ')}. Ask the parent to run those tools in the foreground.`,
+          };
+        }
+      }
       return result;
     } finally {
       detached.clearHeavyState();
@@ -2489,6 +2545,11 @@ export class SubagentExecutor {
       parentMaxDepth: this.maxDepth,
       keepToolDefinitions: hasToolExecuteHandler,
     });
+    if (isBackgroundDenyMode(this.humanInTheLoop)) {
+      for (const agentInputs of childPlan.agents) {
+        excludeBackgroundQuestionTool(agentInputs);
+      }
+    }
     const childAgentId = childPlan.subjectAgentId;
     const currentHookSessionId =
       asNonEmptyString(params.hookSessionId) ??
@@ -2638,6 +2699,18 @@ export class SubagentExecutor {
       });
     }
     childGraph ??= this.createChildGraph(childGraphInput);
+    if (isBackgroundDenyMode(this.humanInTheLoop)) {
+      childGraph.humanInTheLoop = this.humanInTheLoop;
+      childGraph.eagerEventToolExecution = undefined;
+      // Never reuse the HITL parent's saver: its checkpoint namespace may
+      // contain parent messages. A private saver also lets an unexpected
+      // interrupt surface as a task error instead of a missing-saver tool
+      // error that the child could mistake for a completed task.
+      childGraph.compileOptions = {
+        ...childGraph.compileOptions,
+        checkpointer: new MemorySaver(),
+      };
+    }
     if (params.taskRuntime != null) {
       childGraph.hookRegistry = this.hookRegistry;
     }
@@ -2756,7 +2829,8 @@ export class SubagentExecutor {
         childConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY] = resumeAttemptId;
       }
       childConfigurable.thread_id =
-        this.humanInTheLoop?.enabled === true
+        this.humanInTheLoop?.enabled === true ||
+        isBackgroundDenyMode(this.humanInTheLoop)
           ? childThreadId
           : (inheritedConfigurable.thread_id ?? childRunId);
       const childInvokeConfig = {
@@ -2884,16 +2958,31 @@ export class SubagentExecutor {
             },
             sessionId: currentHookSessionId,
             matchQuery: subagentType,
-          }).catch((): AggregatedHookResult => HOOK_FALLBACK);
+          }).catch((): AggregatedHookResult =>
+            isBackgroundDenyMode(this.humanInTheLoop)
+              ? { ...HOOK_FALLBACK, hasHookFailures: true }
+              : HOOK_FALLBACK
+          );
 
-          if (hookResult.decision === 'deny' || hookResult.decision === 'ask') {
+          const policyFailed =
+            hookResult.hasHookFailures === true &&
+            isBackgroundDenyMode(this.humanInTheLoop);
+          if (
+            policyFailed ||
+            hookResult.decision === 'deny' ||
+            hookResult.decision === 'ask'
+          ) {
             this.clearChildGraph(childGraph);
             execution.releaseActiveRun();
             this.executions.remove(execution);
-            return {
-              content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
-              messages: [],
-            };
+            return policyFailed
+              ? createSubagentFailure(
+                'Subagent start policy could not be evaluated; background execution denied.'
+              )
+              : {
+                content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,
+                messages: [],
+              };
           }
         }
         execution.markStarted();
@@ -2956,7 +3045,8 @@ export class SubagentExecutor {
           };
         }
       }
-    } catch (error) {
+    } catch (caught) {
+      let error = caught;
       /** Stamped at failure, not after the error-envelope work below. */
       const childTerminalAt = Date.now();
       /**
@@ -2971,6 +3061,11 @@ export class SubagentExecutor {
        * `cancelled` here.
        */
       const abortedBeforeError = childSignal.aborted;
+      if (isGraphInterrupt(error) && params.taskRuntime != null) {
+        error = new Error(
+          'Background subagent cannot pause for human input. Run the tool in the foreground.'
+        );
+      }
       if (isGraphInterrupt(error)) {
         const activeChildRun = execution.activeRun;
         if (activeChildRun != null) {

package/src/tools/toolErrorContent.ts

@@ -0,0 +1,48 @@
+import { PreparedSubagentError } from '@/tools/preparedSubagents';
+import { truncateToolResultContent } from '@/utils/truncation';
+import { StreamLimitExceededError } from '@/llm/streamLimits';
+
+export const STOPPED_RUN_TOOL_ERROR =
+  'STOP. The user doesn\'t want to proceed with this tool use. ' +
+  'The run was stopped; the tool may not have completed, and its effects should not be assumed. ' +
+  'STOP what you are doing and wait for the user to tell you how to proceed.';
+
+/** A host result only carries error text, so require the run signal as well. */
+function isStoppedRunToolError(
+  message: string | undefined,
+  signal?: AbortSignal,
+  error?: Error
+): boolean {
+  if (
+    signal?.aborted !== true ||
+    signal.reason instanceof StreamLimitExceededError ||
+    signal.reason instanceof PreparedSubagentError
+  ) {
+    return false;
+  }
+  if (
+    (error != null && error === signal.reason) ||
+    (error instanceof Error &&
+      (error.name === 'AbortError' ||
+        ('code' in error &&
+          (error.code === 'ABORT_ERR' || error.code === 'ERR_CANCELED'))))
+  ) {
+    return true;
+  }
+  return (
+    message != null &&
+    /AbortError|(?:operation|request|stream) was aborted/i.test(message)
+  );
+}
+
+export function formatToolErrorContent(
+  message: string | undefined,
+  maxChars: number,
+  signal?: AbortSignal,
+  error?: Error
+): string {
+  const content = isStoppedRunToolError(message, signal, error)
+    ? STOPPED_RUN_TOOL_ERROR
+    : `Error: ${message ?? 'Unknown error'}\n Please fix your mistakes.`;
+  return truncateToolResultContent(content, maxChars);
+}

package/src/types/hitl.ts

@@ -407,6 +407,26 @@ export interface HumanInTheLoopConfig {
    * UI is ready to render and resolve `tool_approval` interrupts.
    */
   enabled?: boolean;
+  /**
+   * Background children cannot pause for human input. `deny` (the default)
+   * lets them run but blocks tools whose hooks request approval, and excludes
+   * `ask_user_question`. `reject` preserves the legacy admission check.
+   * Durable deferred approvals require a separate resume implementation.
+   */
+  backgroundPausePolicy?: 'deny' | 'reject';
+  /** @internal Set only on detached children and their descendants, never on the parent run. */
+  backgroundDeny?: true;
+}
+
+/** True only on an SDK-created background child, not a foreground HITL run. */
+export function isBackgroundDenyMode(
+  config: HumanInTheLoopConfig | undefined
+): boolean {
+  return (
+    config?.backgroundDeny === true &&
+    config.enabled === false &&
+    config.backgroundPausePolicy === 'deny'
+  );
 }
 
 /**

package/src/types/tools.ts

@@ -1256,6 +1256,8 @@ export type ProgrammaticCache = {
 
 export type ProgrammaticHookContext = {
   registry: import('@/hooks').HookRegistry | undefined;
+  /** A detached HITL child must never execute an inner tool if its policy hook fails. */
+  failClosedOnHookError?: boolean;
   runId: string;
   threadId?: string;
   agentId?: string;