@bitkyc08/opencodex 2.26.0 → 2.28.0

package/src/codex/auth-context.ts

@@ -12,7 +12,8 @@ import { ConfigMutationLockError } from "../config";
 import { isCodexAccountUsable } from "./account-usability";
 import { reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountToken, isMainAccountTokenLive } from "./main-account";
-import { isNativeMainTrafficBlocked } from "./native-profile-startup";
+import { isNativeMainTrafficBlocked, nativeMainStartupGateSnapshot } from "./native-profile-startup";
+import type { NativeMainStartupBlockReason } from "./native-profile-startup";
 import {
   codexQuotaScopeForModel,
   getCodexQuotaHealthSnapshot,
@@ -23,6 +24,13 @@ import {
   pickAlternateCodexAccount,
   resolveCodexAccountForThreadDetailed,
 } from "./routing";
+import {
+  entitledCodexAccountIdsForModel,
+  isDirectCallerEntitledToCodexModel,
+  resolveCodexModelEntitlements,
+  type CodexModelEntitlementSnapshot,
+} from "./model-entitlements";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
 import type { CodexCooldownSource, CodexQuotaScope } from "./routing";
 import { maskAccountId } from "../lib/privacy";
 import { formatErrorResponse } from "../bridge";
@@ -116,12 +124,63 @@ export const CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE =
   "OpenCodex local native-main profile maintenance is active; retry this request";
 
 export class CodexMainProfileDrainingError extends Error {
+  /**
+   * Which startup-gate state fenced this request, when one did. Undefined means the
+   * fence came from somewhere other than the startup gate — the turn-drain claim race
+   * throws this same error while the gate reads `ready`, and inventing a reason there
+   * would point the next report at a gate that never closed.
+   *
+   * Captured here rather than at the throw sites because this is the last moment it is
+   * both in scope and still true: every catch site has already lost it, and re-reading
+   * the gate later can observe a recovery that completed in between (#2108).
+   */
+  readonly reason?: NativeMainStartupBlockReason;
+
   constructor() {
     super(CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
     this.name = "CodexMainProfileDrainingError";
+    const gate = nativeMainStartupGateSnapshot();
+    if (gate.status !== "blocked") return;
+    this.reason = gate.reason;
+    reportNativeMainFenceReason(gate.reason);
   }
 }
 
+/**
+ * #2108: a reboot could leave this fence closed until `ocx restart`, and the report was
+ * unactionable because the settled reason was never written anywhere. It cannot ride the
+ * message (claude-messages.ts matches that string exactly to keep the fence a 503 rather
+ * than an Anthropic 529) and it cannot ride a header (/api/logs reads only error.message
+ * from the body, and the Claude surface rebuilds its response headers from scratch), so
+ * stdout is the one surface that covers every path this fence fires on.
+ *
+ * Deduped per distinct reason: the original report shows three 503s in eleven seconds and
+ * a real client retries harder than that, so a per-request line would bury the signal.
+ * Only the reason is emitted; the snapshot's homeId is derived from a profile directory.
+ */
+const reportedFenceReasons = new Set<NativeMainStartupBlockReason>();
+
+function reportNativeMainFenceReason(reason: NativeMainStartupBlockReason): void {
+  if (reportedFenceReasons.has(reason)) return;
+  reportedFenceReasons.add(reason);
+  console.warn(
+    `native-main admission is fenced (reason: ${reason}); native model requests return 503 until it clears`,
+  );
+}
+
+/**
+ * Test-only reset for the dedup set above.
+ *
+ * The dedup is process-lifetime module state, so it is order-sensitive across test files
+ * sharing one Bun process: whichever file constructs this error first consumes the one-shot
+ * warn, and a later file asserting on it would see nothing and pass vacuously. Any test that
+ * asserts on the warn must call this first — an `afterEach` in the asserting file is not
+ * enough on its own, because the consuming file may not be the asserting one.
+ */
+export function __resetNativeMainFenceReasonLog(): void {
+  reportedFenceReasons.clear();
+}
+
 export function codexMainProfileDrainingResponse(): Response {
   const response = formatErrorResponse(503, "server_busy", CODEX_MAIN_PROFILE_MAINTENANCE_MESSAGE);
   const headers = new Headers(response.headers);
@@ -237,6 +296,14 @@ export interface ResolveCodexAuthContextOptions {
   isMainAccountTokenLive?: () => boolean;
   getMainAccountToken?: typeof getMainAccountToken;
   primeCodexPoolQuotas?: (config: OcxConfig, reason: string) => Promise<void>;
+  /** Test seam for account-gated native model discovery. */
+  resolveCodexModelEntitlements?: (
+    config: Pick<OcxConfig, "codexAccounts">,
+  ) => Promise<CodexModelEntitlementSnapshot>;
+  /** Direct requests admitted with a proxy bearer substitute the stored native-main credential. */
+  substituteMainCredentialForDirect?: boolean;
+  /** Test seam for a Direct request's own forwarded ChatGPT credential. */
+  isDirectCallerEntitledToCodexModel?: (headers: Headers, modelId: string) => Promise<boolean>;
 }
 
 export interface CodexAccountSelectionAdmission {
@@ -260,8 +327,28 @@ export async function resolveCodexAuthContext(
   // selected stored credential even while the canonical OpenAI provider is globally Direct.
   if (mode === "direct" && fixedAccountId === undefined) {
     if (!hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
+    if (options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)) {
+      const entitled = options.substituteMainCredentialForDirect
+        ? entitledCodexAccountIdsForModel(
+            await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config),
+            options.modelId,
+          )?.has(MAIN_CODEX_ACCOUNT_ID) === true
+        : await (options.isDirectCallerEntitledToCodexModel ?? isDirectCallerEntitledToCodexModel)(
+            headers,
+            options.modelId,
+          );
+      if (!entitled) {
+        throw new CodexPoolAuthenticationError("The selected ChatGPT account does not support this model");
+      }
+    }
     return { kind: "main", accountId: null };
   }
+  const entitlementSnapshot = options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)
+    ? await (options.resolveCodexModelEntitlements ?? resolveCodexModelEntitlements)(config)
+    : undefined;
+  const modelEligibleAccountIds = entitlementSnapshot
+    ? entitledCodexAccountIdsForModel(entitlementSnapshot, options.modelId)
+    : undefined;
   // Retained startup recovery makes the physical main identity ineligible. Routing
   // can still preserve service by selecting a healthy configured pool account.
   const nativeMainTrafficBlocked = isNativeMainTrafficBlocked();
@@ -273,6 +360,7 @@ export async function resolveCodexAuthContext(
     nativeMainSelectionOnly: !nativeMainTrafficBlocked
       && selectionAdmission?.mainProfileDraining === true,
     isMainAccountTokenLive: options.isMainAccountTokenLive,
+    modelEligibleAccountIds,
   };
   let accountId: string;
   const quotaScope = codexQuotaScopeForModel(options.modelId);
@@ -302,7 +390,11 @@ export async function resolveCodexAuthContext(
     const selected = resolution.status === "selected" ? resolution.accountId : null;
     if (!selected) {
       if (fixedAccountId !== undefined) {
-        throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");
+        throw new CodexPoolAuthenticationError(
+          modelEligibleAccountIds && !modelEligibleAccountIds.has(fixedAccountId)
+            ? "Selected Codex account does not support this model"
+            : "Selected Codex account is unavailable",
+        );
       }
       // Recovery deliberately makes physical main ineligible. If no healthy
       // pool route is configured and main is the intended route, report the
@@ -312,7 +404,9 @@ export async function resolveCodexAuthContext(
       if (nativeMainTrafficBlocked && !options.excludeAccountId) {
         throw new CodexMainProfileDrainingError();
       }
-      throw new CodexPoolAuthenticationError();
+      throw new CodexPoolAuthenticationError(
+        modelEligibleAccountIds ? "No eligible Codex account supports this model" : undefined,
+      );
     }
     accountId = selected;
     if (accountId === MAIN_CODEX_ACCOUNT_ID && nativeMainTrafficBlocked) {
@@ -325,6 +419,17 @@ export async function resolveCodexAuthContext(
     ) {
       throw new CodexMainProfileDrainingError();
     }
+    // Some legacy Pool fallbacks preserve a configured active account even when it is not
+    // currently selectable, so token/cooldown code can produce the historical actionable error.
+    // Model entitlement is different: sending the request would spend a turn on an account whose
+    // authenticated roster already denied the model. Reassert this boundary after every selector.
+    if (modelEligibleAccountIds && !modelEligibleAccountIds.has(accountId)) {
+      throw new CodexPoolAuthenticationError(
+        fixedAccountId !== undefined
+          ? "Selected Codex account does not support this model"
+          : "No eligible Codex account supports this model",
+      );
+    }
     if (fixedAccountId !== undefined) {
       if (isCodexAccountPaused(config, accountId)) {
         throw new CodexPoolAuthenticationError("Selected Codex account is unavailable");

package/src/codex/catalog/aggregation.ts

@@ -183,6 +183,9 @@ export function deriveComboCatalogModel(
         ? { supportsServiceTier: false }
         : {}),
     ...(members.some(member => member.supportsReasoningSummaries === false) ? { supportsReasoningSummaries: false } : {}),
+    ...(members.every(member => member.codexToolMode === "shell")
+      ? { codexToolMode: "shell" as const }
+      : {}),
   };
 }
 

package/src/codex/catalog/metadata.ts

@@ -12,7 +12,7 @@ import { modelInList } from "../../types";
 import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
 import { getModelMetadata, getModelMetadataCaseInsensitive, listModelMetadata, resolveMetadataProvider } from "../../generated/model-metadata";
 import { enrichProviderFromRegistry, shouldCaseFoldMetadataModelId } from "../../providers/derive";
-import { getProviderRegistryEntry } from "../../providers/registry";
+import { getProviderRegistryEntry, providerCodexAccountMode } from "../../providers/registry";
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
 import { identifyRoutedModel } from "../../adapters/identity";
@@ -38,6 +38,7 @@ import { readCurrentCatalogOrCache, readCurrentCodexCatalog, readCurrentCodexMod
 import { trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./account-models";
 import { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
 import {
+  ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
   NATIVE_DAYBREAK_BLUE_MODEL,
   NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS,
   NATIVE_OPENAI_MODELS,
@@ -45,6 +46,8 @@ import {
   isNativeOpenAiCapabilityAliasModel,
   nativeOpenAiCapabilitySourceSlug,
 } from "./native-models";
+import { cachedAvailableAccountGatedNativeModels } from "../model-entitlements";
+import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
 export { CODEX_NATIVE_ALIAS_CATALOG_KIND } from "./kinds";
 export {
   NATIVE_DAYBREAK_BLUE_MODEL,
@@ -390,7 +393,14 @@ export function nativeModelRows(config: Pick<OcxConfig, "disabledModels" | "comb
   // Both user levers, not just the cap: a per-model window set from the dashboard has to show
   // up on the row the dashboard itself renders.
   const limits = nativeContextLimits(config);
-  return NATIVE_OPENAI_MODELS.filter(slug => !shadowed.has(slug)).map(slug => {
+  const bareEligibleAccountIds = providerCodexAccountMode(
+    OPENAI_CODEX_PROVIDER_ID,
+    config.providers?.[OPENAI_CODEX_PROVIDER_ID],
+  ) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
+  const availableGated = cachedAvailableAccountGatedNativeModels(Date.now(), bareEligibleAccountIds);
+  return NATIVE_OPENAI_MODELS
+    .filter(slug => !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableGated.has(slug))
+    .filter(slug => !shadowed.has(slug)).map(slug => {
     const contextWindow = nativeOpenAiContextWindow(slug, limits);
     const maxInputTokens = nativeOpenAiMaxInputTokens(slug, limits);
     return {
@@ -475,7 +485,11 @@ export function shouldUpgradeToUpstreamEntry(entry: RawEntry): boolean {
 
 export function nativeOpenAiSlugs(): string[] {
   const live = catalogNativeSlugs();
-  return live.length > 0 ? unique([...live, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]) : NATIVE_OPENAI_MODELS;
+  const availableGated = cachedAvailableAccountGatedNativeModels();
+  const candidates = live.length > 0 ? unique([...live, ...DOCUMENTED_NATIVE_OPENAI_ADDITIONS]) : NATIVE_OPENAI_MODELS;
+  return candidates.filter(slug => (
+    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableGated.has(slug)
+  ));
 }
 
 const ACCOUNT_BOUND_OPENAI_NATIVE_PREFIX = /^(?:gpt-|o1-|o3-|o4-)/;

package/src/codex/catalog/native-models.ts

@@ -1,12 +1,22 @@
 /** ChatGPT/Codex wire id observed for the account-native Daybreak Blue surface. */
 export const NATIVE_DAYBREAK_BLUE_MODEL = "gpt-daybreak-blue-latest";
 
+/** Native ChatGPT/Codex ids whose availability is proven per authenticated account. */
+export const ACCOUNT_GATED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
+  NATIVE_DAYBREAK_BLUE_MODEL,
+]);
+
 /**
  * Account-native aliases whose Codex capabilities track another pinned native row.
  *
  * This is catalog metadata inheritance only. Routing always preserves the requested
- * wire id, so the ChatGPT/Codex `gpt-daybreak-*` surface never collapses into the
- * separately billed API-key `daybreak-*-latest` surface or into `gpt-5.6-sol`.
+ * wire id for the separately billed API-key `daybreak-*-latest` surface, so the two never
+ * collapse into each other.
+ *
+ * The ChatGPT/Codex surface is different: an account-gated request IS rewritten to its
+ * canonical wire model before it leaves the process (`applyCodexAccountGatedWireNormalization`
+ * in src/server/responses/core.ts), because the authenticated backend rejects the gated slug
+ * on shards that do not carry it. The catalog keeps the product identity; only the wire moves.
  */
 const NATIVE_OPENAI_CAPABILITY_SOURCES: Readonly<Record<string, string>> = Object.freeze({
   [NATIVE_DAYBREAK_BLUE_MODEL]: "gpt-5.6-sol",
@@ -16,14 +26,14 @@ const NATIVE_OPENAI_CAPABILITY_SOURCES: Readonly<Record<string, string>> = Objec
  * Native ids whose capability metadata is inherited from another pinned native row.
  *
  * Membership here is about METADATA INHERITANCE only, and is independent of whether the
- * slug is also globally allowlisted in `NATIVE_OPENAI_MODELS`. `gpt-daybreak-blue-latest`
- * is now in BOTH: it inherits Sol's capability shape AND ships as a globally supported
- * native row (owner decision, devlog 260816_codexrs_multiagent_v2_and_history_perf/011).
+ * slug is also present in `NATIVE_OPENAI_MODELS`. `gpt-daybreak-blue-latest` is now in BOTH:
+ * it inherits Sol's capability shape AND is a supported account-gated native id (owner decision,
+ * devlog 260816_codexrs_multiagent_v2_and_history_perf/011).
  *
  * The maps that consume the union of these two lists (`PINNED_NATIVE_CAPABILITY_ENTRIES`,
  * `UPSTREAM_NATIVE_ENTRIES`) are keyed by slug, so an overlapping id collapses to one
- * entry. Catalog row generation iterates `NATIVE_OPENAI_MODELS` alone, so it still emits
- * exactly one bare row and one row per account selector.
+ * entry. Catalog row generation iterates `NATIVE_OPENAI_MODELS`, then entitlement evidence limits
+ * it to at most one bare row and one row per entitled account selector.
  */
 export const NATIVE_OPENAI_CAPABILITY_ALIAS_MODELS = Object.freeze(
   Object.keys(NATIVE_OPENAI_CAPABILITY_SOURCES),
@@ -42,16 +52,14 @@ export function nativeOpenAiCapabilitySourceSlug(slug: string): string {
  *
  * `gpt-daybreak-blue-latest` is entitlement-gated upstream: it is absent from codex-rs's
  * bundled catalog and reaches a client only through an authenticated `/models` response.
- * It is listed here by explicit owner decision so the row exists without waiting for an
- * observation, because opencodex injects `model_catalog_json` and codex-rs therefore builds
+ * It is listed here by explicit owner decision so the capability template exists without waiting
+ * for an observation, because opencodex injects `model_catalog_json` and codex-rs therefore builds
  * a `StaticModelsManager` whose refresh is a no-op — an entitled account had no way to
  * discover it on a clean install.
  *
- * Accepted tradeoff: an UNENTITLED account also sees the row. Catalog sync still succeeds;
- * selecting the model reaches the canonical OpenAI provider and the backend answers 400
- * "model not supported for this account", which is relayed (a bare pooled route may first
- * retry one alternate account on that exact body; a selector-qualified route is fixed and
- * relays immediately). `disabledModels` hides the row but is NOT a runtime routing denial.
+ * Availability is not static: catalog sync and Pool routing require the account's authenticated
+ * `/models` roster to contain the slug. An unconfirmed or unentitled account never receives the
+ * request. `disabledModels` remains the independent user visibility control.
  *
  * Devlog: 260816_codexrs_multiagent_v2_and_history_perf/011 §4-bis.
  */

package/src/codex/catalog/parsing.ts

@@ -126,6 +126,12 @@ export interface CatalogModel {
   /** Whether this exact routed model has a verified OpenAI-compatible service tier. */
   supportsServiceTier?: boolean;
   supportsReasoningSummaries?: boolean;
+  /**
+   * Codex tool calling mode for this routed model.
+   * "code_mode_only" (default) sets entry.tool_mode = "code_mode_only".
+   * "shell" leaves tool_mode unset so Codex declares top-level shell tools (exec_command).
+   */
+  codexToolMode?: "code_mode_only" | "shell";
   /** Normalized upstream capability names retained for management/API consumers (#485 follow-up). */
   capabilities?: string[];
   /** OpenCodex-only catalog ownership marker; Codex ignores the serialized extension field. */
@@ -423,7 +429,14 @@ export function catalogEntryIsNativeChatGpt(entry: RawEntry): boolean {
 
 export const ROUTED_CODEX_TOOL_MODE = "code_mode_only";
 
-export function applyRoutedCodexToolMode(entry: RawEntry): RawEntry {
+export function applyRoutedCodexToolMode(
+  entry: RawEntry,
+  toolMode?: "code_mode_only" | "shell" | string,
+): RawEntry {
+  if (toolMode === "shell") {
+    delete entry.tool_mode;
+    return entry;
+  }
   entry.tool_mode = ROUTED_CODEX_TOOL_MODE;
   return entry;
 }
@@ -490,10 +503,14 @@ export function applyMultiAgentMode(
   return entries;
 }
 
-export function normalizeRoutedCatalogEntry(entry: RawEntry, parallelToolCalls = false): RawEntry {
+export function normalizeRoutedCatalogEntry(
+  entry: RawEntry,
+  parallelToolCalls = false,
+  toolMode?: "code_mode_only" | "shell" | string,
+): RawEntry {
   delete entry.model_messages;
   delete entry.tool_mode;
-  applyRoutedCodexToolMode(entry);
+  applyRoutedCodexToolMode(entry, toolMode);
   delete entry.multi_agent_version;
   delete entry.use_responses_lite;
   delete entry.supports_websockets;

package/src/codex/catalog/provider-fetch.ts

@@ -413,6 +413,7 @@ function captureProviderGather(
     name,
     provider,
     registryTransportMatch,
+    configured,
   );
   const observedAuth = authResolver.kind === "observed"
     && provider.authMode !== "forward"
@@ -676,6 +677,7 @@ export function applyProviderConfigHints(name: string, prov: OcxProviderConfig,
     ...(prov.parallelToolCalls === true || (prov.adapter === "openai-chat" && prov.parallelToolCalls !== false)
       ? { parallelToolCalls: true }
       : {}),
+    ...(prov.codexToolMode !== undefined ? { codexToolMode: prov.codexToolMode } : {}),
   };
   const capped = applyProviderContextCap(hinted.contextWindow, providerCap);
   if (providerCap !== undefined && capped !== hinted.contextWindow) {
@@ -1881,6 +1883,11 @@ async function gatherRoutedModelsUncached(
       ...(Array.isArray(cm.reasoningEfforts) ? { reasoningEfforts: [...cm.reasoningEfforts] } : {}),
       ...(cm.defaultReasoningEffort ? { defaultReasoningEffort: cm.defaultReasoningEffort } : {}),
       ...(typeof supportsServiceTier === "boolean" ? { supportsServiceTier } : {}),
+      ...(cm.codexToolMode !== undefined
+        ? { codexToolMode: cm.codexToolMode }
+        : effectiveProvider?.codexToolMode !== undefined
+          ? { codexToolMode: effectiveProvider.codexToolMode }
+          : {}),
     };
     // #962: the dedupe below drops the provider-derived row this custom row replaces. Inherit that
     // row's provider capability metadata (reasoning ladder, default effort, parallel tool calls,
@@ -1905,6 +1912,7 @@ async function gatherRoutedModelsUncached(
       ...(base.parallelToolCalls === undefined && replaced.parallelToolCalls !== undefined ? { parallelToolCalls: replaced.parallelToolCalls } : {}),
       ...(base.supportsVerbosity === undefined && replaced.supportsVerbosity !== undefined ? { supportsVerbosity: replaced.supportsVerbosity } : {}),
       ...(base.supportsReasoningSummaries === undefined && replaced.supportsReasoningSummaries !== undefined ? { supportsReasoningSummaries: replaced.supportsReasoningSummaries } : {}),
+      ...(base.codexToolMode === undefined && replaced.codexToolMode !== undefined ? { codexToolMode: replaced.codexToolMode } : {}),
       ...(base.capabilities === undefined && replaced.capabilities !== undefined ? { capabilities: replaced.capabilities } : {}),
     } : base;
     // Vision-sidecar coverage ONLY: if the custom model is in the enriched provider's

package/src/codex/catalog/sync.ts

@@ -30,7 +30,15 @@ import { providerDestinationResolvedError } from "../../lib/destination-policy";
 import { redactSecretString } from "../../lib/redact";
 import upstreamModelsSnapshot from "../data/upstream-models.json";
 import { OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { providerCodexAccountMode } from "../../providers/registry";
 import { codexAccountNamespaceEntries, isMainCodexAccountTarget } from "../account-namespaces";
+import { MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import {
+  availableAccountGatedNativeModels,
+  isCodexModelEntitlementSnapshotCurrent,
+  resolveCodexModelEntitlements,
+  type CodexModelEntitlementSnapshot,
+} from "../model-entitlements";
 
 
 import { CODEX_CUSTOM_MODEL_CATALOG_KIND, CODEX_PROVIDER_MODEL_CATALOG_KIND, activeCodexModelsCachePath, applyCatalogMetadata, applyMultiAgentMode, applyNativeOpenAiContextOverride, applyRoutedCodexToolMode, catalogBackupPathFor, catalogHasRoutedEntries, catalogModelSlug, ensureStrictCatalogFields, findNativeTemplate, isDefaultCatalogPath, isRoutedModelCompatibilityExcluded, legacyCatalogBackupPath, normalizeRoutedCatalogEntry, normalizeServiceTiers, readCatalog, readCatalogBackup, readCodexCatalogPath, readNativeBaseline } from "./parsing";
@@ -64,6 +72,7 @@ import {
 } from "../internal/catalog-writer";
 import { codexRuntimeStatePath } from "../runtime";
 import { accountBoundNativeDisplayName, CODEX_ACCOUNT_BOUND_CATALOG_KIND, trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./account-models";
+import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./native-models";
 
 export const MAX_SPAWN_AGENT_MODEL_OVERRIDES = 5;
 
@@ -331,7 +340,9 @@ export function deriveEntry(
       // This exact provider/model pair is the ChatGPT/Codex forward surface. Keep the pinned
       // native tool/search/responses-lite contract while preserving the routed slug and wire id.
       if (!codexForwardNativeCapabilityAlias) {
-        normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true);
+        normalizeRoutedCatalogEntry(e, model?.parallelToolCalls === true, model?.codexToolMode);
+      } else if (model?.codexToolMode !== undefined) {
+        applyRoutedCodexToolMode(e, model.codexToolMode);
       }
       if (model) applyCatalogMetadata(e, model.provider, model.id, model.contextCap);
       applyCatalogModelMetadata(e, model);
@@ -358,8 +369,8 @@ export function deriveEntry(
     });
   }
   // Fallback when no template is available (best-effort; strict parser may need more).
-  // All routed fallbacks enable deferred code-mode tool exposure; otherwise the nested catalog
-  // expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
+  // Routed fallbacks default to code-mode tool exposure (or shell mode when codexToolMode === "shell");
+  // otherwise the nested catalog expands into `exec.description` and can exceed Cursor's 120 KB serialized tool limit (#1830).
   // Cursor still omits hosted web-search metadata because runTurn bypasses that separate sidecar.
   const isCursorFallback = isRouted && model?.provider === "cursor";
   const entry: RawEntry = {
@@ -373,7 +384,7 @@ export function deriveEntry(
       : {}),
   };
   if (isRouted) {
-    applyRoutedCodexToolMode(entry);
+    applyRoutedCodexToolMode(entry, model?.codexToolMode);
     applyReasoningLevels(entry, model?.reasoningEfforts, model?.defaultReasoningEffort, preserveExact);
   }
   else {
@@ -1236,6 +1247,7 @@ interface RetainedCatalogSyncWrite {
   readonly read: RetainedCatalogSyncRead;
   readonly permit: CatalogWritePermit;
   readonly owningCodexHome: string;
+  readonly modelEntitlements: CodexModelEntitlementSnapshot;
 }
 
 function optionalFileBytes(path: string): string | null {
@@ -1399,6 +1411,7 @@ function writeRetainedCatalogSync({
   read,
   permit,
   owningCodexHome,
+  modelEntitlements,
 }: RetainedCatalogSyncWrite): RetainedCatalogSyncResult {
   const { catalogPath, catalog, onDiskCatalog } = read;
   const catalogModelsForMerge = catalogModelsForMergeWithNativeRecovery(
@@ -1434,7 +1447,28 @@ function writeRetainedCatalogSync({
   const modelPickerOrder = config.modelPickerOrder ?? [];
   const multiAgentMode: MultiAgentMode = config.multiAgentMode === "v1" || config.multiAgentMode === "v2" ? config.multiAgentMode : "default";
   const exactComboSlugs = exactComboCatalogSlugs(config);
-  const suppressedBareNativeSlugs = desktopAllowlistSuppressedNativeSlugs(config);
+  const bareEligibleAccountIds = providerCodexAccountMode(
+    OPENAI_CODEX_PROVIDER_ID,
+    config.providers[OPENAI_CODEX_PROVIDER_ID],
+  ) === "direct" ? new Set([MAIN_CODEX_ACCOUNT_ID]) : undefined;
+  const availableBareGatedNativeSlugs = availableAccountGatedNativeModels(
+    modelEntitlements,
+    bareEligibleAccountIds,
+  );
+  const availableAccountGatedNativeSlugs = availableAccountGatedNativeModels(modelEntitlements);
+  const availableBareNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
+    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableBareGatedNativeSlugs.has(slug)
+  ));
+  const availableAccountNativeSlugs = NATIVE_OPENAI_MODELS.filter(slug => (
+    !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || availableAccountGatedNativeSlugs.has(slug)
+  ));
+  const unavailableGatedNativeSlugs = new Set([...ACCOUNT_GATED_NATIVE_OPENAI_MODELS].filter(slug => (
+    !availableBareGatedNativeSlugs.has(slug)
+  )));
+  const suppressedBareNativeSlugs = new Set([
+    ...desktopAllowlistSuppressedNativeSlugs(config),
+    ...unavailableGatedNativeSlugs,
+  ]);
   const hasPhysicalComboProvider = Object.hasOwn(config.providers, COMBO_NAMESPACE);
   const includeNativeOpenAi = shouldIncludeNativeOpenAi(config);
   const includeAccountBoundNativeOpenAi = shouldIncludeAccountBoundNativeOpenAi(config);
@@ -1449,12 +1483,21 @@ function writeRetainedCatalogSync({
     ...(onDiskCatalog?.models ?? []).filter(entry =>
       trustedAccountBoundNativeCatalogSlug(entry) !== undefined),
   ];
-  const accountNativeSlugs = accountSelectors.length > 0
-    ? accountBoundNativeOpenAiSlugs(observedAccountNativeEntries)
-    : [];
+  const accountTargets = new Map(codexAccountNamespaceEntries(config));
   const accountNativeSlugsBySelector = accountSelectors.length > 0
-    ? accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)
+    ? new Map([...accountBoundNativeOpenAiSlugsBySelector(config, observedAccountNativeEntries)].map(([selector, slugs]) => {
+      const target = accountTargets.get(selector);
+      const accountId = target && isMainCodexAccountTarget(target) ? MAIN_CODEX_ACCOUNT_ID : target;
+      const entitled = accountId ? modelEntitlements.modelsByAccount.get(accountId) : undefined;
+      const confirmed = accountId ? modelEntitlements.confirmedAccountIds.has(accountId) : false;
+      return [selector, slugs.filter(slug => (
+        !ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(slug) || (confirmed && entitled?.has(slug) === true)
+      ))] as const;
+    }))
     : new Map<string, readonly string[]>();
+  const accountNativeSlugs = accountSelectors.length > 0
+    ? [...new Set([...accountNativeSlugsBySelector.values()].flatMap(slugs => [...slugs]))]
+    : [];
   // Unknown account-native ids have no safe bare/global identity. They are only projected through
   // the selector map above; the no-selector catalog remains the static native/API-key surface.
   const observedNativeSlugs: string[] = [];
@@ -1508,7 +1551,7 @@ function writeRetainedCatalogSync({
   const accountBoundEntries = includeAccountBoundNativeOpenAi && accountSelectors.length > 0
     ? buildCatalogEntriesFromObservedState({
       template: template ? JSON.parse(JSON.stringify(template)) : null,
-      gptSlugs: NATIVE_OPENAI_MODELS,
+      gptSlugs: availableAccountNativeSlugs,
       goModels: [],
       featured,
       wsEnabled,
@@ -1548,7 +1591,7 @@ function writeRetainedCatalogSync({
     openaiContextCap,
     policy: {
       ...CANONICAL_NATIVE_CATALOG_CONTENT_POLICY,
-      nativeBackfillSlugs: [...NATIVE_OPENAI_MODELS, ...observedNativeSlugs],
+      nativeBackfillSlugs: [...availableBareNativeSlugs, ...observedNativeSlugs],
       warningPolicy: "emit",
     },
   });
@@ -1662,10 +1705,13 @@ export async function syncCatalogModels(
     evidence: retainedCatalogSyncEvidence(config, preflightRead.catalogPath, preflightRead.catalog),
     processEvidence: retainedCatalogProcessEvidence(),
   };
-  const goModels = await gatherRoutedModels(config, {
-    comboOmissions,
-    providerModelOutcomes,
-  });
+  const [goModels, modelEntitlements] = await Promise.all([
+    gatherRoutedModels(config, {
+      comboOmissions,
+      providerModelOutcomes,
+    }),
+    resolveCodexModelEntitlements(config),
+  ]);
   const committed = withCatalogWriteSerialization(owningCodexHome, permit => {
     // Desired state can flip OFF during the provider await above. The catalog
     // evidence revalidation below cannot see that — intent lives in our config,
@@ -1685,6 +1731,7 @@ export async function syncCatalogModels(
     }
     const current = revalidateRetainedCatalogSync(config, prepared);
     if (current === null) return null;
+    if (!isCodexModelEntitlementSnapshotCurrent(modelEntitlements)) return null;
     return writeRetainedCatalogSync({
       config,
       goModels,
@@ -1693,6 +1740,7 @@ export async function syncCatalogModels(
       read: current,
       permit,
       owningCodexHome,
+      modelEntitlements,
     });
   });
   if (committed.kind === "completed" && committed.value !== null) return committed.value;