Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(routing): send bare non-Claude names to route(), not to Anthropic

Jack Rudenko16b92ccaa01a
diff --git a/packages/cli/src/advisor-startup.test.ts b/packages/cli/src/advisor-startup.test.ts
index 1d809ffe..1e5153c7 100644
--- a/packages/cli/src/advisor-startup.test.ts
+++ b/packages/cli/src/advisor-startup.test.ts
@@ -7,6 +7,7 @@ import {
advisorModelStatus,
decideAdvisorStartup,
evaluateAdvisorStartup,
+ resolveMainModelFact,
} from "./advisor-startup.js";
import { resolveAdvisorToolEnv } from "./claude-runner.js";
import type { ClaudishConfig } from "./types.js";
@@ -86,6 +87,17 @@ function expectProceed(decision: AdvisorStartupDecision) {
return decision;
}
+describe("resolveMainModelFact", () => {
+ it("labels a bare non-Claude name as unresolved until its first routed request", () => {
+ expect(resolveMainModelFact("o4-mini")).toEqual({
+ model: "o4-mini",
+ providerName: "unresolved (routed on the first request)",
+ carriesTools: true,
+ wireFormat: undefined,
+ });
+ });
+});
+
describe("decideAdvisorStartup", () => {
describe("CLAUDE_CODE_DISABLE_ADVISOR_TOOL", () => {
it.each(["1", "true", "yes", "on", " TRUE "])("refuses when the child value is %p", (value) => {
diff --git a/packages/cli/src/advisor-startup.ts b/packages/cli/src/advisor-startup.ts
index 2e592f35..3af52733 100644
--- a/packages/cli/src/advisor-startup.ts
+++ b/packages/cli/src/advisor-startup.ts
@@ -307,8 +307,10 @@ export function resolveMainModelFact(model: string): MainModelFact {
const format = definition
? pinnedFormatForTransport(definition.transport, resolution.modelName)
: null;
+ // `auto-route` is a bare name route() decides on the first request, so no
+ // provider is known yet; `unknown` is a `vendor/` with no known vendor.
const providerName =
- resolution.category === "unknown"
+ resolution.category === "unknown" || resolution.category === "auto-route"
? "unresolved (routed on the first request)"
: definition?.displayName || resolution.providerName;
return {
diff --git a/packages/cli/src/auth/credentials/prehydrate.test.ts b/packages/cli/src/auth/credentials/prehydrate.test.ts
index 50854f5a..692767e2 100644
--- a/packages/cli/src/auth/credentials/prehydrate.test.ts
+++ b/packages/cli/src/auth/credentials/prehydrate.test.ts
@@ -241,6 +241,18 @@ describe("pinSpecFor routing gate", () => {
expect(router).not.toHaveBeenCalled();
});
+ it("routes a bare non-Claude name", async () => {
+ const router = mock(async (spec: string) => ({
+ kind: "ok" as const,
+ primary: { provider: "openrouter", modelSpec: spec, displayName: "OpenRouter" },
+ fallbacks: [],
+ }));
+
+ expect(await pinSpecFor("o4-mini", router)).toBe("or@o4-mini");
+ expect(router).toHaveBeenCalledTimes(1);
+ expect(router).toHaveBeenCalledWith("o4-mini");
+ });
+
it("returns null without throwing when the router finds no route", async () => {
const router = mock(async () => ({
kind: "no-route" as const,
@@ -393,27 +405,27 @@ describe("pre-route target characterization", () => {
},
{
target: "o4-mini",
- nativeRoute: native("o4-mini"),
+ nativeRoute: null,
parsed: {
- provider: "native-anthropic",
+ provider: "auto-route",
model: "o4-mini",
original: "o4-mini",
isLegacySyntax: false,
isExplicitProvider: false,
},
- callsRouter: false,
+ callsRouter: true,
},
{
target: "no-such-model-xyz",
- nativeRoute: native("no-such-model-xyz"),
+ nativeRoute: null,
parsed: {
- provider: "native-anthropic",
+ provider: "auto-route",
model: "no-such-model-xyz",
original: "no-such-model-xyz",
isLegacySyntax: false,
isExplicitProvider: false,
},
- callsRouter: false,
+ callsRouter: true,
},
{
target: "kimi-k3",
@@ -510,8 +522,8 @@ describe("proxyRouteDecision consistency", () => {
{ target: "anthropic/claude-opus-5", type: "explicit" },
{ target: "poe:x", type: "poe" },
{ target: "kc@kimi-k3", type: "explicit" },
- { target: "o4-mini", type: "native" },
- { target: "no-such-model-xyz", type: "native" },
+ { target: "o4-mini", type: "bare" },
+ { target: "no-such-model-xyz", type: "bare" },
{ target: "kimi-k3", type: "bare" },
{ target: "openai/gpt-5", type: "bare" },
{ target: "foo/bar", type: "bare" },
diff --git a/packages/cli/src/auth/credentials/prehydrate.ts b/packages/cli/src/auth/credentials/prehydrate.ts
index f5a9e927..2ad3d7c7 100644
--- a/packages/cli/src/auth/credentials/prehydrate.ts
+++ b/packages/cli/src/auth/credentials/prehydrate.ts
@@ -239,13 +239,15 @@ async function pinRoutes(
* STRIPS the `:3` off `[email protected]:3` (`model` comes back `"llama3.2"`),
* so a spec rebuilt from parsed parts would silently lose it. The early-out,
* NOT lossless round-tripping, is the guarantee.
- * - **native-anthropic** (`opus`, `sonnet`, `claude-*`, and any unrecognised
- * bare name with no `/`) — the child never routes these. `route()` would
- * nonetheless answer `ok` for them, because `defaultProvider` is appended to
- * EVERY bare-name chain, so an unguarded pin would spawn
- * `--model or@opus` and send a native model through OpenRouter. `team`
- * screens these out upstream in `setupSession`, but `create_session` does
- * not.
+ * - **native-anthropic** (Claude Code's own names: `opus`, `sonnet`,
+ * `opusplan`, `claude-*`; see `isClaudeCodeModelName`) — the child never
+ * routes these. `route()` would nonetheless answer `ok` for them, because
+ * `defaultProvider` is appended to EVERY bare-name chain, so an unguarded pin
+ * would spawn `--model or@opus` and send a native model through OpenRouter.
+ * Both `team` and `create_session` run these as native slots (see "Native
+ * Model Slots" in team-orchestrator.ts), so this check is what keeps them
+ * bare. Any other bare name with no `/` (`o4-mini`, a typo) is `bare`: the
+ * child routes it, so the parent pins its chain like any other.
* - **`poe:` models** — same gate, same reason.
*/
function isRoutablyPinnable(model: string): boolean {
diff --git a/packages/cli/src/claude-runner.ts b/packages/cli/src/claude-runner.ts
index 03505b51..9785d779 100644
--- a/packages/cli/src/claude-runner.ts
+++ b/packages/cli/src/claude-runner.ts
@@ -62,9 +62,12 @@ function releaseTerminalIsolation(): void {
}
/**
- * Check if any resolved model mapping targets a native Anthropic model (claude-*).
- * When true, placeholder auth tokens must NOT be set — Claude Code needs its real
- * subscription credentials so NativeHandler can forward them to api.anthropic.com.
+ * Check if any resolved model mapping targets a native Anthropic model: a name
+ * Claude Code owns (`claude-*`, `opus`, `opusplan`, `sonnet[1m]`, …), which the
+ * parser attributes to native-anthropic. When true, placeholder auth tokens must
+ * NOT be set — Claude Code needs its real subscription credentials so
+ * NativeHandler can forward them to api.anthropic.com. Any other bare name
+ * (`o4-mini`) is routed by the proxy, so it does not count.
*/
function hasNativeAnthropicMapping(config: ClaudishConfig): boolean {
const models = [
diff --git a/packages/cli/src/force-login-method.test.ts b/packages/cli/src/force-login-method.test.ts
index 5ddc5bc2..b529019f 100644
--- a/packages/cli/src/force-login-method.test.ts
+++ b/packages/cli/src/force-login-method.test.ts
@@ -194,6 +194,15 @@ describe("shouldHideIncidentalAnthropicKey", () => {
).toBe(true);
});
+ test.each([
+ ["o4-mini", false],
+ ["opusplan", true],
+ ["sonnet[1m]", true],
+ ["claude-haiku-4-5-20251001", true],
+ ])("classifies %s for native Anthropic auth as %p", (model, expected) => {
+ expect(shouldHideIncidentalAnthropicKey(baseConfig({ model }), apiKeyEnv)).toBe(expected);
+ });
+
test("native mapping + API key + API billing opt-in → false", () => {
expect(
shouldHideIncidentalAnthropicKey(
diff --git a/packages/cli/src/providers/claude-code-aliases.ts b/packages/cli/src/providers/claude-code-aliases.ts
index 931639e4..a6bd1c08 100644
--- a/packages/cli/src/providers/claude-code-aliases.ts
+++ b/packages/cli/src/providers/claude-code-aliases.ts
@@ -4,22 +4,25 @@
*
* ## Why this distinction has to exist
*
- * `parseModelSpec` sends every unrecognised bare name to `native-anthropic`
- * ("No '/' - treat as native Anthropic model"), so two very different things
- * arrive at that route:
+ * `parseModelSpec` sends Claude Code's own names to `native-anthropic`: every
+ * `claude-` id, and every name {@link isClaudeCodeModelName} accepts. Any other
+ * bare name with no `/` goes to `route()` instead (`AUTO_ROUTE_PROVIDER`). Two
+ * very different things still arrive at the native route:
*
* - `opus`, `sonnet`, `haiku`, `internal`, `default` — Claude Code's own tier
* selectors. The API rejects them ("not a valid model ID"), but the ROUTE is
* healthy, so probing them verbatim would report a failure that does not
* exist. These need a concrete id substituted.
- * - `swe-1.7`, `some-typo-model` — names nothing serves. At runtime
- * `native-handler.ts` forwards `payload.model` VERBATIM and Anthropic answers
- * 404, so substituting a working id here makes `--probe` report `live` for a
- * model that cannot serve a single request.
+ * - a concrete `claude-` id, including one that does not exist
+ * (`claude-opus-9`). At runtime `native-handler.ts` forwards `payload.model`
+ * VERBATIM and Anthropic answers for it, 404 included, so substituting a
+ * working id here makes `--probe` report `live` for a model that cannot
+ * serve a single request.
*
- * The probe used to substitute for BOTH, which is how `swe-1.7` came to "probe
- * byte-identically to a nonsense string": the substitution erased the difference
- * between them before the request was ever sent.
+ * The probe used to substitute for every name, which is how `swe-1.7` came to
+ * "probe byte-identically to a nonsense string" back when the parser still sent
+ * both natively: the substitution erased the difference between them before the
+ * request was ever sent.
*
* So the rule is: substitute for a KNOWN alias, pass everything else through and
* let the API answer honestly.
diff --git a/packages/cli/src/providers/model-parser.ts b/packages/cli/src/providers/model-parser.ts
index 049c43e9..2f5edfba 100644
--- a/packages/cli/src/providers/model-parser.ts
+++ b/packages/cli/src/providers/model-parser.ts
@@ -44,11 +44,30 @@
* (anything else with /) -> openrouter
*/
+/**
+ * The parser's answer for a bare name it cannot attribute to anyone: no `/`, no
+ * native pattern matched, and not a name Claude Code owns (`o4-mini`,
+ * `no-such-model-xyz`). It is NOT a claudish provider, and nothing may look it up
+ * as one: `route()` decides which provider serves the name, from the user's rules
+ * and the cloud models catalog.
+ *
+ * Why not `"unknown"`: that value already means "a `vendor/` with no known vendor"
+ * (`foo/bar`) to `getMissingKeyError` and the advisor label, and it keeps that
+ * meaning. `auto-route` is the code's existing word for "routing chooses" (the
+ * stats invocation mode), and no provider or provider shortcut carries the name.
+ */
+export const AUTO_ROUTE_PROVIDER = "auto-route";
+
/**
* Parsed model specification
*/
export interface ParsedModel {
- /** Normalized provider name (lowercase) */
+ /**
+ * Normalized provider name (lowercase). For a name with no explicit provider
+ * this may also be one of the parser's own values, none of them a provider:
+ * `custom-url`, `unknown` (a `vendor/` with no known vendor), or
+ * {@link AUTO_ROUTE_PROVIDER} (a bare name `route()` decides).
+ */
provider: string;
/** Model name/ID (without provider prefix) */
model: string;
@@ -66,6 +85,7 @@ export interface ParsedModel {
* Provider shortcut mappings — derived from BUILTIN_PROVIDERS.
* Re-exported for backward compatibility.
*/
+import { isClaudeCodeModelName } from "./claude-code-aliases.js";
import {
getLegacyPrefixPatterns as _getLegacyPrefixPatterns,
getNativeModelPatterns as _getNativeModelPatterns,
@@ -256,9 +276,14 @@ export function parseModelSpec(modelSpec: string): ParsedModel {
};
}
- // No "/" - treat as native Anthropic model
+ // No "/" and no pattern matched. Claude Code's own names (`opus`, `opusplan`,
+ // `sonnet[1m]`, `best`) are served on its own auth by the native passthrough.
+ // `""` and `@model` are not model names at all: they keep the native answer
+ // they always had, and the harness rejects them. Every other bare name
+ // (`o4-mini`, a typo) is routed: the native passthrough serves none of them,
+ // so sending one there only ever earned an Anthropic 404.
return {
- provider: "native-anthropic",
+ provider: lastResortProvider(modelSpec),
model: modelSpec,
original,
isLegacySyntax: false,
@@ -266,6 +291,18 @@ export function parseModelSpec(modelSpec: string): ParsedModel {
};
}
+/**
+ * The provider for a bare name no `/` and no pattern claimed: native-anthropic
+ * for Claude Code's names and for `""` / `@model`, else {@link AUTO_ROUTE_PROVIDER}.
+ * Trimmed, as `isClaudeCodeModelName` is, so a whitespace-only value counts as
+ * empty.
+ */
+function lastResortProvider(modelSpec: string): string {
+ const name = modelSpec.trim();
+ const isNative = name === "" || name.startsWith("@") || isClaudeCodeModelName(name);
+ return isNative ? "native-anthropic" : AUTO_ROUTE_PROVIDER;
+}
+
/**
* Check if a provider is a local provider
*/
diff --git a/packages/cli/src/providers/native-route.test.ts b/packages/cli/src/providers/native-route.test.ts
index aa667770..b6dabc05 100644
--- a/packages/cli/src/providers/native-route.test.ts
+++ b/packages/cli/src/providers/native-route.test.ts
@@ -41,13 +41,7 @@ describe("nativeRouteFor", () => {
expect(nativeRouteFor("dv@claude-opus-5-high")).toBeNull();
});
- test("routes unrecognised bare names natively without treating them as tier aliases", () => {
- // The proxy routes typos natively too, so diagnostics must probe rather than declare success.
- expect(nativeRouteFor("some-typo-model")).toEqual({
- provider: "native-anthropic",
- modelSpec: "some-typo-model",
- displayName: "Anthropic (Native)",
- isTierAlias: false,
- });
+ test("does not route unrecognised bare names through the native passthrough", () => {
+ expect(nativeRouteFor("some-typo-model")).toBeNull();
});
});
diff --git a/packages/cli/src/providers/native-route.ts b/packages/cli/src/providers/native-route.ts
index f266b229..3194c848 100644
--- a/packages/cli/src/providers/native-route.ts
+++ b/packages/cli/src/providers/native-route.ts
@@ -2,7 +2,8 @@
* The native-passthrough answer that `route()` cannot give, and the proxy's
* pre-route decision that produces it.
*
- * A bare Claude name (`claude-opus-5`, `opus`, `internal`) is served by the
+ * A bare name Claude Code owns (`claude-opus-5`, `opus`, `opusplan`,
+ * `sonnet[1m]`, `internal`; see `isClaudeCodeModelName`) is served by the
* proxy's native branch on the harness's own Claude Code auth. `native-anthropic`
* has no credential store — on purpose, it is not a remote provider — so
* `route()`'s credential filter drops it and the chain degrades to OpenRouter.
@@ -12,6 +13,12 @@
* subscription model as "no route" / "OpenRouter, metered" — which is what the
* MCP `preflight` tool and the TUI route probe did.
*
+ * Only Claude Code's names are native, plus `""` and `@model`, which are not
+ * model names and which the harness rejects. Any other bare name with no `/`
+ * (`o4-mini`, a typo) is `bare`: `parseModelSpec` gives it `AUTO_ROUTE_PROVIDER`,
+ * and `route()` decides it like every other bare name. The native passthrough
+ * serves none of them, so it used to answer each with an Anthropic 404.
+ *
* Explicit specs are never native: `anthropic@claude-opus-5` names a vendor,
* and `dv@claude-opus-5-high` is Devin re-serving a Claude id under its own
* prefix. `parseModelSpec` already resolves that precedence; this only reads it.
@@ -30,8 +37,9 @@ export interface NativeRoute {
* True when `model` is a Claude Code tier alias (`opus`, `internal`, …). Those
* are selectors, not API model ids: the native handler forwards the request's
* model verbatim and Anthropic rejects an alias, so a probe must SKIP them and
- * send only concrete names. Everything else — including a typo, which the
- * proxy really does route natively — must be probed, never declared live.
+ * send only concrete names. Everything else — including a `claude-` typo,
+ * which the proxy really does send natively — must be probed, never declared
+ * live.
*/
isTierAlias: boolean;
}
diff --git a/packages/cli/src/providers/provider-resolver-rescue.test.ts b/packages/cli/src/providers/provider-resolver-rescue.test.ts
index af95446c..47232516 100644
--- a/packages/cli/src/providers/provider-resolver-rescue.test.ts
+++ b/packages/cli/src/providers/provider-resolver-rescue.test.ts
@@ -3,7 +3,9 @@ import { describe, expect, test } from "bun:test";
import {
type ProviderResolution,
type RouteOracle,
+ getMissingKeyResolutions,
rescueRoutableResolutions,
+ resolveModelProvider,
} from "./provider-resolver.js";
function makeResolution(overrides: Partial<ProviderResolution> = {}): ProviderResolution {
@@ -36,6 +38,25 @@ const notRoutable: RouteOracle = async () => ({
reason: "No credentialed provider in the routing chain",
});
+describe("resolveModelProvider", () => {
+ test("classifies a bare non-Claude name as auto-route without requiring a key", () => {
+ const resolution = resolveModelProvider("o4-mini");
+
+ expect(resolution).toEqual(
+ expect.objectContaining({
+ category: "auto-route",
+ catalogName: null,
+ providerName: "unresolved (routed on the first request)",
+ modelName: "o4-mini",
+ fullModelId: "o4-mini",
+ requiredApiKeyEnvVar: null,
+ apiKeyAvailable: true,
+ })
+ );
+ expect(getMissingKeyResolutions([resolution])).toEqual([]);
+ });
+});
+
describe("rescueRoutableResolutions", () => {
test("routing chain overturns a missing-key verdict", async () => {
const resolution = makeResolution();
diff --git a/packages/cli/src/providers/provider-resolver.ts b/packages/cli/src/providers/provider-resolver.ts
index b6ee6c14..b1167156 100644
--- a/packages/cli/src/providers/provider-resolver.ts
+++ b/packages/cli/src/providers/provider-resolver.ts
@@ -18,7 +18,8 @@
* - local: ollama@, lmstudio@, vllm@, mlx@, http://... - No API key needed
* - direct-api: google@, openai@, minimax@, kimi@, glm@, z-ai@, x-ai@, zen@ - Provider-specific key
* - openrouter: openrouter@ or unspecified provider for models with "/" - OPENROUTER_API_KEY
- * - native-anthropic: No "/" in model ID (e.g., claude-3-opus-20240229) - Claude Code native auth
+ * - native-anthropic: a name Claude Code owns (claude-3-opus-20240229, opus) - Claude Code native auth
+ * - auto-route: any other bare name with no "/" (o4-mini) - route() picks the provider per request
*
* Legacy syntax (deprecated but supported):
* - g/, gemini/, oai/, mmax/, etc. prefixes still work with deprecation warnings
@@ -26,6 +27,7 @@
import { credentials } from "../auth/credentials/authority.js";
import {
+ AUTO_ROUTE_PROVIDER,
type ParsedModel,
getLegacySyntaxWarning,
isLocalProviderName,
@@ -50,6 +52,7 @@ export type ProviderCategory =
| "direct-api"
| "openrouter"
| "native-anthropic"
+ | "auto-route"
| "unknown";
/**
@@ -164,7 +167,8 @@ const PROVIDER_DISPLAY_NAMES = new Proxy<Record<string, string>>(
* Legacy syntax: prefix/model (with deprecation warnings)
*
* Resolution order:
- * 1. Parse model spec using new unified parser
+ * 1. Parse model spec using new unified parser; a bare name the parser left to
+ * routing (`auto-route`) is answered here, before any provider lookup
* 2. Check for local providers (no API key needed)
* 3. Check for native Anthropic models
* 4. Check for explicit OpenRouter routing
@@ -205,6 +209,26 @@ export function resolveModelProvider(modelId: string | undefined): ProviderResol
concurrency: parsed.concurrency,
});
+ // 0. A bare name the parser attributed to nobody. `route()` picks its provider
+ // on the first request, so there is no provider here to name, look up or ask
+ // for a key: AUTO_ROUTE_PROVIDER is not a provider name, and it is answered
+ // before any lookup that takes one (a custom endpoint could carry the name).
+ // A null `requiredApiKeyEnvVar` is what keeps it out of
+ // getMissingKeyResolutions and away from the credential authority.
+ if (parsed.provider === AUTO_ROUTE_PROVIDER) {
+ return addCommonFields({
+ category: "auto-route",
+ catalogName: null,
+ providerName: "unresolved (routed on the first request)",
+ modelName: parsed.model,
+ fullModelId: modelId,
+ requiredApiKeyEnvVar: null,
+ apiKeyAvailable: true,
+ apiKeyDescription: null,
+ apiKeyUrl: null,
+ });
+ }
+
// 1. Check for local providers (no API key needed)
if (isLocalProviderName(parsed.provider)) {
const resolved = resolveProvider(modelId);
@@ -510,7 +534,8 @@ export function getMissingKeyError(resolution: ProviderResolution): string {
parsed &&
!parsed.isExplicitProvider &&
parsed.provider !== "unknown" &&
- parsed.provider !== "native-anthropic"
+ parsed.provider !== "native-anthropic" &&
+ parsed.provider !== AUTO_ROUTE_PROVIDER
) {
const hint = buildCredentialHint(parsed.model, [parsed.provider]);
if (hint) {
diff --git a/packages/cli/src/providers/provider-routing.test.ts b/packages/cli/src/providers/provider-routing.test.ts
index 658fecf2..a1c3f543 100644
--- a/packages/cli/src/providers/provider-routing.test.ts
+++ b/packages/cli/src/providers/provider-routing.test.ts
@@ -171,9 +171,9 @@ describe("parseModelSpec — native model auto-detection", () => {
expect(parsed.provider).toBe("native-anthropic");
});
- test("unknown-model without / falls to native-anthropic", () => {
+ test("unknown-model without / falls to auto-route", () => {
const parsed = parseModelSpec("unknown-model");
- expect(parsed.provider).toBe("native-anthropic");
+ expect(parsed.provider).toBe("auto-route");
});
test("vendor/model format with unknown vendor", () => {
diff --git a/packages/cli/src/providers/routing-hints.ts b/packages/cli/src/providers/routing-hints.ts
index 7bb2d8f5..14e9bb8b 100644
--- a/packages/cli/src/providers/routing-hints.ts
+++ b/packages/cli/src/providers/routing-hints.ts
@@ -73,9 +73,17 @@ const PROVIDER_HINT_MAP: Record<string, ProviderHintInfo> = {
* @param modelName Bare model name the user asked for.
* @param providers Canonical provider names that would have been tried but
* lacked credentials. Order is preserved in the output.
+ * @param options.suggestOpenRouter `false` drops the `or@<model>` line. For a
+ * caller that knows the catalog denies OpenRouter the model,
+ * where that line would send the user to a hop nobody
+ * published. Defaults to `true`.
* @returns Hint string, or null if no provider in the chain has a known hint.
*/
-export function buildCredentialHint(modelName: string, providers: string[]): string | null {
+export function buildCredentialHint(
+ modelName: string,
+ providers: string[],
+ options: { suggestOpenRouter?: boolean } = {}
+): string | null {
const seen = new Set<string>();
const lines: string[] = [`No credentials found for "${modelName}". Options:`];
let hasOption = false;
@@ -101,9 +109,10 @@ export function buildCredentialHint(modelName: string, providers: string[]): str
}
}
- // Always suggest OpenRouter as the catch-all unless OpenRouter itself was
- // already in the failed chain (which means OPENROUTER_API_KEY is missing).
- if (!seen.has("openrouter")) {
+ // Suggest OpenRouter as the catch-all unless OpenRouter itself was already in
+ // the failed chain (which means OPENROUTER_API_KEY is missing), or the caller
+ // knows the catalog denies OpenRouter this model.
+ if (!seen.has("openrouter") && options.suggestOpenRouter !== false) {
lines.push(` Use: claudish --model or@${modelName} (route via OpenRouter)`);
hasOption = true;
}
diff --git a/packages/cli/src/providers/routing-rules.test.ts b/packages/cli/src/providers/routing-rules.test.ts
index ea132eeb..224768fb 100644
--- a/packages/cli/src/providers/routing-rules.test.ts
+++ b/packages/cli/src/providers/routing-rules.test.ts
@@ -1408,7 +1408,6 @@ describe("route() no-route plan characterization", () => {
reason: 'A routing rule matched "blocked-by-rule" and named no provider.',
hint:
'No credentials found for "blocked-by-rule". Options:\n' +
- " Set: export ANTHROPIC_API_KEY=your-key (for native-anthropic)\n" +
" Use: claudish --model or@blocked-by-rule (route via OpenRouter)",
});
} finally {
@@ -1431,7 +1430,6 @@ describe("route() no-route plan characterization", () => {
reason: 'A routing rule matched "membership-excluded" and named no provider.',
hint:
'No credentials found for "membership-excluded". Options:\n' +
- " Set: export ANTHROPIC_API_KEY=your-key (for native-anthropic)\n" +
" Use: claudish --model or@membership-excluded (route via OpenRouter)",
});
} finally {
@@ -1456,18 +1454,40 @@ describe("route() no-route plan characterization", () => {
});
test.each([
- ["claude-opus-not-published", "Claude name"],
- ["o4-mini", "non-Claude name"],
- ])("pins a readable catalog with no entry for a %s", async (model) => {
+ [
+ "claude-opus-not-published",
+ "Claude name",
+ 'No credentials found for "claude-opus-not-published". Options:\n' +
+ " Set: export ANTHROPIC_API_KEY=your-key (for native-anthropic)\n" +
+ " Use: claudish --model or@claude-opus-not-published (route via OpenRouter)",
+ ],
+ [
+ "o4-mini",
+ "non-Claude name",
+ 'No credentials found for "o4-mini". Options:\n' +
+ " Use: claudish --model or@o4-mini (route via OpenRouter)",
+ ],
+ ])("pins a readable catalog with no entry for a %s", async (model, _label, hint) => {
const fixture = makeTempCatalog({ modelId: "catalog-marker" });
try {
expect(await route(model, {}, "", fixture.path)).toEqual({
kind: "no-route",
reason: `No provider in the catalog serves "${model}".`,
- hint:
- `No credentials found for "${model}". Options:\n` +
- " Set: export ANTHROPIC_API_KEY=your-key (for native-anthropic)\n" +
- ` Use: claudish --model or@${model} (route via OpenRouter)`,
+ hint,
+ });
+ } finally {
+ fixture.cleanup();
+ }
+ });
+
+ test("omits the OpenRouter suggestion when the catalog denies that connection", async () => {
+ const model = "catalog-denies-openrouter";
+ const fixture = makeTempCatalog({ modelId: model });
+ try {
+ expect(await route(model, {}, "", fixture.path)).toEqual({
+ kind: "no-route",
+ reason: `No provider in the catalog serves "${model}".`,
+ hint: undefined,
});
} finally {
fixture.cleanup();
diff --git a/packages/cli/src/providers/routing-rules.ts b/packages/cli/src/providers/routing-rules.ts
index 8d92121c..e0274f2c 100644
--- a/packages/cli/src/providers/routing-rules.ts
+++ b/packages/cli/src/providers/routing-rules.ts
@@ -10,7 +10,7 @@ import { DISPLAY_NAMES, PROVIDER_TO_PREFIX } from "./auto-route.js";
import { resolveExternalId } from "./catalog-client.js";
import { ensureEndpointsRegistered } from "./endpoint-registration.js";
import { providerServesModel } from "./model-availability.js";
-import { PROVIDER_SHORTCUTS } from "./model-parser.js";
+import { AUTO_ROUTE_PROVIDER, PROVIDER_SHORTCUTS } from "./model-parser.js";
import { parseModelSpec } from "./model-parser.js";
import { getProviderByName } from "./provider-definitions.js";
import { catalogDeniesProvider, gatherRouteCandidates } from "./route-candidates.js";
@@ -449,6 +449,63 @@ export function buildCatalogChain(
return { routes, catalogReadable: gathering.catalogReadable };
}
+/** Why a bare name's chain is empty before any credential is read. */
+type EmptyChainCause = "rule-empty" | "catalog-empty";
+
+/**
+ * The no-route plan for a bare name whose chain is empty before any credential
+ * is read. Two very different causes, and a user reading the message needs to
+ * know which: their OWN rule named nothing (they asked for this), or the catalog
+ * publishes no way to call the model (nobody serves it).
+ */
+function emptyChainNoRoute(
+ model: string,
+ nativeProvider: string,
+ cause: EmptyChainCause,
+ cachePath?: string
+): RoutePlan {
+ return {
+ kind: "no-route",
+ reason:
+ cause === "rule-empty"
+ ? `A routing rule matched "${model}" and named no provider.`
+ : `No provider in the catalog serves "${model}".`,
+ hint: emptyChainHint(model, nativeProvider, cause, cachePath),
+ };
+}
+
+/**
+ * The hint for a bare name whose chain is empty before any credential is read:
+ * a user rule that named no provider, or a catalog that gathered none.
+ *
+ * `nativeProvider` is the provider the parser attributed the name to, and its
+ * credential line is offered when it IS one. `AUTO_ROUTE_PROVIDER` says the
+ * parser attributed the name to nobody, so there is no credential to name. Before
+ * it existed those names parsed as `native-anthropic`, and the hint told the user
+ * to set ANTHROPIC_API_KEY for a model Anthropic does not serve.
+ *
+ * When the CATALOG gathered nothing for such a name, the `or@<model>` line is
+ * also dropped if the catalog denies OpenRouter the model (`catalogDeniesProvider`,
+ * the test that withholds the fallback append): it would send the user to a hop
+ * nobody published. Not for a matched user rule, whose empty chain is the user's
+ * own statement, and not for a name the parser attributes to a provider: that
+ * one keeps the line whatever the catalog says, the same flaw, left to a
+ * separate fix.
+ */
+function emptyChainHint(
+ model: string,
+ nativeProvider: string,
+ cause: EmptyChainCause,
+ cachePath?: string
+): string | undefined {
+ if (nativeProvider !== AUTO_ROUTE_PROVIDER) {
+ return buildCredentialHint(model, [nativeProvider]) ?? undefined;
+ }
+ const suggestOpenRouter =
+ cause === "rule-empty" || !catalogDeniesProvider("openrouter", model, cachePath);
+ return buildCredentialHint(model, [], { suggestOpenRouter }) ?? undefined;
+}
+
/**
* Path 2: a bare model name.
*
@@ -508,17 +565,12 @@ async function routeBare(
}
if (candidates.length === 0) {
- // Two very different causes, and a user reading the message needs to know
- // which: their OWN rule named nothing (they asked for this), or the catalog
- // publishes no way to call the model (nobody serves it).
- return {
- kind: "no-route",
- reason:
- matched !== null
- ? `A routing rule matched "${model}" and named no provider.`
- : `No provider in the catalog serves "${model}".`,
- hint: buildCredentialHint(model, [nativeProvider]) ?? undefined,
- };
+ return emptyChainNoRoute(
+ model,
+ nativeProvider,
+ matched !== null ? "rule-empty" : "catalog-empty",
+ cachePath
+ );
}
const credentialed: Route[] = [];