codex-subagent-orchestration.md

Codex Peer Task Orchestration

LoopX supports two different concepts that must not be conflated:

• durable registered agents are equal peers;
• a host runtime may launch an ephemeral child worker for one bounded task.

No registered identity owns the goal. Claims, leases, task boundaries, capabilities, and continuation policy decide who acts. When parallel work is useful, LoopX may choose one temporary task coordinator from the participating peers. That responsibility ends with the task bundle.

Peer Runtime Contract

A registered identity uses agent_model=peer_v1. It has no rank-bearing role, implicit review authority, or permanent writeback ownership. A task coordinator may:

• activate or resume eligible peer lanes;
• issue complete briefs to ephemeral child workers;
• aggregate returned evidence;
• write accepted task-bundle state and account for the completed turn.

It does not own durable goal authority. Repository policy, explicit decision scopes, and todo continuation still govern review, merge, publication, and production actions.

When To Parallelize

The default policy is adaptive orchestration, not a user-selected single-agent or multi-agent mode. LoopX projects ready work and hard boundaries; the task coordinator decides whether parallel execution shortens the critical path, which todos to delegate, and which qualified host context to use.

Parallelize when it reduces uncertainty or latency:

• map disjoint code, docs, test, or runtime surfaces;
• implement isolated slices in independent worktrees;
• run an independent review or validation pass;
• inspect separate adapter, evidence, or boundary questions.

Keep tightly coupled decisions in one peer lane. Do not launch workers merely to make the activity graph look busy, and never let worker count override quota, user gates, write scope, or repository policy.

Adaptive Admission

task_orchestration_contract_v2 admits ephemeral child work only when the current runtime explicitly reports subagent_spawn through observed capabilities and at least two coordinator-owned or unclaimed ready advancement todos remain. A host name or scheduler runtime profile is metadata and never supplies subagent_spawn or subagent_resume. Each candidate is checked against:

• task_domain and the goal's allowed_domains;
• todo status, resume_ready, and open user dependencies;
• required_capabilities and observed host capabilities;
• canonical task_repository identity when declared (otherwise the goal repository remains authoritative); and
• goal-authorized, mutually non-overlapping required_write_scopes.

Rejected candidates remain visible in blocked_lanes with typed reason codes. Ready lanes beyond max_children remain visible as capacity_deferred. To stay inside the TurnEnvelope budget, the signed contract carries one shared child_brief_defaults block plus a bounded per-lane delta. The typed host request combines them into a complete subagent_control_plane_handoff_v0 brief. The coordinator may still keep the work serial; admission is permission and capacity, not a command to spawn.

Without subagent_spawn, LoopX preserves the existing task_orchestration_contract_v1 registered-peer activation path. This keeps long-lived peer identity, leases, worktrees, and multi-round collaboration explicit instead of turning them into the default child-worker mechanism.

Fresh, Fork, Or Resume

The temporary task coordinator chooses a worker context from the work shape:

Work type	Context	Required task brief
Broad mapping, prior-art search, risk discovery	Fresh worker	Objective, authority source, allowed sources, boundary, expected output, non-goals
Independent review or adversarial validation	Fresh worker	Claim under review, exact evidence, validation command, acceptance and merge rules
Failed-smoke repair or review-comment follow-up	Resume or fork	Worktree, failing evidence, latest patch, next bounded repair
Disjoint implementation	Fresh worker in an independent worktree	Claimed todo, allowed paths, write scope, validation, continuation policy
Long-running claimed lane	Resume the registered peer task	Agent id, todo or lease, latest accepted evidence
Production action or emergency rollback	No automatic worker	Operator approval, stop condition, reversible command plan

Fresh workers are useful only when the task coordinator can provide a complete brief. Missing authority, scope, expected output, or validation is a planning gap, not a reason to launch an under-specified worker.

Shared Control Plane Handoff

Every child-worker brief starts from the shared control plane. A worker must not infer current authority from chat history, an old packet, or another worker's summary.

The existing host-child packet name remains subagent_control_plane_handoff_v0 for compatibility. Its lineage fields do not create durable rank:

• parent_goal_id: shared goal lineage, not an owner identity;
• authority_artifact: current goal, policy, or review authority;
• latest_state_ref: state hash, run id, or generated-at value to read first;
• quota_gate_snapshot: current eligibility, wait, or gate state;
• evidence_boundary: allowed sources, paths, and public/private rule;
• writeback_spend_contract: who may accept evidence and account for the turn;
• child_decision: continue, wait, or reuse_existing_evidence.

Only then should the brief include todo id, work scope, expected artifact, validation, and continuation policy. The compact rule is: child worker reports evidence only; the temporary task coordinator writes accepted state and spends.

subagent_control_plane_handoff_v0:
  parent_goal_id: example-peer-task-goal
  authority_artifact: .codex/goals/example-peer-task-goal/ACTIVE_GOAL_STATE.md
  latest_state_ref: state_hash_or_run_id
  quota_gate_snapshot: eligible
  evidence_boundary: public-safe read-only repository map
  writeback_spend_contract: child worker reports evidence only; task coordinator writes accepted state and spends
  child_decision: continue
goal_id: example-peer-task-goal
todo_id: todo_docs_map
work_scope: inspect docs and return evidence paths
validation: cite files and residual risk; do not edit
continuation_policy: independent_handoff

After explicit capability admission, the signed Turn host request uses legitimate host metadata only to map supported native context operations. The host name does not admit child work. The task coordinator chooses from that catalog:

• Codex exposes fresh and resume;
• Claude Code exposes fresh through its native Task surface;
• generic adapters expose no child capability unless the adapter declares one.

fork stays out of the public execution catalog until a real host adapter proves versioned execution state, copy-on-write workspace isolation, capacity reservation, branch lease, held-result settlement, cancellation, and recovery. Context choice is advisory execution strategy and cannot widen LoopX authority.

Claims, Leases, And Worktrees

Registered peers claim work through LoopX todos and leases. The control plane allows one pending lease for (goal_id, todo_id). goal_id is the shared control-plane lane; todo_id is the work item being claimed. A host child may carry the claim context in its brief, but it does not become a ranked agent.

Repository-writing peers and child workers use independent worktrees. Overlap is resolved through task boundaries and repository policy, not through a permanent controller. Completion uses typed continuation:

• independent_handoff: leave the successor available to peers;
• same_agent_non_delivery: keep a non-delivery follow-up with the same peer.

Review remains action_kind=review over independent_handoff. Add the author to excluded_agents only when the successor should stay open for eligible peers but must not be reclaimed by that author.

Enabling Bounded Orchestration

The feature remains opt-in:

loopx configure-goal \
  --goal-id example-peer-task-goal \
  --multi-subagent-feature enabled \
  --max-children 2 \
  --allowed-domain docs \
  --allowed-domain validation \
  --execute

multi_subagent remains the compatibility name for host child-worker capacity and permission policy. It does not ask the user to select a run mode or agent hierarchy. With host child capability, quota should-run projects adaptive task_orchestration_contract_v2; without it, the registered-peer compatibility path remains task_orchestration_contract_v1. Dormant registered agents and closed, blocked, or deferred todos are not coordinator candidates.

Use --multi-subagent-feature off to disable worker spawning. The low-level --orchestration-mode and --spawn-allowed flags remain available for host integrations.

Run History And Observation

Run history should attribute task coordination without persisting rank:

{
  "agent_model": "peer_v1",
  "task_coordinator": "codex-alpha",
  "control_plane_handoff_version": "subagent_control_plane_handoff_v0",
  "peer_lanes": [
    {"agent_id": "codex-beta", "todo_id": "todo_docs_map", "state": "completed"},
    {"agent_id": "codex-gamma", "todo_id": "todo_validation", "state": "running"}
  ],
  "accepted_evidence_count": 1,
  "next_action": "review the remaining validation evidence"
}

Useful observation surfaces include task bundle, participant peers, worker context (fresh, fork, or resume), accepted or rejected evidence, leases, worktrees, quota state, and typed continuation. They must not reconstruct a durable leader from a temporary coordination event.

Safety Rules

• Do not spawn when quota or the selected user gate blocks the task.
• Do not infer permissions from an agent name, profile label, or old prompt.
• Do not launch a fresh worker without a complete task brief.
• Do not put credentials, private links, raw logs, or production material in a public handoff packet.
• Keep implementation scopes disjoint and use independent worktrees.
• Let repository policy decide review and merge; peer identity grants neither.
• Let one temporary coordinator accept bundle evidence and write one spend event after validated progress.

The result is parallel execution without a permanent leader: durable agents remain peers, while task coordination and host-child relationships stay bounded to the work that requires them.