@gotgenes/pi-subagents 6.13.1 → 6.14.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ 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.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)
+
+
+### Features
+
+* add promptSnippet to Agent, get_subagent_result, and steer_subagent ([#152](https://github.com/gotgenes/pi-packages/issues/152)) ([3ccbe14](https://github.com/gotgenes/pi-packages/commit/3ccbe140b05ab038c3c50ff1fdbe314d721c7b60))
+
+
+### Documentation
+
+* plan add promptSnippet to subagent tools ([#152](https://github.com/gotgenes/pi-packages/issues/152)) ([f8fd56d](https://github.com/gotgenes/pi-packages/commit/f8fd56dff3d6a824f36c198d9a9d1b50a0bf740a))
+
 ## [6.13.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.13.0...pi-subagents-v6.13.1) (2026-05-23)
 
 

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

@@ -0,0 +1,91 @@
+---
+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.

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.13.1",
+  "version": "6.14.1",
   "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

@@ -430,6 +430,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 +438,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 +462,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/tools/agent-tool.ts

@@ -71,6 +71,7 @@ export function createAgentTool(deps: AgentToolDeps) {
   return {
     name: "Agent" as const,
     label: "Agent",
+    promptSnippet: "Agent: Launch a specialized agent for complex, multi-step tasks.",
     description: `Launch a new agent to handle complex, multi-step tasks autonomously.
 
 The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.

package/src/tools/get-result-tool.ts

@@ -19,6 +19,7 @@ export function createGetResultTool(deps: GetResultDeps) {
   return {
     name: "get_subagent_result" as const,
     label: "Get Agent Result",
+    promptSnippet: "get_subagent_result: Check status and retrieve results from a background agent.",
     description:
       "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
     parameters: Type.Object({

package/src/tools/steer-tool.ts

@@ -18,6 +18,7 @@ export function createSteerTool(deps: SteerToolDeps) {
   return {
     name: "steer_subagent" as const,
     label: "Steer Agent",
+    promptSnippet: "steer_subagent: Send a mid-run message to redirect a running background agent.",
     description:
       "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
       "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",

package/src/types.ts

@@ -4,7 +4,6 @@
 
 import type { ThinkingLevel } from "@earendil-works/pi-ai";
 
-export type { AgentRecordInit, AgentRecordStatus } from "./agent-record.js";
 
 export { AgentRecord } from "./agent-record.js";
 export type { ThinkingLevel };

package/src/ui/agent-widget.ts

@@ -64,6 +64,7 @@ export class AgentWidget {
   ) {}
 
   /** Set the UI context (grabbed from first tool execution). */
+  // fallow-ignore-next-line unused-class-member
   setUICtx(ctx: UICtx) {
     if (ctx !== this.uiCtx) {
       // UICtx changed — the widget registered on the old context is gone.
@@ -79,6 +80,7 @@ export class AgentWidget {
    * Called on each new turn (tool_execution_start).
    * Ages finished agents and clears those that have lingered long enough.
    */
+  // fallow-ignore-next-line unused-class-member
   onTurnStart() {
     // Age all finished agents
     for (const [id, age] of this.finishedTurnAge) {
@@ -89,6 +91,7 @@ export class AgentWidget {
   }
 
   /** Ensure the widget update timer is running. */
+  // fallow-ignore-next-line unused-class-member
   ensureTimer() {
     if (!this.widgetInterval) {
       this.widgetInterval = setInterval(() => this.update(), 80);
@@ -103,6 +106,7 @@ export class AgentWidget {
   }
 
   /** Record an agent as finished (call when agent completes). */
+  // fallow-ignore-next-line unused-class-member
   markFinished(agentId: string) {
     if (!this.finishedTurnAge.has(agentId)) {
       this.finishedTurnAge.set(agentId, 0);
@@ -354,6 +358,7 @@ export class AgentWidget {
     }
   }
 
+  // fallow-ignore-next-line unused-class-member
   dispose() {
     if (this.widgetInterval) {
       clearInterval(this.widgetInterval);

package/src/ui/conversation-viewer.ts

@@ -90,6 +90,7 @@ export class ConversationViewer implements Component {
     });
   }
 
+  // fallow-ignore-next-line unused-class-member
   handleInput(data: string): void {
     if (matchesKey(data, "escape") || matchesKey(data, "q")) {
       this.closed = true;
@@ -199,8 +200,10 @@ export class ConversationViewer implements Component {
     return lines;
   }
 
+  // fallow-ignore-next-line unused-class-member
   invalidate(): void { /* no cached state to clear */ }
 
+  // fallow-ignore-next-line unused-class-member
   dispose(): void {
     this.closed = true;
     if (this.unsubscribe) {