@mariozechner/pi-coding-agent 0.23.3 → 0.23.5

package/dist/modes/print-mode.js

@@ -90,5 +90,15 @@ export async function runPrintMode(session, mode, messages, initialMessage, init
             }
         }
     }
+    // Ensure stdout is fully flushed before returning
+    // This prevents race conditions where the process exits before all output is written
+    await new Promise((resolve, reject) => {
+        process.stdout.write("", (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
 }
 //# sourceMappingURL=print-mode.js.map

package/dist/modes/print-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"print-mode.js","sourceRoot":"","sources":["../../src/modes/print-mode.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Print mode (single-shot): Send prompts, output result, exit.\n *\n * Used for:\n * - `pi -p \"prompt\"` - text output\n * - `pi --mode json \"prompt\"` - JSON event stream\n */\n\nimport type { Attachment } from \"@mariozechner/pi-agent-core\";\nimport type { AssistantMessage } from \"@mariozechner/pi-ai\";\nimport type { AgentSession } from \"../core/agent-session.js\";\n\n/**\n * Run in print (single-shot) mode.\n * Sends prompts to the agent and outputs the result.\n *\n * @param session The agent session\n * @param mode Output mode: \"text\" for final response only, \"json\" for all events\n * @param messages Array of prompts to send\n * @param initialMessage Optional first message (may contain @file content)\n * @param initialAttachments Optional attachments for the initial message\n */\nexport async function runPrintMode(\n\tsession: AgentSession,\n\tmode: \"text\" | \"json\",\n\tmessages: string[],\n\tinitialMessage?: string,\n\tinitialAttachments?: Attachment[],\n): Promise<void> {\n\t// Load entries once for session start events\n\tconst entries = session.sessionManager.loadEntries();\n\n\t// Hook runner already has no-op UI context by default (set in main.ts)\n\t// Set up hooks for print mode (no UI)\n\tconst hookRunner = session.hookRunner;\n\tif (hookRunner) {\n\t\t// Use actual session file if configured (via --session), otherwise null\n\t\thookRunner.setSessionFile(session.sessionFile);\n\t\thookRunner.onError((err) => {\n\t\t\tconsole.error(`Hook error (${err.hookPath}): ${err.error}`);\n\t\t});\n\t\t// No-op send handler for print mode (single-shot, no async messages)\n\t\thookRunner.setSendHandler(() => {\n\t\t\tconsole.error(\"Warning: pi.send() is not supported in print mode\");\n\t\t});\n\t\t// Emit session event\n\t\tawait hookRunner.emit({\n\t\t\ttype: \"session\",\n\t\t\tentries,\n\t\t\tsessionFile: session.sessionFile,\n\t\t\tpreviousSessionFile: null,\n\t\t\treason: \"start\",\n\t\t});\n\t}\n\n\t// Emit session start event to custom tools (no UI in print mode)\n\tfor (const { tool } of session.customTools) {\n\t\tif (tool.onSession) {\n\t\t\ttry {\n\t\t\t\tawait tool.onSession({\n\t\t\t\t\tentries,\n\t\t\t\t\tsessionFile: session.sessionFile,\n\t\t\t\t\tpreviousSessionFile: null,\n\t\t\t\t\treason: \"start\",\n\t\t\t\t});\n\t\t\t} catch (_err) {\n\t\t\t\t// Silently ignore tool errors\n\t\t\t}\n\t\t}\n\t}\n\n\t// Always subscribe to enable session persistence via _handleAgentEvent\n\tsession.subscribe((event) => {\n\t\t// In JSON mode, output all events\n\t\tif (mode === \"json\") {\n\t\t\tconsole.log(JSON.stringify(event));\n\t\t}\n\t});\n\n\t// Send initial message with attachments\n\tif (initialMessage) {\n\t\tawait session.prompt(initialMessage, { attachments: initialAttachments });\n\t}\n\n\t// Send remaining messages\n\tfor (const message of messages) {\n\t\tawait session.prompt(message);\n\t}\n\n\t// In text mode, output final response\n\tif (mode === \"text\") {\n\t\tconst state = session.state;\n\t\tconst lastMessage = state.messages[state.messages.length - 1];\n\n\t\tif (lastMessage?.role === \"assistant\") {\n\t\t\tconst assistantMsg = lastMessage as AssistantMessage;\n\n\t\t\t// Check for error/aborted\n\t\t\tif (assistantMsg.stopReason === \"error\" || assistantMsg.stopReason === \"aborted\") {\n\t\t\t\tconsole.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);\n\t\t\t\tprocess.exit(1);\n\t\t\t}\n\n\t\t\t// Output text content\n\t\t\tfor (const content of assistantMsg.content) {\n\t\t\t\tif (content.type === \"text\") {\n\t\t\t\t\tconsole.log(content.text);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n}\n"]}
+{"version":3,"file":"print-mode.js","sourceRoot":"","sources":["../../src/modes/print-mode.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Print mode (single-shot): Send prompts, output result, exit.\n *\n * Used for:\n * - `pi -p \"prompt\"` - text output\n * - `pi --mode json \"prompt\"` - JSON event stream\n */\n\nimport type { Attachment } from \"@mariozechner/pi-agent-core\";\nimport type { AssistantMessage } from \"@mariozechner/pi-ai\";\nimport type { AgentSession } from \"../core/agent-session.js\";\n\n/**\n * Run in print (single-shot) mode.\n * Sends prompts to the agent and outputs the result.\n *\n * @param session The agent session\n * @param mode Output mode: \"text\" for final response only, \"json\" for all events\n * @param messages Array of prompts to send\n * @param initialMessage Optional first message (may contain @file content)\n * @param initialAttachments Optional attachments for the initial message\n */\nexport async function runPrintMode(\n\tsession: AgentSession,\n\tmode: \"text\" | \"json\",\n\tmessages: string[],\n\tinitialMessage?: string,\n\tinitialAttachments?: Attachment[],\n): Promise<void> {\n\t// Load entries once for session start events\n\tconst entries = session.sessionManager.loadEntries();\n\n\t// Hook runner already has no-op UI context by default (set in main.ts)\n\t// Set up hooks for print mode (no UI)\n\tconst hookRunner = session.hookRunner;\n\tif (hookRunner) {\n\t\t// Use actual session file if configured (via --session), otherwise null\n\t\thookRunner.setSessionFile(session.sessionFile);\n\t\thookRunner.onError((err) => {\n\t\t\tconsole.error(`Hook error (${err.hookPath}): ${err.error}`);\n\t\t});\n\t\t// No-op send handler for print mode (single-shot, no async messages)\n\t\thookRunner.setSendHandler(() => {\n\t\t\tconsole.error(\"Warning: pi.send() is not supported in print mode\");\n\t\t});\n\t\t// Emit session event\n\t\tawait hookRunner.emit({\n\t\t\ttype: \"session\",\n\t\t\tentries,\n\t\t\tsessionFile: session.sessionFile,\n\t\t\tpreviousSessionFile: null,\n\t\t\treason: \"start\",\n\t\t});\n\t}\n\n\t// Emit session start event to custom tools (no UI in print mode)\n\tfor (const { tool } of session.customTools) {\n\t\tif (tool.onSession) {\n\t\t\ttry {\n\t\t\t\tawait tool.onSession({\n\t\t\t\t\tentries,\n\t\t\t\t\tsessionFile: session.sessionFile,\n\t\t\t\t\tpreviousSessionFile: null,\n\t\t\t\t\treason: \"start\",\n\t\t\t\t});\n\t\t\t} catch (_err) {\n\t\t\t\t// Silently ignore tool errors\n\t\t\t}\n\t\t}\n\t}\n\n\t// Always subscribe to enable session persistence via _handleAgentEvent\n\tsession.subscribe((event) => {\n\t\t// In JSON mode, output all events\n\t\tif (mode === \"json\") {\n\t\t\tconsole.log(JSON.stringify(event));\n\t\t}\n\t});\n\n\t// Send initial message with attachments\n\tif (initialMessage) {\n\t\tawait session.prompt(initialMessage, { attachments: initialAttachments });\n\t}\n\n\t// Send remaining messages\n\tfor (const message of messages) {\n\t\tawait session.prompt(message);\n\t}\n\n\t// In text mode, output final response\n\tif (mode === \"text\") {\n\t\tconst state = session.state;\n\t\tconst lastMessage = state.messages[state.messages.length - 1];\n\n\t\tif (lastMessage?.role === \"assistant\") {\n\t\t\tconst assistantMsg = lastMessage as AssistantMessage;\n\n\t\t\t// Check for error/aborted\n\t\t\tif (assistantMsg.stopReason === \"error\" || assistantMsg.stopReason === \"aborted\") {\n\t\t\t\tconsole.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);\n\t\t\t\tprocess.exit(1);\n\t\t\t}\n\n\t\t\t// Output text content\n\t\t\tfor (const content of assistantMsg.content) {\n\t\t\t\tif (content.type === \"text\") {\n\t\t\t\t\tconsole.log(content.text);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t// Ensure stdout is fully flushed before returning\n\t// This prevents race conditions where the process exits before all output is written\n\tawait new Promise<void>((resolve, reject) => {\n\t\tprocess.stdout.write(\"\", (err) => {\n\t\t\tif (err) reject(err);\n\t\t\telse resolve();\n\t\t});\n\t});\n}\n"]}

package/docs/custom-tools.md

@@ -22,7 +22,7 @@ See [examples/custom-tools/](../examples/custom-tools/) for working examples.
 
 ## Quick Start
 
-Create a file `~/.pi/agent/tools/hello.ts`:
+Create a file `~/.pi/agent/tools/hello/index.ts`:
 
 ```typescript
 import { Type } from "@sinclair/typebox";
@@ -51,13 +51,26 @@ The tool is automatically discovered and available in your next pi session.
 
 ## Tool Locations
 
+Tools must be in a subdirectory with an `index.ts` entry point:
+
 | Location | Scope | Auto-discovered |
 |----------|-------|-----------------|
-| `~/.pi/agent/tools/*.ts` | Global (all projects) | Yes |
-| `.pi/tools/*.ts` | Project-local | Yes |
+| `~/.pi/agent/tools/*/index.ts` | Global (all projects) | Yes |
+| `.pi/tools/*/index.ts` | Project-local | Yes |
 | `settings.json` `customTools` array | Configured paths | Yes |
 | `--tool <path>` CLI flag | One-off/debugging | No |
 
+**Example structure:**
+```
+~/.pi/agent/tools/
+├── hello/
+│   └── index.ts        # Entry point (auto-discovered)
+└── complex-tool/
+    ├── index.ts        # Entry point (auto-discovered)
+    ├── helpers.ts      # Helper module (not loaded directly)
+    └── types.ts        # Type definitions (not loaded directly)
+```
+
 **Priority:** Later sources win on name conflicts. CLI `--tool` takes highest priority.
 
 **Reserved names:** Custom tools cannot use built-in tool names (`read`, `write`, `edit`, `bash`, `grep`, `find`, `ls`).
@@ -125,7 +138,7 @@ The factory receives a `ToolAPI` object (named `pi` by convention):
 ```typescript
 interface ToolAPI {
   cwd: string;  // Current working directory
-  exec(command: string, args: string[]): Promise<ExecResult>;
+  exec(command: string, args: string[], options?: ExecOptions): Promise<ExecResult>;
   ui: {
     select(title: string, options: string[]): Promise<string | null>;
     confirm(title: string, message: string): Promise<boolean>;
@@ -134,10 +147,36 @@ interface ToolAPI {
   };
   hasUI: boolean;  // false in --print or --mode rpc
 }
+
+interface ExecOptions {
+  signal?: AbortSignal;  // Cancel the process
+  timeout?: number;      // Timeout in milliseconds
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+  killed?: boolean;  // True if process was killed by signal/timeout
+}
 ```
 
 Always check `pi.hasUI` before using UI methods.
 
+### Cancellation Example
+
+Pass the `signal` from `execute` to `pi.exec` to support cancellation:
+
+```typescript
+async execute(toolCallId, params, signal) {
+  const result = await pi.exec("long-running-command", ["arg"], { signal });
+  if (result.killed) {
+    return { content: [{ type: "text", text: "Cancelled" }] };
+  }
+  return { content: [{ type: "text", text: result.stdout }] };
+}
+```
+
 ## Session Lifecycle
 
 Tools can implement `onSession` to react to session changes:

package/docs/hooks.md

@@ -222,13 +222,104 @@ Fired after tool executes. **Can modify result.**
 
 ```typescript
 pi.on("tool_result", async (event, ctx) => {
-  // event.toolName, event.toolCallId, event.input
-  // event.result: string
+  // event.toolName: string
+  // event.toolCallId: string
+  // event.input: Record<string, unknown>
+  // event.content: (TextContent | ImageContent)[]
+  // event.details: tool-specific (see below)
   // event.isError: boolean
-  return { result: "modified" }; // or undefined to keep original
+  
+  // Return modified content/details, or undefined to keep original
+  return { content: [...], details: {...} };
 });
 ```
 
+The event type is a discriminated union based on `toolName`. Use the provided type guards to narrow `details` to the correct type:
+
+```typescript
+import { isBashToolResult, type HookAPI } from "@mariozechner/pi-coding-agent/hooks";
+
+export default function (pi: HookAPI) {
+  pi.on("tool_result", async (event, ctx) => {
+    if (isBashToolResult(event)) {
+      // event.details is BashToolDetails | undefined
+      if (event.details?.truncation?.truncated) {
+        // Access full output from temp file
+        const fullPath = event.details.fullOutputPath;
+      }
+    }
+  });
+}
+```
+
+Available type guards: `isBashToolResult`, `isReadToolResult`, `isEditToolResult`, `isWriteToolResult`, `isGrepToolResult`, `isFindToolResult`, `isLsToolResult`.
+
+#### Tool Details Types
+
+Each built-in tool has a typed `details` field. Types are exported from `@mariozechner/pi-coding-agent`:
+
+| Tool | Details Type | Source |
+|------|-------------|--------|
+| `bash` | `BashToolDetails` | `src/core/tools/bash.ts` |
+| `read` | `ReadToolDetails` | `src/core/tools/read.ts` |
+| `edit` | `undefined` | - |
+| `write` | `undefined` | - |
+| `grep` | `GrepToolDetails` | `src/core/tools/grep.ts` |
+| `find` | `FindToolDetails` | `src/core/tools/find.ts` |
+| `ls` | `LsToolDetails` | `src/core/tools/ls.ts` |
+
+Common fields in details:
+- `truncation?: TruncationResult` - present when output was truncated
+- `fullOutputPath?: string` - path to temp file with full output (bash only)
+
+`TruncationResult` contains:
+- `truncated: boolean` - whether truncation occurred
+- `truncatedBy: "lines" | "bytes" | null` - which limit was hit
+- `totalLines`, `totalBytes` - original size
+- `outputLines`, `outputBytes` - truncated size
+
+Custom tools use `CustomToolResultEvent` with `details: unknown`. Create your own type guard to get full type safety:
+
+```typescript
+import { 
+  isBashToolResult,
+  type CustomToolResultEvent,
+  type HookAPI,
+  type ToolResultEvent,
+} from "@mariozechner/pi-coding-agent/hooks";
+
+interface MyCustomToolDetails {
+  someField: string;
+}
+
+// Type guard that narrows both toolName and details
+function isMyCustomToolResult(e: ToolResultEvent): e is CustomToolResultEvent & { 
+  toolName: "my-custom-tool"; 
+  details: MyCustomToolDetails;
+} {
+  return e.toolName === "my-custom-tool";
+}
+
+export default function (pi: HookAPI) {
+  pi.on("tool_result", async (event, ctx) => {
+    // Built-in tool: use provided type guard
+    if (isBashToolResult(event)) {
+      if (event.details?.fullOutputPath) {
+        console.log(`Full output at: ${event.details.fullOutputPath}`);
+      }
+    }
+
+    // Custom tool: use your own type guard
+    if (isMyCustomToolResult(event)) {
+      // event.details is now MyCustomToolDetails
+      console.log(event.details.someField);
+    }
+  });
+}
+```
+
+**Note:** If you modify `content`, you should also update `details` accordingly. The TUI uses `details` (e.g., truncation info) for rendering, so inconsistent values will cause display issues.
+
 ## Context API
 
 Every event handler receives a context object with these methods:
@@ -272,15 +363,23 @@ ctx.ui.notify("Operation complete", "info");
 ctx.ui.notify("Something went wrong", "error");
 ```
 
-### ctx.exec(command, args)
+### ctx.exec(command, args, options?)
 
-Execute a command and get the result.
+Execute a command and get the result. Supports cancellation via `AbortSignal` and timeout.
 
 ```typescript
 const result = await ctx.exec("git", ["status"]);
 // result.stdout: string
 // result.stderr: string
 // result.code: number
+// result.killed?: boolean  // True if killed by signal/timeout
+
+// With timeout (5 seconds)
+const result = await ctx.exec("slow-command", [], { timeout: 5000 });
+
+// With abort signal
+const controller = new AbortController();
+const result = await ctx.exec("long-command", [], { signal: controller.signal });
 ```
 
 ### ctx.cwd

package/docs/skills.md

@@ -2,6 +2,8 @@
 
 Skills are self-contained capability packages that the agent loads on-demand. A skill provides specialized workflows, setup instructions, helper scripts, and reference documentation for specific tasks.
 
+Pi implements the [Agent Skills standard](https://agentskills.io/specification).
+
 **Example use cases:**
 - Web search and content extraction (Brave Search API)
 - Browser automation via Chrome DevTools Protocol
@@ -65,14 +67,13 @@ description: What this skill does and when to use it. Be specific.
 
 Run once before first use:
 \`\`\`bash
-cd {baseDir}
-npm install
+cd /path/to/skill && npm install
 \`\`\`
 
 ## Usage
 
 \`\`\`bash
-{baseDir}/scripts/process.sh <input>
+./scripts/process.sh <input>
 \`\`\`
 
 ## Workflow
@@ -84,20 +85,54 @@ npm install
 
 ### Frontmatter Fields
 
-| Field | Required | Description |
+Per the [Agent Skills specification](https://agentskills.io/specification#frontmatter-required):
+
+| Field | Required | Constraints |
 |-------|----------|-------------|
-| `description` | Yes | What the skill does and when to use it |
-| `name` | No | Override skill name (defaults to directory name) |
+| `name` | Yes | Max 64 chars. Lowercase a-z, 0-9, hyphens only. Must match parent directory name. |
+| `description` | Yes | Max 1024 chars. What the skill does and when to use it. |
+| `license` | No | License name or reference to bundled license file. |
+| `compatibility` | No | Max 500 chars. Environment requirements (system packages, network access, etc.). |
+| `metadata` | No | Arbitrary key-value mapping for additional metadata. |
+| `allowed-tools` | No | Space-delimited list of pre-approved tools (experimental). |
+
+#### Name Validation
+
+The `name` field must:
+- Be 1-64 characters
+- Contain only lowercase letters (a-z), numbers (0-9), and hyphens
+- Not start or end with a hyphen
+- Not contain consecutive hyphens (--)
+- Match the parent directory name exactly
+
+Valid: `pdf-processing`, `data-analysis`, `code-review`
+Invalid: `PDF-Processing`, `-pdf`, `pdf--processing`
 
-The `description` is critical. It's shown in the system prompt and determines when the agent loads the skill. Be specific about both what it does and when to use it.
+#### Description Best Practices
+
+The `description` is critical. It determines when the agent loads the skill. Be specific about both what it does and when to use it.
+
+Good:
+```yaml
+description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
+```
+
+Poor:
+```yaml
+description: Helps with PDFs.
+```
 
-### The `{baseDir}` Placeholder
+### File References
 
-Use `{baseDir}` to reference files in the skill's directory. The agent sees each skill's base directory and substitutes it when following instructions:
+Use relative paths from the skill directory:
 
 ```markdown
-Helper scripts: {baseDir}/scripts/
-Config template: {baseDir}/assets/config.json
+See [the reference guide](references/REFERENCE.md) for details.
+
+Run the extraction script:
+\`\`\`bash
+./scripts/extract.py input.pdf
+\`\`\`
 ```
 
 ## Skill Locations
@@ -110,21 +145,28 @@ Skills are discovered from these locations (later wins on name collision):
 4. `~/.pi/agent/skills/**/SKILL.md` (Pi user, recursive)
 5. `<cwd>/.pi/skills/**/SKILL.md` (Pi project, recursive)
 
-### Subdirectory Naming
-
-Pi skills in subdirectories use colon-separated names:
-- `~/.pi/agent/skills/db/migrate/SKILL.md` → `db:migrate`
-- `<cwd>/.pi/skills/aws/s3/upload/SKILL.md` → `aws:s3:upload`
-
 ## How Skills Work
 
 1. At startup, pi scans skill locations and extracts names + descriptions
-2. The system prompt includes a list of available skills with their descriptions
+2. The system prompt includes available skills in XML format
 3. When a task matches, the agent uses `read` to load the full SKILL.md
-4. The agent follows the instructions, using `{baseDir}` to reference scripts/assets
+4. The agent follows the instructions, using relative paths to reference scripts/assets
 
 This is progressive disclosure: only descriptions are always in context, full instructions load on-demand.
 
+## Validation Warnings
+
+Pi validates skills against the Agent Skills standard and warns (but still loads) non-compliant skills:
+
+- Name doesn't match parent directory
+- Name exceeds 64 characters
+- Name contains invalid characters
+- Name starts/ends with hyphen or has consecutive hyphens
+- Description missing or exceeds 1024 characters
+- Unknown frontmatter fields
+
+Name collisions (same name from different locations) warn and keep the first skill found.
+
 ## Example: Web Search Skill
 
 ```
@@ -146,21 +188,20 @@ description: Web search and content extraction via Brave Search API. Use for sea
 ## Setup
 
 \`\`\`bash
-cd {baseDir}
-npm install
+cd /path/to/brave-search && npm install
 \`\`\`
 
 ## Search
 
 \`\`\`bash
-{baseDir}/search.js "query"              # Basic search
-{baseDir}/search.js "query" --content    # Include page content
+./search.js "query"              # Basic search
+./search.js "query" --content    # Include page content
 \`\`\`
 
 ## Extract Page Content
 
 \`\`\`bash
-{baseDir}/content.js https://example.com
+./content.js https://example.com
 \`\`\`
 ```
 

package/examples/custom-tools/README.md

@@ -4,27 +4,38 @@ Example custom tools for pi-coding-agent.
 
 ## Examples
 
-### hello.ts
+Each example uses the `subdirectory/index.ts` structure required for tool discovery.
+
+### hello/
 Minimal example showing the basic structure of a custom tool.
 
-### question.ts
+### question/
 Demonstrates `pi.ui.select()` for asking the user questions with options.
 
-### todo.ts
+### todo/
 Full-featured example demonstrating:
 - `onSession` for state reconstruction from session history
 - Custom `renderCall` and `renderResult`
 - Proper branching support via details storage
 - State management without external files
 
+### subagent/
+Delegate tasks to specialized subagents with isolated context windows. Includes:
+- `index.ts` - The custom tool (single, parallel, and chain modes)
+- `agents.ts` - Agent discovery helper
+- `agents/` - Sample agent definitions (scout, planner, reviewer, worker)
+- `commands/` - Workflow presets (/implement, /scout-and-plan, /implement-and-review)
+
+See [subagent/README.md](subagent/README.md) for full documentation.
+
 ## Usage
 
 ```bash
-# Test directly
-pi --tool examples/custom-tools/todo.ts
+# Test directly (can point to any .ts file)
+pi --tool examples/custom-tools/todo/index.ts
 
-# Or copy to tools directory for persistent use
-cp todo.ts ~/.pi/agent/tools/
+# Or copy entire folder to tools directory for persistent use
+cp -r todo ~/.pi/agent/tools/
 ```
 
 Then in pi:

package/examples/custom-tools/subagent/README.md

@@ -0,0 +1,172 @@
+# Subagent Example
+
+Delegate tasks to specialized subagents with isolated context windows.
+
+## Features
+
+- **Isolated context**: Each subagent runs in a separate `pi` process
+- **Streaming output**: See tool calls and progress as they happen
+- **Parallel streaming**: All parallel tasks stream updates simultaneously
+- **Markdown rendering**: Final output rendered with proper formatting (expanded view)
+- **Usage tracking**: Shows turns, tokens, cost, and context usage per agent
+- **Abort support**: Ctrl+C propagates to kill subagent processes
+
+## Structure
+
+```
+subagent/
+├── README.md            # This file
+├── subagent.ts          # The custom tool (entry point)
+├── agents.ts            # Agent discovery logic
+├── agents/              # Sample agent definitions
+│   ├── scout.md         # Fast recon, returns compressed context
+│   ├── planner.md       # Creates implementation plans
+│   ├── reviewer.md      # Code review
+│   └── worker.md        # General-purpose (full capabilities)
+└── commands/            # Workflow presets
+    ├── implement.md     # scout -> planner -> worker
+    ├── scout-and-plan.md    # scout -> planner (no implementation)
+    └── implement-and-review.md  # worker -> reviewer -> worker
+```
+
+## Installation
+
+From the repository root, symlink the files:
+
+```bash
+# Symlink the tool (must be in a subdirectory with index.ts)
+mkdir -p ~/.pi/agent/tools/subagent
+ln -sf "$(pwd)/packages/coding-agent/examples/custom-tools/subagent/subagent.ts" ~/.pi/agent/tools/subagent/index.ts
+ln -sf "$(pwd)/packages/coding-agent/examples/custom-tools/subagent/agents.ts" ~/.pi/agent/tools/subagent/agents.ts
+
+# Symlink agents
+mkdir -p ~/.pi/agent/agents
+for f in packages/coding-agent/examples/custom-tools/subagent/agents/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/agents/$(basename "$f")
+done
+
+# Symlink workflow commands
+mkdir -p ~/.pi/agent/commands
+for f in packages/coding-agent/examples/custom-tools/subagent/commands/*.md; do
+  ln -sf "$(pwd)/$f" ~/.pi/agent/commands/$(basename "$f")
+done
+```
+
+## Security Model
+
+This tool executes a separate `pi` subprocess with a delegated system prompt and tool/model configuration.
+
+**Project-local agents** (`.pi/agents/*.md`) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.
+
+**Default behavior:** Only loads **user-level agents** from `~/.pi/agent/agents`.
+
+To enable project-local agents, pass `agentScope: "both"` (or `"project"`). Only do this for repositories you trust.
+
+When running interactively, the tool prompts for confirmation before running project-local agents. Set `confirmProjectAgents: false` to disable.
+
+## Usage
+
+### Single agent
+```
+Use scout to find all authentication code
+```
+
+### Parallel execution
+```
+Run 2 scouts in parallel: one to find models, one to find providers
+```
+
+### Chained workflow
+```
+Use a chain: first have scout find the read tool, then have planner suggest improvements
+```
+
+### Workflow commands
+```
+/implement add Redis caching to the session store
+/scout-and-plan refactor auth to support OAuth
+/implement-and-review add input validation to API endpoints
+```
+
+## Tool Modes
+
+| Mode | Parameter | Description |
+|------|-----------|-------------|
+| Single | `{ agent, task }` | One agent, one task |
+| Parallel | `{ tasks: [...] }` | Multiple agents run concurrently (max 8, 4 concurrent) |
+| Chain | `{ chain: [...] }` | Sequential with `{previous}` placeholder |
+
+## Output Display
+
+**Collapsed view** (default):
+- Status icon (✓/✗/⏳) and agent name
+- Last 5-10 items (tool calls and text)
+- Usage stats: `3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model`
+
+**Expanded view** (Ctrl+O):
+- Full task text
+- All tool calls with formatted arguments
+- Final output rendered as Markdown
+- Per-task usage (for chain/parallel)
+
+**Parallel mode streaming**:
+- Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
+- Updates as each task makes progress
+- Shows "2/3 done, 1 running" status
+
+**Tool call formatting** (mimics built-in tools):
+- `$ command` for bash
+- `read ~/path:1-10` for read
+- `grep /pattern/ in ~/path` for grep
+- etc.
+
+## Agent Definitions
+
+Agents are markdown files with YAML frontmatter:
+
+```markdown
+---
+name: my-agent
+description: What this agent does
+tools: read, grep, find, ls
+model: claude-haiku-4-5
+---
+
+System prompt for the agent goes here.
+```
+
+**Locations:**
+- `~/.pi/agent/agents/*.md` - User-level (always loaded)
+- `.pi/agents/*.md` - Project-level (only with `agentScope: "project"` or `"both"`)
+
+Project agents override user agents with the same name when `agentScope: "both"`.
+
+## Sample Agents
+
+| Agent | Purpose | Model | Tools |
+|-------|---------|-------|-------|
+| `scout` | Fast codebase recon | Haiku | read, grep, find, ls, bash |
+| `planner` | Implementation plans | Sonnet | read, grep, find, ls |
+| `reviewer` | Code review | Sonnet | read, grep, find, ls, bash |
+| `worker` | General-purpose | Sonnet | (all default) |
+
+## Workflow Commands
+
+| Command | Flow |
+|---------|------|
+| `/implement <query>` | scout → planner → worker |
+| `/scout-and-plan <query>` | scout → planner |
+| `/implement-and-review <query>` | worker → reviewer → worker |
+
+## Error Handling
+
+- **Exit code != 0**: Tool returns error with stderr/output
+- **stopReason "error"**: LLM error propagated with error message
+- **stopReason "aborted"**: User abort (Ctrl+C) kills subprocess, throws error
+- **Chain mode**: Stops at first failing step, reports which step failed
+
+## Limitations
+
+- Output truncated to last 10 items in collapsed view (expand to see all)
+- Agents discovered fresh on each invocation (allows editing mid-session)
+- Parallel mode limited to 8 tasks, 4 concurrent

package/examples/custom-tools/subagent/agents/planner.md

@@ -0,0 +1,37 @@
+---
+name: planner
+description: Creates implementation plans from context and requirements
+tools: read, grep, find, ls
+model: claude-sonnet-4-5
+---
+
+You are a planning specialist. You receive context (from a scout) and requirements, then produce a clear implementation plan.
+
+You must NOT make any changes. Only read, analyze, and plan.
+
+Input format you'll receive:
+- Context/findings from a scout agent
+- Original query or requirements
+
+Output format:
+
+## Goal
+One sentence summary of what needs to be done.
+
+## Plan
+Numbered steps, each small and actionable:
+1. Step one - specific file/function to modify
+2. Step two - what to add/change
+3. ...
+
+## Files to Modify
+- `path/to/file.ts` - what changes
+- `path/to/other.ts` - what changes
+
+## New Files (if any)
+- `path/to/new.ts` - purpose
+
+## Risks
+Anything to watch out for.
+
+Keep the plan concrete. The worker agent will execute it verbatim.