Fix subagent completion wakeups

Make terminal subagent completion notifications trigger parent pending work so background agents can hand results back without requiring an explicit wait_agent or close_agent call. Update the nonblocking background execution docs and cover both completion watcher and child-turn forwarding paths.

Co-authored-by: Open Codex <hff582580@gmail.com>

Author: LEON-gittech

README.md

@@ -165,6 +165,7 @@ The shared interaction model is:
 - the status line keeps foreground `Working` state separate from background subagent/terminal counts.
 - terminal details show runtime and recent output; subagent details show role, task, status, runtime, progress, and task-boundary context.
 - `/agent` shows available agent profiles, while `/subagents` keeps the subagent thread picker/switching workflow.
+- completed subagent work wakes the parent turn through a core completion event, so results can be integrated without manually calling `wait_agent` or closing the agent.
 - completed background command output is preserved in history without pulling the task back into the foreground.
 
 This is the essential interaction change behind the Claude Code-style behavior: background work stays visible and controllable, but it no longer blocks normal chat flow.
@@ -455,6 +456,7 @@ Codex CLI 是开源的，但上游仓库当前对外部代码贡献采用 invita
 - status line 会把前台 `Working` 状态和后台 subagent/terminal 数量分开显示。
 - terminal detail 展示运行时间和最近输出；subagent detail 展示 role、task、status、运行时间、progress 和任务边界信息。
 - `/agent` 用于查看可用 agent profiles，`/subagents` 保留 subagent thread picker / 切换工作流。
+- subagent 完成后会通过 core completion event 唤醒 parent turn，因此不需要手动调用 `wait_agent` 或关闭 agent 才能继续整合结果。
 - background command 完成后会保留输出到 history，但不会把任务重新拉回前台。
 
 这是 Claude Code 风格体验背后的本质交互变化：后台工作仍然可见、可管理，但不会阻塞正常聊天流。

codex-rs/core/src/agent/control.rs

@@ -999,7 +999,7 @@ impl AgentControl {
                     parent_agent_path,
                     Vec::new(),
                     message,
-                    /*trigger_turn*/ false,
+                    /*trigger_turn*/ true,
                 );
                 let _ = control
                     .send_inter_agent_communication(parent_thread_id, communication)

codex-rs/core/src/agent/control_tests.rs

@@ -198,6 +198,21 @@ async fn wait_for_subagent_notification(parent_thread: &Arc<CodexThread>) -> boo
     timeout(Duration::from_secs(10), wait).await.is_ok()
 }
 
+async fn wait_for_turn_started(thread: &Arc<CodexThread>) -> bool {
+    let wait = async {
+        loop {
+            let event = thread
+                .next_event()
+                .await
+                .expect("thread event channel open");
+            if matches!(event.msg, EventMsg::TurnStarted(_)) {
+                return true;
+            }
+        }
+    };
+    timeout(Duration::from_secs(5), wait).await.is_ok()
+}
+
 async fn persist_thread_for_tree_resume(thread: &Arc<CodexThread>, message: &str) {
     thread
         .inject_user_message_without_turn(message.to_string())
@@ -1311,7 +1326,7 @@ async fn multi_agent_v2_completion_ignores_dead_direct_parent() {
 async fn multi_agent_v2_completion_queues_message_for_direct_parent() {
     let harness = AgentControlHarness::new().await;
     let (_root_thread_id, root_thread) = harness.start_thread().await;
-    let (worker_thread_id, _worker_thread) = harness.start_thread().await;
+    let (worker_thread_id, worker_thread) = harness.start_thread().await;
     let mut tester_config = harness.config.clone();
     let _ = tester_config.features.enable(Feature::MultiAgentV2);
     let tester_thread_id = harness
@@ -1367,7 +1382,7 @@ async fn multi_agent_v2_completion_queues_message_for_direct_parent() {
                 worker_path.clone(),
                 Vec::new(),
                 expected_message.clone(),
-                /*trigger_turn*/ false,
+                /*trigger_turn*/ true,
             ),
         },
     );
@@ -1387,6 +1402,10 @@ async fn multi_agent_v2_completion_queues_message_for_direct_parent() {
     })
     .await
     .expect("completion watcher should queue a direct-parent message");
+    assert!(
+        wait_for_turn_started(&worker_thread).await,
+        "completion watcher should wake the idle direct parent turn"
+    );
 
     let root_history_items = root_thread
         .codex
@@ -1402,7 +1421,7 @@ async fn multi_agent_v2_completion_queues_message_for_direct_parent() {
             AgentPath::root(),
             Vec::new(),
             expected_message,
-            /*trigger_turn*/ false,
+            /*trigger_turn*/ true,
         )
     ));
 }

codex-rs/core/src/session/mod.rs

@@ -1599,7 +1599,7 @@ impl Session {
             parent_agent_path,
             Vec::new(),
             message,
-            /*trigger_turn*/ false,
+            /*trigger_turn*/ true,
         );
         if let Err(err) = self
             .services

codex-rs/core/src/tools/handlers/multi_agents_tests.rs

@@ -1474,7 +1474,7 @@ async fn multi_agent_v2_followup_task_completion_notifies_parent_on_every_turn()
                                 if communication.author == worker_path
                                     && communication.recipient == AgentPath::root()
                                     && communication.other_recipients.is_empty()
-                                    && !communication.trigger_turn =>
+                                    && communication.trigger_turn =>
                             {
                                 Some(communication.content)
                             }