@gotgenes/pi-subagents 11.3.0 → 11.5.0

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/0256-extract-worktree-isolation.md

@@ -43,3 +43,47 @@ Full suite green at 1047 tests (baseline 1053; +7 new `worktree-isolation` tests
 - `createTestAgent` spreads `init` into the `Agent` constructor, so injecting `worktree` needed no helper change.
 - The Step 2 integration landed cleanly in a single commit as the plan predicted; the type checker pinpointed every stale call site.
 - Pre-completion reviewer: PASS (all deterministic checks, acceptance criteria, conventional commits, docs, code design, test artifacts, Mermaid, and dead-code gates green).
+
+## Stage: Final Retrospective (2026-05-29T00:18:13Z)
+
+### Session summary
+
+Shipped #256 end-to-end across one continuous session: planning → 4-cycle TDD → ship.
+The `WorktreeIsolation` collaborator landed, `WorktreeState` was folded in and deleted, the suite stayed green (1047 tests), the pre-completion reviewer returned PASS on first dispatch, CI passed, and `pi-subagents-v11.3.0` released cleanly.
+The session was notably low-friction; the only judgment calls were a pre-existing baseline lint failure and a fold-vs-wrap confirmation.
+
+### Observations
+
+#### What went well
+
+- The planning-stage lift-and-shift analysis precisely predicted the TDD shape: Step 2 was a single forced commit (the type checker rejects removing `AgentInit` fields while call sites still pass them), and `tsc` pinpointed every stale call site exactly as planned.
+  Zero TDD surprises followed from an accurate plan.
+- The fold decision (delete `WorktreeState`, store a mutable `WorktreeInfo` in `WorktreeIsolation`) preserved the in-place `branch` mutation that `WorktreeManager.cleanup` relies on — the top planning risk never materialized because it was designed around up front.
+- Pre-completion reviewer returned a clean PASS on first dispatch with no findings.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified) — the `tdd-plan` "Verify green baseline" step says "stop and report" on any failed check, but the baseline `pnpm run lint` failed on 5 pre-existing orphaned issue-link definitions in `architecture.md` (from an earlier Phase 15 archive commit).
+  I fixed them as a separate `docs:` cleanup commit and proceeded rather than stopping.
+  This was the pragmatic call and matches the end-of-session rule ("Fix all failures — including pre-existing ones"), but the two prompt sections give opposite guidance for pre-existing failures.
+  Impact: no rework; one momentary judgment call against a contradictory prompt.
+- `missing-context` (user-caught) — in planning I posed the fold-vs-wrap choice to the user via `ask_user`, and the user responded by asking whether the architecture doc had already decided it.
+  The Phase 16 target table I had read already lists `WorktreeIsolation` as absorbing `worktreeState`, so the answer was partly in the doc.
+  Impact: one extra round-trip, no rework; confirming was still defensible since the issue body only mentioned losing 2 fields.
+
+#### What caused friction (user side)
+
+- None notable.
+  User involvement was a single low-cost confirmation; the rest was strategic delegation.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer`, running on `claude-sonnet-4-6-20260526` (declared in `.pi/agents/pre-completion-reviewer.md`).
+  Appropriate: judgment-heavy review work on a capable model, read-only tools.
+- **Escalation-delay tracking** — no `rabbit-hole` friction; the baseline lint was diagnosed and fixed in 3 tool calls (investigate refs → edit → re-lint).
+- **Feedback-loop gap analysis** — verification ran incrementally: `pnpm vitest run <file>` after each red and green phase, `pnpm run check` after the interface change, full suite + `fallow dead-code` from repo root before shipping.
+  No end-loaded verification gap.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — reconciled the "Verify green baseline" section with the end-of-session "fix pre-existing failures" rule: trivial pre-existing failures on untouched files may be fixed as a separate cleanup commit to establish a green baseline; non-trivial or unexplained failures still stop and report.

package/docs/retro/0257-extract-child-session-factory.md

@@ -0,0 +1,31 @@
+---
+issue: 257
+issue_title: "Extract ChildSessionFactory from runner"
+---
+
+# Retro: #257 — Extract ChildSessionFactory from runner
+
+> Superseded — #257 closed `not_planned`; the work was reframed as Phase 16 "invert dependencies" (ADR 0002, issues #261–#265).
+
+## Stage: Planning (2026-05-29T00:32:12Z)
+
+### Session summary
+
+Produced the implementation plan for Phase 16, Step 2 — extracting session *creation* out of `runAgent()` into a `ChildSessionFactory` collaborator while leaving session *interaction* in the runner.
+The plan is a lift-and-shift: `runAgent()` keeps its `(snapshot, type, prompt, options, deps)` signature and delegates creation to a new `ConcreteChildSessionFactory`, so the existing 313-line runner test suite keeps passing through delegation.
+`#256` (`WorktreeIsolation`) is already merged; this step is independent of it and gates Steps 3-4.
+
+### Observations
+
+- Two deliberate refinements of the issue's interface sketch, both forced by the lift-and-shift and documented in the plan:
+  - `ChildSessionResult` adds `agentMaxTurns?: number` — the turn-limit resolution lives in the interaction half but `cfg.agentMaxTurns` is only known after `assembleSessionConfig`, which moves into the factory.
+    Carrying one field across the seam (not the whole `SessionConfig`) is the ISP-narrow choice.
+  - `ChildSessionConfig` is kept narrow (six creation inputs); the issue's target also lists `prompt`/`maxTurns`/`getRunConfig`, but those are interaction concerns that would violate ISP for a creation-only factory.
+- Deferred `ConcreteAgentRunner.createFactory()` to Step 3 (#258) even though the issue lists it as a Step 2 outcome.
+  Adding it now yields an unused class member (fallow flags it): `runAgent` builds the factory directly, and `AgentManager` — the eventual `createFactory` caller — is not wired until Step 3.
+  The factory still has a production consumer this step (`runAgent`), so it is not dead.
+- The permission-bridge `vi.mock()` is path-based, so moving the `registerChildSession`/`unregisterChildSession` import from `agent-runner.ts` into the factory does not break the existing mock — it intercepts the factory's import unchanged.
+- Type-only import of `RunnerDeps` (factory → runner) plus value import of the factory class (runner → factory) is a one-way runtime arrow; `import type` erasure means no real cycle.
+- `RunResult.sessionFile` shifts from a late `sessionManager.getSessionFile()` to the factory's `outputFile` — same value (stable after `newSession()`); the existing `/sessions/child.jsonl` assertion is the guard.
+- Did not invoke `ask_user`: the issue's "Proposed change" is prescriptive, and the two deviations are forced/justified rather than open-ended.
+- IO interfaces (`RunnerIO`, `RunnerDeps`, etc.) intentionally stay in `agent-runner.ts` for this step to minimize churn; their relocation to the factory module is flagged as an Open Question for Step 4 when the runner dissolves.

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.3.0",
+  "version": "11.5.0",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/index.ts

@@ -25,6 +25,7 @@ import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
 import { ConcreteAgentRunner, type RunnerDeps } from "#src/lifecycle/agent-runner";
+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";
@@ -149,6 +150,7 @@ export default function (pi: ExtensionAPI) {
     },
     exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
     registry,
+    lifecycle: createChildLifecyclePublisher((channel, data) => pi.events.emit(channel, data)),
   };
 
   // ConcurrencyQueue: scheduling extracted from AgentManager.
