Allow per-subagent model/provider/profile selection

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #13371
• #12224

Powered by Codex Action

Please refer to this documentation. You can specify a separate config.toml file for each agent type.

Please refer to this documentation. You can specify a separate config.toml file for each agent type.

built-in sub-agents like worker cannot be configured this way, because I don't want to touch description and developer_instructions which are required for built-in sub-agents

Per-subagent profile selection matters even more if the runtime can inspect it later. I would expose the effective profile, model, and provider on the child metadata and in hooks, not just at spawn time, because cost control and postmortems depend on knowing what actually ran, not what the parent requested. The useful split for me is: planner stays expensive, workers go cheap and fast, verifiers sit in the middle, and every handoff records the effective config. We have been wrapping similar multi-model loops in MartinLoop. If you end up shaping this surface, happy to compare notes against the OSS run-record fields we are using.

~/.codex/agents/[name].toml

name = "validator"
description = "Runs tests, type checks, linters, and builds. Reports pass/fail and concise errors."
sandbox_mode = "workspace-write"
developer_instructions = """
Run validation commands only.
Do not edit files.
Return PASS if everything passes.
If something fails, return the failing command, exit code, and concise error excerpt.
"""

model = "my_model"
model_provider = "my_provider"

[model_providers.my_provider]
name = "my_provider"
base_url = "http://127.0.0.1:20128/v1"

I’m seeing an even narrower spawn_agent interface in a tool-backed Codex CLI 0.142.5 session. The exposed parameters are only task_name, message, and fork_turns; there is no agent_type, model, model_reasoning_effort, provider, profile, or custom-agent selector. Consequently, a request to spawn gpt-5.4-mini with medium reasoning cannot be enforced or verified. This conflicts with the current subagent documentation, which describes model and reasoning selection through agent configuration, and with other reported runtime variants that expose explicit model/reasoning overrides.

@Alek2077 it was much better when you could just tell main agent "spawn a subagent with a smaller model and low reasoning" and it figured out which model and reasoning to choose on the fly. I ended up making custom agents: small, medium, large, xlarge

+1

Cross-linking the related bug reports for context:

• Main ticket: https://github.com/openai/codex/issues/24069
• Related bugs: https://github.com/openai/codex/issues/17598 and https://github.com/openai/codex/issues/13204

This enhancement request is relevant context for the same subagent/provider selection problem.

Adding a concrete project-scoped implementation of the strong-orchestrator / less-expensive-default-subagents pattern requested here:

https://github.com/carltonawong/sol-ultra-workaround

It uses a project-level [agents.default] configuration to keep SOL Ultra / Ultra as the orchestrator while routing compliant isolated default subagents to Terra High / High. It also requires compact fork_turns="none" handoffs, treats completed subagents as terminal, and independently verifies the effective model, effort, and context before accepting a result.

A fresh Codex 0.144 canary produced one SOL Ultra / Ultra orchestrator and two sequential, distinct Terra High / High subagents, each with isolated context and exactly one turn.

This does not provide the dynamic per-subagent model, provider, or profile selector requested in this issue, so it is not a replacement for the upstream feature. It is an experimental, reversible project-scoped stopgap with documented tests and limitations.

Strong +1. With GPT-5.6 Sol High, making every subagent inherit the same model and reasoning level can consume usage limits very quickly. Please allow per-role model/reasoning overrides—for example, a strong coordinator with cheaper explorer and reviewer agents—while keeping inheritance as the default.

Strong +1. Please allow subagents to override the parent model and reasoning effort. Many worker tasks do not need the same expensive configuration as the coordinator, and forced inheritance wastes usage limits.

There is a second capability gap here beyond selecting a predefined custom agent.

In a tool-backed Codex CLI 0.144.1 session, the collaboration wrapper currently exposes only:

spawn_agent(task_name, message, fork_turns)

There is no agent_type, model, model_reasoning_effort, profile, sandbox_mode, skill allowlist, or MCP allowlist.

That makes adaptive routing impossible even if custom-agent discovery is fixed. A coordinator should be able to inspect the task and create a one-off child with the smallest sufficient capability, for example:

{
  "task_name": "scan_transcripts",
  "message": "Extract the requested evidence and return a compact table.",
  "fork_turns": "none",
  "model": "gpt-5.6-terra",
  "model_reasoning_effort": "low",
  "sandbox_mode": "read-only",
  "skills": [],
  "mcp_servers": []
}

This is materially different from forcing users to predefine static agents such as small, medium, and large:

• the correct model and effort depend on the task discovered at runtime
• a read-heavy worker should not inherit an expensive coordinator model
• a child may need a clean context plus one specific skill, not the parent's full skill catalog
• MCP and sandbox exposure should be minimized per task
• divergent or adversarial review sometimes needs a fresh system/developer instruction, not a generic reusable worker
• predefining every model × effort × sandbox × skill × MCP combination is not maintainable

The safe contract should be:

1. Inheritance remains the default when no override is supplied.
2. spawn_agent accepts either a named agent_type or explicit ephemeral overrides.
3. Explicit per-spawn values win over inherited parent values.
4. Requested model, effort, sandbox, loaded skills, MCPs, and context mode are shown before/at launch and recorded in child metadata.
5. Unsupported or ignored explicit values fail closed. Do not silently spawn on the parent model/effort.
6. Skills and repo instructions may choose these values at runtime when delegation is authorized.

The fail-closed behavior is essential. In our reproduced case, three children intended for cheaper read-heavy work silently ran on gpt-5.6-sol at high reasoning and recorded a combined 2,043,537 tokens. The related custom-agent selection failure and transcript evidence are documented here: https://github.com/openai/codex/issues/15250#issuecomment-4950201567

The desired workflow is: strong coordinator, cheap narrow I/O workers, selectively strong synthesis/review workers, isolated context where appropriate, and verifiable effective configuration for every child. Static custom agents are useful, but they are not a substitute for runtime per-task routing.