From 58f6b108c35e165db479d632fc07b9556593cdc5 Mon Sep 17 00:00:00 2001
From: alexion <contact@alexion.dev>
Date: Sun, 2 Aug 2026 08:23:57 -0400
Subject: [PATCH] docs(pi): clarify subagent completion behavior

---
 AGENTS.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 042ecc9..b65775d 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,6 +18,8 @@ The domain model (Host, Module, Skeleton, Auto-loader, Enable convention, overla
 
 ## Gotchas
 
+- Subagent completion delivery is non-blocking through immediate spawn, milestone notifications, retained terminal entries, and `subagent_list` or `subagent_result` retrieval.
+  `subagent_wait` intentionally blocks the parent tool call until its condition or timeout, so do not use it merely to keep background work alive during an interactive workflow.
 - This host has no `python` or `python3` command on its ordinary `PATH`.
   For ad hoc Python, use Nix explicitly, such as `nix shell nixpkgs#python3 -c python3 <script>`.
 - ADR bodies are immutable records of decisions as they were made, while frontmatter is mutable.