@esso0428/pi-subagents 0.17.17 → 0.17.19

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.19] - 2026-09-30
+
+### Added
+- **Added nonblocking subagent wait groups**: `Agent` now accepts `wait: true` for background notification grouping, with `wait_group` and `wait_group_done` for explicit multi-agent groups, plus the `subagent_wait_group` tool to create, rename, and seal groups. A sealed wait group emits one completion notification after all members reach a terminal state, avoiding blocking waits and notification spam.
+
+## [0.17.18] - 2026-09-30
+
+### Changed
+- **Republished the intentional v0.17.6 runtime/UI rollback** because npm reserved but did not expose the 0.17.17 version slot. v0.17.17 remains the Git and documentation milestone; v0.17.18 contains the same rollback runtime, with future feature restoration beginning at v0.17.19.
+
 ## [0.17.17] - 2026-09-30
 
 ### Changed

package/README.md

@@ -61,6 +61,38 @@ Agent({
 
 Foreground agents block until complete and return results inline. Background agents return an ID immediately and notify you on completion.
 
+### Wait groups
+
+Use `wait: true` on background agents to suppress individual completion notifications and receive one grouped notification instead:
+
+```
+const group = subagent_wait_group({
+  action: "create",
+  summary: "Compare notification group API designs",
+})
+
+Agent({
+  subagent_type: "Explore",
+  prompt: "Design a group-handle API",
+  description: "Design group handle",
+  run_in_background: true,
+  wait: true,
+  wait_group: group.group_id,
+})
+
+Agent({
+  subagent_type: "Plan",
+  prompt: "Design a batch API",
+  description: "Design batch API",
+  run_in_background: true,
+  wait: true,
+  wait_group: group.group_id,
+  wait_group_done: true,
+})
+```
+
+`subagent_wait_group` supports `create`, `update`, and `seal`. A sealed group sends one notification after every member reaches a terminal state (`completed`, `steered`, `error`, `stopped`, or `aborted`). If `wait: true` is used without `wait_group`, the extension creates and seals a one-agent implicit group.
+
 ### Scheduling
 
 Add a `schedule` field to register the agent to fire later instead of running now:

package/ROADMAP.md

@@ -1,6 +1,6 @@
-# v0.17.17 回退與 v0.17.18+ 恢復路線圖
+# v0.17.17 回退、v0.17.18 registry recovery 與 v0.17.19+ 恢復路線圖
 
-本文件是 v0.17.17 的回退邊界與後續恢復決策，不是 runtime 實作計畫，也不承諾任何日曆日期。主要規格索引是 [`docs/post-0.17.6-feature-specs.md`](docs/post-0.17.6-feature-specs.md)；各階段都必須以該索引及其保存的原始 implementation、測試與 commit 證據為準。
+本文件是 v0.17.17 的回退邊界與後續恢復決策，不是 runtime 實作計畫，也不承諾任何日曆日期。v0.17.18 只因 npm 保留但未公開 v0.17.17 而重發相同 rollback runtime；v0.17.17 仍是 Git／文件里程碑，第一個未來功能恢復版本從 v0.17.19 開始。主要規格索引是 [`docs/post-0.17.6-feature-specs.md`](docs/post-0.17.6-feature-specs.md)；各階段都必須以該索引及其保存的原始 implementation、測試與 commit 證據為準。
 
 ## 目標與不可變邊界
 
@@ -38,15 +38,15 @@
 - [ ] 若證據不足、行為與 archived spec 不一致，或人工操作出現可見卡頓，該功能停留在待恢復狀態，不與其他功能合併。
 - [ ] 本文件本身不執行 Vitest、E2E 或 build；恢復工作是否需要這些檢查，依當時授權與 `AGENTS.md` 的資源政策處理。
 
-## v0.17.18 的決策：只恢復 durable history 基礎層
+## v0.17.19 的決策：只恢復 durable history 基礎層
 
-- [ ] 將 v0.17.18 限定為第一個、可獨立驗證的 durable history/recovery data plane：先處理 transcript 格式、project-local path safety、checkpoint metadata 與 flush/attach seam。
+- [ ] 將 v0.17.19 限定為第一個、可獨立驗證的 durable history/recovery data plane：先處理 transcript 格式、project-local path safety、checkpoint metadata 與 flush/attach seam。
 - [ ] 以 [`docs/post-0.17.6-durable-history-spec.md`](docs/post-0.17.6-durable-history-spec.md) 和 [`docs/post-0.17.6-recovery-shutdown-spec.md`](docs/post-0.17.6-recovery-shutdown-spec.md) 為證據邊界；不得順便恢復 nested agents、Workflow/RPC、FleetView 或整套 Agents UI。
 - [ ] 確保 `output_transcript: false` 不會關閉 `.pi-subagents` durable history，且 GC/session cleanup 不會刪除仍可讀的 terminal record；壞 locator、壞 JSON 或 traversal input 必須 fail safely。
-- [ ] 在接受 v0.17.18 前，人工確認既有 v0.17.6 viewer interaction 沒有 layout/focus/scroll regression；若此基礎層不改 UI，也仍要記錄 baseline 操作結果。
-- [ ] v0.17.18 不承諾任何日曆日期；版本成立條件是上述單一功能的證據完整，而不是時間到期或功能數量達標。
+- [ ] 在接受 v0.17.19 前，人工確認既有 v0.17.6 viewer interaction 沒有 layout/focus/scroll regression；若此基礎層不改 UI，也仍要記錄 baseline 操作結果。
+- [ ] v0.17.19 不承諾任何日曆日期；版本成立條件是上述單一功能的證據完整，而不是時間到期或功能數量達標。
 
-## v0.17.18 之後的證據驅動順序
+## v0.17.19 之後的證據驅動順序
 
 每一列都是獨立候選恢復項；「後續版本」只代表通過前一項 acceptance 後再決定的版本，不預設版本號或日期。
 
@@ -71,9 +71,9 @@
 - [ ] **Render path**：人工觀察長歷史與頻繁事件時沒有隨歷史長度惡化的可見卡頓；同時以規格列出的 perf guards 驗證 render 不做 filesystem I/O，並記錄證據而非臆測數字門檻。
 - [ ] **失敗處理**：任何可見延遲、focus/layout 變化、重複 redraw、stale row 或 history 消失都代表該單一功能未接受；先隔離或回退該變更，不得進入組合 release。
 
-## 0.17.18 與後續 release 的組合決策
+## 0.17.19 與後續 release 的組合決策
 
-- [ ] **v0.17.18**：只接受 durable history/recovery 基礎層；不把 Agents UI、nested、RPC 或 Workflow 當作同一 release 的附帶恢復。
+- [ ] **v0.17.19**：只接受 durable history/recovery 基礎層；不把 Agents UI、nested、RPC 或 Workflow 當作同一 release 的附帶恢復。
 - [ ] **後續版本**：只有已在獨立變更中完成 spec、targeted evidence 與人工 UI latency acceptance 的功能，才可在後續 release 與另一個已接受功能組合。
 - [ ] 組合前要重新執行人工回歸矩陣，特別是 viewer baseline、selector input ownership、長 transcript render 與 resource-policy metadata；單項通過不等於組合後通過。
 - [ ] 若組合回歸失敗，拆回最後一個已接受的功能邊界；不得為了湊版本內容而放寬 acceptance 或重新引入 duplicate UI。

package/docs/post-0.17.6-agents-roster-viewer-spec.md

@@ -2,7 +2,7 @@
 
 ## 基準與目標
 
-本規格保存 `64bbbb0`（v0.17.6）後的 Agents UI 演進，供 v0.17.17 之後逐項恢復。v0.17.6 的 ConversationViewer scrollbar/preview 是不可回退的 interaction baseline；Agents panel 則以 v0.17.0 的 single navigator 為前提，不恢復已移除的 duplicate FleetView。
+本規格保存 `64bbbb0`（v0.17.6）後的 Agents UI 演進，供 v0.17.19 起逐項恢復。v0.17.6 的 ConversationViewer scrollbar/preview 是不可回退的 interaction baseline；Agents panel 則以 v0.17.0 的 single navigator 為前提，不恢復已移除的 duplicate FleetView。
 
 ## UI 契約
 

package/docs/post-0.17.6-feature-specs.md

@@ -2,7 +2,7 @@
 
 ## 文件用途
 
-這組文件是 **v0.17.17 的文件交付物**：保存 `v0.17.6` 之後、程式碼可能回退前的功能契約，讓日後可以按功能選擇性恢復。它不是新的 runtime 設計，也不取代原始測試。`v0.17.17` 目前只代表文件目標版本；本次不修改 package metadata、不 publish，也不刪除既有程式碼。
+這組文件是 **v0.17.17 的文件交付物**：保存 `v0.17.6` 之後、程式碼可能回退前的功能契約，讓日後可以按功能選擇性恢復。它不是新的 runtime 設計，也不取代原始測試。`v0.17.17` 保留為 Git／文件里程碑；npm 未公開該保留版本槽後，v0.17.18 僅重發相同 rollback runtime，第一個未來功能恢復版本從 v0.17.19 開始。
 
 - **基準**：`64bbbb0`（`chore: release 0.17.6`，v0.17.6）；其父提交 `77de83f` 是 scrollbar 實作。
 - **保存範圍**：基準之後至目前 `bad54e4` 的功能；上游整合參考 `upstream/master` 的 `e955e29`。

package/docs/post-0.17.6-nested-agents-spec.md

@@ -2,7 +2,7 @@
 
 ## 目的與來源
 
-保存 `v0.17.6` 後 nested delegation 的行為，供 v0.17.17 之後選擇性恢復。基準是 `64bbbb0`；主要實作由 `8976c63`（#164）開始，後續由 `8d4d4a7` 與 background/workflow 整合延伸。
+保存 `v0.17.6` 後 nested delegation 的行為，供 v0.17.19 起選擇性恢復。基準是 `64bbbb0`；主要實作由 `8976c63`（#164）開始，後續由 `8d4d4a7` 與 background/workflow 整合延伸。
 
 ## 必須保留的行為
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.17",
+  "version": "0.17.19",
   "description": "A pi extension that brings smart Claude Code-style autonomous sub-agents to pi, with npm:pi-subagents-style JSON agent overrides.",
   "author": "ESSO0428",
   "repository": {

package/src/agent-manager.ts

@@ -184,6 +184,8 @@ interface SpawnOptions {
   cwd?: string;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
+  /** Explicit nonblocking completion wait group for this background agent. */
+  waitGroupId?: string;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
   /** Called on tool start/end with activity info (for streaming progress to UI). */
@@ -376,6 +378,7 @@ export class AgentManager {
       // have no inline surface — stay visible instead of vanishing.
       isBackground: options.isBackground,
       invocation: options.invocation,
+      waitGroupId: options.waitGroupId,
     };
     this.agents.set(id, record);
     this.recoveryCwds.set(id, ctx.cwd);
@@ -807,6 +810,9 @@ export class AgentManager {
       record.status = "stopped";
       record.completedAt = Date.now();
       this.checkpoint(record);
+      if (record.waitGroupId) {
+        try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+      }
       return true;
     }
 
@@ -885,6 +891,9 @@ export class AgentManager {
         record.status = "stopped";
         record.completedAt = Date.now();
         this.checkpoint(record);
+        if (record.waitGroupId) {
+          try { this.onComplete?.(record); } catch { /* ignore completion side-effect errors */ }
+        }
         count++;
       }
     }

package/src/agent-runner.ts

@@ -37,6 +37,7 @@ export const SUBAGENT_TOOL_NAMES = {
   AGENT: "Agent",
   GET_RESULT: "get_subagent_result",
   STEER: "steer_subagent",
+  WAIT_GROUP: "subagent_wait_group",
 } as const;
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */

package/src/index.ts

@@ -5,6 +5,7 @@
  *   Agent             — LLM-callable: spawn a sub-agent
  *   get_subagent_result  — LLM-callable: check background agent status/result
  *   steer_subagent       — LLM-callable: send a steering message to a running agent
+ *   subagent_wait_group  — LLM-callable: create, update, or seal a wait group
  *
  * Commands:
  *   /agents                 — Interactive agent management menu
@@ -51,6 +52,7 @@ import {
 } from "./ui/agent-widget.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent, type LifetimeUsage } from "./usage.js";
+import { WaitGroupManager } from "./wait-group.js";
 
 // ---- Shared helpers ----
 
@@ -310,7 +312,10 @@ export default function (pi: ExtensionAPI) {
       }
 
       const all = [d, ...(d.others ?? [])];
-      return new Text(all.map(renderOne).join("\n"), 0, 0);
+      const groupHeader = d.groupSummary
+        ? theme.fg("dim", `Wait group: ${d.groupSummary} (${d.groupId ?? ""})`)
+        : undefined;
+      return new Text([groupHeader, all.map(renderOne).join("\n")].filter(Boolean).join("\n"), 0, 0);
     }
   );
 
@@ -411,6 +416,42 @@ export default function (pi: ExtensionAPI) {
     30_000,
   );
 
+  // Explicit wait groups are separate from smart/group join mode: they never
+  // time out or partially deliver, and are released only when sealed.
+  const waitGroups = new WaitGroupManager((groupId, summary, records) => {
+    for (const record of records) {
+      agentActivity.delete(record.id);
+      widget.markFinished(record.id);
+    }
+
+    const groupKey = `wait-group:${groupId}`;
+    scheduleNudge(groupKey, () => {
+      const notifications = records.map(record => {
+        const consumed = record.resultConsumed ? "\n(Result already retrieved via get_subagent_result.)" : "";
+        return formatTaskNotification(record, 300) + consumed;
+      }).join("\n\n");
+      const consumedCount = records.filter(record => record.resultConsumed).length;
+      const consumedNote = consumedCount > 0
+        ? ` ${consumedCount} result${consumedCount === 1 ? " was" : "s were"} already retrieved.`
+        : "";
+      const [first, ...rest] = records;
+      const details = buildNotificationDetails(first, 300, agentActivity.get(first.id));
+      details.groupId = groupId;
+      details.groupSummary = summary;
+      if (rest.length > 0) {
+        details.others = rest.map(record => buildNotificationDetails(record, 300, agentActivity.get(record.id)));
+      }
+
+      pi.sendMessage<NotificationDetails>({
+        customType: "subagent-notification",
+        content: `Background agent wait group completed: ${summary} (group ${groupId}).${consumedNote}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+        display: true,
+        details,
+      }, { deliverAs: "followUp", triggerTurn: true });
+    });
+    widget.update();
+  });
+
   /** Helper: build event data for lifecycle events from an AgentRecord. */
   function buildEventData(record: AgentRecord) {
     const durationMs = record.completedAt ? record.completedAt - record.startedAt : Date.now() - record.startedAt;
@@ -463,6 +504,17 @@ export default function (pi: ExtensionAPI) {
       transcriptPath: record.transcriptPath,
     });
 
+    // Explicit wait-group members never emit individual notifications. Result
+    // consumption does not remove membership; the sealed group still delivers
+    // exactly one notification for all terminal members.
+    if (record.waitGroupId) {
+      waitGroups.onAgentComplete(record);
+      agentActivity.delete(record.id);
+      widget.markFinished(record.id);
+      widget.update();
+      return;
+    }
+
     // Skip notification if result was already consumed via get_subagent_result
     if (record.resultConsumed) {
       agentActivity.delete(record.id);
@@ -633,6 +685,8 @@ export default function (pi: ExtensionAPI) {
     manager.abortAll();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
     pendingNudges.clear();
+    groupJoin.dispose();
+    waitGroups.dispose();
     widget.dispose();
     manager.dispose();
   });
@@ -856,6 +910,7 @@ Custom agents: .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.
 Notes:
 - description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
 - Parallel work: one message, multiple Agent calls, run_in_background: true on each. You are notified when background agents finish — never poll or sleep.
+- For nonblocking grouped notification, add wait: true. Use subagent_wait_group to create/update/seal explicit groups; wait_group_done seals after the final spawn.
 - The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
 - resume continues a previous agent by ID; steer_subagent messages a running one.
 - isolation: "worktree" runs the agent in an isolated git worktree; changes land on a branch.`;
@@ -880,6 +935,7 @@ If the target is already known, use a direct tool — \`read\` for a known path,
 - When the agent is done, it returns a single message back to you. The result is not visible to the user — to show the user, send a text message with a concise summary.
 - Trust but verify: an agent's summary describes what it intended to do, not necessarily what it did. When an agent writes or edits code, check the actual changes before reporting work as done.
 - Use run_in_background for work you don't need immediately. You will be notified when it completes — do NOT poll or sleep waiting for it. Continue with other work or respond to the user instead.
+- For nonblocking grouped notification, set wait: true with run_in_background: true. Omit wait_group for a one-agent implicit group, or create an explicit group with subagent_wait_group and seal it (or set wait_group_done: true on the final Agent call).
 - Foreground vs background: use foreground (default) when you need the agent's results before you can proceed. Use background when you have genuinely independent work to do in parallel.
 - Use resume with an agent ID to continue a previous agent's work. A new (non-resume) Agent call starts a fresh agent with no memory of prior runs, so the prompt must be self-contained.
 - Use steer_subagent to send mid-run messages to a running background agent.
@@ -959,6 +1015,7 @@ Terse command-style prompts produce shallow, generic work.
       "Use Agent with specialized agents when the task matches an agent type's description. Subagents are valuable for parallelizing independent queries or for protecting the main context window from excessive results, but should not be used excessively when not needed. Importantly, avoid duplicating work that subagents are already doing — if you delegate research to a subagent, do not also perform the same searches yourself.",
       "For broad codebase exploration or research, spawn Agent with an appropriate subagent_type (e.g. Explore). Otherwise use direct tools (read, grep, find) when the target is already known.",
       "When an agent runs in the background, you will be notified on completion — do not poll or sleep waiting for it. Continue with other work instead.",
+      "For a nonblocking grouped notification, use wait: true with run_in_background: true; create/update/seal explicit groups with subagent_wait_group.",
       "Trust but verify: an agent's summary describes intent, not outcome. When an agent writes or edits code, check the actual changes before reporting work as done.",
     ],
     parameters: Type.Object({
@@ -993,6 +1050,22 @@ Terse command-style prompts produce shallow, generic work.
           description: "Set to true to run in background. Returns agent ID immediately. You will be notified on completion.",
         }),
       ),
+      wait: Type.Optional(
+        Type.Boolean({
+          description: "With run_in_background: true, suppress individual completion notification and wait for a sealed group notification. This never blocks execution.",
+        }),
+      ),
+      wait_group: Type.Optional(
+        Type.String({
+          minLength: 1,
+          description: "Existing explicit wait-group ID created by subagent_wait_group. Requires wait: true.",
+        }),
+      ),
+      wait_group_done: Type.Optional(
+        Type.Boolean({
+          description: "With wait: true, seal wait_group after this agent is spawned. Use on the final member.",
+        }),
+      ),
       resume: Type.Optional(
         Type.String({
           description: "Optional agent ID to resume from. Continues from previous context.",
@@ -1169,6 +1242,9 @@ Terse command-style prompts produce shallow, generic work.
       const thinking = resolvedConfig.thinking;
       const inheritContext = resolvedConfig.inheritContext;
       const runInBackground = resolvedConfig.runInBackground;
+      const wait = params.wait === true;
+      const waitGroup = typeof params.wait_group === "string" ? params.wait_group.trim() : undefined;
+      const waitGroupDone = params.wait_group_done === true;
       const isolated = resolvedConfig.isolated;
       const isolation = resolvedConfig.isolation;
       // Whether this spawn writes its .output transcript. Per-agent
@@ -1228,6 +1304,19 @@ Terse command-style prompts produce shallow, generic work.
         tags: agentTags.length > 0 ? agentTags : undefined,
       };
 
+      if ((waitGroup || waitGroupDone) && !wait) {
+        return textResult("wait_group and wait_group_done require wait: true.");
+      }
+      if (wait && !runInBackground) {
+        return textResult("wait: true requires run_in_background: true; it controls nonblocking background notifications.");
+      }
+      if (wait && params.schedule) {
+        return textResult("Cannot combine wait: true with schedule — scheduled jobs are separate future runs.");
+      }
+      if (wait && params.resume) {
+        return textResult("Cannot combine wait: true with resume — wait groups apply to fresh background spawns.");
+      }
+
       // ---- Schedule: register a job, don't spawn now ----
       if (params.schedule) {
         if (!isSchedulingEnabled()) {
@@ -1300,8 +1389,21 @@ Terse command-style prompts produce shallow, generic work.
         // Wrap onSessionCreated to wire output file streaming.
         // The callback reads the transcript paths installed synchronously by
         // onSpawned before the agent can queue or start.
-        let id: string;
-        const joinMode = resolveJoinMode(defaultJoinMode, true);
+        let id = "";
+        let effectiveWaitGroupId: string | undefined;
+        let implicitWaitGroupId: string | undefined;
+        if (wait) {
+          if (waitGroup) {
+            if (!waitGroups.hasGroup(waitGroup)) {
+              return textResult(`Wait group not found: "${waitGroup}". Create it with subagent_wait_group first.`);
+            }
+            effectiveWaitGroupId = waitGroup;
+          } else {
+            implicitWaitGroupId = waitGroups.create(params.description);
+            effectiveWaitGroupId = implicitWaitGroupId;
+          }
+        }
+        const joinMode = wait ? undefined : resolveJoinMode(defaultJoinMode, true);
         const origBgOnSession = bgCallbacks.onSessionCreated;
         bgCallbacks.onSessionCreated = (session: any) => {
           origBgOnSession(session);
@@ -1322,12 +1424,17 @@ Terse command-style prompts produce shallow, generic work.
             isBackground: true,
             isolation,
             invocation: agentInvocation,
+            waitGroupId: effectiveWaitGroupId,
             onSpawned: (spawnedId) => {
+              id = spawnedId;
               attachTranscript(manager.getRecord(spawnedId), spawnedId);
+              if (effectiveWaitGroupId) waitGroups.addAgent(effectiveWaitGroupId, spawnedId);
             },
             ...bgCallbacks,
           });
         } catch (err) {
+          if (effectiveWaitGroupId && id) waitGroups.removeAgent(effectiveWaitGroupId, id);
+          if (implicitWaitGroupId) waitGroups.discard(implicitWaitGroupId);
           return textResult(err instanceof Error ? err.message : String(err));
         }
 
@@ -1339,7 +1446,9 @@ Terse command-style prompts produce shallow, generic work.
           record.toolCallId = toolCallId;
         }
 
-        if (joinMode == null || joinMode === 'async') {
+        if (effectiveWaitGroupId) {
+          if (implicitWaitGroupId || waitGroupDone) waitGroups.seal(effectiveWaitGroupId);
+        } else if (joinMode == null || joinMode === 'async') {
           // Foreground/no join mode or explicit async — not part of any batch
         } else {
           // smart or group — add to current batch
@@ -1370,7 +1479,10 @@ Terse command-style prompts produce shallow, generic work.
           `Description: ${params.description}\n` +
           (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
           (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
-          `\nYou will be notified when this agent completes.\n` +
+          (effectiveWaitGroupId
+            ? `\nWait group: ${effectiveWaitGroupId}${implicitWaitGroupId || waitGroupDone ? " (sealed)" : " (open — seal it with subagent_wait_group)"}.\n` +
+              `You will receive one grouped notification when the sealed wait group completes.\n`
+            : `\nYou will be notified when this agent completes.\n`) +
           `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
           `Do not duplicate this agent's work.`,
           { ...detailBase, toolUses: 0, tokens: "", durationMs: 0, status: "background" as const, agentId: id },
@@ -1494,6 +1606,75 @@ Terse command-style prompts produce shallow, generic work.
     },
   }));
 
+  // ---- subagent_wait_group tool ----
+
+  pi.registerTool(defineTool({
+    name: SUBAGENT_TOOL_NAMES.WAIT_GROUP,
+    label: "Subagent Wait Group",
+    description:
+      "Create, update, or seal a nonblocking wait group for background Agent calls. " +
+      "A sealed group sends one completion notification after all member agents finish.",
+    promptSnippet: "Create, update, or seal a grouped subagent completion notification",
+    parameters: Type.Object({
+      action: Type.String({
+        description: "Operation: create, update, or seal.",
+      }),
+      group_id: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Wait group ID. Required for update and seal; optional custom ID for create.",
+      })),
+      summary: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Human-readable group summary. Required for create and update; shown in the eventual notification.",
+      })),
+    }),
+    execute: async (_toolCallId, params) => {
+      const action = String(params.action).trim();
+      const groupId = typeof params.group_id === "string" ? params.group_id.trim() : undefined;
+      const summary = typeof params.summary === "string" ? params.summary.trim() : undefined;
+
+      try {
+        if (action === "create") {
+          if (!summary) return textResult("summary is required when creating a wait group.");
+          const createdId = waitGroups.create(summary, groupId);
+          return textResult(
+            `Created subagent wait group.\n` +
+            `Group ID: ${createdId}\n` +
+            `Summary: ${summary}\n\n` +
+            `Use Agent with run_in_background: true, wait: true, wait_group: "${createdId}". ` +
+            `Seal the group after adding members.`,
+          );
+        }
+        if (action === "update") {
+          if (!groupId) return textResult("group_id is required when updating a wait group.");
+          if (!summary) return textResult("summary is required when updating a wait group.");
+          waitGroups.update(groupId, summary);
+          return textResult(`Updated subagent wait group ${groupId}.\nSummary: ${summary}`);
+        }
+        if (action === "seal") {
+          if (!groupId) return textResult("group_id is required when sealing a wait group.");
+          const snapshot = waitGroups.getGroup(groupId);
+          const delivered = waitGroups.seal(groupId);
+          if (!snapshot) return textResult(`Wait group not found: "${groupId}".`);
+          if (snapshot.agentIds.length === 0) {
+            return textResult(`Sealed empty subagent wait group ${groupId}. No completion notification will be sent.`);
+          }
+          return textResult(
+            `Sealed subagent wait group ${groupId}.\n` +
+            `Summary: ${snapshot.summary}\n` +
+            `Members: ${snapshot.agentIds.length}\n` +
+            (delivered
+              ? "All members were already complete; notification has been queued."
+              : "You will receive one notification after all members finish."),
+          );
+        }
+        return textResult(`Unknown action "${action}". Use create, update, or seal.`);
+      } catch (err) {
+        return textResult(err instanceof Error ? err.message : String(err));
+      }
+    },
+  }));
+
   // ---- get_subagent_result tool ----
 
   pi.registerTool(defineTool({

package/src/types.ts

@@ -103,6 +103,8 @@ export interface AgentRecord {
   worktreeResult?: { hasChanges: boolean; branch?: string };
   /** The tool_use_id from the original Agent tool call. */
   toolCallId?: string;
+  /** Explicit nonblocking completion wait group for this background agent. */
+  waitGroupId?: string;
   /** Path to the streaming output transcript file. */
   outputFile?: string;
   /** Absolute path to the durable project-local transcript while live. */
@@ -164,6 +166,10 @@ export interface NotificationDetails {
   resultPreview: string;
   /** Additional agents in a group notification. */
   others?: NotificationDetails[];
+  /** Stable ID for an explicit wait-group notification. */
+  groupId?: string;
+  /** Human-readable summary for an explicit wait-group notification. */
+  groupSummary?: string;
 }
 
 export interface EnvInfo {

package/src/wait-group.ts

@@ -0,0 +1,190 @@
+/**
+ * wait-group.ts — Explicit, nonblocking completion wait groups.
+ *
+ * Unlike GroupJoinManager, wait groups never time out or partially deliver.
+ * A group delivers exactly once after it has been sealed and every member has
+ * reached a terminal state.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { AgentRecord } from "./types.js";
+
+export const TERMINAL_AGENT_STATUSES = [
+  "completed",
+  "steered",
+  "error",
+  "stopped",
+  "aborted",
+] as const;
+
+export type TerminalAgentStatus = (typeof TERMINAL_AGENT_STATUSES)[number];
+
+export interface WaitGroupSnapshot {
+  groupId: string;
+  summary: string;
+  agentIds: readonly string[];
+  sealed: boolean;
+  delivered: boolean;
+}
+
+type WaitGroup = {
+  groupId: string;
+  summary: string;
+  agentIds: Set<string>;
+  completedRecords: Map<string, AgentRecord>;
+  sealed: boolean;
+  delivered: boolean;
+};
+
+export type WaitGroupDeliveryCallback = (
+  groupId: string,
+  summary: string,
+  records: AgentRecord[],
+) => void;
+
+function normalizeSummary(summary: string): string {
+  const normalized = summary.trim();
+  if (!normalized) throw new Error("Wait group summary must not be empty.");
+  return normalized;
+}
+
+function createGroupId(): string {
+  return `wait-${randomUUID().slice(0, 17)}`;
+}
+
+export function isTerminalAgentStatus(status: AgentRecord["status"]): status is TerminalAgentStatus {
+  return (TERMINAL_AGENT_STATUSES as readonly string[]).includes(status);
+}
+
+export class WaitGroupManager {
+  private groups = new Map<string, WaitGroup>();
+  private agentToGroup = new Map<string, string>();
+
+  constructor(private deliverCb: WaitGroupDeliveryCallback) {}
+
+  create(summary: string, requestedGroupId?: string): string {
+    const groupId = requestedGroupId?.trim() || createGroupId();
+    if (!groupId) throw new Error("Wait group ID must not be empty.");
+    if (this.groups.has(groupId)) throw new Error(`Wait group already exists: "${groupId}".`);
+
+    this.groups.set(groupId, {
+      groupId,
+      summary: normalizeSummary(summary),
+      agentIds: new Set(),
+      completedRecords: new Map(),
+      sealed: false,
+      delivered: false,
+    });
+    return groupId;
+  }
+
+  update(groupId: string, summary: string): void {
+    const group = this.requireGroup(groupId);
+    if (group.delivered) throw new Error(`Wait group "${groupId}" has already delivered.`);
+    group.summary = normalizeSummary(summary);
+  }
+
+  addAgent(groupId: string, agentId: string): void {
+    const group = this.requireGroup(groupId);
+    if (group.delivered) throw new Error(`Wait group "${groupId}" has already delivered.`);
+    if (group.sealed) throw new Error(`Wait group "${groupId}" is already sealed.`);
+
+    const existingGroupId = this.agentToGroup.get(agentId);
+    if (existingGroupId && existingGroupId !== groupId) {
+      throw new Error(`Agent "${agentId}" already belongs to wait group "${existingGroupId}".`);
+    }
+
+    group.agentIds.add(agentId);
+    this.agentToGroup.set(agentId, groupId);
+  }
+
+  removeAgent(groupId: string, agentId: string): void {
+    const group = this.groups.get(groupId);
+    if (!group || group.delivered) return;
+    group.agentIds.delete(agentId);
+    group.completedRecords.delete(agentId);
+    this.agentToGroup.delete(agentId);
+    if (group.agentIds.size === 0 && !group.sealed) this.groups.delete(groupId);
+  }
+
+  /**
+   * Seal a group. Returns true when this call delivered the group, otherwise
+   * false when members are still running or it was already sealed.
+   */
+  seal(groupId: string): boolean {
+    const group = this.requireGroup(groupId);
+    if (group.delivered) return false;
+    if (group.sealed) return false;
+    group.sealed = true;
+    return this.tryDeliver(group);
+  }
+
+  /** Register a terminal completion and deliver if the sealed group is ready. */
+  onAgentComplete(record: AgentRecord): "pass" | "held" | "delivered" {
+    const groupId = this.agentToGroup.get(record.id);
+    if (!groupId) return "pass";
+
+    const group = this.groups.get(groupId);
+    if (!group) return "pass";
+    if (!isTerminalAgentStatus(record.status)) return "held";
+    if (group.delivered) return "delivered";
+
+    group.completedRecords.set(record.id, record);
+    return this.tryDeliver(group) ? "delivered" : "held";
+  }
+
+  hasGroup(groupId: string): boolean {
+    return this.groups.has(groupId);
+  }
+
+  getGroup(groupId: string): WaitGroupSnapshot | undefined {
+    const group = this.groups.get(groupId);
+    if (!group) return undefined;
+    return {
+      groupId: group.groupId,
+      summary: group.summary,
+      agentIds: [...group.agentIds],
+      sealed: group.sealed,
+      delivered: group.delivered,
+    };
+  }
+
+  /** Remove an empty implicit group when its spawn failed before registration. */
+  discard(groupId: string): void {
+    const group = this.groups.get(groupId);
+    if (!group || group.agentIds.size > 0 || group.delivered) return;
+    this.groups.delete(groupId);
+  }
+
+  isGrouped(agentId: string): boolean {
+    return this.agentToGroup.has(agentId);
+  }
+
+  private requireGroup(groupId: string): WaitGroup {
+    const group = this.groups.get(groupId);
+    if (!group) throw new Error(`Wait group not found: "${groupId}".`);
+    return group;
+  }
+
+  private tryDeliver(group: WaitGroup): boolean {
+    if (group.delivered || !group.sealed || group.agentIds.size === 0) return false;
+    if ([...group.agentIds].some(id => !group.completedRecords.has(id))) return false;
+
+    group.delivered = true;
+    // Preserve join order in the notification rather than completion order.
+    const records = [...group.agentIds]
+      .map(id => group.completedRecords.get(id))
+      .filter((record): record is AgentRecord => record !== undefined);
+    this.deliverCb(group.groupId, group.summary, records);
+    for (const id of group.agentIds) {
+      this.agentToGroup.delete(id);
+    }
+    this.groups.delete(group.groupId);
+    return true;
+  }
+
+  dispose(): void {
+    this.groups.clear();
+    this.agentToGroup.clear();
+  }
+}