@gotgenes/pi-subagents 13.2.1 → 14.0.0

package/docs/plans/0262-add-workspace-provider-seam.md

@@ -7,50 +7,50 @@ issue_title: "Add WorkspaceProvider extension seam"
 
 ## Problem Statement
 
-Phase 16, Step 2 of ADR 0002 (`packages/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md`).
-The core needs only a working directory and a disposal hook for a child run; the default — the parent's cwd, with no setup or teardown — is always correct.
+Phase 16, Step 2 of [ADR-0002].
+The core needs only a working directory and a disposal hook for a child run; the default - the parent's cwd, with no setup or teardown - is always correct.
 "Where does a child run, and what brackets the run?"
 is a *strategy* (git worktree, container, tmpdir, remote sandbox), not core behavior.
-ADR 0002 classifies this as the single *generative* extension surface: a concern that must return a value the core consumes synchronously attaches through a rationed provider seam, not an observational event.
-This issue adds that seam — `WorkspaceProvider` / `Workspace` plus `SubagentsService.registerWorkspaceProvider` — without the core gaining any knowledge of what an "isolation strategy" is.
+[ADR-0002] classifies this as the single *generative* extension surface: a concern that must return a value the core consumes synchronously attaches through a rationed provider seam, not an observational event.
+This issue adds that seam -`WorkspaceProvider` / `Workspace` plus `SubagentsService.registerWorkspaceProvider` - without the core gaining any knowledge of what an "isolation strategy" is.
 
 ## Goals
 
 - Define the `WorkspaceProvider` and `Workspace` interfaces in the core, with zero git or worktree knowledge.
-- Add `SubagentsService.registerWorkspaceProvider(provider): () => void` — a single-provider seam (chaining is out of scope) that throws if a provider is already registered and returns an unregister disposer.
-- At run-start, consult the registered provider for the child's cwd and a disposal handle; with no provider, the child runs in `baseCwd` (parent cwd — default behavior unchanged).
+- Add `SubagentsService.registerWorkspaceProvider(provider): () => void` - a single-provider seam (chaining is out of scope) that throws if a provider is already registered and returns an unregister disposer.
+- At run-start, consult the registered provider for the child's cwd and a disposal handle; with no provider, the child runs in `baseCwd` (parent cwd - default behavior unchanged).
 - Call `dispose()` after the run and append the returned `resultAddendum` to the child's result.
