@signalridge/pi-subagents

Managed isolated Pi agent sessions: foreground/background work, steering, Fleet UI, tiers, scheduling and protocol-v4 integration.

Install

pi install npm:@signalridge/pi-subagents

Use from this checkout

From the repository root:

pi -e ./packages/pi-subagents

Verified host baseline: Pi 1.4.0. Wildcard peer dependency ranges and retained capability fallbacks do not establish support for older host versions.

Quick start

Agent({
  subagent_type: "Explore",
  prompt: "Find all files that handle authentication",
  description: "Find auth files",
  run_in_background: true,
})

Foreground calls return inline; background calls return an ID and notify on completion. Use get_subagent_result({ agent_id, wait?, verbose? }) to read results or steer_subagent({ agent_id, message }) to redirect running/queued work. Cancelling a wait does not stop the child.

Default agent types

The general-purpose agent is a parent twin — it receives the parent's system prompt plus a sub-agent context bridge, so it follows the same rules the parent does. The parent's skill list, cwd and extension sections are left out: the subagent's own session renders them for itself, so its skills follow its skills setting. Explore and Plan use standalone prompts tailored to their read-only roles.

Default agents can be ejected (/agents → select agent → Eject) to export them as .md files for customization, overridden by creating a .md file with the same name (e.g. .pi/agents/general-purpose.md), or disabled per-project with enabled: false frontmatter.

Commands

/agents opens Agent runs, Agent types, Model tiers, Create new agent and Settings. Fleet handles empty-prompt ↓/←, ↑/↓, Enter to observe and Esc to return. Enter in an observer composes steering; x then explicit confirmation stops it. Ctrl+B hands off an eligible independent foreground run without restarting it. Workflow controls stay in /workflows. See UI and ownership.

Model tiers

The Agent tool accepts a catalogue tier, not model/thinking. Configure /agents → Model tiers and Settings → Default tier, or edit global ~/.pi/agent/subagents.json and project <cwd>/.pi/subagents.json (project overrides global; menu writes project only). Example:

{ "agentTiers": { "profiles": { "high": { "model": "provider/reasoning-model", "thinking": "high" } } } }

Both profile fields are required; either can be "inherit". Precedence: call tier → agent tier → default tier → defaultModel → parent model/thinking. Explore ships with tier low; other ordinary types inherit unless configured. Managed untiered calls instead require a named tier, with the shipped medium fallback; explicit none/noDefaultTier rejects them. See complete tier/configuration reference.

Safety and recovery

• Raw inherit_context: true is refused: pass a reviewed, sanitized task summary. Children require a checked parent runtime bridge; absent/incompatible bridges refuse before IDs or provider requests, not a fresh credential/provider runtime.
• Nesting and model scope enforcement are default-off. Nested allowlists grant the listed children's own tools, not the parent's restrictions. Project configuration/resources require trust; extension selection is not an OS sandbox. pi-background is excluded from child loading.
• Transcripts default on, independently of native session persistence, memory and worktree commits. isolation: "worktree" is strict and can make local preservation commits; failed preservation retains the checkout for manual recovery.
• Subagents never open clarification dialogs for you. Eligible background questions go to the main session, which resolves internal issues itself and asks you only for a real decision—in your language, with background, a recommendation and consequences. Other runs report blockers in their result. Permission confirmations remain human-owned; do not block an answering parent with get_subagent_result(wait: true).
• Overflow pauses automatic wakes: compact or start a new session. Reading a terminal result consumes that attempt's reminder, not stored history. Cold continuation needs exact branch/session/catalog-route proof, not physical-endpoint or cross-profile consent; unsafe history is refused.

See runtime/notifications, continuation, worktrees, and clarification limits.

Upstream and local divergence

Derived from tintinweb/pi-subagents, MIT. Local execution, privacy and protocol boundaries remain authoritative; selective-port provenance records pinned sources.

License

MIT; see LICENSE for the complete notice.

Reference

Source entrypoint: src/index.ts; run bun run check from the repository root. Detailed contracts and legacy section links:

• Host-routed clarification (background only)
• Scheduling
• UI
• FleetView
• Custom agents
• Example: .pi/agents/auditor.md
• Frontmatter fields
• Nested subagents
• Child project trust
• Tool & extension scoping
• Tools
• Agent
• Remembered ordinary-agent continuation
• get_subagent_result
• steer_subagent
• answer_subagent_question (main only)
• Graceful max turns
• Concurrency
• Join strategies
• One catalogue, including for workflows
• How the host discovers tiers
• Precedence
• defaultModel
• Editing tiers
• Refusals
• Merging global and project settings
• Migrating from model:/thinking:
• Model scope
• Persistent settings
• Events
• Cross-Extension RPC
• Discovery
• Ping
• Managed spawn (protocol v4)
• Spawn
• Stop
• Optional workflow UI bridge
• Persistent agent memory
• Worktree isolation
• Skill preloading
• Tool denylist