fix(llm): default to claude-opus-5-5 from one owner; keep claude-opus-5 on the ladder

.env.template

@@ -91,7 +91,7 @@ OPENAI_API_KEY=ak-your-api-key-here
 # CODEX_MODEL=your-gateway-kernel-model
 #
 # Uncomment to restore the strict AMD Claude allowlist
-# (opus-5 / 4-8 / 4-7 / 4-6) and refuse to start when the catalog is unreachable.
+# (opus-5-5 / 5 / 4-8 / 4-7 / 4-6) and refuse to start when the catalog is unreachable.
 # INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0
 
 # --- GEAK / kernel-agent model (GEAKv4 Claude Code workflow) ----------------

docs/install/install.md

@@ -73,7 +73,7 @@ It asks for these values with a fixed option order:
    - `Use AMD gateway (https://llm-api.amd.com/anthropic)`
    - `Custom`
 2. Model:
-   - `Use default (claude-opus-5)`
+   - `Use default (claude-opus-5-5)`
    - `Custom`
 3. Secrets:
    - Setup writes placeholders in `.env`.
@@ -209,7 +209,7 @@ LLM defaults:
 
 | Mode | Required secret | Default base URL | Default model |
 |------|-----------------|------------------|---------------|
-| Anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com` | `CLAUDE_MODEL=claude-opus-5` |
+| Anthropic | `ANTHROPIC_API_KEY` | `https://api.anthropic.com` | `CLAUDE_MODEL=claude-opus-5-5` |
 
 Setup creates or updates `.env` in the current workspace and writes the resolved
 values there. Setup asks for the Anthropic side only; to run on Codex, add
@@ -347,7 +347,7 @@ paste API keys into chat.
 cat > .env <<'EOF'
 ANTHROPIC_API_KEY=<PLEASE_FILL_IN>
 ANTHROPIC_BASE_URL=https://api.anthropic.com
-CLAUDE_MODEL=claude-opus-5
+CLAUDE_MODEL=claude-opus-5-5
 # Writable artifact root for runtime files, dependency checkouts, logs,
 # optimizer runs, and generated env files. Set an absolute path you own.
 USER_DATA_PATH=<PLEASE_FILL_IN>

docs/install/slurm.md

@@ -228,9 +228,9 @@ optimization. Model names must exist in your key's catalog:
 
 | Use | Environment variable | Allowed values | Notes |
 |---|---|---|---|
-| Orchestration | `CLAUDE_MODEL` / `LLM_MODEL` | Any model in the gateway catalog; `claude-opus-5` preferred, with `claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6` as the AMD allowlist fallbacks | Validated against your gateway's `/models` catalog. |
-| GEAK (kernel optimization subprocess) | `GEAK_CLAUDE_MODEL` | For example `claude-opus-5` | Defaults from `CLAUDE_MODEL`; set explicitly only when GEAK should use a different model. |
-| Forge (fusion / rewrite) | `CLAUDE_MODEL` / `CODEX_MODEL` | For example `claude-opus-5` / `gpt-5.6-sol` | Forge reads the platform variable for the backend it is on; it has no model variable of its own. |
+| Orchestration | `CLAUDE_MODEL` / `LLM_MODEL` | Any model in the gateway catalog; `claude-opus-5-5` preferred, with `claude-opus-5` / `claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6` as the AMD allowlist fallbacks | Validated against your gateway's `/models` catalog. |
+| GEAK (kernel optimization subprocess) | `GEAK_CLAUDE_MODEL` | For example `claude-opus-5-5` | Defaults from `CLAUDE_MODEL`; set explicitly only when GEAK should use a different model. |
+| Forge (fusion / rewrite) | `CLAUDE_MODEL` / `CODEX_MODEL` | For example `claude-opus-5-5` / `gpt-5.6-sol` | Forge reads the platform variable for the backend it is on; it has no model variable of its own. |
 
 - Do *not* append effort/thinking suffixes (for example
   `claude-opus-4-7-thinking-xhigh`); the gateway returns `Invalid model name`
