Subagent configuration and orchestration

@am-will

What variant of Codex are you using?

cli

What feature would you like to see?

support to config which model and reasoning_effort to use for subagents in ~/.codex/config.toml
may it can be an option of slash cmd: /agents -> config

Description

Current Pain Point
Currently, I prefer using gpt-5.2 for high-level task planning and orchestration, and gpt-5.3-codex or spark for the exploration and execution of specific tasks. However, due to the lack of per-agent model configuration, users are stuck choosing a single model or using a pre-defined configuration for the entire run.

This creates a dilemma:

Sacrificing Planning Quality: Using a smaller model (like Spark) everywhere results in poor high-level orchestration.
Sacrificing Efficiency & Cost: Using a larger model for simple subtasks that don't require it sacrifices speed and cost-effectiveness.

Feature Suggestions

To maximize effectiveness and efficiency, I hope to configure subagent behavior and models granularly:

File-based Configuration & Definition
- Please consider supporting subagent configuration not only via ~/.codex/config.toml (global) but also via files like .agents/subagents/explore_agent.md at the repository or user level.
- As @am-will mentioned, similar to how Claude defines subagent configurations through files, I hope subagent instructions can be defined like AGENTS.md.
- Permission configuration also needs to be supported.
Agent Management Commands
- The slash command /agents -> list should show which subagents are currently available.
- Support for disabling and enabling specific subagents via command.
Custom Subagent Examples & Context Optimization (New)
Beyond basic configuration, I hope to support (and see examples of) custom exploration behaviors tailored to specific domains or projects. Different tech stacks require different exploration strategies:
- Frontend Architecture: An exploration agent could be instructed to prioritize the component tree, state management (Store), and routing structure.
- Backend Architecture: Depending on the language (e.g., Go vs. Python), the agent should prioritize API definitions, DB schemas, or middleware logic.
- Repo-level Optimization: Allow writing custom exploration instructions for specific repositories.
Value: Optimizing exploration behavior for specific repos can effectively reduce the "task cold start time" when a user raises a new requirement in a fresh session. The agent wouldn't need to perform a generic full scan but could follow the pre-defined "map" to locate relevant context immediately.

Expected Outcome
If this subagent configuration and behavior can be supported, users can use it out of the box while also leveraging customized exploration behaviors. We'll see interesting possibilities.

We prioritize feature requests based on upvotes from the community. If a feature request doesn't get enough upvotes, we'll close it. It's therefore important for a feature request to have a clear and compelling title and description. Speaking from experience, I don't think this one will attract much attention. You might want to try to improve the title and provide more details.

We also recommend that feature requests focus on the problem statement rather than a solution. Describe the use case and what problem you'd like to see solved. There are often multiple ways to address a given problem.

This is much needed given Spark's low context window. I have a pretty well optimized setup for AGENTS.md and MCPs, but Spark exhausts context window too quickly. Even competitors' 200k window feels small and results in frequent compaction, 128k results in an experience which feels like more compaction than coding (subjective). Orchestrating Spark subagents with "full" Codex, and excluding MCPs/AGENTS.md from subagent context would allow users to benefit from its speed while still being able to complete work which normally requires more context.

This is absolutely crucial to achieve the true power of the subagent system, using a smarter capable model for planning and smaller efficient and fast models for implementation based on the orchestrator's instructions.

This is a non negotiable in my opinion. This is a must have feature.

I would add that config might not be only via custom config.tomls, but just directly in a running session to expose model and reasoning level for the managing agent to be able to pass, similar to current prompt and task parameters.

@etraut-openai

Leaving this here since mine got closed (no worries @etraut-openai thanks)

To expand on this, this deserves to be defined more clearly, hopefully OP updates the description:

The ability to configure which model and reasoning_effort level subagents use, separately from the main agent. This could live in ~/.codex/config.toml and/or be exposed as an option under the /agents → config slash command.

Why this matters
Right now, there's no way to control what model or reasoning level subagents run with. With the introduction of Spark (which has a 128k context window), this becomes a real limitation. Spark is excellent for fast, scoped implementation tasks, but it doesn't make sense as the planning or orchestration layer given the smaller context.

