Codex adapter: opt-in guidance for concurrent subagent dispatch

[huiyu]

Phenomenon

In daily use, Codex rarely dispatches subagents concurrently, while Claude Code with DevMuse fans out routinely. Same skills, different throughput on decomposable work.

Current design (deliberate, recorded)

• docs/architecture.md: "The adapter boundary is deliberate: workflow content is shared, while invocation, subagent, hook, memory, and safety semantics remain host-native."
• adapters/codex/HOST_POLICY.md: "DevMuse augments Codex; it does not replace the host's normal agent loop."
• docs/platform-support.md (Why policies differ): only the Claude adapter's routing/subagent behavior is behavior-tested; defaults are intentionally conservative. See Decide host-native plan/review policy for non-Claude runtimes #50 for the original policy decision.

So the Codex adapter ships no orchestration guidance, and Codex's own manager is conservative by default — capability exists but goes unused.

Codex host facts (as of Aug 2026)

• Subagents GA since v0.115.0 (2026-03): up to 6 concurrent, manager/worker model, git-worktree isolation, explorer/worker/default roles
• max_threads / max_depth in config.toml; spawn_agents_on_csv for batch dispatch
• Explicit prompts ("spawn subagents in parallel for these N independent tasks") already work

Proposal to scope

Add opt-in, host-native guidance so DevMuse skills on Codex suggest concurrent subagent dispatch where work is decomposable — e.g. mu-code architectural task execution, mu-review multi-mode review, mu-retro parallel data gathering. Candidate shape: a HOST_POLICY section plus per-skill hints in the generated adapter, expressed in Codex-native terms (roles, worktrees), never overriding the host's manager.

Constraints carried over from recorded decisions

1. Must not replace the host's normal agent loop (HOST_POLICY first principle)
2. Behavior claims require behavior tests on Codex before shipping as default — until then, opt-in only
3. State actual coverage; no implied parity with the Claude adapter
4. Keep single-source generation via build:adapters; no hand-maintained per-host orchestration copies

Out of scope

Safety hook parity (settled in #48) and plan/review policy (settled in #50) stay as decided.

[huiyu]

Technical design options — opt-in Codex subagent guidance

Quick Probe classifies this as an adapter-policy change rather than a new workflow. The source skills already define when tasks are genuinely independent; the missing behavior is a Codex-specific opt-in prompt that translates those conditions into the host's native subagent mechanism.

Current Codex evidence

The current official Subagents documentation says:

• local Codex releases enable subagent workflows by default;
• Codex delegates after a direct request or applicable project/skill instruction;
• parallel work is best started with read-heavy exploration/tests/triage, while write-heavy parallelism needs disjoint write sets;
• built-in roles are explorer, worker, and default;
• subagents inherit the parent sandbox/approval policy.

The current Configuration Reference uses agents.max_concurrent_threads_per_session; agents.max_threads is only a legacy alias. No current official entry was found for the issue's older max_depth or spawn_agents_on_csv claims, so 3.0 guidance must not repeat them.

Options

Option	What it does well	What would make it fail?	Coverage
A. One canonical Codex host guide + generated per-skill opt-in pointers (recommended)	Keeps host facts in one file, makes the guidance visible exactly where decomposition is decided, preserves source workflow semantics, and remains generated/testable.	Fails if generated hints become a second task-decomposition policy, edit user config, auto-dispatch before opt-in, or imply Claude parity without behavior evidence.	Covers the proposal and all four recorded constraints.
B. HOST_POLICY-only paragraph	Very small and centrally visible to maintainers.	Installed skills are not guaranteed to load a sibling root document at decision time, so the observed under-dispatch can remain unchanged.	Covers documentation, not behavior.
C. Ship project .codex/config.toml and custom agents	Can strongly shape roles/models and thread limits.	Mutates target-project policy, overrides user/admin choices, expands DevMuse into host configuration management, and is not necessary for an opt-in prompt.	Overreaches the issue and conflicts with host-native authority.

Recommended contract

Create one canonical host-specific knowledge file, consumed by the adapter generator. The generator:

1. derives adapters/codex/HOST_POLICY.md from the canonical host policy instead of maintaining an unrelated hardcoded copy;
2. vendors the subagent guide into selected generated skills;
3. injects a short pointer only into the Codex variants of:
   • mu-code: when the existing plan analysis finds 3+ genuinely independent tasks with disjoint write sets, offer concurrent worker agents once; dispatch only after acceptance;
   • mu-review: when two or more triggered passes can inspect the same committed range read-only, offer one agent per pass, wait for all, then consolidate without losing file coverage;
   • mu-retro: when evidence gathering has independent read-only lanes, offer explorer agents, then synthesize in the main thread.
4. never changes canonical task thresholds, sandbox/approval settings, model selection, thread limits, or project .codex/ files.

The opt-in wording should be operational rather than aspirational:

“This work has N independent lanes with disjoint/read-only scope. Use Codex subagents concurrently and wait for all results? (yes/no)”

Decline means inline execution with no repeat prompt in that invocation. Acceptance tells the manager how to divide work, which role fits each lane, that write agents require disjoint sets, and that the main thread must wait and consolidate. It does not prescribe a numeric concurrency setting.

Evidence and tests

• Deterministic adapter tests prove the source skills contain no Codex-only policy, generated skills reference the single guide, HOST_POLICY shares the same canonical source, and generated drift is clean.
• Prompt fixtures cover eligible and ineligible cases: 3 disjoint tasks, coupled writes, one task, parallel read-only review passes, and user decline.
• Before making the behavior default, run the installed Codex adapter against those fixtures and record whether it offers, waits, consolidates and avoids write collisions. Until that evidence exists, the shipped behavior remains an explicit user opt-in.

If Option A is approved, implementation can be a bounded adapter-policy PR independent of #62/#63.

[huiyu]

Reopening for the 3.0 restructure. The implementation for this issue has landed but does not yet meet the 3.0 release quality bar. The work now lives on the 3.0 branch (main is held at the last release, v2.2.0); this issue stays open and tracked against the 3.0 branch until it is genuinely release-ready. See the DevMuse 3.0 milestone.