@gotgenes/pi-subagents 2.0.0 → 4.0.0

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/docs/retro/0048-implement-subagents-api.md

@@ -0,0 +1,44 @@
+---
+issue: 48
+issue_title: "feat: implement and publish SubagentsService at extension init"
+---
+
+# Retro: #48 — implement and publish SubagentsService at extension init
+
+## Final Retrospective (2026-05-17T15:30:00Z)
+
+### Session summary
+
+Planned and implemented a typed `SubagentsService` interface with `Symbol.for()` accessor functions, an adapter wrapping `AgentManager` with model resolution and record serialization, and wired it into the extension init.
+Released as `@gotgenes/pi-subagents@4.0.0` (breaking: old untyped global removed).
+The plan was revised mid-session to align naming with `pi-permission-system`'s established conventions after the user flagged the discrepancy.
+
+### Observations
+
+#### What went well
+
+- TDD execution was clean: 8 steps, zero rework, all 33 new tests green on first pass.
+- The adapter design was well-scoped — `index.ts` wiring was +16/−12 lines, and the narrow `AgentManagerLike` interface made test mocks trivial.
+- The allowlist serialization pattern (`toSubagentRecord`) prevents future leaks of non-serializable fields by default.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The initial plan adopted the issue body's naming verbatim (`SubagentsAPI`, `api.ts`, `pi:service:subagents`, `(globalThis as any)`) without checking `pi-permission-system` for the established convention (`SubagentsService`, `service.ts`, `@gotgenes/<pkg>:service`, `Record<symbol, unknown>`).
+  The user had to explicitly ask "Does this structure follow the pattern set forth by pi-permission-system?"
+  Impact: full plan rewrite (replaced entire file), issue title update, issue body update — ~15 minutes of rework across 3 user turns.
+  This was **user-caught**.
+
+- `missing-context` — Same pattern as the #49 retro: following the issue spec literally without checking the codebase.
+  The architecture doc also used the stale naming, reinforcing the wrong choice.
+  Root cause: the "Gather context" step in `/plan-issue` didn't include a cross-package convention check.
+
+#### What caused friction (user side)
+
+- The user had to perform mechanical oversight ("Does this follow the pi-permission-system pattern?") that the planner should have caught independently.
+  If the `/plan-issue` prompt included a step to grep sibling packages for established API patterns, this would have been a design decision surfaced during planning rather than a correction after the fact.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0048-implement-subagents-api.md` (this file).
+2. Updated `.pi/skills/package-pi-subagents/SKILL.md` — changed `SubagentsAPI` → `SubagentsService` in Implementation Priorities; added `service.ts` and `service-adapter.ts` to module dependency graph and descriptions.
+3. Updated `.pi/prompts/plan-issue.md` — added step 7 to Gather context: check sibling packages for established API patterns before adopting issue body naming.

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

@@ -0,0 +1,38 @@
+---
+issue: 49
+issue_title: "feat: remove group-join, output-file, and ad-hoc RPC"
+---
+
+# Retro: #49 — remove group-join, output-file, and ad-hoc RPC
+
+## Final Retrospective (2026-05-17T15:15:00Z)
+
+### Session summary
+
+Planned and implemented the removal of group-join and ad-hoc RPC from `pi-subagents`, releasing v3.0.0.
+The original scope included `output-file.ts` removal, but the user intervened to retain it for post-hoc debugging value.
+A new issue (#61) was filed to port the output-file format to Pi's official JSONL session schema.
+
+### Observations
+
+#### What went well
+
+- User intervention produced a materially better outcome — retaining debugging transcripts and identifying a format conformance gap that became #61.
+- TDD execution was clean: 6 steps, zero rework, all tests green on first pass after each step.
+- The `feat!:` → release-please → v3.0.0 pipeline worked smoothly end-to-end.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Included `output-file.ts` removal in the initial plan without questioning its debugging value, despite AGENTS.md's rule "Ask before removing functionality or changing defaults." The issue body explicitly listed it for removal so I followed the spec literally. Impact: required plan revision (amend commit), scope-narrowing comment on issue, and filing #61 — roughly 10 minutes of rework, but produced a better design.
+
+- `missing-context` — When asked whether output-file adheres to Pi's session format, searched the web (`web_search` for "Claude Code session JSONL format") instead of checking the local `~/development/pi/pi` monorepo. The user had to explicitly say "~/development/pi/pi has the code for Pi's JSONL format." Impact: one extra round-trip and less authoritative initial answer (Claude Code's format vs Pi's `SessionManager`). Self-identified after user redirect.
+
+- `instruction-violation` (self-identified) — Shell-escaped the `gh issue comment` body incorrectly; backtick-wrapped `src/output-file.ts` was interpreted by bash. Caught immediately via `gh issue view` and fixed with `--edit-last`. Impact: trivial — one extra command.
+
+#### What caused friction (user side)
+
+- The issue body listed output-file for removal without noting its debugging value. The user's "How confident are we in getting rid of the logging system?" intervention was the correction. If the issue had marked output-file removal as "tentative pending debugging value assessment," the plan would have surfaced it as a design decision from the start. Minor — the discussion was quick and productive.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0049-remove-group-join-output-file-rpc.md` (this file).

