@yefengr/pi-subagents 0.0.0-stage → 0.1.0

package/docs/comparison-with-upstream.md

@@ -0,0 +1,79 @@
+# Comparison with upstream
+
+> Historical document imported from the verified `@gotgenes/pi-subagents@19.3.4` baseline. It describes the lineage and comparison state at that revision, not the current maintenance policy of `@yefengr/pi-subagents`; see [`../UPSTREAM.md`](../UPSTREAM.md).
+
+`@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 and target the same `@earendil-works/pi-*` Pi. This fork exposes `./index.ts` as a thin Pi entry point; its implementation remains in `./src/index.ts`.
+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/docs/configuration.md

@@ -0,0 +1,215 @@
+# Configuration
+
+`@yefengr/pi-subagents` has two configuration surfaces: **agent definition files** that describe an agent type, and a **`subagents.json`** settings file that tunes the runtime.
+Neither is required — every field has a default.
+
+For the tools, commands, events, and service API, see the [README](../README.md).
+
+## Default Agent Types
+
+| Type              | Tools                      | Model                         | Prompt Mode            | Description                                                                                      |
+| ----------------- | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `general-purpose` | all 7                      | inherit                       | `append` (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions            |
+| `Explore`         | read, bash, grep, find, ls | `anthropic/claude-haiku-4-5-20251001` (exact pin) | `replace`              | Fast codebase exploration (read-only); inherits the parent prompt as a base                      |
+| `Plan`            | read, bash, grep, find, ls | inherit                       | `replace`              | Software architect for implementation planning (read-only); inherits the parent prompt as a base |
+
+The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does.
+Explore and Plan use `replace` mode: the parent prompt is the cacheable base and their specialist read-only instructions are appended last, giving them the final say.
+Explore's model is an exact pin, not a fallback: if it is unavailable, unauthenticated, or cannot be resolved by the registry, the spawn fails instead of inheriting the parent model.
+
+In every mode, a child that runs somewhere other than the parent — one given an isolated workspace by a `WorkspaceProvider` — does not inherit the parent's `Current working directory:` footer.
+That line is stripped from the inherited prompt, leaving the fresh footer Pi appends for the child session's own directory as the single, correct claim; without the strip, the child follows the parent's path instead.
+A child sharing the parent's directory inherits the prompt untouched, so its prefix stays byte-identical to the parent's.
+
+Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`). Enablement is managed by `/subagents:agents` and stored per project or globally in `subagents.json`.
+
+## Custom Agents
+
+Define custom agent types by creating `.md` files.
+The filename becomes the agent type name.
+Any name is allowed — using a default agent's name overrides it.
+
+Agents are discovered from two locations (higher priority wins):
+
+| Priority    | Location                                                                         | Scope                         |
+| ----------- | -------------------------------------------------------------------------------- | ----------------------------- |
+| 1 (highest) | `.pi/agents/<name>.md`                                                           | Project — per-repo agents     |
+| 2           | `$PI_CODING_AGENT_DIR/agents/<name>.md` (default `~/.pi/agent/agents/<name>.md`) | Global — available everywhere |
+
+Project-level agents override global ones with the same name, so you can customize a global agent for a specific project.
+The global location follows the upstream `PI_CODING_AGENT_DIR` env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.
+
+### Example: `.pi/agents/auditor.md`
+
+```markdown
+---
+description: Security Code Reviewer
+tools: read, grep, find, bash
+model: anthropic/claude-opus-4-6
+thinking: high
+max_turns: 30
+wrap_up_turns: 2
+max_duration_seconds: 900
+---
+
+You are a security auditor.
+Review code for vulnerabilities including:
+
+- Injection flaws (SQL, command, XSS)
+- Authentication and authorization issues
+- Sensitive data exposure
+- Insecure configurations
+
+Report findings with file paths, line numbers, severity, and remediation advice.
+```
+
+Then spawn it like any built-in type:
+
+```text
+subagent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })
+```
+
+### Frontmatter Fields
+
+All fields are optional — sensible defaults for everything.
+
+| Field               | Default        | Description                                                                                                                                                                                                                                                                                                             |
+| ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`       | filename       | Agent description shown in tool listings                                                                                                                                                                                                                                                                                |
+| `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                                                                                                                                           |
+| `tools`             | all 7          | The agent's complete tool allowlist — built-in or extension-registered names. `none` for no tools. See [Tool selection](#tool-selection)                                                                                                                                                                                |
+| `model`             | inherit parent | Exact model pin (`provider/modelId`) or unqualified fuzzy name (`"haiku"`, `"sonnet"`). A qualified pin never fuzzy-matches another model or provider; an explicit model that cannot be resolved fails the spawn instead of inheriting the parent. |
+| `thinking`          | inherit        | off, minimal, low, medium, high, xhigh                                                                                                                                                                                                                                                                                  |
+| `max_turns`         | global limit   | Positive hard maximum for model turns. It can only tighten the global setting; `0` is invalid.                                                                                                                                                                                                                          |
+| `wrap_up_turns`     | global setting | Non-negative turns reserved within the hard maximum for a final response. It is clamped to `0..max_turns - 1`.                                                                                                                                                                                                          |
+| `max_duration_seconds` | global limit | Positive execution-time limit in seconds. It can only tighten the global setting.                                                                                                                                                                                                                                       |
+| `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                                                                                                                                                                                                                                                                                            |
+Enablement is not an agent-definition field. Use `/subagents:agents` to choose `当前项目` or `全局`, then enable, disable, or restore inheritance. Project overrides are stored in `<cwd>/.pi/subagents.json`; personal global overrides are stored in `~/.pi/agent/subagents.local.json`. The shared `~/.pi/agent/subagents.json` remains read-only for this feature. The persisted `agentEnabled` map uses project-over-global precedence.
+
+Frontmatter is authoritative for `model`, `thinking`, `inherit_context`, and `run_in_background`: when set, those values are locked for that agent and tool parameters only fill omitted fields.
+Only an omitted `model` inherits the parent model. An explicit model from the profile or the tool call is a pin: if it cannot be resolved (unknown name, model without auth, or a `provider/modelId` that is not an exact available match), the spawn fails with the available-model list and never substitutes the parent model.
+Resource settings are deliberately different. `max_turns` and `max_duration_seconds` from a tool call may only lower the profile and global ceilings; they can never raise them. `wrap_up_turns` follows tool-call, then profile, then global precedence and is clamped below the effective hard turn limit.
+
+### Tool selection
+
+`tools` is the agent's **complete allowlist**, not a filter over the built-ins.
+A child session gets exactly the tools it names — nothing else is enabled, whoever registered it.
+
+Entries may name built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) or tools registered by any extension:
+
+```yaml
+---
+description: Browser-driving researcher
+tools: read, grep, find, agent_browser
+---
+```
+
+Naming an extension's tool is the supported way to give a child access to it.
+This matters because a child loads the parent's extensions and runs their setup functions, so an extension **does** call `registerTool` inside the child — and Pi then drops that tool, because the allowlist is applied before the child's tool registry is built.
+The registration reports no error; the tool simply is not there.
+List the tool by name and it is admitted the moment its extension registers it.
+
+Three names are always removed from a child, even when an agent lists them: `subagent`, `get_subagent_result`, and `steer_subagent`.
+This is the recursion guard — without it, an agent could spawn agents of its own without bound.
+
+Accepted forms, all equivalent:
+
+```yaml
+tools: read, grep, find      # comma-separated
+tools: [read, grep, find]    # YAML flow sequence
+tools:                       # YAML block sequence
+  - read
+  - grep
+  - find
+tools: none                  # no tools at all
+```
+
+Omitting `tools` entirely gives the agent all seven built-ins and no extension tools.
+
+Two other settings interact with this list:
+
+- [`excludedExtensionPackages`](#excluding-package-extensions-from-children) stops an extension from loading in children at all, so naming one of its tools has no effect there.
+- When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-system) is installed, its `permission:` frontmatter narrows the set further, per turn.
+  Use it to deny a tool; use `tools` to decide what the agent has in the first place.
+
+## Persistent Settings
+
+Runtime tuning values set via `/subagents:settings` (max concurrency, max turns, reserved wrap-up turns, maximum execution duration, maximum queue wait, abort grace, the two session-retention windows, and the abort-on-interrupt policy) persist across pi restarts.
+A completed subagent's record is kept for the whole parent session (so `get_subagent_result` never misses); only its heavy in-memory session is released — after `consumedSessionRetentionMinutes` once the result has been collected, or after the `unconsumedSessionRetentionMinutes` safety cap if it never was.
+Runtime settings and agent enablement use separate layers. Runtime settings are merged from two files:
+
+- **Global shared:** `~/.pi/agent/subagents.json` — machine-wide runtime defaults and shared child-session policy. It is synchronized from `pi/agent/subagents.json`.
+- **Project:** `<cwd>/.pi/subagents.json` — per-project runtime overrides. Written by `/subagents:settings`.
+
+Agent enablement has an additional personal global layer:
+
+- **Personal global:** `~/.pi/agent/subagents.local.json` — local `agentEnabled` overrides written by `/subagents:agents`.
+- **Project:** `<cwd>/.pi/subagents.json` — project `agentEnabled` overrides, which take precedence over the personal global layer.
+
+`/subagents:agents` never writes the shared global file. If an older shared file still contains `agentEnabled`, it is read as a compatibility layer below `subagents.local.json`.
+
+**Precedence:** project overrides global on any field present in both.
+Missing fields fall back to hardcoded defaults: max concurrency `4`, max turns `30`, reserved wrap-up turns `2`, maximum execution duration `1800` seconds, maximum queue wait `900` seconds, abort grace `5` seconds, consumed-session retention `10` minutes, unconsumed-session retention `720` minutes, and abort-all-on-interrupt `true`.
+
+**Example — global defaults for a beefy machine:**
+
+```bash
+mkdir -p ~/.pi/agent
+cat > ~/.pi/agent/subagents.json <<'EOF'
+{
+  "maxConcurrent": 16,
+  "maxTurns": 20,
+  "wrapUpTurns": 3,
+  "maxDurationSeconds": 1200,
+  "maxQueueWaitSeconds": 300,
+  "abortGraceSeconds": 10,
+  "unconsumedSessionRetentionMinutes": 1440,
+  "abortAllOnInterrupt": false
+}
+EOF
+```
+
+Every project now starts with concurrency 16 and the stated finite resource ceilings, while ESC remains with the parent. Individual projects can still override settings through `/subagents:settings`.
+
+All resource budgets are finite: `maxTurns`, `maxDurationSeconds`, `maxQueueWaitSeconds`, and `abortGraceSeconds` require positive integers; `wrapUpTurns` permits `0` and is clamped below `maxTurns`. A running invocation starts its duration clock at execution and includes workspace setup, session construction, model calls, and tools. Background queue wait is measured separately. On duration expiry or cancellation, the runtime signals cooperative abort; if the invocation remains unsettled once `abortGraceSeconds` passes, parent waiters and the concurrency slot are released. A same-process tool that ignores `AbortSignal` cannot be forcibly killed, and a cancelled record cannot resume until that prior invocation settles.
+
+**Failure behavior:** missing file is silent; malformed JSON logs a `[pi-subagents] Ignoring malformed settings at …` warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the `/subagents:settings` toast to a warning with `(session only; failed to persist)`.
+
+### Excluding package extensions from children
+
+Some package extensions are parent-scoped or expensive to initialize per session.
+Because children run in the parent's process, such an extension initializing once per child multiplies its cost in a single heap — enough, in the case that motivated this feature, to exhaust the V8 heap with four concurrent children.
+
+List the offending packages under `excludedExtensionPackages` to keep their extensions out of child sessions:
+
+```json
+{
+  "excludedExtensionPackages": ["npm:@cortexkit/pi-magic-context"]
+}
+```
+
+Entries must match Pi's configured package source string exactly, as it appears in your Pi `settings.json` `packages` array — there is no glob or prefix matching.
+
+What this does and does not do:
+
+- Only the matched packages' **extensions** are disabled, and only in children.
+  Their skills, prompts, and themes stay available to children.
+- The parent session is unaffected, as is the child's own settings — only the child's resource loading is filtered.
+- The exclusion happens during package resolution, so the extension's module is never imported and its factory never runs in the child.
+- Excluding a package keeps the **tools** that extension registers out of child sessions too: its factory never runs there, so an agent that names one of those tools in [`tools`](#tool-selection) gets nothing.
+  If you need the tools but want the extension's resources released when the child is disposed, exclusion is the wrong lever — see [Child session lifecycle](../README.md#child-session-lifecycle).
+
+This key is hand-edited in the shared global or project `subagents.json`; `/subagents:settings` does not expose it, but it is preserved when you change other runtime settings there. It is unrelated to personal `agentEnabled` overrides.
+An absent or empty list reproduces the default behavior, in which children inherit every parent extension.
+
+### Abort on interrupt
+
+By default, pressing ESC to interrupt the parent agent also aborts every subagent.
+Set `abortAllOnInterrupt` to `false` (or flip it from `/subagents:settings`) to keep background and queued subagents running when you interrupt the parent — useful when you spawn long background work and then want to steer the parent without losing it.
+
+A foreground agent aborts on ESC regardless of this setting.
+It holds the parent's own run signal for the duration of its blocking tool call, so the interrupt reaches it directly; the policy governs background and queued agents.
+
+The policy is read at the moment ESC fires, so flipping it mid-session applies to the very next interrupt.

package/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/docs/decisions/0002-extensions-on-a-minimal-core.md

@@ -0,0 +1,114 @@
+---
+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).
+
+## Amendment: prevent-load ships as a settings key, not a provider seam (#696)
+
+This decision reserved prevent-load as a *latent* provider seam, "added only if a real consumer needs it."
+A real consumer arrived: in-process children reloaded `@cortexkit/pi-magic-context`, whose per-session initialization scans the whole Pi session store, and four concurrent children exhausted the V8 heap in the shared process.
+
+The seam was nonetheless **not** built.
+The governing rule above — no vacant hooks — decides it: a provider seam is warranted when an *extension* must inject a value the core consumes, and no extension wants to supply a prevent-load policy.
+The only policy source is the operator's configuration, so a registerable provider whose sole consumer would be pi-subagents' own settings reader is precisely the speculative abstraction this ADR forbids.
+
+The core therefore reads an `excludedExtensionPackages` list from the layered `subagents.json` and filters the child's package view before resource loading.
+This is narrower than the per-agent policy Phase 14 evicted: it is global/project scope only, never per agent type; it names packages rather than individual extensions or tools; and it carries no tool-permission semantics, which remain deny-at-use in `@gotgenes/pi-permission-system`.
+Default inheritance is unchanged — an absent or empty list reproduces prior behavior exactly.
+
+Latent extensibility is preserved rather than spent.
+The filtering is applied at the composition root, so if a sandboxing extension ever needs to supply the policy generatively, a provider seam can be added additively without disturbing the settings key or the assembly factory.

package/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