@librechat/agents 3.1.68 → 3.1.71-dev.0

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

@@ -4,8 +4,10 @@ import type { UsageMetadata, BaseMessage } from '@langchain/core/messages';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
 import { ToolNode as CustomToolNode } from '@/tools/ToolNode';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 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 +45,20 @@ 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;
+    /**
+     * Run-scoped config for the tool output reference registry. Threaded
+     * from `RunConfig.toolOutputReferences` down into every ToolNode this
+     * graph compiles.
+     */
+    toolOutputReferences: t.ToolOutputReferencesConfig | undefined;
+    /**
+     * Shared registry instance used by every ToolNode compiled from this
+     * graph. Lazily constructed on first access so multi-agent graphs
+     * produce one registry per run (not one per agent), letting cross-
+     * agent `{{tool<i>turn<n>}}` substitutions resolve.
+     */
+    private _toolOutputRegistry?;
     /**
      * Tool session contexts for automatic state persistence across tool invocations.
      * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
@@ -55,6 +71,13 @@ export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphStat
      * Call after a run completes and content has been extracted.
      */
     clearHeavyState(): void;
+    /**
+     * 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.
+     */
+    protected getOrCreateToolOutputRegistry(): ToolOutputReferenceRegistry | undefined;
 }
 export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
     overrideModel?: t.ChatModel;

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[];
+}

package/dist/types/index.d.ts

@@ -7,7 +7,14 @@ export * from './graphs';
 export * from './summarization';
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
+export * from './tools/BashProgrammaticToolCalling';
+export * from './tools/SkillTool';
+export * from './tools/SubagentTool';
+export * from './tools/subagent';
+export * from './tools/ReadFile';
+export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
 export * from './tools/schema';
@@ -15,6 +22,7 @@ export * from './tools/handlers';
 export * from './tools/search';
 export * from './common';
 export * from './utils';
+export * from './hooks';
 export type * from './types';
 export { CustomOpenAIClient } from './llm/openai';
 export { ChatOpenRouter } from './llm/openrouter';

package/dist/types/messages/format.d.ts

@@ -104,9 +104,10 @@ export declare const labelContentByAgent: (contentParts: MessageContentComplex[]
  * @param payload - The array of messages to format.
  * @param indexTokenCountMap - Optional map of message indices to token counts.
  * @param tools - Optional set of tool names that are allowed in the request.
+ * @param skills - Optional map of skill name to body for reconstructing skill HumanMessages.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>) => {
+export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
     /** Cross-run summary extracted from the payload. Should be forwarded to the

package/dist/types/run.d.ts

@@ -9,6 +9,8 @@ export declare class Run<_T extends t.BaseGraphState> {
     id: string;
     private tokenCounter?;
     private handlerRegistry?;
+    private hookRegistry?;
+    private toolOutputReferences?;
     private indexTokenCountMap?;
     calibrationRatio: number;
     graphRunnable?: t.CompiledStateWorkflow;

package/dist/types/summarization/node.d.ts

@@ -1,6 +1,7 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { AgentContext } from '@/agents/AgentContext';
+import type { HookRegistry } from '@/hooks';
 import type * as t from '@/types';
 /** Structured checkpoint prompt for fresh summarization (no prior summary). */
 export declare const DEFAULT_SUMMARIZATION_PROMPT = "Hold on, before you continue I need you to write me a checkpoint of everything so far. Your context window is filling up and this checkpoint replaces the messages above, so capture everything you need to pick right back up.\n\nDon't second-guess or fact-check anything you did, your tool results reflect exactly what happened. If a tool result appears truncated, that's just a display artifact from context management: the tool executed fully. Just record what you did and what you observed. Only the checkpoint, don't respond to me or continue the conversation.\n\n## Checkpoint\n\n## Goal\nWhat I asked you to do and any sub-goals you identified.\n\n## Constraints & Preferences\nAny rules, preferences, or configuration I established.\n\n## Progress\n### Done\n- What you completed and the outcomes\n\n### In Progress\n- What you're currently working on\n\n## Key Decisions\nDecisions you made and why.\n\n## Next Steps\nConcrete task actions remaining, in priority order.\n\n## Critical Context\nExact identifiers, names, error messages, URLs, and details you need to preserve verbatim.\n\nRules:\n- Record what you did and observed, don't judge or re-evaluate it\n- For each tool call: the tool name, key inputs, and the outcome\n- Preserve exact identifiers, names, errors, and references verbatim\n- Short declarative sentences\n- Skip empty sections";
@@ -14,6 +15,7 @@ interface CreateSummarizeNodeParams {
         config?: RunnableConfig;
         runId?: string;
         isMultiAgent: boolean;
+        hookRegistry?: HookRegistry;
         dispatchRunStep: (runStep: t.RunStep, config?: RunnableConfig) => Promise<void>;
         dispatchRunStepCompleted: (stepId: string, result: t.StepCompleted, config?: RunnableConfig) => Promise<void>;
     };