@librechat/agents 3.1.64 → 3.1.66-dev.0

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

@@ -28,7 +28,9 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private directToolNames?;
     /** Maximum characters allowed in a single tool result before truncation. */
     private maxToolResultChars;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, }: t.ToolNodeConstructorParams);
+    /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
+    private hookRegistry?;
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, }: t.ToolNodeConstructorParams);
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -66,11 +68,31 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     /**
      * Dispatches tool calls to the host via ON_TOOL_EXECUTE event and returns raw ToolMessages.
      * Core logic for event-driven execution, separated from output shaping.
+     *
+     * Hook lifecycle (when `hookRegistry` is set):
+     * 1. **PreToolUse** fires per call in parallel before dispatch. Denied
+     *    calls produce error ToolMessages and fire **PermissionDenied**;
+     *    surviving calls proceed with optional `updatedInput`.
+     * 2. Surviving calls are dispatched to the host via `ON_TOOL_EXECUTE`.
+     * 3. **PostToolUse** / **PostToolUseFailure** fire per result. Post hooks
+     *    can replace tool output via `updatedOutput`.
+     * 4. Injected messages from results are collected and returned alongside
+     *    ToolMessages (appended AFTER to respect provider ordering).
      */
     private dispatchToolEvents;
+    private dispatchStepCompleted;
+    /**
+     * Converts InjectedMessage instances to LangChain HumanMessage objects.
+     * Both 'user' and 'system' roles become HumanMessage to avoid provider
+     * rejections (Anthropic/Google reject non-leading SystemMessages).
+     * The original role is preserved in additional_kwargs for downstream consumers.
+     */
+    private convertInjectedMessages;
     /**
      * Execute all tool calls via ON_TOOL_EXECUTE event dispatch.
-     * Used in event-driven mode where the host handles actual tool execution.
+     * Injected messages are placed AFTER ToolMessages to respect provider
+     * message ordering (AIMessage tool_calls must be immediately followed
+     * by their ToolMessage results).
      */
     private executeViaEvent;
     protected run(input: any, config: RunnableConfig): Promise<T>;

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

@@ -0,0 +1,19 @@
+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/types/index.d.ts

@@ -1,6 +1,7 @@
 export * from './graph';
 export * from './llm';
 export * from './run';
+export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';

package/dist/types/types/run.d.ts

@@ -7,6 +7,8 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { ToolSessionMap } from '@/types/tools';
+import type { HookRegistry } from '@/hooks';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
     llmConfig: l.LLMConfig;
@@ -100,6 +102,18 @@ export type RunConfig = {
     runId: string;
     graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
     customHandlers?: Record<string, g.EventHandler>;
+    /**
+     * Pre-constructed hook registry for this run. Hooks fire at lifecycle
+     * points in `processStream` (RunStart, UserPromptSubmit, Stop,
+     * StopFailure) and around tool calls (PreToolUse, PostToolUse,
+     * PostToolUseFailure, PermissionDenied).
+     *
+     * Pass `undefined` (the default) to skip all hook dispatch. When a
+     * registry is provided, the run attaches it to the `Graph` so internal
+     * nodes can fire hooks too, and clears the session in the `finally`
+     * block to prevent leaks.
+     */
+    hooks?: HookRegistry;
     returnContent?: boolean;
     tokenCounter?: TokenCounter;
     indexTokenCountMap?: Record<string, number>;
@@ -114,6 +128,12 @@ export type RunConfig = {
     calibrationRatio?: number;
     /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
     skipCleanup?: boolean;
+    /**
+     * Initial session state to seed the Graph's ToolSessionMap.
+     * Used to carry over code environment sessions from skill file priming
+     * at run start, so ToolNode can inject session_id + files into tool calls.
+     */
+    initialSessions?: ToolSessionMap;
 };
 export type ProvidedCallbacks = (BaseCallbackHandler | CallbackHandlerMethods)[] | undefined;
 export type TokenCounter = (message: BaseMessage) => number;

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

@@ -0,0 +1,9 @@
+/** 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/dist/types/types/tools.d.ts

@@ -1,7 +1,8 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { ToolErrorData } from './stream';
+import type { HookRegistry } from '@/hooks';
+import type { MessageContentComplex, ToolErrorData } from './stream';
 import { EnvVar } from '@/common';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
@@ -39,6 +40,12 @@ export type ToolNodeOptions = {
     agentId?: string;
     /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
     directToolNames?: Set<string>;
+    /**
+     * Hook registry for PreToolUse/PostToolUse lifecycle hooks.
+     * Only fires for event-driven tool calls (`dispatchToolEvents`). Tools
+     * routed through `directToolNames` bypass hook dispatch entirely.
+     */
+    hookRegistry?: HookRegistry;
     /** Max context tokens for the agent — used to compute tool result truncation limits. */
     maxContextTokens?: number;
     /**
@@ -154,6 +161,25 @@ export type ToolExecuteBatchRequest = {
     /** Promise rejector - handler calls this on fatal error */
     reject: (error: Error) => void;
 };
