@tintinweb/pi-subagents 0.2.3 → 0.2.6

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.6] - 2026-03-07
+
+### Added
+- **Background task join strategies** — smart grouping of background agent completion notifications
+  - `smart` (default): 2+ background agents spawned in the same turn are auto-grouped into a single consolidated notification instead of individual nudges
+  - `async`: each agent notifies individually on completion (previous behavior)
+  - `group`: force grouping even for solo agents
+  - 30s timeout after first completion delivers partial results; 15s straggler re-batch window for remaining agents
+- **`join_mode` parameter** on the `Agent` tool — override join strategy per agent (`"async"` or `"group"`)
+- **Join mode setting** in `/agents` → Settings — configure the default join mode at runtime
+- New `src/group-join.ts` — `GroupJoinManager` class for batched completion notifications
+
+### Changed
+- `AgentRecord` now includes optional `groupId`, `joinMode`, and `resultConsumed` fields
+- Background agent completion routing refactored: individual nudge logic extracted to `sendIndividualNudge()`, group delivery via `GroupJoinManager`
+
+### Fixed
+- **Debounce window race** — agents that complete during the 100ms batch debounce window are now deferred and retroactively fed into the group once it's registered, preventing split notifications (one individual + one partial group) and zombie groups
+- **Solo agent swallowed notification** — if only one agent was spawned (no group formed) but it completed during the debounce window, its deferred notification is now sent when the batch finalizes
+- **Duplicate notifications after polling** — calling `get_subagent_result` on a completed agent now marks its result as consumed, suppressing the subsequent completion notification (both individual and group)
+
+## [0.2.5] - 2026-03-06
+
+### Added
+- **Interactive `/agents` menu** — single command replaces `/agent` and `/agents` with a full management wizard
+  - Browse and manage running agents
+  - Custom agents submenu — edit or delete existing agents
+  - Create new custom agents via manual wizard or AI-generated (with comprehensive frontmatter documentation for the generator)
+  - Settings: configure max concurrency, default max turns, and grace turns at runtime
+  - Built-in agent types shown with model info (e.g. `Explore · haiku`)
+  - Aligned formatting for agent lists
+- **Configurable turn limits** — `defaultMaxTurns` and `graceTurns` are now runtime-adjustable via `/agents` → Settings
+- Sub-menus return to main menu instead of exiting
+
+### Removed
+- `/agent <type> <prompt>` command (use `Agent` tool directly, or create custom agents via `/agents`)
+
+## [0.2.4] - 2026-03-06
+
+### Added
+- **Global custom agents** — agents in `~/.pi/agent/agents/*.md` are now discovered automatically and available across all projects
+- Two-tier discovery hierarchy: project-level (`.pi/agents/`) overrides global (`~/.pi/agent/agents/`)
+
 ## [0.2.3] - 2026-03-05
 
 ### Added
@@ -82,6 +125,9 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.2.6]: https://github.com/tintinweb/pi-subagents/compare/v0.2.5...v0.2.6
+[0.2.5]: https://github.com/tintinweb/pi-subagents/compare/v0.2.4...v0.2.5
+[0.2.4]: https://github.com/tintinweb/pi-subagents/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/tintinweb/pi-subagents/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/tintinweb/pi-subagents/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/tintinweb/pi-subagents/compare/v0.2.0...v0.2.1

package/README.md

@@ -6,10 +6,14 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 
 <img width="600" alt="pi-subagents screenshot" src="https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png" />
 
+
+https://github.com/user-attachments/assets/5d1331e8-6d02-420b-b30a-dcbf838b1660
+
+
 ## Features
 
 - **Claude Code look & feel** — same tool names, calling conventions, and UI patterns (`Agent`, `get_subagent_result`, `steer_subagent`) — feels native
-- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4)
+- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and smart group join (consolidated notifications)
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
@@ -83,7 +87,16 @@ Completed results can be expanded (ctrl+o in pi) to show the full agent output i
 
 ## Custom Agents
 
-Define custom agent types by creating `.pi/agents/<name>.md` files. The filename becomes the agent type name.
+Define custom agent types by creating `.md` files. The filename becomes the agent type name.
+
+Custom agents are discovered from two locations (higher priority wins):
+
+| Priority | Location | Scope |
+|----------|----------|-------|
+| 1 (highest) | `.pi/agents/<name>.md` | Project — per-repo agents |
+| 2 | `~/.pi/agent/agents/<name>.md` | Global — available everywhere |
+
+Project-level agents override global ones with the same name, so you can customize a global agent for a specific project.
 
 ### Example: `.pi/agents/auditor.md`
 
@@ -149,6 +162,7 @@ Launch a sub-agent.
 | `resume` | string | no | Agent ID to resume a previous session |
 | `isolated` | boolean | no | No extension/MCP tools |
 | `inherit_context` | boolean | no | Fork parent conversation into agent |
+| `join_mode` | `"async"` \| `"group"` | no | Override join strategy for background completion notifications (default: smart) |
 
 ### `get_subagent_result`
 
@@ -173,15 +187,27 @@ Send a steering message to a running agent. The message interrupts after the cur
 
 | Command | Description |
 |---------|-------------|
-| `/agent <type> <prompt>` | Spawn a sub-agent interactively |
-| `/agents` | List all agents with status tree |
+| `/agents` | Interactive agent management menu |
+
+The `/agents` command opens an interactive menu:
 
 ```
-/agent Explore Find all TypeScript files that handle authentication
-/agent Plan Design a caching layer for the API
-/agent auditor Review the payment processing module
+Running agents (2) — 1 running, 1 done     ← only shown when agents exist
+Custom agents (3)                           ← submenu: edit or delete agents
+Create new agent                            ← manual wizard or AI-generated
+Settings                                    ← max concurrency, max turns, grace turns, join mode
+
+Built-in (always available):
+  general-purpose · inherit
+  Explore         · haiku
+  Plan            · inherit
+  ...
 ```
 
+- **Custom agents submenu** — select an agent to edit (opens editor) or delete
+- **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file)
+- **Settings** — configure max concurrency, default max turns, grace turns, and join mode at runtime
+
 ## Graceful Max Turns
 
 Instead of hard-aborting at the turn limit, agents get a graceful shutdown:
