@yanlinglabs/winter-agent-sdk 0.0.15 → 0.0.17

package/README.md

@@ -68,6 +68,95 @@ 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_MAX_WEB_SEARCHES_PER_SESSION` | `200` | How many `WebSearch` calls one session may make, counted before each search and shared with every descendant subagent (the analogue of `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`). Past it, a call answers with a plain refusal result rather than an error. |
+| `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 built-in web tools (since 0.0.17)
+
+`WebFetch` and `WebSearch` ship in every default `init.tools`, as copies of the pinned `claude`
+runtime's own — same descriptions, same input schemas, same inner-call prompts, same output assembly.
+
+- **`WebFetch`** takes `{url, prompt}`, fetches the page from this machine (`http` is upgraded to
+  `https` unconditionally, and a hostname with fewer than two dot-separated labels is refused — so
+  `localhost` and IPv6 literals are not fetchable, exactly as in claude), converts HTML to markdown,
+  and answers `prompt` over it with a small fast model. Responses are cached for 15 minutes per
+  session. Rules are `WebFetch(domain:<host>)`; an allow rule naming an exact host is standing consent
+  for that host wherever it resolves.
+- **`WebSearch`** takes `{query, allowed_domains?, blocked_domains?}` and runs one inner pass over the
+  search backend, returning titles and urls only. The budget is 200 calls per session
+  (`WINTER_MAX_WEB_SEARCHES_PER_SESSION`), shared with every descendant. Its only rule form is the
+  bare `WebSearch`; a scoped `WebSearch(...)` in `Options.allowedTools`/`disallowedTools` throws at
+  startup (a settings file drops it and warns).
+
+Withdraw either with `disallowedTools`. `WebSearch` can also be switched off at the backend with
+`web.search.enabled: false`.
+
+- **`Options.web`** — `search.enabled`, `search.authRef` (the backend key, used only once the
+  anonymous tier is exhausted), `search.maxSearchesPerCall` / `search.anonymousMaxSearchesPerCall`,
+  `fetch.digestModel` / `fetch.authRef` (the page-digest model and its own credential),
+  `fetch.privateAddressPolicy` (`"ask"` by default, `"deny"` / `"allow"`), and one `blockedDomains`
+  floor both tools honour (suffix match on a label boundary: `example.com` covers
+  `docs.example.com`). Every field is optional; `resolveWebToolsConfig` + `WEB_TOOLS_DEFAULTS` are
+  exported for a host that wants the resolved shape. **An unattended host should set
+  `fetch.privateAddressPolicy: "deny"`** — under the default a private or loopback target raises a real
+  permission prompt, and a session that cannot prompt refuses the call.
+- **`Options.autoMemory`** — `enabled` and `directory` for the auto-memory section, for a host that
+  runs with `settingSources: []` and therefore cannot reach `autoMemoryEnabled` /
+  `autoMemoryDirectory` in a settings file. Precedence per field: this option, then the settings key,
+  then the computed default (`<home>/projects/<memory-key>/memory`, enabled). A relocated directory
+  under the home's own `projects/` tree stays write-denied.
+
+Subagents inherit both.
+
+### 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,6 +4,9 @@ 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 { WEB_TOOLS_DEFAULTS, resolveWebToolsConfig } from "./options.js";
+export type { ResolvedWebToolsConfig } from "./options.js";
+export type { WebToolsConfig, WebSearchConfig, WebFetchConfig, WebPrivateAddressPolicy, AutoMemoryConfig } 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";
@@ -24,7 +27,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

@@ -66,6 +66,38 @@ var DEFAULT_PLANS_DIRECTORY = `${WINTER_BRAND2.projectDirName}/plans`;
 var DEFAULT_OUTPUT_STYLE = "default";
 var DEFAULT_PROVIDER_STALL_TIMEOUT_MS = 120000;
 var DEFAULT_KEYCHAIN_SERVICE = WINTER_BRAND2.keychainService;
