claude-autorouter 0.3.7 → 0.5.0

package/src/model-catalog.mjs

@@ -0,0 +1,96 @@
+// Exact Claude API IDs only. A name containing "sonnet" or "opus" is not
+// evidence that a gateway alias implements that model's request contract.
+export const MODEL_CATALOG_REVIEWED_AT = '2026-10-05';
+export const MODEL_CAPABILITY_SOURCES = Object.freeze({
+  thinking: 'https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting',
+  effort: 'https://platform.claude.com/docs/en/build-with-claude/effort',
+  sonnet55: 'https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide',
+  opus55: 'https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5',
+  auto: 'https://code.claude.com/docs/en/permission-modes',
+  subscriptionContext: 'https://code.claude.com/docs/en/model-config',
+});
+
+/**
+ * @typedef {object} ModelCapabilities
+ * @property {'haiku'|'sonnet'|'opus'} family
+ * @property {number} maxOutputTokens Standard Messages API limit, not Batch beta.
+ * @property {number|undefined} contextWindow Unambiguous window across supported auth modes.
+ * @property {boolean} capacityUpgradeSource Existing small/opt-in-window models.
+ * @property {boolean} toolReferences
+ * @property {boolean} autoMode Claude client Auto eligibility, not arbitrary request compatibility.
+ * @property {boolean} sharedAuto Verified modern Auto execution pair.
+ * @property {readonly string[]} thinkingTypes
+ * @property {readonly string[]} effortLevels
+ * @property {boolean} forcedToolChoice
+ * @property {boolean} assistantPrefill
+ * @property {boolean} defaultSamplingOnly
+ * @property {boolean} midConversationSystem
+ * @property {boolean} perMessageEffort
+ * @property {boolean} taskBudget
+ * @property {'adaptive'|'between_tools'|undefined} [disabledThinkingAdaptation]
+ * @property {string} reviewedAt
+ * @property {string} source
+ */
+
+const BASIC_EFFORT = Object.freeze(['low', 'medium', 'high']);
+const FOUR_EFFORT = Object.freeze([...BASIC_EFFORT, 'max']);
+const FIVE_EFFORT = Object.freeze([...BASIC_EFFORT, 'xhigh', 'max']);
+const EXTENDED = Object.freeze(['disabled', 'enabled']);
+const BOTH = Object.freeze(['disabled', 'enabled', 'adaptive']);
+const ADAPTIVE = Object.freeze(['disabled', 'adaptive']);
+const registry = {};
+
+function add(ids, facts) {
+  const canonical = ids[0].replace(/^claude-/, '');
+  const entry = Object.freeze({
+    contextWindow: 200000, maxOutputTokens: 64000, capacityUpgradeSource: true,
+    toolReferences: true, autoMode: false, sharedAuto: false,
+    thinkingTypes: EXTENDED, effortLevels: Object.freeze([]),
+    forcedToolChoice: true, assistantPrefill: true, defaultSamplingOnly: false,
+    midConversationSystem: false, perMessageEffort: false, taskBudget: false,
+    reviewedAt: MODEL_CATALOG_REVIEWED_AT,
+    source: `https://platform.claude.com/docs/en/models/${canonical}/overview`,
+    ...facts,
+  });
+  for (const id of ids) registry[id] = entry;
+}
+
+add(['claude-haiku-4-5', 'claude-haiku-4-5-20251001'], { family: 'haiku' });
+add(['claude-sonnet-4-5', 'claude-sonnet-4-5-20250929'], { family: 'sonnet' });
+add(['claude-opus-4-5', 'claude-opus-4-5-20251101'], { family: 'opus', effortLevels: BASIC_EFFORT });
+// 4.6 has a 1M API window, but subscription usage can need a client opt-in.
+// Retain the existing conservative capacity policy instead of promising 1M.
+for (const family of ['sonnet', 'opus']) add([`claude-${family}-4-6`], {
+  family, contextWindow: undefined, maxOutputTokens: 128000, autoMode: true,
+  thinkingTypes: BOTH, effortLevels: FOUR_EFFORT, assistantPrefill: false,
+});
+for (const version of ['4-7', '4-8']) add([`claude-opus-${version}`], {
+  family: 'opus', contextWindow: 1000000, maxOutputTokens: 128000,
+  capacityUpgradeSource: false, autoMode: true, thinkingTypes: ADAPTIVE,
+  effortLevels: FIVE_EFFORT, assistantPrefill: false, defaultSamplingOnly: true,
+});
+for (const family of ['sonnet', 'opus']) for (const version of ['5', '5-5']) {
+  const latest = version === '5-5';
+  add([`claude-${family}-${version}`], {
+    family, contextWindow: 1000000, maxOutputTokens: 128000,
+    capacityUpgradeSource: false, autoMode: true, sharedAuto: true,
+    thinkingTypes: latest ? Object.freeze(family === 'sonnet' ? ['adaptive', 'between_tools'] : ['adaptive']) : ADAPTIVE,
+    effortLevels: FIVE_EFFORT, forcedToolChoice: !latest,
+    assistantPrefill: false, defaultSamplingOnly: true,
+    midConversationSystem: family === 'opus' || latest,
+    perMessageEffort: family === 'opus' || latest,
+    taskBudget: family === 'opus' || latest,
+    // Preserve the existing explicit adaptation for Opus 5 as well as 5.5.
+    disabledThinkingAdaptation: family === 'opus' ? 'adaptive' : latest ? 'between_tools' : undefined,
+  });
+}
+
+export const MODEL_CATALOG = Object.freeze(registry);
+/** @returns {Readonly<ModelCapabilities>|undefined} */
+export const modelCapabilities = model => typeof model === 'string' && Object.hasOwn(MODEL_CATALOG, model)
+  ? MODEL_CATALOG[model] : undefined;
+export const modelContextWindow = model => modelCapabilities(model)?.contextWindow;
+export const hasNativeMillionContext = model => modelContextWindow(model) === 1000000;
+export const canUpgradeContext = model => modelCapabilities(model)?.capacityUpgradeSource === true;
+export const supportsToolReferences = model => modelCapabilities(model)?.toolReferences === true;
+export const supportsAutoMode = model => modelCapabilities(model)?.autoMode === true;

package/src/model-request.mjs

@@ -1,6 +1,4 @@
-// Keep adaptations explicit: models in the same family can have different
-// thinking contracts. Preserve the existing adaptive Opus upgrade behavior.
-const ADAPTIVE_TARGETS = new Set(['claude-opus-5', 'claude-opus-5-5']);
+import { modelCapabilities } from './model-catalog.mjs';
 
 function sonnetNeedsAdaptive(body) {
   const effort = body.output_config?.effort ?? 'high';
@@ -14,17 +12,18 @@ function sonnetNeedsAdaptive(body) {
 export function prepareRequest(body, model) {
   const request = { ...body, model };
   const adjustments = [];
+  const adaptation = modelCapabilities(model)?.disabledThinkingAdaptation;
   if (model !== body.model && body.model === 'claude-sonnet-5-5' && body.thinking?.type === 'between_tools'
-    && Object.keys(body.thinking).length === 1 && ADAPTIVE_TARGETS.has(model)) {
+    && Object.keys(body.thinking).length === 1 && adaptation === 'adaptive') {
     request.thinking = { type: 'adaptive' };
     adjustments.push('adaptive_thinking_required');
   }
-  if (model !== body.model && body.thinking?.type === 'disabled') {
-    if (model === 'claude-sonnet-5-5') {
+  if (model !== body.model && body.thinking?.type === 'disabled' && Object.keys(body.thinking).length === 1) {
+    if (adaptation === 'between_tools') {
       const type = sonnetNeedsAdaptive(body) ? 'adaptive' : 'between_tools';
       request.thinking = { type };
       adjustments.push(type === 'adaptive' ? 'adaptive_thinking_required' : 'between_tools_thinking_required');
-    } else if (ADAPTIVE_TARGETS.has(model)) {
+    } else if (adaptation === 'adaptive') {
       request.thinking = { type: 'adaptive' };
       adjustments.push('adaptive_thinking_required');
     }

package/src/ollama-evaluator.mjs

@@ -1,5 +1,6 @@
 import { validateOllamaEndpoint, validateOllamaModel } from './ollama-models.mjs';
 import { buildState } from './prompt-state.mjs';
+import { cancelResponseBody, readBoundedJson, MODEL_METADATA_LIMIT } from './bounded-json.mjs';
 
 // Bound UTF-8 bytes as well as serialized characters to keep local decision
 // excerpts small, including when the prompt contains non-ASCII text.
@@ -51,44 +52,20 @@ export function buildOllamaRequest(state, config) {
   return { model: config.ollamaModel, state, questions: OLLAMA_QUESTIONS, keep_alive: config.ollamaKeepAlive };
 }
 
-async function readJson(response, signal, limit = 64 * 1024) {
-  const reader = response.body?.getReader();
-  if (!reader) throw new Error('classifier_invalid_response');
-  let total = 0;
-  const chunks = [];
-  const abort = () => { void reader.cancel(signal.reason).catch(() => {}); };
-  signal.addEventListener('abort', abort, { once: true });
-  try {
-    while (true) {
-      signal.throwIfAborted();
-      const { value, done } = await reader.read();
-      if (done) break;
-      total += value.byteLength;
-      if (total > limit) throw new Error('classifier_invalid_response');
-      chunks.push(Buffer.from(value));
-    }
-    signal.throwIfAborted();
-    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-  } finally {
-    signal.removeEventListener('abort', abort);
-    await reader.cancel().catch(() => {}); reader.releaseLock();
-  }
-}
-
 async function request(config, path, body, { fetchImpl, signal, responseLimit }) {
   const response = await fetchImpl(`${config.ollamaEndpoint}${path}`, {
     method: 'POST', redirect: 'error', signal,
     headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),
   });
   if (!response.ok) {
-    await response.body?.cancel();
+    cancelResponseBody(response);
     const needsVersion = path === '/v1/systemone' && response.status === 404;
     const error = new Error(needsVersion ? OLLAMA_VERSION_MESSAGE : 'classifier_http_error');
     if (needsVersion) error.code = 'OLLAMA_VERSION';
     error.classifierStatus = response.status;
     throw error;
   }
-  return readJson(response, signal, responseLimit);
+  return readBoundedJson(response, { signal, limit: responseLimit });
 }
 
 const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -120,13 +97,18 @@ export async function checkLocalOllamaModel(config, options) {
   validateOllamaModel(config.ollamaModel);
   // /show includes tensor metadata and licenses that can exceed 64 KiB. Keep
   // its separate limit bounded while decision responses stay at 64 KiB.
-  const model = await request(config, '/api/show', { model: config.ollamaModel }, { ...options, responseLimit: 1024 * 1024 });
+  const model = await request(config, '/api/show', { model: config.ollamaModel }, { ...options, responseLimit: MODEL_METADATA_LIMIT });
   if (!model || typeof model !== 'object' || model.remote_host || model.remote_model
     || typeof model.details?.parameter_size !== 'string' || !model.details.parameter_size) {
     throw new Error('classifier_invalid_response');
   }
 }
 
+/**
+ * @param {any} state
+ * @param {any} config
+ * @param {{fetchImpl?:typeof fetch,signal?:AbortSignal}} [options]
+ */
 export async function evaluateOllama(state, config, { fetchImpl = fetch, signal } = {}) {
   let combined = signal;
   if (config.ollamaTimeoutMs !== 0) {

package/src/onboarding.mjs

@@ -1,11 +1,10 @@
 import { execFile } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { createInterface } from 'node:readline';
 import { Writable } from 'node:stream';
 import { promisify } from 'node:util';
 import { CLIENT_PROFILES, readConfig, requireKeys, parseStopHookBlockCap, parseSessionLogDir } from './config.mjs';
 import { buildClaudeEnv, conflictingProviders, LOCAL_AUTH_HEADER } from './auth.mjs';
-import { getConfigPath, loadUserConfig, saveUserConfig } from './user-config.mjs';
+import { CONFIG_KEYS, SECRET_CONFIG_KEYS, SECRET_STORES, keychainRemovals, loadUserConfig, saveUserConfig } from './user-config.mjs';
 import { DEFAULT_OLLAMA_MODEL, validateOllamaModel } from './ollama-models.mjs';
 import { inspectOllama, setupOllama } from './ollama-setup.mjs';
 
@@ -38,21 +37,34 @@ export async function askSecret(label, { input = process.stdin, output = process
 }
 
 export async function setup(args, {
-  env = process.env, write = console.log, prompt = askSecret, fetchImpl = fetch, signal,
+  env = process.env, write = console.log, prompt = askSecret, fetchImpl = fetch, signal, keychain,
+  platform = process.platform,
 } = {}) {
-  let authMode = env.AUTOROUTER_AUTH_MODE ?? 'subscription';
-  let clientProfile = env.AUTOROUTER_CLIENT_PROFILE ?? 'compatible';
-  let evaluator = env.AUTOROUTER_EVALUATOR ?? 'jev';
+  if (signal?.aborted) throw new Error('Setup cancelled');
+  const store = keychain ? { keychain } : {};
+  const loaded = loadUserConfig(env, { allowMissing: true, ...store });
+  const replace = args.includes('--replace');
+  const mergeExisting = loaded.exists && !replace;
+  // Updating one preference must not turn unrelated runtime overrides into
+  // saved defaults. First setup/replacement still supports environment-only
+  // configuration; an explicitly selected backend can use its supplied key.
+  const effectiveEnv = mergeExisting ? loaded.values : env;
+  let explicitEvaluator = false, explicitAuthMode = false;
+  let authMode = effectiveEnv.AUTOROUTER_AUTH_MODE ?? 'subscription';
+  let clientProfile = effectiveEnv.AUTOROUTER_CLIENT_PROFILE ?? 'compatible';
+  let evaluator = effectiveEnv.AUTOROUTER_EVALUATOR ?? 'ollama';
   let model;
   let ollamaTimeoutMs;
-  let stopHookBlockCap = env.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP;
-  let sessionLogDir = env.AUTOROUTER_SESSION_LOG_DIR;
+  let stopHookBlockCap = effectiveEnv.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP;
+  let sessionLogDir = effectiveEnv.AUTOROUTER_SESSION_LOG_DIR;
+  let sessionLogMode = effectiveEnv.AUTOROUTER_SESSION_LOG_MODE;
+  let secretStore;
   let pull = false;
-  let overwrite = false;
+  let overwrite = replace;
   for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--auth-mode') authMode = args[++i];
+    if (args[i] === '--auth-mode') { authMode = args[++i]; explicitAuthMode = true; }
     else if (args[i] === '--client-profile') clientProfile = args[++i];
-    else if (args[i] === '--evaluator') evaluator = args[++i];
+    else if (args[i] === '--evaluator') { evaluator = args[++i]; explicitEvaluator = true; }
     else if (args[i] === '--ollama-model') { model = args[++i]; if (model === undefined) throw new Error('--ollama-model requires a model tag'); }
     else if (args[i] === '--ollama-timeout-ms') {
       const value = args[++i];
@@ -69,9 +81,18 @@ export async function setup(args, {
       if (sessionLogDir === undefined || sessionLogDir.startsWith('--')) throw new Error('--session-log-dir requires a directory path');
       parseSessionLogDir(sessionLogDir, '--session-log-dir');
     }
+    else if (args[i] === '--session-log-mode') {
+      sessionLogMode = args[++i];
+      if (!['metadata', 'prompts'].includes(sessionLogMode)) throw new Error('--session-log-mode must be metadata or prompts');
+    }
+    else if (args[i] === '--secret-store') {
+      secretStore = args[++i];
+      if (!SECRET_STORES.includes(secretStore)) throw new Error('--secret-store must be file or keychain');
+    }
     else if (args[i] === '--pull') pull = true;
     else if (args[i] === '--force') overwrite = true;
-    else throw new Error('Usage: claude-autorouter setup [--auth-mode subscription|api-key] [--client-profile compatible|native|auto] [--evaluator jev|ollama] [--ollama-model TAG] [--ollama-timeout-ms N] [--stop-hook-block-cap N] [--session-log-dir DIR] [--pull] [--force]');
+    else if (args[i] === '--replace') continue;
+    else throw new Error('Usage: claude-autorouter setup [--auth-mode subscription|api-key] [--client-profile compatible|native|auto] [--evaluator jev|ollama] [--ollama-model TAG] [--ollama-timeout-ms N] [--stop-hook-block-cap N] [--session-log-dir DIR] [--session-log-mode metadata|prompts] [--secret-store file|keychain] [--pull] [--force|--replace]');
   }
   if (!['subscription', 'api-key'].includes(authMode)) throw new Error('--auth-mode must be subscription or api-key');
   if (!CLIENT_PROFILES.includes(clientProfile)) throw new Error('--client-profile must be compatible, native or auto');
@@ -79,69 +100,151 @@ export async function setup(args, {
   if (evaluator !== 'ollama' && (model !== undefined || ollamaTimeoutMs !== undefined || pull)) throw new Error('Ollama model, deadline and download options require --evaluator ollama');
   if (stopHookBlockCap !== undefined) stopHookBlockCap = parseStopHookBlockCap(stopHookBlockCap);
   if (sessionLogDir !== undefined) sessionLogDir = parseSessionLogDir(sessionLogDir) ?? '';
-  const path = getConfigPath(env);
-  if (!overwrite && existsSync(path)) throw new Error('AutoRouter configuration already exists. Use setup --force to replace it.');
+  const path = loaded.path;
+  if (!overwrite && loaded.exists) throw new Error('AutoRouter configuration already exists. Use setup --force to update it while preserving unrelated settings.');
   write(evaluator === 'ollama'
     ? 'AutoRouter evaluates bounded prompt excerpts locally with Ollama. Complete requests still go to Anthropic.'
     : 'AutoRouter sends bounded prompt excerpts to TypeSafe Jev and complete requests to Anthropic.');
-  const values = { AUTOROUTER_AUTH_MODE: authMode, AUTOROUTER_CLIENT_PROFILE: clientProfile, AUTOROUTER_EVALUATOR: evaluator };
+  const values = replace ? {} : { ...loaded.values };
+  const selectedBackendKeys = explicitEvaluator ? CONFIG_KEYS.filter(key => evaluator === 'ollama'
+    ? key.startsWith('AUTOROUTER_OLLAMA_') : key.startsWith('AUTOROUTER_JEV_') || key === 'AUTOROUTER_MIN_CONFIDENCE') : [];
+  for (const key of mergeExisting ? selectedBackendKeys : CONFIG_KEYS) {
+    if (!SECRET_CONFIG_KEYS.includes(key) && env[key] !== undefined) values[key] = env[key];
+  }
+  Object.assign(values, { AUTOROUTER_AUTH_MODE: authMode, AUTOROUTER_CLIENT_PROFILE: clientProfile, AUTOROUTER_EVALUATOR: evaluator });
   if (stopHookBlockCap !== undefined) values.CLAUDE_CODE_STOP_HOOK_BLOCK_CAP = String(stopHookBlockCap);
   if (sessionLogDir !== undefined) values.AUTOROUTER_SESSION_LOG_DIR = sessionLogDir;
+  if (sessionLogMode !== undefined) values.AUTOROUTER_SESSION_LOG_MODE = sessionLogMode;
+  if (secretStore !== undefined) values.AUTOROUTER_SECRET_STORE = secretStore;
+  // New and rebuilt configurations keep keys in the macOS Keychain. An existing
+  // configuration keeps its store until the user moves it deliberately.
+  const defaultedStore = values.AUTOROUTER_SECRET_STORE === undefined && platform === 'darwin' && (!loaded.exists || replace);
+  if (defaultedStore) values.AUTOROUTER_SECRET_STORE = 'keychain';
   if (evaluator === 'ollama') {
-    values.AUTOROUTER_OLLAMA_MODEL = validateOllamaModel(model ?? env.AUTOROUTER_OLLAMA_MODEL ?? DEFAULT_OLLAMA_MODEL);
+    values.AUTOROUTER_OLLAMA_MODEL = validateOllamaModel(model
+      ?? (explicitEvaluator ? env.AUTOROUTER_OLLAMA_MODEL : undefined) ?? effectiveEnv.AUTOROUTER_OLLAMA_MODEL ?? DEFAULT_OLLAMA_MODEL);
     for (const key of ['AUTOROUTER_OLLAMA_URL', 'AUTOROUTER_OLLAMA_TIMEOUT_MS', 'AUTOROUTER_OLLAMA_KEEP_ALIVE']) {
-      if (env[key] !== undefined) values[key] = env[key];
+      if ((!mergeExisting || explicitEvaluator) && env[key] !== undefined) values[key] = env[key];
     }
     if (ollamaTimeoutMs !== undefined) values.AUTOROUTER_OLLAMA_TIMEOUT_MS = ollamaTimeoutMs;
   }
   const keys = [...(evaluator === 'jev' ? ['TYPESAFE_API_KEY'] : []), ...(authMode === 'api-key' ? ['ANTHROPIC_API_KEY'] : [])];
+  // Reject invalid settings before inviting secret input or making local calls.
+  readConfig(values);
+  if (values.AUTOROUTER_SECRET_STORE === 'keychain' && platform !== 'darwin') {
+    throw new Error('--secret-store keychain is available only on macOS');
+  }
   for (const key of keys) {
-    const value = (env[key]?.trim() || await prompt(key)).trim();
+    if (signal?.aborted) throw new Error('Setup cancelled');
+    const explicitlySelected = !mergeExisting || (key === 'TYPESAFE_API_KEY' ? explicitEvaluator : explicitAuthMode);
+    const value = ((explicitlySelected ? env[key]?.trim() : '') || effectiveEnv[key]?.trim() || env[key]?.trim() || await prompt(key)).trim();
+    if (signal?.aborted) throw new Error('Setup cancelled');
     if (!value || /[\r\n\0]/.test(value)) throw new Error(`${key} must be a nonempty, single-line key`);
     values[key] = value;
   }
   const config = readConfig(values);
   requireKeys(config);
+  if (signal?.aborted) throw new Error('Setup cancelled');
   if (config.clientProfile === 'auto') write('Auto-compatible profile: Sonnet/Opus task routing. Claude controls permission-mode availability and safety checks.');
   if (config.stopHookBlockCap !== undefined) write(stopHookCapText(config.stopHookBlockCap));
-  if (config.sessionLogDir) write('Session decision logs enabled; files include up to 500 characters of user prompt text per decision.');
+  if (config.sessionLogDir) write(config.sessionLogMode === 'metadata' ? 'Session logs enabled with metadata only; prompt excerpts are omitted.'
+    : 'Session decision logs enabled; files include up to 500 characters of user prompt text per decision.');
   if (evaluator === 'ollama') {
     write(`Local evaluator: ${config.ollamaModel}; ${ollamaDeadlineText(config.ollamaTimeoutMs)}.`);
     const controller = new AbortController();
     const cancel = () => controller.abort();
     if (!signal) for (const name of ['SIGINT', 'SIGTERM']) process.once(name, cancel);
     try { await setupOllama(config, { pull, warm: true, write, fetchImpl, signal: signal ?? controller.signal }); }
+    catch (error) {
+      // Local evaluation is the default, not a choice the user made, so a
+      // missing or stopped Ollama should say how to pick another evaluator.
+      if (!explicitEvaluator && !mergeExisting && !signal?.aborted) {
+        error.message = `${error.message} Local Ollama is the default evaluator; add --pull to download its model, or use TypeSafe Jev instead: claude-autorouter setup --evaluator jev`;
+      }
+      throw error;
+    }
     finally { if (!signal) for (const name of ['SIGINT', 'SIGTERM']) process.removeListener(name, cancel); }
   }
   if (signal?.aborted) throw new Error('Setup cancelled');
-  saveUserConfig(values, { env, overwrite });
+  let savedStore = values.AUTOROUTER_SECRET_STORE ?? 'file';
+  try {
+    saveUserConfig(values, { env, overwrite, expectedRevision: loaded.revision,
+      removeSecrets: keychainRemovals(loaded, savedStore, { replace, values }), ...store });
+  } catch (error) {
+    // The default must not make setup impossible where the Keychain cannot be
+    // used (locked, headless). An explicit request still fails.
+    if (!defaultedStore || !keys.length || error?.code !== 'AUTOROUTER_CONFIG_ERROR' || !/Keychain/.test(error.message)) throw error;
+    write('The macOS Keychain is unavailable; saving keys in the private configuration file instead. Move them later with: claude-autorouter config set AUTOROUTER_SECRET_STORE keychain');
+    delete values.AUTOROUTER_SECRET_STORE;
+    savedStore = 'file';
+    saveUserConfig(values, { env, overwrite, expectedRevision: loaded.revision,
+      removeSecrets: keychainRemovals(loaded, savedStore, { replace, values }), ...store });
+  }
   write(`Saved ${authMode} configuration to ${path}`);
-  write(`${keys.length ? 'Keys and settings are' : 'Settings are'} stored locally in this file with owner-only permissions. Environment variables take precedence.`);
+  if (keys.length && savedStore === 'keychain') {
+    write('Keys are stored in the macOS Keychain; settings are stored in this file with owner-only permissions. Environment variables take precedence.');
+  } else {
+    write(`${keys.length ? 'Keys and settings are' : 'Settings are'} stored locally in this file with owner-only permissions. Environment variables take precedence.`);
+    if (keys.length && platform === 'darwin' && savedStore === 'file' && !defaultedStore) write('Keys are plaintext in this file. Move them into the macOS Keychain: claude-autorouter config set AUTOROUTER_SECRET_STORE keychain');
+  }
   write('Next: claude-autorouter doctor, then claude-autorouter claude from your project.');
 }
 
-export async function doctor({ env = process.env, write = console.log, run = execute, fetchImpl = fetch, signal } = {}) {
+export async function doctor({ env = process.env, write = console.log, run = execute, fetchImpl = fetch, signal,
+  evaluateLocal = false, json = false, diagnosticRunner, keychain, platform = process.platform } = {}) {
+  if (evaluateLocal) {
+    try {
+      const config = readConfig(loadUserConfig(env).env);
+      if (config.evaluator !== 'ollama') throw new Error('Local evaluation requires AUTOROUTER_EVALUATOR=ollama. It does not call Jev or Anthropic.');
+      const diagnostic = await import('./local-diagnostic.mjs');
+      const onProgress = json ? () => {} : progress => {
+        if (progress.event === 'preflight') write('Checking the local evaluator; no Claude authentication or cloud requests are used.');
+        else if (progress.event === 'startup') write('Preparing the local model with a separate 60-second startup deadline…');
+        else if (progress.event === 'case_start') write('Checking a synthetic routing case…');
+        else if (progress.event === 'case_complete') write('Synthetic routing case finished.');
+      };
+      const result = await (diagnosticRunner ?? diagnostic.runLocalDiagnostic)(config, { fetchImpl, signal, onProgress });
+      if (json) write(JSON.stringify(result));
+      else for (const line of diagnostic.formatLocalDiagnostic(result)) write(line);
+      return result.passed;
+    } catch (error) {
+      if (signal?.aborted) throw error;
+      if (json) write(JSON.stringify({ schema_version: 1, type: 'local_evaluator_diagnostic', passed: false,
+        error: { code: 'configuration_error', message: error.message } }));
+      else write(`FAIL  ${error.message}`);
+      return false;
+    }
+  }
   let healthy = true;
   const report = (ok, message) => { if (!ok) healthy = false; write(`${ok ? 'OK' : 'FAIL'}  ${message}`); };
   report(Number(process.versions.node.split('.')[0]) >= 22, `Node.js ${process.versions.node} (requires 22+)`);
   let config;
   let effectiveEnv = env;
   try {
-    const loaded = loadUserConfig(env);
+    const loaded = loadUserConfig(env, keychain ? { keychain } : {});
     effectiveEnv = loaded.env;
     write(`Config: ${loaded.path}${loaded.exists ? '' : ' (absent; using environment)'}`);
+    if (loaded.secretStore === 'keychain') write(`Saved secrets: macOS Keychain (${loaded.keychainSecrets.length} found).`);
+    else if (platform === 'darwin' && SECRET_CONFIG_KEYS.some(key => Object.hasOwn(loaded.values, key))) {
+      write('WARN  Saved keys are plaintext in the configuration file. Move them into the macOS Keychain: claude-autorouter config set AUTOROUTER_SECRET_STORE keychain');
+    }
     config = readConfig(effectiveEnv);
     requireKeys(config);
     report(true, `Configuration and required keys present (${config.authMode})`);
   } catch (error) {
-    report(false, `${error.message}. Run claude-autorouter setup.`);
+    report(false, `${error.message}. Use claude-autorouter config show --check-all to inspect settings, or setup for first-time configuration.`);
   }
   for (const key of conflictingProviders(effectiveEnv)) {
     report(false, `Unset ${key}; AutoRouter uses the Anthropic Messages API`);
   }
   if (config?.stopHookBlockCap !== undefined) write(stopHookCapText(config.stopHookBlockCap));
+  if (config) {
+    write(`Routing profile: ${config.clientProfile}; Haiku ${config.models.haiku}; Sonnet ${config.models.sonnet}; Opus ${config.models.opus}.`);
+    if (config.evaluator === 'jev') write(`Evaluator: Jev ${config.jevModel}; routing deadline ${config.jevTimeoutMs} ms; confidence floor ${config.minConfidence}.`);
+  }
   if (config?.clientProfile === 'auto') write('Auto-compatible profile: Sonnet/Opus task routing. Claude controls permission-mode availability and safety checks.');
-  if (config?.sessionLogDir) write('Session decision logs enabled; files include up to 500 characters of user prompt text per decision.');
+  if (config?.sessionLogDir) write(config.sessionLogMode === 'metadata' ? 'Session logs enabled with metadata only; prompt excerpts are omitted.'
+    : 'Session decision logs enabled; files include up to 500 characters of user prompt text per decision.');
   if (config?.evaluator === 'ollama') {
     write(`Local evaluator: ${config.ollamaModel}; ${ollamaDeadlineText(config.ollamaTimeoutMs)}.`);
     write('Model availability is checked below; classification speed and accuracy are not tested.');
@@ -149,7 +252,7 @@ export async function doctor({ env = process.env, write = console.log, run = exe
       const result = await inspectOllama(config, { fetchImpl, signal });
       report(result.installed, result.installed
         ? `Local Ollama model available (${result.model})`
-        : `Ollama model missing (${result.model}). Run ollama pull ${result.model}, or setup --evaluator ollama --pull --force.`);
+        : `Ollama model missing (${result.model}). Run claude-autorouter setup --evaluator ollama --ollama-model ${result.model} --pull --force.`);
     } catch (error) {
       report(false, error.message);
     }
@@ -168,6 +271,7 @@ export async function doctor({ env = process.env, write = console.log, run = exe
     const { stdout } = await run('claude', ['--version'], { env: childEnv, timeout: 10000, maxBuffer: 64 * 1024 });
     const version = /\b\d+\.\d+\.\d+\b/.exec(stdout)?.[0];
     report(Boolean(version), version ? `Claude Code ${version}` : 'Could not recognize Claude Code version');
+    if (version) write(`Historical integration observations cover Claude Code 2.1.284 and 2.1.285; finding an executable does not certify its full compatibility${['2.1.284', '2.1.285'].includes(version) ? '.' : ' (installed version differs).'}`);
     claudeAvailable = Boolean(version);
   } catch {
     report(false, 'Claude Code unavailable. Install claude and ensure it is on PATH.');

package/src/prompt-state.mjs

@@ -1,3 +1,5 @@
+import { redactSensitive } from './redaction.mjs';
+
 // Claude Code prepends these as separate text blocks. Ignore only complete
 // wrapper blocks; a user's text that mentions a tag or mixes it with a task
 // must remain part of the classifier's input.
@@ -51,6 +53,16 @@ function excerpt(text, length) {
 
 const textCost = text => JSON.stringify(text).length - 2;
 
+// Redact before excerpting so a value cannot be split into an unrecognizable
+// fragment. Very long text keeps only end windows wider than any retained
+// excerpt; the margin also keeps a value cut at a window edge out of the result.
+const REDACTION_MARGIN = 4096;
+function classifierText(text, limit) {
+  const span = limit + REDACTION_MARGIN;
+  if (text.length > 2 * span) text = `${text.slice(0, span)}\n[... omitted ...]\n${text.slice(-span)}`;
+  return redactSensitive(text);
+}
+
 // Budget serialized characters, including JSON escaping, rather than just
 // raw text length. The two ends keep both an initial instruction and a final
 // question visible when one long text block must be shortened.
@@ -145,6 +157,9 @@ export function promptExcerpt(body, maxChars = 500) {
     const blocks = typeof content === 'string' ? [{ type: 'text', text: content }]
       : Array.isArray(content) ? content : [];
     const characters = [];
+    // Collect past the retained length: redaction must see a value that
+    // straddles the final boundary, and may shorten the text before the cut.
+    const window = maxChars + REDACTION_MARGIN;
     let nonText = false;
     for (const block of blocks) {
       if (block?.type !== 'text' || typeof block.text !== 'string') {
@@ -157,12 +172,12 @@ export function promptExcerpt(body, maxChars = 500) {
       if (!/\S/.test(value) || isReminderBlock(value)) continue;
       if (characters.length) characters.push('\n');
       for (const character of value) {
-        if (characters.length >= maxChars) break;
+        if (characters.length >= window) break;
         characters.push(character);
       }
-      if (characters.length >= maxChars) break;
+      if (characters.length >= window) break;
     }
-    if (characters.length) return characters.join('').toWellFormed();
+    if (characters.length) return [...redactSensitive(characters.join('').toWellFormed())].slice(0, maxChars).join('').toWellFormed();
     // An image/document-only human turn is a new task with no safe excerpt;
     // do not incorrectly label it with the preceding human task's text.
     if (nonText) return '';
@@ -196,9 +211,9 @@ export function buildState(body, limit = 12000) {
   const remaining = () => Math.max(0, limit - JSON.stringify(state).length);
   // Reserve more than half of the budget for the actual latest human task
   // before considering reminders, original instructions, or tool results.
-  state.current_task = fitText(currentTask, Math.min(remaining(), Math.floor(limit * 0.55)));
-  state.original_task = fitText(firstTask, Math.min(2000, Math.floor(remaining() * 0.3)));
-  state.system = fitText(contentText(body.system, true), Math.min(1000, Math.floor(remaining() * 0.3)));
+  state.current_task = fitText(classifierText(currentTask, limit), Math.min(remaining(), Math.floor(limit * 0.55)));
+  state.original_task = fitText(classifierText(firstTask, limit), Math.min(2000, Math.floor(remaining() * 0.3)));
+  state.system = fitText(classifierText(contentText(body.system, true), limit), Math.min(1000, Math.floor(remaining() * 0.3)));
 
   for (let index = messages.length - 1; index >= 0 && state.recent_messages.length < 8; index--) {
     // current_task already contains this message; leave room for actual
@@ -210,7 +225,7 @@ export function buildState(body, limit = 12000) {
     const overhead = JSON.stringify(entry).length + (state.recent_messages.length ? 1 : 0);
     const budget = Math.min(3000, remaining() - overhead);
     if (budget < 1) break;
-    entry.content = fitText(text, budget);
+    entry.content = fitText(classifierText(text, limit), budget);
     state.recent_messages.unshift(entry);
   }
   return state;

package/src/redaction.mjs

@@ -0,0 +1,97 @@
+// @ts-check
+// Pattern-based redaction for evaluator excerpts. Classification needs the
+// shape of a task, not credentials or personal identifiers, so recognizable
+// values are replaced before any excerpt leaves the inference path. This is a
+// best-effort filter: unrecognized formats can remain, and code that merely
+// resembles an assignment can be over-redacted. Every quantifier is bounded or
+// excludes its delimiter, so scanning stays linear in the input length.
+
+const marker = kind => `[REDACTED:${kind}]`;
+
+function ibanValid(value) {
+  const compact = value.replace(/ /g, '');
+  if (compact.length < 15 || compact.length > 34) return false;
+  const rearranged = compact.slice(4) + compact.slice(0, 4);
+  let remainder = 0;
+  for (const character of rearranged) {
+    const digits = /[0-9]/.test(character) ? character : String(character.charCodeAt(0) - 55);
+    for (const digit of digits) remainder = (remainder * 10 + Number(digit)) % 97;
+  }
+  return remainder === 1;
+}
+
+function luhnValid(value) {
+  const digits = value.replace(/[ -]/g, '');
+  if (digits.length < 13 || digits.length > 19) return false;
+  let sum = 0;
+  for (let i = 0; i < digits.length; i++) {
+    let digit = Number(digits[digits.length - 1 - i]);
+    if (i % 2 === 1) { digit *= 2; if (digit > 9) digit -= 9; }
+    sum += digit;
+  }
+  return sum % 10 === 0;
+}
+
+const base64 = code => (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122)
+  || code === 43 || code === 47 || code === 61;
+
+// Key material whose BEGIN line was cut off before the excerpt: walk back from
+// each END line over whole base64 lines. A regex line repetition would
+// backtrack quadratically on a long base64 run that is not followed by END.
+function redactKeyTails(text) {
+  const end = /-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----/g;
+  let output = '', copied = 0;
+  for (let match; (match = end.exec(text));) {
+    let start = match.index;
+    while (start > copied && text[start - 1] === '\n') {
+      let lineEnd = start - 1;
+      if (lineEnd > copied && text[lineEnd - 1] === '\r') lineEnd--;
+      let lineStart = lineEnd;
+      while (lineStart > copied && base64(text.charCodeAt(lineStart - 1))) lineStart--;
+      if (lineEnd - lineStart < 16 || (lineStart > copied && text[lineStart - 1] !== '\n')) break;
+      start = lineStart;
+    }
+    if (start === match.index) continue;
+    output += text.slice(copied, start) + marker('private_key');
+    copied = end.lastIndex;
+  }
+  return copied ? output + text.slice(copied) : text;
+}
+
+/** @type {ReadonlyArray<readonly [RegExp, string | ((...match: string[]) => string)] | ((text: string) => string)>} */
+const RULES = Object.freeze([
+  // A block cut off by excerpting is still redacted through the end of text.
+  [/-----BEGIN [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----[\s\S]*?(?:-----END [A-Z0-9 ]{0,40}PRIVATE KEY(?: BLOCK)?-----|$)/g, marker('private_key')],
+  redactKeyTails,
+  [/\b([a-z][a-z0-9+.-]{1,20}:\/\/)[^\s:@/]{1,256}:[^\s@/]{1,256}@/gi, (_, scheme) => `${scheme}${marker('credentials')}@`],
+  [/\bsk-[A-Za-z0-9_-]{20,}/g, marker('secret')],
+  [/\b[rs]k_(?:live|test)_[A-Za-z0-9]{16,}/g, marker('secret')],
+  [/\b(?:AKIA|ASIA|ABIA|ACCA)[A-Z0-9]{16}\b/g, marker('secret')],
+  [/\b(?:gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{22,})/g, marker('secret')],
+  [/\bglpat-[A-Za-z0-9_-]{20,}/g, marker('secret')],
+  [/\bxox[abposr]-[A-Za-z0-9-]{10,}/g, marker('secret')],
+  [/https:\/\/hooks\.slack\.com\/services\/[A-Za-z0-9/]{8,}/g, marker('secret')],
+  [/\bAIza[0-9A-Za-z_-]{35}/g, marker('secret')],
+  [/\bnpm_[A-Za-z0-9]{36}/g, marker('secret')],
+  [/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}/g, marker('secret')],
+  [/\b((?:proxy-)?authorization["']?[ \t]{0,8}[:=][ \t]{0,8}["']?)(?:(Bearer|Basic|Token|Digest)[ \t]+)?[^\s"',;]{4,}/gi,
+    (_, prefix, scheme) => `${prefix}${scheme ? `${scheme} ` : ''}${marker('secret')}`],
+  [/\b(Bearer[ \t]+)[A-Za-z0-9._~+/-]{16,}=*/g, (_, prefix) => `${prefix}${marker('secret')}`],
+  // Keep the setting name: it tells the classifier what kind of work this is.
+  [/\b([A-Za-z0-9_.-]{0,40}(?:passw(?:or)?d|pwd|secret|token|api[_-]?key|access[_-]?key|private[_-]?key|credentials?)[A-Za-z0-9_.-]{0,40})(["']?[ \t]{0,8}[:=][ \t]{0,8})(["']?)[^\s"',;]{4,}/gi,
+    (_, name, separator, quote) => `${name}${separator}${quote}${marker('secret')}`],
+  [/\b[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,253}\.[A-Za-z]{2,24}\b/g, marker('email')],
+  [/\b[A-Z]{2}[0-9]{2}(?: ?[A-Z0-9]{4}){2,7}(?: ?[A-Z0-9]{1,4})?\b/g, match => ibanValid(match) ? marker('iban') : match],
+  // Major card networks only, so millisecond timestamps and IDs survive.
+  [/\b(?:4|5[1-5]|2[2-7]|3[47]|6)(?:[0-9][ -]?){11,17}[0-9]\b/g, match => luhnValid(match) ? marker('card') : match],
+]);
+
+/** @param {string} text */
+export function redactSensitive(text) {
+  let result = text;
+  for (const rule of RULES) {
+    // @ts-ignore String.replace accepts either replacement form.
+    result = typeof rule === 'function' ? rule(result) : result.replace(rule[0], rule[1]);
+  }
+  return result;
+}