Feature request: add structured work and return contracts to native subagent spawn

[joshmouch]

What variant of Codex are you using?

Codex Desktop and other tool-backed Codex sessions that expose native subagent spawning.

What feature would you like to see?

Add an optional structured work contract to the native subagent spawn API, separate from the prose message, and add a matching structured terminal return.

Today a parent has one prose message field in which to combine the goal, architectural premises, deliverable, acceptance criteria, stop condition, delegation policy, and expected return shape. The child returns a prose summary. This works for small tasks, but it makes important lifecycle terms implicit, invites prompt-string parsing, and gives the parent no typed way to distinguish an accepted result from an incomplete or blocked return.

A backward-compatible request shape could be:

{
  "task_name": "review_auth_change",
  "message": "Review the authentication changes.",
  "contract": {
    "goal": "Determine whether the change preserves the authentication invariants.",
    "premises": ["The existing policy module remains the canonical owner."],
    "deliverable": "A concise evidence-backed review.",
    "acceptance": ["Inspect every changed authentication path.", "Report exact file and line evidence."],
    "stop_condition": "Return when all changed paths are classified or an exact blocker is identified.",
    "delegation": "none",
    "return_schema": {
      "status": "completed | incomplete | blocked",
      "summary": "string",
      "changed_paths": ["string"],
      "acceptance_results": [{"criterion": "string", "status": "passed | failed | not_run", "evidence": "string"}],
      "open_work": ["string"]
    }
  }
}

The exact names are flexible. The important boundary is that lifecycle and result fields are native structured data, not a second prompt framework or a child-artifact subsystem.

The child should receive both the human instruction and structured contract without parsing conventions from prose. The parent and UI should retain the effective contract, and a terminal child event should include a typed result conforming to the declared return shape. Existing callers that send only message should remain unchanged.

Why this is useful

The official Subagents guidance recommends bounded tasks and prompts that state the division of work, wait behavior, and expected output. A structured contract gives those concerns a stable machine-readable home while preserving ordinary prose for the actual task.

It also makes delegation reviewable: a parent can determine whether acceptance was actually run, what remains open, and whether a child stopped because it completed, was blocked, or returned an incomplete result. Concise structured returns should be sufficient for normal delegation; raw child transcripts and a new artifact subsystem are not required.

Acceptance criteria

• Native spawn accepts an optional structured contract independently of the prose message.
• The contract can express goal, premises or constraints, deliverable, acceptance criteria, stop condition, delegation policy, and return schema.
• The child receives the contract as structured context without prompt-string parsing.
• Parent-visible task state and UI preserve the effective contract.
• Every terminal child event includes an explicit status and a structured result or typed reason that no result exists.
• Existing message-only spawning remains backward-compatible.
• The design does not require a separate child-artifact store; concise typed returns remain the default result channel.

Related issues

• Subagents can shut down without delivering results; fork_turns none scouts acted as orchestrators #26822 concerns children shutting down without a parent-delivered result. This request defines the successful and unsuccessful terminal return contract rather than reproducing that lifecycle bug.
• Add Claude Code-style reusable subagent types to MultiAgentV2 spawn_agent #32418 requested reusable named subagent types. This request is about the contract of one delegated work instance, independent of the child role selected.
• Regression: encrypted MultiAgentV2 messages remove readable task audit trail #28058 concerns readable audit retention for encrypted subagent messages. This request concerns typed work semantics and typed returns.
• Desktop app: subagent capabilities vary by task without selectable controls or clear UI distinctions #41935 concerns selecting interactive versus output-only child surfaces. This contract can apply to either child interaction mode.