@librechat/agents 3.1.76 → 3.1.77

package/dist/types/types/hitl.d.ts

@@ -0,0 +1,272 @@
+/**
+ * First-class human-in-the-loop (HITL) types for `@librechat/agents`.
+ * Surfaces the interrupt payload that `ToolNode` raises when a `PreToolUse`
+ * hook returns `decision: 'ask'` and HITL is enabled on the run, plus the
+ * resume-decision shape the host returns to continue or reject the tool.
+ *
+ * Mirrors the LangChain HITL middleware shape (action_requests /
+ * review_configs) so hosts and clients can share rendering/UI semantics
+ * across the langchain ecosystem.
+ */
+/** Per-tool approval request emitted inside an interrupt payload. */
+export interface ToolApprovalRequest {
+    /** Stable id of the tool call (matches LangGraph `ToolCall.id`). */
+    tool_call_id: string;
+    /** Tool name being invoked. */
+    name: string;
+    /**
+     * Arguments the tool is about to be invoked with — already resolved by
+     * any `{{tool<i>turn<n>}}` references and any `updatedInput` returned
+     * by the firing PreToolUse hook.
+     */
+    arguments: Record<string, unknown>;
+    /**
+     * Optional reason the hook supplied for asking (e.g., "destructive
+     * filesystem write"). Hosts can render this verbatim.
+     */
+    description?: string;
+}
+/** Allowed host-side decisions for a `tool_approval` interrupt. */
+export type ToolApprovalDecisionType = 'approve' | 'reject' | 'edit' | 'respond';
+/** Per-action review configuration paired with each action_request. */
+export interface ToolApprovalReviewConfig {
+    /** Tool name (matches the `name` field on the corresponding action_request). */
+    action_name: string;
+    /**
+     * Stable id of the tool call this review_config applies to (matches
+     * the `tool_call_id` of the corresponding action_request). Lets a UI
+     * map review_configs → action_requests directly when a batch
+     * contains the same tool called more than once — by-position
+     * mapping breaks down with duplicates.
+     */
+    tool_call_id: string;
+    /** Decisions the host UI is allowed to surface for this action. */
+    allowed_decisions: ToolApprovalDecisionType[];
+}
+/**
+ * Resume value the host returns through `Run.resume(decisions)` after a
+ * `tool_approval` interrupt. One entry per action_request, in the same
+ * order. Hosts may also return a record keyed by `tool_call_id`; the SDK
+ * handles either shape.
+ *
+ * Variants:
+ *   - `approve`: run the tool with its original (or hook-rewritten) args.
+ *   - `reject`: skip the tool, emit a blocked error `ToolMessage` with
+ *     `reason` surfaced to the model.
+ *   - `edit`: replace the tool's args with `updatedInput` (re-resolves
+ *     any `{{tool<i>turn<n>}}` placeholders) and run the tool.
+ *   - `respond`: skip the tool entirely and emit `responseText` as a
+ *     successful `ToolMessage`. Mirrors LangChain HITL middleware's
+ *     `respond` semantic — the human supplies the result the model sees,
+ *     bypassing tool execution. Useful when the user wants to short-circuit
+ *     a tool call with a hand-written answer (e.g., "don't actually run
+ *     the search, just tell the model 'no relevant results'").
+ *
+ * Note on hook semantics: `respond` does NOT fire the per-tool
+ * `PostToolUse` hook (no real tool execution happened, so the
+ * "post-tool" semantic doesn't apply). It DOES appear in the
+ * `PostToolBatch` entry array with `status: 'success'` and the
+ * user-supplied text as `toolOutput`, so batch-level audit /
+ * convention hooks see the full set of outcomes.
+ */
+export type ToolApprovalDecision = {
+    type: 'approve';
+} | {
+    type: 'reject';
+    reason?: string;
+} | {
+    type: 'edit';
+    updatedInput: Record<string, unknown>;
+} | {
+    type: 'respond';
+    responseText: string;
+};
+/** Map form of resume decisions, keyed by tool call id. */
+export type ToolApprovalDecisionMap = Record<string, ToolApprovalDecision>;
+/**
+ * Categories of human-in-the-loop interrupts the SDK can raise. Hosts
+ * narrow on `HumanInterruptPayload.type` to determine which payload
+ * shape they're handling and which resume value to send back through
+ * `Run.resume()`.
+ *
+ * Exported as a discrete type so downstream consumers (notably
+ * LibreChat's wire types in `librechat-data-provider`) can mirror
+ * the discriminator alongside their own host-side `PendingAction`
+ * record without re-declaring the union themselves. Internal SDK
+ * code narrows directly on the literal strings via the type guards
+ * below; this type alias is primarily an integration-layer contract.
+ */
+export type HumanInterruptType = 'tool_approval' | 'ask_user_question';
+/**
+ * Structured payload the SDK passes to `interrupt()` when one or more
+ * pending tool calls require host approval. All `ask`-decision tool calls
+ * from a single ToolNode batch are bundled into one interrupt so the host
+ * can render and resolve them together.
+ *
+ * Resume value: `ToolApprovalDecision[]` (in `action_requests` order) or
+ * `ToolApprovalDecisionMap` (keyed by `tool_call_id`).
+ */
+export interface ToolApprovalInterruptPayload {
+    type: 'tool_approval';
+    action_requests: ToolApprovalRequest[];
+    review_configs: ToolApprovalReviewConfig[];
+}
+/**
+ * Pre-defined option the user can pick when answering an
+ * `ask_user_question` interrupt. The selected option's `value` becomes
+ * the resume value's `answer` field.
+ */
+export interface AskUserQuestionOption {
+    /** Human-readable label rendered in the host UI. */
+    label: string;
+    /** Value returned via `AskUserQuestionResolution.answer` if picked. */
+    value: string;
+}
+/** Question request emitted inside an `ask_user_question` interrupt. */
+export interface AskUserQuestionRequest {
+    /** The question to ask the human. */
+    question: string;
+    /** Optional context / description rendered alongside the question. */
+    description?: string;
+    /**
+     * Optional pre-defined response options. When present, hosts can render
+     * a picker; the user may still type a free-form answer when the host
+     * UI allows it. Omit to require a free-form answer.
+     */
+    options?: AskUserQuestionOption[];
+}
+/**
+ * Structured payload the SDK passes to `interrupt()` when an agent (or
+ * a custom node) needs to ask the user a clarifying question. Mirrors
+ * Claude Code's `AskUserQuestion` semantic. Resume value:
+ * `AskUserQuestionResolution`.
+ */
+export interface AskUserQuestionInterruptPayload {
+    type: 'ask_user_question';
+    question: AskUserQuestionRequest;
+}
+/**
+ * Discriminated union of every interrupt payload the SDK raises. New
+ * variants can be added without breaking existing handlers as long as
+ * those handlers check `payload.type` before reading variant-specific
+ * fields. Use the `isToolApprovalInterrupt` / `isAskUserQuestionInterrupt`
+ * type guards for ergonomic narrowing.
+ */
+export type HumanInterruptPayload = ToolApprovalInterruptPayload | AskUserQuestionInterruptPayload;
+/** Resume value the host returns for an `ask_user_question` interrupt. */
+export interface AskUserQuestionResolution {
+    /**
+     * The human's answer. Free-form text, or — when `options` were
+     * provided — one of the option `value`s. Hosts may also send any
+     * structured object their custom UI defines; see the host docs for
+     * what your downstream consumer expects.
+     */
+    answer: string;
+}
+/**
+ * Type guard narrowing an arbitrary value to a `ToolApprovalInterruptPayload`.
+ * Accepts `unknown` (not just `HumanInterruptPayload`) because hosts can
+ * raise custom interrupt payloads from custom nodes — `getInterrupt()`
+ * surfaces them as-is, and downstream code must validate the shape at
+ * runtime before reading variant-specific fields.
+ */
+export declare function isToolApprovalInterrupt(payload: unknown): payload is ToolApprovalInterruptPayload;
+/**
+ * Type guard narrowing an arbitrary value to an
+ * `AskUserQuestionInterruptPayload`. Same `unknown`-tolerant contract
+ * as `isToolApprovalInterrupt`.
+ */
+export declare function isAskUserQuestionInterrupt(payload: unknown): payload is AskUserQuestionInterruptPayload;
+/**
+ * Run-level configuration controlling HITL semantics. **HITL is OFF by
+ * default** for now — the SDK ships the interrupt machinery, but the
+ * default stays opt-in until host UIs (notably LibreChat) ship the
+ * approval-rendering affordances needed to surface interrupts to end
+ * users. Without that UI, an interrupt with no resolver looks like a
+ * hung tool-call card. Hosts opt in explicitly with
+ * `{ enabled: true }`. The intent is to flip this default to ON in a
+ * future minor once the consumer ecosystem is ready to render
+ * interrupts end-to-end.
+ *
+ * When enabled (`{ enabled: true }`):
+ *
+ *   - `PreToolUse` hooks returning `decision: 'ask'` raise a real
+ *     LangGraph `interrupt()` instead of being treated as a synchronous
+ *     deny.
+ *   - `Run.create` installs a `MemorySaver` checkpointer fallback on the
+ *     run's compile options if the host did not provide one, since
+ *     LangGraph requires a checkpointer to suspend and resume.
+ *
+ * When disabled (the default — omitted, or `{ enabled: false }`):
+ * `ask` decisions are fail-closed (blocked with an error
+ * `ToolMessage`) and no checkpointer is implicitly attached. This
+ * matches the pre-HITL behavior so existing hosts upgrading the SDK
+ * see no change until they're ready to wire the resume UI.
+ *
+ * ## Scope: event-driven tools only
+ *
+ * The interrupt path is wired into `ToolNode.dispatchToolEvents`, which
+ * runs when the agent uses event-driven tool dispatch (the path
+ * LibreChat and most production hosts take). Tools that execute via
+ * the direct path — i.e. tools listed in `directToolNames` (the
+ * graph-managed handoff and subagent tools) or tools on agents
+ * configured WITHOUT `eventDrivenMode` — bypass the hook system
+ * entirely. `PreToolUse` hooks do not fire for those tools and HITL
+ * approval does not gate them.
+ *
+ * Practical implications:
+ *   - LibreChat-style hosts using event-driven dispatch get the full
+ *     HITL surface across every tool the model calls.
+ *   - Hosts using `AgentInputs.tools` directly without event-driven
+ *     mode get policy enforcement for nothing — the hooks register
+ *     but never fire. Either switch to event-driven mode or accept
+ *     that direct tools are not approval-gated. This is documented
+ *     also on `ToolNodeOptions.hookRegistry`.
+ *   - Mixed direct + event batches (e.g. a handoff tool sharing an
+ *     LLM turn with a regular tool) currently re-execute the direct
+ *     half on resume, since LangGraph rolls back the entire ToolNode
+ *     on `interrupt()` throw. Hosts whose direct tools have side
+ *     effects (subagents that invoke models, handoffs that trigger
+ *     downstream work) should avoid mixing those tools into the same
+ *     batch as approval-gated event tools.
+ *
+ * ## Note on idempotency
+ *
+ * When an interrupt fires, LangGraph re-runs the interrupted node
+ * from the start on resume, which fires `PreToolUse` hooks again.
+ * Hooks that produce side effects (logging, external calls) will see
+ * two invocations per paused turn.
+ */
+export interface HumanInTheLoopConfig {
+    /**
+     * Master switch. Defaults to `false` — omit the field (or pass
+     * `false`) to keep HITL off, or set `true` to opt in once the host
+     * UI is ready to render and resolve `tool_approval` interrupts.
+     */
+    enabled?: boolean;
+}
+/**
+ * Snapshot of an in-flight interrupt surfaced from `Run.processStream`
+ * via `run.getInterrupt()`. Hosts persist this alongside their job
+ * record so they can later call `Run.resume(decisions)` against a Run
+ * compiled with the same `thread_id` / checkpointer.
+ *
+ * The `payload` type defaults to `HumanInterruptPayload` (the SDK's
+ * built-in `tool_approval` / `ask_user_question` discriminated union)
+ * for ergonomic narrowing in the common case. Hosts that raise custom
+ * interrupt payloads from custom graph nodes can pass the type
+ * parameter (`run.getInterrupt<MyCustom>()` or
+ * `RunInterruptResult<MyCustom>`) — the SDK does not validate the
+ * runtime shape, it just transports whatever the node passed to
+ * `interrupt()`. Use the `isToolApprovalInterrupt` /
+ * `isAskUserQuestionInterrupt` guards (which accept `unknown`) when
+ * the source of the interrupt isn't statically known.
+ */
+export interface RunInterruptResult<TPayload = HumanInterruptPayload> {
+    /** Stable id of the LangGraph interrupt (from `Interrupt.id`). */
+    interruptId: string;
+    /** `thread_id` the run was bound to — required to resume. */
+    threadId?: string;
+    /** Structured payload describing what needs human input. */
+    payload: TPayload;
+}

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

