@yanlinglabs/winter-agent-sdk 0.0.1

package/dist/options.d.ts

@@ -0,0 +1,252 @@
+import type { SpawnClaudeCodeProcess } from "./transport.js";
+import type { PermissionMode, CanUseTool, HookEvent, HookCallbackMatcher } from "./permissions/types.js";
+import type { SandboxSettingsConfig, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, RuntimeAgentDefinition, SdkPluginConfig, SystemPromptOption, OutputFormat, SkillsOption, ProviderSelection, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig } from "./protocol/config.js";
+import type { SettingSource } from "./settings/types.js";
+import type { SessionStore } from "./store/session-store.js";
+import { type BrandProfile } from "./brand.js";
+export type { BrandProfile, BrandValidation } from "./brand.js";
+export type { SdkPluginConfig, SystemPromptOption, OutputFormat, JsonSchemaOutputFormat, SkillsOption } from "./protocol/config.js";
+export type { ProviderSelection, ProviderConnectionConfig, CredentialRef, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig } from "./protocol/config.js";
+export declare const SYSTEM_PROMPT_DYNAMIC_BOUNDARY = "__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__";
+export declare const DEFAULT_CONTEXT_WINDOW_TOKENS = 200000;
+export declare const DEFAULT_COMPACTION_THRESHOLD = 0.92;
+export declare const DEFAULT_PLANS_DIRECTORY: string;
+export declare const DEFAULT_OUTPUT_STYLE = "default";
+export declare const DEFAULT_PROVIDER_STALL_TIMEOUT_MS = 120000;
+export declare const DEFAULT_KEYCHAIN_SERVICE: string;
+export interface McpSdkServerConfigWithInstance extends McpSdkServerConfig {
+    instance: unknown;
+}
+export type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig | McpSSEServerConfig | McpSdkServerConfigWithInstance;
+export type { McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig };
+export interface WinterMcpServerInstance {
+    listTools(): Array<{
+        name: string;
+        description?: string;
+        inputSchema: Record<string, unknown>;
+        outputSchema?: Record<string, unknown>;
+        annotations?: {
+            readOnlyHint?: boolean;
+            destructiveHint?: boolean;
+            openWorldHint?: boolean;
+            title?: string;
+            idempotentHint?: boolean;
+        };
+        _meta?: Record<string, unknown>;
+    }>;
+    callTool(name: string, args: Record<string, unknown>): Promise<{
+        content: unknown[];
+        isError?: boolean;
+    }>;
+}
+export declare function isWinterMcpServerInstance(value: unknown): value is WinterMcpServerInstance;
+export type AgentDefinition = Omit<RuntimeAgentDefinition, "permissionMode"> & {
+    permissionMode?: PermissionMode;
+};
+export interface Options {
+    model?: string;
+    permissionMode?: PermissionMode;
+    maxTurns?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+    pathToClaudeCodeExecutable?: string;
+    spawnClaudeCodeProcess?: SpawnClaudeCodeProcess;
+    stderr?: (chunk: string) => void;
+    maxBufferSize?: number;
+    abortController?: AbortController;
+    sessionId?: string;
+    continue?: boolean;
+    resume?: string;
+    forkSession?: boolean;
+    resumeSessionAt?: string;
+    resumeDropsTurn?: boolean;
+    persistSession?: boolean;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    permissions?: {
+        allow?: string[];
+        ask?: string[];
+        deny?: string[];
+        disableBypassPermissionsMode?: boolean;
+    };
+    settingSources?: SettingSource[];
+    /**
+     * Phase 5 fix wave, C1: the MANAGED policy tiers, threaded to the runtime's own settings
+     * resolution. `managedSettings` is filtered restrictive-only there; `serverManagedSettings` is
+     * deliberately not (`sdk.d.ts:2838-2839`). Before this existed the pinned `managed` rule source had
+     * no producer in a live session at all.
+     */
+    managedSettings?: Record<string, unknown>;
+    serverManagedSettings?: Record<string, unknown>;
+    permissionPromptToolName?: string;
+    additionalDirectories?: string[];
+    sandbox?: SandboxSettingsConfig;
+    outputsDir?: string;
+    capabilities?: string[];
+    toolSearchEnabled?: boolean;
+    insideSubagent?: boolean;
+    familyMetadata?: {
+        taskNative?: boolean;
+    };
+    allowDangerouslySkipPermissions?: boolean;
+    canUseTool?: CanUseTool;
+    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
+    includeHookEvents?: boolean;
+    mcpServers?: Record<string, McpServerConfig>;
+    strictMcpConfig?: boolean;
+    toolAliases?: Record<string, string>;
+    agents?: Record<string, AgentDefinition>;
+    forwardSubagentText?: boolean;
+    onElicitation?: (request: {
+        serverName: string;
+        message: string;
+        mode?: "form" | "url";
+        url?: string;
+        elicitationId?: string;
+        requestedSchema?: Record<string, unknown>;
+        title?: string;
+        displayName?: string;
+        description?: string;
+    }, options: {
+        signal: AbortSignal;
+        requestId: string;
+    }) => Promise<{
+        action: "accept" | "decline" | "cancel";
+        content?: Record<string, unknown>;
+    } | null>;
+    systemPrompt?: SystemPromptOption;
+    plugins?: SdkPluginConfig[];
+    skills?: SkillsOption;
+    outputFormat?: OutputFormat;
+    enableFileCheckpointing?: boolean;
+    /**
+     * `sdk.d.ts:1672-1683`: an external session store the runtime MIRRORS transcript writes to. A
+     * DUAL-WRITE MIRROR, never a replacement -- local writes always still happen, which is exactly why
+     * the checkpointing rejection below is about backup blobs specifically rather than about external
+     * storage in general.
+     *
+     * A LIVE OBJECT, like `canUseTool`/`hooks`/`mcpServers[].instance`: it is never serialized into
+     * `--config-json`, so a spawned-process transport reaches it only through the wrapper. Winter does
+     * not yet mirror to it (Lane K / a later phase); it is declared here because two documented
+     * combination REJECTIONS depend on its presence and capture (2) pins both of them at construction.
+     */
+    sessionStore?: SessionStore;
+    contextWindowTokens?: number;
+    compactionThreshold?: number;
+    trustedWorkspace?: boolean;
+    plansDirectory?: string;
+    outputStyle?: string;
+    /**
+     * DISCLOSED WINTER option (R6-9). Which provider a BARE `model` id resolves against, plus that
+     * provider's connection metadata and credential reference.
+     *
+     * `model` itself stays the pinned bare string and `system/init.model` keeps reporting what the
+     * caller passed — the resolved identity rides Winter-only init extension fields instead. A
+     * qualified `"<providerId>/<model>"` key needs no `provider` at all; the pinned Anthropic aliases
+     * (`sonnet`/`opus`/`haiku`/`claude-*`) resolve to the `anthropic` provider when a credential ref
+     * for it is configured. No model and no provider is a typed resolution error, never a silent
+     * default (WS-13 §9: no routing, no substitution in the provider layer).
+     */
+    provider?: ProviderSelection;
+    /**
+     * `sdk.d.ts:1540` — a **single string carrying a COMMA-SEPARATED list**, tried in order. This is
+     * the pin's own convention, not an oversight: the settings twin `Settings.fallbackModel` (`5577`)
+     * is a `string[]`, and the two shapes coexist with a documented precedence. Typing this `string[]`
+     * would be a parity divergence (derived-shapes-p6.md item (g), finding 1).
+     *
+     * Pinned semantics, AS IMPLEMENTED (P6 fix wave, Ruling E-3): the trigger is an R6-6
+     * retryable-class provider failure -- 5xx/overloaded, 429 (non-billing), 408, network, timeout --
+     * AFTER the adapter's own retries are exhausted (NOT a refusal: the `model_refusal_fallback`
+     * frame's `trigger` is the literal `'refusal'`). The failed round is re-run on the next candidate,
+     * candidates are tried in order, each once per turn, and the primary is re-tried at the START OF
+     * EACH USER TURN, so a temporary outage never permanently demotes the session. The swap emits NO
+     * pinned frame (capture (G): the only observable is the outgoing request's `model`); Winter
+     * additionally emits its disclosed `system/model_switch{reason: "fallback"}` for the swap AND for
+     * the restoration, and records both in the dialect record's `providerHistory`. A candidate is
+     * honoured only inside the CURRENT model's continuation domain (R6-9) -- a cross-domain candidate
+     * is a typed error at init and is skipped at engagement time if a `set_model` has since moved the
+     * session. A `set_model` parked during a fallback turn supersedes the restoration.
+     */
+    fallbackModel?: string;
+    /** `sdk.d.ts:1736`, three arms (`adaptive` | `enabled` | `disabled`). Takes precedence over `maxThinkingTokens`, stated twice in the pin (`1732`, `8215`). */
+    thinking?: ThinkingConfig;
+    /**
+     * `sdk.d.ts:1749`. **No numeric form** — see `EffortLevel`'s own declaration comment (R6-E).
+     *
+     * Pinned adjacent rules a consumer must not fight: `'max'` is session-scoped and deliberately not
+     * persistable (`Settings.effortLevel` excludes it), and the ACTIVE level is the one left after a
+     * per-model silent downgrade — which is exactly what the catalog's `reasoning.efforts` evidence
+     * exists to compute honestly rather than by guess.
+     */
+    effort?: EffortLevel;
+    /**
+     * @deprecated Use `thinking` instead.
+     *
+     * `sdk.d.ts:1758`. Kept and typed rather than dropped, because dropping a pinned Options member is
+     * a drop-in parity break. Its semantics CHANGE BY MODEL and that is the trap: on a modern model it
+     * is reinterpreted as on/off — `0` disables, any other value means *adaptive* — so forwarding
+     * `maxThinkingTokens: 8000` is not "budget 8000" (R6-E maps it exactly that way).
+     */
+    maxThinkingTokens?: number;
+    /**
+     * `stream_event` frames (`SDKPartialAssistantMessage`) are emitted only under this gate (R6-5).
+     * Absent/false keeps the stream byte-identical to every session before partial streaming existed.
+     */
+    includePartialMessages?: boolean;
+    /**
+     * A cumulative USD ceiling for this query's provider spend, LIVE since the P6 fix wave (Ruling
+     * E-4, R6-H). Checked BEFORE every provider request: once the accrued `total_cost_usd` exceeds it,
+     * the next request does not go out and the turn ends on the pinned `error_max_budget_usd` result
+     * (`is_error: true`), which carries the cost that crossed it. The generation that crossed the
+     * ceiling still delivers its own frames -- the cut is a request never sent, not an answer lost.
+     *
+     * The descriptor's `pricing` evidence is the ONLY price source: a priced row makes every result
+     * frame carry `total_cost_usd` (accumulated over the whole run and repeated on each result) and a
+     * `modelUsage` row keyed by the model string, with the catalog key as `canonicalModel` and
+     * `costBasis: "list"`; an UNPRICED row emits NO cost field at all and leaves this ceiling inert
+     * (disclosed). Winter deliberately does NOT do what the pin does here -- capture (K) shows the
+     * pinned runtime reporting a non-zero cost for a model no price table contains -- and it does not
+     * emit the main-loop-only `usage` block, which the pin's own JSDoc deprioritises (disclosed).
+     */
+    maxBudgetUsd?: number;
+    /** DISCLOSED WINTER option (R6-6): a stream silent for this long aborts as a typed `ProviderStallError`. Absent means DEFAULT_PROVIDER_STALL_TIMEOUT_MS. */
+    providerStallTimeoutMs?: number;
+    /** DISCLOSED WINTER option (R6-10): the macOS Keychain service every `{ kind: "keychain" }` ref resolves under. Absent means DEFAULT_KEYCHAIN_SERVICE. */
+    keychainService?: string;
+    /** DISCLOSED WINTER option (R6-14): the permission classifier's own model/credential, resolved through the SAME selection path as the session model. With none configured the worker serves only a `classifierEligible` model, else Manual fallback — never a silent weakening. */
+    autoClassifier?: AutoClassifierConfig;
+    /**
+     * DISCLOSED WINTER option (P2 carry, wired in T10): the advisor/reviewer backend's model, same
+     * selection path. Its optional `authRef` (fix wave, Ruling E-1) is the advisor's OWN credential:
+     * a target on another provider than the session's never inherits the session's -- it uses the
+     * route's ref, else the target provider's own keychain record (`<providerId>:default`), else a
+     * typed `no-credential-for-provider` refusal at its first generation.
+     *
+     * The MODEL may also come from `settings.advisor.model` (D30, hot); `Options.advisor.model` wins.
+     */
+    advisor?: AdvisorConfig;
+    /**
+     * DISCLOSED WINTER option (P7a, D19): THE BRAND PROFILE — every Winter-owned name this session
+     * runs under, as a partial that folds onto Winter's own defaults (brand.ts's `WINTER_BRAND`).
+     *
+     * This is what makes the SDK genuinely reusable rather than merely open: a host consuming Winter
+     * alone (D19's tier 1) gets its OWN home dir, project dir, instructions file, env prefix, keychain
+     * service, MCP server name and codex originator, resolved once here and carried to the runtime on
+     * `RuntimeConfig.brand` so a spawned or compiled child derives the same names the wrapper did.
+     *
+     * VALIDATED AT `query()` (brand.ts's grammar rules), and a refusal is a typed `InvalidBrandError`
+     * thrown synchronously at construction, like the other option-combination rejections above --
+     * never a silently-substituted default, because a session that quietly ran under the wrong home
+     * dir or the wrong keychain service is the worst possible outcome of a typo here.
+     *
+     * `keychainService` above is the DEPRECATED standalone alias for `brand.keychainService`: when
+     * both are set the standalone one WINS (it predates the profile and existing hosts pass it), and
+     * `query()` warns when the two are set to DIFFERENT values so the losing one is never silent.
+     *
+     * Claude-mirroring literals are NOT in the profile and cannot be rebranded (WS-01 §5): the
+     * official runtime's `CLAUDE_CONFIG_DIR`/`CLAUDE_CODE_TMPDIR`/`preset: "claude_code"`/
+     * `.claude-plugin` are its names, not ours. Neither are this repository's own test-harness env
+     * names.
+     */
+    brand?: Partial<BrandProfile>;
+}

