Support opt-in skill-driven delegation to project custom agents

What variant of Codex are you using?

Tool-backed Codex sessions today, but this request is meant for Codex generally: CLI, App, IDE extension, and any other surface that loads repo-local .codex/ configuration, AGENTS.md, and skills.

What feature would you like to see?

Summary

Please add an opt-in repo-level delegation mode where Codex may automatically spawn project-scoped custom agents when the active repo instructions clearly route the current task to orchestration.

Today the official subagents docs describe spawning subagents when the user explicitly asks for them:
https://developers.openai.com/codex/subagents

That default makes sense for general use. The problem is that it blocks a more structured workflow that some repos already define very explicitly:

• repo config enables multi-agent work
• custom agents are defined under .codex/agents/*.toml
• AGENTS.md / skills / workflow docs specify when orchestration is required
• the current task clearly matches those orchestration criteria

In that situation, Codex still behaves as if delegation is disallowed unless the user literally says something like "use sub-agents".

I am not asking to change the default globally. I am asking for an opt-in mode that lets repo-defined orchestration rules count as sufficient delegation intent.

Concrete scenario

A repo defines a workflow like this:

• .codex/config.toml has features.multi_agent = true
• custom agents such as section_author and reviewer live in .codex/agents/
• repo instructions say that complex multi-part client-facing work must use orchestration mode
• orchestration mode delegates bounded authoring work and final review

A user then asks Codex to address multiple comments across a large client-facing artifact with changes spanning sections.

Expected behavior in that repo:

• Codex reads the active instructions/skill
• recognizes that this task is in orchestration territory
• chooses the appropriate project-scoped custom agents
• spawns them without requiring the user to add a separate line like "please use subagents"

Actual behavior today:

• Codex stays in a single-agent path unless the user explicitly asks for delegation
• if the session is tool-backed, custom agents may not even be directly invocable by name (#15250)

The result is that repo-authored orchestration workflows are advisory rather than executable.

Why this matters

This gap makes it hard to build reliable team/repo workflows around Codex.

Examples where this matters:

• skill-driven multi-part authoring pipelines
• sectioned review flows
• multi-surface UI + backend changes with bounded ownership
• orchestrator/reviewer workflows where the main agent should coordinate, not do all the work itself

In practice, other coding-agent environments already support this style of skill-driven delegation. When the same repo is run in Codex, the workflow degrades because the user must restate delegation intent manually even though the repo has already encoded it.

Proposed behavior

Add a repo-level config gate, for example:

[agents]
delegation_mode = "explicit"   # current behavior / default
# or
delegation_mode = "skill_auto"

When delegation_mode = "skill_auto", Codex may spawn subagents without extra user phrasing only if all of the following are true:

1. Multi-agent is enabled for the repo.
2. The active repo instructions, skill, or workflow explicitly route this task to orchestration.
3. The task is meaningfully partitionable.
4. A matching project-scoped custom agent exists, or a documented fallback role exists.
5. Runtime limits (max_threads, max_depth, etc.) permit the fan-out.

This keeps the current explicit-ask model as the default while letting advanced repos opt into stronger workflow automation.

Important design constraints

This should not mean "Codex may always delegate whenever it wants".

The proposed mode should still:

• respect approvals and sandbox rules
• respect repo thread/depth limits
• keep delegation explainable
• be easy to disable globally or per repo

I would strongly recommend an explainability requirement such as a visible/logged reason:

Spawned section_author because the active repo workflow selected orchestrate mode for a multi-section comment-heavy task.

That would make the behavior debuggable instead of mysterious.

Related gaps / adjacent issues

This request is related to, but distinct from:

• #15250 — custom subagents in .codex/agents are not accessible from tool-backed Codex sessions as docs imply
• #17545 — first-class main-session agent/role presets with skill scoping
• #18105 — orchestrator/delegate mode such that the main agent is strictly read-only

Even if #15250 is fixed and custom agents become directly invocable in tool-backed sessions, there is still a separate missing capability here: letting repo-defined orchestration rules trigger delegation automatically when the repo has explicitly opted into that behavior.

Acceptance criteria

This feature would feel complete if all of the following were true:

1. A repo can opt in to skill-driven delegation through config.
2. Codex can treat active repo instructions/skills as sufficient delegation intent in that mode.
3. Project-scoped custom agents from .codex/agents/ can be selected automatically when their roles match the routed task.
4. The reason for each auto-spawn is visible in logs/UI.
5. The behavior is consistent across Codex surfaces, or the docs clearly scope where it is supported.

Additional information

A related documentation/config nuance is that current docs already position custom agents as project-scoped building blocks with descriptions that help indicate when they should be used:

• https://developers.openai.com/codex/subagents
• https://developers.openai.com/codex/config-reference

That makes this feature feel like a natural next step: let repos opt into making those routing rules operational, not just descriptive.