@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-8-testability.md

@@ -0,0 +1,103 @@
+# Phase 8: Testability, display extraction, and menu decomposition
+
+Eliminated `vi.mock()` module mocking in the two most fragile test suites by injecting IO-touching collaborators; consolidated shared test fixtures; extracted display helpers into a reusable module; decomposed the largest UI file.
+
+Steps G and H eliminated 11 of the original 12 `vi.mock()` calls in the runner tests, removing fragile call-sequence assertions in favour of injected stubs.
+Step G resolved `session-config.test.ts`; Step H resolved both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`.
+
+The display and menu improvements were identified during Phase 7 but deferred because they did not gate encapsulation work.
+The display extraction unblocked menu decomposition.
+
+## Test pain points (resolved)
+
+| Symptom                                                       | Resolution                                                     |
+| ------------------------------------------------------------- | -------------------------------------------------------------- |
+| 7 `vi.mock()` calls in `agent-runner.test.ts`                 | Step H (#133): injected `RunnerIO` stubs                       |
+| 7 `vi.mock()` calls in `agent-runner-extension-tools.test.ts` | Step H (#133): same                                            |
+| 52 `as any` casts across test suite                           | Step I (#134): reduced to 15                                   |
+| 3× duplicated `mockSession()`                                 | Step F (#131): shared `createMockSession()` in `test/helpers/` |
+| 3× duplicated `makeDeps()`                                    | Step F (#131): shared `createToolDeps()` in `test/helpers/`    |
+
+The well-designed test suites - `agent-manager.test.ts` (1 mock, DI via `AgentRunner` interface), `notification.test.ts` (0 mocks, pure functions + DI), and `agent-tool.test.ts` (0 mocks, tests via deps bag) - confirmed the pattern: modules that accept collaborators through injection produce resilient tests; modules that import collaborators directly produce fragile mock-heavy tests.
+
+## Step F: Shared test fixtures (#131)
+
+Consolidated duplicated mock factories into `test/helpers/`.
+
+1. `createMockSession()` - subscribable event bus with `emit()` helper; replaced 3 hand-rolled copies.
+2. `createToolDeps()` - builds `AgentToolDeps` with sensible defaults and override support; replaced 3 `makeDeps()` copies.
+3. `makeRecord()` - `AgentRecord` factory with sensible defaults; replaced scattered inline construction.
+4. `STUB_CTX` - shared stub `ExtensionContext` constant; centralised unavoidable bridge casts.
+
+Impact: reduced test boilerplate; single source of truth for mock shapes; changes to dep interfaces propagate automatically.
+
+## Step G: Inject IO collaborators into session-config (#132)
+
+`assembleSessionConfig` now accepts `io: AssemblerIO` as a required parameter.
+`index.ts` constructs the real `AssemblerIO` from direct imports via the `RunnerIO.assemblerIO` field (wired in Step H).
+`session-config.test.ts` injects stubs - all 4 `vi.mock()` calls eliminated, assertions shifted to `SessionConfig` output properties.
+
+## Step H: Inject SDK boundary into agent-runner (#133)
+
+`runAgent()` now accepts `io: RunnerIO` as a required parameter bundling all IO collaborators: `detectEnv`, `getAgentDir`, `createResourceLoader`, `deriveSessionDir`, `createSessionManager`, `createSettingsManager`, `createSession`, and `assemblerIO`.
+
+`createAgentRunner(io: RunnerIO): AgentRunner` factory captures the boundary at construction time so `AgentManager` and the `AgentRunner` interface remain unchanged.
+`index.ts` constructs the real `RunnerIO` from Pi SDK imports and sibling modules.
+
+Impact: all 7 `vi.mock()` calls eliminated from both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected stubs; SDK imports moved to the extension entry point.
+
+## Step I: Reduce `as any` casts in tests (#134)
+
+Reduced `as any` count from 93 to 15 (plus 13 explicit `as unknown as T` bridge casts).
+
+Production changes:
+
+- `ResourceLoaderOptions.appendSystemPromptOverride` typed to match `DefaultResourceLoaderOptions`; `createResourceLoader` factory cast removed from `index.ts`.
+- `CreateSessionOptions.settingsManager` / `RunnerIO.createSettingsManager` typed as `SettingsManager`.
+- `WidgetLike` interface in `runtime.ts` narrows the widget field.
+- Local `ToolCallContent` / `BashExecutionMessage` type guards replace `as any` duck-typing in `conversation-viewer.ts` and `agent-runner.ts`.
+- `textResult()` return no longer casts `details as any`.
+- `toAgentSession()` helper and `STUB_CTX` constant centralise unavoidable bridge casts.
+
+Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred - requires `AgentManager.spawn` to accept `ParentSnapshot` directly), 2 `print-mode.test.ts` (same ExtensionContext/API pattern), 2 private-field test access, 1 `createSession` SDK bridge in `index.ts`, 1 `foreground-runner.ts` `AgentToolResult<any>` detail, 1 `stub-ctx.ts` comment.
+
+## Step J: Extract display helpers (#135)
+
+`ui/display.ts` now contains all pure formatters, display helpers, constants, and shared types (`Theme`, `AgentDetails`).
+`agent-widget.ts` dropped from 522 → ~340 lines.
+All consumer modules (menu, tools, renderer, conversation viewer) import from `ui/display.ts` directly.
+`test/agent-widget.test.ts` renamed to `test/display.test.ts`.
+
+## Step K: Decompose agent-menu.ts (#136)
+
+`agent-menu.ts` (668 lines) decomposed into four modules:
+
+1. `ui/agent-file-ops.ts` - `AgentFileOps` interface (`exists`, `read`, `write`, `remove`, `ensureDir`, `findAgentFile`) + `FsAgentFileOps` production implementation.
+2. `ui/agent-config-editor.ts` - `showAgentDetail` with edit/delete/reset/eject/disable/enable transitions (~200 lines).
+3. `ui/agent-creation-wizard.ts` - AI-generation and manual-form creation paths (~250 lines).
+4. `ui/agent-menu.ts` - menu orchestration, agent listing, running-agent viewer, settings form (~300 lines).
+
+Impact: `agent-menu.ts` dropped from 668 → 296 lines; extracted modules receive `AgentFileOps` via injection; `vi.mock("node:fs")` eliminated from `agent-menu.test.ts`.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    subgraph testability["Testability track"]
+        F["F: Shared fixtures"] --> G["G: session-config IO"] --> H["H: agent-runner SDK"] --> I["I: Reduce as-any"]
+    end
+    subgraph display["Display track"]
+        J["J: Display extraction"] --> K["K: Menu decomposition"]
+    end
+```
+
+The two tracks are independent and can proceed in parallel.
+
+## Related issues
+
+- #131 — Shared test fixtures
+- #132 — Inject IO collaborators into session-config
+- #133 — Inject SDK boundary into agent-runner
+- #134 — Reduce as-any casts in tests
+- #135 — Extract display helpers
+- #136 — Decompose agent-menu.ts

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/architecture/history/phase-9-observation-ctx.md

