@gotgenes/pi-subagents 1.0.0 → 1.0.2

package/AGENTS.md

@@ -1,85 +1,7 @@
 # AGENTS.md
 
-## Project Purpose
+⚠️ It looks like the agent was started from a package subdirectory.
 
-This repository is a Pi extension that adds Claude Code-style autonomous subagent dispatch to the Pi coding agent.
-
-This package is a friendly fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
-It carries a small number of patches needed for downstream consumers (notably [RepOne](https://github.com/Tiny-IG-Software/repone)) that intend to use it as a normal Pi extension dependency:
-
-1. **Peer-dep rename** — peer dependencies point at `@earendil-works/pi-*` (the active scope) rather than the deprecated `@mariozechner/pi-*` scope.
-2. **Patch 2 (post-bind active-tool re-filter)** — `runAgent` re-runs the active-tool filter after `session.bindExtensions(...)` so extension-registered tools land in the child's active tool set. Without this, the `extensions: string[]` allowlist branch is functionally dead for extension tools.
-3. **Patch 3 (active_agent tag)** — `runAgent` prepends `<active_agent name="${agentConfig.name}"/>` to every assembled child system prompt so `@gotgenes/pi-permission-system` can resolve per-agent `permission:` frontmatter inside the child.
-
-See `docs/decisions/0001-deferred-patches.md` for a fourth patch (mirror parent resource paths) that was scoped out, and the rationale for not opening upstream PRs yet.
-
-## Workflow
-
-- Keep scope tight — this fork stays as close to upstream as possible.
-- Prefer small, reversible changes.
-- Preserve upstream behavior unless there is a clear reason to diverge.
-- When in doubt about whether a change should land here or be proposed upstream, prefer upstream.
-
-## Implementation Priorities
-
-- Maintain compatibility with upstream's public API.
-- Keep the patch set minimal and clearly identified in the code (search for `Patch 2 (RepOne` / `Patch 3 (RepOne` comments).
-- Mirror sibling Pi-package conventions for tooling (pnpm, biome, vitest, prek, markdownlint-cli2, release-please).
-- Track the upstream `tintinweb/pi-subagents` repository for fixes and incorporate them as merges or cherry-picks.
-
-## Code Style
-
-Use TypeScript. This project uses **pnpm** exclusively — never `npm` or `npx`.
-
-Formatting is handled by Biome (`biome check`, `biome format`). The repo intentionally does not use Prettier — a top-level `.prettierignore` blocks any harness with project-level write-time Prettier formatting from reformatting files here.
-
-## Build, Test, Lint Commands
-
-```bash
-pnpm install                    # Install dependencies + run prek install
-pnpm run build                  # tsc
-pnpm run typecheck              # tsc --noEmit
-pnpm run lint                   # biome check src/ test/
-pnpm run lint:fix               # biome check --fix src/ test/
-pnpm run lint:md                # markdownlint-cli2 '*.md' 'docs/**/*.md'
-pnpm run lint:md:fix            # markdownlint-cli2 --fix '*.md' 'docs/**/*.md'
-pnpm run lint:all               # lint + lint:md
-pnpm run format                 # biome format --write src/ test/
-pnpm test                       # vitest run
-pnpm run test:watch             # vitest
-pnpm run check                  # build + lint:all + test (full local CI)
-```
-
-## Markdown
-
-This project uses `markdownlint-cli2` with the config in `.markdownlint-cli2.yaml`.
-The `CHANGELOG.md` file is machine-generated by release-please and is excluded from linting.
-
-## Testing
-
-The fork preserves upstream's full `vitest` suite (362 tests) plus tests added for Patches 2 and 3.
-All tests must pass before publishing.
-Use `vi.hoisted(...)` for module-level mocks, matching the existing patterns in `test/agent-runner.test.ts`.
-
-## Releases
-
-This repo uses [release-please](https://github.com/googleapis/release-please) and npm trusted publishing via OIDC.
-
-- Conventional Commits drive the version bump (`feat:` → minor, `fix:` → patch, `BREAKING CHANGE:` → major).
-- Pushing to `main` triggers `release-please-action` which opens a release PR.
-- Merging the release PR creates a tag and triggers the publish job (no `NPM_TOKEN` — trusted publishing via OIDC).
-
-## Commits
-
-Use Conventional Commits.
-Commit at meaningful checkpoints without waiting for an explicit reminder.
-Prefer small, reviewable commits that leave the repository in a valid state.
-
-## Notes for Agents
-
-When working in this repo:
-
-1. The two RepOne-specific patches are clearly marked in source — search for `// Patch 2 (RepOne` or `// Patch 3 (RepOne` to find them.
-2. Do not introduce a third or fourth patch without first documenting the rationale in `docs/decisions/`.
-3. Upstream PRs to `tintinweb/pi-subagents` for Patches 2 and 3 are deferred pending production validation in RepOne — see `docs/decisions/0001-deferred-patches.md`.
-4. When syncing with upstream (rare), reapply the peer-dep rename and the two patches; the upstream `vitest` suite is the canary that nothing regressed.
+Advise the user to launch Pi from the **repository root** (`pi-packages/`) instead.
+The root provides `.pi/settings.json`, `.pi/prompts/`, and the full skill set.
+Package-specific context for this package is available via the `package-pi-subagents` skill.

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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).
 
+## [1.0.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v1.0.1...pi-subagents-v1.0.2) (2026-05-17)
+
+
+### Documentation
+
+* plan update ADR 0001 to reflect hard-fork decision ([#51](https://github.com/gotgenes/pi-packages/issues/51)) ([bd4899a](https://github.com/gotgenes/pi-packages/commit/bd4899a0d7e72c43b80c3c07c07ccc32dc0df8ed))
+* update ADR 0001 to reflect hard-fork decision ([#51](https://github.com/gotgenes/pi-packages/issues/51)) ([387e0ad](https://github.com/gotgenes/pi-packages/commit/387e0ad06ec1cf015c1d3d1d9852a1be015fc283))
+
+## [1.0.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v1.0.0...pi-subagents-v1.0.1) (2026-05-17)
+
+
+### Bug Fixes
+
+* restore per-package lint:md and lint scripts ([0e42617](https://github.com/gotgenes/pi-packages/commit/0e42617c443a7f8695f33855fa17058fc1712f27))
+* use root markdownlint config from all packages ([30192f8](https://github.com/gotgenes/pi-packages/commit/30192f8ccfc5c3c420f9f9b602df174baf263e92))
+
+
+### Documentation
+
+* add redirect AGENTS.md to each package subdirectory ([cbdcd29](https://github.com/gotgenes/pi-packages/commit/cbdcd297194c814f545ae93eaa7418e9337450d3))
+
+
+### Miscellaneous Chores
+
+* consolidate configs into monorepo root ([8583eaf](https://github.com/gotgenes/pi-packages/commit/8583eaf0764ac98def1987f20fafcc25e912b134))
+* remove per-package pi-autoformat configs ([b2d405a](https://github.com/gotgenes/pi-packages/commit/b2d405a0a278341e4f6ff1c8b607533eaa4f021a))
+* replace markdownlint-cli2 with rumdl ([d8dc789](https://github.com/gotgenes/pi-packages/commit/d8dc7897d854bf11396b85bc8c365e8e2ed7e66c))
+* update package.json URLs to monorepo ([b92dbfa](https://github.com/gotgenes/pi-packages/commit/b92dbfaeaeb6cf2823272cb6fb6f206fb99a5009))
+
 ## [1.0.0](https://github.com/gotgenes/pi-subagents/compare/v0.7.2...v1.0.0) (2026-05-12)
 
 

package/README.md

@@ -1,10 +1,14 @@
-# @tintinweb/pi-subagents
+# @gotgenes/pi-subagents
 
 A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-agents** to pi. Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level. Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.
 
+> **Fork notice:** This package is a friendly fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents), published to npm as `@gotgenes/pi-subagents`.
+> It carries a small number of patches on top of upstream — peer-dep migration to `@earendil-works/pi-*`, a post-`bindExtensions` active-tool re-filter, and an `<active_agent>` system-prompt tag for permission resolution.
+> See [Deviations from upstream](#deviations-from-upstream) at the bottom of this README for details.
+
 > **Status:** Early release.
 
-<img width="600" alt="pi-subagents screenshot" src="https://github.com/tintinweb/pi-subagents/raw/master/media/screenshot.png" />
+<img width="600" alt="pi-subagents screenshot" src="https://github.com/gotgenes/pi-subagents/raw/main/media/screenshot.png" />
 
 
 https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
@@ -35,7 +39,7 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 ## Install
 
 ```bash
-pi install npm:@tintinweb/pi-subagents
+pi install npm:@gotgenes/pi-subagents
 ```
 
 Or load directly for development:
@@ -523,6 +527,16 @@ src/
     conversation-viewer.ts # Live conversation overlay for viewing agent sessions
 ```
 
+## Deviations from upstream
+
+This fork carries three divergences from [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents). Each has a corresponding upstream PR:
+
+1. **Peer-dep migration to `@earendil-works/pi-*`** — `peerDependencies` and all imports point at `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui` (the active scope on npm) instead of the deprecated `@mariozechner/pi-*` scope. Also fixes a latent bug where `ThinkingLevel` was imported from `pi-agent-core` (an undeclared transitive dep that breaks under pnpm). Upstream PR: [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71).
+2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so extension-registered tools join the child's active tool set. Without this, the `extensions: string[]` allowlist branch was functionally dead for extension tools, and `extensions: true` with a `disallowedTools` denylist let denylisted extension tools slip through. Upstream PR: [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
+3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes). Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session. Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
+
+The upstream `vitest` suite plus tests added for each patch all pass on every commit.
+
 ## License
 
-MIT — [tintinweb](https://github.com/tintinweb)
+MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)

package/docs/architecture/architecture.md

@@ -0,0 +1,391 @@
+# Architecture
+
+This document describes the planned decomposition of the pi-subagents fork
+into a focused, composable core with a stable API boundary that other
+extensions can build on.
+
+## Design principles
+
+1. **Narrow core** — the extension owns agent spawning, execution, and result
+   retrieval. Everything else is a consumer.
+2. **Composable by default** — other extensions can spawn agents, observe
+   their lifecycle, and display their state without importing this package
+   directly.
+3. **Typed API boundary** — this package exports a `SubagentsAPI` interface
+   and `Symbol.for()` accessors (`publishSubagentsAPI` /
+   `getSubagentsAPI`). Consumers declare this package as an optional peer
+   dependency and use dynamic import for compile-time types. The runtime
+   bridge is `Symbol.for()` on `globalThis` — no separate API package.
+4. **No scheduling** — in-process scheduling is removed from the core.
+   Scheduling is a separate concern that any extension can implement by
+   calling `spawn()` on the published API.
+5. **UI extraction is deferred** — the widget, conversation viewer, and
+   `/agents` command menu stay in the core for now. They are the first
+   candidate for extraction once the API boundary is proven stable.
+
+## Current state
+
+The extension is a 6,300 LOC monolith organized into well-factored internal
+modules but with no public API contract. The subsystems are:
+
+```text
+index.ts (1,894 LOC) — entry point, tool registration, event wiring
+agent-manager.ts      — lifecycle, concurrency, queue
+agent-runner.ts       — session creation, turn loop, tool filtering
+agent-types.ts        — type registry (defaults + custom .md files)
+types.ts              — shared type definitions
+
+prompts.ts            — system prompt assembly
+context.ts            — parent conversation extraction
+memory.ts             — persistent MEMORY.md per agent
+skill-loader.ts       — preload .pi/skills into prompts
+env.ts                — git/platform detection
+
+worktree.ts           — git worktree isolation
+usage.ts              — token usage tracking
+model-resolver.ts     — fuzzy model name resolution
+invocation-config.ts  — merge tool params with agent config
+output-file.ts        — JSONL transcript streaming
+settings.ts           — persistent operational settings
+
+schedule.ts           — cron/interval/one-shot job dispatch  ← removing
+schedule-store.ts     — file-backed schedule persistence     ← removing
+cross-extension-rpc.ts — RPC over pi.events                  ← replacing
+group-join.ts         — batch completion notifications
+
+ui/agent-widget.ts       — above-editor live status widget
+ui/conversation-viewer.ts — scrollable session overlay
+ui/schedule-menu.ts      — /agents schedule submenu          ← removing
+```
+
+### Coupling today
+
+The widget reads agent state by holding a direct reference to
+`AgentManager` and polling a shared mutable `Map<string, AgentActivity>`
+every 80 ms. The conversation viewer subscribes directly to `AgentSession`
+objects. The scheduler holds a direct `AgentManager` reference and calls
+`manager.spawn()`.
+
+Cross-extension consumers use an ad-hoc RPC layer over `pi.events`
+(`subagents:rpc:spawn`, `subagents:rpc:stop`, `subagents:rpc:ping`) with
+per-request reply channels and untyped envelopes.
+
+There is also a `Symbol.for("pi-subagents:manager")` export on
+`globalThis` that exposes `{ waitForAll, hasRunning, spawn, getRecord }`,
+but it is undocumented and untyped.
+
+## Target state
+
+```text
+  ┌────────────────────────────────────────────────────────┐
+  │  @earendil-works/pi-subagents  (this package)          │
+  │                                                        │
+  │  Exports:                                              │
+  │    SubagentsAPI interface                              │
+  │    publishSubagentsAPI() / getSubagentsAPI()           │
+  │    SubagentRecord, SubagentStatus, LifetimeUsage types │
+  │    Event channel constants                             │
+  │                                                        │
+  │  Core:                                                 │
+  │    Agent + get_subagent_result + steer_subagent tools  │
+  │    AgentManager, agent-runner, agent-types             │
+  │    publishSubagentsAPI(impl)  ← called at init         │
+  │                                                        │
+  │  Internal UI (widget, viewer, /agents menu)            │
+  │  ← moves to pi-subagents-ui later                     │
+  └──────────────────────┬─────────────────────────────────┘
+                         │ Symbol.for("pi:service:subagents")
+                         │
+       ┌─────────────────┼──────────────────┐
+       │                 │                  │
+       ▼                 ▼                  ▼
+  ┌─────────┐    ┌──────────────┐    ┌──────────────┐
+  │ pi-     │    │ pi-subagents │    │ any future   │
+  │ schedule│    │ -ui          │    │ extension    │
+  │ (other  │    │ (deferred)   │    │              │
+  │  ext)   │    └──────────────┘    └──────────────┘
+  └─────────┘
+       │
+       │  getSubagentsAPI()?.spawn(...)
+       │  (optional peer dep + dynamic import for types)
+       ▼
+```
+
+### What the core owns
+
+- The three tools: `Agent`, `get_subagent_result`, `steer_subagent`.
+- `AgentManager` — spawn, queue, abort, resume, concurrency control.
+- `agent-runner` — session creation, turn loop, tool filtering, extension
+  binding (Patches 2 and 3).
+- Agent type registry — default agents, custom `.md` file loading.
+- Prompt assembly, context extraction, memory, skills, environment.
+- Worktree isolation.
+- Token usage tracking.
+- Settings persistence.
+- Internal UI (widget, conversation viewer, `/agents` menu) — these stay
+  until the API boundary is proven, then move to a separate extension.
+
+### What the core drops
+
+- **Scheduling** (`schedule.ts`, `schedule-store.ts`,
+  `ui/schedule-menu.ts`) — 612 LOC removed. The `schedule` parameter is
+  removed from the `Agent` tool schema. Any extension that wants scheduling
+  can implement it by calling `getSubagentsAPI()?.spawn(...)` on a timer.
+- **Ad-hoc RPC** (`cross-extension-rpc.ts`) — replaced by the typed
+  `SubagentsAPI` published via `Symbol.for()`. The untyped event-bus RPC
+  channels are removed.
+- **Group join** (`group-join.ts`) — 141 LOC removed. The grouped
+  notification batching adds complexity for a marginal UX improvement.
+  Individual completion notifications are sufficient.
+- **Output file** (`output-file.ts`) — 96 LOC removed. JSONL transcript
+  streaming is a consumer concern; a separate extension can subscribe to
+  lifecycle events and write transcripts.
+
+### Estimated impact
+
+| Subsystem removed | LOC removed | LOC removed from index.ts |
+| ----------------- | ----------- | ------------------------- |
+| Scheduling        | 612         | ~200                      |
+| Ad-hoc RPC        | 80          | ~50                       |
+| Group join        | 141         | ~100                      |
+| Output file       | 83          | ~50                       |
+| **Total**         | **~916**    | **~400**                  |
+
+After removal and `index.ts` decomposition, the core shrinks from ~6,300
+to ~5,400 LOC, and `index.ts` shrinks from ~1,894 to ~1,300 LOC.
+
+## SubagentsAPI
+
+The `SubagentsAPI` interface, accessor functions, and serializable types
+are exported directly from this package (`@earendil-works/pi-subagents`).
+No separate API package is needed.
+
+Consumers declare this package as an optional peer dependency:
+
+```json
+{
+  "peerDependencies": {
+    "@earendil-works/pi-subagents": ">=2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-subagents": { "optional": true }
+  }
+}
+```
+
+At runtime, consumers use dynamic import for type-safe access to the
+accessor functions:
+
+```typescript
+const { getSubagentsAPI } = await import("@earendil-works/pi-subagents");
+const api = getSubagentsAPI();
+if (api) {
+  api.spawn("Explore", "Check for stale TODOs");
+}
+```
+
+Pi's extension loader creates a fresh `jiti` instance per extension with
+`moduleCache: false`, so module-scoped singletons don't survive across
+extensions. The accessor functions use `Symbol.for()` on `globalThis`,
+which is process-global by spec, to bridge this gap. The dynamic import
+provides compile-time types; the `Symbol.for()` key is the actual
+runtime channel.
+
+### Interface
+
+```typescript
+/** The public API surface published by pi-subagents. */
+export interface SubagentsAPI {
+  /**
+   * Spawn an agent. Returns the agent ID immediately.
+   * The agent runs in the background unless options.foreground is true.
+   */
+  spawn(type: string, prompt: string, options?: SpawnOptions): string;
+
+  /** Get a snapshot of an agent's current state. */
+  getRecord(id: string): SubagentRecord | undefined;
+
+  /** List all tracked agents, most recent first. */
+  listAgents(): SubagentRecord[];
+
+  /** Abort a running or queued agent. Returns false if not found. */
+  abort(id: string): boolean;
+
+  /** Send a steering message to a running agent. */
+  steer(id: string, message: string): Promise<boolean>;
+
+  /** Wait for all running and queued agents to complete. */
+  waitForAll(): Promise<void>;
+
+  /** Whether any agents are running or queued. */
+  hasRunning(): boolean;
+}
+
+export interface SpawnOptions {
+  description?: string;
+  model?: string;
+  maxTurns?: number;
+  thinkingLevel?: string;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  foreground?: boolean;
+  /** Skip the concurrency queue — start immediately. */
+  bypassQueue?: boolean;
+  isolation?: "worktree";
+}
+```
+
+### Accessor pattern
+
+```typescript
+const KEY = Symbol.for("pi:service:subagents");
+
+export function publishSubagentsAPI(api: SubagentsAPI): void {
+  (globalThis as any)[KEY] = api;
+}
+
+export function getSubagentsAPI(): SubagentsAPI | undefined {
+  return (globalThis as any)[KEY];
+}
+```
+
+If Pi gains a native service registry ([earendil-works/pi#4207]), these
+accessors can be updated to delegate to `pi.registerService()` /
+`pi.getService()` internally while keeping the same consumer API.
+
+### Lifecycle events
+
+The core emits events on `pi.events` that any extension can observe:
+
+| Channel               | Payload                                     | When                 |
+| --------------------- | ------------------------------------------- | -------------------- |
+| `subagents:started`   | `{ id, type, description }`                 | Agent begins running |
+| `subagents:completed` | `{ id, type, status, result?, error? }`     | Agent finishes       |
+| `subagents:activity`  | `{ id, toolName?, textDelta?, turnCount? }` | Streaming progress   |
+
+These replace the ad-hoc RPC channels. They are fire-and-forget broadcast
+events — no request IDs, no reply channels.
+
+### Consumer example: scheduling extension
+
+```typescript
+// package.json:
+// "peerDependencies": { "@earendil-works/pi-subagents": ">=2.0.0" }
+// "peerDependenciesMeta": { "@earendil-works/pi-subagents": { "optional": true } }
+
+export default function (pi) {
+  pi.on("session_start", async (event, ctx) => {
+    let getSubagentsAPI;
+    try {
+      ({ getSubagentsAPI } = await import("@earendil-works/pi-subagents"));
+    } catch {
+      return; // pi-subagents not installed
+    }
+    const api = getSubagentsAPI();
+    if (!api) return;
+
+    setInterval(() => {
+      api.spawn("Explore", "Check for stale TODOs", {
+        bypassQueue: true,
+      });
+    }, 60 * 60 * 1000);
+  });
+}
+```
+
+### Consumer example: transcript extension
+
+```typescript
+export default function (pi) {
+  pi.events.on("subagents:completed", async (data) => {
+    const { id } = data as { id: string };
+    let getSubagentsAPI;
+    try {
+      ({ getSubagentsAPI } = await import("@earendil-works/pi-subagents"));
+    } catch {
+      return;
+    }
+    const record = getSubagentsAPI()?.getRecord(id);
+    if (record?.result) {
+      fs.appendFileSync("agent-log.jsonl", JSON.stringify(record) + "\n");
+    }
+  });
+}
+```
+
+## index.ts decomposition
+
+The 1,894-line `index.ts` is decomposed into focused modules:
+
+```text
+src/
+├── index.ts                  ← slimmed entry point: init, tool registration
+├── tools/
+│   ├── agent-tool.ts         ← Agent tool definition + execute
+│   ├── result-tool.ts        ← get_subagent_result tool
+│   └── steer-tool.ts         ← steer_subagent tool
+├── notifications.ts          ← completion nudges, custom renderer
+├── activity-tracker.ts       ← AgentActivity map + callback factory
+├── agents-command.ts         ← /agents slash command menu
+├── api-adapter.ts            ← SubagentsAPI implementation wrapping AgentManager
+└── (existing modules unchanged)
+```
+
+Each extracted module receives narrow constructor-injected dependencies
+rather than closing over module-level state.
+
+## Phase plan
+
+### Phase 1: Export `SubagentsAPI` from this package
+
+Add the `SubagentsAPI` interface, serializable types, and `Symbol.for()`
+accessor functions as public exports of this package. No behavioral
+changes to the core yet.
+
+### Phase 2: Remove scheduling
+
+Delete `schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`. Remove
+the `schedule` parameter from the `Agent` tool schema. Remove scheduler
+setup and lifecycle hooks from `index.ts`.
+
+### Phase 3: Remove group-join, output-file, ad-hoc RPC
+
+Delete `group-join.ts`, `output-file.ts`, `cross-extension-rpc.ts`.
+Simplify `index.ts` to use direct individual notifications. Emit
+lifecycle events on `pi.events` for external consumers.
+
+### Phase 4: Implement and publish `SubagentsAPI`
+
+Wire `api-adapter.ts` to wrap `AgentManager` and call
+`publishSubagentsAPI()` at extension init. Resolve model strings inside
+the adapter (fixing upstream [tintinweb/pi-subagents#60]).
+
+### Phase 5: Decompose `index.ts`
+
+Extract tools, notifications, activity tracking, and the `/agents` command
+into separate modules per the decomposition above.
+
+### Phase 6 (future): Extract UI to `@earendil-works/pi-subagents-ui`
+
+Move `ui/agent-widget.ts`, `ui/conversation-viewer.ts`, the `/agents`
+command, notifications, and activity tracking to a separate extension that
+consumes `SubagentsAPI` + lifecycle events. This phase is deferred until
+the API boundary is proven stable in production.
+
+## Relationship with upstream
+
+This fork ([earendil-works/pi-subagents]) is now a **hard fork** of
+[tintinweb/pi-subagents]. The decomposition diverges materially from
+upstream's direction.
+
+The three upstream PRs (#71, #72, #73) remain open. If they land, upstream
+gains the peer-dep fix and the two RepOne patches. This fork continues
+independently regardless.
+
+Upstream fixes and ideas are cherry-picked when they align with this
+fork's scope. The upstream test suite is run periodically as a regression
+canary for the agent-runner core.
+
+[earendil-works/pi#4207]: https://github.com/earendil-works/pi/issues/4207
+[earendil-works/pi-subagents]: https://github.com/earendil-works/pi-subagents
+[tintinweb/pi-subagents]: https://github.com/tintinweb/pi-subagents

package/docs/decisions/0001-deferred-patches.md

@@ -1,5 +1,5 @@
 ---
-status: accepted
+status: superseded
 date: 2026-05-11
 ---
 
@@ -7,7 +7,8 @@ date: 2026-05-11
 
 ## Status
 
-Accepted
+Superseded by [`docs/architecture/architecture.md`](../architecture/architecture.md), which commits to a hard fork with material scope reduction (scheduling removal, `SubagentsAPI` boundary, `index.ts` decomposition).
+The original rationale below remains useful context.
 
 ## Context
 
@@ -43,17 +44,16 @@ Neither matches the production need. For RepOne (and any consumer that installs
 
 We therefore defer Patch 1 rather than carry a speculative patch in the fork's diff against upstream. A follow-up issue on the RepOne board (linked from #443) captures the criterion for revisiting: **a workflow that needs `pi -e <path>` ephemeral extensions to reach children**.
 
-### Upstream PRs are deferred
+### Upstream PRs are open
 
-Patches 2 and 3 are both clearly upstream-mergeable bug fixes — they finish a mirror the upstream fork already started (carrying the parent's session configuration through to the child). The natural place for them is in `tintinweb/pi-subagents` itself.
+All three divergences now have upstream PRs, opened after production validation in RepOne:
 
-We defer opening the PRs until **Patches 2 and 3 have been validated end-to-end in production** through at least one milestone of RepOne usage. The reasoning:
+1. **Peer-dep migration** — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (`fix(deps)!: migrate from deprecated @mariozechner/pi-* to @earendil-works/pi-*`)
+2. **Post-bind re-filter** — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72) (`fix(agent-runner): re-filter active tools after bindExtensions so extension tools land in child`)
+3. **Active-agent tag** — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73) (`feat(prompts): inject <active_agent name="..."/> tag for permission resolution`)
 
-1. Production validation is stronger evidence for the upstream maintainer than the spike findings alone.
-2. The patch shapes (especially Patch 2's helper-extraction refactor and Patch 3's exact prepend point) may need adjustment based on real-world behavior; opening PRs prematurely risks needing to amend them under review.
-3. Carrying the fork is low-cost while we iterate; the publishing infrastructure mirrors the other Pi siblings.
-
-A follow-up issue on the RepOne board (linked from #443) tracks the upstream-PR work and the criterion for proceeding.
+If these land upstream, upstream gains the peer-dep fix and the two RepOne patches.
+However, the fork now diverges intentionally beyond those patches — see [`docs/architecture/architecture.md`](../architecture/architecture.md) for the full scope of planned changes.
 
 ## Consequences
 
@@ -61,15 +61,14 @@ A follow-up issue on the RepOne board (linked from #443) tracks the upstream-PR
 
 - The fork's diff against upstream stays minimal — three patches plus tooling alignment.
 - We avoid landing a speculative Patch 1 that would need rework if upstream's `ExtensionContext` API changes.
-- We get production evidence before asking the upstream maintainer to review.
+- Production evidence strengthened the upstream PRs.
 
 ### Negative
 
 - The `pi -e <path>` ephemeral-extension case in subagents will not work until Patch 1 lands. We accept this because no consumer in scope uses that pattern.
-- Patches 2 and 3 stay carried in `@gotgenes/pi-subagents` rather than upstream. Consumers must use this fork (not the upstream package) to get the patches.
 
 ### Operational
 
-- A follow-up issue on the RepOne board (linked from this fork's `README.md` "Deviations from upstream" section and from RepOne issue #443) records both deferrals.
-- When upstream PRs are eventually opened, they should be opened separately for Patches 2 and 3 to keep review simple.
+- Upstream PRs are open and linked above. If merged, upstream gains the three patches, but the fork continues independently with broader architectural changes per [`docs/architecture/architecture.md`](../architecture/architecture.md).
+- The architecture document governs the fork's direction going forward; this ADR's original "thin-patch" framing no longer describes the fork's trajectory.
 - When Patch 1 is eventually added, it should be a separate ADR in `docs/decisions/` with its own follow-up.