+/**
+ * A message injected into graph state by any tool execution handler.
+ * Generic mechanism: any tool returning `injectedMessages` in its `ToolExecuteResult`
+ * will have these appended to state after the ToolMessage for this call.
+ */
+export type InjectedMessage = {
+    /** 'user' for skill body injection, 'system' for context hints.
+     *  Both are converted to HumanMessage at runtime; the original role
+     *  is preserved in additional_kwargs.role. */
+    role: 'user' | 'system';
+    /** Message content: string for simple text, array for complex multi-part content */
+    content: string | MessageContentComplex[];
+    /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+    isMeta?: boolean;
+    /** Origin tag for downstream consumers (UI, pruner, compaction) */
+    source?: 'skill' | 'hook' | 'system';
+    /** Only set when source is 'skill', for compaction preservation */
+    skillName?: string;
+};
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
     /** Matches ToolCallRequest.id */
@@ -166,6 +192,13 @@ export type ToolExecuteResult = {
     status: 'success' | 'error';
     /** Error message if status is 'error' */
     errorMessage?: string;
+    /**
+     * Messages to inject into graph state after the ToolMessage for this call.
+     * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).
+     * The host's message formatter may merge injected user messages with the preceding tool_result turn.
+     * Generic mechanism: any tool execution handler can use this.
+     */
+    injectedMessages?: InjectedMessage[];
 };
 /** Map of tool names to tool definitions */
 export type LCToolRegistry = Map<string, LCTool>;
@@ -266,6 +299,10 @@ export type ProgrammaticExecutionArtifact = {
     session_id?: string;
     files?: FileRefs;
 };
+/** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+/** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
 /**
  * Initialization parameters for the PTC tool
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.64",
+  "version": "3.1.66-dev.0",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -140,7 +140,7 @@
     "cheerio": "^1.0.0",
     "dotenv": "^16.4.7",
     "https-proxy-agent": "^7.0.6",
-    "mathjs": "^15.1.0",
+    "mathjs": "^15.2.0",
     "nanoid": "^3.3.7",
     "okapibm25": "^1.4.1",
     "openai": "5.8.2"

package/src/common/enum.ts

@@ -182,8 +182,20 @@ export enum Constants {
   MCP_DELIMITER = '_mcp_',
   /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
   ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',
+  SKILL_TOOL = 'skill',
+  READ_FILE = 'read_file',
+  BASH_TOOL = 'bash_tool',
+  BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
 }
 
+/** Tool names that use the code execution environment (shared session, file tracking). */
+export const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([
+  Constants.EXECUTE_CODE,
+  Constants.BASH_TOOL,
+  Constants.PROGRAMMATIC_TOOL_CALLING,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+]);
+
 export enum TitleMethod {
   STRUCTURED = 'structured',
   FUNCTIONS = 'functions',

package/src/graphs/Graph.ts

@@ -53,6 +53,7 @@ import { isThinkingEnabled } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
+import type { HookRegistry } from '@/hooks';
 
 const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
 
@@ -123,6 +124,7 @@ export abstract class Graph<
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
+  hookRegistry: HookRegistry | undefined;
   /**
    * Tool session contexts for automatic state persistence across tool invocations.
    * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
@@ -147,6 +149,7 @@ export abstract class Graph<
     this.prelimMessageIdsByStepKey = new Map();
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
+    this.hookRegistry = undefined;
     this.sessions.clear();
   }
 }
@@ -506,6 +509,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         agentId: agentContext?.agentId,
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
+        hookRegistry: this.hookRegistry,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,

package/src/hooks/HookRegistry.ts

@@ -0,0 +1,208 @@
+// 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

@@ -0,0 +1,190 @@
+// 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);
+      }
+    });
+  });
+});