fix(server): Claude lists the models from its modelPicker setting

apps/server/src/provider/ClaudeModelPicker.test.ts

@@ -0,0 +1,103 @@
+import * as NodeServices from "@effect/platform-node/NodeServices";
+import { assert, it } from "@effect/vitest";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { ServerProviderModel } from "@t3tools/contracts";
+import { createModelCapabilities } from "@t3tools/shared/model";
+
+import { applyClaudeModelPicker, readClaudeModelPicker } from "./ClaudeModelPicker.ts";
+
+const builtIn = (slug: string): ServerProviderModel => ({
+  slug,
+  name: `Built-in ${slug}`,
+  shortName: `Short ${slug}`,
+  isCustom: false,
+  capabilities: createModelCapabilities({ optionDescriptors: [] }),
+});
+const builtInModels = [builtIn("claude-known"), builtIn("claude-other")];
+
+const writeSettings = Effect.fn(function* (settings: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const configDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-picker-" });
+  yield* fs.writeFileString(path.join(configDir, "settings.json"), settings);
+  return { homePath: configDir };
+});
+
+it.layer(NodeServices.layer)("Claude modelPicker", (it) => {
+  it.effect("lists picker rows first and keeps bundled models' controls under their label", () =>
+    Effect.gen(function* () {
+      const claudeSettings = yield* writeSettings(
+        JSON.stringify({
+          modelPicker: {
+            options: [
+              { model: "deepseek/deepseek-v4-pro", label: "DeepSeek V4 Pro" },
+              { model: "claude-other", label: "Work Claude" },
+              { model: "claude-known" },
+              { model: "kimi/kimi-k2.6" },
+              { model: "deepseek/deepseek-v4-pro", label: "duplicate" },
+              { model: "  " },
+              { label: "no model" },
+            ],
+          },
+        }),
+      );
+
+      const picker = yield* readClaudeModelPicker(claudeSettings, {});
+      const models = applyClaudeModelPicker(builtInModels, picker);
+
+      assert.deepStrictEqual(
+        models.map((model) => [model.slug, model.name, model.isCustom]),
+        [
+          ["deepseek/deepseek-v4-pro", "DeepSeek V4 Pro", false],
+          ["claude-other", "Work Claude", false],
+          ["claude-known", "Built-in claude-known", false],
+          ["kimi/kimi-k2.6", "kimi/kimi-k2.6", false],
+        ],
+      );
+      assert.strictEqual(models[1]?.capabilities, builtInModels[1]?.capabilities);
+      assert.isUndefined(models[1]?.shortName);
+      assert.strictEqual(models[2], builtInModels[0]);
+      assert.isNull(models[0]?.capabilities);
+    }),
+  );
+
+  it.effect("shows only the picker rows when replaceBuiltInOptions is set", () =>
+    Effect.gen(function* () {
+      const claudeSettings = yield* writeSettings(
+        JSON.stringify({
+          modelPicker: {
+            replaceBuiltInOptions: true,
+            options: [{ model: "kimi/kimi-k2.6", label: "Kimi K2.6" }],
+          },
+        }),
+      );
+
+      const picker = yield* readClaudeModelPicker(claudeSettings, {});
+
+      assert.deepStrictEqual(
+        applyClaudeModelPicker(builtInModels, picker).map((model) => model.slug),
+        ["kimi/kimi-k2.6"],
+      );
+    }),
+  );
+
+  it.effect("leaves the built-in list alone without a usable modelPicker", () =>
+    Effect.gen(function* () {
+      const malformed = yield* writeSettings("{ modelPicker: { options: 'nope' }, }");
+      const unusableRows = yield* writeSettings(
+        JSON.stringify({
+          modelPicker: { replaceBuiltInOptions: true, options: [{ model: "  " }, { label: "x" }] },
+        }),
+      );
+      const absent = yield* writeSettings("{}");
+      const missing = { homePath: `${absent.homePath}/missing` };
+
+      for (const claudeSettings of [malformed, unusableRows, absent, missing]) {
+        const picker = yield* readClaudeModelPicker(claudeSettings, {});
+        assert.strictEqual(applyClaudeModelPicker(builtInModels, picker), builtInModels);
+      }
+    }),
+  );
+});

apps/server/src/provider/ClaudeModelPicker.ts

