From 8dac605901a7a5a91a6a16c381543af070d3c0c6 Mon Sep 17 00:00:00 2001 From: Ahmed Ibrahim Date: Sun, 28 Jun 2026 20:34:47 -0700 Subject: [PATCH] [codex] Restore v1 delegation guidance (#30511) ## Summary - restore the v1 clarification that requests for depth, research, or investigation do not authorize subagent spawning - restore guidance for keeping critical-path, urgent, tightly coupled, or difficult work local - update the focused v1 tool-search and spawn-description coverage ## Why PR #27919 simplified the v1 `spawn_agent` prompt by removing its delegation decision guidance. That left the authorization rule intact, but removed the instructions that constrained what should be delegated after spawning was authorized. Restore those guardrails while preserving later support for explicit delegation authorization from applicable AGENTS.md and skill instructions. Multi-agent v2 prompts are unchanged. ## User impact Models using the v1 multi-agent tool surface receive clearer guidance to delegate independent side work while keeping blocking work on the main rollout. ## Validation - `just fmt` - `git diff --check` - tests not run locally per repository guidance; CI will validate the focused coverage --- codex-rs/core/src/tools/handlers/multi_agents_spec.rs | 7 +++++++ codex-rs/core/tests/suite/search_tool.rs | 4 ++-- codex-rs/core/tests/suite/spawn_agent_description.rs | 6 ++++-- 3 files changed, 13 insertions(+), 4 deletions(-) diff --git a/codex-rs/core/src/tools/handlers/multi_agents_spec.rs b/codex-rs/core/src/tools/handlers/multi_agents_spec.rs index 857a4dea9..23ac4e0bb 100644 --- a/codex-rs/core/src/tools/handlers/multi_agents_spec.rs +++ b/codex-rs/core/src/tools/handlers/multi_agents_spec.rs @@ -674,8 +674,15 @@ fn spawn_agent_tool_description( This spawn_agent tool provides you access to sub-agents that inherit your current model by default. Do not set the `model` field unless the user explicitly asks for a different model or there is a clear task-specific reason. You should follow the rules and guidelines below to use this tool. Do not spawn sub-agents unless the user or applicable AGENTS.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work. +Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do not count as permission to spawn. {agent_role_usage_hint} +### When to delegate vs. do the subtask yourself +- First, quickly analyze the overall user task and form a succinct high-level plan. Identify which tasks are immediate blockers on the critical path, and which tasks are sidecar tasks that are needed but can run in parallel without blocking the next local step. As part of that plan, explicitly decide what immediate task you should do locally right now. Do this planning step before delegating to agents so you do not hand off the immediate blocking task to a submodel and then waste time waiting on it. +- Use a subagent when a subtask is easy enough for it to handle and can run in parallel with your local work. Prefer delegating concrete, bounded sidecar tasks that materially advance the main task without blocking your immediate next local step. +- Do not delegate urgent blocking work when your immediate next step depends on that result. If the very next action is blocked on that task, the main rollout should usually do it locally to keep the critical path moving. +- Keep work local when the subtask is too difficult to delegate well and when it is tightly coupled, urgent, or likely to block your immediate next step. + ### Designing delegated subtasks - Subtasks must be concrete, well-defined, and self-contained. - Delegated subtasks must materially advance the main task. diff --git a/codex-rs/core/tests/suite/search_tool.rs b/codex-rs/core/tests/suite/search_tool.rs index c1bc9cc1f..50ccea0d8 100644 --- a/codex-rs/core/tests/suite/search_tool.rs +++ b/codex-rs/core/tests/suite/search_tool.rs @@ -827,7 +827,7 @@ async fn tool_search_returns_deferred_v1_multi_agent_tools() -> Result<()> { assert!( !first_request_body .to_string() - .contains("Only use `spawn_agent` if and only if"), + .contains("### When to delegate vs. do the subtask yourself"), "deferred v1 multi-agent guidance should stay out of initial developer context" ); @@ -861,7 +861,7 @@ async fn tool_search_returns_deferred_v1_multi_agent_tools() -> Result<()> { "Do not spawn sub-agents unless the user or applicable AGENTS.md/skill instructions explicitly ask for sub-agents, delegation, or parallel agent work." )); assert!(description.contains("### Designing delegated subtasks")); - assert!(!description.contains("### When to delegate vs. do the subtask yourself")); + assert!(description.contains("### When to delegate vs. do the subtask yourself")); Ok(()) } diff --git a/codex-rs/core/tests/suite/spawn_agent_description.rs b/codex-rs/core/tests/suite/spawn_agent_description.rs index e463afad9..e7076e746 100644 --- a/codex-rs/core/tests/suite/spawn_agent_description.rs +++ b/codex-rs/core/tests/suite/spawn_agent_description.rs @@ -219,8 +219,10 @@ async fn spawn_agent_description_lists_visible_models_and_reasoning_efforts() -> "expected explicit authorization rule in spawn_agent description: {description:?}" ); assert!( - !description.contains("### When to delegate vs. do the subtask yourself"), - "spawn_agent description should not include extra when-to-use delegation guidance: {description:?}" + description.contains( + "Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do not count as permission to spawn." + ) && description.contains("### When to delegate vs. do the subtask yourself"), + "expected delegation decision guidance in spawn_agent description: {description:?}" ); assert!( description.contains(