Skip to content

feat(prompt): guide agents to hold for sub-agents, expect auto-notify, and use inter-agent messages#390

Merged
andrei-hasna merged 1 commit into
mainfrom
feat/prompt-multiagent-hold-notify-coordinate
Jul 23, 2026
Merged

feat(prompt): guide agents to hold for sub-agents, expect auto-notify, and use inter-agent messages#390
andrei-hasna merged 1 commit into
mainfrom
feat/prompt-multiagent-hold-notify-coordinate

Conversation

@andrei-hasna

Copy link
Copy Markdown
Contributor

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_idle auto-notify: an idle parent is woken
with 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 / the
gpt-5.* variants / models.json base_instructions (all verified to contain
zero multi-agent text), and templates/collab/experimental_prompt.md is dead
code (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:508 DEFAULT_MULTI_AGENT_V2_ROOT_AGENT_USAGE_HINT_TEXT
  • codex-rs/core/src/config/mod.rs:532 DEFAULT_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)

  1. Hold, don't poll. Call wait_agent once only when genuinely blocked on
    a specific result; never loop wait_agent/list_agents, and never emit
    repeated "waiting for agents" / "no agents completed yet" messages.
  2. Expect auto-notify. Completion is push-based (feat(core): auto-notify parent on sub-agent completion (wake_if_idle) + honest wait + guidance #364): a finishing
    sub-agent's FINAL_ANSWER is delivered automatically and an idle parent is
    woken with the result, so it is safe to stop and wait.
  3. Coordinate via inter-agent messages (fix(core,api): deliver inter-agent messages on chat-wire providers + surface mailbox-full to sender #377): send_message injects a
    message into the target agent's session without starting a turn;
    followup_task hands off a new task and wakes an idle target. Both work
    parent->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 the
message 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_ANSWER completion notification. (No invented tools -- there is
no message_agent/get_status in this codebase.)

Verification (warm Blacksmith, codex-core)

  • rustfmt --check: clean on both changed files (exit 0).
  • just test -p codex-core: 2893 passed. Ran a clean origin/main baseline
    (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::tests or multi_agents. No prompt snapshot
    test covers these strings (config tests compare against the constants
    themselves; send_message test asserts params, not the description).
  • clippy: the only red is pre-existing and unrelated, in
    code-mode/src/runtime/mod.rs:329 (crate not touched here). This change is
    pure string content and adds no lints.
  • No *.md touched, so prettier is N/A.

Do not merge/tag from here -- hand-off for 0.1.78.

…, 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).
@andrei-hasna
andrei-hasna merged commit 19808dd into main Jul 23, 2026
27 checks passed
@github-actions github-actions Bot locked and limited conversation to collaborators Jul 23, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant