Pi Subagent

Run focused, bounded investigations in an ephemeral child Pi process while keeping intermediate tool output out of the parent context.

@mdgchamomile/pi-subagent bundles two parts that work together:

• pi_subagent extension — enforces scope, tool ownership, resource budgets, lifecycle, telemetry, and output boundaries.
• Companion skill — guides the parent in deciding when to delegate and selecting the appropriate capability and model preset.

See it in action

An illustrated CLI walkthrough of Pi Subagent's delegation workflow. The example uses a synthetic retry bug; dialogue, timing, and usage figures are illustrative rather than a recording of a live model session.

Model invoked — ask a normal question. When a focused investigation is appropriate, Pi can select the skill and delegate the investigation to a scoped, read-only child. You can also invoke /skill:pi-subagent explicitly with a focused task and scope; the parent follows the skill guidance and calls the same pi_subagent tool.

Why use it?

What fills an AI's context shapes its work. Investigations can fill the main conversation with file reads, searches, fetched pages, and exploratory reasoning. Pi Subagent moves that work into a foreground child process and returns only its bounded final answer.

• Keep context focused — discard intermediate child turns and tool results while the parent handles decisions and final verification.
• Limit access explicitly — authorize 1–8 local paths or use a separate web-only capability; local and web tools never coexist in one child.
• Bound execution — cap runtime, tool calls, web requests, and final output while reporting progress and partial results visibly.
• Load guidance only when needed — progressively disclose the bundled skill instead of adding the full workflow to every prompt.

How it works

1. The parent chooses one focused task, a capability, an explicit scope, and a preset.
2. An ephemeral, read-only child Pi process investigates within runtime-enforced scope, tool, time, and output limits.
3. Intermediate child turns and tool results are discarded. The parent receives a bounded JSON envelope with runtime-owned status fields and the untrusted child answer; see the result contract.
4. The parent verifies decisive claims and performs any implementation or final validation itself.

The child cannot write files, run Bash or tests, persist a session, or recursively launch more agents. See the extension guide for the process, guard, and readiness details.

Install

Requirements:

• Linux, including Ubuntu on WSL; native Windows is not officially supported or tested;
• Pi 1.0.0 or later;
• authentication for the configured child provider and access to its model (openai-codex by default; see Presets).

Capability-specific requirements:

• local: rg for grep, and fd or fdfind for find;
• web: pi-web-access; see Optional web capability.

[!IMPORTANT] This package provides an application-level capability boundary, not an OS, network, or credential-isolated sandbox. Pi extensions execute with the current user's system permissions. Review the source and trust assumptions before installing it.

pi install npm:@mdgchamomile/pi-subagent

Restart Pi or run /reload.

Optional web capability

Local investigations work with this package alone. Web investigations require pi-web-access v0.33.0 or later (stable releases) with its default tool names:

pi install npm:pi-web-access

Newer stable versions are allowed without an upper bound, not guaranteed compatible; upstream behavior changes may require maintenance. Package provenance checks, argument allowlists, and execution limits remain enforced. Without that dependency, local runs remain available.

First investigation

Before your first call, run /pi-subagent-settings in Pi's TUI to check the model for each preset you plan to use. If you cannot access a default model, select one you can access. Subagents do not inherit the parent model, and there is no automatic fallback. See Presets for details.

The model can select the skill automatically. To invoke it explicitly, include a focused task and scope. For example, from a project with a src/ directory:

/skill:pi-subagent Investigate how cancellation terminates child processes within src/. Return conclusions with file and line evidence.

This command gives delegation guidance to the parent, which then calls the pi_subagent tool.

Capabilities

Mixed local-and-web work uses separate child calls, with synthesis performed by the parent. One call is the default; up to three distinct, independent calls may run in parallel during one parent agent run, which can multiply model, provider, and web-request usage.

Presets

These are default settings, not required providers or models. They do not inherit the parent model or change its thinking level.

Run /pi-subagent-settings in Pi's TUI to change a preset's provider, model, or thinking level, or edit ~/.pi/agent/pi-subagent.json (under PI_CODING_AGENT_DIR when set). Settings apply to the next call without a reload. Only user-level settings are read; project files and tool arguments cannot override them, and there is no automatic fallback. Authenticate each provider through Pi. See the extension guide for the settings file format and validation rules.

Security and data flow

Authorized local-file contents, web tasks and queries, fetched pages, and the final answer are sent to the applicable configured model or search providers. Do not delegate secrets that must not leave the host or use the package for untrusted workloads requiring host isolation.

The runtime canonicalizes local paths, blocks lexical and symlink escapes, verifies tool provenance, and sanitizes control characters in returned text. After the child exits, the parent verifies the guard's private readiness marker before accepting its final answer.

Documentation

• Extension guide — complete runtime, installation, security, and verification contract.
• Skill guide — when delegation is appropriate and how the workflow selects a child.
• Source repository
• Issue tracker
• Contributing — development setup and offline verification.
• Package maintenance — package assembly and release procedures.
• Migration — breaking changes for existing installations.
• Design principles — local pointer to the canonical principles.

License

MIT