@gotgenes/pi-subagents 18.0.1 → 18.0.2

package/docs/plans/0239-collapse-filter-active-tools.md

@@ -1,217 +0,0 @@
----
-issue: 239
-issue_title: "Collapse filterActiveTools to recursion guard (Phase 14, Step 3)"
----
-
-# Collapse `filterActiveTools` to recursion guard
-
-## Problem Statement
-
-With `disallowed_tools` (#237) and `extensions` filtering (#238) removed, `filterActiveTools` retains two branches that no longer justify a config bag or two-pass pre-bind/post-bind dance:
-
-1. The `extensions === false` early return — a passthrough that belongs at the callsite.
-2. The `EXCLUDED_TOOL_NAMES` recursion guard — the function's sole essential purpose.
-
-The `builtinToolNameSet` membership check always returns `true` now (no string-array `extensions` filtering remains), making it dead logic.
-`ToolFilterConfig` exists only to carry two fields (`toolNames`, `extensions`) through the assembler→runner boundary, but after this change they travel independently: `toolNames` feeds `createSession`, `extensions` feeds the resource loader's `noExtensions` flag, and neither is consumed by the filter function.
-
-## Goals
-
-- Reduce `filterActiveTools` to a one-liner: filter out `EXCLUDED_TOOL_NAMES`.
-- Delete the `ToolFilterConfig` interface.
-- Flatten `SessionConfig.toolFilter` back into two top-level fields: `toolNames` and `extensions`.
-- Remove the pre-bind filter call — without denylist/allowlist logic, filtering before `bindExtensions` serves no purpose.
-- Keep a single post-bind filter call for the recursion guard.
-- Update tests to reflect the simplified flow.
-
-## Non-Goals
-
-- Removing `extensions` from `SessionConfig` entirely — it's still needed for the `noExtensions` flag on the resource loader.
-- Renaming `EXCLUDED_TOOL_NAMES` or moving it to a separate module.
-- Phase 15 domain model changes (#227–#232) — those operate on the simplified codebase this change produces.
-
-## Background
-
-`filterActiveTools` was extracted as part of Phase 10 (#168) to group `toolNames`, `disallowedSet`, and `extensions` into a `ToolFilterConfig` bag.
-Issue #237 removed `disallowedSet`; #238 narrowed `extensions` from `true | string[] | false` to `boolean`.
-Both are now closed.
-
-The two-pass filter dance (Patch 2, RepOne #443) exists to catch extension-registered tools that join the active set during `bindExtensions`.
-With the only remaining filter logic being the `EXCLUDED_TOOL_NAMES` guard, a single post-bind pass suffices.
-
-Current `filterActiveTools` body:
-
-```typescript
-function filterActiveTools(
-  activeTools: string[],
-  config: ToolFilterConfig,
-): string[] {
-  const { toolNames, extensions } = config;
-  if (!extensions) {
-    return activeTools;
-  }
-  const builtinToolNameSet = new Set(toolNames);
-  return activeTools.filter((t) => {
-    if (EXCLUDED_TOOL_NAMES.includes(t)) return false;
-    if (builtinToolNameSet.has(t)) return true;
-    return true;
-  });
-}
-```
-
-The `builtinToolNameSet` check is dead — both branches return `true`.
-The `!extensions` early return belongs at the callsite.
-
-### Affected files
-
-- `src/lifecycle/agent-runner.ts` — `filterActiveTools`, pre-bind/post-bind calls, `ToolFilterConfig` import
-- `src/session/session-config.ts` — `ToolFilterConfig` interface, `SessionConfig.toolFilter` field, assembler return literal
-- `test/lifecycle/agent-runner-extension-tools.test.ts` — pre-bind/post-bind assertions
-- `test/session/session-config.test.ts` — `toolFilter.*` assertions
-- `test/lifecycle/agent-runner.test.ts` — session mock (`setActiveToolsByName` calls)
-- `docs/architecture/architecture.md` — references to `ToolFilterConfig`, `filterActiveTools`, Phase 14 status
-
-## Design Overview
-
-### `filterActiveTools` simplification
-
-The function reduces to:
-
-```typescript
-function filterActiveTools(activeTools: string[]): string[] {
-  return activeTools.filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
-}
-```
-
-No config parameter.
-The `extensions === false` guard moves to the callsite: `if (cfg.extensions)`.
-
-### `SessionConfig` flattening
-
-```typescript
-export interface SessionConfig {
-  effectiveCwd: string;
-  systemPrompt: string;
-  toolNames: string[];       // was toolFilter.toolNames
-  extensions: boolean;        // was toolFilter.extensions
-  model: unknown;
-  thinkingLevel: ThinkingLevel | undefined;
-  noSkills: boolean;
-  extras: PromptExtras;
-  agentMaxTurns: number | undefined;
-}
-```
-
-### `runAgent` callsite changes
-
-Before (two-pass):
-
-```typescript
-if (cfg.toolFilter.extensions) {
-  const filtered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-  session.setActiveToolsByName(filtered);
-}
-// ... bindExtensions ...
-if (cfg.toolFilter.extensions) {
-  const refiltered = filterActiveTools(session.getActiveToolNames(), cfg.toolFilter);
-  session.setActiveToolsByName(refiltered);
-}
-```
-
-After (single post-bind pass):
-
-```typescript
-// ... bindExtensions ...
-if (cfg.extensions) {
-  const filtered = filterActiveTools(session.getActiveToolNames());
-  session.setActiveToolsByName(filtered);
-}
-```
-
-Other `cfg.toolFilter.*` references update to `cfg.toolNames` and `cfg.extensions`.
-
-## Module-Level Changes
-
-### `src/session/session-config.ts`
-
-1. Delete the `ToolFilterConfig` interface.
-2. Replace `toolFilter: ToolFilterConfig` on `SessionConfig` with two flat fields: `toolNames: string[]` and `extensions: boolean`.
-3. Update the return literal in `assembleSessionConfig` from `toolFilter: { toolNames, extensions }` to `toolNames, extensions`.
-4. Update the JSDoc on `SessionConfig` — remove "Tool filtering cluster" comment.
-
-### `src/lifecycle/agent-runner.ts`
-
-1. Remove the `ToolFilterConfig` import.
-2. Simplify `filterActiveTools` to `(activeTools: string[]) => string[]` — just the `EXCLUDED_TOOL_NAMES` filter.
-3. Remove the pre-bind filter block (the first `if (cfg.toolFilter.extensions)` block).
-4. Update the post-bind filter block: `cfg.toolFilter.extensions` → `cfg.extensions`, remove the config argument from the `filterActiveTools` call.
-5. Update `noExtensions: !cfg.toolFilter.extensions` → `noExtensions: !cfg.extensions`.
-6. Update `tools: cfg.toolFilter.toolNames` → `tools: cfg.toolNames`.
-7. Update or remove the Patch 2 comments — the two-pass dance is gone; the remaining call is just a recursion guard.
-
-### `test/lifecycle/agent-runner-extension-tools.test.ts`
-
-1. Remove the pre-bind/post-bind ordering assertions — there is only one post-bind call now.
-2. Update `setActiveToolsByName` call count expectations from 2 to 1.
-3. Update assertions to check `setActiveToolsByName.mock.calls[0][0]` (was `calls[1][0]` for the second call).
-4. The `extensions: false` test continues to assert that `setActiveToolsByName` is not called.
-
-### `test/session/session-config.test.ts`
-
-1. Update `result.toolFilter.toolNames` → `result.toolNames`.
-2. Update `result.toolFilter.extensions` → `result.extensions`.
-
-### `test/lifecycle/agent-runner.test.ts`
-
-1. No structural changes needed — the session mock already has `setActiveToolsByName: vi.fn()`, and the default test config has `extensions: false` (so the filter doesn't run).
-   If any test asserts on `setActiveToolsByName` call counts, verify they still pass.
-
-### `docs/architecture/architecture.md`
-
-1. Update the Phase 14 Step 3 entry to mark it complete.
-2. Update the structural analysis table: `SessionConfig` field count changes, `ToolFilterConfig` is removed.
-3. Update the smell table to mark the two-pass filter and `ToolFilterConfig` smells as resolved.
-
-## Test Impact Analysis
-
-1. **New tests enabled:** None — the simplification doesn't introduce new testable surface.
-2. **Tests that become redundant:** The pre-bind/post-bind ordering test in `agent-runner-extension-tools.test.ts` — the pre-bind call is removed.
-   The test that the post-bind filter includes extension tools stays; it verifies the recursion guard runs after `bindExtensions`.
-3. **Tests that stay as-is:** The `extensions: false` skip test, the `EXCLUDED_TOOL_NAMES` exclusion test, all `session-config.test.ts` tests (with property path updates).
-
-## TDD Order
-
-1. **Flatten `SessionConfig` and delete `ToolFilterConfig`** — Replace `toolFilter: ToolFilterConfig` with `toolNames: string[]` and `extensions: boolean` on `SessionConfig`.
-   Delete the `ToolFilterConfig` interface.
-   Update the assembler return literal.
-   Update `session-config.test.ts` property paths (`result.toolFilter.toolNames` → `result.toolNames`, `result.toolFilter.extensions` → `result.extensions`).
-   Run `pnpm run check` to verify downstream compile errors (expected in `agent-runner.ts`).
-   Commit: `refactor: flatten SessionConfig and remove ToolFilterConfig`
-
-2. **Simplify `filterActiveTools` and remove pre-bind call** — Reduce `filterActiveTools` to `(activeTools: string[]) => string[]`.
-   Remove the `ToolFilterConfig` import.
-   Remove the pre-bind filter block.
-   Update the post-bind filter block to use `cfg.extensions` and pass no config to `filterActiveTools`.
-   Update `noExtensions` and `tools` references to `cfg.extensions` and `cfg.toolNames`.
-   Update `agent-runner-extension-tools.test.ts`: change `setActiveToolsByName` call count from 2 to 1, update assertion indices from `calls[1]` to `calls[0]`, remove the pre-bind/post-bind ordering test, update comments.
-   Verify `agent-runner.test.ts` still passes.
-   Commit: `refactor: simplify filterActiveTools to recursion guard`
-
-3. **Update architecture docs** — Mark Phase 14 Step 3 as complete.
-   Update `SessionConfig` field count and remove `ToolFilterConfig` references from the structural analysis.
-   Mark the two-pass filter and `ToolFilterConfig` smells as resolved.
-   Commit: `docs: mark Phase 14 Step 3 complete in architecture`
-
-## Risks and Mitigations
-
-1. **Pre-bind filter removal may miss a recursion-guard edge case** — If a subagent's own tools (`subagent`, `get_subagent_result`, `steer_subagent`) were in the built-in tool set before `bindExtensions`, removing the pre-bind filter could leave them active during the bind phase.
-   Mitigation: These tools are registered by this extension during `bindExtensions`, not before.
-   They cannot be in the pre-bind active set.
-   The post-bind filter is sufficient.
-
-2. **Flattening `SessionConfig` may break external consumers** — `SessionConfig` is not exported from the package entry point; it's an internal interface between `session-config.ts` and `agent-runner.ts`.
-   No external consumers exist.
-
-## Open Questions
-
-None — the issue's changes are unambiguous and all dependencies are complete.

package/docs/plans/0242-rename-agent-tool-to-subagent.md

@@ -1,165 +0,0 @@
----
-issue: 242
-issue_title: "Rename `Agent` tool to `subagent`"
----
-
-# Rename `Agent` tool to `subagent`
-
-## Problem Statement
-
-The `Agent` tool is the only PascalCase tool name in the Pi ecosystem.
-Pi's built-in tools are all lowercase (`read`, `bash`, `write`, `edit`, `find`, `grep`, `ls`), and the companion tools in this package already use lowercase snake_case (`get_subagent_result`, `steer_subagent`).
-The PascalCase name was inherited from tintinweb/pi-subagents, which mimicked Claude Code's convention rather than Pi's.
-
-## Goals
-
-- Rename the tool from `"Agent"` to `"subagent"` — a **breaking change** (`feat!:`).
-- Update `label`, `promptSnippet`, and `description` text to reference `subagent` instead of `Agent`.
-- Update `EXCLUDED_TOOL_NAMES` in `agent-runner.ts`.
-- Update the fallback display name in `agent-tool.ts` `renderCall`.
-- Update architecture docs that reference the `Agent` tool name.
-- Update `README.md` tool-name references.
-- Update all affected tests.
-
-## Non-Goals
-
-- Renaming the `displayName` of the general-purpose agent type (`"Agent"` in `default-agents.ts` and `agent-types.ts` fallback) — that is a UI display name for the agent *type*, not the tool name.
-  The widget shows "Agent" as the display name for general-purpose agents; this is a separate concern.
-- Renaming the companion tools `get_subagent_result` and `steer_subagent` — they already follow the lowercase convention.
-- Updating the companion tools' `label` fields (`"Steer Agent"`, `"Get Agent Result"`) — these use "Agent" in the human-readable sense, not as the tool name.
-- Collapsing `filterActiveTools` (#239) — that step is independent within Phase 14.
-- Updating pi-permission-system docs — verified that no docs there reference the `Agent` tool name specifically.
-  All "Agent" references in that package's docs refer to the agent-name concept (per-agent overrides, agent frontmatter), not the tool.
-
-## Background
-
-Phase 14 of the architecture roadmap strips policy enforcement from pi-subagents.
-Steps 1 and 2 (#237, #238) are complete; Step 3 (#239, collapse `filterActiveTools`) is open but independent of this rename.
-This is Step 4 — the final convention-alignment step in Phase 14.
-
-### Files affected
-
-| File                                                  | Current `"Agent"` references                                                                                                                      |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/tools/agent-tool.ts`                             | `name`, `label`, `promptSnippet`, description text, `renderCall` fallback (line 247)                                                              |
-| `src/lifecycle/agent-runner.ts`                       | `EXCLUDED_TOOL_NAMES` array (line 22)                                                                                                             |
-| `README.md`                                           | Tool name references, usage examples, tool parameter table heading                                                                                |
-| `docs/architecture/architecture.md`                   | Directory listing comment, findings table, Step 4 description                                                                                     |
-| `test/tools/agent-tool.test.ts`                       | `name` and `label` assertions                                                                                                                     |
-| `test/lifecycle/agent-runner-extension-tools.test.ts` | `"Agent"` in active-tools arrays and `not.toContain` assertion                                                                                    |
-| `test/print-mode.test.ts`                             | `tools.get("Agent")` lookup                                                                                                                       |
-| `test/widget-renderer.test.ts`                        | `"Agent"` in display-name comment and assertion                                                                                                   |
-| `test/tools/spawn-config.test.ts`                     | `displayName: "Agent"` assertions (general-purpose type display name — **no change**, these test the agent type's displayName, not the tool name) |
-| `test/tools/foreground-runner.test.ts`                | `displayName: "Agent"` in fixture data (**no change** — tests general-purpose type displayName)                                                   |
-| `test/tools/helpers.test.ts`                          | `displayName: "Agent"` in fixture data (**no change** — tests result rendering, not tool name)                                                    |
-| `test/display.test.ts`                                | `"Agent"` display name assertion (**no change** — tests `getDisplayName` for general-purpose type)                                                |
-
-## Design Overview
-
-This is a straightforward string-replacement change with no logic or type changes.
-The tool's `name` field drives Pi's tool registration, system-prompt toolbox, and LLM invocations.
-
-### Tool definition changes
-
-```typescript
-// Before
-name: "Agent" as const,
-label: "Agent",
-promptSnippet: "Agent: Launch a specialized agent for complex, multi-step tasks.",
-
-// After
-name: "subagent" as const,
-label: "Subagent",
-promptSnippet: "subagent: Launch a specialized agent for complex, multi-step tasks.",
-```
-
-The description body changes `"The Agent tool launches"` → `"The subagent tool launches"` and `"Agent results are returned"` → `"Subagent results are returned"`.
-
-### renderCall fallback
-
-```typescript
-// Before
-: "Agent";
-// After
-: "Subagent";
-```
-
-This fallback shows when no `subagent_type` is provided.
-Using `"Subagent"` (capitalized for display) is appropriate — it mirrors the tool's identity without conflating with the general-purpose agent type's `displayName`.
-
-### EXCLUDED_TOOL_NAMES
-
-```typescript
-// Before
-const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
-// After
-const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
-```
-
-## Module-Level Changes
-
-### `src/tools/agent-tool.ts`
-
-1. Change `name: "Agent" as const` → `name: "subagent" as const`.
-2. Change `label: "Agent"` → `label: "Subagent"`.
-3. Change `promptSnippet` to start with `subagent:` instead of `Agent:`.
-4. Change `"The Agent tool launches"` → `"The subagent tool launches"` in description.
-5. Change `"Agent results are returned"` → `"Subagent results are returned"` in description guidelines.
-6. Change fallback `"Agent"` → `"Subagent"` in `renderCall`.
-
-### `src/lifecycle/agent-runner.ts`
-
-1. Change `"Agent"` → `"subagent"` in `EXCLUDED_TOOL_NAMES`.
-
-### `README.md`
-
-1. Update tool name references in the "features" bullet (`` `Agent` `` → `` `subagent` ``).
-2. Update usage example heading and code block (`Agent({` → `subagent({`).
-3. Update tool parameter table heading (`### \`Agent\`` → `### \`subagent\``).
-4. Update prose references to the `Agent` tool ("`Agent` tool parameters", "`Agent` tool returns").
-5. Update widget example display — the widget shows `Agent` because the general-purpose type's `displayName` is `"Agent"`, so those lines stay as-is.
-
-### `docs/architecture/architecture.md`
-
-1. Update the directory listing comment: `agent-tool.ts` description → `subagent tool definition`.
-2. Update the findings table row to mark the item as resolved.
-3. Update Step 4 description to indicate completion.
-4. The `(née \`Agent\`)` parenthetical in the "What the core owns" section already anticipates the rename — keep it as-is for historical context.
-
-### Test files
-
-1. `test/tools/agent-tool.test.ts` — update `name` and `label` assertions.
-2. `test/lifecycle/agent-runner-extension-tools.test.ts` — update `"Agent"` in active-tools arrays and `.not.toContain("Agent")` → `.not.toContain("subagent")`.
-3. `test/print-mode.test.ts` — update `tools.get("Agent")` → `tools.get("subagent")`.
-4. `test/widget-renderer.test.ts` — update the comment text (the assertion tests general-purpose displayName, which stays `"Agent"`).
-
-## Test Impact Analysis
-
-1. No new tests are needed — this is a string-value change.
-2. Existing tests that assert the tool name `"Agent"` must be updated to assert `"subagent"`.
-3. Tests that assert the general-purpose agent type's `displayName` (`"Agent"`) are **not affected** — the `displayName` is an agent-type property, not the tool name.
-
-## TDD Order
-
-1. **Update tool definition and runner constant.**
-   Change `name`, `label`, `promptSnippet`, description text, and `renderCall` fallback in `agent-tool.ts`.
-   Change `EXCLUDED_TOOL_NAMES` in `agent-runner.ts`.
-   Update affected tests in `agent-tool.test.ts`, `agent-runner-extension-tools.test.ts`, `print-mode.test.ts`, and `widget-renderer.test.ts`.
-   Commit: `feat!: rename Agent tool to subagent (#242)`
-
-2. **Update documentation.**
-   Update `README.md` tool-name references and usage examples.
-   Update `docs/architecture/architecture.md` directory listing, findings table, and Step 4 status.
-   Commit: `docs: update tool name references after Agent → subagent rename (#242)`
-
-## Risks and Mitigations
-
-| Risk                                                                                            | Mitigation                                                                                                                    |
-| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Breaking change for users referencing `Agent` in AGENTS.md, prompt templates, or custom configs | This is intentional and documented in the issue. Fits within the Phase 14 breaking-change window. Use `feat!:` commit prefix. |
-| Forgetting a test reference to `"Agent"`                                                        | Grep all test files for `"Agent"` before committing. Distinguish tool-name references from agent-type displayName references. |
-| Companion tool labels (`"Steer Agent"`, `"Get Agent Result"`) use "Agent"                       | These use "Agent" in the human-readable sense. They are not affected by the tool-name rename and remain consistent.           |
-
-## Open Questions
-
-None — the issue scope is unambiguous.

package/docs/plans/0256-extract-worktree-isolation.md

@@ -1,256 +0,0 @@
----
-issue: 256
-issue_title: "Extract WorktreeIsolation collaborator"
----
-
-# Extract WorktreeIsolation collaborator
-
-## Problem Statement
-
-`Agent` currently holds three separate worktree-related members — `_worktrees` (a shared `WorktreeManager`), `_isolation` (the `IsolationMode`), and `worktreeState` (a `WorktreeState` phase object) — and orchestrates the worktree internals itself.
-It checks `this._isolation !== "worktree"`, calls `this._worktrees.create()`, constructs the `WorktreeState`, and drives `worktreeState.performCleanup(this._worktrees, ...)` from both `completeRun()` and `failRun()`.
-This is Ask-Don't-Tell: `Agent` asks its collaborators for raw materials and does the worktree work itself rather than telling a single collaborator to handle its own lifecycle.
-
-This is Phase 16, Step 1 of the agent-collaborator architecture (`docs/architecture/architecture.md`).
-
-## Goals
-
-- Introduce a `WorktreeIsolation` collaborator that owns the entire worktree lifecycle: `setup()`, `path` access, and `cleanup(description)`.
-- `AgentManager` constructs the collaborator only when `isolation === "worktree"` and passes it to `Agent` ready to go.
-- Replace `Agent`'s mode check (`this._isolation !== "worktree"`) with a null check (`this.worktree?.setup()`).
-- Fold the existing `WorktreeState` value object into `WorktreeIsolation` (delete `worktree-state.ts`), matching the architecture's target table which lists `WorktreeIsolation` as absorbing `worktrees` + `isolation` + `worktreeState`.
-- Shrink `Agent`: remove `_worktrees`, `_isolation`, `worktreeState`, and `setupWorktree()`; add a single `worktree?: WorktreeIsolation` collaborator.
-
-This change is **not** breaking to any published API — `WorktreeManager`, `WorktreeState`, and `AgentInit` are all internal to the package.
-
-## Non-Goals
-
-- No changes to the runner, session creation, or `ChildSessionFactory` — that is Step 2 (#257).
-- No changes to `Agent.run()`'s session-interaction logic, turn-limit enforcement, or response collection — that is Step 3 (#258).
-- No changes to the low-level git plumbing in `worktree.ts` (`createWorktree`, `cleanupWorktree`, `pruneWorktrees`, `GitWorktreeManager`) — those free functions and the `WorktreeManager` interface stay as-is.
-- No change to the `worktreeResult` shape exposed by `service-adapter.ts` — only the access path changes.
-
-## Background
-
-Relevant modules:
-
-- `src/lifecycle/agent.ts` — the `Agent` class.
-  Holds `_worktrees: WorktreeManager`, `_isolation: IsolationMode`, `worktreeState?: WorktreeState`; defines `setupWorktree()`; reads `this.worktreeState?.path` for the runner `cwd`; drives cleanup in `completeRun()` / `failRun()`.
-- `src/lifecycle/agent-manager.ts` — `AgentManager` holds the shared `WorktreeManager` (`this.worktrees`), passes `worktrees` + `isolation` into each `Agent` via `AgentInit`, and calls `this.worktrees.prune()` on `dispose()`.
-- `src/lifecycle/worktree.ts` — `WorktreeManager` interface + `GitWorktreeManager` impl + free functions.
-  `WorktreeManager.cleanup(wt, description)` mutates `wt.branch` in place (in `cleanupWorktree`), so the object passed must carry a writable `branch`.
-- `src/lifecycle/worktree-state.ts` — `WorktreeState`: holds `path`/`branch`, tracks `cleanupResult`, exposes `performCleanup(worktrees, description)`.
-  Re-exports `WorktreeCleanupResult` and `WorktreeInfo` (no external consumer imports those two from this path — verified by grep).
-- `src/service/service-adapter.ts:131` — reads `record.worktreeState?.cleanupResult` to populate `worktreeResult`.
-- `src/index.ts:167` — constructs `new GitWorktreeManager(process.cwd())` and passes it to `AgentManager`.
-
-AGENTS.md constraints that apply:
-
-- This package targets ES2024; Biome (not Prettier) formats.
-- Tests use `vi.hoisted(...)` patterns; the full vitest suite must pass before publishing.
-- When a barrel/module gains exports, verify a consumer imports them — fallow flags speculative re-exports.
-  Here we are removing a module, not adding one, so the risk is dangling imports rather than dead exports.
-
-## Design Overview
-
-### Decision model
-
-`AgentManager` owns the shared `WorktreeManager` (one instance, repo-root-bound).
-Per spawn, when `isolation === "worktree"`, it constructs a per-agent `WorktreeIsolation` bound to that `WorktreeManager` and the agent id, and hands it to `Agent`.
-When isolation is not requested, no collaborator is created and `Agent.worktree` is `undefined`.
-
-`Agent` no longer knows the isolation mode or the `WorktreeManager`.
-The presence/absence of the collaborator *is* the mode: `this.worktree?.setup()` and `this.worktree?.cleanup(...)`.
-
-### WorktreeIsolation shape
-
-```typescript
-// src/lifecycle/worktree-isolation.ts
-import type { WorktreeCleanupResult, WorktreeInfo, WorktreeManager } from "#src/lifecycle/worktree";
-
-export class WorktreeIsolation {
-	private _info?: WorktreeInfo;
-	private _cleanupResult?: WorktreeCleanupResult;
-
-	constructor(
-		private readonly worktrees: WorktreeManager,
-		private readonly agentId: string,
-	) {}
-
-	/** Absolute worktree path — undefined before setup(). */
-	get path(): string | undefined {
-		return this._info?.path;
-	}
-
-	/** Cleanup outcome — undefined until cleanup() runs. */
-	get cleanupResult(): WorktreeCleanupResult | undefined {
-		return this._cleanupResult;
-	}
-
-	/**
-	 * Create the git worktree and store its info.
-	 * Throws on failure (strict isolation — no silent fallback).
-	 */
-	setup(): void {
-		const wt = this.worktrees.create(this.agentId);
-		if (!wt) {
-			throw new Error(
-				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
-				"Initialize git and commit at least once, or omit `isolation`.",
-			);
-		}
-		this._info = wt;
-	}
-
-	/** Perform cleanup and record the result. No-op ({ hasChanges: false }) if setup never ran. */
-	cleanup(description: string): WorktreeCleanupResult {
-		if (!this._info) return { hasChanges: false };
-		const result = this.worktrees.cleanup(this._info, description);
-		this._cleanupResult = result;
-		return result;
-	}
-}
-```
-
-Notes:
-
-- `_info` is a mutable `WorktreeInfo`, so `WorktreeManager.cleanup` mutating `branch` in place keeps working (the same behavior `WorktreeState` relied on today).
-- The `missing worktrees dependency` error from `setupWorktree()` disappears: the collaborator is only ever created with a `WorktreeManager`, so that defensive branch is structurally impossible.
-- `cleanup()` returns `{ hasChanges: false }` when `setup()` never ran, so `Agent`'s `completeRun()`/`failRun()` can call it unconditionally via the optional-chain without a separate guard.
-
-### Agent call sites (Tell-Don't-Ask)
-
-`Agent.run()` setup:
-
-```typescript
-try {
-	this.worktree?.setup();   // was: this.setupWorktree() with internal mode check
-} catch (err) {
-	this.markError(err);
-	this.releaseListeners();
-	this.observer?.onRunFinished?.(this);
-	return;
-}
-// ...
-cwd: this.worktree?.path,   // was: this.worktreeState?.path
-```
-
-`Agent.completeRun()`:
-
-```typescript
-let finalResult = result.responseText;
-const wtResult = this.worktree?.cleanup(this.description);
-if (wtResult?.hasChanges && wtResult.branch) {
-	finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
-}
-```
-
-`Agent.failRun()`:
-
-```typescript
-try {
-	this.worktree?.cleanup(this.description);
-} catch (cleanupErr) {
-	debugLog("cleanupWorktree on agent error", cleanupErr);
-}
-```
-
-`AgentManager.spawn()`:
-
-```typescript
-const worktree = options.isolation === "worktree"
-	? new WorktreeIsolation(this.worktrees, id)
-	: undefined;
-const record = new Agent({ /* ... */, worktree /* was: worktrees + isolation */ });
-```
-
-The reach-through `agent.worktreeState.cleanupResult` in `service-adapter.ts` becomes `agent.worktree?.cleanupResult` — the collaborator owns the result, so this is a single-hop access, not a reach-through into a phase object.
-
-### Edge cases
-
-- Isolation not requested → `worktree` is `undefined` → `setup()`/`cleanup()` are skipped via optional chaining; behavior identical to today's `_isolation !== "worktree"` early-return.
-- `create()` returns `undefined` (not a git repo) → `setup()` throws; `Agent.run()` catches, marks error, releases listeners, fires `onRunFinished`.
-  The existing AgentManager regression test (worktree fails loud, no silent fallback) is preserved.
-- Cleanup throws in `failRun()` → caught and logged best-effort, identical to today.
-
-## Module-Level Changes
-
-- New: `src/lifecycle/worktree-isolation.ts` — the `WorktreeIsolation` class (shape above).
-- Changed: `src/lifecycle/agent.ts`
-  - Remove imports of `WorktreeManager` (type) and `WorktreeState`; add import of `WorktreeIsolation`.
-  - `AgentInit`: remove `worktrees?: WorktreeManager` and `isolation?: IsolationMode`; add `worktree?: WorktreeIsolation`.
-    (`IsolationMode` may remain imported if still referenced elsewhere in the file; grep confirms it is only used for the removed field — remove the now-unused import.)
-  - Remove instance fields `_worktrees`, `_isolation`, `worktreeState`; add `worktree?: WorktreeIsolation`.
-  - Remove the `setupWorktree()` method.
-  - Constructor: replace the `_worktrees`/`_isolation` assignments with `this.worktree = init.worktree`.
-  - `run()`: `this.worktree?.setup()`; `cwd: this.worktree?.path`.
-  - `completeRun()` / `failRun()`: replace the 4-line `worktreeState && _worktrees` blocks with `this.worktree?.cleanup(this.description)`.
-  - Update the file header doc comment (lists `worktreeState` as a phase-specific collaborator).
-- Changed: `src/lifecycle/agent-manager.ts`
-  - Import `WorktreeIsolation`.
-  - `spawn()`: construct the per-agent `WorktreeIsolation` when `options.isolation === "worktree"`; pass `worktree` to `Agent` instead of `worktrees` + `isolation`.
-  - Keep `this.worktrees` field, `AgentManagerOptions.worktrees`, and the `dispose()` → `this.worktrees.prune()` call unchanged.
-- Changed: `src/service/service-adapter.ts`
-  - `record.worktreeState?.cleanupResult` → `record.worktree?.cleanupResult`.
-- Removed: `src/lifecycle/worktree-state.ts` (folded into `WorktreeIsolation`).
-- Doc updates (`docs/architecture/architecture.md`):
-  - Class diagram (line ~115): `+worktreeState?: WorktreeState` → `+worktree?: WorktreeIsolation`; remove the `+setupWorktree(...)` method line.
-  - Layout listing (lines ~279–280): replace `worktree-state.ts  worktree phase state` with `worktree-isolation.ts  worktree lifecycle collaborator`.
-- Doc update (`.pi/skills/package-pi-subagents/SKILL.md`): Lifecycle domain row — replace `worktree-state.ts` with `worktree-isolation.ts` (module count stays 9).
-
-Symbols removed and their consumers (grepped across `src/` and `test/`):
-
-- `WorktreeState` (class): `src/lifecycle/agent.ts` (removed in this plan), `test/lifecycle/agent.test.ts`, `test/service/service-adapter.test.ts`, `test/lifecycle/worktree-state.test.ts` — all updated/removed below.
-- `Agent.setupWorktree()`: only `test/lifecycle/agent.test.ts` — removed below.
-- `Agent.worktreeState`: `service-adapter.ts` + several tests — all migrated to `worktree`.
-- The `WorktreeCleanupResult`/`WorktreeInfo` re-exports from `worktree-state.ts`: no external importer (verified) — safe to drop.
-
-## Test Impact Analysis
-
-1. New unit tests enabled by the extraction: `WorktreeIsolation` is now independently testable without an `Agent` — `worktree-isolation.test.ts` covers `setup()` (success stores path; failure throws), `cleanup()` (delegates to `worktrees.cleanup` with stored info + description, records `cleanupResult`; no-op before setup), and `path`/`cleanupResult` getters.
-   These absorb the existing `worktree-state.test.ts` coverage (constructor, `recordCleanup`, `performCleanup`) at the same granularity.
-2. Existing tests that become redundant / simplified: `test/lifecycle/worktree-state.test.ts` is removed (its behavior is covered by the new collaborator tests).
-   The `Agent — setupWorktree` describe block in `agent.test.ts` is removed (the method is gone); its intent migrates to the `WorktreeIsolation` unit tests plus the existing `Agent.run() — worktree` integration tests.
-3. Existing tests that must stay (genuinely exercise the layer):
-   `test/lifecycle/worktree.test.ts` (git plumbing + `GitWorktreeManager`) is untouched.
-   `Agent.run() — worktree` integration tests stay but switch their assertions from `agent.worktreeState` to `agent.worktree` and construct the agent with a `WorktreeIsolation`.
-   `agent-manager.test.ts` worktree tests stay but assert via `record.worktree?.path` / `record.worktree?.cleanupResult`.
-
-## TDD Order
-
-1. Add `WorktreeIsolation` with unit tests — new module, no consumers yet.
-   Surface: `test/lifecycle/worktree-isolation.test.ts`.
-   Covers: `setup()` success/failure, `cleanup()` delegation + result recording + pre-setup no-op, `path`/`cleanupResult` getters (migrating `worktree-state.test.ts` coverage).
-   Commit: `test: add WorktreeIsolation collaborator tests` then `feat(pi-subagents): add WorktreeIsolation collaborator`. (May be a single `feat` commit with the test if preferred — the module is self-contained.)
-2. Wire `WorktreeIsolation` into `Agent` and `AgentManager`; drop the old fields.
-   This is one commit because TypeScript will not accept `AgentInit` losing `worktrees`/`isolation` while call sites still pass them.
-   Changes: `agent.ts` (remove `_worktrees`/`_isolation`/`worktreeState`/`setupWorktree`, add `worktree`, update `run`/`completeRun`/`failRun`), `agent-manager.ts` (construct collaborator in `spawn`), `service-adapter.ts` (`record.worktree?.cleanupResult`), and their tests (`agent.test.ts` helpers `createRunnableAgent`/`createAgentWithWorktrees` + worktree describe blocks; remove the `setupWorktree` block; `agent-manager.test.ts` worktree assertions; `service-adapter.test.ts` setup).
-   Commit: `refactor(pi-subagents): Agent delegates worktree lifecycle to WorktreeIsolation`.
-3. Delete the now-orphaned `WorktreeState`.
-   Remove `src/lifecycle/worktree-state.ts` and `test/lifecycle/worktree-state.test.ts`; remove any remaining `WorktreeState` imports.
-   Run `pnpm fallow dead-code` to confirm no dangling exports.
-   Commit: `refactor(pi-subagents): remove WorktreeState, folded into WorktreeIsolation`.
-4. Update architecture doc + package skill.
-   `docs/architecture/architecture.md` class diagram + layout listing; `SKILL.md` Lifecycle domain row.
-   Commit: `docs(pi-subagents): reflect WorktreeIsolation extraction in architecture`.
-
-After all steps: `pnpm run check`, `pnpm run lint`, `pnpm -r run test`, `pnpm fallow dead-code`.
-
-## Risks and Mitigations
-
-- Risk: `WorktreeManager.cleanup` mutates `branch` in place; folding `WorktreeState` could lose that behavior.
-  Mitigation: `WorktreeIsolation` stores a mutable `WorktreeInfo` (`_info`) and passes it directly to `cleanup`, preserving the in-place mutation.
-- Risk: a hidden consumer imports `WorktreeCleanupResult`/`WorktreeInfo` from `worktree-state.ts`.
-  Mitigation: grep confirms all consumers import those types from `worktree.ts`; the deletion step re-runs the grep and `pnpm run check`.
-- Risk: the combined Step 2 commit touches several test files at once.
-  Mitigation: the changes are mechanical and localized to worktree-specific helpers/describe blocks; the type checker pinpoints every call site.
-  The bulk of `agent.test.ts` is untouched.
-- Risk: AgentManager's `dispose()` prune path relies on `this.worktrees`.
-  Mitigation: `AgentManager` keeps ownership of the shared `WorktreeManager`; only per-agent collaborator construction is added.
-
-## Open Questions
-
-- Whether `setup()` should return the path (as `setupWorktree()` did) for symmetry.
-  Deferred: no caller needs the return value once `Agent` reads `this.worktree?.path`; keep `setup(): void` until a consumer needs otherwise.
-- Whether `WorktreeIsolation` should later absorb the parent `cwd`/repo-root concern from `GitWorktreeManager`.
-  Deferred to the broader Phase 16 collaborator work; out of scope for Step 1.