-- This change is **additive and non-breaking** — the existing `isolation: "worktree"` path is left intact (its eviction is #263).
+- This change is **additive and non-breaking** - the existing `isolation: "worktree"` path is left intact (its eviction is #263).
 
 ## Non-Goals
 
-- Removing `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, or the `isolation: "worktree"` spawn mode — deferred to #263.
-- Removing `isolated` / `extensions: false` / `noSkills` — deferred to #264.
-- Born-complete child execution / dissolving the runner — deferred to #265.
-- Multiple/chained providers — out of scope per the issue; one provider only.
-- Shipping a concrete provider implementation — the worktrees package (#263) is the seam's first real consumer.
+- Removing `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, or the `isolation: "worktree"` spawn mode - deferred to #263.
+- Removing `isolated` / `extensions: false` / `noSkills` - deferred to #264.
+- Born-complete child execution / dissolving the runner - deferred to #265.
+- Multiple/chained providers - out of scope per the issue; one provider only.
+- Shipping a concrete provider implementation - the worktrees package (#263) is the seam's first real consumer.
   Within this issue the seam is exercised only by test fakes; see Risks for the "no vacant hooks" release-coordination constraint.
 
 ## Background
 
 Relevant existing modules:
 
-- `src/lifecycle/agent.ts` — `Agent.run()` calls `this.worktree?.setup()` at run-start to obtain a cwd, threads it into `runner.run({ context: { cwd } })`, and on completion calls `this.worktree?.cleanup(description)`, appending a "Changes saved to branch …" addendum.
+- `src/lifecycle/agent.ts` - `Agent.run()` calls `this.worktree?.setup()` at run-start to obtain a cwd, threads it into `runner.run({ context: { cwd } })`, and on completion calls `this.worktree?.cleanup(description)`, appending a "Changes saved to branch ..." addendum.
   This is exactly the prepare/dispose shape the seam generalizes.
-- `src/lifecycle/worktree-isolation.ts` — `WorktreeIsolation` is the current run-scoped collaborator: `setup()` returns a path, `cleanup(description)` returns a `WorktreeCleanupResult`.
+- `src/lifecycle/worktree-isolation.ts` - `WorktreeIsolation` is the current run-scoped collaborator: `setup()` returns a path, `cleanup(description)` returns a `WorktreeCleanupResult`.
   The seam is its abstraction; #263 will reimplement it as a `WorkspaceProvider` in a separate package.
-- `src/lifecycle/agent-manager.ts` — constructs each `Agent`, owns the injected `WorktreeManager`, and threads `getRunConfig` as a getter.
+- `src/lifecycle/agent-manager.ts` - constructs each `Agent`, owns the injected `WorktreeManager`, and threads `getRunConfig` as a getter.
   The same getter pattern is reused for the workspace provider.
-- `src/service/service.ts` — the package's public API surface (`package.json` `exports` points at `./src/service.ts`).
+- `src/service/service.ts` - the package's public API surface (`package.json` `exports` points at `./src/service.ts`).
   `SubagentsService`, `SpawnOptions`, and `SubagentRecord` all live here; the seam types are re-exported here so the worktrees package can implement them.
-- `src/service/service-adapter.ts` — `SubagentsServiceAdapter implements SubagentsService`, wrapping the `AgentManagerLike` narrow interface.
-- `src/lifecycle/child-lifecycle.ts` — the *observational* lifecycle events from #261 (`spawning`, `session-created`, `completed`, `disposed`).
+- `src/service/service-adapter.ts` - `SubagentsServiceAdapter implements SubagentsService`, wrapping the `AgentManagerLike` narrow interface.
+- `src/lifecycle/child-lifecycle.ts` - the *observational* lifecycle events from #261 (`spawning`, `session-created`, `completed`, `disposed`).
   The provider seam is orthogonal: events tell consumers what happened; the provider returns a value the core consumes.
 
 AGENTS.md constraints that apply:
 
-- Pi SDK imports stay out of library modules — the seam interfaces and `AgentManager` accept the provider as a parameter; `index.ts` (the SDK edge) supplies `baseCwd: process.cwd()`.
-- Do not read `process.cwd()` inside library functions — `baseCwd` is injected into `AgentManager` from `index.ts`.
+- Pi SDK imports stay out of library modules - the seam interfaces and `AgentManager` accept the provider as a parameter; `index.ts` (the SDK edge) supplies `baseCwd: process.cwd()`.
+- Do not read `process.cwd()` inside library functions - `baseCwd` is injected into `AgentManager` from `index.ts`.
 - When adding a public API pattern, follow the established convention: the repo's registration/subscription convention is an unsubscribe **function** (`() => void`, as in `SubscribableSession.subscribe` and `pi.events.on`), not a `Symbol.dispose` `Disposable`.
   The seam therefore returns `() => void`; this is a deliberate divergence from the issue's literal `Disposable` to match the codebase convention.
 
@@ -97,10 +97,10 @@ export interface WorkspaceProvider {
 ```
 
 Note the addendum-formatting boundary: the core appends `resultAddendum` *verbatim*.
-The provider owns its own separator and wording (the worktrees package owns the "Changes saved to branch …" string in #263).
+The provider owns its own separator and wording (the worktrees package owns the "Changes saved to branch ..." string in #263).
 The core never formats branch text.
 
-### Registration — single provider, throw on duplicate
+### Registration - single provider, throw on duplicate
 
 `AgentManager` holds an optional provider and exposes registration:
 
@@ -130,7 +130,7 @@ The disposer clears the slot only if the same provider is still active, so a sta
 Provider-first precedence: when a provider supplies a workspace, the core routes cwd and dispose through it and skips the legacy worktree collaborator; with no provider it falls back to the existing worktree path; with neither it runs in `baseCwd` (cwd undefined → SDK uses the parent cwd).
 
 ```typescript
-// run() — replacing the worktree?.setup() block
+// run() - replacing the worktree?.setup() block
 let cwd: string | undefined;
 try {
   const provider = this._getWorkspaceProvider?.();
@@ -152,7 +152,7 @@ try {
   this.observer?.onRunFinished?.(this);
   return;
 }
-// … runner.run({ context: { cwd, parentSession }, … })
+// ... runner.run({ context: { cwd, parentSession }, ... })
 ```
 
 On completion (`completeRun`) the core computes the final status, then disposes:
@@ -165,7 +165,7 @@ if (this._workspace) {
   if (out?.resultAddendum) finalResult += out.resultAddendum;
 } else {
   const wt = this.worktree?.cleanup(this.description);
-  if (wt?.hasChanges && wt.branch) finalResult += `\n\n---\nChanges saved to branch \`${wt.branch}\`…`;
+  if (wt?.hasChanges && wt.branch) finalResult += `\n\n---\nChanges saved to branch \`${wt.branch}\`...`;
 }
 ```
 
@@ -197,7 +197,7 @@ Provider-first precedence means the two never silently conflict, and #263 collap
 | `src/lifecycle/agent-manager.ts`    | `AgentManagerOptions` gains required `baseCwd: string`. New `workspaceProvider` field, `registerWorkspaceProvider()` (throw on dup, unregister disposer). `spawn()` passes `baseCwd` and the `getWorkspaceProvider` getter into each `Agent`.                                                                                           |
 | `src/service/service.ts`            | Re-export the five seam types and `AgentStatus`. Add `registerWorkspaceProvider(provider: WorkspaceProvider): () => void` to the `SubagentsService` interface.                                                                                                                                                                          |
 | `src/service/service-adapter.ts`    | `AgentManagerLike` gains `registerWorkspaceProvider(provider): () => void`. `SubagentsServiceAdapter` implements the method, delegating to the manager.                                                                                                                                                                                 |
-| `src/index.ts`                      | Pass `baseCwd: process.cwd()` to the `new AgentManager({…})` construction (alongside the existing `GitWorktreeManager(process.cwd())`).                                                                                                                                                                                                 |
+| `src/index.ts`                      | Pass `baseCwd: process.cwd()` to the `new AgentManager({...})` construction (alongside the existing `GitWorktreeManager(process.cwd())`).                                                                                                                                                                                               |
 | `docs/architecture/architecture.md` | Mark Phase 16 Step 2 (#262) as landed in the roadmap; note the seam exists and `workspace.ts` is added to the lifecycle domain listing.                                                                                                                                                                                                 |
 
 No exports are removed or renamed, so no `src/`/`test/` removed-symbol grep is required.
@@ -206,8 +206,8 @@ No file in Module-Level Changes is also claimed as unchanged in Non-Goals (the w
 ### Grep checklist before finalizing
 
 - Objects typed as `SubagentsService` in tests: `test/service/service.test.ts` casts `{ spawn: () => "id" } as unknown as SubagentsService`, so adding an interface method does **not** break it (verified).
-- `new AgentManager(` call sites: `src/index.ts` (one) and `test/lifecycle/agent-manager.test.ts` `createManager` (one) — both updated for required `baseCwd` in the same step.
-- `AgentManagerLike` mocks in `test/service/service-adapter.test.ts` (`defaultManager`, inline `spawn:` stubs) — add `registerWorkspaceProvider` stub in the same step.
+- `new AgentManager(` call sites: `src/index.ts` (one) and `test/lifecycle/agent-manager.test.ts` `createManager` (one) - both updated for required `baseCwd` in the same step.
+- `AgentManagerLike` mocks in `test/service/service-adapter.test.ts` (`defaultManager`, inline `spawn:` stubs) - add `registerWorkspaceProvider` stub in the same step.
 
 ## Test Impact Analysis
 
@@ -216,36 +216,36 @@ This is an additive seam, so the work is dominated by *new* tests; little existi
 1. New unit tests the seam enables: provider registration (throw-on-duplicate, disposer-unregisters), run-start consultation (cwd from `prepare`, `resultAddendum` appended on dispose), `prepare` returns undefined → `baseCwd`, `prepare` rejects → `markError`, and adapter delegation.
    These were impossible before because there was no provider abstraction to substitute.
 2. Redundant existing tests: none.
-   The seam does not subsume worktree tests — they exercise the legacy path, which is preserved.
-3. Existing tests that must stay as-is: all `worktree.test.ts`, `worktree-isolation.test.ts`, and the AgentManager worktree-isolation tests (`calls worktrees.create` / `cleanup`) — they genuinely exercise the fallback path that remains in #262.
+   The seam does not subsume worktree tests - they exercise the legacy path, which is preserved.
+3. Existing tests that must stay as-is: all `worktree.test.ts`, `worktree-isolation.test.ts`, and the AgentManager worktree-isolation tests (`calls worktrees.create` / `cleanup`) - they genuinely exercise the fallback path that remains in #262.
    The Agent no-provider tests assert unchanged worktree behavior.
 
 ## TDD Order
 
-1. **Seam types + registration surface** — `feat`.
+1. **Seam types + registration surface** - `feat`.
    New `src/lifecycle/workspace.ts`; re-export seam types + `AgentStatus` from `service.ts`; add `registerWorkspaceProvider` to `SubagentsService`, `AgentManagerLike`, and `SubagentsServiceAdapter` (delegating); add required `baseCwd` + provider field + `registerWorkspaceProvider` (throw on dup, disposer) to `AgentManager`; update `index.ts` and the `createManager` test factory for `baseCwd`.
    Tests: `agent-manager.test.ts` registration (throws on second register; disposer clears only the active provider; getter returns the registered provider) and `service-adapter.test.ts` delegation.
-   This whole surface lands in one commit because the `SubagentsService` interface method forces the adapter to implement it and the required `baseCwd` forces both construction sites — splitting would not type-check.
+   This whole surface lands in one commit because the `SubagentsService` interface method forces the adapter to implement it and the required `baseCwd` forces both construction sites - splitting would not type-check.
    Suggested message: `feat: add WorkspaceProvider registration seam to subagents service`.
    Run `pnpm run check` immediately after (shared-interface change).
 
-2. **Run-start consumption + dispose** — `feat`.
+2. **Run-start consumption + dispose** - `feat`.
    `Agent`: `AgentInit` gains `baseCwd`/`getWorkspaceProvider`; new private fields; `run()` provider-first prepare; `completeRun`/`failRun` dispose + verbatim `resultAddendum`.
    `AgentManager.spawn` passes `baseCwd` and the `getWorkspaceProvider` getter (sole extra construction site, folded in).
-   Tests: `agent.test.ts` — provider `prepare` supplies cwd to the runner; `dispose` `resultAddendum` appended to the result; `prepare` undefined → cwd falls back to `baseCwd`; `prepare` rejects → `markError` + `onRunFinished`; no-provider path still uses the worktree collaborator (regression guard).
+   Tests: `agent.test.ts` - provider `prepare` supplies cwd to the runner; `dispose` `resultAddendum` appended to the result; `prepare` undefined → cwd falls back to `baseCwd`; `prepare` rejects → `markError` + `onRunFinished`; no-provider path still uses the worktree collaborator (regression guard).
    Suggested message: `feat: consult workspace provider for child cwd and disposal`.
    Run `pnpm run check` after (AgentInit change).
 
-3. **Architecture doc update** — `docs`.
+3. **Architecture doc update** - `docs`.
    Mark Phase 16 Step 2 (#262) landed in the roadmap; add `workspace.ts` to the lifecycle domain listing; cross-link the seam.
    Suggested message: `docs: record WorkspaceProvider seam in phase 16 roadmap`.
 
 ## Risks and Mitigations
 
 - **Vacant hook (the headline risk).**
-  ADR 0002's "no vacant hooks" rule says a provider seam with no consumer is a speculative abstraction that `fallow` flags as dead.
+  [ADR-0002]’s “no vacant hooks” rule says a provider seam with no consumer is a speculative abstraction that `fallow` flags as dead.
   Within #262 the seam is exercised only by test fakes.
-  Mitigation: land #262 **alongside** #263 (its first real consumer, `@gotgenes/pi-subagents-worktrees`) — do not cut a release that contains the seam without the worktrees package.
+  Mitigation: land #262 **alongside** #263 (its first real consumer, `@gotgenes/pi-subagents-worktrees`) - do not cut a release that contains the seam without the worktrees package.
   Track this as a release-coordination constraint; the architecture roadmap already pairs Steps 2 and 3.
 - **Dual cwd path confusion.**
   Provider-first precedence keeps worktree and provider from silently conflicting; the branch is documented and removed in #263.
@@ -257,6 +257,8 @@ This is an additive seam, so the work is dominated by *new* tests; little existi
 ## Open Questions
 
 - Should `baseCwd` eventually come from the parent `SessionContext.cwd` rather than `process.cwd()`?
-  Deferred — `process.cwd()` preserves current worktree behavior; revisit during the born-complete work (#265).
+  Deferred -`process.cwd()` preserves current worktree behavior; revisit during the born-complete work (#265).
 - Should the `disposed` lifecycle event (#261) and `Workspace.dispose` be reconciled into one teardown notion?
-  Deferred — they serve different surfaces (observational vs generative); revisit if #265 dissolves the runner.
+  Deferred - they serve different surfaces (observational vs generative); revisit if #265 dissolves the runner.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/plans/0264-remove-extension-lifecycle-control.md

@@ -7,13 +7,13 @@ issue_title: "Remove isolated / extensions:false / noSkills from core"
 
 ## Problem Statement
 
-The core still carries an extension-lifecycle-control axis — `isolated`, `extensions: false`, and `noSkills` — that lets a spawn blanket-disable a child's extensions and skills.
-Per ADR 0002, this is policy that does not belong in a minimal orchestrator.
+The core still carries an extension-lifecycle-control axis - `isolated`, `extensions: false`, and `noSkills` - that lets a spawn blanket-disable a child's extensions and skills.
+Per [ADR-0002], this is policy that does not belong in a minimal orchestrator.
 Deny-at-use (the in-child permission layer, shipped in Step 1 / #261) already covers what `isolated` pretended to do for tools.
-Prevent-load (refusing to bind an extension for true sandboxing) is genuinely generative and is deliberately left as a *latent, un-built* provider seam — we do not ship a vacant hook.
+Prevent-load (refusing to bind an extension for true sandboxing) is genuinely generative and is deliberately left as a *latent, un-built* provider seam - we do not ship a vacant hook.
 
 This is Phase 16, Step 4.
-With the axis gone, children always load the parent's extensions and skills, and the recursion guard — which currently gates on `cfg.extensions` — becomes unconditional.
+With the axis gone, children always load the parent's extensions and skills, and the recursion guard - which currently gates on `cfg.extensions` - becomes unconditional.
 
 ## Goals
 
@@ -22,47 +22,47 @@ With the axis gone, children always load the parent's extensions and skills, and
 - Remove `noSkills` from the assembler and the resource-loader options.
 - Collapse the skill-curation axis symmetrically: remove `AgentConfig.skills` and the skill-**preload** path (`skill-loader.ts`, `safe-fs.ts`, `preloadSkills`, `PromptExtras`, `extras.skillBlocks`).
   Children always load Pi's full skill system, exactly as `skills: true` does today.
-- Make the recursion guard unconditional — it always strips `subagent` / `get_subagent_result` / `steer_subagent` from children, keyed off the core's own tool names.
+- Make the recursion guard unconditional - it always strips `subagent` / `get_subagent_result` / `steer_subagent` from children, keyed off the core's own tool names.
 - This is a **breaking** change: the public `SpawnOptions.isolated` field and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are removed.
   Suggested commits use `feat!:`.
 
 ## Non-Goals
 
-- Born-complete child execution / dissolving the runner — that is Step 5 (#265) and depends on this step.
+- Born-complete child execution / dissolving the runner - that is Step 5 (#265) and depends on this step.
   `RunOptions`, `runAgent`, `ConcreteAgentRunner`, and `Agent.run()` survive this issue (with `isolated` removed from them).
-- Shipping a prevent-load provider seam — ADR 0002 leaves it latent until a real consumer needs it.
-- Changing `builtinToolNames` (the `tools:` frontmatter allowlist) — that is a separate, surviving concern.
-- Changing deny-at-use behavior in `@gotgenes/pi-permission-system` — already in place from #261.
+- Shipping a prevent-load provider seam — [ADR-0002] leaves it latent until a real consumer needs it.
+- Changing `builtinToolNames` (the `tools:` frontmatter allowlist) - that is a separate, surviving concern.
+- Changing deny-at-use behavior in `@gotgenes/pi-permission-system` - already in place from #261.
 
 ## Background
 
 Relevant modules and how they relate:
 
-- `src/types.ts` — declares `AgentConfig` (`extensions`, `skills`, `isolated`) and `AgentInvocation` (`isolated`).
-- `src/config/default-agents.ts` — the three embedded agents set `extensions: true`, `skills: true`.
-- `src/config/custom-agents.ts` — parses `extensions` / `skills` / `isolated` from `.md` frontmatter via `resolveBoolExtensions` and `inheritField`.
-- `src/config/invocation-config.ts` — merges `isolated` from agent config + tool params.
-- `src/config/agent-types.ts` — an absolute-fallback `AgentConfig` literal sets `extensions: true`, `skills: true`.
-- `src/session/session-config.ts` — `assembleSessionConfig` derives `extensions`/`skills` from `options.isolated`, calls `io.preloadSkills` when `skills` is `string[]`, and computes `noSkills`.
+- `src/types.ts` - declares `AgentConfig` (`extensions`, `skills`, `isolated`) and `AgentInvocation` (`isolated`).
+- `src/config/default-agents.ts` - the three embedded agents set `extensions: true`, `skills: true`.
+- `src/config/custom-agents.ts` - parses `extensions` / `skills` / `isolated` from `.md` frontmatter via `resolveBoolExtensions` and `inheritField`.
+- `src/config/invocation-config.ts` - merges `isolated` from agent config + tool params.
+- `src/config/agent-types.ts` - an absolute-fallback `AgentConfig` literal sets `extensions: true`, `skills: true`.
+- `src/session/session-config.ts` - `assembleSessionConfig` derives `extensions`/`skills` from `options.isolated`, calls `io.preloadSkills` when `skills` is `string[]`, and computes `noSkills`.
   Returns `SessionConfig.{ extensions, noSkills, extras }`.
-- `src/session/prompts.ts` — `buildAgentPrompt` injects `extras.skillBlocks` as `# Preloaded Skill:` sections; `PromptExtras` carries only `skillBlocks` (memory was removed in #185).
-- `src/session/skill-loader.ts` — `preloadSkills` reads named skill files from disk; consumes `safe-fs.ts`.
-- `src/session/safe-fs.ts` — symlink/path-traversal guards; **only consumer is `skill-loader.ts`**.
-- `src/lifecycle/agent-runner.ts` — `RunOptions.isolated` flows into the assembler; `createResourceLoader` is called with `noExtensions: !cfg.extensions` and `noSkills: cfg.noSkills`; the recursion guard runs only `if (cfg.extensions)`.
+- `src/session/prompts.ts` - `buildAgentPrompt` injects `extras.skillBlocks` as `# Preloaded Skill:` sections; `PromptExtras` carries only `skillBlocks` (memory was removed in #185).
+- `src/session/skill-loader.ts` - `preloadSkills` reads named skill files from disk; consumes `safe-fs.ts`.
+- `src/session/safe-fs.ts` - symlink/path-traversal guards; **only consumer is `skill-loader.ts`**.
+- `src/lifecycle/agent-runner.ts` - `RunOptions.isolated` flows into the assembler; `createResourceLoader` is called with `noExtensions: !cfg.extensions` and `noSkills: cfg.noSkills`; the recursion guard runs only `if (cfg.extensions)`.
   `ResourceLoaderOptions` (a local narrow interface, not the SDK type) declares `noExtensions?` / `noSkills?`.
-- `src/lifecycle/agent.ts` — `AgentInit.isolated`, the `_isolated` field, and `isolated:` in the `runner.run(...)` call.
-- `src/lifecycle/agent-manager.ts` — `AgentSpawnConfig.isolated` and its pass-through to `new Agent(...)`.
-- `src/tools/{agent-tool,spawn-config,foreground-runner,background-spawner}.ts` — tool schema `isolated`, `SpawnExecution.isolated`, and pass-through.
-- `src/service/{service,service-adapter}.ts` — public `SpawnOptions.isolated` and its pass-through to the manager.
-- `src/ui/{display,agent-config-editor,agent-creation-wizard}.ts` — `isolated` tag, eject-content emission, and generation-prompt template text.
-- `src/index.ts` — wires `preloadSkills` and `buildAgentPrompt` into `assemblerIO`.
+- `src/lifecycle/agent.ts` - `AgentInit.isolated`, the `_isolated` field, and `isolated:` in the `runner.run(...)` call.
+- `src/lifecycle/agent-manager.ts` - `AgentSpawnConfig.isolated` and its pass-through to `new Agent(...)`.
+- `src/tools/{agent-tool,spawn-config,foreground-runner,background-spawner}.ts` - tool schema `isolated`, `SpawnExecution.isolated`, and pass-through.
+- `src/service/{service,service-adapter}.ts` - public `SpawnOptions.isolated` and its pass-through to the manager.
+- `src/ui/{display,agent-config-editor,agent-creation-wizard}.ts` - `isolated` tag, eject-content emission, and generation-prompt template text.
+- `src/index.ts` - wires `preloadSkills` and `buildAgentPrompt` into `assemblerIO`.
 
 AGENTS.md constraints that apply:
 
 - Conventional Commits; breaking changes use `feat!:`.
 - Do not edit `CHANGELOG.md` (release-please owns it).
 - When removing an export, grep all `src/` and `test/` for the symbol before finalizing (done below).
-- When adding/removing a module, check `docs/architecture/` for layout listings and complexity tables that reference it (done below — Mermaid + tree + field tables).
+- When adding/removing a module, check `docs/architecture/` for layout listings and complexity tables that reference it (done below - Mermaid + tree + field tables).
 - One-sentence-per-line markdown; sequential numbering restarting per heading.
 
 ## Design Overview
@@ -76,8 +76,8 @@ Two parallel axes leave the core together:
 | Skills     | `skills: true \| string[] \| false`; `isolated` forces `false` | always inherit full skill system (field gone) |
 
 The `skills` field collapses for the same reason `extensions` does: `noSkills` is the single mechanism behind **both** restriction modes (`skills: false` → no skills; `skills: string[]` → only those, preloaded into the prompt with the SDK loader suppressed).
-Removing `noSkills` without removing `AgentConfig.skills` would leave a field that silently stops restricting — a `string[]` agent would get its baked-in skills *plus* the full system.
-ADR 0002 says children always load the parent's skills, which is exactly the `skills: true` path; the other two values are skill curation/policy and leave the core.
+Removing `noSkills` without removing `AgentConfig.skills` would leave a field that silently stops restricting - a `string[]` agent would get its baked-in skills *plus* the full system.
+[ADR-0002] says children always load the parent’s skills, which is exactly the `skills: true` path; the other two values are skill curation/policy and leave the core.
 
 ### Assembler after collapse
 
@@ -121,16 +121,16 @@ const loader = deps.io.createResourceLoader({
 });
 // ...
 await session.bindExtensions({});
-// Recursion guard — now unconditional (children always load extensions).
+// Recursion guard - now unconditional (children always load extensions).
 const filtered = filterActiveTools(session.getActiveToolNames());
 session.setActiveToolsByName(filtered);
 ```
 
-`ResourceLoaderOptions` drops `noExtensions?` / `noSkills?` (a local narrow interface — removing the latent fields keeps us honest per ADR 0002's "no vacant hooks").
+`ResourceLoaderOptions` drops `noExtensions?` / `noSkills?` (a local narrow interface - removing the latent fields keeps us honest per [ADR-0002]’s “no vacant hooks”).
 
-### Call-site sketch — recursion guard (Tell-Don't-Ask check)
+### Call-site sketch - recursion guard (Tell-Don't-Ask check)
 
-The guard already asks the session for its active tools and tells it the filtered set — unchanged except for removing the `if`.
+The guard already asks the session for its active tools and tells it the filtered set - unchanged except for removing the `if`.
 No new collaborator, no reach-through; the only structural change is that `cfg.extensions` is no longer consulted, so `SessionConfig` no longer needs to expose it.
 This is a narrowing of the assembler's output contract, which is the desired direction.
 
@@ -143,91 +143,91 @@ This is a narrowing of the assembler's output contract, which is the desired dir
 
 ## Module-Level Changes
 
-### Source — `isolated` axis
-
-- `src/types.ts` — remove `AgentConfig.isolated`, `AgentInvocation.isolated`.
-- `src/config/invocation-config.ts` — remove `isolated` from `AgentInvocationParams` and the return object.
-- `src/config/custom-agents.ts` — remove the `isolated:` frontmatter parse.
-- `src/session/session-config.ts` — remove `AssemblerOptions.isolated` and the `options.isolated ? false : ...` derivation (read `agentConfig.extensions`/`agentConfig.skills` directly, for now).
-- `src/lifecycle/agent-runner.ts` — remove `RunOptions.isolated` and the `isolated:` argument passed to `assembleSessionConfig`.
-- `src/lifecycle/agent.ts` — remove `AgentInit.isolated`, the `_isolated` field + constructor assignment, and `isolated:` in the `runner.run(...)` call.
-- `src/lifecycle/agent-manager.ts` — remove `AgentSpawnConfig.isolated` and its pass-through to `new Agent(...)`.
-- `src/tools/agent-tool.ts` — remove the `isolated` schema property.
-- `src/tools/spawn-config.ts` — remove `SpawnExecution.isolated`, the `const isolated = resolvedConfig.isolated`, `isolated` in `agentInvocation`, and `isolated` in the `execution` return.
-- `src/tools/foreground-runner.ts` / `src/tools/background-spawner.ts` — remove `isolated: execution.isolated`.
-- `src/service/service.ts` — remove `SpawnOptions.isolated`.
-- `src/service/service-adapter.ts` — remove `isolated: options?.isolated` from the `manager.spawn(...)` call.
-- `src/ui/display.ts` — remove `if (invocation.isolated) tags.push("isolated")` and the `isolated` mention in the JSDoc example.
-- `src/ui/agent-config-editor.ts` — remove the `isolated: true` line from `buildEjectContent`.
-- `src/ui/agent-creation-wizard.ts` — remove the `isolated:` template line and the "Set isolated: true …" guideline.
-
-### Source — `extensions` axis + unconditional guard
-
-- `src/types.ts` — remove `AgentConfig.extensions`.
-- `src/config/default-agents.ts` — remove `extensions: true` from all three agents.
-- `src/config/agent-types.ts` — remove `extensions: true` from the absolute-fallback literal.
-- `src/config/custom-agents.ts` — remove the `extensions:` frontmatter parse and delete `resolveBoolExtensions`.
-- `src/session/session-config.ts` — remove `SessionConfig.extensions` and stop assigning it.
-- `src/lifecycle/agent-runner.ts` — remove `ResourceLoaderOptions.noExtensions`, drop `noExtensions` from the `createResourceLoader` call, and make the recursion guard unconditional (delete `if (cfg.extensions)`); update the explanatory comment.
-- `src/ui/agent-config-editor.ts` — remove the `extensions: false` line from `buildEjectContent`.
-- `src/ui/agent-creation-wizard.ts` — remove the `extensions:` template line.
-
-### Source — `skills` axis + preload path
-
-- `src/types.ts` — remove `AgentConfig.skills`.
-- `src/config/default-agents.ts` — remove `skills: true` from all three agents.
-- `src/config/agent-types.ts` — remove `skills: true` from the absolute-fallback literal.
-- `src/config/custom-agents.ts` — remove the `skills:` frontmatter parse and delete `inheritField` (its only remaining callers are `skills`/`extensions`; `csvList`, `parseCsvField`, `str`, `nonNegativeInt` stay — `csvList` still serves `tools:`).
-- `src/session/session-config.ts` — remove `AssemblerIO.preloadSkills`, `SessionConfig.noSkills`, `SessionConfig.extras`, the `extras`/`preloadSkills` block, and the `extras` argument to `buildAgentPrompt`.
-- `src/session/prompts.ts` — remove `PromptExtras`, the `extras` parameter, and the `extrasSuffix` logic.
-- `src/session/skill-loader.ts` — **delete** (export `preloadSkills`, `PreloadedSkill`).
-- `src/session/safe-fs.ts` — **delete** (sole consumer was `skill-loader.ts`).
-- `src/lifecycle/agent-runner.ts` — remove `ResourceLoaderOptions.noSkills` and drop `noSkills` from the `createResourceLoader` call.
-- `src/index.ts` — remove the `preloadSkills` import and its `assemblerIO.preloadSkills` wiring.
-- `src/ui/agent-config-editor.ts` — remove the `skills: false` / `skills: <list>` lines from `buildEjectContent`.
-- `src/ui/agent-creation-wizard.ts` — remove the `skills:` template line.
+### Source - `isolated` axis
+
+- `src/types.ts` - remove `AgentConfig.isolated`, `AgentInvocation.isolated`.
+- `src/config/invocation-config.ts` - remove `isolated` from `AgentInvocationParams` and the return object.
+- `src/config/custom-agents.ts` - remove the `isolated:` frontmatter parse.
+- `src/session/session-config.ts` - remove `AssemblerOptions.isolated` and the `options.isolated ? false : ...` derivation (read `agentConfig.extensions`/`agentConfig.skills` directly, for now).
+- `src/lifecycle/agent-runner.ts` - remove `RunOptions.isolated` and the `isolated:` argument passed to `assembleSessionConfig`.
+- `src/lifecycle/agent.ts` - remove `AgentInit.isolated`, the `_isolated` field + constructor assignment, and `isolated:` in the `runner.run(...)` call.
+- `src/lifecycle/agent-manager.ts` - remove `AgentSpawnConfig.isolated` and its pass-through to `new Agent(...)`.
+- `src/tools/agent-tool.ts` - remove the `isolated` schema property.
+- `src/tools/spawn-config.ts` - remove `SpawnExecution.isolated`, the `const isolated = resolvedConfig.isolated`, `isolated` in `agentInvocation`, and `isolated` in the `execution` return.
+- `src/tools/foreground-runner.ts` / `src/tools/background-spawner.ts` - remove `isolated: execution.isolated`.
+- `src/service/service.ts` - remove `SpawnOptions.isolated`.
+- `src/service/service-adapter.ts` - remove `isolated: options?.isolated` from the `manager.spawn(...)` call.
+- `src/ui/display.ts` - remove `if (invocation.isolated) tags.push("isolated")` and the `isolated` mention in the JSDoc example.
+- `src/ui/agent-config-editor.ts` - remove the `isolated: true` line from `buildEjectContent`.
+- `src/ui/agent-creation-wizard.ts` - remove the `isolated:` template line and the "Set isolated: true ..." guideline.
+
+### Source - `extensions` axis + unconditional guard
+
+- `src/types.ts` - remove `AgentConfig.extensions`.
+- `src/config/default-agents.ts` - remove `extensions: true` from all three agents.
+- `src/config/agent-types.ts` - remove `extensions: true` from the absolute-fallback literal.
+- `src/config/custom-agents.ts` - remove the `extensions:` frontmatter parse and delete `resolveBoolExtensions`.
+- `src/session/session-config.ts` - remove `SessionConfig.extensions` and stop assigning it.
+- `src/lifecycle/agent-runner.ts` - remove `ResourceLoaderOptions.noExtensions`, drop `noExtensions` from the `createResourceLoader` call, and make the recursion guard unconditional (delete `if (cfg.extensions)`); update the explanatory comment.
+- `src/ui/agent-config-editor.ts` - remove the `extensions: false` line from `buildEjectContent`.
+- `src/ui/agent-creation-wizard.ts` - remove the `extensions:` template line.
+
+### Source - `skills` axis + preload path
+
+- `src/types.ts` - remove `AgentConfig.skills`.
+- `src/config/default-agents.ts` - remove `skills: true` from all three agents.
+- `src/config/agent-types.ts` - remove `skills: true` from the absolute-fallback literal.
+- `src/config/custom-agents.ts` - remove the `skills:` frontmatter parse and delete `inheritField` (its only remaining callers are `skills`/`extensions`; `csvList`, `parseCsvField`, `str`, `nonNegativeInt` stay - `csvList` still serves `tools:`).
+- `src/session/session-config.ts` - remove `AssemblerIO.preloadSkills`, `SessionConfig.noSkills`, `SessionConfig.extras`, the `extras`/`preloadSkills` block, and the `extras` argument to `buildAgentPrompt`.
+- `src/session/prompts.ts` - remove `PromptExtras`, the `extras` parameter, and the `extrasSuffix` logic.
+- `src/session/skill-loader.ts` - **delete** (export `preloadSkills`, `PreloadedSkill`).
+- `src/session/safe-fs.ts` - **delete** (sole consumer was `skill-loader.ts`).
+- `src/lifecycle/agent-runner.ts` - remove `ResourceLoaderOptions.noSkills` and drop `noSkills` from the `createResourceLoader` call.
+- `src/index.ts` - remove the `preloadSkills` import and its `assemblerIO.preloadSkills` wiring.
+- `src/ui/agent-config-editor.ts` - remove the `skills: false` / `skills: <list>` lines from `buildEjectContent`.
+- `src/ui/agent-creation-wizard.ts` - remove the `skills:` template line.
 
 ### Tests
 
-- `test/session/skill-loader.test.ts` — **delete**.
-- `test/session/safe-fs.test.ts` — **delete**.
-- `test/session/session-config.test.ts` — remove the `isolated`-mode `describe`, the `noSkills` assertions, and the preload tests; keep model-resolution and prompt-assembly assertions.
-- `test/session/prompts.test.ts` — remove `isolated`/`extensions`/`skills` from `AgentConfig` fixtures and any `skillBlocks`/`extras` cases.
-- `test/config/invocation-config.test.ts` — remove `isolated` cases and fixture fields.
-- `test/config/custom-agents.test.ts` — remove `extensions` / `skills` / `isolated` frontmatter-parsing tests.
-- `test/config/agent-types.test.ts` — remove `extensions` / `skills` / `isolated` from fixtures.
-- `test/lifecycle/agent-runner-extension-tools.test.ts` — remove `extensions`/`skills`/`isolated` from the mock config; delete the "extensions: false skips the filter entirely" test; keep/adjust the post-bind guard tests to assert the guard runs unconditionally.
-- `test/tools/spawn-config.test.ts` — remove the "sets isolated from params" test and `isolated` fixture fields.
-- `test/tools/background-spawner.test.ts` / `test/tools/foreground-runner.test.ts` — remove `isolated` from fixtures and `agentInvocation` assertions.
-- `test/tools/result-renderer.test.ts` — remove the `"isolated"` tag case.
-- `test/ui/agent-config-editor.test.ts` — remove the `isolated` / `extensions: false` eject-emission tests.
-- `test/display.test.ts` — remove `extensions`/`skills` from `AgentConfig` fixtures.
-- `test/helpers/runner-io.ts` — remove `extensions`/`skills`/`isolated` from `DEFAULT_AGENT_CONFIG`.
-- `test/helpers/runner-io.test.ts` — remove the `config.extensions`/`config.skills` assertions and the `extensions: true` override case.
-- `test/helpers/ui-stubs.ts` — remove `extensions: true` / `skills: true` from the stub `AgentConfig`.
+- `test/session/skill-loader.test.ts` - **delete**.
+- `test/session/safe-fs.test.ts` - **delete**.
+- `test/session/session-config.test.ts` - remove the `isolated`-mode `describe`, the `noSkills` assertions, and the preload tests; keep model-resolution and prompt-assembly assertions.
+- `test/session/prompts.test.ts` - remove `isolated`/`extensions`/`skills` from `AgentConfig` fixtures and any `skillBlocks`/`extras` cases.
+- `test/config/invocation-config.test.ts` - remove `isolated` cases and fixture fields.
+- `test/config/custom-agents.test.ts` - remove `extensions` / `skills` / `isolated` frontmatter-parsing tests.
+- `test/config/agent-types.test.ts` - remove `extensions` / `skills` / `isolated` from fixtures.
+- `test/lifecycle/agent-runner-extension-tools.test.ts` - remove `extensions`/`skills`/`isolated` from the mock config; delete the "extensions: false skips the filter entirely" test; keep/adjust the post-bind guard tests to assert the guard runs unconditionally.
+- `test/tools/spawn-config.test.ts` - remove the "sets isolated from params" test and `isolated` fixture fields.
+- `test/tools/background-spawner.test.ts` / `test/tools/foreground-runner.test.ts` - remove `isolated` from fixtures and `agentInvocation` assertions.
+- `test/tools/result-renderer.test.ts` - remove the `"isolated"` tag case.
+- `test/ui/agent-config-editor.test.ts` - remove the `isolated` / `extensions: false` eject-emission tests.
+- `test/display.test.ts` - remove `extensions`/`skills` from `AgentConfig` fixtures.
+- `test/helpers/runner-io.ts` - remove `extensions`/`skills`/`isolated` from `DEFAULT_AGENT_CONFIG`.
+- `test/helpers/runner-io.test.ts` - remove the `config.extensions`/`config.skills` assertions and the `extensions: true` override case.
+- `test/helpers/ui-stubs.ts` - remove `extensions: true` / `skills: true` from the stub `AgentConfig`.
 
 ### Docs
 
-- `docs/architecture/architecture.md` —
+- `docs/architecture/architecture.md` -
   remove the `SafeFs` and `SkillLoader` nodes from the session-domain Mermaid subgraph;
   remove `safe-fs.ts` and `skill-loader.ts` from the directory-tree listing;
   drop `isolated` from the `SpawnOptions` field list (≈ line 418) and the `RunOptions` field list (≈ line 651);
   mark Phase 16 Step 4 (#264) done in the roadmap and update the "Children always load the parent's extensions and skills" note;
   reflect the smaller session domain (8 → 6 modules).
-- `.pi/skills/package-pi-subagents/SKILL.md` — update the Session domain row (module count 8 → 6, drop `safe-fs.ts` / `skill-loader.ts` from the file list).
+- `.pi/skills/package-pi-subagents/SKILL.md` - update the Session domain row (module count 8 → 6, drop `safe-fs.ts` / `skill-loader.ts` from the file list).
 
 ## Test Impact Analysis
 
-1. New coverage enabled — minimal (this is a removal).
+1. New coverage enabled - minimal (this is a removal).
    The one behavioral assertion worth strengthening: the post-bind recursion guard now runs **unconditionally**.
    Update `agent-runner-extension-tools.test.ts` so a case that previously relied on `extensions: true` instead asserts the guard always calls `setActiveToolsByName` and always excludes `EXCLUDED_TOOL_NAMES`, with no config dependence.
-2. Tests that become redundant and are removed —
+2. Tests that become redundant and are removed -
    `skill-loader.test.ts` and `safe-fs.test.ts` (modules deleted);
    the `isolated`-mode `describe` in `session-config.test.ts`;
    the "extensions: false skips the filter entirely" case;
    `isolated` parameter tests in `spawn-config.test.ts` / `invocation-config.test.ts`;
    `extensions` / `skills` frontmatter-parsing tests in `custom-agents.test.ts`.
-3. Tests that must stay (genuinely exercise surviving layers) —
+3. Tests that must stay (genuinely exercise surviving layers) -
    prompt assembly (`prompts.test.ts`, minus `extras`);
    model resolution in `session-config.test.ts`;
    the post-bind guard ordering tests (adjusted, not removed);
@@ -260,7 +260,7 @@ The three axes are split so each commit stays reviewable and leaves the repo com
 - Risk: deleting `safe-fs.ts` orphans an import.
   Mitigation: grep confirms `skill-loader.ts` is its sole consumer; `safe-fs.test.ts` is deleted in the same cycle.
 - Risk: removing `SpawnOptions.isolated` breaks a published consumer of the service.
-  Mitigation: this is an intentional breaking change (ADR 0002); `feat!:` triggers a major bump via release-please.
+  Mitigation: this is an intentional breaking change ([ADR-0002]); `feat!:` triggers a major bump via release-please.
   The public type surface is verified by `pnpm run verify:public-types` after Step 3.
 - Risk: skill behavior silently changes for agents that relied on `skills: string[]` curation.
   Mitigation: documented in Goals as breaking; children now inherit the full skill system, which is strictly more capable, and deny-at-use governs what they may act on.
@@ -272,4 +272,6 @@ The three axes are split so each commit stays reviewable and leaves the repo com
 - Should custom-agent `.md` files with now-defunct `extensions:` / `skills:` / `isolated:` frontmatter emit a one-time deprecation warning, or be silently ignored?
   Deferred: silent-ignore matches the Phase 14 precedent for the removed `disallowed_tools` field; revisit only if users report confusion.
 - Does `verify:public-types` need a new negative assertion that `isolated` is absent from `SpawnOptions`?
-  Deferred to Step 3 implementation — the existing consumer type-check will fail if a stale field lingers.
+  Deferred to Step 3 implementation - the existing consumer type-check will fail if a stale field lingers.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

package/docs/plans/0265-born-complete-subagent-session.md

@@ -7,7 +7,7 @@ issue_title: "Born-complete child execution; dissolve the runner"
 
 ## Problem Statement
 
-Phase 16, Step 5 of ADR 0002.
+Phase 16, Step 5 of [ADR-0002].
 Today a subagent run is assembled by a monolithic `runAgent()` (the "runner") in `src/lifecycle/agent-runner.ts`: it creates the child session, binds extensions, drives the turn loop, collects the result, and emits the child-execution lifecycle events.
 `Agent` then sequences workspace teardown and status transitions around it through an injected `AgentRunner` interface.
 With the cwd now resolved through the `WorkspaceProvider` seam (Step 2) and worktrees evicted to a sibling package (Step 3), there is nothing left for a separate runner layer to assemble.
@@ -72,7 +72,7 @@ The workspace therefore stays a separate `Agent`-sequenced resource (prepare at
 
 AGENTS.md constraints that apply:
 
-- Ship-source package with a public type bundle (ADR 0003): none of the dissolved types (`RunOptions`, `RunResult`, `AgentRunner`) are part of `service.ts`, so `public.d.ts` is unaffected.
+- Ship-source package with a public type bundle ([ADR-0003]): none of the dissolved types (`RunOptions`, `RunResult`, `AgentRunner`) are part of `service.ts`, so `public.d.ts` is unaffected.
   Run `pnpm run verify:public-types` is **not** required (no public-surface change), but `pnpm run check` is.
 - fallow dead-code: new exports (`SubagentSession`, `createSubagentSession`) must have a production consumer by the end of the work; transient intermediate commits where they are consumed only by tests are acceptable because fallow runs at pre-completion, against the final state.
 - `#src/` path-alias imports only; ES2024 target.
@@ -328,3 +328,6 @@ Each step compiles and the suite passes; run `pnpm run check` after every step t
   This needs `WorkspaceProvider` support for resume and is out of scope; capture as a follow-up if it becomes a real need.
 - Whether `completed` should also fire on resume (it does not today).
   Deferred — preserve current behavior; revisit only with a concrete consumer.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md
+[ADR-0003]: ../decisions/0003-publish-bundled-type-declarations.md

package/docs/plans/0270-type-consumable-public-surface.md

@@ -57,7 +57,7 @@ Relevant modules and facts:
 Constraints from `AGENTS.md` and the package skill:
 
 - Ship-source model: every package ships raw `.ts` executed directly by Pi; there is no build step today.
-  ADR 0002 frames pi-subagents as a minimal core.
+  [ADR-0002] frames pi-subagents as a minimal core.
   Introducing the repo's **first build step** is a deliberate decision and warrants an ADR.
 - `eslint`'s `no-parent-relative-imports` rule forbids `../` imports inside `packages/*/src`; same-directory `./` is allowed.
   This (plus the deep type entanglement above) is why the alias-free-entry alternative was rejected.
@@ -200,3 +200,5 @@ This is a tooling/config change with a verification harness (not red→green→r
 - Whether to add a fast vitest self-containment assertion in addition to the shell harness, or keep the guard inside the script only — defer to the build stage.
 - Whether the ADR should add a short "build process" subsection to `docs/architecture/architecture.md` — defer; the ADR is sufficient.
 - Exact `files` allowlist entries — finalize against `pnpm pack --dry-run` in Step 2.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md