@yanlinglabs/winter-agent-runtime 0.0.27 → 0.0.28

package/README.md

@@ -49,6 +49,10 @@ each session needs its own JavaScript realm: run one session per Bun `Worker`.
   and returns a `SpawnedRuntimeProcess`. Hand it to `query()` through `Options.spawnClaudeCodeProcess`.
   The frames on the wire are exactly the ones the spawned binary writes. This module does not load
   the engine, so it is safe to import on a host's main thread.
+  A session's shell commands, stdio MCP servers and hooks run as their own process groups. A Worker
+  that is `terminate()`d or crashes never runs the teardown that kills them, so once `exited` settles,
+  SIGKILL every group the returned process still lists in `processGroups()`
+  (`process.kill(-pgid, "SIGKILL")`). After a clean exit the list is empty.
 - `@yanlinglabs/winter-agent-runtime/embedded-worker` — the Worker entry. A compiled
   (`bun build --compile`) host passes its own one-line worker file as an extra entrypoint and
   constructs the Worker from that file's plain relative path.

package/dist/context/attachments.d.ts

@@ -30,6 +30,29 @@ export interface DateChangeAttachment extends AttachmentPayload {
     type: "date_change";
     newDate: string;
 }
+/**
+ * WS-24 (I-1 fix round): Winter's own, no claude equivalent. Plan mode moved OUT of the system
+ * prompt's dynamic half and into a persisted attachment at the tail of the conversation -- the block
+ * used to sit ahead of the conversation history, so a toggle shifted every downstream token and
+ * busted the whole cached prefix on the vendor's own prompt-cache accounting (WS-24 follow-up 8's
+ * confirmed live finding, on every provider: OpenAI's byte-exact prefix match and Anthropic's `org`
+ * dynamic system block alike). As an attachment it costs exactly ONE cache miss on the turn the mode
+ * actually changes, and the history stays a stable, cacheable prefix while the mode holds steady in
+ * either direction.
+ */
+export interface PlanModeAttachment extends AttachmentPayload {
+    type: "plan_mode";
+    state: "entered" | "exited";
+    /**
+     * Present only for `state: "entered"`. Captured ONCE at production time
+     * (`SystemPromptAssembler.planModeInput`, the settings/brand precedence `assemble()` used to apply
+     * inline) rather than re-derived at render time -- a renderer takes only the payload, never live
+     * settings or the session's brand.
+     */
+    plansDirectory?: string;
+    plansDirectoryFallback?: string;
+    hostPlanBody?: string;
+}
 export declare const AGENT_LISTING_INITIAL_HEADER = "Available agent types for the Agent tool:";
 export declare const AGENT_LISTING_ADDED_HEADER = "New agent types are now available for the Agent tool:";
 export declare const AGENT_LISTING_REMOVED_HEADER = "The following agent types are no longer available:";
@@ -39,6 +62,13 @@ export declare const AMBIENT_CONTEXT_SENTENCE = "This is ambient context \u2014
 export declare const AGENT_CONCURRENCY_SENTENCE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
 export declare const SKILL_LISTING_HEADER = "The following skills are available for use with the Skill tool:";
 export declare function dateChangeText(newDate: string): string;
+/**
+ * WS-24 (I-1): kept deliberately MINIMAL. The `ExitPlanMode` tool's own result already announces the
+ * mode change in the model-visible function_call_output ("Plan approved; permission mode restored to
+ * ..."), so this attachment's job is only to cover the OTHER way the mode can leave plan -- a host or
+ * UI action (`set_permission_mode`) with no tool call at all -- without repeating that sentence.
+ */
+export declare const PLAN_MODE_EXITED_TEXT = "Plan mode has ended. The write restriction is lifted.";
 /** claude's attachment wrapper (`Qa`). Nothing is added around it and nothing after it. */
 export declare function wrapSystemReminder(body: string): string;
 /** A renderer returns the UNWRAPPED body, or `undefined` when the attachment has nothing to say. */
