@gotgenes/pi-subagents 6.14.0 → 6.15.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [6.15.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.14.1...pi-subagents-v6.15.0) (2026-05-23)
+
+
+### Features
+
+* extract resolveSpawnConfig pure function ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([e89724a](https://github.com/gotgenes/pi-packages/commit/e89724a87480713529160d0fa23975becbcfe162))
+
+
+### Documentation
+
+* plan decompose execute and push ctx to boundary ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([aae7d7b](https://github.com/gotgenes/pi-packages/commit/aae7d7b4e04ab0dddedd2a0f9f2b806719956ced))
+* update architecture doc for completed Step M ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([33ec0c7](https://github.com/gotgenes/pi-packages/commit/33ec0c73479076c180381dcc1cb4106ba635f33f))
+* update plan with injected collaborators for ctx elimination ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([76bb57b](https://github.com/gotgenes/pi-packages/commit/76bb57b4b5190078ded8685907f0878640031e13))
+
+## [6.14.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.14.0...pi-subagents-v6.14.1) (2026-05-23)
+
+
+### Bug Fixes
+
+* resolve fallow dead-code warnings ([2113f6b](https://github.com/gotgenes/pi-packages/commit/2113f6bc49812ce32ac68d0e2dd88e0a60b4474a))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#152](https://github.com/gotgenes/pi-packages/issues/152) ([7337bc1](https://github.com/gotgenes/pi-packages/commit/7337bc175528b4fb99dbc765eb06f0bcf2accec1))
+
 ## [6.14.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.13.1...pi-subagents-v6.14.0) (2026-05-23)
 
 

package/docs/architecture/architecture.md

@@ -647,38 +647,24 @@ Apply the dependency bag convention to touched modules: `NotificationDeps` (4 fi
 
 Impact: eliminates dual counting; removes `??` fallback pattern from widget and conversation viewer; hides `ExecutionState` structure from consumers.
 
-### Step M: Decompose execute and push ExtensionContext to the boundary (#145)
+### Step M: Decompose execute and push ExtensionContext to the boundary (#145) ✓
 
-`execute` is 145 lines with three responsibilities mixed together:
+Extracted config resolution into `resolveSpawnConfig` (pure function in `spawn-config.ts`).
+Injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` so `execute` no longer reads `ctx` beyond `ctx.ui` (already delegated to `widget.setUICtx`).
+`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
+`service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
+`foreground-runner` and `background-spawner` receive `ResolvedSpawnConfig` + domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
 
-1. **Boundary extraction** (~5 lines) - read `ctx.model`, `ctx.modelRegistry`, `ctx.ui`, `ctx.sessionManager`, call `buildParentSnapshot(ctx)`.
-2. **Config resolution** (~60 lines) - resolve agent type, merge invocation config, resolve model, compute max turns, build tags and display metadata.
-3. **Dispatch** (~80 lines) - resume / background / foreground, each passing 14-16 field parameter bags.
-
-The config resolution section is working for the dependencies: manually unpacking `resolvedConfig` field by field, computing derived values, then repacking everything into massive objects for `spawnBackground` and `runForeground`.
-The 16-field bags are the symptom - they exist because the resolution happened in the wrong place.
-
-The fix has two parts:
-
-1. **Extract config resolution** into a pure function (e.g. `resolveSpawnConfig`) that accepts the raw tool params, registry, model info, and settings, and returns a single `ResolvedSpawnConfig` object.
-   `execute` becomes: extract ctx → resolve config → dispatch.
-   `spawnBackground` and `runForeground` receive `ResolvedSpawnConfig` instead of 16 individual fields.
-2. **Push `ctx` to the boundary.**
-   `execute` extracts everything from `ctx` in its first few lines.
-   `foreground-runner.ts` and `background-spawner.ts` receive domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
-   `AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
-   `service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
+Dissolved `ForegroundDeps`, `BackgroundDeps`, and `AdapterDeps` into plain parameters.
+`AgentToolDeps` is destructured in the `createAgentTool` signature.
 
 After this step, `ExtensionContext` appears only in:
 
-- `agent-tool.ts execute` (SDK callback - unavoidable)
+- `index.ts` closures (wired at extension startup)
 - `service-adapter.ts` (cross-extension boundary)
-- `index.ts` (extension entry point)
 - Menu handlers (addressed by Step N)
 
-Apply the dependency bag convention to touched modules: `ForegroundDeps` (3 fields) and `BackgroundDeps` (3 fields) become plain parameters; `AdapterDeps` (3 fields) becomes plain parameters; `AgentToolDeps` (6 fields) is destructured in the signature.
-
-Impact: `execute` drops from ~145 to ~30 lines; eliminates 16-field parameter bags; eliminates 1 `vi.mock()` call in `agent-manager.test.ts`; `foreground-runner` and `background-spawner` tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
+Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
 
 ### Step N: Narrow UI context for menu handlers (#146)
 
@@ -690,7 +676,7 @@ Creation wizard’s `spawnAndWait` call changes: the narrow `AgentMenuManager.sp
 
 Apply the dependency bag convention to touched modules: `AgentConfigEditorDeps` (4 fields), `SteerToolDeps` (4 fields), and `GetResultDeps` (4 fields) become plain parameters; `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) are destructured in the signature.
 
-After Steps M and N, `ExtensionContext` appears only at true boundaries: `agent-tool.ts execute` (SDK callback), `service-adapter.ts` (cross-extension bridge), and `index.ts` (extension entry point).
+After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures, `service-adapter.ts` (cross-extension bridge), and `index.ts` (extension entry point).
 
 Impact: eliminates ~43 `ctx as any` casts across menu, editor, and wizard test files; tests construct a plain object satisfying `MenuUI` with no cast.
 

package/docs/plans/0145-decompose-execute-push-ctx-to-boundary.md

@@ -0,0 +1,290 @@
+---
+issue: 145
+issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
+---
+
+# Decompose execute and push ctx to the boundary
+
+## Problem Statement
+
+`agent-tool.ts` `execute` is ~140 lines mixing three concerns: boundary extraction (~5 lines reading `ctx`), config resolution (~60 lines unpacking `resolvedConfig` field by field), and dispatch (~80 lines building 14–16 field parameter bags for `spawnBackground` and `runForeground`).
+The large parameter bags exist because config resolution happens inline instead of in a dedicated function.
+Meanwhile, `ExtensionContext` is threaded from `execute` through `ForegroundParams.ctx` / `BackgroundParams.ctx` into `foreground-runner` and `background-spawner`, where the only thing consumed is `sessionManager.getSessionFile()` and `sessionManager.getSessionId()`.
+`AgentManager.spawn()` and `spawnAndWait()` accept `ExtensionContext` directly and call `buildParentSnapshot(ctx)` internally — but this is already a pure boundary concern that belongs at the call site.
+Additionally, `execute` reaches into `ctx` for model info and session identity — these are session-scoped values that `index.ts` already captures and could inject as collaborators, removing `execute`'s need to read `ctx` beyond the UI context it already delegates to `widget.setUICtx()`.
+
+## Goals
+
+- Extract config resolution into a pure function (`resolveSpawnConfig`) so `execute` becomes: resolve config → dispatch.
+- Inject three missing collaborators into `createAgentTool` so `execute` no longer extracts values from `ctx`:
+  - `buildSnapshot: (inheritContext: boolean) => ParentSnapshot` — closure over `ctx`, wired in `index.ts`.
+  - `getModelInfo: () => ModelInfo` — provides `parentModel` and `modelRegistry` for `resolveSpawnConfig`.
+  - `getSessionInfo: () => { parentSessionFile: string; parentSessionId: string }` — parent session identity.
+- Replace `ForegroundParams.ctx` and `BackgroundParams.ctx` with plain domain values (`parentSessionFile`, `parentSessionId`, `snapshot`).
+- Change `AgentManager.spawn()` and `spawnAndWait()` to accept `ParentSnapshot` instead of `ExtensionContext`.
+- Move `buildParentSnapshot(ctx)` calls to the two boundaries: `index.ts` (via closure) and `service-adapter.ts`.
+- Eliminate the `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`.
+- Apply the dependency bag convention: dissolve `ForegroundDeps`, `BackgroundDeps`, `AdapterDeps` (each ≤3 fields) into plain parameters.
+- This is a breaking internal refactor — no public API changes.
+
+## Non-Goals
+
+- Narrowing menu handler ctx (Step N, #146) — deferred.
+- Injecting text wrapping into ConversationViewer (Step O, #147) — unrelated track.
+- Observation model consolidation (Step L, #144) — independent track.
+- Changing the `SubagentsService` public API in `service.ts`.
+
+## Background
+
+### Relevant modules
+
+| Module                        | Current role                                                                                     |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `tools/agent-tool.ts`         | `execute` callback — 140 lines, mixes boundary extraction, config resolution, dispatch           |
+| `tools/foreground-runner.ts`  | `runForeground()` — receives 14-field `ForegroundParams` including `ctx` with `sessionManager`   |
+| `tools/background-spawner.ts` | `spawnBackground()` — receives 14-field `BackgroundParams` including `ctx` with `sessionManager` |
+| `agent-manager.ts`            | `spawn()` / `spawnAndWait()` accept `ExtensionContext`, call `buildParentSnapshot()` internally  |
+| `parent-snapshot.ts`          | `buildParentSnapshot(ctx)` — pure function capturing `ParentSnapshot` from ctx                   |
+| `service-adapter.ts`          | Cross-extension boundary — calls `manager.spawn(session.ctx, ...)`                               |
+| `invocation-config.ts`        | `resolveAgentInvocationConfig()` — merges agent config with tool params                          |
+| `model-resolver.ts`           | `resolveInvocationModel()` — resolves model strings to model instances                           |
+| `index.ts`                    | Extension entry point — wires `createAgentTool` deps, captures `runtime.currentCtx`              |
+| `runtime.ts`                  | `SubagentRuntime` — holds session-scoped mutable state including `currentCtx`                    |
+
+### Constraints from AGENTS.md
+
+- Keep modules focused and composable (one concern per file).
+- Prefer explicit configuration over hidden behavior.
+- Keep Pi SDK imports out of business-logic modules.
+- Business logic should be pure functions — keep IO at the edges.
+
+### Phase 9 context
+
+This is Step M of Phase 9.
+It has no blockers and blocks Step N (#146), which narrows menu handler ctx.
+After this step, `ExtensionContext` appears only at true SDK/extension boundaries: `index.ts` closures, `service-adapter.ts`, and menu handlers.
+
+## Design Overview
+
+### Part 1: Extract config resolution (done)
+
+A new pure function `resolveSpawnConfig` in `spawn-config.ts` encapsulates all config resolution logic previously inline in `execute`.
+`execute` calls `resolveSpawnConfig(params, registry, modelInfo, settings)` and dispatches on the result.
+This is already committed.
+
+### Part 2: Inject collaborators and push ctx out of execute
+
+`execute` currently reads `ctx.model`, `ctx.modelRegistry`, `ctx.sessionManager`, and passes `ctx` to `buildParentSnapshot`.
+These are all session-scoped values that `index.ts` captures at session start.
+Three collaborators replace the `ctx` reads:
+
+```typescript
+// Injected as plain parameters into createAgentTool:
+buildSnapshot: (inheritContext: boolean) => ParentSnapshot,
+getModelInfo: () => ModelInfo,
+getSessionInfo: () => { parentSessionFile: string; parentSessionId: string },
+```
+
+`index.ts` wires them as closures over `runtime.currentCtx`:
+
+```typescript
+createAgentTool({
+  // ... existing params ...
+  buildSnapshot: (inheritContext) => buildParentSnapshot(ctx, inheritContext),
+  getModelInfo: () => ({
+    parentModel: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+  }),
+  getSessionInfo: () => ({
+    parentSessionFile: ctx.sessionManager.getSessionFile(),
+    parentSessionId: ctx.sessionManager.getSessionId(),
+  }),
+})
+```
+
+After this, `execute` touches `ctx` only for `ctx.ui` — which is already delegated via `widget.setUICtx()`.
+The `ExtensionContext` import in `agent-tool.ts` is removed entirely.
+
+### Part 3: Push ctx out of AgentManager
+
+`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
+The internal `buildParentSnapshot(ctx, ...)` call is removed — `snapshot` arrives pre-built from the call sites.
+`service-adapter.ts` calls `buildParentSnapshot(session.ctx, ...)` at its boundary before delegating.
+
+### Part 4: Push ctx out of foreground-runner and background-spawner
+
+`ForegroundParams.ctx` and `BackgroundParams.ctx` are replaced by `snapshot: ParentSnapshot`, `parentSessionFile: string`, `parentSessionId: string`.
+The narrow manager interfaces change from `ctx: any` to `snapshot: ParentSnapshot`.
+
+### Part 5: Shrink params bags with ResolvedSpawnConfig
+
+`ForegroundParams` and `BackgroundParams` carry `ResolvedSpawnConfig` instead of 10+ individual fields that were computed during config resolution.
+Only dispatch-specific fields (`rawType`, `fellBack`, `toolCallId`, `displayName`) remain as separate params fields.
+
+### Part 6: Dissolve small dependency bags
+
+Per the dependency bag convention:
+
+- `ForegroundDeps` (3 fields) → plain parameters on `runForeground`.
+- `BackgroundDeps` (3 fields) → plain parameters on `spawnBackground`.
+- `AdapterDeps` (4 fields) → plain parameters on `createSubagentsService`.
+- `AgentToolDeps` → destructured in the `createAgentTool` signature; the interface stays as a named type for the test factory.
+
+The narrow `*ManagerDeps` and `*WidgetDeps` interfaces stay — they define the contract each function needs from its collaborators.
+
+## Module-Level Changes
+
+### New file: `src/tools/spawn-config.ts` (done)
+
+- `ResolvedSpawnConfig` interface.
+- `ModelInfo` interface.
+- `resolveSpawnConfig()` pure function.
+
+### Modified: `src/tools/agent-tool.ts`
+
+- `execute` shrinks from ~140 to ~20 lines.
+- `ExtensionContext` import removed — `execute` no longer reads `ctx` directly (beyond `ctx.ui` via widget).
+- Three new collaborator parameters: `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
+- Calls `resolveSpawnConfig(params, registry, getModelInfo(), settings)`.
+- Calls `buildSnapshot(config.inheritContext)` for the snapshot.
+- Calls `getSessionInfo()` for parent session identity.
+- Passes domain values (not `ctx`) to `runForeground` / `spawnBackground`.
+- `AgentToolManager.spawn` and `spawnAndWait` signatures change to accept `ParentSnapshot`.
+- `AgentToolDeps` stays as a named type (used by test factory) but its fields are destructured in `createAgentTool`.
+
+### Modified: `src/tools/foreground-runner.ts`
+
+- `ForegroundDeps` interface removed — `runForeground` accepts `manager`, `widget`, `agentActivity` as plain parameters.
+- `ForegroundParams.ctx` removed — replaced by `snapshot`, `parentSessionFile`, `parentSessionId`.
+- `ForegroundManagerDeps.spawnAndWait` signature changes from `ctx: any` to `snapshot: ParentSnapshot`.
+- Individual config fields move into `ResolvedSpawnConfig`.
+
+### Modified: `src/tools/background-spawner.ts`
+
+- `BackgroundDeps` interface removed — `spawnBackground` accepts `manager`, `widget`, `agentActivity` as plain parameters.
+- `BackgroundParams.ctx` removed — replaced by `snapshot`, `parentSessionFile`, `parentSessionId`.
+- `BackgroundManagerDeps.spawn` signature changes from `ctx: any` to `snapshot: ParentSnapshot`.
+- Individual config fields move into `ResolvedSpawnConfig`.
+
+### Modified: `src/agent-manager.ts`
+
+- `spawn()` signature changes from `ctx: ExtensionContext` to `snapshot: ParentSnapshot`.
+- `spawnAndWait()` signature changes from `ctx: ExtensionContext` to `snapshot: ParentSnapshot`.
+- Internal `buildParentSnapshot(ctx, ...)` call removed.
+- Imports of `ExtensionContext` and `buildParentSnapshot` removed.
+
+### Modified: `src/service-adapter.ts`
+
+- `AdapterDeps` interface removed — `createSubagentsService` accepts plain parameters.
+- `AgentManagerLike.spawn` signature changes from `ctx: unknown` to `snapshot: ParentSnapshot`.
+- `spawn()` method calls `buildParentSnapshot(session.ctx, options?.inheritContext)` before delegating.
+- Adds imports of `buildParentSnapshot` and `ParentSnapshot`.
+
+### Modified: `src/index.ts`
+
+- Wiring for `createAgentTool` adds three collaborator closures: `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
+- `manager.spawn` / `spawnAndWait` wiring adapters removed (closures no longer need to relay `ctx`).
+- Wiring for `createSubagentsService` changes from bag to plain arguments.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+- `spawn-config.test.ts` (done) — pure-function tests for `resolveSpawnConfig`.
+
+### Existing tests that simplify
+
+- `agent-manager.test.ts` — the `vi.mock("../src/parent-snapshot.js")` block is removed.
+  All tests pass a plain `ParentSnapshot` object directly instead of `mockCtx`.
+- `foreground-runner.test.ts` — `makeCtx()` helper removed; plain strings for session identity.
+- `background-spawner.test.ts` — same as foreground.
+- `agent-tool.test.ts` — `makeCtx()` simplified; collaborator stubs replace `ctx.model` / `ctx.modelRegistry` reads.
+- `service-adapter.test.ts` — adapter test setup changes from bag to plain parameters.
+
+### Existing tests that stay
+
+- `parent-snapshot.test.ts` — unchanged; `buildParentSnapshot` is still a standalone pure function.
+
+## TDD Order
+
+### Step 1: Extract resolveSpawnConfig (done)
+
+1. ~~Write `spawn-config.test.ts`, implement `spawn-config.ts`.~~
+   Commit: `feat: extract resolveSpawnConfig pure function (#145)` ✓
+
+2. ~~Rewire `execute` to call `resolveSpawnConfig`.~~
+   Commit: `refactor: use resolveSpawnConfig in execute (#145)` ✓
+
+### Step 2: Push ctx out of AgentManager
+
+3. Red: update `agent-manager.test.ts` — replace `mockCtx` with a plain `ParentSnapshot` object, remove `vi.mock("../src/parent-snapshot.js")`.
+   Green: change `AgentManager.spawn()` and `spawnAndWait()` to accept `ParentSnapshot`.
+   Update `agent-tool.ts` manager interface, `service-adapter.ts` to call `buildParentSnapshot` at its boundary, and `index.ts` wiring.
+   Commit: `refactor: AgentManager accepts ParentSnapshot instead of ExtensionContext (#145)`
+
+### Step 3: Inject collaborators into createAgentTool
+
+4. Red: update `agent-tool.test.ts` — add `buildSnapshot`, `getModelInfo`, `getSessionInfo` stubs to `createToolDeps`; simplify `makeCtx()`.
+   Green: add three collaborator parameters to `createAgentTool`; rewrite `execute` to use them instead of `ctx.model` / `ctx.modelRegistry` / `ctx.sessionManager`.
+   Remove `ExtensionContext` import from `agent-tool.ts`.
+   Update `index.ts` wiring to provide closures.
+   Commit: `refactor: inject collaborators into createAgentTool, eliminate ctx reads (#145)`
+
+### Step 4: Push ctx out of foreground-runner and background-spawner
+
+5. Red: update `foreground-runner.test.ts` — remove `makeCtx()`, replace `ForegroundParams.ctx` with `snapshot` / `parentSessionFile` / `parentSessionId`.
+   Green: change `ForegroundParams` to use plain domain values, update `runForeground` accordingly.
+   Commit: `refactor: foreground-runner receives domain values instead of ctx (#145)`
+
+6. Red: update `background-spawner.test.ts` — remove `makeCtx()`, replace `BackgroundParams.ctx` with `snapshot` / `parentSessionFile` / `parentSessionId`.
+   Green: change `BackgroundParams` to use plain domain values, update `spawnBackground` accordingly.
+   Commit: `refactor: background-spawner receives domain values instead of ctx (#145)`
+
+### Step 5: Shrink params bags with ResolvedSpawnConfig
+
+7. Red: update `foreground-runner.test.ts` `makeParams()` to use `ResolvedSpawnConfig` fields.
+   Green: change `ForegroundParams` to carry `ResolvedSpawnConfig`.
+   Update `agent-tool.ts` dispatch to pass the config through.
+   Commit: `refactor: ForegroundParams carries ResolvedSpawnConfig (#145)`
+
+8. Red: update `background-spawner.test.ts` `makeParams()` to use `ResolvedSpawnConfig` fields.
+   Green: change `BackgroundParams` to carry `ResolvedSpawnConfig`.
+   Update `agent-tool.ts` dispatch to pass the config through.
+   Commit: `refactor: BackgroundParams carries ResolvedSpawnConfig (#145)`
+
+### Step 6: Dissolve small dependency bags
+
+9. Red: update `foreground-runner.test.ts` calls to pass `manager`, `widget`, `agentActivity` as plain args.
+   Green: remove `ForegroundDeps` interface, change `runForeground` signature.
+   Commit: `refactor: dissolve ForegroundDeps into plain parameters (#145)`
+
+10. Red: update `background-spawner.test.ts` calls to pass plain args.
+    Green: remove `BackgroundDeps` interface, change `spawnBackground` signature.
+    Commit: `refactor: dissolve BackgroundDeps into plain parameters (#145)`
+
+11. Red: update `service-adapter.test.ts` to pass plain parameters instead of `AdapterDeps` bag.
+    Green: remove `AdapterDeps` interface, change `createSubagentsService` signature.
+    Update `index.ts` wiring call site.
+    Commit: `refactor: dissolve AdapterDeps into plain parameters (#145)`
+
+12. Refactor: destructure `AgentToolDeps` in `createAgentTool` signature (keep the named type for test factory).
+    Commit: `refactor: destructure AgentToolDeps in createAgentTool (#145)`
+
+### Step 7: Final verification
+
+13. Run full test suite and type check.
+
+## Risks and Mitigations
+
+| Risk                                                                  | Mitigation                                                                                                                                                                      |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Wide blast radius — touches 7+ source files and 5+ test files         | Incremental TDD steps; each commit leaves the repo green                                                                                                                        |
+| `service-adapter.ts` now imports `buildParentSnapshot` — new coupling | Acceptable: the adapter is already a boundary module that bridges `ExtensionContext` to domain types                                                                            |
+| `ResolvedSpawnConfig` could become a new "god object"                 | It is a pure data return from a single function; consumers destructure what they need                                                                                           |
+| Three new collaborators grow `AgentToolDeps` from 6 to 9 fields       | The deps bag is destructured at the signature; the named type exists only for the test factory. The real dependency count stays the same — previously hidden behind `ctx` reads |
+| `index.ts` closures capture `ctx` — stale reference risk              | Same pattern `service-adapter.ts` already uses via `runtime.currentCtx`; session lifecycle clears on shutdown                                                                   |
+
+## Open Questions
+
+- The exact boundary between fields that stay in `ForegroundParams` / `BackgroundParams` vs. fields that move into `ResolvedSpawnConfig` may shift during implementation.
+  The guiding principle: if the field is computed during config resolution, it belongs in `ResolvedSpawnConfig`; if it is dispatch-specific (e.g., `toolCallId`, `signal`, `onUpdate`), it stays in the params type.

package/docs/retro/0152-add-prompt-snippet.md

@@ -0,0 +1,34 @@
+---
+issue: 152
+issue_title: "Add promptSnippet to pi-subagents tools"
+---
+
+# Retro: #152 — Add `promptSnippet` to pi-subagents tools
+
+## Final Retrospective (2026-05-22)
+
+### Session summary
+
+Added `promptSnippet` to the `Agent`, `get_subagent_result`, and `steer_subagent` tool registrations in pi-subagents, matching the convention used by pi-github-tools and pi-colgrep.
+The full plan→TDD→ship pipeline completed in one session with zero rework.
+Released as `pi-subagents-v6.14.0`.
+
+### Observations
+
+#### What went well
+
+- Clean single-cycle execution: the issue was unambiguous, the plan correctly scoped it as one TDD step, and the implementation matched the plan exactly.
+- Cross-package convention check (grepping sibling packages for `promptSnippet` usage) confirmed the `"tool_name: One-liner."` format before writing the plan, avoiding any wording rework.
+
+#### What caused friction (agent side)
+
+No friction points identified.
+The issue was a straightforward property addition with no design decisions, no interface changes, and no downstream breakage.
+
+#### What caused friction (user side)
+
+No friction points identified.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0152-add-prompt-snippet.md` (this file).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.14.0",
+  "version": "6.15.0",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -35,8 +35,7 @@
     "@earendil-works/pi-tui": ">=0.75.0"
   },
   "dependencies": {
-    "@sinclair/typebox": "^0.34.49",
-    "nanoid": "^5.0.0"
+    "@sinclair/typebox": "^0.34.49"
   },
   "engines": {
     "node": ">=22"

package/src/agent-manager.ts

@@ -8,14 +8,13 @@
 
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSession, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
 import { NotificationState } from "./notification-state.js";
 import type { ParentSnapshot } from "./parent-snapshot.js";
-import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
@@ -141,7 +140,7 @@ export class AgentManager {
    * If the concurrency limit is reached, the agent is queued.
    */
   spawn(
-    ctx: ExtensionContext,
+    snapshot: ParentSnapshot,
     type: SubagentType,
     prompt: string,
     options: AgentSpawnConfig,
@@ -167,7 +166,6 @@ export class AgentManager {
       this.observer?.onAgentCreated(record);
     }
 
-    const snapshot = buildParentSnapshot(ctx, options.inheritContext);
     const args: SpawnArgs = { snapshot, type, prompt, options };
 
     if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
@@ -332,12 +330,12 @@ export class AgentManager {
    * Foreground agents bypass the concurrency queue.
    */
   async spawnAndWait(
-    ctx: ExtensionContext,
+    snapshot: ParentSnapshot,
     type: SubagentType,
     prompt: string,
     options: Omit<AgentSpawnConfig, "isBackground">,
   ): Promise<AgentRecord> {
-    const id = this.spawn(ctx, type, prompt, { ...options, isBackground: false });
+    const id = this.spawn(snapshot, type, prompt, { ...options, isBackground: false });
     const record = this.agents.get(id)!;
     await record.promise;
     return record;
@@ -430,6 +428,7 @@ export class AgentManager {
   }
 
   /** Whether any agents are still running or queued. */
+  // fallow-ignore-next-line unused-class-member
   hasRunning(): boolean {
     return [...this.agents.values()].some(
       r => r.status === "running" || r.status === "queued",
@@ -437,6 +436,7 @@ export class AgentManager {
   }
 
   /** Abort all running and queued agents immediately. */
+  // fallow-ignore-next-line unused-class-member
   abortAll(): number {
     let count = 0;
     // Clear queued agents first
@@ -460,6 +460,7 @@ export class AgentManager {
   }
 
   /** Wait for all running and queued agents to complete (including queued ones). */
+  // fallow-ignore-next-line unused-class-member
   async waitForAll(): Promise<void> {
     // Loop because drainQueue respects the concurrency limit — as running
     // agents finish they start queued ones, which need awaiting too.

package/src/handlers/index.ts

@@ -1,6 +1,2 @@
-export {
-  type LifecycleManager,
-  type LifecycleRuntime,
-  SessionLifecycleHandler,
-} from "./lifecycle.js";
-export { ToolStartHandler, type ToolStartRuntime } from "./tool-start.js";
+export { SessionLifecycleHandler } from "./lifecycle.js";
+export { ToolStartHandler } from "./tool-start.js";

package/src/index.ts

@@ -29,6 +29,7 @@ import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
+import { buildParentSnapshot } from "./parent-snapshot.js";
 import { buildAgentPrompt } from "./prompts.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
@@ -162,12 +163,12 @@ export default function (pi: ExtensionAPI) {
 
   // Typed service published via Symbol.for() for cross-extension access.
   // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");
-  const service = createSubagentsService({
+  const service = createSubagentsService(
     manager,
     resolveModel,
-    getCtx: () => runtime.currentCtx,
-    getModelRegistry: () => (runtime.currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
-  });
+    () => runtime.currentCtx,
+    () => (runtime.currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
+  );
   publishSubagentsService(service);
 
   const lifecycle = new SessionLifecycleHandler(
@@ -193,8 +194,8 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerTool(defineTool(createAgentTool({
     manager: {
-      spawn: (ctx, type, prompt, opts) => manager.spawn(ctx, type, prompt, opts),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
+      spawn: (snapshot, type, prompt, opts) => manager.spawn(snapshot, type, prompt, opts),
+      spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
       getMaxConcurrent: () => settings.maxConcurrent,
@@ -209,6 +210,19 @@ export default function (pi: ExtensionAPI) {
     registry,
     agentDir: getAgentDir(),
     settings,
+    buildSnapshot: (inheritContext) =>
+      buildParentSnapshot(
+        runtime.currentCtx?.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext,
+        inheritContext,
+      ),
+    getModelInfo: () => ({
+      parentModel: (runtime.currentCtx?.ctx as any)?.model,
+      modelRegistry: (runtime.currentCtx?.ctx as any)?.modelRegistry,
+    }),
+    getSessionInfo: () => ({
+      parentSessionFile: (runtime.currentCtx?.ctx as any)?.sessionManager?.getSessionFile() ?? "",
+      parentSessionId: (runtime.currentCtx?.ctx as any)?.sessionManager?.getSessionId() ?? "",
+    }),
   })));
 
   // ---- get_subagent_result tool ----
@@ -235,7 +249,7 @@ export default function (pi: ExtensionAPI) {
     manager: {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
+      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(buildParentSnapshot(ctx), type, prompt, opts),
     },
     registry,
     agentActivity: runtime.agentActivity,

package/src/service-adapter.ts

@@ -5,13 +5,16 @@
  * (stripping non-serializable fields), and session gating.
  */
 
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ModelRegistry } from "./model-resolver.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
+import { buildParentSnapshot } from "./parent-snapshot.js";
 import type { SubagentRecord, SubagentsService } from "./service.js";
 import type { AgentRecord } from "./types.js";
 
 /** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
 export interface AgentManagerLike {
-  spawn(ctx: unknown, type: string, prompt: string, options: unknown): string;
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
   getRecord(id: string): AgentRecord | undefined;
   listAgents(): AgentRecord[];
   abort(id: string): boolean;
@@ -20,32 +23,27 @@ export interface AgentManagerLike {
   queueSteer(id: string, message: string): boolean;
 }
 
-/** Dependencies injected into the adapter factory. */
-export interface AdapterDeps {
-  manager: AgentManagerLike;
-  resolveModel: (input: string, registry: ModelRegistry) => unknown | string;
-  getCtx: () => { pi: unknown; ctx: unknown } | undefined;
-  getModelRegistry: () => ModelRegistry | undefined;
-}
-
 /** Create a SubagentsService backed by the given dependencies. */
-export function createSubagentsService(deps: AdapterDeps): SubagentsService {
-  const { manager } = deps;
-
+export function createSubagentsService(
+  manager: AgentManagerLike,
+  resolveModel: (input: string, registry: ModelRegistry) => unknown | string,
+  getCtx: () => { pi: unknown; ctx: unknown } | undefined,
+  getModelRegistry: () => ModelRegistry | undefined,
+): SubagentsService {
   return {
     spawn(type: string, prompt: string, options?) {
-      const session = deps.getCtx();
+      const session = getCtx();
       if (!session) {
         throw new Error("No active session — cannot spawn agents outside a session.");
       }
 
       let model: unknown;
       if (options?.model) {
-        const registry = deps.getModelRegistry();
+        const registry = getModelRegistry();
         if (!registry) {
           throw new Error("No model registry available.");
         }
-        const resolved = deps.resolveModel(options.model, registry);
+        const resolved = resolveModel(options.model, registry);
         if (typeof resolved === "string") {
           throw new Error(resolved);
         }
@@ -55,7 +53,11 @@ export function createSubagentsService(deps: AdapterDeps): SubagentsService {
       const description = options?.description ?? prompt.slice(0, 80);
       const isBackground = !(options?.foreground ?? false);
 
-      return manager.spawn(session.ctx, type, prompt, {
+      const snapshot = buildParentSnapshot(
+        session.ctx as ExtensionContext,
+        options?.inheritContext,
+      );
+      return manager.spawn(snapshot, type, prompt, {
         description,
         model,
         maxTurns: options?.maxTurns,