feat(billing): honor the gateway's model marks — authed fetches, safe defaults, locked pickers

Third slice of the cutover stack:

- Gateway /v1/models fetches send the user's token wherever one exists
  (Claude adapter, workspace-server preview/models, cloud agent, pi harness)
  so the gateway can mark plan-restricted models; the models caches key on
  auth presence so authed and anonymous responses never cross-serve.
- pickAllowedModel keeps session defaults off restricted models — a
  free-tier org lands on the free model instead of a premium default that
  403s its first message. Applied on the Claude-family default paths; codex
  free tier has no allowed models, so its sends surface the PR-1 modal.
- Restricted models stay listed and render dimmed with a lock
  (ModelRadioItem); picking one opens the upgrade gate instead of selecting.
  Marks ride option _meta (posthog.code/restrictedModel); no codex
  model/list threading — its live options stay unmarked by design.
- The pi harness drops restricted models (no locked rendering there) and
  falls back to the first served model when the preferred one is gone.

Generated-By: PostHog Code
Task-Id: 1039ea23-9930-44e2-9888-b05cf8b129ec

Author: adboio

packages/agent/src/adapters/base-acp-agent.ts

@@ -16,6 +16,7 @@ import type {
   WriteTextFileRequest,
   WriteTextFileResponse,
 } from "@agentclientprotocol/sdk";
+import { restrictedModelMeta } from "@posthog/shared";
 import {
   DEFAULT_GATEWAY_MODEL,
   fetchGatewayModels,
@@ -25,6 +26,7 @@ import {
   isAnthropicModel,
   isCloudflareModel,
   isCloudflareModelId,
+  pickAllowedModel,
 } from "../gateway-models";
 import { Logger } from "../utils/logger";
 /**
@@ -136,22 +138,30 @@ export abstract class BaseAcpAgent implements Agent {
   async getModelConfigOptions(
     currentModelOverride?: string,
     gatewayUrl?: string,
+    gatewayAuthToken?: string,
   ): Promise<{
     currentModelId: string;
     options: SessionConfigSelectOption[];
   }> {
+    // Authenticated so the gateway can mark plan-restricted models —
+    // anonymous fetches see everything allowed.
     this.gatewayModels = await fetchGatewayModels(
-      gatewayUrl ? { gatewayUrl } : undefined,
+      gatewayUrl ? { gatewayUrl, authToken: gatewayAuthToken } : undefined,
     );
 
-    const options = this.gatewayModels
+    const adapterModels = this.gatewayModels
       // Cloudflare models are servable on the Claude adapter too — the gateway translates the
       // `@cf/` path onto its Anthropic-Messages surface — so include them alongside Anthropic models.
-      .filter((model) => isAnthropicModel(model) || isCloudflareModel(model))
+      .filter((model) => isAnthropicModel(model) || isCloudflareModel(model));
+
+    const options = adapterModels
       .map((model) => ({
         value: model.id,
         name: formatGatewayModelName(model),
         description: `Context: ${model.context_window.toLocaleString()} tokens`,
+        // Locked models stay listed so the picker can gate them instead of
+        // silently dropping them.
+        ...(model.allowed ? {} : { _meta: restrictedModelMeta() }),
       }))
       // Sort oldest-to-newest so the picker is deterministic and the newest
       // model lands at the end of the list, closest to the trigger.
@@ -186,6 +196,11 @@ export abstract class BaseAcpAgent implements Agent {
       }
     }
 
+    // Never auto-select a model the org's plan can't use — it would 403 on
+    // the first message. An explicit user pick still goes through the
+    // picker's upgrade gate.
+    currentModelId = pickAllowedModel(adapterModels, currentModelId);
+
     if (!options.some((opt) => opt.value === currentModelId)) {
       options.unshift({
         value: currentModelId,

packages/agent/src/adapters/claude/claude-agent.ts

@@ -2097,6 +2097,7 @@ export class ClaudeAcpAgent extends BaseAcpAgent {
       this.getModelConfigOptions(
         settingsManager.getSettings().model || meta?.model || undefined,
         this.options?.gatewayEnv?.anthropicBaseUrl,
+        this.options?.gatewayEnv?.anthropicAuthToken,
       ),
       ...(meta?.taskRunId
         ? [

packages/agent/src/gateway-models.test.ts

@@ -8,6 +8,7 @@ import {
   isAnthropicModel,
   isBlockedModelId,
   isCloudflareModel,
+  pickAllowedModel,
 } from "./gateway-models";
 
 const model = (id: string, owned_by = ""): GatewayModel => ({
@@ -16,6 +17,7 @@ const model = (id: string, owned_by = ""): GatewayModel => ({
   context_window: 128000,
   supports_streaming: true,
   supports_vision: false,
+  allowed: true,
 });
 
 describe("formatGatewayModelName", () => {
@@ -27,6 +29,7 @@ describe("formatGatewayModelName", () => {
         context_window: 200000,
         supports_streaming: true,
         supports_vision: true,
+        allowed: true,
       }),
     ).toBe("Claude Opus 4.8");
   });
@@ -39,6 +42,7 @@ describe("formatGatewayModelName", () => {
         context_window: 200000,
         supports_streaming: true,
         supports_vision: true,
+        allowed: true,
       }),
     ).toBe("gpt-5.5");
   });
@@ -51,6 +55,7 @@ describe("formatGatewayModelName", () => {
         context_window: 200000,
         supports_streaming: true,
         supports_vision: true,
+        allowed: true,
       }),
     ).toBe("gpt-5.5");
   });
@@ -63,6 +68,7 @@ describe("formatGatewayModelName", () => {
         context_window: 128000,
         supports_streaming: true,
         supports_vision: false,
+        allowed: true,
       }),
     ).toBe("glm-5.2");
   });
@@ -189,3 +195,46 @@ describe("isCloudflareModel", () => {
     expect(isAnthropicModel(glm)).toBe(false);
   });
 });
+
+describe("pickAllowedModel", () => {
+  const entry = (id: string, allowed: boolean) => ({ id, allowed });
+
+  it.each([
+    [
+      "keeps an allowed preferred model",
+      [entry("claude-opus-4-8", true)],
+      "claude-opus-4-8",
+      "claude-opus-4-8",
+    ],
+    [
+      "keeps a preferred model absent from the list",
+      [entry("claude-opus-4-8", true)],
+      "claude-sonnet-5",
+      "claude-sonnet-5",
+    ],
+    [
+      "moves a restricted preferred model to the newest allowed one",
+      [
+        entry("claude-opus-4-8", false),
+        entry("claude-sonnet-4-6", true),
+        entry("@cf/zai-org/glm-5.2", true),
+      ],
+      "claude-opus-4-8",
+      "@cf/zai-org/glm-5.2",
+    ],
+    [
+      "keeps the preferred model when everything is restricted",
+      [entry("claude-opus-4-8", false)],
+      "claude-opus-4-8",
+      "claude-opus-4-8",
+    ],
+    [
+      "keeps the preferred model when the list is empty",
+      [],
+      "claude-opus-4-8",
+      "claude-opus-4-8",
+    ],
+  ] as const)("%s", (_name, models, preferred, expected) => {
+    expect(pickAllowedModel(models, preferred)).toBe(expected);
+  });
+});

packages/agent/src/gateway-models.ts

@@ -4,15 +4,22 @@ export interface GatewayModel {
   context_window: number;
   supports_streaming: boolean;
   supports_vision: boolean;
+  // Free-tier model gate: authenticated fetches mark models outside the
+  // caller's plan `allowed: false`. Anonymous fetches and older gateways
+  // don't mark, so absence means allowed.
+  allowed: boolean;
+  restriction_reason?: string | null;
 }
 
 interface GatewayModelsResponse {
   object: "list";
-  data: GatewayModel[];
+  data: Array<Omit<GatewayModel, "allowed"> & { allowed?: boolean }>;
 }
 
 export interface FetchGatewayModelsOptions {
   gatewayUrl: string;
+  /** Bearer token; required for accurate free-tier marks. */
+  authToken?: string;
 }
 
 export const DEFAULT_GATEWAY_MODEL = "claude-opus-4-8";
