@yanlinglabs/winter-agent-runtime 0.0.27

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

@@ -0,0 +1,21 @@
+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";
+export interface HookAdditionalContextAttachment extends AttachmentPayload {
+    type: typeof HOOK_ADDITIONAL_CONTEXT_ATTACHMENT;
+    hookName: string;
+    content: string[];
+    toolUseID?: string;
+}
+export interface HookFeedbackAttachment extends AttachmentPayload {
+    type: typeof HOOK_FEEDBACK_ATTACHMENT;
+    hookName: string;
+    content: string[];
+}
+/** The `additionalContext` strings a composite accumulated, in evaluation order (non-string or empty entries dropped). */
+export declare function contextStrings(extraContext: ReadonlyArray<{
+    context: unknown;
+}> | undefined): string[];
+/** `undefined` when there is nothing to say -- the caller then appends nothing at all. */
+export declare function hookAdditionalContextAttachment(hookName: string, content: readonly string[], toolUseID?: string): HookAdditionalContextAttachment | undefined;
+export declare function hookFeedbackAttachment(hookName: string, content: readonly string[]): HookFeedbackAttachment | undefined;

package/dist/hooks/bounds.d.ts

@@ -0,0 +1,6 @@
+export declare const MAX_HOOK_TEXT_CHARS = 10000;
+export declare const MAX_HOOK_TOOL_OUTPUT_CHARS = 100000;
+export declare const MAX_HOOK_STDOUT_CAPTURE: number;
+export declare function hookTruncationMarker(limit: number): string;
+/** `text` unchanged when within `limit`, else its first `limit` characters plus the visible marker. */
+export declare function capHookText(text: string, limit?: number): string;

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

@@ -0,0 +1,3 @@
+import type { HookInvoker } from "./runner.js";
+import type { RpcBridge } from "../rpc/bridge.js";
+export declare function createBridgeHookInvoker(bridge: RpcBridge): HookInvoker;

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

@@ -0,0 +1,52 @@
+import { type BrandProfile } from "@yanlinglabs/winter-agent-sdk";
+import { type HookInvocationRequest, type HookInvoker } from "./runner.js";
+import type { SourcedHookEntry } from "./registry.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 {
+    readonly exitCode: number | null;
+    readonly stderr: string;
+    /** Fix round 1 (M3): the failure's machine-readable class -- what a fail-closed denial names instead of this error's message (which embeds the command line). */
+    readonly code: string;
+    constructor(message: string, exitCode: number | null, stderr: string, stdout?: string, code?: string);
+}
+export interface CommandHookInvokerOptions {
+    /** Where a non-command entry's invocation goes -- normally `createBridgeHookInvoker(bridge)`. */
+    next: HookInvoker;
+    /** Working directory for the spawned command. The session cwd; never `process.cwd()` picked up implicitly. */
+    cwd: string;
+    /** Environment for the spawned command. Passed explicitly so a caller states which environment governs, matching this codebase's standing rule for env-derived behaviour. */
+    env?: Record<string, string | undefined>;
+    /** The shell used to interpret a command string. Overridable for tests; never taken from `$SHELL`, which a repository could influence. */
+    shellPath?: string;
+    killGraceMs?: number;
+    /** WS-23: `CLAUDE_PROJECT_DIR` (and its brand twin). Defaults to `cwd` -- the session's project directory. */
+    projectDir?: string;
+    /** WS-23: the brand whose env prefix names the Winter twins of `CLAUDE_PROJECT_DIR`/`CLAUDE_PLUGIN_ROOT`. Absent = no twin exported. */
+    brand?: Pick<BrandProfile, "envPrefix">;
+    /** WS-23: the stdin input's `transcript_path` -- the session transcript's absolute path, or `""` when there is none to name. */
+    transcriptPath?: string;
+    /** WS-23: the stdin input's `permission_mode`, read at invocation time (it changes mid-session). */
+    permissionMode?: () => string | undefined;
+}
+/**
+ * Wraps `opts.next`, executing any invocation whose `hookId` belongs to a command-bearing entry as a
+ * subprocess instead.
+ *
+ * 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;
+/**
+ * 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
+ * engine's firing sites pass `tool_response`, `prompt`, `source`, `stop_hook_active`, ...), so it is
+ * spread last and verbatim -- the same lossless construction query.ts's `buildHookInput` applies for
+ * a JS callback. `transcript_path` is claude's non-optional field: `""` when the session has no
+ * durable transcript to point at, never a guessed path.
+ */
+export declare function commandHookInput(request: HookInvocationRequest, ctx: {
+    cwd: string;
+    transcriptPath: string;
+    permissionMode?: string;
+}): Record<string, unknown>;

