@librechat/agents 3.1.67 → 3.1.68-dev.0

package/dist/cjs/hooks/executeHooks.cjs

@@ -0,0 +1,276 @@
+'use strict';
+
+var matchers = require('./matchers.cjs');
+
+/** Default per-hook timeout when a matcher doesn't set its own. */
+const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+function freshResult() {
+    return {
+        additionalContexts: [],
+        errors: [],
+    };
+}
+function combineSignals(parent, timeoutMs) {
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    if (parent === undefined) {
+        return timeoutSignal;
+    }
+    return AbortSignal.any([parent, timeoutSignal]);
+}
+function isTimeout(err) {
+    if (err instanceof Error) {
+        return err.name === 'TimeoutError' || err.name === 'AbortError';
+    }
+    return false;
+}
+function describeError(err) {
+    if (err instanceof Error) {
+        return err.message !== '' ? err.message : err.name;
+    }
+    return String(err);
+}
+function makeAbortPromise(signal) {
+    let onAbort;
+    const promise = new Promise((_resolve, reject) => {
+        if (signal.aborted) {
+            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+            return;
+        }
+        onAbort = () => {
+            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    const cleanup = () => {
+        if (onAbort !== undefined) {
+            signal.removeEventListener('abort', onAbort);
+            onAbort = undefined;
+        }
+    };
+    return { promise, cleanup };
+}
+async function runHook(hook, input, signal, matcher) {
+    const hookPromise = Promise.resolve().then(() => hook(input, signal));
+    const { promise: abortPromise, cleanup } = makeAbortPromise(signal);
+    try {
+        const output = await Promise.race([hookPromise, abortPromise]);
+        return { matcher, output, error: null, timedOut: false };
+    }
+    catch (err) {
+        return {
+            matcher,
+            output: null,
+            error: describeError(err),
+            timedOut: isTimeout(err),
+        };
+    }
+    finally {
+        cleanup();
+    }
+}
+function reportErrors(outcomes, event, logger) {
+    for (const outcome of outcomes) {
+        if (outcome.error === null) {
+            continue;
+        }
+        if (outcome.matcher.internal === true) {
+            continue;
+        }
+        const label = outcome.timedOut ? 'timed out' : 'threw an error';
+        const message = `Hook for ${event} ${label}: ${outcome.error}`;
+        if (logger !== undefined) {
+            logger.warn(message);
+            continue;
+        }
+        // eslint-disable-next-line no-console
+        console.warn(message);
+    }
+}
+function applyToolDecision(agg, decision, reason) {
+    if (decision === 'deny') {
+        if (agg.decision === 'deny') {
+            return;
+        }
+        agg.decision = 'deny';
+        agg.reason = reason;
+        return;
+    }
+    if (decision === 'ask') {
+        if (agg.decision === 'deny' || agg.decision === 'ask') {
+            return;
+        }
+        agg.decision = 'ask';
+        agg.reason = reason;
+        return;
+    }
+    if (agg.decision === undefined) {
+        agg.decision = 'allow';
+        agg.reason = reason;
+    }
+}
+function applyStopDecision(agg, decision, reason) {
+    if (decision === 'block') {
+        if (agg.stopDecision === 'block') {
+            return;
+        }
+        agg.stopDecision = 'block';
+        agg.reason = reason;
+        return;
+    }
+    if (agg.stopDecision === undefined) {
+        agg.stopDecision = 'continue';
+        if (agg.reason === undefined) {
+            agg.reason = reason;
+        }
+    }
+}
+function applyDecision(agg, output) {
+    if (!('decision' in output) || output.decision === undefined) {
+        return;
+    }
+    const decision = output.decision;
+    const reason = 'reason' in output && typeof output.reason === 'string'
+        ? output.reason
+        : undefined;
+    if (decision === 'deny' || decision === 'ask' || decision === 'allow') {
+        applyToolDecision(agg, decision, reason);
+        return;
+    }
+    applyStopDecision(agg, decision, reason);
+}
+function applyContext(agg, output) {
+    if (typeof output.additionalContext === 'string' &&
+        output.additionalContext.length > 0) {
+        agg.additionalContexts.push(output.additionalContext);
+    }
+}
+function applyStopFlag(agg, output) {
+    if (output.preventContinuation !== true) {
+        return;
+    }
+    agg.preventContinuation = true;
+    if (typeof output.stopReason === 'string' && agg.stopReason === undefined) {
+        agg.stopReason = output.stopReason;
+    }
+}
+function applyUpdatedInput(agg, output) {
+    if (!('updatedInput' in output) || output.updatedInput === undefined) {
+        return;
+    }
+    agg.updatedInput = output.updatedInput;
+}
+function applyUpdatedOutput(agg, output) {
+    if (!('updatedOutput' in output) || output.updatedOutput === undefined) {
+        return;
+    }
+    agg.updatedOutput = output.updatedOutput;
+}
+function fold(outcomes) {
+    const agg = freshResult();
+    for (const outcome of outcomes) {
+        if (outcome.error !== null) {
+            if (outcome.matcher.internal !== true) {
+                agg.errors.push(outcome.error);
+            }
+            continue;
+        }
+        const output = outcome.output;
+        if (output === null) {
+            continue;
+        }
+        applyContext(agg, output);
+        applyStopFlag(agg, output);
+        applyDecision(agg, output);
+        applyUpdatedInput(agg, output);
+        applyUpdatedOutput(agg, output);
+    }
+    return agg;
+}
+/**
+ * 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`.
+ */
+async function executeHooks(opts) {
+    const { registry, input, sessionId, matchQuery, signal, timeoutMs = DEFAULT_HOOK_TIMEOUT_MS, logger, } = opts;
+    const event = input.hook_event_name;
+    const matchers$1 = registry.getMatchers(event, sessionId);
+    if (matchers$1.length === 0) {
+        return freshResult();
+    }
+    // --- SYNC CRITICAL SECTION: once-matcher removal must complete before any await ---
+    const tasks = [];
+    for (const matcher of matchers$1) {
+        if (!matchers.matchesQuery(matcher.pattern, matchQuery)) {
+            continue;
+        }
+        if (matcher.once === true) {
+            registry.removeMatcher(event, matcher, sessionId);
+        }
+        const perHookTimeout = matcher.timeout ?? timeoutMs;
+        const matcherSignal = combineSignals(signal, perHookTimeout);
+        for (const hook of matcher.hooks) {
+            tasks.push(runHook(hook, input, matcherSignal, matcher));
+        }
+    }
+    // --- END SYNC CRITICAL SECTION ---
+    if (tasks.length === 0) {
+        return freshResult();
+    }
+    const outcomes = await Promise.all(tasks);
+    reportErrors(outcomes, event, logger);
+    return fold(outcomes);
+}
+
+exports.DEFAULT_HOOK_TIMEOUT_MS = DEFAULT_HOOK_TIMEOUT_MS;
+exports.executeHooks = executeHooks;
+//# sourceMappingURL=executeHooks.cjs.map

package/dist/cjs/hooks/executeHooks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"executeHooks.cjs","sources":["../../../src/hooks/executeHooks.ts"],"sourcesContent":["// src/hooks/executeHooks.ts\nimport type { Logger } from 'winston';\nimport type { HookRegistry } from './HookRegistry';\nimport type {\n  HookInput,\n  HookEvent,\n  HookOutput,\n  HookMatcher,\n  ToolDecision,\n  StopDecision,\n  HookCallback,\n  AggregatedHookResult,\n} from './types';\nimport { matchesQuery } from './matchers';\n\n/** Default per-hook timeout when a matcher doesn't set its own. */\nexport const DEFAULT_HOOK_TIMEOUT_MS = 30_000;\n\n/**\n * Options for a single `executeHooks` call. The `input` drives everything —\n * the event name is read from `input.hook_event_name`, matchers are looked\n * up against that event, and each hook receives `input` directly.\n */\nexport interface ExecuteHooksOptions {\n  registry: HookRegistry;\n  input: HookInput;\n  /** Scope lookup to this session (in addition to global matchers). */\n  sessionId?: string;\n  /** Query string matched against each matcher's pattern (tool name, etc.). */\n  matchQuery?: string;\n  /** Parent AbortSignal — combined with per-hook timeout into the hook signal. */\n  signal?: AbortSignal;\n  /** Default per-hook timeout; overridden by `matcher.timeout` when present. */\n  timeoutMs?: number;\n  /** Optional winston logger for non-internal hook errors. */\n  logger?: Logger;\n}\n\ntype WideMatcher = HookMatcher<HookEvent>;\ntype WideCallback = HookCallback<HookEvent>;\n\ninterface HookOutcome {\n  matcher: WideMatcher;\n  output: HookOutput | null;\n  error: string | null;\n  timedOut: boolean;\n}\n\nfunction freshResult(): AggregatedHookResult {\n  return {\n    additionalContexts: [],\n    errors: [],\n  };\n}\n\nfunction combineSignals(\n  parent: AbortSignal | undefined,\n  timeoutMs: number\n): AbortSignal {\n  const timeoutSignal = AbortSignal.timeout(timeoutMs);\n  if (parent === undefined) {\n    return timeoutSignal;\n  }\n  return AbortSignal.any([parent, timeoutSignal]);\n}\n\nfunction isTimeout(err: unknown): boolean {\n  if (err instanceof Error) {\n    return err.name === 'TimeoutError' || err.name === 'AbortError';\n  }\n  return false;\n}\n\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) {\n    return err.message !== '' ? err.message : err.name;\n  }\n  return String(err);\n}\n\nfunction makeAbortPromise(signal: AbortSignal): {\n  promise: Promise<never>;\n  cleanup: () => void;\n} {\n  let onAbort: (() => void) | undefined;\n  const promise = new Promise<never>((_resolve, reject) => {\n    if (signal.aborted) {\n      reject(\n        signal.reason instanceof Error ? signal.reason : new Error('aborted')\n      );\n      return;\n    }\n    onAbort = (): void => {\n      reject(\n        signal.reason instanceof Error ? signal.reason : new Error('aborted')\n      );\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n  });\n  const cleanup = (): void => {\n    if (onAbort !== undefined) {\n      signal.removeEventListener('abort', onAbort);\n      onAbort = undefined;\n    }\n  };\n  return { promise, cleanup };\n}\n\nasync function runHook(\n  hook: WideCallback,\n  input: HookInput,\n  signal: AbortSignal,\n  matcher: WideMatcher\n): Promise<HookOutcome> {\n  const hookPromise = Promise.resolve().then(() => hook(input, signal));\n  const { promise: abortPromise, cleanup } = makeAbortPromise(signal);\n  try {\n    const output = await Promise.race([hookPromise, abortPromise]);\n    return { matcher, output, error: null, timedOut: false };\n  } catch (err) {\n    return {\n      matcher,\n      output: null,\n      error: describeError(err),\n      timedOut: isTimeout(err),\n    };\n  } finally {\n    cleanup();\n  }\n}\n\nfunction reportErrors(\n  outcomes: readonly HookOutcome[],\n  event: HookEvent,\n  logger: Logger | undefined\n): void {\n  for (const outcome of outcomes) {\n    if (outcome.error === null) {\n      continue;\n    }\n    if (outcome.matcher.internal === true) {\n      continue;\n    }\n    const label = outcome.timedOut ? 'timed out' : 'threw an error';\n    const message = `Hook for ${event} ${label}: ${outcome.error}`;\n    if (logger !== undefined) {\n      logger.warn(message);\n      continue;\n    }\n    // eslint-disable-next-line no-console\n    console.warn(message);\n  }\n}\n\nfunction applyToolDecision(\n  agg: AggregatedHookResult,\n  decision: ToolDecision,\n  reason: string | undefined\n): void {\n  if (decision === 'deny') {\n    if (agg.decision === 'deny') {\n      return;\n    }\n    agg.decision = 'deny';\n    agg.reason = reason;\n    return;\n  }\n  if (decision === 'ask') {\n    if (agg.decision === 'deny' || agg.decision === 'ask') {\n      return;\n    }\n    agg.decision = 'ask';\n    agg.reason = reason;\n    return;\n  }\n  if (agg.decision === undefined) {\n    agg.decision = 'allow';\n    agg.reason = reason;\n  }\n}\n\nfunction applyStopDecision(\n  agg: AggregatedHookResult,\n  decision: StopDecision,\n  reason: string | undefined\n): void {\n  if (decision === 'block') {\n    if (agg.stopDecision === 'block') {\n      return;\n    }\n    agg.stopDecision = 'block';\n    agg.reason = reason;\n    return;\n  }\n  if (agg.stopDecision === undefined) {\n    agg.stopDecision = 'continue';\n    if (agg.reason === undefined) {\n      agg.reason = reason;\n    }\n  }\n}\n\nfunction applyDecision(agg: AggregatedHookResult, output: HookOutput): void {\n  if (!('decision' in output) || output.decision === undefined) {\n    return;\n  }\n  const decision = output.decision;\n  const reason =\n    'reason' in output && typeof output.reason === 'string'\n      ? output.reason\n      : undefined;\n  if (decision === 'deny' || decision === 'ask' || decision === 'allow') {\n    applyToolDecision(agg, decision, reason);\n    return;\n  }\n  applyStopDecision(agg, decision, reason);\n}\n\nfunction applyContext(agg: AggregatedHookResult, output: HookOutput): void {\n  if (\n    typeof output.additionalContext === 'string' &&\n    output.additionalContext.length > 0\n  ) {\n    agg.additionalContexts.push(output.additionalContext);\n  }\n}\n\nfunction applyStopFlag(agg: AggregatedHookResult, output: HookOutput): void {\n  if (output.preventContinuation !== true) {\n    return;\n  }\n  agg.preventContinuation = true;\n  if (typeof output.stopReason === 'string' && agg.stopReason === undefined) {\n    agg.stopReason = output.stopReason;\n  }\n}\n\nfunction applyUpdatedInput(\n  agg: AggregatedHookResult,\n  output: HookOutput\n): void {\n  if (!('updatedInput' in output) || output.updatedInput === undefined) {\n    return;\n  }\n  agg.updatedInput = output.updatedInput;\n}\n\nfunction applyUpdatedOutput(\n  agg: AggregatedHookResult,\n  output: HookOutput\n): void {\n  if (!('updatedOutput' in output) || output.updatedOutput === undefined) {\n    return;\n  }\n  agg.updatedOutput = output.updatedOutput;\n}\n\nfunction fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {\n  const agg = freshResult();\n  for (const outcome of outcomes) {\n    if (outcome.error !== null) {\n      if (outcome.matcher.internal !== true) {\n        agg.errors.push(outcome.error);\n      }\n      continue;\n    }\n    const output = outcome.output;\n    if (output === null) {\n      continue;\n    }\n    applyContext(agg, output);\n    applyStopFlag(agg, output);\n    applyDecision(agg, output);\n    applyUpdatedInput(agg, output);\n    applyUpdatedOutput(agg, output);\n  }\n  return agg;\n}\n\n/**\n * Fires every matcher registered against `input.hook_event_name`, folding\n * their results per `deny > ask > allow` precedence and accumulating\n * context/errors.\n *\n * ## Parallelism and determinism\n *\n * All matching hooks fire simultaneously and are awaited via `Promise.all`,\n * which preserves input-array order in its returned results. The fold\n * therefore iterates outcomes in **registration order** — outer loop over\n * matchers as they sit in the registry (global first, then session), inner\n * loop over each matcher's `hooks` array. Last-writer-wins fields\n * (`updatedInput`, `updatedOutput`) are deterministic in that order, even\n * though hooks may complete in arbitrary wall-clock order.\n *\n * Consumers that need a single authoritative rewrite should still scope\n * `updatedInput`/`updatedOutput` to one hook per matcher to avoid subtle\n * precedence bugs when matchers are added in a different order than\n * expected.\n *\n * ## Timeouts and cancellation\n *\n * Each matcher receives **one shared `AbortSignal`** derived from the\n * caller's parent signal combined with `matcher.timeout` (falling back to\n * `opts.timeoutMs`, default {@link DEFAULT_HOOK_TIMEOUT_MS}). Sharing the\n * signal across hooks in a matcher collapses N timer allocations into\n * one, which matters on the PreToolUse hot path where a matcher with\n * several hooks fires on every tool call. Each hook call is raced\n * against the shared signal, so even a hook that ignores the signal is\n * force-unblocked when the timeout fires. Timeout/abort errors are\n * swallowed into the aggregated result's `errors` array (non-fatal by\n * default).\n *\n * ## Internal matchers\n *\n * A matcher with `internal: true` is excluded from both the `errors` array\n * and the logger output. Use it for infrastructure hooks whose failures\n * should not pollute user-visible diagnostics.\n *\n * ## Once semantics — atomic at-most-once\n *\n * A matcher with `once: true` is removed from the registry **before any\n * hook runs**, inside the synchronous prefix of `executeHooks` (between\n * `getMatchers` and the first `await`). Because Node's event loop serialises\n * sync work, two concurrent `executeHooks` calls can never both observe\n * and dispatch the same `once` matcher — whichever call runs its sync\n * prefix first consumes it, and the loser sees an empty bucket.\n *\n * Trade-off: if every hook in a `once` matcher throws, the matcher is\n * still gone. \"Once\" here means \"at most one dispatch, ever\", not \"at\n * most one successful execution with retry on failure\". Hosts that need\n * retry semantics should register a normal matcher and self-unregister\n * via the `unregister` callback returned from `registry.register`.\n */\nexport async function executeHooks(\n  opts: ExecuteHooksOptions\n): Promise<AggregatedHookResult> {\n  const {\n    registry,\n    input,\n    sessionId,\n    matchQuery,\n    signal,\n    timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,\n    logger,\n  } = opts;\n  const event = input.hook_event_name;\n  const matchers = registry.getMatchers(event, sessionId);\n  if (matchers.length === 0) {\n    return freshResult();\n  }\n\n  // --- SYNC CRITICAL SECTION: once-matcher removal must complete before any await ---\n  const tasks: Promise<HookOutcome>[] = [];\n  for (const matcher of matchers) {\n    if (!matchesQuery(matcher.pattern, matchQuery)) {\n      continue;\n    }\n    if (matcher.once === true) {\n      registry.removeMatcher(event, matcher, sessionId);\n    }\n    const perHookTimeout = matcher.timeout ?? timeoutMs;\n    const matcherSignal = combineSignals(signal, perHookTimeout);\n    for (const hook of matcher.hooks) {\n      tasks.push(runHook(hook, input, matcherSignal, matcher));\n    }\n  }\n  // --- END SYNC CRITICAL SECTION ---\n  if (tasks.length === 0) {\n    return freshResult();\n  }\n\n  const outcomes = await Promise.all(tasks);\n  reportErrors(outcomes, event, logger);\n  return fold(outcomes);\n}\n"],"names":["matchers","matchesQuery"],"mappings":"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"}

package/dist/cjs/hooks/matchers.cjs

@@ -0,0 +1,256 @@
+'use strict';
+
+// src/hooks/matchers.ts
+/**
+ * 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.
+ */
+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.
+ */
+const MAX_CACHE_SIZE = 256;
+/**
+ * Module-level LRU cache keyed by pattern string. Map iteration order is
+ * insertion order in ECMAScript, so refreshing an entry's position means
+ * "delete then re-set". On overflow we evict the first key (least
+ * recently used).
+ *
+ * Failed compiles are cached as `{ regex: null }` so a malformed pattern
+ * does not re-enter the compiler — and so a tenant spamming bad patterns
+ * doesn't burn CPU on every call.
+ */
+const patternCache = new Map();
+/**
+ * Threshold above which `touchCacheEntry` actually performs the LRU
+ * refresh. Below this watermark the cache has zero eviction pressure, so
+ * the delete+set on every hit would be pure overhead. Above it we refresh
+ * properly so hot patterns survive evictions. 75% of capacity is the
+ * standard sweet spot.
+ */
+const LRU_REFRESH_THRESHOLD = Math.floor((MAX_CACHE_SIZE * 3) / 4);
+function touchCacheEntry(pattern, entry) {
+    if (patternCache.size < LRU_REFRESH_THRESHOLD) {
+        return;
+    }
+    patternCache.delete(pattern);
+    patternCache.set(pattern, entry);
+}
+function setCacheEntry(pattern, entry) {
+    if (patternCache.size >= MAX_CACHE_SIZE) {
+        const oldestKey = patternCache.keys().next().value;
+        if (oldestKey !== undefined) {
+            patternCache.delete(oldestKey);
+        }
+    }
+    patternCache.set(pattern, entry);
+}
+function skipGroupSyntaxPrefix(pattern, start) {
+    if (start >= pattern.length || pattern[start] !== '?') {
+        return start;
+    }
+    let i = start + 1;
+    if (i >= pattern.length) {
+        return i;
+    }
+    const modifier = pattern[i];
+    if (modifier === ':' || modifier === '=' || modifier === '!') {
+        return i + 1;
+    }
+    if (modifier !== '<') {
+        return i;
+    }
+    i++;
+    if (i < pattern.length && (pattern[i] === '=' || pattern[i] === '!')) {
+        return i + 1;
+    }
+    while (i < pattern.length && pattern[i] !== '>') {
+        i++;
+    }
+    if (i < pattern.length) {
+        i++;
+    }
+    return i;
+}
+/**
+ * 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.
+ */
+function hasNestedQuantifier(pattern) {
+    const stack = [];
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '\\') {
+            i += 2;
+            continue;
+        }
+        if (ch === '[') {
+            i = findCharClassEnd(pattern, i) + 1;
+            continue;
+        }
+        if (ch === '(') {
+            stack.push({ hasBacktrackRisk: false });
+            i = skipGroupSyntaxPrefix(pattern, i + 1);
+            continue;
+        }
+        if (ch === ')') {
+            const frame = stack.pop();
+            if (frame === undefined) {
+                i++;
+                continue;
+            }
+            const next = pattern[i + 1];
+            const isQuantifier = next === '*' || next === '+' || next === '?' || next === '{';
+            if (isQuantifier && frame.hasBacktrackRisk) {
+                return true;
+            }
+            if (stack.length > 0 && (frame.hasBacktrackRisk || isQuantifier)) {
+                stack[stack.length - 1].hasBacktrackRisk = true;
+            }
+            i++;
+            continue;
+        }
+        if (ch === '*' || ch === '+' || ch === '?' || ch === '{') {
+            if (stack.length > 0) {
+                stack[stack.length - 1].hasBacktrackRisk = true;
+            }
+        }
+        i++;
+    }
+    return false;
+}
+function findCharClassEnd(pattern, start) {
+    let i = start + 1;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '\\') {
+            i += 2;
+            continue;
+        }
+        if (ch === ']') {
+            return i;
+        }
+        i++;
+    }
+    return pattern.length - 1;
+}
+function compile(pattern) {
+    const cached = patternCache.get(pattern);
+    if (cached !== undefined) {
+        touchCacheEntry(pattern, cached);
+        return cached.regex;
+    }
+    if (pattern.length > MAX_PATTERN_LENGTH) {
+        setCacheEntry(pattern, { regex: null });
+        return null;
+    }
+    if (hasNestedQuantifier(pattern)) {
+        setCacheEntry(pattern, { regex: null });
+        return null;
+    }
+    try {
+        const regex = new RegExp(pattern);
+        setCacheEntry(pattern, { regex });
+        return regex;
+    }
+    catch {
+        setCacheEntry(pattern, { regex: null });
+        return null;
+    }
+}
+/**
+ * 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.
+ */
+function matchesQuery(pattern, query) {
+    if (pattern === undefined || pattern === '') {
+        return true;
+    }
+    if (query === undefined || query === '') {
+        return false;
+    }
+    const regex = compile(pattern);
+    if (regex === null) {
+        return false;
+    }
+    return regex.test(query);
+}
+
+exports.MAX_CACHE_SIZE = MAX_CACHE_SIZE;
+exports.MAX_PATTERN_LENGTH = MAX_PATTERN_LENGTH;
+exports.hasNestedQuantifier = hasNestedQuantifier;
+exports.matchesQuery = matchesQuery;
+//# sourceMappingURL=matchers.cjs.map

