From 8c81d95460488315e1aacc150d8a3b8eb34b5f25 Mon Sep 17 00:00:00 2001
From: Eve <eve@ai.cowbay.org>
Date: Fri, 24 Apr 2026 10:17:09 +0800
Subject: [PATCH] docs: define subagent dispatch receipt fields

---
 docs/runbooks/subagent-anti-blackhole.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 docs/runbooks/subagent-anti-blackhole.md

diff --git a/docs/runbooks/subagent-anti-blackhole.md b/docs/runbooks/subagent-anti-blackhole.md
new file mode 100644
index 0000000..e19d61b
--- /dev/null
+++ b/docs/runbooks/subagent-anti-blackhole.md
@@ -0,0 +1,23 @@
+# Subagent Anti-Blackhole Runbook
+
+## Dispatch receipt fields
+
+Dispatch receipt 僅定義子代理派發當下所需的欄位，用來識別本次派發、關聯子 session，以及標記預期完成時限。
+
+- `runId`: 本次 subagent dispatch 的唯一執行識別碼。用於把同一次任務派發、後續狀態檢查與回報關聯到同一個 run。
+- `childSessionKey`: 子代理 session 的穩定關聯鍵。用於把 dispatch receipt 對應到實際被派發出去的 child session。
+- `dispatchAt`: dispatch receipt 寫入時間，也就是主流程實際派發 subagent 的時間戳記。建議使用可排序的標準時間格式。
+- `expectedBy`: 依照當次任務 SLA 或預估完成時間計算出的期望完成時間戳記。用於判斷目前仍屬正常執行中，或已超過預期等待窗口。
+
+> 本節僅定義 dispatch receipt 欄位，不涵蓋 completion receipts、watchdog logic、recovery 流程或其他後續 task。
+
+## Minimal example
+
+```json
+{
+  "runId": "run_2026-04-24_001",
+  "childSessionKey": "agent:engineering:subagent:example",
+  "dispatchAt": "2026-04-24T10:00:00+08:00",
+  "expectedBy": "2026-04-24T10:15:00+08:00"
+}
+```