What happened
In PR #7028, the code agent implemented config alias threading for sub-agent dispatch (commit fa4a895). The implementation blindly prepended anthropic-vertex/ to every alias value in piAgentModels, not accounting for already-qualified values like google-vertex/gemini-3.7-flash or xai-vertex specs like xai/grok-4.6. This produced invalid model IDs (e.g., anthropic-vertex/google-vertex/gemini-3.7-flash). The human (waynesun09, commit 7e14c94) had to fix this with a three-way dispatch: xai-vertex normalization, pass-through for already-qualified values, and prefix-only for bare IDs. The codebase already had translatePiModel and normalizeXaiVertexModel in pi_run.go demonstrating this exact pattern, but the code agent didn't reference them when working on the adjacent piAgentModels in pi_bootstrap.go.
What could go better
The code agent had no documented guidance about the provider-qualification invariant in model alias values. The pattern exists implicitly in translatePiModel and normalizeXaiVertexModel, but these are functions in pi_run.go that the code agent may not have read when working on pi_bootstrap.go. Without explicit documentation, the agent (and future human contributors) must independently discover that alias values can be bare IDs, provider-qualified IDs, or xai-vertex specs — each requiring different handling. The code agent wrote a happy-path test ("config aliases reach the sub-agent model table") but missed the edge case because nothing in the contributing docs or AGENTS.md flags this as a known invariant. Confidence: high — the bug was directly caused by the agent not knowing about the three value formats, and the fix was straightforward once the pattern was understood.
Proposed change
Add a section to docs/contributing/runtime-implementation.md (or the AGENTS.md runtime section) documenting the provider-qualification pattern for model alias values. The section should: (1) explain that alias values can be bare model IDs (claude-sonnet-5), provider-qualified IDs (google-vertex/gemini-3.7-flash), or xai-vertex specs (xai/grok-4.6); (2) reference translatePiModel and normalizeXaiVertexModel as canonical implementations of the three-way dispatch; (3) state the invariant: any code that transforms alias values must handle all three formats — bare IDs get the default provider prefix, already-qualified values pass through unchanged, xai-vertex specs get normalized to canonical three-segment form; (4) note that tests for alias-handling code should cover each format type.
Validation criteria
The next code agent run that modifies model alias resolution or sub-agent model dispatch in the pi runtime should not introduce a provider double-prefixing bug. Validate by: (1) the documentation section exists and is discoverable from AGENTS.md; (2) a future code agent PR that touches alias resolution includes tests with provider-qualified values. Observable within the next 3 PRs that modify pi_run.go or pi_bootstrap.go.
Generated by retro agent from #7028
What happened
In PR #7028, the code agent implemented config alias threading for sub-agent dispatch (commit
fa4a895). The implementation blindly prependedanthropic-vertex/to every alias value inpiAgentModels, not accounting for already-qualified values likegoogle-vertex/gemini-3.7-flashor xai-vertex specs likexai/grok-4.6. This produced invalid model IDs (e.g.,anthropic-vertex/google-vertex/gemini-3.7-flash). The human (waynesun09, commit7e14c94) had to fix this with a three-way dispatch: xai-vertex normalization, pass-through for already-qualified values, and prefix-only for bare IDs. The codebase already hadtranslatePiModelandnormalizeXaiVertexModelinpi_run.godemonstrating this exact pattern, but the code agent didn't reference them when working on the adjacentpiAgentModelsinpi_bootstrap.go.What could go better
The code agent had no documented guidance about the provider-qualification invariant in model alias values. The pattern exists implicitly in
translatePiModelandnormalizeXaiVertexModel, but these are functions inpi_run.gothat the code agent may not have read when working onpi_bootstrap.go. Without explicit documentation, the agent (and future human contributors) must independently discover that alias values can be bare IDs, provider-qualified IDs, or xai-vertex specs — each requiring different handling. The code agent wrote a happy-path test ("config aliases reach the sub-agent model table") but missed the edge case because nothing in the contributing docs or AGENTS.md flags this as a known invariant. Confidence: high — the bug was directly caused by the agent not knowing about the three value formats, and the fix was straightforward once the pattern was understood.Proposed change
Add a section to
docs/contributing/runtime-implementation.md(or the AGENTS.md runtime section) documenting the provider-qualification pattern for model alias values. The section should: (1) explain that alias values can be bare model IDs (claude-sonnet-5), provider-qualified IDs (google-vertex/gemini-3.7-flash), or xai-vertex specs (xai/grok-4.6); (2) referencetranslatePiModelandnormalizeXaiVertexModelas canonical implementations of the three-way dispatch; (3) state the invariant: any code that transforms alias values must handle all three formats — bare IDs get the default provider prefix, already-qualified values pass through unchanged, xai-vertex specs get normalized to canonical three-segment form; (4) note that tests for alias-handling code should cover each format type.Validation criteria
The next code agent run that modifies model alias resolution or sub-agent model dispatch in the pi runtime should not introduce a provider double-prefixing bug. Validate by: (1) the documentation section exists and is discoverable from AGENTS.md; (2) a future code agent PR that touches alias resolution includes tests with provider-qualified values. Observable within the next 3 PRs that modify
pi_run.goorpi_bootstrap.go.Generated by retro agent from #7028