su-subagent — Minimal Delegation Extension for Pi

A minimal delegation extension for the pi coding agent. Adds a single delegate(taskPrompt) tool that spawns a fresh, isolated pi subprocess to complete a sub-task.

Installation

pi install /path/to/su-subagent

Usage

The parent agent gets a single capability:

delegate(taskPrompt: string) -> string

The sub-agent is a plain, non-configured pi agent with no inherited context. It runs autonomously with standard built-in tools (read, bash, write, edit, etc.). Its output is returned as text — no file handoff.

Example delegation:

delegate(taskPrompt="Find all TODO comments in the repository and categorize them")
delegate(taskPrompt="Investigate why tests in src/auth.test.ts are failing")
delegate(taskPrompt="Refactor utils.js: extract the CSV parser into its own module")

How It Works

Parent Agent
    │
    ├─ tool call: delegate(taskPrompt)
    ▼
Spawn `pi --mode json -p --no-session --no-skills --no-extensions "Task: ..."`
    │
    ▼
Parse JSON events from stdout, extract final assistant message
    │
    ▼
Return output text as tool result

Each sub-agent runs as an isolated OS process — a completely fresh pi instance. No context leakage. No session files. No in-process state sharing.

When to Delegate

Use delegate for	Don't use delegate for
Multi-step file exploration	Simple lookups (use grep/read directly)
Code refactoring in a single file	Design or architectural decisions
Running tests and diagnosing failures	Anything needing user interaction
Research across many files	Work dependent on conversation state
Parallel independent investigations	Planning or decision-making

Core Logic

Adapted from amosblomqvist/pi-subagents but simplified to its essence:

• One default sub-agent — no agent profiles, no frontmatter, no config
• Subprocess isolation — each delegation spawns a pi process
• JSON mode — --mode json -p for machine-readable output
• No frills — no skills, no extensions, no session persistence, no custom rendering

License

MIT