Implementation Plan: T5-P4-A5-WP1 Replace three-way gpt-5.5 collision in CODEX_MODEL_ALIASES (#4097)

## Summary

Replace the degenerate three-way `gpt-5.5` collision in
`CODEX_MODEL_ALIASES` with three distinct real OpenAI model IDs aligned
with `CODEX_EFFORT_MAPPING` semantics: `gpt-5.5` (opus/xhigh), `gpt-5.4`
(sonnet/high), `gpt-5.4-mini` (haiku/medium). Implement a
`model_class()` utility function for cross-backend opus/sonnet/haiku
tier resolution via suffix stripping, identity check on
`CLAUDE_MODEL_ALIASES` keys, and reverse-map on `CODEX_MODEL_ALIASES`
values. Thread the new symbol through the re-export chain and add
architecture and unit tests.

## Implementation Plan

Plan file:
`/home/talon/projects/autoskillit-runs/impl-20260612-150756-734470/.autoskillit/temp/make-plan/t5_p4_a5_wp1_replace_gpt55_collision_plan_2026-06-12_151500.md`

Closes #4022

🤖 Generated with [Claude Code](https://claude.com/claude-code) via
AutoSkillit
<!-- autoskillit:pipeline-signature
steps=prepare_pr,run_arch_lenses,compose_pr,annotate_pr_diff,review_pr
-->

## Token Usage Summary

| Step | Model | count | uncached | output | cache_read | peak_ctx |
turns | cache_write | time |

|------|-------|-------|----------|--------|------------|----------|-------|-------------|------|
| plan* | opus[1m] | 1 | 67 | 22.1k | 1.7M | 106.3k | 51 | 107.1k | 11m
37s |
| verify* | sonnet | 1 | 78 | 16.1k | 407.5k | 61.2k | 26 | 40.3k | 6m
36s |
| implement* | MiniMax-M3 | 1 | 1.1M | 6.7k | 0 | 0 | 50 | 0 | 2m 48s |
| audit_impl* | sonnet | 1 | 2.3k | 6.3k | 166.5k | 41.7k | 16 | 29.8k |
3m 49s |
| prepare_pr* | MiniMax-M3 | 1 | 232.8k | 2.8k | 0 | 0 | 15 | 0 | 1m 8s
|
| compose_pr* | MiniMax-M3 | 1 | 176.4k | 1.3k | 0 | 0 | 12 | 0 | 36s |
| **Total** | | | 1.5M | 55.3k | 2.2M | 106.3k | | 177.2k | 26m 36s |

\* *Step used a non-Anthropic provider; caching behavior may differ.*

## Token Efficiency

| Step | LoC Changed | cache_read/LoC | cache_write/LoC | output/LoC |
|------|-------------|----------------|-----------------|------------|
| plan | 0 | — | — | — |
| verify | 0 | — | — | — |
| implement | 59 | 0.0 | 0.0 | 113.2 |
| audit_impl | 0 | — | — | — |
| prepare_pr | 0 | — | — | — |
| compose_pr | 0 | — | — | — |
| **Total** | **59** | 38004.2 | 3003.8 | 936.9 |

## Model Usage Breakdown

| Model | steps | uncached | output | cache_read | cache_write | time |
|-------|-------|----------|--------|------------|-------------|------|
| opus[1m] | 1 | 67 | 22.1k | 1.7M | 107.1k | 11m 37s |
| sonnet | 2 | 2.4k | 22.5k | 574.0k | 70.1k | 10m 26s |
| MiniMax-M3 | 3 | 1.5M | 10.8k | 0 | 0 | 4m 32s |

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: Trecek

src/autoskillit/core/__init__.pyi

@@ -359,6 +359,7 @@ from .types import extract_positional_args as extract_positional_args
 from .types import extract_skill_name as extract_skill_name
 from .types import fleet_error as fleet_error
 from .types import is_path_like_token as is_path_like_token
+from .types import model_class as model_class
 from .types import resolve_payload_field as resolve_payload_field
 from .types import resolve_skill_name as resolve_skill_name
 from .types import resolve_target_skill as resolve_target_skill

src/autoskillit/core/types/_type_backend.py

@@ -29,6 +29,7 @@
     "CodexEventData",
     "SessionEvent",
     "AgentSessionResult",
+    "model_class",
     "strip_context_window_suffix",
 ]
 
@@ -169,9 +170,9 @@ class BackendCapabilities:
 }
 
 CODEX_MODEL_ALIASES: dict[str, str] = {
-    "sonnet": "gpt-5.5",
+    "sonnet": "gpt-5.4",
     "opus": "gpt-5.5",
-    "haiku": "gpt-5.5",
+    "haiku": "gpt-5.4-mini",
 }
 
 CODEX_EFFORT_MAPPING: dict[str, str] = {
@@ -180,6 +181,14 @@ class BackendCapabilities:
     "haiku": "medium",
 }
 