@@ -91,6 +121,13 @@ export declare function attachmentsIn(messages: readonly ProviderMessage[]): Att
 export declare function announcedAgentTypes(messages: readonly ProviderMessage[]): Set<string>;
 /** claude's `alr` fold: whether a `date_change` for `date` is already in the history. */
 export declare function dateChangeAnnounced(messages: readonly ProviderMessage[], date: string): boolean;
+/**
+ * WS-24 (I-1): the last `plan_mode` attachment's state, or `"exited"` when none exists yet -- a
+ * session that never entered plan mode is, correctly, not IN it. This is what the engine's own
+ * producer compares against the LIVE `policyStateStore` mode to decide whether anything changed
+ * since the history's own last word on it -- emitting only on a genuine difference, never every turn.
+ */
+export declare function lastPlanModeState(messages: readonly ProviderMessage[]): "entered" | "exited";
 /**
  * claude's `vlr` resume seed for the skill listing: the names every persisted `skill_listing` sent,
  * and whether a legacy entry without `names` asks the next listing to be suppressed (claude's

package/dist/context/seam.d.ts

@@ -1,5 +1,6 @@
 import type { RuntimeConfig } from "@yanlinglabs/winter-agent-sdk";
 import type { ContextEntry } from "./request-layout.js";
+import type { PlanModeInput } from "./plan-mode.js";
 export type SkillListing = Array<{
     name: string;
     description: string;
@@ -43,7 +44,12 @@ export interface SystemPromptInput {
     modelDisplayName?: string;
     memoryDir?: string;
     outputStyle?: OutputStyle;
-    planMode: boolean;
+    /**
+     * WS-24 (I-1 fix round): the host's replacement for the plan-mode body's middle section
+     * (`planModeInstructions` on the wire, `plan-mode.ts`'s own header on the two-name mapping). Still
+     * carried on the snapshot -- `planModeInput()` reads it -- even though the block itself no longer
+     * renders inline here; it moved to a persisted attachment (`context/attachments.ts`'s `plan_mode`).
+     */
     hostPlanBody?: string;
     /**
      * DISCLOSED WINTER FIELD, not in the brief's list: the child persona a subagent runs with
@@ -118,6 +124,18 @@ export interface SystemPromptAssembler {
      * per session context rather than once per turn. Absent = no index-0 message.
      */
     userContext?(input: SystemPromptInput): ContextEntry[];
+    /**
+     * WS-24 (I-1 fix round): the plan-mode block's render inputs -- `plansDirectory` (the session's own
+     * project dot-dir default, config then settings then the brand's), `plansDirectoryFallback` (the
+     * same brand default, for a refused `plansDirectory`) and `hostPlanBody` passed through. `assemble()`
+     * used to derive these inline and render the block into the dynamic system half on every request
+     * while the mode held; the block moved to a persisted attachment (`context/attachments.ts`'s
+     * `plan_mode`) so a toggle costs one cache miss instead of shifting the whole downstream prefix on
+     * every request. The ENGINE calls this ONCE, when producing the attachment on a genuine mode change
+     * -- never per render -- so the settings/brand precedence stays derived in this one place. Absent =
+     * the engine falls back to the SDK's own `DEFAULT_PLANS_DIRECTORY` with no `hostPlanBody`.
+     */
+    planModeInput?(input: SystemPromptInput): PlanModeInput;
 }
 /**
  * The spine's own test double. NOT a minimal prompt and never a stand-in for one (R5-16): it echoes

package/dist/embedded-host.d.ts

@@ -39,6 +39,20 @@ export interface EmbeddedWorkerProcess extends SpawnedRuntimeProcess {
     terminate(): void;
     /** `running` → (`kill()`) `stopping` → `closed`. `closed` means `exited` has settled. */
     readonly state: "running" | "stopping" | "closed";
