[codex] Add configurable multi-agent mode hint text by shijie-oai · Pull Request #30493 · openai/codex

shijie-oai · 2026-06-29T00:14:03Z

Why

Multi-agent V2 normally derives its mode instructions from reasoning effort: Ultra enables proactive delegation, while other efforts require an explicit request. Some deployments need to provide one configured delegation policy that replaces those built-ins and remains stable when reasoning effort changes.

What changed

Add features.multi_agent_v2.multi_agent_mode_hint_text alongside the existing root and subagent hint settings.
Treat any configured value, including an empty string, as MultiAgentMode::Custom(hint_text), so the configured text replaces the built-in explicit-only and proactive policies.
Persist the full custom variant and hint text in the turn-context snapshot, so the durable comparison baseline detects both reasoning-effort changes and configured policy-text changes.
Preserve the existing explicit-only/proactive behavior when the setting is absent.
Replace the ambiguous MultiAgentMode::None variant with MultiAgentMode::Custom(String) in new rollouts and API schemas. A compatibility wire type maps legacy serialized none values to Custom("") when resuming existing rollouts.
Regenerate the config and app-server schemas.

Configuration examples

The distinction is whether multi_agent_mode_hint_text is present. An empty string is still a configured value and intentionally suppresses the built-in mode instructions.

Unset: preserve existing effort-derived behavior

[features.multi_agent_v2]
enabled = true
# multi_agent_mode_hint_text is omitted

Ultra reasoning uses the built-in proactive delegation instructions.
Other reasoning efforts use the built-in explicit-request-only instructions.

Empty: suppress all mode hint text

[features.multi_agent_v2]
enabled = true
multi_agent_mode_hint_text = ""

This selects effective mode custom at every reasoning effort and injects an empty mode body, suppressing both built-in policies.

Set: always use the configured text

[features.multi_agent_v2]
enabled = true
multi_agent_mode_hint_text = "Delegate to subagents when it will materially improve the result."

This selects effective mode custom at every reasoning effort and injects the configured text verbatim instead of either built-in policy.

Verification

just test -p codex-core multi_agent_mode
- Covers a configured hint across High and Ultra reasoning efforts and verifies the full custom hint is recorded for both turns.
- Covers an empty-string override suppressing both built-in instruction bodies.
just test -p codex-protocol -p codex-app-server-protocol
- Covers legacy none turn-context deserialization as Custom("") and verifies the regenerated schemas.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 58a3a77edd

ℹ️ 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 · 2026-06-29T05:28:29Z