Subagent support is still missing in Codex, and this issue is exactly the gap:

Skills/config define what to do, but not who does it (model, tools, permissions, prompt, memory).

Claude Code’s per-agent YAML gives a portable, version-controlled way to define that who.

And the YAML allows you to define n number of subagents, all with different models/reasoning level for different tasks. TRUE customization. Right now, we have just 1 subagent and we're stuck with that.

Proposed ideal (aligned with this issue):

A first-class agent registry in Codex (project + user scope).
Agent definition files compatible with Claude Code’s format (or a small, documented superset).
Ability to invoke agents directly or pair with skills (e.g., a skill that routes to a named agent).
Model/tools/permissions/memory/prompt all captured per agent, and checked in at the project level.
The ideal workflow looks something like this:

Planning and orchestration with a higher-capability model (e.g. base 5.3) that can hold the full project context and break work into well-defined tasks

Implementation via subagents using Spark or another lightweight model that executes those tasks quickly and cheaply

Without per-agent model configuration, users are stuck choosing a single model for the entire run. That means either sacrificing planning quality by using Spark everywhere, or sacrificing speed and cost efficiency by using a larger model for implementation subtasks that don't need it.

Proposed config example
toml[agent]
model = "codex-5.3"
reasoning_effort = "high"

[subagent]
model = "codex-5.3-spark"
reasoning_effort = "low"

Additional information

This would pair well with existing slash commands. For example, /agents config could allow toggling subagent settings mid-session for experimentation without editing the config file directly.

Thank you for reading! PLEASE UPVOTE the issue itself (first message) if you agree.

@jif-oai

@jif-oai Similar to the previous comment, one issue I ran into is that subagents inherit global instructions file and there's no way to set "this only applies to root agent"

In my fork I added a simple config option for agents that's just:
inherit_instruction_file either true or false, default true.

And I found that skill config in agents' configs doesn't work, so can't disable per subagent skills. (I think this is already covered by others above)

>_ OpenAI Codex (v0.105.0-alpha.18)
model:     gpt-5.3-codex medium

I noticed something that I'm not sure why it happens:
When I send the following prompt:

› Spawn a generic 'default' subagent and instruct it to list the available MCP context (tools/functions) (it should not do anything else)!


• Spawned Begonia [default]
  └ Please list the available MCP context (tools/functions) and do not perform any other actions.

• Begonia confirms the request and will list the available MCP context.

the “default” agent is used, which calls toolcodex.list_mcp_resources and does not see any MCP servers:

› Please list the available MCP context (tools/functions) and do not perform any other actions.


• Called codex.list_mcp_resources({})
  └ {"resources": []}

• No MCP resources are currently available in this environment.

When I send the following prompt:

› Spawn a generic 'worker' subagent and instruct it to list the available MCP context (tools/functions) (it should not do anything else)!


• Spawned Marigold [worker]
  └ List the available MCP context (tools/functions). Do not do anything else.

• Waiting for Marigold [worker]

• Finished waiting
  └ Marigold [worker]: Completed - Available tools/functions in this session: - `web.run` (web search/open/click/find/screenshot/image/finance/weather/sports/time) **`functions` namespace** - `exec_command`
