pi-subprocess

Minimal subprocess isolation for Pi agents. Spawns isolated Pi subprocesses and returns curated results — keeps the parent's context clean.

Install

From npm:

pi install npm:pi-subprocess

From git:

pi install git+https://github.com/juanje/pi-subprocess.git

Or load directly without installing:

pi -e /path/to/pi-subprocess/extensions/subprocess.ts

Quick start

Once installed, a subprocess tool becomes available in your Pi session:

> Use subprocess to investigate how error handling works in the tools/ directory

The agent spawns an isolated Pi subprocess that investigates independently and returns a summary. The parent session's context grows by the summary size only, not by all the files the subagent read.

How it works

The extension registers a subprocess tool that:

1. Spawns a child Pi process in JSON mode with its own system prompt
2. Streams the child's JSONL output, collecting message_end events
3. Extracts the final assistant text from the child session
4. Truncates the output to a configurable maximum (default: 100 lines)
5. Returns the curated text + stats (turns, tool calls, tokens, cost, duration)

Context isolation

The child runs in its own process with a fresh context window. It inherits the parent's working directory and environment (including permission policies from pi-permission-gate if installed), but none of the parent's conversation history.

Project system prompt

If .pi/SUBPROCESS_SYSTEM.md exists in the working directory, its content replaces the default generic worker prompt. This lets a project define subprocess behavior once — identity, rules, tool constraints — instead of repeating it in every call.

Per-call specialization appends on top of the base via system_prompt (inline text) or system_prompt_file (path to a file on disk). Use system_prompt_file for static per-phase identities that don't change between invocations — the parent agent passes a path and never loads the content into its own context.

Prompt hierarchy:

.pi/SUBPROCESS_SYSTEM.md (or built-in default)
  └── system_prompt OR system_prompt_file (per-call specialization)
        └── task parameter (the work item for this subprocess)

Example with multiple worker types:

.pi/
├── SUBPROCESS_SYSTEM.md        # Shared base (authority, atomicity, return rules)
└── workers/
    ├── extract.md              # Extraction identity + manifest format
    ├── write.md                # Page-writing rules + link format
    └── fix.md                  # Link-fixing constraints

subprocess(
  task = "Read /path/to/manifest.md and write pages...",
  system_prompt_file = ".pi/workers/write.md",
  tools = "read,write",
  timeout_ms = 600000
)

Recursion prevention

The extension sets PI_SUBPROCESS_CHILD=1 in the child's environment. If this variable is already set, the extension skips registration entirely — no infinite recursion.

Session persistence

Child sessions are saved alongside the parent session for post-hoc analysis:

~/.pi/agent/sessions/my-project/
├── 2026-06-19_abc123.jsonl          # parent session
└── 2026-06-19_abc123/
    └── subprocess-x7k9m2/           # child session
        ├── session.jsonl
        └── ...

Tool parameters

Parameter	Type	Required	Default	Description
task	string	yes	—	What the worker should do
system_prompt	string	no	—	Custom prompt text appended to the worker prompt. Mutually exclusive with system_prompt_file.
system_prompt_file	string	no	—	Path (relative to cwd) to a file appended to the worker prompt. Use for static identities. Mutually exclusive with system_prompt.
tools	string	no	read,bash,grep,find,ls	Comma-separated tools for the worker
max_lines	number	no	100	Maximum output lines returned
effort	fast | balanced | thorough	no	—	Thinking depth (maps to Pi --thinking low/medium/high)
timeout_ms	number	no	900000 (15 min)	Kill the subprocess after this duration

Tool result

The tool returns:

• content — the subprocess's final text (truncated if over max_lines)
• details — stats object:

Field	Type	Description
turns	number	Assistant turns in the child session
toolCalls	number	Total tool invocations
totalTokens	number	Token consumption
cost	number	API cost
durationMs	number	Wall-clock duration
sessionDir	string	Path to child session JSONL
timedOut	boolean	Whether the timeout killed the child
outputTruncated	boolean	Whether output exceeded max_lines
fullOutputFile	string?	Path to untruncated output (only when truncated)

The details field is visible to the parent agent but not injected into the context text. When output is truncated, the full text is saved to full-output.md in the session directory for post-hoc review.

When to use

• Investigation would flood context — reading multiple files, grepping large codebases, fetching logs
• Research before synthesis — delegate the fact-finding, keep the parent focused on analysis
• Skill-directed isolation — skills can explicitly invoke subprocess for specific substeps

When NOT to use

• Simple file reads or single tool calls — the overhead of spawning a subprocess isn't worth it
• Tasks requiring parent conversation history — the child starts fresh
• Tasks requiring write access to parent state — the child's writes don't propagate back

Development

git clone https://github.com/juanje/pi-subprocess.git
cd pi-subprocess
npm install
npm run check    # typecheck + lint + test

License

MIT — see LICENSE.