codex-mmo/docs/ORCHESTRATION_BACKENDS.md

Orchestration Backends

Codex MMO supports three profile-level orchestration modes:

[coordination]
orchestration = "mcp"     # or "native" or "hybrid"

Each non-root agent declares one or more executable backends compatible with the profile mode.

Agent MCP

Agent MCP runs each participant through an isolated detached runner that privately hosts a persistent Codex app-server thread. Callers use the authenticated local mmo_mesh STDIO supervisor; they never connect to app-server or a worker control socket directly.

Mechanically enforced properties

• Exact role, model, route, and reasoning binding.
• Caller authentication and durable lineage.
• Directed can_spawn edges and exact per-target/action controls grants.
• Maximum depth and ancestor-role rejection.
• Reusable active-agent and active-child limits.
• Per-role concurrent max_active limits; terminal workers release their admission slots for later sequential work.
• Global weighted resource limits.
• Sandbox ceiling.
• Task-kind, task-size, goal/turn lifecycle, token ceilings, warning-only stalls, finalization grace, reasoning-effort allowlist, and attachment admission.
• Isolated writer worktrees, explicit scope leasing, patch capture, and conflict rejection.
• Structured output-contract, command-evidence, artifact-hash, and literal-task validation.
• Explicit result read/accept/reject disposition and root-controlled patch integration.
• Result visibility.
• Opaque-run compare-and-swap inspect, filtered trace, steer, interrupt, pause, same-thread continue/token extension, detach, full stop, evidence-only finalize, compact, pending-request response, allowed effort changes, and fork.
• Codex goal token accounting or clock-free turns; stall intervals warn without interruption and the model never tracks time.
• Transport/host recovery on the exact thread, recoverable suspension, graceful stop, immediate cancellation, and descendant cascades.
• Persistent prompts, headerless app-server protocol events, terminal history, pending requests, stderr, partial/final result, disposition, patch/artifact, route, metadata, and audit logs.

Costs

• A detached runner, private Unix app-server host, and generated home per active worker. A lost host may be replaced only to resume its exact durable thread.
• Higher launch latency than a native subagent.
• Separate model context rather than a shared native thread.

Appropriate work

Use MCP for:

• Low-trust or inconsistent models.
• Long-running asynchronous work.
• Route/model pinning that must be auditable.
• Participant-to-participant delegation.
• Work requiring isolated writes and explicit integration.
• Strict result contracts.
• Jobs that may need live steering, interruption, continuation, compaction, finalization, or independent forking.
• Slow or long-horizon jobs whose useful evidence must survive transport/host failure.
• Independent branches where context isolation is useful.

Codex native subagents

Native agents are generated as Codex custom-agent files and launched through Codex’s own subagent tools.

Advantages

• Lower launch overhead.
• Natural /agent inspection plus app-server-backed steering/interrupt/pause/continue/detach/stop once a native run is observed.
• Tight integration with the root Codex session.
• Effective for fast read-heavy parallel investigations.
• Built-in Codex models retain their native provider behavior and authentication.

Enforcement boundary

Codex MMO can generate a native role with a pinned model, provider, reasoning level, description, and instructions. It cannot intercept every native spawn and tool action. Consequently:

• Directed graph and child limits are conveyed to the model but are not mechanically intercepted for a pure native nested tree.
• Per-job isolated worktrees, write-scope leasing, result disposition, and patch integration are unavailable.
• Output contracts are advisory (contract_enforcement = "warn") rather than supervisor-validated; the compiler rejects strict on a native-only role.
• Native writers share the workspace and require disjoint assignments plus root diff review. All featured bundled native roles are therefore read-only.
• Native subagents inherit relevant Codex session sandbox/approval behavior.
• Native spawn events may not be completely represented in noninteractive JSON event streams; the live smoke test uses a behavioral completion marker.

Appropriate work

Use native agents for:

• Small read-only investigations.
• Independent code review with no writes.
• Tight, low-latency work under a built-in Codex root.
• Single-model context specialization.
• Work where /agent UX and shared root-host context matter more than strict per-job isolation.

Hybrid mode

Hybrid mode makes both paths available:

[coordination]
orchestration = "hybrid"
native_nested_delegation = false

The recommended topology is:

root
├── native participant      fast first-level branch
│     └── MCP participant   enforceable nested branch
└── MCP participant         durable/strict branch

With native_nested_delegation = false, any child reachable from a native participant must support MCP. The generated native role receives an authenticated mmo_mesh MCP server containing only its allowed children. This gives the first-level native path low overhead while keeping nested depth, resources, scopes, and contracts enforceable.

Setting native_nested_delegation = true allows a profile to instruct native participants to spawn native children directly. Profile compilation emits a warning because those nested edges are advisory. Use this only when native latency is more important than mechanical policy enforcement.

Backend selection in hybrid profiles

A participant can support both:

[agents.expert]
backends = ["mcp", "native"]

The root instructions provide role descriptions and available paths. The default guidance is:

• Native for fast, read-heavy, tightly coupled work.
• MCP for durable, strict, nested, write-scoped, or low-trust work.
• After client or transport recovery, list and inspect retained work before spawning replacements; continue the same suspended job when its objective remains useful.
• Treat a stock-TUI fresh context as a host-owned root generation inside the immutable MMO session/run, not as permission to start a replacement root or session.

Smoke tests must specify a backend when a role supports both:

[[tasks]]
agent = "expert"
backend = "native"

An unspecified hybrid smoke task defaults to MCP because MCP produces stronger observable guarantees.

Root productivity

Every backend uses the same root policy:

1. Determine the immediate critical path.
2. Identify genuinely independent side work.
3. Spawn only work that saves time, isolates noise, adds specialization, or improves confidence.
4. Continue useful non-overlapping root work immediately.
5. Poll or inspect results as needed.
6. Wait only when the next action depends on unfinished output.
7. Reconcile results from primary evidence.
8. Explicitly accept or reject material results, integrate accepted patches, and run canonical validation.

An agent is not useful merely because capacity is available. The configured maximum is a ceiling, not a target.

Contradictions

Profile contradiction policies control generated instructions:

• primary_evidence — resolve from repository, tests, logs, and specifications.
• designated_judge — one role adjudicates after examining evidence.
• root_adjudication — the root makes the final determination.

No policy uses model majority vote as a substitute for evidence.