@gotgenes/pi-subagents 11.4.0 → 11.6.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v11.5.0...pi-subagents-v11.6.0) (2026-05-29)
+
+
+### Features
+
+* **pi-subagents:** publish bundled type declarations and fix stale exports path ([8eda6f6](https://github.com/gotgenes/pi-packages/commit/8eda6f6611a12c60d99a5069f352abd634997e67))
+
+## [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/dist/public.d.ts

@@ -0,0 +1,178 @@
+import { ThinkingLevel } from '@earendil-works/pi-ai';
+
+/** usage.ts — Token usage: shapes, accumulator operators, session-stats readers. */
+/**
+ * Lifetime usage components, accumulated via `message_end` events. Survives
+ * compaction (which replaces session.state.messages and would reset any
+ * stats-derived sum). cacheRead is excluded because each turn's cacheRead is
+ * the cumulative cached prefix re-read on that one call — summing across
+ * turns counts the prefix N times. See issue #38.
+ */
+type LifetimeUsage = {
+    input: number;
+    output: number;
+    cacheWrite: number;
+};
+
+/**
+ * types.ts — Type definitions for the subagent system.
+ */
+
+/** 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;
+    thinking?: ThinkingLevel;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    runInBackground?: boolean;
+    isolation?: IsolationMode;
+}
+
+/**
+ * agent.ts — Agent class with encapsulated status-transition logic and per-agent behavior.
+ *
+ * Status transitions (status, result, error, startedAt, completedAt) are owned
+ * by the class and exposed via transition methods. External code reads these
+ * fields through public properties but cannot write them directly.
+ *
+ * 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.
+ *
+ * Worktree isolation is delegated to an optional WorktreeIsolation collaborator
+ * (set at construction when isolation is requested); its presence IS the mode.
+ *
+ * Phase-specific collaborators (execution, notification) are attached
+ * after construction as lifecycle information becomes available.
+ */
+
+type AgentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
+/**
+ * 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.
+ */
+
+/** Context the core hands a provider when a child run starts. */
+interface WorkspacePrepareContext {
+    agentId: string;
+    agentType: SubagentType;
+    baseCwd: string;
+    invocation?: AgentInvocation;
+}
+/** Outcome the core reports to a workspace when the run ends. */
+interface WorkspaceDisposeOutcome {
+    status: AgentStatus;
+    description: string;
+}
+/** What dispose may hand back for the core to fold into the child result. */
+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. */
+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. */
+interface WorkspaceProvider {
+    prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
+}
+
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+/** Serializable snapshot of an agent's state — no live session objects. */
+interface SubagentRecord {
+    id: string;
+    type: string;
+    description: string;
+    status: SubagentStatus;
+    result?: string;
+    error?: string;
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    lifetimeUsage: LifetimeUsage;
+    compactionCount: number;
+    worktreeResult?: {
+        hasChanges: boolean;
+        branch?: string;
+    };
+}
+/** Options for spawning an agent via the service. */
+interface SpawnOptions {
+    description?: string;
+    model?: string;
+    maxTurns?: number;
+    thinkingLevel?: string;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    foreground?: boolean;
+    bypassQueue?: boolean;
+    isolation?: "worktree";
+}
+/** The public service contract for cross-extension subagent access. */
+interface SubagentsService {
+    /** Spawn an agent. Returns the agent ID immediately. */
+    spawn(type: string, prompt: string, options?: SpawnOptions): string;
+    /** Get a snapshot of an agent's current state. */
+    getRecord(id: string): SubagentRecord | undefined;
+    /** List all tracked agents, most recent first. */
+    listAgents(): SubagentRecord[];
+    /** Abort a running or queued agent. Returns false if not found. */
+    abort(id: string): boolean;
+    /** Send a steering message to a running agent. */
+    steer(id: string, message: string): Promise<boolean>;
+    /** Wait for all running and queued agents to complete. */
+    waitForAll(): Promise<void>;
+    /** 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. */
+declare const SUBAGENT_EVENTS: {
+    readonly STARTED: "subagents:started";
+    readonly COMPLETED: "subagents:completed";
+    readonly ACTIVITY: "subagents:activity";
+};
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+declare function publishSubagentsService(service: SubagentsService): void;
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+declare function getSubagentsService(): SubagentsService | undefined;
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+declare function unpublishSubagentsService(): void;
+
+export { SUBAGENT_EVENTS, getSubagentsService, publishSubagentsService, unpublishSubagentsService };
+export type { LifetimeUsage, SpawnOptions, SubagentRecord, SubagentStatus, SubagentsService, WorkspaceProvider };

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/decisions/0003-publish-bundled-type-declarations.md

@@ -0,0 +1,69 @@
+---
+status: accepted
+date: 2026-05-29
+---
+
+# 0003 — Publish a bundled `.d.ts` for the public surface
+
+## Status
+
+Accepted.
+Introduces the repository's first build step, scoped to type declarations only.
+
+## Context
+
+`@gotgenes/pi-subagents` could not be imported by another TypeScript package in this workspace.
+Issue #263 (extract worktree isolation to `@gotgenes/pi-subagents-worktrees`) is the first intra-repo consumer: it must `implements WorkspaceProvider` and call `getSubagentsService().registerWorkspaceProvider(...)`, both of which require importing the package by name.
+
+A `tsc --traceResolution` of a sibling consuming the package surfaced two compounding failures.
+
+1. `package.json` `exports["."]` pointed at `./src/service.ts`, which does not exist — the real module is `./src/service/service.ts`.
+   A latent bug, unnoticed because nothing in-repo imported the package by name.
+2. Once corrected, the public entry's internal alias imports cascade.
+   `service/service.ts` imports `type LifetimeUsage` and `type WorkspaceProvider` via the `#src/*` alias.
+   When a sibling's `tsc` follows the symlink, the consumer's own `paths` (`#src/*` → `./src/*`) intercept first and resolve into the *consumer's* `src/` — a global-`paths` collision, since both packages define `#src/*`.
+   The fallback to the publisher's `package.json` `imports` field also fails: `tsc` cannot resolve the extensionless `.ts` target under Node `imports` semantics ("Import specifier '#src/lifecycle/usage' does not exist in package.json scope").
+
+The public entry's type closure is deeply entangled: `WorkspaceProvider` (in `lifecycle/workspace.ts`) reaches `AgentStatus` in the 510-line `lifecycle/agent.ts`, plus `SubagentType`/`AgentInvocation` from `types.ts` (which itself re-exports the `Agent` class).
+A shallow alias-free entry is therefore not achievable without a substantial source restructure.
+
+This collides with the ship-source model (ADR 0002): every package ships raw `.ts` executed directly by Pi, with no build step.
+
+## Decision
+
+Emit a single, self-contained `dist/public.d.ts` for the public surface and advertise it through a `types` export condition, while the runtime entry continues to serve `.ts` source.
+
+```jsonc
+"exports": {
+  ".": {
+    "types": "./dist/public.d.ts",
+    "default": "./src/service/service.ts"
+  }
+}
+```
+
+- `rollup-plugin-dts` rolls the declaration graph rooted at `src/service/service.ts` into one file, inlining the internal `#src/*` types and keeping peer-dependency types (`@earendil-works/*`, `@sinclair/typebox`) external.
+  We ship `.ts` source, so only the declaration bundle is emitted — no JS.
+- The bundle is generated at `prepack` time and shipped via a `files` allowlist; it is gitignored and never committed.
+- `default` → `./src/service/service.ts` fixes the stale path and serves runtime consumers; its `import type` lines erase, so no runtime `#src/*` resolution is needed.
+- A `pnpm pack` → throwaway-consumer → `tsc` harness proves external consumability with no publish round-trip and no workspace privileges.
+
+This is the repository's first build step.
+It is deliberately narrow: it produces type declarations only and changes nothing about how Pi loads the extension from source (`pi.extensions: ["./src/index.ts"]` is untouched).
+
+## Alternatives considered
+
+- Alias-free public entry (restructure the source so the entry's full type closure resolves via same-directory `./` imports).
+  Mechanically possible, but it requires moving the `AgentStatus`/`SubagentType`/`AgentInvocation`/`WorkspaceProvider` definitions and untangling the `agent.ts`/`types.ts` graph, with care that inner layers do not import the outer service layer.
+  `eslint`'s `no-parent-relative-imports` rule (which forbids `../`) narrows the options further.
+  Larger blast radius than emitting a `.d.ts`, and it churns the domain model to serve a packaging concern.
+- A self-contained entry that re-declares the public types inline, guarded by a conformance test.
+  Avoids a build step but duplicates the seam/usage/status type definitions, which drift over time.
+
+## Consequences
+
+- The repository now has a build step, but it is type-only and isolated to this package; the ship-source model is otherwise intact.
+- Consumers (including `@gotgenes/pi-subagents-worktrees` in #263) consume the packaged public interface like any external developer — no `workspace:*` privileges.
+- The `types` condition points at a build-time artifact; an in-repo workspace-linked consumer that imported the package would need `dist/public.d.ts` present.
+  This is acceptable because no in-repo package imports the surface yet; #263 consumes the built artifact from the published tarball.
+- Sequencing: #270 must be published (its release-please PR merged) before #263 edits `pi-subagents` core, so #263's changes do not batch into the same `pi-subagents` release.

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.