@@ -269,7 +269,7 @@ The following items address common Slurm job and cluster configuration problems.
 - `CERTIFICATE_VERIFY_FAILED: unable to get local issuer` (huggingface/github): The CA bundle has only the internal cert. Use a combined CA bundle.
 - `ModuleNotFoundError: No module named '...cli'`: The source snapshot is incomplete or an old layout. Stage a complete src-layout checkout (`src/hyperloom/...`).
 - `--gpu-type: invalid choice: 'MI355X'`: The CLI is case-sensitive. Use lowercase (for example `mi355x`; `submit-vultr.sh` already does).
-- `--claude-model=... is not allowed`: The strict AMD allowlist is in force (`INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0`). Use `claude-opus-5` for orchestration, or unset the variable to validate against the gateway catalog instead.
+- `--claude-model=... is not allowed`: The strict AMD allowlist is in force (`INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0`). Use an allowlisted id (`claude-opus-5-5` first, then `claude-opus-5`) for orchestration, or unset the variable to validate against the gateway catalog instead.
 - `Invalid model name` / `401 missing subscription key`: The model name is not in the key catalog (often a suffixed variant). Use a name from `curl $OPENAI_BASE_URL/models`.
 - Server fails to start / OOM in shm: `/dev/shm` is too small. Raise `HL_SHM_SIZE` (default `64g`).
 - DNS failure / connection timeout to the gateway: The host alias was not applied. The docker path uses `--add-host`; confirm the node can reach the jump host on `:443`.

docs/reference/authentication.md

@@ -193,8 +193,8 @@ export CODEX_MODEL=your-gateway-kernel-model
 
 Custom orchestration models are allowed by default: preflight validates the
 chosen `CLAUDE_MODEL` against your gateway's `/models` catalog. To restore the
-stricter AMD Claude allowlist (`claude-opus-5` preferred, `claude-opus-4-8` /
-`claude-opus-4-7` / `claude-opus-4-6` fallback), set
+stricter AMD Claude allowlist (`claude-opus-5-5` preferred, `claude-opus-5` /
+`claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6` fallback), set
 `INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0`.
 
 A gateway that exposes no `/models` route cannot be probed; preflight warns and

examples/README.md

@@ -77,7 +77,7 @@ It asks for these values with a fixed option order:
    - If `.env` already exists, setup preserves unrelated keys but updates the
      Hyperloom setup keys selected in this run.
 3. Model, asked alongside the non-secret values:
-   - `Use default (claude-opus-5)`
+   - `Use default (claude-opus-5-5)`
    - `Custom`
 4. `USER_DATA_PATH`:
    - Default: `<workspace>/session`

src/hyperloom/agents/quantization/driver/runner.py

@@ -12,9 +12,10 @@
 from typing import Any, Awaitable, Callable, Iterable
 
 from hyperloom.common.llm_attribution import sdk_env_overlay
+from hyperloom.common.llm_config import DEFAULT_CLAUDE_MODEL
 
 
-DEFAULT_MODEL = "claude-opus-5"
+DEFAULT_MODEL = DEFAULT_CLAUDE_MODEL
 DEFAULT_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash"]
 DEFAULT_MAX_TURNS = 240  # Quark workflow has 4 STOPs + validator + eval
 

src/hyperloom/common/llm_config.py

@@ -163,7 +163,7 @@ def with_synthesized_anthropic_keys(env: Mapping[str, str]) -> dict[str, str]:
 
 # The model each backend runs when neither the operator nor a known gateway host names one. This is the last rung of
 # every model ladder in both packages, so it lives beside the backend names it is keyed by.
-DEFAULT_CLAUDE_MODEL = "claude-opus-5"
+DEFAULT_CLAUDE_MODEL = "claude-opus-5-5"
 # The gateway publishes both ``gpt-5.6`` and ``gpt-5.6-sol`` in ``/v1/models``, but only the latter has a deployment
 # behind it: a bare ``gpt-5.6`` answers 400 "Deployment ... is not found" on both ChatCompletions and Responses.
 DEFAULT_CODEX_MODEL = "gpt-5.6-sol"

src/hyperloom/inference_optimizer/SKILL.md