@@ -165,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-runner.ts

@@ -9,8 +9,8 @@ import {
   type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import { registerChildSession, unregisterChildSession } from "#src/lifecycle/permission-bridge";
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
@@ -123,6 +123,8 @@ export interface RunnerDeps {
   io: RunnerIO;
   exec: ShellExec;
   registry: AgentConfigLookup;
+  /** Publishes the child-execution lifecycle so consumers can observe it. */
+  lifecycle: ChildLifecyclePublisher;
 }
 
 // ── Public interfaces ─────────────────────────────────────────────────────────
@@ -263,6 +265,9 @@ export async function runAgent(
   options: RunOptions,
   deps: RunnerDeps,
 ): Promise<RunResult> {
+  const parentSessionId = options.context.parentSession?.parentSessionId;
+  deps.lifecycle.spawning({ agentName: type, parentSessionId });
+
   // Resolve working directory upfront - needed for detectEnv before assembly.
   const effectiveCwd = options.context.cwd ?? snapshot.cwd;
   const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
@@ -327,14 +332,13 @@ export async function runAgent(
     thinkingLevel: cfg.thinkingLevel,
   });
 
-  // Register with pi-permission-system's SubagentSessionRegistry before
-  // bindExtensions() so isSubagentExecutionContext() hits the registry on the
-  // first check during child extension initialization. Unregistered in the
+  // Publish session-created before bindExtensions() so observers (e.g. the
+  // permission system) can register the child synchronously and have their
+  // entry in place for the first permission check during child extension
+  // initialization. The event bus dispatches synchronously, so a synchronous
+  // subscriber completes before this returns. Paired with disposed() in the
   // finally block below to guarantee cleanup on both success and error paths.
-  registerChildSession(sessionDir, {
-    agentName: type,
-    parentSessionId: options.context.parentSession?.parentSessionId,
-  });
+  deps.lifecycle.sessionCreated({ sessionDir, agentName: type, parentSessionId });
 
   // Bind extensions so that session_start fires and extensions can initialize
   // (e.g. loading credentials, setting up state). Placed after tool filtering
@@ -389,11 +393,12 @@ export async function runAgent(
 
   try {
     await session.prompt(effectivePrompt);
+    deps.lifecycle.completed({ sessionDir, agentName: type, aborted, steered: softLimitReached });
   } finally {
     unsubTurns();
     collector.unsubscribe();
     cleanupAbort();
-    unregisterChildSession(sessionDir);
+    deps.lifecycle.disposed({ sessionDir });
   }
 
   const responseText =