package/dist/cjs/hooks/matchers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchers.cjs","sources":["../../../src/hooks/matchers.ts"],"sourcesContent":["// src/hooks/matchers.ts\n\n/**\n * Upper bound on hook-matcher pattern length. Patterns longer than this\n * are rejected outright — the goal is a cheap cap on pathological inputs\n * (repeated quantifiers, huge alternation groups) without pulling in a\n * safe-regex dependency.\n *\n * Legitimate matchers are almost always under 50 characters (tool names,\n * short alternations, simple prefix anchors); 512 leaves generous\n * headroom while preventing 10KB regexes.\n */\nexport const MAX_PATTERN_LENGTH = 512;\n\n/**\n * Upper bound on the compilation cache. Chosen to comfortably hold every\n * distinct pattern a single multi-tenant run is likely to see (tools,\n * agent types, basename filters) without growing without bound.\n *\n * Under hosts that register unique patterns per tenant, LRU eviction\n * keeps the working set bounded — cold patterns are re-compiled on next\n * use, which is the correct cost trade-off for long-running processes\n * that must not leak memory.\n */\nexport const MAX_CACHE_SIZE = 256;\n\ninterface CacheEntry {\n  regex: RegExp | null;\n}\n\n/**\n * Module-level LRU cache keyed by pattern string. Map iteration order is\n * insertion order in ECMAScript, so refreshing an entry's position means\n * \"delete then re-set\". On overflow we evict the first key (least\n * recently used).\n *\n * Failed compiles are cached as `{ regex: null }` so a malformed pattern\n * does not re-enter the compiler — and so a tenant spamming bad patterns\n * doesn't burn CPU on every call.\n */\nconst patternCache: Map<string, CacheEntry> = new Map();\n\n/**\n * Threshold above which `touchCacheEntry` actually performs the LRU\n * refresh. Below this watermark the cache has zero eviction pressure, so\n * the delete+set on every hit would be pure overhead. Above it we refresh\n * properly so hot patterns survive evictions. 75% of capacity is the\n * standard sweet spot.\n */\nconst LRU_REFRESH_THRESHOLD = Math.floor((MAX_CACHE_SIZE * 3) / 4);\n\nfunction touchCacheEntry(pattern: string, entry: CacheEntry): void {\n  if (patternCache.size < LRU_REFRESH_THRESHOLD) {\n    return;\n  }\n  patternCache.delete(pattern);\n  patternCache.set(pattern, entry);\n}\n\nfunction setCacheEntry(pattern: string, entry: CacheEntry): void {\n  if (patternCache.size >= MAX_CACHE_SIZE) {\n    const oldestKey = patternCache.keys().next().value;\n    if (oldestKey !== undefined) {\n      patternCache.delete(oldestKey);\n    }\n  }\n  patternCache.set(pattern, entry);\n}\n\ninterface QuantifierFrame {\n  hasBacktrackRisk: boolean;\n}\n\nfunction skipGroupSyntaxPrefix(pattern: string, start: number): number {\n  if (start >= pattern.length || pattern[start] !== '?') {\n    return start;\n  }\n  let i = start + 1;\n  if (i >= pattern.length) {\n    return i;\n  }\n  const modifier = pattern[i];\n  if (modifier === ':' || modifier === '=' || modifier === '!') {\n    return i + 1;\n  }\n  if (modifier !== '<') {\n    return i;\n  }\n  i++;\n  if (i < pattern.length && (pattern[i] === '=' || pattern[i] === '!')) {\n    return i + 1;\n  }\n  while (i < pattern.length && pattern[i] !== '>') {\n    i++;\n  }\n  if (i < pattern.length) {\n    i++;\n  }\n  return i;\n}\n\n/**\n * Cheap syntactic detector for the most common catastrophic-backtracking\n * shape: a quantified group that contains another quantifier (e.g.\n * `(a+)+`, `(.*)*`, `(\\w+)+$`, `(?:(a+))+`). This is the \"nested\n * quantifier\" class of ReDoS — runs in polynomial-or-worse time on\n * adversarial inputs.\n *\n * The scan walks the pattern linearly using an explicit stack of group\n * frames. For each group it tracks whether the group's contents include\n * \"backtrack risk\" — meaning a direct quantifier OR a nested group that\n * carries risk up. When a group closes with a trailing quantifier AND its\n * frame carries backtrack risk, the pattern is flagged. Risk propagates\n * to the enclosing frame when a child group closes (whether the child\n * itself was quantified or not), so `(?:(a+))+` — equivalent to `(a+)+`\n * — is flagged correctly even though the outer non-capturing wrapper is\n * one level removed from the inner quantifier.\n *\n * ## Group-syntax prefixes\n *\n * Non-capturing groups (`(?:`), lookaheads (`(?=`, `(?!`), lookbehinds\n * (`(?<=`, `(?<!`), and named groups (`(?<name>`) are skipped over at\n * the `(` so their `?` is not misread as a quantifier. Without this,\n * `(?:pre_)?tool_name` would be incorrectly rejected because the scanner\n * would see the group-syntax `?` as a quantifier at depth 1.\n *\n * ## Heuristic, not a proof\n *\n * This catches the common forms but not all. Ambiguous-alternation ReDoS\n * like `(a|a)+` is not detected. Pathologically long patterns are also\n * caught by {@link MAX_PATTERN_LENGTH}. Hosts that accept user-supplied\n * patterns must still validate upstream.\n */\nexport function hasNestedQuantifier(pattern: string): boolean {\n  const stack: QuantifierFrame[] = [];\n  let i = 0;\n  while (i < pattern.length) {\n    const ch = pattern[i];\n    if (ch === '\\\\') {\n      i += 2;\n      continue;\n    }\n    if (ch === '[') {\n      i = findCharClassEnd(pattern, i) + 1;\n      continue;\n    }\n    if (ch === '(') {\n      stack.push({ hasBacktrackRisk: false });\n      i = skipGroupSyntaxPrefix(pattern, i + 1);\n      continue;\n    }\n    if (ch === ')') {\n      const frame = stack.pop();\n      if (frame === undefined) {\n        i++;\n        continue;\n      }\n      const next = pattern[i + 1];\n      const isQuantifier =\n        next === '*' || next === '+' || next === '?' || next === '{';\n      if (isQuantifier && frame.hasBacktrackRisk) {\n        return true;\n      }\n      if (stack.length > 0 && (frame.hasBacktrackRisk || isQuantifier)) {\n        stack[stack.length - 1].hasBacktrackRisk = true;\n      }\n      i++;\n      continue;\n    }\n    if (ch === '*' || ch === '+' || ch === '?' || ch === '{') {\n      if (stack.length > 0) {\n        stack[stack.length - 1].hasBacktrackRisk = true;\n      }\n    }\n    i++;\n  }\n  return false;\n}\n\nfunction findCharClassEnd(pattern: string, start: number): number {\n  let i = start + 1;\n  while (i < pattern.length) {\n    const ch = pattern[i];\n    if (ch === '\\\\') {\n      i += 2;\n      continue;\n    }\n    if (ch === ']') {\n      return i;\n    }\n    i++;\n  }\n  return pattern.length - 1;\n}\n\nfunction compile(pattern: string): RegExp | null {\n  const cached = patternCache.get(pattern);\n  if (cached !== undefined) {\n    touchCacheEntry(pattern, cached);\n    return cached.regex;\n  }\n  if (pattern.length > MAX_PATTERN_LENGTH) {\n    setCacheEntry(pattern, { regex: null });\n    return null;\n  }\n  if (hasNestedQuantifier(pattern)) {\n    setCacheEntry(pattern, { regex: null });\n    return null;\n  }\n  try {\n    const regex = new RegExp(pattern);\n    setCacheEntry(pattern, { regex });\n    return regex;\n  } catch {\n    setCacheEntry(pattern, { regex: null });\n    return null;\n  }\n}\n\n/**\n * Tests whether a hook matcher pattern matches the given query string.\n *\n * ## Semantics\n *\n * - `undefined` or empty `pattern` matches any query (wildcard). This is\n *   the intended shape for events that do not supply a query string at\n *   all (`RunStart`, `Stop`, etc.) — register such matchers without a\n *   pattern.\n * - `undefined` or empty `query` with a non-empty `pattern` never matches.\n *   Setting a pattern on a query-less event is therefore inert: the\n *   matcher will simply never fire. This is intentional — it keeps\n *   query-based filtering out of event types where \"query\" has no meaning,\n *   and is documented on `HookMatcher.pattern`.\n * - Otherwise, the pattern is compiled once (via a bounded LRU cache) and\n *   tested against the query.\n * - Invalid regex patterns never throw — a failed compile is cached as\n *   \"never matches\" so a single malformed pattern cannot take out a whole\n *   `executeHooks` batch.\n *\n * ## ReDoS mitigations\n *\n * Patterns compile through three cheap gates before reaching `new RegExp`:\n *\n * 1. {@link MAX_PATTERN_LENGTH} length cap rejects oversized inputs.\n * 2. {@link hasNestedQuantifier} rejects the most common catastrophic-\n *    backtracking shape (quantified group containing a quantifier).\n * 3. Successful compiles are cached in a bounded LRU so repeated calls\n *    never re-enter the regex compiler.\n *\n * These are a floor, not a ceiling. Hosts that accept user-supplied\n * patterns should still validate upstream. The design report §3.8 routes\n * persistable hooks through a host-side compiler before they reach this\n * module.\n */\nexport function matchesQuery(\n  pattern: string | undefined,\n  query: string | undefined\n): boolean {\n  if (pattern === undefined || pattern === '') {\n    return true;\n  }\n  if (query === undefined || query === '') {\n    return false;\n  }\n  const regex = compile(pattern);\n  if (regex === null) {\n    return false;\n  }\n  return regex.test(query);\n}\n\n/** Clears the regex compilation cache. Intended for test isolation. */\nexport function clearMatcherCache(): void {\n  patternCache.clear();\n}\n\n/** Returns the current size of the compilation cache. Intended for tests. */\nexport function getMatcherCacheSize(): number {\n  return patternCache.size;\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/hooks/types.cjs

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * 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.
+ */
+const HOOK_EVENTS = [
+    'RunStart',
+    'UserPromptSubmit',
+    'PreToolUse',
+    'PostToolUse',
+    'PostToolUseFailure',
+    'PermissionDenied',
+    'SubagentStart',
+    'SubagentStop',
+    'Stop',
+    'StopFailure',
+    'PreCompact',
+    'PostCompact',
+];
+
+exports.HOOK_EVENTS = HOOK_EVENTS;
+//# sourceMappingURL=types.cjs.map

package/dist/cjs/hooks/types.cjs.map

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