Context

Part of #415 Phase 1, item 3. After the auth config field exists (#421) and auth profiles are relocated (#419), the runtime layer needs to resolve profile keys to env vars and inject them into CLI subprocess environments.

Scope

1. In the agent runner (where buildEnv() or equivalent assembles the CLI subprocess environment):

   • Resolve the agent's auth config value
   • If auth: false → skip (no profile injection)
   • If auth: "profile-id" → load profile, resolve provider → env var name, inject
   • If auth: ["id1", "id2"] → pick next in rotation, resolve, inject

2. Provider → env var mapping (already exists in resolveEnvApiKey):

   • anthropic → ANTHROPIC_API_KEY
   • google → GEMINI_API_KEY
   • openai → OPENAI_API_KEY
   • codex → CODEX_API_KEY
   • Claude OAuth → CLAUDE_CODE_OAUTH_TOKEN

3. Credential precedence (highest to lowest):

   agent.auth profile key → runtimeEnv → process.env → CLI-native auth
   

   If runtimeEnv already has the same env var, auth profile takes priority.

4. Round-robin state: track last-used index per agent. Reset on process restart (no persistence needed — rotation is best-effort).

Tests

• Auth profile key is injected as correct env var for each provider type
• auth: false results in no profile injection
• runtimeEnv is overridden by auth profile when both set same var
• Round-robin cycles through array entries across calls
• Missing/invalid profile ID logs warning, falls through to next precedence level

Depends on

• refactor(auth): relocate auth-profiles from src/agents/ to src/auth/ #419 — auth relocation
• feat(config): add per-agent auth field to agent list config #421 — auth config field

Related

• feat: unified auth + multimodal AgentRuntime — implementation plan #415 — implementation plan (parent)