feat: smart auto-routing (per-turn simple-vs-strong model selection)

README.md

@@ -216,6 +216,7 @@ Beginner-friendly guides:
 Advanced and source-build guides:
 
 - [Advanced Setup](docs/advanced-setup.md)
+- [Smart Auto-Routing](docs/smart-routing.md)
 - [Android Install](ANDROID_INSTALL.md)
 
 ## Supported Providers

docs/smart-routing.md

@@ -0,0 +1,57 @@
+# Smart auto-routing
+
+Smart routing is an opt-in mode that classifies each user turn as **simple** or **strong** and sends it to your configured **simple** or **strong** model accordingly, so trivial turns ("ok", "rename this", "what does this do?") can go to a cheaper model while the strong model handles everything non-trivial. Whether the simple role is actually cheaper depends on how your provider bills it. OpenClaude routes to the role you set and does not verify your provider's pricing.
+
+It is **off by default** and **experimental** — the classifier is a fast heuristic (prompt length, code blocks, reasoning/planning keywords, first turn of a session), not a perfect judge. When in doubt it routes to the strong model, so the failure mode is "no savings on a turn that could have been cheap," never a silently degraded answer on a turn you cared about.
+
+Smart routing is provider-agnostic: it swaps the model within your current provider. It works against any backend where you have both a cheaper and a stronger model configured. It does not read your provider's, gateway's, or account's pricing, so any savings or cost estimates it shows are based on a first-party reference table and may not match what you are actually billed.
+
+## Setup
+
+Both roles point at `agentModels` keys (or bare model ids). For example, in `~/.openclaude.json`:
+
+```json
+{
+  "agentModels": {
+    "mini": { "model": "gpt-5-mini" },
+    "main": { "model": "gpt-5" }
+  },
+  "smartRouting": {
+    "enabled": true,
+    "simpleModel": "mini",
+    "strongModel": "main"
+  }
+}
+```
+
+Optional tuning fields: `simpleMaxChars` and `simpleMaxWords` raise or lower the size threshold for "simple".
+
+## The `/smartroute` command
+
+| Command | Effect |
+| --- | --- |
+| `/smartroute` | Show status (enabled/disabled, the two roles, available `agentModels` keys). |
+| `/smartroute on` | Enable (requires both roles set). |
+| `/smartroute off` | Disable. |
+| `/smartroute simple <key>` | Set the simple-turn model to an `agentModels` key. |
+| `/smartroute strong <key>` | Set the strong-turn model. |
+
+When you set roles, the command warns if the simple model is not actually priced below the strong model (for models with known first-party pricing).
+
+## Environment variables
+
+These set a startup default. An explicit `smartRouting` block in settings always overrides them.
+
+| Variable | Meaning |
+| --- | --- |
+| `OPENCLAUDE_SMART_ROUTING` | `1` or `true` enables routing at startup. |
+| `OPENCLAUDE_SMART_ROUTING_SIMPLE` | `agentModels` key or model id for simple turns. |
+| `OPENCLAUDE_SMART_ROUTING_STRONG` | `agentModels` key or model id for strong turns. |
+
+## Behavior notes
+
+- **One decision per turn.** The model is chosen once when your message arrives and held for the whole turn (including its tool calls), so it does not flap mid-turn.
+- **Fallback.** If a simple-routed turn's model call errors (transport or server error), it retries once on the strong model. Aborts and auth/permission/bad-request errors are not retried.
+- **Allowlist.** Any model smart routing selects is checked against your org model allowlist (`availableModels`). A disallowed model is coerced to strong; if strong is also disallowed, routing disables itself for the session and the default model is used. Running `/smartroute on` re-enables routing and clears that session disable.
+- **Same-provider only.** Roles must be model-only `agentModels` entries (or bare model ids). If a role resolves to a cross-provider entry (one with `base_url`/`api_key`), routing silently disables — cross-provider routing is not supported yet.
+- **Auditing.** `/cost` shows a routing summary: how many turns went simple vs strong, how many escalated to strong via fallback, and an estimated savings line when both models appear in the first-party reference pricing table. That estimate is reference pricing only and may not reflect what your provider/gateway/account actually bills.

src/commands.ts

@@ -167,6 +167,7 @@ import chrome from './commands/chrome/index.js'
 import stickers from './commands/stickers/index.js'
 import advisor from './commands/advisor.js'
 import ads from './commands/ads.js'
