@yanlinglabs/winter-agent-sdk 0.0.14 → 0.0.16

package/README.md

@@ -68,6 +68,57 @@ plus two canonical standing-server twins, and `@yanlinglabs/winter-runtime-sdk`
 definitions under Claude's built-in names. Handlers return `{ text, isError? }` for each host to
 wrap in its own result shape.
 
+## Environment variables and settings
+
+The runtime child reads a handful of environment variables at spawn/per-turn, plus a few
+`Options`/`RuntimeConfig` fields. Every variable name below is `WINTER_`-prefixed for Winter's own
+build (`BrandProfile.envPrefix`); a rebranded host reads the identical suffix under its own prefix.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `WINTER_DISABLE_BACKGROUND_TASKS` | off | A hard kill switch with two effects together: it drops `run_in_background` from the Agent tool's own advertised schema entirely, and it forces every subagent spawn to the foreground unconditionally (outranking a definition's own `background: true`, a fork, and an explicit `run_in_background: true` alike). |
+| `WINTER_BACKGROUND_BY_DEFAULT` | on (background) | A softer opt-out than the kill switch above: a falsy value (`0`/`false`/`no`/`off`, case-insensitive) restores the pre-0.0.16 default (an unflagged spawn runs in the FOREGROUND) without removing `run_in_background` from the schema — the model can still ask for either explicitly either way. `Options.backgroundByDefault` (see below) wins over this variable in either direction when both are set. |
+| `WINTER_PRINT_BG_WAIT_CEILING_MS` | `600000` (10 minutes) | How long a closed-input session holds its result for a still-running background agent/workflow before sweeping it as stopped. `0` waits indefinitely. |
+| `WINTER_EMIT_SESSION_STATE_EVENTS` | off | Truthy (`1`/`true`) emits `system/session_state_changed` frames (`running`/`idle`) as a turn starts and ends. Absent, the frame stream is unchanged from before this existed. |
+| `WINTER_DISABLE_GIT_INSTRUCTIONS` | off | Truthy disables the git status/instructions section of the system prompt outright, overriding `Settings.includeGitInstructions` in either direction. A falsy value (`0`/`false`/`no`/`off`) explicitly re-enables it even when the setting says otherwise. |
+| `WINTER_DISABLE_EXPLORE_INHERIT_CAP` | off | Truthy opts a first-party Anthropic session out of the Explore built-in's own model cap (which otherwise caps a Fable-tier session's Explore spawn down to Opus). |
+| `WINTER_FORK_SUBAGENT` | off | Truthy enables `subagent_type: "fork"` for the session (mirrors `CLAUDE_CODE_FORK_SUBAGENT`). `Options.forkSubagent` (below) wins over this variable in either direction. |
+| `WINTER_WEB_FETCH_AGENT` | off | Truthy makes the `web-fetch` built-in agent type available (off by default, like claude's own). |
+| `WINTER_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | off | Truthy withholds every built-in `subagent_type` (gated or not) for the session. |
+| `WINTER_DISABLE_EXPLORE_PLAN_AGENTS` | off | Truthy withholds the `Explore` and `Plan` built-ins together. |
+| `WINTER_DISABLE_AGENT_VIEW` | off | Truthy withholds the `claude` catch-all built-in (mirrors `CLAUDE_CODE_DISABLE_AGENT_VIEW`). |
+| `WINTER_MAX_SUBAGENT_SPAWN_DEPTH` | `3` | How many levels of subagent nesting are allowed beneath the top-level session before a spawn is refused. |
+| `WINTER_MAX_CONCURRENT_SUBAGENTS` | `20` | How many subagents may run at once (across the whole nesting tree) before a spawn is refused. |
+
+A handful of `Options`/settings fields carry the same weight as their env counterparts, and a
+RuntimeConfig field always wins over its own env fallback in either direction when both are set:
+
+- **`Settings.includeGitInstructions`** (default `true`) — the setting `WINTER_DISABLE_GIT_INSTRUCTIONS` overrides above.
+- **`Options.forkSubagent`** (`boolean`, default unset → env fallback) — the RuntimeConfig field behind `WINTER_FORK_SUBAGENT`.
+- **`Options.backgroundByDefault`** (`boolean`, default unset → env fallback) — the RuntimeConfig field behind `WINTER_BACKGROUND_BY_DEFAULT`, above.
+
+`RuntimeConfig.allowedAgentTypes` (`string[]`) is a different shape of field, not a host-settable
+one: there is no `Options.allowedAgentTypes` and no env fallback to win over. It exists only on the
+wire `RuntimeConfig`, and the engine — never a host — populates it: when a running agent's own
+definition restricts `tools` with an `Agent(a, b)` entry, `allowedAgentTypesFromTools` parses that
+restriction and threads the resulting list onto the CHILD it spawns for that agent's own
+`RuntimeConfig`, so the child's listing / `init.agents` / Agent-tool resolution sees only `[a, b]`,
+never the full universe of types its parent session could otherwise reach. Absent (every top-level
+session, and any child whose parent definition named no `Agent(...)` restriction) means
+unrestricted, the behavior every session had before this field existed.
+
+### The 0.0.16 background-default change
+
+Before 0.0.16, an Agent tool call with no `run_in_background` ran in the **foreground** (this call
+does not return until the spawned agent finishes). From 0.0.16 on, matching claude, the same
+unflagged call runs in the **background** by default: the call returns immediately with a task id,
+and the model is told about the result later as a task notification (mid-turn, or as its own
+unsolicited turn). `run_in_background: false` still asks for the old, synchronous behavior on any
+one call. A host that wants the *default* itself to stay foreground — without losing the
+`run_in_background` field or forcing every call to name it explicitly — sets
+`Options.backgroundByDefault: false` (or `WINTER_BACKGROUND_BY_DEFAULT=false`); the kill switch,
+`WINTER_DISABLE_BACKGROUND_TASKS`, is unrelated and unaffected by this knob in either direction.
+
 ## License
 
 MIT — see [`LICENSE`](./LICENSE), which ships in the published tarball.

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export type { QueryInternal, ControlRequestHandler, ControlRequestHandlerResult
 export type { Options } from "./options.js";
 export { SYSTEM_PROMPT_DYNAMIC_BOUNDARY, DEFAULT_CONTEXT_WINDOW_TOKENS, DEFAULT_COMPACTION_THRESHOLD, DEFAULT_PLANS_DIRECTORY, DEFAULT_OUTPUT_STYLE } from "./options.js";
 export { DEFAULT_PROVIDER_STALL_TIMEOUT_MS, DEFAULT_KEYCHAIN_SERVICE } from "./options.js";
-export type { ProviderSelection, ProviderConnectionConfig, CredentialRef, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, ModelInfo, AccountInfo } from "./protocol/config.js";
+export type { ProviderSelection, ProviderConnectionConfig, CredentialRef, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, ModelInfo, AgentInfo, AccountInfo } from "./protocol/config.js";
 export type { SlotView, ActiveSlotSet, ModelFamilyListing, ModelSlotSetting, ModelRowServable } from "./protocol/config.js";
 export type { SdkPluginConfig, SystemPromptOption, SystemPromptPreset, OutputFormat, JsonSchemaOutputFormat, SkillsOption, RewindFilesResult, RewindFilesRequest, InitPluginInfo } from "./protocol/config.js";
 export type { McpServerConfig, McpSdkServerConfigWithInstance, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, AgentDefinition } from "./options.js";
@@ -24,7 +24,7 @@ export { SDK_VERSION } from "./version.js";
 export { MESSAGING_CONTROL_SUBTYPES, MESSAGING_CONTROL_SUBTYPE_LIST, MESSAGING_HOST_REQUEST_SUBTYPES, MESSAGING_RUNTIME_REQUEST_SUBTYPES, resolveFacetTarget } from "./protocol/messaging.js";
 export { isRuntimeAddress, isGlobalAgentMessage, isDeliveryOutcome, isListedRuntimeObjectArray, isPermissionClassLabel, isMessagingDeliverRequest, isMessagingChildRequest, isMessagingSubscribeIdleRequest, isMessagingReadNotificationsRequest, isMessagingNotificationsPage, isMessagingIdleNoticePayload, isNotificationRecord, } from "./protocol/messaging.js";
 export type { MessagingControlSubtype, MessagingDeliverRequest, MessagingChildRequest, MessagingSubscribeIdleRequest, MessagingSenderClassResponse, MessagingReadNotificationsRequest, MessagingNotificationsPage, MessagingIdleNoticePayload, } from "./protocol/messaging.js";
-export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, WireContentBlock, WireStreamEvent, WireStreamEventDelta, SDKPartialAssistantMessage, SDKAssistantMessageError, SDKAPIRetryMessage, SDKRateLimitEvent, SDKRateLimitInfo, SDKAuthStatusMessage, SDKThinkingTokensMessage, SDKModelRefusalFallbackMessage, SDKModelRefusalNoFallbackMessage, SDKReasoningSummaryMessage, SDKModelSwitchMessage, SDKContinuityWarningMessage, } from "./protocol/frames.js";
+export type { ProtocolVersion, WinterFrame, SdkMessage as ProtocolSdkMessage, InitFrame, UserFrame, DataFrame, ControlRequestFrame, ControlResponseFrame, UnknownFrame, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, SDKPermissionDeniedMessage, SDKPermissionDenial, SDKTaskStartedMessage, SDKTaskNotificationMessage, SDKTaskUpdatedMessage, SDKTaskProgressMessage, SDKBackgroundTasksChangedMessage, SDKLocalCommandOutputMessage, BackgroundTaskMessage, SDKCompactBoundaryMessage, SDKSessionStateChangedMessage, WireContentBlock, WireStreamEvent, WireStreamEventDelta, SDKPartialAssistantMessage, SDKAssistantMessageError, SDKAPIRetryMessage, SDKRateLimitEvent, SDKRateLimitInfo, SDKAuthStatusMessage, SDKThinkingTokensMessage, SDKModelRefusalFallbackMessage, SDKModelRefusalNoFallbackMessage, SDKReasoningSummaryMessage, SDKModelSwitchMessage, SDKContinuityWarningMessage, } from "./protocol/frames.js";
 export { resolveWinterHome, resolveKeychainServiceForProfile, isUnset } from "./paths/home.js";
 export { transcriptProjectKey, TRANSCRIPT_PROJECT_KEY_MAX_LENGTH, isVendorCompliantProjectKey } from "./paths/project-key.js";
 export { compatibilityKeys } from "./paths/keys.js";

package/dist/index.js

@@ -578,6 +578,8 @@ function query(args) {
     ...options.toolAliases !== undefined ? { toolAliases: options.toolAliases } : {},
     ...options.agents !== undefined ? { agents: options.agents } : {},
     ...options.forwardSubagentText !== undefined ? { forwardSubagentText: options.forwardSubagentText } : {},
+    ...options.forkSubagent !== undefined ? { forkSubagent: options.forkSubagent } : {},
+    ...options.backgroundByDefault !== undefined ? { backgroundByDefault: options.backgroundByDefault } : {},
     ...options.systemPrompt !== undefined ? { systemPrompt: options.systemPrompt } : {},
     ...options.plugins !== undefined ? { plugins: options.plugins } : {},
     ...options.skills !== undefined ? { skills: options.skills } : {},
@@ -850,6 +852,10 @@ function query(args) {
     const payload = await sendControlRequest("list_models", undefined);
     return Array.isArray(payload) ? payload : [];
   };
+  gen.supportedAgents = async () => {
+    const payload = await sendControlRequest("list_agents", undefined);
+    return Array.isArray(payload) ? payload : [];
+  };
   gen.listModelFamilies = async () => {
     const payload = await sendControlRequest("list_model_families", undefined);
     return isModelFamilyListing(payload) ? payload : { active: undefined, families: [] };
@@ -961,7 +967,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.14";
+var SDK_VERSION = "0.0.16";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;

package/dist/options.d.ts

@@ -97,6 +97,27 @@ export interface Options {
     toolAliases?: Record<string, string>;
     agents?: Record<string, AgentDefinition>;
     forwardSubagentText?: boolean;
+    /**
+     * Winter extension (spawn-surface parity R-S5): enables `subagent_type: "fork"` for this session.
+     * `true` on, `false` off; omitted = the runtime reads `WINTER_FORK_SUBAGENT` (claude's own
+     * `CLAUDE_CODE_FORK_SUBAGENT`), and is off when that is unset.
+     */
+    forkSubagent?: boolean;
+    /**
+     * I4 (fix wave): a programmatic opt-out for the Agent tool's own background default (SDK 0.0.16,
+     * `subagents/policy.ts`'s `resolveForegroundBackground` -- "background unless `run_in_background`
+     * is explicitly false"). `false` restores the 0.0.15 default (foreground) for every spawn this
+     * knob's stage of the chain decides; `true` is the 0.0.16 default, spelled out. Omitted = the
+     * runtime reads `WINTER_BACKGROUND_BY_DEFAULT` (falsy -- "0"/"false"/"no"/"off" -- restores
+     * foreground; anything else, including absent, keeps background), the SAME `forkSubagent`
+     * precedent: the field wins in either direction, the env is only the fallback.
+     *
+     * Distinct from `WINTER_DISABLE_BACKGROUND_TASKS` (which keeps its own, unrelated meaning -- a
+     * hard kill switch that ALSO removes `run_in_background` from the advertised schema entirely):
+     * this knob changes only which way an OMITTED `run_in_background` resolves, and the field stays
+     * on the schema either way.
+     */
+    backgroundByDefault?: boolean;
     onElicitation?: (request: {
         serverName: string;
         message: string;

package/dist/protocol/config.d.ts

@@ -164,6 +164,47 @@ export interface RuntimeAgentDefinition {
     permissionMode?: string;
     observer?: string;
     observerMessage?: string;
+    /**
+     * A filesystem/frontmatter agent's own `isolation` (research §A1's own field table: "also color,
+     * isolation (worktree|remote), background, memory, effort, permissionMode"). Mirrors the model-
+     * facing `Agent` tool's own `isolation` enum exactly -- a DEFINITION may pin the isolation a caller
+     * would otherwise choose per-invocation. Absent = no isolation preference from the definition
+     * (today: the invocation's own `isolation` field, if any, still governs -- wiring a definition's
+     * own value through spawn resolution is a later lane's job; this field only carries it now).
+     */
+    isolation?: "worktree" | "remote";
+    /**
+     * A filesystem/frontmatter agent's own display `color` (research §A1's field table, same entry as
+     * `isolation` above). Advisory/presentational only -- nothing in this package interprets it; a host
+     * UI (or a future Winter surface) may render an agent's rows in its own color.
+     */
+    color?: string;
+    /**
+     * The `claude` built-in's own shape (research §A1: "`appendSystemPrompt: true` (appended to the
+     * default prompt)"): when true, `prompt` is APPENDED to the session's own composed system prompt
+     * rather than replacing it the way every other definition's `prompt` does (WS-10 §2's "system
+     * prompt of the child", layered onto the base). Absent/false = the established replace-and-layer
+     * behavior every pre-existing definition already has.
+     */
+    appendSystemPrompt?: boolean;
+    /**
+     * The `Explore`/`Plan` built-ins' own shape (research §A1: "`omitClaudeMd: true`; context also
+     * drops gitStatus"). WINTER-NAMED rather than mirroring the pinned field's own product-specific
+     * spelling (WS-01 §5's own "rebrand, don't borrow the vendor's literal name" posture) -- but the
+     * BEHAVIOR is identical: when true, this agent's own context assembly omits the discovered
+     * project-instructions file (the brand's own instructions-file convention, `brand.instructionsFile`) and the git-status dynamic section
+     * from its system/user-context, the same two things claude's `omitClaudeMd` drops. Absent/false =
+     * every pre-existing definition's context, unchanged.
+     */
+    omitProjectContext?: boolean;
+    /**
+     * SDK 0.0.16 Lane P (R3b §5): claude's `whenToUseLean` -- used in place of `description` in the
+     * Agent-tool listing when the session's own model takes the lean prompt (`leanModel`, computed
+     * by `context/agent-listing.ts`'s own caller). Set only on Winter's built-in Explore; every other
+     * definition (Winter's own, or a filesystem/programmatic one) has none, and the listing falls
+     * back to `description` exactly as it always has.
+     */
+    whenToUseLean?: string;
 }
 export interface RuntimeConfig {
     sessionId: string;
@@ -207,8 +248,37 @@ export interface RuntimeConfig {
     toolAliases?: Record<string, string>;
     agents?: Record<string, RuntimeAgentDefinition>;
     forwardSubagentText?: boolean;
+    /**
+     * SDK 0.0.16 Lane P (R3b §4): the RUNNING agent's own `Agent(a, b)` restriction, parsed from its
+     * `AgentDefinition.tools` entries by `subagents/definitions.ts`'s own `allowedAgentTypesFromTools`
+     * and threaded onto a CHILD's own RuntimeConfig at spawn (`child-engine.ts`) -- so a session
+     * spawned from a definition with `tools: ["*", "Agent(Explore, Plan)"]` sees only [Explore, Plan]
+     * in ITS OWN listing / `init.agents` / Agent-tool resolution, never the full universe of types
+     * this session could otherwise reach. Absent = unrestricted, the pre-existing behaviour every
+     * session before this field existed keeps. Pure passthrough; query.ts never interprets it.
+     */
+    allowedAgentTypes?: string[];
     agentId?: string;
     isolationPinnedCwd?: boolean;
+    /**
+     * Spawn-surface parity (R-S5): the fork gate -- `subagent_type: "fork"` is selectable (and the
+     * `fork` built-in is listed) only when this is `true`. `false` forces it off; ABSENT falls back to
+     * the `<PREFIX>FORK_SUBAGENT` env var (claude's own `CLAUDE_CODE_FORK_SUBAGENT` precedent), and
+     * absent-and-unset is OFF (a Winter session is non-interactive, like a headless SDK session).
+     */
+    forkSubagent?: boolean;
+    /**
+     * Spawn-surface parity (R-S5): set ONLY on the RuntimeConfig of a child that is itself a FORK --
+     * a forked worker may not fork again (claude's own refusal). Never set by `query()`.
+     */
+    insideFork?: boolean;
+    /**
+     * I4 (fix wave): mirrors `Options.backgroundByDefault` exactly -- see that field's own comment.
+     * `subagents/policy.ts`'s `resolveForegroundBackground` reads it at its own stage 5, AFTER the
+     * `WINTER_DISABLE_BACKGROUND_TASKS` kill switch (stage 2, unrelated and unaffected) and the
+     * invocation's own explicit `run_in_background` (stage 4, always wins when given).
+     */
+    backgroundByDefault?: boolean;
     systemPrompt?: SystemPromptOption;
     plugins?: SdkPluginConfig[];
     skills?: SkillsOption;
@@ -422,6 +492,21 @@ export interface ModelInfo {
     supportsFastMode?: boolean;
     supportsAutoMode?: boolean;
 }
+/**
+ * The pinned `AgentInfo` (0.3.250 `sdk.d.ts`: "Information about an available subagent that can be
+ * invoked via the Task/Agent tool"). Three fields, one required trio short of `ModelInfo`'s own
+ * richness -- `name`/`description` required, `model` optional ("Model alias this agent uses. If
+ * omitted, inherits the parent's model").
+ *
+ * Declared here for the identical structural reason `ModelInfo`/`AccountInfo` are: `Query.
+ * supportedAgents()` is on the sdk's public surface, the sdk package is dependency-free and
+ * fence-resident, and `packages/runtime` (which BUILDS the listing this feeds) is Bun-only.
+ */
+export interface AgentInfo {
+    name: string;
+    description: string;
+    model?: string;
+}
 /**
  * The pinned `AccountInfo` (`sdk.d.ts:23-33`). EVERY field optional; an empty object is valid, and
  * capture (J) observed exactly three keys present under API-key auth.

package/dist/protocol/frames.d.ts

@@ -245,6 +245,7 @@ export type WireContentBlock = {
     type: "tool_result";
     tool_use_id: string;
     content: string | WireContentBlock[];
+    is_error?: boolean;
     [k: string]: unknown;
 } | {
     type: "image";
@@ -543,6 +544,24 @@ export interface SDKContinuityWarningMessage {
     uuid: string;
     session_id: string;
 }
+/**
+ * SDK 0.0.16 Lane N: `notifySessionStateChanged` (pinned `sdk.d.ts`: "Mirrors notifySessionStateChanged.
+ * 'idle' fires after heldBackResult flushes and the bg-agent do-while exits -- authoritative turn-over
+ * signal"). ENV-GATED on both runtimes: the pinned binary emits it only under
+ * `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS`, Winter only under `WINTER_EMIT_SESSION_STATE_EVENTS`, so a
+ * default session's frame stream is byte-identical with or without this variant existing.
+ *
+ * `requires_action` is declared (it is in the pinned union) but has no Winter producer: Winter's
+ * approval prompts ride `control_request`, not a session-state transition.
+ */
+export interface SDKSessionStateChangedMessage {
+    type: "system";
+    subtype: "session_state_changed";
+    state: "idle" | "running" | "requires_action";
+    uuid: string;
+    session_id: string;
+    [k: string]: unknown;
+}
 export type SdkMessage = {
     type: "system";
     subtype: "init";
@@ -557,8 +576,17 @@ export type SdkMessage = {
     skills: string[];
     plugins: InitPluginInfo[];
     mcp_servers?: WireMcpServerStatus[];
+    /**
+     * Spawn-surface parity (research §A3): the per-session `subagent_type` names -- the SAME set
+     * `Query.supportedAgents()` reports (research: "Same list feeds `system/init.agents?:
+     * string[]` and `Query.supportedAgents(): AgentInfo[]`"). Present only when the `Agent` tool
+     * is itself advertised (absent otherwise, matching `mcp_servers`' own conditional-presence
+     * convention on this same frame) -- the engine-side producer is `engine.ts`'s own
+     * `system/init` block.
+     */
+    agents?: string[];
     [k: string]: unknown;
-} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
+} | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPermissionDeniedMessage | SDKStatusMessage | SDKCompactBoundaryMessage | SDKSessionStateChangedMessage | BackgroundTaskMessage | SDKPartialAssistantMessage | SDKAPIRetryMessage | SDKRateLimitEvent | SDKAuthStatusMessage | SDKThinkingTokensMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKReasoningSummaryMessage | SDKModelSwitchMessage | SDKContinuityWarningMessage | {
     type: "assistant";
     message: {
         content: Array<{

package/dist/query.d.ts

@@ -1,5 +1,5 @@
 import type { SdkMessage as RuntimeSdkMessage } from "./protocol/frames.js";
-import type { AccountInfo, ModelInfo, ModelFamilyListing, RewindFilesResult } from "./protocol/config.js";
+import type { AccountInfo, AgentInfo, ModelInfo, ModelFamilyListing, RewindFilesResult } from "./protocol/config.js";
 import { type Options } from "./options.js";
 import type { PermissionMode, PermissionResult } from "./permissions/types.js";
 import { type DeliveryOutcome, type GlobalAgentMessage, type ListedRuntimeObject, type PermissionClassLabel } from "./messaging/index.js";
@@ -120,6 +120,20 @@ export interface Query extends AsyncGenerator<SdkMessage> {
      * so the answer is a table lookup rather than a network round trip.
      */
     supportedModels(): Promise<ModelInfo[]>;
+    /**
+     * Spawn-surface parity (0.3.250 `sdk.d.ts:2572`, pinned): "Get the list of available subagents for
+     * the current session" — the SAME per-session agent-type list `system/init.agents` carries (research
+     * §A3: "Same list feeds `system/init.agents?: string[]` and `Query.supportedAgents(): AgentInfo[]`"),
+     * here as the richer `{name, description, model?}` triple rather than bare names. A BARE ARRAY, same
+     * shape as `supportedModels` above — served from the runtime's own resolved built-in/filesystem/
+     * programmatic agent set, a table lookup rather than a network round trip.
+     *
+     * The control-subtype producer (the runtime's `list_agents` handler) is a separate lane's wiring;
+     * this wrapper degrades a malformed/absent payload to `[]`, matching `supportedModels`'/
+     * `listModelFamilies`' own "answers with data, never leaves a rejection standing in for absence"
+     * posture.
+     */
+    supportedAgents(): Promise<AgentInfo[]>;
     /**
      * WS-13c §7 (P6.6 Lane C) — WINTER-ONLY, no pinned counterpart: the active slot set this session is
      * currently offering, plus every model family behind "more options". A model switcher shows

package/dist/settings/types.d.ts

@@ -76,6 +76,11 @@ export interface Settings {
     skillListingMaxDescChars?: number;
     /** `sdk.d.ts:5503`. The listing's share of the context window (default 0.01). */
     skillListingBudgetFraction?: number;
+    /**
+     * `sdk.d.ts:5539`. SDK 0.0.16: whether the systemContext `gitStatus` snapshot is sent (default
+     * true). `<PREFIX>DISABLE_GIT_INSTRUCTIONS` overrides it either way.
+     */
+    includeGitInstructions?: boolean;
     /**
      * A settings-tier MCP server block. Deliberately `Record<string, unknown>` rather than a typed
      * server union: `settings/loaders/mcp-config.ts` validates each entry and `resolveMcpServerSources`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yanlinglabs/winter-agent-sdk",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,15 +45,15 @@
     }
   },
   "dependencies": {
-    "@yanlinglabs/winter-provider-catalog": "0.0.14"
+    "@yanlinglabs/winter-provider-catalog": "0.0.16"
   },
   "optionalDependencies": {
-    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.14"
+    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.16"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "@yanlinglabs/winter-conformance": "0.0.14",
-    "winter-agent-runtime": "0.0.14"
+    "winter-agent-runtime": "0.0.16",
+    "@yanlinglabs/winter-conformance": "0.0.16"
   },
   "scripts": {}
 }