@gotgenes/pi-subagents 13.2.0 → 13.2.2

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

package/docs/plans/0280-rename-agent-to-subagent.md

@@ -0,0 +1,197 @@
+---
+issue: 280
+issue_title: "Rename the internal Agent class to Subagent"
+---
+
+# Rename the internal `Agent` class to `Subagent`
+
+## Problem Statement
+
+The internal lifecycle class `Agent` (`src/lifecycle/agent.ts`) models a single spawned subagent, but the bare name `Agent` collides with two unrelated concepts in the same code: the parent Pi agent that invokes our tooling, and the SDK's `AgentSession` that each subagent wraps.
+The public API already standardized on the `Subagent*` family (`SubagentsService`, `SubagentRecord`, `SubagentStatus`, `SubagentType`, and — after [#265] — `SubagentSession` / `createSubagentSession`).
+The internal lifecycle layer is the lone holdout still using bare `Agent*`.
+Renaming the subagent-instance cluster closes that inconsistency and removes the parent/child/SDK ambiguity.
+
+## Goals
+
+- Rename the subagent-instance cluster in `src/lifecycle/` to the `Subagent*` family: `Agent` → `Subagent`, `AgentManager` → `SubagentManager`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`, `AgentManagerObserver` → `SubagentManagerObserver`, `AgentManagerOptions` → `SubagentManagerOptions`, `AgentObserverOptions` → `SubagentObserverOptions`, `AgentManagerLike` → `SubagentManagerLike`.
+- Consolidate the duplicate `AgentStatus` union into the existing public `SubagentStatus`, deleting the duplicate and re-pointing `WorkspaceDisposeOutcome.status`.
+- Rename the lifecycle module files to match their primary export: `agent.ts` → `subagent.ts`, `agent-manager.ts` → `subagent-manager.ts`, plus the matching test files and the `make-agent.ts` test helper.
+- Extend the rename to adjacent identifiers in the same cluster for full consistency: the `subscribeAgentObserver` function → `subscribeSubagentObserver`, the `SubagentManagerObserver` methods `onAgent*` → `onSubagent*`, and the `createTestAgent` helper → `createTestSubagent`.
+- Update residual bare `Agent` / `AgentManager` references in lifecycle comments, JSDoc, and error strings — the acceptance grep matches these, not just symbols.
+- Update `docs/architecture/architecture.md` to the new names.
+- This is internal-only and non-breaking — the exported surface is unchanged apart from `WorkspaceDisposeOutcome.status` reading `SubagentStatus` (an identical union), so commits use `refactor:`, never `feat!:`.
+
+## Non-Goals
+
+- The agent-type/config axis stays untouched: `AgentConfig`, `AgentType`, `AgentTypeRegistry`, `AgentConfigLookup`, `AgentInvocation`, `AgentPromptConfig`, `AgentCategories`.
+- The UI/tool surface stays untouched: `AgentTool` (+ `AgentTool*` variants), `AgentSpawnConfig`, `AgentWidget`, `AgentsMenuHandler`, `AgentActivityTracker`, `AgentDetails`, `AgentCreationWizard`, `AgentConfigEditor`, `AgentFileOps`.
+- SDK types stay untouched: `AgentSession`, `AgentSessionEvent`.
+- Internal field/method names that do not contain the bare `Agent` word — `listAgents`, `getRecord`, the `agents` map, and `record:` parameters — are left as-is; they are not bare-`Agent` symbols and the acceptance grep does not flag them.
+- No behavior changes: this is a pure rename plus a structurally no-op type consolidation.
+
+## Background
+
+Relevant modules (Lifecycle domain unless noted):
+
+- `src/lifecycle/agent.ts` — defines `Agent`, `AgentInit`, `AgentLifecycleObserver`, and the duplicate `AgentStatus` union; owns the full execution lifecycle (`run`, `resume`, `abort`, `steer`, status transitions, workspace disposal).
+  Contains bare-`Agent` JSDoc and two error strings (`"Agent not configured for execution …"`, `"Agent not configured for resume …"`).
+- `src/lifecycle/agent-manager.ts` — defines `AgentManager`, `AgentManagerObserver` (methods `onAgentStarted` / `onAgentCompleted` / `onAgentCompacted` / `onAgentCreated`), `AgentManagerOptions`, and `AgentSpawnConfig` (out of scope).
+- `src/lifecycle/workspace.ts` — `WorkspaceDisposeOutcome.status` is typed as the internal `AgentStatus`, imported from `#src/lifecycle/agent`.
+- `src/observation/record-observer.ts` — defines `AgentObserverOptions` and the `subscribeAgentObserver` function.
+- `src/service/service.ts` — defines the public `SubagentStatus` union (verbatim duplicate of `AgentStatus`) and re-exports `LifetimeUsage`, `Workspace`, and the four workspace collaborator types from the lifecycle layer.
+- `src/service/service-adapter.ts` — defines the `AgentManagerLike` test seam.
+- `src/types.ts` — barrel that re-exports `Agent` from `#src/lifecycle/agent`; most consumers import `Agent` via this barrel.
+- `test/helpers/make-agent.ts` — exports `createTestAgent`, imported by ~16 test files.
+
+Blast radius is mechanical but wide (~360 occurrences, dominated by the `Agent` class via the `types.ts` barrel).
+`typescript` + `tsserver` are available, so each rename is a scope-aware language-service pass verified by `pnpm run check`; the occurrence count does not drive scope.
+
+Constraints from AGENTS.md and skills that apply:
+
+- Within a package, import siblings via `#src/` / `#test/` aliases (eslint enforces this) — the file moves must preserve alias imports, not introduce relative paths.
+- After a barrel rename, verify at least one consumer still imports the renamed symbol from the barrel — many consumers import `Subagent` from `#src/types`, so this holds.
+- The public `dist/public.d.ts` bundle is rolled from `src/service/service.ts`; run `pnpm run verify:public-types` after touching the public surface or the status consolidation.
+- Load the `mermaid` skill before editing the architecture doc's class/sequence diagrams.
+
+## Design Overview
+
+### Status consolidation and the layering constraint
+
+`AgentStatus` (in `agent.ts`) and `SubagentStatus` (in `service.ts`) are identical seven-member unions (`queued | running | completed | steered | aborted | stopped | error`).
+The issue asks `WorkspaceDisposeOutcome.status` to point at the public `SubagentStatus`.
+
+A naive fix — importing `SubagentStatus` from `service.ts` into `workspace.ts` — would create a circular dependency: `service.ts` already imports the workspace collaborator types (`WorkspaceDisposeOutcome`, …) from `workspace.ts`, so `workspace.ts → service.ts` reverses an existing arrow.
+The correct single home is the lifecycle layer, mirroring how `service.ts` already re-exports `LifetimeUsage` from `#src/lifecycle/usage` and the workspace types from `#src/lifecycle/workspace`:
+
+- Keep the union defined in the lifecycle layer (in the renamed `subagent.ts`), renamed `AgentStatus` → `SubagentStatus`.
+- `service.ts` deletes its local definition and adds `export type { SubagentStatus } from "#src/lifecycle/subagent";` alongside its existing re-exports.
+- `workspace.ts` imports `SubagentStatus` from `#src/lifecycle/subagent` (it already imports `AgentStatus` from the same module today — only the symbol name and, after the file move, the path change).
+
+The `subagent ↔ workspace` relationship is type-only and already exists (`subagent.ts` imports `Workspace` / `WorkspaceProvider` from `workspace.ts`; `workspace.ts` imports the status union from `subagent.ts`), so no new runtime cycle is introduced — type-only imports are erased.
+
+`rollup-plugin-dts` inlines `#src/*` types, so `dist/public.d.ts` still emits the same `SubagentStatus` union literal — structurally a no-op for consumers, confirmed by `verify:public-types`.
+
+```typescript
+// src/lifecycle/subagent.ts (renamed from agent.ts)
+export type SubagentStatus =
+  | "queued" | "running" | "completed" | "steered"
+  | "aborted" | "stopped" | "error";
+
+// src/service/service.ts — delete local def, re-export instead
+export type { SubagentStatus } from "#src/lifecycle/subagent";
+
+// src/lifecycle/workspace.ts
+import type { SubagentStatus } from "#src/lifecycle/subagent";
+export interface WorkspaceDisposeOutcome {
+  status: SubagentStatus;
+  description: string;
+}
+```
+
+### Rename mechanics
+
+Each symbol rename is an atomic, scope-aware language-service operation (the API behind LSP "Rename Symbol"); after each, `pnpm run check` verifies the tree compiles.
+Because a rename updates every reference in one pass and leaves the build green, each logical rename is its own commit with the repository in a valid state — no lift-and-shift staging is required (a rename is not a type replacement; old and new names never coexist).
+
+Symbol renames do not touch comments, JSDoc, or string literals.
+There are 26 bare `Agent` and 4 bare `AgentManager` word-occurrences in `src/lifecycle/` comments/strings (e.g. the two `"Agent not configured …"` error messages and cross-file JSDoc in `turn-limits.ts`, `create-subagent-session.ts`, `subagent-session.ts`).
+The acceptance criterion greps `src/lifecycle/` for bare `Agent` / `AgentManager`, so each rename step must also sweep residual comment/string occurrences.
+Compound names (`AgentSession`, `AgentInvocation`, `AgentTypeRegistry`) are not bare-word matches and stay.
+
+### Full-consistency adjacent identifiers
+
+Per the scope decision, the rename extends to the rest of the cluster's naming so no `Agent`-as-subagent identifier survives:
+
+- `src/observation/record-observer.ts`: `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions`.
+- `src/lifecycle/subagent-manager.ts`: `SubagentManagerObserver` methods `onAgentStarted` / `onAgentCompleted` / `onAgentCompacted` / `onAgentCreated` → `onSubagentStarted` / `onSubagentCompleted` / `onSubagentCompacted` / `onSubagentCreated` (8 + 11 + 6 + 14 call sites across `src/` and `test/`, all updated by the language-service rename).
+- `test/helpers/make-agent.ts`: `createTestAgent` → `createTestSubagent`, file → `make-subagent.ts` (~16 importers, including `make-deps.ts` and `ui-stubs.ts`).
+
+## Module-Level Changes
+
+Renamed files (git move, preserving `#src/` / `#test/` alias imports):
+
+- `src/lifecycle/agent.ts` → `src/lifecycle/subagent.ts`
+- `src/lifecycle/agent-manager.ts` → `src/lifecycle/subagent-manager.ts`
+- `test/lifecycle/agent.test.ts` → `test/lifecycle/subagent.test.ts`
+- `test/lifecycle/agent-manager.test.ts` → `test/lifecycle/subagent-manager.test.ts`
+- `test/helpers/make-agent.ts` → `test/helpers/make-subagent.ts`
+- `test/helpers/make-agent.test.ts` → `test/helpers/make-subagent.test.ts`
+
+Changed (symbols, members, imports, comments/strings):
+
+- `src/lifecycle/subagent.ts` — `Agent` → `Subagent`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`, `AgentStatus` → `SubagentStatus` (kept here as the single home); update JSDoc and the two error strings.
+- `src/lifecycle/subagent-manager.ts` — `AgentManager` → `SubagentManager`, `AgentManagerObserver` → `SubagentManagerObserver` (+ `onAgent*` methods → `onSubagent*`), `AgentManagerOptions` → `SubagentManagerOptions`; `AgentSpawnConfig` unchanged; update header comment.
+- `src/lifecycle/workspace.ts` — import `SubagentStatus` from `#src/lifecycle/subagent`; `WorkspaceDisposeOutcome.status` retyped.
+- `src/service/service.ts` — delete local `SubagentStatus` definition; add `export type { SubagentStatus } from "#src/lifecycle/subagent";`.
+- `src/service/service-adapter.ts` — `AgentManagerLike` → `SubagentManagerLike`; update header comment referencing `AgentManager`.
+- `src/observation/record-observer.ts` — `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions`; update header comment.
+- `src/types.ts` — barrel re-export `export { Agent } from "#src/lifecycle/agent";` → `export { Subagent } from "#src/lifecycle/subagent";`.
+- All consumers of the renamed symbols across `src/` and `test/` (tools, UI, runtime, `index.ts`, session, observation, and their tests) — updated transitively by each language-service rename.
+  Out-of-scope `Agent*` symbols in these files are untouched.
+- `test/helpers/make-subagent.ts`, `make-deps.ts`, `ui-stubs.ts`, and ~16 test importers — `createTestAgent` → `createTestSubagent` and updated import paths.
+- `docs/architecture/architecture.md` — file-listing entries (`agent.ts`, `agent-manager.ts`), class/sequence Mermaid diagrams, the type-complexity table row (`AgentInit` → `SubagentInit`, module `agent` → `subagent`), and current-state prose naming the renamed cluster.
+  Out-of-scope `Agent*` names (`AgentTool`, `AgentSession`, `AgentTypeRegistry`, …) and historical phase narrative stay as written.
+
+No exports are removed from the public surface; the barrel rename swaps one name for another with many live consumers.
+Also swept for the `package-pi-subagents` SKILL.md, which documents internals (`AgentManager`, `Agent`, `make-agent`): update its dependency-flow sketch and module table to the new names.
+
+## Test Impact Analysis
+
+This is a pure rename plus a no-op type consolidation, so the extraction-style test questions resolve simply:
+
+1. New tests enabled: none — no new seams or behavior are introduced.
+2. Tests made redundant: none — no test is duplicated or subsumed.
+3. Tests that must stay as-is (renamed/retargeted only): all of them.
+   `test/lifecycle/subagent.test.ts`, `subagent-manager.test.ts`, `record-observer.test.ts`, `service-adapter.test.ts`, and every `createTestSubagent` consumer continue to exercise the same behavior under the new names.
+   The status consolidation leaves `WorkspaceDisposeOutcome` behavior identical, so workspace/service tests are unchanged beyond the symbol name.
+
+## TDD Order
+
+This is a refactor with no red phase; each step is a green checkpoint verified by `pnpm run check` && `pnpm -r run test` (and `verify:public-types` where the public surface is touched) before committing.
+Steps are independent renames ordered smallest-blast-first where practical; any order keeps the tree green.
+
+1. Consolidate the status union.
+   In `agent.ts` rename `AgentStatus` → `SubagentStatus` and keep the definition there; delete the duplicate in `service.ts` and re-export from the lifecycle module; retype `workspace.ts`.
+   Run `pnpm run check`, tests, and `pnpm run verify:public-types` to confirm the bundle is unchanged.
+   Commit: `refactor: consolidate AgentStatus into public SubagentStatus (#280)`.
+2. Rename the `Agent` class cluster.
+   `Agent` → `Subagent`, `AgentInit` → `SubagentInit`, `AgentLifecycleObserver` → `SubagentLifecycleObserver`; git-move `agent.ts` → `subagent.ts` and `test/lifecycle/agent.test.ts` → `subagent.test.ts`; update the `types.ts` barrel re-export and the `workspace.ts` / `service.ts` import paths to `#src/lifecycle/subagent`; sweep residual bare-`Agent` JSDoc and the two error strings in `subagent.ts`.
+   Commit: `refactor: rename Agent class to Subagent (#280)`.
+3. Rename the manager cluster.
+   `AgentManager` → `SubagentManager`, `AgentManagerObserver` → `SubagentManagerObserver` (+ `onAgent*` methods → `onSubagent*`), `AgentManagerOptions` → `SubagentManagerOptions`; git-move `agent-manager.ts` → `subagent-manager.ts` and its test file; sweep residual bare-`AgentManager` comments.
+   `AgentSpawnConfig` left untouched.
+   Commit: `refactor: rename AgentManager cluster to SubagentManager (#280)`.
+4. Rename the observation seam.
+   `subscribeAgentObserver` → `subscribeSubagentObserver`, `AgentObserverOptions` → `SubagentObserverOptions` in `record-observer.ts`; update its test and header comment.
+   Commit: `refactor: rename subscribeAgentObserver to subscribeSubagentObserver (#280)`.
+5. Rename the adapter seam.
+   `AgentManagerLike` → `SubagentManagerLike` in `service-adapter.ts`; update its test and header comment.
+   Commit: `refactor: rename AgentManagerLike to SubagentManagerLike (#280)`.
+6. Rename the test helper.
+   `createTestAgent` → `createTestSubagent`; git-move `make-agent.ts` → `make-subagent.ts` and `make-agent.test.ts` → `make-subagent.test.ts`; update all importers and `#test/helpers/make-agent` paths.
+   Commit: `test: rename createTestAgent to createTestSubagent (#280)`.
+7. Update docs.
+   Architecture doc current-state references (file listing, Mermaid diagrams, complexity table, prose) and the `package-pi-subagents` SKILL.md internals; load the `mermaid` skill before editing diagrams.
+   Final verification: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fallow dead-code`, `pnpm run verify:public-types`, and `grep -rnE '\bAgent(Manager|Init)?\b' src/lifecycle/` returns no bare in-scope matches.
+   Commit: `docs: update architecture and skill docs for Subagent rename (#280)`.
+
+## Risks and Mitigations
+
+- Risk: a symbol rename misses string literals or comments, leaving bare `Agent` that the acceptance grep flags.
+  Mitigation: each rename step explicitly sweeps comments/strings; the final grep gate in step 7 is the backstop.
+- Risk: pointing `workspace.ts` at the public `SubagentStatus` introduces a `lifecycle → service` cycle.
+  Mitigation: keep the union's home in the lifecycle layer (`subagent.ts`) and re-export from `service.ts`, mirroring the existing `LifetimeUsage` / workspace re-export pattern — no new arrow.
+- Risk: the public type bundle changes shape.
+  Mitigation: `verify:public-types` after step 1 and step 7; the union is identical, so the bundle differs only in provenance, not content.
+- Risk: a file move accidentally rewrites `#src/` alias imports to relative paths.
+  Mitigation: use `git mv` and rely on the language service for import updates; eslint's no-relative-sibling rule catches regressions during `pnpm run lint`.
+- Risk: over-reach into out-of-scope `Agent*` names.
+  Mitigation: the rename is symbol-scoped (not text find-replace); the Non-Goals list enumerates the protected names, and the acceptance grep targets only bare `Agent` / `AgentManager` / `AgentInit` / `Agent*Observer`.
+
+## Open Questions
+
+- Whether to later lowercase incidental prose uses of "Agent" (meaning subagent) in the architecture doc's event tables and history sections — deferred; this plan updates symbol/file names and current-state references, leaving historical narrative as written.
+- Whether `listAgents` / `getRecord` / the `agents` map deserve a follow-up naming pass — deferred; they are not bare-`Agent` symbols and fall outside the approved scope.
+
+[#265]: https://github.com/gotgenes/pi-packages/issues/265

package/docs/retro/0051-update-adr-0001-hard-fork.md

@@ -3,13 +3,13 @@ issue: 51
 issue_title: "docs: update ADR 0001 to reflect hard-fork decision"
 ---
 
-# Retro: #51 — docs: update ADR 0001 to reflect hard-fork decision
+# Retro: #51 — docs: update ADR-0001 to reflect hard-fork decision
 
 ## Final Retrospective (2026-05-16)
 
 ### Session summary
 
-Updated ADR 0001 (`docs/decisions/0001-deferred-patches.md`) to reflect the hard-fork decision documented in `docs/architecture/architecture.md`.
+Updated [ADR-0001] to reflect the hard-fork decision documented in `docs/architecture/architecture.md`.
 The change was planned, implemented, shipped, and released as `pi-subagents-v1.0.2` in a single clean pass with no rework.
 
 ### Observations
@@ -35,3 +35,5 @@ The change was planned, implemented, shipped, and released as `pi-subagents-v1.0
 - The `package-pi-subagents` skill (`.pi/skills/package-pi-subagents/SKILL.md`) still frames the fork as "a friendly fork… carrying a small number of patches" with priorities like "stays as close to upstream as possible."
   This framing is now stale given the hard-fork commitment.
   A separate issue should update the skill to reflect the architecture document's posture.
+
+[ADR-0001]: ../decisions/0001-deferred-patches.md

package/docs/retro/0257-extract-child-session-factory.md

@@ -5,7 +5,7 @@ issue_title: "Extract ChildSessionFactory from runner"
 
 # Retro: #257 — Extract ChildSessionFactory from runner
 
-> Superseded — #257 closed `not_planned`; the work was reframed as Phase 16 "invert dependencies" (ADR 0002, issues #261–#265).
+> Superseded — #257 closed `not_planned`; the work was reframed as Phase 16 "invert dependencies" ([ADR-0002], issues #261–#265).
 
 ## Stage: Planning (2026-05-29T00:32:12Z)
 
@@ -29,3 +29,5 @@ The plan is a lift-and-shift: `runAgent()` keeps its `(snapshot, type, prompt, o
 - `RunResult.sessionFile` shifts from a late `sessionManager.getSessionFile()` to the factory's `outputFile` — same value (stable after `newSession()`); the existing `/sessions/child.jsonl` assertion is the guard.
 - Did not invoke `ask_user`: the issue's "Proposed change" is prescriptive, and the two deviations are forced/justified rather than open-ended.
 - IO interfaces (`RunnerIO`, `RunnerDeps`, etc.) intentionally stay in `agent-runner.ts` for this step to minimize churn; their relocation to the factory module is flagged as an Open Question for Step 4 when the runner dissolves.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md

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

@@ -9,7 +9,7 @@ issue_title: "Add WorkspaceProvider extension seam"
 
 ### Session summary
 
-Produced a numbered implementation plan for the Phase 16, Step 2 `WorkspaceProvider` seam (ADR 0002).
+Produced a numbered implementation plan for the Phase 16, Step 2 `WorkspaceProvider` seam ([ADR-0002]).
 The plan adds the seam additively — `WorkspaceProvider` / `Workspace` interfaces, `SubagentsService.registerWorkspaceProvider`, run-start consultation, and `dispose` with a verbatim `resultAddendum` — while leaving the existing `isolation: "worktree"` path untouched for #263 to evict.
 Three TDD steps (two `feat`, one `docs`).
 
@@ -85,3 +85,5 @@ Across all stages the plan's risk predictions held and TDD verification was incr
 
 1. `AGENTS.md` (Pre-completion reviewer subsection) — added a one-line guardrail: agent `model:` frontmatter must use the `provider/id` alias form the Pi CLI/UI accepts, because an ID absent from the model registry silently falls back to the parent session model.
 2. `packages/pi-subagents/docs/retro/0262-add-workspace-provider-seam.md` — this Final Retrospective stage entry.
+
+[ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md