@librechat/agents 3.1.67-dev.4 → 3.1.68

package/dist/types/tools/SkillTool.d.ts

@@ -1,40 +0,0 @@
-import { Constants } from '@/common';
-export declare const SkillToolName = Constants.SKILL_TOOL;
-export declare const SkillToolDescription = "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
-/**
- * JSON Schema for the SkillTool parameters.
- * Single source of truth used by both SkillToolDefinition (LCTool registry)
- * and createSkillTool() (DynamicStructuredTool instance).
- */
-export declare const SkillToolSchema: {
-    readonly type: "object";
-    readonly properties: {
-        readonly skillName: {
-            readonly type: "string";
-            readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
-        };
-        readonly args: {
-            readonly type: "string";
-            readonly description: "Optional freeform arguments string passed to the skill.";
-        };
-    };
-    readonly required: readonly ["skillName"];
-};
-export declare const SkillToolDefinition: {
-    readonly name: Constants.SKILL_TOOL;
-    readonly description: "Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.\n\nWHEN TO USE:\n- The user's request matches a skill listed in the \"Available Skills\" section of the system prompt.\n- You MUST invoke the matching skill BEFORE attempting the task yourself.\n\nWHAT HAPPENS:\n- The skill's full instructions are loaded into the conversation as context.\n- Files bundled with the skill may become accessible via available tools.\n- Follow the skill's instructions to complete the task.\n\nCONSTRAINTS:\n- Do not invoke a skill that is already active in this conversation.\n- Skill names come from the catalog only. Do not guess names.";
-    readonly parameters: {
-        readonly type: "object";
-        readonly properties: {
-            readonly skillName: {
-                readonly type: "string";
-                readonly description: "The kebab-case identifier of the skill to invoke (e.g. \"financial-analyzer\", \"meeting-notes\"). Must match a name from the \"Available Skills\" section.";
-            };
-            readonly args: {
-                readonly type: "string";
-                readonly description: "Optional freeform arguments string passed to the skill.";
-            };
-        };
-        readonly required: readonly ["skillName"];
-    };
-};

package/dist/types/tools/SubagentTool.d.ts

@@ -1,36 +0,0 @@
-import { Constants } from '@/common';
-import type { SubagentConfig } from '@/types';
-import type { JsonSchemaType, LCTool } from '@/types/tools';
-export declare const SubagentToolName = Constants.SUBAGENT;
-export declare const SubagentToolDescription = "Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result \u2014 all intermediate tool calls, reasoning, and context stay isolated.\n\nWHEN TO USE:\n- The task is self-contained and can be described in a single prompt.\n- You want to offload verbose or exploratory work without bloating your own context.\n- A specialized subagent is available for the task domain.\n\nWHAT HAPPENS:\n- A fresh agent is created with the task description as its only input.\n- The subagent runs to completion using its own tools and context.\n- Only the final text response is returned to you.\n\nCONSTRAINTS:\n- subagent_type must match one of the available types listed below.\n- The subagent cannot see your conversation history.";
-export declare const SubagentToolSchema: {
-    readonly type: "object";
-    readonly properties: {
-        readonly description: {
-            readonly type: "string";
-            readonly description: "Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.";
-        };
-        readonly subagent_type: {
-            readonly type: "string";
-            readonly description: "Which subagent type to delegate to. Must be one of the available types.";
-        };
-    };
-    readonly required: string[];
-};
-export declare const SubagentToolDefinition: LCTool;
-/**
- * Build the name, schema, and description params for `tool()` from available configs.
- * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
- * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
- */
-export declare function buildSubagentToolParams(configs: SubagentConfig[]): {
-    name: string;
-    schema: JsonSchemaType;
-    description: string;
-};
-/**
- * Create a SubagentTool LCTool definition with dynamic enum and description
- * populated from the available subagent configs.
- * Used for the tool registry in event-driven mode.
- */
-export declare function createSubagentToolDefinition(configs: SubagentConfig[]): LCTool;

package/dist/types/tools/skillCatalog.d.ts