package/dist/paths/home.d.ts

@@ -0,0 +1,48 @@
+import { type BrandProfile } from "../brand.js";
+export declare function isUnset(value: string | undefined): boolean;
+/**
+ * The two brand fields this module needs. A `Pick` rather than the whole profile so a caller
+ * holding a partially-threaded config (or a test) can call it without constructing one.
+ */
+export type HomeBrand = Pick<BrandProfile, "envPrefix" | "homeDirName">;
+/**
+ * `<PREFIX>HOME` || `~/<homeDirName>` — mirrors `CLAUDE_CONFIG_DIR`'s env-override semantics
+ * (WS-05 §4), with the brand's own token instead of Claude's.
+ *
+ * `env` is injectable so tests never read the real process environment; it defaults to
+ * `process.env` in production. `brand` defaults to `WINTER_BRAND`, so every existing caller keeps
+ * exactly today's behaviour (`WINTER_HOME` || `~/.winter`) until it threads a profile through.
+ *
+ * THE ENV NAME IS DERIVED, NEVER SPELLED, and it is read INSIDE this function — never at module
+ * load. The brand arrives with `--config-json`, so a module-level read of a literal `<PREFIX>HOME`
+ * would bake in the wrong prefix for a reuser and could never be corrected; the sweep gate
+ * (packages/runtime/src/brand-gate.test.ts, rules 9 and 10) is what keeps it that way.
+ *
+ * PRECEDENCE (WS-01 §2.2, and the same rule the current daemon has always had): an explicit
+ * `<PREFIX>HOME` wins over EVERYTHING, including the dev profile. `<PREFIX>PROFILE=dev` selects
+ * `~/<homeDirName>-dev` — the dev/dist split, so a development build can never share a home (or a
+ * transcript store, or a settings file) with the copy a user actually runs.
+ */
+export declare function resolveWinterHome(env?: Record<string, string | undefined>, brand?: HomeBrand): string;
+/**
+ * P7a fix wave (item 5, whole-branch review M-3): THE OTHER HALF OF THE DEV PROFILE.
+ *
+ * WS-01's Phase 6 amendment pairs `<PREFIX>PROFILE=dev` with BOTH `~/<homeDirName>-dev` and a
+ * `.dev`-suffixed Keychain service, and assigns the fold "to whichever phase introduces the
+ * profile" -- this one. Only the home half landed: an env-selected dev session got its own home and
+ * its own transcript store while reading and WRITING the dist Keychain service, which is the one
+ * piece of state a developer most needs separated from the copy they actually use.
+ *
+ * It lives here, immediately beside `resolveWinterHome`, because the two are one rule read from two
+ * fields -- putting them in different files is how they came to disagree in the first place.
+ *
+ * AN EXPLICIT VALUE IS NEVER REWRITTEN. `hostSetKeychainService` is true when the host passed
+ * `brand.keychainService` or the deprecated `keychainService` alias: they named a service, and a
+ * runtime that silently appended to it would be rewriting a host's own decision -- the same
+ * precedence `resolveWinterHome` gives an explicit `<PREFIX>HOME` over the profile.
+ *
+ * The suffix is applied only when the result still satisfies `BrandProfile`'s own service grammar
+ * (64 chars); a longer name is left alone rather than made invalid, since an invalid service reaches
+ * the Keychain as a lookup that can never match.
+ */
+export declare function resolveKeychainServiceForProfile(brand: Pick<BrandProfile, "envPrefix" | "keychainService">, env: Record<string, string | undefined> | undefined, hostSetKeychainService: boolean): string;

