@esso0428/pi-subagents 0.17.18 → 0.17.20

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.17.20] - 2026-10-01
+
+### Changed
+- **Removed blocking waits from `get_subagent_result`**: the legacy `wait` parameter is now a non-blocking compatibility flag. Running or queued agents return their current status immediately, while background and wait-group completion notifications remain the expandable output surface for finished results.
+
+## [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

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:
@@ -400,10 +432,10 @@ Check status and retrieve results from a background agent.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `agent_id` | string | yes | Agent ID to check |
-| `wait` | boolean | no | Wait for completion |
+| `wait` | boolean | no | Deprecated compatibility flag; never blocks |
 | `verbose` | boolean | no | Include full conversation log |
 
-Cancelling a `wait: true` call (for example, with `Esc`) stops only the wait. The background agent keeps running, and its completion notification still arrives normally.
+`get_subagent_result` never blocks. If an agent is still running or queued, the tool returns the current status immediately; wait for the background or wait-group completion notification for the expandable final output.
 
 ### `steer_subagent`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esso0428/pi-subagents",
-  "version": "0.17.18",
+  "version": "0.17.20",
   "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 ----
 
@@ -59,39 +61,6 @@ function textResult(msg: string, details?: AgentDetails) {
   return { content: [{ type: "text" as const, text: msg }], details: details as any };
 }
 
-/** Await a promise until it settles or the caller cancels, without aborting the underlying work. */
-function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
-  if (!signal) return promise;
-  if (signal.aborted) return Promise.reject(signal.reason);
-
-  return new Promise<T>((resolve, reject) => {
-    let settled = false;
-    const cleanup = () => signal.removeEventListener("abort", onAbort);
-    const onAbort = () => {
-      if (settled) return;
-      settled = true;
-      cleanup();
-      reject(signal.reason);
-    };
-
-    signal.addEventListener("abort", onAbort, { once: true });
-    promise.then(
-      (value) => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        resolve(value);
-      },
-      (error: unknown) => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        reject(error);
-      },
-    );
-  });
-}
-
 export function renderRunningAgentStatus(
   frame: string,
   statsText: string,
@@ -310,7 +279,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);
     }
   );
 
@@ -332,9 +304,6 @@ export default function (pi: ExtensionAPI) {
   // before they reach pi.sendMessage (fire-and-forget).
   const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
   const NUDGE_HOLD_MS = 200;
-  // A queued result wait must observe completion before its held notification
-  // can fire, so successful waits can still suppress that redundant nudge.
-  const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
 
   function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
     cancelNudge(key);
@@ -411,6 +380,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 +468,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 +649,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 +874,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 +899,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 +979,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 +1014,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 +1206,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 +1268,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 +1353,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 +1388,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 +1410,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 +1443,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 +1570,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({
@@ -1508,7 +1653,7 @@ Terse command-style prompts produce shallow, generic work.
       }),
       wait: Type.Optional(
         Type.Boolean({
-          description: "If true, wait for the agent to complete before returning. Default: false.",
+          description: "Deprecated compatibility flag. Results never block; running agents return current status immediately.",
         }),
       ),
       verbose: Type.Optional(
@@ -1517,27 +1662,12 @@ Terse command-style prompts produce shallow, generic work.
         }),
       ),
     }),
-    execute: async (_toolCallId, params, signal, _onUpdate, _ctx) => {
+    execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
       const record = manager.getRecord(params.agent_id);
       if (!record) {
         return textResult(`Agent not found: "${params.agent_id}". It may have been cleaned up.`);
       }
 
-      // Wait for completion if requested. Cancellation stops only this tool
-      // call; the background agent keeps running and remains unconsumed so its
-      // completion notification can still be delivered.
-      // Queued agents have no promise yet (it's created when the queue starts
-      // them), so poll until they leave the queue, then await like a running one.
-      if (params.wait && (record.status === "running" || record.status === "queued")) {
-        while (record.status === "queued") {
-          await abortable(
-            new Promise<void>((resolve) => setTimeout(resolve, QUEUE_WAIT_POLL_MS)),
-            signal,
-          );
-        }
-        if (record.promise) await abortable(record.promise, signal);
-      }
-
       const durableResult = !record.result?.trim() && record.transcriptPath && currentCtx?.cwd
         ? readAgentHistoryResult(currentCtx.cwd, record.transcriptPath)
         : undefined;
@@ -1556,8 +1686,10 @@ Terse command-style prompts produce shallow, generic work.
         `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
         `Description: ${record.description}\n\n`;
 
-      if (record.status === "running") {
-        output += "Agent is still running. Use wait: true or check back later.";
+      if (record.status === "running" || record.status === "queued") {
+        output += params.wait
+          ? `Agent is still ${record.status}. wait:true is deprecated and no longer blocks; wait for the background completion notification or check again later.`
+          : `Agent is still ${record.status}. Wait for the background completion notification or check again later.`;
       } else if (record.status === "error") {
         output += `Error: ${record.error}${partialOutputSuffix(record, durableResult)}`;
       } else {

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();
+  }
+}