package/dist/hooks/from-config.d.ts

@@ -0,0 +1,31 @@
+import { type ResolvedSettingSource, type RuntimeHooksConfig } from "@yanlinglabs/winter-agent-sdk";
+import type { SourcedHookEntry } from "./registry.js";
+export declare function buildHookEntriesFromConfig(config: RuntimeHooksConfig | undefined): SourcedHookEntry[];
+/** A settings hook block that could not be turned into an entry. Reported, never thrown (the brief's own MUST). */
+export interface RejectedHookBlock {
+    source: ResolvedSettingSource;
+    path?: string;
+    event?: string;
+    reason: string;
+}
+export interface HookEntriesFromSettings {
+    entries: SourcedHookEntry[];
+    rejected: RejectedHookBlock[];
+}
+/** One settings tier's contribution, as `resolveSettingsDetailed` reports it (`perSource`) or as the pinned `ResolvedSettings.sources` does. */
+export interface SettingsHookSourceInput {
+    source: ResolvedSettingSource;
+    path?: string;
+    settings?: {
+        hooks?: unknown;
+        [key: string]: unknown;
+    };
+    values?: {
+        hooks?: unknown;
+        [key: string]: unknown;
+    };
+    policyOrigin?: string;
+    loaded?: boolean;
+    error?: string;
+}
+export declare function buildHookEntriesFromSettings(perSource: readonly SettingsHookSourceInput[] | undefined): HookEntriesFromSettings;

package/dist/hooks/hook-stage.d.ts

@@ -0,0 +1,25 @@
+import type { PermissionCall, HookStage } from "../permissions/evaluator.js";
+import { type HookInvoker, type HookAuditRecorder, type HookTimeoutConfig, type ToolInputValidator, type HookLifecycleSink } from "./runner.js";
+import type { HookRegistry } from "./registry.js";
+import type { HookComposite } from "./reducer.js";
+export interface HookStageDeps {
+    registry: HookRegistry;
+    invoker: HookInvoker;
+    audit: HookAuditRecorder;
+    sessionId: string;
+    agentID?: string;
+    timeouts?: HookTimeoutConfig;
+    validator?: ToolInputValidator;
+    lifecycle?: HookLifecycleSink;
+    /**
+     * WS-23: every composite this stage computes, handed to the engine BESIDE the decision -- the
+     * parts of a PreToolUse/PermissionRequest answer that are not a permission decision
+     * (`extraContext`, `systemMessages`, `preventContinuation`) and so have no field on evaluator.ts's
+     * `HookDecision`/`PermissionDecisionRecord`. A side channel rather than thirty new spreads through
+     * every record construction site in evaluate(): the engine keys what it receives by `toolUseId`
+     * and OVERWRITES on each call, so evaluateWithFreshPolicy's stale-policy re-evaluation replaces
+     * the earlier composite instead of doubling its context.
+     */
+    onComposite?: (event: "PreToolUse" | "PermissionRequest", call: PermissionCall, composite: HookComposite) => void;
+}
+export declare function createHookStage(deps: HookStageDeps): HookStage;

package/dist/hooks/input-validator.d.ts

@@ -0,0 +1,6 @@
+import type { ToolInputValidator } from "./runner.js";
+export interface RegistryToolInputValidatorOptions {
+    /** Where the once-per-tool "this schema does not compile" note goes. Defaults to stderr. */
+    warn?: (line: string) => void;
+}
+export declare function createRegistryToolInputValidator(opts?: RegistryToolInputValidatorOptions): ToolInputValidator;

package/dist/hooks/reducer.d.ts

