Orchestrated multi-agent mode PoC

Open 💬 2 comments Opened Jul 10, 2026 by yusing

What variant of Codex are you using?

CLI

What feature would you like to see?

True, native orchestrated mode. No subagents spawning/polling.

Here is a PoC implementation of #21998: https://github.com/yusing/codex. Since PR is invitation only, I'm posting it here.

Summary

This fork adds an experimental Orchestrated mode: a bounded workflow that assigns task framing, repository investigation, planning, execution, and review to explicit internal roles before the root agent completes the turn.

The mode has two paths:

Direct execution for narrow follow-ups whose scope and evidence are already established, such as fixing one previously identified documentation mismatch.
Reviewed execution for material work that needs fresh investigation, plan approval, implementation, and result review.

This split keeps the full safety workflow for complex changes without forcing every small correction through redundant exploration and review. Worker owns implementation and verification. Explorer remains read-only even when the parent turn has full filesystem permissions. Root orchestrator coordinates decisions and emits a short final synthesis instead of repeating the Worker packet.

This remains a proof of concept and reference implementation, not a claim of production readiness.

Why this exists

Existing multi-agent controls decide whether delegation is available. They do not define a complete workflow for questions such as:

What evidence must exist before implementation starts?
Which role owns mutation and verification?
How is a material plan approved before tools can change state?
How are incomplete, malformed, or unverified Worker results handled?
How can small, already-bounded follow-ups avoid unnecessary model calls?
How much internal tool history can enter model-visible context?
What happens when a user-facing spawned agent also uses Orchestrated mode?
How do internal phases avoid recursively starting another orchestration pipeline?

This fork makes those choices explicit through phase contracts, tool boundaries, bounded packets, proportional routing, approval gates, revision limits, inherited mode behavior, and role attribution.

Several implementation details evolved while the orchestration design was tested:

Explorer and targeted Plan Evidence have shell access, but run under enforced read-only permissions.
Worker owns mutation-capable execution after approval, or immediately after a strictly bounded direct contract.
Narrow follow-ups can bypass redundant exploration, planning, and result review.
Malformed or truncated Worker packets return directly to Worker instead of consuming a Result Review attempt.
Root synthesis is intentionally short and must not restate an already complete Worker report.

Execution model

Orchestration is sequential and bounded. It does not run phases concurrently.

flowchart TD
    U[User turn] --> C{Task Contract}

    C -->|Direct: narrow scope and existing evidence| WD[Worker execution]
    WD -->|Latest packet is non-truncated<br/>worker: complete| SD[Short root completion]
    WD -->|Malformed, truncated,<br/>or worker: incomplete| WDR{Retry budget left?}
    WDR -->|Yes| WD
    WDR -->|No| DF[Short root failure:<br/>report remaining corrections]

    C -->|Reviewed: material, uncertain,<br/>or direct contract was truncated| E[Read-only Explorer]
    E -->|Bounded evidence packet| P[Worker Plan]
    P --> PR{Plan Review}

    PR -->|One unanswered material question round| PE[Read-only targeted evidence]
    PE --> PR
    PR -->|Plan needs correction| PBR{Plan revision budget left?}
    PBR -->|Yes| P
    PBR -->|No| PF[Short root failure:<br/>plan not approved]
    PR -->|Approved| W[Worker execution]

    W -->|Malformed or truncated packet| WR{Worker revision budget left?}
    WR -->|Yes| W
    WR -->|No| RF[Short root failure:<br/>report remaining corrections]

    W -->|Valid complete or incomplete packet| RR{Result Review}
    RR -->|Approved and worker was complete| S[Short root synthesis]
    RR -->|Revise, invalid review,<br/>truncated review, or worker incomplete| WR

    SD --> A[Final response]
    DF --> A
    PF --> A
    RF --> A
    S --> A

Both successful and exhausted paths still use one final root model request so output-schema and client lifecycle behavior remain intact. Its prompt constrains successful synthesis to a one-line orc: confirmation and exhausted synthesis to remaining corrections only; the runtime does not construct that natural-language line itself.

Direct execution

Task Contract may emit task-contract: direct only when work is already bounded by conversation evidence and does not need a new plan-review cycle. Direct work must have no unresolved user choice, security impact, external side effect, or broad code-behavior change. Intended examples include:

Applying one previously reviewed documentation correction.
Completing a small follow-up with known files, exact scope, and explicit verification.
Re-emitting or correcting a compact packet when underlying work is already complete.

Direct execution skips Explorer, Worker Plan, Plan Review, Plan Evidence, and Result Review. Worker still owns implementation, current-state inspection, and required verification. Malformed, truncated, and valid worker: incomplete packets return directly to Worker within the normal retry limit. Only the latest non-truncated worker: complete packet authorizes short root completion; exhausted retries produce a short failure report instead of a completion claim.

Material code changes, ambiguous requests, new architecture, broad reviews, security-sensitive work, and tasks lacking repository evidence use the reviewed path.

Reviewed execution

Reviewed execution uses these phases:

Task Contract translates the user request into objective, scope, constraints, non-goals, done criteria, and verification expectations.