@@ -0,0 +1,93 @@
+import type { ClaudeSettings, ServerProviderModel } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as FileSystem from "effect/FileSystem";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schema from "effect/Schema";
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import { fromLenientJson } from "@t3tools/shared/schemaJson";
+
+import { resolveClaudeHomePath } from "./Drivers/ClaudeHome.ts";
+import { claudeManagedSettingsPath } from "./Drivers/ClaudeSkills.ts";
+
+const ModelPickerSettings = fromLenientJson(
+  Schema.Struct({
+    modelPicker: Schema.optional(
+      Schema.Struct({
+        options: Schema.Array(Schema.Unknown),
+        replaceBuiltInOptions: Schema.optional(Schema.Boolean),
+      }),
+    ),
+  }),
+);
+const ModelPickerRow = Schema.Struct({
+  model: Schema.String,
+  label: Schema.optional(Schema.String),
+});
+
+const decodeModelPickerSettings = Schema.decodeUnknownEffect(ModelPickerSettings);
+const decodeModelPickerRow = Schema.decodeUnknownOption(ModelPickerRow);
+
+export interface ClaudeModelPicker {
+  readonly replaceBuiltInOptions: boolean;
+  /** Configured labels keyed by model id, in picker order. */
+  readonly labels: ReadonlyMap<string, string | undefined>;
+}
+
+// Claude Code ignores a project checkout's `modelPicker`, and the highest source
+// that defines one replaces the rest, so the first hit wins and nothing merges.
+export const readClaudeModelPicker = Effect.fn("readClaudeModelPicker")(function* (
+  claudeSettings: Pick<ClaudeSettings, "homePath">,
+  environment: NodeJS.ProcessEnv,
+) {
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const platform = yield* HostProcess.Platform;
+  const configDir = yield* resolveClaudeHomePath(claudeSettings, environment);
+  const managedPath = claudeManagedSettingsPath(path, platform, environment);
+
+  for (const settingsPath of [
+    ...(managedPath ? [managedPath] : []),
+    path.join(configDir, "settings.json"),
+  ]) {
+    const contents = yield* fileSystem
+      .readFileString(settingsPath)
+      .pipe(Effect.orElseSucceed(() => undefined));
+    if (contents === undefined) continue;
+    const picker = (yield* decodeModelPickerSettings(contents).pipe(
+      Effect.orElseSucceed(() => undefined),
+    ))?.modelPicker;
+    if (!picker) continue;
+
+    const labels = new Map<string, string | undefined>();
+    for (const option of picker.options) {
+      const row = Option.getOrUndefined(decodeModelPickerRow(option));
+      const slug = row?.model.trim();
+      if (row && slug && !labels.has(slug)) labels.set(slug, row.label?.trim() || undefined);
+    }
+    return labels.size === 0
+      ? undefined
+      : { replaceBuiltInOptions: picker.replaceBuiltInOptions === true, labels };
+  }
+  return undefined;
+});
+
+export function applyClaudeModelPicker(
+  builtInModels: ReadonlyArray<ServerProviderModel>,
+  picker: ClaudeModelPicker | undefined,
+): ReadonlyArray<ServerProviderModel> {
+  if (!picker) return builtInModels;
+  const builtInBySlug = new Map(builtInModels.map((model) => [model.slug, model]));
+  // Rows naming a bundled model keep its effort and context controls. Any other
+  // id goes to Claude Code verbatim with no controls, like a custom model.
+  const listed = [...picker.labels].map(([slug, label]): ServerProviderModel => {
+    const builtIn = builtInBySlug.get(slug);
+    if (!builtIn) return { slug, name: label ?? slug, isCustom: false, capabilities: null };
+    if (!label) return builtIn;
+    const { shortName: _shortName, ...rest } = builtIn;
+    return { ...rest, name: label };
+  });
+  return picker.replaceBuiltInOptions
+    ? listed
+    : [...listed, ...builtInModels.filter((model) => !picker.labels.has(model.slug))];
+}

apps/server/src/provider/ClaudeProvider.ts

@@ -52,6 +52,7 @@ import {
   resolveClaudeModelsForVersion,
   resolveClaudeUpdateRequiredModels,
 } from "./ClaudeModelCatalog.ts";
+import { applyClaudeModelPicker, readClaudeModelPicker } from "./ClaudeModelPicker.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
   optionDescriptors: [],
@@ -559,8 +560,9 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
     });
   }
 