@@ -859,8 +859,8 @@ auto-`pip install` the SDKs / `ray` / `Magpie` /
 canonical `Preflight diagnostics:` block (paste verbatim into status
 reports). Two checks **abort** the run on failure: the model gate
 (probed against `<OPENAI_BASE_URL>/models`; the allowlist
-{`claude-opus-5` preferred, `claude-opus-4-8`, `claude-opus-4-7`,
-`claude-opus-4-6` fallback}
+{`claude-opus-5-5` preferred, `claude-opus-5`, `claude-opus-4-8`,
+`claude-opus-4-7`, `claude-opus-4-6` fallback}
 binds only under `INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0` — otherwise
 the catalog probe is the sole gate; see
 `## Failure Handling`) and, when `--critic-agent` is active, the
@@ -1639,7 +1639,7 @@ Transient SDK errors retry/resume up to the Coordinator emergency threshold.
 Custom orchestration models are enabled by default and are validated against the
 configured gateway catalog. Set `INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0`
 only when you intentionally want the strict AMD Claude allowlist
-(`claude-opus-5` / `claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6`).
+(`claude-opus-5-5` / `claude-opus-5` / `claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6`).
 
 | Symptom | Fix |
 |---|---|

src/hyperloom/inference_optimizer/assets/install_kernel_tools.sh

@@ -179,7 +179,7 @@ if [ -z "${GEAK_ROOT:-}" ]; then
   GEAK_ROOT="${_open_source_root}/GEAK@${_GEAK_SHA}"
 fi
 GEAK_E2E_RUNNER="${GEAK_E2E_RUNNER:-${GEAK_ROOT}/interface/run_e2e.py}"
-GEAK_CLAUDE_MODEL_VAL="${GEAK_CLAUDE_MODEL:-${CLAUDE_MODEL:-claude-opus-5}}"
+GEAK_CLAUDE_MODEL_VAL="${GEAK_CLAUDE_MODEL:-${CLAUDE_MODEL:-claude-opus-5-5}}"
 # Run mode for the GEAKv4 Claude Code workflow. ``full`` (default) selects the
 # 2 h / 5-round preset; ``quick`` selects the 1 h / 2-round smoke-test preset.
 # GEAK still honours later CLI ``--mode`` or LLM-parsed task-hint overrides.

src/hyperloom/inference_optimizer/assets/slurm/proxy.env.template

@@ -42,8 +42,8 @@ HL_CA_BUNDLE_CONTAINER=/etc/ssl/amd/amd-ca.pem
 #     (list them with: curl $OPENAI_BASE_URL/models). Do NOT use *-thinking-xhigh
 #     variants unless the gateway lists them.
 #     IMPORTANT: the orchestration model (--claude-model / $CLAUDE_MODEL) is
-#     hard-allowlisted by the optimizer to claude-opus-5 (preferred), then
-#     claude-opus-4-8, claude-opus-4-7, claude-opus-4-6 -- preflight walks that
+#     hard-allowlisted by the optimizer to claude-opus-5-5 (preferred), then
+#     claude-opus-5, claude-opus-4-8, claude-opus-4-7, claude-opus-4-6 -- preflight walks that
 #     ladder and takes the newest id your gateway actually serves.
 #     GEAK_CLAUDE_MODEL gets no such treatment: GEAKv4 uses Claude Code against
 #     GEAK_BASE_URL, which may be a different (and older) endpoint, and an

src/hyperloom/inference_optimizer/breakdown/reporters/llm_client.py

@@ -41,7 +41,7 @@ class OpenAIHttpClient:
     """OpenAI-compatible chat-completions client for the narrative pass."""
 
     client: Any
-    model: str = "claude-opus-5"
+    model: str = llm_config.DEFAULT_CLAUDE_MODEL
     max_output_tokens: int = 1024
 
     def complete(self, *, system: str, user: str) -> str:
@@ -64,7 +64,7 @@ def complete(self, *, system: str, user: str) -> str:
 class AnthropicClient:
     """Anthropic client for the narrative pass."""
 
-    model: str = "claude-opus-5"
+    model: str = llm_config.DEFAULT_CLAUDE_MODEL
     max_output_tokens: int = 1024
     timeout: Any = None
     timeout_s: float = REPORT_HTTP_TIMEOUT_SEC
@@ -88,7 +88,7 @@ def build_client_from_env() -> Any | None:
     backend = (os.environ.get("HYPERLOOM_REPORT_LLM_BACKEND") or "none").lower()
     if backend in ("", "none", "off", "disabled"):
         return None