package/dist/paths/keys.d.ts

@@ -0,0 +1,6 @@
+export interface CompatibilityKeys {
+    transcriptProjectKey: string;
+    memoryProjectKey: string;
+    tempProjectKey: string;
+}
+export declare function compatibilityKeys(cwd: string): CompatibilityKeys;

package/dist/paths/project-key.d.ts

@@ -0,0 +1 @@
+export declare function transcriptProjectKey(absPath: string): string;

package/dist/permissions/types.d.ts

@@ -0,0 +1,272 @@
+export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "auto";
+export type PermissionBehavior = "allow" | "deny" | "ask";
+export type PermissionRuleValue = {
+    toolName: string;
+    ruleContent?: string;
+};
+export type PermissionUpdate = {
+    type: "addRules";
+    rules: PermissionRuleValue[];
+    behavior: PermissionBehavior;
+    destination: PermissionUpdateDestination;
+} | {
+    type: "replaceRules";
+    rules: PermissionRuleValue[];
+    behavior: PermissionBehavior;
+    destination: PermissionUpdateDestination;
+} | {
+    type: "removeRules";
+    rules: PermissionRuleValue[];
+    behavior: PermissionBehavior;
+    destination: PermissionUpdateDestination;
+} | {
+    type: "setMode";
+    mode: PermissionMode;
+    destination: PermissionUpdateDestination;
+} | {
+    type: "addDirectories";
+    directories: string[];
+    destination: PermissionUpdateDestination;
+} | {
+    type: "removeDirectories";
+    directories: string[];
+    destination: PermissionUpdateDestination;
+};
+export type PermissionUpdateDestination = "userSettings" | "projectSettings" | "localSettings" | "session" | "cliArg";
+export type RuleSource = "managed" | "user" | "project" | "local" | "cliArg" | "session" | "sdk";
+export type CanUseTool = (toolName: string, input: Record<string, unknown>, options: {
+    signal: AbortSignal;
+    suggestions?: PermissionUpdate[];
+    blockedPath?: string;
+    decisionReason?: string;
+    title?: string;
+    displayName?: string;
+    description?: string;
+    toolUseID: string;
+    agentID?: string;
+    requestId: string;
+    matchedAskRule?: {
+        source: string;
+        toolName: string;
+        ruleContent?: string;
+    };
+}) => Promise<PermissionResult | null>;
+export type PermissionDecisionClassification = "user_temporary" | "user_permanent" | "user_reject";
+export type PermissionResult = {
+    behavior: "allow";
+    updatedInput?: Record<string, unknown>;
+    updatedPermissions?: PermissionUpdate[];
+    toolUseID?: string;
+    decisionClassification?: PermissionDecisionClassification;
+} | {
+    behavior: "deny";
+    message: string;
+    interrupt?: boolean;
+    toolUseID?: string;
+    decisionClassification?: PermissionDecisionClassification;
+};
+export interface PermissionRequestPayload {
+    toolName: string;
+    input: Record<string, unknown>;
+    suggestions?: PermissionUpdate[];
+    blockedPath?: string;
+    decisionReason?: string;
+    title?: string;
+    displayName?: string;
+    description?: string;
+    toolUseID: string;
+    agentID?: string;
+    requestId: string;
+    matchedAskRule?: {
+        source: string;
+        toolName: string;
+        ruleContent?: string;
+    };
+    policyVersion: number;
+}
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "UserPromptSubmit", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest", "Notification", "PostToolBatch", "UserPromptExpansion", "MessageDisplay", "StopFailure", "PostCompact", "PermissionDenied", "SessionStart", "SessionEnd", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "InstructionsLoaded", "WorktreeCreate", "WorktreeRemove", "CwdChanged", "FileChanged", "DirectoryAdded"];
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+export type HookEventName = HookEvent;
+export type HookSource = "managed" | "user" | "project" | "local" | "sdk" | "plugin";
+export interface BaseHookInput {
+    session_id: string;
+    transcript_path: string;
+    cwd: string;
+    prompt_id?: string;
+    permission_mode?: string;
+    agent_id?: string;
+    agent_type?: string;
+    effort?: {
+        level: string;
+    };
+}
+export type HookPermissionDecision = "allow" | "ask" | "deny" | "defer";
+export interface PreToolUseHookInput extends BaseHookInput {
+    hook_event_name: "PreToolUse";
+    tool_name: string;
+    tool_input: unknown;
+    tool_use_id: string;
+}
+export interface PostToolUseHookInput extends BaseHookInput {
+    hook_event_name: "PostToolUse";
+    tool_name: string;
+    tool_input: unknown;
+    tool_response: unknown;
+    tool_use_id: string;
+    duration_ms?: number;
+}
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+    hook_event_name: "PostToolUseFailure";
+    tool_name: string;
+    tool_input: unknown;
+    tool_use_id: string;
+    error: string;
+    is_interrupt?: boolean;
+    duration_ms?: number;
+}
+export interface UserPromptSubmitHookInput extends BaseHookInput {
+    hook_event_name: "UserPromptSubmit";
+    prompt: string;
+    source?: "user" | "sdk" | "system" | "loop_wakeup" | "schedule_wakeup" | "poll_event";
+    session_title?: string;
+}
+export interface StopHookInput extends BaseHookInput {
+    hook_event_name: "Stop";
+    stop_hook_active: boolean;
+    last_assistant_message?: unknown;
+    background_tasks?: unknown[];
+    session_crons?: unknown[];
+}
+export interface SessionStartHookInput extends BaseHookInput {
+    hook_event_name: "SessionStart";
+    source: "startup" | "resume" | "clear" | "compact" | "fork";
+    agent_type?: string;
+    model?: string;
+    session_title?: string;
+}
+export interface SessionEndHookInput extends BaseHookInput {
+    hook_event_name: "SessionEnd";
+    reason: string;
+}
+export interface NotificationHookInput extends BaseHookInput {
+    hook_event_name: "Notification";
+    message: string;
+    title?: string;
+    notification_type: string;
+}
+export interface PermissionRequestHookInput extends BaseHookInput {
+    hook_event_name: "PermissionRequest";
+    tool_name: string;
+    tool_input: unknown;
+    permission_suggestions?: PermissionUpdate[];
+}
+export interface PermissionDeniedHookInput extends BaseHookInput {
+    hook_event_name: "PermissionDenied";
+    tool_name: string;
+    tool_input: unknown;
+    tool_use_id: string;
+    reason: string;
+}
+export interface GenericHookInput extends BaseHookInput {
+    hook_event_name: string;
+}
+export type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | UserPromptSubmitHookInput | StopHookInput | SessionStartHookInput | SessionEndHookInput | NotificationHookInput | PermissionRequestHookInput | PermissionDeniedHookInput | GenericHookInput;
+export interface AsyncHookJSONOutput {
+    async: true;
+    asyncTimeout?: number;
+}
+export interface PreToolUseHookSpecificOutput {
+    hookEventName: "PreToolUse";
+    permissionDecision?: HookPermissionDecision;
+    permissionDecisionReason?: string;
+    updatedInput?: Record<string, unknown>;
+    additionalContext?: string;
+}
+export interface PostToolUseHookSpecificOutput {
+    hookEventName: "PostToolUse";
+    additionalContext?: string;
+    classifierContext?: string;
+    updatedToolOutput?: unknown;
+    updatedMCPToolOutput?: unknown;
+}
+export interface PostToolUseFailureHookSpecificOutput {
+    hookEventName: "PostToolUseFailure";
+    additionalContext?: string;
+}
+export interface UserPromptSubmitHookSpecificOutput {
+    hookEventName: "UserPromptSubmit";
+    additionalContext?: string;
+    sessionTitle?: string;
+    suppressOriginalPrompt?: boolean;
+}
+export interface StopHookSpecificOutput {
+    hookEventName: "Stop";
+    additionalContext?: string;
+}
+export interface SessionStartHookSpecificOutput {
+    hookEventName: "SessionStart";
+    additionalContext?: string;
+    initialUserMessage?: string;
+    sessionTitle?: string;
+    watchPaths?: string[];
+    reloadSkills?: boolean;
+}
+export interface NotificationHookSpecificOutput {
+    hookEventName: "Notification";
+    additionalContext?: string;
+}
+export interface PermissionRequestHookSpecificOutput {
+    hookEventName: "PermissionRequest";
+    decision: {
+        behavior: "allow";
+        updatedInput?: Record<string, unknown>;
+        updatedPermissions?: PermissionUpdate[];
+    } | {
+        behavior: "deny";
+        message?: string;
+        interrupt?: boolean;
+    };
+}
+export interface PermissionDeniedHookSpecificOutput {
+    hookEventName: "PermissionDenied";
+    retry?: boolean;
+}
+export interface GenericHookSpecificOutput {
+    hookEventName: string;
+    additionalContext?: string;
+    [key: string]: unknown;
+}
+export type HookSpecificOutput = PreToolUseHookSpecificOutput | PostToolUseHookSpecificOutput | PostToolUseFailureHookSpecificOutput | UserPromptSubmitHookSpecificOutput | StopHookSpecificOutput | SessionStartHookSpecificOutput | NotificationHookSpecificOutput | PermissionRequestHookSpecificOutput | PermissionDeniedHookSpecificOutput | GenericHookSpecificOutput;
+export interface SyncHookJSONOutput {
+    continue?: boolean;
+    suppressOutput?: boolean;
+    stopReason?: string;
+    decision?: "approve" | "block";
+    systemMessage?: string;
+    terminalSequence?: string;
+    reason?: string;
+    hookSpecificOutput?: HookSpecificOutput;
+}
+export type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
+export type HookCallback = (input: HookInput, toolUseID: string | undefined, options: {
+    signal: AbortSignal;
+}) => Promise<HookJSONOutput>;
+export interface HookCallbackMatcher {
+    matcher?: string;
+    hooks: HookCallback[];
+    timeout?: number;
+}
+export interface HookInvocationPayload {
+    event: string;
+    matchedMatcher?: string;
+    sessionId: string;
+    agentID?: string;
+    toolUseID?: string;
+    toolName?: string;
+    input?: Record<string, unknown>;
+    payload?: unknown;
+    policyVersion: string;
+    requestId: string;
+    hookId: string;
+    hookName?: string;
+}

package/dist/protocol/codec.d.ts

@@ -0,0 +1,10 @@
+import type { WinterFrame } from "./frames.js";
+export declare class ProtocolError extends Error {
+    constructor(message: string);
+}
+export declare function encodeFrame(frame: WinterFrame): string;
+export declare function decodeFrame(line: string): WinterFrame;
+export declare function splitFrames(chunk: string, carry: string): {
+    frames: WinterFrame[];
+    carry: string;
+};