@@ -1,19 +0,0 @@
-import type { SkillCatalogEntry } from '@/types';
-export type SkillCatalogOptions = {
-    /** Total context window in tokens. Default: 200_000 */
-    contextWindowTokens?: number;
-    /** Fraction of context budget for catalog. Default: 0.01 (1%) */
-    budgetPercent?: number;
-    /** Max chars per entry description. Default: 250 */
-    maxEntryChars?: number;
-    /** Descriptions below this length trigger names-only fallback. Default: 20 */
-    minDescLength?: number;
-    /** Approximate chars per token for budget calculation. Default: 4 */
-    charsPerToken?: number;
-};
-/**
- * Formats a skill catalog for injection into agent context.
- * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
- * Returns empty string for empty input.
- */
-export declare function formatSkillCatalog(skills: SkillCatalogEntry[], opts?: SkillCatalogOptions): string;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -1,137 +0,0 @@
-import type { BaseMessage } from '@langchain/core/messages';
-import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, TokenCounter } from '@/types';
-import type { HookRegistry } from '@/hooks';
-import type { AgentContext } from '@/agents/AgentContext';
-import type { StandardGraph } from '@/graphs/Graph';
-import type { HandlerRegistry } from '@/events';
-export type SubagentExecuteParams = {
-    description: string;
-    subagentType: string;
-    threadId?: string;
-    /**
-     * Parent-side `tool_call_id` of the `subagent` tool invocation that
-     * triggered this execution. Surfaced on {@link SubagentUpdateEvent} so
-     * hosts can correlate child updates back to the originating tool call
-     * without relying on event ordering heuristics.
-     */
-    parentToolCallId?: string;
-};
-export type SubagentExecuteResult = {
-    content: string;
-    messages: BaseMessage[];
-};
-/**
- * Factory that constructs a child graph for subagent execution. Injected
- * rather than imported so that `SubagentExecutor` does not have a runtime
- * dependency on `StandardGraph` — this avoids a circular dependency between
- * `src/graphs/Graph.ts` and `src/tools/subagent/` that would otherwise break
- * Rollup's chunking under `preserveModules`.
- */
-export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
-export type SubagentExecutorOptions = {
-    configs: Map<string, ResolvedSubagentConfig>;
-    parentSignal?: AbortSignal;
-    hookRegistry?: HookRegistry;
-    parentRunId: string;
-    parentAgentId?: string;
-    tokenCounter?: TokenCounter;
-    /** Remaining nesting budget. 0 or negative blocks execution. */
-    maxDepth?: number;
-    /**
-     * Factory for constructing the isolated child graph. Callers pass
-     * `(input) => new StandardGraph(input)` — injected to break a circular
-     * module dependency.
-     */
-    createChildGraph: ChildGraphFactory;
-    /**
-     * Parent's event handler registry. When provided, child-graph events are
-     * forwarded through this registry so hosts can:
-     *   (a) execute event-driven tools (`ON_TOOL_EXECUTE` routed to parent's handler),
-     *   (b) surface child activity to a UI via wrapped {@link GraphEvents.ON_SUBAGENT_UPDATE}.
-     * When omitted, the child runs fully isolated (legacy behavior).
-     *
-     * Can be a direct `HandlerRegistry` or a zero-arg getter — use the getter
-     * form when the registry is assigned to the graph AFTER the executor is
-     * constructed (the current `Run.create` flow sets `handlerRegistry`
-     * post-`createWorkflow`, so `createAgentNode` must capture lazily).
-     */
-    parentHandlerRegistry?: HandlerRegistry | (() => HandlerRegistry | undefined);
-};
-export declare class SubagentExecutor {
-    private readonly configs;
-    private readonly parentSignal?;
-    private readonly hookRegistry?;
-    private readonly parentRunId;
-    private readonly parentAgentId?;
-    private readonly tokenCounter?;
-    private readonly maxDepth;
-    private readonly createChildGraph;
-    private readonly resolveParentHandlerRegistry?;
-    constructor(options: SubagentExecutorOptions);
-    /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
-    private getParentHandlerRegistry;
-    execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
-    /**
-     * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
-     * parent's handler registry. Silent no-op when no parent registry is set.
-     * Errors are swallowed — update events are observational.
-     */
-    private emitSubagentUpdate;
-    /**
-     * Builds a BaseCallbackHandler that intercepts the child graph's custom
-     * events. Routing rules:
-     *   - `ON_TOOL_EXECUTE` → forwarded as-is to the parent's ON_TOOL_EXECUTE
-     *     handler (so event-driven tools work identically for child and parent).
-     *   - `ON_RUN_STEP` / `ON_RUN_STEP_DELTA` / `ON_RUN_STEP_COMPLETED` /
-     *     `ON_MESSAGE_DELTA` / `ON_REASONING_DELTA` → wrapped in a
-     *     {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope with a human-readable
-     *     label, delivered to the parent's subagent-update handler.
-     *   - Everything else → ignored (keeps parent's UI scoped to the events it
-     *     cares about; host apps can extend by registering more phases).
-     */
-    private createForwarderCallback;
-}
-/**
- * Produces a short single-line label for an arbitrary forwarded child event.
- * Used to populate {@link SubagentUpdateEvent.label} so the host UI can show
- * a compact status ticker without parsing the raw payload.
- */
-export declare function summarizeEvent(eventName: string, data: unknown): string;
-/**
- * Walk messages from last to first, returning the text content of the most
- * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
- * redacted_thinking, tool_result) are stripped. If the last AIMessage is
- * pure tool_use (e.g. the subagent hit `maxTurns` mid-tool-call), the walk
- * continues to earlier AIMessages so partial progress is salvaged — this
- * matches Claude Code's behavior in `agentToolUtils.finalizeAgentTool`.
- * Returns "Task completed" only when no AIMessage in the history contains
- * any text.
- */
-export declare function filterSubagentResult(messages: BaseMessage[]): string;
-/**
- * Resolve self-spawn configs by filling in agentInputs from the parent context.
- * Returns configs with agentInputs guaranteed present. Throws on duplicate
- * `type` values to prevent silent config shadowing.
- */
-export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
-/**
- * Build child AgentInputs from a resolved config, stripping nesting and
- * (optionally) event-driven fields. When `allowNested: true`, the child's
- * `maxSubagentDepth` is decremented so that depth is consumed as the call
- * chain deepens across graph boundaries — the parent's executor-level check
- * alone cannot see into the child graph's separate executor.
- *
- * When `keepToolDefinitions` is `true`, the child retains the parent's
- * `toolDefinitions` so event-driven tools remain usable. This is only safe
- * when the caller has wired a forwarder for `ON_TOOL_EXECUTE` to a
- * registered handler — otherwise the child will hang on tool dispatch.
- *
- * @remarks Advanced utility: exported primarily for testing and by
- * {@link SubagentExecutor}. Host applications configuring subagents should
- * not need to call this directly — it is invoked internally when a subagent
- * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
- * child's decremented `maxSubagentDepth` on the returned inputs) is the
- * mechanism that bounds nesting across graph boundaries; callers must
- * respect it.
- */
-export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number, keepToolDefinitions?: boolean): AgentInputs;

