model-selection

name

model-selection

description

Required reading before invoking another goose recipe via shell (`goose run --recipe ...`). Tells you exactly which environment variable to set for each model role on each provider. Goose's `--model` flag and `GOOSE_MODEL` env var DO NOT actually select the model for ACP providers — only the substrate-native overrides documented here work. Load this skill any time you are about to spawn a `goose run` subprocess.

Model Selection for goose run subprocess invocations

Why this skill exists

Goose's session banner LIES about which model is actually serving an ACP provider. Setting --model X or GOOSE_MODEL=X echoes into the banner but does not change the model that actually runs. Verified 2026-04-26 against claude-acp (every --model <anything> returned the same substrate default model).

To actually select the model for claude-acp or codex-acp, use the substrate-native env vars below. Bad model IDs fail loudly with a clean error — that's the right basis for retry-on-failure.

The role-to-env-var map

This project uses three model roles. Each role maps to a different model per provider.

Role	Provider	Env var(s) to set on the spawning shell
top-model	claude-acp	ANTHROPIC_MODEL=claude-opus-4-7
top-model	codex-acp	CODEX_HOME=$HOME/.codex-homes/gpt-5.5
top-model	openrouter	OPENROUTER_API_KEY=<key> + GOOSE_MODEL=moonshotai/kimi-k2.6
fallback-model	claude-acp	ANTHROPIC_MODEL=claude-sonnet-4-6
fallback-model	codex-acp	CODEX_HOME=$HOME/.codex-homes/gpt-5.4
fallback-model	openrouter	OPENROUTER_API_KEY=<key> + GOOSE_MODEL=qwen/qwen3-coder
fast-model	claude-acp	ANTHROPIC_MODEL=claude-haiku-4-5-20251001
fast-model	codex-acp	(no fast tier yet — fall back to fallback-model)
fast-model	openrouter	OPENROUTER_API_KEY=<key> + GOOSE_MODEL=google/gemini-2.5-flash

$HOME resolves to the user's home (e.g., C:/Users/Doni.Lerner on this machine). Use the absolute path in actual shell invocations.

For OpenRouter, <key> is the contents of an OpenRouter API key file (NOT the path). On this machine the file is at ~/AI Projects/.secrets/openrouter-goose-test.key; in the Docker harness the bash launcher reads that file and forwards the contents via docker run -e OPENROUTER_API_KEY=....

Command shape

Claude leaves:

ANTHROPIC_MODEL=<id-from-table> goose run --recipe <path> --provider claude-acp [--params k=v ...]

Codex leaves:

CODEX_HOME=<path-from-table> goose run --recipe <path> --provider codex-acp [--params k=v ...]

OpenRouter:

OPENROUTER_API_KEY=<key> GOOSE_MODEL=<id-from-table> goose run --recipe <path> --provider openrouter [--params k=v ...]

For ACP providers, no --model flag and no GOOSE_MODEL env var — the substrate reads the env vars above directly. For OpenRouter, GOOSE_MODEL IS the active knob (Goose's native provider path), and OPENROUTER_API_KEY is required for auth. Recipes invoked via OpenRouter must declare - type: platform; name: skills in their extensions: block (LEARNINGS.md 2026-04-28); ACP providers ignore that declaration.

Failure modes and how to detect them

Symptom	Mechanism	What to do
Bad ANTHROPIC_MODEL	exit ≠ 0, stderr: "There's an issue with the selected model …"	Pick a different role from the table; retry
Bad CODEX_HOME path / missing auth.json	exit ≠ 0, stderr: "Authentication required"	Stop and report — setup problem, not a model problem
Bad GOOSE_MODEL on openrouter	exit ≠ 0, stderr usually contains "model not found" or HTTP 4xx from OpenRouter	Pick a different role from the table; retry
Missing OPENROUTER_API_KEY	exit ≠ 0, stderr: "OPENROUTER_API_KEY not set" or HTTP 401	Stop and report — setup problem, not a model problem
Rate limit	exit ≠ 0, stderr contains "rate limit" / "429" / "quota exceeded"	Wait 5 min, retry same model up to 2 times, then escalate to a different role
Silent degenerate output (exit 0, but content is empty / mismatched / "I already did this")	No exit-code signal	Validate output content (minimum length, required markers); treat as failure if validation fails

Verification when correctness matters

Goose's banner (● new session · <provider> <model>) is unreliable for ACP providers. To verify which model actually ran, ask the model to self-identify in the response — model self-IDs are reliable when the prompt is explicit ("State your exact model ID, not just the family name").

Setup (per machine, per collaborator)

The codex homes referenced above must exist on the machine running goose:

• ~/.codex-homes/gpt-5.5/ (top-model on codex)
• ~/.codex-homes/gpt-5.4/ (fallback-model on codex)

Each contains auth.json (copied from ~/.codex/auth.json) and config.toml with model = "<name>". Setup is per-machine — see project LEARNINGS.md for the one-time setup steps.

Notes for adding a new role or model

• New role: add a row to the table above. Roles are intentionally task-shaped (top / fallback / fast), not model-named, so model upgrades don't ripple into recipe changes.
• New claude model: just edit the env var value in this skill.
• New codex model: create a new codex home (mkdir, copy auth.json, write config.toml), then point the role at it here.
• New openrouter model: edit the GOOSE_MODEL=<id> value here. The id is the OpenRouter model slug (e.g., google/gemini-2.5-flash). The Docker harness's model_resolver.py mirrors this table — update both in the same change.

Source for these claims

Verified 2026-04-26 via sterile-CWD tests: --model fake-model-99-doesnt-exist against claude-acp returned a successful run with the substrate default model (banner lies). ANTHROPIC_MODEL=claude-opus-4-7 returned an Opus 4 self-ID with opus-style output. ANTHROPIC_MODEL=claude-haiku-4-5-20251001 returned Haiku 4.5 self-ID. ANTHROPIC_MODEL=fake-name failed loudly. CODEX_HOME swap verified for both gpt-5.5 and gpt-5.4 homes. Full details in docs/goose-provider-model-semantics.md and LEARNINGS.md (2026-04-26).