@tian.zuo/pi-subagents (deprecated)

Release notes: changelog · GitHub releases

Deprecated: no longer recommended or actively developed. The source remains here for historical reference; deprecation does not introduce a replacement tool. The root package no longer loads this extension.

Remove it

pi remove npm:@tian.zuo/pi-subagents

Restart Pi or run /reload to unload it. Remove any explicit local extension paths and instructions requiring the subagent tools from your own settings, prompts, or AGENTS.md.

Historical behavior

Delegates bounded tasks to isolated subagent runs from pi. Each profile can run on a Herdr pane backend (interactive agent CLIs in dedicated panes) or fall back to the legacy RPC child backend (pi --mode rpc headless children).

Requires a Herdr session (HERDR_ENV=1 and herdr on PATH) for non-pi agent kinds and for profiles that pin backend: herdr. Built-in profiles default to kind: pi and backend: auto, so out-of-the-box behavior stays RPC-based when Herdr is not active.

What it does

• subagent tool — spawn a profile-locked run and return a bounded report (structured when possible)
• Dual backend — Herdr when available and appropriate; RPC child otherwise (see Backend selection below)
• Structured handoff — Herdr runs use a file-based report contract; RPC runs use the report_result tool. Missing or invalid reports fall back to bounded transcript text
• Built-in profiles — scout, planner, reviewer, oracle (read-only), worker (git worktree + writes)
• Parallel runs — call subagent multiple times in one turn (sibling tool calls)
• Background mode — mode: "background" returns immediately; completion arrives as a follow-up notification (exactly once)
• subagent_status / subagent_cancel / subagent_apply — poll, cancel, or explicitly apply a worker patch
• /agents command — list session runs, Herdr pane metadata, and actions to focus a pane, read the last 80 transcript lines, or close a helper pane

Capabilities (tools, workspace) and the resolved model come from the profile — not from tool arguments.

Backend selection

Resolved per run from profile frontmatter:

If backend: auto (or implicit auto) and kind is not pi while Herdr is unavailable, the run fails with a clear error (for example: Profile "x" requires agent kind "codex", which needs a Herdr session). Non-pi kinds are never silently downgraded to a pi RPC child.

Profile frontmatter

Profiles live as Markdown with YAML frontmatter:

Reference profiles by short name (scout) or qualified id (builtin/reviewer, project/my-agent).

Example user profile for a read-only Codex reviewer in Herdr:

---
kind: codex
backend: herdr
tools: [read, grep]
workspace: shared-readonly
---

Herdr runs — honest limits

Herdr-backed runs do not provide:

• Usage / cost telemetry — reports show cost: n/a; session cost warnings only count RPC usage
• Per-tool allowlist enforcement — only the RPC backend can enforce --tools; Herdr profiles should declare tools honestly in the prompt
• maxTurns enforcement — no turn_start signal; wall-clock timeoutMs only

blocked agent status is surfaced to the parent; the extension never auto-approves.

Worker isolation for write profiles uses herdr worktree create (branch checked out in a linked worktree). Patch generation, 0600/0700 artifacts, sha256 confirmation, and subagent_apply behave the same as RPC worktrees.

Helper panes and workspaces created by this session stay open for inspection until /agents closes them or the session shuts down.

Example

{
  "profile": "scout",
  "task": "Find where session cost is accumulated and summarize the flow.",
  "context": "Repo is pi-extensions; subagents live in packages/pi-subagents."
}

Background:

{
  "profile": "planner",
  "task": "Draft a test plan for worktree cleanup.",
  "mode": "background"
}

Apply a worker patch after explicit confirmation:

{
  "run_id": "sa-a13f9c2b"
}

Use the subagent_apply tool (not automatic for worker runs).

Session limits

• Max 4 concurrent runs (and concurrently open helper panes on Herdr)
• Max 20 runs per parent session
• Profile maxTurns default 8 — RPC only (soft live-turn boundary via turn_start)
• Soft cost warning at 80% of session ceiling (default $5; RPC usage only; override via settings.json → subagents.sessionSoftCostUsd)

RPC child isolation

RPC children use --no-extensions, --no-skills, and related flags. The supervisor loads only the package-owned child runtime via -e <package>/lib/child-runtime.ts, which registers report_result.

Worktrees and patches

The worker profile commits changes to pi-subagent-<runId> branches, writes a private persistent patch artifact under ~/.pi/agent/subagents/runs/<runId>/changes.patch, and removes the temp worktree (or Herdr workspace) only after the branch and patch are durable. Applying changes to the parent checkout requires subagent_apply with interactive confirmation.

Patch artifact storage and security

Machine-local subagent state lives under ~/.pi/agent/subagents/:

Patch artifacts are written with 0600 files inside 0700 directories. Each patch is a full git diff --binary from the run baseline and may contain secrets. The supervisor keeps the 32 most recent runs/<runId>/ directories (by modification time) on session start and dispose.

Settings (~/.pi/agent/settings.json or .pi/settings.json)

{
  "subagents": {
    "defaultTimeoutMs": 600000,
    "defaultMaxTurns": 8,
    "sessionSoftCostUsd": 5,
    "agentOverrides": {
      "scout": { "thinking": "high", "maxTurns": 6 }
    }
  }
}

Development

From the monorepo:

pnpm --filter @tian.zuo/pi-subagents run check
pi -e ./packages/pi-subagents

Tests remain under test/ as historical reference, but this package no longer declares a test script. Local workspace runs and CI skip them.

Set HERDR_ENV=1 and ensure a fake or real herdr binary is on PATH when exercising Herdr-backed profiles locally.