Allow per-subagent model/provider/profile selection

Summary

Codex should allow spawned subagents to run with a different model, provider, or named profile than the parent session.

Problem

Right now, even where Codex supports custom model_provider / profile selection for the main session, there does not appear to be a public way to route subagents to different models/providers.

This blocks workflows such as:

main agent on a larger reasoning model
subagents on a cheaper/faster coding model
OpenAI parent session with local/compatible-provider worker subagents
specialized agents bound to named profiles (reviewer, fast-fix, research, etc.)

Why this matters

Subagents are exactly where model specialization pays off the most:

coordinator agent needs stronger planning/context
worker agents often need lower latency and lower cost
some tasks should route to a provider with different strengths or local deployment constraints

Without this, multi-agent support is less useful and more expensive than it needs to be.

Proposed UX

Any of these would solve it:

Allow subagent creation to accept profile
Allow explicit model + model_provider on subagent creation
Allow named agent presets in config, for example:

[agents.reviewer]
profile = "openai-gpt5"

[agents.fast_worker]
profile = "spark"

[agents.local_worker]
profile = "lmstudio-qwen"

Then something like:

/agents reviewer
spawn_agent(..., agent="fast_worker")

Expected behavior

Parent session keeps its own model/provider/profile
Each subagent can inherit parent config by default
Each subagent can optionally override with another profile/model/provider
Tooling and status output should show which profile/model/provider each subagent is using

Related context

Broad subagent request: Subagent Support #2604
Provider support discussion: Are other provider's models supported? #924
Routing inconsistency example: The /review command ignores the configured model and endpoint settings, defaulting to gpt-5-codex instead of the specified custom model. #5245

Additional note

OpenAI’s GPT-5.3-Codex-Spark announcement mentions delegating/fanning out work to many models in parallel. This feature would expose that power in a concrete, user-configurable way.

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

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

@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: Regression: Codex CLI 0.133.0 breaks native subagent spawning for local Ollama provider; 0.132.0 works #24069
Related bugs: Native subagent orchestration does not work correctly with non-OpenAI custom providers #17598 and Subagent ignores active profile/provider and falls back to openai #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:

Inheritance remains the default when no override is supplied.
spawn_agent accepts either a named agent_type or explicit ephemeral overrides.
Explicit per-spawn values win over inherited parent values.
Requested model, effort, sandbox, loaded skills, MCPs, and context mode are shown before/at launch and recorded in child metadata.
Unsupported or ignored explicit values fail closed. Do not silently spawn on the parent model/effort.
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: #15250 (comment)

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.

First-class Advisor routing for high-impact decisions

I would like Codex to support an Advisor or “second opinion” mechanism for important decisions.

The desired workflow is:

The primary agent remains responsible for execution. For example, I would like to use gpt-5.6-luna at Max as the primary agent.
When it reaches a decision with significant uncertainty or impact, it can ask gpt-5.6-sol at Extra High or Max for an independent review.
The primary agent sends a compact decision brief containing the goal, verified evidence, available options, current recommendation, risks, and open questions.
The Advisor returns criticism, missing risks, alternative approaches, and a recommendation.
The Advisor is read-only, cannot make changes or external side effects, and cannot start further consultations.
The primary agent remains the final decision owner and clearly reports which Advisor suggestions it accepted or rejected.

Useful initial triggers could include architecture choices, security boundaries, data migrations, public API changes, irreversible actions, or repeated failed attempts.

This should not run on every turn. A practical UX could include:

off
suggest: explain why an Advisor review would help and ask for confirmation
auto: invoke it automatically within user-defined limits
a manual “Ask Advisor” action

Please also consider per-task call limits, token/cost/latency budgets, duplicate-call suppression, privacy controls, visible model attribution, and graceful fallback when the Advisor is unavailable.

This would provide a quality gate for high-impact decisions while preserving the speed of the primary agent. It is not intended to create a model debate on every task; the key value is selective, bounded, and auditable second-opinion review.

Subagents support model, reasoning, provider, and role configuration.

Following up on the resolution note: per-role configuration is useful, but automatic delegation still has a gap. When the coordinator discovers work and launches a child on the fly, it cannot choose that child's model and reasoning effort based on the task; automatically launched children inherit the parent unless a preconfigured role is selected.

This means routing a simple read-only task to a cheaper/lower-effort model and a synthesis or review task to a stronger model requires static roles instead of adaptive dispatch. Could the automatic spawn path support per-spawn model and model_reasoning_effort overrides, with inheritance as the default, and expose the effective values? If this is already supported in a particular Codex surface, please point to the documented mechanism.

@lxsloves

(response from codex)

@lxsloves, per-spawn subagent overrides are supported: the parent can pass model and reasoning_effort to spawn_agent without selecting a static role. The spawn argument is reasoning_effort, rather than the config-file name model_reasoning_effort. See the tool schema and child configuration logic.

There are qualifications: some surfaces can hide those controls, and some parent instructions require an explicit user request before choosing a different model. So adaptive selection without any user direction is not guaranteed. The effective model and effort are emitted in subagent activity, but they are not currently included in the spawn_agent return value. If you’re seeing the narrower interface, please share the Codex version and surface so we can identify that path.

Navigation Menu

Repository navigation

Allow per-subagent model/provider/profile selection #14039

Summary

Problem

Why this matters

Proposed UX

Expected behavior

Related context

Additional note

First-class Advisor routing for high-impact decisions

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Allow per-subagent model/provider/profile selection #14039

Description

Summary

Problem

Why this matters

Proposed UX

Expected behavior

Related context

Additional note

Activity

github-actions commented on Mar 9, 2026

etraut-openai commented on Mar 9, 2026

HaoboGu commented on Mar 18, 2026

Keesan12 commented on May 18, 2026

souljorje commented on Jun 9, 2026

Alek2077 commented on Jul 3, 2026

souljorje commented on Jul 6, 2026

iqdoctor commented on Jul 9, 2026

iqdoctor commented on Jul 9, 2026

carltonawong commented on Jul 11, 2026

ChanTinPing commented on Jul 11, 2026

ChanTinPing commented on Jul 11, 2026

CodeWarriorr commented on Jul 12, 2026

pixelsama commented on Aug 4, 2026

First-class Advisor routing for high-impact decisions

etraut-openai commented on Aug 5, 2026

lxsloves commented on Oct 13, 2026

etraut-openai commented on Oct 13, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions