@gotgenes/pi-subagents 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [3.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v2.0.0...pi-subagents-v3.0.0) (2026-05-17)
+
+
+### ⚠ BREAKING CHANGES
+
+* The JoinMode type and defaultJoinMode setting are removed from the public settings interface.
+* The join-mode setting (smart/async/group) is removed. Background agents always notify individually on completion.
+* The subagents:ready event is no longer emitted. Extensions should use the typed SubagentsAPI ([#48](https://github.com/gotgenes/pi-packages/issues/48)) instead of event-based RPC discovery.
+* The subagents:rpc:ping, subagents:rpc:spawn, and subagents:rpc:stop event channels are no longer registered. Use the typed SubagentsAPI via Symbol.for() instead.
+
+### Features
+
+* remove group-join and cross-extension-rpc source ([b7d7f21](https://github.com/gotgenes/pi-packages/commit/b7d7f21af265e2ff95f0534f5c0b51f71b8f1e7f))
+* remove group-join wiring from index.ts ([4e2dc7f](https://github.com/gotgenes/pi-packages/commit/4e2dc7f8a98e441308f229745dfc42d09784d786))
+* remove join-mode types and settings ([1d98793](https://github.com/gotgenes/pi-packages/commit/1d98793eb85aa3d9815274aa443c34bb4434b6f9))
+* remove RPC wiring from index.ts ([3a960af](https://github.com/gotgenes/pi-packages/commit/3a960af8f6bb83219497d6229d12c6859cf3eb71))
+
+
+### Documentation
+
+* plan removal of group-join, output-file, and ad-hoc RPC ([#49](https://github.com/gotgenes/pi-packages/issues/49)) ([853a97f](https://github.com/gotgenes/pi-packages/commit/853a97f1c47051868b2ffddd7d5509f765a80d07))
+* remove group-join and RPC from README and AGENTS ([9f65f7a](https://github.com/gotgenes/pi-packages/commit/9f65f7a21611af8dead00a5fb34d7d10f3d6ab43))
+
 ## [2.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v1.0.2...pi-subagents-v2.0.0) (2026-05-17)
 
 

package/README.md

@@ -17,7 +17,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 ## 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) and smart group join (consolidated notifications)
+- **Parallel background agents** — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
 - **Live widget UI** — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause)
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
@@ -31,9 +31,9 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
 - **Skill preloading** — inject named skills into agent system prompts, discovered from `.pi/skills/`, `.agents/skills/`, and global locations (Pi-standard `<name>/SKILL.md` directory layout supported)
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
-- **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
+- **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
-- **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Standardized reply envelopes with protocol versioning. Emits `subagents:ready` on load
+
 
 ## Install
 
@@ -103,7 +103,7 @@ Background agent completion notifications render as styled boxes:
   transcript: .pi/output/agent-abc123.jsonl
 ```
 
-Group completions render each agent as a separate block. The LLM receives structured `<task-notification>` XML for parsing, while the user sees the themed visual.
+The LLM receives structured `<task-notification>` XML for parsing, while the user sees the themed visual.
 
 ## Default Agent Types
 
@@ -232,7 +232,7 @@ The `/agents` command opens an interactive menu:
 Running agents (2) — 1 running, 1 done     ← only shown when agents exist
 Agent types (6)                             ← unified list: defaults + custom
 Create new agent                            ← manual wizard or AI-generated
-Settings                                    ← max concurrency, max turns, grace turns, join mode
+Settings                                    ← max concurrency, max turns, grace turns
 ```
 
 - **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled). Select an agent to manage it:
@@ -243,7 +243,7 @@ Settings                                    ← max concurrency, max turns, grac
 - **Eject** — writes the embedded default config as a `.md` file to project or personal location, so you can customize it
 - **Disable/Enable** — toggle agent availability. Disabled agents stay visible in the list (marked `✕`) and can be re-enabled
 - **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). Any name is allowed, including default agent names (overrides them)
-- **Settings** — configure max concurrency, default max turns, grace turns, and join mode at runtime
+- **Settings** — configure max concurrency, default max turns, and grace turns at runtime
 
 ## Graceful Max Turns
 
@@ -266,29 +266,14 @@ 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. It applies only to background agents.
-
-| 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:**
-- Configure join mode in `/agents` → Settings → Join mode
-
 ## Persistent Settings
 
-Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns, default join mode) persist across pi restarts. Two files, merged on load:
+Runtime tuning values set via `/agents` → Settings (max concurrency, default max turns, grace turns) persist across pi restarts. Two files, merged on load:
 
 - **Global:** `~/.pi/agent/subagents.json` — your machine-wide defaults. Edit by hand; the `/agents` menu never writes here.
 - **Project:** `<cwd>/.pi/subagents.json` — per-project overrides. Written by `/agents` → Settings.
 
-**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`, join mode `smart`).
+**Precedence:** project overrides global on any field present in both. Missing fields fall back to the hardcoded defaults (max concurrency `4`, default max turns unlimited, grace turns `5`).
 
 **Example — global defaults for a beefy machine:**
 
@@ -318,78 +303,11 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
 | `subagents:steered` | Steering message sent | `id`, `message` |
 | `subagents:compacted` | Agent's session successfully compacted | `id`, `type`, `description`, `reason` (`"manual"` / `"threshold"` / `"overflow"`), `tokensBefore`, `compactionCount` |
-| `subagents:ready` | Extension loaded and RPC handlers registered | — |
 | `subagents:settings_loaded` | Persisted settings applied at extension init | `settings` (merged global + project) |
 | `subagents:settings_changed` | `/agents` → Settings mutation was applied | `settings`, `persisted` (`boolean` — `false` on write failure) |
 
 `tokens.total` = `input + output + cacheWrite`. `cacheRead` is excluded — each turn's `cacheRead` is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it. Use `contextUsage.percent` (surfaced as `(NN%)` in the widget) for current context size.
 
-## Cross-Extension RPC
-
-Other pi extensions can spawn and stop subagents programmatically via the `pi.events` event bus, without importing this package directly.
-
-All RPC replies use a standardized envelope: `{ success: true, data?: T }` on success, `{ success: false, error: string }` on failure.
-
-### Discovery
-
-Listen for `subagents:ready` to know when RPC handlers are available:
-
-```typescript
-pi.events.on("subagents:ready", () => {
-  // RPC handlers are registered — safe to call ping/spawn/stop
-});
-```
-
-### Ping
-
-Check if the subagents extension is loaded and get the protocol version:
-
-```typescript
-const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, (reply) => {
-  unsub();
-  if (reply.success) console.log("Protocol version:", reply.data.version);
-});
-pi.events.emit("subagents:rpc:ping", { requestId });
-```
-
-### Spawn
-
-Spawn a subagent and receive its ID:
-
-```typescript
-const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
-  unsub();
-  if (!reply.success) {
-    console.error("Spawn failed:", reply.error);
-  } else {
-    console.log("Agent ID:", reply.data.id);
-  }
-});
-pi.events.emit("subagents:rpc:spawn", {
-  requestId,
-  type: "general-purpose",
-  prompt: "Do something useful",
-  options: { description: "My task", run_in_background: true },
-});
-```
-
-### Stop
-
-Stop a running agent by ID:
-
-```typescript
-const requestId = crypto.randomUUID();
-const unsub = pi.events.on(`subagents:rpc:stop:reply:${requestId}`, (reply) => {
-  unsub();
-  if (!reply.success) console.error("Stop failed:", reply.error);
-});
-pi.events.emit("subagents:rpc:stop", { requestId, agentId: "agent-id-here" });
-```
-
-Reply channels are scoped per `requestId`, so concurrent requests don't interfere.
-
 ## Persistent Agent Memory
 
 Agents can have persistent memory across sessions. Set `memory` in frontmatter to enable:
@@ -477,8 +395,6 @@ src/
   agent-types.ts      # Unified agent registry (defaults + user), tool name resolution
   agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
-  cross-extension-rpc.ts # RPC handlers for cross-extension spawn/ping via pi.events
-  group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
   memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
   skill-loader.ts     # Preload skills (Pi-standard + Agent Skills spec layouts)

package/docs/plans/0049-remove-group-join-output-file-rpc.md

@@ -0,0 +1,163 @@
+---
+issue: 49
+issue_title: "feat: remove group-join, output-file, and ad-hoc RPC"
+---
+
+# Remove group-join and ad-hoc RPC
+
+## Problem Statement
+
+Two optional subsystems remain in the core that are either consumer concerns or replaced by the typed `SubagentsAPI` (#48):
+
+1. **Group join** — grouped completion notifications add batching complexity for marginal UX benefit when individual notifications are sufficient.
+2. **Ad-hoc RPC** — untyped RPC over `pi.events` with per-request reply channels is replaced by the typed `SubagentsAPI` published via `Symbol.for()`.
+
+Removing these two subsystems reduces the core's surface area by ~220 source LOC, eliminates the join-mode settings system, and simplifies the completion callback path in `index.ts`.
+
+The **output file** subsystem (`src/output-file.ts`) is retained — it provides valuable post-hoc debugging transcripts for subagent sessions.
+A separate issue (#61) tracks porting it to Pi's official JSONL session format.
+
+## Goals
+
+- Delete `src/group-join.ts` (141 LOC) and `src/cross-extension-rpc.ts` (80 LOC).
+- Delete `test/cross-extension-rpc.test.ts`.
+- Remove all group-join wiring from `index.ts`: `GroupJoinManager` instantiation, batch tracking (`currentBatchAgents`, `finalizeBatch`, `batchFinalizeTimer`, `batchCounter`), join-mode configuration state, and settings menu entry.
+- Remove all RPC wiring from `index.ts`: `registerRpcHandlers` import, `currentCtx` capture for RPC, `unsubPing/Spawn/Stop` teardown, and the `subagents:ready` broadcast.
+- Remove `JoinMode` type and `joinMode`/`groupId` fields from `types.ts`.
+- Remove `NotificationDetails.others` field (no longer needed without grouping).
+- Remove `defaultJoinMode` from `SubagentsSettings` and `SettingsAppliers` in `settings.ts`.
+- Remove `resolveJoinMode` from `invocation-config.ts`.
+- Simplify the completion callback in `index.ts` to always send an individual notification.
+- Preserve existing lifecycle events (`subagents:started`, `subagents:completed`, `subagents:failed`) — they are already emitted.
+- This is a **breaking change** (`feat!:`) — the join-mode setting is removed and RPC channels are no longer registered.
+
+## Non-Goals
+
+- Removing the `Symbol.for("pi-subagents:manager")` global accessor — that belongs to #48 (implement SubagentsAPI), which replaces it with the typed `publishSubagentsAPI()`.
+- Removing `bypassQueue` from `SpawnOptions` — it remains useful for the typed API.
+- Providing migration shims for RPC consumers — none known.
+- Removing or modifying `src/output-file.ts` — retained for debugging value; porting to Pi's JSONL format is tracked in #61.
+
+## Background
+
+The architecture doc marks these modules as "removing."
+Issue #52 (remove scheduled subagents) is already implemented and merged.
+Issue #48 (implement SubagentsAPI) depends on RPC removal here since the typed API replaces the untyped RPC.
+
+The `index.ts` file is the primary wiring layer affected.
+The completion callback currently routes through `groupJoin.onAgentComplete()` and only falls through to `sendIndividualNudge()` on `'pass'`.
+After this change, the callback always calls `sendIndividualNudge()` directly, which simplifies the control flow from ~90 lines of group/batch logic down to a single function call.
+
+The `currentCtx` variable captured in `session_start` exists solely for the RPC spawn handler.
+After RPC removal, session lifecycle hooks simplify: `session_start` only needs `manager.clearCompleted()`.
+
+## Design Overview
+
+This is a pure deletion change with minor simplification of the remaining completion path.
+
+After removal, the background-agent completion flow becomes:
+
+1. `AgentManager` calls `onComplete(record)`.
+2. `onComplete` emits `subagents:completed` or `subagents:failed` on `pi.events`.
+3. `onComplete` persists the record via `pi.appendEntry`.
+4. If `record.resultConsumed`, clean up widget and return.
+5. Otherwise, call `sendIndividualNudge(record)` — which schedules the notification with a 200ms debounce window (retained for `get_subagent_result` cancellation).
+
+The `NotificationDetails` interface stays (individual notifications still use it) but loses the `others` field.
+The `outputFile` field on `NotificationDetails` stays since output-file is retained.
+
+### Settings changes
+
+`SubagentsSettings` loses `defaultJoinMode`.
+The settings menu loses the "Join mode" entry.
+`snapshotSettings()` and `persistToastFor()` patterns are unchanged — they just carry one fewer field.
+
+### Types changes
+
+```typescript
+// Remove from types.ts:
+export type JoinMode = 'async' | 'group' | 'smart';
+
+// Remove from AgentRecord:
+groupId?: string;
+joinMode?: JoinMode;
+
+// Remove from NotificationDetails:
+others?: NotificationDetails[];
+```
+
+`AgentRecord.outputFile`, `outputCleanup`, and `toolCallId` are retained — they support the output-file subsystem which remains in scope.
+
+## Module-Level Changes
+
+### Delete
+
+| File                               | Lines |
+| ---------------------------------- | ----- |
+| `src/group-join.ts`                | 141   |
+| `src/cross-extension-rpc.ts`       | 80    |
+| `test/cross-extension-rpc.test.ts` | ~220  |
+
+### Modify
+
+| File                                       | Change                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/index.ts`                             | Remove imports for group-join and RPC modules. Remove `GroupJoinManager` instantiation and the grouped-delivery callback (~30 lines). Remove batch tracking state and `finalizeBatch()` (~40 lines). Remove join-mode state (`defaultJoinMode`, `getDefaultJoinMode`, `setDefaultJoinMode`). Remove RPC registration, `currentCtx` capture, `unsubPing/Spawn/Stop` teardown. Remove `subagents:ready` emit. Remove "Join mode" settings menu entry and `snapshotSettings` join-mode field. Simplify `onComplete` callback to always call `sendIndividualNudge`. Remove the `currentBatchAgents` deferred-notification check. Remove join-mode resolution in background spawn path. |
+| `src/types.ts`                             | Remove `JoinMode` type. Remove `groupId` and `joinMode` from `AgentRecord`. Remove `others` from `NotificationDetails`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `src/settings.ts`                          | Remove `JoinMode` import. Remove `defaultJoinMode` from `SubagentsSettings`. Remove `setDefaultJoinMode` from `SettingsAppliers`. Remove `VALID_JOIN_MODES`. Remove sanitize clause and `applySettings` clause for `defaultJoinMode`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `src/invocation-config.ts`                 | Remove `JoinMode` import. Remove `resolveJoinMode` export.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `README.md`                                | Remove "Cross-extension RPC" section. Remove join-mode documentation. Remove `subagents:ready` from events table. Update settings persistence paragraph to drop join-mode.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `.pi/skills/package-pi-subagents/SKILL.md` | Remove `cross-extension-rpc.ts` and `group-join.ts` from architecture diagram and module tables. Update `index.ts` description.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — this is pure deletion.
+2. `test/cross-extension-rpc.test.ts` becomes entirely redundant and is deleted.
+3. `test/output-file.test.ts` is retained (output-file stays).
+4. There is no dedicated `group-join.test.ts` — the group-join logic was only tested indirectly through integration.
+5. Existing tests for `agent-manager`, `agent-runner`, `settings`, and `invocation-config` must be checked for references to `joinMode`, `groupId`, `defaultJoinMode`, or `resolveJoinMode` — any such references need updating.
+6. The notification renderer test (if any) may reference `others` on `NotificationDetails` — check and remove.
+
+## TDD Order
+
+Since this is a removal (not a feature), the order is deletion-first with validation passes.
+
+1. **Delete source files for both subsystems.**
+   Delete `src/group-join.ts`, `src/cross-extension-rpc.ts`.
+   Delete `test/cross-extension-rpc.test.ts`.
+   Commit: `feat!: remove group-join and cross-extension-rpc source`
+
+2. **Remove RPC wiring from `index.ts`.**
+   Remove `registerRpcHandlers` import and call. Remove `currentCtx` state and RPC-related `session_start`/`session_shutdown` logic (keep `manager.clearCompleted()` call). Remove `unsubPing/Spawn/Stop` teardown. Remove `subagents:ready` emit.
+   Commit: `feat!: remove RPC wiring from index.ts`
+
+3. **Remove group-join wiring from `index.ts`.**
+   Remove `GroupJoinManager` import and instantiation (including the grouped-delivery callback). Remove batch tracking (`currentBatchAgents`, `batchFinalizeTimer`, `batchCounter`, `finalizeBatch`). Remove `defaultJoinMode` state, `getDefaultJoinMode`, `setDefaultJoinMode`. Remove join-mode resolution in background spawn path. Remove "Join mode" settings menu entry. Remove `defaultJoinMode` from `snapshotSettings()`. Simplify the `onComplete` callback: remove `currentBatchAgents` check and `groupJoin.onAgentComplete()` routing — always call `sendIndividualNudge(record)`. Remove `setDefaultJoinMode` from `applyAndEmitLoaded` appliers.
+   Commit: `feat!: remove group-join wiring from index.ts`
+
+4. **Clean up types, settings, and invocation-config.**
+   Remove `JoinMode` type from `types.ts`. Remove `groupId` and `joinMode` from `AgentRecord`. Remove `others` from `NotificationDetails`. Remove `defaultJoinMode` from `SubagentsSettings` and `SettingsAppliers` in `settings.ts`. Remove `VALID_JOIN_MODES` and sanitize/apply clauses. Remove `resolveJoinMode` and `JoinMode` import from `invocation-config.ts`.
+   Commit: `feat!: remove join-mode types and settings`
+
+5. **Verify all tests pass and fix straggling references.**
+   Run `pnpm vitest run` and `pnpm run check`. Fix any test fixtures or assertions that reference removed fields (`joinMode`, `groupId`, `defaultJoinMode`, `resolveJoinMode`).
+   Commit (if fixes needed): `test: remove references to deleted subsystems from test fixtures`
+
+6. **Update documentation.**
+   Update `README.md`: remove "Cross-extension RPC" section, join-mode documentation, `subagents:ready` event row. Update settings persistence paragraph.
+   Update `.pi/skills/package-pi-subagents/SKILL.md`: remove `cross-extension-rpc.ts` and `group-join.ts` from architecture diagram and module tables, update `index.ts` description.
+   Commit: `docs: remove group-join and RPC from README and AGENTS`
+
+## Risks and Mitigations
+
+| Risk                                                      | Mitigation                                                                                                                                                             |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Missed references cause compile errors                    | `grep -rn 'group.join\|GroupJoin\|registerRpcHandlers\|resolveJoinMode\|JoinMode' src/` after each step. `pnpm run check` catches import errors.                       |
+| Test fixtures reference removed fields                    | Step 5 explicitly scans for and fixes these. TypeScript `noEmit` check catches type mismatches.                                                                        |
+| `Symbol.for("pi-subagents:manager")` accidentally removed | Explicitly out of scope — this belongs to #48. The global accessor stays until the typed API replaces it.                                                              |
+| Breaking change not communicated                          | `feat!:` commit prefix triggers a major version bump via release-please.                                                                                               |
+| Settings file with `defaultJoinMode` on disk              | `sanitize()` already drops unknown fields silently — once the field is removed from the interface, existing files just have an inert JSON key that is ignored on load. |
+
+## Open Questions
+
+None — the issue scope is fully specified and the architecture doc ratified these removals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "A pi extension that brings Claude Code-style autonomous sub-agents to pi. Friendly fork of @tintinweb/pi-subagents.",
   "author": {
     "name": "Chris Lasher"

package/src/index.ts

@@ -12,20 +12,18 @@
 
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { defineTool, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext, getAgentDir } from "@earendil-works/pi-coding-agent";
+import { defineTool, type ExtensionAPI, type ExtensionCommandContext, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
-import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
-import { GroupJoinManager } from "./group-join.js";
-import { resolveAgentInvocationConfig, resolveJoinMode } from "./invocation-config.js";
+import { resolveAgentInvocationConfig } from "./invocation-config.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./output-file.js";
 import { applyAndEmitLoaded, type SubagentsSettings, saveAndEmitChanged } from "./settings.js";
-import { type AgentConfig, type AgentInvocation, type AgentRecord, type JoinMode, type NotificationDetails, type SubagentType } from "./types.js";
+import { type AgentConfig, type AgentInvocation, type AgentRecord, type NotificationDetails, type SubagentType } from "./types.js";
 import {
   type AgentActivity,
   type AgentDetails,
@@ -246,8 +244,7 @@ export default function (pi: ExtensionAPI) {
         return line;
       }
 
-      const all = [d, ...(d.others ?? [])];
-      return new Text(all.map(renderOne).join("\n"), 0, 0);
+      return new Text(renderOne(d), 0, 0);
     }
   );
 
@@ -307,40 +304,6 @@ export default function (pi: ExtensionAPI) {
     widget.update();
   }
 
-  // ---- Group join manager ----
-  const groupJoin = new GroupJoinManager(
-    (records, partial) => {
-      for (const r of records) { agentActivity.delete(r.id); widget.markFinished(r.id); }
-
-      const groupKey = `group:${records.map(r => r.id).join(",")}`;
-      scheduleNudge(groupKey, () => {
-        // Re-check at send time
-        const unconsumed = records.filter(r => !r.resultConsumed);
-        if (unconsumed.length === 0) { widget.update(); return; }
-
-        const notifications = unconsumed.map(r => formatTaskNotification(r, 300)).join('\n\n');
-        const label = partial
-          ? `${unconsumed.length} agent(s) finished (partial — others still running)`
-          : `${unconsumed.length} agent(s) finished`;
-
-        const [first, ...rest] = unconsumed;
-        const details = buildNotificationDetails(first, 300, agentActivity.get(first.id));
-        if (rest.length > 0) {
-          details.others = rest.map(r => buildNotificationDetails(r, 300, agentActivity.get(r.id)));
-        }
-
-        pi.sendMessage<NotificationDetails>({
-          customType: "subagent-notification",
-          content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
-          display: true,
-          details,
-        }, { deliverAs: "followUp", triggerTurn: true });
-      });
-      widget.update();
-    },
-    30_000,
-  );
-
   /** 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;
@@ -366,7 +329,7 @@ export default function (pi: ExtensionAPI) {
     };
   }
 
-  // Background completion: route through group join or send individual nudge
+  // Background completion: emit lifecycle event and send individual nudge
   const manager = new AgentManager((record) => {
     // Emit lifecycle event based on terminal status
     const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
@@ -392,19 +355,7 @@ export default function (pi: ExtensionAPI) {
       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
+    sendIndividualNudge(record);
     widget.update();
   }, undefined, (record) => {
     // Emit started event when agent transitions to running (including from queue)
@@ -436,12 +387,7 @@ export default function (pi: ExtensionAPI) {
     getRecord: (id: string) => manager.getRecord(id),
   };
 
-  // --- Cross-extension RPC via pi.events ---
-  let currentCtx: ExtensionContext | undefined;
-
-  // Capture ctx from session_start for RPC spawn handler.
-  pi.on("session_start", async (_event, ctx) => {
-    currentCtx = ctx;
+  pi.on("session_start", async (_event, _ctx) => {
     manager.clearCompleted();
   });
 
@@ -449,23 +395,9 @@ export default function (pi: ExtensionAPI) {
     manager.clearCompleted();
   });
 
-  const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc, unsubStop: unsubStopRpc } = registerRpcHandlers({
-    events: pi.events,
-    pi,
-    getCtx: () => currentCtx,
-    manager,
-  });
-
-  // Broadcast readiness so extensions loaded after us can discover us
-  pi.events.emit("subagents:ready", {});
-
   // On shutdown, abort all agents immediately and clean up.
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
-    unsubSpawnRpc();
-    unsubStopRpc();
-    unsubPingRpc();
-    currentCtx = undefined;
     delete (globalThis as any)[MANAGER_KEY];
     manager.abortAll();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
@@ -476,55 +408,6 @@ export default function (pi: ExtensionAPI) {
   // 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);
@@ -574,7 +457,6 @@ export default function (pi: ExtensionAPI) {
       setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
       setDefaultMaxTurns,
       setGraceTurns,
-      setDefaultJoinMode,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
@@ -870,28 +752,15 @@ Guidelines:
           return textResult(err instanceof Error ? err.message : String(err));
         }
 
-        // Set output file + join mode synchronously after spawn, before the
+        // Set output file synchronously after spawn, before the
         // event loop yields — onSessionCreated is async so this is safe.
-        const joinMode = resolveJoinMode(defaultJoinMode, true);
         const record = manager.getRecord(id);
-        if (record && joinMode) {
-          record.joinMode = joinMode;
+        if (record) {
           record.toolCallId = toolCallId;
           record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
           writeInitialEntry(record.outputFile, id, params.prompt, ctx.cwd);
         }
 
-        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
-          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();
@@ -1678,7 +1547,6 @@ ${systemPrompt}
       // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
-      defaultJoinMode: getDefaultJoinMode(),
     };
   }
 
@@ -1687,7 +1555,6 @@ ${systemPrompt}
       `Max concurrency (current: ${manager.getMaxConcurrent()})`,
       `Default max turns (current: ${getDefaultMaxTurns() ?? "unlimited"})`,
       `Grace turns (current: ${getGraceTurns()})`,
-      `Join mode (current: ${getDefaultJoinMode()})`,
     ]);
     if (!choice) return;
 
@@ -1727,17 +1594,6 @@ ${systemPrompt}
           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);
-        notifyApplied(ctx, `Default join mode set to ${mode}`);
-      }
     }
   }
 

package/src/invocation-config.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig, IsolationMode, JoinMode, ThinkingLevel } from "./types.js";
+import type { AgentConfig, IsolationMode, ThinkingLevel } from "./types.js";
 
 interface AgentInvocationParams {
   model?: string;
@@ -34,7 +34,3 @@ export function resolveAgentInvocationConfig(
     isolation: agentConfig?.isolation ?? params.isolation,
   };
 }
-
-export function resolveJoinMode(defaultJoinMode: JoinMode, runInBackground: boolean): JoinMode | undefined {
-  return runInBackground ? defaultJoinMode : undefined;
-}

package/src/settings.ts

@@ -5,8 +5,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import type { JoinMode } from "./types.js";
-
 export interface SubagentsSettings {
   maxConcurrent?: number;
   /**
@@ -16,7 +14,6 @@ export interface SubagentsSettings {
    */
   defaultMaxTurns?: number;
   graceTurns?: number;
-  defaultJoinMode?: JoinMode;
 }
 
 /** Setter hooks used by applySettings to wire persisted values into in-memory state. */
@@ -24,14 +21,11 @@ export interface SettingsAppliers {
   setMaxConcurrent: (n: number) => void;
   setDefaultMaxTurns: (n: number) => void;
   setGraceTurns: (n: number) => void;
-  setDefaultJoinMode: (mode: JoinMode) => void;
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
 export type SettingsEmit = (event: string, payload: unknown) => void;
 
-const VALID_JOIN_MODES: ReadonlySet<string> = new Set<JoinMode>(["async", "group", "smart"]);
-
 // Sanity ceilings — prevent hand-edited configs from asking for values that
 // make no operational sense (e.g. 1e6 concurrent subagents). Permissive enough
 // that any realistic power-user setting passes through.
@@ -65,9 +59,6 @@ function sanitize(raw: unknown): SubagentsSettings {
   ) {
     out.graceTurns = r.graceTurns as number;
   }
-  if (typeof r.defaultJoinMode === "string" && VALID_JOIN_MODES.has(r.defaultJoinMode)) {
-    out.defaultJoinMode = r.defaultJoinMode as JoinMode;
-  }
   return out;
 }
 
@@ -121,7 +112,6 @@ export function applySettings(s: SubagentsSettings, appliers: SettingsAppliers):
   if (typeof s.maxConcurrent === "number") appliers.setMaxConcurrent(s.maxConcurrent);
   if (typeof s.defaultMaxTurns === "number") appliers.setDefaultMaxTurns(s.defaultMaxTurns);
   if (typeof s.graceTurns === "number") appliers.setGraceTurns(s.graceTurns);
-  if (s.defaultJoinMode) appliers.setDefaultJoinMode(s.defaultJoinMode);
 }
 
 /**

package/src/types.ts

@@ -55,8 +55,6 @@ export interface AgentConfig {
   source?: "default" | "project" | "global";
 }
 
-export type JoinMode = 'async' | 'group' | 'smart';
-
 export interface AgentRecord {
   id: string;
   type: SubagentType;
@@ -70,8 +68,6 @@ 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;
   /** Steering messages queued before the session was ready. */
@@ -122,8 +118,7 @@ export interface NotificationDetails {
   outputFile?: string;
   error?: string;
   resultPreview: string;
-  /** Additional agents in a group notification. */
-  others?: NotificationDetails[];
+
 }
 
 export interface EnvInfo {

package/src/cross-extension-rpc.ts

@@ -1,95 +0,0 @@
-/**
- * Cross-extension RPC handlers for the subagents extension.
- *
- * Exposes ping, spawn, and stop RPCs over the pi.events event bus,
- * using per-request scoped reply channels.
- *
- * Reply envelope follows pi-mono convention:
- *   success → { success: true, data?: T }
- *   error   → { success: false, error: string }
- */
-
-/** Minimal event bus interface needed by the RPC handlers. */
-export interface EventBus {
-  on(event: string, handler: (data: unknown) => void): () => void;
-  emit(event: string, data: unknown): void;
-}
-
-/** RPC reply envelope — matches pi-mono's RpcResponse shape. */
-export type RpcReply<T = void> =
-  | { success: true; data?: T }
-  | { success: false; error: string };
-
-/** RPC protocol version — bumped when the envelope or method contracts change. */
-export const PROTOCOL_VERSION = 2;
-
-/** Minimal AgentManager interface needed by the spawn/stop RPCs. */
-export interface SpawnCapable {
-  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
-  abort(id: string): boolean;
-}
-
-export interface RpcDeps {
-  events: EventBus;
-  pi: unknown;                    // passed through to manager.spawn
-  getCtx: () => unknown | undefined;  // returns current ExtensionContext
-  manager: SpawnCapable;
-}
-
-export interface RpcHandle {
-  unsubPing: () => void;
-  unsubSpawn: () => void;
-  unsubStop: () => void;
-}
-
-/**
- * Wire a single RPC handler: listen on `channel`, run `fn(params)`,
- * emit the reply envelope on `channel:reply:${requestId}`.
- */
-function handleRpc<P extends { requestId: string }>(
-  events: EventBus,
-  channel: string,
-  fn: (params: P) => unknown | Promise<unknown>,
-): () => void {
-  return events.on(channel, async (raw: unknown) => {
-    const params = raw as P;
-    try {
-      const data = await fn(params);
-      const reply: { success: true; data?: unknown } = { success: true };
-      if (data !== undefined) reply.data = data;
-      events.emit(`${channel}:reply:${params.requestId}`, reply);
-    } catch (err: any) {
-      events.emit(`${channel}:reply:${params.requestId}`, {
-        success: false, error: err?.message ?? String(err),
-      });
-    }
-  });
-}
-
-/**
- * Register ping, spawn, and stop RPC handlers on the event bus.
- * Returns unsub functions for cleanup.
- */
-export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
-  const { events, pi, getCtx, manager } = deps;
-
-  const unsubPing = handleRpc(events, "subagents:rpc:ping", () => {
-    return { version: PROTOCOL_VERSION };
-  });
-
-  const unsubSpawn = handleRpc<{ requestId: string; type: string; prompt: string; options?: any }>(
-    events, "subagents:rpc:spawn", ({ type, prompt, options }) => {
-      const ctx = getCtx();
-      if (!ctx) throw new Error("No active session");
-      return { id: manager.spawn(pi, ctx, type, prompt, options ?? {}) };
-    },
-  );
-
-  const unsubStop = handleRpc<{ requestId: string; agentId: string }>(
-    events, "subagents:rpc:stop", ({ agentId }) => {
-      if (!manager.abort(agentId)) throw new Error("Agent not found");
-    },
-  );
-
-  return { unsubPing, unsubSpawn, unsubStop };
-}

package/src/group-join.ts

@@ -1,141 +0,0 @@
-/**
- * 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();
-  }
-}