From 5633af2d29f23f65c3bc02dcc04aa3816289c9a4 Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Sun, 17 May 2026 10:38:38 +0200
Subject: [PATCH] docs: parent must NEVER actively wait for subagent results

---
 prompts/tools-subagent.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/prompts/tools-subagent.md b/prompts/tools-subagent.md
index 1784ef8..d4e6265 100644
--- a/prompts/tools-subagent.md
+++ b/prompts/tools-subagent.md
@@ -83,7 +83,9 @@ Remaining args: the task prompt (immediate task only — coordination lives in t
 
 ## Returning results to the parent
 
-Subagents signal completion by writing directly to `s/{parent_session_id}/prompt`. This wakes the parent's idle session and delivers the result as its next turn input — no polling required.
+Subagents signal completion by writing directly to `s/{parent_session_id}/prompt`. This delivers the result as the parent's next queued turn — no polling, no blocking, no active waiting.
+
+**Critical**: The parent must NEVER actively wait for subagent results. No `statewait`, no polling loops, no blocking reads. After spawning, the parent either continues its own work or ends its turn. When a child writes to the parent's prompt, the message queues and drains automatically when the parent next idles. This avoids wasting expensive coordinator tokens on idle waiting and eliminates coordination deadlocks.
 
 The result written to the parent's prompt should be compact and unambiguous. Use this format: