amicus 2.2.0 → 3.1.0

package/skills/second-opinion/SKILL.md

@@ -523,6 +523,8 @@ Use these together with `amicus council stats` (the ledger — authoritative qua
 
 Always **rank recommendations by fit**, state the trade-off for each option, and surface the estimated cost (an estimate, not a guarantee; unpriced legs disclosed as "cost unknown"). Never present a single option without explanation.
 
+**Model naming for council members.** Name bench members by alias (`gemini`, `gpt`, `deepseek`, `opus`, …) or by full `provider/model` id — both work with `--models`/`amicus_fanout`. A bare canonical id (e.g. `anthropic/claude-opus-4.8`) is policy-routed **direct-first**: Amicus uses the user's direct provider key when one is configured, falling back to OpenRouter automatically. `openrouter/provider/model` is an explicit force-OpenRouter override — reach for it only when the user deliberately wants a specific member to run through OpenRouter (e.g. to use a free-tier variant), or for gateway-only vendors with no direct integration. A per-run `--gateway auto|direct|openrouter` (also on `amicus_fanout`/`amicus_start`) overrides routing for the whole wave if the user asks for it; leave it unset (`auto`) by default.
+
 ---
 
 ## Output & naming

package/skills/sidecar/SKILL.md

@@ -75,9 +75,19 @@ Amicus uses the OpenCode SDK to communicate with LLM providers. You need to conf
 
 **Recommended:** run `amicus setup` — a guided wizard that stores keys in `~/.config/amicus/.env`, picks your default model from the live catalog, and seeds aliases. The options below are manual alternatives.
 
+### Model Naming: Bare Canonical Is the Normal Form
+
+Read this before picking a model string — it decides both routing and which credentials get used:
+
+- **Bare `provider/model`** (e.g. `openai/gpt-5.5`, `anthropic/claude-opus-4.8`, `google/gemini-3.5-flash`) is the **canonical, policy-routed** form — use it by default. Amicus routes it **direct-first**: your direct provider key when one is configured, falling back to OpenRouter automatically when only `OPENROUTER_API_KEY` exists. You never pick the gateway by hand.
+- **`openrouter/provider/model`** (e.g. `openrouter/google/gemini-3.5-flash`) is an **explicit force-OpenRouter override** — it always routes through OpenRouter even when a direct key is present. Reach for it deliberately, or for gateway-only vendors with no direct integration at all (Qwen, Grok, Mistral, GLM, MiniMax, Kimi, Seed, …) — those *require* the `openrouter/` prefix.
+- Short aliases (`gemini`, `gpt`, `opus`, `claude`, `deepseek`, …) resolve to one of the two forms above via your config; `amicus setup` seeds direct-capable vendors to the bare canonical form automatically.
+- **Routing controls:** `routing.prefer` in `~/.config/amicus/config.json` sets the global default — `"direct"` (the default) or `"openrouter"` to always prefer OpenRouter. Per call, `--gateway auto|direct|openrouter` overrides it (`auto` = direct-first, same as the default).
+- **One-time migration notice:** if you hold both an OpenRouter key and a direct key for a vendor, the first launch that resolves to that vendor prints a one-time notice that routing moved to direct API (previously OpenRouter); set `routing.prefer: "openrouter"` (or pass `--gateway openrouter`) to restore the old all-OpenRouter behavior.
+
 ### Option A: OpenRouter (Recommended for Multi-Model Access)
 
-OpenRouter provides unified access to many models (Gemini, GPT-4, Claude, o3, etc.) with a single API key. If you'd rather not hand-edit JSON, run `amicus setup` instead — it stores the key for you.
+OpenRouter provides unified access to many models (Gemini, GPT, Claude, o3, etc.) with a single API key. If you'd rather not hand-edit JSON, run `amicus setup` instead — it stores the key for you.
 
 **Step 1: Get an OpenRouter API key**
 - Sign up at https://openrouter.ai
@@ -103,12 +113,11 @@ EOF
 amicus start --model gemini --prompt "Say hello" --no-ui
 ```
 
-**Model names with OpenRouter:**
-When using OpenRouter, prefix the model with `openrouter/`:
+**With OpenRouter as your only key**, aliases and bare canonical ids both work — the router falls back to OpenRouter automatically since no direct key exists for the vendor:
 ```bash
-amicus start --model gemini --prompt "..."
-amicus start --model gpt --prompt "..."
-amicus start --model claude --prompt "..."
+amicus start --model gemini --prompt "..."                              # alias
+amicus start --model google/gemini-3.5-flash --prompt "..."             # bare canonical, falls back to OpenRouter
+amicus start --model openrouter/google/gemini-3.5-flash --prompt "..."  # explicit override — same result here
 ```
 
 ### Option B: Direct API Keys (Provider-Specific)
@@ -136,8 +145,8 @@ Add these to your shell profile (`~/.bashrc`, `~/.zshrc`) for persistence.
 - Run `amicus setup` to store keys in amicus's config (recommended)
 - Move your exports to `~/.zshenv` (sourced by all zsh shell types)
 
-**Model names with direct API keys:**
-When using direct API keys, use the provider/model format WITHOUT the `openrouter/` prefix:
+**Model names with a direct key configured:**
+Use the bare canonical `provider/model` form — direct-first routing picks up these keys automatically, no `openrouter/` prefix needed:
 ```bash
 amicus start --model google/<model-name> --prompt "..."
 amicus start --model openai/<model-name> --prompt "..."
@@ -146,18 +155,15 @@ amicus start --model anthropic/<model-name> --prompt "..."
 
 ### Model Naming Summary
 
-| Provider Access | Model Name Format | Example |
-|-----------------|-------------------|---------|
-| OpenRouter | `openrouter/provider/model` | `openrouter/google/<model-name>` |
-| Direct Google API | `google/model` | `google/<model-name>` |
-| Direct OpenAI API | `openai/model` | `openai/<model-name>` |
-| Direct Anthropic API | `anthropic/model` | `anthropic/<model-name>` |
+| Form | Meaning | Credentials used |
+|------|---------|-------------------|
+| `provider/model` (bare, canonical) | Policy-routed, direct-first | Direct provider key if configured, else `OPENROUTER_API_KEY` |
+| `openrouter/provider/model` | Explicit force-OpenRouter override (required for gateway-only vendors) | `OPENROUTER_API_KEY`, always |
 
-**Important:** The model name format tells the SDK which authentication to use:
-- `openrouter/...` → Uses OpenRouter API key from auth.json
-- `google/...` → Uses `GOOGLE_GENERATIVE_AI_API_KEY` environment variable
-- `openai/...` → Uses `OPENAI_API_KEY` environment variable
-- `anthropic/...` → Uses `ANTHROPIC_API_KEY` environment variable
+**Important:** the bare form is not tied to one credential — the router decides at launch time:
+- `google/...`, `openai/...`, `anthropic/...`, `deepseek/...` (bare) → that vendor's direct key if present, else `OPENROUTER_API_KEY`
+- `openrouter/...` → always `OPENROUTER_API_KEY`
+- `--gateway direct` forces the direct key (errors if it's missing); `--gateway openrouter` forces OpenRouter (errors if that key is missing); omit `--gateway` (or pass `auto`) for the default direct-first behavior described above
 
 ---
 
@@ -252,6 +258,10 @@ amicus start \
 - `--json`: With `--no-ui`, emit the run result as one stable JSON document on stdout
   (`schemaVersion: 2`; the `summary` field is the model's output).
 - `--no-validate-model`: Skip the model-catalog pre-flight check (validation is on by default).
+- `--gateway <mode>`: Routing override for this launch — `auto` (default, direct-first: your
+  direct provider key when present, else OpenRouter), `direct` (require a direct provider key,
+  errors if missing), or `openrouter` (force OpenRouter, errors if that key is missing). Omit to
+  fall back to the `routing.prefer` config default (`"direct"` unless changed).
 - `--agent <agent>`: Agent mode (controls tool permissions). If omitted, defaults to
   **Chat** in interactive mode and **Build** in headless (`--no-ui`) mode — `chat`
   stalls without user interaction, so headless runs need an agent that doesn't wait
@@ -281,17 +291,26 @@ The CLI validates all inputs **before** launching the sidecar. Invalid inputs fa
 | `--timeout` | Must be positive number | `Error: --timeout must be a positive number` |
 | `--context-turns` | Must be positive number | `Error: --context-turns must be a positive number` |
 | `--context-since` | Must match format: `30m`, `2h`, `1d` | `Error: --context-since must be in format: 30m, 2h, or 1d` |
-| API Key | Must be set for model's provider | `Error: <KEY_NAME> environment variable is required for <Provider> models` |
+| `--gateway` | If provided, must be one of `auto`, `direct`, `openrouter` | `Error: --gateway must be one of: auto, direct, openrouter` |
+| API Key | The router must be able to resolve *some* usable key for the requested model (see below) | Reason sentence + fix hint, e.g. `No API key was found for this vendor via any gateway.` / `Add a provider key or an OpenRouter key.` |
 
 **API Key Requirements by Provider:**
 
-| Model Prefix | Required Env Var | Example |
-|--------------|------------------|---------|
-| `openrouter/...` | `OPENROUTER_API_KEY` | `export OPENROUTER_API_KEY=sk-or-...` |
-| `google/...` | `GOOGLE_GENERATIVE_AI_API_KEY` | `export GOOGLE_GENERATIVE_AI_API_KEY=...` |
-| `openai/...` | `OPENAI_API_KEY` | `export OPENAI_API_KEY=sk-...` |
-| `anthropic/...` | `ANTHROPIC_API_KEY` | `export ANTHROPIC_API_KEY=sk-ant-...` |
-| `deepseek/...` | `DEEPSEEK_API_KEY` | `export DEEPSEEK_API_KEY=...` |
+Bare canonical ids (`google/...`, `openai/...`, `anthropic/...`, `deepseek/...`) are policy-routed —
+the direct key for that vendor if configured, else `OPENROUTER_API_KEY` as fallback. Only
+`openrouter/...` (the explicit override) and gateway-only vendors (Qwen, Grok, Mistral, GLM, …)
+strictly require `OPENROUTER_API_KEY`:
+
+| Model Prefix | Env Var Amicus Will Use | Notes |
+|--------------|--------------------------|-------|
+| `openrouter/...` | `OPENROUTER_API_KEY` | Always required for this form |
+| `google/...` (bare) | `GOOGLE_GENERATIVE_AI_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+| `openai/...` (bare) | `OPENAI_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+| `anthropic/...` (bare) | `ANTHROPIC_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+| `deepseek/...` (bare) | `DEEPSEEK_API_KEY`, else `OPENROUTER_API_KEY` | Errors only if neither is set |
+
+`--gateway direct` narrows this to "the direct key specifically" (errors if only OpenRouter is
+configured); `--gateway openrouter` narrows it to `OPENROUTER_API_KEY` specifically.
 
 **Handling validation errors:**
 
@@ -310,8 +329,8 @@ amicus start --model gemini --prompt "Task" --agent Build
 # Fix: Provide a non-empty briefing
 amicus start --model gemini --prompt "Detailed task description"
 
-# Error: OPENROUTER_API_KEY environment variable is required
-# Fix: Set the API key for your provider
+# Error: No API key was found for this vendor via any gateway.
+# Fix: add a direct provider key or an OpenRouter key
 export OPENROUTER_API_KEY=sk-or-your-key
 amicus start --model gemini --prompt "Task"
 ```
@@ -325,10 +344,11 @@ amicus fanout --models "gemini,gpt,deepseek" --prompt-file ./briefing.md --json
 Runs the same prompt on every listed model in parallel (one shared engine server, headless),
 then prints ONE JSON wave document: `status` (`complete`|`partial`|`error`), `counts`, and
 `legs[]` where each leg's `summary` is that model's answer. Exit codes: 0 complete, 2 partial,
-1 error/aborted. Aliases and full `provider/model` IDs both work; duplicates are allowed
+1 error/aborted. Aliases and full `provider/model` IDs both work — bare canonical ids route
+direct-first, `openrouter/provider/model` forces OpenRouter; duplicates are allowed
 (distinct legs). `--wave-id <id>` pins leg IDs to `<id>-1..N`. Shared per-leg knobs: `--agent`,
 `--thinking`, `--timeout`, `--summary-length`, `--no-context`, `--context-*`, `--mcp*`,
-`--no-validate-model`, `--cwd`.
+`--no-validate-model`, `--gateway`, `--cwd`.
 
 ### Inspect the Model Catalog
 
@@ -386,7 +406,10 @@ Starts a **new** sidecar session that inherits the old session's conversation as
 - `--prompt`: New task description for the continuation
 
 **Optional:**
-- `--model <model>`: Override model (defaults to original session's model)
+- `--model <model>`: Override model (defaults to original session's model) — bare canonical ids
+  route direct-first; `openrouter/provider/model` forces OpenRouter
+- `--gateway <mode>`: Routing override for the new session (`auto`|`direct`|`openrouter`), same
+  semantics as `start`. Only meaningful when `--model` is also given
 - `--context-turns <N>`: Max turns from previous session to include (default: 50)
 - `--context-max-tokens <N>`: Max tokens for context (default: 80000)
 - `--no-ui`: Run in autonomous mode
@@ -427,7 +450,9 @@ Use short aliases (run `amicus models` to see the live catalog, and `amicus mode
 - `--model deepseek` -- DeepSeek
 - Omit `--model` entirely to use your configured default
 
-Full model strings also work: `--model openrouter/provider/model-id`
+Full model strings also work: `--model provider/model-id` (bare canonical, direct-first — e.g.
+`--model anthropic/claude-opus-4.8`) or `--model openrouter/provider/model-id` (explicit
+force-OpenRouter override).
 
 ### Verifying Model Names
 
@@ -891,8 +916,8 @@ echo $ANTHROPIC_API_KEY # For Anthropic models
 ### "401 Unauthorized" or authentication errors
 
 1. Verify you're using the correct model name format:
-   - OpenRouter models: `openrouter/provider/model`
-   - Direct API models: `provider/model`
+   - Bare canonical (policy-routed, direct-first): `provider/model`
+   - Explicit force-OpenRouter override: `openrouter/provider/model`
 
 2. Check your API key is valid and has credits
 
@@ -967,11 +992,14 @@ amicus start --model ... --prompt "..." --agent Explore
 amicus start --model ... --prompt "..." --agent MyCustomAgent
 ```
 
-**"Error: <KEY_NAME> environment variable is required for <Provider> models"**
+**"No API key was found for this vendor via any gateway." / "No API key is configured for this vendor's direct API."**
 
-The API key for the model's provider is not set:
+A bare canonical id needs *some* usable key for the vendor — either its direct key or
+`OPENROUTER_API_KEY` as a fallback. `--gateway direct` narrows that to "the direct key
+specifically" (fails if only OpenRouter is configured); `--gateway openrouter` narrows it to
+`OPENROUTER_API_KEY` specifically:
 ```bash
-# For OpenRouter models (openrouter/...)
+# OPENROUTER_API_KEY is the fallback for every direct-capable vendor
 export OPENROUTER_API_KEY=sk-or-your-key
 
 # For Google models (google/...)

package/src/cli-handlers-resume-continue.js

@@ -10,9 +10,10 @@
 
 'use strict';
 
-const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
+const { resolveLaunchModel } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { requireNoUiForJson, requireValidTaskId } = require('./utils/cli-preflight');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Handle 'amicus resume' command
@@ -70,11 +71,35 @@ async function handleContinue(args) {
 
   requireNoUiForJson(args, useJson);
 
-  // F5: an explicitly passed --model gets the same resolution+validation as start.
+  // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
+  // --gateway via validateStartArgs (cli.js) — continue never did, so a
+  // typo'd value silently fell through to resolveGatewayMode's pass-through
+  // instead of failing fast with a clear error. Checked unconditionally
+  // (not just when --model is also given) since --gateway alone is still a
+  // user-facing typo worth catching.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
+  }
+
+  // F5/#61 Task 7.3: an explicitly passed --model routes through the gateway
+  // router exactly like start (resolveLaunchModel), so --gateway / direct-first
+  // policy / structured route errors apply here too. The NO-`--model` case
+  // (inherit the prior session's model) is unchanged below — that IS the
+  // "preserve prior route" behavior: the prior concrete id is reused verbatim,
+  // never re-resolved.
+  // #61 Task 5.2 (best-effort provenance): stash the freshly-resolved
+  // gateway/resolutionVersion so the NEW session's metadata can record them.
+  // These stay undefined on the inherit-prior-model path (no fresh routing
+  // happened there), so the metadata writer simply omits them — the prior
+  // concrete model id being reused verbatim already prevents a silent gateway
+  // change for a continued session without a fresh --model.
+  let routeGateway;
+  let routeResolutionVersion;
   if (args.model !== undefined) {
-    const { model, alias } = resolveModelFromArgs(args);
+    const { model, gateway, provenance } = await resolveLaunchModel(args);
     args.model = model;
-    args.model = await validateFallbackModel(args, alias);
+    routeGateway = gateway;
+    routeResolutionVersion = provenance && provenance.resolutionVersion;
   }
 
   const { continueAmicus } = require('./index');
@@ -91,6 +116,8 @@ async function handleContinue(args) {
       headless: args['no-ui'],
       timeout: args.timeout,
       json: useJson,
+      gateway: routeGateway,
+      resolutionVersion: routeResolutionVersion,
     });
   } catch (err) {
     // Same rationale as handleResume above: continueSidecar/loadPreviousSession

package/src/cli-handlers-run.js

@@ -14,9 +14,10 @@
 
 const { validateStartArgs } = require('./cli');
 const { validateTaskId } = require('./utils/validators');
-const { resolveModelFromArgs, validateFallbackModel } = require('./utils/start-helpers');
+const { resolveLaunchModel } = require('./utils/start-helpers');
 const { failJson, ERROR_CODES } = require('./utils/error-doc');
 const { requireNoUiForJson } = require('./utils/cli-preflight');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Handle 'sidecar start' command
@@ -43,9 +44,8 @@ async function handleStart(args) {
     process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: 'Error: --max-cost must be a positive number' }));
   }
 
-  const { model, alias } = resolveModelFromArgs(args);
+  const { model, alias } = await resolveLaunchModel(args);
   args.model = model;
-  args.model = await validateFallbackModel(args, alias);
 
   // Normalize agent: --agent takes precedence, otherwise use --mode
   args.agent = args.agent || args.mode;
@@ -108,6 +108,14 @@ async function handleStart(args) {
 async function handleFanout(args) {
   const useJson = !!args.json;
 
+  // FIX 4 (#61 whole-branch review, cheap parity): handleStart validates
+  // --gateway via validateStartArgs (cli.js) — fanout never did, so a typo'd
+  // value silently fell through to resolveGatewayMode's pass-through instead
+  // of failing fast with a clear error.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    process.exit(failJson(useJson, { code: ERROR_CODES.BAD_ARGS, message: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` }));
+  }
+
   const { resolvePromptSource } = require('./utils/prompt-source');
   const promptRes = resolvePromptSource(args);
   if (promptRes.error) {
@@ -161,7 +169,7 @@ async function handleFanout(args) {
 
   // Direct require — the src/index.js public re-export is added later (Task 13)
   const { runFanout } = require('./sidecar/fanout');
-  const { loadConfig } = require('./utils/config');
+  const { loadConfig, resolveGatewayMode } = require('./utils/config');
   const cfg = loadConfig() || {};
   const { exitCode } = await runFanout({
     models: args.models,
@@ -187,6 +195,9 @@ async function handleFanout(args) {
     noMcp: args['no-mcp'],
     excludeMcp: args['exclude-mcp'],
     noValidateModel: args['no-validate-model'],
+    // #61 Task 7.3: --gateway merged with routing.prefer, applied per leg
+    // by validateFanoutModels' router call.
+    gatewayMode: resolveGatewayMode(args.gateway),
     json: !!args.json,
     client: args.client,
     maxCost: args['max-cost'] !== null && args['max-cost'] !== undefined ? args['max-cost'] : cfg.maxCost,

package/src/cli.js

@@ -18,6 +18,7 @@ const {
 } = require('./utils/validators');
 const { resolvePromptSource } = require('./utils/prompt-source');
 const { logger } = require('./utils/logger');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /**
  * Default values per spec §4.1
@@ -245,6 +246,15 @@ function validateStartArgs(args) {
     }
   }
 
+  // Validate --gateway (if provided) — #61 Task 7.1. resolveGatewayMode()
+  // already treats any non-'direct'/'openrouter' string as a pass-through
+  // (effectively silent auto fallback), so this pre-flight check exists
+  // purely to catch typos with a clear error instead of letting them slip
+  // through unnoticed.
+  if (args.gateway !== undefined && !GATEWAY_MODES.includes(args.gateway)) {
+    return { valid: false, error: `Error: --gateway must be one of: ${GATEWAY_MODES.join(', ')}` };
+  }
+
   // Validate MCP spec format (if provided)
   const mcpCheck = validateMcpSpec(args.mcp);
   if (!mcpCheck.valid) {
@@ -401,6 +411,7 @@ Options for 'start':
   --exclude-mcp <name>           Exclude specific MCP server (repeatable)
   --validate-model             (Deprecated: validation is on by default)
   --no-validate-model          Skip model-catalog validation before launch
+  --gateway <mode>             Routing: auto (direct-first), direct, or openrouter
   --position <pos>             Window position: right (default), left, center
 `,
   fanout: `
@@ -415,6 +426,7 @@ Options for 'fanout':
   --json                       Emit the wave result as stable JSON on stdout
   --max-cost <$>               Refuse the wave if the estimated total exceeds $ (soft ceiling)
   --no-cost-gate               Disable the budget gate (per-$/Mtok threshold + ceiling) for this run
+  --gateway <mode>              Routing: auto (direct-first), direct, or openrouter
   Shared per-leg knobs: --agent, --thinking, --timeout, --summary-length,
   --no-context, --context-*, --mcp*, --no-validate-model, --cwd
   Exit codes: 0 all legs complete, 2 partial, 1 none complete / hard failure
@@ -456,6 +468,7 @@ Options for 'continue':
   <task_id>                    Required. Session to build on (positional)
   --prompt <text>              Required. Briefing for the new session
   --model <model>              Optional. Override the model (alias or provider/model)
+  --gateway <mode>             Routing when --model is given: auto (direct-first), direct, or openrouter
   --cwd <path>                 Project directory (default: cwd)
   --no-ui                      Run without GUI (autonomous mode)
   --json                       With --no-ui: emit the run result as stable JSON

package/src/mcp-server.js

@@ -4,7 +4,6 @@ const path = require('path');
 const { writeFileAtomic } = require('./utils/atomic-write');
 const { spawn } = require('child_process');
 const { getTools, getGuideText } = require('./mcp-tools');
-const { tryResolveModel } = require('./utils/config');
 const os = require('os');
 const { logger } = require('./utils/logger');
 const { safeSessionDir } = require('./utils/validators');
@@ -241,7 +240,7 @@ function spawnSidecarProcess(args, sessionDir) {
 /** Tool handler implementations */
 const handlers = {
   async amicus_start(input, project, mcpServer) {
-    // Validate all inputs before any session creation
+    // Validate non-model inputs (prompt/timeout/agent) before any session creation.
     const { validateStartInputs } = require('./utils/input-validators');
     const validation = validateStartInputs(input);
     if (!validation.valid) {
@@ -250,7 +249,40 @@ const handlers = {
         content: [{ type: 'text', text: JSON.stringify(validation.error) }],
       };
     }
-    const resolvedModel = validation.resolvedModel;
+
+    // Model routing (#61 Task 6.2): route through the gateway router for MCP
+    // parity with the CLI's resolveLaunchModel (start-helpers.js). Unlike the
+    // CLI, this handler must never process.exit — the MCP server is long-lived
+    // and serves many tool calls — so a routing failure returns a structured
+    // model_route_error response instead.
+    //
+    // Default resolution mirrors resolveLaunchModel: an omitted input.model
+    // falls back to the configured default before hitting the router, so
+    // "no model, no default" produces a clean invalid_descriptor structured
+    // error (via the router) rather than a crash. Shared with the CLI's
+    // resolveLaunchModel (start-helpers.js) via model-input-default.js.
+    const { resolveGatewayMode } = require('./utils/config');
+    const { resolveRouteForLaunch } = require('./utils/route-launch');
+    const { toStructuredError } = require('./utils/route-error');
+    const { resolveModelInputOrDefault } = require('./utils/model-input-default');
+
+    const modelInput = resolveModelInputOrDefault(input.model);
+    // input.gateway is now exposed by the MCP tool schema (#61 Task 7.2);
+    // resolveGatewayMode(undefined) falls back to config routing.prefer / 'auto'.
+    const routeResult = await resolveRouteForLaunch({
+      model: modelInput,
+      gatewayMode: resolveGatewayMode(input.gateway),
+      source: 'mcp',
+      allowSelection: false,
+      validateModel: true,
+    });
+    if (routeResult.kind !== 'resolved') {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify(toStructuredError(routeResult)) }],
+      };
+    }
+    const resolvedModel = routeResult.executableId;
 
     const cwd = project || getProjectDir(input.project);
     const { generateTaskId } = require('./sidecar/start');
@@ -268,7 +300,9 @@ const handlers = {
     const briefingPath = path.join(sessionDir, 'briefing.md');
     const detectedClient = detectClient(mcpServer);
     const args = ['start', '--prompt-file', briefingPath, '--task-id', taskId, '--client', detectedClient];
-    if (resolvedModel) { args.push('--model', resolvedModel); }
+    // resolvedModel is always defined here — a routing failure already
+    // returned above — and is the router's executableId, not the raw alias.
+    args.push('--model', resolvedModel);
     const agent = (input.noUi && (!input.agent || input.agent.toLowerCase() === 'chat'))
       ? 'build' : input.agent;
     if (agent) { args.push('--agent', agent); }
@@ -296,7 +330,8 @@ const handlers = {
         const { runHeadless } = require('./headless');
         const { generateFoldNonce } = require('./utils/fold-marker');
         const { finalizeHeadlessResult } = require('./sidecar/session-finalize');
-        // resolvedModel is already available from validateStartInputs() above
+        // resolvedModel (the router's executableId) is already available from
+        // the model-routing step above
 
         // #47: the shared OpenCode server is shared across projects, so the
         // session must be created scoped to the resolved project directory
@@ -441,7 +476,15 @@ const handlers = {
           taskId, status: 'running', mode: 'headless',
           message: 'Amicus started in headless mode. Use amicus_status to check progress.',
         });
-        return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
+        // FIX 2 (#61 whole-branch review): surface the router's one-shot
+        // migration notice here too — resolveRouteForLaunch already burned
+        // the migration_notified flag for this vendor when it built
+        // routeResult above, so this is the only chance to show it on the
+        // shared-server path (no CLI stderr exists for an MCP caller).
+        const sharedServerContent = [{ type: 'text', text: body }];
+        if (routeResult.notice) { sharedServerContent.push({ type: 'text', text: routeResult.notice }); }
+        sharedServerContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
+        return { content: sharedServerContent };
       } catch (err) {
         logger.warn('Shared server path failed, falling back to spawn', { error: err.message });
         // Clean up partial shared server state before falling through
@@ -490,10 +533,16 @@ const handlers = {
         'Then wait for the user to tell you. Use amicus_read to get results once they confirm.';
 
     const body = JSON.stringify({ taskId, status: 'running', mode, message });
+    // FIX 2 (#61 whole-branch review): the spawn path never touches stderr of
+    // the CLI child that will do the routing print — this handler already
+    // resolved the route in-process above, so surface its notice here.
+    const spawnContent = [{ type: 'text', text: body }];
+    if (routeResult.notice) { spawnContent.push({ type: 'text', text: routeResult.notice }); }
     if (isHeadless) {
-      return { content: [{ type: 'text', text: body }, { type: 'text', text: HEADLESS_START_REMINDER }] };
+      spawnContent.push({ type: 'text', text: HEADLESS_START_REMINDER });
+      return { content: spawnContent };
     }
-    return textResult(body);
+    return { content: spawnContent };
   },
 
   async amicus_status(input, project) {
@@ -795,11 +844,37 @@ const handlers = {
   },
 
   async amicus_continue(input, project, mcpServer) {
+    // Model routing parity with amicus_start (#61 whole-branch review FIX 3,
+    // Task 6.2 follow-up): an explicit --model on continue used to be
+    // pre-checked only with the legacy tryResolveModel (alias-existence-only),
+    // so an unroutable model (e.g. a gateway-only vendor with no OpenRouter
+    // key) spawned a child that then died opaquely trying to launch it.
+    // Route it through the SAME gateway router amicus_start uses instead, and
+    // return the same structured model_route_error on failure — never spawn.
+    // The no-`--model` inherit-prior-session-model path is UNCHANGED: nothing
+    // below runs, and handleContinue reuses the prior concrete model verbatim.
+    let resolvedModel;
     if (input.model) {
-      const modelCheck = tryResolveModel(input.model);
-      if (modelCheck.error) {
-        return textResult(modelCheck.error, true);
+      const { resolveGatewayMode } = require('./utils/config');
+      const { resolveRouteForLaunch } = require('./utils/route-launch');
+      const { toStructuredError } = require('./utils/route-error');
+      const { resolveModelInputOrDefault } = require('./utils/model-input-default');
+
+      const modelInput = resolveModelInputOrDefault(input.model);
+      const routeResult = await resolveRouteForLaunch({
+        model: modelInput,
+        gatewayMode: resolveGatewayMode(input.gateway),
+        source: 'mcp',
+        allowSelection: false,
+        validateModel: true,
+      });
+      if (routeResult.kind !== 'resolved') {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify(toStructuredError(routeResult)) }],
+        };
       }
+      resolvedModel = routeResult.executableId;
     }
 
     const cwd = project || getProjectDir(input.project);
@@ -814,7 +889,15 @@ const handlers = {
     const briefingPath = path.join(sessionDir, 'briefing.md');
     const args = ['continue', input.taskId, '--prompt-file', briefingPath,
       '--task-id', newTaskId, '--client', detectClient(mcpServer), '--cwd', cwd];
-    if (input.model) { args.push('--model', input.model); }
+    // resolvedModel is the router's executableId (never the raw alias) — a
+    // routing failure already returned above, so this is only reached when
+    // input.model was absent (resolvedModel stays undefined) or resolved.
+    if (resolvedModel) { args.push('--model', resolvedModel); }
+    // #61 Task 7.3: forward the caller's gateway preference to the spawned
+    // CLI child too — handleContinue still does its OWN routing (it's the
+    // one wiring --model/--gateway into a resolved session), this just keeps
+    // the child's own resolution consistent with what was already decided.
+    if (input.gateway) { args.push('--gateway', input.gateway); }
     if (input.noUi) { args.push('--no-ui', '--agent', 'build'); }
     if (input.timeout) { args.push('--timeout', String(input.timeout)); }
     if (input.contextTurns)     { args.push('--context-turns', String(input.contextTurns)); }
@@ -955,6 +1038,10 @@ const handlers = {
     ];
     const agent = input.agent || 'Build';
     args.push('--agent', agent);
+    // #61 Task 7.3: forward the caller's gateway preference to the spawned
+    // CLI child, which routes each leg's model (piece 2) — unlike
+    // amicus_start, this handler never resolves any leg's route itself.
+    if (input.gateway) { args.push('--gateway', input.gateway); }
     if (input.thinking)      { args.push('--thinking', input.thinking); }
     if (input.timeout)       { args.push('--timeout', String(input.timeout)); }
     if (input.summaryLength) { args.push('--summary-length', input.summaryLength); }

package/src/mcp-tools.js

@@ -10,6 +10,7 @@
 const { z } = require('zod');
 const { formatAliasNames } = require('./utils/config');
 const { READ_CAP_BYTES } = require('./utils/read-slice');
+const { GATEWAY_MODES } = require('./utils/model-descriptor');
 
 /** Zod pattern for safe task IDs (alphanumeric, hyphens, underscores only) */
 const safeTaskId = z.string().regex(
@@ -55,9 +56,15 @@ function getTools() {
       ' Pass includeContext: false when the briefing is fully self-contained.',
     inputSchema: {
       model: safeModel.optional().describe(
-        `Short alias (${aliasNames}) or full provider/model ID. ` +
+        `Short alias (${aliasNames}) or full model ID ` +
+        '(bare provider/model is canonical and routes direct-first, e.g. anthropic/claude-opus-4.8; ' +
+        'openrouter/provider/model forces OpenRouter). ' +
         'If omitted, uses the configured default. Call amicus_guide to see all aliases.'
       ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (direct-first, default), direct (require a ' +
+        'direct provider key), or openrouter (force OpenRouter).'
+      ),
       prompt: z.string().describe(
         'Detailed task briefing. Include: objective, background, ' +
         'files of interest, success criteria.'
@@ -251,7 +258,13 @@ function getTools() {
         'New task description for the continuation.'
       ),
       model: safeModel.optional().describe(
-        `Override model — short alias (${aliasNames}) or full provider/model ID. Defaults to the original session's model.`
+        `Override model — short alias (${aliasNames}) or full model ID. Bare provider/model routes ` +
+        'direct-first (canonical); openrouter/provider/model forces OpenRouter. Defaults to the ' +
+        "original session's model."
+      ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (direct-first, default), direct (require a ' +
+        'direct provider key), or openrouter (force OpenRouter).'
       ),
       noUi: z.boolean().optional().default(false).describe(
         'Run headless. Default false (opens Electron window).'
@@ -308,13 +321,19 @@ function getTools() {
       'inside). Each leg is also an ordinary session readable by taskId.',
     inputSchema: {
       models: z.array(safeModel).min(1).max(10).optional().describe(
-        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
+        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full model IDs — ` +
+        'bare provider/model routes direct-first (canonical), openrouter/provider/model forces ' +
+        "OpenRouter. Duplicates allowed. Omit when using 'council'."
       ),
       council: z.string().optional().describe(
         "Run a saved council, or a built-in bench ('free', 'budget', 'frontier'), instead of 'models'. " +
         "Expands to the council's members; a saved council of the same name shadows a built-in. " +
         'Mutually exclusive with \'models\'.'
       ),
+      gateway: z.enum(GATEWAY_MODES).optional().describe(
+        'Routing preference: auto (direct-first, default), direct (require a ' +
+        'direct provider key), or openrouter (force OpenRouter).'
+      ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'
       ),
@@ -492,7 +511,10 @@ Include: Objective, Background, Files of interest, Success criteria, Constraints
 |-------|-------|
 ${aliasRows}
 
-Or use full IDs in provider/model format (e.g., openrouter/provider/model-id).
+Or use a full model ID. Bare \`provider/model\` (e.g. anthropic/claude-opus-4.8) is the canonical,
+policy-routed form — it routes direct-first (your direct provider key if configured, else
+OpenRouter). \`openrouter/provider/model\` is an explicit override that forces OpenRouter. The
+\`gateway\` param (or \`routing.prefer\` in config.json) controls this per call or globally.
 Run amicus_setup to configure defaults and add custom aliases.
 
 ## Session Matching