@gotgenes/pi-subagents 11.6.0 → 12.0.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [12.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.6.0...pi-subagents-v12.0.0) (2026-05-29)
+
+
+### ⚠ BREAKING CHANGES
+
+* SubagentRecord no longer carries worktreeResult, and the core no longer creates git worktrees. Worktree isolation moves to @gotgenes/pi-subagents-worktrees.
+* the Agent tool no longer accepts isolation: "worktree", and SubagentsService.SpawnOptions no longer has an isolation field. Install @gotgenes/pi-subagents-worktrees and list the agent in worktreeAgents instead.
+
+### Features
+
+* drop the isolation spawn axis from the subagents API ([2ff8970](https://github.com/gotgenes/pi-packages/commit/2ff897059feec67a49af7e3f54e0e4828faa2521))
+* remove git worktree isolation from the subagents core ([2e81044](https://github.com/gotgenes/pi-packages/commit/2e81044221562c528d1fb296f356f60d81af0661))
+
 ## [11.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.5.0...pi-subagents-v11.6.0) (2026-05-29)
 
 

package/dist/public.d.ts

@@ -20,8 +20,6 @@ type LifetimeUsage = {
 
 /** Agent type: any string name (built-in defaults or user-defined). */
 type SubagentType = string;
-/** Isolation mode for agent execution. */
-type IsolationMode = "worktree";
 interface AgentInvocation {
     /** Short display name, e.g. "haiku" — only set when different from parent. */
     modelName?: string;
@@ -30,7 +28,6 @@ interface AgentInvocation {
     isolated?: boolean;
     inheritContext?: boolean;
     runInBackground?: boolean;
-    isolation?: IsolationMode;
 }
 
 /**
@@ -43,11 +40,11 @@ interface AgentInvocation {
  * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
  * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
  *
- * Behavior (abort, steer buffering, worktree setup) lives on the agent
- * rather than on AgentManager — each agent manages its own lifecycle concerns.
+ * Behavior (abort, steer buffering) lives on the agent rather than on
+ * AgentManager — each agent manages its own lifecycle concerns.
  *
- * Worktree isolation is delegated to an optional WorktreeIsolation collaborator
- * (set at construction when isolation is requested); its presence IS the mode.
+ * 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
  * after construction as lifecycle information becomes available.
@@ -121,10 +118,6 @@ interface SubagentRecord {
     completedAt?: number;
     lifetimeUsage: LifetimeUsage;
     compactionCount: number;
-    worktreeResult?: {
-        hasChanges: boolean;
-        branch?: string;
-    };
 }
 /** Options for spawning an agent via the service. */
 interface SpawnOptions {
@@ -136,7 +129,6 @@ interface SpawnOptions {
     inheritContext?: boolean;
     foreground?: boolean;
     bypassQueue?: boolean;
-    isolation?: "worktree";
 }
 /** The public service contract for cross-extension subagent access. */
 interface SubagentsService {

package/docs/architecture/architecture.md

@@ -56,9 +56,9 @@ flowchart TB
         AgentManager["AgentManager<br/>(spawn, abort, collection)"]
         ConcurrencyQueue["ConcurrencyQueue<br/>(scheduling, drain)"]
         AgentRunner["agent-runner<br/>(session, turns, results)"]
-        Agent["Agent<br/>(status, behavior: abort/steer/worktree/run lifecycle)"]
+        Agent["Agent<br/>(status, behavior: abort/steer/run lifecycle)"]
         ParentSnapshot["ParentSnapshot<br/>(frozen parent state)"]
-        Worktree["worktree<br/>(git isolation)"]
+        Workspace["workspace<br/>(provider seam: child cwd + teardown)"]
     end
 
     subgraph observation["Observation domain"]
@@ -112,7 +112,6 @@ classDiagram
         +toolUses: number
         +lifetimeUsage: LifetimeUsage
         +execution?: ExecutionState
-        +worktree?: WorktreeIsolation
         +notification?: NotificationState
         +markRunning()
         +markCompleted()
@@ -270,14 +269,12 @@ src/
 ├── lifecycle/                      agent execution and state tracking
 │   ├── agent-manager.ts            collection manager + observer wiring
 │   ├── agent-runner.ts             session creation, turn loop, tool filtering
-│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, worktree)
+│   ├── agent.ts                    owns full execution lifecycle (run, abort, steer, workspace)
 │   ├── concurrency-queue.ts        background agent scheduling with configurable concurrency limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── execution-state.ts          session/output phase state
 │   ├── child-lifecycle.ts          child-execution lifecycle event publisher
 │   ├── workspace.ts                workspace provider seam (generative extension surface)
-│   ├── worktree.ts                 git worktree isolation
-│   ├── worktree-isolation.ts       worktree lifecycle collaborator
 │   └── usage.ts                    token usage tracking
 │
 ├── observation/                    progress tracking and notification
@@ -357,14 +354,14 @@ They declare this package as an optional peer dependency and use dynamic import
   Reactive consumers subscribe: `@gotgenes/pi-permission-system` registers each child session on `session-created` and unregisters it on `disposed`.
   This replaced the former outbound `permission-bridge` (#261, ADR 0002) — the core no longer looks up a named consumer.
 - `workspace` — the single generative seam (#262, ADR 0002): a registered `WorkspaceProvider` supplies a child's cwd plus bracketed `dispose()` at run-start.
-  With no provider, children run in the parent cwd (default unchanged); the git worktree strategy moves behind this seam in #263.
+  With no provider, children run in the parent cwd (default unchanged); the git worktree strategy lives behind this seam in `@gotgenes/pi-subagents-worktrees` (#263, the seam's first consumer).
 - `session-config` — pure configuration assembler (extracted from `agent-runner`).
 - `SubagentRuntime` — session-scoped state bag with methods.
 - `ParentSnapshot` — immutable snapshot of parent session state, captured once at spawn time.
 - `record-observer` — session-event observer that updates record statistics without callback threading.
 - Agent type registry — default agents, custom `.md` file loading.
 - Prompt assembly, context extraction, skills, environment.
-- Worktree isolation — moving to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (ADR 0002).
+- Worktree isolation — evicted to `@gotgenes/pi-subagents-worktrees` via the workspace provider seam in Phase 16 (#263, ADR 0002); `git` no longer appears in the core.
 - Token usage tracking.
 - Session directory derivation and persisted `SessionManager` for subagent transcripts.
 - Settings persistence.
@@ -418,7 +415,7 @@ Key types:
 
 - `SubagentsService` — `spawn`, `getRecord`, `listAgents`, `abort`, `steer`, `waitForAll`, `hasRunning`.
 - `SubagentRecord` — serializable agent snapshot (no live session objects).
-- `SpawnOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `isolated`, `inheritContext`, `foreground`, `bypassQueue`, `isolation`.
+- `SpawnOptions` — `description`, `model`, `maxTurns`, `thinkingLevel`, `isolated`, `inheritContext`, `foreground`, `bypassQueue`.
 - `SUBAGENT_EVENTS` — channel constants for `pi.events` subscriptions.
 
 ### Accessor pattern
@@ -501,7 +498,7 @@ Latent extensibility is the deliverable; a vacant hook is not.
 - **Extension filtering** (`extensions: string[]` allowlist) — tool visibility is pi-permission-system's job.
 - **Worktree isolation** (`worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, the `isolation: "worktree"` spawn mode) — environment policy, not core.
   Git worktrees are one *strategy* for choosing the child's working directory; containers, throwaway tmpdirs, and remote sandboxes are others.
-  These move to `@gotgenes/pi-subagents-worktrees`, the first consumer of the workspace provider seam.
+  Evicted to `@gotgenes/pi-subagents-worktrees` (#263), the first consumer of the workspace provider seam.
 - **Extension lifecycle control** (`extensions: false`, `isolated`, `noSkills`) — deny-at-use (the in-child permission layer blocking disallowed tool calls) covers what `isolated` pretended to do for tools.
   Prevent-load (refusing to bind an extension because of load-time side effects, cost, or true sandboxing) is genuinely generative and is left as a *latent* (un-built) provider seam, added only if a real consumer needs it.
 
@@ -608,7 +605,6 @@ interface SpawnExecution {
   inheritContext: boolean;
   runInBackground: boolean;
   isolated: boolean;
-  isolation: IsolationMode | undefined;
   agentInvocation: AgentInvocation;
 }
 
@@ -765,8 +761,8 @@ Migrate `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disp
 #### Step 2: Define the `WorkspaceProvider` seam — [#262] ✅ Delivered
 
 Added the `WorkspaceProvider` / `Workspace` interfaces (`src/lifecycle/workspace.ts`) and `SubagentsService.registerWorkspaceProvider` (single provider, throws on duplicate, returns an unregister disposer).
-Only `WorkspaceProvider` is named-re-exported from `service.ts`; `Workspace` and the context types resolve via inference when a consumer assigns to `WorkspaceProvider` (the worktrees package adds named re-exports in #263 when it imports them by name).
-At run-start `Agent.run()` consults the registered provider (provider-first precedence) for the child's cwd and a disposal handle; with no provider it falls back to the legacy worktree collaborator, and with neither the child runs in the parent's cwd.
+Only `WorkspaceProvider` is named-re-exported from `service.ts`; `Workspace` and the context types resolve via inference when a consumer assigns to `WorkspaceProvider` (named re-exports of the collaborator types are tracked in #272).
+At run-start `Agent.run()` consults the registered provider for the child's cwd and a disposal handle; with no provider the child runs in the parent's cwd (the legacy worktree-collaborator fallback was removed when worktrees left the core in #263).
 On completion the core calls `Workspace.dispose({ status, description })` and appends the returned `resultAddendum` verbatim — the provider owns the wording.
 
 - The seam is additive and non-breaking: the existing `isolation: "worktree"` path is untouched (its eviction is Step 3).
@@ -774,13 +770,15 @@ On completion the core calls `Workspace.dispose({ status, description })` and ap
   Within #262 the seam is exercised only by test fakes; do not cut a release containing the seam without `@gotgenes/pi-subagents-worktrees`.
 - Outcome: a single generative seam; the core no longer knows what an "isolation strategy" is.
 
-#### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263]
+#### Step 3: Extract worktrees to `@gotgenes/pi-subagents-worktrees` — [#263] ✅ Delivered
 
 New package implementing `WorkspaceProvider`: prepares a git worktree at run-start (born complete), tears it down after (saving the branch), and owns the "changes saved to branch" result.
-Remove `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; drop `isolation` from the spawn API and `SubagentsService`.
+Worktree isolation is opt-in per agent type via the package's own `worktreeAgents` config; creation failure for an opted-in agent throws (strict, no silent fallback).
+Removed `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, and the `isolation: "worktree"` mode from the core; dropped `isolation` from the spawn API and `SubagentsService`, and `worktreeResult` from `SubagentRecord`.
 
 - Supersedes #256.
-  New package registered in `release-please-config.json`; peer-depends on `@gotgenes/pi-subagents`.
+  New package registered in `release-please-config.json` and `.pi/settings.json` (after pi-subagents); consumes the published `@gotgenes/pi-subagents` from the registry (`linkWorkspacePackages: false`), since `exports.types` resolves to the shipped declaration bundle.
+  Only `WorkspaceProvider` is importable by name from 11.6.0; the collaborator types are recovered via inference until #272 adds named re-exports.
 - Outcome: git leaves the core; worktree users install one package, everyone else pays nothing.
 
 #### Step 4: Remove `isolated` / `extensions: false` / `noSkills` — [#264]

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

@@ -54,3 +54,53 @@ Root `pnpm run check`, root `pnpm run lint`, and `verify:public-types` all pass.
 - No `src/`/`test/` `.ts` files were touched, so the vitest suite and `tsc` were unaffected (confirmed via root check).
 - Pre-completion reviewer: WARN — no findings attributable to this session.
   Reviewer warnings: (1) the `package-pi-subagents` skill lacked a build-step note — addressed in commit `2ff5a375`; (2) `pnpm fallow dead-code` exits non-zero on a pre-existing finding in `packages/pi-subagents-worktrees/package.json` from the #263 scaffold (commit `9a7dcfc5`), out of scope for #270 and left for #263.
+
+## Stage: Final Retrospective (2026-05-29T21:00:00Z)
+
+### Session summary
+
+Shipped #270 end-to-end across planning, build, and ship stages: diagnosed the cross-package type-resolution failure empirically, built a `rollup-plugin-dts` declaration bundle plus a pack-based verification harness, and published `@gotgenes/pi-subagents@11.6.0` (tag `pi-subagents-v11.6.0`).
+Two CI failures during the ship stage — a pre-existing `pnpm fallow dead-code` gate and lockfile drift — required two extra fix commits before CI went green.
+
+### Observations
+
+#### What went well
+
+- Empirical-first diagnosis: `tsc --traceResolution` in planning pinned the exact two-part failure (consumer `paths` collision + the publisher's `imports`-field extensionless-`.ts` miss) and directly justified the chosen `.d.ts`-emit approach over the alias-free restructure.
+- The flagged primary risk evaporated: `rollup-plugin-dts` resolved `#src/*` out of the box via the package `tsconfig` paths, producing a clean 178-line `dist/public.d.ts` with no resolver plugin.
+- Novel, reusable pattern: `scripts/verify-public-types.sh` proves a ship-source package is externally type-consumable via `pnpm pack` → throwaway-consumer → `tsc`, with no publish round-trip.
+  Worth promoting if other packages grow public surfaces.
+- Disciplined `ask_user` use on the genuinely ambiguous decisions (approach, bundler, artifact handling, scope), with strong user steering — the `tsup`-is-unmaintained redirect to `rollup-plugin-dts`, the "no workspace trickery / use released versions" directive, and the #263 chicken-and-egg catch that correctly narrowed scope.
+
+#### What caused friction (agent side)
+
+- `missing-context` — Pushed to `main` with a pre-existing `pnpm fallow dead-code` failure (unused `@earendil-works/pi-coding-agent` devDependency in `packages/pi-subagents-worktrees/package.json`, from the #263 scaffold).
+  The pre-completion reviewer reported it as `FAIL` but labelled it out-of-scope, and I accepted that framing and pushed.
+  The CI `Fallow dead-code gate` runs `if: github.ref == 'refs/heads/main'` — a hard gate that fires on every `main` push regardless of who introduced the failure — so CI failed (run `26659647270`).
+  Impact: 2 fix commits (`7e7afadd`, `10e74f2f`) and 2 extra CI cycles (~10 min).
+  The ship pre-push step runs only `pnpm run lint`, never `pnpm fallow dead-code`.
+- `missing-context` — Removed the devDependency and committed/pushed `package.json` (`7e7afadd`) without the updated `pnpm-lock.yaml`.
+  CI's `pnpm install --frozen-lockfile` failed with `ERR_PNPM_OUTDATED_LOCKFILE` (run `26659851716`).
+  Impact: 1 extra commit (`10e74f2f`) and 1 extra CI cycle.
+  Self-identified from the CI log.
+- `rabbit-hole` (minor) — While debugging the harness's `ERR_PNPM_IGNORED_BUILDS`, the `pnpm ... | tail; echo $?` idiom reported `tail`'s exit code, masking pnpm's real failure; took ~4 tool calls before tracing with `bash -x`.
+  Impact: added friction, no rework.
+
+#### What caused friction (user side)
+
+- The "pi-subagents-* extensions should use the released, npm-installed version, no workspace trickery" directive arrived mid-planning, after initial exploration.
+  Surfacing the consumption-model constraint at kickoff would have framed the scope question earlier.
+  Opportunity, not criticism — the same exchange produced the high-value chicken-and-egg catch (the registry version with the fix cannot exist until #270 publishes) that correctly deferred the worktrees flip to #263.
+- A brief "there is no ADR 0003" → "My mistake" exchange; no rework.
+
+### Diagnostic details
+
+- Model-performance correlation — the lone subagent dispatch (`pre-completion-reviewer`) ran on `anthropic/claude-sonnet-4-6`, appropriate for judgment-heavy review.
+  The dead-code-gate framing miss was a protocol-scope issue (pre-existing vs blocking), not a model-capability mismatch.
+- Escalation-delay — no error sequence exceeded 5 consecutive tool calls; the harness `ERR_PNPM_IGNORED_BUILDS` resolved in ~4.
+- Feedback-loop gap — build-stage verification ran incrementally after each step (good); the gap was at ship: the pre-push check omits the `main`-only gates (`pnpm fallow dead-code`) and lockfile validation that CI enforces, so a locally-clean `pnpm run lint` still failed CI twice.
+
+### Changes made
+
+1. `.pi/prompts/ship-issue.md` — renamed Step 2 to "Pre-push checks" and added `pnpm fallow dead-code` alongside `pnpm run lint`, with a one-line note that the gate is `main`-only and blocks pushes regardless of who introduced the failure.
+2. `AGENTS.md` (§ Code Style pnpm rules) — added a rule to run `pnpm install` and commit the updated `pnpm-lock.yaml` in the same commit when a `package.json` dependency changes, since CI installs with `--frozen-lockfile`.

package/package.json

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

package/src/config/custom-agents.ts

@@ -68,7 +68,6 @@ function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "pro
       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,
-      isolation: fm.isolation === "worktree" ? "worktree" : undefined,
       enabled: fm.enabled !== false,  // default true; explicitly false disables
       source,
     });

package/src/config/invocation-config.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig, IsolationMode, ThinkingLevel } from "#src/types";
+import type { AgentConfig, ThinkingLevel } from "#src/types";
 
 interface AgentInvocationParams {
   model?: string;
@@ -7,7 +7,6 @@ interface AgentInvocationParams {
   run_in_background?: boolean;
   inherit_context?: boolean;
   isolated?: boolean;
-  isolation?: IsolationMode;
 }
 
 export function resolveAgentInvocationConfig(
@@ -21,7 +20,6 @@ export function resolveAgentInvocationConfig(
   inheritContext: boolean;
   runInBackground: boolean;
   isolated: boolean;
-  isolation?: IsolationMode;
 } {
   return {
     modelInput: agentConfig?.model ?? params.model,
@@ -31,6 +29,5 @@ export function resolveAgentInvocationConfig(
     inheritContext: agentConfig?.inheritContext ?? params.inherit_context ?? false,
     runInBackground: agentConfig?.runInBackground ?? params.run_in_background ?? false,
     isolated: agentConfig?.isolated ?? params.isolated ?? false,
-    isolation: agentConfig?.isolation ?? params.isolation,
   };
 }

package/src/index.ts

@@ -28,7 +28,6 @@ import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runne
 import { createChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import { GitWorktreeManager } from "#src/lifecycle/worktree";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
 import { createNotificationRenderer } from "#src/observation/renderer";
 import { createSubagentRuntime } from "#src/runtime";
@@ -166,7 +165,6 @@ export default function (pi: ExtensionAPI) {
 
   const manager = new AgentManager({
     runner: new ConcreteAgentRunner(runnerDeps),
-    worktrees: new GitWorktreeManager(process.cwd()),
     baseCwd: process.cwd(),
     observer,
     queue,

package/src/lifecycle/agent-manager.ts

@@ -14,11 +14,9 @@ import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorkspaceProvider } from "#src/lifecycle/workspace";
-import type { WorktreeManager } from "#src/lifecycle/worktree";
-import { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Observer interface for agent lifecycle notifications. */
 export interface AgentManagerObserver {
@@ -31,7 +29,6 @@ export interface AgentManagerObserver {
 
 export interface AgentManagerOptions {
   runner: AgentRunner;
-  worktrees: WorktreeManager;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
   queue: ConcurrencyQueue;
   /** Base working directory handed to a workspace provider (the parent cwd). */
@@ -54,8 +51,6 @@ export interface AgentSpawnConfig {
    * callers (e.g. cross-extension RPC) that must not be deferred by the queue.
    */
   bypassQueue?: boolean;
-  /** Isolation mode - "worktree" creates a temp git worktree for the agent. */
-  isolation?: IsolationMode;
   /** Resolved invocation snapshot captured for UI display. */
   invocation?: AgentInvocation;
   /** Parent abort signal - when aborted, the subagent is also stopped. */
@@ -71,7 +66,6 @@ export class AgentManager {
   private cleanupInterval: ReturnType<typeof setInterval>;
   private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
-  private readonly worktrees: WorktreeManager;
   private readonly queue: ConcurrencyQueue;
   private readonly baseCwd: string;
   private getRunConfig?: () => RunConfig;
@@ -84,7 +78,6 @@ export class AgentManager {
 
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
-    this.worktrees = options.worktrees;
     this.queue = options.queue;
     this.baseCwd = options.baseCwd;
     this.observer = options.observer;
@@ -162,10 +155,6 @@ export class AgentManager {
       signal: options.signal,
       // Shared deps
       runner: this.runner,
-      worktree:
-        options.isolation === "worktree"
-          ? new WorktreeIsolation(this.worktrees, id)
-          : undefined,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
       baseCwd: this.baseCwd,
@@ -322,7 +311,5 @@ export class AgentManager {
       record.session?.dispose();
     }
     this.agents.clear();
-    // Prune any orphaned git worktrees (crash recovery)
-    try { this.worktrees.prune(); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }

package/src/lifecycle/agent.ts

@@ -8,11 +8,11 @@
  * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
  * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
  *
- * Behavior (abort, steer buffering, worktree setup) lives on the agent
- * rather than on AgentManager — each agent manages its own lifecycle concerns.
+ * Behavior (abort, steer buffering) lives on the agent rather than on
+ * AgentManager — each agent manages its own lifecycle concerns.
  *
- * Worktree isolation is delegated to an optional WorktreeIsolation collaborator
- * (set at construction when isolation is requested); its presence IS the mode.
+ * 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
  * after construction as lifecycle information becomes available.
@@ -27,7 +27,6 @@ import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
-import type { WorktreeIsolation } from "#src/lifecycle/worktree-isolation";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
@@ -70,7 +69,6 @@ export interface AgentInit {
 
 	// Shared deps (required for run(), optional for tests)
 	runner?: AgentRunner;
-	worktree?: WorktreeIsolation;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 	/** Resolves the registered workspace provider (if any) at run-start. */
@@ -130,8 +128,6 @@ export class Agent {
 
 	// Shared deps — optional (required for run())
 	private readonly _runner?: AgentRunner;
-	/** Worktree isolation collaborator — present only when isolation: "worktree". */
-	readonly worktree?: WorktreeIsolation;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
@@ -192,7 +188,6 @@ export class Agent {
 
 		// Shared deps
 		this._runner = init.runner;
-		this.worktree = init.worktree;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
 		this._getWorkspaceProvider = init.getWorkspaceProvider;
@@ -215,8 +210,8 @@ export class Agent {
 	}
 
 	/**
-	 * Execute the full agent lifecycle: worktree setup, runner invocation,
-	 * session-creation handling, observer wiring, worktree cleanup, and
+	 * Execute the full agent lifecycle: workspace preparation, runner invocation,
+	 * session-creation handling, observer wiring, workspace disposal, and
 	 * status transitions.
 	 *
 	 * Requires runner and snapshot to be set at construction.
@@ -236,8 +231,8 @@ export class Agent {
 
 		let cwd: string | undefined;
 		try {
-			// Provider-first: a registered workspace provider supplies the cwd and
-			// owns teardown; otherwise fall back to the legacy worktree collaborator.
+			// A registered workspace provider supplies the child's cwd and owns its
+			// teardown; with no provider the child runs in the parent cwd.
 			const provider = this._getWorkspaceProvider?.();
 			if (provider) {
 				this._workspace = await provider.prepare({
@@ -247,9 +242,6 @@ export class Agent {
 					invocation: this.invocation,
 				});
 				cwd = this._workspace?.cwd;
-			} else {
-				this.worktree?.setup();
-				cwd = this.worktree?.path;
 			}
 		} catch (err) {
 			this.markError(err);
@@ -463,7 +455,7 @@ export class Agent {
 		this._detachFn = undefined;
 	}
 
-	/** Complete a run: release listeners, worktree cleanup, status transition, execution update, notify observer. */
+	/** Complete a run: release listeners, dispose the workspace, status transition, execution update, notify observer. */
 	completeRun(result: RunResult): void {
 		this.releaseListeners();
 
@@ -476,11 +468,6 @@ export class Agent {
 					: "completed";
 			const disposeResult = this._workspace.dispose({ status: finalStatus, description: this.description });
 			if (disposeResult?.resultAddendum) finalResult += disposeResult.resultAddendum;
-		} else {
-			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}\``;
-			}
 		}
 
 		if (result.aborted) this.markAborted(finalResult);
@@ -495,14 +482,13 @@ export class Agent {
 		this.observer?.onRunFinished?.(this);
 	}
 
-	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, notify observer. */
+	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);
 		this.releaseListeners();
 
 		try {
 			if (this._workspace) this._workspace.dispose({ status: "error", description: this.description });
-			else this.worktree?.cleanup(this.description);
 		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
 
 		this.observer?.onRunFinished?.(this);

package/src/service/service-adapter.ts

@@ -69,7 +69,6 @@ export class SubagentsServiceAdapter implements SubagentsService {
       isolated: options?.isolated,
       inheritContext: options?.inheritContext,
       bypassQueue: options?.bypassQueue,
-      isolation: options?.isolation,
       isBackground,
     });
   }
@@ -134,8 +133,6 @@ export function toSubagentRecord(record: Agent): SubagentRecord {
   if (record.result !== undefined) out.result = record.result;
   if (record.error !== undefined) out.error = record.error;
   if (record.completedAt !== undefined) out.completedAt = record.completedAt;
-  const worktreeResult = record.worktree?.cleanupResult;
-  if (worktreeResult !== undefined) out.worktreeResult = worktreeResult;
 
   return out;
 }

package/src/service/service.ts

@@ -14,8 +14,9 @@ import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
 // Generative extension seam (ADR 0002, Phase 16 Step 2). Only the provider
 // entry-point type is re-exported here; a consumer assigning to
-// `WorkspaceProvider` gets `Workspace` and the context types via inference.
-// The worktrees package (#263) adds named re-exports when it imports them.
+// `WorkspaceProvider` recovers `Workspace` and the context types via inference
+// (e.g. `Parameters<WorkspaceProvider["prepare"]>[0]`). Named re-exports of
+// those collaborator types are tracked in #272.
 export type { LifetimeUsage, WorkspaceProvider };
 
 export type SubagentStatus =
@@ -40,7 +41,6 @@ export interface SubagentRecord {
   completedAt?: number;
   lifetimeUsage: LifetimeUsage;
   compactionCount: number;
-  worktreeResult?: { hasChanges: boolean; branch?: string };
 }
 
 /** Options for spawning an agent via the service. */
@@ -53,7 +53,6 @@ export interface SpawnOptions {
   inheritContext?: boolean;
   foreground?: boolean;
   bypassQueue?: boolean;
-  isolation?: "worktree";
 }
 
 /** The public service contract for cross-extension subagent access. */

package/src/tools/agent-tool.ts

@@ -179,7 +179,7 @@ Guidelines:
 - Use model to specify a different model (as "provider/modelId", or fuzzy e.g. "haiku", "sonnet").
 - Use thinking to control extended thinking level.
 - Use inherit_context if the agent needs the parent conversation history.
-- Use isolation: "worktree" to run the agent in an isolated git worktree (safe parallel file modifications).`,
+`,
 			parameters: Type.Object({
 				prompt: Type.String({
 					description: "The task for the agent to perform.",
@@ -231,12 +231,6 @@ Guidelines:
 							"If true, fork parent conversation into the agent. Default: false (fresh context).",
 					}),
 				),
-				isolation: Type.Optional(
-					Type.Literal("worktree", {
-						description:
-							'Set to "worktree" to run the agent in a temporary git worktree (isolated copy of the repo). Changes are saved to a branch on completion.',
-					}),
-				),
 			}),
 
 			// ---- Custom rendering: Claude Code style ----

package/src/tools/background-spawner.ts

@@ -52,7 +52,6 @@ export function spawnBackground(
       inheritContext: execution.inheritContext,
       thinkingLevel: execution.thinking,
       isBackground: true,
-      isolation: execution.isolation,
       invocation: execution.agentInvocation,
       observer: {
         onSessionCreated: (_agent, session) => {

package/src/tools/foreground-runner.ts

@@ -105,7 +105,6 @@ export async function runForeground(
         isolated: execution.isolated,
         inheritContext: execution.inheritContext,
         thinkingLevel: execution.thinking,
-        isolation: execution.isolation,
         invocation: execution.agentInvocation,
         signal,
         parentSession: params.parentSession,

package/src/tools/spawn-config.ts

@@ -12,7 +12,7 @@ import type { AgentTypeRegistry } from "#src/config/agent-types";
 import { resolveAgentInvocationConfig } from "#src/config/invocation-config";
 import { normalizeMaxTurns } from "#src/lifecycle/agent-runner";
 import { resolveInvocationModel } from "#src/session/model-resolver";
-import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "#src/types";
+import type { AgentInvocation, SubagentType, ThinkingLevel } from "#src/types";
 import {
   type AgentDetails,
   buildInvocationTags,
@@ -44,7 +44,6 @@ export interface SpawnExecution {
   inheritContext: boolean;
   runInBackground: boolean;
   isolated: boolean;
-  isolation: IsolationMode | undefined;
   agentInvocation: AgentInvocation;
 }
 
@@ -104,7 +103,6 @@ export function resolveSpawnConfig(
   const inheritContext = resolvedConfig.inheritContext;
   const runInBackground = resolvedConfig.runInBackground;
   const isolated = resolvedConfig.isolated;
-  const isolation = resolvedConfig.isolation;
 
   // Compute display model name (only shown when different from parent)
   const parentModelId = modelInfo.parentModel?.id;
@@ -125,7 +123,6 @@ export function resolveSpawnConfig(
     isolated,
     inheritContext,
     runInBackground,
-    isolation,
   };
 
   const modeLabel = getPromptModeLabel(subagentType, registry);
@@ -151,7 +148,6 @@ export function resolveSpawnConfig(
       inheritContext,
       runInBackground,
       isolated,
-      isolation,
       agentInvocation,
     },
     presentation: { modelName, agentTags, detailBase },

package/src/types.ts

@@ -21,9 +21,6 @@ export interface SubscribableSession {
 /** Agent type: any string name (built-in defaults or user-defined). */
 export type SubagentType = string;
 
-/** Isolation mode for agent execution. */
-export type IsolationMode = "worktree";
-
 /** UI display and agent listing — name, display name, description, prompt mode. */
 export interface AgentIdentity {
   name: string;
@@ -55,8 +52,6 @@ export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   runInBackground?: boolean;
   /** Default for spawn: no extension tools. undefined = caller decides. */
   isolated?: boolean;
-  /** Isolation mode — "worktree" runs the agent in a temporary git worktree */
-  isolation?: IsolationMode;
   /** true = this is an embedded default agent (informational) */
   isDefault?: boolean;
   /** false = agent is hidden from the registry */
@@ -73,7 +68,6 @@ export interface AgentInvocation {
   isolated?: boolean;
   inheritContext?: boolean;
   runInBackground?: boolean;
-  isolation?: IsolationMode;
 }
 
 /**

package/src/ui/agent-config-editor.ts

@@ -54,7 +54,6 @@ export function buildEjectContent(cfg: AgentConfig): string {
   if (cfg.inheritContext) fmFields.push("inherit_context: true");
   if (cfg.runInBackground) fmFields.push("run_in_background: true");
   if (cfg.isolated) fmFields.push("isolated: true");
-  if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
   return `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
 }
 

package/src/ui/agent-creation-wizard.ts

@@ -109,7 +109,6 @@ skills: <true (inherit all), false (none), or comma-separated skill names to pre
 inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
 run_in_background: <true to run in background by default. Default: false>
 isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
-isolation: <"worktree" to run in isolated git worktree. Omit for normal>
 ---
 
 <system prompt body — instructions for the agent>

package/src/ui/display.ts

@@ -136,7 +136,6 @@ export function buildInvocationTags(
   if (!invocation) return { tags };
   if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
   if (invocation.isolated) tags.push("isolated");
-  if (invocation.isolation === "worktree") tags.push("worktree");
   if (invocation.inheritContext) tags.push("inherit context");
   if (invocation.runInBackground) tags.push("background");
   if (invocation.maxTurns != null) tags.push(`max turns: ${invocation.maxTurns}`);

package/src/lifecycle/worktree-isolation.ts

@@ -1,59 +0,0 @@
-/**
- * worktree-isolation.ts — WorktreeIsolation: collaborator that owns the
- * git-worktree lifecycle for an isolated agent.
- *
- * Constructed by AgentManager only when isolation === "worktree", bound to a
- * WorktreeManager and the agent id. Agent tells it `setup()` and
- * `cleanup(description)` instead of managing worktree internals itself.
- *
- * The presence/absence of this collaborator IS the isolation mode: Agent calls
- * `this.worktree?.setup()` rather than checking an isolation string.
- */
-
-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 worktree cleanup and record the result.
-	 * No-op returning { 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;
-	}
-}

package/src/lifecycle/worktree.ts

@@ -1,194 +0,0 @@
-/**
- * worktree.ts — Git worktree isolation for agents.
- *
- * Creates a temporary git worktree so the agent works on an isolated copy of the repo.
- * On completion, if no changes were made, the worktree is cleaned up.
- * If changes exist, a branch is created and returned in the result.
- */
-
-import { execFileSync } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { debugLog } from "#src/debug";
-
-export interface WorktreeInfo {
-  /** Absolute path to the worktree directory. */
-  path: string;
-  /** Branch name created for this worktree (if changes exist). */
-  branch: string;
-}
-
-export interface WorktreeCleanupResult {
-  /** Whether changes were found in the worktree. */
-  hasChanges: boolean;
-  /** Branch name if changes were committed. */
-  branch?: string;
-  /** Worktree path if it was kept. */
-  path?: string;
-}
-
-/**
- * Create a temporary git worktree for an agent.
- * Returns the worktree path, or undefined if not in a git repo.
- */
-export function createWorktree(cwd: string, agentId: string): WorktreeInfo | undefined {
-  // Verify we're in a git repo with at least one commit (HEAD must exist)
-  try {
-    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe", timeout: 5000 });
-    execFileSync("git", ["rev-parse", "HEAD"], { cwd, stdio: "pipe", timeout: 5000 });
-  } catch (err) {
-    debugLog("createWorktree git rev-parse", err);
-    return undefined;
-  }
-
-  const branch = `pi-agent-${agentId}`;
-  const suffix = randomUUID().slice(0, 8);
-  const worktreePath = join(tmpdir(), `pi-agent-${agentId}-${suffix}`);
-
-  try {
-    // Create detached worktree at HEAD
-    execFileSync("git", ["worktree", "add", "--detach", worktreePath, "HEAD"], {
-      cwd,
-      stdio: "pipe",
-      timeout: 30000,
-    });
-    return { path: worktreePath, branch };
-  } catch (err) {
-    debugLog("git worktree add", err);
-    return undefined;
-  }
-}
-
-/**
- * Clean up a worktree after agent completion.
- * - If no changes: remove worktree entirely.
- * - If changes exist: create a branch, commit changes, return branch info.
- */
-export function cleanupWorktree(
-  cwd: string,
-  worktree: WorktreeInfo,
-  agentDescription: string,
-): WorktreeCleanupResult {
-  if (!existsSync(worktree.path)) {
-    return { hasChanges: false };
-  }
-
-  try {
-    // Check for uncommitted changes in the worktree
-    const status = execFileSync("git", ["status", "--porcelain"], {
-      cwd: worktree.path,
-      stdio: "pipe",
-      timeout: 10000,
-    }).toString().trim();
-
-    if (!status) {
-      // No changes — remove worktree
-      removeWorktree(cwd, worktree.path);
-      return { hasChanges: false };
-    }
-
-    // Changes exist — stage, commit, and create a branch
-    execFileSync("git", ["add", "-A"], { cwd: worktree.path, stdio: "pipe", timeout: 10000 });
-    // Truncate description for commit message (no shell sanitization needed — execFileSync uses argv)
-    const safeDesc = agentDescription.slice(0, 200);
-    const commitMsg = `pi-agent: ${safeDesc}`;
-    execFileSync("git", ["commit", "-m", commitMsg], {
-      cwd: worktree.path,
-      stdio: "pipe",
-      timeout: 10000,
-    });
-
-    // Create a branch pointing to the worktree's HEAD.
-    // If the branch already exists, append a suffix to avoid overwriting previous work.
-    let branchName = worktree.branch;
-    try {
-      execFileSync("git", ["branch", branchName], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 5000,
-      });
-    } catch (err) {
-      debugLog("git branch", err);
-      branchName = `${worktree.branch}-${Date.now()}`;
-      execFileSync("git", ["branch", branchName], {
-        cwd: worktree.path,
-        stdio: "pipe",
-        timeout: 5000,
-      });
-    }
-    // Update branch name in worktree info for the caller
-    worktree.branch = branchName;
-
-    // Remove the worktree (branch persists in main repo)
-    removeWorktree(cwd, worktree.path);
-
-    return {
-      hasChanges: true,
-      branch: worktree.branch,
-      path: worktree.path,
-    };
-  } catch (err) {
-    debugLog("cleanupWorktree", err);
-    try { removeWorktree(cwd, worktree.path); } catch (removeErr) { debugLog("removeWorktree on cleanup error", removeErr); }
-    return { hasChanges: false };
-  }
-}
-
-/**
- * Force-remove a worktree.
- */
-function removeWorktree(cwd: string, worktreePath: string): void {
-  try {
-    execFileSync("git", ["worktree", "remove", "--force", worktreePath], {
-      cwd,
-      stdio: "pipe",
-      timeout: 10000,
-    });
-  } catch (err) {
-    debugLog("git worktree remove", err);
-    try {
-      execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
-    } catch (pruneErr) { debugLog("git worktree prune", pruneErr); }
-  }
-}
-
-/**
- * Prune any orphaned worktrees (crash recovery).
- */
-export function pruneWorktrees(cwd: string): void {
-  try {
-    execFileSync("git", ["worktree", "prune"], { cwd, stdio: "pipe", timeout: 5000 });
-  } catch (err) { debugLog("pruneWorktrees", err); }
-}
-
-/**
- * Interface for managing git worktrees relative to a fixed repository root.
- * Callers do not thread `cwd` per call — it is captured at construction time.
- */
-export interface WorktreeManager {
-  create(id: string): WorktreeInfo | undefined;
-  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult;
-  prune(): void;
-}
-
-/**
- * Concrete implementation of WorktreeManager backed by the free functions in this module.
- * Captures `cwd` (the repository root) at construction and delegates each method.
- */
-export class GitWorktreeManager implements WorktreeManager {
-  constructor(private readonly cwd: string) {}
-
-  create(id: string): WorktreeInfo | undefined {
-    return createWorktree(this.cwd, id);
-  }
-
-  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult {
-    return cleanupWorktree(this.cwd, wt, description);
-  }
-
-  prune(): void {
-    pruneWorktrees(this.cwd);
-  }
-}