+        if let Some(hint_text) = &self.hint_text {
+            return hint_text.clone();


Cap configured multi-agent hint text

When features.multi_agent_v2.multi_agent_mode_hint_text is configured, this branch returns the raw config string as one developer fragment. The new TOML/schema field is an unconstrained String, so a large value can become a single model-visible item that crosses the >1k manual-review threshold or even the 10K-token hard limit; add a hard cap/truncation at config resolution or render time before injecting it.

AGENTS.md reference: AGENTS.md:L97-L100

Useful? React with 👍 / 👎.

Looked around and no cap enforcement for the other and I am okay with keep it as is for now.

chatgpt-codex-connector · 2026-06-29T05:28:29Z

+        .multi_agent_v2
+        .multi_agent_mode_hint_text
+    {
+        Some(_) => MultiAgentMode::None,


Track configured hint changes in baseline

When a thread already has a configured multi_agent_mode_hint_text, every configured value is collapsed to MultiAgentMode::None here, while the durable TurnContextItem records only that enum. If the app-server reloads config or a rollout is resumed after the configured policy text changes, previous.multi_agent_mode == effective_multi_agent_mode and no incremental developer update is emitted, so the model keeps following the stale policy until a full context reinjection happens; include a bounded hint version/hash in the diff baseline or otherwise force an update when the rendered fragment changes.

AGENTS.md reference: AGENTS.md:L102-L110

Useful? React with 👍 / 👎.

that is okay too - if it was None previously it indicates that we do not have any specific sub agent delegation instruction. And a later resumed None would indicate the same.

chatgpt-codex-connector · 2026-06-29T05:28:29Z

+        if let Some(hint_text) = &self.hint_text {
+            return hint_text.clone();


Clear proactive mode for empty hint overrides

When an existing thread already has the proactive mode message in history and config is changed or resumed with multi_agent_mode_hint_text = "", this returns the empty hint verbatim, so the only new model-visible item is <multi_agent_mode></multi_agent_mode>. Because the context is incremental, the earlier proactive text remains in the request and explicitly says it stays active until a later mode message changes it; emit an explicit inactive/override message for the empty override instead of relying on empty tags to clear that prior policy.

AGENTS.md reference: AGENTS.md:L95-L96

Useful? React with 👍 / 👎.

This is acceptable.

dylan-hurd-oai · 2026-07-02T21:48:58Z

 use codex_protocol::protocol::MULTI_AGENT_MODE_OPEN_TAG;

 const EXPLICIT_REQUEST_ONLY_MULTI_AGENT_MODE_TEXT: &str = "Do not spawn sub-agents unless the user or applicable AGENTS.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work.";
-const NO_MULTI_AGENT_MODE_TEXT: &str = "Multi-agent delegation mode instructions are inactive. Any earlier multi-agent mode developer message no longer applies.";


Why are we removing this?

This is only used by multi_agent_mode:None but that particular option is not reachable. Ultra breaks down to max + multi_agent_mode:proactive and non-ultra breaks down to effort + multi_agent_mode:explicitRequestOnly.

This is a relic when we were supporting multi_agent_mode as an independent param in various location like thread/start or turn/start before folding it into a reasoning effort transformation.

Can we mark None as deprecated then? Ideally we'd remove it as well

I am reusing it - if a custom hint text is provided, multi_agent_mode on the turn is marked as None. But tying to the conversation below maybe we should implement a custom enum type?

Yep, I don't think we should conflate None vs. Custom

dylan-hurd-oai · 2026-07-02T21:52:30Z

 #[derive(Debug, Clone, PartialEq, Eq)]
 pub(crate) struct MultiAgentModeInstructions {
    multi_agent_mode: MultiAgentMode,
+    hint_text: Option<String>,


It feels like it might be simpler to create MultiAgentMode::Custom and store hint_text inside that enum variant?

dylan-hurd-oai · 2026-07-03T01:12:56Z

 }

+fn configure_custom_mode_hint(config: &mut Config) {
+    configure_multi_agent_v2(config);


We should document that this function implicitly enables v2

shijie-oai added the code-reviewed label Jun 29, 2026

github-actions Bot mentioned this pull request Jun 29, 2026

📊 AI CLI 工具社区动态日报 2026-06-29 zx0828/big_model_radar#193

Open

shijie-oai force-pushed the shijie/multi-agent-mode-hint-text branch from ce63391 to 8e2d3a0 Compare June 29, 2026 04:26

github-actions Bot mentioned this pull request Jun 29, 2026

📊 AI CLI 工具社区动态日报 2026-06-29 96loveslife/big_model_radar#73

Open

shijie-oai force-pushed the shijie/multi-agent-mode-hint-text branch from 8e2d3a0 to 58a3a77 Compare June 29, 2026 05:15

shijie-oai marked this pull request as ready for review June 29, 2026 05:16

shijie-oai requested a review from a team as a code owner June 29, 2026 05:16

chatgpt-codex-connector Bot reviewed Jun 29, 2026

View reviewed changes

shijie-oai added a commit that referenced this pull request Jun 29, 2026

codex: fix CI failure on PR #30493

3db4362

dylan-hurd-oai reviewed Jul 2, 2026

View reviewed changes

shijie-oai added 3 commits July 2, 2026 17:22

Add configurable multi-agent mode hint text

20d36ee

codex: fix CI failure on PR #30493

248c46c

codex: distinguish custom multi-agent mode

a3c3ed3

shijie-oai force-pushed the shijie/multi-agent-mode-hint-text branch from 3a9ca01 to a3c3ed3 Compare July 3, 2026 00:22

codex: persist custom hint in multi-agent mode

329c5f1

shijie-oai requested a review from dylan-hurd-oai July 3, 2026 01:10

dylan-hurd-oai approved these changes Jul 3, 2026

View reviewed changes

codex: document multi-agent test setup

e2a559d

shijie-oai merged commit da4c8ca into main Jul 3, 2026
35 checks passed

shijie-oai deleted the shijie/multi-agent-mode-hint-text branch July 3, 2026 01:44

github-actions Bot locked and limited conversation to collaborators Jul 3, 2026

		if let Some(hint_text) = &self.hint_text {
		return hint_text.clone();

Uh oh!

Conversation

shijie-oai commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why

What changed

Configuration examples

Unset: preserve existing effort-derived behavior

Empty: suppress all mode hint text

Set: always use the configured text

Verification

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shijie-oai Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

shijie-oai commented Jun 29, 2026 •

edited

Loading

shijie-oai Jul 2, 2026 •

edited

Loading