+var WEB_TOOLS_DEFAULTS = {
+  searchEnabled: true,
+  maxSearchesPerCall: 8,
+  anonymousMaxSearchesPerCall: 3,
+  privateAddressPolicy: "ask"
+};
+function positiveIntegerOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 1 ? Math.floor(value) : fallback;
+}
+var PRIVATE_ADDRESS_POLICIES = ["allow", "ask", "deny"];
+function resolveWebToolsConfig(web) {
+  const rawDigest = web?.fetch?.digestModel;
+  const digestModel = typeof rawDigest === "string" ? rawDigest.trim() : undefined;
+  const rawPolicy = web?.fetch?.privateAddressPolicy;
+  const privateAddressPolicy = PRIVATE_ADDRESS_POLICIES.find((policy) => policy === rawPolicy) ?? WEB_TOOLS_DEFAULTS.privateAddressPolicy;
+  const rawEnabled = web?.search?.enabled;
+  const rawBlocked = web?.blockedDomains;
+  return {
+    search: {
+      enabled: rawEnabled === undefined ? WEB_TOOLS_DEFAULTS.searchEnabled : rawEnabled === true,
+      ...web?.search?.authRef !== undefined ? { authRef: web.search.authRef } : {},
+      maxSearchesPerCall: positiveIntegerOr(web?.search?.maxSearchesPerCall, WEB_TOOLS_DEFAULTS.maxSearchesPerCall),
+      anonymousMaxSearchesPerCall: positiveIntegerOr(web?.search?.anonymousMaxSearchesPerCall, WEB_TOOLS_DEFAULTS.anonymousMaxSearchesPerCall)
+    },
+    fetch: {
+      ...digestModel !== undefined && digestModel.length > 0 ? { digestModel } : {},
+      ...web?.fetch?.authRef !== undefined ? { authRef: web.fetch.authRef } : {},
+      privateAddressPolicy
+    },
+    blockedDomains: (Array.isArray(rawBlocked) ? rawBlocked : []).filter((d) => typeof d === "string" && d.trim().length > 0)
+  };
+}
 function isWinterMcpServerInstance(value) {
   if (typeof value !== "object" || value === null)
     return false;
@@ -579,6 +611,7 @@ function query(args) {
     ...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 } : {},
@@ -600,6 +633,8 @@ function query(args) {
     ...brand.keychainService !== WINTER_BRAND2.keychainService || options.keychainService !== undefined ? { keychainService: brand.keychainService } : {},
     ...options.autoClassifier !== undefined ? { autoClassifier: options.autoClassifier } : {},
     ...options.advisor !== undefined ? { advisor: options.advisor } : {},
+    ...options.web !== undefined ? { web: options.web } : {},
+    ...options.autoMemory !== undefined ? { autoMemory: options.autoMemory } : {},
     brand
   };
   const command = options.spawnClaudeCodeProcess ? options.pathToClaudeCodeExecutable ?? "winter" : resolveRuntimeExecutable(options);
@@ -966,7 +1001,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.15";
+var SDK_VERSION = "0.0.17";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -1689,6 +1724,7 @@ export {
   SYSTEM_PROMPT_DYNAMIC_BOUNDARY,
   SessionNotFoundError,
   TRANSCRIPT_PROJECT_KEY_MAX_LENGTH,
+  WEB_TOOLS_DEFAULTS,
   WINTER_BRAND2 as WINTER_BRAND,
   WinterCompatibilitySessionStore2 as WinterCompatibilitySessionStore,
   WinterRpcError,
@@ -1737,6 +1773,7 @@ export {
   resolveRuntimeExecutable,
   resolveSettings,
   resolveSettingsDetailed,
+  resolveWebToolsConfig,
   resolveWinterHome2 as resolveWinterHome,
   settingsPathFor,
   splitFrames,

package/dist/options.d.ts

@@ -1,12 +1,13 @@
 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 { SandboxSettingsConfig, McpServerToolPolicy, McpStdioServerConfig, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, RuntimeAgentDefinition, SdkPluginConfig, SystemPromptOption, OutputFormat, SkillsOption, ProviderSelection, ThinkingConfig, EffortLevel, AutoClassifierConfig, AdvisorConfig, WebToolsConfig, WebPrivateAddressPolicy, AutoMemoryConfig, CredentialRef } 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 type { WebToolsConfig, WebSearchConfig, WebFetchConfig, WebPrivateAddressPolicy, AutoMemoryConfig } 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;
@@ -14,6 +15,42 @@ 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;
+/**
+ * Every web-tool default, spelled ONCE. A reader function resolves an absent field against this --
+ * no consumer writes a literal of its own.
+ *
+ * `maxSearchesPerCall: 8` is the pinned tool's own per-call bound. `anonymousMaxSearchesPerCall: 3`
+ * is Winter's: see `WebSearchConfig.anonymousMaxSearchesPerCall`. `privateAddressPolicy: "ask"` is
+ * the conservative interactive posture; a host that can never ask sets `"deny"`.
+ */
+export declare const WEB_TOOLS_DEFAULTS: {
+    readonly searchEnabled: true;
+    readonly maxSearchesPerCall: 8;
+    readonly anonymousMaxSearchesPerCall: 3;
+    readonly privateAddressPolicy: "ask";
+};
+/** `WebToolsConfig` with every default applied -- what a consumer reads instead of the raw option. */
+export interface ResolvedWebToolsConfig {
+    search: {
+        enabled: boolean;
+        authRef?: CredentialRef;
+        maxSearchesPerCall: number;
+        anonymousMaxSearchesPerCall: number;
+    };
+    fetch: {
+        digestModel?: string;
+        authRef?: CredentialRef;
+        privateAddressPolicy: WebPrivateAddressPolicy;
+    };
+    blockedDomains: string[];
+}
+/**
+ * THE one reader of `WebToolsConfig`. Pure, dependency-free and total: an absent block, an absent
+ * field, a non-positive or non-finite bound and a whitespace-only `digestModel` all resolve to the
+ * default rather than to a value no consumer can act on (a bound of `0` would make a tool that is
+ * advertised and can never search; disabling search is `search.enabled: false`).
+ */
+export declare function resolveWebToolsConfig(web: WebToolsConfig | undefined): ResolvedWebToolsConfig;
 export interface McpSdkServerConfigWithInstance extends McpSdkServerConfig {
     instance: unknown;
 }
@@ -103,6 +140,21 @@ export interface Options {
      * `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;
@@ -231,6 +283,20 @@ export interface Options {
      * The MODEL may also come from `settings.advisor.model` (D30, hot); `Options.advisor.model` wins.
      */
     advisor?: AdvisorConfig;
+    /**
+     * DISCLOSED WINTER option: the `WebSearch` / `WebFetch` tools' configuration -- the search
+     * backend's fallback key and per-call bounds, the page-digest model and its credential, the
+     * private-address policy, and the ONE `blockedDomains` floor both tools honour. Every field is
+     * optional; `resolveWebToolsConfig` applies `WEB_TOOLS_DEFAULTS`. See `WebToolsConfig`.
+     */
+    web?: WebToolsConfig;
+    /**
+     * DISCLOSED WINTER option: the host's say over the auto-memory section -- whether it is on, and
+     * which directory it names. Wins over the settings keys, which win over the computed default; it
+     * is how a host that disables settings files (`settingSources: []`) still makes the session agree
+     * with it about where memory lives. See `AutoMemoryConfig`.
+     */
+    autoMemory?: AutoMemoryConfig;
     /**
      * 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`).

package/dist/protocol/config.d.ts

@@ -197,6 +197,14 @@ export interface RuntimeAgentDefinition {
      * 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;
@@ -240,6 +248,16 @@ 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;
     /**
@@ -254,6 +272,13 @@ export interface RuntimeConfig {
      * 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;
@@ -297,6 +322,10 @@ export interface RuntimeConfig {
     keychainService?: string;
     autoClassifier?: AutoClassifierConfig;
     advisor?: AdvisorConfig;
+    /** The wire twin of `Options.web` -- see `WebToolsConfig`. Pure passthrough; absent means every default in `WEB_TOOLS_DEFAULTS`. */
+    web?: WebToolsConfig;
+    /** The wire twin of `Options.autoMemory` -- see `AutoMemoryConfig`. Pure passthrough; absent means "settings, then the computed default". */
+    autoMemory?: AutoMemoryConfig;
     /**
      * P7a (D19): the RESOLVED brand profile — every Winter-owned name this session runs under.
      *
@@ -447,6 +476,139 @@ export interface AdvisorConfig {
     model: string;
     authRef?: CredentialRef;
 }
+/**
+ * What to do when `WebFetch` is pointed at a loopback, private-range or link-local address.
+ *
+ *   `"ask"`    raise the ordinary permission prompt for that host before anything is fetched;
+ *   `"deny"`   refuse with a typed tool result and fetch nothing;
+ *   `"allow"`  fetch it like any public host.
+ *
+ * WHY THIS IS A HOST DECISION AND NOT A CONSTANT. A sandboxed shell has no network, so `WebFetch` is
+ * the only door from a session to the services on the user's own machine and LAN -- an admin page, a
+ * metadata endpoint. Whether that door opens silently depends on whether the session can ask a human
+ * at all: an interactive host can, an unattended one cannot and must refuse.
+ *
+ * WHAT `"allow"` AND AN APPROVAL CAN AND CANNOT REACH. `WebFetch` upgrades `http` to `https`
+ * unconditionally and refuses any hostname with fewer than two dot-separated labels -- both are the
+ * reference runtime's own rules, kept. So this policy governs an `https` service at an IPv4 literal
+ * (`https://127.0.0.1:8443/`) or at a name the URL parser leaves with two or more labels
+ * (`printer.local`, `api.localhost`). A plain-`http` port and every IPv6 literal (`[::1]` is one
+ * label) are unfetchable whatever this says -- a session pointed at one gets `Invalid URL` from the
+ * tool, and no approval is raised for it, because no answer could make it work.
+ */
+export type WebPrivateAddressPolicy = "allow" | "ask" | "deny";
+/** `WebSearch`'s own configuration. Every field is optional; see `WEB_TOOLS_DEFAULTS` (options.ts) for what absent means. */
+export interface WebSearchConfig {
+    /**
+     * The host's explicit OFF switch for the search BACKEND. Absent means enabled.
+     *
+     * The backend's anonymous tier needs no credential, so "is a search backend usable" is `true` for
+     * every session by default -- which would make the tool's capability gate a constant. This is the
+     * one fact that can make it `false`: a host that must not let a session reach the backend at all
+     * (an offline deployment, a policy that forbids the third-party endpoint). With `false` the tool is
+     * not advertised, and a call that reaches it anyway answers with a typed refusal.
+     *
+     * NOT a substitute for `disallowedTools`, which hides a tool the runtime has; this says the
+     * backend behind it is not there.
+     */
+    enabled?: boolean;
+    /**
+     * A reference to the search backend's API key -- the FALLBACK, used only once the anonymous tier
+     * is exhausted or rate-limited. A locator, never the key: the runtime resolves it at the last
+     * responsible moment and accepts EITHER JSON credential material (`{"kind":"api-key","key":...}`)
+     * OR a bare non-empty string, because a host that shares this keychain slot with another client
+     * cannot change what is stored in it. Absent means anonymous-only: an exhausted quota is then a
+     * typed "add a key" result, never an error that ends the turn.
+     */
+    authRef?: CredentialRef;
+    /**
+     * The most backend searches ONE `WebSearch` call may run while a key is in use (the inner model
+     * decides how many it needs, up to this). Absent means `WEB_TOOLS_DEFAULTS.maxSearchesPerCall`.
+     */
+    maxSearchesPerCall?: number;
+    /**
+     * The same bound while the call is riding the ANONYMOUS tier. Separate, and lower by default,
+     * because the anonymous tier is a small shared daily allowance: eight searches per call would
+     * spend it in a handful of calls and push every later one onto the key (or onto the "quota
+     * exhausted" result when there is no key). Absent means
+     * `WEB_TOOLS_DEFAULTS.anonymousMaxSearchesPerCall`.
+     */
+    anonymousMaxSearchesPerCall?: number;
+}
+/** `WebFetch`'s own configuration. Every field is optional; see `WEB_TOOLS_DEFAULTS` (options.ts) for what absent means. */
+export interface WebFetchConfig {
+    /**
+     * The model that digests a fetched page against the caller's prompt -- a provider-qualified tag
+     * (`<providerId>/<model>`) or a slot name, resolved through the SAME selection path as the session
+     * model.
+     *
+     * THE DEFAULT, stated plainly: when the host names none, the digest runs on the SESSION'S OWN
+     * MODEL. That is the one choice that is always resolvable and needs no second credential. There is
+     * deliberately no "cheapest slot" heuristic -- a family's slots are not reliably ranked
+     * strongest-to-weakest, so picking one by position would be a guess presented as a rule.
+     *
+     * A STATED model that cannot be resolved (unknown tag, disabled provider, no credential) is a
+     * typed refusal surfaced as the tool's RESULT. It is never a silent fallback onto the session's
+     * model: a host that named a small model did so to bound cost, and quietly spending the session
+     * model's price instead is the failure this field exists to prevent.
+     */
+    digestModel?: string;
+    /**
+     * The digest model's OWN credential, for a digest model on another provider than the session's
+     * (the cross-provider credential rule every auxiliary route follows: the route's own ref, else the
+     * session's material only when the provider is the same, else the target provider's
+     * `<providerId>:default` keychain record, else a typed `no-credential-for-provider`). The session's
+     * key is never sent to another provider. Ignored when `digestModel` is absent.
+     */
+    authRef?: CredentialRef;
+    /** See `WebPrivateAddressPolicy`. Absent means `WEB_TOOLS_DEFAULTS.privateAddressPolicy`. */
+    privateAddressPolicy?: WebPrivateAddressPolicy;
+}
+/**
+ * DISCLOSED WINTER option: the two web tools' configuration.
+ *
+ * `blockedDomains` sits at THIS level, not under either tool, because it is ONE list with ONE
+ * meaning -- the host's domain floor -- and both tools must honour it: `WebFetch` refuses a listed
+ * host outright, and `WebSearch` sends the list as the backend's exclusion filter on EVERY inner
+ * search, so a blocked domain can neither be fetched nor be surfaced as a link to fetch. Two lists
+ * would be two chances to update one and forget the other.
+ *
+ * MATCHING IS BY SUFFIX ON A LABEL BOUNDARY: listing `example.com` blocks `example.com` and every
+ * subdomain of it (`docs.example.com`), and does not block `notexample.com`. Entries are compared
+ * case-insensitively; a leading `*.` or `.` and a trailing `.` are ignored.
+ */
+export interface WebToolsConfig {
+    search?: WebSearchConfig;
+    fetch?: WebFetchConfig;
+    blockedDomains?: string[];
+}
+/**
+ * DISCLOSED WINTER option: the host's say over the auto-memory section.
+ *
+ * WHY IT EXISTS. The runtime computes the memory directory itself and reads `autoMemoryEnabled` /
+ * `autoMemoryDirectory` from SETTINGS FILES only. A host that turns settings files off
+ * (`settingSources: []`) therefore had no way to make the session agree with it about where memory
+ * lives, or to turn the section off -- the two sides could only agree by computing the same path by
+ * coincidence.
+ *
+ * PRECEDENCE, per field: this option, then the settings key, then the computed default
+ * (`<home>/projects/<memory-key>/memory`, enabled).
+ *
+ *   `enabled: false`  the auto-memory section and its index are omitted entirely, whatever settings
+ *                     say; `enabled: true` turns it on even over a settings `false`.
+ *   `directory`       REPLACES the computed path outright, with no per-project nesting beneath it
+ *                     (`~` and a cwd-relative path are expanded exactly as the settings key's are).
+ *                     Whitespace-only counts as absent.
+ *
+ * NOTE FOR A HOST RELOCATING THE DIRECTORY: the write-permission carve-out for memory files is keyed
+ * to the DEFAULT `projects/<key>/memory` shape under the home. A directory elsewhere under the
+ * home's `projects/` tree is still write-denied; one outside the home meets no floor at all and
+ * follows the session's ordinary write rules.
+ */
+export interface AutoMemoryConfig {
+    enabled?: boolean;
+    directory?: string;
+}
 /**
  * The pinned `ModelInfo` (`sdk.d.ts:1261-1300`): three required fields, six optional.
  *

package/dist/protocol/frames.d.ts

@@ -544,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";
@@ -568,7 +586,7 @@ export type SdkMessage = {
      */
     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/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.15",
+  "version": "0.0.17",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -45,15 +45,15 @@
     }
   },
   "dependencies": {
-    "@yanlinglabs/winter-provider-catalog": "0.0.15"
+    "@yanlinglabs/winter-provider-catalog": "0.0.17"
   },
   "optionalDependencies": {
-    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.15"
+    "@yanlinglabs/winter-agent-sdk-darwin-arm64": "0.0.17"
   },
   "devDependencies": {
     "@types/node": "^26.4.0",
-    "@yanlinglabs/winter-conformance": "0.0.15",
-    "winter-agent-runtime": "0.0.15"
+    "winter-agent-runtime": "0.0.17",
+    "@yanlinglabs/winter-conformance": "0.0.17"
   },
   "scripts": {}
 }