+  const modelPicker = yield* readClaudeModelPicker(claudeSettings, resolvedEnvironment);
   const models = providerModelsFromSettings(
-    resolveClaudeModelsForVersion(modelCatalog, parsedVersion),
+    applyClaudeModelPicker(resolveClaudeModelsForVersion(modelCatalog, parsedVersion), modelPicker),
     claudeSettings.customModels,
     DEFAULT_CLAUDE_MODEL_CAPABILITIES,
   );

apps/server/src/provider/Drivers/ClaudeSkills.ts

@@ -104,7 +104,7 @@ function parseSkillFrontmatter(contents: string): SkillFrontmatter {
   };
 }
 
-function claudeManagedSettingsPath(
+export function claudeManagedSettingsPath(
   path: Path.Path,
   platform: NodeJS.Platform,
   environment: NodeJS.ProcessEnv,

apps/server/src/provider/ProviderRegistry.test.ts

@@ -4,6 +4,8 @@ import * as CodexInstallation from "./CodexInstallation.ts";
 import * as CodexManagedTokenBroker from "./CodexManagedTokenBroker.ts";
 import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
 import * as NodeServices from "@effect/platform-node/NodeServices";
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
 import { describe, it, assert, expect } from "@effect/vitest";
 import * as DateTime from "effect/DateTime";
 import * as Deferred from "effect/Deferred";
@@ -40,6 +42,7 @@ import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
 
 import { checkCodexProviderStatus, type CodexAppServerProviderSnapshot } from "./CodexProvider.ts";
 import { checkClaudeProviderStatus } from "./ClaudeProvider.ts";
+import { BUNDLED_CLAUDE_MODEL_CATALOG } from "./ClaudeModelCatalog.ts";
 import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
 import * as AntigravityInstallation from "./AntigravityInstallation.ts";
 import * as ModelManifest from "./ModelManifest.ts";
@@ -2407,5 +2410,46 @@ it.layer(
         ),
       ),
     );
+
+    it.effect("offers the models from Claude Code's modelPicker ahead of the catalog", () =>
+      Effect.gen(function* () {
+        const fs = yield* FileSystem.FileSystem;
+        const path = yield* Path.Path;
+        const configDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3-claude-status-" });
+        yield* fs.writeFileString(
+          path.join(configDir, "settings.json"),
+          JSON.stringify({
+            modelPicker: {
+              options: [
+                { model: "deepseek/deepseek-v4-pro", label: "DeepSeek V4 Pro" },
+                { model: "kimi/kimi-k2.6", label: "Kimi K2.6" },
+              ],
+            },
+          }),
+        );
+
+        const status = yield* checkClaudeProviderStatus(
+          { ...defaultClaudeSettings, homePath: configDir },
+          claudeCapabilities(),
+        );
+        assert.deepStrictEqual(
+          status.models.slice(0, 2).map((model) => [model.slug, model.name]),
+          [
+            ["deepseek/deepseek-v4-pro", "DeepSeek V4 Pro"],
+            ["kimi/kimi-k2.6", "Kimi K2.6"],
+          ],
+        );
+        assert.strictEqual(status.models[2]?.slug, "claude-opus-5-5");
+        assert.strictEqual(status.models.length, BUNDLED_CLAUDE_MODEL_CATALOG.models.length + 2);
+      }).pipe(
+        Effect.provide(
+          layerMockSpawner((args) => {
+            const joined = args.join(" ");
+            if (joined === "--version") return { stdout: "2.1.296\n", stderr: "", code: 0 };
+            throw new Error(`Unexpected args: ${joined}`);
+          }),
+        ),
+      ),
+    );
   });
 });

docs/user/providers-claude.md

@@ -110,9 +110,10 @@ If that Claude config directory has a cached Anthropic login, run `/logout` in a
 Claude Code session using that directory before starting the router setup. Cached
 login credentials can conflict with the router token.
 
-Select the model you want in T3 Code. For an OpenRouter model outside the built-in
-list, open that Claude instance in **Settings > Providers** and add its full model
-ID with **Add custom model**. Then select it in the chat model picker.
+Select the model you want in T3 Code. Models listed in that config directory's
+`modelPicker` already appear in the picker. For an OpenRouter model outside both
+the built-in list and `modelPicker`, open that Claude instance in **Settings > Providers**
+and add its full model ID with **Add custom model**. Then select it in the chat model picker.
 `ANTHROPIC_DEFAULT_*_MODEL` variables map Claude Code aliases such as `sonnet`; they
 do not replace the explicit model ID selected in T3 Code. Custom models may have
 fewer effort, thinking, or context controls than built-in models.