-    model = os.environ.get("HYPERLOOM_REPORT_MODEL") or "claude-opus-5"
+    model = os.environ.get("HYPERLOOM_REPORT_MODEL") or llm_config.DEFAULT_CLAUDE_MODEL
     try:
         max_tokens = int(os.environ.get("HYPERLOOM_REPORT_MAX_TOKENS") or "1024")
     except ValueError:

src/hyperloom/inference_optimizer/cli/credentials.py

@@ -30,6 +30,7 @@
 # gateway actually serves, so the order is the fallback ladder.
 _CLAUDE_ALLOWED_MODELS = (
     DEFAULT_CLAUDE_MODEL,
+    "claude-opus-5",
     "claude-opus-4-8",
     "claude-opus-4-7",
     "claude-opus-4-6",

src/hyperloom/inference_optimizer/cli/parser.py

@@ -931,8 +931,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "gates; rater identities are anonymized in the orchestration "
         "prompt). Only takes effect when --proposal-scoring is also "
         "passed (scoring is OFF by default); this flag alone does not "
-        "enable scoring. Default 'claude-opus-5,gpt-5.6-sol,"
-        "dvue-aoai-005-Kimi-K2.6,gemini/gemini-3.1-pro-preview'. "
+        "enable scoring. Default '%(default)s'. "
         "Add a model by appending its slug. Empty list disables scoring "
         "even when enabled.",
     )

src/hyperloom/inference_optimizer/references/troubleshooting.md

@@ -57,7 +57,7 @@ Transient SDK errors retry/resume up to the Coordinator emergency threshold.
 Custom orchestration models are enabled by default and are validated against the
 configured gateway catalog. Set `INFERENCE_OPTIMIZER_ALLOW_CUSTOM_ORCH_MODEL=0`
 only when you intentionally want the strict AMD Claude allowlist
-(`claude-opus-5` / `claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6`).
+(`claude-opus-5-5` / `claude-opus-5` / `claude-opus-4-8` / `claude-opus-4-7` / `claude-opus-4-6`).
 
 | Symptom | Fix |
 |---|---|

src/hyperloom/inference_optimizer/tests/test_agent_roles_and_policy.py

@@ -34,12 +34,13 @@
 
 
 # agent_role
-def test_default_claude_model_is_opus_5():
+def test_default_claude_model_is_opus_5_5():
     """The allowlist ladder is headed by the default, and the older rungs are the fallback order."""
     from hyperloom.inference_optimizer.cli.credentials import _CLAUDE_ALLOWED_MODELS
 