@@ -1,4 +1,5 @@
 export * from './graph';
+export * from './hitl';
 export * from './llm';
 export * from './messages';
 export * from './run';

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

@@ -8,6 +8,7 @@ import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
 import type { ToolSessionMap, ToolOutputReferencesConfig } from '@/types/tools';
+import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
 export type BaseGraphConfig = {
@@ -144,6 +145,38 @@ export type RunConfig = {
      * placeholders. Disabled by default so existing runs are unaffected.
      */
     toolOutputReferences?: ToolOutputReferencesConfig;
+    /**
+     * First-class human-in-the-loop (HITL) flow for this run.
+     *
+     * **HITL is OFF by default.** Omitting this field — or passing
+     * `{ enabled: false }` — keeps the pre-HITL fail-closed semantics
+     * where `ask` decisions collapse into a synchronous deny. Hosts opt
+     * in explicitly with `{ enabled: true }` once their UI can render
+     * and resolve `tool_approval` interrupts (otherwise the run just
+     * pauses with no resolver, which surfaces to end users as a hung
+     * tool-call card).
+     *
+     * Plan of record: the default flips back to ON in a future minor
+     * once the consumer ecosystem (notably LibreChat) ships HITL UI
+     * end-to-end. See `HumanInTheLoopConfig` JSDoc.
+     *
+     * When enabled (`{ enabled: true }`):
+     *   - `PreToolUse` hooks returning `decision: 'ask'` raise a real
+     *     LangGraph `interrupt()` instead of being treated as a synchronous
+     *     deny. The graph pauses and the run exits cleanly.
+     *   - If `graphConfig.compileOptions.checkpointer` is missing, the SDK
+     *     installs an in-memory `MemorySaver` as a fallback so scripts and
+     *     tests can resume without external infrastructure. Production
+     *     hosts should always provide a durable checkpointer.
+     *   - Hosts inspect the pending interrupt via `run.getInterrupt()` and
+     *     continue with `Run.resume(decisions)` against a Run rebuilt with
+     *     the same `thread_id` and checkpointer.
+     *
+     * When disabled (the default): `ask` decisions remain fail-closed
+     * (blocked with an error `ToolMessage`) and no checkpointer is
+     * implicitly attached.
+     */
+    humanInTheLoop?: HumanInTheLoopConfig;
 };
 export type ProvidedCallbacks = (BaseCallbackHandler | CallbackHandlerMethods)[] | undefined;
 export type TokenCounter = (message: BaseMessage) => number;

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

@@ -4,6 +4,7 @@ import type { ToolCall } from '@langchain/core/messages/tool';
 import type { HookRegistry } from '@/hooks';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import type { MessageContentComplex, ToolErrorData } from './stream';
+import type { HumanInTheLoopConfig } from './hitl';
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
     name: string;
@@ -46,6 +47,24 @@ export type ToolNodeOptions = {
      * routed through `directToolNames` bypass hook dispatch entirely.
      */
     hookRegistry?: HookRegistry;
+    /**
+     * Run-scoped HITL config. **HITL is OFF by default** — omitting this
+     * field (or passing `{ enabled: false }`) keeps the pre-HITL
+     * fail-closed behavior where a `PreToolUse` `ask` decision collapses
+     * into a blocked `ToolMessage`. Hosts opt in with
+     * `{ enabled: true }` once their UI can render and resolve a
+     * `tool_approval` interrupt; that engages the interrupt path where
+     * `ask` raises a real LangGraph `interrupt()` carrying a
+     * `HumanInterruptPayload` and the host resumes with
+     * `Run.resume(decisions)`.
+     *
+     * Mirrors `RunConfig.humanInTheLoop` (which is the canonical place
+     * to set this); the Graph threads it down to every ToolNode it
+     * compiles. Same caveat: the interrupt path is only wired into the
+     * event-driven dispatch (`dispatchToolEvents`), not into
+     * `directToolNames` execution — direct tools bypass HITL entirely.
+     */
+    humanInTheLoop?: HumanInTheLoopConfig;
     /** Max context tokens for the agent — used to compute tool result truncation limits. */
     maxContextTokens?: number;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.76",
+  "version": "3.1.77",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/graphs/Graph.ts

@@ -129,6 +129,13 @@ export abstract class Graph<
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
   hookRegistry: HookRegistry | undefined;
+  /**
+   * Run-scoped HITL configuration. When `humanInTheLoop?.enabled` is
+   * `true`, `ToolNode` raises a real `interrupt()` for `PreToolUse`
+   * `ask` decisions instead of treating them as a synchronous deny.
+   * Threaded from `RunConfig.humanInTheLoop`.
+   */
+  humanInTheLoop: t.HumanInTheLoopConfig | undefined;
   /**
    * Run-scoped config for the tool output reference registry. Threaded
    * from `RunConfig.toolOutputReferences` down into every ToolNode this
@@ -167,6 +174,7 @@ export abstract class Graph<
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
     this.hookRegistry = undefined;
+    this.humanInTheLoop = undefined;
     this.toolOutputReferences = undefined;
     /**
      * ToolNodes compiled from this graph captured the registry
@@ -579,6 +587,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
         hookRegistry: this.hookRegistry,
+        humanInTheLoop: this.humanInTheLoop,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,

package/src/hitl/askUserQuestion.ts

@@ -0,0 +1,72 @@
+/**
+ * Typed convenience wrapper around LangGraph's `interrupt()` for the
+ * `ask_user_question` interrupt category. Lets a custom graph node
+ * (or a tool implementation) suspend execution to collect a free-form
+ * answer from the human, without the host having to assemble the
+ * interrupt payload by hand. The companion to `Run.resume(answer)` on
+ * the host side.
+ *
+ * AsyncLocalStorage anchoring: this helper does NOT call
+ * `runWithConfig` itself — it expects to be invoked from inside a
+ * LangGraph node where the framework has already established the
+ * runnable config. ToolNode is the one place in this codebase that
+ * needs the manual `runWithConfig` shim, because its
+ * `RunnableCallable.trace = false` skips the upstream tracing path
+ * that normally sets up the AsyncLocalStorage frame; ordinary user
+ * nodes (RunnableLambda, addNode callbacks) do not have that
+ * constraint.
+ */
+
+import { interrupt } from '@langchain/langgraph';
+import type {
+  AskUserQuestionRequest,
+  AskUserQuestionResolution,
+  AskUserQuestionInterruptPayload,
+} from '@/types/hitl';
+
+/**
+ * Suspend the current graph node to ask the human a question. Returns
+ * the host-supplied resolution after `Run.resume(resolution)` is
+ * called against a Run rebuilt with the same `thread_id` and
+ * checkpointer.
+ *
+ * On the FIRST call (no resume value available), `interrupt()` throws
+ * a `GraphInterrupt` that LangGraph catches; this function does not
+ * return — execution unwinds, the SDK persists the checkpoint, and
+ * the run completes with `run.getInterrupt()` returning a
+ * `RunInterruptResult` whose `payload` is an
+ * `AskUserQuestionInterruptPayload`.
+ *
+ * On RESUME, LangGraph re-runs the node from the start and this call
+ * returns the host's `AskUserQuestionResolution` directly.
+ *
+ * Hosts that prefer the raw `interrupt()` (e.g., to attach extra
+ * metadata) can construct an `AskUserQuestionInterruptPayload` and
+ * call `interrupt()` themselves — this helper is purely convenience.
+ *
+ * @example
+ * ```ts
+ * const builder = new StateGraph(MessagesAnnotation)
+ *   .addNode('clarifier', () => {
+ *     const { answer } = askUserQuestion({
+ *       question: 'Which environment should I deploy to?',
+ *       options: [
+ *         { label: 'Staging', value: 'staging' },
+ *         { label: 'Production', value: 'production' },
+ *       ],
+ *     });
+ *     return { messages: [new HumanMessage(`Use ${answer}`)] };
+ *   });
+ * ```
+ */
+export function askUserQuestion(
+  question: AskUserQuestionRequest
+): AskUserQuestionResolution {
+  const payload: AskUserQuestionInterruptPayload = {
+    type: 'ask_user_question',
+    question,
+  };
+  return interrupt<AskUserQuestionInterruptPayload, AskUserQuestionResolution>(
+    payload
+  );
+}

package/src/hitl/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Human-in-the-loop helpers. Type definitions live in `@/types/hitl`
+ * and re-export from the top-level types barrel; runtime helpers (like
+ * `askUserQuestion()`) live here.
+ */
+
+export { askUserQuestion } from './askUserQuestion';

package/src/hooks/HookRegistry.ts

@@ -13,6 +13,20 @@ import type { HookEvent, HookMatcher } from './types';
  */
 type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 
+/**
+ * Snapshot of a halt request raised by a hook returning
+ * `preventContinuation: true`. The SDK's run loop polls for this between
+ * stream events and exits cleanly when set, skipping the `Stop` hook
+ * (the run is being halted, not naturally completing). One per registry
+ * instance — the first hook to halt wins; subsequent halts are ignored
+ * so the original reason isn't clobbered.
+ */
+export interface HookHaltSignal {
+  reason: string;
+  /** Event of the hook that triggered the halt (for diagnostics). */
+  source: HookEvent;
+}
+
 /**
  * Run-scoped storage for hook matchers with an additional layer for
  * session-scoped matchers that should be cleaned up between sessions.
@@ -34,6 +48,18 @@ type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
 export class HookRegistry {
   private readonly global: MatcherBucket = {};
   private readonly sessions: Map<string, MatcherBucket> = new Map();
+  /**
+   * Per-session halt signals. Scoped by `sessionId` (= the run id the
+   * hook fired under) so a host that shares one registry across
+   * concurrent runs cannot leak `preventContinuation` from one run
+   * into another. Without scoping, a halt raised by run A's hook
+   * would trip run B's stream-loop poll on the next iteration —
+   * silently terminating an unrelated run.
+   *
+   * Map storage mirrors the reasoning above for session matchers:
+   * O(1) insertion in hot paths, no spread-on-write.
+   */
+  private readonly haltSignals: Map<string, HookHaltSignal> = new Map();
 
   /**
    * Register a matcher for the lifetime of this registry (= one Run).
@@ -125,6 +151,51 @@ export class HookRegistry {
     this.sessions.delete(sessionId);
   }
 
+  /**
+   * Raise a halt signal scoped to `sessionId` (= the run id the hook
+   * fired under). The SDK's run loop polls for this between stream
+   * events with the run's own id. First-write-wins per session: a
+   * halt already raised by an earlier hook in the same run is
+   * preserved so the original `reason` / `source` aren't overwritten.
+   *
+   * Per-session scoping is critical when hosts share one registry
+   * across concurrent runs (e.g. a global policy registered once and
+   * reused). Without it, a `preventContinuation` from run A would
+   * trip run B's stream-loop poll on the next iteration and silently
+   * terminate an unrelated run.
+   *
+   * Called by the SDK after `executeHooks` returns an aggregate with
+   * `preventContinuation: true`. Hosts can also call it directly from
+   * inside a hook callback if they want to halt without going through
+   * the aggregated return value, but `preventContinuation` is the
+   * canonical path.
+   */
+  haltRun(sessionId: string, reason: string, source: HookEvent): void {
+    if (this.haltSignals.has(sessionId)) {
+      return;
+    }
+    this.haltSignals.set(sessionId, { reason, source });
+  }
+
+  /**
+   * Returns the halt signal raised by hooks running under `sessionId`,
+   * or `undefined` if no hook in that run has halted. Polled by
+   * `Run.processStream` between stream events using the run's own id.
+   */
+  getHaltSignal(sessionId: string): HookHaltSignal | undefined {
+    return this.haltSignals.get(sessionId);
+  }
+
+  /**
+   * Clears the halt signal for `sessionId`. Called by
+   * `Run.processStream` in its `finally` block so a subsequent
+   * invocation of the same Run (e.g. resume) starts with a fresh
+   * halt state. No-op when no signal exists for that session.
+   */
+  clearHaltSignal(sessionId: string): void {
+    this.haltSignals.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) {