+import smartroute from './commands/smartroute/index.js'
 import { logError } from './utils/log.js'
 import { toError } from './utils/errors.js'
 import { logForDebugging } from './utils/debug.js'
@@ -278,6 +279,7 @@ const COMMANDS = memoize((): Command[] => [
   addDir,
   advisor,
   ads,
+  smartroute,
   agents,
   autoFix,
   branch,

src/commands/login/login.tsx

@@ -1,7 +1,9 @@
 import { feature } from 'bun:bundle'
 import * as React from 'react'
 
-import { resetCostState } from '../../bootstrap/state.js'
+// Use the cost-tracker wrapper (not the raw bootstrap reset) so the routing
+// tally is cleared alongside cost counters on an account switch.
+import { resetCostState } from '../../cost-tracker.js'
 import {
   clearTrustedDeviceToken,
   enrollTrustedDevice,

src/commands/smartroute/index.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test'
+import command from './index.js'
+import * as settingsModule from '../../utils/settings/settings.js'
+import type { SettingsJson } from '../../utils/settings/types.js'
+import type { LocalCommandResult } from '../../types/command.js'
+
+// The command always returns a `text` result; narrow the union so `.value` is
+// accessible without an `as` cast (and assert that contract while we're here).
+function expectText(res: LocalCommandResult): Extract<LocalCommandResult, { type: 'text' }> {
+  if (res.type !== 'text') throw new Error(`expected a text result, got ${res.type}`)
+  return res
+}
+
+// Two model-only agentModels keys with first-party-priced models so the
+// cheaper-than warning can be exercised: haiku (cheap) vs opus (expensive).
+const AGENT_MODELS = {
+  mini: { model: 'claude-haiku-4-5' },
+  main: { model: 'claude-opus-4-5' },
+}
+
+function makeContext(initial: Partial<SettingsJson> = {}) {
+  let state = {
+    settings: { agentModels: AGENT_MODELS, ...initial } as SettingsJson,
+  }
+  return {
+    getAppState: () => state as never,
+    setAppState: (updater: (s: typeof state) => typeof state) => {
+      state = updater(state)
+    },
+    _state: () => state,
+  } as unknown as Parameters<Awaited<ReturnType<typeof command.load>>['call']>[1] & {
+    _state: () => typeof state
+  }
+}
+
+describe('/smartroute command', () => {
+  let writeSpy: ReturnType<typeof spyOn>
+  let call: Awaited<ReturnType<typeof command.load>>['call']
+
+  beforeEach(async () => {
+    writeSpy = spyOn(settingsModule, 'updateSettingsForSource').mockImplementation(() => undefined as never)
+    call = (await command.load()).call
+  })
+  afterEach(() => writeSpy.mockRestore())
+
+  test('status with no config shows disabled and available keys', async () => {
+    const ctx = makeContext()
+    const res = expectText(await call('', ctx))
+    expect(res.value).toContain('status: disabled')
+    expect(res.value).toContain('mini, main')
+  })
+
+  test('on without both roles set is rejected', async () => {
+    const ctx = makeContext({ smartRouting: { enabled: false, simpleModel: 'mini' } })
+    const res = expectText(await call('on', ctx))
+    expect(res.value).toContain('Set both roles first')
+    expect(writeSpy).not.toHaveBeenCalled()
+  })
+
+  test('setting simple/strong to a valid key persists', async () => {
+    const ctx = makeContext()
+    await call('simple mini', ctx)
+    expect(writeSpy).toHaveBeenCalledWith('userSettings', { smartRouting: { simpleModel: 'mini' } })
+    expect((ctx as never as { _state: () => { settings: SettingsJson } })._state().settings.smartRouting).toEqual({
+      simpleModel: 'mini',
+    })
+  })
+
+  test('setting the strong role to a valid key persists', async () => {
+    const ctx = makeContext()
+    await call('strong main', ctx)
+    expect(writeSpy).toHaveBeenCalledWith('userSettings', { smartRouting: { strongModel: 'main' } })
+  })
+
+  test('simple/strong with no value argument is rejected', async () => {
+    const ctx = makeContext()
+    const res = expectText(await call('simple', ctx))
+    expect(res.value).toContain('Specify an agentModels key')
+    expect(writeSpy).not.toHaveBeenCalled()
+  })
+
+  test('setting a role to an unknown key is rejected with available keys', async () => {
+    const ctx = makeContext()
+    const res = expectText(await call('simple nope', ctx))
+    expect(res.value).toContain('not a configured agentModels key')
+    expect(res.value).toContain('mini, main')
+    expect(writeSpy).not.toHaveBeenCalled()
+  })
+
+  test('enabling with simple cheaper than strong gives no warning', async () => {
+    const ctx = makeContext({ smartRouting: { enabled: false, simpleModel: 'mini', strongModel: 'main' } })
+    const res = expectText(await call('on', ctx))
+    expect(res.value).toContain('Smart routing enabled')
+    expect(res.value).not.toContain('Heads up')
+    expect(writeSpy).toHaveBeenCalledWith('userSettings', {
+      smartRouting: { enabled: true, simpleModel: 'mini', strongModel: 'main' },
+    })
+  })
+
+  test('warns when the simple model is not cheaper than the strong model', async () => {
+    // Swap roles: simple=opus (expensive), strong=haiku (cheap).
+    const ctx = makeContext({ smartRouting: { enabled: false, simpleModel: 'main', strongModel: 'mini' } })
+    const res = expectText(await call('on', ctx))
+    expect(res.value).toContain('Heads up')
+    expect(res.value).toContain('not cheaper')
+    // The warning must be hedged as first-party reference pricing, since the
+    // active provider may bill these models differently (jatmn P2).
+    expect(res.value).toContain('first-party reference pricing')
+    expect(res.value).toContain('provider may bill differently')
+  })
+
+  test('off disables', async () => {
+    const ctx = makeContext({ smartRouting: { enabled: true, simpleModel: 'mini', strongModel: 'main' } })
+    const res = expectText(await call('off', ctx))
+    expect(res.value).toContain('disabled')
+    expect(writeSpy).toHaveBeenCalledWith('userSettings', {
+      smartRouting: { enabled: false, simpleModel: 'mini', strongModel: 'main' },
+    })
+  })
+})

src/commands/smartroute/index.ts

@@ -0,0 +1,123 @@
+import type { Command } from '../../commands.js'
+import type { LocalCommandCall } from '../../types/command.js'
+import { updateSettingsForSource } from '../../utils/settings/settings.js'
+import type { SettingsJson } from '../../utils/settings/types.js'
+import { readSmartRouting } from '../../services/api/smartRouting/settings.js'
+import {
+  clearSmartRoutingSessionDisable,
+  getKnownInputCost,
+  isSmartRoutingDisabledForSession,
+} from '../../services/api/smartRouting/index.js'
+import { getSessionId } from '../../bootstrap/state.js'
+
+type SmartRoutingSettings = NonNullable<SettingsJson['smartRouting']>
+
+const HELP =
+  'Usage:\n' +
+  '  /smartroute            show status\n' +
+  '  /smartroute on|off     enable / disable\n' +
+  '  /smartroute simple <agentModels-key>\n' +
+  '  /smartroute strong <agentModels-key>'
+
+function text(value: string) {
+  return { type: 'text' as const, value }
+}
+
+/** Resolve an agentModels key to its underlying model string (for pricing). */
+function roleModelString(key: string | undefined, settings: SettingsJson | null): string | undefined {
+  if (!key) return undefined
+  return settings?.agentModels?.[key]?.model ?? key
+}
+
+/**
+ * Warn when both roles have first-party reference pricing and, by that pricing,
+ * simple is not actually cheaper. The numbers are first-party list prices, not
+ * the active provider's, so the warning is hedged accordingly.
+ */
+function cheaperWarning(s: SmartRoutingSettings, settings: SettingsJson | null): string {
+  const simple = getKnownInputCost(roleModelString(s.simpleModel, settings) ?? '')
+  const strong = getKnownInputCost(roleModelString(s.strongModel, settings) ?? '')
+  if (simple != null && strong != null && simple >= strong) {
+    return `\nHeads up: by first-party reference pricing the simple model is not cheaper than the strong model (${simple} vs ${strong} per Mtok input); your provider may bill differently. Smart routing may not save money.`
+  }
+  return ''
+}
+
+const call: LocalCommandCall = async (args, context) => {
+  const arg = args.trim()
+  const settings = context.getAppState().settings as unknown as SettingsJson
+  const current: SmartRoutingSettings = { ...(settings?.smartRouting ?? {}) }
+  const agentModelKeys = Object.keys(settings?.agentModels ?? {})
+
+  const persist = (next: SmartRoutingSettings) => {
+    context.setAppState(s => ({
+      ...s,
+      settings: { ...s.settings, smartRouting: next },
+    }))
+    updateSettingsForSource('userSettings', { smartRouting: next })
+  }
+
+  // Status (no args).
+  if (!arg) {
+    const normalized = readSmartRouting(settings)
+    const disabledForSession = isSmartRoutingDisabledForSession(getSessionId())
+    const lines = [
+      'Smart routing (experimental)',
+      `  status: ${normalized.enabled ? 'enabled' : 'disabled'}${
+        disabledForSession ? ' (auto-disabled this session: both models outside the org allowlist)' : ''
+      }`,
+      `  simple: ${current.simpleModel ?? '(unset)'}`,
+      `  strong: ${current.strongModel ?? '(unset)'}`,
+    ]
+    if (agentModelKeys.length > 0) lines.push(`  available agentModels keys: ${agentModelKeys.join(', ')}`)
+    return text(lines.join('\n') + '\n\n' + HELP)
+  }
+
+  const [sub, value] = arg.split(/\s+/, 2)
+  const lower = sub.toLowerCase()
+
+  if (lower === 'on') {
+    if (!current.strongModel || !current.simpleModel) {
+      return text('Set both roles first: /smartroute simple <key> and /smartroute strong <key>.')
+    }
+    const next = { ...current, enabled: true }
+    persist(next)
+    // Re-enabling clears any session auto-disable.
+    clearSmartRoutingSessionDisable(getSessionId())
+    return text(`Smart routing enabled (simple=${next.simpleModel}, strong=${next.strongModel}).${cheaperWarning(next, settings)}`)
+  }
+
+  if (lower === 'off') {
+    persist({ ...current, enabled: false })
+    return text('Smart routing disabled.')
+  }
+
+  if (lower === 'simple' || lower === 'strong') {
+    if (!value) return text(`Specify an agentModels key: /smartroute ${lower} <key>.`)
+    if (!agentModelKeys.includes(value)) {
+      return text(
+        `"${value}" is not a configured agentModels key.` +
+          (agentModelKeys.length ? ` Available: ${agentModelKeys.join(', ')}.` : ' Configure agentModels first.'),
+      )
+    }
+    const next: SmartRoutingSettings =
+      lower === 'simple' ? { ...current, simpleModel: value } : { ...current, strongModel: value }
+    persist(next)
+    return text(`Set ${lower} model to "${value}".${cheaperWarning(next, settings)}`)
+  }
+
+  return text(HELP)
+}
+
+const smartroute = {
+  type: 'local',
+  name: 'smartroute',
+  description: 'Configure smart auto-routing (experimental): route simple turns to your configured simple model',
+  argumentHint: '[on|off|simple <key>|strong <key>]',
+  isEnabled: () => true,
+  isHidden: false,
+  supportsNonInteractive: true,
+  load: () => Promise.resolve({ call }),
+} satisfies Command
+
+export default smartroute

src/cost-tracker.ts

@@ -9,6 +9,8 @@ import {
   resetSessionCacheStats,
 } from './services/api/cacheStatsTracker.js'
 import { getAPIProvider, isGithubNativeAnthropicMode } from './utils/model/providers.js'
+import { getRoutingSummaryForDisplay, resetRoutingTally } from './services/api/smartRouting/index.js'
+import { getSettings_DEPRECATED } from './utils/settings/settings.js'
 import {
   addToTotalCostState,
   addToTotalLinesChanged,
@@ -83,6 +85,9 @@ export {
 export function resetCostState(): void {
   baseResetCostState()
   resetSessionCacheStats()
+  // Keep the routing summary scoped to the same session window as the cost
+  // block it renders beside — otherwise /cost shows stale cross-session counts.
+  resetRoutingTally()
 }
 
 type StoredCostState = {
@@ -286,9 +291,12 @@ Total duration (wall): ${formatDuration(getTotalDuration())}
 Total code changes:    ${getTotalLinesAdded()} ${getTotalLinesAdded() === 1 ? 'line' : 'lines'} added, ${getTotalLinesRemoved()} ${getTotalLinesRemoved() === 1 ? 'line' : 'lines'} removed`,
   )
 
+  const routingSummary = getRoutingSummaryForDisplay(getSettings_DEPRECATED())
+  const routingSection = routingSummary ? `\n\n${chalk.dim(routingSummary)}` : ''
+
   return `${statsBlock}${tokenSection}
 
-${modelUsageDisplay}`
+${modelUsageDisplay}${routingSection}`
 }
 
 function round(number: number, precision: number): number {