Skip to content
TypeScript

feat(server): list Claude models reported by Claude Code (#30511)

Julius Marmingedd69b3166561
diff --git a/apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts b/apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts
index c03916564e0..d71421debc7 100644
--- a/apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts
+++ b/apps/server/src/provider/ClaudeCapabilitiesProbe.test.ts
@@ -2,12 +2,16 @@
import * as NodeServices from "@effect/platform-node/NodeServices";
import { ClaudeSettings, type ServerProvider } from "@t3tools/contracts";
import { vi } from "vite-plus/test";
+import * as ClaudeSdk from "@anthropic-ai/claude-agent-sdk";
import { assert, it } from "@effect/vitest";
import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
import * as Schema from "effect/Schema";
+import * as TestClock from "effect/testing/TestClock";
import {
buildClaudeCapabilitiesProbeQueryOptions,
+ probeClaudeCapabilities,
probeClaudeWorkspaceSnapshot,
} from "./ClaudeProvider.ts";
@@ -41,3 +45,45 @@ it.effect("reports a deleted worktree's scan as finished, not pending", () =>
assert.strictEqual(snapshot.slashCommandsPending, false);
}).pipe(Effect.provide(NodeServices.layer)),
);
+
+it.effect("keeps the probe subprocess alive while gateway model discovery can finish", () =>
+ Effect.gen(function* () {
+ let abortSignal: AbortSignal | undefined;
+ const query = vi.spyOn(ClaudeSdk, "query").mockImplementation(({ options }) => {
+ abortSignal = options?.abortController?.signal;
+ return {
+ initializationResult: async () => ({
+ account: { email: "[email protected]", subscriptionType: "pro", tokenSource: "oauth" },
+ commands: [{ name: "review", description: "Review changes", argumentHint: "[path]" }],
+ models: [{ value: "gateway/claude-relay", displayName: "Relay", description: "" }],
+ }),
+ usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: () =>
+ new Promise((_, reject) => reject(new Error("usage unavailable"))),
+ } as ReturnType<typeof ClaudeSdk.query>;
+ });
+ yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
+ const fileSystem = yield* FileSystem.FileSystem;
+ const configDir = yield* fileSystem.makeTempDirectoryScoped();
+ // Claude Code also reads these from settings.json, which is where gateway users set them.
+ yield* fileSystem.writeFileString(
+ `${configDir}/settings.json`,
+ JSON.stringify({
+ env: {
+ ANTHROPIC_BASE_URL: "https://gateway.example",
+ CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: "1",
+ },
+ }),
+ );
+ const capabilities = yield* probeClaudeCapabilities(
+ yield* decodeClaudeSettings({ binaryPath: "claude" }),
+ { PATH: process.env.PATH, CLAUDE_CONFIG_DIR: configDir },
+ );
+ assert.deepEqual(
+ capabilities.models?.map((model) => model.value),
+ ["gateway/claude-relay"],
+ );
+ assert.equal(abortSignal?.aborted, false);
+ yield* TestClock.adjust("3 seconds");
+ assert.equal(abortSignal?.aborted, true);
+ }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+);
diff --git a/apps/server/src/provider/ClaudeModelCatalog.ts b/apps/server/src/provider/ClaudeModelCatalog.ts
index f67628efb83..d4fba425386 100644
--- a/apps/server/src/provider/ClaudeModelCatalog.ts
+++ b/apps/server/src/provider/ClaudeModelCatalog.ts
@@ -6,6 +6,7 @@ import {
type ServerProviderModel,
type ServerProviderUpdateRequiredModel,
} from "@t3tools/contracts";
+import type { ModelInfo as ClaudeModelInfo } from "@anthropic-ai/claude-agent-sdk";
import * as Option from "effect/Option";
import {
getModelSelectionStringOptionValue,
@@ -114,6 +115,66 @@ export function scopeClaudeModelCatalog(
return { models: [...builtInModels, ...customCatalogModels] };
}
+const CLAUDE_EFFORT_LABELS: Readonly<Record<string, string>> = {
+ low: "Low",
+ medium: "Medium",
+ high: "High",
+ xhigh: "Extra High",
+ max: "Max",
+};
+
+function stripClaudeContextWindowSuffix(value: string): string {
+ return value.replace(/\[[^\]]*\]$/, "").trim();
+}
+
+export function claudeReportedModels(
+ catalog: ClaudeModelCatalog,
+ customModels: ReadonlyArray<CustomModelSetting>,
+ reported: ReadonlyArray<ClaudeModelInfo> | undefined,
+): ReadonlyArray<ServerProviderModel> {
+ if (!reported?.length) return [];
+ const known = new Set(
+ [
+ ...catalog.models.flatMap(({ model }) => [model.slug, ...(model.aliases ?? [])]),
+ ...readCustomModelEntries(customModels).map((entry) => entry.slug),
+ ].map((id) => stripClaudeContextWindowSuffix(id).toLowerCase()),
+ );
+ const models: Array<ServerProviderModel> = [];
+ for (const info of reported) {
+ const slug = info.value.trim();
+ // `default` is Claude Code's pointer at its own default model, not a model.
+ if (!slug || slug === "default") continue;
+ const ids = [slug, info.resolvedModel ?? ""]
+ .map((id) => stripClaudeContextWindowSuffix(id).toLowerCase())
+ .filter((id) => id.length > 0);
+ if (ids.some((id) => known.has(id))) continue;
+ for (const id of ids) known.add(id);
+ const efforts = info.supportsEffort ? (info.supportedEffortLevels ?? []) : [];
+ models.push({
+ slug,
+ name: info.displayName.trim() || slug,
+ isCustom: false,
+ capabilities: {
+ optionDescriptors: efforts.length
+ ? [
+ {
+ id: "effort",
+ label: "Reasoning",
+ type: "select",
+ // `default` is not an effort, so choosing it sends none and Claude Code picks.
+ options: [
+ { id: "default", label: "Default", isDefault: true },
+ ...efforts.map((id) => ({ id, label: CLAUDE_EFFORT_LABELS[id] ?? id })),
+ ],
+ },
+ ]
+ : [],
+ },
+ });
+ }
+ return models;
+}
+
function resolveClaudeCatalogModel(
catalog: ClaudeModelCatalog,
slugOrAlias: string | null | undefined,
diff --git a/apps/server/src/provider/ClaudeProvider.ts b/apps/server/src/provider/ClaudeProvider.ts
index a596f613103..97512d3d621 100644
--- a/apps/server/src/provider/ClaudeProvider.ts
+++ b/apps/server/src/provider/ClaudeProvider.ts
@@ -18,6 +18,7 @@ import { createModelCapabilities } from "@t3tools/shared/model";
import { resolveSpawnCommand } from "@t3tools/shared/shell";
import {
query as claudeQuery,
+ type ModelInfo as ClaudeModelInfo,
type Options as ClaudeQueryOptions,
type SlashCommand as ClaudeSlashCommand,
type SDKControlGetUsageResponse,
@@ -48,6 +49,7 @@ import {
import {
BUNDLED_CLAUDE_MODEL_CATALOG,
type ClaudeModelCatalog,
+ claudeReportedModels,
formatClaudeVersionUpgradeMessage,
resolveClaudeModelsForVersion,
resolveClaudeUpdateRequiredModels,
@@ -241,6 +243,7 @@ export type ClaudeCapabilitiesProbe = {
/** OAuth applies only to firstParty; Bedrock uses external AWS credentials and omits subscription/token fields. */
readonly apiProvider: string | undefined;
readonly slashCommands: ReadonlyArray<ServerProviderSlashCommand>;
+ readonly models?: ReadonlyArray<ClaudeModelInfo>;
/** Undefined means get_usage failed; absent windows on success mean no subscription windows, as with API keys. */
readonly usage?: Pick<SDKControlGetUsageResponse, "rate_limits_available" | "rate_limits">;
readonly usageCheckedAt?: string;
@@ -318,6 +321,20 @@ function waitForAbortSignal(signal: AbortSignal): Promise<void> {
});
}
+/**
+ * With gateway model discovery on, Claude Code refreshes its model cache in the background after
+ * initialization, so the probe subprocess outlives init by Claude Code's discovery timeout.
+ */
+function claudeGatewayDiscoveryGraceMs(environment: Readonly<Record<string, unknown>>): number {
+ const enabled = String(environment.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY ?? "")
+ .trim()
+ .toLowerCase();
+ if (!enabled || enabled === "0" || enabled === "false") return 0;
+ if (!String(environment.ANTHROPIC_BASE_URL ?? "").trim()) return 0;
+ const configured = Number(environment.CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS);
+ return Number.isFinite(configured) && configured > 0 ? configured : 3_000;
+}
+
/** A never-yielding prompt allows local initialization IPC without sending an Anthropic request. */
const probeClaudeCapabilities = (
claudeSettings: ClaudeSettings,
@@ -326,6 +343,9 @@ const probeClaudeCapabilities = (
includeUsage = true,
) => {
const abort = new AbortController();
+ const abortProbe = Effect.sync(() => {
+ if (!abort.signal.aborted) abort.abort();
+ });
return Effect.gen(function* () {
const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
const executablePath = yield* resolveClaudeSdkExecutablePath(
@@ -333,6 +353,13 @@ const probeClaudeCapabilities = (
claudeEnvironment,
);
const managedMcpConfig = yield* hasClaudeManagedMcpConfig();
+ // Workspace probes (no usage) discard models; the machine probe refreshes the shared cache.
+ const graceMs = includeUsage
+ ? claudeGatewayDiscoveryGraceMs({
+ ...claudeEnvironment,
+ ...(yield* readClaudeSettingsEnv(claudeSettings, cwd, claudeEnvironment)),
+ })
+ : 0;
return yield* Effect.tryPromise(async () => {
const q = claudeQuery({
// oxlint-disable-next-line require-yield -- never yields, so no prompt reaches the API
@@ -348,11 +375,11 @@ const probeClaudeCapabilities = (
}),
});
const init = await q.initializationResult();
- return { q, init };
+ return { q, init, graceMs };
});
}).pipe(
Effect.timeout(CAPABILITIES_PROBE_TIMEOUT_MS),
- Effect.flatMap(({ q, init }) =>
+ Effect.flatMap(({ q, init, graceMs }) =>
Effect.gen(function* () {
// Usage has its own deadline so a slow optional request cannot discard initialization.
// Only the rate limits are read, so skip the local transcript scan that fills
@@ -386,15 +413,18 @@ const probeClaudeCapabilities = (
apiKeySource: account?.apiKeySource,
apiProvider: account?.apiProvider,
slashCommands: parseClaudeInitializationCommands(init.commands),
+ ...(init.models?.length ? { models: init.models } : {}),
...(usage ? { usage, usageCheckedAt } : {}),
} satisfies ClaudeCapabilitiesProbe;
- }),
- ),
- Effect.ensuring(
- Effect.sync(() => {
- if (!abort.signal.aborted) abort.abort();
- }),
+ }).pipe(
+ Effect.tap(() =>
+ graceMs > 0
+ ? Effect.sleep(graceMs).pipe(Effect.andThen(abortProbe), Effect.forkDetach)
+ : abortProbe,
+ ),
+ ),
),
+ Effect.onError(() => abortProbe),
Effect.tapError((error) =>
Effect.logWarning("Claude capability probe failed.", { errorTag: error._tag }),
),
@@ -557,11 +587,6 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
});
}
- const models = providerModelsFromSettings(
- resolveClaudeModelsForVersion(modelCatalog, parsedVersion),
- claudeSettings.customModels,
- DEFAULT_CLAUDE_MODEL_CAPABILITIES,
- );
const updateRequiredModels = resolveClaudeUpdateRequiredModels(modelCatalog, parsedVersion);
const versionUpgradeMessage = formatClaudeVersionUpgradeMessage(modelCatalog, parsedVersion);
@@ -572,6 +597,14 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
probeResult && Result.isSuccess(probeResult) ? probeResult.success : undefined;
const probeFailure =
probeResult && Result.isFailure(probeResult) ? probeResult.failure : undefined;
+ const models = providerModelsFromSettings(
+ [
+ ...resolveClaudeModelsForVersion(modelCatalog, parsedVersion),
+ ...claudeReportedModels(modelCatalog, claudeSettings.customModels, capabilities?.models),
+ ],
+ claudeSettings.customModels,
+ DEFAULT_CLAUDE_MODEL_CAPABILITIES,
+ );
const skills = yield* discoverClaudeSkills(claudeSettings, cwd, resolvedEnvironment);
const slashCommands = [COMPACT_SLASH_COMMAND, ...(capabilities?.slashCommands ?? [])];
const dedupedSlashCommands = dedupeSlashCommands(slashCommands);
diff --git a/apps/server/src/provider/Drivers/ClaudeSkills.ts b/apps/server/src/provider/Drivers/ClaudeSkills.ts
index 2bcf9ca472f..0d62109cce8 100644
--- a/apps/server/src/provider/Drivers/ClaudeSkills.ts
+++ b/apps/server/src/provider/Drivers/ClaudeSkills.ts
@@ -436,6 +436,9 @@ const resolveClaudeConfigDirPath = Effect.fn("resolveClaudeConfigDirPath")(funct
const SettingsEnv = Schema.Struct({
ANTHROPIC_BASE_URL: Schema.optional(Schema.String),
CLAUDE_CODE_ENTRYPOINT: Schema.optional(Schema.String),
+ // Unquoted JSON values must not fail the decode and drop ANTHROPIC_BASE_URL with them.
+ CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY: Schema.optional(Schema.Unknown),
+ CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS: Schema.optional(Schema.Unknown),
});
const decodeSettingsEnv = Schema.decodeUnknownEffect(
fromLenientJson(Schema.Struct({ env: Schema.optional(SettingsEnv) })),
diff --git a/apps/server/src/provider/ProviderRegistry.test.ts b/apps/server/src/provider/ProviderRegistry.test.ts
index 1fb343eb2de..e318a3c79a6 100644
--- a/apps/server/src/provider/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/ProviderRegistry.test.ts
@@ -6,6 +6,7 @@ import * as CodexManagedTokenBroker from "./CodexManagedTokenBroker.ts";
import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
import * as NodeServices from "@effect/platform-node/NodeServices";
+import type { ModelInfo } from "@anthropic-ai/claude-agent-sdk";
import { describe, it, assert, expect } from "@effect/vitest";
import * as DateTime from "effect/DateTime";
import * as Deferred from "effect/Deferred";
@@ -44,6 +45,7 @@ import { createModelCapabilities } from "@t3tools/shared/model";
import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
import { checkCodexProviderStatus, type CodexAppServerProviderSnapshot } from "./CodexProvider.ts";
+import { BUNDLED_CLAUDE_MODEL_CATALOG } from "./ClaudeModelCatalog.ts";
import { checkClaudeProviderStatus } from "./ClaudeProvider.ts";
import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
import * as AntigravityInstallation from "./AntigravityInstallation.ts";
@@ -175,6 +177,7 @@ type TestClaudeCapabilities = {
readonly apiKeySource: string | undefined;
readonly apiProvider: string | undefined;
readonly slashCommands: ReadonlyArray<ServerProviderSlashCommand>;
+ readonly models?: ReadonlyArray<ModelInfo>;
};
function claudeCapabilities(overrides: Partial<TestClaudeCapabilities> = {}) {
@@ -3038,6 +3041,72 @@ it.layer(
});
describe("checkClaudeProviderStatus", () => {
+ it.effect("adds models Claude Code reports that the catalog does not know", () =>
+ Effect.gen(function* () {
+ const status = yield* checkClaudeProviderStatus(
+ {
+ ...defaultClaudeSettings,
+ customModels: [{ slug: "gateway/kimi-3[1m]", name: "Kimi (mine)" }],
+ },
+ claudeCapabilities({
+ models: [
+ { value: "default", displayName: "Default", description: "" },
+ { value: "sonnet", displayName: "Sonnet", description: "" },
+ { value: "claude-haiku-4-5[1m]", displayName: "Haiku", description: "" },
+ {
+ value: "best",
+ resolvedModel: "claude-opus-5[1m]",
+ displayName: "Best",
+ description: "",
+ },
+ { value: "gateway/kimi-3[1m]", displayName: "Kimi 3", description: "" },
+ { value: "gateway/glm-5[1m]", displayName: "GLM 5", description: "" },
+ { value: "gateway/glm-5", displayName: "GLM 5 again", description: "" },
+ {
+ value: "gateway/claude-relay",
+ displayName: "Claude Relay",
+ description: "",
+ supportsEffort: true,
+ supportedEffortLevels: ["low", "high"],
+ },
+ ],
+ }),
+ );
+ const catalogSlugs = new Set(BUNDLED_CLAUDE_MODEL_CATALOG.models.map((m) => m.model.slug));
+ const added = status.models.filter((model) => !catalogSlugs.has(model.slug));
+
+ assert.deepStrictEqual(
+ added.map((model) => [model.slug, model.name, model.isCustom]),
+ [
+ ["gateway/glm-5[1m]", "GLM 5", false],
+ ["gateway/claude-relay", "Claude Relay", false],
+ ["gateway/kimi-3[1m]", "Kimi (mine)", true],
+ ],
+ );
+ assert.deepStrictEqual(added[0]?.capabilities?.optionDescriptors, []);
+ assert.deepStrictEqual(added[1]?.capabilities?.optionDescriptors, [
+ {
+ id: "effort",
+ label: "Reasoning",
+ type: "select",
+ options: [
+ { id: "default", label: "Default", isDefault: true },
+ { id: "low", label: "Low" },
+ { id: "high", label: "High" },
+ ],
+ },
+ ]);
+ }).pipe(
+ Effect.provide(
+ layerMockSpawner((args) => {
+ const joined = args.join(" ");
+ if (joined === "--version") return { stdout: "1.0.0\n", stderr: "", code: 0 };
+ throw new Error(`Unexpected args: ${joined}`);
+ }),
+ ),
+ ),
+ );
+
it.effect("reports a logged-out CLI as unauthenticated", () =>
Effect.gen(function* () {
const status = yield* checkClaudeProviderStatus(