@@ -0,0 +1,74 @@
+import type { HookEvent, HookSource, HookPermissionDecision, PermissionUpdate } from "@yanlinglabs/winter-agent-sdk";
+export interface HookOutcomeFields {
+    transformedInput?: Record<string, unknown>;
+    transformedOutput?: unknown;
+    extraContext?: unknown;
+    classifierContext?: string;
+    message?: string;
+    interrupt?: boolean;
+    updatedPermissions?: PermissionUpdate[];
+    blockReason?: string;
+    preventContinuation?: boolean;
+    stopReason?: string;
+    systemMessage?: string;
+    suppressOutput?: boolean;
+}
+export type HookOutcome = ({
+    kind: "decision";
+    decision: HookPermissionDecision;
+} & HookOutcomeFields) | ({
+    kind: "none";
+} & HookOutcomeFields) | {
+    kind: "error";
+    reason?: string;
+    code?: string;
+} | {
+    kind: "timeout";
+} | {
+    kind: "skipped";
+};
+export interface HookParticipant {
+    id: string;
+    name?: string;
+    event: HookEvent;
+    matcher?: string;
+    source: HookSource;
+}
+export interface AttributedContext {
+    hookId: string;
+    hookName?: string;
+    context: unknown;
+}
+export type HookInvocationOutcome = "decision" | "none" | "error" | "timeout" | "skipped";
+export interface HookLifecycleRecord {
+    hookId: string;
+    hookName?: string;
+    event: HookEvent;
+    matchedMatcher?: string;
+    source: HookSource;
+    outcome: HookInvocationOutcome;
+    decision?: HookPermissionDecision;
+}
+export interface HookComposite {
+    decision?: HookPermissionDecision;
+    transformedInput?: Record<string, unknown>;
+    transformedOutput?: unknown;
+    extraContext?: AttributedContext[];
+    classifierContext?: AttributedContext[];
+    message?: string;
+    interrupt?: boolean;
+    updatedPermissions?: PermissionUpdate[];
+    blockReasons?: AttributedContext[];
+    systemMessages?: AttributedContext[];
+    preventContinuation?: {
+        hookId: string;
+        hookName?: string;
+        reason?: string;
+    };
+    lifecycleMessages: HookLifecycleRecord[];
+}
+export interface HookOutcomeEntry {
+    participant: HookParticipant;
+    outcome: HookOutcome;
+}
+export declare function reduceHookOutcomes(results: HookOutcomeEntry[]): HookComposite;

package/dist/hooks/registry.d.ts

@@ -0,0 +1,33 @@
+import type { HookEvent } from "@yanlinglabs/winter-agent-sdk";
+import type { HookParticipant } from "./reducer.js";
+export declare const TOOL_SCOPED_HOOK_EVENTS: ReadonlySet<HookEvent>;
+export declare function isToolScopedHookEvent(event: HookEvent): boolean;
+export declare const MATCHER_SUBJECT_FIELD: Readonly<Partial<Record<HookEvent, string>>>;
+export interface SourcedHookEntry extends HookParticipant {
+    timeoutMs?: number;
+    command?: string;
+    /**
+     * WS-23: fail CLOSED on PreToolUse/PermissionRequest -- an error, a timeout or a malformed output
+     * from THIS hook denies the call (runner.ts's `failClosedDenial`) instead of contributing nothing.
+     * Absent = the long-standing non-blocking default. Set from `HookCallbackMatcher.failClosed` (per
+     * callback matcher, riding the wire as `RuntimeHookMatcherGroup.failClosed`) or from a settings /
+     * plugin command handler's own `failClosed: true`.
+     */
+    failClosed?: boolean;
+    /**
+     * WS-23: the plugin's own root directory, for a plugin-sourced command hook -- exported as
+     * `CLAUDE_PLUGIN_ROOT` (and its brand twin) in the hook's environment, so `/bin/sh` expands a
+     * `${CLAUDE_PLUGIN_ROOT}` in `command` itself; never spliced into the command text
+     * (command-invoker.ts). Absent on every non-plugin entry.
+     */
+    pluginRoot?: string;
+}
+export interface HookRegistry {
+    matching(event: HookEvent, toolName?: string): SourcedHookEntry[];
+}
+export interface HookRegistryOptions {
+    trustedWorkspace?: boolean;
+    /** WS-23: where a matcher that will not compile is reported, once. Defaults to stderr. */
+    warn?: (line: string) => void;
+}
+export declare function buildHookRegistry(entries: SourcedHookEntry[], opts?: HookRegistryOptions): HookRegistry;