@@ -0,0 +1,122 @@
+# Phase 9: Observation consolidation, ctx elimination, and remaining mocks
+
+Target: consolidate the dual observation model so stats live in one place; remove `ExtensionContext` from all internal APIs; eliminate remaining `vi.mock()` calls and `as any` casts; split widget rendering from lifecycle; apply dependency bag convention.
+
+## Current smells
+
+| Smell                                             | Location                                                                  | Evidence                                                                                                                       | Severity |
+| ------------------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `execute` does config resolution for its callees  | `agent-tool.ts` (145-line `execute`)                                      | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep | Medium   |
+| ~~Wide `ctx` in menu handlers~~                   | ~~`agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts`~~ | Resolved by #146: `MenuUI` interface introduced; 42 `ctx as any` casts eliminated across 5 test files                          | Done     |
+| ~~Direct SDK import in `conversation-viewer.ts`~~ | ~~`conversation-viewer.test.ts`~~                                         | Resolved by #147: `wrapText` injected via `ConversationViewerOptions`; `vi.mock("@earendil-works/pi-tui")` eliminated          | Done     |
+| ~~Widget mixes rendering, lifecycle, and state~~  | ~~`agent-widget.ts` (370 lines)~~                                         | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                         | Done     |
+| `deps.` prefix noise in function bodies           | remaining modules across tools, UI, service-adapter                       | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line      | Low      |
+
+## Dependency bag convention
+
+Applied incrementally as each step touches a module:
+
+- **≤4 fields** - accept as plain parameters; drop the interface.
+- **≥5 fields** - keep a named interface but destructure in the function signature (`{ manager, widget }: ForegroundDeps`) so the function body uses bare names, not `deps.foo`.
+
+This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
+
+## Step L: Consolidate observation model (#144)
+
+Removed `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
+UI consumers read stats from `AgentRecord` instead of the tracker.
+The UI observer retains event subscriptions for re-render triggers but no longer accumulates stats independently.
+
+Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
+The 15+ callsites that navigate `record.execution?.session` simplify to `record.session`.
+
+Apply the dependency bag convention to touched modules: `NotificationDeps` (4 fields) becomes plain parameters on `NotificationManager` constructor.
+
+Impact: eliminates dual counting; removes `??` fallback pattern from widget and conversation viewer; hides `ExecutionState` structure from consumers.
+
+## Step M: Decompose execute and push ExtensionContext to the boundary (#145)
+
+Extracted config resolution into `resolveSpawnConfig` (pure function in `spawn-config.ts`).
+Injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` so `execute` no longer reads `ctx` beyond `ctx.ui` (already delegated to `widget.setUICtx`).
+`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
+`service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
+`foreground-runner` and `background-spawner` receive `ResolvedSpawnConfig` + domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
+
+Dissolved `ForegroundDeps`, `BackgroundDeps`, and `AdapterDeps` into plain parameters.
+`AgentToolDeps` is destructured in the `createAgentTool` signature.
+
+After this step, `ExtensionContext` appears only in:
+
+- `index.ts` closures (wired at extension startup)
+- `service-adapter.ts` (cross-extension boundary)
+- Menu handlers (addressed by Step N)
+
+Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
+
+## Step N: Narrow UI context for menu handlers (#146)
+
+Defined `MenuUI` interface (exported from `agent-menu.ts`) with `select`, `confirm`, `input`, `notify`, `editor`, and `custom` methods — the exact subset `ctx.ui` methods used by menu handlers.
+All inner functions in `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts` now accept `(ui: MenuUI)` instead of `(ctx: ExtensionContext)`.
+`index.ts` passes `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)` to the handler.
+
+`AgentMenuManager.spawnAndWait` and `WizardManager.spawnAndWait` both accept `ParentSnapshot` (enabled by Step M).
+Creation wizard threads `parentSnapshot` from `showCreateWizard(ui, parentSnapshot)` → `showGenerateWizard(ui, parentSnapshot, targetDir)` → `manager.spawnAndWait(parentSnapshot, ...)`.
+
+Applied the dependency bag convention:
+
+- `AgentConfigEditorDeps` (4 fields), `GetResultDeps` (4 fields), `SteerToolDeps` (4 fields) dissolved into plain parameters.
+- `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) kept as interfaces, destructured in the function signature.
+
+After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures and `service-adapter.ts` (cross-extension bridge).
+
+Impact: eliminated 42 `ctx as any` casts across 5 test files (`agent-menu.test.ts`: 8, `agent-config-editor.test.ts`: 20, `agent-creation-wizard.test.ts`: 14); tests construct plain `MenuUI`-shaped objects with no cast.
+
+## Step O: Inject text wrapping into ConversationViewer (#147)
+
+Accepted `wrapText: (text: string, width: number) => string[]` via `ConversationViewerOptions`.
+`agent-menu.ts` passes the real `wrapTextWithAnsi` import at the `ConversationViewer` construction site.
+Tests inject a stub or the real function directly via options — no module-level mock needed.
+
+Applied the dependency bag convention: `ConversationViewerOptions` is now destructured in the constructor signature.
+
+Impact: eliminated the hoisted `vi.mock("@earendil-works/pi-tui")` from `conversation-viewer.test.ts`; 1 test deleted (mock-mechanism sentinel); net −1 test.
+
+## Step P: Split AgentWidget rendering (#148)
+
+Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
+The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
+Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    subgraph observation["Observation track"]
+        L["L: Consolidate observation #144"] --> P["P: Split widget rendering #148"]
+    end
+    subgraph ctx["ctx elimination track"]
+        M["M: Decompose execute / push ctx #145"] --> N["N: Narrow UI context #146"]
+    end
+    O["O: Inject text wrapping #147"]
+```
+
+The three tracks are independent of each other.
+
+## Projected impact
+
+| Metric                             | Before                   | After                    |
+| ---------------------------------- | ------------------------ | ------------------------ |
+| `vi.mock()` calls remaining        | 4                        | 1 (`print-mode.test.ts`) |
+| `as any` casts remaining           | 45                       | ~5                       |
+| Independent tool-use counters      | 2                        | 1                        |
+| `record.execution?.` traversals    | 15+                      | 0                        |
+| `ExtensionContext` in domain types | 1 (`AgentManager.spawn`) | 0                        |
+| `deps.` prefix accesses            | ~124                     | 0                        |
+
+## Related issues
+
+- #144 — Consolidate observation model
+- #145 — Decompose execute and push ExtensionContext to boundary
+- #146 — Narrow UI context for menu handlers
+- #147 — Inject text wrapping into ConversationViewer
+- #148 — Split AgentWidget rendering

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/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 — autonomous 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:
+
+- 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.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0001-deferred-patches.md