Explorer inspects repository state and returns source-of-truth anchors, likely tests, and risks. Its shell executes under read-only permissions regardless of broader parent permissions. Explorer evidence describes pre-execution state.

Worker Plan converts the contract and Explorer evidence into an implementation plan covering files, intended changes, verification, and risk.

Plan Review checks alignment and evidence. Existing Explorer evidence remains valid; Plan Review requests targeted evidence only for material questions not already answered by available packets.

Plan Evidence answers only those focused questions through read-only inspection. It does not repeat broad exploration or execute project behavior.

Worker Execution owns edits, commands, tests, and verification after plan approval. Worker must emit worker: complete only when done criteria pass; otherwise it emits worker: incomplete.

Result Review checks a valid Worker packet against the contract and approved plan. Explorer state is treated as a pre-execution baseline, not as proof that later Worker changes did not occur. Raw Worker tool history is intentionally compacted, so concrete command and result statements in the Worker packet are the review evidence.

Root Synthesis reports the approved outcome briefly. It references the approved Worker result without duplicating its full changed-file, test, and risk sections. If plan or work retries are exhausted, Root reports only the remaining corrections and does not claim completion.

Packet and retry semantics

Each phase emits one role-prefixed packet. Prompts target packets under 2 KiB. General phase packets have an 8,192-byte hard ceiling to tolerate small model-side budget misses; Plan Evidence has a separate 1,000-token hard cap.

After each phase, raw phase history is replaced with its compact packet. This keeps model-visible history bounded and prevents Worker tool logs from being replayed into every later request.

Compaction creates explicit review rules:

Worker packet carries changed files, verification commands and results, failures, and unresolved risks.
Result Review must not demand raw tool calls that compaction intentionally removed.
Explorer packet is a pre-execution baseline and cannot contradict a later verified Worker result solely because Explorer observed an unchanged worktree.
A packet missing its expected phase prefix is invalid.
Malformed or truncated Worker packets return directly to Worker for a corrected packet; they do not run Result Review.
On the reviewed path, worker: incomplete is valid and runs Result Review so bounded corrective guidance can be produced. Runtime still requires both a complete Worker packet and Result Review approval before successful synthesis.
On the direct path, worker: incomplete returns directly to Worker because Result Review is intentionally skipped.
Direct completion considers only the latest Worker packet. A superseded or truncated worker: complete packet cannot authorize success.
Plan and work retries remain hard-limited. Exhaustion returns remaining corrections without a false completion claim.

Tool and permission model

Task Contract, Worker Plan, Plan Review, and Result Review

These phases receive no tools. They frame, plan, and decide from bounded packets.

Explorer and Plan Evidence

These phases receive shell inspection tools only. Their phase context is forced to read-only filesystem access with no escalation path, even when parent turn uses workspace-write or full-access permissions.

This distinction matters: hiding apply_patch alone does not make a shell read-only. Filesystem policy enforces the role contract.

Worker

Worker receives mutation-capable shell, core utility, MCP, extension, dynamic, and collaboration tools only after reviewed-plan approval or a direct task contract. Worker cannot recursively spawn another internal orchestration pipeline.

User-facing spawned agents inherit Orchestrated mode. Internal roles use phase-specific context, preventing recursive orchestration fanout.

What changed

Core orchestration

Added Orchestrated phase state machine and role-specific prompts.
Added proportional direct and reviewed execution paths.
Added plan approval before mutation on reviewed work.
Added bounded Plan Evidence, plan-revision, Worker-retry, and result-revision loops.
Added validation so malformed or truncated Worker packets are retried before Result Review.
Added compact phase packets and phase-history compaction.
Added review semantics for compacted tool history and pre-execution Explorer evidence.
Added active-role lifecycle state and token accounting.
Integrated orchestration with normal turn, pending-input, resume, and cancellation behavior.

Multi-agent behavior and safety

Added Orchestrated-mode inheritance for user-facing spawned agents.
Prevented internal phases from recursively launching the full pipeline.
Enforced read-only filesystem access for Explorer and Plan Evidence independent of parent permissions.
Reserved mutation and collaboration tools for Worker after approval or direct routing.
Preserved selected sandbox and approval behavior for Worker execution.
Aligned collaboration-mode templates with Worker-owned implementation and concise root synthesis.

Protocol and app-server surfaces

Added Orchestrated mode to protocol configuration.
Added active-role events and app-server notifications.
Added per-role token usage to thread token accounting.
Updated thread lifecycle and resume behavior.
Regenerated affected app-server JSON schemas and TypeScript types.
Updated app-server documentation for exposed behavior.

TUI

Added active-role status and role-model rendering.
Added role attribution to history messages, patches, and execution cells.
Added Orchestrated-mode status and token metrics.
Updated snapshots for role labels, status surfaces, and execution attribution.

Tests

Integration and UI coverage includes:

