@johnnywu/pi-subagents 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [1.1.0](https://github.com/jwu/pi-subagents/compare/v1.0.1...v1.1.0) (2026-05-31)
+
+
+### Features
+
+* **subagent:** list available agents in system prompt Guidelines ([317ed58](https://github.com/jwu/pi-subagents/commit/317ed5845379d3edd535bc03dab8460b29a82164))
+
+## [1.0.1](https://github.com/jwu/pi-subagents/compare/v1.0.0...v1.0.1) (2026-05-31)
+
+
+### Bug Fixes
+
+* add spacing before subagent result status ([21932f5](https://github.com/jwu/pi-subagents/commit/21932f5cc7a59f504c60f36a6375f322c46acf8c))
+
 # 1.0.0 (2026-05-30)
 
 

package/README.md

@@ -2,12 +2,120 @@
 
 Sub-agents extension for [pi](https://github.com/badlogic/pi-mono) coding agent.
 
+Delegates tasks to isolated pi child processes — each running with its own model, system prompt, and tool set. Sub-agents inherit zero conversation context; all necessary context must be provided in the task description.
+
 ## Install
 
 ```bash
 pi install npm:@johnnywu/pi-subagents
 ```
 
+## Quick start
+
+### 1. Define an agent
+
+Create a `.pi/agents/code-reviewer.md` file in your project:
+
+```markdown
+---
+name: code-reviewer
+description: Reviews code changes for correctness and style
+tools: read, grep, find, ls, bash
+model: anthropic/claude-sonnet-4-6
+thinking: low
+---
+
+You are a code reviewer. When given a diff or file list, read the relevant
+files and provide a concise review covering:
+
+- Logic errors and edge cases
+- Style and consistency issues
+- Performance concerns
+- Test coverage gaps
+```
+
+### 2. Use it
+
+The `subagent` tool is automatically registered. In a pi session:
+
+```
+Review the changes in src/auth.ts using the code-reviewer agent
+```
+
+Or instruct pi to delegate:
+
+```
+Run the code-reviewer agent on the last three commits
+```
+
+## Agent configuration
+
+Agents are Markdown files with YAML frontmatter.
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `name` | **yes** | — | Unique agent identifier |
+| `description` | no | — | Human-readable summary |
+| `tools` | no | _none_ | Comma-separated tool whitelist (`read, write, bash, grep`, etc.) |
+| `model` | no | parent's model | Provider/model-id (`anthropic/claude-sonnet-4-6`) |
+| `thinking` | no | `off` | Reasoning level: `off`, `low`, `medium`, `high` |
+| `systemPrompt` | no | `replace` | How the body is applied: `replace` (default system prompt) or `append` |
+| `allowedAgents` | no | _all_ | Comma-separated list of sub-agents this agent may spawn |
+| `maxDepth` | no | `10` | Maximum recursion depth (`0` = no sub-agents, `1` = one level, etc.) |
+
+The Markdown body after the frontmatter is the agent's system prompt.
+
+### Example with all fields
+
+```markdown
+---
+name: orchestrator
+description: High-level planner that delegates to specialists
+tools: subagent, read, grep, find
+model: anthropic/claude-sonnet-4-6
+thinking: high
+systemPrompt: replace
+allowedAgents: code-reviewer, refactor, test-writer
+maxDepth: 2
+---
+
+You are an orchestrator. Break complex tasks into sub-tasks and delegate
+them to specialist agents. Combine their results and report a summary.
+```
+
+## Agent discovery
+
+Agents are discovered from two locations (project overrides global):
+
+| Scope | Path |
+|-------|------|
+| Global | `~/.pi/agent/agents/*.md` |
+| Project | `.pi/agents/*.md` |
+
+Only `.md` files are scanned. Files are parsed at extension load time; parse errors produce warnings but don't block other agents.
+
+## Recursion control
+
+Sub-agents can spawn their own sub-agents (if the `subagent` tool is in their whitelist). Two mechanisms prevent unbounded recursion:
+
+**`maxDepth`** — Hard limit counting from the originating agent. `maxDepth: 0` means the agent cannot spawn sub-agents. `maxDepth: 1` allows one level, etc. Defaults to `10` when the agent has `subagent` in tools.
+
+**`allowedAgents`** — Whitelist enforced by the parent before spawning. A child process never sees agent names outside its parent's whitelist.
+
+These are passed via environment variables (`PI_SUBAGENT_DEPTH`, `PI_SUBAGENT_MAX_DEPTH`, `PI_SUBAGENT_ALLOWED`).
+
+## Session storage
+
+Sub-agent sessions are saved as `.jsonl` files for post-hoc debugging:
+
+```
+~/.pi/agent/sessions/--{safe-project-path}--/subagents/
+  ├── 2026-05-31T03-47-16-502Z_019e7c24-a395-707a-a262-ec5b1664ffa7.jsonl
+  └── ...
+```
+
+Each file contains one JSON object per line — session headers, messages, tool calls, and usage data. Parent pi sessions live in the same project directory (no `subagents/` subdirectory).
+
 ## Development
 
 ```bash
@@ -23,7 +131,7 @@ bun run typecheck
 # Format
 bun run format
 
-# Release (local, requires GH_TOKEN and NPM_TOKEN)
+# Release (requires GH_TOKEN and NPM_TOKEN)
 bun run release
 ```
 

package/extensions/env-utils.ts

@@ -0,0 +1,26 @@
+export type RecursionEnv = Partial<
+  Record<'PI_SUBAGENT_ALLOWED' | 'PI_SUBAGENT_DEPTH' | 'PI_SUBAGENT_MAX_DEPTH', string>
+>;
+
+export function parseEnvNumber(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+export function allowedAgentNames(env: RecursionEnv): Set<string> | undefined {
+  const raw = env?.PI_SUBAGENT_ALLOWED;
+  if (!raw) return undefined;
+  return new Set(
+    raw
+      .split(',')
+      .map((name) => name.trim())
+      .filter(Boolean),
+  );
+}
+
+export function isPastMaxDepth(env: RecursionEnv): boolean {
+  const depth = parseEnvNumber(env?.PI_SUBAGENT_DEPTH);
+  const maxDepth = parseEnvNumber(env?.PI_SUBAGENT_MAX_DEPTH);
+  return depth !== undefined && maxDepth !== undefined && depth > maxDepth;
+}

package/extensions/subagent-render.ts

@@ -1,5 +1,5 @@
-import { homedir } from 'node:os';
 import type { AgentProgress } from './subagent-executor.ts';
+import { numberArg, preview, shortenPath, stringArg } from './tool-args.ts';
 
 export interface SubagentCallArgs {
   agent?: string;
@@ -41,10 +41,6 @@ export function contextUsageSeverity(usage: {
   return 'dim';
 }
 
-function preview(text: string, length: number): string {
-  return text.length > length ? `${text.slice(0, length)}...` : text;
-}
-
 function elapsedSeconds(ms: number): number {
   return Math.round(ms / 1000);
 }
@@ -85,26 +81,10 @@ function indent(text: string, spaces: number): string {
     .join('\n');
 }
 
-function shortenPath(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined;
-  const home = homedir();
-  return value.startsWith(`${home}/`) ? `~/${value.slice(home.length + 1)}` : value;
-}
-
 function quote(value: string | undefined): string {
   return value ? JSON.stringify(value) : '';
 }
 
-function stringArg(args: Record<string, unknown>, key: string): string | undefined {
-  const value = args[key];
-  return typeof value === 'string' ? value : undefined;
-}
-
-function numberArg(args: Record<string, unknown>, key: string): number | undefined {
-  const value = args[key];
-  return typeof value === 'number' ? value : undefined;
-}
-
 function pathArg(args: Record<string, unknown>, fallback?: string): string {
   return shortenPath(args.path ?? args.file_path) ?? fallback ?? '...';
 }
@@ -221,6 +201,7 @@ export function formatSubagentResultLines(
   const toolLines = formatToolLineItems(progress, options);
   const usage = formatUsage(progress);
   const lines: SubagentResultLine[] = [
+    { text: '', kind: 'blank', singleLine: false },
     { text: statusLine, kind: 'status', singleLine: false },
     ...toolLines,
   ];

package/extensions/subagent-tool.ts

@@ -1,4 +1,3 @@
-import { homedir } from 'node:os';
 import {
   getMarkdownTheme,
   keyHint,
@@ -17,6 +16,8 @@ import {
   formatUsage,
   type SubagentResultLine,
 } from './subagent-render.ts';
+import { numberArg, preview, shortenPath, stringArg } from './tool-args.ts';
+import { allowedAgentNames, isPastMaxDepth, type RecursionEnv } from './env-utils.ts';
 
 const SubagentParams = {
   type: 'object',
@@ -36,10 +37,6 @@ type SubagentParamsType = {
 };
 
 type RegisterablePi = Pick<ExtensionAPI, 'registerTool'>;
-type RecursionEnv = Partial<
-  Record<'PI_SUBAGENT_ALLOWED' | 'PI_SUBAGENT_DEPTH' | 'PI_SUBAGENT_MAX_DEPTH', string>
->;
-
 export interface RegisterSubagentToolOptions {
   agents: AgentConfig[];
   run?: typeof runSubagent;
@@ -70,54 +67,11 @@ function toProgressResult(progress: AgentProgress) {
   };
 }
 
-function parseEnvNumber(value: string | undefined): number | undefined {
-  if (value === undefined) return undefined;
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-function allowedAgentNames(env: RecursionEnv): Set<string> | undefined {
-  const raw = env?.PI_SUBAGENT_ALLOWED;
-  if (!raw) return undefined;
-  return new Set(
-    raw
-      .split(',')
-      .map((name) => name.trim())
-      .filter(Boolean),
-  );
-}
-
-function isPastMaxDepth(env: RecursionEnv): boolean {
-  const depth = parseEnvNumber(env?.PI_SUBAGENT_DEPTH);
-  const maxDepth = parseEnvNumber(env?.PI_SUBAGENT_MAX_DEPTH);
-  return depth !== undefined && maxDepth !== undefined && depth > maxDepth;
-}
-
 type CollapsedTheme = {
   fg: (name: ThemeColor, text: string) => string;
   bold: (text: string) => string;
 };
 
-function preview(text: string, length: number): string {
-  return text.length > length ? `${text.slice(0, length)}...` : text;
-}
-
-function shortenPath(value: unknown): string | undefined {
-  if (typeof value !== 'string') return undefined;
-  const home = homedir();
-  return value.startsWith(`${home}/`) ? `~/${value.slice(home.length + 1)}` : value;
-}
-
-function stringArg(args: Record<string, unknown>, key: string): string | undefined {
-  const value = args[key];
-  return typeof value === 'string' ? value : undefined;
-}
-
-function numberArg(args: Record<string, unknown>, key: string): number | undefined {
-  const value = args[key];
-  return typeof value === 'number' ? value : undefined;
-}
-
 function styledPathArg(
   args: Record<string, unknown>,
   theme: CollapsedTheme,
@@ -263,11 +217,19 @@ export function registerSubagentTool(
     : options.agents;
   const runner = options.run ?? runSubagent;
 
+  const agentNames = agents
+    .map((a) => a.name)
+    .sort()
+    .join(', ');
+  const promptGuidelines =
+    agentNames.length > 0 ? [`Available subagents: ${agentNames}`] : undefined;
+
   pi.registerTool({
     name: 'subagent',
     label: 'Subagent',
     description: 'Delegate a task to a named sub-agent running in an isolated pi process.',
     promptSnippet: 'Delegate isolated tasks with subagent({ agent, task, cwd? }).',
+    promptGuidelines,
     parameters: SubagentParams,
 
     async execute(

package/extensions/tool-args.ts

@@ -0,0 +1,21 @@
+import { homedir } from 'node:os';
+
+export function preview(text: string, length: number): string {
+  return text.length > length ? `${text.slice(0, length)}...` : text;
+}
+
+export function shortenPath(value: unknown): string | undefined {
+  if (typeof value !== 'string') return undefined;
+  const home = homedir();
+  return value.startsWith(`${home}/`) ? `~/${value.slice(home.length + 1)}` : value;
+}
+
+export function stringArg(args: Record<string, unknown>, key: string): string | undefined {
+  const value = args[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+export function numberArg(args: Record<string, unknown>, key: string): number | undefined {
+  const value = args[key];
+  return typeof value === 'number' ? value : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnnywu/pi-subagents",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Sub-agents extension for pi coding agent.",
   "homepage": "https://github.com/jwu/pi-subagents#readme",
   "repository": {