@@ -0,0 +1,80 @@
+---
+status: superseded
+date: 2026-05-11
+---
+
+# 0001 — Deferred fork patches and upstream-PR strategy
+
+## Status
+
+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
+
+This fork was created to land three pieces of work identified during RepOne issue [#442](https://github.com/Tiny-IG-Software/repone/issues/442):
+
+1. **Peer-dep rename** — `@mariozechner/pi-*` → `@earendil-works/pi-*`.
+2. **Patch 2 — Re-activate extension tools post-`bindExtensions`** (Spike 3 finding).
+3. **Patch 3 — Inject `<active_agent>` tag** (Spike 4 finding).
+
+A fourth piece of work was scoped during the same spike round but deferred:
+
+- **Patch 1 — Mirror parent's `additionalExtensionPaths` (and siblings) into the child's `DefaultResourceLoader`** (Spike 2 finding).
+
+This ADR records why Patch 1 was deferred and the strategy for upstream PRs back to [`tintinweb/pi-subagents`](https://github.com/tintinweb/pi-subagents).
+
+## Decision
+
+### Patch 1 is deferred
+
+The original Spike 2 finding was that the parent's `additionalExtensionPaths` does not propagate to the child's `DefaultResourceLoader`.
+The fix was sketched as "plumb parent's `additionalExtensionPaths` (and siblings) into the child."
+
+During planning for this fork, two implementation constraints surfaced:
+
+1. The parent's `DefaultResourceLoader.additionalExtensionPaths` is **private** — no public getter on `ExtensionContext`.
+2. The parent's CLI flags (e.g., `pi -e <path>`) are parsed in `main.js` and not surfaced through any extension API.
+
+A working patch would have to either:
+
+- Accept new fields in `RunOptions` so callers supply the paths explicitly, **or**
+- Reach into `process.argv` to re-resolve `-e`/`--extensions` flags from the child's perspective.
+
+Neither matches the production need.
+For RepOne (and any consumer that installs extensions via `pi install`), extensions are settings-discoverable: children inherit them independently of the parent's `DefaultResourceLoader` configuration.
+The `pi -e <path>` ephemeral-extension case is the only beneficiary of Patch 1, and it does not appear in our workflow.
+
+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 open
+
+All three divergences now have upstream PRs, opened after production validation in RepOne:
+
+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`)
+
+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
+
+### Positive
+
+- 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.
+- 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.
+
+### Operational
+
+- 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.

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md

@@ -0,0 +1,98 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0002 — Workspaces and permissions are extensions on a minimal core
+
+## Status
+
+Accepted.
+Supersedes the "agent collaborator architecture" framing of Phase 16 (an abandoned exploration) and the work shipped under it: issue #256 (`WorktreeIsolation` as an `Agent` collaborator) and issue #257 (`ChildSessionFactory` extraction, parked at planning).
+Reclaims Phase 16's original intent — "invert dependencies" — and extends it to evict worktree isolation from the core.
+
+## Context
+
+The core question that triggered this decision: a single-method `ChildSessionFactory` with a `create(cwd?)` method (planned for #257) looked like it wanted to be a function, and the `cwd` parameter was late-bound.
+Pulling that thread exposed progressively more rudimentary issues.
+
+1. `cwd` is late-bound because `WorktreeIsolation.setup()` is called lazily inside `Agent.run()`, after construction — a two-phase `construct-then-setup()` that violates design principle 8 ("Construct complete").
+2. The worktree is *ready* only at dequeue (a concurrency slot is held and `git worktree add` has run).
+   "Construct when ready" therefore means constructing the worktree at run-start, not at spawn — which dissolves the lazy `setup()` and makes `cwd` knowable at construction.
+3. The worktree and the child session share one lifespan: both are born at run-start and torn down at completion (the worktree's cleanup saves a branch; the session is disposed).
+   Resources with one lifetime are one resource, not sibling collaborators that `Agent` must sequence.
+   The `create(cwd?)` parameter only existed because we split one run-scoped resource (the worktree) out and made `Agent` relay its output back in.
+4. Worktrees are not intrinsic to what makes subagents useful.
+   The maintainer never uses them (WIP-of-1, trunk-based, CI/CD).
+   Git worktree isolation is one *strategy* for answering "where does this child run, and what brackets the run?"
+   — a container, a throwaway tmpdir, or a remote sandbox are others.
+   The core needs only *a working directory and a disposal hook*; the default (the parent's cwd, no setup/teardown) is always correct.
+5. This mirrors Phase 14, which evicted tool/extension *policy* (`disallowed_tools`, `extensions` filtering) to `@gotgenes/pi-permission-system`.
+   Worktrees are *environment* policy; they belong outside the core for the same reason.
+
+Permissions and workspaces are orthogonal concerns that must compose as independent extensions on the core, never knowing about each other.
+
+## Decision
+
+pi-subagents is a minimal orchestrator: it spawns a child session derived from the parent, runs the turn loop, tracks and streams and collects the result, gates concurrency, supports resume, and **publishes its lifecycle**.
+Everything else attaches through exactly two extension surfaces, distinguished by the direction of information flow.
+
+### Two extension surfaces
+
+1. **Lifecycle events (observational) — unlimited.**
+   The core emits awaited, ordered events for the child-execution lifecycle (`spawning`, `session-created` pre-`bindExtensions`, `completed`, `disposed`).
+   Any number of extensions subscribe; handlers return nothing.
+   Reactive concerns live here: permission detection, telemetry, UI, notifications.
+   Adding a reactive concern never modifies the core.
+
+2. **Provider seams (generative) — rationed.**
+   The rare concern that must *inject* a value the core consumes synchronously registers a provider the core consults.
+   Today there is exactly one: the **workspace provider** (it returns the child's working directory plus bracketed setup/teardown).
+   A provider seam is the only place the core is "open," so the list is kept as small as possible.
+
+### The discriminator
+
+When deciding how a concern attaches:
+
+- It only needs to **know** what happened → subscribe to a lifecycle event (observational, unlimited).
+- It must **return a value the core consumes** → register a provider (generative, rationed).
+
+Permissions are observational: the core does not enforce policy; it publishes the child's identity at the pre-bind instant so the permission extension (loaded in the child) can detect "am I a subagent?"
+and gate tool calls at runtime.
+Workspaces are generative: the core cannot default the cwd away when an isolation strategy is requested, so the provider hands it back.
+
+### The governing rule: no vacant hooks
+
+The architecture must *admit* a seam without *shipping* it until a concrete consumer exists.
+A provider seam with no consumer is not extensibility — it is a speculative abstraction that taxes every reader, and `fallow` flags it as dead.
+Latent extensibility (the design can host the seam additively) is the deliverable; a vacant hook is not.
+
+### What leaves the core
+
+- **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) → a new package, `@gotgenes/pi-subagents-worktrees`, that implements the workspace provider and owns the git plumbing and the "saved to branch" result.
+- **`permission-bridge.ts`** → retired.
+  The core stops reaching *out* to `Symbol.for("@gotgenes/pi-permission-system:service")` and instead *emits* lifecycle events the permission system subscribes to.
+- **`isolated` / `extensions: false` / `noSkills`** → removed.
+  Deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
+  Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and cannot be reduced to observation, so it is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
+
+### What stays in the core (not policy)
+
+- The **recursion guard** (stripping the core's own `subagent` / `get_subagent_result` / `steer_subagent` tools from children).
+  It defends the core's own invariant — a subagent must not recursively spawn — keyed off the core's own tool names.
+  With `isolated` gone, children always load the parent's resources, so the guard becomes unconditional rather than gated on `cfg.extensions`.
+
+### Composition test
+
+Install neither extension, only permissions, only workspaces, or both: the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
+Permissions depend only on the core's events; workspaces depend only on the core's provider seam; the core depends on neither.
+
+## Consequences
+
+- The "agent collaborator architecture" Phase 16 (give `Agent` a worktree collaborator + a session factory) is abandoned.
+  #256 is superseded (worktree was placed in the wrong layer); #257 is parked (it polished a subsystem slated for eviction).
+- A new package `@gotgenes/pi-subagents-worktrees` is introduced; the core spawn API drops `isolation` and `isolated`.
+- `permission-bridge.ts` is removed; `@gotgenes/pi-permission-system` migrates from a published-service lookup to lifecycle-event subscription, which requires the core to emit an awaited, ordered `session-created` event before `bindExtensions()`.
+  Confirming Pi's event model supports awaited pre-bind emission is the first investigation of the reclaimed phase.
+- Once the cwd is resolved through the provider seam rather than relayed by `Agent`, child-session creation can construct a born-complete execution and the "runner" concept dissolves — recovering the structural goal of the abandoned collaborator steps by a cleaner route.
+- The reclaimed Phase 16 roadmap and step issues live in [`docs/architecture/architecture.md`](../architecture/architecture.md).

package/node_modules/@nklisch/pi-plugins/node_modules/@nklisch/pi-subagents/docs/decisions/0003-publish-bundled-type-declarations.md

@@ -0,0 +1,71 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0003 — Publish a bundled `.d.ts` for the public surface
+
+## Status
+
+Accepted.
+Introduces the repository's first build step, scoped to type declarations only.
+
+## Context
+
+`@gotgenes/pi-subagents` could not be imported by another TypeScript package in this workspace.
+Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`) is the first intra-repo consumer: it must `implements WorkspaceProvider` and call `getSubagentsService().registerWorkspaceProvider(...)`, both of which require importing the package by name.
+
+A `tsc --traceResolution` of a sibling consuming the package surfaced two compounding failures.
+
+1. `package.json` `exports["."]` pointed at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   A latent bug, unnoticed because nothing in-repo imported the package by name.
+2. Once corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via the `#src/*` alias.
+   When a sibling's `tsc` follows the symlink, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and resolve into the *consumer's* `src/` — a global-`paths` collision, since both packages define `#src/*`.
+   The fallback to the publisher's `package.json` `imports` field also fails: `tsc` cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
+
+The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
+A shallow alias-free entry is therefore not achievable without a substantial source restructure.
+
+This collides with the ship-source model ([ADR-0002]): every package ships raw `.ts` executed directly by Pi, with no build step.
+
+## Decision
+
+Emit a single, self-contained `dist/public.d.ts` for the public surface and advertise it through a `types` export condition, while the runtime entry continues to serve `.ts` source.
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into one file, inlining the internal `#src/*` types and keeping peer-dependency types (`@earendil-works/*`, `@sinclair/typebox`) external.
+  We ship `.ts` source, so only the declaration bundle is emitted — no JS.
+- The bundle is generated at `prepack` time and shipped via a `files` allowlist; it is gitignored and never committed.
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime consumers; its `import type` lines erase, so no runtime `#src/*` resolution is needed.
+- A `pnpm pack` → throwaway-consumer → `tsc` harness proves external consumability with no publish round-trip and no workspace privileges.
+
+This is the repository's first build step.
+It is deliberately narrow: it produces type declarations only and changes nothing about how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+
+## Alternatives considered
+
+- Alias-free public entry (restructure the source so the entry's full type closure resolves via same-directory `./` imports).
+  Mechanically possible, but it requires moving the `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and untangling the `agent.ts`/`types.ts` graph, with care that inner layers do not import the outer service layer.
+  `eslint`'s `no-parent-relative-imports` rule (which forbids `../`) narrows the options further.
+  Larger blast radius than emitting a `.d.ts`, and it churns the domain model to serve a packaging concern.
+- A self-contained entry that re-declares the public types inline, guarded by a conformance test.
+  Avoids a build step but duplicates the seam/usage/status type definitions, which drift over time.
+
+## Consequences
+
+- The repository now has a build step, but it is type-only and isolated to this package; the ship-source model is otherwise intact.
+- Consumers (including `@gotgenes/pi-subagents-worktrees` in #263) consume the packaged public interface like any external developer — no `workspace:*` privileges.
+- The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
+  This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
+- Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.
+
+[ADR-0002]: ./0002-extensions-on-a-minimal-core.md