-    assert DEFAULT_CLAUDE_MODEL == "claude-opus-5"
+    assert DEFAULT_CLAUDE_MODEL == "claude-opus-5-5"
     assert _CLAUDE_ALLOWED_MODELS == (
+        "claude-opus-5-5",
         "claude-opus-5",
         "claude-opus-4-8",
         "claude-opus-4-7",

src/hyperloom/inference_optimizer/tests/test_proposal_scorer.py

@@ -318,7 +318,7 @@ def test_extract_scores_json_bare_and_fenced():
 
 def test_default_models_constant():
     assert DEFAULT_SCORER_MODELS == (
-        "claude-opus-5",
+        "claude-opus-5-5",
         "gpt-5.6-sol",
         "dvue-aoai-005-Kimi-K2.6",
         "gemini/gemini-3.1-pro-preview",

src/hyperloom/inference_optimizer/tests/test_reporters_llm_client.py

@@ -172,7 +172,7 @@ def test_build_client_wires_the_anthropic_backend(monkeypatch: pytest.MonkeyPatc
 
     assert isinstance(client, AnthropicClient)
     assert client.timeout_s == REPORT_HTTP_TIMEOUT_SEC
-    assert client.model == "claude-opus-5"
+    assert client.model == "claude-opus-5-5"
     assert client.max_output_tokens == 1024
     assert built["openai"] == []
 

src/hyperloom/orchestrator/scoring/proposal_scorer.py

@@ -15,6 +15,7 @@
 from typing import Any, Callable
 
 from hyperloom.common.llm_config import (
+    DEFAULT_CLAUDE_MODEL,
     LLMConfigError,
     apply_reasoning_effort,
     astream_chat_completion_text,
@@ -30,7 +31,7 @@
 
 
 DEFAULT_SCORER_MODELS: tuple[str, ...] = (
-    "claude-opus-5",
+    DEFAULT_CLAUDE_MODEL,
     "gpt-5.6-sol",
     # Gemini MUST carry the ``gemini/`` prefix (bare slug routes to a broken Vertex ADC path).
     "dvue-aoai-005-Kimi-K2.6",

src/hyperloom/skills/hyperloom-setup/SKILL.md

@@ -105,7 +105,7 @@ value.
    - Ask `ANTHROPIC_BASE_URL` with exactly these option labels in this order:
      `Use default (https://api.anthropic.com)` /
      `Use AMD gateway (https://llm-api.amd.com/anthropic)` / `Custom`.
-   - Ask `CLAUDE_MODEL`: options `Use default (claude-opus-5)` / `Custom`.
+   - Ask `CLAUDE_MODEL`: options `Use default (claude-opus-5-5)` / `Custom`.
 4. Explain `USER_DATA_PATH`:
    - It is the writable root for Hyperloom runtime files, dependency checkouts, logs, optimizer runs, and generated env files.
    - Offer `<workspace>/session` (the current workspace directory plus a

src/kernelforge/tests/fusion/test_resolve_and_cli.py

@@ -188,7 +188,7 @@ def test_explicit_claude_wins_over_openai_credentials(clean_agent_env, monkeypat
     monkeypatch.setenv("OPENAI_API_KEY", "openai-key")
     provider, model = _resolve_agent_choice("claude", None)
     assert provider == "claude"
-    assert model == "claude-opus-5"
+    assert model == "claude-opus-5-5"
 
 
 def test_agent_model_precedence(clean_agent_env, monkeypatch):

src/kernelforge/tests/test_agent_env_contract.py

@@ -84,7 +84,7 @@ def test_the_context_window_env_is_not_read(clean_env) -> None:
     clean_env.setenv("CLAUDE_CONTEXT_WINDOW", "1m")
     config = Config.from_env(agent_backend="claude", workspace="/tmp")
     assert not hasattr(config, "agent_context_window")
-    assert config.agent_runtime().model == "claude-opus-5"
+    assert config.agent_runtime().model == "claude-opus-5-5"
 
 
 def test_the_removed_alias_is_no_longer_read(clean_env) -> None:

src/kernelforge/tests/test_claude_resume.py

@@ -199,7 +199,7 @@ def test_run_does_not_pass_a_resume_option():
     assert "resume" not in captured["options"].kwargs
 
 
-def test_opus_5_uses_the_runtime_effort_and_adaptive_thinking():
+def test_default_model_uses_the_runtime_effort_and_adaptive_thinking():
     captured: dict = {}
     backend = _backend(
         [_result_message(session_id="s-opus-48")],
@@ -224,7 +224,7 @@ def test_opus_5_uses_the_runtime_effort_and_adaptive_thinking():
     )
 
     kwargs = captured["options"].kwargs
-    assert kwargs["model"] == "claude-opus-5"
+    assert kwargs["model"] == DEFAULT_CLAUDE_MODEL
     # The spec asked for ``max``; the runtime says ``high`` and the runtime wins.
     # An effort written at a call site is this repository's opinion, and the one
     # on the runtime is the operator's decision about the run in front of them.
@@ -241,6 +241,7 @@ def test_opus_5_uses_the_runtime_effort_and_adaptive_thinking():
         ("claude-sonnet-4-6", True),
         ("claude-haiku-4-8", True),
         ("claude-opus-5", True),
+        ("claude-opus-5-5", True),
         ("company-current-claude", True),
         ("claude-opus-4", False),
         ("claude-sonnet-4", False),

src/kernelforge/tests/test_provider_registry.py

@@ -139,7 +139,7 @@ def test_builtin_model_ownership_predicates() -> None:
     """Recognize each built-in provider's model family without env coupling."""
     claude = get_agent_provider("claude")
     codex = get_agent_provider("codex")
-    assert claude.default_model == "claude-opus-5"
+    assert claude.default_model == "claude-opus-5-5"
     assert codex.default_model == "gpt-5.6-sol"
     assert claude.owns_model("claude-opus-5")
     assert not claude.owns_model("gpt-5.6")