Support pluggable external backends for native subagent tools

What variant of Codex are you using?

Codex CLI / App multi-agent runtime.

What feature would you like to see?

Support a pluggable external backend for Codex's native subagent tools.

Codex should continue exposing and using its existing native collaboration surface (spawn_agent, send_message, followup_task, interrupt_agent, list_agents, and wait_agent), while allowing the lifecycle implementation behind those tools to be supplied by a configured external process or MCP-compatible adapter.

A possible configuration shape:

[agents]
backend = native # default

[agents.external_backend]
command = my-subagent-adapter
protocol = stdio-json

The exact configuration and transport are not important. The important part is an explicit backend interface below the existing tool handlers, rather than adding a second set of model-visible tools.

Motivation

Codex is an excellent primary planner and orchestrator, but users may want delegated work to run in another compatible agent runtime for cost, quota, model specialization, enterprise policy, or access to a pre-existing worker environment.

Today the practical alternatives are incomplete:

1. Expose separate MCP tools and teach the model when to use them. This changes the model-visible delegation schema, competes with native spawn_agent, and requires prompt/rule/skill guidance.
2. Launch another CLI through shell or MCP. This loses Codex's native agent handles, lifecycle semantics, status UI, cancellation, follow-up messaging, and compact result path.
3. Intercept spawn_agent with hooks. The multi-agent handlers do not currently provide a reliable replace-execution hook, and an allow/deny hook would still be insufficient because the adapter must return a synthetic native spawn result.
4. Fork each external agent integration directly into the spawn_agent handler. This does not scale and makes integrations difficult to maintain.

A backend interface would let Codex remain fully responsible for deciding when to delegate, task decomposition, orchestration, and final decisions. Only child execution would be externalized. No system-prompt modification would be required.

Suggested backend contract

The existing internal agent-control boundary appears to be a natural integration point. An external backend would need operations equivalent to:

• spawn: task/message, role or agent type, workspace, context-fork policy, model settings, and capability policy
• send message / follow-up
• interrupt or cancel
• list/get status
• wait for state changes or completion
• close and process-tree cleanup

It should return stable opaque child handles and compact structured results that Codex can translate into its existing native tool outputs.

The backend should declare supported capabilities. Codex should fail closed when a requested semantic cannot be represented, rather than silently broadening permissions or dropping configuration. Examples include:

• unsupported context-fork modes
• unavailable per-child model overrides
• inability to enforce requested tool restrictions
• missing cancellation or follow-up support

Security and isolation

• native remains the default backend.
• External backends are explicitly configured and locally trusted, similar to MCP servers.
• Permission, sandbox, workspace, and capability information is passed explicitly.
• The adapter must not receive secrets unrelated to its declared configuration.
• Cancellation and timeout handling must terminate the external process tree.
• Backend stdout/stderr should remain diagnostic data and not automatically enter model context.
• Codex should surface compatibility failures rather than silently falling back to a different execution mode.

Example use case

A user uses Codex for architecture and difficult reasoning while delegating repository exploration and implementation to a separately installed coding-agent CLI. The external CLI already provides thin native subagents and its own authenticated tool environment.

The adapter launches those native workers and maps their lifecycle to Codex's existing collaboration tools. From the model's perspective, nothing changes: it calls the same spawn_agent and management tools with the same schemas and receives the same compact results. From the user's perspective, delegated work uses the selected external runtime without adding prompt instructions or polluting the main Codex context with terminal output.

Related work

• #11701 covers per-agent configuration and orchestration, but assumes Codex-native child execution.
• #20204 tracks incomplete PreToolUse coverage across handlers.
• #21753 tracks broader hook parity, including missing subagent lifecycle events.
• #32749 adds model overrides to multi-agent v2 spawn, showing that spawn configuration is actively evolving.

Even with complete hook coverage, a first-class backend remains useful because interception needs to replace execution and preserve the native lifecycle—not merely observe, allow, deny, or mutate a tool call.