reporting-governance-plugin/docs/runbooks/subagent-anti-blackhole.md

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

{
  "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"
}

Completion receipt fields

Completion receipt 僅定義子代理完成結果被接收到之後所需記錄的欄位，用來區分「子代理已完成」與「結果是否已成功轉交 main conversation」。

• completionReceivedAt: 主流程或監看機制實際收到 completion/result 的時間戳記。用於確認子代理何時已經完成並回傳結果，不再只靠 expectedBy 推估。
• forwardedToMain: 布林欄位，表示該 completion/result 是否已成功轉送到 main conversation。用於區分「已收到結果」與「已完成主線回報」這兩個不同狀態。
• resultSource: completion/result 的來源標記，例如來自主動 completion push、補抓回來的 session 狀態，或其他明確來源。用於後續判讀結果是正常送達還是經由補救路徑取得。

本節僅定義 completion receipt 欄位，不涵蓋 watchdog logic、recovery 流程、scenario tests 或其他後續 task。

Completion receipt example

{
  "completionReceivedAt": "2026-04-24T10:12:34+08:00",
  "forwardedToMain": true,
  "resultSource": "completion_push"
}