@mono-agent/agent-runtime 0.6.1 → 0.8.0

package/src/ai/providers/claude-cli.js

@@ -15,6 +15,62 @@ import {
   claudeNativeAgentDefinitions,
   resolveClaudeAllowedTools,
 } from "./claude-subagents.js";
+import {
+  claudeCapabilityMismatchResult,
+  claudeSandboxCapabilityMismatchResult,
+  claudeSandboxPolicyProblem,
+} from "./claude-sandbox.js";
+import { resolveSandboxPolicy } from "../../agent/tools/shared/tool-context.js";
+
+const CODEX_CLI_SANDBOX_POLICY_UNSUPPORTED =
+  "Direct Codex CLI cannot enforce mono-agent's native srt sandbox scopes. Remove the mono-agent sandbox policy or use a Pi runtime for exact readableRoots, writableRoots, denyWrite, and network rules.";
+const CLAUDE_CLI_EMPTY_TOOL_POLICY_UNSUPPORTED =
+  "Claude Code CLI cannot enforce an explicit empty allowedTools list: omitting --tools would restore Claude Code's default toolset. Use a specific non-empty allowlist, a denylist, or the Claude SDK for a no-tools run.";
+
+function codexCliToolPolicyProblem(options) {
+  const allowedTools = Array.isArray(options.allowedTools) ? options.allowedTools : null;
+  const disallowedTools = Array.isArray(options.disallowedTools) ? options.disallowedTools : [];
+  const exactAllowAll = allowedTools === null
+    || (allowedTools.length === 1 && allowedTools[0] === "*");
+  return exactAllowAll && disallowedTools.length === 0
+    ? null
+    : "Direct Codex CLI cannot enforce allowedTools/disallowedTools. Use exact allow-all ([\"*\"] with no disallowedTools) or another runtime.";
+}
+
+function codexCliCapabilityMismatchResult(options, error, codexErrorCode, start) {
+  const resolved = options.model;
+  const providerSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
+    || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
+    || null;
+  return {
+    text: null,
+    structuredResult: undefined,
+    structuredResultSource: null,
+    events: [],
+    usage: {},
+    durationMs: Date.now() - start,
+    numTurns: 0,
+    model: resolved?.reference || `codex:${resolved?.model || ""}`,
+    effort: options.effort || null,
+    sdk: "codex",
+    providerSessionId,
+    provider_session_id: providerSessionId,
+    cancelled: false,
+    error,
+    failureKind: "skipped_capability_mismatch",
+    diagnostics: { codex_error_code: codexErrorCode },
+    capabilitiesUsed: buildCapabilitiesUsed({
+      promptCacheActive: null,
+      thinkingEnabled: null,
+      structuredOutputEnforced: !!options.outputSchema,
+      subagentInvoked: null,
+      mcpServersUsed: [],
+      nativeSubagentsUsed: [],
+      toolCompactionApplied: false,
+      contextCompactionApplied: null,
+    }),
+  };
+}
 
 const DORMANT_CLI_CAPABILITIES = {
   streaming: true,
@@ -371,9 +427,8 @@ export function buildCliCommand({
   nativeSubagents,
   contextWindow,
 }) {
-  // Effort is expected to be pre-normalized by core/ai.js#generateResponse
-  // before reaching this provider. Direct callers of buildCliCommand must
-  // pass an already-normalized reasoning level (low/medium/high/xhigh/none).
+  // Effort arrives pre-normalized (low/medium/high/xhigh/max/none); per-CLI
+  // ceilings are clamped below rather than by callers.
   const normalizedEffort = typeof effort === "string" && effort.trim() ? effort : null;
   if (sdk === "claude-code") {
     const nativeAgents = claudeNativeAgentDefinitions(nativeSubagents);
@@ -435,8 +490,10 @@ export function buildCliCommand({
   if (permissionMode === "bypassPermissions") args.push("--dangerously-bypass-approvals-and-sandbox");
   else if (permissionMode === "acceptEdits" || permissionMode === "auto") args.push("--full-auto");
   else if (permissionMode === "plan") args.push("--sandbox", "read-only");
-  if (normalizedEffort) args.push("--config", `model_reasoning_effort=${normalizedEffort}`);
-  if (normalizedEffort !== "none") args.push("--config", `model_reasoning_summary=${tomlValue("auto")}`);
+  // codex has no "max" reasoning tier; clamp to its ceiling instead of crashing the CLI.
+  const codexEffort = normalizedEffort === "max" ? "xhigh" : normalizedEffort;
+  if (codexEffort) args.push("--config", `model_reasoning_effort=${codexEffort}`);
+  if (codexEffort !== "none") args.push("--config", `model_reasoning_summary=${tomlValue("auto")}`);
   if (hasEntries(mcpServers)) args.push(...codexMcpConfigArgs(mcpServers));
   args.push([systemPrompt, prompt].filter((part) => String(part || "").trim()).join("\n\n"));
   return { command: "codex", args, cwd };
@@ -445,6 +502,53 @@ export function buildCliCommand({
 export async function generateCliResponse(systemPrompt, options = {}) {
   const start = Date.now();
   const resolved = options.model;
+  if (resolved?.sdk === "claude-code" && claudeSandboxPolicyProblem(options)) {
+    const providerSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
+      || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
+      || null;
+    return claudeSandboxCapabilityMismatchResult({
+      model: resolved.reference || `claude:${resolved.model}`,
+      effort: options.effort,
+      sdk: "claude-code",
+      providerSessionId,
+      durationMs: Date.now() - start,
+      outputSchema: options.outputSchema,
+    });
+  }
+  if (resolved?.sdk === "claude-code" && Array.isArray(options.allowedTools) && options.allowedTools.length === 0) {
+    const providerSessionId = (typeof options.sessionId === "string" && options.sessionId.trim())
+      || (typeof options.providerSessionId === "string" && options.providerSessionId.trim())
+      || null;
+    return claudeCapabilityMismatchResult({
+      model: resolved.reference || `claude:${resolved.model}`,
+      effort: options.effort,
+      sdk: "claude-code",
+      providerSessionId,
+      durationMs: Date.now() - start,
+      outputSchema: options.outputSchema,
+      error: CLAUDE_CLI_EMPTY_TOOL_POLICY_UNSUPPORTED,
+      errorCode: "claude_cli_empty_tool_policy_unsupported",
+    });
+  }
+  if (resolved?.sdk !== "claude-code") {
+    if (resolveSandboxPolicy(options.toolContext, options.sandboxPolicy) !== undefined) {
+      return codexCliCapabilityMismatchResult(
+        options,
+        CODEX_CLI_SANDBOX_POLICY_UNSUPPORTED,
+        "codex_sandbox_policy_unsupported",
+        start,
+      );
+    }
+    const toolPolicyProblem = codexCliToolPolicyProblem(options);
+    if (toolPolicyProblem !== null) {
+      return codexCliCapabilityMismatchResult(
+        options,
+        toolPolicyProblem,
+        "codex_tool_policy_unsupported",
+        start,
+      );
+    }
+  }
   const prompt = promptFromMessages(options.messages);
   const dir = mkdtempSync(join(tmpdir(), (options.toolContext?.runtimeBrand ?? readRuntimeBrand()).tempdirPrefix));
   const schemaPath = options.outputSchema ? join(dir, "output-schema.json") : null;

package/src/ai/providers/claude-sandbox.js

@@ -0,0 +1,71 @@
+import { buildCapabilitiesUsed } from "../runtime/capabilities-used.js";
+import { resolveSandboxPolicy } from "../../agent/tools/shared/tool-context.js";
+
+export const CLAUDE_SANDBOX_POLICY_UNSUPPORTED =
+  "Claude SDK/CLI cannot enforce mono-agent's native srt sandbox scopes. Remove the mono-agent sandbox policy or use a Pi runtime for exact readableRoots, writableRoots, denyWrite, and network rules.";
+
+/**
+ * Claude owns its built-in tool subprocesses, so mono-agent's runtime tool
+ * context cannot wrap them with the configured srt engine. An explicit `off`
+ * policy is inert and remains valid; every enforcing mono-agent mode must fail
+ * before the provider starts instead of silently running outside that policy.
+ */
+export function claudeSandboxPolicyProblem(options) {
+  const effectivePolicy = resolveSandboxPolicy(
+    options?.toolContext,
+    options?.sandboxPolicy,
+  );
+  return effectivePolicy !== undefined
+    ? CLAUDE_SANDBOX_POLICY_UNSUPPORTED
+    : null;
+}
+
+/** Typed provider result used by Claude bridges for fail-closed capability paths. */
+export function claudeCapabilityMismatchResult({
+  model,
+  effort,
+  sdk,
+  providerSessionId = null,
+  durationMs = 0,
+  outputSchema,
+  error,
+  errorCode,
+}) {
+  return {
+    text: null,
+    structuredResult: undefined,
+    structuredResultSource: null,
+    events: [],
+    usage: {},
+    durationMs,
+    numTurns: 0,
+    model,
+    effort: effort || null,
+    sdk,
+    providerSessionId,
+    provider_session_id: providerSessionId,
+    cancelled: false,
+    error,
+    failureKind: "skipped_capability_mismatch",
+    diagnostics: { claude_error_code: errorCode },
+    capabilitiesUsed: buildCapabilitiesUsed({
+      promptCacheActive: null,
+      thinkingEnabled: null,
+      structuredOutputEnforced: !!outputSchema,
+      subagentInvoked: null,
+      mcpServersUsed: [],
+      nativeSubagentsUsed: [],
+      toolCompactionApplied: false,
+      contextCompactionApplied: null,
+    }),
+  };
+}
+
+/** Typed provider result used by both Claude bridges for the sandbox path. */
+export function claudeSandboxCapabilityMismatchResult(options) {
+  return claudeCapabilityMismatchResult({
+    ...options,
+    error: CLAUDE_SANDBOX_POLICY_UNSUPPORTED,
+    errorCode: "claude_sandbox_policy_unsupported",
+  });
+}

package/src/ai/providers/claude-sdk-discovery-worker.js

@@ -0,0 +1,53 @@
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { normalizeClaudeSdkCatalog } from "./claude-sdk-discovery.js";
+
+const abortController = new AbortController();
+let activeQuery = null;
+
+async function* emptyInput() {
+  // Initialization is the operation. An empty async input keeps the SDK from
+  // executing a paid model turn while still opening the control channel.
+}
+
+function abort() {
+  abortController.abort();
+  try { activeQuery?.close?.(); } catch { /* best effort */ }
+}
+
+process.on("message", (message) => {
+  if (message && typeof message === "object" && /** @type {any} */ (message).type === "abort") abort();
+});
+
+async function main() {
+  try {
+    activeQuery = query({
+      prompt: emptyInput(),
+      options: /** @type {any} */ ({
+        cwd: process.cwd(),
+        abortController,
+        persistSession: false,
+        settingSources: [],
+        tools: [],
+        mcpServers: {},
+        strictMcpConfig: true,
+        env: {
+          ...process.env,
+          MCP_CONNECTION_NONBLOCKING: "0",
+        },
+      }),
+    });
+    const initialization = await activeQuery.initializationResult();
+    const models = normalizeClaudeSdkCatalog(initialization?.models, "discovered");
+    process.send?.({ type: "claude_catalog", models });
+  } catch {
+    // Raw SDK errors may contain paths or account detail. The parent needs
+    // only a typed failure signal so it can use the curated cache.
+    process.send?.({ type: "claude_catalog_error" });
+    process.exitCode = 1;
+  } finally {
+    try { activeQuery?.close?.(); } catch { /* best effort */ }
+    try { process.disconnect?.(); } catch { /* best effort */ }
+  }
+}
+
+void main();

package/src/ai/providers/claude-sdk-discovery.js

@@ -0,0 +1,352 @@
+import { fork } from "node:child_process";
+import { chmod, mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const DEFAULT_TIMEOUT_MS = 5_000;
+const CHILD_STOP_TIMEOUT_MS = 300;
+const MAX_MODELS = 64;
+const MAX_DESCRIPTION_CHARS = 320;
+const MODEL_ALIASES = new Set(["default", "opus", "sonnet", "haiku", "fable", "mythos", "inherit"]);
+const SUPPORTED_EFFORTS = new Set(["low", "medium", "high", "xhigh", "max"]);
+const WORKER_PATH = fileURLToPath(new URL("./claude-sdk-discovery-worker.js", import.meta.url));
+
+export const CLAUDE_SDK_CATALOG_VERSION = "claude-agent-sdk-0.3.206";
+
+/** @typedef {"low"|"medium"|"high"|"xhigh"|"max"} ClaudeSdkEffort */
+/**
+ * @typedef {Object} ClaudeSdkCatalogModel
+ * @property {string} model Exact model id accepted by the SDK.
+ * @property {`claude:${string}`} reference Canonical mono-agent reference.
+ * @property {string} displayName
+ * @property {string} description
+ * @property {readonly ClaudeSdkEffort[]} supportedEfforts
+ * @property {boolean} supportsAdaptiveThinking
+ * @property {boolean} supportsFastMode
+ * @property {"discovered"|"cached"} source
+ * @property {typeof CLAUDE_SDK_CATALOG_VERSION} catalogVersion
+ */
+
+const CURATED_CATALOG = Object.freeze([
+  curatedModel("claude-sonnet-5", "Claude Sonnet 5", "Efficient for routine tasks", {
+    supportedEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsAdaptiveThinking: true,
+  }),
+  curatedModel("claude-opus-4-8[1m]", "Claude Opus 4.8 (1M context)", "Opus 4.8 with the 1M context window", {
+    supportedEfforts: ["low", "medium", "high", "xhigh", "max"],
+    supportsAdaptiveThinking: true,
+    supportsFastMode: true,
+  }),
+  curatedModel("claude-haiku-4-5-20251001", "Claude Haiku 4.5", "Fastest for quick answers"),
+]);
+
+/**
+ * @param {string} model
+ * @param {string} displayName
+ * @param {string} description
+ * @param {{supportedEfforts?: ClaudeSdkEffort[], supportsAdaptiveThinking?: boolean, supportsFastMode?: boolean}} [capabilities]
+ * @returns {Readonly<ClaudeSdkCatalogModel>}
+ */
+function curatedModel(model, displayName, description, capabilities = {}) {
+  return Object.freeze({
+    model,
+    reference: `claude:${model}`,
+    displayName,
+    description,
+    supportedEfforts: Object.freeze([...(capabilities.supportedEfforts || [])]),
+    supportsAdaptiveThinking: capabilities.supportsAdaptiveThinking === true,
+    supportsFastMode: capabilities.supportsFastMode === true,
+    source: "cached",
+    catalogVersion: CLAUDE_SDK_CATALOG_VERSION,
+  });
+}
+
+/**
+ * Return the versioned, SDK-matched fallback without exposing mutable shared
+ * objects to callers.
+ */
+export function curatedClaudeSdkModels() {
+  return CURATED_CATALOG.map((entry) => ({ ...entry, supportedEfforts: [...entry.supportedEfforts] }));
+}
+
+/**
+ * Normalize only exact Claude model ids. CLI convenience aliases are rejected
+ * so persisted configuration never changes meaning when an alias advances.
+ * Exact dated ids and a canonical `[1m]` suffix are preserved.
+ * @param {unknown} value
+ * @returns {string|null}
+ */
+export function normalizeClaudeSdkModelId(value) {
+  let model = String(value ?? "").trim().toLowerCase();
+  if (!model || model.length > 160) return null;
+  if (model.startsWith("claude:")) model = model.slice("claude:".length);
+  if (MODEL_ALIASES.has(model)) return null;
+
+  const contextSuffix = model.endsWith("[1m]") ? "[1m]" : "";
+  if (contextSuffix) model = model.slice(0, -contextSuffix.length);
+  if (!/^claude-(?:opus|sonnet|haiku|fable|mythos)-\d+(?:-\d+)*$/u.test(model)) return null;
+  return `${model}${contextSuffix}`;
+}
+
+function displayNameForModel(model) {
+  const oneMillion = model.endsWith("[1m]");
+  const base = oneMillion ? model.slice(0, -4) : model;
+  const match = /^claude-([a-z]+)-(.+)$/u.exec(base);
+  if (!match) return model;
+  const family = `${match[1][0].toUpperCase()}${match[1].slice(1)}`;
+  const version = match[2].replace(/-20\d{6}$/u, "").replace(/-/g, ".");
+  return `Claude ${family} ${version}${oneMillion ? " (1M context)" : ""}`;
+}
+
+function boundedCatalogText(value, limit) {
+  const text = String(value ?? "")
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  return text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+function normalizedEfforts(entry) {
+  const values = Array.isArray(entry?.supportedEffortLevels)
+    ? entry.supportedEffortLevels
+    : Array.isArray(entry?.supportedEfforts)
+      ? entry.supportedEfforts
+      : [];
+  return [...new Set(values.map((value) => String(value)).filter((value) => SUPPORTED_EFFORTS.has(value)))];
+}
+
+/**
+ * Whitelist the SDK initialization catalog into the public mono-agent shape.
+ * No account, organization, token source, raw error, or unknown SDK field can
+ * cross this boundary.
+ * @param {unknown} rows
+ * @param {"discovered"|"cached"} [source]
+ * @returns {ClaudeSdkCatalogModel[]}
+ */
+export function normalizeClaudeSdkCatalog(rows, source = "discovered") {
+  if (!Array.isArray(rows)) return [];
+  const byModel = new Map();
+  for (const raw of rows.slice(0, MAX_MODELS * 4)) {
+    if (!raw || typeof raw !== "object") continue;
+    const row = /** @type {any} */ (raw);
+    const model = normalizeClaudeSdkModelId(
+      row.resolvedModel ?? row.model ?? row.reference ?? row.value,
+    );
+    if (!model) continue;
+    const supportedEfforts = /** @type {ClaudeSdkEffort[]} */ (normalizedEfforts(row));
+    const description = boundedCatalogText(row.description, MAX_DESCRIPTION_CHARS)
+      || `Claude ${displayNameForModel(model).replace(/^Claude /u, "")}`;
+    const current = byModel.get(model);
+    /** @type {ClaudeSdkCatalogModel} */
+    const normalized = {
+      model,
+      reference: `claude:${model}`,
+      displayName: displayNameForModel(model),
+      description,
+      supportedEfforts,
+      supportsAdaptiveThinking: row.supportsAdaptiveThinking === true,
+      supportsFastMode: row.supportsFastMode === true,
+      source,
+      catalogVersion: CLAUDE_SDK_CATALOG_VERSION,
+    };
+    if (!current) {
+      byModel.set(model, normalized);
+      continue;
+    }
+    byModel.set(model, {
+      ...current,
+      description: current.description.length >= normalized.description.length
+        ? current.description
+        : normalized.description,
+      supportedEfforts: [...new Set([...current.supportedEfforts, ...supportedEfforts])],
+      supportsAdaptiveThinking: current.supportsAdaptiveThinking || normalized.supportsAdaptiveThinking,
+      supportsFastMode: current.supportsFastMode || normalized.supportsFastMode,
+    });
+  }
+  return [...byModel.values()].slice(0, MAX_MODELS);
+}
+
+function authoredCatalogRows(references) {
+  return (Array.isArray(references) ? references : []).map((reference) => ({ reference }));
+}
+
+/** @param {...ClaudeSdkCatalogModel[]} catalogs @returns {ClaudeSdkCatalogModel[]} */
+function mergeCatalogs(...catalogs) {
+  const byModel = new Map();
+  for (const catalog of catalogs) {
+    for (const entry of catalog) {
+      const existing = byModel.get(entry.model);
+      if (!existing || (existing.source === "cached" && entry.source === "discovered")) {
+        byModel.set(entry.model, entry);
+      }
+    }
+  }
+  return [...byModel.values()].slice(0, MAX_MODELS);
+}
+
+function safeDiscoveryEnvironment(baseEnvironment = process.env) {
+  const env = {};
+  for (const key of [
+    "PATH", "LANG", "LC_ALL", "LC_CTYPE", "SHELL",
+    "SystemRoot", "WINDIR", "ComSpec", "PATHEXT",
+  ]) {
+    const value = baseEnvironment[key];
+    if (typeof value === "string" && value) env[key] = value;
+  }
+  return env;
+}
+
+async function privateDirectory(parent, name) {
+  const path = join(parent, name);
+  await mkdir(path, { mode: 0o700 });
+  if (process.platform !== "win32") await chmod(path, 0o700);
+  return path;
+}
+
+/** @internal Exported for deterministic isolation tests. */
+export async function createClaudeSdkDiscoveryIsolation({ baseEnvironment = process.env } = {}) {
+  const root = await mkdtemp(join(tmpdir(), "mono-agent-claude-discovery-"));
+  try {
+    if (process.platform !== "win32") await chmod(root, 0o700);
+    const home = await privateDirectory(root, "home");
+    const claudeConfig = await privateDirectory(root, "secure-storage");
+    const config = await privateDirectory(root, "xdg-config");
+    const cache = await privateDirectory(root, "xdg-cache");
+    const data = await privateDirectory(root, "xdg-data");
+    const state = await privateDirectory(root, "xdg-state");
+    const temp = await privateDirectory(root, "tmp");
+    const cwd = await privateDirectory(root, "cwd");
+    const env = {
+      ...safeDiscoveryEnvironment(baseEnvironment),
+      HOME: home,
+      CLAUDE_CONFIG_DIR: claudeConfig,
+      XDG_CONFIG_HOME: config,
+      XDG_CACHE_HOME: cache,
+      XDG_DATA_HOME: data,
+      XDG_STATE_HOME: state,
+      TMPDIR: temp,
+      TMP: temp,
+      TEMP: temp,
+      CLAUDE_AGENT_SDK_CLIENT_APP: "mono-agent-model-discovery/0.6",
+      MCP_CONNECTION_NONBLOCKING: "0",
+    };
+    return {
+      root,
+      cwd,
+      env,
+      cleanup: async () => {
+        await rm(root, { recursive: true, force: true }).catch(() => undefined);
+      },
+    };
+  } catch (error) {
+    await rm(root, { recursive: true, force: true }).catch(() => undefined);
+    throw error;
+  }
+}
+
+function waitForWorker(child, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (callback, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener?.("message", onMessage);
+      child.removeListener?.("error", onError);
+      child.removeListener?.("exit", onExit);
+      callback(value);
+    };
+    const onMessage = (message) => {
+      if (message?.type === "claude_catalog") finish(resolve, message.models);
+      else if (message?.type === "claude_catalog_error") finish(reject, new Error("Claude catalog worker failed"));
+    };
+    const onError = () => finish(reject, new Error("Claude catalog worker failed"));
+    const onExit = (code) => {
+      if (code !== 0) finish(reject, new Error("Claude catalog worker exited before returning a catalog"));
+    };
+    const timer = setTimeout(() => {
+      try {
+        if (child.connected !== false) child.send?.({ type: "abort" }, () => undefined);
+      } catch { /* best effort */ }
+      finish(reject, new Error("Claude catalog discovery timed out"));
+    }, timeoutMs);
+    timer.unref?.();
+    child.on("message", onMessage);
+    child.on("error", onError);
+    child.on("exit", onExit);
+  });
+}
+
+async function stopWorker(child) {
+  if (!child || child.exitCode != null || child.signalCode != null) return;
+  await new Promise((resolve) => {
+    let settled = false;
+    let timer;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener?.("exit", finish);
+      child.removeListener?.("error", finish);
+      resolve(undefined);
+    };
+    child.once?.("exit", finish);
+    child.once?.("error", finish);
+    try {
+      if (child.connected !== false) child.send?.({ type: "abort" }, () => undefined);
+    } catch { /* best effort */ }
+    try { child.disconnect?.(); } catch { /* best effort */ }
+    timer = setTimeout(() => {
+      try { child.kill?.("SIGKILL"); } catch { /* best effort */ }
+      finish();
+    }, CHILD_STOP_TIMEOUT_MS);
+    timer.unref?.();
+    try { child.kill?.("SIGTERM"); } catch { finish(); }
+  });
+}
+
+/**
+ * Discover Claude's current model catalog in a throwaway, no-auth process.
+ * Failure is deliberately non-fatal: the exact SDK-versioned curated catalog
+ * remains available with `source: "cached"`.
+ *
+ * @param {Object} [options]
+ * @param {number} [options.timeoutMs]
+ * @param {readonly string[]} [options.authoredModelRefs]
+ * @param {typeof fork} [options.forkProcess]
+ * @param {(isolation: Awaited<ReturnType<typeof createClaudeSdkDiscoveryIsolation>>) => void} [options.onIsolation]
+ * @returns {Promise<ClaudeSdkCatalogModel[]>}
+ */
+export async function discoverClaudeSdkModels({
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  authoredModelRefs = [],
+  forkProcess = fork,
+  onIsolation,
+} = {}) {
+  const cached = curatedClaudeSdkModels();
+  const authored = normalizeClaudeSdkCatalog(authoredCatalogRows(authoredModelRefs), "cached");
+  let isolation;
+  let child;
+  try {
+    isolation = await createClaudeSdkDiscoveryIsolation();
+    onIsolation?.(isolation);
+    child = forkProcess(WORKER_PATH, [], {
+      cwd: isolation.cwd,
+      env: isolation.env,
+      // Do not inherit caller preload/debug/input-type flags into the
+      // credential-isolated discovery process.
+      execArgv: [],
+      stdio: ["ignore", "ignore", "ignore", "ipc"],
+      serialization: "json",
+    });
+    const raw = await waitForWorker(child, Math.max(1, Math.min(30_000, Number(timeoutMs) || DEFAULT_TIMEOUT_MS)));
+    const discovered = normalizeClaudeSdkCatalog(raw, "discovered");
+    return mergeCatalogs(cached, authored, discovered);
+  } catch {
+    return mergeCatalogs(cached, authored);
+  } finally {
+    await stopWorker(child);
+    await isolation?.cleanup();
+  }
+}