@librechat/agents 3.4.6 → 3.5.0

package/dist/esm/hooks/HookRegistry.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"HookRegistry.mjs","names":[],"sources":["../../../src/hooks/HookRegistry.ts"],"sourcesContent":["// src/hooks/HookRegistry.ts\nimport type {\n  HookEvent,\n  HookMatcher,\n  ToolApprovalReplayKey,\n  ToolApprovalReplaySnapshot,\n  AggregatedHookResult,\n} from './types';\n\nfunction serializeApprovalKey(key: ToolApprovalReplayKey): string {\n  return JSON.stringify([key.executionScope, key.agentId, key.toolUseId]);\n}\n\nfunction deserializeApprovalKey(value: string): ToolApprovalReplayKey | null {\n  const parsed: unknown = JSON.parse(value);\n  if (\n    !Array.isArray(parsed) ||\n    parsed.length !== 3 ||\n    parsed.some((part) => typeof part !== 'string')\n  ) {\n    return null;\n  }\n  return {\n    executionScope: parsed[0],\n    agentId: parsed[1],\n    toolUseId: parsed[2],\n  };\n}\n\n/**\n * Internal matcher storage type.\n *\n * Matchers registered via the public `register<E>` API are strictly typed\n * to a single `E`, but the storage needs one uniform slot type per event.\n * We store them as `HookMatcher<HookEvent>` and cast once at the variance\n * boundary — see `ensureList` and `snapshot` below. The invariant (every\n * matcher in `bucket[event]` was registered with that exact event) is\n * enforced by the public API; breaking it requires bypassing the types.\n */\ntype MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;\n\n/**\n * Events whose hooks can change a tool call's input or output. Presence of\n * any of these disables eager tool execution and early completion emission;\n * observation-only events (`PostToolBatch`, `Stop`, telemetry hooks) do not.\n */\nconst RESULT_ALTERING_HOOK_EVENTS = [\n  'PreToolUse',\n  'PostToolUse',\n  'PostToolUseFailure',\n] as const satisfies readonly HookEvent[];\n\n/**\n * Snapshot of a halt request raised by a hook returning\n * `preventContinuation: true`. The SDK's run loop polls for this between\n * stream events and exits cleanly when set, skipping the `Stop` hook\n * (the run is being halted, not naturally completing). One per registry\n * instance — the first hook to halt wins; subsequent halts are ignored\n * so the original reason isn't clobbered.\n */\nexport interface HookHaltSignal {\n  reason: string;\n  /** Event of the hook that triggered the halt (for diagnostics). */\n  source: HookEvent;\n}\n\n/**\n * Run-scoped storage for hook matchers with an additional layer for\n * session-scoped matchers that should be cleaned up between sessions.\n *\n * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is\n * scoped) and register global matchers + per-session matchers against it.\n * Registration is strictly additive — nothing in this class mutates a\n * matcher's callbacks or flags after insertion.\n *\n * ## Why `Map<sessionId, MatcherBucket>` and not `Record`\n *\n * LibreChat runs thousands of parallel sessions in one Node process, and\n * hook registration happens inside hot paths (tool loading, agent spawning).\n * A `Record<sessionId, ...>` has to be spread on every insertion, which is\n * O(n) per call and O(n²) total for a batch of parallel registrations. A\n * Map mutates in place, keeping insertions O(1). This mirrors the reasoning\n * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.\n */\nexport class HookRegistry {\n  private readonly global: MatcherBucket = {};\n  private readonly sessions: Map<string, MatcherBucket> = new Map();\n  /**\n   * Per-session halt signals. Scoped by `sessionId` (= the run id the\n   * hook fired under) so a host that shares one registry across\n   * concurrent runs cannot leak `preventContinuation` from one run\n   * into another. Without scoping, a halt raised by run A's hook\n   * would trip run B's stream-loop poll on the next iteration —\n   * silently terminating an unrelated run.\n   *\n   * Map storage mirrors the reasoning above for session matchers:\n   * O(1) insertion in hot paths, no spread-on-write.\n   */\n  private readonly haltSignals: Map<string, HookHaltSignal> = new Map();\n  /** One-shot hook contributions retained until approval is consumed. */\n  private readonly pendingToolApprovals = new Map<\n    string,\n    Map<string, AggregatedHookResult>\n  >();\n\n  /**\n   * Register a matcher for the lifetime of this registry (= one Run).\n   * Returns an unregister function that removes the matcher by reference.\n   */\n  register<E extends HookEvent>(event: E, matcher: HookMatcher<E>): () => void {\n    const list = ensureList(this.global, event);\n    list.push(widen(matcher));\n    return () => {\n      removeFromList(list, matcher);\n    };\n  }\n\n  /**\n   * Register a matcher for a specific session. Cleared automatically when\n   * `clearSession(sessionId)` is called, or can be removed directly via the\n   * returned unregister function.\n   */\n  registerSession<E extends HookEvent>(\n    sessionId: string,\n    event: E,\n    matcher: HookMatcher<E>\n  ): () => void {\n    const bucket = this.ensureSessionBucket(sessionId);\n    const list = ensureList(bucket, event);\n    list.push(widen(matcher));\n    return () => {\n      removeFromList(list, matcher);\n    };\n  }\n\n  /**\n   * Returns all matchers registered for `event`, concatenating global first\n   * and then session-specific (when `sessionId` is supplied). The caller\n   * receives a fresh array, so iterating it is safe even if a matcher is\n   * removed mid-iteration (e.g. via `once: true`).\n   */\n  getMatchers<E extends HookEvent>(\n    event: E,\n    sessionId?: string\n  ): HookMatcher<E>[] {\n    const globalList = readList(this.global, event);\n    if (sessionId === undefined) {\n      return snapshot<E>(globalList);\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return snapshot<E>(globalList);\n    }\n    const sessionList = readList(bucket, event);\n    if (globalList.length === 0) {\n      return snapshot<E>(sessionList);\n    }\n    if (sessionList.length === 0) {\n      return snapshot<E>(globalList);\n    }\n    return snapshot<E>([...globalList, ...sessionList]);\n  }\n\n  /**\n   * Removes `matcher` by reference from global storage first, falling back\n   * to the session bucket when `sessionId` is supplied. Used by\n   * `executeHooks` to drop `once: true` matchers after they fire.\n   */\n  removeMatcher<E extends HookEvent>(\n    event: E,\n    matcher: HookMatcher<E>,\n    sessionId?: string\n  ): boolean {\n    if (removeFromList(readList(this.global, event), matcher)) {\n      return true;\n    }\n    if (sessionId === undefined) {\n      return false;\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return false;\n    }\n    return removeFromList(readList(bucket, event), matcher);\n  }\n\n  /**\n   * Drops every session-scoped matcher for `sessionId`. Call this in the\n   * `finally` block around a Run so a `once: true` hook that never fired\n   * cannot leak into the next session on the same registry.\n   */\n  clearSession(sessionId: string): void {\n    this.sessions.delete(sessionId);\n    this.pendingToolApprovals.delete(sessionId);\n  }\n\n  /** Copies session-scoped policy into a rebuilt or branched Run. */\n  copySession(sourceSessionId: string, targetSessionId: string): void {\n    if (sourceSessionId === targetSessionId) {\n      return;\n    }\n    const source = this.sessions.get(sourceSessionId);\n    if (source != null) {\n      const target = this.ensureSessionBucket(targetSessionId);\n      for (const event of Object.keys(source) as HookEvent[]) {\n        const targetList = ensureList(target, event);\n        for (const matcher of readList(source, event)) {\n          if (!targetList.includes(matcher)) {\n            targetList.push(matcher);\n          }\n        }\n      }\n    }\n    const pending = this.pendingToolApprovals.get(sourceSessionId);\n    if (pending == null) {\n      return;\n    }\n    let targetPending = this.pendingToolApprovals.get(targetSessionId);\n    if (targetPending == null) {\n      targetPending = new Map();\n      this.pendingToolApprovals.set(targetSessionId, targetPending);\n    }\n    for (const [toolUseId, result] of pending) {\n      if (!targetPending.has(toolUseId)) {\n        targetPending.set(toolUseId, result);\n      }\n    }\n  }\n\n  getPendingToolApproval(\n    sessionId: string,\n    key: ToolApprovalReplayKey\n  ): AggregatedHookResult | undefined {\n    return this.pendingToolApprovals\n      .get(sessionId)\n      ?.get(serializeApprovalKey(key));\n  }\n\n  setPendingToolApproval(\n    sessionId: string,\n    key: ToolApprovalReplayKey,\n    result: AggregatedHookResult\n  ): void {\n    let pending = this.pendingToolApprovals.get(sessionId);\n    if (pending == null) {\n      pending = new Map();\n      this.pendingToolApprovals.set(sessionId, pending);\n    }\n    pending.set(serializeApprovalKey(key), result);\n  }\n\n  clearPendingToolApproval(\n    sessionId: string,\n    key: ToolApprovalReplayKey\n  ): void {\n    const pending = this.pendingToolApprovals.get(sessionId);\n    if (pending == null) {\n      return;\n    }\n    pending.delete(serializeApprovalKey(key));\n    if (pending.size === 0) {\n      this.pendingToolApprovals.delete(sessionId);\n    }\n  }\n\n  snapshotPendingToolApprovals(\n    sessionId: string,\n    executionScope: string\n  ): ToolApprovalReplaySnapshot[] {\n    const pending = this.pendingToolApprovals.get(sessionId);\n    if (pending == null) {\n      return [];\n    }\n    const snapshots: ToolApprovalReplaySnapshot[] = [];\n    for (const [serializedKey, result] of pending) {\n      const key = deserializeApprovalKey(serializedKey);\n      if (key == null || key.executionScope !== executionScope) {\n        continue;\n      }\n      snapshots.push({ key, result });\n    }\n    return snapshots;\n  }\n\n  restorePendingToolApprovals(\n    sessionId: string,\n    targetExecutionScope: string,\n    snapshots: ReadonlyArray<ToolApprovalReplaySnapshot>\n  ): void {\n    const restored = new Map<string, AggregatedHookResult>();\n    for (const [serializedKey, result] of this.pendingToolApprovals.get(\n      sessionId\n    ) ?? []) {\n      const key = deserializeApprovalKey(serializedKey);\n      if (key?.executionScope !== targetExecutionScope) {\n        restored.set(serializedKey, result);\n      }\n    }\n    for (const snapshot of snapshots) {\n      restored.set(\n        serializeApprovalKey({\n          ...snapshot.key,\n          executionScope: targetExecutionScope,\n        }),\n        snapshot.result\n      );\n    }\n    if (restored.size === 0) {\n      this.pendingToolApprovals.delete(sessionId);\n      return;\n    }\n    this.pendingToolApprovals.set(sessionId, restored);\n  }\n\n  /**\n   * Raise a halt signal scoped to `sessionId` (= the run id the hook\n   * fired under). The SDK's run loop polls for this between stream\n   * events with the run's own id. First-write-wins per session: a\n   * halt already raised by an earlier hook in the same run is\n   * preserved so the original `reason` / `source` aren't overwritten.\n   *\n   * Per-session scoping is critical when hosts share one registry\n   * across concurrent runs (e.g. a global policy registered once and\n   * reused). Without it, a `preventContinuation` from run A would\n   * trip run B's stream-loop poll on the next iteration and silently\n   * terminate an unrelated run.\n   *\n   * Called by the SDK after `executeHooks` returns an aggregate with\n   * `preventContinuation: true`. Hosts can also call it directly from\n   * inside a hook callback if they want to halt without going through\n   * the aggregated return value, but `preventContinuation` is the\n   * canonical path.\n   */\n  haltRun(sessionId: string, reason: string, source: HookEvent): void {\n    if (this.haltSignals.has(sessionId)) {\n      return;\n    }\n    this.haltSignals.set(sessionId, { reason, source });\n  }\n\n  /**\n   * Returns the halt signal raised by hooks running under `sessionId`,\n   * or `undefined` if no hook in that run has halted. Polled by\n   * `Run.processStream` between stream events using the run's own id.\n   */\n  getHaltSignal(sessionId: string): HookHaltSignal | undefined {\n    return this.haltSignals.get(sessionId);\n  }\n\n  /**\n   * Clears the halt signal for `sessionId`. Called by\n   * `Run.processStream` in its `finally` block so a subsequent\n   * invocation of the same Run (e.g. resume) starts with a fresh\n   * halt state. No-op when no signal exists for that session.\n   */\n  clearHaltSignal(sessionId: string): void {\n    this.haltSignals.delete(sessionId);\n  }\n\n  /**\n   * True when any registered hook can alter a tool result before or after\n   * execution (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`). Eager\n   * tool execution and early completion emission gate on this instead of\n   * registry presence, so observation-only registries (e.g. a\n   * `PostToolBatch` steering drain) keep those fast paths. With\n   * `sessionId`, checks global + that session; without it, conservatively\n   * scans every session bucket.\n   */\n  hasResultAlteringHooks(sessionId?: string): boolean {\n    if (hasResultAlteringInBucket(this.global)) {\n      return true;\n    }\n    if (sessionId !== undefined) {\n      const bucket = this.sessions.get(sessionId);\n      return bucket !== undefined && hasResultAlteringInBucket(bucket);\n    }\n    for (const bucket of this.sessions.values()) {\n      if (hasResultAlteringInBucket(bucket)) {\n        return true;\n      }\n    }\n    return false;\n  }\n\n  /** True if at least one matcher exists for `event` (global + session). */\n  hasHookFor(event: HookEvent, sessionId?: string): boolean {\n    if (readList(this.global, event).length > 0) {\n      return true;\n    }\n    if (sessionId === undefined) {\n      return false;\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return false;\n    }\n    return readList(bucket, event).length > 0;\n  }\n\n  /**\n   * True when at least one matcher for `event` would actually DISPATCH on a\n   * query-less call — a wildcard pattern with a non-empty `hooks` array.\n   *\n   * `hasHookFor` answers \"is one registered\", which is not the same question:\n   * a matcher carrying a pattern is inert for events that supply no\n   * `matchQuery`, so a caller using registration as a proxy for \"something\n   * will run\" can act on a hook that never fires. Mirrors the two skips in\n   * `executeHooks` (pattern mismatch, empty `hooks`).\n   *\n   * Non-allocating on purpose — `StandardGraph.canClaimPreemptSeal` reads it\n   * once per streamed chunk, where `getMatchers`' defensive `slice()` would\n   * allocate on every delta.\n   */\n  hasDispatchableHookFor(event: HookEvent, sessionId?: string): boolean {\n    if (hasDispatchableInList(readList(this.global, event))) {\n      return true;\n    }\n    if (sessionId === undefined) {\n      return false;\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return false;\n    }\n    return hasDispatchableInList(readList(bucket, event));\n  }\n\n  private ensureSessionBucket(sessionId: string): MatcherBucket {\n    const existing = this.sessions.get(sessionId);\n    if (existing !== undefined) {\n      return existing;\n    }\n    const fresh: MatcherBucket = {};\n    this.sessions.set(sessionId, fresh);\n    return fresh;\n  }\n}\n\nfunction ensureList(\n  bucket: MatcherBucket,\n  event: HookEvent\n): HookMatcher<HookEvent>[] {\n  const existing = bucket[event];\n  if (existing !== undefined) {\n    return existing;\n  }\n  const fresh: HookMatcher<HookEvent>[] = [];\n  bucket[event] = fresh;\n  return fresh;\n}\n\nfunction readList(\n  bucket: MatcherBucket,\n  event: HookEvent\n): HookMatcher<HookEvent>[] {\n  return bucket[event] ?? [];\n}\n\nfunction hasDispatchableInList(list: HookMatcher<HookEvent>[]): boolean {\n  for (const matcher of list) {\n    if (\n      (matcher.pattern === undefined || matcher.pattern === '') &&\n      matcher.hooks.length > 0\n    ) {\n      return true;\n    }\n  }\n  return false;\n}\n\nfunction hasResultAlteringInBucket(bucket: MatcherBucket): boolean {\n  for (const event of RESULT_ALTERING_HOOK_EVENTS) {\n    if (readList(bucket, event).length > 0) {\n      return true;\n    }\n  }\n  return false;\n}\n\nfunction removeFromList<E extends HookEvent>(\n  list: HookMatcher<HookEvent>[],\n  matcher: HookMatcher<E>\n): boolean {\n  const idx = list.indexOf(widen(matcher));\n  if (idx < 0) {\n    return false;\n  }\n  list.splice(idx, 1);\n  return true;\n}\n\n/**\n * Widen a per-event matcher to the storage's uniform slot type. Unsound at\n * the type level (function parameters are contravariant) but safe by\n * construction: `HookRegistry.register<E>` only ever puts matchers into the\n * bucket slot for their own event, and reads go through `snapshot<E>`\n * which is only called with the same `E`.\n */\nfunction widen<E extends HookEvent>(\n  matcher: HookMatcher<E>\n): HookMatcher<HookEvent> {\n  return matcher as unknown as HookMatcher<HookEvent>;\n}\n\n/**\n * Narrow a storage list back to a per-event matcher list on the way out.\n * Sound counterpart to `widen`: the list only contains matchers that were\n * registered against `E`, because the public API enforces it on insert.\n */\nfunction snapshot<E extends HookEvent>(\n  list: readonly HookMatcher<HookEvent>[]\n): HookMatcher<E>[] {\n  return list.slice() as unknown as HookMatcher<E>[];\n}\n"],"mappings":"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"}
+{"version":3,"file":"HookRegistry.mjs","names":[],"sources":["../../../src/hooks/HookRegistry.ts"],"mappings":";AASA,SAAS,qBAAqB,KAAoC;CAChE,OAAO,KAAK,UAAU;EAAC,IAAI;EAAgB,IAAI;EAAS,IAAI;CAAS,CAAC;AACxE;AAEA,SAAS,uBAAuB,OAA6C;CAC3E,MAAM,SAAkB,KAAK,MAAM,KAAK;CACxC,IACE,CAAC,MAAM,QAAQ,MAAM,KACrB,OAAO,WAAW,KAClB,OAAO,MAAM,SAAS,OAAO,SAAS,QAAQ,GAE9C,OAAO;CAET,OAAO;EACL,gBAAgB,OAAO;EACvB,SAAS,OAAO;EAChB,WAAW,OAAO;CACpB;AACF;AAmBA,MAAM,8BAA8B;CAClC;CACA;CACA;AACF;AAkCA,IAAa,eAAb,MAA0B;CACxB,SAAyC,CAAC;CAC1C,2BAAwD,IAAI,IAAI;CAYhE,8BAA4D,IAAI,IAAI;CAEpE,uCAAwC,IAAI,IAG1C;CAMF,SAA8B,OAAU,SAAqC;EAC3E,MAAM,OAAO,WAAW,KAAK,QAAQ,KAAK;EAC1C,KAAK,KAAK,MAAM,OAAO,CAAC;EACxB,aAAa;GACX,eAAe,MAAM,OAAO;EAC9B;CACF;CAOA,gBACE,WACA,OACA,SACY;EAEZ,MAAM,OAAO,WADE,KAAK,oBAAoB,SACX,GAAG,KAAK;EACrC,KAAK,KAAK,MAAM,OAAO,CAAC;EACxB,aAAa;GACX,eAAe,MAAM,OAAO;EAC9B;CACF;CAQA,YACE,OACA,WACkB;EAClB,MAAM,aAAa,SAAS,KAAK,QAAQ,KAAK;EAC9C,IAAI,cAAc,KAAA,GAChB,OAAO,SAAY,UAAU;EAE/B,MAAM,SAAS,KAAK,SAAS,IAAI,SAAS;EAC1C,IAAI,WAAW,KAAA,GACb,OAAO,SAAY,UAAU;EAE/B,MAAM,cAAc,SAAS,QAAQ,KAAK;EAC1C,IAAI,WAAW,WAAW,GACxB,OAAO,SAAY,WAAW;EAEhC,IAAI,YAAY,WAAW,GACzB,OAAO,SAAY,UAAU;EAE/B,OAAO,SAAY,CAAC,GAAG,YAAY,GAAG,WAAW,CAAC;CACpD;CAOA,cACE,OACA,SACA,WACS;EACT,IAAI,eAAe,SAAS,KAAK,QAAQ,KAAK,GAAG,OAAO,GACtD,OAAO;EAET,IAAI,cAAc,KAAA,GAChB,OAAO;EAET,MAAM,SAAS,KAAK,SAAS,IAAI,SAAS;EAC1C,IAAI,WAAW,KAAA,GACb,OAAO;EAET,OAAO,eAAe,SAAS,QAAQ,KAAK,GAAG,OAAO;CACxD;CAOA,aAAa,WAAyB;EACpC,KAAK,SAAS,OAAO,SAAS;EAC9B,KAAK,qBAAqB,OAAO,SAAS;CAC5C;CAGA,YAAY,iBAAyB,iBAA+B;EAClE,IAAI,oBAAoB,iBACtB;EAEF,MAAM,SAAS,KAAK,SAAS,IAAI,eAAe;EAChD,IAAI,UAAU,MAAM;GAClB,MAAM,SAAS,KAAK,oBAAoB,eAAe;GACvD,KAAK,MAAM,SAAS,OAAO,KAAK,MAAM,GAAkB;IACtD,MAAM,aAAa,WAAW,QAAQ,KAAK;IAC3C,KAAK,MAAM,WAAW,SAAS,QAAQ,KAAK,GAC1C,IAAI,CAAC,WAAW,SAAS,OAAO,GAC9B,WAAW,KAAK,OAAO;GAG7B;EACF;EACA,MAAM,UAAU,KAAK,qBAAqB,IAAI,eAAe;EAC7D,IAAI,WAAW,MACb;EAEF,IAAI,gBAAgB,KAAK,qBAAqB,IAAI,eAAe;EACjE,IAAI,iBAAiB,MAAM;GACzB,gCAAgB,IAAI,IAAI;GACxB,KAAK,qBAAqB,IAAI,iBAAiB,aAAa;EAC9D;EACA,KAAK,MAAM,CAAC,WAAW,WAAW,SAChC,IAAI,CAAC,cAAc,IAAI,SAAS,GAC9B,cAAc,IAAI,WAAW,MAAM;CAGzC;CAEA,uBACE,WACA,KACkC;EAClC,OAAO,KAAK,qBACT,IAAI,SAAS,CAAC,EACb,IAAI,qBAAqB,GAAG,CAAC;CACnC;CAEA,uBACE,WACA,KACA,QACM;EACN,IAAI,UAAU,KAAK,qBAAqB,IAAI,SAAS;EACrD,IAAI,WAAW,MAAM;GACnB,0BAAU,IAAI,IAAI;GAClB,KAAK,qBAAqB,IAAI,WAAW,OAAO;EAClD;EACA,QAAQ,IAAI,qBAAqB,GAAG,GAAG,MAAM;CAC/C;CAEA,yBACE,WACA,KACM;EACN,MAAM,UAAU,KAAK,qBAAqB,IAAI,SAAS;EACvD,IAAI,WAAW,MACb;EAEF,QAAQ,OAAO,qBAAqB,GAAG,CAAC;EACxC,IAAI,QAAQ,SAAS,GACnB,KAAK,qBAAqB,OAAO,SAAS;CAE9C;CAEA,6BACE,WACA,gBAC8B;EAC9B,MAAM,UAAU,KAAK,qBAAqB,IAAI,SAAS;EACvD,IAAI,WAAW,MACb,OAAO,CAAC;EAEV,MAAM,YAA0C,CAAC;EACjD,KAAK,MAAM,CAAC,eAAe,WAAW,SAAS;GAC7C,MAAM,MAAM,uBAAuB,aAAa;GAChD,IAAI,OAAO,QAAQ,IAAI,mBAAmB,gBACxC;GAEF,UAAU,KAAK;IAAE;IAAK;GAAO,CAAC;EAChC;EACA,OAAO;CACT;CAEA,4BACE,WACA,sBACA,WACM;EACN,MAAM,2BAAW,IAAI,IAAkC;EACvD,KAAK,MAAM,CAAC,eAAe,WAAW,KAAK,qBAAqB,IAC9D,SACF,KAAK,CAAC,GAEJ,IADY,uBAAuB,aAC7B,CAAC,EAAE,mBAAmB,sBAC1B,SAAS,IAAI,eAAe,MAAM;EAGtC,KAAK,MAAM,YAAY,WACrB,SAAS,IACP,qBAAqB;GACnB,GAAG,SAAS;GACZ,gBAAgB;EAClB,CAAC,GACD,SAAS,MACX;EAEF,IAAI,SAAS,SAAS,GAAG;GACvB,KAAK,qBAAqB,OAAO,SAAS;GAC1C;EACF;EACA,KAAK,qBAAqB,IAAI,WAAW,QAAQ;CACnD;CAqBA,QAAQ,WAAmB,QAAgB,QAAyB;EAClE,IAAI,KAAK,YAAY,IAAI,SAAS,GAChC;EAEF,KAAK,YAAY,IAAI,WAAW;GAAE;GAAQ;EAAO,CAAC;CACpD;CAOA,cAAc,WAA+C;EAC3D,OAAO,KAAK,YAAY,IAAI,SAAS;CACvC;CAQA,gBAAgB,WAAyB;EACvC,KAAK,YAAY,OAAO,SAAS;CACnC;CAWA,uBAAuB,WAA6B;EAClD,IAAI,0BAA0B,KAAK,MAAM,GACvC,OAAO;EAET,IAAI,cAAc,KAAA,GAAW;GAC3B,MAAM,SAAS,KAAK,SAAS,IAAI,SAAS;GAC1C,OAAO,WAAW,KAAA,KAAa,0BAA0B,MAAM;EACjE;EACA,KAAK,MAAM,UAAU,KAAK,SAAS,OAAO,GACxC,IAAI,0BAA0B,MAAM,GAClC,OAAO;EAGX,OAAO;CACT;CAGA,WAAW,OAAkB,WAA6B;EACxD,IAAI,SAAS,KAAK,QAAQ,KAAK,CAAC,CAAC,SAAS,GACxC,OAAO;EAET,IAAI,cAAc,KAAA,GAChB,OAAO;EAET,MAAM,SAAS,KAAK,SAAS,IAAI,SAAS;EAC1C,IAAI,WAAW,KAAA,GACb,OAAO;EAET,OAAO,SAAS,QAAQ,KAAK,CAAC,CAAC,SAAS;CAC1C;CAgBA,uBAAuB,OAAkB,WAA6B;EACpE,IAAI,sBAAsB,SAAS,KAAK,QAAQ,KAAK,CAAC,GACpD,OAAO;EAET,IAAI,cAAc,KAAA,GAChB,OAAO;EAET,MAAM,SAAS,KAAK,SAAS,IAAI,SAAS;EAC1C,IAAI,WAAW,KAAA,GACb,OAAO;EAET,OAAO,sBAAsB,SAAS,QAAQ,KAAK,CAAC;CACtD;CAEA,oBAA4B,WAAkC;EAC5D,MAAM,WAAW,KAAK,SAAS,IAAI,SAAS;EAC5C,IAAI,aAAa,KAAA,GACf,OAAO;EAET,MAAM,QAAuB,CAAC;EAC9B,KAAK,SAAS,IAAI,WAAW,KAAK;EAClC,OAAO;CACT;AACF;AAEA,SAAS,WACP,QACA,OAC0B;CAC1B,MAAM,WAAW,OAAO;CACxB,IAAI,aAAa,KAAA,GACf,OAAO;CAET,MAAM,QAAkC,CAAC;CACzC,OAAO,SAAS;CAChB,OAAO;AACT;AAEA,SAAS,SACP,QACA,OAC0B;CAC1B,OAAO,OAAO,UAAU,CAAC;AAC3B;AAEA,SAAS,sBAAsB,MAAyC;CACtE,KAAK,MAAM,WAAW,MACpB,KACG,QAAQ,YAAY,KAAA,KAAa,QAAQ,YAAY,OACtD,QAAQ,MAAM,SAAS,GAEvB,OAAO;CAGX,OAAO;AACT;AAEA,SAAS,0BAA0B,QAAgC;CACjE,KAAK,MAAM,SAAS,6BAClB,IAAI,SAAS,QAAQ,KAAK,CAAC,CAAC,SAAS,GACnC,OAAO;CAGX,OAAO;AACT;AAEA,SAAS,eACP,MACA,SACS;CACT,MAAM,MAAM,KAAK,QAAQ,MAAM,OAAO,CAAC;CACvC,IAAI,MAAM,GACR,OAAO;CAET,KAAK,OAAO,KAAK,CAAC;CAClB,OAAO;AACT;AASA,SAAS,MACP,SACwB;CACxB,OAAO;AACT;AAOA,SAAS,SACP,MACkB;CAClB,OAAO,KAAK,MAAM;AACpB"}

