@librechat/agents 3.1.66 → 3.1.67-dev.0

package/dist/esm/tools/subagent/SubagentExecutor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"SubagentExecutor.mjs","sources":["../../../../src/tools/subagent/SubagentExecutor.ts"],"sourcesContent":["import { nanoid } from 'nanoid';\nimport { HumanMessage } from '@langchain/core/messages';\nimport type { BaseMessage } from '@langchain/core/messages';\nimport type {\n  AgentInputs,\n  StandardGraphInput,\n  ResolvedSubagentConfig,\n  SubagentConfig,\n  TokenCounter,\n} from '@/types';\nimport type { AggregatedHookResult, HookRegistry } from '@/hooks';\nimport type { AgentContext } from '@/agents/AgentContext';\nimport type { StandardGraph } from '@/graphs/Graph';\nimport { executeHooks } from '@/hooks';\n\nconst DEFAULT_MAX_TURNS = 25;\nconst RECURSION_MULTIPLIER = 3;\nconst ERROR_MESSAGE_MAX_CHARS = 200;\n\nconst HOOK_FALLBACK: AggregatedHookResult = Object.freeze({\n  additionalContexts: [] as string[],\n  errors: [] as string[],\n});\n\nexport type SubagentExecuteParams = {\n  description: string;\n  subagentType: string;\n  threadId?: string;\n};\n\nexport type SubagentExecuteResult = {\n  content: string;\n  messages: BaseMessage[];\n};\n\n/**\n * Factory that constructs a child graph for subagent execution. Injected\n * rather than imported so that `SubagentExecutor` does not have a runtime\n * dependency on `StandardGraph` — this avoids a circular dependency between\n * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break\n * Rollup's chunking under `preserveModules`.\n */\nexport type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;\n\nexport type SubagentExecutorOptions = {\n  configs: Map<string, ResolvedSubagentConfig>;\n  parentSignal?: AbortSignal;\n  hookRegistry?: HookRegistry;\n  parentRunId: string;\n  parentAgentId?: string;\n  tokenCounter?: TokenCounter;\n  /** Remaining nesting budget. 0 or negative blocks execution. */\n  maxDepth?: number;\n  /**\n   * Factory for constructing the isolated child graph. Callers pass\n   * `(input) => new StandardGraph(input)` — injected to break a circular\n   * module dependency.\n   */\n  createChildGraph: ChildGraphFactory;\n};\n\nexport class SubagentExecutor {\n  private readonly configs: Map<string, ResolvedSubagentConfig>;\n  private readonly parentSignal?: AbortSignal;\n  private readonly hookRegistry?: HookRegistry;\n  private readonly parentRunId: string;\n  private readonly parentAgentId?: string;\n  private readonly tokenCounter?: TokenCounter;\n  private readonly maxDepth: number;\n  private readonly createChildGraph: ChildGraphFactory;\n\n  constructor(options: SubagentExecutorOptions) {\n    this.configs = options.configs;\n    this.parentSignal = options.parentSignal;\n    this.hookRegistry = options.hookRegistry;\n    this.parentRunId = options.parentRunId;\n    this.parentAgentId = options.parentAgentId;\n    this.tokenCounter = options.tokenCounter;\n    this.maxDepth = options.maxDepth ?? 1;\n    this.createChildGraph = options.createChildGraph;\n  }\n\n  async execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult> {\n    const { description, subagentType, threadId } = params;\n    const config = this.configs.get(subagentType);\n\n    if (!config) {\n      const available = [...this.configs.keys()].join(', ');\n      return {\n        content: `Error: Unknown subagent type \"${subagentType}\". Available types: ${available}`,\n        messages: [],\n      };\n    }\n\n    if (this.maxDepth <= 0) {\n      return {\n        content: 'Error: Maximum subagent nesting depth exceeded.',\n        messages: [],\n      };\n    }\n\n    const childAgentId =\n      config.agentInputs.agentId ||\n      `${this.parentAgentId ?? 'agent'}_sub_${nanoid(8)}`;\n\n    if (\n      this.hookRegistry?.hasHookFor('SubagentStart', this.parentRunId) === true\n    ) {\n      const hookResult = await executeHooks({\n        registry: this.hookRegistry,\n        input: {\n          hook_event_name: 'SubagentStart',\n          runId: this.parentRunId,\n          threadId,\n          parentAgentId: this.parentAgentId,\n          agentId: childAgentId,\n          agentType: subagentType,\n          inputs: [new HumanMessage(description)],\n        },\n        sessionId: this.parentRunId,\n        matchQuery: subagentType,\n      }).catch((): AggregatedHookResult => HOOK_FALLBACK);\n\n      /**\n       * `ask` is treated identically to `deny` in the subagent context:\n       * subagents are non-interactive, so there is no prompt path for `ask`.\n       * Both decisions block execution and return a \"Blocked\" tool result.\n       */\n      if (hookResult.decision === 'deny' || hookResult.decision === 'ask') {\n        return {\n          content: `Blocked: ${hookResult.reason ?? 'Blocked by hook'}`,\n          messages: [],\n        };\n      }\n    }\n\n    const childInputs = buildChildInputs(config, childAgentId, this.maxDepth);\n    const childRunId = `${this.parentRunId}_sub_${nanoid(8)}`;\n    const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;\n\n    const childGraph = this.createChildGraph({\n      runId: childRunId,\n      signal: this.parentSignal,\n      agents: [childInputs],\n      tokenCounter: this.tokenCounter,\n    });\n\n    let result: { messages: BaseMessage[] };\n    try {\n      const workflow = childGraph.createWorkflow();\n      /**\n       * Detach the child invocation from the parent's callback chain.\n       * Without this, `streamEvents` in the parent's `Run.processStream`\n       * captures events from the child graph's LLM calls (e.g.\n       * `on_chat_model_stream` for the \"researcher\" agent) and delivers\n       * them to the parent's handlers. The parent then tries to resolve\n       * the child's agent ID in its own `agentContexts` map and throws\n       * \"No agent context found for agent ID …\". Setting `callbacks: []`\n       * overrides the inherited callbacks for this invoke; combined with\n       * the child's own empty `handlerRegistry`/`hookRegistry`, the child\n       * runs fully isolated.\n       *\n       * `runName` gives the child a distinct LangSmith trace root (avoids\n       * nested trace pollution).\n       */\n      result = await workflow.invoke(\n        { messages: [new HumanMessage(description)] },\n        {\n          recursionLimit: maxTurns * RECURSION_MULTIPLIER,\n          signal: this.parentSignal,\n          callbacks: [],\n          runName: `subagent:${subagentType}`,\n          configurable: {\n            thread_id: childRunId,\n          },\n        }\n      );\n    } catch (error) {\n      childGraph.clearHeavyState();\n      return {\n        content: `Subagent error: ${truncateErrorMessage(error)}`,\n        messages: [],\n      };\n    }\n\n    const filteredContent = filterSubagentResult(result.messages);\n\n    if (\n      this.hookRegistry?.hasHookFor('SubagentStop', this.parentRunId) === true\n    ) {\n      /**\n       * Awaited (not fire-and-forget) for deterministic test synchronization\n       * and consistency with PostCompact. The parent is already waiting on the\n       * tool result, so the small extra latency is acceptable. Errors are\n       * swallowed — SubagentStop is observational.\n       */\n      await executeHooks({\n        registry: this.hookRegistry,\n        input: {\n          hook_event_name: 'SubagentStop',\n          runId: this.parentRunId,\n          threadId,\n          agentId: childAgentId,\n          agentType: subagentType,\n          messages: result.messages,\n        },\n        sessionId: this.parentRunId,\n        matchQuery: subagentType,\n      }).catch(() => {\n        /* SubagentStop is observational — swallow errors */\n      });\n    }\n\n    childGraph.clearHeavyState();\n\n    return { content: filteredContent, messages: result.messages };\n  }\n}\n\n/**\n * Walk messages from last to first, returning the text content of the most\n * recent AIMessage that has any. Non-text blocks (tool_use, thinking,\n * redacted_thinking, tool_result) are stripped. If the last AIMessage is\n * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk\n * continues to earlier AIMessages so partial progress is salvaged — this\n * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.\n * Returns \"Task completed\" only when no AIMessage in the history contains\n * any text.\n */\nexport function filterSubagentResult(messages: BaseMessage[]): string {\n  for (let i = messages.length - 1; i >= 0; i--) {\n    if (messages[i]._getType() !== 'ai') {\n      continue;\n    }\n\n    const content = messages[i].content;\n\n    if (typeof content === 'string') {\n      if (content) return content;\n      continue;\n    }\n\n    if (!Array.isArray(content)) {\n      continue;\n    }\n\n    const textParts: string[] = [];\n    for (const block of content) {\n      if (typeof block === 'string') {\n        textParts.push(block);\n      } else if ('type' in block && block.type === 'text' && 'text' in block) {\n        textParts.push(block.text as string);\n      }\n    }\n\n    if (textParts.length > 0) {\n      return textParts.join('\\n');\n    }\n  }\n\n  return 'Task completed';\n}\n\n/**\n * Resolve self-spawn configs by filling in agentInputs from the parent context.\n * Returns configs with agentInputs guaranteed present. Throws on duplicate\n * `type` values to prevent silent config shadowing.\n */\nexport function resolveSubagentConfigs(\n  configs: SubagentConfig[],\n  parentContext: AgentContext\n): ResolvedSubagentConfig[] {\n  const resolved = configs\n    .map((config) => {\n      if (config.agentInputs != null) {\n        return config as ResolvedSubagentConfig;\n      }\n      if (config.self !== true || parentContext._sourceInputs == null) {\n        return null;\n      }\n      return {\n        ...config,\n        agentInputs: { ...parentContext._sourceInputs },\n      } as ResolvedSubagentConfig;\n    })\n    .filter((c): c is ResolvedSubagentConfig => c != null);\n\n  const seenTypes = new Set<string>();\n  for (const config of resolved) {\n    if (seenTypes.has(config.type)) {\n      throw new Error(\n        `Duplicate subagent type \"${config.type}\". Each SubagentConfig must have a unique \"type\" field.`\n      );\n    }\n    seenTypes.add(config.type);\n  }\n\n  return resolved;\n}\n\n/**\n * Build child AgentInputs from a resolved config, stripping nesting and\n * event-driven fields. When `allowNested: true`, the child's\n * `maxSubagentDepth` is decremented so that depth is consumed as the call\n * chain deepens across graph boundaries — the parent's executor-level check\n * alone cannot see into the child graph's separate executor.\n *\n * @remarks Advanced utility: exported primarily for testing and by\n * {@link SubagentExecutor}. Host applications configuring subagents should\n * not need to call this directly — it is invoked internally when a subagent\n * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,\n * child's decremented `maxSubagentDepth` on the returned inputs) is the\n * mechanism that bounds nesting across graph boundaries; callers must\n * respect it.\n */\nexport function buildChildInputs(\n  config: ResolvedSubagentConfig,\n  childAgentId: string,\n  parentMaxDepth: number\n): AgentInputs {\n  const { agentInputs } = config;\n  const childInputs: AgentInputs = {\n    ...agentInputs,\n    agentId: childAgentId,\n    toolDefinitions: undefined,\n  };\n\n  if (config.allowNested === true) {\n    childInputs.maxSubagentDepth = Math.max(0, parentMaxDepth - 1);\n  } else {\n    childInputs.subagentConfigs = undefined;\n    childInputs.maxSubagentDepth = undefined;\n  }\n\n  return childInputs;\n}\n\nfunction truncateErrorMessage(error: unknown): string {\n  const message = error instanceof Error ? error.message : String(error);\n  if (message.length <= ERROR_MESSAGE_MAX_CHARS) {\n    return message;\n  }\n  return `${message.slice(0, ERROR_MESSAGE_MAX_CHARS)}...`;\n}\n"],"names":[],"mappings":"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"}

