pi-echo-subagents

Delegate tasks to specialized subagents with isolated context, adapted from Pi's own official subagent example.

Design note

Each invocation spawns a separate pi child process (--mode json -p --no-session [--model x] [--tools a,b,c] --append-system-prompt <tmpfile> "Task: ..."), parsing newline-delimited JSON events from stdout to reconstruct messages, usage, and cost. This gives true OS-level context isolation for free — no SessionManager.fork()/worktree isolation needed, and no risk of the subagent's conversation bleeding into the parent's context or vice versa, since it's a genuinely separate process with --no-session.

This package trades the official example's rich TUI rendering (custom renderCall/renderResult with themed Container output) for the default tool-result display, to keep this module smaller. The mechanism itself — subprocess spawn, JSON-event parsing, .md-frontmatter agent discovery (agents.ts, vendored verbatim from the official example), single/parallel (max 8, concurrency 4)/chain execution modes — is preserved in full. Richer rendering can be layered on later without touching this logic.

Permission-gate composition — read this before relying on it

Verified directly against the installed @earendil-works/pi-coding-agent source (dist/main.js): extension auto-discovery for a spawned child process is entirely independent of --no-session — it's driven by resource-loader options, unrelated to session persistence. Project-local extensions (like pi-echo-permissions, if installed to .pi/extensions/) still require project trust, and trust is resolved per-cwd from a persistent trust store shared between parent and child process.

In the near-universal case — the user's own interactive session already trusted this project before ever invoking a subagent — the child reads that same cached trust and pi-echo-permissions' gate applies to the subagent's tool calls exactly as it does to the parent's. In the narrow edge case of a project that has never been interactively trusted, a headless child cannot answer a trust prompt, and project-local extensions (including pi-echo-permissions itself) silently do not load for that child. This is documented in SECURITY.md, not silently assumed away — if you need the gate to unconditionally apply to subagents even on a project's very first run, trust the project once interactively before using /subagent, or pass explicit -e flags in a custom wrapper around this tool (not implemented here).

Usage

Install locally for development: pi -e ./packages/pi-echo-subagents. Agent definitions are .md files with YAML-ish frontmatter (name, description, optional tools comma-list, optional model), discovered from ~/.pi/agent/agents/ (user scope, default) and/or the nearest ancestor .pi/agents/ (project scope, opt-in via agentScope: "both" or "project" — gated behind a confirmation prompt since project agents are repo-controlled). See examples/agents/ in this package for two starter definitions (scout.md, reviewer.md) — copy them to ~/.pi/agent/agents/ (or a project's .pi/agents/) to try them; they are not auto-installed anywhere by this package.

subagent({ agent: "scout", task: "find where the auth middleware is registered" })
subagent({ tasks: [{agent: "scout", task: "..."}, {agent: "reviewer", task: "..."}] })
subagent({ chain: [{agent: "scout", task: "find X"}, {agent: "reviewer", task: "review {previous}"}] })