+_CODEX_MODEL_REVERSE: dict[str, str] = {v: k for k, v in CODEX_MODEL_ALIASES.items()}
+_codex_alias_values = list(CODEX_MODEL_ALIASES.values())
+assert len(_CODEX_MODEL_REVERSE) == len(CODEX_MODEL_ALIASES), (
+    "CODEX_MODEL_ALIASES values must be unique — duplicate makes an alias unreachable "
+    f"via model_class(). Duplicates: "
+    f"{[v for v in _codex_alias_values if _codex_alias_values.count(v) > 1]}"
+)
+
 
 @dataclass(frozen=True, slots=True)
 class ModelTranslation:
@@ -198,6 +207,13 @@ def strip_context_window_suffix(model: str) -> str:
     return _CONTEXT_WINDOW_SUFFIX_RE.sub("", model)
 
 
+def model_class(model: str) -> str:
+    base = strip_context_window_suffix(model)
+    if base in CLAUDE_MODEL_ALIASES:
+        return base
+    return _CODEX_MODEL_REVERSE.get(base, base)
+
+
 CLAUDE_CODE_CAPABILITIES: BackendCapabilities = BackendCapabilities(
     channel_b_capable=True,
     pty_required=True,

tests/arch/test_backend_translate_model.py

@@ -66,3 +66,19 @@ def test_translate_model_called_at_terminal_model_sites() -> None:
                 f"{backend_name}.{method_name} appends --model but does not call "
                 f"self.translate_model"
             )
+
+
+def test_translate_model_distinct_per_alias_class() -> None:
+    from autoskillit.core.types._type_backend import CLAUDE_MODEL_ALIASES
+
+    alias_keys = list(CLAUDE_MODEL_ALIASES.keys())
+    for backend_name, cls in BACKEND_REGISTRY.items():
+        try:
+            backend = cls()
+        except TypeError:
+            pytest.skip(f"{backend_name}: requires constructor args — cannot validate")
+        translated = [backend.translate_model(k) for k in alias_keys]
+        assert len(translated) == len(set(translated)), (
+            f"{backend_name}: translate_model produced duplicate outputs for alias keys "
+            f"{alias_keys}: {translated}"
+        )

tests/core/test_backend_dataclasses.py

@@ -204,6 +204,7 @@ def test_backend_module_all_exhaustive():
         "CodexEventData",
         "SessionEvent",
         "AgentSessionResult",
+        "model_class",
         "strip_context_window_suffix",
     }
 

tests/execution/backends/test_model_translation.py

@@ -183,3 +183,31 @@ def test_interactive_cmd_has_effort(self) -> None:
     def test_no_effort_for_native_model_in_headless_cmd(self) -> None:
         spec = CodexBackend().build_headless_cmd("test prompt", model="gpt-5.5")
         assert "model_reasoning_effort" not in " ".join(spec.cmd)
+
+
+class TestModelClass:
+    def test_canonical_keys(self) -> None:
+        from autoskillit.core import model_class
+
+        assert model_class("opus") == "opus"
+        assert model_class("sonnet") == "sonnet"
+        assert model_class("haiku") == "haiku"
+
+    def test_suffix_stripping(self) -> None:
+        from autoskillit.core import model_class
+
+        assert model_class("opus[1m]") == "opus"
+        assert model_class("sonnet[1m]") == "sonnet"
+        assert model_class("haiku[1m]") == "haiku"
+
+    def test_codex_reverse_map(self) -> None:
+        from autoskillit.core import model_class
+
+        assert model_class(CODEX_MODEL_ALIASES["opus"]) == "opus"
+        assert model_class(CODEX_MODEL_ALIASES["sonnet"]) == "sonnet"
+        assert model_class(CODEX_MODEL_ALIASES["haiku"]) == "haiku"
+
+    def test_unknown_passthrough(self) -> None:
+        from autoskillit.core import model_class
+
+        assert model_class("custom-model-xyz") == "custom-model-xyz"

tests/execution/test_model_alias_registry.py

@@ -6,7 +6,7 @@
 
 pytestmark = [pytest.mark.layer("execution"), pytest.mark.small]
 
-VALID_CODEX_MODEL_IDS: frozenset[str] = frozenset({"gpt-5.5"})
+VALID_CODEX_MODEL_IDS: frozenset[str] = frozenset({"gpt-5.4", "gpt-5.4-mini", "gpt-5.5"})
 
 VALID_CLAUDE_MODEL_IDS: frozenset[str] = frozenset({"sonnet", "opus", "haiku"})