package/dist/types/agents/AgentContext.d.ts

@@ -86,6 +86,12 @@ export declare class AgentContext {
     toolDefinitions?: t.LCTool[];
     /** Set of tool names discovered via tool search (to be loaded) */
     discoveredToolNames: Set<string>;
+    /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+    _sourceInputs?: t.AgentInputs;
+    /** Subagent configurations for hierarchical delegation. */
+    subagentConfigs?: t.SubagentConfig[];
+    /** Maximum subagent nesting depth. */
+    maxSubagentDepth?: number;
     /** Instructions for this agent */
     instructions?: string;
     /** Additional instructions for this agent */

package/dist/types/common/enum.d.ts

@@ -136,8 +136,15 @@ export declare enum Constants {
     /** Delimiter for MCP tools: toolName_mcp_serverName */
     MCP_DELIMITER = "_mcp_",
     /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
-    ANTHROPIC_SERVER_TOOL_PREFIX = "srvtoolu_"
+    ANTHROPIC_SERVER_TOOL_PREFIX = "srvtoolu_",
+    SKILL_TOOL = "skill",
+    READ_FILE = "read_file",
+    BASH_TOOL = "bash_tool",
+    BASH_PROGRAMMATIC_TOOL_CALLING = "run_tools_with_bash",
+    SUBAGENT = "subagent"
 }
+/** Tool names that use the code execution environment (shared session, file tracking). */
+export declare const CODE_EXECUTION_TOOLS: ReadonlySet<string>;
 export declare enum TitleMethod {
     STRUCTURED = "structured",
     FUNCTIONS = "functions",

package/dist/types/graphs/Graph.d.ts

@@ -6,6 +6,7 @@ import type * as t from '@/types';
 import { ToolNode as CustomToolNode } from '@/tools/ToolNode';
 import { AgentContext } from '@/agents/AgentContext';
 import { HandlerRegistry } from '@/events';
+import type { HookRegistry } from '@/hooks';
 export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphState, _TNodeName extends string = string> {
     abstract resetValues(): void;
     abstract initializeTools({ currentTools, currentToolMap, }: {
@@ -43,6 +44,7 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
     /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
     invokedToolIds?: Set<string>;
     handlerRegistry: HandlerRegistry | undefined;
+    hookRegistry: HookRegistry | undefined;
     /**
      * Tool session contexts for automatic state persistence across tool invocations.
      * Keyed by tool name (e.g., Constants.EXECUTE_CODE).

package/dist/types/hooks/HookRegistry.d.ts

@@ -0,0 +1,56 @@
+import type { HookEvent, HookMatcher } from './types';
+/**
+ * Run-scoped storage for hook matchers with an additional layer for
+ * session-scoped matchers that should be cleaned up between sessions.
+ *
+ * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is
+ * scoped) and register global matchers + per-session matchers against it.
+ * Registration is strictly additive — nothing in this class mutates a
+ * matcher's callbacks or flags after insertion.
+ *
+ * ## Why `Map<sessionId, MatcherBucket>` and not `Record`
+ *
+ * LibreChat runs thousands of parallel sessions in one Node process, and
+ * hook registration happens inside hot paths (tool loading, agent spawning).
+ * A `Record<sessionId, ...>` has to be spread on every insertion, which is
+ * O(n) per call and O(n²) total for a batch of parallel registrations. A
+ * Map mutates in place, keeping insertions O(1). This mirrors the reasoning
+ * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.
+ */
+export declare class HookRegistry {
+    private readonly global;
+    private readonly sessions;
+    /**
+     * Register a matcher for the lifetime of this registry (= one Run).
+     * Returns an unregister function that removes the matcher by reference.
+     */
+    register<E extends HookEvent>(event: E, matcher: HookMatcher<E>): () => void;
+    /**
+     * Register a matcher for a specific session. Cleared automatically when
+     * `clearSession(sessionId)` is called, or can be removed directly via the
+     * returned unregister function.
+     */
+    registerSession<E extends HookEvent>(sessionId: string, event: E, matcher: HookMatcher<E>): () => void;
+    /**
+     * Returns all matchers registered for `event`, concatenating global first
+     * and then session-specific (when `sessionId` is supplied). The caller
+     * receives a fresh array, so iterating it is safe even if a matcher is
+     * removed mid-iteration (e.g. via `once: true`).
+     */
+    getMatchers<E extends HookEvent>(event: E, sessionId?: string): HookMatcher<E>[];
+    /**
+     * Removes `matcher` by reference from global storage first, falling back
+     * to the session bucket when `sessionId` is supplied. Used by
+     * `executeHooks` to drop `once: true` matchers after they fire.
+     */
+    removeMatcher<E extends HookEvent>(event: E, matcher: HookMatcher<E>, sessionId?: string): boolean;
+    /**
+     * Drops every session-scoped matcher for `sessionId`. Call this in the
+     * `finally` block around a Run so a `once: true` hook that never fired
+     * cannot leak into the next session on the same registry.
+     */
+    clearSession(sessionId: string): void;
+    /** True if at least one matcher exists for `event` (global + session). */
+    hasHookFor(event: HookEvent, sessionId?: string): boolean;
+    private ensureSessionBucket;
+}

package/dist/types/hooks/executeHooks.d.ts

@@ -0,0 +1,79 @@
+import type { Logger } from 'winston';
+import type { HookRegistry } from './HookRegistry';
+import type { HookInput, AggregatedHookResult } from './types';
+/** Default per-hook timeout when a matcher doesn't set its own. */
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 30000;
+/**
+ * Options for a single `executeHooks` call. The `input` drives everything —
+ * the event name is read from `input.hook_event_name`, matchers are looked
+ * up against that event, and each hook receives `input` directly.
+ */
+export interface ExecuteHooksOptions {
+    registry: HookRegistry;
+    input: HookInput;
+    /** Scope lookup to this session (in addition to global matchers). */
+    sessionId?: string;
+    /** Query string matched against each matcher's pattern (tool name, etc.). */
+    matchQuery?: string;
+    /** Parent AbortSignal — combined with per-hook timeout into the hook signal. */
+    signal?: AbortSignal;
+    /** Default per-hook timeout; overridden by `matcher.timeout` when present. */
+    timeoutMs?: number;
+    /** Optional winston logger for non-internal hook errors. */
+    logger?: Logger;
+}
+/**
+ * Fires every matcher registered against `input.hook_event_name`, folding
+ * their results per `deny > ask > allow` precedence and accumulating
+ * context/errors.
+ *
+ * ## Parallelism and determinism
+ *
+ * All matching hooks fire simultaneously and are awaited via `Promise.all`,
+ * which preserves input-array order in its returned results. The fold
+ * therefore iterates outcomes in **registration order** — outer loop over
+ * matchers as they sit in the registry (global first, then session), inner
+ * loop over each matcher's `hooks` array. Last-writer-wins fields
+ * (`updatedInput`, `updatedOutput`) are deterministic in that order, even
+ * though hooks may complete in arbitrary wall-clock order.
+ *
+ * Consumers that need a single authoritative rewrite should still scope
+ * `updatedInput`/`updatedOutput` to one hook per matcher to avoid subtle
+ * precedence bugs when matchers are added in a different order than
+ * expected.
+ *
+ * ## Timeouts and cancellation
+ *
+ * Each matcher receives **one shared `AbortSignal`** derived from the
+ * caller's parent signal combined with `matcher.timeout` (falling back to
+ * `opts.timeoutMs`, default {@link DEFAULT_HOOK_TIMEOUT_MS}). Sharing the
+ * signal across hooks in a matcher collapses N timer allocations into
+ * one, which matters on the PreToolUse hot path where a matcher with
+ * several hooks fires on every tool call. Each hook call is raced
+ * against the shared signal, so even a hook that ignores the signal is
+ * force-unblocked when the timeout fires. Timeout/abort errors are
+ * swallowed into the aggregated result's `errors` array (non-fatal by
+ * default).
+ *
+ * ## Internal matchers
+ *
+ * A matcher with `internal: true` is excluded from both the `errors` array
+ * and the logger output. Use it for infrastructure hooks whose failures
+ * should not pollute user-visible diagnostics.
+ *
+ * ## Once semantics — atomic at-most-once
+ *
+ * A matcher with `once: true` is removed from the registry **before any
+ * hook runs**, inside the synchronous prefix of `executeHooks` (between
+ * `getMatchers` and the first `await`). Because Node's event loop serialises
+ * sync work, two concurrent `executeHooks` calls can never both observe
+ * and dispatch the same `once` matcher — whichever call runs its sync
+ * prefix first consumes it, and the loser sees an empty bucket.
+ *
+ * Trade-off: if every hook in a `once` matcher throws, the matcher is
+ * still gone. "Once" here means "at most one dispatch, ever", not "at
+ * most one successful execution with retry on failure". Hosts that need
+ * retry semantics should register a normal matcher and self-unregister
+ * via the `unregister` callback returned from `registry.register`.
+ */
+export declare function executeHooks(opts: ExecuteHooksOptions): Promise<AggregatedHookResult>;

package/dist/types/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { HookRegistry } from './HookRegistry';
+export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
+export { matchesQuery, hasNestedQuantifier, MAX_PATTERN_LENGTH, MAX_CACHE_SIZE, } from './matchers';
+export { HOOK_EVENTS } from './types';
+export type { HookEvent, HookInput, HookOutput, HookCallback, HookMatcher, HooksByEvent, HookInputByEvent, HookOutputByEvent, BaseHookInput, BaseHookOutput, ToolDecision, StopDecision, AggregatedHookResult, RunStartHookInput, UserPromptSubmitHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, PermissionDeniedHookInput, SubagentStartHookInput, SubagentStopHookInput, StopHookInput, StopFailureHookInput, PreCompactHookInput, PostCompactHookInput, RunStartHookOutput, UserPromptSubmitHookOutput, PreToolUseHookOutput, PostToolUseHookOutput, PostToolUseFailureHookOutput, PermissionDeniedHookOutput, SubagentStartHookOutput, SubagentStopHookOutput, StopHookOutput, StopFailureHookOutput, PreCompactHookOutput, PostCompactHookOutput, } from './types';
+export type { ExecuteHooksOptions } from './executeHooks';

package/dist/types/hooks/matchers.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Upper bound on hook-matcher pattern length. Patterns longer than this
+ * are rejected outright — the goal is a cheap cap on pathological inputs
+ * (repeated quantifiers, huge alternation groups) without pulling in a
+ * safe-regex dependency.
+ *
+ * Legitimate matchers are almost always under 50 characters (tool names,
+ * short alternations, simple prefix anchors); 512 leaves generous
+ * headroom while preventing 10KB regexes.
+ */
+export declare const MAX_PATTERN_LENGTH = 512;
+/**
+ * Upper bound on the compilation cache. Chosen to comfortably hold every
+ * distinct pattern a single multi-tenant run is likely to see (tools,
+ * agent types, basename filters) without growing without bound.
+ *
+ * Under hosts that register unique patterns per tenant, LRU eviction
+ * keeps the working set bounded — cold patterns are re-compiled on next
+ * use, which is the correct cost trade-off for long-running processes
+ * that must not leak memory.
+ */
+export declare const MAX_CACHE_SIZE = 256;
+/**
+ * Cheap syntactic detector for the most common catastrophic-backtracking
+ * shape: a quantified group that contains another quantifier (e.g.
+ * `(a+)+`, `(.*)*`, `(\w+)+$`, `(?:(a+))+`). This is the "nested
+ * quantifier" class of ReDoS — runs in polynomial-or-worse time on
+ * adversarial inputs.
+ *
+ * The scan walks the pattern linearly using an explicit stack of group
+ * frames. For each group it tracks whether the group's contents include
+ * "backtrack risk" — meaning a direct quantifier OR a nested group that
+ * carries risk up. When a group closes with a trailing quantifier AND its
+ * frame carries backtrack risk, the pattern is flagged. Risk propagates
+ * to the enclosing frame when a child group closes (whether the child
+ * itself was quantified or not), so `(?:(a+))+` — equivalent to `(a+)+`
+ * — is flagged correctly even though the outer non-capturing wrapper is
+ * one level removed from the inner quantifier.
+ *
+ * ## Group-syntax prefixes
+ *
+ * Non-capturing groups (`(?:`), lookaheads (`(?=`, `(?!`), lookbehinds
+ * (`(?<=`, `(?<!`), and named groups (`(?<name>`) are skipped over at
+ * the `(` so their `?` is not misread as a quantifier. Without this,
+ * `(?:pre_)?tool_name` would be incorrectly rejected because the scanner
+ * would see the group-syntax `?` as a quantifier at depth 1.
+ *
+ * ## Heuristic, not a proof
+ *
+ * This catches the common forms but not all. Ambiguous-alternation ReDoS
+ * like `(a|a)+` is not detected. Pathologically long patterns are also
+ * caught by {@link MAX_PATTERN_LENGTH}. Hosts that accept user-supplied
+ * patterns must still validate upstream.
+ */
+export declare function hasNestedQuantifier(pattern: string): boolean;
+/**
+ * Tests whether a hook matcher pattern matches the given query string.
+ *
+ * ## Semantics
+ *
+ * - `undefined` or empty `pattern` matches any query (wildcard). This is
+ *   the intended shape for events that do not supply a query string at
+ *   all (`RunStart`, `Stop`, etc.) — register such matchers without a
+ *   pattern.
+ * - `undefined` or empty `query` with a non-empty `pattern` never matches.
+ *   Setting a pattern on a query-less event is therefore inert: the
+ *   matcher will simply never fire. This is intentional — it keeps
+ *   query-based filtering out of event types where "query" has no meaning,
+ *   and is documented on `HookMatcher.pattern`.
+ * - Otherwise, the pattern is compiled once (via a bounded LRU cache) and
+ *   tested against the query.
+ * - Invalid regex patterns never throw — a failed compile is cached as
+ *   "never matches" so a single malformed pattern cannot take out a whole
+ *   `executeHooks` batch.
+ *
+ * ## ReDoS mitigations
+ *
+ * Patterns compile through three cheap gates before reaching `new RegExp`:
+ *
+ * 1. {@link MAX_PATTERN_LENGTH} length cap rejects oversized inputs.
+ * 2. {@link hasNestedQuantifier} rejects the most common catastrophic-
+ *    backtracking shape (quantified group containing a quantifier).
+ * 3. Successful compiles are cached in a bounded LRU so repeated calls
+ *    never re-enter the regex compiler.
+ *
+ * These are a floor, not a ceiling. Hosts that accept user-supplied
+ * patterns should still validate upstream. The design report §3.8 routes
+ * persistable hooks through a host-side compiler before they reach this
+ * module.
+ */
+export declare function matchesQuery(pattern: string | undefined, query: string | undefined): boolean;
+/** Clears the regex compilation cache. Intended for test isolation. */
+export declare function clearMatcherCache(): void;
+/** Returns the current size of the compilation cache. Intended for tests. */
+export declare function getMatcherCacheSize(): number;

package/dist/types/hooks/types.d.ts

@@ -0,0 +1,320 @@
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Closed set of hook lifecycle events supported by the hooks system.
+ *
+ * These mirror the subset of Claude Code's event surface that makes sense
+ * for a library context (no filesystem/CLI-specific events). See
+ * `docs/hooks-design-report.md` §3.2 for the mapping to existing
+ * `@librechat/agents` emission points.
+ */
+export declare const HOOK_EVENTS: readonly ["RunStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionDenied", "SubagentStart", "SubagentStop", "Stop", "StopFailure", "PreCompact", "PostCompact"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
+export type ToolDecision = 'allow' | 'deny' | 'ask';
+/** Stop-loop decision; `block` means "do not stop, run another turn". Any `block` wins. */
+export type StopDecision = 'continue' | 'block';
+/**
+ * Fields shared by every `HookInput`. Discriminated by `hook_event_name`.
+ *
+ * - `runId` identifies the current agent run and is always present.
+ * - `threadId` identifies the conversation thread when the host has one.
+ * - `agentId` is only set when the hook fires inside a subagent scope.
+ */
+export interface BaseHookInput {
+    runId: string;
+    threadId?: string;
+    agentId?: string;
+}
+export interface RunStartHookInput extends BaseHookInput {
+    hook_event_name: 'RunStart';
+    messages: BaseMessage[];
+}
+export interface UserPromptSubmitHookInput extends BaseHookInput {
+    hook_event_name: 'UserPromptSubmit';
+    prompt: string;
+    attachments?: BaseMessage[];
+}
+/**
+ * Fires before a tool is invoked. Hook may return `deny`/`ask`/`allow` and/or
+ * an `updatedInput` that replaces the tool arguments before invocation.
+ *
+ * `toolInput` is intentionally typed as `Record<string, unknown>` because the
+ * SDK is tool-agnostic — concrete tool argument shapes are only known at the
+ * call site and are narrowed by the host. This is the one escape hatch in
+ * the hook type system.
+ */
+export interface PreToolUseHookInput extends BaseHookInput {
+    hook_event_name: 'PreToolUse';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    stepId?: string;
+    /**
+     * Number of times this tool has been invoked in prior batches within the
+     * current run. Within a single batch of parallel calls, all calls to the
+     * same tool share the same turn value — per-call discrimination within a
+     * batch is not supported in v1.
+     */
+    turn?: number;
+}
+export interface PostToolUseHookInput extends BaseHookInput {
+    hook_event_name: 'PostToolUse';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolOutput: unknown;
+    toolUseId: string;
+    stepId?: string;
+    turn?: number;
+}
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    hook_event_name: 'PostToolUseFailure';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    error: string;
+    stepId?: string;
+    turn?: number;
+}
+export interface PermissionDeniedHookInput extends BaseHookInput {
+    hook_event_name: 'PermissionDenied';
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolUseId: string;
+    reason: string;
+}
+export interface SubagentStartHookInput extends BaseHookInput {
+    hook_event_name: 'SubagentStart';
+    parentAgentId?: string;
+    agentId: string;
+    agentType: string;
+    inputs: BaseMessage[];
+}
+export interface SubagentStopHookInput extends BaseHookInput {
+    hook_event_name: 'SubagentStop';
+    agentId: string;
+    agentType: string;
+    messages: BaseMessage[];
+}
+export interface StopHookInput extends BaseHookInput {
+    hook_event_name: 'Stop';
+    messages: BaseMessage[];
+    stopReason?: string;
+    stopHookActive: boolean;
+}
+export interface StopFailureHookInput extends BaseHookInput {
+    hook_event_name: 'StopFailure';
+    error: string;
+    lastAssistantMessage?: BaseMessage;
+}
+export interface PreCompactHookInput extends BaseHookInput {
+    hook_event_name: 'PreCompact';
+    messagesBeforeCount: number;
+    /**
+     * What triggered compaction. Matches `SummarizationTrigger.type` from the
+     * agent's summarization config. `'default'` means no trigger was
+     * configured and compaction fired because messages were pruned.
+     */
+    trigger: 'token_ratio' | 'remaining_tokens' | 'messages_to_refine' | 'default' | (string & {});
+}
+export interface PostCompactHookInput extends BaseHookInput {
+    hook_event_name: 'PostCompact';
+    summary: string;
+    /**
+     * Number of messages remaining after compaction. The summarize node
+     * returns a `removeAll` signal that clears all messages from state;
+     * the summary itself is injected into the system prompt, not as a
+     * message. This is `0` at the point of hook dispatch.
+     */
+    messagesAfterCount: number;
+}
+/** Discriminated union of every hook input shape. */
+export type HookInput = RunStartHookInput | UserPromptSubmitHookInput | PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | PermissionDeniedHookInput | SubagentStartHookInput | SubagentStopHookInput | StopHookInput | StopFailureHookInput | PreCompactHookInput | PostCompactHookInput;
+/** Compile-time map from event name to its input shape. */
+export type HookInputByEvent = {
+    RunStart: RunStartHookInput;
+    UserPromptSubmit: UserPromptSubmitHookInput;
+    PreToolUse: PreToolUseHookInput;
+    PostToolUse: PostToolUseHookInput;
+    PostToolUseFailure: PostToolUseFailureHookInput;
+    PermissionDenied: PermissionDeniedHookInput;
+    SubagentStart: SubagentStartHookInput;
+    SubagentStop: SubagentStopHookInput;
+    Stop: StopHookInput;
+    StopFailure: StopFailureHookInput;
+    PreCompact: PreCompactHookInput;
+    PostCompact: PostCompactHookInput;
+};
+/**
+ * Fields common to every hook output. Hooks that have nothing to say simply
+ * return `{}` (or omit the fields below).
+ */
+export interface BaseHookOutput {
+    /** Context string to inject into the conversation. Accumulated across hooks. */
+    additionalContext?: string;
+    /** True to prevent the next model turn. Any hook can set this. */
+    preventContinuation?: boolean;
+    /** Reason reported alongside `preventContinuation`. */
+    stopReason?: string;
+}
+export type RunStartHookOutput = BaseHookOutput;
+export interface UserPromptSubmitHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+}
+export interface PreToolUseHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+    /**
+     * Replacement tool input. Merged into the pending tool call by the host.
+     *
+     * When multiple hooks set `updatedInput` within a single `executeHooks`
+     * call, the last writer in registration order wins (outer loop: matcher
+     * registration order; inner loop: hook position within the matcher). The
+     * winner is deterministic — `Promise.all` preserves input-array order.
+     * Consumers that need a single authoritative rewrite should still scope
+     * `updatedInput` to one hook per matcher to avoid confusing precedence.
+     */
+    updatedInput?: Record<string, unknown>;
+}
+export interface PostToolUseHookOutput extends BaseHookOutput {
+    /**
+     * Replacement tool output. Flows through the aggregated result so the
+     * host can substitute it before appending the tool result message.
+     * Ordering semantics match `PreToolUseHookOutput.updatedInput`:
+     * last-writer-wins in registration order.
+     */
+    updatedOutput?: unknown;
+}
+export type PostToolUseFailureHookOutput = BaseHookOutput;
+export type PermissionDeniedHookOutput = BaseHookOutput;
+export interface SubagentStartHookOutput extends BaseHookOutput {
+    decision?: ToolDecision;
+    reason?: string;
+}
+export type SubagentStopHookOutput = BaseHookOutput;
+export interface StopHookOutput extends BaseHookOutput {
+    decision?: StopDecision;
+    reason?: string;
+}
+export type StopFailureHookOutput = BaseHookOutput;
+export type PreCompactHookOutput = BaseHookOutput;
+export type PostCompactHookOutput = BaseHookOutput;
+/** Compile-time map from event name to its output shape. */
+export type HookOutputByEvent = {
+    RunStart: RunStartHookOutput;
+    UserPromptSubmit: UserPromptSubmitHookOutput;
+    PreToolUse: PreToolUseHookOutput;
+    PostToolUse: PostToolUseHookOutput;
+    PostToolUseFailure: PostToolUseFailureHookOutput;
+    PermissionDenied: PermissionDeniedHookOutput;
+    SubagentStart: SubagentStartHookOutput;
+    SubagentStop: SubagentStopHookOutput;
+    Stop: StopHookOutput;
+    StopFailure: StopFailureHookOutput;
+    PreCompact: PreCompactHookOutput;
+    PostCompact: PostCompactHookOutput;
+};
+/** Superset output shape used by the executor's fold loop. */
+export type HookOutput = RunStartHookOutput | UserPromptSubmitHookOutput | PreToolUseHookOutput | PostToolUseHookOutput | PostToolUseFailureHookOutput | PermissionDeniedHookOutput | SubagentStartHookOutput | SubagentStopHookOutput | StopHookOutput | StopFailureHookOutput | PreCompactHookOutput | PostCompactHookOutput;
+/**
+ * A hook callback is a plain async function registered against a specific
+ * event. The `signal` is always supplied by `executeHooks` and combines the
+ * batch's parent signal with the per-hook timeout — callbacks that perform
+ * long-running work should observe it.
+ */
+export type HookCallback<E extends HookEvent = HookEvent> = (input: HookInputByEvent[E], signal: AbortSignal) => HookOutputByEvent[E] | Promise<HookOutputByEvent[E]>;
+/**
+ * A matcher groups one or more callbacks under a shared regex filter and
+ * shared timeout/once/internal flags. The generic `E` ties the callback
+ * types to the event the matcher is registered against.
+ */
+export interface HookMatcher<E extends HookEvent = HookEvent> {
+    /**
+     * Regex pattern matched against the event's primary query string (e.g.
+     * the tool name for `PreToolUse`, the agent type for `SubagentStart`).
+     *
+     * Omitted or empty means "always match". For events that do not supply a
+     * query string (`RunStart`, `Stop`, etc.), only wildcard matchers fire —
+     * a non-empty pattern on such events will never match.
+     *
+     * Patterns are treated as trusted input: `executeHooks` compiles them
+     * with `new RegExp(pattern)` without any sandbox, and a pathological
+     * pattern can block the event loop. Host registration code is expected
+     * to validate or length-bound patterns that originate from user input.
+     */
+    pattern?: string;
+    /** Callbacks that fire when the matcher hits. Executed in parallel. */
+    hooks: HookCallback<E>[];
+    /** Per-matcher timeout in ms. Defaults to the executor's batch timeout. */
+    timeout?: number;
+    /**
+     * Atomically remove the matcher before its first dispatch.
+     *
+     * `executeHooks` claims `once: true` matchers synchronously — between
+     * `getMatchers` and its first `await` — so two concurrent calls cannot
+     * both dispatch the same matcher. Whichever call runs its sync prefix
+     * first wins the matcher; the other sees an empty bucket.
+     *
+     * Semantics are "at most one dispatch, ever" — if every hook in the
+     * matcher throws, the matcher is still gone. Use `once` for
+     * fire-and-forget bootstrapping (registration, telemetry, setup). Hosts
+     * that need retry semantics should register a normal matcher and
+     * self-unregister via the callback returned from `registry.register`.
+     */
+    once?: boolean;
+    /** Internal hooks are excluded from telemetry and non-fatal error logging. */
+    internal?: boolean;
+}
+/**
+ * Storage shape for matchers keyed by event. Each event's matcher list is
+ * a generic array parameterized by that event type, so lookup via
+ * `HooksByEvent[E]` preserves type-safe callback signatures.
+ */
+export type HooksByEvent = {
+    [E in HookEvent]?: HookMatcher<E>[];
+};
+/**
+ * Aggregated result of a single `executeHooks` call. Fields are populated
+ * according to the fold rules in `executeHooks.ts`.
+ */
+export interface AggregatedHookResult {
+    /** Folded tool-gating decision; `deny > ask > allow`. */
+    decision?: ToolDecision;
+    /** Folded stop decision; any `block` wins. */
+    stopDecision?: StopDecision;
+    /** Reason from the hook that set the winning decision. */
+    reason?: string;
+    /**
+     * Replacement tool input from a `PreToolUse` hook.
+     *
+     * Last-writer-wins in **registration order**: `executeHooks` uses
+     * `Promise.all`, which preserves input-array order, so the fold iterates
+     * outcomes in the same order they were pushed — outer loop over matchers
+     * as they sit in the registry, inner loop over each matcher's `hooks`
+     * array. The winner is therefore deterministic but may not match the
+     * order in which hooks actually completed. Consumers that want a single
+     * authoritative rewrite should still register one `updatedInput`-setting
+     * hook per matcher to avoid subtle precedence bugs.
+     */
+    updatedInput?: Record<string, unknown>;
+    /**
+     * Replacement tool output from a `PostToolUse` hook.
+     *
+     * Same last-writer-wins-in-registration-order semantics as
+     * `updatedInput`. Present only when at least one hook set it; `undefined`
+     * means "use the original tool output".
+     */
+    updatedOutput?: unknown;
+    /** Accumulated `additionalContext` strings from every hook, in order. */
+    additionalContexts: string[];
+    /** True if any hook returned `preventContinuation`. */
+    preventContinuation?: boolean;
+    /**
+     * Reason recorded alongside `preventContinuation`. First winner wins:
+     * once a hook sets both flags, later hooks that also set
+     * `preventContinuation` do not overwrite the reason.
+     */
+    stopReason?: string;
+    /** Error messages from hooks that threw; always present (possibly empty). */
+    errors: string[];
+}