pi-tidy-subagents

Fan work out to child Pi agents without losing the thread. Adds a subagent tool for Pi that runs independent child prompts concurrently — in the foreground or as session-scoped background workers — and renders each child as one compact, scannable line. A companion subagent_control tool steers, cancels, inspects, and collects them.

pi install npm:@mobrienv/pi-tidy-subagents

Usage

The model calls subagent with an ordered batch. Each child carries a short transcript reason and a verbatim prompt:

{
  "agents": [
    {
      "label": "tests",
      "reason": "run the unit suite",
      "prompt": "Run npm test and summarize any failures.",
    },
    {
      "label": "review",
      "reason": "audit the diff",
      "prompt": "Review the working-tree diff for correctness bugs.",
      "thinking": "high",
    },
  ],
}

Children inherit the parent's model, thinking level, working directory, extensions, skills, and active tools by default; each may optionally pick an exact model or a different thinking level. The call waits for every foreground child and preserves healthy sibling results when an individual child fails. Settled children read:

<agentName>[<model>|<thinking>] <reason> (<age> ago) → <metrics>

Active children keep their latest activity visible. Once settled, response prose moves behind ctrl+o, leaving the child summary compact; interrupted tool state remains visible because it is terminal truth. Metrics show tool calls, token traffic (↑ input, ↓ output), and elapsed time. Cards start at the terminal's left edge without a decorative rail or outer indent. Child glyphs remain because a batch can contain mixed outcomes; settled control cards rely on Pi's native success/error background instead of a redundant check or cross.

Background children

Add execution: "background" to any child and the call returns immediately with an acknowledgement while the child keeps working:

• Active background work appears in a live widget above the editor; durable transcript stamps record launches and completions, and survive session resume.
• Manage children with the /subagents overlay (ctrl+shift+b) or the subagent_control tool: background, steer, cancel, inspect, status, set_delivery, collect. Control calls render as one compact, action-specific status line; ctrl+o reveals their bounded raw response.
• Finished results arrive automatically as a follow-up turn when the parent is idle, or on demand via collect.
• Workers live for the session: reload, exit, or session replacement cancels them cleanly.

Good to know

• Children share your working tree. This package does not lock files, create worktrees, or coordinate writes — give children non-overlapping mutation scopes or read-only work.
• Complete run manifests (prompts, responses, usage, model/thinking provenance) persist under Pi's agent directory at pi-tidy-subagents/runs/<run-id>/.
• A batch fails preflight as a whole if any child requests an invalid model or an unsupported thinking level — no partial runs.
• An optional per-task routing map (/tidy-subagents-routing) can suggest thinking levels and models per task class.

The full behavior contract — runtime selection and provenance, routing hierarchy, scheduling, rendering, run-artifact schema, and the background lifecycle — lives in docs/reference.md.

Out of scope

Installing this beside another extension that owns the subagent tool name is unsupported. Cross-session/crash recovery, background-to-foreground handoff, personas, automatic model selection, fuzzy matching, and project-level routing rules are intentionally outside this package.

Development

npm test --workspace @mobrienv/pi-tidy-subagents
npm run check --workspace @mobrienv/pi-tidy-subagents
npm pack --workspace @mobrienv/pi-tidy-subagents --dry-run

Script	Role
npm test	Release-blocking hermetic suite (fake RPC; no network)
npm run smoke	Opt-in real-provider smoke (PI_TIDY_REAL_SMOKE=1); hetero children when ≥2 auth'd models; skips with diagnostics otherwise
npm run routing-eval	Opt-in observational routing probes (PI_TIDY_ROUTING_EVAL=1); offline structural fixtures already run under npm test

See docs/reference.md for routing-eval and smoke details. Regenerate the renderer artifact with bash docs/visual.sh (Chrome/Chromium and ImageMagick required).