@gotgenes/pi-subagents 11.4.0 → 11.5.0

package/CHANGELOG.md

@@ -5,6 +5,14 @@ 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).
 
+## [11.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.4.0...pi-subagents-v11.5.0) (2026-05-29)
+
+
+### Features
+
+* add WorkspaceProvider registration seam to subagents service ([51a9970](https://github.com/gotgenes/pi-packages/commit/51a99701db214c11f08251e9ed5549d01c4d5839))
+* consult workspace provider for child cwd and disposal ([32eeffc](https://github.com/gotgenes/pi-packages/commit/32eeffc1cc31bc7e403c25cdd116e2b351be4527))
+
 ## [11.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.3.0...pi-subagents-v11.4.0) (2026-05-29)
 
 

package/docs/architecture/architecture.md

@@ -275,6 +275,7 @@ src/
 │   ├── 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
@@ -355,6 +356,8 @@ They declare this package as an optional peer dependency and use dynamic import
 - `child-lifecycle` — publishes the child-execution lifecycle (`spawning`, `session-created` before `bindExtensions()`, `completed`, `disposed`) on `pi.events`.
   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.
 - `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.
@@ -719,6 +722,14 @@ See [phase-14-strip-policy.md](history/phase-14-strip-policy.md) for details.
 [#239]: https://github.com/gotgenes/pi-packages/issues/239
 [#242]: https://github.com/gotgenes/pi-packages/issues/242
 
+## Phase 15 (complete)
+
+Phase 15 evolved `Agent` from a passive state machine (`AgentRecord`) into an object that owns its entire execution lifecycle.
+Before Phase 15, `AgentManager` orchestrated everything: calling the runner, handling session creation, wiring observers, and cleaning up worktrees — reaching into Agent 10+ times across `spawn()` and `startAgent()`.
+After Phase 15, Agent is born complete with all dependencies and configuration, owns `run()` and `resume()`, and manages its own observer and worktree lifecycle.
+All six steps are closed: [#227], [#228], [#231], [#229], [#230], [#232].
+See [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md) for details.
+
 ## Improvement roadmap (Phase 16 — invert dependencies: extensions on a minimal core)
 
 Phase 16 reclaims its original intent — invert the core's outbound dependencies — and extends it: worktree isolation joins permissions as an *extension* on a minimal core, leaving pi-subagents a pure child-session orchestrator.
@@ -751,12 +762,16 @@ Migrate `@gotgenes/pi-permission-system` to subscribe to `session-created`/`disp
 - Outcome: the core stops reaching out to a named consumer; permission detection rides events.
 - Deferred: removing the now-caller-less `registerSubagentSession`/`unregisterSubagentSession` from `PermissionsService` → #267; registry-detected resume ("executing now" → "exists" semantics) → #265.
 
-#### Step 2: Define the `WorkspaceProvider` seam — [#262]
+#### Step 2: Define the `WorkspaceProvider` seam — [#262] ✅ Delivered
 
-Add the `WorkspaceProvider` / `Workspace` interfaces and `SubagentsService.registerWorkspaceProvider`.
-At run-start the core consults the registered provider (if any) for the child's cwd and a disposal handle; with no provider, the child runs in the parent's cwd.
+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.
+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).
 - Land alongside its first consumer (Step 3) to avoid a vacant hook — the "no vacant hooks" rule.
+  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]
@@ -895,4 +910,14 @@ The upstream test suite is run periodically as a regression canary for the agent
 [#217]: https://github.com/gotgenes/pi-packages/issues/217
 [#218]: https://github.com/gotgenes/pi-packages/issues/218
 [#219]: https://github.com/gotgenes/pi-packages/issues/219
+[#227]: https://github.com/gotgenes/pi-packages/issues/227
+[#228]: https://github.com/gotgenes/pi-packages/issues/228
+[#229]: https://github.com/gotgenes/pi-packages/issues/229
+[#230]: https://github.com/gotgenes/pi-packages/issues/230
 [#231]: https://github.com/gotgenes/pi-packages/issues/231
+[#232]: https://github.com/gotgenes/pi-packages/issues/232
+[#261]: https://github.com/gotgenes/pi-packages/issues/261
+[#262]: https://github.com/gotgenes/pi-packages/issues/262
+[#263]: https://github.com/gotgenes/pi-packages/issues/263
+[#264]: https://github.com/gotgenes/pi-packages/issues/264
+[#265]: https://github.com/gotgenes/pi-packages/issues/265

package/docs/plans/0262-add-workspace-provider-seam.md

@@ -0,0 +1,262 @@
+---
+issue: 262
+issue_title: "Add WorkspaceProvider extension seam"
+---
+
+# Add the WorkspaceProvider extension seam
+
+## Problem Statement
+
+Phase 16, Step 2 of ADR 0002 (`packages/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md`).
+The core needs only a working directory and a disposal hook for a child run; the default — the parent's cwd, with no setup or teardown — is always correct.
+"Where does a child run, and what brackets the run?"
+is a *strategy* (git worktree, container, tmpdir, remote sandbox), not core behavior.
+ADR 0002 classifies this as the single *generative* extension surface: a concern that must return a value the core consumes synchronously attaches through a rationed provider seam, not an observational event.
+This issue adds that seam — `WorkspaceProvider` / `Workspace` plus `SubagentsService.registerWorkspaceProvider` — without the core gaining any knowledge of what an "isolation strategy" is.
+
+## Goals
+
+- Define the `WorkspaceProvider` and `Workspace` interfaces in the core, with zero git or worktree knowledge.
+- Add `SubagentsService.registerWorkspaceProvider(provider): () => void` — a single-provider seam (chaining is out of scope) that throws if a provider is already registered and returns an unregister disposer.
+- At run-start, consult the registered provider for the child's cwd and a disposal handle; with no provider, the child runs in `baseCwd` (parent cwd — default behavior unchanged).
+- Call `dispose()` after the run and append the returned `resultAddendum` to the child's result.
+- This change is **additive and non-breaking** — the existing `isolation: "worktree"` path is left intact (its eviction is #263).
+
+## Non-Goals
+
+- Removing `worktree.ts`, `worktree-isolation.ts`, `GitWorktreeManager`, or the `isolation: "worktree"` spawn mode — deferred to #263.
+- Removing `isolated` / `extensions: false` / `noSkills` — deferred to #264.
+- Born-complete child execution / dissolving the runner — deferred to #265.
+- Multiple/chained providers — out of scope per the issue; one provider only.
+- Shipping a concrete provider implementation — the worktrees package (#263) is the seam's first real consumer.
+  Within this issue the seam is exercised only by test fakes; see Risks for the "no vacant hooks" release-coordination constraint.
+
+## Background
+
+Relevant existing modules:
+
+- `src/lifecycle/agent.ts` — `Agent.run()` calls `this.worktree?.setup()` at run-start to obtain a cwd, threads it into `runner.run({ context: { cwd } })`, and on completion calls `this.worktree?.cleanup(description)`, appending a "Changes saved to branch …" addendum.
+  This is exactly the prepare/dispose shape the seam generalizes.
+- `src/lifecycle/worktree-isolation.ts` — `WorktreeIsolation` is the current run-scoped collaborator: `setup()` returns a path, `cleanup(description)` returns a `WorktreeCleanupResult`.
+  The seam is its abstraction; #263 will reimplement it as a `WorkspaceProvider` in a separate package.
+- `src/lifecycle/agent-manager.ts` — constructs each `Agent`, owns the injected `WorktreeManager`, and threads `getRunConfig` as a getter.
+  The same getter pattern is reused for the workspace provider.
+- `src/service/service.ts` — the package's public API surface (`package.json` `exports` points at `./src/service.ts`).
+  `SubagentsService`, `SpawnOptions`, and `SubagentRecord` all live here; the seam types are re-exported here so the worktrees package can implement them.
+- `src/service/service-adapter.ts` — `SubagentsServiceAdapter implements SubagentsService`, wrapping the `AgentManagerLike` narrow interface.
+- `src/lifecycle/child-lifecycle.ts` — the *observational* lifecycle events from #261 (`spawning`, `session-created`, `completed`, `disposed`).
+  The provider seam is orthogonal: events tell consumers what happened; the provider returns a value the core consumes.
+
+AGENTS.md constraints that apply:
+
+- Pi SDK imports stay out of library modules — the seam interfaces and `AgentManager` accept the provider as a parameter; `index.ts` (the SDK edge) supplies `baseCwd: process.cwd()`.
+- Do not read `process.cwd()` inside library functions — `baseCwd` is injected into `AgentManager` from `index.ts`.
+- When adding a public API pattern, follow the established convention: the repo's registration/subscription convention is an unsubscribe **function** (`() => void`, as in `SubscribableSession.subscribe` and `pi.events.on`), not a `Symbol.dispose` `Disposable`.
+  The seam therefore returns `() => void`; this is a deliberate divergence from the issue's literal `Disposable` to match the codebase convention.
+
+## Design Overview
+
+### Seam interfaces
+
+Defined in a new core module `src/lifecycle/workspace.ts` (sibling to `child-lifecycle.ts`), re-exported from `service.ts` for public consumers.
+The `status` field reuses the core `AgentStatus` union (from `agent.ts`), re-exported publicly so the worktrees package can name it.
+
+```typescript
+import type { AgentStatus } from "#src/lifecycle/agent";
+import type { AgentInvocation, SubagentType } from "#src/types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+  agentId: string;
+  agentType: SubagentType;
+  baseCwd: string;
+  invocation?: AgentInvocation;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+  status: AgentStatus;
+  description: string;
+}
+
+/** What dispose may hand back for the core to fold into the child result. */
+export interface WorkspaceDisposeResult {
+  resultAddendum?: string;
+}
+
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+export interface Workspace {
+  readonly cwd: string; // the directory already exists
+  dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | void;
+}
+
+/** The single generative seam: supplies a child's workspace. */
+export interface WorkspaceProvider {
+  prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}
+```
+
+Note the addendum-formatting boundary: the core appends `resultAddendum` *verbatim*.
+The provider owns its own separator and wording (the worktrees package owns the "Changes saved to branch …" string in #263).
+The core never formats branch text.
+
+### Registration — single provider, throw on duplicate
+
+`AgentManager` holds an optional provider and exposes registration:
+
+```typescript
+private workspaceProvider?: WorkspaceProvider;
+
+registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+  if (this.workspaceProvider) {
+    throw new Error(
+      "A WorkspaceProvider is already registered; only one is supported.",
+    );
+  }
+  this.workspaceProvider = provider;
+  return () => {
+    if (this.workspaceProvider === provider) this.workspaceProvider = undefined;
+  };
+}
+```
+
+The throw surfaces a misconfiguration loudly (two workspace extensions installed at once).
+The disposer clears the slot only if the same provider is still active, so a stale disposer cannot evict a later registration.
+`SubagentsServiceAdapter.registerWorkspaceProvider` delegates straight through; `AgentManagerLike` gains the method.
+
+### Run-start consultation (Tell-Don't-Ask call site)
+
+`Agent.run()` consults the provider at the point where it currently calls `worktree?.setup()`.
+Provider-first precedence: when a provider supplies a workspace, the core routes cwd and dispose through it and skips the legacy worktree collaborator; with no provider it falls back to the existing worktree path; with neither it runs in `baseCwd` (cwd undefined → SDK uses the parent cwd).
+
+```typescript
+// run() — replacing the worktree?.setup() block
+let cwd: string | undefined;
+try {
+  const provider = this._getWorkspaceProvider?.();
+  if (provider) {
+    this._workspace = await provider.prepare({
+      agentId: this.id,
+      agentType: this.type,
+      baseCwd: this._baseCwd,
+      invocation: this.invocation,
+    });
+    cwd = this._workspace?.cwd;
+  } else {
+    this.worktree?.setup();
+    cwd = this.worktree?.path;
+  }
+} catch (err) {
+  this.markError(err);
+  this.releaseListeners();
+  this.observer?.onRunFinished?.(this);
+  return;
+}
+// … runner.run({ context: { cwd, parentSession }, … })
+```
+
+On completion (`completeRun`) the core computes the final status, then disposes:
+
+```typescript
+const finalStatus: AgentStatus =
+  result.aborted ? "aborted" : result.steered ? "steered" : "completed";
+if (this._workspace) {
+  const out = this._workspace.dispose({ status: finalStatus, description: this.description });
+  if (out?.resultAddendum) finalResult += out.resultAddendum;
+} else {
+  const wt = this.worktree?.cleanup(this.description);
+  if (wt?.hasChanges && wt.branch) finalResult += `\n\n---\nChanges saved to branch \`${wt.branch}\`…`;
+}
+```
+
+`failRun` mirrors this in a `try/catch`, disposing with `status: "error"` and discarding any addendum (matching the existing error-path behavior, which does not append branch text).
+
+The provider getter is injected into each `Agent` by `AgentManager.spawn` (`getWorkspaceProvider: () => this.workspaceProvider`), exactly like `getRunConfig`.
+`baseCwd` is injected into `AgentManager` from `index.ts` and threaded to each `Agent`.
+
+### Why the worktree path stays (scope decision A)
+
+Per the clarification, #262 is the additive seam only; the legacy `isolation: "worktree"` orchestration is untouched and removed in #263.
+A genuinely separate strategy could register a provider today and get correct cwd + dispose behavior; worktree spawns keep working unchanged.
+Provider-first precedence means the two never silently conflict, and #263 collapses the branch by deleting the worktree arm.
+
+### Edge cases
+
+- `prepare()` resolves `undefined` → `cwd` is undefined → runner uses `baseCwd` (parent cwd).
+  No dispose call (no workspace).
+- `prepare()` rejects → `markError`, release listeners, notify observer, return (same shape as a worktree `setup()` failure today).
+- `dispose()` returns `void` or no `resultAddendum` → result unchanged.
+- Duplicate `registerWorkspaceProvider` → throws synchronously.
+
+## Module-Level Changes
+
+| File                                | Change                                                                                                                                                                                                                                                                                                                                  |
+| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/lifecycle/workspace.ts`        | **New.** Defines `WorkspaceProvider`, `Workspace`, `WorkspacePrepareContext`, `WorkspaceDisposeOutcome`, `WorkspaceDisposeResult`. No behavior.                                                                                                                                                                                         |
+| `src/lifecycle/agent.ts`            | `AgentInit` gains optional `baseCwd?: string` and `getWorkspaceProvider?: () => WorkspaceProvider \| undefined`. New private fields `_baseCwd`, `_getWorkspaceProvider`, `_workspace?: Workspace`. `run()` provider-first prepare; `completeRun`/`failRun` dispose + verbatim `resultAddendum`. Export `AgentStatus` is already public. |
+| `src/lifecycle/agent-manager.ts`    | `AgentManagerOptions` gains required `baseCwd: string`. New `workspaceProvider` field, `registerWorkspaceProvider()` (throw on dup, unregister disposer). `spawn()` passes `baseCwd` and the `getWorkspaceProvider` getter into each `Agent`.                                                                                           |
+| `src/service/service.ts`            | Re-export the five seam types and `AgentStatus`. Add `registerWorkspaceProvider(provider: WorkspaceProvider): () => void` to the `SubagentsService` interface.                                                                                                                                                                          |
+| `src/service/service-adapter.ts`    | `AgentManagerLike` gains `registerWorkspaceProvider(provider): () => void`. `SubagentsServiceAdapter` implements the method, delegating to the manager.                                                                                                                                                                                 |
+| `src/index.ts`                      | Pass `baseCwd: process.cwd()` to the `new AgentManager({…})` construction (alongside the existing `GitWorktreeManager(process.cwd())`).                                                                                                                                                                                                 |
+| `docs/architecture/architecture.md` | Mark Phase 16 Step 2 (#262) as landed in the roadmap; note the seam exists and `workspace.ts` is added to the lifecycle domain listing.                                                                                                                                                                                                 |
+
+No exports are removed or renamed, so no `src/`/`test/` removed-symbol grep is required.
+No file in Module-Level Changes is also claimed as unchanged in Non-Goals (the worktree *modules* are non-goals; `agent.ts` touches the worktree *call path* additively, which is consistent).
+
+### Grep checklist before finalizing
+
+- Objects typed as `SubagentsService` in tests: `test/service/service.test.ts` casts `{ spawn: () => "id" } as unknown as SubagentsService`, so adding an interface method does **not** break it (verified).
+- `new AgentManager(` call sites: `src/index.ts` (one) and `test/lifecycle/agent-manager.test.ts` `createManager` (one) — both updated for required `baseCwd` in the same step.
+- `AgentManagerLike` mocks in `test/service/service-adapter.test.ts` (`defaultManager`, inline `spawn:` stubs) — add `registerWorkspaceProvider` stub in the same step.
+
+## Test Impact Analysis
+
+This is an additive seam, so the work is dominated by *new* tests; little existing coverage is affected.
+
+1. New unit tests the seam enables: provider registration (throw-on-duplicate, disposer-unregisters), run-start consultation (cwd from `prepare`, `resultAddendum` appended on dispose), `prepare` returns undefined → `baseCwd`, `prepare` rejects → `markError`, and adapter delegation.
+   These were impossible before because there was no provider abstraction to substitute.
+2. Redundant existing tests: none.
+   The seam does not subsume worktree tests — they exercise the legacy path, which is preserved.
+3. Existing tests that must stay as-is: all `worktree.test.ts`, `worktree-isolation.test.ts`, and the AgentManager worktree-isolation tests (`calls worktrees.create` / `cleanup`) — they genuinely exercise the fallback path that remains in #262.
+   The Agent no-provider tests assert unchanged worktree behavior.
+
+## TDD Order
+
+1. **Seam types + registration surface** — `feat`.
+   New `src/lifecycle/workspace.ts`; re-export seam types + `AgentStatus` from `service.ts`; add `registerWorkspaceProvider` to `SubagentsService`, `AgentManagerLike`, and `SubagentsServiceAdapter` (delegating); add required `baseCwd` + provider field + `registerWorkspaceProvider` (throw on dup, disposer) to `AgentManager`; update `index.ts` and the `createManager` test factory for `baseCwd`.
+   Tests: `agent-manager.test.ts` registration (throws on second register; disposer clears only the active provider; getter returns the registered provider) and `service-adapter.test.ts` delegation.
+   This whole surface lands in one commit because the `SubagentsService` interface method forces the adapter to implement it and the required `baseCwd` forces both construction sites — splitting would not type-check.
+   Suggested message: `feat: add WorkspaceProvider registration seam to subagents service`.
+   Run `pnpm run check` immediately after (shared-interface change).
+
+2. **Run-start consumption + dispose** — `feat`.
+   `Agent`: `AgentInit` gains `baseCwd`/`getWorkspaceProvider`; new private fields; `run()` provider-first prepare; `completeRun`/`failRun` dispose + verbatim `resultAddendum`.
+   `AgentManager.spawn` passes `baseCwd` and the `getWorkspaceProvider` getter (sole extra construction site, folded in).
+   Tests: `agent.test.ts` — provider `prepare` supplies cwd to the runner; `dispose` `resultAddendum` appended to the result; `prepare` undefined → cwd falls back to `baseCwd`; `prepare` rejects → `markError` + `onRunFinished`; no-provider path still uses the worktree collaborator (regression guard).
+   Suggested message: `feat: consult workspace provider for child cwd and disposal`.
+   Run `pnpm run check` after (AgentInit change).
+
+3. **Architecture doc update** — `docs`.
+   Mark Phase 16 Step 2 (#262) landed in the roadmap; add `workspace.ts` to the lifecycle domain listing; cross-link the seam.
+   Suggested message: `docs: record WorkspaceProvider seam in phase 16 roadmap`.
+
+## Risks and Mitigations
+
+- **Vacant hook (the headline risk).**
+  ADR 0002's "no vacant hooks" rule says a provider seam with no consumer is a speculative abstraction that `fallow` flags as dead.
+  Within #262 the seam is exercised only by test fakes.
+  Mitigation: land #262 **alongside** #263 (its first real consumer, `@gotgenes/pi-subagents-worktrees`) — do not cut a release that contains the seam without the worktrees package.
+  Track this as a release-coordination constraint; the architecture roadmap already pairs Steps 2 and 3.
+- **Dual cwd path confusion.**
+  Provider-first precedence keeps worktree and provider from silently conflicting; the branch is documented and removed in #263.
+- **`baseCwd` source.**
+  Injecting `process.cwd()` from `index.ts` matches the existing `GitWorktreeManager(process.cwd())` construction; no new global-state read enters a library module.
+- **Status timing in dispose.**
+  The final status is computed before the status-transition methods mutate, so `dispose`'s outcome reflects the true terminal status.
+
+## Open Questions
+
+- Should `baseCwd` eventually come from the parent `SessionContext.cwd` rather than `process.cwd()`?
+  Deferred — `process.cwd()` preserves current worktree behavior; revisit during the born-complete work (#265).
+- Should the `disposed` lifecycle event (#261) and `Workspace.dispose` be reconciled into one teardown notion?
+  Deferred — they serve different surfaces (observational vs generative); revisit if #265 dissolves the runner.

package/docs/retro/0262-add-workspace-provider-seam.md

@@ -0,0 +1,44 @@
+---
+issue: 262
+issue_title: "Add WorkspaceProvider extension seam"
+---
+
+# Retro: #262 — Add WorkspaceProvider extension seam
+
+## Stage: Planning (2026-05-29T14:51:15Z)
+
+### Session summary
+
+Produced a numbered implementation plan for the Phase 16, Step 2 `WorkspaceProvider` seam (ADR 0002).
+The plan adds the seam additively — `WorkspaceProvider` / `Workspace` interfaces, `SubagentsService.registerWorkspaceProvider`, run-start consultation, and `dispose` with a verbatim `resultAddendum` — while leaving the existing `isolation: "worktree"` path untouched for #263 to evict.
+Three TDD steps (two `feat`, one `docs`).
+
+### Observations
+
+- Two ambiguous choices were surfaced via `ask_user` and resolved: **scope = additive seam only** (Option A — leave the legacy worktree path; #263 evicts it), and **duplicate registration = throw** (loud misconfiguration surface, disposer clears only the active provider).
+- The package's public surface is `./src/service.ts` (per `package.json` `exports`), so the seam types are defined in a new core `src/lifecycle/workspace.ts` and re-exported from `service.ts` — avoiding a `service ↔ lifecycle` import cycle while still exposing them to the worktrees consumer.
+- Diverged from the issue's literal `Disposable` return type: the repo convention for unsubscribe/unregister is a plain `() => void` (matching `SubscribableSession.subscribe` and `pi.events.on`); no `Symbol.dispose` usage exists anywhere in the codebase.
+- Provider-first precedence was chosen so the new seam and the legacy worktree collaborator never silently conflict during the transient dual-path window (#263 collapses the branch).
+- Headline risk is the ADR "no vacant hooks" rule: within #262 the seam is exercised only by test fakes, so it must land **alongside** #263 (`@gotgenes/pi-subagents-worktrees`) and not ship in a release on its own.
+- Step 1 bundles the entire registration surface (types, `SubagentsService` method, adapter impl, `AgentManagerLike`, required `baseCwd`) into one commit because the interface method forces the adapter and the required field forces both construction sites — splitting would not type-check.
+- Verified `test/service/service.test.ts` casts its mock `as unknown as SubagentsService`, so adding an interface method does not break it; flagged the `createManager` and `AgentManagerLike` mock updates for the `baseCwd` and registration additions.
+
+## Stage: Implementation — TDD (2026-05-29T15:09:49Z)
+
+### Session summary
+
+Implemented the `WorkspaceProvider` seam across three TDD cycles (two `feat`, one `docs`): the registration surface (`AgentManager.registerWorkspaceProvider` + service/adapter delegation + `workspace.ts` types), run-start consumption in `Agent.run()` with provider-first precedence and `dispose`/`resultAddendum`, and an architecture-doc update.
+Test count went from 1049 to 1061 (+12 new tests; +6 in `agent.test.ts`, +4 registration in `agent-manager.test.ts`, +1 adapter delegation, plus existing-helper additions).
+All deterministic gates green: `check`, `lint`, `test`, and `fallow dead-code` (run from repo root).
+
+### Observations
+
+- Deviation from plan (Module-Level Changes): the plan said `service.ts` would re-export "the five seam types and `AgentStatus`", but `fallow dead-code` flagged those five re-exports as unused (no consumer until #263), and AGENTS.md forbids speculative re-exports.
+  Resolved by re-exporting only `WorkspaceProvider` — a consumer assigning to it gets `Workspace` and the context types via inference; #263 adds named re-exports when it imports them.
+  This is the concrete manifestation of the plan's headline "vacant hook" risk surfacing in the dead-code gate.
+- Lint surprise: `WorkspaceDisposeResult | void` tripped eslint `no-invalid-void-type`.
+  Changed the `dispose` return type to `WorkspaceDisposeResult | undefined` (equivalent — a side-effecting `dispose` that falls off the end returns `undefined`); minor divergence from the issue's literal `| void`.
+- Three test mock factories implement `AgentManagerLike` in `service-adapter.test.ts` (`createMockManager`, `defaultManager`, `createTestManager`) — all three needed the new `registerWorkspaceProvider` stub; `tsc` caught the third after the first two were updated.
+- Used `git commit --fixup` + `--autosquash` rebase twice (unpushed history) to fold the fallow trim into the Step 1 `feat` commit and the reviewer's doc-wording fix into the Step 3 `docs` commit, keeping each commit self-consistent.
+- Pre-completion reviewer: WARN — all blocking checks pass; one non-blocking doc finding (architecture.md overstated that `Workspace` is re-exported).
+  Addressed before finishing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "11.4.0",
+  "version": "11.5.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/index.ts

@@ -167,6 +167,7 @@ export default function (pi: ExtensionAPI) {
   const manager = new AgentManager({
     runner: new ConcreteAgentRunner(runnerDeps),
     worktrees: new GitWorktreeManager(process.cwd()),
+    baseCwd: process.cwd(),
     observer,
     queue,
     getRunConfig: () => settings,

package/src/lifecycle/agent-manager.ts

@@ -13,6 +13,7 @@ import { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
 import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ConcurrencyQueue } from "#src/lifecycle/concurrency-queue";
 import type { 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";
 
@@ -33,6 +34,8 @@ export interface AgentManagerOptions {
   worktrees: WorktreeManager;
   /** Concurrency queue — owns scheduling, limit checks, and drain logic. */
   queue: ConcurrencyQueue;
+  /** Base working directory handed to a workspace provider (the parent cwd). */
+  baseCwd: string;
   getRunConfig?: () => RunConfig;
   observer?: AgentManagerObserver;
 }
@@ -70,12 +73,20 @@ export class AgentManager {
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
   private readonly queue: ConcurrencyQueue;
+  private readonly baseCwd: string;
   private getRunConfig?: () => RunConfig;
+  private _workspaceProvider?: WorkspaceProvider;
+
+  /** The registered workspace provider, or undefined when none is registered. */
+  get workspaceProvider(): WorkspaceProvider | undefined {
+    return this._workspaceProvider;
+  }
 
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
     this.queue = options.queue;
+    this.baseCwd = options.baseCwd;
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
@@ -83,6 +94,23 @@ export class AgentManager {
     this.cleanupInterval.unref();
   }
 
+  /**
+   * Register the single workspace provider. Throws if one is already
+   * registered (chaining is out of scope — see ADR 0002). Returns a disposer
+   * that clears the slot only if this provider is still the active one.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    if (this._workspaceProvider) {
+      throw new Error(
+        "A WorkspaceProvider is already registered; only one is supported.",
+      );
+    }
+    this._workspaceProvider = provider;
+    return () => {
+      if (this._workspaceProvider === provider) this._workspaceProvider = undefined;
+    };
+  }
+
   /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
   private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
     return {
@@ -140,6 +168,8 @@ export class AgentManager {
           : undefined,
       observer: this.buildObserver(options),
       getRunConfig: this.getRunConfig,
+      baseCwd: this.baseCwd,
+      getWorkspaceProvider: () => this._workspaceProvider,
     });
     this.agents.set(id, record);
 

package/src/lifecycle/agent.ts

@@ -26,6 +26,7 @@ import type { ExecutionState } from "#src/lifecycle/execution-state";
 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";
@@ -72,6 +73,10 @@ export interface AgentInit {
 	worktree?: WorktreeIsolation;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
+	/** Resolves the registered workspace provider (if any) at run-start. */
+	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	/** Parent working directory handed to a workspace provider's prepare(). */
+	baseCwd?: string;
 
 	// Run config (required for run(), optional for tests)
 	snapshot?: ParentSnapshot;
@@ -129,6 +134,10 @@ export class Agent {
 	readonly worktree?: WorktreeIsolation;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
+	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	private readonly _baseCwd: string;
+	/** Workspace prepared at run-start by a provider — undefined when none is registered. */
+	private _workspace?: Workspace;
 
 	// Run config — optional (required for run())
 	private readonly _snapshot?: ParentSnapshot;
@@ -186,6 +195,8 @@ export class Agent {
 		this.worktree = init.worktree;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
+		this._getWorkspaceProvider = init.getWorkspaceProvider;
+		this._baseCwd = init.baseCwd ?? "";
 
 		// Run config
 		this._snapshot = init.snapshot;
@@ -223,8 +234,23 @@ export class Agent {
 		this.observer?.onStarted?.(this);
 		this.wireSignal(this._signal, () => this.abort());
 
+		let cwd: string | undefined;
 		try {
-			this.worktree?.setup();
+			// Provider-first: a registered workspace provider supplies the cwd and
+			// owns teardown; otherwise fall back to the legacy worktree collaborator.
+			const provider = this._getWorkspaceProvider?.();
+			if (provider) {
+				this._workspace = await provider.prepare({
+					agentId: this.id,
+					agentType: this.type,
+					baseCwd: this._baseCwd,
+					invocation: this.invocation,
+				});
+				cwd = this._workspace?.cwd;
+			} else {
+				this.worktree?.setup();
+				cwd = this.worktree?.path;
+			}
 		} catch (err) {
 			this.markError(err);
 			this.releaseListeners();
@@ -236,7 +262,7 @@ export class Agent {
 		try {
 			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
 				context: {
-					cwd: this.worktree?.path,
+					cwd,
 					parentSession: this._parentSession,
 				},
 				model: this._model,
@@ -442,9 +468,19 @@ export class Agent {
 		this.releaseListeners();
 
 		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}\``;
+		if (this._workspace) {
+			const finalStatus: AgentStatus = result.aborted
+				? "aborted"
+				: result.steered
+					? "steered"
+					: "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);
@@ -465,8 +501,9 @@ export class Agent {
 		this.releaseListeners();
 
 		try {
-			this.worktree?.cleanup(this.description);
-		} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
+			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/lifecycle/workspace.ts

@@ -0,0 +1,47 @@
+/**
+ * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
+ *
+ * "Where does a child run, and what brackets the run?" is a strategy (git
+ * worktree, container, tmpdir, remote sandbox), not core behavior. The core
+ * needs only a working directory plus a disposal hook; the default — the
+ * parent's cwd, with no setup/teardown — is always correct.
+ *
+ * Unlike the observational lifecycle events in child-lifecycle.ts, this is a
+ * *generative* seam: a registered provider returns a value the core consumes
+ * synchronously at run-start. The core has no knowledge of git or worktrees.
+ */
+
+import type { AgentStatus } from "#src/lifecycle/agent";
+import type { AgentInvocation, SubagentType } from "#src/types";
+
+/** Context the core hands a provider when a child run starts. */
+export interface WorkspacePrepareContext {
+  agentId: string;
+  agentType: SubagentType;
+  baseCwd: string;
+  invocation?: AgentInvocation;
+}
+
+/** Outcome the core reports to a workspace when the run ends. */
+export interface WorkspaceDisposeOutcome {
+  status: AgentStatus;
+  description: string;
+}
+
+/** What dispose may hand back for the core to fold into the child result. */
+export interface WorkspaceDisposeResult {
+  /** Appended verbatim to the child's result text — the provider owns the wording. */
+  resultAddendum?: string;
+}
+
+/** A prepared working directory plus its bracketed teardown. Born complete. */
+export interface Workspace {
+  /** The working directory — already exists when the workspace is handed back. */
+  readonly cwd: string;
+  dispose(outcome: WorkspaceDisposeOutcome): WorkspaceDisposeResult | undefined;
+}
+
+/** The single generative seam: supplies a child's workspace. */
+export interface WorkspaceProvider {
+  prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}

package/src/service/service-adapter.ts

@@ -6,6 +6,7 @@
  */
 
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
 import type { ModelRegistry } from "#src/session/model-resolver";
 import type { Agent, SessionContext } from "#src/types";
@@ -18,6 +19,7 @@ export interface AgentManagerLike {
   abort(id: string): boolean;
   waitForAll(): Promise<void>;
   hasRunning(): boolean;
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
 }
 
 /**
@@ -107,6 +109,10 @@ export class SubagentsServiceAdapter implements SubagentsService {
   hasRunning(): boolean {
     return this.manager.hasRunning();
   }
+
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    return this.manager.registerWorkspaceProvider(provider);
+  }
 }
 
 /**

package/src/service/service.ts

@@ -10,8 +10,13 @@
  */
 
 import type { LifetimeUsage } from "#src/lifecycle/usage";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
 
-export type { LifetimeUsage };
+// 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.
+export type { LifetimeUsage, WorkspaceProvider };
 
 export type SubagentStatus =
   | "queued"
@@ -73,6 +78,13 @@ export interface SubagentsService {
 
   /** Whether any agents are running or queued. */
   hasRunning(): boolean;
+
+  /**
+   * Register the single workspace provider that supplies a child's working
+   * directory plus bracketed setup/teardown. Throws if one is already
+   * registered. Returns a disposer that unregisters the provider.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
 }
 
 /** Event channel constants for pi.events subscriptions. */