+    /**
+     * WS-24: the process groups the session reported live and has not reported ended
+     * (`EmbeddedProcessGroupMessage`), oldest first. Still readable once `exited` has settled -- which is
+     * when it matters: a Worker that closed WITHOUT its own teardown (`terminate()` of a spinning Worker,
+     * a crash) leaves here exactly the groups it orphaned, and nothing but the host can reap them (each
+     * was `setsid`-detached). A healthy close leaves it empty, because every removal is posted before
+     * `exit`.
+     *
+     * The host OWNS the reaping, deliberately: SIGKILL `-pgid` for each entry once `exited` settles
+     * (Winter's daemon does, in `runtime-sdk/embedded.ts`). Residual: a group that ended in the instant
+     * between its last message and the kill leaves a pgid the OS could in principle hand to a new group
+     * leader -- pids are not reused while any member of the group lives, so only that race window remains.
+     */
+    processGroups(): readonly number[];
 }
 /**
  * Construct the Worker, send `start`, and return the process handle. Never throws for a Worker that

package/dist/embedded-host.js

@@ -28,6 +28,7 @@ function spawnEmbeddedWorker(opts) {
   let stdinEnded = false;
   let graceTimer;
   let closeTimer;
+  const processGroups = new Set;
   let settleExited;
   const exited = new Promise((resolve) => {
     settleExited = resolve;
@@ -77,6 +78,14 @@ function spawnEmbeddedWorker(opts) {
       case "stderr":
         stderr.write(message.chunk);
         return;
+      case "process-group":
+        if (!Number.isInteger(message.pgid) || message.pgid <= 1 || message.pgid === process.pid)
+          return;
+        if (message.op === "add")
+          processGroups.add(message.pgid);
+        else
+          processGroups.delete(message.pgid);
+        return;
       case "exit":
         exitCode = message.code;
         closeTimer = setTimeout(terminate, CLOSE_AFTER_EXIT_MS);
@@ -146,7 +155,8 @@ function spawnEmbeddedWorker(opts) {
     pid: null,
     get state() {
       return state;
-    }
+    },
+    processGroups: () => [...processGroups]
   };
 }
 export {

package/dist/embedded-protocol.d.ts

@@ -31,10 +31,26 @@ export type EmbeddedWorkerMessage = {
 } | {
     kind: "stderr";
     chunk: string;
-} | {
+} | EmbeddedProcessGroupMessage | {
     kind: "exit";
     code: number;
 };
+/**
+ * WS-24: a process group the session's realm started (`add`) or saw end (`remove`) -- Bash/Monitor
+ * commands, stdio MCP servers, command hooks, the workflow worker (`process-groups.ts`). The host keeps
+ * the live set so that a Worker which dies WITHOUT running its own kill doors (a `terminate()` of a
+ * spinning Worker, a crash) does not orphan them: `setsid` detached every one from the host process,
+ * so nothing else will ever reap them. Posted in order with `stdout`, so by the time a healthy Worker's
+ * `exit` arrives every group its teardown ended has already been removed.
+ *
+ * ADDITIVE: a host that predates it ignores an unknown `kind` (`embedded-host.ts`'s switch has no
+ * default arm), and a runtime that predates it simply never posts one.
+ */
+export interface EmbeddedProcessGroupMessage {
+    kind: "process-group";
+    op: "add" | "remove";
+    pgid: number;
+}
 /**
  * The request ids of the two control frames an ABORT synthesizes (`embedded.ts`). Fixed strings, not
  * UUIDs, so the output filter can recognise their acknowledgements without state: no host ever

package/dist/embedded-worker.js

@@ -1,15 +1,25 @@
-import"./index-9qgkpv56.js";
+import"./index-mftq279y.js";
+import {
+  liveProcessGroups,
+  onProcessGroupChange
+} from "./index-8jgwp1px.js";
 import"./index-bef62z3r.js";
-import"./index-584yahed.js";
+import"./index-mqj4x0fn.js";
 import {
   runEmbeddedSession2
-} from "./index-rkhh0457.js";
+} from "./index-d255xsgm.js";
 import {
   Queue
 } from "./index-97t2rmtf.js";
 
 // src/embedded-worker.ts
 import { isMainThread } from "node:worker_threads";
+var EXIT_AFTER_GROUPS_SETTLE_MS = 250;
+async function groupsSettled() {
+  const deadline = Date.now() + EXIT_AFTER_GROUPS_SETTLE_MS;
+  while (liveProcessGroups().length > 0 && Date.now() < deadline)
+    await new Promise((resolve) => setTimeout(resolve, 10));
+}
 function post(message) {
   postMessage(message);
 }
@@ -24,8 +34,14 @@ function fenceProcessWideState() {
     return readUmask();
   };
 }
+function mirrorProcessGroups() {
+  for (const { pgid } of liveProcessGroups())
+    post({ kind: "process-group", op: "add", pgid });
+  onProcessGroupChange((change) => post({ kind: "process-group", op: change.op, pgid: change.pgid }));
+}
 function installEmbeddedWorker() {
   fenceProcessWideState();
+  mirrorProcessGroups();
   const input = new Queue;
   const abort = new AbortController;
   let started = false;
@@ -46,6 +62,7 @@ function installEmbeddedWorker() {
 ` });
       code = 1;
     }
+    await groupsSettled();
     post({ kind: "exit", code });
     process.exit(code);
   };

package/dist/embedded.js

@@ -1,9 +1,10 @@
 import {
   runEmbeddedSession2
-} from "./index-rkhh0457.js";
-import"./index-584yahed.js";
-import"./index-9qgkpv56.js";
+} from "./index-d255xsgm.js";
+import"./index-mqj4x0fn.js";
+import"./index-mftq279y.js";
 import"./index-bef62z3r.js";
+import"./index-8jgwp1px.js";
 export {
   runEmbeddedSession2 as runEmbeddedSession
 };

package/dist/engine.d.ts

@@ -64,6 +64,13 @@ export type ContentBlock = {
         data: string;
     };
 };
+/**
+ * WS-24: the text a FORK's ToolSearch result carries for loaded tools its frozen `tools` does not declare
+ * (the engine's `forkLoadedDefinitionsText`, on a row with `undeclaredToolCalls` evidence). Exported so
+ * the live probe that gathers that evidence (`scripts/probe-fork-undeclared-tool.ts`) sends these exact
+ * bytes rather than a lookalike.
+ */
+export declare function undeclaredToolDefinitionsText(definitions: readonly LoadedToolDefinition[]): string;
 /** WS-23 (midconv, review I-2): one loaded tool's definition as it stood at load time (see `tool_result.loadedToolDefinitions`). */
 export interface LoadedToolDefinition {
     name: string;
@@ -184,6 +191,8 @@ export interface ModelWireFeatures {
     additionalToolsItem?: true;
     /** WS-23 (midconv): OpenAI's `tool_choice: allowed_tools` restricts the callable set without editing `tools` (`allowedToolsChoice`). */
     allowedToolsChoice?: true;
+    /** WS-24: the endpoint takes a call (and its history) to a tool absent from `tools` (`undeclaredToolCalls`, live-probe-proven) -- what lets a fork run a self-loaded tool its frozen `tools` lacks. */
+    undeclaredToolCalls?: true;
 }
 /** What `EngineOptions.describeModel` knows about a model: its display name, its verified effort vocabulary, and its wire features. */
 export interface ModelDescription {
@@ -458,6 +467,11 @@ export interface ProviderUsage {
     };
     /** WS-23: replayed thinking blocks the provider dropped (Anthropic's `input_transformations`). */
     thinkingBlocksDropped?: number;
+    /**
+     * WS-24 (follow-up 1, lane `providers`): the Responses family's reasoning-token count -- a SUBSET
+     * of `outputTokens`. Anthropic reports no separate count and leaves this absent.
+     */
+    reasoningTokens?: number;
 }
 export type ProviderTurn = {
     kind: "text";
@@ -809,6 +823,15 @@ export interface EngineOptions {
      * Round 20 carried the parent's board only, and only to a child with object-form servers.
      */
     inheritedMcpServerNames?: () => readonly string[];
+    /**
+     * WS-24: a SUBAGENT's own MCP servers connected under a name other than the one its definition
+     * declared (subagents/child-engine.ts's `allocateChildScopedServers` renames one that collides),
+     * as `{ actual: declared }`. Set by child-engine.ts only. A call to `mcp__<actual>__<tool>` is then
+     * ALSO governed by every permission rule and hook matcher written against `mcp__<declared>__<tool>`
+     * (strictest-of, like a tool alias), so a rename never lets a call escape a rule or hook that named
+     * the server as the author declared it.
+     */
+    mcpServerRenames?: Readonly<Record<string, string>>;
     mcpControlSeam?: McpControlSeam;
     contextAccountant?: ContextAccountant;
     onChildRosterReady?: (getChildren: () => readonly ChildHandle[]) => void;

package/dist/hooks/additional-context.d.ts

@@ -1,6 +1,8 @@
 import { type AttachmentPayload } from "../context/attachments.js";
 export declare const HOOK_ADDITIONAL_CONTEXT_ATTACHMENT = "hook_additional_context";
 export declare const HOOK_FEEDBACK_ATTACHMENT = "hook_feedback";
+/** WS-24: what a BACKGROUND (async) hook said once it finished -- hooks/async-hooks.ts. */
+export declare const ASYNC_HOOK_RESPONSE_ATTACHMENT = "async_hook_response";
 export interface HookAdditionalContextAttachment extends AttachmentPayload {
     type: typeof HOOK_ADDITIONAL_CONTEXT_ATTACHMENT;
     hookName: string;
@@ -12,6 +14,24 @@ export interface HookFeedbackAttachment extends AttachmentPayload {
     hookName: string;
     content: string[];
 }
+export interface AsyncHookResponseAttachment extends AttachmentPayload {
+    type: typeof ASYNC_HOOK_RESPONSE_ATTACHMENT;
+    hookName: string;
+    systemMessage?: string;
+    content: string[];
+    toolUseID?: string;
+    /** Set on the notice that `dropped` finished outputs never reached the model (the pending cap). */
+    dropped?: number;
+}
+/** WS-24: the attachment for one finished async hook -- `undefined` when it said nothing. */
+export declare function asyncHookResponseAttachment(output: {
+    hookName: string;
+    systemMessage?: string;
+    additionalContext?: string;
+    toolUseID?: string;
+}): AsyncHookResponseAttachment | undefined;
+/** WS-24: the notice that `dropped` finished async-hook outputs were discarded for the pending cap. */
+export declare function asyncHookDroppedAttachment(dropped: number): AsyncHookResponseAttachment | undefined;
 /** The `additionalContext` strings a composite accumulated, in evaluation order (non-string or empty entries dropped). */
 export declare function contextStrings(extraContext: ReadonlyArray<{
     context: unknown;

package/dist/hooks/async-hooks.d.ts

@@ -0,0 +1,64 @@
+import type { HookEvent } from "@yanlinglabs/winter-agent-sdk";
+/** Ten minutes: background work (a test run after an edit, a lint of the tree) is minutes, not seconds -- the gating hooks' 60 s would cut it off. */
+export declare const DEFAULT_ASYNC_HOOK_TIMEOUT_MS = 600000;
+/**
+ * Concurrent background hooks per ENGINE. A PostToolUse hook on every call of a 50-call burst must not
+ * become 50 processes. Per engine, not per session: a subagent's engine builds its own command invoker
+ * and so its own queue (killed at that engine's teardown), so a session running N subagents at once can
+ * hold up to (N + 1) x this many -- each still bounded, and each gone with its engine.
+ */
+export declare const MAX_RUNNING_ASYNC_HOOKS = 16;
+/** Finished outputs waiting for the next safe point. At `MAX_HOOK_TEXT_CHARS` each, one delivery stays far below the per-message cap. */
+export declare const MAX_PENDING_ASYNC_HOOK_OUTPUTS = 16;
+/** One finished async hook's model-facing output. */
+export interface AsyncHookOutput {
+    /** `<Event>` or `<Event>:<tool name>` -- the same naming the synchronous context attachments use. */
+    hookName: string;
+    systemMessage?: string;
+    additionalContext?: string;
+    toolUseID?: string;
+}
+/** What `drain()` returns: finished outputs, oldest first, plus how many were dropped for the pending cap. */
+export interface AsyncHookDrain {
+    outputs: AsyncHookOutput[];
+    dropped: number;
+}
+/** A backgrounded invocation as the command invoker hands it over. */
+export interface AsyncHookJob {
+    event: HookEvent;
+    hookName: string;
+    toolUseID?: string;
+    /** Settles when the process has exited, with what `finishedOutput` needs. Never rejects. */
+    finished: Promise<FinishedHookProcess>;
+    /** SIGKILL the job's whole process group. Idempotent. */
+    kill: () => void;
+    timeoutMs: number;
+}
+/** A background process's end state. */
+export interface FinishedHookProcess {
+    exitCode: number | null;
+    stdout: string;
+}
+export interface AsyncHookQueue {
+    /** Take ownership of a backgrounded job. `false` (and the job killed) when the concurrency cap is reached or the queue is disposed. */
+    adopt(job: AsyncHookJob): boolean;
+    /** Finished outputs since the last drain, oldest first. Empties the queue. */
+    drain(): AsyncHookDrain;
+    /** Jobs still running. */
+    running(): number;
+    /** Session end: kill every running job, forget every undelivered output. Idempotent. */
+    dispose(): void;
+}
+/**
+ * What a finished background hook SAYS -- `systemMessage` and `additionalContext`, nothing else (see this
+ * file's header). Only a clean exit counts: a non-zero exit (2 included -- a block it can no longer
+ * perform) or a kill says nothing. `stdout` is everything AFTER an announced `{"async": true}` line.
+ */
+export declare function finishedOutput(event: HookEvent, finished: FinishedHookProcess): Pick<AsyncHookOutput, "systemMessage" | "additionalContext">;
+export interface AsyncHookQueueOptions {
+    maxRunning?: number;
+    maxPending?: number;
+    /** Where a refused, failed or timed-out job is reported (one line each). Defaults to stderr. */
+    warn?: (line: string) => void;
+}
+export declare function createAsyncHookQueue(opts?: AsyncHookQueueOptions): AsyncHookQueue;

package/dist/hooks/command-invoker.d.ts

@@ -1,6 +1,7 @@
 import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
 import { type HookInvocationRequest, type HookInvoker } from "./runner.js";
 import type { SourcedHookEntry } from "./registry.js";
+import { type AsyncHookQueue } from "./async-hooks.js";
 /** Grace between SIGTERM and SIGKILL. Short: by the time this fires the runner has already given up on the hook. */
 export declare const COMMAND_HOOK_KILL_GRACE_MS = 250;
 export declare class CommandHookError extends Error {
@@ -28,6 +29,12 @@ export interface CommandHookInvokerOptions {
     transcriptPath?: string;
     /** WS-23: the stdin input's `permission_mode`, read at invocation time (it changes mid-session). */
     permissionMode?: () => string | undefined;
+    /** WS-24: where backgrounded (async) hooks go. Defaults to a fresh `createAsyncHookQueue()`, exposed as the invoker's `asyncHooks`. */
+    asyncHooks?: AsyncHookQueue;
+}
+/** WS-24: the command invoker also OWNS the session's background hooks (hooks/async-hooks.ts). */
+export interface CommandHookInvoker extends HookInvoker {
+    readonly asyncHooks: AsyncHookQueue;
 }
 /**
  * Wraps `opts.next`, executing any invocation whose `hookId` belongs to a command-bearing entry as a
@@ -36,7 +43,7 @@ export interface CommandHookInvokerOptions {
  * The entry list is snapshotted at construction, matching `buildHookRegistry`'s own "a registry is
  * immutable for the life of a run" contract -- a run builds both from the same entries.
  */
-export declare function createCommandHookInvoker(entries: readonly SourcedHookEntry[], opts: CommandHookInvokerOptions): HookInvoker;
+export declare function createCommandHookInvoker(entries: readonly SourcedHookEntry[], opts: CommandHookInvokerOptions): CommandHookInvoker;
 /**
  * claude's command-hook stdin: the snake_case `HookInput` for this event, built from the runner's
  * camelCase request. `payload` already carries each event's own fields in claude's spelling (the

package/dist/hooks/registry.d.ts

@@ -21,6 +21,12 @@ export interface SourcedHookEntry extends HookParticipant {
      * (command-invoker.ts). Absent on every non-plugin entry.
      */
     pluginRoot?: string;
+    /**
+     * WS-24: a settings/plugin command handler declared `async: true` -- it runs in the BACKGROUND and
+     * never blocks its event (hooks/async-hooks.ts). Never set together with `failClosed` on a
+     * PreToolUse/PermissionRequest entry: from-config.ts refuses the flag there (a floor must gate).
+     */
+    async?: boolean;
 }
 export interface HookRegistry {
     matching(event: HookEvent, toolName?: string): SourcedHookEntry[];

package/dist/hooks/runner.d.ts

@@ -1,6 +1,7 @@
 import type { HookEvent, HookPermissionDecision } from "@yanlinglabs/winter-agent-sdk";
 import { type HookRegistry } from "./registry.js";
 import { type HookComposite } from "./reducer.js";
+import type { AsyncHookQueue } from "./async-hooks.js";
 export interface HookInvocationRequest {
     event: HookEvent;
     matchedMatcher?: string;
@@ -8,6 +9,14 @@ export interface HookInvocationRequest {
     agentID?: string;
     toolUseID?: string;
     toolName?: string;
+    /**
+     * WS-24: for an MCP tool, the server that registered `toolName` and the tool's own name there
+     * (`mcpToolProvenance` below). Both builders of a hook's input -- `commandHookInput`
+     * (command-invoker.ts) and the wrapper's `buildHookInput` (sdk query.ts) -- turn them into
+     * `mcp_server_name`/`mcp_tool_name`. Absent for every non-MCP tool and every tool-less event.
+     */
+    mcpServerName?: string;
+    mcpToolName?: string;
     input?: Record<string, unknown>;
     payload?: unknown;
     policyVersion: string;
@@ -15,10 +24,21 @@ export interface HookInvocationRequest {
     hookId: string;
     hookName?: string;
 }
+export interface McpToolProvenanceInfo {
+    server: string;
+    tool: string;
+}
+export declare function mcpToolProvenance(toolName: string): McpToolProvenanceInfo | undefined;
 export interface HookInvoker {
     invoke(request: HookInvocationRequest, opts: {
         signal: AbortSignal;
     }): Promise<unknown>;
+    /**
+     * WS-24: the session's background (async) hooks, when this invoker can run any -- only the command
+     * invoker can (hooks/async-hooks.ts). The engine drains it at each safe point and disposes it at
+     * session end; a callback-only session has none.
+     */
+    readonly asyncHooks?: AsyncHookQueue;
 }
 export type HookAuditOutcome = "decision" | "none" | "error" | "timeout" | "skipped";
 export interface HookAuditRecord {
@@ -100,6 +120,8 @@ export interface RunHooksContext {
     timeouts?: HookTimeoutConfig;
     validator?: ToolInputValidator;
     lifecycle?: HookLifecycleSink;
+    /** WS-24: the MCP provenance lookup. Defaults to `mcpToolProvenance` (the live registry); a test seam. */
+    mcpProvenance?: (toolName: string) => McpToolProvenanceInfo | undefined;
 }
 export declare const FAIL_CLOSED_EVENTS: ReadonlySet<HookEvent>;
 export declare function runHooks(event: HookEvent, call: RunHooksCallInfo, ctx: RunHooksContext): Promise<HookComposite>;