@yansigit/opencodex 2.36.1-dev.20260829.42 → 2.36.1-dev.20260829.48

package/src/cli/provider.ts

@@ -8,7 +8,7 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, mutatePersistedConfig, sanitizeModelCostsForDisplay } from "../config";
 import { apiKeyTransportConfigError } from "../config/provider-validation";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
@@ -57,19 +57,26 @@ function maskSecret(value: string): string {
 }
 
 // ---------------------------------------------------------------------------
-// Validation helper (F1 fix: validate before saveConfig)
+// Validation helper
 // ---------------------------------------------------------------------------
 
-function validateAndSave(config: ReturnType<typeof loadConfig>): void {
+function validateProviderConfig(config: ReturnType<typeof loadConfig>): void {
   if (!config.providers || Object.keys(config.providers).length === 0) {
-    console.error("Error: config would have no providers. Aborting.");
-    process.exit(1);
+    throw new Error("config would have no providers");
   }
   if (!hasOwnProvider(config.providers, config.defaultProvider)) {
-    console.error(`Error: defaultProvider "${config.defaultProvider}" does not exist in providers. Aborting.`);
-    process.exit(1);
+    throw new Error(`defaultProvider "${config.defaultProvider}" does not exist in providers`);
+  }
+}
+
+function mutateProviderConfig<T>(mutate: (config: ReturnType<typeof loadConfig>) => { changed: boolean; value: T }): T {
+  const outcome = mutatePersistedConfig(mutate);
+  if (outcome.status === "unavailable") {
+    throw new Error(outcome.reason === "conflict"
+      ? "config changed while applying this provider update; retry"
+      : `config is ${outcome.reason}`);
   }
-  saveConfig(config);
+  return outcome.value;
 }
 
 // ---------------------------------------------------------------------------
@@ -154,19 +161,6 @@ async function handleAdd(args: string[]): Promise<void> {
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
   rejectUnknownArgs(restArgs, ADD_USAGE);
 
-  const config = loadConfig();
-
-  const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
-  if (namespaceCollision) {
-    console.error(`Error: ${namespaceCollision}.`);
-    process.exit(1);
-  }
-
-  if (hasOwnProvider(config.providers, name) && !force) {
-    console.error(`Provider "${name}" already exists. Use --force to overwrite.`);
-    process.exit(1);
-  }
-
   let provConfig: OcxProviderConfig;
   const registryEntry = getProviderRegistryEntry(name);
 
@@ -211,18 +205,21 @@ async function handleAdd(args: string[]): Promise<void> {
     provConfig.apiKeyTransport = apiKeyTransport;
   }
 
-  const existingProvider = config.providers[name];
-  config.providers[name] = provConfig;
-  // A --force overwrite rotates the key/endpoint but must not drop a
-  // user-configured price overlay (same rule as the /api/providers path and
-  // the login paths); there is no explicit clear/replace flag yet.
-  if (existingProvider?.modelCosts !== undefined && provConfig.modelCosts === undefined) {
-    provConfig.modelCosts = existingProvider.modelCosts;
-  }
   if (allowPrivateNetwork) provConfig.allowPrivateNetwork = true;
-  if (setDefault) config.defaultProvider = name;
-
-  validateAndSave(config);
+  const saved = mutateProviderConfig(config => {
+    const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
+    if (namespaceCollision) throw new Error(`${namespaceCollision}.`);
+    const existingProvider = config.providers[name];
+    if (existingProvider && !force) throw new Error(`Provider "${name}" already exists. Use --force to overwrite.`);
+    const next = structuredClone(provConfig);
+    // A --force overwrite rotates the key/endpoint but must not drop a user-configured price overlay.
+    if (existingProvider?.modelCosts !== undefined && next.modelCosts === undefined) next.modelCosts = existingProvider.modelCosts;
+    config.providers[name] = next;
+    if (setDefault) config.defaultProvider = name;
+    validateProviderConfig(config);
+    return { changed: JSON.stringify(existingProvider) !== JSON.stringify(next) || (setDefault && config.defaultProvider === name), value: { provider: next, defaultProvider: config.defaultProvider } };
+  });
+  provConfig = saved.provider;
 
   if (wantsJson) {
     console.log(JSON.stringify({
@@ -231,7 +228,7 @@ async function handleAdd(args: string[]): Promise<void> {
       adapter: provConfig.adapter,
       baseUrl: provConfig.baseUrl,
       defaultModel: provConfig.defaultModel ?? null,
-      isDefault: config.defaultProvider === name,
+      isDefault: saved.defaultProvider === name,
       source: registryEntry ? "registry" : "custom",
       needsSync: true,
     }, null, 2));
@@ -285,42 +282,32 @@ function handleRemove(args: string[]): void {
   }
   rejectUnknownArgs(restArgs.slice(1), "Usage: ocx provider remove <name> [--json]");
 
-  const config = loadConfig();
-  if (!hasOwnProvider(config.providers, name)) {
-    console.error(`Provider "${name}" is not configured.`);
-    process.exit(1);
-  }
-
-  if (name === config.defaultProvider) {
-    console.error(`Cannot remove "${name}" — it is the default provider. Change the default first: ocx provider set-default <other>`);
-    process.exit(1);
-  }
-
-  if (Object.keys(config.providers).length <= 1) {
-    console.error("Cannot remove the last provider.");
-    process.exit(1);
-  }
-
-  const dependentCombos = Object.entries(config.combos ?? {})
-    .filter(([, combo]) => combo.targets.some(target => target.provider === name))
-    .map(([id]) => id)
-    .sort();
-  if (dependentCombos.length > 0) {
-    console.error(`Cannot remove "${name}" — combo(s) depend on it: ${dependentCombos.join(", ")}`);
-    process.exit(1);
-  }
-
-  delete config.providers[name];
-  const droppedCustomModels = dropProviderCustomModels(config, name);
-  validateAndSave(config);
+  const saved = mutateProviderConfig(config => {
+    if (!hasOwnProvider(config.providers, name)) throw new Error(`Provider "${name}" is not configured.`);
+    if (name === config.defaultProvider) throw new Error(`Cannot remove "${name}" — it is the default provider. Change the default first: ocx provider set-default <other>`);
+    if (Object.keys(config.providers).length <= 1) throw new Error("Cannot remove the last provider.");
+    const dependentCombos = Object.entries(config.combos ?? {})
+      .filter(([, combo]) => combo.targets.some(target => target.provider === name))
+      .map(([id]) => id).sort();
+    if (dependentCombos.length > 0) throw new Error(`Cannot remove "${name}" — combo(s) depend on it: ${dependentCombos.join(", ")}`);
+    const dependentProfiles = Object.entries(config.routingProfiles ?? {})
+      .filter(([, profile]) => profile.candidates.some(candidate => candidate.provider === name))
+      .map(([id]) => id).sort();
+    if (dependentProfiles.length > 0) throw new Error(`Cannot remove "${name}" — routing profile(s) depend on it: ${dependentProfiles.join(", ")}`);
+    delete config.providers[name];
+    const droppedCustomModels = dropProviderCustomModels(config, name);
+    validateProviderConfig(config);
+    return { changed: true, value: { droppedCustomModels, providers: Object.keys(config.providers), defaultProvider: config.defaultProvider } };
+  });
+  const { droppedCustomModels } = saved;
 
 
   if (wantsJson) {
     console.log(JSON.stringify({
       action: "removed",
       provider: name,
-      remainingProviders: Object.keys(config.providers),
-      defaultProvider: config.defaultProvider,
+      remainingProviders: saved.providers,
+      defaultProvider: saved.defaultProvider,
       needsSync: true,
       ...(droppedCustomModels > 0 ? { droppedCustomModels } : {}),
     }, null, 2));
@@ -396,13 +383,14 @@ function handleSetDefault(args: string[]): void {
   }
   rejectUnknownArgs(restArgs.slice(1), "Usage: ocx provider set-default <name> [--json]");
 
-  const config = loadConfig();
-  if (!hasOwnProvider(config.providers, name)) {
-    console.error(`Provider "${name}" is not configured. Add it first: ocx provider add ${name}`);
-    process.exit(1);
-  }
-
-  if (config.defaultProvider === name) {
+  const changed = mutateProviderConfig(config => {
+    if (!hasOwnProvider(config.providers, name)) throw new Error(`Provider "${name}" is not configured. Add it first: ocx provider add ${name}`);
+    if (config.defaultProvider === name) return { changed: false, value: false };
+    config.defaultProvider = name;
+    validateProviderConfig(config);
+    return { changed: true, value: true };
+  });
+  if (!changed) {
     if (wantsJson) {
       console.log(JSON.stringify({ action: "noop", provider: name, defaultProvider: name, needsSync: false }, null, 2));
     } else {
@@ -411,10 +399,6 @@ function handleSetDefault(args: string[]): void {
     return;
   }
 
-  config.defaultProvider = name;
-  validateAndSave(config);
-
-
   if (wantsJson) {
     console.log(JSON.stringify({ action: "set-default", provider: name, defaultProvider: name, needsSync: true }, null, 2));
     return;

package/src/cli/registry.ts

@@ -205,7 +205,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "agent",
-    usage: "ocx agent <status|injection|effort|subagents|roles|fallback|sidecar> ...",
+    usage: "ocx agent <status|injection|effort|subagents|authority|roles|fallback|sidecar> ...",
     summary: "Manage headless multi-agent, roster, roles, effort, injection, and sidecar settings.",
   },
   {

package/src/codex/catalog.ts

@@ -8,7 +8,7 @@ export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, c
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithMetadata, resolveComboCatalogMember, configuredComboTargetModelsByProvider } from "./catalog/provider-fetch";
 export { deriveComboCatalogModel, exactComboCatalogSlugs, getLastComboCatalogOmissions, resetOpenAiApiCatalogWarningStateForTests, uniqueCatalogModelsForPublicList, uniqueCatalogModelsForRawPublicList, buildComboCatalogOmission, comboCatalogOmissionReason, summarizeComboCatalogOmissions } from "./catalog/aggregation";
 export type { ComboCatalogOmission, ComboCatalogOmissionReason } from "./catalog/aggregation";
-export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache, finalizeAutoReviewModelOverride } from "./catalog/sync";
+export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, CANONICAL_NATIVE_CATALOG_CONTENT_POLICY, effectiveSubagentRoster, isEligibleV2SubagentEntry, buildCatalogEntries, mergeCatalogEntriesFromObservedState, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache, finalizeAutoReviewModelOverride } from "./catalog/sync";
 export type { ObservedCatalogMergeInput } from "./catalog/sync";
 export type { SpawnAgentSurface, SubagentRosterExclusionReason, EffectiveSubagentModel, SubagentRosterExclusion, EffectiveSubagentRoster } from "./catalog/sync";
 export { accountBoundNativeDisplayName, accountBoundNativeModelSlugs, CODEX_ACCOUNT_BOUND_CATALOG_KIND, trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./catalog/account-models";

package/src/codex/convergence.ts

@@ -1,10 +1,13 @@
 import { join } from "node:path";
 
-import { getConfigDir, saveConfigPreservingClaudeCode, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
-import { reconcileSuccessfulModelDiscoveries } from "../providers/new-model-policy";
+import { getConfigDir, mutatePersistedConfig, websocketsEnabled, withExpectedConfigGenerationSync } from "../config";
+import {
+  reconcileSuccessfulModelDiscoveries,
+  type KnownModelBaseline,
+} from "../providers/new-model-policy";
 import { COMBO_NAMESPACE } from "../combos";
 import { getAuthStorePath } from "../oauth/store";
-import type { OcxConfig } from "../types";
+import type { OcxConfig, OcxProviderConfig } from "../types";
 import { captureCatalogAdmissionSnapshot } from "./catalog-admission";
 import { legacyCustomModelCatalogSlugs } from "./custom-model-catalog-migration";
 import {
@@ -137,7 +140,22 @@ interface CandidateState {
   readonly changed: boolean;
   readonly notices: readonly CatalogNotice[];
   readonly modelEntitlements: CodexModelEntitlementSnapshot;
-  readonly discoveryConfig?: OcxConfig;
+  readonly discovery: DiscoveryEvidence;
+}
+
+interface DiscoveryEvidence {
+  readonly models: readonly { provider: string; id: string; custom?: boolean }[];
+  readonly authoritativeProviders: readonly string[];
+  readonly providerIdentities: Readonly<Record<string, string>>;
+  readonly now: string;
+}
+
+interface DiscoveryProjection {
+  readonly providers: Readonly<Record<string, Readonly<{
+    knownModel?: KnownModelBaseline;
+    recentArrivals?: readonly { id: string; at: string }[];
+  }>>>;
+  readonly disabledModelsToAdd: readonly string[];
 }
 
 const candidateStates = new WeakMap<object, CandidateState>();
@@ -145,6 +163,16 @@ function same(left: unknown, right: unknown): boolean {
   return JSON.stringify(left) === JSON.stringify(right);
 }
 
+function discoveryProviderIdentity(provider: OcxProviderConfig | undefined): string {
+  if (!provider) return "missing";
+  const row: Record<string, unknown> = { ...provider };
+  delete row.note;
+  delete row.newModelPolicy;
+  return JSON.stringify(row, (_key, value) => value && typeof value === "object" && !Array.isArray(value)
+    ? Object.fromEntries(Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right)))
+    : value);
+}
+
 function targetPath(identity: string): string {
   const parsed = JSON.parse(identity) as { path?: unknown };
   if (typeof parsed.path !== "string") throw new TypeError("Catalog target identity has no path.");
@@ -441,13 +469,15 @@ export async function gatherCodexCatalogCandidate(
           : !hasRoutedEntries(source.catalog) ? source.catalog : null)
         : null);
     const discoveryConfig = structuredClone(snapshot.config) as OcxConfig;
-    const discoveryChanged = reconcileSuccessfulModelDiscoveries({
+    const authoritativeProviders = providerModelOutcomes
+      .filter(outcome => outcome.state === "authoritative")
+      .map(outcome => outcome.provider);
+    const discoveryNow = new Date().toISOString();
+    reconcileSuccessfulModelDiscoveries({
       config: discoveryConfig,
       models: routedModels,
-      authoritativeProviders: providerModelOutcomes
-        .filter(outcome => outcome.state === "authoritative")
-        .map(outcome => outcome.provider),
-      now: new Date().toISOString(),
+      authoritativeProviders,
+      now: discoveryNow,
     });
     const preparedCatalog = prepareCatalog(
       discoveryConfig,
@@ -515,7 +545,15 @@ export async function gatherCodexCatalogCandidate(
         || Buffer.from(cacheBytes ?? []).toString("utf8") !== preparedCacheBytes,
       notices: Object.freeze([...notices]),
       modelEntitlements,
-      ...(discoveryChanged ? { discoveryConfig } : {}),
+      discovery: {
+        models: routedModels,
+        authoritativeProviders,
+        providerIdentities: Object.fromEntries(authoritativeProviders.map(provider => [
+          provider,
+          discoveryProviderIdentity(snapshot.config.providers[provider]),
+        ])),
+        now: discoveryNow,
+      },
     });
     return { kind: "candidate", candidate };
   } catch (error) {
@@ -532,6 +570,63 @@ export async function gatherCodexCatalogCandidate(
   }
 }
 
+function reconcilePersistedDiscovery(state: CandidateState) {
+  return mutatePersistedConfig(config => {
+    if (state.discovery.authoritativeProviders.some(provider => (
+      discoveryProviderIdentity(config.providers[provider]) !== state.discovery.providerIdentities[provider]
+    ))) {
+      return { changed: false, value: null };
+    }
+    const disabledBefore = new Set(config.disabledModels ?? []);
+    const changed = reconcileSuccessfulModelDiscoveries({
+      config,
+      ...state.discovery,
+    });
+    const providers = Object.fromEntries(state.discovery.authoritativeProviders.flatMap(provider => {
+      const configured = config.providers[provider];
+      if (!configured || configured.liveModels === false) return [];
+      const knownModel = config.modelDiscovery?.knownModels?.[provider];
+      const recentArrivals = config.modelDiscovery?.recentArrivals?.[provider];
+      return [[provider, {
+        ...(knownModel ? { knownModel: structuredClone(knownModel) } : {}),
+        ...(recentArrivals ? { recentArrivals: structuredClone(recentArrivals) } : {}),
+      }]];
+    }));
+    return {
+      changed,
+      value: {
+        providers,
+        disabledModelsToAdd: (config.disabledModels ?? []).filter(slug => !disabledBefore.has(slug)),
+      } satisfies DiscoveryProjection,
+    };
+  });
+}
+
+function adoptDiscoveryProjection(config: OcxConfig, projection: DiscoveryProjection): void {
+  for (const [provider, discovered] of Object.entries(projection.providers)) {
+    if (discovered.knownModel) {
+      const discovery = config.modelDiscovery ??= {};
+      const knownModels = discovery.knownModels ??= {};
+      knownModels[provider] = structuredClone(discovered.knownModel);
+    } else if (config.modelDiscovery?.knownModels) {
+      delete config.modelDiscovery.knownModels[provider];
+    }
+    if (discovered.recentArrivals) {
+      const discovery = config.modelDiscovery ??= {};
+      const recentArrivals = discovery.recentArrivals ??= {};
+      recentArrivals[provider] = discovered.recentArrivals.map(arrival => ({ ...arrival }));
+    } else if (config.modelDiscovery?.recentArrivals) {
+      delete config.modelDiscovery.recentArrivals[provider];
+    }
+  }
+  if (projection.disabledModelsToAdd.length > 0) {
+    const disabledModels = config.disabledModels ??= [];
+    for (const slug of projection.disabledModelsToAdd) {
+      if (!disabledModels.includes(slug)) disabledModels.push(slug);
+    }
+  }
+}
+
 function revalidateCandidate(state: CandidateState): CodexCatalogCommitResult | null {
   if (!isCodexModelEntitlementSnapshotCurrent(state.modelEntitlements)) {
     return { kind: "stale", reason: "account-entitlement" };
@@ -663,11 +758,11 @@ export async function convergeCodexCatalog(
   const state = candidateStates.get(gathered.candidate as object)!;
   lifecycle.onCommitBegin?.();
   const committed = await commitCodexCatalogCandidate(gathered.candidate, request.deadlineMs);
-  if (committed.kind === "committed" && state.discoveryConfig) {
-    const mutable = snapshot.config as OcxConfig;
-    mutable.modelDiscovery = state.discoveryConfig.modelDiscovery;
-    mutable.disabledModels = state.discoveryConfig.disabledModels;
-    saveConfigPreservingClaudeCode(mutable);
+  if (committed.kind === "committed") {
+    const persisted = reconcilePersistedDiscovery(state);
+    if ((persisted.status === "committed" || persisted.status === "unchanged") && persisted.value) {
+      adoptDiscoveryProjection(snapshot.config as OcxConfig, persisted.value);
+    }
   }
   return {
     changed: committed.kind === "committed" ? committed.changed : false,

package/src/codex/inject.ts

@@ -38,6 +38,7 @@ import {
   writeJournal,
 } from "./journal";
 import { withCatalogWriteSerialization } from "./catalog-write-serialization";
+import { resetCodexAppServerCatalogStateCache } from "./app-server-processes";
 import { restoreCodexCatalogWithPermit } from "./catalog/sync";
 import { syncCodexHistoryProvider, type CodexHistoryFailureReason } from "./history-provider";
 import {
@@ -931,6 +932,7 @@ export async function injectCodexConfig(
       configContent: baselineContent,
     });
     atomicWriteFile(CODEX_CONFIG_PATH, content);
+    resetCodexAppServerCatalogStateCache();
     atomicWriteFile(CODEX_PROFILE_PATH, profileContent);
     markJournalInjectedState(content, profileContent, {
       // A root override is ours only in loopback Design B when no user-owned value won.

package/src/codex/subagent-defaults.ts

@@ -442,16 +442,9 @@ export async function resolveNativeDefaultState(
   const inspected = inspectManagedSubagentDefaults(content);
   if (!inspected.ok) return "blocked";
 
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = Bun.TOML.parse(content) as Record<string, unknown>;
-  } catch {
-    return "blocked";
-  }
   const provider = resolveEffectiveProjectModelProvider(content).provider;
   if (provider && provider !== "openai" && provider !== "opencodex") return "blocked";
-  const baseUrl = parsed.openai_base_url;
-  if (typeof baseUrl === "string" && baseUrl.trim() && !hasInjectedCodexRouting(content)) return "blocked";
+  if (!hasInjectedCodexRouting(content)) return "blocked";
 
   const { values, owned } = inspected.inspection;
   for (const key of TARGET_KEYS) {

package/src/codex/subagent-model-authority.ts

@@ -0,0 +1,189 @@
+import type { OcxConfig } from "../types";
+import { isEligibleV2SubagentEntry, readCatalog, readCodexCatalogPath } from "./catalog";
+import { catalogEntryEfforts } from "./catalog/effort";
+import type { RawEntry } from "./catalog/parsing";
+import { resolveNativeDefaultState, type NativeDefaultState } from "./subagent-defaults";
+
+export const SUBAGENT_MODEL_AUTHORITY_VERSION = 1 as const;
+
+export interface SubagentModelAuthorityInput {
+  schemaVersion: typeof SUBAGENT_MODEL_AUTHORITY_VERSION;
+  role: string;
+  agentType: string;
+  typedDispatchRequired?: boolean;
+  requestedModel?: string;
+  requestedEffort?: string;
+  spawnAgent: {
+    surface: "v1" | "v2";
+    supportsAgentType: boolean;
+    supportsModel: boolean;
+    supportsEffort: boolean;
+    supportsForkTurns: boolean;
+  };
+  confirmation?: { decision: "approve" | "decline" };
+  interactive?: boolean;
+}
+
+export interface SubagentModelAuthorityHost {
+  catalogState: "fresh" | "stale" | "not_running" | "unknown";
+  nativeDefaultState: NativeDefaultState;
+  preferredModel: string | null;
+  preferredEffort: string | null;
+  executableModels: Array<{ model: string; efforts: string[] }>;
+}
+
+export type SubagentModelAuthorityResult = {
+  schemaVersion: typeof SUBAGENT_MODEL_AUTHORITY_VERSION;
+  decision: "forward" | "omit" | "confirm" | "blocked";
+  requestClassification: "inherit" | "preferred" | "exception";
+  reason: string;
+  spawn?: {
+    agent_type?: string;
+    model?: string;
+    reasoning_effort?: string;
+    fork_turns?: "none";
+  };
+  confirmation?: {
+    role: string;
+    preferredModel: string | null;
+    requestedModel: string;
+    scope: "single spawn";
+  };
+};
+
+export function parseSubagentModelAuthorityInput(value: unknown): SubagentModelAuthorityInput | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const input = value as Record<string, unknown>;
+  const spawn = input.spawnAgent;
+  if (!spawn || typeof spawn !== "object" || Array.isArray(spawn)) return null;
+  const tool = spawn as Record<string, unknown>;
+  if (input.schemaVersion !== SUBAGENT_MODEL_AUTHORITY_VERSION
+    || typeof input.role !== "string"
+    || typeof input.agentType !== "string"
+    || (input.typedDispatchRequired !== undefined && typeof input.typedDispatchRequired !== "boolean")
+    || (input.requestedModel !== undefined && typeof input.requestedModel !== "string")
+    || (input.requestedEffort !== undefined && typeof input.requestedEffort !== "string")
+    || (input.interactive !== undefined && typeof input.interactive !== "boolean")
+    || (tool.surface !== "v1" && tool.surface !== "v2")
+    || ["supportsAgentType", "supportsModel", "supportsEffort", "supportsForkTurns"]
+      .some(key => typeof tool[key] !== "boolean")) return null;
+  if (input.confirmation !== undefined) {
+    if (!input.confirmation || typeof input.confirmation !== "object" || Array.isArray(input.confirmation)) return null;
+    const decision = (input.confirmation as Record<string, unknown>).decision;
+    if (decision !== "approve" && decision !== "decline") return null;
+  }
+  return value as SubagentModelAuthorityInput;
+}
+
+function result(
+  decision: SubagentModelAuthorityResult["decision"],
+  requestClassification: SubagentModelAuthorityResult["requestClassification"],
+  reason: string,
+  extra: Pick<SubagentModelAuthorityResult, "spawn" | "confirmation"> = {},
+): SubagentModelAuthorityResult {
+  return { schemaVersion: SUBAGENT_MODEL_AUTHORITY_VERSION, decision, requestClassification, reason, ...extra };
+}
+
+export function resolveSubagentModelAuthority(
+  input: SubagentModelAuthorityInput,
+  host: SubagentModelAuthorityHost,
+): SubagentModelAuthorityResult {
+  const requestedModel = input.requestedModel?.trim() || undefined;
+  const preferredModel = host.preferredModel?.trim() || undefined;
+  const classification = requestedModel === undefined
+    ? "inherit"
+    : requestedModel === preferredModel ? "preferred" : "exception";
+  if (input.schemaVersion !== SUBAGENT_MODEL_AUTHORITY_VERSION) {
+    return result("blocked", classification, "unsupported authority schema version");
+  }
+  if (!input.role.trim() || !input.agentType.trim()) {
+    return result("blocked", classification, "role and agentType must be non-empty");
+  }
+  if (input.typedDispatchRequired && !input.spawnAgent.supportsAgentType) {
+    return result("blocked", classification, "spawn_agent does not support required agent_type dispatch");
+  }
+  if (host.catalogState === "stale" || host.catalogState === "unknown") {
+    return result("blocked", classification, "OpenCodex model authority is not current; sync or restart Codex and retry");
+  }
+
+  const chosenModel = requestedModel ?? preferredModel;
+  const executable = chosenModel
+    ? host.executableModels.find(candidate => candidate.model === chosenModel)
+    : undefined;
+  if (chosenModel && !executable) {
+    return result("blocked", classification, `model ${JSON.stringify(chosenModel)} is not executable on this collaboration surface`);
+  }
+  if (chosenModel && !input.spawnAgent.supportsModel) {
+    return result("blocked", classification, "spawn_agent does not support model overrides");
+  }
+  const effort = input.requestedEffort?.trim() || (requestedModel ? undefined : host.preferredEffort?.trim()) || undefined;
+  if (effort && !input.spawnAgent.supportsEffort) {
+    return result("blocked", classification, "spawn_agent does not support reasoning_effort overrides");
+  }
+  if (effort && executable && !executable.efforts.includes(effort)) {
+    return result("blocked", classification, `reasoning effort ${JSON.stringify(effort)} is unavailable for ${JSON.stringify(chosenModel)}`);
+  }
+
+  if (classification === "exception") {
+    if (input.confirmation?.decision === "decline") {
+      return result("blocked", classification, "single-spawn model exception was declined");
+    }
+    if (input.confirmation?.decision !== "approve") {
+      if (input.interactive === false) {
+        return result("blocked", classification, "single-spawn model exception requires interactive confirmation");
+      }
+      return result("confirm", classification, "confirm this model exception for one spawn", {
+        confirmation: {
+          role: input.role,
+          preferredModel: preferredModel ?? null,
+          requestedModel: requestedModel!,
+          scope: "single spawn",
+        },
+      });
+    }
+  }
+
+  if (!chosenModel) {
+    return host.nativeDefaultState === "active"
+      ? result("omit", classification, "native OpenCodex defaults are active")
+      : result("blocked", classification, `native OpenCodex defaults are ${host.nativeDefaultState}`);
+  }
+  const spawn: NonNullable<SubagentModelAuthorityResult["spawn"]> = {
+    ...(input.spawnAgent.supportsAgentType ? { agent_type: input.agentType } : {}),
+    model: chosenModel,
+    ...(effort ? { reasoning_effort: effort } : {}),
+    ...((input.spawnAgent.supportsForkTurns && (chosenModel || effort)) ? { fork_turns: "none" as const } : {}),
+  };
+  return result("forward", classification, classification === "exception"
+    ? "single-spawn model exception approved"
+    : "OpenCodex preferred model is executable", { spawn });
+}
+
+function executableModels(entries: readonly RawEntry[], surface: "v1" | "v2"): SubagentModelAuthorityHost["executableModels"] {
+  const seen = new Set<string>();
+  return entries.flatMap(entry => {
+    const model = typeof entry.slug === "string" ? entry.slug.trim() : "";
+    if (!model || seen.has(model) || entry.visibility !== "list" || (surface === "v2" && !isEligibleV2SubagentEntry(entry))) return [];
+    seen.add(model);
+    return [{ model, efforts: catalogEntryEfforts(entry) }];
+  });
+}
+
+export async function resolveOpenCodexSubagentModelAuthority(
+  input: SubagentModelAuthorityInput,
+  config: OcxConfig,
+): Promise<SubagentModelAuthorityResult> {
+  const { collectCodexAppServerCatalogStateForRequest } = await import("./app-server-processes");
+  const catalogState = await collectCodexAppServerCatalogStateForRequest();
+  const models = executableModels(readCatalog(readCodexCatalogPath())?.models ?? [], input.spawnAgent.surface);
+  const configured = config.injectionModel?.trim() || null;
+  const exact = configured ? models.find(candidate => candidate.model === configured)?.model ?? null : null;
+  const host: SubagentModelAuthorityHost = {
+    catalogState: catalogState.state,
+    nativeDefaultState: await resolveNativeDefaultState(config),
+    preferredModel: exact,
+    preferredEffort: config.injectionEffort?.trim() || null,
+    executableModels: models,
+  };
+  return resolveSubagentModelAuthority(input, host);
+}