package/dist/esm/hooks/createToolPolicyHook.mjs

@@ -1,17 +1,8 @@
 //#region src/hooks/createToolPolicyHook.ts
-/**
-* Compile a glob string with `*` wildcards into a single anchored
-* `RegExp`. Other regex metacharacters are escaped, so `read_file.md`
-* matches the literal dot. Patterns are short (tool names), so we do
-* not cache here — the registry's `matchesQuery` already caches its own
-* regex compilations and our patterns are evaluated once per ToolNode
-* batch, not once per stream chunk.
-*/
 function globToRegex(pattern) {
 	const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
 	return new RegExp("^" + escaped.replace(/\*/g, ".*") + "$");
 }
-/** Pre-compile a list of glob patterns into a single match function. */
 function compileMatchers(patterns) {
 	if (patterns == null || patterns.length === 0) return () => false;
 	const regexes = patterns.map(globToRegex);
@@ -24,35 +15,6 @@ function formatReason(template, toolName) {
 	if (template == null) return;
 	return template.replace(/\{tool\}/g, toolName);
 }
-/**
-* Build a `PreToolUse` hook callback that applies a declarative tool
-* permission policy. Register it with a `HookRegistry` and the SDK's
-* `humanInTheLoop` machinery handles the rest:
-*
-* ```ts
-* const policyHook = createToolPolicyHook({
-*   mode: 'default',
-*   allow: ['read_*', 'grep', 'glob'],
-*   deny:  ['delete_*'],
-*   ask:   ['execute_*', 'mcp:*'],
-* });
-* registry.register('PreToolUse', { hooks: [policyHook] });
-* ```
-*
-* Explicit rules take precedence over fallback modes:
-*
-*   1. `deny` rule match → `'deny'` (always wins, even in `bypass`).
-*   2. `ask` rule match → `'ask'`.
-*   3. `allow` rule match → `'allow'`.
-*   4. `mode === 'bypass'` → `'allow'`.
-*   5. `mode === 'dontAsk'` → `'deny'`.
-*   6. fallthrough → `'ask'`.
-*
-* The returned callback is a single `HookCallback`, not a `HookMatcher` —
-* register it under the matcher with the pattern you want (omit the
-* pattern to fire on every tool call, which is the typical case since
-* the policy itself does the filtering).
-*/
 function createToolPolicyHook(config) {
 	const denyMatcher = compileMatchers(config.deny);
 	const allowMatcher = compileMatchers(config.allow);

package/dist/esm/hooks/createToolPolicyHook.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"createToolPolicyHook.mjs","names":[],"sources":["../../../src/hooks/createToolPolicyHook.ts"],"sourcesContent":["/**\n * Declarative `PreToolUse` hook factory. Lets hosts express common\n * permission policies (allow / deny / ask lists + a global mode) without\n * hand-rolling matching, precedence, and decision logic per-host.\n *\n * Uses the Claude Code Agent SDK permission vocabulary (`allowed_tools` /\n * `disallowed_tools` / `permissionMode`) while treating modes as fallbacks\n * for calls that match no explicit rule. See the README's HITL section for\n * the cross-walk and `docs/hooks-design-report.md` for the broader hook\n * system context.\n */\n\nimport type { HookCallback, PreToolUseHookOutput, ToolDecision } from './types';\n\n/**\n * Permission mode controlling how tool calls that match no rule are\n * resolved. Mirrors Claude Code's `permissionMode`.\n *\n *   - `default`  — unmatched tools fall through to `'ask'` (interrupt).\n *   - `dontAsk`  — unmatched tools are denied; the human is never\n *                  prompted. Useful for headless / API agents where a\n *                  silent denial is preferable to a hung interrupt.\n *   - `bypass`   — unmatched tools are approved. Explicit `deny` and `ask`\n *                  rules still apply.\n */\nexport type ToolPolicyMode = 'default' | 'dontAsk' | 'bypass';\n\nexport interface ToolPolicyConfig {\n  /**\n   * Global mode applied to tools that don't match any rule.\n   * Defaults to `'default'` (ask the human).\n   */\n  mode?: ToolPolicyMode;\n  /**\n   * Tool name patterns that are auto-approved without a prompt.\n   * Patterns support glob `*` wildcards: `read_file`, `mcp:github:*`,\n   * `*search*`. Match is anchored (`^pattern$`).\n   */\n  allow?: readonly string[];\n  /**\n   * Tool name patterns that are blocked outright. Wins over `allow`\n   * and `ask`, and overrides `mode: 'bypass'` — a deny rule always\n   * holds, matching Claude Code's \"deny rules are checked first\" guarantee.\n   */\n  deny?: readonly string[];\n  /**\n   * Tool name patterns that always trigger human approval. Wins over\n   * `allow` and every mode, but not `deny`.\n   */\n  ask?: readonly string[];\n  /**\n   * Optional reason attached to the resulting `ask` / `deny` hook\n   * decision so the host UI can render why approval is required.\n   * The literal token `{tool}` is replaced with the tool name.\n   */\n  reason?: string;\n}\n\n/**\n * Compile a glob string with `*` wildcards into a single anchored\n * `RegExp`. Other regex metacharacters are escaped, so `read_file.md`\n * matches the literal dot. Patterns are short (tool names), so we do\n * not cache here — the registry's `matchesQuery` already caches its own\n * regex compilations and our patterns are evaluated once per ToolNode\n * batch, not once per stream chunk.\n */\nfunction globToRegex(pattern: string): RegExp {\n  const escaped = pattern.replace(/[.+?^${}()|[\\]\\\\]/g, '\\\\$&');\n  return new RegExp('^' + escaped.replace(/\\*/g, '.*') + '$');\n}\n\n/** Pre-compile a list of glob patterns into a single match function. */\nfunction compileMatchers(\n  patterns: readonly string[] | undefined\n): (toolName: string) => boolean {\n  if (patterns == null || patterns.length === 0) {\n    return () => false;\n  }\n  const regexes = patterns.map(globToRegex);\n  return (toolName: string): boolean => {\n    for (const regex of regexes) {\n      if (regex.test(toolName)) {\n        return true;\n      }\n    }\n    return false;\n  };\n}\n\nfunction formatReason(\n  template: string | undefined,\n  toolName: string\n): string | undefined {\n  if (template == null) {\n    return undefined;\n  }\n  return template.replace(/\\{tool\\}/g, toolName);\n}\n\n/**\n * Build a `PreToolUse` hook callback that applies a declarative tool\n * permission policy. Register it with a `HookRegistry` and the SDK's\n * `humanInTheLoop` machinery handles the rest:\n *\n * ```ts\n * const policyHook = createToolPolicyHook({\n *   mode: 'default',\n *   allow: ['read_*', 'grep', 'glob'],\n *   deny:  ['delete_*'],\n *   ask:   ['execute_*', 'mcp:*'],\n * });\n * registry.register('PreToolUse', { hooks: [policyHook] });\n * ```\n *\n * Explicit rules take precedence over fallback modes:\n *\n *   1. `deny` rule match → `'deny'` (always wins, even in `bypass`).\n *   2. `ask` rule match → `'ask'`.\n *   3. `allow` rule match → `'allow'`.\n *   4. `mode === 'bypass'` → `'allow'`.\n *   5. `mode === 'dontAsk'` → `'deny'`.\n *   6. fallthrough → `'ask'`.\n *\n * The returned callback is a single `HookCallback`, not a `HookMatcher` —\n * register it under the matcher with the pattern you want (omit the\n * pattern to fire on every tool call, which is the typical case since\n * the policy itself does the filtering).\n */\nexport function createToolPolicyHook(\n  config: ToolPolicyConfig\n): HookCallback<'PreToolUse'> {\n  const denyMatcher = compileMatchers(config.deny);\n  const allowMatcher = compileMatchers(config.allow);\n  const askMatcher = compileMatchers(config.ask);\n  const mode: ToolPolicyMode = config.mode ?? 'default';\n  const reasonTemplate = config.reason;\n\n  return async (input): Promise<PreToolUseHookOutput> => {\n    const toolName = input.toolName;\n    const decision = decide(\n      toolName,\n      mode,\n      denyMatcher,\n      allowMatcher,\n      askMatcher\n    );\n    if (decision === 'allow') {\n      return { decision };\n    }\n    const reason = formatReason(reasonTemplate, toolName);\n    if (reason != null) {\n      return { decision, reason };\n    }\n    return { decision };\n  };\n}\n\nfunction decide(\n  toolName: string,\n  mode: ToolPolicyMode,\n  denyMatch: (n: string) => boolean,\n  allowMatch: (n: string) => boolean,\n  askMatch: (n: string) => boolean\n): ToolDecision {\n  if (denyMatch(toolName)) {\n    return 'deny';\n  }\n  if (askMatch(toolName)) {\n    return 'ask';\n  }\n  if (allowMatch(toolName)) {\n    return 'allow';\n  }\n  if (mode === 'bypass') {\n    return 'allow';\n  }\n  if (mode === 'dontAsk') {\n    return 'deny';\n  }\n  return 'ask';\n}\n"],"mappings":";;;;;;;;;AAkEA,SAAS,YAAY,SAAyB;CAC5C,MAAM,UAAU,QAAQ,QAAQ,sBAAsB,MAAM;CAC5D,OAAO,IAAI,OAAO,MAAM,QAAQ,QAAQ,OAAO,IAAI,IAAI,GAAG;AAC5D;;AAGA,SAAS,gBACP,UAC+B;CAC/B,IAAI,YAAY,QAAQ,SAAS,WAAW,GAC1C,aAAa;CAEf,MAAM,UAAU,SAAS,IAAI,WAAW;CACxC,QAAQ,aAA8B;EACpC,KAAK,MAAM,SAAS,SAClB,IAAI,MAAM,KAAK,QAAQ,GACrB,OAAO;EAGX,OAAO;CACT;AACF;AAEA,SAAS,aACP,UACA,UACoB;CACpB,IAAI,YAAY,MACd;CAEF,OAAO,SAAS,QAAQ,aAAa,QAAQ;AAC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,SAAgB,qBACd,QAC4B;CAC5B,MAAM,cAAc,gBAAgB,OAAO,IAAI;CAC/C,MAAM,eAAe,gBAAgB,OAAO,KAAK;CACjD,MAAM,aAAa,gBAAgB,OAAO,GAAG;CAC7C,MAAM,OAAuB,OAAO,QAAQ;CAC5C,MAAM,iBAAiB,OAAO;CAE9B,OAAO,OAAO,UAAyC;EACrD,MAAM,WAAW,MAAM;EACvB,MAAM,WAAW,OACf,UACA,MACA,aACA,cACA,UACF;EACA,IAAI,aAAa,SACf,OAAO,EAAE,SAAS;EAEpB,MAAM,SAAS,aAAa,gBAAgB,QAAQ;EACpD,IAAI,UAAU,MACZ,OAAO;GAAE;GAAU;EAAO;EAE5B,OAAO,EAAE,SAAS;CACpB;AACF;AAEA,SAAS,OACP,UACA,MACA,WACA,YACA,UACc;CACd,IAAI,UAAU,QAAQ,GACpB,OAAO;CAET,IAAI,SAAS,QAAQ,GACnB,OAAO;CAET,IAAI,WAAW,QAAQ,GACrB,OAAO;CAET,IAAI,SAAS,UACX,OAAO;CAET,IAAI,SAAS,WACX,OAAO;CAET,OAAO;AACT"}
+{"version":3,"file":"createToolPolicyHook.mjs","names":[],"sources":["../../../src/hooks/createToolPolicyHook.ts"],"mappings":";AAkEA,SAAS,YAAY,SAAyB;CAC5C,MAAM,UAAU,QAAQ,QAAQ,sBAAsB,MAAM;CAC5D,OAAO,IAAI,OAAO,MAAM,QAAQ,QAAQ,OAAO,IAAI,IAAI,GAAG;AAC5D;AAGA,SAAS,gBACP,UAC+B;CAC/B,IAAI,YAAY,QAAQ,SAAS,WAAW,GAC1C,aAAa;CAEf,MAAM,UAAU,SAAS,IAAI,WAAW;CACxC,QAAQ,aAA8B;EACpC,KAAK,MAAM,SAAS,SAClB,IAAI,MAAM,KAAK,QAAQ,GACrB,OAAO;EAGX,OAAO;CACT;AACF;AAEA,SAAS,aACP,UACA,UACoB;CACpB,IAAI,YAAY,MACd;CAEF,OAAO,SAAS,QAAQ,aAAa,QAAQ;AAC/C;AA+BA,SAAgB,qBACd,QAC4B;CAC5B,MAAM,cAAc,gBAAgB,OAAO,IAAI;CAC/C,MAAM,eAAe,gBAAgB,OAAO,KAAK;CACjD,MAAM,aAAa,gBAAgB,OAAO,GAAG;CAC7C,MAAM,OAAuB,OAAO,QAAQ;CAC5C,MAAM,iBAAiB,OAAO;CAE9B,OAAO,OAAO,UAAyC;EACrD,MAAM,WAAW,MAAM;EACvB,MAAM,WAAW,OACf,UACA,MACA,aACA,cACA,UACF;EACA,IAAI,aAAa,SACf,OAAO,EAAE,SAAS;EAEpB,MAAM,SAAS,aAAa,gBAAgB,QAAQ;EACpD,IAAI,UAAU,MACZ,OAAO;GAAE;GAAU;EAAO;EAE5B,OAAO,EAAE,SAAS;CACpB;AACF;AAEA,SAAS,OACP,UACA,MACA,WACA,YACA,UACc;CACd,IAAI,UAAU,QAAQ,GACpB,OAAO;CAET,IAAI,SAAS,QAAQ,GACnB,OAAO;CAET,IAAI,WAAW,QAAQ,GACrB,OAAO;CAET,IAAI,SAAS,UACX,OAAO;CAET,IAAI,SAAS,WACX,OAAO;CAET,OAAO;AACT"}

package/dist/esm/hooks/createWorkspacePolicyHook.mjs

@@ -4,54 +4,6 @@ import { homedir } from "os";
 import { realpath } from "fs/promises";
 import { isAbsolute, relative, resolve } from "path";
 //#region src/hooks/createWorkspacePolicyHook.ts
-/**
-* Workspace boundary policy as a `PreToolUse` hook.
-*
-* Local-engine file tools enforce a hard workspace boundary at the
-* tool implementation layer (`resolveWorkspacePathSafe`). This hook
-* adds a complementary, host-controlled layer on top that uses the
-* standard PreToolUse / HITL machinery to *negotiate* access to
-* paths outside the workspace — instead of just throwing.
-*
-* The host opts in by registering this hook on a `HookRegistry`; the
-* hook inspects each tool call's input, extracts the file paths it
-* mentions via per-tool extractors, and returns:
-*
-*   - `allow`               — every path is inside `workspace.root`
-*                              (or `additionalRoots`)
-*   - `deny`                — at least one path is outside, and the
-*                              configured outside-policy is `'deny'`
-*   - `ask`                 — at least one path is outside, and the
-*                              outside-policy is `'ask'` (default).
-*                              When `humanInTheLoop.enabled` is true,
-*                              the existing PreToolUse `'ask'` flow
-*                              raises a tool_approval interrupt the
-*                              host UI can render. When HITL is off,
-*                              `'ask'` collapses to `deny` (matches
-*                              the rest of the SDK's default).
-*
-* Default per-tool path extractors cover the local-engine coding
-* suite (`read_file`, `write_file`, `edit_file`, `grep_search`,
-* `glob_search`, `list_directory`, `compile_check`). The host can
-* override or extend via `pathExtractors`. Bash/code paths are not
-* extracted by default — bash command parsing is its own concern, and
-* the existing `bashAst` validator + sandbox-runtime fs allowlist are
-* the right gates for those.
-*
-* Important: this hook does NOT replace `resolveWorkspacePathSafe`.
-* Even if the hook returns `allow`, the file tool still enforces its
-* own clamp unless `workspace.allowReadOutside` /
-* `workspace.allowWriteOutside` (or the legacy
-* `allowOutsideWorkspace`) is set. The recommended composition for
-* "ask the user" semantics is:
-*
-*   workspace: {
-*     root,
-*     allowReadOutside: true,
-*     allowWriteOutside: true,
-*   },
-*   // …with the hook installed and humanInTheLoop.enabled = true.
-*/
 const READ_TOOLS = new Set([
 	"read_file",
 	"grep_search",
@@ -93,20 +45,6 @@ function isInsideAnyRoot(absolutePath, roots) {
 	}
 	return false;
 }
-/**
-* Symlink-aware variant: realpaths the candidate AND the roots before
-* comparing. Without this, a symlink inside the workspace pointing
-* outside (e.g. `workspace/link → /etc/passwd`) compares as
-* "in-workspace" lexically, but actually grants the agent reach
-* outside the boundary. Critical when this hook is the primary gate
-* (i.e. the host opted into `workspace.allowReadOutside: true` /
-* `allowWriteOutside: true` so the file tools' own clamp is off).
-*
-* Handles paths that don't yet exist (e.g. `write_file` to a brand
-* new path) by walking up to the nearest existing ancestor and
-* realpathing that, then re-attaching the unresolved suffix. Mirrors
-* `resolveWorkspacePathSafe`'s approach in LocalExecutionEngine.
-*/
 async function realpathOrSelf(absolutePath) {
 	try {
 		return await realpath(absolutePath);
@@ -136,20 +74,6 @@ function formatReason(template, toolName, outsidePaths) {
 	if (template == null) return fallback;
 	return template.replace(/\{tool\}/g, toolName).replace(/\{paths\}/g, outsidePaths.join(", "));
 }
-/**
-* Build a `PreToolUse` callback that enforces the workspace policy.
-* Register it on a `HookRegistry`:
-*
-* ```ts
-* registry.register('PreToolUse', {
-*   hooks: [createWorkspacePolicyHook({ root, outsideWrite: 'ask' })],
-* });
-* ```
-*
-* The hook is composable with `createToolPolicyHook` — register both;
-* `executeHooks` precedence (`deny > ask > allow`) sorts out which
-* decision wins per call.
-*/
 function createWorkspacePolicyHook(config) {
 	const root = resolve(config.root);
 	const allRoots = [root, ...(config.additionalRoots ?? []).map((p) => isAbsolute(p) ? resolve(p) : resolve(root, p))];
@@ -164,7 +88,6 @@ function createWorkspacePolicyHook(config) {
 		...DEFAULT_EXTRACTORS,
 		...config.pathExtractors ?? {}
 	};
-	/** Unknown tools are treated as writes (the stricter policy). */
 	const resolvePolicy = (toolName) => {
 		if (WRITE_TOOLS.has(toolName)) return writePolicy;
 		if (READ_TOOLS.has(toolName)) return readPolicy;

package/dist/esm/hooks/createWorkspacePolicyHook.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"createWorkspacePolicyHook.mjs","names":[],"sources":["../../../src/hooks/createWorkspacePolicyHook.ts"],"sourcesContent":["/**\n * Workspace boundary policy as a `PreToolUse` hook.\n *\n * Local-engine file tools enforce a hard workspace boundary at the\n * tool implementation layer (`resolveWorkspacePathSafe`). This hook\n * adds a complementary, host-controlled layer on top that uses the\n * standard PreToolUse / HITL machinery to *negotiate* access to\n * paths outside the workspace — instead of just throwing.\n *\n * The host opts in by registering this hook on a `HookRegistry`; the\n * hook inspects each tool call's input, extracts the file paths it\n * mentions via per-tool extractors, and returns:\n *\n *   - `allow`               — every path is inside `workspace.root`\n *                              (or `additionalRoots`)\n *   - `deny`                — at least one path is outside, and the\n *                              configured outside-policy is `'deny'`\n *   - `ask`                 — at least one path is outside, and the\n *                              outside-policy is `'ask'` (default).\n *                              When `humanInTheLoop.enabled` is true,\n *                              the existing PreToolUse `'ask'` flow\n *                              raises a tool_approval interrupt the\n *                              host UI can render. When HITL is off,\n *                              `'ask'` collapses to `deny` (matches\n *                              the rest of the SDK's default).\n *\n * Default per-tool path extractors cover the local-engine coding\n * suite (`read_file`, `write_file`, `edit_file`, `grep_search`,\n * `glob_search`, `list_directory`, `compile_check`). The host can\n * override or extend via `pathExtractors`. Bash/code paths are not\n * extracted by default — bash command parsing is its own concern, and\n * the existing `bashAst` validator + sandbox-runtime fs allowlist are\n * the right gates for those.\n *\n * Important: this hook does NOT replace `resolveWorkspacePathSafe`.\n * Even if the hook returns `allow`, the file tool still enforces its\n * own clamp unless `workspace.allowReadOutside` /\n * `workspace.allowWriteOutside` (or the legacy\n * `allowOutsideWorkspace`) is set. The recommended composition for\n * \"ask the user\" semantics is:\n *\n *   workspace: {\n *     root,\n *     allowReadOutside: true,\n *     allowWriteOutside: true,\n *   },\n *   // …with the hook installed and humanInTheLoop.enabled = true.\n */\n\nimport { homedir } from 'os';\nimport { realpath } from 'fs/promises';\nimport { isAbsolute, relative, resolve } from 'path';\nimport type {\n  HookCallback,\n  PreToolUseHookInput,\n  PreToolUseHookOutput,\n  ToolDecision,\n} from './types';\nimport { Constants } from '@/common';\n\n/**\n * What to do when a tool call references a path outside the workspace.\n *\n *   - `'ask'`    : default. Raise a PreToolUse `ask` (host UI prompts\n *                  via the HITL interrupt path).\n *   - `'allow'`  : let the call through (use the existing tool clamp\n *                  to actually enforce — the hook is purely advisory).\n *   - `'deny'`   : block the call with an error ToolMessage.\n */\nexport type OutsideAccessPolicy = 'ask' | 'allow' | 'deny';\n\nexport interface WorkspacePolicyConfig {\n  /** Canonical workspace root. Required. */\n  root: string;\n  /** Sibling roots that count as inside-workspace. */\n  additionalRoots?: readonly string[];\n  /** Policy applied to read-only file tools. Defaults to `'ask'`. */\n  outsideRead?: OutsideAccessPolicy;\n  /** Policy applied to write-shaped file tools. Defaults to `'ask'`. */\n  outsideWrite?: OutsideAccessPolicy;\n  /**\n   * Optional reason template surfaced in the `ask`/`deny` decision.\n   * Supports `{tool}` and `{paths}` substitution.\n   */\n  reason?: string;\n  /**\n   * Per-tool path extractors. Defaults cover the local-engine coding\n   * suite. Returning an empty array opts that tool out of policy.\n   */\n  pathExtractors?: Record<string, PathExtractor>;\n}\n\nexport type PathExtractor = (\n  toolInput: Record<string, unknown>\n) => readonly string[];\n\nconst READ_TOOLS = new Set<string>([\n  Constants.READ_FILE,\n  Constants.GREP_SEARCH,\n  Constants.GLOB_SEARCH,\n  Constants.LIST_DIRECTORY,\n  Constants.COMPILE_CHECK,\n]);\n\nconst WRITE_TOOLS = new Set<string>([\n  Constants.WRITE_FILE,\n  Constants.EDIT_FILE,\n]);\n\n/**\n * Best-effort extractor for `compile_check` — pulls absolute and `~/`\n * path tokens out of the `command` string so the workspace boundary\n * sees them. Without this, a model could ship `command: 'cat\n * /etc/passwd'` and the policy hook would short-circuit to `allow`\n * (Codex P1 #26 — the prior `() => []` made the hook a no-op for\n * compile_check). Conservative by design:\n *\n *   - Matches `/foo`, `~/foo`, `$HOME/foo`, `${HOME}/foo` followed by\n *     non-shell-special chars. Stops at whitespace, quotes, redirect\n *     operators, pipes, semicolons.\n *   - Strips a leading `--flag=` so `--out=/etc/foo` extracts as\n *     `/etc/foo` (the path the agent's actually trying to write).\n *   - Misses relative paths (intended — those resolve under cwd\n *     anyway), and shell-substituted paths whose final form isn't\n *     visible at extract time. Hosts that need bulletproof gating\n *     should pair this with a `bash_tool`-level policy.\n */\n// `[\"']?` slots before AND after the captured path cover quoted\n// forms like `cat \"/etc/passwd\"` and `--out='/tmp/x'`. Codex P1 #31\n// — the previous regex only matched unquoted tokens, so a model\n// could trivially bypass the workspace policy by quoting any\n// destination path. The path content character class still excludes\n// quotes/whitespace/shell-specials so we don't over-extract; that's\n// the defensive trade we want for fallback-grep style matching.\n//\n// The `\\.\\.(?:\\/[^…]*)?` alternation covers parent-traversal forms\n// (`..`, `../secrets.txt`, `../foo/bar`). Without it, a model could\n// exfiltrate parent-directory files via `cat ../secrets` and the\n// hook would short-circuit to `allow` because the extractor saw no\n// \"absolute\" token. The boundary check at the call site resolves\n// non-absolute extracted tokens against `root`, so `../secrets`\n// becomes `<parent-of-workspace>/secrets` which the boundary then\n// correctly flags as outside. Codex P2 #35.\nconst PATH_TOKEN =\n  /(?:^|[\\s=])(?:--[^\\s=]+=)?[\"']?(\\/[^\\s'\"|;&<>()`]+|~\\/[^\\s'\"|;&<>()`]+|\\$\\{?HOME\\}?\\/[^\\s'\"|;&<>()`]+|\\.\\.(?:\\/[^\\s'\"|;&<>()`]*)?)[\"']?/g;\n// Back-compat alias kept for any downstream import.\nconst ABSOLUTE_PATH_TOKEN = PATH_TOKEN;\nfunction expandHomeRelative(token: string): string {\n  // Expand ~/foo and $HOME/foo and ${HOME}/foo to absolute. The\n  // workspace boundary check resolves non-absolute paths against the\n  // workspace root, which would silently treat `~/secret` as\n  // `<workspace>/~/secret` — exactly the bypass the codex flagged.\n  const home = homedir();\n  if (token.startsWith('~/')) return `${home}/${token.slice(2)}`;\n  if (token.startsWith('${HOME}/')) return `${home}/${token.slice(8)}`;\n  if (token.startsWith('$HOME/')) return `${home}/${token.slice(6)}`;\n  return token;\n}\nfunction extractCompileCheckPaths(input: Record<string, unknown>): string[] {\n  const command = typeof input.command === 'string' ? input.command : '';\n  if (command === '') return [];\n  const out: string[] = [];\n  for (const match of command.matchAll(ABSOLUTE_PATH_TOKEN)) {\n    out.push(expandHomeRelative(match[1]));\n  }\n  return out;\n}\n\n// All built-in coding tools take their file/dir target in `path`.\nconst extractPath: PathExtractor = (i) =>\n  typeof i.path === 'string' && i.path !== '' ? [i.path] : [];\n\nconst DEFAULT_EXTRACTORS: Record<string, PathExtractor> = {\n  [Constants.READ_FILE]: extractPath,\n  [Constants.WRITE_FILE]: extractPath,\n  [Constants.EDIT_FILE]: extractPath,\n  [Constants.GREP_SEARCH]: (i) =>\n    typeof i.path === 'string' && i.path !== '' ? [i.path] : [],\n  [Constants.GLOB_SEARCH]: (i) =>\n    typeof i.path === 'string' && i.path !== '' ? [i.path] : [],\n  [Constants.LIST_DIRECTORY]: (i) =>\n    typeof i.path === 'string' && i.path !== '' ? [i.path] : [],\n  [Constants.COMPILE_CHECK]: extractCompileCheckPaths,\n};\n\nfunction isInsideAnyRoot(absolutePath: string, roots: string[]): boolean {\n  for (const root of roots) {\n    if (absolutePath === root) return true;\n    const rel = relative(root, absolutePath);\n    if (!rel.startsWith('..') && !isAbsolute(rel)) return true;\n  }\n  return false;\n}\n\n/**\n * Symlink-aware variant: realpaths the candidate AND the roots before\n * comparing. Without this, a symlink inside the workspace pointing\n * outside (e.g. `workspace/link → /etc/passwd`) compares as\n * \"in-workspace\" lexically, but actually grants the agent reach\n * outside the boundary. Critical when this hook is the primary gate\n * (i.e. the host opted into `workspace.allowReadOutside: true` /\n * `allowWriteOutside: true` so the file tools' own clamp is off).\n *\n * Handles paths that don't yet exist (e.g. `write_file` to a brand\n * new path) by walking up to the nearest existing ancestor and\n * realpathing that, then re-attaching the unresolved suffix. Mirrors\n * `resolveWorkspacePathSafe`'s approach in LocalExecutionEngine.\n */\nasync function realpathOrSelf(absolutePath: string): Promise<string> {\n  try {\n    return await realpath(absolutePath);\n  } catch {\n    return absolutePath;\n  }\n}\n\nasync function realpathOfPathOrAncestor(absolutePath: string): Promise<string> {\n  let current = absolutePath;\n  let suffix = '';\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  while (true) {\n    try {\n      const real = await realpath(current);\n      return suffix === '' ? real : resolve(real, suffix);\n    } catch {\n      const parent = resolve(current, '..');\n      if (parent === current) {\n        return absolutePath;\n      }\n      const base = current.slice(parent.length + 1);\n      suffix = suffix === '' ? base : `${base}/${suffix}`;\n      current = parent;\n    }\n  }\n}\n\nasync function isInsideAnyRootRealpath(\n  absolutePath: string,\n  realRoots: readonly string[]\n): Promise<boolean> {\n  const real = await realpathOfPathOrAncestor(absolutePath);\n  return isInsideAnyRoot(real, [...realRoots]);\n}\n\nfunction formatReason(\n  template: string | undefined,\n  toolName: string,\n  outsidePaths: readonly string[]\n): string {\n  const fallback = `Tool \"${toolName}\" wants to touch ${outsidePaths.length} path(s) outside the workspace: ${outsidePaths.join(', ')}`;\n  if (template == null) return fallback;\n  return template\n    .replace(/\\{tool\\}/g, toolName)\n    .replace(/\\{paths\\}/g, outsidePaths.join(', '));\n}\n\n/**\n * Build a `PreToolUse` callback that enforces the workspace policy.\n * Register it on a `HookRegistry`:\n *\n * ```ts\n * registry.register('PreToolUse', {\n *   hooks: [createWorkspacePolicyHook({ root, outsideWrite: 'ask' })],\n * });\n * ```\n *\n * The hook is composable with `createToolPolicyHook` — register both;\n * `executeHooks` precedence (`deny > ask > allow`) sorts out which\n * decision wins per call.\n */\nexport function createWorkspacePolicyHook(\n  config: WorkspacePolicyConfig\n): HookCallback<'PreToolUse'> {\n  const root = resolve(config.root);\n  // Relative `additionalRoots` entries are anchored to `root` so a\n  // monorepo config like `additionalRoots: ['../shared']` resolves\n  // to a sibling of `root`, not of process.cwd. Matches\n  // `getWorkspaceRoots` in LocalExecutionEngine.\n  const additionalRoots = (config.additionalRoots ?? []).map((p) =>\n    isAbsolute(p) ? resolve(p) : resolve(root, p)\n  );\n  const allRoots = [root, ...additionalRoots];\n\n  // Pre-realpath the roots once at construction — these are stable\n  // per Run. The candidate paths get realpath'd lazily inside the\n  // hook callback. Cached so the per-call cost is just one realpath.\n  let realRootsPromise: Promise<string[]> | undefined;\n  const getRealRoots = (): Promise<string[]> => {\n    if (realRootsPromise == null) {\n      realRootsPromise = Promise.all(allRoots.map(realpathOrSelf));\n    }\n    return realRootsPromise;\n  };\n\n  const readPolicy: OutsideAccessPolicy = config.outsideRead ?? 'ask';\n  const writePolicy: OutsideAccessPolicy = config.outsideWrite ?? 'ask';\n\n  const extractors: Record<string, PathExtractor | undefined> = {\n    ...DEFAULT_EXTRACTORS,\n    ...(config.pathExtractors ?? {}),\n  };\n\n  /** Unknown tools are treated as writes (the stricter policy). */\n  const resolvePolicy = (toolName: string): OutsideAccessPolicy => {\n    if (WRITE_TOOLS.has(toolName)) {\n      return writePolicy;\n    }\n    if (READ_TOOLS.has(toolName)) {\n      return readPolicy;\n    }\n    return writePolicy;\n  };\n\n  return async (input: PreToolUseHookInput): Promise<PreToolUseHookOutput> => {\n    const extractor = extractors[input.toolName];\n    if (extractor == null) return { decision: 'allow' };\n\n    const paths = extractor(input.toolInput);\n    if (paths.length === 0) return { decision: 'allow' };\n\n    // Two-stage check:\n    //   1. Lexical fast path — anything that's lexically inside the\n    //      workspace AND doesn't get redirected by realpath stays\n    //      allow-able without paying the realpath cost on every call.\n    //   2. For paths that look outside lexically OR look inside but\n    //      may have been routed through a symlink, realpath both the\n    //      candidate and the roots and compare. This catches the\n    //      `workspace/link → /etc/passwd` escape that lexical-only\n    //      checks miss.\n    const outside: string[] = [];\n    const realRoots = await getRealRoots();\n    for (const p of paths) {\n      const abs = isAbsolute(p) ? resolve(p) : resolve(root, p);\n      // Realpath is the source of truth — it catches both the\n      // symlink-escape case (lexically-inside path that resolves\n      // outside) and the alternate-mount case (lexically-outside\n      // path that resolves back inside the workspace). The lexical\n      // check alone gives the wrong answer for either, so we don't\n      // bother computing it.\n      const realInside = await isInsideAnyRootRealpath(abs, realRoots);\n      if (!realInside) {\n        outside.push(p);\n      }\n    }\n    if (outside.length === 0) return { decision: 'allow' };\n\n    const policy = resolvePolicy(input.toolName);\n    if (policy === 'allow') return { decision: 'allow' };\n\n    const decision: ToolDecision = policy === 'deny' ? 'deny' : 'ask';\n    return {\n      decision,\n      reason: formatReason(config.reason, input.toolName, outside),\n      ...(decision === 'ask'\n        ? { allowedDecisions: ['approve', 'reject'] as const }\n        : {}),\n    };\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"createWorkspacePolicyHook.mjs","names":[],"sources":["../../../src/hooks/createWorkspacePolicyHook.ts"],"mappings":"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"}

package/dist/esm/hooks/executeHooks.mjs

@@ -1,6 +1,5 @@
 import { matchesQuery } from "./matchers.mjs";
 //#region src/hooks/executeHooks.ts
-/** Default per-hook timeout when a matcher doesn't set its own. */
 const DEFAULT_HOOK_TIMEOUT_MS = 3e4;
 function freshResult() {
 	return {
@@ -191,12 +190,6 @@ function fold(outcomes) {
 		}
 		const output = outcome.output;
 		if (output === null) continue;
-		/**
-		* Skip fire-and-forget outputs entirely: the agent has already
-		* moved on, so an async hook cannot influence the run. Background
-		* work inside the hook body still runs (we don't cancel it), it
-		* just doesn't fold into the aggregate result.
-		*/
 		if (output.async === true) continue;
 		const targets = isOnceMatcher ? [aggregated, onceContribution] : [aggregated];
 		if (isOnceMatcher) hasOnceContribution = true;
@@ -215,60 +208,6 @@ function fold(outcomes) {
 		...hasOnceContribution ? { onceReplayContribution: onceContribution } : {}
 	};
 }
-/**
-* Fires every matcher registered against `input.hook_event_name`, folding
-* their results per `deny > ask > allow` precedence and accumulating
-* context/errors.
-*
-* ## Parallelism and determinism
-*
-* All matching hooks fire simultaneously and are awaited via `Promise.all`,
-* which preserves input-array order in its returned results. The fold
-* therefore iterates outcomes in **registration order** — outer loop over
-* matchers as they sit in the registry (global first, then session), inner
-* loop over each matcher's `hooks` array. Last-writer-wins fields
-* (`updatedInput`, `updatedOutput`) are deterministic in that order, even
-* though hooks may complete in arbitrary wall-clock order.
-*
-* Consumers that need a single authoritative rewrite should still scope
-* `updatedInput`/`updatedOutput` to one hook per matcher to avoid subtle
-* precedence bugs when matchers are added in a different order than
-* expected.
-*
-* ## Timeouts and cancellation
-*
-* Each matcher receives **one shared `AbortSignal`** derived from the
-* caller's parent signal combined with `matcher.timeout` (falling back to
-* `opts.timeoutMs`, default {@link DEFAULT_HOOK_TIMEOUT_MS}). Sharing the
-* signal across hooks in a matcher collapses N timer allocations into
-* one, which matters on the PreToolUse hot path where a matcher with
-* several hooks fires on every tool call. Each hook call is raced
-* against the shared signal, so even a hook that ignores the signal is
-* force-unblocked when the timeout fires. Timeout/abort errors are
-* swallowed into the aggregated result's `errors` array (non-fatal by
-* default).
-*
-* ## Internal matchers
-*
-* A matcher with `internal: true` is excluded from both the `errors` array
-* and the logger output. Use it for infrastructure hooks whose failures
-* should not pollute user-visible diagnostics.
-*
-* ## Once semantics — atomic at-most-once
-*
-* A matcher with `once: true` is removed from the registry **before any
-* hook runs**, inside the synchronous prefix of `executeHooks` (between
-* `getMatchers` and the first `await`). Because Node's event loop serialises
-* sync work, two concurrent `executeHooks` calls can never both observe
-* and dispatch the same `once` matcher — whichever call runs its sync
-* prefix first consumes it, and the loser sees an empty bucket.
-*
-* Trade-off: if every hook in a `once` matcher throws, the matcher is
-* still gone. "Once" here means "at most one dispatch, ever", not "at
-* most one successful execution with retry on failure". Hosts that need
-* retry semantics should register a normal matcher and self-unregister
-* via the `unregister` callback returned from `registry.register`.
-*/
 async function executeHooks(opts) {
 	const { registry, input, sessionId, matchQuery, onceReplayKey, onceReplaySessionId, signal, timeoutMs = DEFAULT_HOOK_TIMEOUT_MS, logger } = opts;
 	const event = input.hook_event_name;
@@ -291,24 +230,6 @@ async function executeHooks(opts) {
 	const aggregated = combineAggregatedResults(pendingApproval, liveResult);
 	if (event === "PreToolUse" && aggregated.decision === "ask" && onceReplayContribution != null && replaySessionId != null && onceReplayKey != null) registry.setPendingToolApproval(replaySessionId, onceReplayKey, createPendingApprovalReplay(aggregated, pendingApproval, onceReplayContribution));
 	else if (event === "PreToolUse" && aggregated.decision !== "ask" && pendingApproval != null && replaySessionId != null && onceReplayKey != null) registry.clearPendingToolApproval(replaySessionId, onceReplayKey);
-	/**
-	* Centralized `preventContinuation` propagation: when any hook (across
-	* any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,
-	* etc.) returns `preventContinuation: true`, raise a halt signal on
-	* the registry scoped to the run's `sessionId`. `Run.processStream`
-	* polls the signal between stream events using its own id and exits
-	* cleanly, skipping the `Stop` hook (since the run is being halted,
-	* not naturally completing).
-	*
-	* First-write-wins per session inside the registry — a halt already
-	* raised by an earlier hook in the same run is preserved so the
-	* original `reason` / `source` are not clobbered. Hooks fired
-	* without a `sessionId` cannot raise a halt (there's no run for the
-	* loop to poll under), which is fine: every in-tree callsite passes
-	* `sessionId: runId`. Pre-stream callsites in `Run.processStream`
-	* still read `preventContinuation` directly off the result for an
-	* early return because they have not yet entered the stream loop.
-	*/
 	if (aggregated.preventContinuation === true && sessionId !== void 0) registry.haltRun(sessionId, aggregated.stopReason ?? "preventContinuation", event);
 	return aggregated;
 }

package/dist/esm/hooks/executeHooks.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"executeHooks.mjs","names":[],"sources":["../../../src/hooks/executeHooks.ts"],"sourcesContent":["// src/hooks/executeHooks.ts\nimport type { Logger } from 'winston';\nimport type {\n  HookInput,\n  HookEvent,\n  HookOutput,\n  HookMatcher,\n  ToolDecision,\n  StopDecision,\n  HookCallback,\n  ToolApprovalReplayKey,\n  AggregatedHookResult,\n} from './types';\nimport type { HookRegistry } from './HookRegistry';\nimport { matchesQuery } from './matchers';\n\n/** Default per-hook timeout when a matcher doesn't set its own. */\nexport const DEFAULT_HOOK_TIMEOUT_MS = 30_000;\n\n/**\n * Options for a single `executeHooks` call. The `input` drives everything —\n * the event name is read from `input.hook_event_name`, matchers are looked\n * up against that event, and each hook receives `input` directly.\n */\nexport interface ExecuteHooksOptions {\n  registry: HookRegistry;\n  input: HookInput;\n  /** Scope lookup to this session (in addition to global matchers). */\n  sessionId?: string;\n  /** Query string matched against each matcher's pattern (tool name, etc.). */\n  matchQuery?: string;\n  /** Stable tool-call key for replaying consumed one-shot contributions. */\n  onceReplayKey?: ToolApprovalReplayKey;\n  /** Storage scope for replay state when it must outlive or branch from the hook session. */\n  onceReplaySessionId?: string;\n  /** Parent AbortSignal — combined with per-hook timeout into the hook signal. */\n  signal?: AbortSignal;\n  /** Default per-hook timeout; overridden by `matcher.timeout` when present. */\n  timeoutMs?: number;\n  /** Optional winston logger for non-internal hook errors. */\n  logger?: Logger;\n}\n\ntype WideMatcher = HookMatcher<HookEvent>;\ntype WideCallback = HookCallback<HookEvent>;\n\ninterface HookOutcome {\n  matcher: WideMatcher;\n  output: HookOutput | null;\n  error: string | null;\n  timedOut: boolean;\n}\n\ninterface AbortRace {\n  promise: Promise<never>;\n  cleanup: () => void;\n}\n\nfunction freshResult(): AggregatedHookResult {\n  return {\n    additionalContexts: [],\n    injectedMessages: [],\n    errors: [],\n  };\n}\n\nfunction combineSignals(\n  parent: AbortSignal | undefined,\n  timeoutMs: number\n): AbortSignal {\n  const timeoutSignal = AbortSignal.timeout(timeoutMs);\n  if (parent === undefined) {\n    return timeoutSignal;\n  }\n  return AbortSignal.any([parent, timeoutSignal]);\n}\n\nfunction isTimeout(err: unknown): boolean {\n  if (err instanceof Error) {\n    return err.name === 'TimeoutError' || err.name === 'AbortError';\n  }\n  return false;\n}\n\nfunction describeError(err: unknown): string {\n  if (err instanceof Error) {\n    return err.message !== '' ? err.message : err.name;\n  }\n  return String(err);\n}\n\nfunction makeAbortPromise(signal: AbortSignal): {\n  promise: Promise<never>;\n  cleanup: () => void;\n} {\n  let onAbort: (() => void) | undefined;\n  const promise = new Promise<never>((_resolve, reject) => {\n    if (signal.aborted) {\n      reject(\n        signal.reason instanceof Error ? signal.reason : new Error('aborted')\n      );\n      return;\n    }\n    onAbort = (): void => {\n      reject(\n        signal.reason instanceof Error ? signal.reason : new Error('aborted')\n      );\n    };\n    signal.addEventListener('abort', onAbort, { once: true });\n  });\n  const cleanup = (): void => {\n    if (onAbort !== undefined) {\n      signal.removeEventListener('abort', onAbort);\n      onAbort = undefined;\n    }\n  };\n  return { promise, cleanup };\n}\n\nasync function runHook(\n  hook: WideCallback,\n  input: HookInput,\n  signal: AbortSignal,\n  abortPromise: Promise<never>,\n  matcher: WideMatcher\n): Promise<HookOutcome> {\n  const hookPromise = Promise.resolve().then(() => hook(input, signal));\n  try {\n    const output = await Promise.race([hookPromise, abortPromise]);\n    return { matcher, output, error: null, timedOut: false };\n  } catch (err) {\n    return {\n      matcher,\n      output: null,\n      error: describeError(err),\n      timedOut: isTimeout(err),\n    };\n  }\n}\n\nasync function runMatcherHooks(\n  matcher: WideMatcher,\n  input: HookInput,\n  signal: AbortSignal\n): Promise<HookOutcome[]> {\n  const abortRace: AbortRace = makeAbortPromise(signal);\n  const tasks = matcher.hooks.map((hook) =>\n    runHook(hook, input, signal, abortRace.promise, matcher)\n  );\n  try {\n    return await Promise.all(tasks);\n  } finally {\n    abortRace.cleanup();\n  }\n}\n\nfunction reportErrors(\n  outcomes: readonly HookOutcome[],\n  event: HookEvent,\n  logger: Logger | undefined\n): void {\n  for (const outcome of outcomes) {\n    if (outcome.error === null) {\n      continue;\n    }\n    if (outcome.matcher.internal === true) {\n      continue;\n    }\n    const label = outcome.timedOut ? 'timed out' : 'threw an error';\n    const message = `Hook for ${event} ${label}: ${outcome.error}`;\n    if (logger !== undefined) {\n      logger.warn(message);\n      continue;\n    }\n    // eslint-disable-next-line no-console\n    console.warn(message);\n  }\n}\n\nfunction applyToolDecision(\n  agg: AggregatedHookResult,\n  decision: ToolDecision,\n  reason: string | undefined\n): void {\n  if (decision === 'deny') {\n    if (agg.decision === 'deny') {\n      return;\n    }\n    agg.decision = 'deny';\n    agg.reason = reason;\n    return;\n  }\n  if (decision === 'ask') {\n    if (agg.decision === 'deny' || agg.decision === 'ask') {\n      return;\n    }\n    agg.decision = 'ask';\n    agg.reason = reason;\n    return;\n  }\n  if (agg.decision === undefined) {\n    agg.decision = 'allow';\n    agg.reason = reason;\n  }\n}\n\nfunction applyStopDecision(\n  agg: AggregatedHookResult,\n  decision: StopDecision,\n  reason: string | undefined\n): void {\n  if (decision === 'block') {\n    if (agg.stopDecision === 'block') {\n      return;\n    }\n    agg.stopDecision = 'block';\n    agg.reason = reason;\n    return;\n  }\n  if (agg.stopDecision === undefined) {\n    agg.stopDecision = 'continue';\n    if (agg.reason === undefined) {\n      agg.reason = reason;\n    }\n  }\n}\n\nfunction applyDecision(agg: AggregatedHookResult, output: HookOutput): void {\n  if (!('decision' in output) || output.decision === undefined) {\n    return;\n  }\n  const decision = output.decision;\n  const reason =\n    'reason' in output && typeof output.reason === 'string'\n      ? output.reason\n      : undefined;\n  if (decision === 'deny' || decision === 'ask' || decision === 'allow') {\n    applyToolDecision(agg, decision, reason);\n    return;\n  }\n  applyStopDecision(agg, decision, reason);\n}\n\nfunction applyContext(agg: AggregatedHookResult, output: HookOutput): void {\n  if (\n    typeof output.additionalContext === 'string' &&\n    output.additionalContext.length > 0\n  ) {\n    agg.additionalContexts.push(output.additionalContext);\n  }\n}\n\nfunction applyInjectedMessages(\n  agg: AggregatedHookResult,\n  output: HookOutput\n): void {\n  if (\n    output.injectedMessages === undefined ||\n    output.injectedMessages.length === 0\n  ) {\n    return;\n  }\n  agg.injectedMessages.push(...output.injectedMessages);\n}\n\nfunction applyStopFlag(agg: AggregatedHookResult, output: HookOutput): void {\n  if (output.preventContinuation !== true) {\n    return;\n  }\n  agg.preventContinuation = true;\n  if (typeof output.stopReason === 'string' && agg.stopReason === undefined) {\n    agg.stopReason = output.stopReason;\n  }\n}\n\nfunction applyUpdatedInput(\n  agg: AggregatedHookResult,\n  output: HookOutput\n): void {\n  if (!('updatedInput' in output) || output.updatedInput === undefined) {\n    return;\n  }\n  agg.updatedInput = output.updatedInput;\n}\n\nfunction applyUpdatedOutput(\n  agg: AggregatedHookResult,\n  output: HookOutput\n): void {\n  if (!('updatedOutput' in output) || output.updatedOutput === undefined) {\n    return;\n  }\n  agg.updatedOutput = output.updatedOutput;\n}\n\nfunction applyAllowedDecisions(\n  agg: AggregatedHookResult,\n  output: HookOutput\n): void {\n  if (\n    !('allowedDecisions' in output) ||\n    output.allowedDecisions === undefined\n  ) {\n    return;\n  }\n  agg.allowedDecisions = output.allowedDecisions;\n}\n\nfunction applyAggregatedResult(\n  target: AggregatedHookResult,\n  source: AggregatedHookResult\n): void {\n  target.additionalContexts.push(...source.additionalContexts);\n  target.injectedMessages.push(...source.injectedMessages);\n  target.errors.push(...source.errors);\n  if (source.decision != null) {\n    applyToolDecision(target, source.decision, source.reason);\n  }\n  if (source.stopDecision != null) {\n    applyStopDecision(target, source.stopDecision, source.reason);\n  }\n  if (source.updatedInput != null) {\n    target.updatedInput = source.updatedInput;\n  }\n  if (source.updatedOutput !== undefined) {\n    target.updatedOutput = source.updatedOutput;\n  }\n  if (source.allowedDecisions != null) {\n    target.allowedDecisions = source.allowedDecisions;\n  }\n  if (source.preventContinuation === true) {\n    target.preventContinuation = true;\n    target.stopReason ??= source.stopReason;\n  }\n}\n\nfunction combineAggregatedResults(\n  first: AggregatedHookResult | undefined,\n  second: AggregatedHookResult\n): AggregatedHookResult {\n  if (first == null) {\n    return second;\n  }\n  const combined = freshResult();\n  applyAggregatedResult(combined, first);\n  applyAggregatedResult(combined, second);\n  return combined;\n}\n\nfunction createPendingApprovalReplay(\n  approvalResult: AggregatedHookResult,\n  pendingApproval: AggregatedHookResult | undefined,\n  onceContribution: AggregatedHookResult\n): AggregatedHookResult {\n  const replay = freshResult();\n  if (pendingApproval != null) {\n    applyAggregatedResult(replay, pendingApproval);\n  }\n  applyAggregatedResult(replay, onceContribution);\n  replay.decision = 'ask';\n  replay.reason = approvalResult.reason;\n  if (approvalResult.allowedDecisions == null) {\n    delete replay.allowedDecisions;\n  } else {\n    replay.allowedDecisions = approvalResult.allowedDecisions;\n  }\n  return replay;\n}\n\nfunction fold(outcomes: readonly HookOutcome[]): {\n  aggregated: AggregatedHookResult;\n  onceReplayContribution?: AggregatedHookResult;\n} {\n  const aggregated = freshResult();\n  const onceContribution = freshResult();\n  let hasOnceContribution = false;\n  for (const outcome of outcomes) {\n    const isOnceMatcher = outcome.matcher.once === true;\n    if (outcome.error !== null) {\n      if (outcome.matcher.internal !== true) {\n        aggregated.errors.push(outcome.error);\n      }\n      continue;\n    }\n    const output = outcome.output;\n    if (output === null) {\n      continue;\n    }\n    /**\n     * Skip fire-and-forget outputs entirely: the agent has already\n     * moved on, so an async hook cannot influence the run. Background\n     * work inside the hook body still runs (we don't cancel it), it\n     * just doesn't fold into the aggregate result.\n     */\n    if (output.async === true) {\n      continue;\n    }\n    const targets = isOnceMatcher\n      ? [aggregated, onceContribution]\n      : [aggregated];\n    if (isOnceMatcher) {\n      hasOnceContribution = true;\n    }\n    for (const target of targets) {\n      applyContext(target, output);\n      applyInjectedMessages(target, output);\n      applyStopFlag(target, output);\n      applyDecision(target, output);\n      applyUpdatedInput(target, output);\n      applyUpdatedOutput(target, output);\n      applyAllowedDecisions(target, output);\n    }\n  }\n  return {\n    aggregated,\n    ...(hasOnceContribution\n      ? { onceReplayContribution: onceContribution }\n      : {}),\n  };\n}\n\n/**\n * Fires every matcher registered against `input.hook_event_name`, folding\n * their results per `deny > ask > allow` precedence and accumulating\n * context/errors.\n *\n * ## Parallelism and determinism\n *\n * All matching hooks fire simultaneously and are awaited via `Promise.all`,\n * which preserves input-array order in its returned results. The fold\n * therefore iterates outcomes in **registration order** — outer loop over\n * matchers as they sit in the registry (global first, then session), inner\n * loop over each matcher's `hooks` array. Last-writer-wins fields\n * (`updatedInput`, `updatedOutput`) are deterministic in that order, even\n * though hooks may complete in arbitrary wall-clock order.\n *\n * Consumers that need a single authoritative rewrite should still scope\n * `updatedInput`/`updatedOutput` to one hook per matcher to avoid subtle\n * precedence bugs when matchers are added in a different order than\n * expected.\n *\n * ## Timeouts and cancellation\n *\n * Each matcher receives **one shared `AbortSignal`** derived from the\n * caller's parent signal combined with `matcher.timeout` (falling back to\n * `opts.timeoutMs`, default {@link DEFAULT_HOOK_TIMEOUT_MS}). Sharing the\n * signal across hooks in a matcher collapses N timer allocations into\n * one, which matters on the PreToolUse hot path where a matcher with\n * several hooks fires on every tool call. Each hook call is raced\n * against the shared signal, so even a hook that ignores the signal is\n * force-unblocked when the timeout fires. Timeout/abort errors are\n * swallowed into the aggregated result's `errors` array (non-fatal by\n * default).\n *\n * ## Internal matchers\n *\n * A matcher with `internal: true` is excluded from both the `errors` array\n * and the logger output. Use it for infrastructure hooks whose failures\n * should not pollute user-visible diagnostics.\n *\n * ## Once semantics — atomic at-most-once\n *\n * A matcher with `once: true` is removed from the registry **before any\n * hook runs**, inside the synchronous prefix of `executeHooks` (between\n * `getMatchers` and the first `await`). Because Node's event loop serialises\n * sync work, two concurrent `executeHooks` calls can never both observe\n * and dispatch the same `once` matcher — whichever call runs its sync\n * prefix first consumes it, and the loser sees an empty bucket.\n *\n * Trade-off: if every hook in a `once` matcher throws, the matcher is\n * still gone. \"Once\" here means \"at most one dispatch, ever\", not \"at\n * most one successful execution with retry on failure\". Hosts that need\n * retry semantics should register a normal matcher and self-unregister\n * via the `unregister` callback returned from `registry.register`.\n */\nexport async function executeHooks(\n  opts: ExecuteHooksOptions\n): Promise<AggregatedHookResult> {\n  const {\n    registry,\n    input,\n    sessionId,\n    matchQuery,\n    onceReplayKey,\n    onceReplaySessionId,\n    signal,\n    timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,\n    logger,\n  } = opts;\n  const event = input.hook_event_name;\n  const replaySessionId = onceReplaySessionId ?? sessionId;\n  const pendingApproval =\n    event === 'PreToolUse' && replaySessionId != null && onceReplayKey != null\n      ? registry.getPendingToolApproval(replaySessionId, onceReplayKey)\n      : undefined;\n  const matchers = registry.getMatchers(event, sessionId);\n  if (matchers.length === 0) {\n    return pendingApproval ?? freshResult();\n  }\n\n  // --- SYNC CRITICAL SECTION: once-matcher removal must complete before any await ---\n  const tasks: Promise<HookOutcome[]>[] = [];\n  for (const matcher of matchers) {\n    if (!matchesQuery(matcher.pattern, matchQuery)) {\n      continue;\n    }\n    if (matcher.once === true) {\n      registry.removeMatcher(event, matcher, sessionId);\n    }\n    if (matcher.hooks.length === 0) {\n      continue;\n    }\n    const perHookTimeout = matcher.timeout ?? timeoutMs;\n    const matcherSignal = combineSignals(signal, perHookTimeout);\n    tasks.push(runMatcherHooks(matcher, input, matcherSignal));\n  }\n  // --- END SYNC CRITICAL SECTION ---\n  if (tasks.length === 0) {\n    return pendingApproval ?? freshResult();\n  }\n\n  const outcomes = (await Promise.all(tasks)).flat();\n  reportErrors(outcomes, event, logger);\n  const { aggregated: liveResult, onceReplayContribution } = fold(outcomes);\n  const aggregated = combineAggregatedResults(pendingApproval, liveResult);\n  if (\n    event === 'PreToolUse' &&\n    aggregated.decision === 'ask' &&\n    onceReplayContribution != null &&\n    replaySessionId != null &&\n    onceReplayKey != null\n  ) {\n    registry.setPendingToolApproval(\n      replaySessionId,\n      onceReplayKey,\n      createPendingApprovalReplay(\n        aggregated,\n        pendingApproval,\n        onceReplayContribution\n      )\n    );\n  } else if (\n    event === 'PreToolUse' &&\n    aggregated.decision !== 'ask' &&\n    pendingApproval != null &&\n    replaySessionId != null &&\n    onceReplayKey != null\n  ) {\n    registry.clearPendingToolApproval(replaySessionId, onceReplayKey);\n  }\n  /**\n   * Centralized `preventContinuation` propagation: when any hook (across\n   * any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,\n   * etc.) returns `preventContinuation: true`, raise a halt signal on\n   * the registry scoped to the run's `sessionId`. `Run.processStream`\n   * polls the signal between stream events using its own id and exits\n   * cleanly, skipping the `Stop` hook (since the run is being halted,\n   * not naturally completing).\n   *\n   * First-write-wins per session inside the registry — a halt already\n   * raised by an earlier hook in the same run is preserved so the\n   * original `reason` / `source` are not clobbered. Hooks fired\n   * without a `sessionId` cannot raise a halt (there's no run for the\n   * loop to poll under), which is fine: every in-tree callsite passes\n   * `sessionId: runId`. Pre-stream callsites in `Run.processStream`\n   * still read `preventContinuation` directly off the result for an\n   * early return because they have not yet entered the stream loop.\n   */\n  if (aggregated.preventContinuation === true && sessionId !== undefined) {\n    registry.haltRun(\n      sessionId,\n      aggregated.stopReason ?? 'preventContinuation',\n      event\n    );\n  }\n  return aggregated;\n}\n"],"mappings":"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"}
+{"version":3,"file":"executeHooks.mjs","names":[],"sources":["../../../src/hooks/executeHooks.ts"],"mappings":"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"}

package/dist/esm/hooks/index.mjs

@@ -5,23 +5,7 @@ import "./createToolPolicyHook.mjs";
 import "./createWorkspacePolicyHook.mjs";
 import "./types.mjs";
 //#region src/hooks/index.ts
-/**
-* Feature probe for hosts: hook outputs support `injectedMessages`
-* (per-message graph-state injection at the `PostToolBatch` boundary).
-* Hosts must gate drain-style hooks on this so a queued message can never
-* be consumed by an SDK version that would silently drop it.
-*/
 const HOOK_INJECTED_MESSAGES_CAPABLE = true;
-/**
-* Feature probe for hosts: this SDK dispatches `PreemptBoundary`, so a
-* cooperative mid-generation seal can drain into the run.
-*
-* Deliberately separate from {@link HOOK_INJECTED_MESSAGES_CAPABLE} — an SDK
-* version can support `injectedMessages` at the tool boundary and know
-* nothing about preemption. A host that probed the wrong flag would arm an
-* interrupt control whose seal request is silently ignored, which reads to
-* the user as a dead button rather than as an unsupported feature.
-*/
 const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;
 //#endregion
 export { HOOK_INJECTED_MESSAGES_CAPABLE, HOOK_PREEMPT_BOUNDARY_CAPABLE };

package/dist/esm/hooks/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/hooks/index.ts"],"sourcesContent":["// src/hooks/index.ts\n//\n// Hook lifecycle system for `@librechat/agents`. Re-exported from\n// `src/index.ts` and consumed by `Run.processStream` (RunStart,\n// UserPromptSubmit, Stop, StopFailure), `ToolNode.dispatchToolEvents`\n// (PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied),\n// `createSummarizeNode` (PreCompact, PostCompact),\n// `SubagentExecutor.execute` (SubagentStart, SubagentStop), and\n// `StandardGraph.createCallModel` (PreemptBoundary).\nexport { HookRegistry } from './HookRegistry';\nexport type { HookHaltSignal } from './HookRegistry';\nexport { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';\n/**\n * Feature probe for hosts: hook outputs support `injectedMessages`\n * (per-message graph-state injection at the `PostToolBatch` boundary).\n * Hosts must gate drain-style hooks on this so a queued message can never\n * be consumed by an SDK version that would silently drop it.\n */\nexport const HOOK_INJECTED_MESSAGES_CAPABLE = true;\n/**\n * Feature probe for hosts: this SDK dispatches `PreemptBoundary`, so a\n * cooperative mid-generation seal can drain into the run.\n *\n * Deliberately separate from {@link HOOK_INJECTED_MESSAGES_CAPABLE} — an SDK\n * version can support `injectedMessages` at the tool boundary and know\n * nothing about preemption. A host that probed the wrong flag would arm an\n * interrupt control whose seal request is silently ignored, which reads to\n * the user as a dead button rather than as an unsupported feature.\n */\nexport const HOOK_PREEMPT_BOUNDARY_CAPABLE = true;\nexport {\n  matchesQuery,\n  hasNestedQuantifier,\n  MAX_PATTERN_LENGTH,\n  MAX_CACHE_SIZE,\n} from './matchers';\nexport { createToolPolicyHook } from './createToolPolicyHook';\nexport type { ToolPolicyMode, ToolPolicyConfig } from './createToolPolicyHook';\nexport { createWorkspacePolicyHook } from './createWorkspacePolicyHook';\nexport type {\n  OutsideAccessPolicy,\n  WorkspacePolicyConfig,\n  PathExtractor,\n} from './createWorkspacePolicyHook';\nexport { HOOK_EVENTS, TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY } from './types';\nexport type {\n  HookEvent,\n  HookInput,\n  HookOutput,\n  HookCallback,\n  HookMatcher,\n  HooksByEvent,\n  HookInputByEvent,\n  HookOutputByEvent,\n  BaseHookInput,\n  BaseHookOutput,\n  ToolDecision,\n  StopDecision,\n  ToolApprovalReplayKey,\n  ToolApprovalReplaySnapshot,\n  AggregatedHookResult,\n  RunStartHookInput,\n  UserPromptSubmitHookInput,\n  PreToolUseHookInput,\n  PostToolUseHookInput,\n  PostToolUseFailureHookInput,\n  PostToolBatchHookInput,\n  PostToolBatchEntry,\n  PreemptBoundaryHookInput,\n  PermissionDeniedHookInput,\n  SubagentStartHookInput,\n  SubagentStopHookInput,\n  StopHookInput,\n  StopFailureHookInput,\n  PreCompactHookInput,\n  PostCompactHookInput,\n  RunStartHookOutput,\n  UserPromptSubmitHookOutput,\n  PreToolUseHookOutput,\n  PostToolUseHookOutput,\n  PostToolUseFailureHookOutput,\n  PostToolBatchHookOutput,\n  PreemptBoundaryHookOutput,\n  PermissionDeniedHookOutput,\n  SubagentStartHookOutput,\n  SubagentStopHookOutput,\n  StopHookOutput,\n  StopFailureHookOutput,\n  PreCompactHookOutput,\n  PostCompactHookOutput,\n} from './types';\nexport type { ExecuteHooksOptions } from './executeHooks';\n"],"mappings":";;;;;;;;;;;;;AAkBA,MAAa,iCAAiC;;;;;;;;;;;AAW9C,MAAa,gCAAgC"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/hooks/index.ts"],"mappings":";;;;;;;AAkBA,MAAa,iCAAiC;AAW9C,MAAa,gCAAgC"}