@@ -203,6 +229,22 @@ Background agents are subject to a configurable concurrency limit (default: 4).
 
 Foreground agents bypass the queue — they block the parent anyway.
 
+## Join Strategies
+
+When background agents complete, they notify the main agent. The **join mode** controls how these notifications are delivered:
+
+| Mode | Behavior |
+|------|----------|
+| `smart` (default) | 2+ background agents spawned in the same turn are auto-grouped into a single consolidated notification. Solo agents notify individually. |
+| `async` | Each agent sends its own notification on completion (original behavior). Best when results need incremental processing. |
+| `group` | Force grouping even when spawning a single agent. Useful when you know more agents will follow. |
+
+**Timeout behavior:** When agents are grouped, a 30-second timeout starts after the first agent completes. If not all agents finish in time, a partial notification is sent with completed results and remaining agents continue with a shorter 15-second re-batch window for stragglers.
+
+**Configuration:**
+- Per-call: `Agent({ ..., join_mode: "async" })` overrides for that agent
+- Global default: `/agents` → Settings → Join mode
+
 ## Architecture
 
 ```
@@ -212,6 +254,7 @@ src/
   agent-types.ts      # Agent type registry (built-in + custom), tool factories
   agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
+  group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load custom agents from .pi/agents/*.md
   prompts.ts          # System prompts per agent type
   context.ts          # Parent conversation context for inherit_context

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.2.3",
-  "description": "A pi extension providing autonomous sub-agents with Claude Code-style UI",
+  "version": "0.2.6",
+  "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
   "repository": {

package/src/agent-runner.ts

@@ -23,10 +23,20 @@ import type { SubagentType, ThinkingLevel } from "./types.js";
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
 
 /** Default max turns to prevent subagents from looping indefinitely. */
-const DEFAULT_MAX_TURNS = 50;
+let defaultMaxTurns = 50;
+
+/** Get the default max turns value. */
+export function getDefaultMaxTurns(): number { return defaultMaxTurns; }
+/** Set the default max turns value (minimum 1). */
+export function setDefaultMaxTurns(n: number): void { defaultMaxTurns = Math.max(1, n); }
 
 /** Additional turns allowed after the soft limit steer message. */
-const GRACE_TURNS = 5;
+let graceTurns = 5;
+
+/** Get the grace turns value. */
+export function getGraceTurns(): number { return graceTurns; }
+/** Set the grace turns value (minimum 1). */
+export function setGraceTurns(n: number): void { graceTurns = Math.max(1, n); }
 
 /** Haiku model IDs to try for Explore agents (in preference order). */
 const HAIKU_MODEL_IDS = [
@@ -215,7 +225,7 @@ export async function runAgent(
 
   // Track turns for graceful max_turns enforcement
   let turnCount = 0;
-  const maxTurns = options.maxTurns ?? customConfig?.maxTurns ?? DEFAULT_MAX_TURNS;
+  const maxTurns = options.maxTurns ?? customConfig?.maxTurns ?? defaultMaxTurns;
   let softLimitReached = false;
   let aborted = false;
 
@@ -226,7 +236,7 @@ export async function runAgent(
       if (!softLimitReached && turnCount >= maxTurns) {
         softLimitReached = true;
         session.steer("You have reached your turn limit. Wrap up immediately — provide your final answer now.");
-      } else if (softLimitReached && turnCount >= maxTurns + GRACE_TURNS) {
+      } else if (softLimitReached && turnCount >= maxTurns + graceTurns) {
         aborted = true;
         session.abort();
       }

package/src/custom-agents.ts

@@ -1,30 +1,43 @@
 /**
- * custom-agents.ts — Load user-defined agents from .pi/agents/*.md files.
+ * custom-agents.ts — Load user-defined agents from project (.pi/agents/) and global (~/.pi/agent/agents/) locations.
  */
 
 import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
+import { homedir } from "node:os";
 import { SUBAGENT_TYPES, type CustomAgentConfig, type ThinkingLevel } from "./types.js";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 
 /**
- * Scan .pi/agents/*.md and return a map of custom agent configs.
- * Filename (without .md) becomes the agent name.
+ * Scan for custom agent .md files from multiple locations.
+ * Discovery hierarchy (higher priority wins):
+ *   1. Project: <cwd>/.pi/agents/*.md
+ *   2. Global:  ~/.pi/agent/agents/*.md
+ *
+ * Project-level agents override global ones with the same name.
  */
 export function loadCustomAgents(cwd: string): Map<string, CustomAgentConfig> {
-  const dir = join(cwd, ".pi", "agents");
-  if (!existsSync(dir)) return new Map();
+  const globalDir = join(homedir(), ".pi", "agent", "agents");
+  const projectDir = join(cwd, ".pi", "agents");
+
+  const agents = new Map<string, CustomAgentConfig>();
+  loadFromDir(globalDir, agents);   // lower priority
+  loadFromDir(projectDir, agents);  // higher priority (overwrites)
+  return agents;
+}
+
+/** Load agent configs from a directory into the map. */
+function loadFromDir(dir: string, agents: Map<string, CustomAgentConfig>): void {
+  if (!existsSync(dir)) return;
 
   let files: string[];
   try {
     files = readdirSync(dir).filter(f => f.endsWith(".md"));
   } catch {
-    return new Map();
+    return;
   }
 
-  const agents = new Map<string, CustomAgentConfig>();
-
   for (const file of files) {
     const name = basename(file, ".md");
     if ((SUBAGENT_TYPES as readonly string[]).includes(name)) continue;
@@ -54,8 +67,6 @@ export function loadCustomAgents(cwd: string): Map<string, CustomAgentConfig> {
       isolated: fm.isolated === true,
     });
   }
-
-  return agents;
 }
 
 // ---- Field parsers ----

package/src/group-join.ts

@@ -0,0 +1,141 @@
+/**
+ * group-join.ts — Manages grouped background agent completion notifications.
+ *
+ * Instead of each agent individually nudging the main agent on completion,
+ * agents in a group are held until all complete (or a timeout fires),
+ * then a single consolidated notification is sent.
+ */
+
+import type { AgentRecord } from "./types.js";
+
+export type DeliveryCallback = (records: AgentRecord[], partial: boolean) => void;
+
+interface AgentGroup {
+  groupId: string;
+  agentIds: Set<string>;
+  completedRecords: Map<string, AgentRecord>;
+  timeoutHandle?: ReturnType<typeof setTimeout>;
+  delivered: boolean;
+  /** Shorter timeout for stragglers after a partial delivery. */
+  isStraggler: boolean;
+}
+
+/** Default timeout: 30s after first completion in a group. */
+const DEFAULT_TIMEOUT = 30_000;
+/** Straggler re-batch timeout: 15s. */
+const STRAGGLER_TIMEOUT = 15_000;
+
+export class GroupJoinManager {
+  private groups = new Map<string, AgentGroup>();
+  private agentToGroup = new Map<string, string>();
+
+  constructor(
+    private deliverCb: DeliveryCallback,
+    private groupTimeout = DEFAULT_TIMEOUT,
+  ) {}
+
+  /** Register a group of agent IDs that should be joined. */
+  registerGroup(groupId: string, agentIds: string[]): void {
+    const group: AgentGroup = {
+      groupId,
+      agentIds: new Set(agentIds),
+      completedRecords: new Map(),
+      delivered: false,
+      isStraggler: false,
+    };
+    this.groups.set(groupId, group);
+    for (const id of agentIds) {
+      this.agentToGroup.set(id, groupId);
+    }
+  }
+
+  /**
+   * Called when an agent completes.
+   * Returns:
+   * - 'pass'      — agent is not grouped, caller should send individual nudge
+   * - 'held'      — result held, waiting for group completion
+   * - 'delivered'  — this completion triggered the group notification
+   */
+  onAgentComplete(record: AgentRecord): 'delivered' | 'held' | 'pass' {
+    const groupId = this.agentToGroup.get(record.id);
+    if (!groupId) return 'pass';
+
+    const group = this.groups.get(groupId);
+    if (!group || group.delivered) return 'pass';
+
+    group.completedRecords.set(record.id, record);
+
+    // All done — deliver immediately
+    if (group.completedRecords.size >= group.agentIds.size) {
+      this.deliver(group, false);
+      return 'delivered';
+    }
+
+    // First completion in this batch — start timeout
+    if (!group.timeoutHandle) {
+      const timeout = group.isStraggler ? STRAGGLER_TIMEOUT : this.groupTimeout;
+      group.timeoutHandle = setTimeout(() => {
+        this.onTimeout(group);
+      }, timeout);
+    }
+
+    return 'held';
+  }
+
+  private onTimeout(group: AgentGroup): void {
+    if (group.delivered) return;
+    group.timeoutHandle = undefined;
+
+    // Partial delivery — some agents still running
+    const remaining = new Set<string>();
+    for (const id of group.agentIds) {
+      if (!group.completedRecords.has(id)) remaining.add(id);
+    }
+
+    // Clean up agentToGroup for delivered agents (they won't complete again)
+    for (const id of group.completedRecords.keys()) {
+      this.agentToGroup.delete(id);
+    }
+
+    // Deliver what we have
+    this.deliverCb([...group.completedRecords.values()], true);
+
+    // Set up straggler group for remaining agents
+    group.completedRecords.clear();
+    group.agentIds = remaining;
+    group.isStraggler = true;
+    // Timeout will be started when the next straggler completes
+  }
+
+  private deliver(group: AgentGroup, partial: boolean): void {
+    if (group.timeoutHandle) {
+      clearTimeout(group.timeoutHandle);
+      group.timeoutHandle = undefined;
+    }
+    group.delivered = true;
+    this.deliverCb([...group.completedRecords.values()], partial);
+    this.cleanupGroup(group.groupId);
+  }
+
+  private cleanupGroup(groupId: string): void {
+    const group = this.groups.get(groupId);
+    if (!group) return;
+    for (const id of group.agentIds) {
+      this.agentToGroup.delete(id);
+    }
+    this.groups.delete(groupId);
+  }
+
+  /** Check if an agent is in a group. */
+  isGrouped(agentId: string): boolean {
+    return this.agentToGroup.has(agentId);
+  }
+
+  dispose(): void {
+    for (const group of this.groups.values()) {
+      if (group.timeoutHandle) clearTimeout(group.timeoutHandle);
+    }
+    this.groups.clear();
+    this.agentToGroup.clear();
+  }
+}

package/src/index.ts

@@ -7,17 +7,20 @@
  *   steer_subagent       — LLM-callable: send a steering message to a running agent
  *
  * Commands:
- *   /agent <type> <prompt>  — User-invocable agent spawning
- *   /agents                 — List all agents with status
+ *   /agents                 — Interactive agent management menu
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import { existsSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
 import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { steerAgent, getAgentConversation } from "./agent-runner.js";
-import { SUBAGENT_TYPES, type SubagentType, type ThinkingLevel, type CustomAgentConfig } from "./types.js";
-import { getConfig, getAvailableTypes, getCustomAgentNames, getCustomAgentConfig, isValidType, registerCustomAgents } from "./agent-types.js";
+import { steerAgent, getAgentConversation, getDefaultMaxTurns, setDefaultMaxTurns, getGraceTurns, setGraceTurns } from "./agent-runner.js";
+import { SUBAGENT_TYPES, type SubagentType, type ThinkingLevel, type CustomAgentConfig, type JoinMode, type AgentRecord } from "./types.js";
+import { GroupJoinManager } from "./group-join.js";
+import { getAvailableTypes, getCustomAgentNames, getCustomAgentConfig, isValidType, registerCustomAgents, BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import {
   AgentWidget,
@@ -200,13 +203,11 @@ export default function (pi: ExtensionAPI) {
   // ---- Agent activity tracking + widget ----
   const agentActivity = new Map<string, AgentActivity>();
 
-  // Background completion: push notification into conversation
-  const manager = new AgentManager((record) => {
+  // ---- Individual nudge helper (async join mode) ----
+  function sendIndividualNudge(record: AgentRecord) {
     const displayName = getDisplayName(record.type);
     const duration = formatDuration(record.startedAt, record.completedAt);
-
     const status = getStatusLabel(record.status, record.error);
-
     const resultPreview = record.result
       ? record.result.length > 500
         ? record.result.slice(0, 500) + "\n...(truncated, use get_subagent_result for full output)"
@@ -216,7 +217,6 @@ export default function (pi: ExtensionAPI) {
     agentActivity.delete(record.id);
     widget.markFinished(record.id);
 
-    // Poke the main agent so it processes the result (queues as follow-up if busy)
     pi.sendUserMessage(
       `Background agent completed: ${displayName} (${record.description})\n` +
       `Agent ID: ${record.id} | Status: ${status} | Tool uses: ${record.toolUses} | Duration: ${duration}\n\n` +
@@ -224,11 +224,128 @@ export default function (pi: ExtensionAPI) {
       { deliverAs: "followUp" },
     );
     widget.update();
+  }
+
+  /** Format a single agent's summary for grouped notification. */
+  function formatAgentSummary(record: AgentRecord): string {
+    const displayName = getDisplayName(record.type);
+    const duration = formatDuration(record.startedAt, record.completedAt);
+    const status = getStatusLabel(record.status, record.error);
+    const resultPreview = record.result
+      ? record.result.length > 300
+        ? record.result.slice(0, 300) + "\n...(truncated)"
+        : record.result
+      : "No output.";
+    return `- ${displayName} (${record.description})\n  ID: ${record.id} | Status: ${status} | Tools: ${record.toolUses} | Duration: ${duration}\n  ${resultPreview}`;
+  }
+
+  // ---- Group join manager ----
+  const groupJoin = new GroupJoinManager(
+    (records, partial) => {
+      // Filter out agents whose results were already consumed via get_subagent_result
+      const unconsumed = records.filter(r => !r.resultConsumed);
+
+      for (const r of records) {
+        agentActivity.delete(r.id);
+        widget.markFinished(r.id);
+      }
+
+      // If all results were already consumed, skip the notification entirely
+      if (unconsumed.length === 0) {
+        widget.update();
+        return;
+      }
+
+      const total = unconsumed.length;
+      const label = partial ? `${total} agent(s) finished (partial — others still running)` : `${total} agent(s) finished`;
+      const summary = unconsumed.map(r => formatAgentSummary(r)).join("\n\n");
+
+      pi.sendUserMessage(
+        `Background agent group completed: ${label}\n\n${summary}\n\nUse get_subagent_result for full output.`,
+        { deliverAs: "followUp" },
+      );
+      widget.update();
+    },
+    30_000,
+  );
+
+  // Background completion: route through group join or send individual nudge
+  const manager = new AgentManager((record) => {
+    // Skip notification if result was already consumed via get_subagent_result
+    if (record.resultConsumed) {
+      agentActivity.delete(record.id);
+      widget.markFinished(record.id);
+      widget.update();
+      return;
+    }
+
+    // If this agent is pending batch finalization (debounce window still open),
+    // don't send an individual nudge — finalizeBatch will pick it up retroactively.
+    if (currentBatchAgents.some(a => a.id === record.id)) {
+      widget.update();
+      return;
+    }
+
+    const result = groupJoin.onAgentComplete(record);
+    if (result === 'pass') {
+      sendIndividualNudge(record);
+    }
+    // 'held' → do nothing, group will fire later
+    // 'delivered' → group callback already fired
+    widget.update();
   });
 
   // Live widget: show running agents above editor
   const widget = new AgentWidget(manager, agentActivity);
 
+  // ---- Join mode configuration ----
+  let defaultJoinMode: JoinMode = 'smart';
+  function getDefaultJoinMode(): JoinMode { return defaultJoinMode; }
+  function setDefaultJoinMode(mode: JoinMode) { defaultJoinMode = mode; }
+
+  // ---- Batch tracking for smart join mode ----
+  // Collects background agent IDs spawned in the current turn for smart grouping.
+  // Uses a debounced timer: each new agent resets the 100ms window so that all
+  // parallel tool calls (which may be dispatched across multiple microtasks by the
+  // framework) are captured in the same batch.
+  let currentBatchAgents: { id: string; joinMode: JoinMode }[] = [];
+  let batchFinalizeTimer: ReturnType<typeof setTimeout> | undefined;
+  let batchCounter = 0;
+
+  /** Finalize the current batch: if 2+ smart-mode agents, register as a group. */
+  function finalizeBatch() {
+    batchFinalizeTimer = undefined;
+    const batchAgents = [...currentBatchAgents];
+    currentBatchAgents = [];
+
+    const smartAgents = batchAgents.filter(a => a.joinMode === 'smart' || a.joinMode === 'group');
+    if (smartAgents.length >= 2) {
+      const groupId = `batch-${++batchCounter}`;
+      const ids = smartAgents.map(a => a.id);
+      groupJoin.registerGroup(groupId, ids);
+      // Retroactively process agents that already completed during the debounce window.
+      // Their onComplete fired but was deferred (agent was in currentBatchAgents),
+      // so we feed them into the group now.
+      for (const id of ids) {
+        const record = manager.getRecord(id);
+        if (!record) continue;
+        record.groupId = groupId;
+        if (record.completedAt != null && !record.resultConsumed) {
+          groupJoin.onAgentComplete(record);
+        }
+      }
+    } else {
+      // No group formed — send individual nudges for any agents that completed
+      // during the debounce window and had their notification deferred.
+      for (const { id } of batchAgents) {
+        const record = manager.getRecord(id);
+        if (record?.completedAt != null && !record.resultConsumed) {
+          sendIndividualNudge(record);
+        }
+      }
+    }
+  }
+
   // Grab UI context from first tool execution + clear lingering widget on new turn
   pi.on("tool_execution_start", async (_event, ctx) => {
     widget.setUICtx(ctx.ui as UICtx);
@@ -256,7 +373,7 @@ export default function (pi: ExtensionAPI) {
       ...builtinDescs,
       ...(customDescs.length > 0 ? ["", "Custom types:", ...customDescs] : []),
       "",
-      "Custom agents can be defined in .pi/agents/<name>.md — they are picked up automatically.",
+      "Custom agents can be defined in .pi/agents/<name>.md (project) or ~/.pi/agent/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones.",
     ].join("\n");
   };
 
@@ -286,7 +403,8 @@ Guidelines:
 - Use steer_subagent to send mid-run messages to a running background agent.
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
-- Use inherit_context if the agent needs the parent conversation history.`,
+- Use inherit_context if the agent needs the parent conversation history.
+- Use join_mode to control how background completion notifications are delivered. By default (smart), 2+ background agents spawned in the same turn are grouped into a single notification. Use "async" for individual notifications or "group" to force grouping.`,
     parameters: Type.Object({
       prompt: Type.String({
         description: "The task for the agent to perform.",
@@ -295,7 +413,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Built-in: ${SUBAGENT_TYPES.join(", ")}. Custom agents from .pi/agents/*.md are also available.`,
+        description: `The type of specialized agent to use. Built-in: ${SUBAGENT_TYPES.join(", ")}. Custom agents from .pi/agents/*.md (project) or ~/.pi/agent/agents/*.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -334,6 +452,12 @@ Guidelines:
           description: "If true, fork parent conversation into the agent. Default: false (fresh context).",
         }),
       ),
+      join_mode: Type.Optional(
+        Type.Union([
+          Type.Literal("async"),
+          Type.Literal("group"),
+        ], { description: "Override join behavior for background agents. async: individual nudge on completion. group: hold and send one consolidated notification when all agents in the group complete. Default: smart (auto-groups 2+ background agents spawned in the same turn)." }),
+      ),
     }),
 
     // ---- Custom rendering: Claude Code style ----
@@ -518,10 +642,25 @@ Guidelines:
           ...bgCallbacks,
         });
 
+        // Determine join mode and track for batching
+        const joinMode: JoinMode = params.join_mode ?? defaultJoinMode;
+        const record = manager.getRecord(id);
+        if (record) record.joinMode = joinMode;
+
+        if (joinMode === 'async') {
+          // Explicit async — not part of any batch
+        } else {
+          // smart or group — add to current batch
+          currentBatchAgents.push({ id, joinMode });
+          // Debounce: reset timer on each new agent so parallel tool calls
+          // dispatched across multiple event loop ticks are captured together
+          if (batchFinalizeTimer) clearTimeout(batchFinalizeTimer);
+          batchFinalizeTimer = setTimeout(finalizeBatch, 100);
+        }
+
         agentActivity.set(id, bgState);
         widget.ensureTimer();
         widget.update();
-        const record = manager.getRecord(id);
         const isQueued = record?.status === "queued";
         return textResult(
           `Agent ${isQueued ? "queued" : "started"} in background.\n` +
@@ -668,6 +807,11 @@ Guidelines:
         output += record.result ?? "No output.";
       }
 
+      // Mark result as consumed — suppresses the completion notification
+      if (record.status !== "running" && record.status !== "queued") {
+        record.resultConsumed = true;
+      }
+
       // Verbose: include full conversation
       if (params.verbose && record.session) {
         const conversation = getAgentConversation(record.session);
@@ -717,139 +861,430 @@ Guidelines:
     },
   });
 
-  // ---- /agent command ----
-
-  pi.registerCommand("agent", {
-    description: "Spawn a sub-agent: /agent <type> <prompt>",
-    handler: async (args, ctx) => {
-      const trimmed = args?.trim() ?? "";
-
-      if (!trimmed) {
-        const lines = [
-          "Usage: /agent <type> <prompt>",
-          "",
-          "Agent types:",
-          ...getAvailableTypes().map(
-            (t) => `  ${t.padEnd(20)} ${getConfig(t).description}`,
-          ),
-          "",
-          "Examples:",
-          "  /agent Explore Find all TypeScript files that handle authentication",
-          "  /agent Plan Design a caching layer for the API",
-          "  /agent general-purpose Refactor the auth module to use JWT",
-        ];
-        ctx.ui.notify(lines.join("\n"), "info");
-        return;
-      }
+  // ---- /agents interactive menu ----
 
-      // Parse: first word is type, rest is prompt
-      const spaceIdx = trimmed.indexOf(" ");
-      if (spaceIdx === -1) {
-        ctx.ui.notify(
-          `Missing prompt. Usage: /agent <type> <prompt>\nTypes: ${getAvailableTypes().join(", ")}`,
-          "warning",
-        );
-        return;
-      }
+  const projectAgentsDir = () => join(process.cwd(), ".pi", "agents");
+  const personalAgentsDir = () => join(homedir(), ".pi", "agent", "agents");
 
-      const typeName = trimmed.slice(0, spaceIdx);
-      const prompt = trimmed.slice(spaceIdx + 1).trim();
+  /** Find the file path of a custom agent by name (project first, then global). */
+  function findAgentFile(name: string): { path: string; location: "project" | "personal" } | undefined {
+    const projectPath = join(projectAgentsDir(), `${name}.md`);
+    if (existsSync(projectPath)) return { path: projectPath, location: "project" };
+    const personalPath = join(personalAgentsDir(), `${name}.md`);
+    if (existsSync(personalPath)) return { path: personalPath, location: "personal" };
+    return undefined;
+  }
 
-      if (!isValidType(typeName)) {
-        ctx.ui.notify(
-          `Unknown agent type: "${typeName}"\nValid types: ${getAvailableTypes().join(", ")}`,
-          "warning",
-        );
-        return;
-      }
+  /** Model label for display: built-in types have known defaults, custom agents show their config. */
+  const BUILTIN_MODEL_LABELS: Record<string, string> = {
+    "general-purpose": "inherit",
+    "Explore": "haiku",
+    "Plan": "inherit",
+    "statusline-setup": "inherit",
+    "claude-code-guide": "inherit",
+  };
 
-      if (!prompt) {
-        ctx.ui.notify("Missing prompt.", "warning");
-        return;
-      }
+  function getModelLabel(type: string): string {
+    const builtin = BUILTIN_MODEL_LABELS[type];
+    if (builtin) return builtin;
+    const custom = getCustomAgentConfig(type);
+    if (custom?.model) {
+      // Show short form: "anthropic/claude-haiku-4-5-20251001" → "haiku"
+      const id = custom.model.toLowerCase();
+      if (id.includes("haiku")) return "haiku";
+      if (id.includes("sonnet")) return "sonnet";
+      if (id.includes("opus")) return "opus";
+      return custom.model;
+    }
+    return "inherit";
+  }
 
-      const displayName = getDisplayName(typeName);
-      ctx.ui.notify(`Spawning ${displayName} agent...`, "info");
+  async function showAgentsMenu(ctx: ExtensionCommandContext) {
+    reloadCustomAgents();
+    const customNames = getCustomAgentNames();
 
-      const customConfig = getCustomAgentConfig(typeName);
-      const { systemPromptOverride, systemPromptAppend } = resolveCustomPrompt(customConfig);
+    // Build select options
+    const options: string[] = [];
 
-      const record = await manager.spawnAndWait(pi, ctx, typeName, prompt, {
-        description: prompt.slice(0, 40),
-        thinkingLevel: customConfig?.thinking,
-        systemPromptOverride,
-        systemPromptAppend,
-      });
+    // Running agents entry (only if there are active agents)
+    const agents = manager.listAgents();
+    if (agents.length > 0) {
+      const running = agents.filter(a => a.status === "running" || a.status === "queued").length;
+      const done = agents.filter(a => a.status === "completed" || a.status === "steered").length;
+      options.push(`Running agents (${agents.length}) — ${running} running, ${done} done`);
+    }
 
-      if (record.status === "error") {
-        ctx.ui.notify(`Agent failed: ${record.error}`, "warning");
-        return;
-      }
+    // Custom agents submenu (only if there are custom agents)
+    if (customNames.length > 0) {
+      options.push(`Custom agents (${customNames.length})`);
+    }
 
-      const duration = formatDuration(record.startedAt, record.completedAt);
-      const statusNote = getStatusNote(record.status);
-
-      // Send the result as a message so it appears in the conversation
-      pi.sendMessage(
-        {
-          customType: "agent-result",
-          content: [
-            {
-              type: "text",
-              text:
-                `**${displayName}** agent completed in ${duration} (${record.toolUses} tool uses)${statusNote}\n\n` +
-                (record.result ?? "No output."),
-            },
-          ],
-          display: true,
-        },
-        { triggerTurn: false },
-      );
-    },
-  });
+    // Actions
+    options.push("Create new agent");
+    options.push("Settings");
 
-  // ---- /agents command ----
+    // Show built-in types below the select as informational text (like Claude does)
+    const maxBuiltin = Math.max(...SUBAGENT_TYPES.map(t => t.length));
+    const builtinLines = SUBAGENT_TYPES.map(t => {
+      const model = BUILTIN_MODEL_LABELS[t] ?? "inherit";
+      return `  ${t.padEnd(maxBuiltin)} · ${model}`;
+    });
 
-  pi.registerCommand("agents", {
-    description: "List all agents with status",
-    handler: async (_args, ctx) => {
-      const agents = manager.listAgents();
+    const noAgentsMsg = customNames.length === 0 && agents.length === 0
+      ? "No agents found. Create specialized subagents that can be delegated to.\n\n" +
+        "Each subagent has its own context window, custom system prompt, and specific tools.\n\n" +
+        "Try creating: Code Reviewer, Security Auditor, Test Writer, or Documentation Writer.\n\n"
+      : "";
 
-      if (agents.length === 0) {
-        ctx.ui.notify("No agents have been spawned yet.", "info");
-        return;
+    ctx.ui.notify(
+      `${noAgentsMsg}Built-in (always available):\n${builtinLines.join("\n")}`,
+      "info",
+    );
+
+    const choice = await ctx.ui.select("Agents", options);
+    if (!choice) return;
+
+    if (choice.startsWith("Running agents (")) {
+      await showRunningAgents(ctx);
+      await showAgentsMenu(ctx);
+    } else if (choice.startsWith("Custom agents (")) {
+      await showCustomAgentsList(ctx);
+      await showAgentsMenu(ctx);
+    } else if (choice === "Create new agent") {
+      await showCreateWizard(ctx);
+    } else if (choice === "Settings") {
+      await showSettings(ctx);
+      await showAgentsMenu(ctx);
+    }
+  }
+
+  async function showCustomAgentsList(ctx: ExtensionCommandContext) {
+    const customNames = getCustomAgentNames();
+    if (customNames.length === 0) {
+      ctx.ui.notify("No custom agents.", "info");
+      return;
+    }
+
+    // Compute max width of "name · model" for alignment
+    const entries = customNames.map(name => {
+      const cfg = getCustomAgentConfig(name);
+      const model = getModelLabel(name);
+      const prefix = `${name} · ${model}`;
+      return { prefix, desc: cfg?.description ?? name };
+    });
+    const maxPrefix = Math.max(...entries.map(e => e.prefix.length));
+
+    const options = entries.map(({ prefix, desc }) =>
+      `${prefix.padEnd(maxPrefix)} — ${desc}`,
+    );
+
+    const choice = await ctx.ui.select("Custom agents", options);
+    if (!choice) return;
+
+    const agentName = choice.split(" · ")[0];
+    if (getCustomAgentConfig(agentName)) {
+      await showAgentDetail(ctx, agentName);
+    }
+  }
+
+  async function showRunningAgents(ctx: ExtensionCommandContext) {
+    const agents = manager.listAgents();
+    if (agents.length === 0) {
+      ctx.ui.notify("No agents.", "info");
+      return;
+    }
+
+    // Show as a selectable list for potential future actions
+    const options = agents.map(a => {
+      const dn = getDisplayName(a.type);
+      const dur = formatDuration(a.startedAt, a.completedAt);
+      return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
+    });
+
+    await ctx.ui.select("Running agents", options);
+  }
+
+  async function showAgentDetail(ctx: ExtensionCommandContext, name: string) {
+    const file = findAgentFile(name);
+    if (!file) {
+      ctx.ui.notify(`Agent file not found for "${name}".`, "warning");
+      return;
+    }
+
+    const choice = await ctx.ui.select(name, ["Edit", "Delete", "Back"]);
+    if (!choice || choice === "Back") return;
+
+    if (choice === "Edit") {
+      const content = readFileSync(file.path, "utf-8");
+      const edited = await ctx.ui.editor(`Edit ${name}`, content);
+      if (edited !== undefined && edited !== content) {
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(file.path, edited, "utf-8");
+        reloadCustomAgents();
+        ctx.ui.notify(`Updated ${file.path}`, "info");
       }
+    } else if (choice === "Delete") {
+      const confirmed = await ctx.ui.confirm("Delete agent", `Delete ${name} from ${file.location} (${file.path})?`);
+      if (confirmed) {
+        unlinkSync(file.path);
+        reloadCustomAgents();
+        ctx.ui.notify(`Deleted ${file.path}`, "info");
+      }
+    }
+  }
 
-      const lines: string[] = [];
-      const counts: Record<string, number> = {};
-      for (const a of agents) counts[a.status] = (counts[a.status] ?? 0) + 1;
+  async function showCreateWizard(ctx: ExtensionCommandContext) {
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      "Personal (~/.pi/agent/agents/)",
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project") ? projectAgentsDir() : personalAgentsDir();
+
+    const method = await ctx.ui.select("Creation method", [
+      "Generate with Claude (recommended)",
+      "Manual configuration",
+    ]);
+    if (!method) return;
+
+    if (method.startsWith("Generate")) {
+      await showGenerateWizard(ctx, targetDir);
+    } else {
+      await showManualWizard(ctx, targetDir);
+    }
+  }
 
-      lines.push(
-        `${agents.length} agent(s): ${counts.running ?? 0} running, ${(counts.completed ?? 0) + (counts.steered ?? 0)} completed, ${counts.stopped ?? 0} stopped, ${counts.aborted ?? 0} aborted, ${counts.error ?? 0} errored`,
-      );
-      lines.push("");
+  async function showGenerateWizard(ctx: ExtensionCommandContext, targetDir: string) {
+    const description = await ctx.ui.input("Describe what this agent should do");
+    if (!description) return;
 
-      for (let i = 0; i < agents.length; i++) {
-        const a = agents[i];
-        const connector = i === agents.length - 1 ? "└─" : "├─";
-        const displayName = getDisplayName(a.type);
-        const duration = formatDuration(a.startedAt, a.completedAt);
+    const name = await ctx.ui.input("Agent name (filename, no spaces)");
+    if (!name) return;
 
-        lines.push(
-          `${connector} ${displayName} (${a.description}) · ${a.toolUses} tool uses · ${a.status} · ${duration}`,
-        );
+    // Validate name
+    if (isValidType(name) && !getCustomAgentConfig(name)) {
+      ctx.ui.notify(`"${name}" conflicts with a built-in agent type.`, "warning");
+      return;
+    }
+
+    if (!mkdirSync(targetDir, { recursive: true }) && !existsSync(targetDir)) {
+      mkdirSync(targetDir, { recursive: true });
+    }
+
+    const targetPath = join(targetDir, `${name}.md`);
+    if (existsSync(targetPath)) {
+      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      if (!overwrite) return;
+    }
+
+    ctx.ui.notify("Generating agent definition...", "info");
+
+    const generatePrompt = `Create a custom pi sub-agent definition file based on this description: "${description}"
+
+Write a markdown file to: ${targetPath}
+
+The file format is a markdown file with YAML frontmatter and a system prompt body:
+
+\`\`\`markdown
+---
+description: <one-line description shown in UI>
+tools: <comma-separated built-in tools: read, bash, edit, write, grep, find, ls. Use "none" for no tools. Omit for all tools>
+model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-20251001". Omit to inherit parent model>
+thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
+max_turns: <optional max agentic turns, default 50. Omit for default>
+prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
+extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
+skills: <true (inherit all), false (none). Default: true>
+inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
+run_in_background: <true to run in background by default. Default: false>
+isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+---
+
+<system prompt body — instructions for the agent>
+\`\`\`
+
+Guidelines for choosing settings:
+- For read-only tasks (review, analysis): tools: read, bash, grep, find, ls
+- For code modification tasks: include edit, write
+- Use prompt_mode: append if the agent should keep the default system prompt and add specialization on top
+- Use prompt_mode: replace for fully custom agents with their own personality/instructions
+- Set inherit_context: true if the agent needs to know what was discussed in the parent conversation
+- Set isolated: true if the agent should NOT have access to MCP servers or other extensions
+- Only include frontmatter fields that differ from defaults — omit fields where the default is fine
+
+Write the file using the write tool. Only write the file, nothing else.`;
+
+    const record = await manager.spawnAndWait(pi, ctx, "general-purpose", generatePrompt, {
+      description: `Generate ${name} agent`,
+      maxTurns: 5,
+    });
+
+    if (record.status === "error") {
+      ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+      return;
+    }
+
+    reloadCustomAgents();
+
+    if (existsSync(targetPath)) {
+      ctx.ui.notify(`Created ${targetPath}`, "info");
+    } else {
+      ctx.ui.notify("Agent generation completed but file was not created. Check the agent output.", "warning");
+    }
+  }
+
+  async function showManualWizard(ctx: ExtensionCommandContext, targetDir: string) {
+    // 1. Name
+    const name = await ctx.ui.input("Agent name (filename, no spaces)");
+    if (!name) return;
+
+    if (isValidType(name) && !getCustomAgentConfig(name)) {
+      ctx.ui.notify(`"${name}" conflicts with a built-in agent type.`, "warning");
+      return;
+    }
+
+    // 2. Description
+    const description = await ctx.ui.input("Description (one line)");
+    if (!description) return;
+
+    // 3. Tools
+    const toolChoice = await ctx.ui.select("Tools", ["all", "none", "read-only (read, bash, grep, find, ls)", "custom..."]);
+    if (!toolChoice) return;
+
+    let tools: string;
+    if (toolChoice === "all") {
+      tools = BUILTIN_TOOL_NAMES.join(", ");
+    } else if (toolChoice === "none") {
+      tools = "none";
+    } else if (toolChoice.startsWith("read-only")) {
+      tools = "read, bash, grep, find, ls";
+    } else {
+      const customTools = await ctx.ui.input("Tools (comma-separated)", BUILTIN_TOOL_NAMES.join(", "));
+      if (!customTools) return;
+      tools = customTools;
+    }
+
+    // 4. Model
+    const modelChoice = await ctx.ui.select("Model", [
+      "inherit (parent model)",
+      "haiku",
+      "sonnet",
+      "opus",
+      "custom...",
+    ]);
+    if (!modelChoice) return;
+
+    let modelLine = "";
+    if (modelChoice === "haiku") modelLine = "\nmodel: anthropic/claude-haiku-4-5-20251001";
+    else if (modelChoice === "sonnet") modelLine = "\nmodel: anthropic/claude-sonnet-4-6";
+    else if (modelChoice === "opus") modelLine = "\nmodel: anthropic/claude-opus-4-6";
+    else if (modelChoice === "custom...") {
+      const customModel = await ctx.ui.input("Model (provider/modelId)");
+      if (customModel) modelLine = `\nmodel: ${customModel}`;
+    }
+
+    // 5. Thinking
+    const thinkingChoice = await ctx.ui.select("Thinking level", [
+      "inherit",
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+    ]);
+    if (!thinkingChoice) return;
+
+    let thinkingLine = "";
+    if (thinkingChoice !== "inherit") thinkingLine = `\nthinking: ${thinkingChoice}`;
+
+    // 6. System prompt
+    const systemPrompt = await ctx.ui.editor("System prompt", "");
+    if (systemPrompt === undefined) return;
+
+    // Build the file
+    const content = `---
+description: ${description}
+tools: ${tools}${modelLine}${thinkingLine}
+prompt_mode: replace
+---
+
+${systemPrompt}
+`;
+
+    mkdirSync(targetDir, { recursive: true });
+    const targetPath = join(targetDir, `${name}.md`);
+
+    if (existsSync(targetPath)) {
+      const overwrite = await ctx.ui.confirm("Overwrite", `${targetPath} already exists. Overwrite?`);
+      if (!overwrite) return;
+    }
 
-        if (a.status === "error" && a.error) {
-          const indent = i === agents.length - 1 ? "   " : "│  ";
-          lines.push(`${indent} ⎿  Error: ${a.error.slice(0, 100)}`);
+    const { writeFileSync } = await import("node:fs");
+    writeFileSync(targetPath, content, "utf-8");
+    reloadCustomAgents();
+    ctx.ui.notify(`Created ${targetPath}`, "info");
+  }
+
+  async function showSettings(ctx: ExtensionCommandContext) {
+    const choice = await ctx.ui.select("Settings", [
+      `Max concurrency (current: ${manager.getMaxConcurrent()})`,
+      `Default max turns (current: ${getDefaultMaxTurns()})`,
+      `Grace turns (current: ${getGraceTurns()})`,
+      `Join mode (current: ${getDefaultJoinMode()})`,
+    ]);
+    if (!choice) return;
+
+    if (choice.startsWith("Max concurrency")) {
+      const val = await ctx.ui.input("Max concurrent background agents", String(manager.getMaxConcurrent()));
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          manager.setMaxConcurrent(n);
+          ctx.ui.notify(`Max concurrency set to ${n}`, "info");
+        } else {
+          ctx.ui.notify("Must be a positive integer.", "warning");
+        }
+      }
+    } else if (choice.startsWith("Default max turns")) {
+      const val = await ctx.ui.input("Default max turns before wrap-up", String(getDefaultMaxTurns()));
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          setDefaultMaxTurns(n);
+          ctx.ui.notify(`Default max turns set to ${n}`, "info");
+        } else {
+          ctx.ui.notify("Must be a positive integer.", "warning");
         }