package/dist/types/tools/subagent/index.d.ts

@@ -1,2 +0,0 @@
-export { SubagentExecutor, filterSubagentResult, resolveSubagentConfigs, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
-export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';

package/dist/types/types/skill.d.ts

@@ -1,9 +0,0 @@
-/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
-export type SkillCatalogEntry = {
-    /** Kebab-case identifier (what the model passes to SkillTool) */
-    name: string;
-    /** One-line description for the catalog listing */
-    description: string;
-    /** Optional human-readable label (UI only, not shown to model) */
-    displayTitle?: string;
-};

package/src/hooks/HookRegistry.ts

@@ -1,208 +0,0 @@
-// src/hooks/HookRegistry.ts
-import type { HookEvent, HookMatcher } from './types';
-
-/**
- * Internal matcher storage type.
- *
- * Matchers registered via the public `register<E>` API are strictly typed
- * to a single `E`, but the storage needs one uniform slot type per event.
- * We store them as `HookMatcher<HookEvent>` and cast once at the variance
- * boundary — see `ensureList` and `snapshot` below. The invariant (every
- * matcher in `bucket[event]` was registered with that exact event) is
- * enforced by the public API; breaking it requires bypassing the types.
- */
-type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
-
-/**
- * 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 class HookRegistry {
-  private readonly global: MatcherBucket = {};
-  private readonly sessions: Map<string, MatcherBucket> = new Map();
-
-  /**
-   * 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 {
-    const list = ensureList(this.global, event);
-    list.push(widen(matcher));
-    return () => {
-      removeFromList(list, matcher);
-    };
-  }
-
-  /**
-   * 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 {
-    const bucket = this.ensureSessionBucket(sessionId);
-    const list = ensureList(bucket, event);
-    list.push(widen(matcher));
-    return () => {
-      removeFromList(list, matcher);
-    };
-  }
-
-  /**
-   * 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>[] {
-    const globalList = readList(this.global, event);
-    if (sessionId === undefined) {
-      return snapshot<E>(globalList);
-    }
-    const bucket = this.sessions.get(sessionId);
-    if (bucket === undefined) {
-      return snapshot<E>(globalList);
-    }
-    const sessionList = readList(bucket, event);
-    if (globalList.length === 0) {
-      return snapshot<E>(sessionList);
-    }
-    if (sessionList.length === 0) {
-      return snapshot<E>(globalList);
-    }
-    return snapshot<E>([...globalList, ...sessionList]);
-  }
-
-  /**
-   * 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 {
-    if (removeFromList(readList(this.global, event), matcher)) {
-      return true;
-    }
-    if (sessionId === undefined) {
-      return false;
-    }
-    const bucket = this.sessions.get(sessionId);
-    if (bucket === undefined) {
-      return false;
-    }
-    return removeFromList(readList(bucket, event), matcher);
-  }
-
-  /**
-   * 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 {
-    this.sessions.delete(sessionId);
-  }
-
-  /** True if at least one matcher exists for `event` (global + session). */
-  hasHookFor(event: HookEvent, sessionId?: string): boolean {
-    if (readList(this.global, event).length > 0) {
-      return true;
-    }
-    if (sessionId === undefined) {
-      return false;
-    }
-    const bucket = this.sessions.get(sessionId);
-    if (bucket === undefined) {
-      return false;
-    }
-    return readList(bucket, event).length > 0;
-  }
-
-  private ensureSessionBucket(sessionId: string): MatcherBucket {
-    const existing = this.sessions.get(sessionId);
-    if (existing !== undefined) {
-      return existing;
-    }
-    const fresh: MatcherBucket = {};
-    this.sessions.set(sessionId, fresh);
-    return fresh;
-  }
-}
-
-function ensureList(
-  bucket: MatcherBucket,
-  event: HookEvent
-): HookMatcher<HookEvent>[] {
-  const existing = bucket[event];
-  if (existing !== undefined) {
-    return existing;
-  }
-  const fresh: HookMatcher<HookEvent>[] = [];
-  bucket[event] = fresh;
-  return fresh;
-}
-
-function readList(
-  bucket: MatcherBucket,
-  event: HookEvent
-): HookMatcher<HookEvent>[] {
-  return bucket[event] ?? [];
-}
-
-function removeFromList<E extends HookEvent>(
-  list: HookMatcher<HookEvent>[],
-  matcher: HookMatcher<E>
-): boolean {
-  const idx = list.indexOf(widen(matcher));
-  if (idx < 0) {
-    return false;
-  }
-  list.splice(idx, 1);
-  return true;
-}
-
-/**
- * Widen a per-event matcher to the storage's uniform slot type. Unsound at
- * the type level (function parameters are contravariant) but safe by
- * construction: `HookRegistry.register<E>` only ever puts matchers into the
- * bucket slot for their own event, and reads go through `snapshot<E>`
- * which is only called with the same `E`.
- */
-function widen<E extends HookEvent>(
-  matcher: HookMatcher<E>
-): HookMatcher<HookEvent> {
-  return matcher as unknown as HookMatcher<HookEvent>;
-}
-
-/**
- * Narrow a storage list back to a per-event matcher list on the way out.
- * Sound counterpart to `widen`: the list only contains matchers that were
- * registered against `E`, because the public API enforces it on insert.
- */
-function snapshot<E extends HookEvent>(
-  list: readonly HookMatcher<HookEvent>[]
-): HookMatcher<E>[] {
-  return list.slice() as unknown as HookMatcher<E>[];
-}

