@golba98/codexa 1.0.4 → 1.0.5

package/src/core/providerRuntime/claudeCodeDiscovery.ts

@@ -1,692 +1,724 @@
-import { existsSync, readFileSync, realpathSync } from "fs";
-import { dirname, join } from "path";
-import { buildClaudeSpawnSpec, resolveClaudeExecutable } from "../executables/claudeExecutable.js";
-import { runCommand } from "../process/CommandRunner.js";
-import type { CommandResult } from "../process/CommandRunner.js";
-import type { ReasoningEffortCapability } from "../models/codexModelCapabilities.js";
-import { ANTHROPIC_FALLBACK_MODELS } from "./models.js";
-import { CLAUDE_CODE_EFFORT_IDS, getClaudeCodeEffortLevels } from "./reasoning.js";
-import type { ProviderModel } from "./types.js";
-
-type CommandRunner = typeof runCommand;
-
-const CLAUDE_MODEL_FAMILIES = ["opus", "sonnet", "haiku"] as const;
-type ClaudeModelFamily = (typeof CLAUDE_MODEL_FAMILIES)[number];
-const CLAUDE_FAMILIES_ALT = CLAUDE_MODEL_FAMILIES.join("|");
-// Pre-compiled from CLAUDE_MODEL_FAMILIES — update that constant when new families are added.
-const RE_VERSIONED_ID = new RegExp(`\\bclaude-(?:${CLAUDE_FAMILIES_ALT})-(\\d+)(?:-(\\d+))?\\b`);
-const RE_VAGUE_LABEL = new RegExp(`^(?:claude\\s+)?(?:${CLAUDE_FAMILIES_ALT})$`, "i");
-
-export type ClaudeCodeModelSource =
-  | "claude-code"
-  | "claude-code-command"
-  | "claude-code-package"
-  | "claude-code-cache"
-  | "claude-code-config"
-  | "config"
-  | "settings"
-  | "fallback";
-
-export interface ClaudeCodeAuthInfo {
-  loggedIn: boolean;
-  authMethod?: string;
-  apiProvider?: string;
-  subscriptionType?: string;
-}
-
-export interface ClaudeCodeModel {
-  label: string;
-  family: string;
-  value: string;
-  canonicalId: string;
-  source: ClaudeCodeModelSource;
-  version?: string;
-  isFallback: boolean;
-  discoveryKind?: "models" | "aliases";
-  effortLevels: readonly string[];
-  defaultEffort: string;
-  effortSource: ClaudeCodeModelSource;
-  effortVerified: boolean;
-  description?: string;
-}
-
-export interface ClaudeCodeCapabilityDiscovery {
-  provider: "anthropic";
-  backend: "claude-code-cli";
-  resolvedCommand: string;
-  auth: ClaudeCodeAuthInfo;
-  models: ClaudeCodeModel[];
-  modelSource: ClaudeCodeModelSource;
-  discoveredAt: string;
-  settings?: {
-    path: string;
-    model?: string;
-    effortLevel?: string;
-    availableModels?: readonly string[];
-  };
-  diagnostics?: Record<string, string | number | boolean | null>;
-}
-
-export interface DiscoverClaudeCodeCapabilitiesOptions {
-  cwd: string;
-  runCommandImpl?: CommandRunner;
-  configuredPath?: string | null;
-  settingsPath?: string | null;
-  now?: () => Date;
-  timeoutMs?: number;
-  metadataPaths?: readonly string[];
-}
-
-interface ClaudeSettingsInfo {
-  path: string;
-  model?: string;
-  effortLevel?: string;
-  availableModels?: readonly string[];
-  models?: readonly ClaudeCodeModel[];
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
-function readString(value: unknown): string | undefined {
-  return typeof value === "string" && value.trim() ? value.trim() : undefined;
-}
-
-function readStringArray(value: unknown): string[] | undefined {
-  if (!Array.isArray(value)) return undefined;
-  const result = value.map(readString).filter((item): item is string => Boolean(item));
-  return result.length > 0 ? result : undefined;
-}
-
-export function parseClaudeAuthStatus(stdout: string): ClaudeCodeAuthInfo | null {
-  try {
-    const parsed = JSON.parse(stdout.trim()) as unknown;
-    if (!isRecord(parsed)) return null;
-    return {
-      loggedIn: parsed["loggedIn"] === true,
-      authMethod: readString(parsed["authMethod"]),
-      apiProvider: readString(parsed["apiProvider"]),
-      subscriptionType: readString(parsed["subscriptionType"]),
-    };
-  } catch {
-    return null;
-  }
-}
-
-function modelFamilyFromValue(value: string): ClaudeModelFamily {
-  const normalized = value.toLowerCase();
-  if (normalized.includes("opus")) return "opus";
-  if (normalized.includes("haiku")) return "haiku";
-  return "sonnet";
-}
-
-function fallbackModelByFamily(family: string): ProviderModel | undefined {
-  return ANTHROPIC_FALLBACK_MODELS.find((model) => model.family === family || model.modelId === family);
-}
-
-function fallbackEffortIds(family: string): string[] {
-  const fallback = fallbackModelByFamily(family);
-  return fallback?.supportedReasoningLevels?.map((level) => level.id) ?? ["low", "medium", "high"];
-}
-
-function fallbackDefaultEffort(family: string): string {
-  return fallbackModelByFamily(family)?.defaultReasoningLevel ?? "medium";
-}
-
-function titleCaseFamily(family: string): string {
-  if (family === "opus") return "Opus";
-  if (family === "haiku") return "Haiku";
-  return "Sonnet";
-}
-
-function versionFromModelText(value: string): string | null {
-  const normalized = value.trim().toLowerCase();
-  const idMatch = normalized.match(RE_VERSIONED_ID);
-  if (idMatch) return idMatch[2] ? `${idMatch[1]}.${idMatch[2]}` : idMatch[1] ?? null;
-  const labelMatch = normalized.match(/^(?:claude\s+)?(?:opus|sonnet|haiku)\s+(\d+(?:\.\d+)?)\b/);
-  return labelMatch?.[1] ?? null;
-}
-
-function compareVersionStrings(left: string | null | undefined, right: string | null | undefined): number {
-  const leftParts = (left ?? "").split(".").map((part) => Number.parseInt(part, 10));
-  const rightParts = (right ?? "").split(".").map((part) => Number.parseInt(part, 10));
-  const maxLength = Math.max(leftParts.length, rightParts.length);
-  for (let index = 0; index < maxLength; index += 1) {
-    const l = Number.isFinite(leftParts[index]) ? leftParts[index] : 0;
-    const r = Number.isFinite(rightParts[index]) ? rightParts[index] : 0;
-    if (l !== r) return l - r;
-  }
-  return 0;
-}
-
-function isVagueClaudeFamilyLabel(value: string): boolean {
-  return RE_VAGUE_LABEL.test(value.trim());
-}
-
-function normalizeClaudeDisplayLabel(value: string, rawLabel?: string): string {
-  const family = modelFamilyFromValue(value);
-  const familyLabel = titleCaseFamily(family);
-  const raw = rawLabel?.trim();
-  const valueVersion = versionFromModelText(value);
-
-  if (raw) {
-    const rawVersion = versionFromModelText(raw);
-    if (rawVersion) {
-      const prefixed = /^claude\b/i.test(raw) ? raw : `Claude ${raw}`;
-      return prefixed.replace(/\b(opus|sonnet|haiku)\b/i, familyLabel);
-    }
-    if (!isVagueClaudeFamilyLabel(raw) && !valueVersion) {
-      return raw;
-    }
-  }
-
-  if (valueVersion) return `Claude ${familyLabel} ${valueVersion}`;
-  return `Claude ${familyLabel} (version unknown)`;
-}
-
-function normalizeEffortIds(value: unknown, fallbackFamily: string): string[] {
-  const fromArray = readStringArray(value)
-    ?.filter((item) => CLAUDE_CODE_EFFORT_IDS.has(item));
-  return fromArray && fromArray.length > 0 ? fromArray : fallbackEffortIds(fallbackFamily);
-}
-
-function normalizeClaudeCodeModel(raw: unknown, source: ClaudeCodeModelSource): ClaudeCodeModel | null {
-  if (typeof raw === "string") {
-    const value = raw.trim();
-    if (!value) return null;
-    const family = modelFamilyFromValue(value);
-    const version = versionFromModelText(value) ?? undefined;
-    return {
-      label: normalizeClaudeDisplayLabel(value),
-      family,
-      value,
-      canonicalId: value,
-      source,
-      ...(version ? { version } : {}),
-      isFallback: source === "fallback",
-      effortLevels: fallbackEffortIds(family),
-      defaultEffort: fallbackDefaultEffort(family),
-      effortSource: "fallback",
-      effortVerified: false,
-      description: source === "settings" ? "Claude settings model" : undefined,
-    };
-  }
-
-  if (!isRecord(raw)) return null;
-  const value = readString(raw.value ?? raw.model ?? raw.modelId ?? raw.id ?? raw.name);
-  if (!value) return null;
-  const family = readString(raw.family) ?? modelFamilyFromValue(value);
-  // Accept both camelCase and snake_case effort field names for compatibility.
-  const rawEffortArray = raw.effortLevels ?? raw.effort_levels ?? raw.supportedEfforts ?? raw.supported_efforts;
-  const effortLevels = normalizeEffortIds(rawEffortArray, family);
-  const defaultEffort = readString(raw.defaultEffort ?? raw.default_effort ?? raw.effortLevel ?? raw.effort_level)
-    ?? fallbackDefaultEffort(family);
-  const hasRawEffortArray = Array.isArray(rawEffortArray);
-
-  const version = versionFromModelText(value) ?? versionFromModelText(readString(raw.label ?? raw.displayName ?? raw.display_name) ?? "");
-
-  return {
-    label: normalizeClaudeDisplayLabel(value, readString(raw.label ?? raw.displayName ?? raw.display_name)),
-    family,
-    value,
-    canonicalId: readString(raw.canonicalId ?? raw.canonical_id) ?? value,
-    source,
-    ...(version ? { version } : {}),
-    isFallback: source === "fallback",
-    discoveryKind: readString(raw.discoveryKind ?? raw.discovery_kind) === "aliases" ? "aliases" : "models",
-    effortLevels,
-    defaultEffort: effortLevels.includes(defaultEffort) ? defaultEffort : effortLevels[0] ?? "medium",
-    effortSource: hasRawEffortArray ? source : "fallback",
-    effortVerified: (source === "claude-code" || source === "claude-code-command" || source === "claude-code-package") && hasRawEffortArray,
-    description: readString(raw.description),
-  };
-}
-
-function dedupeModels(models: ClaudeCodeModel[]): ClaudeCodeModel[] {
-  const seen = new Set<string>();
-  const result: ClaudeCodeModel[] = [];
-  for (const model of models) {
-    const key = model.value.toLowerCase();
-    if (seen.has(key)) continue;
-    seen.add(key);
-    result.push(model);
-  }
-  return result;
-}
-
-function fallbackClaudeModels(): ClaudeCodeModel[] {
-  return ANTHROPIC_FALLBACK_MODELS.map((model) => ({
-    label: model.label,
-    family: model.family ?? model.modelId,
-    value: model.modelId,
-    canonicalId: model.canonicalId ?? model.modelId,
-    source: "fallback",
-    isFallback: true,
-    discoveryKind: "aliases",
-    effortLevels: model.supportedReasoningLevels?.map((level) => level.id) ?? [],
-    defaultEffort: model.defaultReasoningLevel ?? "medium",
-    effortSource: "fallback",
-    effortVerified: false,
-    description: model.description ?? undefined,
-  }));
-}
-
-function applyAvailableModelAllowlist(models: ClaudeCodeModel[], allowlist: readonly string[] | undefined): ClaudeCodeModel[] {
-  if (!allowlist || allowlist.length === 0) return models;
-  const allowed = new Set(allowlist.map((item) => item.toLowerCase()));
-  const filtered = models.filter((model) =>
-    allowed.has(model.value.toLowerCase()) ||
-    allowed.has(model.family.toLowerCase()) ||
-    allowed.has(model.canonicalId.toLowerCase()) ||
-    allowed.has(model.label.toLowerCase())
-  );
-  return filtered.length > 0 ? filtered : models;
-}
-
-function defaultClaudeSettingsPath(): string | null {
-  const home = process.env.USERPROFILE ?? process.env.HOME;
-  return home ? join(home, ".claude", "settings.json") : null;
-}
-
-function readClaudeSettings(settingsPath: string | null | undefined): ClaudeSettingsInfo | null {
-  const path = settingsPath === undefined ? defaultClaudeSettingsPath() : settingsPath;
-  if (!path || !existsSync(path)) return null;
-  try {
-    const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-    if (!isRecord(parsed)) return null;
-    // Accept both camelCase and snake_case field names — Claude settings.json has used both across versions.
-    const availableModels = readStringArray(parsed.availableModels ?? parsed.available_models);
-    const modelOverrides = parsed.modelOverrides ?? parsed.model_overrides;
-    const overrideModels = isRecord(modelOverrides)
-      ? Object.entries(modelOverrides)
-          .map(([key, value]) => normalizeClaudeCodeModel(
-            isRecord(value) ? { id: key, ...value } : key,
-            "settings",
-          ))
-          .filter((model): model is ClaudeCodeModel => Boolean(model))
-      : [];
-    return {
-      path,
-      model: readString(parsed.model ?? parsed.defaultModel ?? parsed.default_model),
-      effortLevel: readString(parsed.effortLevel ?? parsed.effort_level),
-      availableModels,
-      models: overrideModels,
-    };
-  } catch {
-    return null;
-  }
-}
-
-async function runClaudeCommand(
-  executable: string,
-  args: string[],
-  cwd: string,
-  runCommandImpl: CommandRunner,
-  timeoutMs: number,
-): Promise<CommandResult> {
-  const spawnSpec = buildClaudeSpawnSpec(executable, args);
-  return await runCommandImpl({
-    executable: spawnSpec.executable,
-    args: spawnSpec.args,
-    cwd,
-    timeoutMs,
-  }).result;
-}
-
-function parseModelsFromJsonOutput(stdout: string): ClaudeCodeModel[] {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(stdout.trim());
-  } catch {
-    return [];
-  }
-  const rawModels = Array.isArray(parsed)
-    ? parsed
-    : isRecord(parsed) && Array.isArray(parsed.models)
-      ? parsed.models
-      : isRecord(parsed) && Array.isArray(parsed.data)
-        ? parsed.data
-        : [];
-  return dedupeModels(
-    rawModels
-      .map((raw) => normalizeClaudeCodeModel(raw, "claude-code-command"))
-      .filter((model): model is ClaudeCodeModel => Boolean(model)),
-  );
-}
-
-interface ClaudeCodePackageMetadataDiscovery {
-  sourcePath: string;
-  rawModelIds: string[];
-  models: ClaudeCodeModel[];
-}
-
-function uniqueStrings(values: Iterable<string>): string[] {
-  return Array.from(new Set(Array.from(values).filter(Boolean)));
-}
-
-function executablePathCandidates(command: string): string[] {
-  if (command.includes("/") || command.includes("\\")) return [command];
-  const pathValue = process.env.PATH ?? "";
-  const extensions = process.platform === "win32"
-    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
-    : [""];
-  const candidates: string[] = [];
-  for (const directory of pathValue.split(process.platform === "win32" ? ";" : ":")) {
-    if (!directory) continue;
-    for (const extension of extensions) {
-      candidates.push(join(directory, `${command}${extension}`));
-    }
-  }
-  return candidates;
-}
-
-function defaultClaudeMetadataPaths(resolvedCommand: string): string[] {
-  const candidates: string[] = [];
-  for (const executablePath of executablePathCandidates(resolvedCommand)) {
-    candidates.push(executablePath);
-    try {
-      const realPath = realpathSync.native(executablePath);
-      candidates.push(realPath);
-      candidates.push(join(dirname(dirname(realPath)), "package.json"));
-    } catch {
-      // Best effort only: package metadata discovery must never block CLI probing.
-    }
-  }
-  return uniqueStrings(candidates);
-}
-
-function extractClaudeModelIdsFromMetadata(raw: Buffer): string[] {
-  const text = raw.toString("latin1");
-  const ids = new Set<string>();
-  // Fresh regex per call — /g flag requires a clean lastIndex on each invocation.
-  const pattern = new RegExp(`\\bclaude-(${CLAUDE_FAMILIES_ALT})-(\\d+)-(\\d{1,2})\\b`, "g");
-  for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
-    ids.add(match[0]);
-  }
-  return Array.from(ids);
-}
-
-function latestModelIdByFamily(modelIds: readonly string[]): Map<string, { id: string; version: string }> {
-  const result = new Map<string, { id: string; version: string }>();
-  for (const id of modelIds) {
-    const family = modelFamilyFromValue(id);
-    const version = versionFromModelText(id);
-    if (!version) continue;
-    const existing = result.get(family);
-    if (!existing || compareVersionStrings(version, existing.version) > 0) {
-      result.set(family, { id, version });
-    }
-  }
-  return result;
-}
-
-function aliasResolvedModel(family: string, canonicalId: string, version: string): ClaudeCodeModel {
-  const alias = family;
-  return {
-    label: normalizeClaudeDisplayLabel(canonicalId),
-    family,
-    value: alias,
-    canonicalId,
-    source: "claude-code-package",
-    version,
-    isFallback: false,
-    discoveryKind: "aliases",
-    effortLevels: fallbackEffortIds(family),
-    defaultEffort: fallbackDefaultEffort(family),
-    effortSource: "fallback",
-    effortVerified: false,
-    description: `Claude Code alias resolved to ${canonicalId} from installed package metadata`,
-  };
-}
-
-function resolveAliasModelsWithPackageMetadata(
-  models: readonly ClaudeCodeModel[],
-  packageMetadata: ClaudeCodePackageMetadataDiscovery | null,
-): ClaudeCodeModel[] {
-  if (!packageMetadata) return [...models];
-  const byFamily = new Map(packageMetadata.models.map((model) => [model.family, model]));
-  return models.map((model) => {
-    if (!isVagueClaudeFamilyLabel(model.value) || model.version) return model;
-    return byFamily.get(model.family) ?? model;
-  });
-}
-
-function allModelsHaveKnownVersions(models: readonly ClaudeCodeModel[]): boolean {
-  return models.length > 0 && models.every((model) => Boolean(model.version));
-}
-
-export function discoverModelsFromClaudePackageMetadata(
-  resolvedCommand: string,
-  metadataPaths?: readonly string[],
-): ClaudeCodePackageMetadataDiscovery | null {
-  const paths = metadataPaths
-    ? uniqueStrings(metadataPaths)
-    : defaultClaudeMetadataPaths(resolvedCommand);
-
-  for (const path of paths) {
-    if (!existsSync(path)) continue;
-    try {
-      const rawModelIds = extractClaudeModelIdsFromMetadata(readFileSync(path));
-      const latestByFamily = latestModelIdByFamily(rawModelIds);
-      const models = CLAUDE_MODEL_FAMILIES
-        .map((family) => {
-          const latest = latestByFamily.get(family);
-          return latest ? aliasResolvedModel(family, latest.id, latest.version) : null;
-        })
-        .filter((model): model is ClaudeCodeModel => Boolean(model));
-      if (models.length > 0) {
-        return {
-          sourcePath: path,
-          rawModelIds,
-          models,
-        };
-      }
-    } catch {
-      continue;
-    }
-  }
-  return null;
-}
-
-// Claude Code CLI does not consistently advertise JSON model listing in its help text,
-// so we probe these well-known command shapes directly first, before falling back to
-// help-text analysis. Each probe fails fast (non-zero exit) if unsupported.
-const PROBE_MODEL_LIST_ARGS: string[][] = [
-  ["model", "list", "--json"],
-  ["models", "--json"],
-  ["models", "list", "--json"],
-];
-
-function candidateModelListArgs(helpOutput: string): string[][] {
-  const text = helpOutput.toLowerCase();
-  const candidates: string[][] = [];
-  if (/model\s+list/.test(text) && /--json/.test(text)) {
-    candidates.push(["model", "list", "--json"]);
-  }
-  if (/models\s+list/.test(text) && /--json/.test(text)) {
-    candidates.push(["models", "list", "--json"]);
-  }
-  if (/\bmodels\b/.test(text) && /--json/.test(text)) {
-    candidates.push(["models", "--json"]);
-  }
-  return candidates;
-}
-
-async function discoverModelsFromClaudeHelp(
-  executable: string,
-  cwd: string,
-  runCommandImpl: CommandRunner,
-  timeoutMs: number,
-): Promise<ClaudeCodeModel[]> {
-  // Step 1: try well-known command shapes directly, without requiring the help text
-  // to advertise them. Claude Code CLI versions vary in whether (and how) they expose
-  // a model list command — probing directly is more reliable than help-text detection.
-  const triedArgKeys = new Set<string>();
-  for (const args of PROBE_MODEL_LIST_ARGS) {
-    triedArgKeys.add(args.join("\0"));
-    const result = await runClaudeCommand(executable, args, cwd, runCommandImpl, timeoutMs);
-    if (result.status === "completed" && result.exitCode === 0) {
-      const models = parseModelsFromJsonOutput(result.stdout);
-      if (models.length > 0) return models;
-    }
-  }
-
-  // Step 2: fall through to help-text-based detection as a supplementary strategy
-  // for future Claude Code versions that advertise additional model-list commands.
-  const helpResults = await Promise.all([
-    runClaudeCommand(executable, ["--help"], cwd, runCommandImpl, timeoutMs),
-    runClaudeCommand(executable, ["model", "--help"], cwd, runCommandImpl, timeoutMs),
-  ]);
-  const candidates = helpResults.flatMap((result) =>
-    result.status === "completed" && result.exitCode === 0
-      ? candidateModelListArgs(`${result.stdout}\n${result.stderr}`)
-      : []
-  );
-
-  for (const args of candidates) {
-    if (triedArgKeys.has(args.join("\0"))) continue; // skip already-probed commands
-    const result = await runClaudeCommand(executable, args, cwd, runCommandImpl, timeoutMs);
-    if (result.status !== "completed" || result.exitCode !== 0) continue;
-    const models = parseModelsFromJsonOutput(result.stdout);
-    if (models.length > 0) return models;
-  }
-  return [];
-}
-
-export function claudeCodeModelsToProviderModels(models: readonly ClaudeCodeModel[]): readonly ProviderModel[] {
-  return models.map((model) => ({
-    id: model.value,
-    modelId: model.value,
-    label: model.label,
-    description: model.description ?? (
-      model.source === "fallback"
-        ? `${model.label} - Fallback defaults${model.effortVerified ? "" : "; effort metadata unverified"}`
-        : model.source === "settings" || model.source === "config" || model.source === "claude-code-config"
-          ? `${model.label} - From Claude settings`
-          : `${model.label} - ${model.discoveryKind === "aliases" ? "Claude Code alias resolved" : "Discovered from Claude Code"} (${model.source})`
-    ),
-    defaultReasoningLevel: model.defaultEffort,
-    supportedReasoningLevels: getClaudeCodeEffortLevels(model.effortLevels),
-    source: model.source,
-    canonicalId: model.canonicalId,
-    family: model.family,
-    version: model.version,
-    isFallback: model.isFallback,
-    discoveryKind: model.discoveryKind,
-    effortSource: model.effortSource,
-    effortVerified: model.effortVerified,
-  }));
-}
-
-export async function discoverClaudeCodeCapabilities(
-  options: DiscoverClaudeCodeCapabilitiesOptions,
-): Promise<ClaudeCodeCapabilityDiscovery> {
-  const runCommandImpl = options.runCommandImpl ?? runCommand;
-  const timeoutMs = options.timeoutMs ?? 10_000;
-  const resolvedCommand = await resolveClaudeExecutable({
-    runCommandImpl: options.runCommandImpl,
-    cwd: options.cwd,
-    configuredPath: options.configuredPath,
-  });
-
-  const authResult = await runClaudeCommand(resolvedCommand, ["auth", "status"], options.cwd, runCommandImpl, timeoutMs);
-  const authJson = authResult.status === "completed" && authResult.exitCode === 0
-    ? parseClaudeAuthStatus(authResult.stdout)
-    : null;
-  const auth: ClaudeCodeAuthInfo = authJson?.loggedIn === true
-    ? authJson
-    : { loggedIn: false };
-
-  const settings = readClaudeSettings(options.settingsPath);
-  const discoveredModels = await discoverModelsFromClaudeHelp(resolvedCommand, options.cwd, runCommandImpl, timeoutMs);
-  const packageMetadata = discoverModelsFromClaudePackageMetadata(resolvedCommand, options.metadataPaths);
-
-  let modelSource: ClaudeCodeModelSource = "fallback";
-  let models: ClaudeCodeModel[] = fallbackClaudeModels();
-
-  if (discoveredModels.length > 0) {
-    const resolvedModels = resolveAliasModelsWithPackageMetadata(discoveredModels, packageMetadata);
-    modelSource = allModelsHaveKnownVersions(resolvedModels) && resolvedModels.some((model) => model.source === "claude-code-package")
-      ? "claude-code-package"
-      : "claude-code-command";
-    models = resolvedModels;
-  } else if (packageMetadata?.models && packageMetadata.models.length > 0) {
-    modelSource = "claude-code-package";
-    models = packageMetadata.models;
-  } else if (settings?.models && settings.models.length > 0) {
-    modelSource = "settings";
-    models = [...settings.models];
-  } else if (settings?.availableModels && settings.availableModels.length > 0) {
-    modelSource = "settings";
-    models = settings.availableModels
-      .map((model) => normalizeClaudeCodeModel(model, "settings"))
-      .filter((model): model is ClaudeCodeModel => Boolean(model));
-  }
-
-  if (settings?.model && !models.some((model) =>
-    model.value === settings.model || model.canonicalId === settings.model || model.family === settings.model
-  )) {
-    const settingsModel = normalizeClaudeCodeModel(settings.model, "settings");
-    if (settingsModel) {
-      models = [settingsModel, ...models];
-      if (modelSource === "fallback") modelSource = "settings";
-    }
-  }
-
-  models = applyAvailableModelAllowlist(dedupeModels(models), settings?.availableModels);
-
-  return {
-    provider: "anthropic",
-    backend: "claude-code-cli",
-    resolvedCommand,
-    auth,
-    models,
-    modelSource,
-    discoveredAt: (options.now?.() ?? new Date()).toISOString(),
-    ...(settings ? {
-      settings: {
-        path: settings.path,
-        ...(settings.model ? { model: settings.model } : {}),
-        ...(settings.effortLevel ? { effortLevel: settings.effortLevel } : {}),
-        ...(settings.availableModels ? { availableModels: settings.availableModels } : {}),
-      },
-    } : {}),
-    diagnostics: {
-      authExitCode: authResult.exitCode,
-      authStatus: authResult.status,
-      authJsonParsed: authJson !== null,
-      loggedIn: auth.loggedIn,
-      modelSource,
-      settingsPath: settings?.path ?? null,
-      packageMetadataPath: packageMetadata?.sourcePath ?? null,
-      packageMetadataModelCount: packageMetadata?.rawModelIds.length ?? 0,
-      rawPackageModelIds: packageMetadata?.rawModelIds.slice(0, 12).join(",") ?? null,
-    },
-  };
-}
-
-export function getClaudeModelDefaultEffort(modelId: string, models: readonly ProviderModel[]): string {
-  const normalized = modelId.toLowerCase();
-  const model = models.find((item) =>
-    item.modelId.toLowerCase() === normalized ||
-    item.id.toLowerCase() === normalized ||
-    item.family?.toLowerCase() === normalized ||
-    item.canonicalId?.toLowerCase() === normalized ||
-    (item.family ? normalized.includes(item.family.toLowerCase()) : false)
-  );
-  return model?.defaultReasoningLevel ?? "medium";
-}
-
-export function modelSupportsClaudeEffort(modelId: string, effort: string | null | undefined, models: readonly ProviderModel[]): boolean {
-  if (!effort) return false;
-  const normalized = modelId.toLowerCase();
-  const model = models.find((item) =>
-    item.modelId.toLowerCase() === normalized ||
-    item.id.toLowerCase() === normalized ||
-    item.family?.toLowerCase() === normalized ||
-    item.canonicalId?.toLowerCase() === normalized ||
-    (item.family ? normalized.includes(item.family.toLowerCase()) : false)
-  );
-  return Boolean(model?.supportedReasoningLevels?.some((level) => level.id === effort));
-}
+import { existsSync, readFileSync, realpathSync } from "fs";
+import { dirname, join } from "path";
+import { buildClaudeSpawnSpec, resolveClaudeExecutable } from "../executables/claudeExecutable.js";
+import { runCommand } from "../process/CommandRunner.js";
+import type { CommandResult } from "../process/CommandRunner.js";
+import type { ReasoningEffortCapability } from "../models/codexModelCapabilities.js";
+import { ANTHROPIC_FALLBACK_MODELS } from "./models.js";
+import { getClaudeCodeEffortLevels } from "./reasoning.js";
+import type { ProviderModel } from "./types.js";
+
+type CommandRunner = typeof runCommand;
+
+const CLAUDE_MODEL_FAMILIES = ["fable", "opus", "sonnet", "haiku"] as const;
+type ClaudeModelFamily = (typeof CLAUDE_MODEL_FAMILIES)[number];
+const CLAUDE_FAMILIES_ALT = CLAUDE_MODEL_FAMILIES.join("|");
+// Pre-compiled from CLAUDE_MODEL_FAMILIES — update that constant when new families are added.
+const RE_VERSIONED_ID = new RegExp(`\\bclaude-(?:${CLAUDE_FAMILIES_ALT})-(\\d+)(?:-(\\d+))?\\b`);
+const RE_VAGUE_LABEL = new RegExp(`^(?:claude\\s+)?(?:${CLAUDE_FAMILIES_ALT})$`, "i");
+
+export type ClaudeCodeModelSource =
+  | "claude-code"
+  | "claude-code-command"
+  | "claude-code-package"
+  | "claude-code-cache"
+  | "claude-code-config"
+  | "config"
+  | "settings"
+  | "fallback";
+
+export interface ClaudeCodeAuthInfo {
+  loggedIn: boolean;
+  authMethod?: string;
+  apiProvider?: string;
+  subscriptionType?: string;
+}
+
+export interface ClaudeCodeModel {
+  label: string;
+  family: string;
+  value: string;
+  canonicalId: string;
+  source: ClaudeCodeModelSource;
+  version?: string;
+  isFallback: boolean;
+  discoveryKind?: "models" | "aliases";
+  effortLevels: readonly string[];
+  defaultEffort: string;
+  effortSource: ClaudeCodeModelSource;
+  effortVerified: boolean;
+  description?: string;
+}
+
+export interface ClaudeCodeCapabilityDiscovery {
+  provider: "anthropic";
+  backend: "claude-code-cli";
+  resolvedCommand: string;
+  auth: ClaudeCodeAuthInfo;
+  models: ClaudeCodeModel[];
+  modelSource: ClaudeCodeModelSource;
+  discoveredAt: string;
+  settings?: {
+    path: string;
+    model?: string;
+    effortLevel?: string;
+    availableModels?: readonly string[];
+  };
+  diagnostics?: Record<string, string | number | boolean | null>;
+}
+
+export interface DiscoverClaudeCodeCapabilitiesOptions {
+  cwd: string;
+  runCommandImpl?: CommandRunner;
+  configuredPath?: string | null;
+  settingsPath?: string | null;
+  now?: () => Date;
+  timeoutMs?: number;
+  metadataPaths?: readonly string[];
+}
+
+interface ClaudeSettingsInfo {
+  path: string;
+  model?: string;
+  effortLevel?: string;
+  availableModels?: readonly string[];
+  models?: readonly ClaudeCodeModel[];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readStringArray(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const result = value.map(readString).filter((item): item is string => Boolean(item));
+  return result.length > 0 ? result : undefined;
+}
+
+export function parseClaudeAuthStatus(stdout: string): ClaudeCodeAuthInfo | null {
+  try {
+    const parsed = JSON.parse(stdout.trim()) as unknown;
+    if (!isRecord(parsed)) return null;
+    return {
+      loggedIn: parsed["loggedIn"] === true,
+      authMethod: readString(parsed["authMethod"]),
+      apiProvider: readString(parsed["apiProvider"]),
+      subscriptionType: readString(parsed["subscriptionType"]),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function parseClaudeEffortLevelsFromHelp(helpText: string): string[] | null {
+  const match = helpText.match(/^\s*--effort\b[^\r\n]*\(([^)]+)\)/im);
+  if (!match?.[1]) return null;
+  const levels = match[1].split(",").map((level) => level.trim()).filter(Boolean);
+  return levels.length > 0 ? levels : null;
+}
+
+function modelFamilyFromValue(value: string): ClaudeModelFamily {
+  const normalized = value.toLowerCase();
+  if (normalized.includes("fable")) return "fable";
+  if (normalized.includes("opus")) return "opus";
+  if (normalized.includes("haiku")) return "haiku";
+  return "sonnet";
+}
+
+function fallbackModelByFamily(family: string): ProviderModel | undefined {
+  return ANTHROPIC_FALLBACK_MODELS.find((model) => model.family === family || model.modelId === family);
+}
+
+function fallbackEffortIds(family: string): string[] {
+  const fallback = fallbackModelByFamily(family);
+  return fallback?.supportedReasoningLevels?.map((level) => level.id) ?? ["low", "medium", "high"];
+}
+
+function fallbackDefaultEffort(family: string): string {
+  return fallbackModelByFamily(family)?.defaultReasoningLevel ?? "medium";
+}
+
+function titleCaseFamily(family: string): string {
+  if (family === "fable") return "Fable";
+  if (family === "opus") return "Opus";
+  if (family === "haiku") return "Haiku";
+  return "Sonnet";
+}
+
+function versionFromModelText(value: string): string | null {
+  const normalized = value.trim().toLowerCase();
+  const idMatch = normalized.match(RE_VERSIONED_ID);
+  if (idMatch) return idMatch[2] ? `${idMatch[1]}.${idMatch[2]}` : idMatch[1] ?? null;
+  const labelMatch = normalized.match(new RegExp(`^(?:claude\\s+)?(?:${CLAUDE_FAMILIES_ALT})\\s+(\\d+(?:\\.\\d+)?)\\b`));
+  return labelMatch?.[1] ?? null;
+}
+
+function compareVersionStrings(left: string | null | undefined, right: string | null | undefined): number {
+  const leftParts = (left ?? "").split(".").map((part) => Number.parseInt(part, 10));
+  const rightParts = (right ?? "").split(".").map((part) => Number.parseInt(part, 10));
+  const maxLength = Math.max(leftParts.length, rightParts.length);
+  for (let index = 0; index < maxLength; index += 1) {
+    const l = Number.isFinite(leftParts[index]) ? leftParts[index] : 0;
+    const r = Number.isFinite(rightParts[index]) ? rightParts[index] : 0;
+    if (l !== r) return l - r;
+  }
+  return 0;
+}
+
+function isVagueClaudeFamilyLabel(value: string): boolean {
+  return RE_VAGUE_LABEL.test(value.trim());
+}
+
+function normalizeClaudeDisplayLabel(value: string, rawLabel?: string): string {
+  const family = modelFamilyFromValue(value);
+  const familyLabel = titleCaseFamily(family);
+  const raw = rawLabel?.trim();
+  const valueVersion = versionFromModelText(value);
+
+  if (raw) {
+    const rawVersion = versionFromModelText(raw);
+    if (rawVersion) {
+      const prefixed = /^claude\b/i.test(raw) ? raw : `Claude ${raw}`;
+      return prefixed.replace(/\b(opus|sonnet|haiku)\b/i, familyLabel);
+    }
+    if (!isVagueClaudeFamilyLabel(raw) && !valueVersion) {
+      return raw;
+    }
+  }
+
+  if (valueVersion) return `Claude ${familyLabel} ${valueVersion}`;
+  return `Claude ${familyLabel} (version unknown)`;
+}
+
+function normalizeEffortIds(value: unknown, fallbackFamily: string): string[] {
+  const fromArray = readStringArray(value);
+  return fromArray && fromArray.length > 0 ? fromArray : fallbackEffortIds(fallbackFamily);
+}
+
+function normalizeClaudeCodeModel(raw: unknown, source: ClaudeCodeModelSource): ClaudeCodeModel | null {
+  if (typeof raw === "string") {
+    const value = raw.trim();
+    if (!value) return null;
+    const family = modelFamilyFromValue(value);
+    const version = versionFromModelText(value) ?? undefined;
+    return {
+      label: normalizeClaudeDisplayLabel(value),
+      family,
+      value,
+      canonicalId: value,
+      source,
+      ...(version ? { version } : {}),
+      isFallback: source === "fallback",
+      effortLevels: fallbackEffortIds(family),
+      defaultEffort: fallbackDefaultEffort(family),
+      effortSource: "fallback",
+      effortVerified: false,
+      description: source === "settings" ? "Claude settings model" : undefined,
+    };
+  }
+
+  if (!isRecord(raw)) return null;
+  const value = readString(raw.value ?? raw.model ?? raw.modelId ?? raw.id ?? raw.name);
+  if (!value) return null;
+  const family = readString(raw.family) ?? modelFamilyFromValue(value);
+  // Accept both camelCase and snake_case effort field names for compatibility.
+  const rawEffortArray = raw.effortLevels ?? raw.effort_levels ?? raw.supportedEfforts ?? raw.supported_efforts;
+  const effortLevels = normalizeEffortIds(rawEffortArray, family);
+  const defaultEffort = readString(raw.defaultEffort ?? raw.default_effort ?? raw.effortLevel ?? raw.effort_level)
+    ?? fallbackDefaultEffort(family);
+  const hasRawEffortArray = Array.isArray(rawEffortArray);
+
+  const version = versionFromModelText(value) ?? versionFromModelText(readString(raw.label ?? raw.displayName ?? raw.display_name) ?? "");
+
+  return {
+    label: normalizeClaudeDisplayLabel(value, readString(raw.label ?? raw.displayName ?? raw.display_name)),
+    family,
+    value,
+    canonicalId: readString(raw.canonicalId ?? raw.canonical_id) ?? value,
+    source,
+    ...(version ? { version } : {}),
+    isFallback: source === "fallback",
+    discoveryKind: readString(raw.discoveryKind ?? raw.discovery_kind) === "aliases" ? "aliases" : "models",
+    effortLevels,
+    defaultEffort: effortLevels.includes(defaultEffort) ? defaultEffort : effortLevels[0] ?? "medium",
+    effortSource: hasRawEffortArray ? source : "fallback",
+    effortVerified: (source === "claude-code" || source === "claude-code-command" || source === "claude-code-package") && hasRawEffortArray,
+    description: readString(raw.description),
+  };
+}
+
+function dedupeModels(models: ClaudeCodeModel[]): ClaudeCodeModel[] {
+  const seen = new Set<string>();
+  const result: ClaudeCodeModel[] = [];
+  for (const model of models) {
+    const key = model.value.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(model);
+  }
+  return result;
+}
+
+function fallbackClaudeModels(): ClaudeCodeModel[] {
+  return ANTHROPIC_FALLBACK_MODELS.map((model) => ({
+    label: model.label,
+    family: model.family ?? model.modelId,
+    value: model.modelId,
+    canonicalId: model.canonicalId ?? model.modelId,
+    source: "fallback",
+    isFallback: true,
+    discoveryKind: "aliases",
+    effortLevels: model.supportedReasoningLevels?.map((level) => level.id) ?? [],
+    defaultEffort: model.defaultReasoningLevel ?? "medium",
+    effortSource: "fallback",
+    effortVerified: false,
+    description: model.description ?? undefined,
+  }));
+}
+
+function applyAvailableModelAllowlist(models: ClaudeCodeModel[], allowlist: readonly string[] | undefined): ClaudeCodeModel[] {
+  if (!allowlist || allowlist.length === 0) return models;
+  const allowed = new Set(allowlist.map((item) => item.toLowerCase()));
+  const filtered = models.filter((model) =>
+    allowed.has(model.value.toLowerCase()) ||
+    allowed.has(model.family.toLowerCase()) ||
+    allowed.has(model.canonicalId.toLowerCase()) ||
+    allowed.has(model.label.toLowerCase())
+  );
+  return filtered.length > 0 ? filtered : models;
+}
+
+function defaultClaudeSettingsPath(): string | null {
+  const home = process.env.USERPROFILE ?? process.env.HOME;
+  return home ? join(home, ".claude", "settings.json") : null;
+}
+
+function readClaudeSettings(settingsPath: string | null | undefined): ClaudeSettingsInfo | null {
+  const path = settingsPath === undefined ? defaultClaudeSettingsPath() : settingsPath;
+  if (!path || !existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
+    if (!isRecord(parsed)) return null;
+    // Accept both camelCase and snake_case field names — Claude settings.json has used both across versions.
+    const availableModels = readStringArray(parsed.availableModels ?? parsed.available_models);
+    const modelOverrides = parsed.modelOverrides ?? parsed.model_overrides;
+    const overrideModels = isRecord(modelOverrides)
+      ? Object.entries(modelOverrides)
+          .map(([key, value]) => normalizeClaudeCodeModel(
+            isRecord(value) ? { id: key, ...value } : key,
+            "settings",
+          ))
+          .filter((model): model is ClaudeCodeModel => Boolean(model))
+      : [];
+    return {
+      path,
+      model: readString(parsed.model ?? parsed.defaultModel ?? parsed.default_model),
+      effortLevel: readString(parsed.effortLevel ?? parsed.effort_level),
+      availableModels,
+      models: overrideModels,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function runClaudeCommand(
+  executable: string,
+  args: string[],
+  cwd: string,
+  runCommandImpl: CommandRunner,
+  timeoutMs: number,
+): Promise<CommandResult> {
+  const spawnSpec = buildClaudeSpawnSpec(executable, args);
+  return await runCommandImpl({
+    executable: spawnSpec.executable,
+    args: spawnSpec.args,
+    cwd,
+    timeoutMs,
+  }).result;
+}
+
+function parseModelsFromJsonOutput(stdout: string): ClaudeCodeModel[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(stdout.trim());
+  } catch {
+    return [];
+  }
+  const rawModels = Array.isArray(parsed)
+    ? parsed
+    : isRecord(parsed) && Array.isArray(parsed.models)
+      ? parsed.models
+      : isRecord(parsed) && Array.isArray(parsed.data)
+        ? parsed.data
+        : [];
+  return dedupeModels(
+    rawModels
+      .map((raw) => normalizeClaudeCodeModel(raw, "claude-code-command"))
+      .filter((model): model is ClaudeCodeModel => Boolean(model)),
+  );
+}
+
+interface ClaudeCodePackageMetadataDiscovery {
+  sourcePath: string;
+  rawModelIds: string[];
+  models: ClaudeCodeModel[];
+}
+
+function uniqueStrings(values: Iterable<string>): string[] {
+  return Array.from(new Set(Array.from(values).filter(Boolean)));
+}
+
+function executablePathCandidates(command: string): string[] {
+  if (command.includes("/") || command.includes("\\")) return [command];
+  const pathValue = process.env.PATH ?? "";
+  const extensions = process.platform === "win32"
+    ? (process.env.PATHEXT ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+    : [""];
+  const candidates: string[] = [];
+  for (const directory of pathValue.split(process.platform === "win32" ? ";" : ":")) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      candidates.push(join(directory, `${command}${extension}`));
+    }
+  }
+  return candidates;
+}
+
+function defaultClaudeMetadataPaths(resolvedCommand: string): string[] {
+  const candidates: string[] = [];
+  for (const executablePath of executablePathCandidates(resolvedCommand)) {
+    candidates.push(executablePath);
+    try {
+      const realPath = realpathSync.native(executablePath);
+      candidates.push(realPath);
+      candidates.push(join(dirname(dirname(realPath)), "package.json"));
+    } catch {
+      // Best effort only: package metadata discovery must never block CLI probing.
+    }
+  }
+  return uniqueStrings(candidates);
+}
+
+function extractClaudeModelIdsFromMetadata(raw: Buffer): string[] {
+  const text = raw.toString("latin1");
+  const ids = new Set<string>();
+  // Fresh regex per call — /g flag requires a clean lastIndex on each invocation.
+  // The minor version is optional (mirrors RE_VERSIONED_ID): major-only ids like
+  // claude-sonnet-5 must be discovered too. \d{1,2} keeps date suffixes
+  // (claude-haiku-4-5-20251001) from being absorbed into the version.
+  const pattern = new RegExp(`\\bclaude-(${CLAUDE_FAMILIES_ALT})-(\\d+)(?:-(\\d{1,2}))?\\b`, "g");
+  for (let match = pattern.exec(text); match; match = pattern.exec(text)) {
+    ids.add(match[0]);
+  }
+  return Array.from(ids);
+}
+
+function latestModelIdByFamily(modelIds: readonly string[]): Map<string, { id: string; version: string }> {
+  const result = new Map<string, { id: string; version: string }>();
+  for (const id of modelIds) {
+    const family = modelFamilyFromValue(id);
+    const version = versionFromModelText(id);
+    if (!version) continue;
+    const existing = result.get(family);
+    if (!existing || compareVersionStrings(version, existing.version) > 0) {
+      result.set(family, { id, version });
+    }
+  }
+  return result;
+}
+
+function aliasResolvedModel(family: string, canonicalId: string, version: string): ClaudeCodeModel {
+  const alias = family;
+  return {
+    label: normalizeClaudeDisplayLabel(canonicalId),
+    family,
+    value: alias,
+    canonicalId,
+    source: "claude-code-package",
+    version,
+    isFallback: false,
+    discoveryKind: "aliases",
+    effortLevels: fallbackEffortIds(family),
+    defaultEffort: fallbackDefaultEffort(family),
+    effortSource: "fallback",
+    effortVerified: false,
+    description: `Claude Code alias resolved to ${canonicalId} from installed package metadata`,
+  };
+}
+
+function resolveAliasModelsWithPackageMetadata(
+  models: readonly ClaudeCodeModel[],
+  packageMetadata: ClaudeCodePackageMetadataDiscovery | null,
+): ClaudeCodeModel[] {
+  if (!packageMetadata) return [...models];
+  const byFamily = new Map(packageMetadata.models.map((model) => [model.family, model]));
+  return models.map((model) => {
+    if (!isVagueClaudeFamilyLabel(model.value) || model.version) return model;
+    return byFamily.get(model.family) ?? model;
+  });
+}
+
+function allModelsHaveKnownVersions(models: readonly ClaudeCodeModel[]): boolean {
+  return models.length > 0 && models.every((model) => Boolean(model.version));
+}
+
+export function discoverModelsFromClaudePackageMetadata(
+  resolvedCommand: string,
+  metadataPaths?: readonly string[],
+): ClaudeCodePackageMetadataDiscovery | null {
+  const paths = metadataPaths
+    ? uniqueStrings(metadataPaths)
+    : defaultClaudeMetadataPaths(resolvedCommand);
+
+  for (const path of paths) {
+    if (!existsSync(path)) continue;
+    try {
+      const rawModelIds = extractClaudeModelIdsFromMetadata(readFileSync(path));
+      const latestByFamily = latestModelIdByFamily(rawModelIds);
+      const models = CLAUDE_MODEL_FAMILIES
+        .map((family) => {
+          const latest = latestByFamily.get(family);
+          return latest ? aliasResolvedModel(family, latest.id, latest.version) : null;
+        })
+        .filter((model): model is ClaudeCodeModel => Boolean(model));
+      if (models.length > 0) {
+        return {
+          sourcePath: path,
+          rawModelIds,
+          models,
+        };
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// Claude Code CLI does not consistently advertise JSON model listing in its help text,
+// so we probe these well-known command shapes directly first, before falling back to
+// help-text analysis. Each probe fails fast (non-zero exit) if unsupported.
+const PROBE_MODEL_LIST_ARGS: string[][] = [
+  ["model", "list", "--json"],
+  ["models", "--json"],
+  ["models", "list", "--json"],
+];
+
+function candidateModelListArgs(helpOutput: string): string[][] {
+  const text = helpOutput.toLowerCase();
+  const candidates: string[][] = [];
+  if (/model\s+list/.test(text) && /--json/.test(text)) {
+    candidates.push(["model", "list", "--json"]);
+  }
+  if (/models\s+list/.test(text) && /--json/.test(text)) {
+    candidates.push(["models", "list", "--json"]);
+  }
+  if (/\bmodels\b/.test(text) && /--json/.test(text)) {
+    candidates.push(["models", "--json"]);
+  }
+  return candidates;
+}
+
+async function discoverModelsFromClaudeHelp(
+  executable: string,
+  cwd: string,
+  runCommandImpl: CommandRunner,
+  timeoutMs: number,
+  rootHelpText: string,
+): Promise<ClaudeCodeModel[]> {
+  // Step 1: try well-known command shapes directly, without requiring the help text
+  // to advertise them. Claude Code CLI versions vary in whether (and how) they expose
+  // a model list command — probing directly is more reliable than help-text detection.
+  const triedArgKeys = new Set<string>();
+  for (const args of PROBE_MODEL_LIST_ARGS) {
+    triedArgKeys.add(args.join("\0"));
+    const result = await runClaudeCommand(executable, args, cwd, runCommandImpl, timeoutMs);
+    if (result.status === "completed" && result.exitCode === 0) {
+      const models = parseModelsFromJsonOutput(result.stdout);
+      if (models.length > 0) return models;
+    }
+  }
+
+  // Step 2: fall through to help-text-based detection as a supplementary strategy
+  // for future Claude Code versions that advertise additional model-list commands.
+  const modelHelpResult = await runClaudeCommand(executable, ["model", "--help"], cwd, runCommandImpl, timeoutMs);
+  const candidates = [
+    ...candidateModelListArgs(rootHelpText),
+    ...([modelHelpResult].flatMap((result) =>
+    result.status === "completed" && result.exitCode === 0
+      ? candidateModelListArgs(`${result.stdout}\n${result.stderr}`)
+      : []
+    )),
+  ];
+
+  for (const args of candidates) {
+    if (triedArgKeys.has(args.join("\0"))) continue; // skip already-probed commands
+    const result = await runClaudeCommand(executable, args, cwd, runCommandImpl, timeoutMs);
+    if (result.status !== "completed" || result.exitCode !== 0) continue;
+    const models = parseModelsFromJsonOutput(result.stdout);
+    if (models.length > 0) return models;
+  }
+  return [];
+}
+
+export function claudeCodeModelsToProviderModels(models: readonly ClaudeCodeModel[]): readonly ProviderModel[] {
+  return models.map((model) => ({
+    id: model.value,
+    modelId: model.value,
+    label: model.label,
+    description: model.description ?? (
+      model.source === "fallback"
+        ? `${model.label} - Fallback defaults${model.effortVerified ? "" : "; effort metadata unverified"}`
+        : model.source === "settings" || model.source === "config" || model.source === "claude-code-config"
+          ? `${model.label} - From Claude settings`
+          : `${model.label} - ${model.discoveryKind === "aliases" ? "Claude Code alias resolved" : "Discovered from Claude Code"} (${model.source})`
+    ),
+    defaultReasoningLevel: model.defaultEffort,
+    supportedReasoningLevels: getClaudeCodeEffortLevels(model.effortLevels),
+    source: model.source,
+    canonicalId: model.canonicalId,
+    family: model.family,
+    version: model.version,
+    isFallback: model.isFallback,
+    discoveryKind: model.discoveryKind,
+    effortSource: model.effortSource,
+    effortVerified: model.effortVerified,
+  }));
+}
+
+export async function discoverClaudeCodeCapabilities(
+  options: DiscoverClaudeCodeCapabilitiesOptions,
+): Promise<ClaudeCodeCapabilityDiscovery> {
+  const runCommandImpl = options.runCommandImpl ?? runCommand;
+  const timeoutMs = options.timeoutMs ?? 10_000;
+  const resolvedCommand = await resolveClaudeExecutable({
+    runCommandImpl: options.runCommandImpl,
+    cwd: options.cwd,
+    configuredPath: options.configuredPath,
+  });
+
+  const authResult = await runClaudeCommand(resolvedCommand, ["auth", "status"], options.cwd, runCommandImpl, timeoutMs);
+  const authJson = authResult.status === "completed" && authResult.exitCode === 0
+    ? parseClaudeAuthStatus(authResult.stdout)
+    : null;
+  const auth: ClaudeCodeAuthInfo = authJson?.loggedIn === true
+    ? authJson
+    : { loggedIn: false };
+
+  const settings = readClaudeSettings(options.settingsPath);
+  const helpResult = await runClaudeCommand(resolvedCommand, ["--help"], options.cwd, runCommandImpl, timeoutMs);
+  const helpText = helpResult.status === "completed" && helpResult.exitCode === 0
+    ? `${helpResult.stdout}\n${helpResult.stderr}`
+    : "";
+  const cliEffortLevels = parseClaudeEffortLevelsFromHelp(helpText);
+  const discoveredModels = await discoverModelsFromClaudeHelp(resolvedCommand, options.cwd, runCommandImpl, timeoutMs, helpText);
+  const packageMetadata = discoverModelsFromClaudePackageMetadata(resolvedCommand, options.metadataPaths);
+
+  let modelSource: ClaudeCodeModelSource = "fallback";
+  let models: ClaudeCodeModel[] = fallbackClaudeModels();
+
+  if (discoveredModels.length > 0) {
+    const resolvedModels = resolveAliasModelsWithPackageMetadata(discoveredModels, packageMetadata);
+    modelSource = allModelsHaveKnownVersions(resolvedModels) && resolvedModels.some((model) => model.source === "claude-code-package")
+      ? "claude-code-package"
+      : "claude-code-command";
+    models = resolvedModels;
+  } else if (packageMetadata?.models && packageMetadata.models.length > 0) {
+    modelSource = "claude-code-package";
+    models = packageMetadata.models;
+  } else if (settings?.models && settings.models.length > 0) {
+    modelSource = "settings";
+    models = [...settings.models];
+  } else if (settings?.availableModels && settings.availableModels.length > 0) {
+    modelSource = "settings";
+    models = settings.availableModels
+      .map((model) => normalizeClaudeCodeModel(model, "settings"))
+      .filter((model): model is ClaudeCodeModel => Boolean(model));
+  }
+
+  if (settings?.model && !models.some((model) =>
+    model.value === settings.model || model.canonicalId === settings.model || model.family === settings.model
+  )) {
+    const settingsModel = normalizeClaudeCodeModel(settings.model, "settings");
+    if (settingsModel) {
+      models = [settingsModel, ...models];
+      if (modelSource === "fallback") modelSource = "settings";
+    }
+  }
+
+  models = applyAvailableModelAllowlist(dedupeModels(models), settings?.availableModels);
+  if (cliEffortLevels) {
+    models = models.map((model) => {
+      if (model.effortSource !== "fallback") return model;
+      const preferredDefault = settings?.effortLevel && cliEffortLevels.includes(settings.effortLevel)
+        ? settings.effortLevel
+        : model.defaultEffort;
+      return {
+        ...model,
+        effortLevels: cliEffortLevels,
+        defaultEffort: cliEffortLevels.includes(preferredDefault) ? preferredDefault : cliEffortLevels[0] ?? "high",
+        effortSource: "claude-code-command",
+        effortVerified: true,
+      };
+    });
+  }
+
+  return {
+    provider: "anthropic",
+    backend: "claude-code-cli",
+    resolvedCommand,
+    auth,
+    models,
+    modelSource,
+    discoveredAt: (options.now?.() ?? new Date()).toISOString(),
+    ...(settings ? {
+      settings: {
+        path: settings.path,
+        ...(settings.model ? { model: settings.model } : {}),
+        ...(settings.effortLevel ? { effortLevel: settings.effortLevel } : {}),
+        ...(settings.availableModels ? { availableModels: settings.availableModels } : {}),
+      },
+    } : {}),
+    diagnostics: {
+      authExitCode: authResult.exitCode,
+      authStatus: authResult.status,
+      authJsonParsed: authJson !== null,
+      loggedIn: auth.loggedIn,
+      modelSource,
+      settingsPath: settings?.path ?? null,
+      packageMetadataPath: packageMetadata?.sourcePath ?? null,
+      packageMetadataModelCount: packageMetadata?.rawModelIds.length ?? 0,
+      rawPackageModelIds: packageMetadata?.rawModelIds.slice(0, 12).join(",") ?? null,
+    },
+  };
+}
+
+export function getClaudeModelDefaultEffort(modelId: string, models: readonly ProviderModel[]): string {
+  const normalized = modelId.toLowerCase();
+  const model = models.find((item) =>
+    item.modelId.toLowerCase() === normalized ||
+    item.id.toLowerCase() === normalized ||
+    item.family?.toLowerCase() === normalized ||
+    item.canonicalId?.toLowerCase() === normalized ||
+    (item.family ? normalized.includes(item.family.toLowerCase()) : false)
+  );
+  return model?.defaultReasoningLevel ?? "medium";
+}
+
+export function modelSupportsClaudeEffort(modelId: string, effort: string | null | undefined, models: readonly ProviderModel[]): boolean {
+  if (!effort) return false;
+  const normalized = modelId.toLowerCase();
+  const model = models.find((item) =>
+    item.modelId.toLowerCase() === normalized ||
+    item.id.toLowerCase() === normalized ||
+    item.family?.toLowerCase() === normalized ||
+    item.canonicalId?.toLowerCase() === normalized ||
+    (item.family ? normalized.includes(item.family.toLowerCase()) : false)
+  );
+  return Boolean(model?.supportedReasoningLevels?.some((level) => level.id === effort));
+}