- `write_stdin` - `list_mcp_resources` - `list_mcp_resource_templ...

• Tools summary from worker subagent “Marigold”: web.run (various search helpers), the functions namespace (exec_command, JetBrains helpers, Context7, Stitch, apply_patch, etc.), and
  multi_tool_use.parallel. Let me know if you need anything else.

a custom “worker” agent (only model and reasoning set) is used, which does not call any tool and sees all MCP servers that the parent has:

› List the available MCP context (tools/functions). Do not do anything else.


• Available tools/functions in this session:

  - web.run (web search/open/click/find/screenshot/image/finance/weather/sports/time)

  functions namespace

  - exec_command
  - write_stdin
  - list_mcp_resources
  - list_mcp_resource_templates
....
- mcp__JetBrains__build_project
  - mcp__JetBrains__create_new_file
  - mcp__JetBrains__execute_run_configuration
  - mcp__JetBrains__execute_terminal_command
...

Should I open an issue?

I’m seeing what looks like a global subagent-thread cap shared across multiple concurrent codex resume processes, which IMO should not be the case.

Observed behavior

Config: max_threads = 32
In one Codex session, I attempted to spawn 32 operator subagents in parallel.
The runtime started rejecting additional spawns with the exact error:
- collab spawn failed: agent thread limit reached (max 32)
However, the session only managed to spawn 25 operators before hitting the limit.

Evidence suggesting cross-session contention

At the time, the machine had multiple Codex sessions running:
- ps -Ao pid,etime,command | rg '\\bcodex( resume)?\\b'
- This showed several concurrent codex resume processes.

This strongly suggests the “max 32” limit is enforced across all running Codex sessions (or a shared runtime pool), rather than per independent Codex process/session. That makes concurrency testing and real workloads unpredictable unless users manually ensure all other sessions are closed and all subagents are close_agent’d.

Expected behavior

Each independent Codex process/session should have its own max_threads = 32 budget (or the UI/config should make it explicit that the limit is global/shared and provide tooling to introspect/kill leaked subagents).

Update after tightening our protocol: we enforce strict parent->direct-subordinate spawning only (no skip-level spawns, no same-level spawns). Under that valid hierarchy, depth=3 still fails because the nested orchestrator lacks the spawn_agent tool.

Protocol hierarchy (strict)

Director (main) -> Auditor
Auditor -> Orchestrator
Orchestrator -> (Coder | Operator | Awaiter)
(Coder | Operator | Awaiter) -> (spawn nothing)

Environment

codex-cli: 0.105.0-alpha.23
macOS: 26.3 (Darwin 25.3.0, arm64)
Config: max_threads = 32, max_depth = 3

Repro (valid chain, no forbidden edges)

From main, spawn an Auditor (spawn_agent(agent_type=auditor)).
Ask the Auditor to spawn an Orchestrator (spawn_agent(agent_type=orchestrator)).
Ask that Orchestrator to spawn a Coder or Operator (spawn_agent(agent_type=coder_spark) or operator).

Expected
Step 3 should succeed (Orchestrator spawning its direct subordinate is allowed by protocol and should be allowed by runtime when max_depth >= 3).

Actual
Step 3 fails because the nested Orchestrator reports that spawn_agent is not available (e.g. blocked=true reason=no_spawn_agent_tool).

This blocks any strict-hierarchy depth=3 workflow (main -> auditor -> orchestrator -> coder/operator).

Additional finding: this behavior lines up with the recently-merged agents.max_spawn_depth change from PR #10935.

PR #10935 introduces agents.max_spawn_depth (default appears to be Some(2)) and uses it to decide when to disable Collab features for spawned subagents.

In our strict chain main -> auditor -> orchestrator -> coder/operator, the orchestrator is a thread-spawned subagent at depth=2, and it consistently reports no_spawn_agent_tool when asked to spawn its direct subordinate.

Hypothesis:

agents.max_depth controls structural nesting.
agents.max_spawn_depth controls how deep Collab tools (including spawn_agent) remain available to subagents.
With max_spawn_depth=2, a nested orchestrator may lose Collab, so it cannot spawn leaf agents even though the hierarchy is valid and max_depth is sufficient.

Potential fix/workaround:

Document the distinction clearly.
Ensure agents.max_spawn_depth defaults and enforcement match expected multi-agent workflows (depth=3 chain).
Consider defaulting max_spawn_depth >= 3 when multi-agent is enabled, or provide a clearer error when Collab is disabled due to spawn depth.

@aurexav, please do not have your agent post to our issue tracker.

@aurexav, please do not have your agent post to our issue tracker.

I instruct it to post the update here. This is not a self-automated process.

A feature request regarding the upper limit. Almost every user will assume the maximum limit is bound to a single codex run rather than being globally applicable.
A broken change reminder for other testers. And the two similar-named parameters require comprehensive documentation upon release. Really confuse me.

This is in line with the other feedback provided.

Please ignore agent_max_spawn_depth for now. This parameter is orthogonal and should have been documented in another way. I will check where does it come from and fix

We run 9 agents across providers (OpenAI, Anthropic, Google and lower grade ones such as Moonshot, Qwen and Mistral) with per-agent model assignment in a single config file. Each agent gets its own model, behavioral constraints, and tool permissions.

The practical reason this matters: we've switched individual agents between providers 6+ times in the last month. Anthropic credits ran out, so ether moved to Gemini. Gemini rate-limited us, so klaus, mecha, and jean-clawde moved to Moonshot. sally moved to GPT-5.2 for better tool use. None of these changes required touching the other agents.

A single model for all subagents can break down fast in production. Different tasks need different cost/quality tradeoffs, and provider availability changes constantly. Per-agent config is not a nice-to-have, it is the first thing you need when running more than 2 agents.

Also I wonder, do senseless, hallucinatory feedback loops trigger easier when models are the same? It is not a big surprise that three Kimi K2.5 Openclaw Bots have managed this, but I've seen it happen also betweem Codex with 5.3 Codex and Openclaw with Codex 5.3. It sounded more intelligent than the Kimi loop but it was equally worthless, the Frontier Codexes just figured out a smarter way to ping pong rapid fire technical ACK hallucinatory nonsense.

Add Codex subagents (GA March 2026) and refresh skills paths

@EternalRights

@EternalRights that looks good. Does it work with codex/cc?

i really like this idea and i believe codex and cc need to lean in this direction as well.

it reminds me of the new eve by vercel. basically both are covering my main pain points listed 4m ago in this thread:

#11701 (comment)

p.s. seems post to what i replied to was deleted.

but i'd still raise the discussion of the bad DX with agent definition and lifecycle we have in codex right now.

@EternalRights that looks good. Does it work with codex/cc?

i really like this idea and i believe codex and cc need to lean in this direction as well.

it reminds me of the new eve by vercel. basically both are covering my main pain points listed 4m ago in this thread:

#11701 (comment)

p.s. seems post to what i replied to was deleted.

but i'd still raise the discussion of the bad DX with agent definition and lifecycle we have in codex right now.

Sorry, accidentally nuked my earlier comment.

To answer your question — agenthatch compiles SKILL.md into standalone Python agents. It's not tied to any specific platform, so it works alongside Codex, CC, whatever you're using. Each compiled agent is its own pip-installable package with scoped permissions.

One thing I should add: I'd actually love to see this embedded into tools like Codex and CC. Imagine Codex spawning a compiled skill agent as a subagent — it gets its own process, its own tool permissions, no prompt bloat. The orchestrator doesn't need to carry 20 SKILL.md files in context. I think that's a direction that benefits the whole ecosystem, not just one project.

https://github.com/agenthatch/agenthatch

Navigation Menu

Repository navigation

Subagent configuration and orchestration #11701

What variant of Codex are you using?

What feature would you like to see?

Description

54 remaining items

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Subagent configuration and orchestration #11701

Description

What variant of Codex are you using?

What feature would you like to see?

Description

Activity

etraut-openai commented on Feb 13, 2026

merlinnot commented on Feb 13, 2026

slobodaapl commented on Feb 13, 2026

am-will commented on Feb 13, 2026

ignatremizov commented on Feb 13, 2026

am-will commented on Feb 13, 2026

54 remaining items

slobodaapl commented on Feb 23, 2026

mrclrchtr commented on Feb 24, 2026

acgxv commented on Feb 25, 2026

acgxv commented on Feb 25, 2026

acgxv commented on Feb 25, 2026

etraut-openai commented on Feb 25, 2026

acgxv commented on Feb 25, 2026

jif-oai commented on Feb 25, 2026

ggoss0289-alt commented on Feb 26, 2026

ThinkOffApp commented on Mar 6, 2026

noname-oni commented on Jun 18, 2026

EternalRights commented on Jun 18, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions