Expose thread-level multi-agent mode

[shijie-oai]

Why

Once multi-agent mode can be selected per turn, clients also need to choose the initial selection when creating a thread and observe that selection through lifecycle and settings APIs.

The selected value is intentionally distinct from the effective model-visible value: no client selection is represented as null, even though an eligible multi-agent v2 turn derives explicitRequestOnly as its effective default.

What changed

• Add the optional experimental thread/start.multiAgentMode parameter and pass it through thread creation.
• Preserve an omitted initial value as an unset selection rather than eagerly storing explicitRequestOnly.
• Apply an explicit thread/start selection to the first turn through the session configuration established at thread creation.
• Restore the latest persisted effective mode as the selected baseline on cold resume when rollout history contains one.
• Inherit the optional selected mode from a loaded parent when creating related runtime threads.
• Return the current selected multiAgentMode from thread/start, thread/resume, thread/fork, and thread settings, using null when no mode is selected.
• Keep lifecycle reporting independent from model capability and feature eligibility; core turn construction remains responsible for calculating and persisting the effective mode.

Not covered

• Clearing an existing loaded-session selection back to unset through turn/start; omitted or null currently retains the session's selection.
• A TUI control, slash command, or config.toml preference.

Verification

• CARGO_INCREMENTAL=0 just test -p codex-app-server-protocol
• CARGO_INCREMENTAL=0 just test -p codex-app-server multi_agent_mode

The focused app-server coverage verifies explicit thread/start initialization, first-turn prompting, nullable reporting for an omitted selection, and retention of selections that are not currently runtime-eligible.

Stack

Stacked on #28685. This PR contains only the thread initialization and lifecycle/settings API layer.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6a0aad7247

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Preserve selected mode across cold resume

When thread/start.multiAgentMode is supplied, this only seeds the live session; cold resume reconstructs the setting from conversation_history.get_multi_agent_mode(), which reads the persisted effective turn mode rather than the selected thread mode. In inspected app-server resume/fork paths, this means a thread started with proactive can later resume as null if it had no turns or as explicitRequestOnly/null when the selected mode was not applicable or was downgraded for the turn, so clients cannot recover the selected thread-level mode the new lifecycle API promises. Persist and restore the selected mode separately from the effective model-visible mode.

AGENTS.md reference: AGENTS.md:L103-L110

Useful? React with 👍 / 👎.