pi-simple-subagents

Delegate bounded tasks to isolated Pi subagent processes. Each invocation spawns a separate pi process with its own context window; the parent collects structured output and keeps its own context lean.

Despite the name, this is the full-featured subagent tool — "simple" refers to the contract: bounded tasks in, structured result out.

What it adds

• subagent, an LLM-callable tool with three modes:
  • single — one agent, one task
  • parallel — a tasks[] batch with an optional shared immutable context
  • chain — sequential steps where {previous} placeholders receive the prior step's output
• Execution profiles (quick, coder, default, thinker, deep-thinker): ordered model-candidate ladders from the shared machine-local ~/.pi/agent/profiles.yaml, shared with @pi-kaush/pi-agent-mode and @pi-kaush/pi-model-profiles. Profiles reload on file change — ladder edits apply to long-running sessions without a restart.
• Model-facing discovery: user agents are read from ~/.pi/agent/agents/*.md when the extension loads and listed alongside the execution profiles in the tool guidance. Agent names select behavior and tools; profile names select compute. When both appear in a request, their order does not matter: thinker redteam and redteam thinker select the same pair.
• Bounded delegation: depth 2, five children per call, five active children per Pi session, at most thirty simultaneously active descendants. Completed children release their slots.
• Subtree-safe lifecycle: depth-1 children lead POSIX process groups; abort, timeout, and session shutdown terminate the whole subtree (graceful then forced). Windows uses taskkill /T.
• Child watchdogs: two hours total runtime and fifteen minutes without output by default; either configurable in src/limits.json, 0 disables. The orchestrator is never watchdogged.
• Resumable child sessions: children persist real Pi sessions, named subagent(<agent>): <task preview>. Expanded tool output shows the full session ID with a pi --session <id> resume hint and the session file path for live tail -f viewing. Disable with persistChildSessions: false.
• Transcript artifacts: every child's complete stdout/stderr streams to a private JSONL artifact under ~/.pi/agent/subagent-runs/; tool details keep bounded previews and artifact paths.
• Structured yield: delegated children finish through a terminating yield tool (completed, blocked, failed), with artifact paths; ordinary final assistant output remains a fallback.
• Model resolution: before delegation, refresh Pi's authenticated model catalog locally; select profile candidates and bare model overrides from that catalog, not the parent's enabledModels / scopedModels cycling list. An explicit model overrides an invocation profile, which overrides the agent's profile frontmatter, then its legacy model field. Bare ids resolve family-scoped by nearest version; qualified refs pass through to the child for validation.

Agents

Agent definitions are Markdown files with optional frontmatter (emoji, profile, model, tools, confirmProjectAgents). Declare either profile or model, not both. Discovery:

1. user: ~/.pi/agent/agents/*.md
2. project: nearest .pi/agents/*.md, with agentScope: "project" | "both"

User agents are advertised to the parent model at extension load. Additions or renames need /reload to refresh that catalog. Project agents remain dynamically discoverable by exact name without being embedded in the global catalog. Project-controlled agents prompt for confirmation before first use.

Configuration

src/limits.json bounds delegation (validated against hard ceilings):

{
  "maxDepth": 2,
  "maxChildrenPerCall": 5,
  "maxConcurrency": 5,
  "maxRuntimeMs": 7200000,
  "maxInactivityMs": 900000,
  "persistChildSessions": true
}

The model-profiles schema lives in @pi-kaush/pi-model-profiles.