@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0147-inject-wrap-text-into-conversation-viewer.md

@@ -1,166 +0,0 @@
----
-issue: 147
-issue_title: "Inject text wrapping into ConversationViewer (Phase 9, Step O)"
----
-
-# Inject text wrapping into ConversationViewer
-
-## Problem Statement
-
-`ConversationViewer` calls `wrapTextWithAnsi` directly from `@earendil-works/pi-tui` in four places inside `buildContentLines`.
-Because the function is a module-level binding, tests must intercept it via a hoisted `vi.mock("@earendil-works/pi-tui")` factory that replaces the entire TUI module.
-This is the last `vi.mock` on an SDK module in the test suite, added specifically to exercise the overwidth-clamping safety net.
-
-## Goals
-
-- Accept `wrapText: (text: string, width: number) => string[]` via `ConversationViewerOptions`.
-- Destructure `ConversationViewerOptions` in the constructor signature (dependency bag convention).
-- Replace all four `wrapTextWithAnsi` calls in `buildContentLines` with `this.wrapText`.
-- Remove `wrapTextWithAnsi` from `conversation-viewer.ts`'s `@earendil-works/pi-tui` import.
-- Pass `wrapTextWithAnsi` at the production call site in `agent-menu.ts`.
-- Eliminate the hoisted `vi.mock("@earendil-works/pi-tui")` from `conversation-viewer.test.ts`.
-
-## Non-Goals
-
-- Injecting `truncateToWidth` or any other TUI function (only `wrapTextWithAnsi` is relevant here).
-- Changing the overwidth-clamping behavior of `buildContentLines`.
-- Touching `agent-widget.ts` (tracked separately as Issue #148, Step P — already closed).
-
-## Background
-
-`ui/conversation-viewer.ts` is the live conversation overlay rendered when a user selects an agent in the `/agents` menu.
-Its `buildContentLines` method formats messages from the agent session into displayable lines, calling `wrapTextWithAnsi` to soft-wrap text to the available terminal width.
-
-The overwidth-clamping safety net (`truncateToWidth` applied after `wrapTextWithAnsi`) exists because a prior upstream bug returned lines wider than the requested width.
-The `vi.mock` in the test is the mechanism for simulating that bug by returning overwidth strings from `wrapTextWithAnsi`.
-
-The only production call site for `new ConversationViewer(...)` is in the `viewAgentConversation` closure inside `createAgentsMenuHandler` in `ui/agent-menu.ts`.
-
-Architecture reference: `docs/architecture/architecture.md` § Phase 9, Step O.
-
-## Design Overview
-
-### `ConversationViewerOptions` — add `wrapText`
-
-```typescript
-export interface ConversationViewerOptions {
-  tui: TUI;
-  session: AgentSession;
-  record: AgentRecord;
-  activity: AgentActivityTracker | undefined;
-  theme: Theme;
-  done: (result: undefined) => void;
-  registry: AgentConfigLookup;
-  wrapText: (text: string, width: number) => string[];
-}
-```
-
-The field is **required** — it must be supplied at every construction site.
-No default is provided; the default would be an invisible SDK dependency hidden inside the class.
-
-### Constructor destructuring
-
-The constructor adopts the dependency bag convention — destructure the options object rather than accessing via `options.*`:
-
-```typescript
-constructor({
-  tui, session, record, activity, theme, done, registry, wrapText,
-}: ConversationViewerOptions) {
-  this.tui = tui;
-  this.session = session;
-  // … etc.
-  this.wrapText = wrapText;
-  this.unsubscribe = session.subscribe(() => { … });
-}
-```
-
-### Production wiring — `agent-menu.ts`
-
-`agent-menu.ts` statically imports `wrapTextWithAnsi` from `@earendil-works/pi-tui` and passes it when constructing `ConversationViewer`:
-
-```typescript
-import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
-// …
-return new ConversationViewer({
-  tui, session, record, activity, theme, done, registry,
-  wrapText: wrapTextWithAnsi,
-});
-```
-
-Adding `wrapText` to `AgentMenuDeps` and threading it through the closure would violate the Law of Demeter — `AgentMenuDeps` has no conceptual ownership of a text-wrapping function.
-The `viewAgentConversation` closure is the direct consumer; the import belongs there.
-
-### Test strategy
-
-After DI, tests pass `wrapText` directly in `ConversationViewerOptions`:
-
-- **"render width safety" tests**: pass `wrapText: wrapTextWithAnsi` (real function, statically imported — no mock).
-- **"safety net" tests**: pass a stub `wrapText: () => ["X".repeat(width + 50)]` inline in options — no `vi.mock` needed.
-- The "mock is intercepting wrapTextWithAnsi" test is removed (it verified the mock mechanism, not viewer behavior).
-- The module-level `wrapOverride` variable and the `vi.mock` block are removed entirely.
-- The `await import("@earendil-works/pi-tui")` and `await import("../src/ui/conversation-viewer.js")` dynamic imports are converted to ordinary top-level `import` statements.
-
-## Module-Level Changes
-
-| File                               | Change                                                                                                                                                                                                                                                       |
-| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `src/ui/conversation-viewer.ts`    | Add `wrapText` field to `ConversationViewerOptions`; add `private wrapText` field; destructure options in constructor; replace 4× `wrapTextWithAnsi(...)` with `this.wrapText(...)`; remove `wrapTextWithAnsi` from the `@earendil-works/pi-tui` import line |
-| `src/ui/agent-menu.ts`             | Add `import { wrapTextWithAnsi } from "@earendil-works/pi-tui"`; pass `wrapText: wrapTextWithAnsi` in `viewAgentConversation`                                                                                                                                |
-| `test/conversation-viewer.test.ts` | Convert top-level dynamic `await import()` to static imports; remove `vi.mock`, `wrapOverride`, and "mock is intercepting" test; add `wrapText` to every `new ConversationViewer({…})` call; update safety-net tests to pass inline stub `wrapText`          |
-
-No symbols are removed from exported API (`ConversationViewerOptions`, `ConversationViewer`, `VIEWPORT_HEIGHT_PCT` all remain).
-The `wrapText` addition to `ConversationViewerOptions` is a breaking change for any external consumers that construct `ConversationViewer` — check for usages outside this package.
-
-Grep check: `ConversationViewer` appears only in `src/ui/conversation-viewer.ts`, `src/ui/agent-menu.ts`, and `test/conversation-viewer.test.ts` — no other files construct it.
-
-## Test Impact Analysis
-
-1. **New unit-test capability**: The safety-net tests can now inject exactly the stub they need without patching a module.
-   Each test is self-contained and immediately legible — the stub is declared inline at the call site.
-
-2. **Tests that become redundant**: The "mock is intercepting wrapTextWithAnsi" test verified the test mechanism, not production behavior.
-   It is deleted.
-   The `wrapOverride` reset in `beforeEach` is no longer needed.
-
-3. **Tests that stay**: All "render width safety" tests and all overwidth-clamping tests remain; they exercise real viewer behavior with real or controlled inputs.
-
-## TDD Order
-
-### Cycle 1 — Add `wrapText` field and update production wiring
-
-1. **Red**: Update one `new ConversationViewer({…})` in the test to include `wrapText: vi.fn()` — TypeScript rejects the unknown field.
-2. **Green**:
-   - Add `wrapText: (text: string, width: number) => string[]` to `ConversationViewerOptions`.
-   - Add `private wrapText: (text: string, width: number) => string[]` field to the class.
-   - Destructure options in the constructor; assign `this.wrapText = wrapText`.
-   - Replace all four `wrapTextWithAnsi(...)` calls with `this.wrapText(...)` in `buildContentLines`.
-   - Remove `wrapTextWithAnsi` from the `@earendil-works/pi-tui` import in `conversation-viewer.ts`.
-   - In `agent-menu.ts`: add static import of `wrapTextWithAnsi` from `@earendil-works/pi-tui`; pass `wrapText: wrapTextWithAnsi`.
-   - Update **all** `new ConversationViewer({…})` calls in `conversation-viewer.test.ts` to include `wrapText`.
-     "Render width safety" tests pass `wrapText: wrapTextWithAnsi` (real function, still imported via the existing `vi.mock` shim for now).
-     Safety-net tests pass a stub inline: `wrapText: () => ["X".repeat(w + 50)]`.
-   - Delete the "mock is intercepting wrapTextWithAnsi" test.
-3. **Verify**: `pnpm vitest run test/conversation-viewer.test.ts` passes.
-4. **Commit**: `feat: inject wrapText into ConversationViewer (Phase 9, Step O) (#147)`
-
-### Cycle 2 — Remove the module mock
-
-1. **Red**: Remove the `vi.mock("@earendil-works/pi-tui", …)` block, the `wrapOverride` variable, and the `beforeEach(() => { wrapOverride = null; })` reset.
-   Convert `const { visibleWidth } = await import("@earendil-works/pi-tui")` to `import { visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui"`.
-   Convert `const { ConversationViewer } = await import("../src/ui/conversation-viewer.js")` to `import { ConversationViewer } from "../src/ui/conversation-viewer.js"`.
-   Run tests — they should still pass (the mock was no longer needed after Cycle 1).
-2. **Green**: Tests pass without any module mock.
-3. **Verify**: `pnpm vitest run test/conversation-viewer.test.ts` and `pnpm run check` both pass.
-4. **Commit**: `refactor: remove vi.mock from conversation-viewer tests (#147)`
-
-## Risks and Mitigations
-
-| Risk                                                                              | Mitigation                                                                                             |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Missing a `new ConversationViewer({…})` call site in tests                        | Grep confirms only `test/conversation-viewer.test.ts` constructs the viewer; all instances are in-file |
-| TypeScript missing the `private wrapText` field type                              | Use `pnpm run check` after Cycle 1 to verify no type errors                                            |
-| The dynamic `await import()` pattern in tests was necessary for some other reason | The only purpose was to run after `vi.mock` hoisting; once the mock is gone, static imports work fine  |
-
-## Open Questions
-
-None — the issue's "Changes" section is unambiguous and the call-site inventory is small.

package/docs/plans/0148-split-agent-widget-rendering.md

@@ -1,255 +0,0 @@
----
-issue: 148
-issue_title: "Split AgentWidget rendering from lifecycle (Phase 9, Step P)"
----
-
-# Split AgentWidget rendering from lifecycle
-
-## Problem Statement
-
-`AgentWidget` (374 lines) mixes rendering, lifecycle management, spinner animation, state filtering, and status bar management in a single class.
-`renderWidget` alone is ~109 lines, and `renderFinishedLine` adds another ~40.
-The constructor takes 3 concrete collaborators (`AgentManager`, `Map<string, AgentActivityTracker>`, `AgentTypeRegistry`) with no interface extraction.
-Rendering logic cannot be unit-tested without instantiating the full widget with its lifecycle machinery.
-
-## Goals
-
-- Extract pure rendering functions from `AgentWidget` into `ui/widget-renderer.ts`.
-- Make `AgentWidget` a thin lifecycle/polling wrapper that delegates to pure render functions.
-- Enable direct unit testing of rendering logic with plain data — no widget lifecycle, no mocks for `setInterval`/`setWidget`/`requestRender`.
-
-## Non-Goals
-
-- Changing the visual output of the widget (this is a pure refactor).
-- Extracting the status bar logic into a separate module (could follow up).
-- Narrowing the `AgentManager` dependency to an interface (tracked separately in the architecture doc).
-- Injecting `truncateToWidth` (tracked as #147, Step O — an independent track).
-
-## Background
-
-### Dependency: #144 (Step L) — Consolidate observation model
-
-Issue #144 is **closed/implemented**.
-The renderer now reads stats (`toolUses`, `lifetimeUsage`, `compactionCount`) from `AgentRecord` and live UI state (`activeTools`, `responseText`, `turnCount`, `maxTurns`) from `AgentActivityTracker`.
-No dual-counting fallback exists.
-
-### Existing pure helpers
-
-`ui/display.ts` already contains stateless formatting functions (`formatMs`, `formatTurns`, `formatSessionTokens`, `describeActivity`, `getDisplayName`, `getPromptModeLabel`, `SPINNER`, `ERROR_STATUSES`, `Theme`).
-The new `widget-renderer.ts` will consume these — it does not duplicate them.
-
-### Rendering data flow
-
-The widget's `renderWidget` currently:
-
-1. Calls `this.manager.listAgents()` to get `AgentRecord[]`.
-2. Categorizes into running/queued/finished.
-3. Filters finished agents via `this.shouldShowFinished()`.
-4. Looks up `this.agentActivity.get(a.id)` for live stats.
-5. Calls `this.registry` for display names.
-6. Reads `this.widgetFrame` for spinner animation.
-7. Assembles tree-style lines with overflow logic.
-
-Steps 3–7 are pure given the right inputs.
-Steps 1–2 are also pure categorization.
-
-## Design Overview
-
-### Separation of concerns
-
-The rendering extraction splits the widget into two layers:
-
-1. **`widget-renderer.ts`** — Pure functions that accept data and return `string[]`.
-   No `this`, no timers, no SDK types, no side effects.
-2. **`agent-widget.ts`** — Thin lifecycle wrapper that owns timers, UICtx, finished-turn aging, and calls the renderer with live data.
-
-### Renderer input shape
-
-Rather than passing the full `AgentRecord` class (which carries mutation methods and phase collaborators), the renderer receives a plain data slice:
-
-```typescript
-/** Minimal agent snapshot for rendering — no class methods, no mutation surface. */
-export interface WidgetAgent {
-  readonly id: string;
-  readonly type: SubagentType;
-  readonly status: string;
-  readonly description: string;
-  readonly toolUses: number;
-  readonly startedAt: number;
-  readonly completedAt?: number;
-  readonly error?: string;
-  readonly lifetimeUsage?: Readonly<LifetimeUsage>;
-  readonly compactionCount: number;
-}
-```
-
-This is structurally compatible with `AgentRecord` (the class satisfies it), so no mapping code is needed at the call site — `listAgents()` returns `AgentRecord[]` which satisfies `WidgetAgent[]`.
-
-### Renderer input for activity
-
-Activity state is read from `AgentActivityTracker`.
-The renderer needs a read-only view per agent:
-
-```typescript
-/** Read-only activity snapshot for widget rendering. */
-export interface WidgetActivity {
-  readonly activeTools: ReadonlyMap<string, string>;
-  readonly responseText: string;
-  readonly turnCount: number;
-  readonly maxTurns?: number;
-  readonly session?: SessionLike;
-}
-```
-
-`AgentActivityTracker` already satisfies this structurally (it exposes these as getters).
-
-### Agent config lookup
-
-The renderer needs `getDisplayName` and `getPromptModeLabel`, which take a `SubagentType` and an `AgentConfigLookup`.
-The renderer accepts `AgentConfigLookup` (the existing interface from `agent-types.ts`) — not the concrete `AgentTypeRegistry` class.
-
-### Renderer API
-
-```typescript
-/** Pure rendering of the widget body. Returns lines to display. */
-export function renderWidgetLines(params: {
-  agents: readonly WidgetAgent[];
-  activityMap: ReadonlyMap<string, WidgetActivity>;
-  registry: AgentConfigLookup;
-  spinnerFrame: number;
-  terminalWidth: number;
-  shouldShowFinished: (agentId: string, status: string) => boolean;
-}): string[];
-
-/** Pure rendering of a single finished agent line (no tree connector prefix). */
-export function renderFinishedLine(
-  agent: WidgetAgent,
-  activity: WidgetActivity | undefined,
-  registry: AgentConfigLookup,
-  theme: Theme,
-): string;
-
-/** Pure rendering of a single running agent (header + activity lines, no tree connector prefix). */
-export function renderRunningLines(
-  agent: WidgetAgent,
-  activity: WidgetActivity | undefined,
-  registry: AgentConfigLookup,
-  spinnerFrame: number,
-  theme: Theme,
-): [header: string, activity: string];
-```
-
-The top-level `renderWidgetLines` encapsulates the full categorization, overflow logic, and tree-connector fixup.
-The per-agent functions are exported for fine-grained testing.
-
-The `shouldShowFinished` callback is injected rather than re-implementing the aging logic inside the renderer, keeping the renderer pure and the aging state in the widget.
-
-### Call site in AgentWidget
-
-```typescript
-// Inside renderWidget(tui, theme):
-const w = tui.terminal.columns;
-return renderWidgetLines({
-  agents: this.manager.listAgents(),
-  activityMap: this.agentActivity,
-  registry: this.registry,
-  spinnerFrame: this.widgetFrame,
-  terminalWidth: w,
-  shouldShowFinished: (id, status) => this.shouldShowFinished(id, status),
-});
-```
-
-The widget's `renderWidget` method shrinks to ~5 lines.
-
-### Tell-Don't-Ask verification
-
-The renderer receives pre-collected data and returns formatted strings.
-It does not reach through collaborators — it reads flat fields from `WidgetAgent` and `WidgetActivity`.
-The widget tells the renderer "render this data"; the renderer returns lines.
-No Law of Demeter violations.
-
-## Module-Level Changes
-
-### New file: `src/ui/widget-renderer.ts`
-
-- `WidgetAgent` interface (structural subset of `AgentRecord`).
-- `WidgetActivity` interface (structural subset of `AgentActivityTracker`).
-- `renderWidgetLines()` — top-level rendering with categorization, overflow, tree connectors.
-- `renderFinishedLine()` — single finished-agent line.
-- `renderRunningLines()` — single running-agent header + activity pair.
-- Imports from `display.ts` (`SPINNER`, `ERROR_STATUSES`, `formatMs`, `formatTurns`, `formatSessionTokens`, `describeActivity`, `getDisplayName`, `getPromptModeLabel`, `Theme`), from `usage.ts` (`getLifetimeTotal`, `getSessionContextPercent`, `LifetimeUsage`, `SessionLike`), and from `@earendil-works/pi-tui` (`truncateToWidth`).
-
-### Modified: `src/ui/agent-widget.ts`
-
-- Remove `renderWidget()` method body — replace with call to `renderWidgetLines()`.
-- Remove `renderFinishedLine()` method entirely.
-- Remove direct imports of display helpers and usage helpers that are now only consumed by `widget-renderer.ts`.
-- Keep: constructor, `setUICtx`, `onTurnStart`, `ensureTimer`, `shouldShowFinished`, `markFinished`, `update`, `dispose`, `UICtx` type, `MAX_WIDGET_LINES`.
-- The inline type on `renderFinishedLine`'s parameter `a` is replaced by the `WidgetAgent` import.
-
-### New file: `test/widget-renderer.test.ts`
-
-- Unit tests for `renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`.
-- Uses plain data objects (no mocks for `AgentManager`, `setInterval`, or SDK).
-- Stub `Theme` matching the pattern in `test/renderer.test.ts`.
-
-### No changes to
-
-- `src/index.ts` — the widget is constructed the same way; renderer is internal to the widget module.
-- `src/ui/display.ts` — unchanged; consumed by the new renderer.
-- `src/usage.ts` — unchanged.
-
-## Test Impact Analysis
-
-1. The extraction enables direct unit testing of widget rendering that was previously impossible — testing `renderWidget` required constructing a full `AgentWidget` with mocked `AgentManager`, fake timers, and a stubbed UICtx.
-   The new tests cover: finished-agent line formatting (all status variants), running-agent header/activity rendering, overflow logic, tree-connector fixup, empty-state handling, and `shouldShowFinished` filtering.
-2. No existing tests become redundant — there are currently **no** unit tests for `AgentWidget` rendering.
-   The existing `display.test.ts` tests lower-level formatters and remains as-is.
-3. `renderer.test.ts` tests the notification renderer — unrelated, stays as-is.
-
-## TDD Order
-
-1. **Red → Green:** Test `renderFinishedLine` for a completed agent (success icon, stats, duration).
-   Commit: `test: add renderFinishedLine tests for completed status`
-
-2. **Red → Green:** Test `renderFinishedLine` for error/aborted/steered/stopped statuses (icon and status text variations).
-   Commit: `test: renderFinishedLine error and terminal status variants`
-
-3. **Red → Green:** Test `renderRunningLines` (spinner frame, stats, activity description, token display).
-   Commit: `test: add renderRunningLines tests`
-
-4. **Red → Green:** Test `renderWidgetLines` — basic case with one running agent (heading, tree connectors).
-   Commit: `test: renderWidgetLines single running agent`
-
-5. **Red → Green:** Test `renderWidgetLines` — mixed running + finished + queued, verifying categorization and ordering.
-   Commit: `test: renderWidgetLines mixed agent states`
-
-6. **Red → Green:** Test `renderWidgetLines` — overflow cap with many agents, verifying the priority (running > queued > finished) and overflow summary line.
-   Commit: `test: renderWidgetLines overflow behavior`
-
-7. **Red → Green:** Test `renderWidgetLines` — empty state returns `[]`; finished-only state uses dim heading.
-   Commit: `test: renderWidgetLines empty and finished-only states`
-
-8. **Green → Refactor:** Extract `renderFinishedLine`, `renderRunningLines`, and `renderWidgetLines` into `src/ui/widget-renderer.ts`.
-   All tests pass against the extracted module.
-   Commit: `refactor: extract widget rendering into widget-renderer`
-
-9. **Green → Refactor:** Wire `AgentWidget.renderWidget()` to delegate to `renderWidgetLines()`.
-   Remove the inlined rendering logic from `agent-widget.ts`.
-   Remove unused imports.
-   Commit: `refactor: AgentWidget delegates rendering to widget-renderer`
-
-10. **Verify:** Run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
-    Commit: none (verification only).
-
-## Risks and Mitigations
-
-| Risk                                                                                                           | Mitigation                                                                                                                                                                |
-| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Structural compatibility between `AgentRecord` and `WidgetAgent` could drift if `AgentRecord` renames a field. | TypeScript's structural checking catches this at the call site in `agent-widget.ts` — `listAgents()` returns `AgentRecord[]` which must satisfy `readonly WidgetAgent[]`. |
-| `truncateToWidth` is an external dependency (`@earendil-works/pi-tui`) in the renderer.                        | Step O (#147) will inject it; for now, the renderer imports it directly, matching the current widget behavior.                                                            |
-| Overflow logic is complex and hand-tested — extraction could introduce subtle line-count bugs.                 | TDD steps 4–7 exercise overflow edge cases before the extraction step. The extraction is a mechanical move with tests already passing.                                    |
-
-## Open Questions
-
-- None — the design follows the architecture doc's Step P specification and the dependency (#144) is already implemented.

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

@@ -1,91 +0,0 @@
----
-issue: 152
-issue_title: "Add promptSnippet to pi-subagents tools"
----
-
-# Add `promptSnippet` to pi-subagents tools
-
-## Problem Statement
-
-The `Agent`, `get_subagent_result`, and `steer_subagent` tools are the only tools across the monorepo that lack `promptSnippet`.
-Pi's `buildSystemPrompt` uses `promptSnippet` to build a concise tool summary in the system prompt.
-Without it, these tools rely entirely on their `description` field for model guidance.
-The `Agent` tool's description is especially long (embeds full usage guidelines), so a short snippet would give the model a better quick-reference view.
-
-## Goals
-
-- Add `promptSnippet` to each of the three tool registrations in pi-subagents.
-- Match the established `"<toolName>: <one-liner>"` format used by pi-github-tools and pi-colgrep.
-
-## Non-Goals
-
-- Changing `description`, `promptGuidelines`, or any other tool registration field.
-- Adding `promptSnippet` to tools in other packages (already done).
-
-## Background
-
-Sibling packages pi-github-tools and pi-colgrep already provide `promptSnippet` on every tool.
-The convention is a single string in the form `"tool_name: Short imperative description."`.
-For example: `"ci_list: List recent CI runs for a workflow."`.
-
-The three tool factories live in:
-
-| Factory               | File                           |
-| --------------------- | ------------------------------ |
-| `createAgentTool`     | `src/tools/agent-tool.ts`      |
-| `createGetResultTool` | `src/tools/get-result-tool.ts` |
-| `createSteerTool`     | `src/tools/steer-tool.ts`      |
-
-Each factory returns a plain object with `name`, `label`, `description`, `parameters`, and `execute`.
-Adding `promptSnippet` is a single property addition per factory.
-
-## Design Overview
-
-No structural change — this is a property addition to three existing object literals.
-
-Proposed snippets:
-
-- **Agent** — `"Agent: Launch a specialized agent for complex, multi-step tasks."`
-- **get_subagent_result** — `"get_subagent_result: Check status and retrieve results from a background agent."`
-- **steer_subagent** — `"steer_subagent: Send a mid-run message to redirect a running background agent."`
-
-These are the exact phrasings from the issue.
-Exact wording may be refined during implementation.
-
-## Module-Level Changes
-
-### `src/tools/agent-tool.ts`
-
-Add `promptSnippet` property to the object returned by `createAgentTool`, after `label`.
-
-### `src/tools/get-result-tool.ts`
-
-Add `promptSnippet` property to the object returned by `createGetResultTool`, after `label`.
-
-### `src/tools/steer-tool.ts`
-
-Add `promptSnippet` property to the object returned by `createSteerTool`, after `label`.
-
-## Test Impact Analysis
-
-Existing tool-definition tests (`test/tools/agent-tool.test.ts`, `get-result-tool.test.ts`, `steer-tool.test.ts`) assert `name`, `label`, and `description` but not `promptSnippet`.
-New assertions will verify the property exists with the expected value.
-No existing tests need modification — the new property is additive.
-
-## TDD Order
-
-1. **Red → Green:** Add `promptSnippet` assertions to the tool-definition tests for all three tools, then add the `promptSnippet` property to each factory.
-   Commit: `feat: add promptSnippet to Agent, get_subagent_result, and steer_subagent (#152)`
-
-This is a single-cycle change — one test step, one implementation step, one commit.
-
-## Risks and Mitigations
-
-| Risk                                                  | Mitigation                                                                                                                    |
-| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| Snippet wording doesn't match what Pi displays well   | The snippets mirror the first sentence of each tool's `description`; can be tweaked in a follow-up without breaking anything. |
-| SDK `defineTool` doesn't pass through `promptSnippet` | Sibling packages already use it successfully, confirming SDK support.                                                         |
-
-## Open Questions
-
-None.