package/dist/hooks/runner.d.ts

@@ -0,0 +1,105 @@
+import type { HookEvent, HookPermissionDecision } from "@yanlinglabs/winter-agent-sdk";
+import { type HookRegistry } from "./registry.js";
+import { type HookComposite } from "./reducer.js";
+export interface HookInvocationRequest {
+    event: HookEvent;
+    matchedMatcher?: string;
+    sessionId: string;
+    agentID?: string;
+    toolUseID?: string;
+    toolName?: string;
+    input?: Record<string, unknown>;
+    payload?: unknown;
+    policyVersion: string;
+    requestId: string;
+    hookId: string;
+    hookName?: string;
+}
+export interface HookInvoker {
+    invoke(request: HookInvocationRequest, opts: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+}
+export type HookAuditOutcome = "decision" | "none" | "error" | "timeout" | "skipped";
+export interface HookAuditRecord {
+    hookId: string;
+    hookName?: string;
+    hookEvent: HookEvent;
+    sessionId: string;
+    uuid: string;
+    toolUseID?: string;
+    requestId?: string;
+    outcome: HookAuditOutcome;
+    decision?: HookPermissionDecision;
+    durationMs?: number;
+    agentID?: string;
+}
+export interface HookAuditRecorder {
+    record(entry: HookAuditRecord): void | Promise<void>;
+}
+export interface ToolInputValidator {
+    validate(toolName: string, input: Record<string, unknown>): {
+        valid: true;
+    } | {
+        valid: false;
+        reason?: string;
+    };
+}
+export declare const NO_SCHEMAS_YET_VALIDATOR: ToolInputValidator;
+export interface HookTimeoutConfig {
+    gatingTimeoutMs?: number;
+    observationalTimeoutMs?: number;
+}
+export declare const DEFAULT_GATING_TIMEOUT_MS = 60000;
+export declare const DEFAULT_OBSERVATIONAL_TIMEOUT_MS = 30000;
+export declare const GATING_HOOK_EVENTS: ReadonlySet<HookEvent>;
+export declare function isGatingHookEvent(event: HookEvent): boolean;
+export interface RunHooksCallInfo {
+    toolUseID?: string;
+    toolName?: string;
+    input?: Record<string, unknown>;
+    payload?: unknown;
+}
+export interface HookLifecycleSink {
+    started(info: {
+        hookId: string;
+        hookName?: string;
+        hookEvent: HookEvent;
+        sessionId: string;
+    }): void;
+    response(info: {
+        hookId: string;
+        hookName?: string;
+        hookEvent: HookEvent;
+        sessionId: string;
+        outcome: "success" | "error" | "cancelled";
+        stdout?: string;
+        stderr?: string;
+        exitCode?: number;
+    }): void;
+}
+/**
+ * WS-23: the side channel a command hook's own process output rides from the invoker to the lifecycle
+ * sink. A SYMBOL-keyed, non-enumerable property on the output object the invoker returns: invisible to
+ * every interpreter (which read string keys) and to `JSON.stringify`, so no hook output shape changes.
+ * Only a command invoker ever sets it; a callback hook has no process and no stdout.
+ */
+export declare const HOOK_PROCESS_OUTPUT: unique symbol;
+export interface HookProcessOutput {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}
+export interface RunHooksContext {
+    registry: HookRegistry;
+    invoker: HookInvoker;
+    audit: HookAuditRecorder;
+    sessionId: string;
+    policyVersion: string | number;
+    agentID?: string;
+    timeouts?: HookTimeoutConfig;
+    validator?: ToolInputValidator;
+    lifecycle?: HookLifecycleSink;
+}
+export declare const FAIL_CLOSED_EVENTS: ReadonlySet<HookEvent>;
+export declare function runHooks(event: HookEvent, call: RunHooksCallInfo, ctx: RunHooksContext): Promise<HookComposite>;