package/src/hooks/__tests__/HookRegistry.test.ts

@@ -1,190 +0,0 @@
-// src/hooks/__tests__/HookRegistry.test.ts
-import { HookRegistry } from '../HookRegistry';
-import type {
-  HookMatcher,
-  HookCallback,
-  PreToolUseHookOutput,
-  PostToolUseHookOutput,
-} from '../types';
-
-const noop: HookCallback<
-  'PreToolUse'
-> = async (): Promise<PreToolUseHookOutput> => ({});
-const noopPost: HookCallback<
-  'PostToolUse'
-> = async (): Promise<PostToolUseHookOutput> => ({});
-
-function makePreToolUseMatcher(pattern?: string): HookMatcher<'PreToolUse'> {
-  return {
-    pattern,
-    hooks: [noop],
-  };
-}
-
-function makePostToolUseMatcher(): HookMatcher<'PostToolUse'> {
-  return {
-    hooks: [noopPost],
-  };
-}
-
-describe('HookRegistry', () => {
-  describe('global registration', () => {
-    it('stores a matcher and returns it via getMatchers', () => {
-      const registry = new HookRegistry();
-      const matcher = makePreToolUseMatcher('Bash');
-      registry.register('PreToolUse', matcher);
-      const matchers = registry.getMatchers('PreToolUse');
-      expect(matchers).toHaveLength(1);
-      expect(matchers[0]).toBe(matcher);
-    });
-
-    it('keeps registrations isolated across events', () => {
-      const registry = new HookRegistry();
-      const pre = makePreToolUseMatcher('Bash');
-      const post = makePostToolUseMatcher();
-      registry.register('PreToolUse', pre);
-      registry.register('PostToolUse', post);
-      expect(registry.getMatchers('PreToolUse')).toEqual([pre]);
-      expect(registry.getMatchers('PostToolUse')).toEqual([post]);
-      expect(registry.getMatchers('Stop')).toEqual([]);
-    });
-
-    it('unregister removes the matcher from the registry', () => {
-      const registry = new HookRegistry();
-      const matcher = makePreToolUseMatcher();
-      const unregister = registry.register('PreToolUse', matcher);
-      expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
-      unregister();
-      expect(registry.getMatchers('PreToolUse')).toHaveLength(0);
-    });
-
-    it('hasHookFor reflects registration state', () => {
-      const registry = new HookRegistry();
-      expect(registry.hasHookFor('PreToolUse')).toBe(false);
-      registry.register('PreToolUse', makePreToolUseMatcher());
-      expect(registry.hasHookFor('PreToolUse')).toBe(true);
-      expect(registry.hasHookFor('PostToolUse')).toBe(false);
-    });
-
-    it('supports multiple matchers on the same event', () => {
-      const registry = new HookRegistry();
-      const a = makePreToolUseMatcher('Bash');
-      const b = makePreToolUseMatcher('Edit');
-      registry.register('PreToolUse', a);
-      registry.register('PreToolUse', b);
-      const matchers = registry.getMatchers('PreToolUse');
-      expect(matchers).toHaveLength(2);
-      expect(matchers).toContain(a);
-      expect(matchers).toContain(b);
-    });
-
-    it('returns a fresh array on each getMatchers call', () => {
-      const registry = new HookRegistry();
-      registry.register('PreToolUse', makePreToolUseMatcher());
-      const first = registry.getMatchers('PreToolUse');
-      const second = registry.getMatchers('PreToolUse');
-      expect(first).not.toBe(second);
-      first.length = 0;
-      expect(registry.getMatchers('PreToolUse')).toHaveLength(1);
-    });
-  });
-
-  describe('session registration', () => {
-    it('scopes matchers to a single session', () => {
-      const registry = new HookRegistry();
-      const sessionA = makePreToolUseMatcher('Bash');
-      const sessionB = makePreToolUseMatcher('Edit');
-      registry.registerSession('run-a', 'PreToolUse', sessionA);
-      registry.registerSession('run-b', 'PreToolUse', sessionB);
-
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([sessionA]);
-      expect(registry.getMatchers('PreToolUse', 'run-b')).toEqual([sessionB]);
-      expect(registry.getMatchers('PreToolUse')).toEqual([]);
-    });
-
-    it('merges global matchers in front of session matchers', () => {
-      const registry = new HookRegistry();
-      const global = makePreToolUseMatcher('global');
-      const session = makePreToolUseMatcher('session');
-      registry.register('PreToolUse', global);
-      registry.registerSession('run-a', 'PreToolUse', session);
-
-      const matchers = registry.getMatchers('PreToolUse', 'run-a');
-      expect(matchers).toEqual([global, session]);
-    });
-
-    it('clearSession drops only the given session', () => {
-      const registry = new HookRegistry();
-      const a = makePreToolUseMatcher('a');
-      const b = makePreToolUseMatcher('b');
-      registry.registerSession('run-a', 'PreToolUse', a);
-      registry.registerSession('run-b', 'PreToolUse', b);
-
-      registry.clearSession('run-a');
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([]);
-      expect(registry.getMatchers('PreToolUse', 'run-b')).toEqual([b]);
-    });
-
-    it('removeMatcher removes from the correct scope', () => {
-      const registry = new HookRegistry();
-      const global = makePreToolUseMatcher('global');
-      const session = makePreToolUseMatcher('session');
-      registry.register('PreToolUse', global);
-      registry.registerSession('run-a', 'PreToolUse', session);
-
-      expect(registry.removeMatcher('PreToolUse', session, 'run-a')).toBe(true);
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([global]);
-
-      expect(registry.removeMatcher('PreToolUse', global)).toBe(true);
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([]);
-    });
-
-    it('removeMatcher returns false when the matcher is not found', () => {
-      const registry = new HookRegistry();
-      const orphan = makePreToolUseMatcher('orphan');
-      expect(registry.removeMatcher('PreToolUse', orphan)).toBe(false);
-      expect(registry.removeMatcher('PreToolUse', orphan, 'run-a')).toBe(false);
-    });
-
-    it('session unregister function removes only that matcher', () => {
-      const registry = new HookRegistry();
-      const a = makePreToolUseMatcher('a');
-      const b = makePreToolUseMatcher('b');
-      const unregisterA = registry.registerSession('run-a', 'PreToolUse', a);
-      registry.registerSession('run-a', 'PreToolUse', b);
-
-      unregisterA();
-      expect(registry.getMatchers('PreToolUse', 'run-a')).toEqual([b]);
-    });
-
-    it('hasHookFor honours the sessionId parameter', () => {
-      const registry = new HookRegistry();
-      registry.registerSession('run-a', 'PreToolUse', makePreToolUseMatcher());
-      expect(registry.hasHookFor('PreToolUse')).toBe(false);
-      expect(registry.hasHookFor('PreToolUse', 'run-a')).toBe(true);
-      expect(registry.hasHookFor('PreToolUse', 'run-b')).toBe(false);
-    });
-  });
-
-  describe('session isolation under parallel registration', () => {
-    it('does not leak matchers between sessions registered in parallel', async () => {
-      const registry = new HookRegistry();
-      const sessions = Array.from({ length: 50 }, (_, i) => `run-${i}`);
-      await Promise.all(
-        sessions.map(async (sid): Promise<void> => {
-          registry.registerSession(
-            sid,
-            'PreToolUse',
-            makePreToolUseMatcher(sid)
-          );
-        })
-      );
-
-      for (const sid of sessions) {
-        const matchers = registry.getMatchers('PreToolUse', sid);
-        expect(matchers).toHaveLength(1);
-        expect(matchers[0]?.pattern).toBe(sid);
-      }
-    });
-  });
-});