@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

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

@@ -7,6 +7,8 @@
 export declare enum GraphEvents {
     /** [Custom] Agent update event in multi-agent graph/workflow */
     ON_AGENT_UPDATE = "on_agent_update",
+    /** [Custom] Subagent lifecycle event (start, run_step, message_delta, stop, error) */
+    ON_SUBAGENT_UPDATE = "on_subagent_update",
     /** [Custom] Delta event for run steps (message creation and tool calls) */
     ON_RUN_STEP = "on_run_step",
     /** [Custom] Delta event for run steps (tool calls) */
@@ -79,12 +81,22 @@ export declare enum Providers {
     MOONSHOT = "moonshot"
 }
 export declare enum EdgeType {
-    /** True agent handoff — parent calls child agent inline, gets result back, continues orchestrating */
+    /**
+     * Upstream-aligned handoff: one-way routing where the parent agent exits
+     * via a `lc_transfer_to_<destination>` tool call, the child takes over,
+     * and the child responds directly to the user. Replaces what used to be
+     * called "TRANSFER" in earlier Ranger versions; the parent-calls-child
+     * supervisor pattern (formerly `EdgeType.HANDOFF`) is gone — use the
+     * Subagent primitive (Tier 5) for deep delegation instead.
+     */
     HANDOFF = "handoff",
-    /** One-way transfer — parent exits, child takes over and responds directly to user */
-    TRANSFER = "transfer",
-    /** Fixed graph edges for automatic sequential/parallel transitions */
-    SEQUENCE = "sequence"
+    /**
+     * Fixed graph edges for automatic transitions. Naming matches upstream.
+     * Ranger keeps its enriched wiring on top of this edge type:
+     * fan-in with prompt + {results}, parallel groups, ApprovalGateNode
+     * insertion, and the `excludeResults` agentMessages channel.
+     */
+    DIRECT = "direct"
 }
 export declare enum GraphNodeKeys {
     TOOLS = "tools=",
@@ -137,17 +149,30 @@ export declare enum Callback {
 export declare enum Constants {
     OFFICIAL_CODE_BASEURL = "https://api.illuma.ai/v1",
     EXECUTE_CODE = "execute_code",
+    /** Tool name for the bash execution primitive (upstream Tier 3). */
+    BASH_TOOL = "execute_bash",
+    /** Tool name for the bash programmatic-tool-calling variant (upstream Tier 3). */
+    BASH_PROGRAMMATIC_TOOL_CALLING = "run_tools_with_bash",
+    /** Tool name for the read-file primitive (upstream Tier 3). */
+    READ_FILE = "read_file",
+    /** Tool name for the SkillTool primitive (upstream Tier 2). */
+    SKILL_TOOL = "skill",
+    /** Tool name for the Subagent primitive (upstream Tier 5). */
+    SUBAGENT = "subagent",
     TOOL_SEARCH = "tool_search",
     PROGRAMMATIC_TOOL_CALLING = "run_tools_with_code",
     WEB_SEARCH = "web_search",
     CONTENT_AND_ARTIFACT = "content_and_artifact",
+    /** Prefix for handoff tool names (parent-exits routing): lc_transfer_to_{agentId}. */
     LC_TRANSFER_TO_ = "lc_transfer_to_",
-    /** Prefix for handoff tool names: lc_handoff_to_{agentId} */
-    LC_HANDOFF_TO_ = "lc_handoff_to_",
     /** Tool name for the AskUser structured question tool */
     ASK_USER = "ask_user",
     /** Delimiter for MCP tools: toolName_mcp_serverName */
-    MCP_DELIMITER = "_mcp_"
+    MCP_DELIMITER = "_mcp_",
+    /** Prefix for Anthropic-hosted server tool ids (web_search, code_execution).
+     *  These are issued by Anthropic, not by us, and should be ignored by
+     *  orphan-repair sweeps that don't have ground truth for them. */
+    ANTHROPIC_SERVER_TOOL_PREFIX = "srvtoolu_"
 }
 export declare enum TitleMethod {
     STRUCTURED = "structured",
@@ -191,7 +216,9 @@ export declare enum MessageTypes {
     DEVELOPER = "developer",
     REMOVE = "remove"
 }
-/** Default max characters for handoff results returned to parent (~8192 tokens at ~4 chars/token) */
-export declare const DEFAULT_HANDOFF_MAX_RESULT_CHARS = 32768;
-/** Default timeout for handoff sub-agent execution in milliseconds (5 minutes) */
-export declare const HANDOFF_TIMEOUT_MS = 300000;
+/**
+ * Tool names that use the code execution environment (shared session, file
+ * tracking). Used by ToolNode to inject session context + file refs into
+ * `invokeParams` before tool execution. Upstream-aligned constant.
+ */
+export declare const CODE_EXECUTION_TOOLS: ReadonlySet<string>;

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

@@ -1,4 +1,3 @@
 export * from './enum';
 export * from './constants';
-export * from './spawnPath';
 export * from '../tools/approval/constants';

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

@@ -46,6 +46,49 @@ 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;
+    /** Optional hook registry threaded down from Run; consumed by ToolNode for tool-lifecycle hooks. */
+    hookRegistry?: import('@/hooks').HookRegistry;
+    /**
+     * Optional tool-output reference registry threaded down from Run
+     * (upstream PR #114). When set, every ToolNode built by this graph
+     * stores successful outputs here and resolves `{{tool<i>turn<n>}}`
+     * placeholders in args before invoking the tool.
+     *
+     * @deprecated Prefer `toolOutputReferences` config + the lazy
+     * `getOrCreateToolOutputRegistry()` accessor — keeps the registry
+     * lifecycle explicit (cleared in `clearHeavyState()`). Existing
+     * direct-set callers still work for backwards compat.
+     */
+    toolOutputRegistry?: import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry;
+    /**
+     * Run-scoped tool output reference configuration (upstream PR #117).
+     * When `enabled` is true, the graph lazily allocates a single
+     * `ToolOutputReferenceRegistry` on first `getOrCreateToolOutputRegistry()`
+     * call and shares it with every ToolNode the graph compiles, so
+     * cross-agent `{{tool<i>turn<n>}}` substitutions resolve.
+     */
+    toolOutputReferences?: import('@/types/tools').ToolOutputReferencesConfig;
+    /**
+     * Lazy single-instance registry for the run. Constructed on first
+     * `getOrCreateToolOutputRegistry()` call when
+     * `toolOutputReferences.enabled` is true. Cleared (and recreated on
+     * next access) by `clearHeavyState()`.
+     */
+    private _toolOutputRegistry?;
+    /**
+     * Returns the shared `ToolOutputReferenceRegistry` for this run,
+     * constructing it on first access. Returns `undefined` when the
+     * feature is disabled. All ToolNodes compiled from this graph share
+     * this single instance so cross-agent `{{...}}` references resolve.
+     *
+     * @internal Public so `attemptInvoke` can read it through the typed
+     * `InvokeContext` and project ToolMessages into LLM-facing annotated
+     * copies right before each provider call (see `annotateMessagesForLLM`).
+     * Host code should not call this directly — registry mutations outside
+     * the ToolNode lifecycle break the partitioning, eviction, and
+     * turn-counter invariants.
+     */
+    getOrCreateToolOutputRegistry(): import('@/tools/toolOutputReferences').ToolOutputReferenceRegistry | undefined;
     /**
      * Tool session contexts for automatic state persistence across tool invocations.
      * Keyed by tool name (e.g., Constants.EXECUTE_CODE).

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

@@ -1,4 +1,3 @@
-import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { StandardGraph } from './Graph';
 /**
@@ -6,29 +5,20 @@ import { StandardGraph } from './Graph';
  * with handoffs, fan-in/fan-out, and other composable patterns.
  *
  * Key behavior:
- * - Agents with ONLY transfer edges: Can dynamically route to any transfer destination
- * - Agents with ONLY sequence edges: Always follow their sequence edges
- * - Agents with BOTH: Use Command for exclusive routing (transfer OR sequence, not both)
- *   - If transfer occurs: Only the transfer destination executes
- *   - If no transfer: Sequence edges execute (potentially in parallel)
+ * - Agents with ONLY handoff edges: Can dynamically route to any handoff destination
+ * - Agents with ONLY direct edges: Always follow their direct edges
+ * - Agents with BOTH: Use Command for exclusive routing (handoff OR direct, not both)
+ *   - If handoff occurs: Only the handoff destination executes
+ *   - If no handoff: Direct edges execute (potentially in parallel)
  *
- * This enables the common pattern where an agent either transfers (one-way)
- * OR continues its workflow (sequence edges), but not both simultaneously.
+ * This enables the common pattern where an agent either delegates (handoff)
+ * OR continues its workflow (direct edges), but not both simultaneously.
  */
 export declare class MultiAgentGraph extends StandardGraph {
     private edges;
     private startingNodes;
-    private sequenceEdges;
-    private transferEdges;
+    private directEdges;
     private handoffEdges;
-    /**
-     * Lazily populated registry of compiled subgraphs, keyed by agentId.
-     * Handoff tools are created in the constructor but reference subgraphs
-     * that are only created in createWorkflow(). This Map bridges that gap —
-     * tools capture the Map reference in their closure, and createWorkflow()
-     * populates it before any tool invocation occurs.
-     */
-    private subgraphRegistry;
     /**
      * Map of agentId to parallel group info.
      * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
@@ -40,25 +30,21 @@ export declare class MultiAgentGraph extends StandardGraph {
      * - summarizer: undefined (sequential, order 2)
      */
     private agentParallelGroups;
+    constructor(input: t.MultiAgentGraphInput);
     /**
-     * Tracks the ID of the last agent that produced output.
-     * Used by auto-continuation to know which agent's context to preserve after handoff.
-     */
-    private lastActiveAgentId;
-    /**
-     * Registry for async handoff execution.
-     * Enables autonomous orchestration: spawn children non-blocking,
-     * orchestrator stays alive to reason and collect results when ready.
-     */
-    /**
-     * When set, the graph routes START to this agent instead of the default starting nodes.
-     * Enables multi-turn resumption: follow-up messages go to the agent that last handled
-     * the conversation rather than restarting from the root/router agent.
+     * Fails fast when an edge references an agent that is not in
+     * `agentContexts`. Without this check, the underlying LangGraph
+     * `StateGraph.compile()` would throw the opaque
+     * `Found edge ending at unknown node "<id>"` error after graph
+     * construction — far from the true root cause.
+     *
+     * This catches the common misuse of passing `edges` into a multi-agent
+     * config without also passing the corresponding sub-agent configs in
+     * `agents` (e.g. a host that forgot to pre-load handoff targets).
      */
-    private resumeFromAgentId;
-    constructor(input: t.MultiAgentGraphInput);
+    private validateEdgeAgents;
     /**
-     * Categorize edges into handoff, transfer, and sequence types
+     * Categorize edges into handoff and direct types
      */
     private categorizeEdges;
     /**
@@ -86,12 +72,6 @@ export declare class MultiAgentGraph extends StandardGraph {
      * Group IDs are incrementing numbers reflecting execution order.
      */
     getParallelGroupId(agentId: string): number | undefined;
-    /**
-     * Returns the ID of the last agent that produced output.
-     * Used by auto-continuation to determine which agent's context to preserve
-     * when a response is truncated after an agent handoff.
-     */
-    getLastActiveAgentId(): string | undefined;
     /**
      * Override to indicate this is a multi-agent graph.
      * Enables agentId to be included in RunStep for frontend agent labeling.
@@ -102,112 +82,20 @@ export declare class MultiAgentGraph extends StandardGraph {
      */
     protected getParallelGroupIdForAgent(agentId: string): number | undefined;
     /**
-     * Create transfer tools for agents based on transfer edges only.
-     * Transfer tools return Command for one-way routing — parent exits, child takes over.
-     */
-    private createTransferTools;
-    /**
-     * Create transfer tools for an edge (handles multiple destinations).
-     * Transfer tools return Command for one-way routing — parent exits, child takes over.
-     * @param edge - The graph edge defining the transfer
-     * @param sourceAgentId - The ID of the agent that will perform the transfer
-     * @param sourceAgentName - The human-readable name of the source agent
-     */
-    private createTransferToolsForEdge;
-    /**
-     * Builds orchestration guidance injected into the system message of agents
-     * that have handoff or transfer tools (i.e., orchestrator agents).
-     *
-     * Implements two orchestration primitives:
-     * - Execution bias guidance injected into the system prompt
-     * - Multi-round autonomous execution for dependent tasks
-     *
-     * Handoff tools are synchronous (browser-tool callback pattern): spawn the
-     * child, await completion, return the real text as the tool output. Parallel
-     * handoff tool calls in one turn run concurrently via LangGraph's ToolNode,
-     * so independent children run in parallel without explicit orchestration.
-     *
-     * @param childDescs - Display names (with optional descriptions) of child agents
-     * @param toolCount - Number of handoff/transfer tools available
-     */
-    private buildOrchestratorGuidance;
-    /**
-     * Builds subagent context instructions injected into child agents that are
-     * handoff destinations. This tells the child agent it is a subagent with
-     * a focused task.
-     *
-     * @param orchestratorName - Display name of the parent orchestrator agent
-     */
-    private buildChildAgentContext;
-    /**
-     * Builds a meaningful default description for a transfer tool when no explicit
-     * edge.description is provided. Uses the destination agent's name and description
-     * so the LLM can make informed routing decisions.
-     * @param destContext - AgentContext of the destination agent (may be undefined)
-     * @param destinationId - Raw agent ID (fallback when context unavailable)
-     */
-    private buildDefaultTransferDescription;
-    /**
-     * Create handoff tools for agents based on handoff edges.
-     * Handoff tools invoke child agent subgraphs inline and return the result
-     * as a string to the parent agent's context. Unlike transfer tools (which
-     * return Command for one-way routing), handoff tools execute the child,
-     * extract the final text, and return it within the parent's agent loop.
-     *
-     * This enables the supervisor pattern: parent calls child → gets result → thinks → calls another.
+     * Create handoff tools for agents based on handoff edges only
      */
     private createHandoffTools;
     /**
-     * Create handoff tools for an edge (handles multiple destinations).
-     * Each handoff tool spawns the child agent's compiled subgraph asynchronously
-     * and returns immediately. The orchestrator uses `collect_results` to retrieve
-     * outputs and `check_agents` to monitor status — a push-based autonomous
-     * orchestration pattern.
-     *
+     * Create handoff tools for an edge (handles multiple destinations)
      * @param edge - The graph edge defining the handoff
-     * @param sourceAgentId - The ID of the parent/supervisor agent
+     * @param sourceAgentId - The ID of the agent that will perform the handoff
+     * @param sourceAgentName - The human-readable name of the source agent
      */
     private createHandoffToolsForEdge;
-    /**
-     * Extract the final text result from a child agent's output messages.
-     * Walks backwards to find the last AIMessage with text content.
-     * Handles both string content and array content (multi-modal messages).
-     * @param messages - The child agent's output messages
-     * @param agentId - The child agent ID (for fallback message)
-     */
-    static extractHandoffResult(messages: BaseMessage[], agentId: string): string;
-    /**
-     * Truncate handoff result using head/tail strategy (60/40 split).
-     * Preserves the beginning (key findings) and end (conclusions).
-     * Matches the TaskTool.truncateResult pattern used by host orchestrators.
-     * @param result - The full result text
-     * @param maxChars - Maximum allowed characters
-     */
-    static truncateHandoffResult(result: string, maxChars: number): string;
-    /**
-     * Build a meaningful default description for a handoff tool.
-     * @param destContext - AgentContext of the destination agent
-     * @param destinationId - Raw agent ID (fallback)
-     */
-    private buildDefaultHandoffDescription;
     /**
      * Create a complete agent subgraph (similar to createReactAgent)
      */
     private createAgentSubgraph;
-    /**
-     * BFS from `rootAgentId` across sequence + transfer edges (NOT handoff edges).
-     * Returns the set of agents reachable in this agent's "local workflow".
-     */
-    private computeReachableViaNonHandoff;
-    /**
-     * Build a compiled scoped StateGraph containing `agentIds` as nodes, rooted
-     * at `rootAgentId`. Linear sequence edges where both endpoints are in scope
-     * are wired directly; nodes with no outgoing in-scope edges route to END.
-     *
-     * Each node is wrapped around the per-agent `createAgentNode` compiled
-     * workflow (agent + tools loop) to preserve isolated tool context.
-     */
-    private buildScopedSubgraph;
     /**
      * Detects if the current agent is receiving a handoff and processes the messages accordingly.
      * Returns filtered messages with the transfer tool call/message removed, plus any instructions,
@@ -220,21 +108,9 @@ export declare class MultiAgentGraph extends StandardGraph {
      * @param agentId - The agent ID to check for handoff reception
      * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
      */
+    private processHandoffReception;
     /**
-     * Prepare messages for a handoff child agent. See
-     * {@link prepareHandoffMessagesUtil} for the full implementation and
-     * semantics — this static method is a thin delegate preserved for
-     * backward compatibility with existing call sites and unit tests.
-     */
-    static prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[];
-    /**
-     * Build an isolated message context for a downstream scoped-subgraph
-     * node. See {@link prepareIsolatedChildMessagesUtil} for details.
-     */
-    static prepareIsolatedChildMessages(messages: BaseMessage[]): BaseMessage[];
-    private processTransferReception;
-    /**
-     * Create the multi-agent workflow with handoffs, transfers, and sequences
+     * Create the multi-agent workflow with dynamic handoffs
      */
     createWorkflow(): t.CompiledMultiAgentWorkflow;
 }

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

@@ -1,3 +1,2 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
-export * from './HandoffRegistry';

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;