Full reviewed phase ordering.
Direct-contract routing without exploration, planning, or review.
Direct-worker retry exhaustion without a false completion claim.
Plan approval before Worker tool access.
Existing Explorer evidence reuse and targeted Plan Evidence.
Bounded plan and work revisions.
Malformed and truncated Worker packet retries before Result Review.
Worker correction after worker: incomplete.
Result Review behavior with compacted Worker execution history.
Explorer read access and denied writes across read-only, workspace-write, and full parent permissions.
Plan Evidence write denial under permissive parent permissions.
Write-denial assertions against the selected local or remote executor filesystem.
Worker shell and collaboration-tool access.
Spawned-agent Orchestrated-mode inheritance.
Internal-role recursion prevention.
Protocol serialization, token accounting, and thread resume.
TUI role status, history, patch, execution, and snapshot rendering.

Model-visible context and cost controls

Orchestrated mode deliberately bounds context growth:

Raw internal tool histories are removed after each phase.
Phase packets have hard size limits.
Plan Evidence answers only focused questions.
Direct routing skips redundant phases for already-proven work.
Invalid Worker packets retry without spending a Result Review call.
Root synthesis stays short instead of repeating Worker output.
Role-specific model and reasoning settings allow tool-heavy work to run on configured cheaper models while root decisions remain on the orchestrator model.

These controls reduce repeated input, output, and latency while preserving review gates for tasks that need them.

Change size

Current committed origin/main..HEAD range changes 109 files with:

+5,050 / -208 lines overall
+1,719 / -203 lines of non-test/runtime source
+3,331 / -5 lines of tests and other excluded artifacts

Non-test/runtime count is path-based and excludes:

Files under test directories.
tests.rs and *_tests.rs files.
Snapshot files.
Generated files under app-server-protocol/schema/.
app-server/README.md.

It includes runtime Rust source, configuration, collaboration-mode templates, protocol implementations, and TUI implementation. Test-only sections embedded inside otherwise-runtime source files are not separated by this calculation.

These numbers reflect current committed range. Refresh them after repair commits land.

Runtime changes concentrate in:

codex-rs/core/src/session/orchestrated.rs
codex-rs/core/src/session/orchestrated/prompts.rs
session and turn lifecycle code
multi-agent spawn/config propagation
protocol and app-server role events
TUI role attribution and status rendering

Largest test addition is codex-rs/core/tests/suite/multi_agent_mode.rs.

Related merged work

This builds on existing collaboration and multi-agent foundations:

| PR | Relationship |
| --- | --- |
| #28685 — Add per-turn multi-agent mode, merged 2026-06-19 | Added per-turn delegation selection, bounded mode context, and durable effective-mode handling. |
| #28792 — Expose thread-level multi-agent mode, merged 2026-06-19 | Added thread initialization, lifecycle reporting, resume behavior, API representation, and inherited selected-mode groundwork. |
| #29324 — Simplify multi-agent mode controls, merged 2026-06-22 | Consolidated live delegation policy around multiAgentMode. |
| #29067 — Namespace multi-agent v2 tools under collaboration, merged 2026-06-23 | Moved model-visible collaboration tools and hints under functions.collaboration.*. |

Those PRs established policy, lifecycle, inheritance, and collaboration-tool surfaces. They did not implement this staged orchestration protocol.

Verification

Primary verification target is codex-core integration coverage in core/tests/suite/multi_agent_mode.rs, plus affected protocol, app-server, and TUI suites.

Required final checks:

just fmt
just test -p codex-core
just test -p codex-app-server-protocol
just test -p codex-app-server
just test -p codex-tui
just fix -p codex-core
Relevant schema generation and pending-snapshot review when those surfaces change

Proof-of-concept status

Implementation was developed rapidly and remains experimental. Main goal is a concrete end-to-end reference for evaluating orchestration semantics, cost, safety, and UX.

Production-readiness review still needs to cover:

Direct-contract classification accuracy and resistance to scope drift.
Prompt injection and adversarial role-output handling.
Filesystem and network isolation for read-only phases across Linux, macOS, Windows, and remote executors.
Failure, cancellation, retry, compaction, and resume semantics.
Token, context, latency, and cost budgets under realistic workloads.
Partial execution and interrupted-session recovery.
Result-review calibration with compacted execution evidence.
Observability and attribution across internal phases.
API stability for role and token-usage events.
TUI behavior during long-running or repeatedly revised phases.
Evaluations showing when direct and reviewed routing improve outcomes.

This PR exists to make those questions inspectable and testable through one coherent implementation.

Additional information

Example config

# config.toml
[orchestrated_mode]
orchestrator_model = "..."
orchestrator_reasoning_effort = "..."
worker_model = "..."
worker_reasoning_effort = "..."
explorer_model = "..."
explorer_reasoning_effort = "..."

Example session

Token usage

| Model | Cached input | Uncached input | Output | Reasoning | Total |
|---|---:|---:|---:|---:|---:|
| gpt-5.6-sol | 251,904 | 85,541 | 7,126 | 2,257 | 344,571 |
| gpt-5.6-luna | 486,912 | 149,827 | 10,412 | 1,399 | 647,151 |
| gpt-5.6-terra | 58,112 | 95,579 | 3,480 | 789 | 157,171 |
| Total | 796,928 | 330,947 | 21,018 | 4,445 | 1,148,893 |

Screenshots

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