@gotgenes/pi-subagents 16.2.1 → 16.3.0

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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).
 
+## [16.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.2...pi-subagents-v16.3.0) (2026-06-16)
+
+
+### Features
+
+* self-seed finished agents in AgentWidget.update ([#377](https://github.com/gotgenes/pi-packages/issues/377)) ([fd99a29](https://github.com/gotgenes/pi-packages/commit/fd99a297f70ce4c1c078fd486be042f691fe5a79))
+
+
+### Documentation
+
+* **pi-subagents:** drop removed memory, skills, isolation surfaces ([7cf20ee](https://github.com/gotgenes/pi-packages/commit/7cf20eebf109c979a864000cd8b9d84a13d0df90))
+
+## [16.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.1...pi-subagents-v16.2.2) (2026-06-15)
+
+
+### Documentation
+
+* **pi-subagents:** replace fork notice with upstream comparison ([513df4d](https://github.com/gotgenes/pi-packages/commit/513df4d6149178c5c8074cf07d8ad248c50d4c47))
+
 ## [16.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.2.0...pi-subagents-v16.2.1) (2026-06-15)
 
 

package/README.md

@@ -6,11 +6,8 @@ A [pi](https://pi.dev) extension that brings **Claude Code-style autonomous sub-
 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.
+> Originally forked from [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb), now an independently maintained hard fork.
+> See [Comparison with upstream](./docs/comparison-with-upstream.md) for a feature-by-feature comparison and guidance on which to choose.
 
 <img width="600" alt="pi-subagents screenshot" src="https://github.com/gotgenes/pi-subagents/raw/main/media/screenshot.png" />
 
@@ -30,9 +27,6 @@ Run them in foreground or background, steer them mid-run, resume completed sessi
   Unknown types fall back to general-purpose with a note
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
-- **Persistent agent memory** — three scopes (project, local, user) with automatic read-only fallback for agents without write tools
-- **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)
 - **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
@@ -177,21 +171,16 @@ All fields are optional — sensible defaults for everything.
 | `description`       | filename       | Agent description shown in tool listings                                                                                                                                                                                                                                                                                |
 | `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                                                                                                                                           |
 | `tools`             | all 7          | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools                                                                                                                                                                                                                            |
-| `extensions`        | `true`         | `true` to inherit all MCP/extension tools, `false` to disable                                                                                                                                                                                                                                                           |
-| `skills`            | `true`         | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations)                                                                                                                                                                 |
-| `memory`            | —              | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents                                                                                                                                                                                                                             |
-| `isolation`         | —              | Set to `worktree` to run in an isolated git worktree                                                                                                                                                                                                                                                                    |
 | `model`             | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`)                                                                                                                                                                                                                                                        |
 | `thinking`          | inherit        | off, minimal, low, medium, high, xhigh                                                                                                                                                                                                                                                                                  |
 | `max_turns`         | unlimited      | Max agentic turns before graceful shutdown. `0` or omit for unlimited                                                                                                                                                                                                                                                   |
 | `prompt_mode`       | `append`       | `replace`: parent prompt is the cacheable base; body is appended last with full control (no `<sub_agent_context>` bridge, no `<agent_instructions>` wrapper). `append`: parent prompt is the base; body is wrapped in `<agent_instructions>` and a sub-agent context bridge is injected (agent acts as a "parent twin") |
 | `inherit_context`   | `false`        | Fork parent conversation into agent                                                                                                                                                                                                                                                                                     |
 | `run_in_background` | `false`        | Run in background by default                                                                                                                                                                                                                                                                                            |
-| `isolated`          | `false`        | No extension/MCP tools, only built-in                                                                                                                                                                                                                                                                                   |
 | `enabled`           | `true`         | Set to `false` to disable an agent (useful for hiding a default agent per-project)                                                                                                                                                                                                                                      |
 
 Frontmatter is authoritative.
-If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent.
+If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, or `run_in_background`, those values are locked for that agent.
 `subagent` tool parameters only fill fields the agent config leaves unspecified.
 
 ## Tools
@@ -210,8 +199,6 @@ Launch a sub-agent.
 | `max_turns`         | number       | no       | Max agentic turns. Omit for unlimited (default)                  |
 | `run_in_background` | boolean      | no       | Run without blocking                                             |
 | `resume`            | string       | no       | Agent ID to resume a previous session                            |
-| `isolated`          | boolean      | no       | No extension/MCP tools                                           |
-| `isolation`         | `"worktree"` | no       | Run in an isolated git worktree                                  |
 | `inherit_context`   | boolean      | no       | Fork parent conversation into agent                              |
 
 ### `get_subagent_result`
@@ -334,77 +321,16 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 `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.
 
-## Persistent Agent Memory
-
-Agents can have persistent memory across sessions.
-Set `memory` in frontmatter to enable:
-
-```yaml
----
-memory: project   # project | local | user
----
-```
-
-| Scope     | Location                         | Use case                           |
-| --------- | -------------------------------- | ---------------------------------- |
-| `project` | `.pi/agent-memory/<name>/`       | Shared across the team (committed) |
-| `local`   | `.pi/agent-memory-local/<name>/` | Machine-specific (gitignored)      |
-| `user`    | `~/.pi/agent-memory/<name>/`     | Global personal memory             |
-
-Memory uses a `MEMORY.md` index file and individual memory files with frontmatter.
-Agents with write tools get full read-write access.
-**Read-only agents** (no `write`/`edit` tools) automatically get read-only memory — they can consume memories written by other agents but cannot modify them.
-This prevents unintended tool escalation.
-
 ## Worktree Isolation
 
-Set `isolation: worktree` to run an agent in a temporary git worktree:
-
-```text
-subagent({ subagent_type: "refactor", prompt: "...", isolation: "worktree" })
-```
-
-The agent gets a full, isolated copy of the repository.
-On completion:
-
-- **No changes:** worktree is cleaned up automatically
-- **Changes made:** changes are committed to a new branch (`pi-agent-<id>`) and returned in the result
-
-If the worktree cannot be created (not a git repo, no commits, or `git worktree add` fails), the `subagent` tool returns a clear error instead of running unisolated — `isolation: "worktree"` is a strict guarantee, not a hint.
-Initialize git and commit at least once, or omit `isolation`.
+Worktree isolation lives in a companion package, not this core.
+Install [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees) and list the agent types you want isolated in its `worktreeAgents` config — opted-in agents run in a temporary git worktree, and their changes are saved to a branch on completion.
+The earlier `isolation: "worktree"` spawn flag and `isolation:` frontmatter key were removed from the core.
 
-## Skill Preloading
+## Removed: agent memory and skill preloading
 
-Skills can be preloaded by name and injected into the agent's system prompt:
-
-```yaml
----
-skills: api-conventions, error-handling
----
-```
-
-**Discovery roots** (checked in this order, first match wins):
-
-| Scope   | Path                                                           | Source                                                       |
-| ------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
-| Project | `<cwd>/.pi/skills/`                                            | Pi-standard                                                  |
-| Project | `<cwd>/.agents/skills/`                                        | [Agent Skills spec](https://agentskills.io/integrate-skills) |
-| User    | `$PI_CODING_AGENT_DIR/skills/` (default `~/.pi/agent/skills/`) | Pi-standard                                                  |
-| User    | `~/.agents/skills/`                                            | [Agent Skills spec](https://agentskills.io/integrate-skills) |
-| User    | `~/.pi/skills/`                                                | Legacy (pre-Pi)                                              |
-
-**Per root, a skill named `foo` resolves to the first of:**
-
-- `<root>/foo.md` — flat file at the top level
-- `<root>/foo/SKILL.md` — directory skill (top-level)
-- `<root>/*/.../foo/SKILL.md` — directory skill, found by recursive descent
-
-Recursion skips dotfile directories and `node_modules`.
-A directory that itself contains a `SKILL.md` is treated as a single skill — we don't descend into it.
-Traversal is byte-order sorted for deterministic resolution across filesystems.
-
-**Security:** symlinks are rejected at every layer (root, flat file, skill directory, `SKILL.md` inside a skill directory) — intentional deviation from Pi, which follows symlinks.
-Skill names with path-traversal characters (`..`, `/`, `\`, spaces, leading dot, >128 chars) are rejected.
+Persistent agent memory (the `memory:` frontmatter key) and skill preloading (the `skills:` frontmatter key) were removed when the core was slimmed down.
+Children now always inherit the parent's skills and extensions, so the `isolated`, `extensions`, and `skills` frontmatter keys no longer exist.
 
 ## Migrating from `disallowed_tools`
 
@@ -436,73 +362,18 @@ When `@gotgenes/pi-permission-system` is not installed, the lifecycle events hav
 
 ## Architecture
 
-See `docs/architecture/architecture.md` for the full architecture document with domain decomposition, Mermaid diagrams, and improvement roadmap.
+This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.
 
-```text
-src/
-  index.ts                          # Extension entry: tool/command registration, rendering
-  runtime.ts                        # Session-scoped state bag with methods
-  types.ts                          # Shared type definitions
-  settings.ts                       # Persistent settings (concurrency, turn limits)
-  config/                           # Agent type registry and configuration
-    agent-types.ts                  # Unified agent registry (defaults + custom)
-    default-agents.ts               # Embedded default agent configs
-    custom-agents.ts                # Load user-defined agents from .pi/agents/*.md
-    invocation-config.ts            # Per-call merge of tool params + agent config
-  session/                          # Pure session assembly
-    session-config.ts               # Session configuration assembler
-    prompts.ts                      # Config-driven system prompt builder
-    context.ts                      # Parent conversation context for inherit_context
-    conversation.ts                 # Render a session's messages as formatted text
-    content-items.ts                # Shared message content parsing
-    env.ts                          # Environment detection (git, platform)
-    model-resolver.ts               # Fuzzy model matching
-    session-dir.ts                  # Session directory derivation
-  lifecycle/                        # Agent execution and state tracking
-    agent-manager.ts                # Collection manager + observer wiring
-    agent.ts                        # Full execution lifecycle (run, abort, steer, workspace)
-    create-subagent-session.ts      # Assembly factory: session creation, binding, tool filtering
-    subagent-session.ts             # Born-complete child session: turn loop, steer, dispose
-    child-lifecycle.ts              # Child-execution lifecycle event publisher
-    concurrency-queue.ts            # Background agent scheduling
-    parent-snapshot.ts              # Immutable spawn-time parent state
-    turn-limits.ts                  # Turn-count policy (normalizeMaxTurns)
-    workspace.ts                    # Workspace provider seam
-    usage.ts                        # Token usage tracking
-  observation/                      # Progress tracking and notification
-    record-observer.ts              # Session-event stats observer
-    notification.ts                 # Completion nudges
-    notification-state.ts           # Notification state tracking
-    renderer.ts                     # Notification rendering
-  service/                          # Cross-extension API boundary
-    service.ts                      # SubagentsService interface + Symbol.for() accessors
-    service-adapter.ts              # SubagentsService wrapper around AgentManager
-  tools/                            # LLM-facing tools
-  ui/                               # Widget, conversation viewer, /agents menu
-```
-
-## Deviations from upstream
+See [`docs/architecture/architecture.md`](./docs/architecture/architecture.md) for the full architecture document — design principles, domain decomposition, module dependency flow, Mermaid diagrams, and the improvement roadmap.
 
-This fork carries three divergences from [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
-Each has a corresponding upstream PR:
+## Relationship to upstream
 
-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 the `EXCLUDED_TOOL_NAMES` recursion guard applies to extension-registered tools (which join the active set during `bindExtensions`).
-   Upstream PR: [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
-3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` includes `<active_agent name="${config.name}"/>` in every assembled child system prompt (both `replace` and `append` modes); the tag follows the cacheable parent-prompt prefix in both 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).
-4. **Child-execution lifecycle events** (`src/lifecycle/child-lifecycle.ts`) — the child-session execution lifecycle is published as ordered events on `pi.events` (`subagents:child:spawning`, `session-created`, `completed`, `disposed`).
-   `session-created` fires synchronously before `bindExtensions()` so consumers (e.g. `@gotgenes/pi-permission-system`) can register the child session before binding proceeds.
-   This inverts the former outbound `permission-bridge` pattern ([ADR-0002] / [#261]) — the core publishes, consumers subscribe.
-   No upstream equivalent — this feature is specific to the `@gotgenes` fork.
+This package is an independently maintained hard fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
+It has diverged substantially in scope and architecture: a minimal core with a typed service API and lifecycle events, with tool-restriction policy and worktree isolation delegated to companion packages.
+Upstream remains the batteries-included option, keeping scheduling, cross-extension RPC, model-scope enforcement, and a built-in tool denylist in a single package.
 
-The upstream `vitest` suite plus tests added for each patch all pass on every commit.
+See [Comparison with upstream](./docs/comparison-with-upstream.md) for a full feature-by-feature comparison against the current upstream release and guidance on which to choose.
 
 ## License
 
 MIT — [tintinweb](https://github.com/tintinweb) (upstream) and [Chris Lasher](https://github.com/gotgenes) (fork)
-
-[ADR-0002]: docs/decisions/0002-extensions-on-a-minimal-core.md

package/docs/architecture/architecture.md

@@ -646,7 +646,7 @@ That method — testability friction as a boundary probe, with its limits — is
 | Metric                     | Value                                   |
 | -------------------------- | --------------------------------------- |
 | Health score               | 78/100 (B)                              |
-| Total LOC                  | 8,356 (60 files, as of Phase 17 Step 4) |
+| Total LOC                  | 8,356 (61 files, as of Phase 17 Step 5) |
 | Dead code                  | 0 files, 0 exports                      |
 | Maintainability index      | 90.8 (good)                             |
 | Avg cyclomatic complexity  | 1.4                                     |
@@ -893,7 +893,7 @@ Updated health metrics (fallow, package-wide including tests):
 | Metric                     | Phase 16 baseline              | Current                                       |
 | -------------------------- | ------------------------------ | --------------------------------------------- |
 | Health score               | 78/100 (B)                     | 78/100 (B)                                    |
-| Source LOC                 | 7,778 (57 files)               | 8,356 (60 files, landed Phase 17 Step 4)      |
+| Source LOC                 | 7,778 (57 files)               | 8,356 (61 files, landed Phase 17 Step 5)      |
 | Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                            |
 | Maintainability index      | 90.8 (good)                    | 90.8 (good)                                   |
 | Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                       |
@@ -970,7 +970,7 @@ Priority = Impact × (6 − Risk).
   Fixed by inverting control: `scheduleVia` captures the limiter promise eagerly inside the agent (no external `.promise =` write), restoring the invariant.
   Lesson: a step's acceptance criteria must include the cross-step invariants it could regress, not only its own grep-verifiable outcome.
 
-#### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375])
+#### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375]) ✅ Complete
 
 - Targets: `src/lifecycle/subagent.ts` (455 LOC after Step 2 extracted SubagentState — still the largest source file).
 - Smell: Category B (oversized class; per-run listener fields declared mid-class) and Category C (state owns its mutations: workspace dispose logic appears in `run()`'s catch, `completeRun`, and `failRun`).
@@ -981,19 +981,26 @@ Priority = Impact × (6 − Risk).
   `subagent.ts`: 488 → 448 LOC.
   Test count: 982 → 994 (+12: 7 RunListeners + 13 WorkspaceBracket − 8 redundant Subagent listener tests).
 
-#### Step 5 — Extract the manager observer from index.ts into a class ([#376])
+#### Step 5 — Extract the manager observer from index.ts into a class ([#376]) ✅ Complete
 
 - Targets: `src/index.ts` (inline `SubagentManagerObserver` literal, ~70 lines), new module under `src/observation/`.
 - Smell: Category B/E — `index.ts` is the dominant churn hotspot (31.3, 91 commits); the literal mixes event emission, record persistence (`appendEntry`), and notification dispatch; principle 9 (state and behavior belong in classes, not closure-captured literals).
 - Change: extract a class (e.g. `SubagentEventsObserver`) constructed with narrow deps (`emit`, `appendEntry`, the `NotificationSystem`).
 - Outcome: `index.ts` < 170 lines; the observer's three concerns unit-tested directly without booting the extension.
+- Landed: `src/observation/subagent-events-observer.ts` (new, 97 LOC); `index.ts` 226 → 177 lines; 60 → 61 source files; 994 → 1009 tests (+15 covering all four observer methods).
 
-#### Step 6 — Split widget delegation out of SubagentRuntime ([#377])
+#### Step 6 — Split widget delegation out of SubagentRuntime ([#377]) ✅ Complete
 
-- Targets: `src/runtime.ts`, `src/tools/agent-tool.ts` (`AgentToolRuntime`), `src/tools/foreground-runner.ts`, `src/tools/background-spawner.ts`, `src/observation/notification.ts` (`NotificationManager` constructor), `src/index.ts`.
+- Targets: `src/runtime.ts`, `src/tools/agent-tool.ts` (`AgentToolRuntime`), `src/handlers/tool-start.ts` (`ToolStartRuntime`), `src/observation/notification.ts` (`NotificationManager` constructor), `src/ui/agent-widget.ts`, `src/index.ts`.
 - Smell: Category C — relay-only dependency (five delegation methods that only forward to `widget`) and a post-construction `runtime.widget =` write violating principle 8.
-- Change: pass the existing `WidgetLike` handle directly to the consumers that need it (tool deps, `NotificationManager`) and construct the widget before them; remove the `widget` field and the five relay methods from `SubagentRuntime`.
-- Outcome: `SubagentRuntime` has zero widget knowledge; no post-construction field writes in `index.ts`; tool fixtures stub a 5-method `WidgetLike` instead of widget methods on the runtime mock.
+- Constraint discovered in planning: "pass the handle directly to the consumers" is infeasible for `NotificationManager`, which is a _transitive dependency_ of the widget (`NotificationManager → widget → manager → observer → NotificationManager`).
+  The `runtime.widget` lazy field exists to break exactly this cycle; removing it forces the one late seam to move, and the operator's principles (no setters, instantiate ready-to-work) rule out relocating it to a setter or forward-ref `let`.
+- Change (tidy-first): first dissolve the cycle by giving `AgentWidget.update()` self-seeding of `finishedTurnAge` for finished agents it observes via `listAgents()`, then drop the `markFinished`/`updateWidget` callbacks from `NotificationManager` (it keeps `agentActivity.delete` + nudge scheduling).
+  With the cycle gone, the widget is constructed as a `const` after the manager and injected directly into `AgentTool` and `ToolStartHandler`; the `widget` field, the five relay methods, and the post-construction write delete cleanly, and `AgentToolRuntime` narrows to its context-query slice.
+- Outcome: `SubagentRuntime` has zero widget knowledge; no post-construction field writes in `index.ts`; the construction graph is a cycle-free DAG (`notifications → observer → manager → widget → {AgentTool, ToolStartHandler}`).
+- Landed: `AgentWidget.seedFinishedAgents` owns completion detection; `NotificationManager` has no widget dependency (2-arg constructor); `AgentToolWidget` (in `agent-tool.ts`) and `ToolStartWidget` (in `tool-start.ts`) are narrow per-consumer interfaces the real widget satisfies structurally; tool fixtures stub a `widget` separate from the narrowed `runtime` mock.
+  Behavior-preserving: the widget timer runs through every background completion, so self-seeding lands ≤80ms later within the same turn (linger is turn-based).
+  Test count: 1009 → 1005 (+3 widget self-seed tests, −7 removed relay/field tests).
 
 #### Step 7 — Consolidate lifecycle test fixtures ([#378])
 

package/docs/comparison-with-upstream.md

@@ -0,0 +1,77 @@
+# Comparison with upstream
+
+`@gotgenes/pi-subagents` began as a fork of [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents) by [@tintinweb](https://github.com/tintinweb).
+The original design — Claude Code-style subagent dispatch, the live widget, the conversation viewer, custom agent types — is the foundation everything here builds on.
+
+It has since become an independently maintained hard fork.
+It follows its own architecture, does not track upstream as a merge target, and cherry-picks upstream fixes only when they fit its scope.
+This document compares the fork against the current upstream release so you can choose between them.
+
+Versions compared: `@gotgenes/pi-subagents` 16.2.1 and `@tintinweb/pi-subagents` 0.10.3 (current at the time of writing).
+
+## At a glance
+
+| Aspect          | @gotgenes/pi-subagents          | @tintinweb/pi-subagents                 |
+| --------------- | ------------------------------- | --------------------------------------- |
+| Philosophy      | Minimal, composable core        | Batteries-included, all-in-one          |
+| Pi peer scope   | `@earendil-works/pi-*` (>=0.75) | `@earendil-works/pi-*` (>=0.74)         |
+| Spawn tool name | `subagent`                      | `Agent`                                 |
+| Runtime deps    | `@sinclair/typebox`             | `@sinclair/typebox`, `croner`, `nanoid` |
+| License         | MIT                             | MIT                                     |
+
+Both ship TypeScript source directly (Pi runs `./src/index.ts`) and target the same `@earendil-works/pi-*` Pi.
+The peer-dep migration that prompted the original fork has since landed upstream, so the Pi scope is no longer a differentiator.
+
+## Common ground
+
+Both extensions provide the same core experience:
+
+- Claude Code-style foreground/background subagents with a live above-editor widget and a conversation viewer.
+- Custom agent types defined in `.pi/agents/<name>.md` with YAML frontmatter (system prompt, model, thinking, tools).
+- Fuzzy model selection, context inheritance, mid-run steering, session resume, and graceful turn limits.
+- A `pi.events` lifecycle bus (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`).
+
+## What upstream has that this fork does not
+
+Upstream is the batteries-included option.
+It keeps several subsystems built in that this fork deliberately removed or delegated:
+
+| Capability              | @tintinweb/pi-subagents                           | @gotgenes/pi-subagents                                                                                                                            |
+| ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tool restrictions       | `disallowed_tools` frontmatter (denylist)         | Delegated — `permission:` via [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) |
+| Worktree isolation      | Built-in                                          | Delegated — [`@gotgenes/pi-subagents-worktrees`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-subagents-worktrees)               |
+| Persistent agent memory | `memory:` frontmatter (project / local / user)    | Removed                                                                                                                                           |
+| Skill preloading        | `skills:` frontmatter (preload named skills)      | Removed — children always inherit the parent's skills                                                                                             |
+| Scheduling              | Cron / interval / one-shot subagents (`schedule`) | Removed                                                                                                                                           |
+| Cross-extension control | `subagents:rpc:*` event RPC                       | Replaced by a typed service (below)                                                                                                               |
+| Model-scope enforcement | `enabledModels` allowlist validation              | Not included                                                                                                                                      |
+| Notifications           | Smart group-join consolidation                    | Individual per-agent notifications                                                                                                                |
+
+## What this fork adds
+
+This fork is a minimal core that other extensions build on, plus a small companion ecosystem:
+
+- **Typed service API** — `SubagentsService` exposed via `Symbol.for()` accessors, so another extension can spawn and manage subagents without importing this package or relying on ad-hoc event RPC.
+- **Child-session lifecycle events** — `subagents:child:spawning` / `session-created` / `completed` / `disposed`, with `session-created` firing synchronously before `bindExtensions()` so consumers can register the child session deterministically.
+- **`<active_agent>` system-prompt tag** — lets [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) resolve per-agent `permission:` frontmatter (allow / ask / deny — richer than a binary denylist) inside the child session.
+- **Companion packages** — permission policy and worktree isolation live in dedicated packages rather than the core.
+- **Re-architected codebase** — decomposed into seven domains behind a typed public API boundary, backed by ~994 tests.
+
+## Which should I use?
+
+**Use `@tintinweb/pi-subagents`** if you want a single, batteries-included extension with nothing else to install: built-in tool denylist, scheduled / cron subagents, cross-extension RPC, and model-scope enforcement in one package.
+It is the canonical upstream and the original.
+
+**Use `@gotgenes/pi-subagents`** if you want a minimal, composable core: richer allow / ask / deny permissions and worktree isolation through companion packages, a typed service plus lifecycle events to build your own extensions on, and an actively refactored codebase — and you do not need built-in scheduling, RPC, or model-scope enforcement.
+
+The spawn tool is named `subagent` here versus `Agent` upstream, so prompts and docs that hard-code the tool name are not drop-in portable between the two.
+
+## Patches contributed upstream
+
+Three of the fork's early changes were opened as PRs against upstream and remain a record of the shared lineage:
+
+1. Peer-dep migration to `@earendil-works/pi-*` — [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71) (upstream has since migrated).
+2. Post-`bindExtensions` active-tool re-filter — [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
+3. `<active_agent>` system-prompt tag — [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
+
+The fork has since diverged well beyond these.