feat: expose per-agent model configuration for Codex CLI users

[Q00]

Context

User feedback: ability to set different models per agent role would be valuable — e.g., orchestrator on gpt-5.4 high reasoning effort, workers on gpt-5.4 mini medium.

Current State

Ouroboros (already supported)

Ouroboros supports 15+ per-role model overrides via ~/.ouroboros/config.yaml and environment variables:

Role	Config field	Env var
Interview	clarification.default_model	OUROBOROS_CLARIFICATION_MODEL
Semantic evaluation	evaluation.semantic_model	OUROBOROS_SEMANTIC_MODEL
QA verdict	llm.qa_model	OUROBOROS_QA_MODEL
Wonder (lateral thinking)	resilience.wonder_model	OUROBOROS_WONDER_MODEL
Consensus advocate/devil/judge	consensus.*_model	OUROBOROS_CONSENSUS_*_MODEL
... and 10+ more

Additionally, PAL tier routing (frugal / standard / frontier) enables cost-optimized model selection with automatic escalation on failure.

Codex CLI (not supported)

Codex CLI's ~/.codex/config.toml only supports a single global model:

model = "gpt-5.4"
model_reasoning_effort = "xhigh"

There is no per-agent, per-task, or per-role model override mechanism.

Proposal

Short term (workaround — works today)

Pass Ouroboros model overrides via the MCP server env block in config.toml:

[mcp_servers.ouroboros.env]
OUROBOROS_AGENT_RUNTIME = "codex"
OUROBOROS_CLARIFICATION_MODEL = "gpt-5.4"
OUROBOROS_SEMANTIC_MODEL = "gpt-4o-mini"
OUROBOROS_QA_MODEL = "gpt-4o-mini"

This only affects Ouroboros-managed phases (interview, evaluation, consensus), not the Codex execution runtime itself.

Medium term

1. Document the existing per-role model config more prominently for Codex users
2. Add an ouroboros config models CLI command to list/set role-model mappings interactively
3. Consider a model_profiles config section for predefined cost presets (e.g., cost-optimized, quality-first)

Long term (upstream)

Per-agent model routing in Codex CLI itself would require changes to the Codex config schema — this is an upstream feature request for the Codex CLI project.

References

• Config model definitions: src/ouroboros/config/models.py
• Config loader (getters): src/ouroboros/config/loader.py L587-862
• PAL tier routing: src/ouroboros/routing/tiers.py

[ouroboros-agent]

Thanks for writing this up clearly.

This is a valid feature request, but it currently spans multiple scopes:

• better documentation for Codex users around the existing per-role model overrides
• a new ouroboros config models CLI surface for listing/editing role-model mappings
• possible new model_profiles config/schema support for predefined presets
• an upstream Codex CLI limitation that Ouroboros itself cannot resolve

Given that blast radius, I’m routing this to needs-design rather than treating it as a single fix.

Scope assessment

• Docs: docs/runtime-guides/codex.md, docs/config-reference.md, and likely onboarding/config docs
• CLI surface: src/ouroboros/cli/commands/config*.py / current config command scaffolding
• Config schema + loader: src/ouroboros/config/models.py, src/ouroboros/config/loader.py
• Potential follow-up: decide whether this should be split into separate issues (docs-only, CLI UX, config profiles)

Suggested next step: split this into a concrete first slice — most likely a docs improvement issue or a narrowly-scoped CLI issue with explicit acceptance criteria.

ouroboros-agent[bot]