package/package.json

@@ -1,6 +1,9 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "2.0.0",
+  "version": "4.0.0",
+  "exports": {
+    ".": "./src/service.ts"
+  },
   "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,20 @@
 
 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 { publishSubagentsService, unpublishSubagentsService } from "./service.js";
+import { createSubagentsService } from "./service-adapter.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 +246,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 +306,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 +331,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 +357,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)
@@ -425,23 +378,19 @@ export default function (pi: ExtensionAPI) {
     });
   });
 
-  // Expose manager via Symbol.for() global registry for cross-package access.
-  // Standard Node.js pattern for cross-package singletons (used by OpenTelemetry, etc.).
-  const MANAGER_KEY = Symbol.for("pi-subagents:manager");
-  (globalThis as any)[MANAGER_KEY] = {
-    waitForAll: () => manager.waitForAll(),
-    hasRunning: () => manager.hasRunning(),
-    spawn: (piRef: any, ctx: any, type: string, prompt: string, options: any) =>
-      manager.spawn(piRef, ctx, type, prompt, options),
-    getRecord: (id: string) => manager.getRecord(id),
-  };
-
-  // --- Cross-extension RPC via pi.events ---
-  let currentCtx: ExtensionContext | undefined;
+  // Typed service published via Symbol.for() for cross-extension access.
+  // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+  let currentCtx: { pi: unknown; ctx: unknown } | undefined;
+  const service = createSubagentsService({
+    manager,
+    resolveModel,
+    getCtx: () => currentCtx,
+    getModelRegistry: () => (currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
+  });
+  publishSubagentsService(service);
 
-  // Capture ctx from session_start for RPC spawn handler.
   pi.on("session_start", async (_event, ctx) => {
-    currentCtx = ctx;
+    currentCtx = { pi, ctx };
     manager.clearCompleted();
   });
 
@@ -449,24 +398,11 @@ 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();
+    unpublishSubagentsService();
     currentCtx = undefined;
-    delete (globalThis as any)[MANAGER_KEY];
     manager.abortAll();
     for (const timer of pendingNudges.values()) clearTimeout(timer);
     pendingNudges.clear();
@@ -476,55 +412,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 +461,6 @@ export default function (pi: ExtensionAPI) {
       setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
       setDefaultMaxTurns,
       setGraceTurns,
-      setDefaultJoinMode,
     },
     (event, payload) => pi.events.emit(event, payload),
   );
@@ -870,28 +756,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 +1551,6 @@ ${systemPrompt}
       // normalizeMaxTurns() in agent-runner.ts (which maps 0 → undefined).
       defaultMaxTurns: getDefaultMaxTurns() ?? 0,
       graceTurns: getGraceTurns(),
-      defaultJoinMode: getDefaultJoinMode(),
     };
   }
 
@@ -1687,7 +1559,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 +1598,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;
-}