@yanlinglabs/winter-agent-sdk 0.0.17 → 0.0.22

package/dist/{index-qst9rwbb.js → index-0xks1t4r.js}

@@ -118,7 +118,7 @@ function resolveWinterHome2(env, brand) {
     return override;
   const profile = e[envName2(b, "PROFILE")];
   const dirName = profile !== undefined && profile.trim() === "dev" ? `${b.homeDirName}-dev` : b.homeDirName;
-  return join(homedir(), dirName);
+  return join(homedir(), dirName, "sdk");
 }
 function resolveKeychainServiceForProfile2(brand, env, hostSetKeychainService) {
   if (hostSetKeychainService)

package/dist/index.d.ts

@@ -27,11 +27,13 @@ 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, SDKSessionStateChangedMessage, 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, ControlCancelRequestFrame, WireResultUsage, 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";
 export type { CompatibilityKeys } from "./paths/keys.js";
+export { globalConfigFileName } from "./paths/global-config.js";
+export { storeHomeEnvName, pluginCacheDirEnvName, providerManagedByHostEnvName, disableCronEnvName } from "./paths/host-env.js";
 export { WinterCompatibilitySessionStore, WinterStoreError, WinterStoreLeaseError, DIALECT_RECORD_ENTRY_TYPE, PROVIDER_STATE_FILE_SUFFIX, } from "./store/session-store.js";
 export type { SessionKey, SessionStoreEntry, SessionSummaryEntry, SessionStore } from "./store/session-store.js";
 export { forkSessionByKey } from "./store/fork-session.js";
@@ -49,3 +51,7 @@ export type { PermissionUpdate, PermissionUpdateDestination, RuleSource } from "
 export type { CanUseTool, PermissionResult, PermissionDecisionClassification, PermissionRequestPayload } from "./permissions/types.js";
 export { HOOK_EVENTS } from "./permissions/types.js";
 export type { HookEvent, HookEventName, HookSource, HookPermissionDecision, BaseHookInput, PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput, UserPromptSubmitHookInput, StopHookInput, SessionStartHookInput, SessionEndHookInput, NotificationHookInput, PermissionRequestHookInput, PermissionDeniedHookInput, GenericHookInput, HookInput, AsyncHookJSONOutput, SyncHookJSONOutput, HookJSONOutput, PreToolUseHookSpecificOutput, PostToolUseHookSpecificOutput, PostToolUseFailureHookSpecificOutput, UserPromptSubmitHookSpecificOutput, StopHookSpecificOutput, SessionStartHookSpecificOutput, NotificationHookSpecificOutput, PermissionRequestHookSpecificOutput, PermissionDeniedHookSpecificOutput, GenericHookSpecificOutput, HookSpecificOutput, HookCallback, HookCallbackMatcher, HookInvocationPayload, } from "./permissions/types.js";
+export { CATALOG_TAG_RENAMES } from "@yanlinglabs/winter-provider-catalog";
+export { PluginManagerError, listMarketplaces, addMarketplace, removeMarketplace, updateMarketplace, installPlugin, uninstallPlugin, setPluginEnabled, updatePlugin, listPlugins } from "./plugins/manage.js";
+export type { PluginScope, PluginManagerOptions, MarketplaceInfo, InstalledPlugin, PluginListing } from "./plugins/manage.js";
+export { resolveMarketplacePluginPath } from "./plugins/marketplace-path.js";

package/dist/index.js

@@ -14,7 +14,7 @@ import {
   DIALECT_RECORD_ENTRY_TYPE2,
   PROVIDER_STATE_FILE_SUFFIX2,
   WinterCompatibilitySessionStore2
-} from "./index-qst9rwbb.js";
+} from "./index-0xks1t4r.js";
 import {
   deliveryUncertain2,
   refused2,
@@ -666,6 +666,7 @@ function query(args) {
     proc.stdin.write(encodeFrame(frame));
   }
   const controlRequestHandlers = new Map;
+  const incomingRequestAborts = new Map;
   async function handleIncomingControlRequest(cf) {
     try {
       const handler = controlRequestHandlers.get(cf.subtype);
@@ -678,8 +679,12 @@ function query(args) {
         });
         return;
       }
+      const cancel = new AbortController;
+      incomingRequestAborts.set(cf.requestId, cancel);
       try {
-        const result = await handler(cf.payload);
+        const result = await handler(cf.payload, { signal: cancel.signal });
+        if (cancel.signal.aborted)
+          return;
         if (result.ok) {
           writeControlResponse({
             type: "control_response",
@@ -691,19 +696,27 @@ function query(args) {
           writeControlResponse({ type: "control_response", requestId: cf.requestId, ok: false, error: result.error });
         }
       } catch (err) {
+        if (cancel.signal.aborted)
+          return;
         const message = err instanceof Error ? err.message : String(err);
         writeControlResponse({ type: "control_response", requestId: cf.requestId, ok: false, error: { code: "handler_threw", message } });
+      } finally {
+        incomingRequestAborts.delete(cf.requestId);
       }
     } catch {}
   }
   function makePermissionHandler(canUseTool) {
-    return async (payload) => {
+    return async (payload, handlerCtx) => {
       const req = payload;
       const controller = new AbortController;
       if (options.abortController?.signal.aborted)
         controller.abort();
       else
         options.abortController?.signal.addEventListener("abort", () => controller.abort(), { once: true });
+      if (handlerCtx?.signal.aborted === true)
+        controller.abort();
+      else
+        handlerCtx?.signal.addEventListener("abort", () => controller.abort(), { once: true });
       let result;
       try {
         result = await canUseTool(req.toolName, req.input, {
@@ -828,6 +841,13 @@ function query(args) {
               }
               continue;
             }
+            if (frame.type === "control_cancel_request") {
+              const cancelledId = frame.requestId ?? "";
+              const cancelled = incomingRequestAborts.get(cancelledId);
+              incomingRequestAborts.delete(cancelledId);
+              cancelled?.abort();
+              continue;
+            }
             if (frame.type === "control_request") {
               handleIncomingControlRequest(frame);
               continue;
@@ -1001,7 +1021,7 @@ function query(args) {
   return gen;
 }
 // src/version.ts
-var SDK_VERSION = "0.0.17";
+var SDK_VERSION = "0.0.22";
 // src/paths/project-key.ts
 var TRANSCRIPT_PROJECT_KEY_MAX_LENGTH = 64;
 var VENDOR_PROJECT_KEY_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
@@ -1044,13 +1064,41 @@ function resolveCanonical(raw) {
   }
 }
 function gitCommonRoot(resolvedCwd) {
+  let commonDir;
+  try {
+    const raw = runGit(["-C", resolvedCwd, "rev-parse", "--git-common-dir"]);
+    commonDir = platformNormalize(realpathSync(isAbsolute(raw) ? raw : resolvePath(resolvedCwd, raw)));
+  } catch {
+    return null;
+  }
+  const candidate = dirname2(commonDir);
+  if (isWithin(resolvedCwd, candidate))
+    return candidate;
+  if (registeredWorktrees(commonDir).some((worktree) => isWithin(resolvedCwd, worktree)))
+    return candidate;
+  const configured = configuredWorktree(commonDir);
+  if (configured !== null && isWithin(resolvedCwd, configured))
+    return configured;
+  return null;
+}
+function runGit(args) {
+  return execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+}
+function isWithin(path, dir) {
+  return path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`);
+}
+function registeredWorktrees(commonDir) {
+  try {
+    return runGit(["--git-dir", commonDir, "worktree", "list", "--porcelain"]).split(`
+`).filter((line) => line.startsWith("worktree ")).map((line) => resolveCanonical(line.slice("worktree ".length)));
+  } catch {
+    return [];
+  }
+}
+function configuredWorktree(commonDir) {
   try {
-    const raw = execFileSync("git", ["-C", resolvedCwd, "rev-parse", "--git-common-dir"], {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"]
-    }).trim();
-    const commonDir = isAbsolute(raw) ? raw : resolvePath(resolvedCwd, raw);
-    return platformNormalize(dirname2(realpathSync(commonDir)));
+    const raw = runGit(["--git-dir", commonDir, "config", "--get", "core.worktree"]);
+    return raw.length > 0 ? resolveCanonical(isAbsolute(raw) ? raw : resolvePath(commonDir, raw)) : null;
   } catch {
     return null;
   }
@@ -1062,6 +1110,23 @@ function compatibilityKeys(cwd) {
   const memoryKey = commonRoot === null ? cwdKey : transcriptProjectKey(commonRoot);
   return { transcriptProjectKey: cwdKey, memoryProjectKey: memoryKey, tempProjectKey: cwdKey };
 }
+// src/paths/global-config.ts
+function globalConfigFileName(brand) {
+  return `${brand.homeDirName}.json`;
+}
+// src/paths/host-env.ts
+function storeHomeEnvName(brand) {
+  return envName2(brand, "STORE_HOME");
+}
+function pluginCacheDirEnvName(brand) {
+  return envName2(brand, "PLUGIN_CACHE_DIR");
+}
+function providerManagedByHostEnvName(brand) {
+  return envName2(brand, "PROVIDER_MANAGED_BY_HOST");
+}
+function disableCronEnvName(brand) {
+  return envName2(brand, "DISABLE_CRON");
+}
 // src/store/fork-session.ts
 import { randomUUID as randomUUID2 } from "node:crypto";
 var IDENTITY_FIELDS = ["providerId", "modelKey", "adapterId", "adapterVersion", "catalogVersion", "authRef", "classifierPin"];
@@ -1394,6 +1459,45 @@ function unionRuleArray(tiersLowestFirst, key) {
   }
   return out.length > 0 ? out : undefined;
 }
+function unionSandboxFilesystemArray(tiersLowestFirst, key) {
+  const seen = new Set;
+  const out = [];
+  for (const tier of tiersLowestFirst) {
+    const sandbox = tier.values["sandbox"];
+    if (!isPlainObject2(sandbox))
+      continue;
+    const filesystem = sandbox["filesystem"];
+    if (!isPlainObject2(filesystem))
+      continue;
+    for (const rule of stringArrayOrUndefined(filesystem[key]) ?? []) {
+      if (seen.has(rule))
+        continue;
+      seen.add(rule);
+      out.push(rule);
+    }
+  }
+  return out.length > 0 ? out : undefined;
+}
+function unionSandboxFilesystemDenyArrays(effective, tiersLowestFirst) {
+  const mergedSandbox = effective["sandbox"];
+  const mergedFilesystem = isPlainObject2(mergedSandbox) ? mergedSandbox["filesystem"] : undefined;
+  const filesystem = isPlainObject2(mergedFilesystem) ? { ...mergedFilesystem } : {};
+  let any = isPlainObject2(mergedFilesystem);
+  for (const key of ["allowWrite", "denyWrite", "allowRead", "denyRead"]) {
+    const unioned = unionSandboxFilesystemArray(tiersLowestFirst, key);
+    if (unioned === undefined)
+      delete filesystem[key];
+    else {
+      filesystem[key] = unioned;
+      any = true;
+    }
+  }
+  if (!any)
+    return;
+  const sandbox = isPlainObject2(mergedSandbox) ? { ...mergedSandbox } : {};
+  sandbox["filesystem"] = filesystem;
+  effective["sandbox"] = sandbox;
+}
 function restrictProviderEnables(effective, tiersLowestFirst) {
   const disabled = new Set;
   for (const tier of tiersLowestFirst) {
@@ -1492,6 +1596,7 @@ async function resolveSettingsDetailed(opts = {}) {
   const overlayFilteredTiers = lowestFirst.map((entry) => ({ values: tierContribution(entry.values, entry.source === "project", trustedWorkspace) }));
   unionPermissionRuleArrays(effective, overlayFilteredTiers);
   restrictProviderEnables(effective, overlayFilteredTiers);
+  unionSandboxFilesystemDenyArrays(effective, overlayFilteredTiers);
   if (!trustedWorkspace) {
     const projectIndex = lowestFirst.findIndex((e) => e.source === "project");
     if (projectIndex !== -1) {
@@ -1692,9 +1797,394 @@ var HOOK_EVENTS = [
   "FileChanged",
   "DirectoryAdded"
 ];
+
+// src/index.ts
+import { CATALOG_TAG_RENAMES } from "@yanlinglabs/winter-provider-catalog";
+
+// src/plugins/manage.ts
+import { mkdir, open, readFile as readFile2, rename, rmdir, unlink, writeFile } from "node:fs/promises";
+import { dirname as dirname3, isAbsolute as isAbsolute2, join as join3, resolve as resolve2 } from "node:path";
+import { randomBytes } from "node:crypto";
+
+// src/plugins/marketplace-path.ts
+import { resolve, sep } from "node:path";
+var BARE_SOURCE_NAME = /^[A-Za-z0-9][-A-Za-z0-9._]*$/;
+function isBareSourceName(source) {
+  return BARE_SOURCE_NAME.test(source) && !source.includes("..");
+}
+function normalizePluginRoot(pluginRoot) {
+  if (typeof pluginRoot !== "string" || pluginRoot === "" || pluginRoot.startsWith("/") || pluginRoot.includes("\\") || pluginRoot.includes(":"))
+    return;
+  const stripped = pluginRoot.replace(/^\.\//, "").replace(/\/+$/, "");
+  if (stripped === "" || stripped === ".")
+    return ".";
+  if (stripped.split("/").some((segment) => segment === "" || segment === "." || segment === ".."))
+    return;
+  return stripped;
+}
+function withPluginRootPrefix(source, normalizedRoot) {
+  if (normalizedRoot === undefined || !isBareSourceName(source))
+    return source;
+  return normalizedRoot === "." ? `./${source}` : `./${normalizedRoot}/${source}`;
+}
+function schemaSourcePath(source) {
+  const normalized = source === "." ? "./" : source;
+  return normalized.startsWith("./") ? normalized : undefined;
+}
+function resolveWithinBase(base, relativePath) {
+  const normalizedBase = resolve(base);
+  const resolved = resolve(base, relativePath);
+  if (resolved !== normalizedBase && !resolved.startsWith(normalizedBase + sep)) {
+    throw new Error(`Path traversal detected: "${relativePath}" would escape the base directory`);
+  }
+  return resolved;
+}
+function resolveMarketplacePluginPath(installLocation, pluginRoot, source) {
+  if (typeof source !== "string" || source === "")
+    return;
+  const normalizedRoot = normalizePluginRoot(pluginRoot);
+  const prefixed = withPluginRootPrefix(source, normalizedRoot);
+  const sourcePath = schemaSourcePath(prefixed);
+  if (sourcePath === undefined)
+    return;
+  try {
+    return resolveWithinBase(installLocation, sourcePath);
+  } catch {
+    return;
+  }
+}
+
+// src/plugins/manage.ts
+class PluginManagerError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PluginManagerError";
+  }
+}
+function installedPluginsPath(o) {
+  return join3(o.pluginsRoot, "installed_plugins.json");
+}
+function knownMarketplacesPath(o) {
+  return join3(o.pluginsRoot, "known_marketplaces.json");
+}
+function isEnoent(err) {
+  return err?.code === "ENOENT";
+}
+var RETRYABLE_RENAME_CODES = new Set(["EXDEV", "EPERM", "EEXIST", "EBUSY"]);
+async function writeJsonAtomicNoLock(path, data) {
+  const body = `${JSON.stringify(data, null, 2)}
+`;
+  const tmp = `${path}.tmp.${randomBytes(4).toString("hex")}`;
+  let created = false;
+  try {
+    const handle = await open(tmp, "wx", 384);
+    created = true;
+    try {
+      await handle.writeFile(body, "utf8");
+    } finally {
+      await handle.close();
+    }
+    await rename(tmp, path);
+  } catch (err) {
+    const code = err?.code;
+    if (code === undefined || !RETRYABLE_RENAME_CODES.has(code))
+      throw err;
+    await writeFile(path, body, { encoding: "utf8", mode: 384 });
+    if (created) {
+      try {
+        await unlink(tmp);
+      } catch (cleanupErr) {
+        if (!isEnoent(cleanupErr))
+          throw cleanupErr;
+      }
+    }
+  }
+}
+async function readInstalledPluginsFile(o) {
+  try {
+    const raw = await readFile2(installedPluginsPath(o), "utf8");
+    const parsed = JSON.parse(raw);
+    const plugins = parsed !== null && typeof parsed === "object" && typeof parsed.plugins === "object" && parsed.plugins !== null ? parsed.plugins : {};
+    return { version: 2, plugins };
+  } catch (err) {
+    if (isEnoent(err))
+      return { version: 2, plugins: {} };
+    throw err;
+  }
+}
+var MARKETPLACES_LOCK_ATTEMPTS = 25;
+var MARKETPLACES_LOCK_RETRY_DELAY_MS = 20;
+async function withMarketplacesLock(path, fn) {
+  const lockPath = `${path}.lock`;
+  let acquired = false;
+  for (let attempt = 0;attempt < MARKETPLACES_LOCK_ATTEMPTS; attempt++) {
+    try {
+      await mkdir(lockPath);
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err?.code !== "EEXIST")
+        throw err;
+      await new Promise((r) => setTimeout(r, MARKETPLACES_LOCK_RETRY_DELAY_MS));
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    if (acquired) {
+      try {
+        await rmdir(lockPath);
+      } catch (err) {
+        if (!isEnoent(err))
+          throw err;
+      }
+    }
+  }
+}
+async function readKnownMarketplacesFile(o) {
+  try {
+    const raw = await readFile2(knownMarketplacesPath(o), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch (err) {
+    if (isEnoent(err))
+      return {};
+    throw err;
+  }
+}
+async function writeKnownMarketplacesFile(path, file) {
+  await writeJsonAtomicNoLock(path, file);
+}
+async function readDirectoryMarketplaceManifest(marketplaceDir) {
+  const manifestPath = join3(marketplaceDir, ".claude-plugin", "marketplace.json");
+  let raw;
+  try {
+    raw = await readFile2(manifestPath, "utf8");
+  } catch (err) {
+    if (isEnoent(err))
+      throw new PluginManagerError(`${manifestPath}: no marketplace manifest there (expected .claude-plugin/marketplace.json under ${marketplaceDir})`);
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new PluginManagerError(`${manifestPath}: malformed JSON (${err.message})`);
+  }
+  if (typeof parsed !== "object" || parsed === null)
+    throw new PluginManagerError(`${manifestPath}: expected a JSON object at the top level`);
+  const obj = parsed;
+  if (typeof obj.name !== "string" || obj.name.length === 0)
+    throw new PluginManagerError(`${manifestPath}: missing required "name"`);
+  if (!Array.isArray(obj.plugins))
+    throw new PluginManagerError(`${manifestPath}: missing required "plugins" array`);
+  return {
+    name: obj.name,
+    plugins: obj.plugins,
+    ...obj.version !== undefined ? { version: obj.version } : {},
+    ...obj.description !== undefined ? { description: obj.description } : {},
+    ...obj.metadata !== undefined ? { metadata: obj.metadata } : {}
+  };
+}
+function classifySource(source) {
+  if (/^https?:\/\//i.test(source))
+    return { kind: "url", locator: source };
+  if (/^git@[^:]+:/i.test(source) || /^git\+/i.test(source) || /\.git$/i.test(source))
+    return { kind: "git", locator: source };
+  if (/^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?\/[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/.test(source) && !source.includes("..")) {
+    return { kind: "github", locator: source };
+  }
+  return { kind: "directory", locator: isAbsolute2(source) ? source : resolve2(source) };
+}
+function marketplaceInfoOf(name, record) {
+  const kind = record.source.source;
+  const source = record.source.path ?? record.source.url ?? record.source.repo ?? record.installLocation;
+  return { name, source, kind, path: record.installLocation };
+}
+function parseSpec(spec) {
+  const at = spec.lastIndexOf("@");
+  if (at <= 0 || at === spec.length - 1) {
+    throw new PluginManagerError(`plugin spec must be "<name>@<marketplace>" (got ${JSON.stringify(spec)}) -- bare-name marketplace inference is not implemented in this build`);
+  }
+  return { name: spec.slice(0, at), marketplace: spec.slice(at + 1) };
+}
+function keyFor(name, marketplace) {
+  return `${name}@${marketplace}`;
+}
+async function readEnabledFromSettings(o, scope, key) {
+  const loaded = await loadSettingsFile(o.settingsPathFor(scope));
+  return loaded.values.enabledPlugins?.[key] === true;
+}
+function assertSettingsWritable(loaded, path) {
+  if (loaded.present && !loaded.loaded) {
+    throw new PluginManagerError(`${path}: cannot update enabledPlugins -- the file exists but ${loaded.error ?? "could not be read"}; fix it by hand first`);
+  }
+}
+async function setEnabledInSettings(o, scope, key, enabled) {
+  const path = o.settingsPathFor(scope);
+  const loaded = await loadSettingsFile(path);
+  assertSettingsWritable(loaded, path);
+  const settings = { ...loaded.values };
+  const enabledPlugins = { ...settings.enabledPlugins ?? {} };
+  if (enabled === undefined)
+    delete enabledPlugins[key];
+  else
+    enabledPlugins[key] = enabled;
+  settings.enabledPlugins = enabledPlugins;
+  await mkdir(dirname3(path), { recursive: true });
+  await writeJsonAtomicNoLock(path, settings);
+}
+async function listMarketplaces(o) {
+  const file = await readKnownMarketplacesFile(o);
+  return Object.entries(file).map(([name, rec]) => marketplaceInfoOf(name, rec));
+}
+async function addMarketplace(o, source) {
+  const classification = classifySource(source);
+  if (classification.kind !== "directory") {
+    throw new PluginManagerError(`marketplace source kind "${classification.kind}" is not supported in this build (no network) -- only local directory marketplaces can be added; got ${JSON.stringify(source)}`);
+  }
+  const dir = classification.locator;
+  const manifest = await readDirectoryMarketplaceManifest(dir);
+  await mkdir(o.pluginsRoot, { recursive: true });
+  const path = knownMarketplacesPath(o);
+  const record = {
+    source: { source: "directory", path: dir },
+    installLocation: dir,
+    lastUpdated: new Date().toISOString(),
+    autoUpdate: false
+  };
+  await withMarketplacesLock(path, async () => {
+    const file = await readKnownMarketplacesFile(o);
+    file[manifest.name] = record;
+    await writeKnownMarketplacesFile(path, file);
+  });
+  return marketplaceInfoOf(manifest.name, record);
+}
+async function removeMarketplace(o, name) {
+  const path = knownMarketplacesPath(o);
+  await withMarketplacesLock(path, async () => {
+    const file = await readKnownMarketplacesFile(o);
+    if (!(name in file))
+      throw new PluginManagerError(`marketplace "${name}" is not known`);
+    delete file[name];
+    await writeKnownMarketplacesFile(path, file);
+  });
+}
+async function updateMarketplace(o, name) {
+  const path = knownMarketplacesPath(o);
+  await withMarketplacesLock(path, async () => {
+    const file = await readKnownMarketplacesFile(o);
+    const names = name !== undefined ? [name] : Object.keys(file);
+    for (const n of names) {
+      const rec = file[n];
+      if (rec === undefined)
+        throw new PluginManagerError(`marketplace "${n}" is not known`);
+      if (rec.source.source !== "directory") {
+        throw new PluginManagerError(`marketplace "${n}" has source kind "${rec.source.source}", which this build cannot refresh (no network)`);
+      }
+      await readDirectoryMarketplaceManifest(rec.installLocation);
+      rec.lastUpdated = new Date().toISOString();
+    }
+    await writeKnownMarketplacesFile(path, file);
+  });
+}
+async function resolvePluginSourcePath(o, name, marketplace) {
+  const marketplaces = await readKnownMarketplacesFile(o);
+  const rec = marketplaces[marketplace];
+  if (rec === undefined)
+    throw new PluginManagerError(`marketplace "${marketplace}" is not known -- add it first`);
+  if (rec.source.source !== "directory") {
+    throw new PluginManagerError(`marketplace "${marketplace}" has source kind "${rec.source.source}", which this build cannot install from (no network)`);
+  }
+  const manifest = await readDirectoryMarketplaceManifest(rec.installLocation);
+  const entry = manifest.plugins.find((p) => p.name === name);
+  if (entry === undefined)
+    throw new PluginManagerError(`plugin "${name}" is not listed by marketplace "${marketplace}"`);
+  if (typeof entry.source !== "string") {
+    throw new PluginManagerError(`plugin "${name}@${marketplace}" declares a non-local source, which this build cannot install (no network)`);
+  }
+  const installPath = resolveMarketplacePluginPath(rec.installLocation, manifest.metadata?.pluginRoot, entry.source);
+  if (installPath === undefined) {
+    throw new PluginManagerError(`plugin "${name}@${marketplace}" declares a source (${JSON.stringify(entry.source)}) this build refuses to resolve -- it must be a "./relative/path" under the marketplace root (or a bare name when the marketplace's own metadata.pluginRoot is set), and must not escape the marketplace directory`);
+  }
+  return { installPath, version: entry.version };
+}
+async function installPlugin(o, spec, scope) {
+  const { name, marketplace } = parseSpec(spec);
+  const settingsPath = o.settingsPathFor(scope);
+  assertSettingsWritable(await loadSettingsFile(settingsPath), settingsPath);
+  const { installPath, version } = await resolvePluginSourcePath(o, name, marketplace);
+  const key = keyFor(name, marketplace);
+  await mkdir(o.pluginsRoot, { recursive: true });
+  const now = new Date().toISOString();
+  const record = { scope, installPath, installedAt: now, ...version !== undefined ? { version } : {} };
+  const file = await readInstalledPluginsFile(o);
+  const existing = file.plugins[key] ?? [];
+  file.plugins[key] = [...existing.filter((r) => r.scope !== scope), record];
+  await writeJsonAtomicNoLock(installedPluginsPath(o), file);
+  await setEnabledInSettings(o, scope, key, true);
+  return { id: name, installPath, scope, ...version !== undefined ? { version } : {} };
+}
+async function uninstallPlugin(o, spec, scope) {
+  const { name, marketplace } = parseSpec(spec);
+  const key = keyFor(name, marketplace);
+  const settingsPath = o.settingsPathFor(scope);
+  assertSettingsWritable(await loadSettingsFile(settingsPath), settingsPath);
+  const file = await readInstalledPluginsFile(o);
+  const existing = file.plugins[key];
+  const remaining = (existing ?? []).filter((r) => r.scope !== scope);
+  if (existing === undefined || remaining.length === existing.length) {
+    throw new PluginManagerError(`plugin "${key}" is not installed at scope "${scope}"`);
+  }
+  if (remaining.length > 0)
+    file.plugins[key] = remaining;
+  else
+    delete file.plugins[key];
+  await writeJsonAtomicNoLock(installedPluginsPath(o), file);
+  await setEnabledInSettings(o, scope, key, undefined);
+}
+async function setPluginEnabled(o, spec, scope, enabled) {
+  const { name, marketplace } = parseSpec(spec);
+  const key = keyFor(name, marketplace);
+  const file = await readInstalledPluginsFile(o);
+  if (!(file.plugins[key]?.some((r) => r.scope === scope) ?? false)) {
+    throw new PluginManagerError(`plugin "${key}" is not installed at scope "${scope}"`);
+  }
+  await setEnabledInSettings(o, scope, key, enabled);
+}
+async function updatePlugin(o, spec) {
+  const { name, marketplace } = parseSpec(spec);
+  const key = keyFor(name, marketplace);
+  const file = await readInstalledPluginsFile(o);
+  const records = file.plugins[key];
+  if (records === undefined || records.length === 0)
+    throw new PluginManagerError(`plugin "${key}" is not installed`);
+  const { installPath, version } = await resolvePluginSourcePath(o, name, marketplace);
+  const now = new Date().toISOString();
+  const updated = records.map((r) => ({ ...r, installPath, lastUpdated: now, ...version !== undefined ? { version } : {} }));
+  file.plugins[key] = updated;
+  await writeJsonAtomicNoLock(installedPluginsPath(o), file);
+  const last = updated[updated.length - 1];
+  return { id: name, installPath, scope: last.scope, ...version !== undefined ? { version } : {} };
+}
+async function listPlugins(o) {
+  const file = await readInstalledPluginsFile(o);
+  const out = [];
+  for (const [key, records] of Object.entries(file.plugins)) {
+    const at = key.lastIndexOf("@");
+    const name = at > 0 ? key.slice(0, at) : key;
+    const marketplace = at > 0 ? key.slice(at + 1) : "";
+    for (const rec of records) {
+      const enabled = await readEnabledFromSettings(o, rec.scope, key);
+      out.push({ id: name, installPath: rec.installPath, scope: rec.scope, enabled, marketplace, ...rec.version !== undefined ? { version: rec.version } : {} });
+    }
+  }
+  return out;
+}
 export {
   AbortError,
   BRAND_TOKEN_RE2 as BRAND_TOKEN_RE,
+  CATALOG_TAG_RENAMES,
   CLIConnectionError,
   DEFAULT_COMPACTION_THRESHOLD,
   DEFAULT_CONTEXT_WINDOW_TOKENS,
@@ -1715,6 +2205,7 @@ export {
   PROJECT_PERMISSIVE_KEYS,
   PROTOCOL_VERSION,
   PROVIDER_STATE_FILE_SUFFIX2 as PROVIDER_STATE_FILE_SUFFIX,
+  PluginManagerError,
   ProcessError,
   ProtocolDecodeError,
   ProtocolError,
@@ -1732,11 +2223,13 @@ export {
   WinterSDKError,
   WinterStoreError2 as WinterStoreError,
   WinterStoreLeaseError2 as WinterStoreLeaseError,
+  addMarketplace,
   applyWorkspaceTrust,
   compatibilityKeys,
   decodeFrame,
   defaultSpawn,
   deleteSession,
+  disableCronEnvName,
   encodeFrame,
   envName2 as envName,
   filterEscalatingDefaultMode,
@@ -1745,6 +2238,8 @@ export {
   getSessionInfo,
   getSessionMessages,
   getSubagentMessages,
+  globalConfigFileName,
+  installPlugin,
   isDeliveryOutcome,
   isGlobalAgentMessage,
   isListedRuntimeObjectArray,
@@ -1760,25 +2255,36 @@ export {
   isUnset2 as isUnset,
   isVendorCompliantProjectKey,
   isWinterMcpServerInstance,
+  listMarketplaces,
+  listPlugins,
   listSessions,
   listSubagents,
   loadSettingsFile,
   mcpToolName2 as mcpToolName,
+  pluginCacheDirEnvName,
+  providerManagedByHostEnvName,
   providerSettingsFrom,
   query,
+  removeMarketplace,
   renameSession,
   resolveBrand2 as resolveBrand,
   resolveFacetTarget,
   resolveKeychainServiceForProfile2 as resolveKeychainServiceForProfile,
+  resolveMarketplacePluginPath,
   resolveRuntimeExecutable,
   resolveSettings,
   resolveSettingsDetailed,
   resolveWebToolsConfig,
   resolveWinterHome2 as resolveWinterHome,
+  setPluginEnabled,
   settingsPathFor,
   splitFrames,
+  storeHomeEnvName,
   tagSession,
   transcriptProjectKey,
+  uninstallPlugin,
+  updateMarketplace,
+  updatePlugin,
   userAgent2 as userAgent,
   validateModelSlots
 };

package/dist/options.d.ts

@@ -275,7 +275,9 @@ export interface Options {
     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:
+     * selection path -- a provider-qualified tag (`<providerId>/<model>`) names its own provider, so a
+     * reviewer on another provider than the session's is just that tag plus that provider's credential
+     * (the `web.fetch.digestModel` shape). 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.

package/dist/paths/global-config.d.ts

@@ -0,0 +1,7 @@
+import type { BrandProfile } from "../brand.js";
+/**
+ * `<brand.homeDirName>.json` -- `.winter.json` for Winter's own brand. `brand.homeDirName` is
+ * documented (`brand.ts`) as never containing a slash, so this is always a single path segment,
+ * safe to `join` onto any directory without further validation.
+ */
+export declare function globalConfigFileName(brand: Pick<BrandProfile, "homeDirName">): string;

package/dist/paths/home.d.ts

@@ -19,9 +19,21 @@ export type HomeBrand = Pick<BrandProfile, "envPrefix" | "homeDirName">;
  * (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.
+ * `<PREFIX>HOME` wins over EVERYTHING, including the dev profile and the WS-21 `sdk` suffix below.
+ * `<PREFIX>PROFILE=dev` selects `~/<homeDirName>-dev/sdk` — 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.
+ *
+ * WS-21 §6.3 item 8: the DEFAULT (no `<PREFIX>HOME`, no explicit `brand`-threaded value) is now
+ * `~/<homeDirName>/sdk`, not `~/<homeDirName>` -- Contract A's `sdkHomeOf(home) = join(home, "sdk")`,
+ * inlined here rather than imported (the router that exports it is a separate package this SDK
+ * never depends on). `brand.homeDirName` cannot contain a slash (`brand.ts`'s own validation), so
+ * this is always exactly one extra path segment. This changes ONLY the bare-default case: every
+ * router-routed session gets an EXPLICIT `WINTER_HOME` (the Global Constraints list: "only the
+ * router sets ... WINTER_HOME"), which still wins outright, and the daemon's own pre-router-link
+ * fallback threads its own value too (`session-driver.ts`'s `WINTER_HOME` default, unaffected by
+ * this function). A bare `winter` invocation with no env override is the only caller this moves --
+ * consistent with the shared runtime home being the thing the SDK itself now means by "home".
  */
 export declare function resolveWinterHome(env?: Record<string, string | undefined>, brand?: HomeBrand): string;
 /**

package/dist/paths/host-env.d.ts

@@ -0,0 +1,11 @@
+import { type BrandProfile } from "../brand.js";
+type EnvPrefixBrand = Pick<BrandProfile, "envPrefix">;
+/** `WINTER_STORE_HOME` -- the shared runtime home's durable-paths root (spec §3.7). No claude twin. */
+export declare function storeHomeEnvName(brand: EnvPrefixBrand): string;
+/** `WINTER_PLUGIN_CACHE_DIR` -- the twin of `CLAUDE_CODE_PLUGIN_CACHE_DIR` (F15). */
+export declare function pluginCacheDirEnvName(brand: EnvPrefixBrand): string;
+/** `WINTER_PROVIDER_MANAGED_BY_HOST` -- the twin of `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` (F20). */
+export declare function providerManagedByHostEnvName(brand: EnvPrefixBrand): string;
+/** `WINTER_DISABLE_CRON` -- the twin of `CLAUDE_CODE_DISABLE_CRON` (F19a). */
+export declare function disableCronEnvName(brand: EnvPrefixBrand): string;
+export {};

package/dist/plugins/manage.d.ts

@@ -0,0 +1,37 @@
+export declare class PluginManagerError extends Error {
+    constructor(message: string);
+}
+export type PluginScope = "user" | "project" | "local";
+export interface PluginManagerOptions {
+    /** claude's plugins root (WS-21 §6.3 item 5: `storeHome/plugins`) -- `installed_plugins.json` and `known_marketplaces.json` live directly under it. */
+    pluginsRoot: string;
+    /** The `enabledPlugins` carrier for one scope -- the settings file at that tier (the shared runtime home's own `settings.json` for `user`; the project dir's `settings.json`/`settings.local.json` for `project`/`local`). */
+    settingsPathFor(scope: PluginScope): string;
+}
+export interface MarketplaceInfo {
+    name: string;
+    /** The human-facing locator: the directory path, the repo `owner/repo`, or the URL -- whichever the source kind carries. */
+    source: string;
+    kind: "directory" | "git" | "github" | "url";
+    /** Where the marketplace's own content lives on disk. For `directory`, this IS the source (read in place, F15). */
+    path: string;
+}
+export interface InstalledPlugin {
+    id: string;
+    version?: string;
+    installPath: string;
+    scope: PluginScope;
+}
+export interface PluginListing extends InstalledPlugin {
+    enabled: boolean;
+    marketplace: string;
+}
+export declare function listMarketplaces(o: PluginManagerOptions): Promise<MarketplaceInfo[]>;
+export declare function addMarketplace(o: PluginManagerOptions, source: string): Promise<MarketplaceInfo>;
+export declare function removeMarketplace(o: PluginManagerOptions, name: string): Promise<void>;
+export declare function updateMarketplace(o: PluginManagerOptions, name?: string): Promise<void>;
+export declare function installPlugin(o: PluginManagerOptions, spec: string, scope: PluginScope): Promise<InstalledPlugin>;
+export declare function uninstallPlugin(o: PluginManagerOptions, spec: string, scope: PluginScope): Promise<void>;
+export declare function setPluginEnabled(o: PluginManagerOptions, spec: string, scope: PluginScope, enabled: boolean): Promise<void>;
+export declare function updatePlugin(o: PluginManagerOptions, spec: string): Promise<InstalledPlugin>;
+export declare function listPlugins(o: PluginManagerOptions): Promise<PluginListing[]>;

package/dist/plugins/marketplace-path.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Resolve one marketplace manifest plugin entry's install path -- the ONE function
+ * `packages/runtime/src/plugins/installed.ts` (the daemon's own directory-marketplace fallback,
+ * SV-4) and `packages/sdk/src/plugins/manage.ts` (`resolvePluginSourcePath`, the CLI-facing install
+ * command) both call, so the two can never resolve the identical manifest entry to two different
+ * paths. `undefined` for anything invalid or refused -- a bare name with no usable `pluginRoot`, an
+ * absolute/malformed source, or a path that would escape `installLocation` -- NEVER a throw a
+ * caller must remember to catch; each caller renders its own typed rejection from `undefined`.
+ */
+export declare function resolveMarketplacePluginPath(installLocation: string, pluginRoot: unknown, source: unknown): string | undefined;

package/dist/protocol/config.d.ts

@@ -88,7 +88,9 @@ export interface SandboxSettingsConfig {
     filesystem?: {
         allowWrite?: string[];
         denyWrite?: string[];
+        allowRead?: string[];
         denyRead?: string[];
+        allowGitConfig?: boolean;
     };
     network?: {
         allowedDomains?: string[];
@@ -219,6 +221,17 @@ export interface RuntimeConfig {
     resumeDropsTurn?: boolean;
     persistSession?: boolean;
     winterHome?: string;
+    /**
+     * WS-21 §3.7/§6.3 item 11: the shared runtime home's durable-paths root (`storeHomeEnvName`'s
+     * value) and the claude-`CLAUDE_CODE_PLUGIN_CACHE_DIR` twin, next to `winterHome` for a host that
+     * assembles `--config-json` directly rather than only setting the child's env. The CANONICAL
+     * channel is still the child's own env (`production-wiring.ts` reads `config.storeHome ??
+     * env[storeHomeEnvName(brand)]`, the same precedence `winterHome` already has over
+     * `resolveWinterHome(env, brand)`) -- these two fields exist so a host with no separate env-setting
+     * step has an equivalent one.
+     */
+    storeHome?: string;
+    pluginCacheDir?: string;
     allowedTools?: string[];
     disallowedTools?: string[];
     permissions?: {
@@ -473,6 +486,18 @@ export interface AutoClassifierConfig {
  * advisor's provider, the advisor's provider refuses with a typed `no-credential-for-provider`.
  */
 export interface AdvisorConfig {
+    /**
+     * The reviewer's model: a PROVIDER-QUALIFIED TAG (`<providerId>/<model>`, e.g.
+     * `codex-oauth/gpt-5.6-sol`) or a slot name, resolved through the SAME selection path as the
+     * session model -- exactly as `WebFetchConfig.digestModel` is.
+     *
+     * THE TAG IS THE PROVIDER IDENTITY; there is deliberately no second field for it. A qualified tag
+     * resolves under ITS OWN provider, never under the session's (`Options.provider`), so an advisor on
+     * another provider than the session's needs nothing but that tag and, in `authRef`, that provider's
+     * own credential. A host that splits the tag down to a bare model id before passing it has thrown
+     * the provider away: a bare id is read as a slot name or canonical id and resolved by the session's
+     * slot rules, which is a different question.
+     */
     model: string;
     authRef?: CredentialRef;
 }

package/dist/protocol/frames.d.ts

@@ -42,11 +42,56 @@ export interface ControlResponseFrame {
         message: string;
     };
 }
+/**
+ * Runtime -> host: "I stopped waiting for control_request `requestId`" (lane C, C2 -- claude parity:
+ * claude's structuredIO writes `control_cancel_request` when a pending request's signal aborts, e.g.
+ * a turn interrupted while a permission prompt is open). The host aborts the callback it is running
+ * for that request (`canUseTool`'s `signal`) and owes no response; one sent anyway is dropped.
+ */
+/**
+ * `result.usage`: claude's `NonNullableUsage` (every `BetaUsage` field, none null), carrying THIS
+ * turn's main-loop generations -- claude builds a fresh QueryEngine per prompt in SDK mode, so its
+ * `totalUsage` starts at EMPTY_USAGE each turn. The four token counts are real; the rest is filled the
+ * way the pinned binary's own EMPTY_USAGE fills a value it has no data for, and says so:
+ *   - `cache_creation`: every cache write Winter marks is the default 5-minute ephemeral one (the
+ *     adapters send `{type: "ephemeral"}` with no ttl), so `ephemeral_5m_input_tokens` equals
+ *     `cache_creation_input_tokens` and `ephemeral_1h_input_tokens` is 0;
+ *   - `server_tool_use`: Winter's WebSearch/WebFetch run client-side, never as billed server tools: 0/0;
+ *   - `output_tokens_details.thinking_tokens`: 0 -- providers' reasoning-token counts are not threaded
+ *     through Winter's usage yet (they are included in `output_tokens`);
+ *   - `service_tier: "standard"`, `inference_geo: ""`, `iterations: []`, `speed: "standard"`: the
+ *     pinned EMPTY_USAGE's own values.
+ */
+export interface WireResultUsage {
+    output_tokens_details: {
+        thinking_tokens: number;
+    };
+    input_tokens: number;
+    cache_creation_input_tokens: number;
+    cache_read_input_tokens: number;
+    output_tokens: number;
+    server_tool_use: {
+        web_search_requests: number;
+        web_fetch_requests: number;
+    };
+    service_tier: "standard" | "priority" | "batch";
+    cache_creation: {
+        ephemeral_1h_input_tokens: number;
+        ephemeral_5m_input_tokens: number;
+    };
+    inference_geo: string;
+    iterations: unknown[];
+    speed: "standard" | "fast";
+}
+export interface ControlCancelRequestFrame {
+    type: "control_cancel_request";
+    requestId: string;
+}
 export interface UnknownFrame {
     type: string;
     [k: string]: unknown;
 }
-export type WinterFrame = InitFrame | UserFrame | DataFrame | ControlRequestFrame | ControlResponseFrame | UnknownFrame;
+export type WinterFrame = InitFrame | UserFrame | DataFrame | ControlRequestFrame | ControlResponseFrame | ControlCancelRequestFrame | UnknownFrame;
 export interface SDKHookStartedMessage {
     type: "system";
     subtype: "hook_started";
@@ -618,6 +663,8 @@ export type SdkMessage = {
     structured_output?: unknown;
     terminal_reason?: "structured_output_retry_exhausted" | "api_error" | string;
     api_error_status?: number | null;
+    /** THIS turn's main-loop usage -- claude's `result.usage` (dist-session fixes C1); see `WireResultUsage`. */
+    usage?: WireResultUsage;
     permission_denials: SDKPermissionDenial[];
     [k: string]: unknown;
 } | {

package/dist/query.d.ts

@@ -21,7 +21,14 @@ export type ControlRequestHandlerResult = {
         message: string;
     };
 };
-export type ControlRequestHandler = (payload: unknown) => Promise<ControlRequestHandlerResult>;
+/**
+ * A handler for one runtime-originated control_request subtype. `ctx.signal` aborts when the runtime
+ * CANCELS the request (`control_cancel_request` -- lane C, C2, claude parity): the handler should stop
+ * waiting, and whatever it returns afterwards is not sent (the runtime already stopped waiting).
+ */
+export type ControlRequestHandler = (payload: unknown, ctx?: {
+    signal: AbortSignal;
+}) => Promise<ControlRequestHandlerResult>;
 export interface QueryInternal {
     registerControlRequestHandler(subtype: string, handler: ControlRequestHandler): void;
     respondPermission(requestId: string, result: PermissionResult): void;

package/dist/settings/types.d.ts

@@ -5,7 +5,7 @@ import type { BrandProfile } from "../brand.js";
  * caller can thread three fields rather than construct one.
  */
 export type SettingsBrand = Pick<BrandProfile, "envPrefix" | "homeDirName" | "projectDirName">;
-import type { ModelSlotSetting } from "../protocol/config.js";
+import type { ModelSlotSetting, SandboxSettingsConfig } from "../protocol/config.js";
 /** The three settings FILE tiers a session may load. `sdk.d.ts:7917`, verbatim and in pinned order. */
 export type SettingSource = "user" | "project" | "local";
 /** Pinned order (`sdk.d.ts:7917`). Also the value `settingSources: undefined` means (all three). */
@@ -39,6 +39,35 @@ export interface SettingsPermissionsBlock {
 }
 export interface Settings {
     permissions?: SettingsPermissionsBlock;
+    /**
+     * SV-11 (WS-21 fix round 9, security): the CC-shaped sandbox configuration surface, same shape as
+     * `RuntimeConfig.sandbox` (`protocol/config.ts`'s own `SandboxSettingsConfig`, kept structurally
+     * identical to `packages/runtime/src/sandbox/profile.ts`'s `SandboxSettings` for the same
+     * WS-02 §3 reason that type's own header states). Before this field existed, Winter's runtime read
+     * ONLY the host-supplied `RuntimeConfig.sandbox`, ignoring `settings.json`'s own `sandbox` block
+     * entirely -- a denied write from a plain, un-escalated `sandbox.filesystem.denyWrite` path went
+     * through unsandboxed, silently, because nothing ever threaded that key into the running sandbox at
+     * all (not a merge-precedence bug; there was no merge). `production-wiring.ts` now feeds the host's
+     * own `RuntimeConfig.sandbox` into this resolution as the `flag` tier (claude's own architecture:
+     * its SDK `Options` occupies the identical tier position for this same setting), and reads the
+     * result back off `effective.sandbox` into the config it actually hands the engine.
+     *
+     * ALL FOUR `filesystem` arrays -- `allowWrite`, `denyWrite`, `allowRead`, `denyRead` -- UNION
+     * across every tier (deep-merge's ordinary replace-by-higher-tier would let a higher tier
+     * silently drop a lower tier's own restriction -- the identical fail-open shape
+     * `permissions.deny`'s own union exists to prevent; see `unionSandboxFilesystemDenyArrays` below).
+     * CORRECTED in fix round 10, item C: round 9 reasoned `allowWrite` should NOT union (a widening
+     * key should never accumulate) and used the ordinary replace-by-higher-tier merge for it instead
+     * -- the controller's round-10 ruling reverses this, dump-confirmed against claude's own live
+     * sandbox-reconciliation code unioning its OWN rule-derived allowWrite set with the native
+     * sandbox's currently-configured one (`xr=se([...yr,...$r.filter(...)])`, not a replacement).
+     * Claude itself unions the widening array too; ported here to match. `allowRead` (also new this
+     * round) is claude's own read carve-out (`getFsReadConfig`'s `allowWithinDeny`) -- carried and
+     * unioned identically for merge-parity, though `packages/runtime/src/sandbox/profile.ts`'s own
+     * `buildSeatbeltProfile` does not yet enforce it (a disclosed, fails-CLOSED gap: see that file's
+     * own `SandboxFilesystemSettings.allowRead` doc comment).
+     */
+    sandbox?: SandboxSettingsConfig;
     hooks?: SettingsHooksConfig;
     env?: Record<string, string>;
     apiKeyHelper?: string;

package/dist/tools/index.js

@@ -8,7 +8,7 @@ import {
 import {
   resolveWinterHome2,
   WinterCompatibilitySessionStore2
-} from "../index-qst9rwbb.js";
+} from "../index-0xks1t4r.js";
 
 // src/tools/schemas.ts
 var SEND_MESSAGE_TO_MAX = 300;

package/package.json

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