@gotgenes/pi-subagents 12.1.0 → 13.1.0

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

@@ -0,0 +1,89 @@
+---
+issue: 264
+issue_title: "Remove isolated / extensions:false / noSkills from core"
+---
+
+# Retro: #264 — Remove isolated / extensions:false / noSkills from core
+
+## Stage: Planning (2026-05-30T00:09:21Z)
+
+### Session summary
+
+Planned Phase 16, Step 4: removing the extension-lifecycle-control axis (`isolated`, `extensions: false`, `noSkills`) from the pi-subagents core per ADR 0002.
+Confirmed all three prerequisite Phase 16 steps (#261, #262, #263) are closed, so the explicit "deny-at-use" dependency is satisfied.
+Produced a four-cycle TDD plan (`isolated` → `extensions` → `skills`/`noSkills`/preload → docs) and committed it.
+
+### Observations
+
+- Scope expansion decided with the user: the issue names only `isolated` / `extensions: false` / `noSkills`, but `noSkills` is the single mechanism behind **both** skill-restriction modes (`skills: false` and `skills: string[]` preload).
+  Removing `noSkills` without also removing `AgentConfig.skills` would leave a field that silently stops restricting.
+  Chose the **collapse-skills-fully** option (symmetric with `extensions`): retire `AgentConfig.skills`, `skill-loader.ts`, `safe-fs.ts` (sole consumer was the skill loader), `preloadSkills`, `PromptExtras`, and `extras.skillBlocks`.
+  Children always inherit Pi's full skill system — the `skills: true` path.
+- The recursion guard's `if (cfg.extensions)` gate is removed in the `extensions` cycle (cycle 2), since `SessionConfig.extensions` disappears there.
+  A guard-always-runs assertion replaces the deleted "extensions: false skips the filter entirely" test.
+- This is a **breaking** change (`feat!:`): public `SpawnOptions.isolated` and the `isolated:` / `extensions:` / `skills:` custom-agent frontmatter keys are removed.
+  Custom agents with legacy frontmatter will silently ignore those keys (matches the Phase 14 precedent for `disallowed_tools`).
+- Sequencing note surfaced to the user: some `isolated`-threading removed here (`RunOptions.isolated`, `Agent.run()` plumbing) is structure that Step 5 (#265, dissolve the runner) will delete anyway — small, unavoidable, and #265 depends on this step, so no reordering benefit.
+- Helper-file churn accepted: `test/helpers/runner-io.ts` is touched in all three removal cycles (one field per cycle); ordering is fixed (`isolated` → `extensions` → `skills`) so no cycle leaves a dangling reference.
+- Doc updates identified: `docs/architecture/architecture.md` (Mermaid session subgraph, directory tree, `SpawnOptions`/`RunOptions` field lists, roadmap status) and the `package-pi-subagents` SKILL.md session-domain row (8 → 6 modules).
+
+## Stage: Implementation — TDD (2026-05-30T00:38:00Z)
+
+### Session summary
+
+Executed all four plan cycles (`isolated` → `extensions` + unconditional guard → `skills`/`noSkills`/preload → docs) as three `feat!:` commits plus one `docs:` commit.
+The extension-lifecycle-control axis and the `skills` curation axis are gone; children always inherit the parent's extensions and full skill system, and the recursion guard is unconditional.
+Test count went 1016 → 951 (−65): deleted `skill-loader.test.ts` and `safe-fs.test.ts`, plus removed isolated/extensions/skills/preload-specific cases; `check`, `lint`, `fallow dead-code`, and `verify:public-types` all green.
+
+### Observations
+
+- The plan's cycle split held up cleanly.
+  The only interleaving friction was `test/config/custom-agents.test.ts`, where `extensions` and `skills` assertions shared the same `it` blocks.
+  Handled it by retitling the shared tests to skills-only in cycle 2 (keeping skills compiling/passing), then deleting them in cycle 3 — no dangling references between commits.
+- BSD `sed` (macOS) does not support `\|` alternation in basic regex; the standalone-fixture-line deletions needed `sed -E`.
+  Worth remembering for future bulk fixture removals.
+- Two in-scope judgment calls beyond the literal plan: (1) kept the generic tag-rendering test in `result-renderer.test.ts` by swapping the example tag `"isolated"` → `"inherit context"` rather than deleting coverage; (2) removed the now-unused `vi` import from `custom-agents.test.ts` after dropping the extensions-deprecation-warning test.
+- The `spawn-config.test.ts` `agentInvocation` snapshot carried a stale `isolation: undefined` leftover (from the #263 worktree eviction) that `toEqual` had been silently ignoring; removed it alongside `isolated: false` for a clean exact-match assertion.
+- `verify:public-types` confirmed the breaking `SpawnOptions.isolated` removal type-checks against an external consumer; no lockfile changes; `dist/` correctly gitignored after the type-bundle build.
+- Pre-completion reviewer: **PASS** — both acceptance criteria code-verified, all deterministic checks green, 6 Mermaid diagrams render, docs accurate, zero dead code.
+
+## Stage: Final Retrospective (2026-05-30T01:13:26Z)
+
+### Session summary
+
+Shipped #264 end-to-end across three stages (Planning → TDD → Ship) in one conversation: planned the four-cycle removal, implemented it as three `feat!:` commits plus docs, and released `pi-subagents-v13.0.0` via the release-please PR (#276).
+The run had zero rework and a PASS pre-completion review; test count moved 1016 → 951.
+
+### Observations
+
+#### What went well
+
+- The planning-stage `ask-user` gate caught a real scope trap before any code was written.
+  The issue named three fields (`isolated`, `extensions: false`, `noSkills`), but `noSkills` turned out to be the single mechanism behind **two** skill-restriction modes (skill-disable and `skills: string[]` preload).
+  Removing it while keeping `AgentConfig.skills` would have left a field that silently stops restricting — a mid-cycle-3 wall.
+  Catching it at planning time expanded the clean scope to four collapsing fields and produced a symmetric, reviewable plan.
+- The four-cycle split (`isolated` → `extensions` + unconditional guard → `skills`/`noSkills`/preload → docs) held with no cross-cycle dangling references, validating the lift-and-shift discipline for shared-interface removal.
+- Verification ran incrementally (`pnpm run check` + `pnpm run test` after every cycle), so each commit landed green; the only end-of-run surprise was a pre-commit `end-of-file-fixer` hook touching `custom-agents.ts` (handled with a re-add, no rework).
+
+#### What caused friction (agent side)
+
+- `other` (tooling) — BSD `sed` on macOS does not support `\|` alternation in basic regex; the first bulk fixture-deletion attempt silently matched nothing.
+  Impact: one wasted tool call, no rework; resolved by switching to `sed -E`.
+
+#### What caused friction (user side)
+
+- The opening sequencing question ("is there work that should precede this") was first read literally as a prerequisite check (#261/#262/#263), and the user had to rephrase to get at the within-issue sequencing point that surfaced the `noSkills`/`skills` coupling.
+  Opportunity, not criticism: offering both readings of an ambiguous "what comes first" question up front would have reached the valuable discovery one turn sooner.
+
+#### Diagnostic details
+
+- **Model-performance correlation** — one subagent dispatch (`pre-completion-reviewer`, 325s, 43 tool uses) on a judgment-heavy review task; appropriate assignment.
+  No Explore/Plan subagents were needed — planning-stage exploration was direct file reads and targeted greps, efficient for this removal's scope.
+- **Escalation-delay tracking** — no rabbit-holes; the `sed` issue resolved in one retry.
+- **Feedback-loop gap analysis** — no gap; `check`/`test`/`lint` ran after each cycle, with `fallow dead-code` and `verify:public-types` at the end.
+
+### Changes made
+
+1. Appended this Final Retrospective stage entry to `packages/pi-subagents/docs/retro/0264-remove-extension-lifecycle-control.md`.
+2. Considered but **declined** (user: "too narrow") a removal-coupling detection rule for `.pi/prompts/plan-issue.md` — the heuristic that a field named for removal may be the mechanism behind a separate surviving feature.
+   No prompt or `AGENTS.md` changes were made this retro.

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

@@ -0,0 +1,58 @@
+---
+issue: 265
+issue_title: "Born-complete child execution; dissolve the runner"
+---
+
+# Retro: #265 — Born-complete child execution; dissolve the runner
+
+## Stage: Planning (2026-05-30T02:30:00Z)
+
+### Session summary
+
+Produced the implementation plan for dissolving the `agent-runner` and introducing a born-complete `SubagentSession`.
+Most of the session was a design dialogue that resolved naming, the turn-loop home, a discovered Law-of-Demeter cluster, and the workspace-ownership fork before any plan text was written.
+Plan committed as `0265-born-complete-subagent-session.md`; a side-quest filed #277 and added an architecture-doc breadcrumb for discovered debt.
+
+### Observations
+
+- Vocabulary was pinned down explicitly because "execution" is overloaded: granular execution = one turn loop (one `session.prompt()`, run or resume); the born-complete object spans the whole session lifetime (run + resumes).
+  The object is named `SubagentSession` (matches the existing `SubagentType` / `SubagentSessionDir` / `SubagentSessionRegistry` family; cohesive with the deferred `Agent` → `Subagent` rename).
+  Turn driving is `runTurnLoop` / `resumeTurnLoop`; resume is *not* an SDK `session.resume()` — it is `session.prompt()` again on the retained session.
+- The turn-loop home is **on `SubagentSession`** (methods), not inline on `Agent` and not a free function.
+  The user caught that `subagent.driveTurnLoop(subagentSession.session, …)` is a Law-of-Demeter reach-through; putting the behavior on the object that owns the `AgentSession` is both LoD-correct and more testable (satisfying the user's conditional "inline only if straightforward to test").
+- Workspace ownership locked to **Option A** (session-only `SubagentSession`; `Agent` keeps workspace prepare/dispose).
+  Decisive reasoning: the workspace and the session have genuinely different lifetimes (workspace dies at run-completion to fold its `resultAddendum` into the result; session survives to cleanup for resume + the new registry boundary), so they are different resources.
+  Option B would fuse them into one object needing two teardown methods, and would thread the `WorkspaceProvider` + prepare-context through the factory just to call `prepare()` — a parameter-relay smell the user flagged.
+  The factory takes a resolved `cwd` value (used directly), never the provider.
+- Worktrees are already out of the core (#263) — confirmed zero git code in `pi-subagents/src/` (only doc comments).
+  The A/B fork is purely about how the core sequences its abstract `WorkspaceProvider` seam; `@gotgenes/pi-subagents-worktrees` is untouched.
+- Registry semantics: moving `disposed` from run-completion to true session disposal makes resume executions registry-detected (closes the gap deferred from #261).
+  The permission system's subscription code does not change; only *when* `disposed` fires moves.
+  Edge case planned: `createSubagentSession` must dispose on a post-`session-created` failure to avoid a registry leak.
+- Discovered debt captured (the user's "it is in doing the work that we discover the work to be done"): filed #277 for the remaining `agent.session` reach-throughs (steer buffer-or-deliver duplicated across `steer-tool` + `service-adapter`, conversation viewing, resume-readiness guards) and added a "Session encapsulation debt (Law of Demeter)" subsection to `architecture.md` (commit `038a1283`).
+  `SubagentSession` exposes a `.session` accessor in #265 so observer wiring + consumers keep working; #277 retires those.
+- Two follow-ups deliberately deferred and noted in the plan's Non-Goals / Open Questions: the `Agent` → `Subagent` class rename (mechanical, ~19 files — separate issue) and resume-aware workspaces (a worktree's lifetime is one turn loop; worktree + resume is degenerate today).
+- The change is non-breaking (no `feat!:`): the dissolved types (`RunOptions`, `RunResult`, `AgentRunner`) are internal, so `public.d.ts` is unaffected.
+  TDD order uses lift-and-shift across 7 steps to keep each commit compiling; transient duplication of the turn-loop helpers/assembly exists between steps 3–5 and is deleted in step 6.
+
+## Stage: Implementation — TDD (2026-05-29T22:18:00Z)
+
+### Session summary
+
+Executed all 7 TDD steps from the plan via lift-and-shift, one commit per step, each leaving the suite green.
+Introduced `SubagentSession` (`runTurnLoop`/`resumeTurnLoop`/`steer`/`dispose`) and the `createSubagentSession()` assembly factory, swapped `Agent`/`AgentManager`/`index.ts` onto them, then deleted `agent-runner.ts` + `execution-state.ts` and the three runner test files.
+Package test count went 951 → 960 (net +9: new `subagent-session`/`create-subagent-session`/`turn-limits` suites added, the redundant runner suites deleted).
+Pre-completion reviewer: initial FAIL (MD060 table alignment in SKILL.md, auto-fixed by `rumdl fmt`), PASS on re-check after fix + stale doc cleanup.
+
+### Observations
+
+- The plan sketch's `TurnLoopOptions` listed only `maxTurns`/`graceTurns`/`signal`, but preserving the old `runAgent` precedence `per-call ?? agentMaxTurns ?? defaultMaxTurns` required threading `defaultMaxTurns` through `TurnLoopOptions` and storing `agentMaxTurns` + `parentContext` in `SubagentSession` meta (both are session-level facts known at creation).
+  This is a correctness-preserving deviation, well covered by three precedence tests plus a parent-context-prepend test in `subagent-session.test.ts`.
+- The atomic call-site swap (step 5) touched more test files than the plan's step-5 list anticipated: every tool/service test that set `record.execution = { session, outputFile }` (`steer-tool`, `agent-tool`, `background-spawner`, `foreground-runner`, `get-result-tool`, `service-adapter`) had to migrate to `record.subagentSession = toSubagentSession(createSubagentSessionStub(...))`.
+  Added `createSubagentSessionStub`/`toSubagentSession` to `mock-session.ts` so the migration was a one-line change per call site; the stub's `steer`/`dispose` delegate to the underlying `MockSession` so existing session-spy assertions kept working unchanged.
+- `disposed` moved from `runAgent`'s `finally` (run-completion) to `SubagentSession.dispose()`, invoked by `AgentManager` via the new `Agent.disposeSession()` (routing both `record.session?.dispose?.()` call sites at `agent-manager.ts:235,309`).
+  The full cross-package suite confirms the permission system (1504 tests) is unaffected — its subscription code did not change, only *when* `disposed` fires.
+- Test-helper gotcha: `makeSubagentSession`'s `outputFile` default initially swallowed an explicit `undefined` via `?? default`; fixed with an `"outputFile" in metaOverrides` presence check (the testing-skill "Partial spread erases explicit undefined" family).
+- `print-mode.test.ts` now mocks `#src/lifecycle/create-subagent-session` (was `#src/lifecycle/agent-runner`); `index.ts` wraps the factory as `(params) => createSubagentSession(params, deps)`, so the module mock still intercepts it.
+- fallow stayed clean throughout — the transient duplication of IO interfaces + turn-loop helpers between `agent-runner.ts` and the new modules (steps 3–5) was removed in step 6 before the pre-completion gate ran.
+- Reviewer's two minor non-blocking notes: SKILL.md Session-domain count now lists `conversation.ts` but still omits the pre-existing `content-items.ts` (drift predates this issue); `create-subagent-session.ts` keeps an accurate "old runner's runAgent()" provenance comment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "12.1.0",
+  "version": "13.1.0",
   "type": "module",
   "exports": {
     ".": {

package/src/config/agent-types.ts

@@ -114,8 +114,6 @@ export class AgentTypeRegistry implements AgentConfigLookup {
       displayName: "Agent",
       description: "General-purpose agent for complex, multi-step tasks",
       builtinToolNames: BUILTIN_TOOL_NAMES,
-      extensions: true,
-      skills: true,
       systemPrompt: "",
       promptMode: "append",
     };

package/src/config/custom-agents.ts

@@ -58,8 +58,6 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       displayName: str(fm.display_name),
       description: str(fm.description) ?? name,
       builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
-      extensions: resolveBoolExtensions(fm.extensions ?? fm.inherit_extensions),
-      skills: inheritField(fm.skills ?? fm.inherit_skills),
       model: str(fm.model),
       thinking: str(fm.thinking) as ThinkingLevel | undefined,
       maxTurns: nonNegativeInt(fm.max_turns),
@@ -67,7 +65,6 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       promptMode: fm.prompt_mode === "append" ? "append" : "replace",
       inheritContext: fm.inherit_context != null ? fm.inherit_context === true : undefined,
       runInBackground: fm.run_in_background != null ? fm.run_in_background === true : undefined,
-      isolated: fm.isolated != null ? fm.isolated === true : undefined,
       enabled: fm.enabled !== false,  // default true; explicitly false disables
       source,
     });
@@ -107,30 +104,3 @@ function csvList(val: unknown, defaults: string[]): string[] {
   if (val === undefined || val === null) return defaults;
   return parseCsvField(val) ?? [];
 }
-
-/**
- * Resolve the `extensions` field to a boolean.
- * CSV/array values (legacy allowlist syntax) are coerced to `true` with a warning.
- */
-function resolveBoolExtensions(val: unknown): boolean {
-  const result = inheritField(val);
-  if (Array.isArray(result)) {
-    console.warn(
-      "[pi-subagents] extensions allowlist syntax is deprecated — treating as \"true\" (inherit all).\n" +
-        "Use \"permission:\" frontmatter in pi-permission-system for per-tool access control.",
-    );
-    return true;
-  }
-  return result;
-}
-
-/**
- * Parse an inherit field (extensions, skills).
- * omitted/true → true (inherit all); false/"none"/empty → false; csv → listed names.
- */
-function inheritField(val: unknown): true | string[] | false {
-  if (val === undefined || val === null || val === true) return true;
-  if (val === false || val === "none") return false;
-  const items = csvList(val, []);
-  return items.length > 0 ? items : false;
-}

package/src/config/default-agents.ts

@@ -16,10 +16,8 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       displayName: "Agent",
       description: "General-purpose agent for complex, multi-step tasks",
       // builtinToolNames omitted — means "all available tools" (resolved at lookup time)
-      // inheritContext / runInBackground / isolated omitted — strategy fields, callers decide per-call.
+      // inheritContext / runInBackground omitted — strategy fields, callers decide per-call.
       // Setting them to false would lock callsite intent (see resolveAgentInvocationConfig in invocation-config.ts).
-      extensions: true,
-      skills: true,
       systemPrompt: "",
       promptMode: "append",
       isDefault: true,
@@ -32,8 +30,6 @@ export const DEFAULT_AGENTS: Map<string, AgentConfig> = new Map([
       displayName: "Explore",
       description: "Fast codebase exploration agent (read-only)",
       builtinToolNames: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
       model: "anthropic/claude-haiku-4-5-20251001",
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
@@ -74,8 +70,6 @@ Use Bash ONLY for read-only operations: ls, git status, git log, git diff, find,
       displayName: "Plan",
       description: "Software architect for implementation planning (read-only)",
       builtinToolNames: READ_ONLY_TOOLS,
-      extensions: true,
-      skills: true,
       systemPrompt: `# CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS
 You are a software architect and planning specialist.
 Your role is EXCLUSIVELY to explore the codebase and design implementation plans.

package/src/config/invocation-config.ts

@@ -6,7 +6,6 @@ interface AgentInvocationParams {
   max_turns?: number;
   run_in_background?: boolean;
   inherit_context?: boolean;
-  isolated?: boolean;
 }
 
 export function resolveAgentInvocationConfig(
@@ -19,7 +18,6 @@ export function resolveAgentInvocationConfig(
   maxTurns?: number;
   inheritContext: boolean;
   runInBackground: boolean;
-  isolated: boolean;
 } {
   return {
     modelInput: agentConfig?.model ?? params.model,
@@ -28,6 +26,5 @@ export function resolveAgentInvocationConfig(
     maxTurns: agentConfig?.maxTurns ?? params.max_turns,
     inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
     runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
-    isolated: agentConfig?.isolated ?? params.isolated ?? false,
   };
 }

package/src/index.ts

@@ -24,9 +24,9 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
-import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runner";
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
+import { createSubagentSession, type SubagentSessionDeps } from "#src/lifecycle/create-subagent-session";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
@@ -38,7 +38,6 @@ import { detectEnv } from "#src/session/env";
 import { resolveModel } from "#src/session/model-resolver";
 import { buildAgentPrompt } from "#src/session/prompts";
 import { deriveSubagentSessionDir } from "#src/session/session-dir";
-import { preloadSkills } from "#src/session/skill-loader";
 import { SettingsManager } from "#src/settings";
 import { AgentTool } from "#src/tools/agent-tool";
 import { GetResultTool } from "#src/tools/get-result-tool";
@@ -133,7 +132,7 @@ export default function (pi: ExtensionAPI) {
     },
   };
 
-  const runnerDeps: RunnerDeps = {
+  const subagentSessionDeps: SubagentSessionDeps = {
     io: {
       detectEnv,
       getAgentDir,
@@ -143,7 +142,6 @@ export default function (pi: ExtensionAPI) {
       createSettingsManager: (cwd, dir) => SdkSettingsManager.create(cwd, dir),
       createSession: (opts) => createAgentSession(opts as any),
       assemblerIO: {
-        preloadSkills,
         buildAgentPrompt,
       },
     },
@@ -164,7 +162,7 @@ export default function (pi: ExtensionAPI) {
   );
 
   const manager = new AgentManager({
-    runner: new ConcreteAgentRunner(runnerDeps),
+    createSubagentSession: (params) => createSubagentSession(params, subagentSessionDeps),
     baseCwd: process.cwd(),
     observer,
     queue,

package/src/lifecycle/agent-manager.ts

@@ -10,9 +10,10 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import { debugLog } from "#src/debug";
 import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
-import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { SubagentSession } from "#src/lifecycle/subagent-session";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 import type { RunConfig } from "#src/runtime";
@@ -28,7 +29,8 @@ export interface AgentManagerObserver {
 }
 
 export interface AgentManagerOptions {
-  runner: AgentRunner;
+  /** Assembly factory that produces a born-complete SubagentSession per spawn. */
+  createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
   queue: ConcurrencyQueue;
   /** Base working directory handed to a workspace provider (the parent cwd). */
@@ -41,7 +43,6 @@ export interface AgentSpawnConfig {
   description: string;
   model?: Model<any>;
   maxTurns?: number;
-  isolated?: boolean;
   inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
   isBackground?: boolean;
@@ -65,7 +66,7 @@ export class AgentManager {
   private agents = new Map<string, Agent>();
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: AgentManagerObserver;
-  private readonly runner: AgentRunner;
+  private readonly createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
   private readonly queue: ConcurrencyQueue;
   private readonly baseCwd: string;
   private getRunConfig?: () => RunConfig;
@@ -77,7 +78,7 @@ export class AgentManager {
   }
 
   constructor(options: AgentManagerOptions) {
-    this.runner = options.runner;
+    this.createSubagentSession = options.createSubagentSession;
     this.queue = options.queue;
     this.baseCwd = options.baseCwd;
     this.observer = options.observer;
@@ -149,12 +150,11 @@ export class AgentManager {
       prompt,
       model: options.model,
       maxTurns: options.maxTurns,
-      isolated: options.isolated,
       thinkingLevel: options.thinkingLevel,
       parentSession: options.parentSession,
       signal: options.signal,
       // Shared deps
-      runner: this.runner,
+      createSubagentSession: this.createSubagentSession,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
       baseCwd: this.baseCwd,
@@ -233,8 +233,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: Agent): void {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
-    record.session?.dispose?.();
+    record.disposeSession();
     this.agents.delete(id);
   }
 
@@ -308,7 +307,7 @@ export class AgentManager {
     // Clear queue
     this.queue.clear();
     for (const record of this.agents.values()) {
-      record.session?.dispose();
+      record.disposeSession();
     }
     this.agents.clear();
   }

package/src/lifecycle/agent.ts

@@ -14,16 +14,16 @@
  * The child's working directory is supplied by a registered WorkspaceProvider
  * (the workspace seam); with no provider the child runs in the parent cwd.
  *
- * Phase-specific collaborators (execution, notification) are attached
+ * Phase-specific collaborators (subagentSession, notification) are attached
  * after construction as lifecycle information becomes available.
  */
 
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
-import type { ExecutionState } from "#src/lifecycle/execution-state";
+import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { SubagentSession, TurnLoopResult } from "#src/lifecycle/subagent-session";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
@@ -36,7 +36,7 @@ import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType,
 export interface AgentLifecycleObserver {
 	/** Fires when the agent transitions to running (inside run(), after markRunning). */
 	onStarted?(agent: Agent): void;
-	/** Fires when the runner creates the session — delivers the session to external consumers. */
+	/** Fires once the session is created — delivers the session to external consumers. */
 	onSessionCreated?(agent: Agent, session: AgentSession): void;
 	/** Fires once when the run completes or fails (for concurrency drain). */
 	onRunFinished?(agent: Agent): void;
@@ -68,7 +68,8 @@ export interface AgentInit {
 	error?: string;
 
 	// Shared deps (required for run(), optional for tests)
-	runner?: AgentRunner;
+	/** Assembly factory that produces a born-complete SubagentSession. */
+	createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 	/** Resolves the registered workspace provider (if any) at run-start. */
@@ -81,7 +82,6 @@ export interface AgentInit {
 	prompt?: string;
 	model?: Model<any>;
 	maxTurns?: number;
-	isolated?: boolean;
 	thinkingLevel?: ThinkingLevel;
 	parentSession?: ParentSessionInfo;
 	isBackground?: boolean;
@@ -127,7 +127,7 @@ export class Agent {
 	promise?: Promise<void>;
 
 	// Shared deps — optional (required for run())
-	private readonly _runner?: AgentRunner;
+	private readonly _createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
@@ -140,13 +140,13 @@ export class Agent {
 	private readonly _prompt?: string;
 	private readonly _model?: Model<any>;
 	private readonly _maxTurns?: number;
-	private readonly _isolated?: boolean;
 	private readonly _thinkingLevel?: ThinkingLevel;
 	private readonly _parentSession?: ParentSessionInfo;
 	private readonly _signal?: AbortSignal;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
-	execution?: ExecutionState;
+	/** The born-complete child session — set when the factory returns inside run(). */
+	subagentSession?: SubagentSession;
 	notification?: NotificationState;
 
 	// Steer buffer — messages queued before the session is ready
@@ -156,12 +156,12 @@ export class Agent {
 
 	/** The active agent session, or undefined before the session is created. */
 	get session(): AgentSession | undefined {
-		return this.execution?.session;
+		return this.subagentSession?.session;
 	}
 
 	/** Path to the agent's session JSONL file, or undefined if not yet available. */
 	get outputFile(): string | undefined {
-		return this.execution?.outputFile;
+		return this.subagentSession?.outputFile;
 	}
 
 	constructor(init: AgentInit) {
@@ -187,7 +187,7 @@ export class Agent {
 		this.abortController = new AbortController();
 
 		// Shared deps
-		this._runner = init.runner;
+		this._createSubagentSession = init.createSubagentSession;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
 		this._getWorkspaceProvider = init.getWorkspaceProvider;
@@ -198,7 +198,6 @@ export class Agent {
 		this._prompt = init.prompt;
 		this._model = init.model;
 		this._maxTurns = init.maxTurns;
-		this._isolated = init.isolated;
 		this._thinkingLevel = init.thinkingLevel;
 		this._parentSession = init.parentSession;
 		this._signal = init.signal;
@@ -210,16 +209,16 @@ export class Agent {
 	}
 
 	/**
-	 * Execute the full agent lifecycle: workspace preparation, runner invocation,
-	 * session-creation handling, observer wiring, workspace disposal, and
+	 * Execute the full agent lifecycle: workspace preparation, session creation
+	 * via the factory, observer wiring, the turn loop, workspace disposal, and
 	 * status transitions.
 	 *
-	 * Requires runner and snapshot to be set at construction.
+	 * Requires the session factory and snapshot to be set at construction.
 	 * The returned promise always resolves (errors are captured internally).
 	 */
 	async run(): Promise<void> {
-		if (!this._runner) {
-			throw new Error("Agent not configured for execution — missing runner");
+		if (!this._createSubagentSession) {
+			throw new Error("Agent not configured for execution — missing session factory");
 		}
 		if (!this._snapshot || !this._prompt) {
 			throw new Error("Agent not configured for execution — missing snapshot or prompt");
@@ -250,30 +249,35 @@ export class Agent {
 			return;
 		}
 
-		const runConfig = this._getRunConfig?.();
 		try {
-			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
-				context: {
-					cwd,
-					parentSession: this._parentSession,
-				},
+			this.subagentSession = await this._createSubagentSession({
+				snapshot: this._snapshot,
+				type: this.type,
+				cwd,
+				parentSession: this._parentSession,
 				model: this._model,
+				thinkingLevel: this._thinkingLevel,
+			});
+		} catch (err) {
+			// The factory disposed its own session on a post-creation failure.
+			this.failRun(err);
+			return;
+		}
+
+		const session = this.subagentSession.session;
+		this.flushPendingSteers();
+		this.attachObserver(subscribeAgentObserver(session, this, {
+			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		}));
+		this.observer?.onSessionCreated?.(this, session);
+
+		const runConfig = this._getRunConfig?.();
+		try {
+			const result = await this.subagentSession.runTurnLoop(this._prompt, {
 				maxTurns: this._maxTurns,
 				defaultMaxTurns: runConfig?.defaultMaxTurns,
 				graceTurns: runConfig?.graceTurns,
-				isolated: this._isolated,
-				thinkingLevel: this._thinkingLevel,
 				signal: this.abortController.signal,
-				onSessionCreated: (session) => {
-					// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
-					const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
-					this.execution = { session, outputFile };
-					this.flushPendingSteers(session);
-					this.attachObserver(subscribeAgentObserver(session, this, {
-						onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
-					}));
-					this.observer?.onSessionCreated?.(this, session);
-				},
 			});
 			this.completeRun(result);
 		} catch (err) {
@@ -285,27 +289,24 @@ export class Agent {
 	 * Resume an existing session with a new prompt, managing the observer
 	 * subscription lifecycle internally (same wiring as run()).
 	 *
-	 * Requires runner and an existing session (set when the original run created it).
+	 * Requires an existing SubagentSession (set when the original run created it).
 	 * The returned promise always resolves (errors are captured internally).
-	 * The parent signal flows straight through to runner.resume — resume does not
+	 * The parent signal flows straight through to resumeTurnLoop — resume does not
 	 * route through this.abortController.
 	 */
 	async resume(prompt: string, signal?: AbortSignal): Promise<void> {
-		if (!this._runner) {
-			throw new Error("Agent not configured for execution — missing runner");
-		}
-		const session = this.session;
-		if (!session) {
+		const subagentSession = this.subagentSession;
+		if (!subagentSession) {
 			throw new Error("Agent not configured for resume — missing session");
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeAgentObserver(session, this, {
+		this.attachObserver(subscribeAgentObserver(subagentSession.session, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
 
 		try {
-			const responseText = await this._runner.resume(session, prompt, { signal });
+			const responseText = await subagentSession.resumeTurnLoop(prompt, signal);
 			this.markCompleted(responseText);
 		} catch (err) {
 			this.markError(err);
@@ -411,11 +412,11 @@ export class Agent {
 
 	/**
 	 * Flush all buffered steer messages to the session and clear the buffer.
-	 * Called from onSessionCreated once the session is available.
+	 * Called once the session is available, delegating to SubagentSession.steer.
 	 */
-	flushPendingSteers(session: AgentSession): void {
+	flushPendingSteers(): void {
 		for (const msg of this._pendingSteers) {
-			session.steer(msg).catch(() => {});
+			this.subagentSession?.steer(msg).catch(() => {});
 		}
 		this._pendingSteers = [];
 	}
@@ -455,8 +456,8 @@ export class Agent {
 		this._detachFn = undefined;
 	}
 
-	/** Complete a run: release listeners, dispose the workspace, status transition, execution update, notify observer. */
-	completeRun(result: RunResult): void {
+	/** Complete a run: release listeners, dispose the workspace, status transition, notify observer. */
+	completeRun(result: TurnLoopResult): void {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
@@ -474,14 +475,14 @@ export class Agent {
 		else if (result.steered) this.markSteered(finalResult);
 		else this.markCompleted(finalResult);
 
-		this.execution = {
-			session: result.session,
-			outputFile: result.sessionFile ?? this.execution?.outputFile,
-		};
-
 		this.observer?.onRunFinished?.(this);
 	}
 
+	/** Dispose the wrapped session, firing the `disposed` lifecycle event. */
+	disposeSession(): void {
+		this.subagentSession?.dispose();
+	}
+
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);