-        if (a.session) {
-          const indent = i === agents.length - 1 ? "   " : "│  ";
-          lines.push(`${indent} ⎿  ID: ${a.id} (resumable)`);
+      }
+    } else if (choice.startsWith("Grace turns")) {
+      const val = await ctx.ui.input("Grace turns after wrap-up steer", String(getGraceTurns()));
+      if (val) {
+        const n = parseInt(val, 10);
+        if (n >= 1) {
+          setGraceTurns(n);
+          ctx.ui.notify(`Grace turns set to ${n}`, "info");
+        } else {
+          ctx.ui.notify("Must be a positive integer.", "warning");
         }
       }
+    } else if (choice.startsWith("Join mode")) {
+      const val = await ctx.ui.select("Default join mode for background agents", [
+        "smart — auto-group 2+ agents in same turn (default)",
+        "async — always notify individually",
+        "group — always group background agents",
+      ]);
+      if (val) {
+        const mode = val.split(" ")[0] as JoinMode;
+        setDefaultJoinMode(mode);
+        ctx.ui.notify(`Default join mode set to ${mode}`, "info");
+      }
+    }
+  }
 
-      ctx.ui.notify(lines.join("\n"), "info");
-    },
+  pi.registerCommand("agents", {
+    description: "Manage agents",
+    handler: async (_args, ctx) => { await showAgentsMenu(ctx); },
   });
 }

package/src/types.ts

@@ -62,6 +62,8 @@ export interface CustomAgentConfig {
   isolated: boolean;
 }
 
+export type JoinMode = 'async' | 'group' | 'smart';
+
 export interface AgentRecord {
   id: string;
   type: SubagentType;
@@ -75,6 +77,10 @@ export interface AgentRecord {
   session?: AgentSession;
   abortController?: AbortController;
   promise?: Promise<string>;
+  groupId?: string;
+  joinMode?: JoinMode;
+  /** Set when result was already consumed via get_subagent_result — suppresses completion notification. */
+  resultConsumed?: boolean;
 }
 
 export interface EnvInfo {