@gotgenes/pi-subagents 12.1.0 → 13.1.0

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

@@ -0,0 +1,275 @@
+---
+issue: 264
+issue_title: "Remove isolated / extensions:false / noSkills from core"
+---
+
+# Remove the extension-lifecycle-control axis from the 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.
+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.
+
+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.
+
+## Goals
+
+- Remove `isolated` from the spawn API, `SubagentsService`, the lifecycle plumbing, and the config assembler.
+- Remove the `extensions` boolean from `AgentConfig` and the assembler (children always inherit extensions).
+- 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.
+- 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.
+  `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.
+
+## 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`.
+  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)`.
+  `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`.
+
+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).
+- One-sentence-per-line markdown; sequential numbering restarting per heading.
+
+## Design Overview
+
+This is a **symmetric collapse**, not a refactor.
+Two parallel axes leave the core together:
+
+| Axis       | Today                                                          | After                                         |
+| ---------- | -------------------------------------------------------------- | --------------------------------------------- |
+| Extensions | `extensions: true \| false`; `isolated` forces `false`         | always inherit (field gone)                   |
+| 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.
+
+### Assembler after collapse
+
+`assembleSessionConfig` loses the `isolated` branch, the `preloadSkills` block, and the `noSkills`/`extensions`/`extras` outputs:
+
+```typescript
+export interface AssemblerOptions {
+  cwd?: string;
+  model?: unknown;
+  thinkingLevel?: ThinkingLevel;
+  // isolated removed
+}
+
+export interface SessionConfig {
+  effectiveCwd: string;
+  systemPrompt: string;
+  toolNames: string[];
+  model: unknown;
+  thinkingLevel: ThinkingLevel | undefined;
+  agentMaxTurns: number | undefined;
+  // extensions, noSkills, extras removed
+}
+```
+
+`AssemblerIO` drops `preloadSkills`, keeping only `buildAgentPrompt` (now called without `extras`).
+
+### Runner after collapse
+
+The resource-loader call drops the two suppression flags, and the guard runs unconditionally:
+
+```typescript
+const loader = deps.io.createResourceLoader({
+  cwd: cfg.effectiveCwd,
+  agentDir,
+  noPromptTemplates: true,
+  noThemes: true,
+  noContextFiles: true,
+  systemPromptOverride: () => cfg.systemPrompt,
+  appendSystemPromptOverride: () => [],
+  // noExtensions, noSkills removed
+});
+// ...
+await session.bindExtensions({});
+// 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").
+
+### 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`.
+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.
+
+### Edge cases
+
+- Append-mode agents: `parentSystemPrompt` still embeds parent context via `systemPromptOverride`; nothing about that path depends on skills/extensions flags.
+- Custom agents with legacy `extensions:` / `skills:` / `isolated:` frontmatter: the keys are silently ignored after this change (no parse, no warning).
+  `resolveBoolExtensions` already warned on the deprecated allowlist syntax; that warning path is removed with the parser.
+- The absolute-fallback `AgentConfig` in `agent-types.ts` drops `extensions`/`skills` like every other construction site.
+
+## 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.
+
+### 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`.
+
+### Docs
+
+- `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).
+
+## Test Impact Analysis
+
+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 —
+   `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) —
+   prompt assembly (`prompts.test.ts`, minus `extras`);
+   model resolution in `session-config.test.ts`;
+   the post-bind guard ordering tests (adjusted, not removed);
+   custom-agent `tools:` parsing (`csvList` survives).
+
+## TDD Order
+
+Each cycle ends green (`pnpm run check` + `pnpm -r run test`).
+Because removing a field from `AgentConfig` / `AgentInvocation` breaks every reader and every object-literal construction site at once (TS excess-property + property-access), each cycle folds its test updates into the same commit (per the testing skill's removal rule).
+The three axes are split so each commit stays reviewable and leaves the repo compiling.
+
+1. Remove the `isolated` axis end-to-end.
+   Surface: `types.ts` (`AgentConfig.isolated`, `AgentInvocation.isolated`), `invocation-config.ts`, `custom-agents.ts` (parse only), `session-config.ts` (`AssemblerOptions.isolated` + derivation), `agent-runner.ts` (`RunOptions.isolated`), `agent.ts`, `agent-manager.ts`, `tools/*`, `service*.ts`, `ui/*` (isolated bits), plus all listed tests.
+   After: `extensions`/`skills`/`noSkills` still function; the assembler reads `agentConfig.extensions`/`agentConfig.skills` directly.
+   Commit: `feat!: remove isolated from the subagent spawn API and lifecycle (#264)`.
+2. Remove the `extensions` axis; make the recursion guard unconditional.
+   Surface: `types.ts` (`AgentConfig.extensions`), `default-agents.ts`, `agent-types.ts` (fallback), `custom-agents.ts` (parse + delete `resolveBoolExtensions`), `session-config.ts` (`SessionConfig.extensions`), `agent-runner.ts` (`ResourceLoaderOptions.noExtensions`, drop `noExtensions` arg, unconditional guard), `ui/agent-config-editor.ts` + `ui/agent-creation-wizard.ts` (extensions bits), plus tests (including the guard-always-runs update and deleting the "skips filter" case).
+   Commit: `feat!: always inherit extensions; make the recursion guard unconditional (#264)`.
+3. Remove the `skills` axis, `noSkills`, and the skill-preload path.
+   Surface: `types.ts` (`AgentConfig.skills`), `default-agents.ts`, `agent-types.ts` (fallback), `custom-agents.ts` (parse + delete `inheritField`), `session-config.ts` (`AssemblerIO.preloadSkills`, `SessionConfig.noSkills`/`extras`, preload block, `buildAgentPrompt` call), `prompts.ts` (`PromptExtras`/`extras`/`extrasSuffix`), delete `skill-loader.ts` + `safe-fs.ts`, `agent-runner.ts` (`ResourceLoaderOptions.noSkills`, drop arg), `index.ts` (wiring), `ui/*` (skills bits), plus tests (delete `skill-loader.test.ts` + `safe-fs.test.ts`).
+   Commit: `feat!: always inherit skills; remove noSkills and the skill-preload path (#264)`.
+4. Update the architecture doc and package skill.
+   Surface: `docs/architecture/architecture.md` (Mermaid session subgraph, directory tree, `SpawnOptions`/`RunOptions` field lists, roadmap status), `.pi/skills/package-pi-subagents/SKILL.md` (session domain row).
+   Commit: `docs: record removal of the extension-lifecycle-control axis (#264)`.
+
+## Risks and Mitigations
+
+- Risk: `resolveBoolExtensions` / `inheritField` deletion removes a helper still used elsewhere.
+  Mitigation: greps confirm `resolveBoolExtensions` is used only by the removed `extensions` parse, and `inheritField` only by `extensions`/`skills`; `csvList`/`parseCsvField` (used by `tools:`) stay.
+- 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.
+  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.
+- Risk: a test file is touched in multiple cycles (e.g. `runner-io.ts`).
+  Mitigation: each cycle removes only the field it owns; ordering is fixed (isolated → extensions → skills) so no cycle leaves a dangling reference.
+
+## Open Questions
+
+- 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.

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

@@ -0,0 +1,330 @@
+---
+issue: 265
+issue_title: "Born-complete child execution; dissolve the runner"
+---
+
+# Born-complete `SubagentSession`; dissolve the runner
+
+## Problem Statement
+
+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.
+
+Child-session creation should instead produce a *born-complete* value object — a `SubagentSession` that wraps one SDK `AgentSession` plus its turn-driving and teardown — and the runner concept should dissolve.
+`Agent.run()` becomes coordination, not assembly.
+
+This step also closes the determinism gap deferred from #261: today `session-created`/`disposed` bracket only the first turn loop ("executing now"), so a resume — a *second* turn loop on the same session — fires no events and the permission system falls back to its filesystem-path heuristic.
+Moving unregistration to true session disposal shifts the registry from "executing now" to "exists", and resume executions become registry-detected for free.
+
+## Goals
+
+- Introduce a born-complete `SubagentSession` (`{ session, outputFile?, dispose() }` plus turn-driving behavior) produced by a `createSubagentSession()` factory.
+- `Agent` owns session interaction directly: it tells `SubagentSession` to run/resume turn loops, steer, and dispose — no injected runner.
+- Dissolve the runner: remove `runAgent`, `resumeAgent`, `ConcreteAgentRunner`, `AgentRunner`, `RunOptions`, `RunResult`, `ResumeOptions`.
+- Retain `getAgentConversation()` and `normalizeMaxTurns()` by relocating them to focused homes.
+- Move child-session registration to creation and unregistration to true session disposal, so resume executions are registry-detected (the `disposed` event fires at cleanup, not at run-completion).
+- No two-phase `setup()` / late-bound `cwd`: the factory receives a resolved `cwd` value and builds a session that is fully usable the moment it is returned.
+
+This is an internal structural refactor.
+The public `SubagentsService` surface (`spawn`, `resume`, `steer`, `registerWorkspaceProvider`) is unchanged, so the change is **non-breaking** for consumers — no `feat!:`.
+The one externally observable change is positive: the permission registry now detects resume executions.
+
+## Non-Goals
+
+- Renaming the `Agent` class to `Subagent` — deferred to its own follow-up issue (mechanical, ~19 files, orthogonal to this structural change).
+  In this issue the class stays `Agent`; only the new object is named `SubagentSession` (consistent with the existing `SubagentType` / `SubagentSessionDir` naming family).
+- Retiring the remaining `agent.session` reach-throughs (steer tool/service buffer-or-deliver, conversation viewing, resume-readiness guards) — tracked in #277.
+  `SubagentSession` exposes a `.session` accessor so the existing observer wiring and consumers keep working unchanged; #277 retires those.
+- A resume-aware workspace lifecycle (re-establishing a worktree before a resume).
+  A worktree's natural lifetime is one turn loop, not the session; worktree + resume is already degenerate today and stays so.
+  See Open Questions.
+- UI extraction (Phase 17).
+
+## Background
+
+Relevant modules:
+
+- `src/lifecycle/agent-runner.ts` — the runner being dissolved.
+  `runAgent()` does assembly + turn loop + result collection + lifecycle events; `resumeAgent()` re-prompts an existing session; `ConcreteAgentRunner` wraps both behind the `AgentRunner` interface injected into `AgentManager`.
+  Also currently the home of the retained `getAgentConversation()` and `normalizeMaxTurns()`, plus the SDK-bridge IO interfaces (`EnvironmentIO`, `SessionFactoryIO`, `RunnerIO`, `ResourceLoaderOptions`, `CreateSessionOptions`) and the recursion guard `filterActiveTools()`.
+- `src/lifecycle/agent.ts` — `Agent` holds `runner`, `execution: ExecutionState`, workspace prepare/dispose, status transitions, steer buffering, and `run()`/`resume()`.
+- `src/lifecycle/execution-state.ts` — `ExecutionState { session, outputFile }`, attached to `Agent` on session creation.
+  Subsumed by `SubagentSession`.
+- `src/lifecycle/agent-manager.ts` — constructs `Agent`s with the injected `runner`; disposes sessions in `removeRecord`/`dispose`/`cleanup`.
+- `src/lifecycle/child-lifecycle.ts` — the `ChildLifecyclePublisher` (`spawning`, `sessionCreated`, `completed`, `disposed`).
+  Unchanged here; only *when* `disposed` fires moves.
+- `src/lifecycle/workspace.ts` — the abstract `WorkspaceProvider`/`Workspace` seam.
+  The core has zero git/worktree knowledge; all worktree mechanics live in `@gotgenes/pi-subagents-worktrees`, untouched by this issue.
+- `src/session/session-config.ts` — `assembleSessionConfig()`, the pure assembler `runAgent()` calls.
+  Unchanged; the factory calls it instead.
+
+Registry semantics (the determinism gap): The permission system (`pi-permission-system/src/subagent-lifecycle-events.ts`) registers on `subagents:child:session-created` and unregisters on `subagents:child:disposed`, keyed by `sessionDir`.
+That subscription code does **not** change.
+Today `disposed` fires in `runAgent`'s `finally` (end of the first turn loop), so the registry entry is gone before any resume.
+After this change `disposed` fires when the session is truly disposed (`AgentManager` cleanup / session switch / shutdown), so the entry spans the session's whole existence — every turn loop, including resumes.
+
+The two-lifetimes fact (why Option A): A workspace's natural lifetime is **one turn loop** (the run): the `WorkspaceProvider`'s `dispose()` returns a `resultAddendum` that is folded into the run's result, so it must be called at run-completion.
+A session's lifetime spans **many turn loops** (run + resumes) and ends at cleanup.
+Different clocks ⇒ different resources.
+The workspace therefore stays a separate `Agent`-sequenced resource (prepare at run-start, dispose at run-completion, exactly as today); only the session becomes the born-complete object.
+
+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.
+  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.
+
+## Design Overview
+
+Two new lifecycle modules replace the runner.
+
+### `SubagentSession` — the born-complete object (owns runtime behavior)
+
+```typescript
+/** Outcome of one turn loop. */
+export interface TurnLoopResult {
+  responseText: string;
+  aborted: boolean; // hard-aborted (max turns + grace exceeded)
+  steered: boolean; // soft-limit steer fired, finished in time
+}
+
+export interface TurnLoopOptions {
+  maxTurns?: number;
+  graceTurns?: number;
+  signal?: AbortSignal;
+}
+
+/**
+ * One child AgentSession plus its turn-driving and teardown — born complete.
+ * Construction (createSubagentSession) yields a fully usable instance: the
+ * session exists, extensions are bound, the recursion guard is applied.
+ */
+export class SubagentSession {
+  constructor(
+    private readonly _session: AgentSession,
+    private readonly meta: {
+      outputFile: string | undefined;
+      sessionDir: string;
+      agentName: string;
+      lifecycle: ChildLifecyclePublisher;
+    },
+  ) {}
+
+  /** Wrapped session — exposed for observer wiring + consumers; retired by #277. */
+  get session(): AgentSession { return this._session; }
+  get outputFile(): string | undefined { return this.meta.outputFile; }
+
+  /** Drive the initial run's turn loop; emits `completed` on success. */
+  runTurnLoop(prompt: string, opts: TurnLoopOptions): Promise<TurnLoopResult>;
+
+  /** Re-prompt the same session (resume); does not emit `completed`. */
+  resumeTurnLoop(prompt: string, signal?: AbortSignal): Promise<string>;
+
+  /** Deliver a steer to the live session. */
+  steer(message: string): Promise<void>;
+
+  /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
+  dispose(): void;
+}
+```
+
+`runTurnLoop` / `resumeTurnLoop` absorb the turn-counting, soft/hard-limit steer+abort, abort-signal forwarding, and response-text collection currently inside `runAgent`/`resumeAgent`, plus the private helpers `collectResponseText`, `getLastAssistantText`, `forwardAbortSignal`.
+Placing them on `SubagentSession` (the object that owns the `AgentSession`) — rather than reaching through `subagentSession.session` from `Agent` — keeps the design free of the Law-of-Demeter violation that an inline-on-`Agent` or free-function approach would introduce.
+
+### `createSubagentSession` — the assembly factory
+
+```typescript
+export interface SubagentSessionDeps { // (was RunnerDeps)
+  io: SubagentSessionIO;               // EnvironmentIO & SessionFactoryIO (moved verbatim)
+  exec: ShellExec;
+  registry: AgentConfigLookup;
+  lifecycle: ChildLifecyclePublisher;
+}
+
+export interface CreateSubagentSessionParams {
+  snapshot: ParentSnapshot;
+  type: SubagentType;
+  cwd?: string;                  // resolved workspace cwd; undefined → parent cwd
+  parentSession?: ParentSessionInfo;
+  model?: Model<any>;
+  thinkingLevel?: ThinkingLevel;
+}
+
+export function createSubagentSession(
+  params: CreateSubagentSessionParams,
+  deps: SubagentSessionDeps,
+): Promise<SubagentSession>;
+```
+
+Body (the assembly portion of `runAgent`, unchanged in substance):
+
+1. `lifecycle.spawning(...)`.
+2. `detectEnv(exec, cwd ?? snapshot.cwd)` → `assembleSessionConfig(...)`.
+3. `createResourceLoader` → `reload()`; `createSessionManager` → `newSession(...)`; `createSession(...)`.
+4. Construct `SubagentSession` (session, outputFile, sessionDir, agentName, lifecycle).
+5. `lifecycle.sessionCreated({ sessionDir, agentName, parentSessionId })` — synchronous, before `bindExtensions()` (the pre-bind ordering the permission registry depends on).
+6. `try { await session.bindExtensions({}); applyRecursionGuard(session); } catch (err) { subagentSession.dispose(); throw err; }` — if binding fails *after* `sessionCreated`, dispose (emit `disposed` + `session.dispose()`) before rethrowing, so registration is never leaked.
+7. Return the `SubagentSession`.
+
+Note the factory takes a resolved `cwd` value, never the `WorkspaceProvider`.
+The provider stays inside `Agent` (Option A): threading the provider + its prepare-context through the factory just to call `prepare()` would be a parameter-relay smell; `cwd` is a value the factory consumes directly (`detectEnv`, `assembleSessionConfig`, `createSession`).
+
+### Lifecycle-event ownership
+
+| Event             | Emitted by                    | When                                                            |
+| ----------------- | ----------------------------- | --------------------------------------------------------------- |
+| `spawning`        | `createSubagentSession`       | run start, before session creation                              |
+| `session-created` | `createSubagentSession`       | after creation, before `bindExtensions()`                       |
+| `completed`       | `SubagentSession.runTurnLoop` | end of the run's turn loop (success path)                       |
+| `disposed`        | `SubagentSession.dispose`     | true session disposal (cleanup) — **moved** from run-completion |
+
+`resume` neither creates a session nor emits `completed`/`disposed` — it re-prompts the live session, preserving today's behavior.
+
+### `Agent.run()` — coordination, not assembly (consumer call-site sketch)
+
+```typescript
+async run(): Promise<void> {
+  this.markRunning(Date.now());
+  this.observer?.onStarted?.(this);
+  this.wireSignal(this._signal, () => this.abort());
+
+  let cwd: string | undefined;
+  try {                                            // workspace prepare — unchanged
+    const provider = this._getWorkspaceProvider?.();
+    if (provider) { this._workspace = await provider.prepare({ ... }); cwd = this._workspace?.cwd; }
+  } catch (err) { this.markError(err); this.releaseListeners(); this.observer?.onRunFinished?.(this); return; }
+
+  try {
+    this.subagentSession = await this._createSubagentSession({
+      snapshot: this._snapshot!, type: this.type, cwd,
+      parentSession: this._parentSession, model: this._model, thinkingLevel: this._thinkingLevel,
+    });
+  } catch (err) { this.failRun(err); return; }     // factory already disposed its own session
+
+  this.flushPendingSteers();                        // → this.subagentSession.steer(msg)
+  this.attachObserver(subscribeAgentObserver(this.subagentSession.session, this, { ... }));
+  this.observer?.onSessionCreated?.(this, this.subagentSession.session);
+
+  try {
+    const result = await this.subagentSession.runTurnLoop(this._prompt!, {
+      maxTurns: this._maxTurns, graceTurns: cfg?.graceTurns, signal: this.abortController.signal,
+      // (maxTurns resolution stays: per-call ?? agentMaxTurns ?? defaultMaxTurns, via normalizeMaxTurns)
+    });
+    this.completeRun(result);                       // workspace teardown + status; no execution rebuild
+  } catch (err) { this.failRun(err); }
+}
+```
+
+`Agent.resume()` becomes `await this.subagentSession!.resumeTurnLoop(prompt, signal)` wrapped in the existing reset/observer/markCompleted/markError/releaseListeners scaffolding — no runner.
+
+`completeRun(result: TurnLoopResult)` drops the `session`/`sessionFile` fields (the `SubagentSession` already holds them) and no longer rebuilds `execution`; it does workspace teardown (folding `resultAddendum`) and the status transition, exactly as today.
+
+`Agent.execution: ExecutionState` becomes `Agent.subagentSession?: SubagentSession`; the `session` / `outputFile` getters delegate to it.
+A new `Agent.disposeSession()` calls `this.subagentSession?.dispose()`, invoked by `AgentManager` where `record.session?.dispose?.()` is called today.
+
+The `subscribeAgentObserver(subagentSession.session, ...)` wiring and `observer.onSessionCreated(agent, session)` still pass the raw `AgentSession`; these are the observer reach-throughs explicitly deferred to #277.
+The `Agent.session` getter likewise still exposes the wrapped session for the external consumers (steer tool, get-result, menu) that #277 retires.
+
+### Edge cases
+
+- Creation failure after `session-created`: the factory disposes (emit `disposed` + `session.dispose()`) before rethrowing → no registry leak; symmetric with the success path.
+- Turn-loop throw: `SubagentSession` exists and stays registered; `Agent.failRun` runs (workspace teardown + error status); `disposed` fires later at cleanup — symmetric register/unregister regardless of run success or failure.
+- Graceful abort (max turns + grace): `runTurnLoop` returns `{ aborted: true }` and emits `completed` (matching today); a *thrown* error skips `completed`.
+
+## Module-Level Changes
+
+New:
+
+- `src/lifecycle/subagent-session.ts` — `SubagentSession` class, `TurnLoopResult`, `TurnLoopOptions`, and the private turn-loop helpers (`collectResponseText`, `getLastAssistantText`, `forwardAbortSignal`).
+- `src/lifecycle/create-subagent-session.ts` — `createSubagentSession`, `SubagentSessionDeps`, `CreateSubagentSessionParams`, the SDK-bridge IO interfaces moved from `agent-runner.ts` (`EnvironmentIO`, `SessionFactoryIO`, `SubagentSessionIO`, `ResourceLoaderLike`, `SessionManagerLike`, `ResourceLoaderOptions`, `CreateSessionOptions`), and the recursion guard `applyRecursionGuard`/`filterActiveTools` + `EXCLUDED_TOOL_NAMES`.
+- `src/lifecycle/turn-limits.ts` — `normalizeMaxTurns`.
+- `src/session/conversation.ts` — `getAgentConversation` + `formatAttribution`.
+
+Changed:
+
+- `src/lifecycle/agent.ts` — drop `runner`/`AgentRunner`/`RunResult`/`ExecutionState`; add injected `createSubagentSession` factory dep; `execution` → `subagentSession`; rewrite `run()`/`resume()`; `completeRun(result: TurnLoopResult)`; add `disposeSession()`; `flushPendingSteers()` delegates to `subagentSession.steer`; update the "missing runner" guard messages.
+- `src/lifecycle/agent-manager.ts` — `AgentManagerOptions.runner: AgentRunner` → `createSubagentSession: (params) => Promise<SubagentSession>`; pass it into each `Agent`; `removeRecord`/`dispose` call `record.disposeSession()` instead of `record.session?.dispose?.()`.
+- `src/index.ts` — drop `ConcreteAgentRunner`/`RunnerDeps`; build `SubagentSessionDeps`; pass `createSubagentSession: (p) => createSubagentSession(p, deps)` to `AgentManager`.
+- `src/tools/get-result-tool.ts` — import `getAgentConversation` from `#src/session/conversation`.
+- `src/tools/spawn-config.ts` — import `normalizeMaxTurns` from `#src/lifecycle/turn-limits`.
+- `src/settings.ts` — update the `normalizeMaxTurns()` doc-comment reference.
+- `src/runtime.ts` — update the `RunConfig` doc comment that mentions `RunOptions`.
+- `src/session/session-config.ts` — update doc comments referencing `runAgent()` → `createSubagentSession()`.
+- `docs/architecture/architecture.md` — update the domain dependency diagram (drop `agent-runner` node, add `SubagentSession`/`createSubagentSession`), the execution-flow sequence diagram, the current-layout listing (lifecycle dir), the dependency-bag inventory rows (`RunOptions`, `RunnerIO`, `CreateSessionOptions`, `ResourceLoaderOptions` now belong to the factory module), and mark Step 5 delivered.
+- `.pi/skills/package-pi-subagents/SKILL.md` — the "Lifecycle domain" table lists `agent-runner.ts`; update to the new modules.
+
+Removed (final step):
+
+- `src/lifecycle/agent-runner.ts` — `runAgent`, `resumeAgent`, `ConcreteAgentRunner`, `AgentRunner`, `RunOptions`, `RunResult`, `ResumeOptions`, `RunContext`, `RunnerDeps`, `RunnerIO` (all migrated or deleted).
+- `src/lifecycle/execution-state.ts` — `ExecutionState` (subsumed by `SubagentSession`).
+
+Symbol-removal sweep (grep before finalizing each removal step): `runAgent`, `resumeAgent`, `ConcreteAgentRunner`, `AgentRunner`, `RunResult`, `RunOptions`, `ResumeOptions`, `RunContext`, `RunnerDeps`, `RunnerIO`, `ExecutionState`, `execution-state`, `agent-runner`.
+
+## Test Impact Analysis
+
+New unit tests the extraction enables:
+
+- `SubagentSession` in isolation — construct with a mock `AgentSession` and a `ChildLifecyclePublisher` mock; assert `runTurnLoop` turn-limit behavior (soft steer, hard abort, grace window), response capture, `completed` emission, `resumeTurnLoop` re-prompt, `steer` delegation, and `dispose` (session.dispose + `disposed`).
+  Previously these lived as `runAgent`/`resumeAgent` tests entangled with assembly.
+- `createSubagentSession` — assembly + `spawning`/`session-created` ordering + dispose-on-creation-failure, with no turn-loop noise.
+
+Tests that become redundant / simplified:
+
+- `test/lifecycle/concrete-agent-runner.test.ts` — deleted; `ConcreteAgentRunner` is gone, its delegation coverage absorbed by the factory + `SubagentSession` tests.
+- `Agent.run()` tests no longer re-drive turn events through a mock runner; they assert coordination against a stub `SubagentSession` whose `runTurnLoop` resolves to a canned `TurnLoopResult`.
+
+Tests that must stay (genuinely exercise the layer):
+
+- The turn-limit behavior tests (now retargeted from the runner to `SubagentSession.runTurnLoop`).
+- The recursion-guard / extension-tool filtering tests (now `createSubagentSession`).
+- The child-lifecycle ordering tests (now split across the factory and `SubagentSession`).
+- The workspace prepare/dispose tests in `agent.test.ts` — unchanged (Option A leaves that path intact); only assertions that read `runner.run`'s args switch to reading the `createSubagentSession` factory params.
+
+## TDD Order
+
+Lift-and-shift: introduce the new modules alongside the runner, swap consumers atomically, delete the runner last.
+Each step compiles and the suite passes; run `pnpm run check` after every step that touches a shared interface.
+
+1. Extract `normalizeMaxTurns` → `src/lifecycle/turn-limits.ts`; update `agent-runner.ts` (internal use), `spawn-config.ts`, and the `settings.ts` comment; move `agent-runner-settings.test.ts` → `turn-limits.test.ts`.
+   Commit `refactor: extract normalizeMaxTurns to turn-limits`.
+2. Extract `getAgentConversation` → `src/session/conversation.ts`; update `get-result-tool.ts` import and `test/agent-conversation.test.ts` import.
+   Commit `refactor: extract getAgentConversation to session/conversation`.
+3. Add `SubagentSession` (`src/lifecycle/subagent-session.ts`) with `runTurnLoop`/`resumeTurnLoop`/`steer`/`dispose` + the turn-loop helpers (copied from `agent-runner.ts`; the originals are deleted in step 6 — transient duplication).
+   New `test/lifecycle/subagent-session.test.ts` (turn limits, response capture, `completed`/`disposed` emission, resume) — retargeted from the runner's turn-limit + final-output tests.
+   Commit `feat: add SubagentSession with turn-loop and disposal behavior`.
+4. Add `createSubagentSession` (`src/lifecycle/create-subagent-session.ts`) + `SubagentSessionDeps`/`CreateSubagentSessionParams` + the IO interfaces (moved; re-export from `agent-runner.ts` if still needed there, else copied) + the recursion guard.
+   New `test/lifecycle/create-subagent-session.test.ts` and `create-subagent-session-extension-tools.test.ts` — from the runner's assembly, `spawning`/`session-created` ordering, and recursion-guard tests, plus a dispose-on-creation-failure test.
+   Commit `feat: add createSubagentSession factory`.
+5. Swap `Agent` + `AgentManager` + `index.ts` to the factory/`SubagentSession`; drop `runner` from `AgentInit`/`AgentManagerOptions`/`index`; `execution` → `subagentSession`; add `disposeSession()`; `disposed` now fires at cleanup.
+   This is the atomic call-site swap (the `runner` dep is type-coupled across `Agent` ↔ `AgentManager` ↔ `index`), so it lands with its test updates in one commit: `agent.test.ts` (run/resume/completeRun/workspace/disposeSession sections), `agent-manager.test.ts` (`createManager` helper + the dispose-on-cleanup test), `test/helpers/manager-stubs.ts` (runner stubs → factory stubs), `test/print-mode.test.ts` (mock `createSubagentSession` instead of `runAgent`).
+   These are localized edits to large files, not full rewrites — the bulk of `agent.test.ts`/`agent-manager.test.ts` (status transitions, getters, queue) is untouched.
+   Commit `feat: dissolve the runner; Agent drives SubagentSession directly`.
+6. Delete `agent-runner.ts`, `execution-state.ts`, and `concrete-agent-runner.test.ts`; rename `test/helpers/runner-io.ts` → `subagent-session-io.ts` (and its factory functions); update `session-config.ts` / `runtime.ts` doc comments; run the symbol-removal grep sweep.
+   Commit `refactor: remove agent-runner and ExecutionState`.
+7. Update `docs/architecture/architecture.md` (diagrams, layout, bag inventory, mark Step 5 delivered) and the `package-pi-subagents` skill's lifecycle-domain table.
+   Commit `docs: record runner dissolution and SubagentSession (#265)`.
+
+## Risks and Mitigations
+
+- **Registry entry persists longer (cross-package behavior).**
+  `disposed` now fires at session disposal, so permission-registry entries live from creation to cleanup.
+  Mitigation: `AgentManager.dispose()` (session_shutdown) disposes every `SubagentSession`, firing `disposed` for each; the permission system's subscription is unchanged.
+  Verify with `pnpm -r run test` (the permission system mocks the bus, so no timing coupling).
+- **Transient duplication (steps 3–5).**
+  The turn-loop helpers and assembly exist in both `agent-runner.ts` and the new modules until step 6.
+  Mitigation: deleted in step 6; fallow runs at pre-completion against the final state.
+- **Large-file test edits in step 5.**
+  Mitigation: edits are confined to the run/resume/dispose describe blocks and the `createManager` helper; the new turn-limit/assembly coverage already lives in steps 3–4's dedicated files, so step 5 only adapts coordination assertions.
+- **`disposed` not fired on a path that disposes the raw session directly.**
+  Mitigation: grep for every `session?.dispose` / `.dispose()` on a session in `agent-manager.ts` and route all of them through `record.disposeSession()`.
+
+## Open Questions
+
+- Resume-aware workspaces: should a resumed worktree agent re-establish (or reattach) a workspace before the next `session.prompt()`?
+  Today it runs in the removed worktree directory (degenerate).
+  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.