@@ -42,12 +49,19 @@ export function isBlockedModelId(modelId: string): boolean {
   return BLOCKED_MODELS.has(modelId.toLowerCase());
 }
 
+interface ModelsListEntry {
+  id?: string;
+  owned_by?: string;
+  allowed?: boolean;
+  restriction_reason?: string | null;
+}
+
 type ModelsListResponse =
   | {
-      data?: Array<{ id?: string; owned_by?: string }>;
-      models?: Array<{ id?: string; owned_by?: string }>;
+      data?: ModelsListEntry[];
+      models?: ModelsListEntry[];
     }
-  | Array<{ id?: string; owned_by?: string }>;
+  | ModelsListEntry[];
 
 const CACHE_TTL = 10 * 60 * 1000; // 10 minutes
 
@@ -57,11 +71,29 @@ const CACHE_TTL = 10 * 60 * 1000; // 10 minutes
 // the callers fall through to `return []`.
 const GATEWAY_FETCH_TIMEOUT_MS = 10_000;
 
-let gatewayModelsCache: {
-  models: GatewayModel[];
+// Authed and anonymous responses differ (free-tier marks are authed-only),
+// so cache entries are keyed on auth presence.
+interface ModelsCache<T> {
+  models: T[];
   expiry: number;
   url: string;
-} | null = null;
+  authed: boolean;
+}
+
+function readModelsCache<T>(
+  cache: ModelsCache<T> | null,
+  url: string,
+  authed: boolean,
+): T[] | null {
+  if (!cache || cache.url !== url || cache.authed !== authed) return null;
+  return Date.now() < cache.expiry ? cache.models : null;
+}
+
+function authHeaders(authToken?: string): Record<string, string> | undefined {
+  return authToken ? { Authorization: `Bearer ${authToken}` } : undefined;
+}
+
+let gatewayModelsCache: ModelsCache<GatewayModel> | null = null;
 
 export async function fetchGatewayModels(
   options?: FetchGatewayModelsOptions,
@@ -71,18 +103,15 @@ export async function fetchGatewayModels(
     return [];
   }
 
-  if (
-    gatewayModelsCache &&
-    gatewayModelsCache.url === gatewayUrl &&
-    Date.now() < gatewayModelsCache.expiry
-  ) {
-    return gatewayModelsCache.models;
-  }
+  const authed = Boolean(options?.authToken);
+  const cached = readModelsCache(gatewayModelsCache, gatewayUrl, authed);
+  if (cached) return cached;
 
   const modelsUrl = `${gatewayUrl}/v1/models`;
 
   try {
     const response = await fetch(modelsUrl, {
+      headers: authHeaders(options?.authToken),
       signal: AbortSignal.timeout(GATEWAY_FETCH_TIMEOUT_MS),
     });
 
@@ -91,11 +120,14 @@ export async function fetchGatewayModels(
     }
 
     const data = (await response.json()) as GatewayModelsResponse;
-    const models = (data.data ?? []).filter((m) => !isBlockedModelId(m.id));
+    const models = (data.data ?? [])
+      .filter((m) => !isBlockedModelId(m.id))
+      .map((m) => ({ ...m, allowed: m.allowed !== false }));
     gatewayModelsCache = {
       models,
       expiry: Date.now() + CACHE_TTL,
       url: gatewayUrl,
+      authed,
     };
     return models;
   } catch {
@@ -136,13 +168,11 @@ export function isCloudflareModel(model: GatewayModel): boolean {
 export interface ModelInfo {
   id: string;
   owned_by?: string;
+  allowed: boolean;
+  restriction_reason?: string | null;
 }
 
-let modelsListCache: {
-  models: ModelInfo[];
-  expiry: number;
-  url: string;
-} | null = null;
+let modelsListCache: ModelsCache<ModelInfo> | null = null;
 
 export async function fetchModelsList(
   options?: FetchGatewayModelsOptions,
@@ -152,17 +182,14 @@ export async function fetchModelsList(
     return [];
   }
 
-  if (
-    modelsListCache &&
-    modelsListCache.url === gatewayUrl &&
-    Date.now() < modelsListCache.expiry
-  ) {
-    return modelsListCache.models;
-  }
+  const authed = Boolean(options?.authToken);
+  const cached = readModelsCache(modelsListCache, gatewayUrl, authed);
+  if (cached) return cached;
 
   try {
     const modelsUrl = `${gatewayUrl}/v1/models`;
     const response = await fetch(modelsUrl, {
+      headers: authHeaders(options?.authToken),
       signal: AbortSignal.timeout(GATEWAY_FETCH_TIMEOUT_MS),
     });
     if (!response.ok) {
@@ -177,19 +204,48 @@ export async function fetchModelsList(
       const id = model?.id ? String(model.id) : "";
       if (!id) continue;
       if (isBlockedModelId(id)) continue;
-      results.push({ id, owned_by: model?.owned_by });
+      results.push({
+        id,
+        owned_by: model?.owned_by,
+        allowed: model?.allowed !== false,
+        restriction_reason: model?.restriction_reason ?? null,
+      });
     }
     modelsListCache = {
       models: results,
       expiry: Date.now() + CACHE_TTL,
       url: gatewayUrl,
+      authed,
     };
     return results;
   } catch {
     return [];
   }
 }
 
+/**
+ * The model a session should start on: the preferred id when present and
+ * allowed, else the newest allowed model — a free-tier org must not default
+ * onto a model that 403s its first message. Falls back to the preferred id
+ * when the list is empty (fetch failed) or nothing is allowed (all locked —
+ * the picker gate communicates that state better than a silent swap).
+ */
+export function pickAllowedModel(
+  models: ReadonlyArray<Pick<GatewayModel, "id" | "allowed">>,
+  preferred: string,
+): string {
+  if (models.length === 0) return preferred;
+  const preferredEntry = models.find((m) => m.id === preferred);
+  if (!preferredEntry || preferredEntry.allowed) return preferred;
+  const allowed = models.filter((m) => m.allowed);
+  if (allowed.length === 0) return preferred;
+  return allowed.reduce((best, candidate) =>
+    getClaudeModelRecency(candidate.id) >= getClaudeModelRecency(best.id)
+      ? candidate
+      : best,
+  ).id;
+}
+
 const PROVIDER_NAMES: Record<string, string> = {
   anthropic: "Anthropic",
   openai: "OpenAI",

packages/agent/src/server/agent-server.ts

@@ -1279,8 +1279,11 @@ export class AgentServer {
     });
 
     if (this.config.repoReadyFile && gatewayEnv.anthropicBaseUrl) {
+      // Authed so this cache-warm matches the session's own authed fetch
+      // (the models cache is keyed on auth presence).
       void fetchGatewayModels({
         gatewayUrl: gatewayEnv.anthropicBaseUrl,
+        authToken: gatewayEnv.anthropicAuthToken,
       }).catch(() => {});
     }