feat(prompt): guide agents to hold for sub-agents, expect auto-notify, and use inter-agent messages#390
Merged
Conversation
…, and use inter-agent messages Expand the shared multi-agent v2 usage hints (the model-facing agent system prompt for multi-agent sessions) with a full coordination loop that integrates with #364's push-based completion guidance instead of duplicating it: - After spawning, do not busy-poll: never loop wait_agent/list_agents, and do not emit repeated "waiting for agents" / "no agents completed yet" messages. - Completion is push-based (#364 wake_if_idle): a finishing sub-agent's FINAL_ANSWER is delivered to you automatically and an idle parent is woken, so it is safe to stop and wait. Call wait_agent once, only when genuinely blocked on a specific result. - Coordinate mid-flight with send_message (injects a message into the target agent's session, no turn) or followup_task (new task + wakes an idle target); these work parent->child, child->parent, and peer-to-peer (#377). Applied to both DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT and DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT in codex-core config -- the single, model-independent location that every root and sub-agent inherits (no per-model-family prompt variant carries multi-agent guidance). Also note in the send_message tool description that the message is injected into the target agent's session and works in all directions. Verified on a warm Blacksmith box (codex-core): rustfmt --check clean on both files; just test -p codex-core = 2893 passed with an identical pass/fail set with and without this patch (75 pre-existing environmental sandbox/landlock/MCP failures, zero in config or multi_agents). The only clippy red is pre-existing and unrelated, in code-mode/src/runtime/mod.rs (untouched here).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Codewith agents were spawning sub-agents and then busy-polling / spamming
"Waiting for agents" / "No agents completed yet". #364 (0.1.77) made sub-agent
completion push-based (
wake_if_idleauto-notify: an idle parent is wokenwith the child's result) and #377 delivers inter-agent messages into the
target's session, but the agent system prompt did not yet teach the model the
full Claude-Code-style coordination loop. This PR adds that guidance, merging
with (not duplicating) #364's existing text.
Where the prompt lives
The model-facing multi-agent guidance is not in
prompt.md/ thegpt-5.*variants /models.jsonbase_instructions(all verified to containzero multi-agent text), and
templates/collab/experimental_prompt.mdis deadcode (unreferenced anywhere). The live, model-independent "agent system prompt"
for multi-agent sessions is the v2 usage hints in codex-core config, which
every root and sub-agent inherits (no per-model-family variant carries this):
codex-rs/core/src/config/mod.rs:508DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXTcodex-rs/core/src/config/mod.rs:532DEFAULT_MULTI_AGENT_V2_SUBAGENT_USAGE_HINT_TEXT#364's existing text there was a single line: "Sub-agent completion is
push-based: after spawning, do other work or end your turn ... Do not busy-wait
with wait_agent." I replaced that single line (in both hints) with the fuller
coordination loop below. Tool-level guidance from #364 already lives in
codex-rs/core/src/tools/handlers/multi_agents_spec.rs(spawn_agent /wait_agent v2 descriptions) and is left intact.
Guidance added (merged with #364)
wait_agentonce only when genuinely blocked ona specific result; never loop
wait_agent/list_agents, and never emitrepeated "waiting for agents" / "no agents completed yet" messages.
sub-agent's
FINAL_ANSWERis delivered automatically and an idle parent iswoken with the result, so it is safe to stop and wait.
send_messageinjects amessage into the target agent's session without starting a turn;
followup_taskhands off a new task and wakes an idle target. Both workparent->child, child->parent, and peer-to-peer -- use them to steer an agent,
delegate a sub-task, or answer a running agent's question.
Also updated
create_send_message_tool's description(
codex-rs/core/src/tools/handlers/multi_agents_spec.rs:179) to state themessage is injected into the target agent's session and works in all directions.
Exact tool names referenced (real, verified in this codebase)
spawn_agent,wait_agent,list_agents,send_message,followup_task,plus the
FINAL_ANSWERcompletion notification. (No invented tools -- there isno
message_agent/get_statusin this codebase.)Verification (warm Blacksmith, codex-core)
origin/mainbaseline(patch stashed) vs. patched -- identical pass/fail set; the patched failure
set is a strict subset of baseline. The 75 failures are pre-existing
environmental sandbox/landlock/network/MCP/shell-snapshot integration tests;
zero failures in
config::testsormulti_agents. No prompt snapshottest covers these strings (config tests compare against the constants
themselves; send_message test asserts params, not the description).
code-mode/src/runtime/mod.rs:329(crate not touched here). This change ispure string content and adds no lints.
*.mdtouched, so prettier is N/A.Do not merge/tag from here -- hand-off for 0.1.78.