@gotgenes/pi-subagents 11.5.0 → 12.0.0

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

@@ -0,0 +1,106 @@
+---
+issue: 270
+issue_title: "Make @gotgenes/pi-subagents type-consumable by sibling workspace packages"
+---
+
+# Retro: #270 — Make @gotgenes/pi-subagents type-consumable by sibling workspace packages
+
+## Stage: Planning (2026-05-29T00:00:00Z)
+
+### Session summary
+
+Diagnosed the consumability failure empirically with `tsc --traceResolution` and planned a `.d.ts`-emit fix.
+The plan adds a `rollup-plugin-dts` build that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`, wires conditional `exports` (`types` → the bundle, `default` → the real source), generates the artifact at `prepack` time, ships it via a `files` allowlist, and proves external consumability with a `pnpm pack` → throwaway-consumer → `tsc` harness.
+
+### Observations
+
+- Root cause is two compounding failures: the stale `exports["."]` path (`./src/service.ts` does not exist) and, once fixed, an unresolvable `#src/*` cascade.
+  The trace showed the consumer's own `paths` (`#src/*` → `./src/*`) intercept first (both packages define `#src/*`), and the publisher's `imports`-field fallback cannot resolve the extensionless `.ts` target.
+- The public type closure is entangled: `WorkspaceProvider` → `AgentStatus` (in the 510-LOC `agent.ts`) → `types.ts` (which re-exports the `Agent` class).
+  This made the alias-free-entry alternative (Option 2) a substantial source restructure, so it was rejected.
+- Decisions taken via `ask_user`:
+  1. Approach — emit a bundled `.d.ts` (the repo's first build step), over alias-free restructure or type re-declaration.
+  2. Bundler — `rollup-plugin-dts` (purpose-built for flattening declarations; no JS bundle, which suits ship-source), over `tsdown`/`api-extractor`.
+  3. Artifact — not committed; generated at `prepack` and shipped in the tarball, consumed via the package interface.
+  4. Scope — tight: packaging + a `pnpm pack`-based verification harness in #270; defer the `pi-subagents-worktrees` registry-consumption flip (drop `workspace:*`, `link-workspace-packages: false`, wire the real import) to #263.
+- Scope was deliberately narrowed after a chicken-and-egg surfaced: the registry version carrying the fix does not exist until #270 publishes, so the meaningful consumer flip belongs to #263.
+- Sequencing constraint for #263 (captured in the plan): publish #270 first — merge its release-please PR so `pi-subagents` publishes — *before* resuming #263, otherwise #263's `pi-subagents` core edits batch into the same release.
+  The current `#263` scaffold commits on `main` touch only the unregistered `pi-subagents-worktrees` component, so they do not batch into `pi-subagents` and #270 ships cleanly.
+- Primary feasibility risk flagged: whether `rollup-plugin-dts` resolves `#src/*` while rolling up the type graph.
+  Build Step 1 is the explicit checkpoint (emit + assert the output is alias-free and exports the expected symbols).
+- `dist/` is gitignored and already excluded by eslint/biome; the new wrinkle is that a `files` allowlist is required so the gitignored `dist/public.d.ts` is included in the npm tarball — validate `pnpm pack --dry-run` parity so no currently-shipped file is dropped.
+
+## Stage: Implementation — Build (2026-05-29T00:00:00Z)
+
+### Session summary
+
+Executed all four build-order steps: added `rollup` + `rollup-plugin-dts` and a `build:types` script that bundles `src/service/service.ts` into a self-contained `dist/public.d.ts`; wired conditional `exports` (`types` + `default`, fixing the stale path) with a `prepack` hook and a `files` allowlist; added a `pnpm pack` → throwaway-consumer → `tsc` verification harness (`scripts/verify-public-types.sh`) plus a CI step; and recorded ADR 0003.
+A fifth commit documented the new build step in the `package-pi-subagents` skill (reviewer WARN).
+Root `pnpm run check`, root `pnpm run lint`, and `verify:public-types` all pass.
+
+### Observations
+
+- The primary feasibility risk (`rollup-plugin-dts` resolving `#src/*`) resolved cleanly out of the box: driving it with the package `tsconfig` (which carries the `#src/*` paths) produced a 178-line `dist/public.d.ts` with zero `#src/` residue and only `ThinkingLevel` kept external from `@earendil-works/pi-ai`.
+  No alias/path resolver plugin was needed.
+- Harness deviation (fixed in the same step): `pnpm add` in the isolated (`--ignore-workspace`) throwaway consumer exited non-zero with `ERR_PNPM_IGNORED_BUILDS` because it does not inherit the workspace `allowBuilds` approvals (`@google/genai`, `protobufjs`).
+  Fixed by adding `--ignore-scripts` — a type-check needs no dependency build scripts.
+  Worth remembering for any future packaged-consumer harness.
+- A subtle gotcha while debugging: `pnpm ... | tail; echo $?` reports `tail`'s exit, not pnpm's, which masked the real failure.
+  Use `set -o pipefail` or check the command directly.
+- `files` allowlist parity was validated with a before/after `pnpm pack --dry-run` diff: nothing dropped, only `dist/public.d.ts` added.
+  The allowlist reproduces the current contents (`src`, `docs`, `vitest.config.ts`, `AGENTS.md`, `CHANGELOG.md`, `.prettierignore`) plus `dist`.
+  Did not take the opportunity to slim the tarball (docs/test-config still ship) — that would be a separate deliberate change.
+- Runtime `default` → `./src/service/service.ts` is safe because that module's only internal imports are `import type`, which erase; no runtime `#src/*` resolution occurs.
+- 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,10 +1,22 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "11.5.0",
+  "version": "12.0.0",
   "type": "module",
   "exports": {
-    ".": "./src/service.ts"
+    ".": {
+      "types": "./dist/public.d.ts",
+      "default": "./src/service/service.ts"
+    }
   },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "vitest.config.ts",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    ".prettierignore"
+  ],
   "imports": {
     "#src/*": "./src/*",
     "#test/*": "./test/*"
@@ -51,6 +63,8 @@
     "@earendil-works/pi-coding-agent": "0.75.4",
     "@earendil-works/pi-tui": "0.75.4",
     "@types/node": "^22.15.3",
+    "rollup": "^4.60.4",
+    "rollup-plugin-dts": "^6.4.1",
     "rumdl": "^0.1.93",
     "typescript": "^6.0.3",
     "vitest": "^4.1.5"
@@ -64,6 +78,8 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "build:types": "rollup -c rollup.dts.config.mjs",
+    "verify:public-types": "bash scripts/verify-public-types.sh",
     "test": "vitest run",
     "test:watch": "vitest",
     "lint:md": "rumdl check *.md docs/**/*.md",

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;
-	}
-}