Add Claude Code-style reusable subagent types to MultiAgentV2 spawn_agent

What variant of Codex are you using?

Codex CLI and tool-backed Codex sessions (MultiAgentV2 / collaboration.spawn_agent).

What feature would you like to see?

Add a first-class subagent_type (or agent_type) parameter to the MultiAgentV2 spawn_agent tool so reusable custom subagents can be selected by name across all Codex surfaces.

The current V2 tool surface exposes runtime-instance fields such as task_name, message, and fork_turns, but it does not expose the role to instantiate. A task named reviewer is still a generic child; it does not resolve and apply ~/.codex/agents/reviewer.toml or .codex/agents/reviewer.toml.

This conflates two different concepts:

• Task instance identity: the name/path of one spawned run (task_name).
• Reusable agent type: a persistent role with its own description, instructions, model, tools, permissions, sandbox, and MCP configuration (subagent_type).

A minimal schema addition would look like:

{
  "task_name": "review_auth_change",
  "subagent_type": "security-reviewer",
  "message": "Review the authentication changes.",
  "fork_turns": "none"
}

At session initialization, Codex should discover custom agent definitions and expose only their names and descriptions to the parent agent, allowing it to select the correct reusable role without injecting every role's full prompt into the parent context.

When spawn_agent is called with subagent_type, Codex should:

1. Resolve the named role from user- and project-level agent registries.
2. Create a fresh child context.
3. Load that role's configured developer instructions into the child.
4. Apply its model, reasoning effort, sandbox, tool/MCP, and permission settings.
5. Keep task_name as the independent runtime instance name.
6. Return the resolved role in child metadata so the parent and UI can verify what ran.

Unknown role names should produce a structured error that lists available types rather than silently spawning a generic child.

Additional information

Claude Code provides the useful reference design. Its subagent tool separates the reusable subagent_type from the optional runtime name, and loads custom subagent descriptions into the parent agent's available-type context. The selected subagent then runs with the instructions defined in its agent file. This enables both automatic delegation based on descriptions and explicit invocation of a known reusable agent.

Reference: https://code.claude.com/docs/en/sub-agents

This request is broader than the existing runtime bugs: it proposes a stable cross-surface contract for reusable named subagents in MultiAgentV2.

Related issues:

• #32291 — Tool-backed Codex Desktop cannot select named custom agents.
• #15250 — Custom subagents are inaccessible from tool-backed sessions.
• #31097 — MultiAgentV2 hides documented custom-agent controls.
• #20077 — MultiAgentV2 rejects role/model overrides under full-history forks.

Acceptance criteria:

• V2 spawn_agent exposes a role selector (subagent_type or agent_type).
• User and trusted project custom agents are discoverable by name and description.
• The selected agent file's instructions and scoped configuration are applied to the child.
• Runtime task identity remains separate from role identity.
• CLI, Desktop/App, IDE, and other tool-backed surfaces share the same behavior.
• Existing generic spawning remains backward-compatible when no role is selected.