billion-context-pi-subagents

English | 中文

acp_delegate sub-agent tools for the Pi coding agent — split out of billion-context-pi (#612). Hand a self-contained task to a fresh pi process running in a clean context; the result comes back as a file path, keeping your main session lean.

Relationship to the other packages

billion-context-pi bundles this package. Since the split (#612), billion-context-pi pins this package as an exact devDependency and inlines it into its dist at build time (the same mechanism it uses for acp-kernel). If you use billion-context-pi you already have acp_delegate — do not install this package separately. If both end up loaded, the standalone copy detects the bundled copy at session start and stands down automatically (no duplicate tools or prompt sections).

Install this package directly only if you want delegation without billion-context-pi: the delegate children then rely on Pi's native context management instead of ACP compression, and the /acp-subagents command is not available.

When the two run together they coexist in one Pi process: same acp.json convention (each reads only its own keys) and same log file (~/.pi/acp.log).

Install

billion-context-pi users: skip this — it is already bundled. This install is only for standalone use without billion-context-pi:

pi install npm:billion-context-pi-subagents

No configuration needed — delegates are enabled by default. Restart Pi after installing.

⚠️ v0.1.x has no auto-update. Standalone installs must be upgraded manually (pi install npm:billion-context-pi-subagents@latest or re-install). The copy bundled inside billion-context-pi updates with billion-context-pi releases.

Model-facing tools

Roles

Five built-in roles, each with a system prompt and a soft tool guardrail:

Read-only roles receive a restricted tool allowlist plus ACP context tools so they can manage their own context. This prevents accidental file modifications, but bash can bypass it — it is a guardrail, not a security boundary. Worker runs on Pi's full default toolset (any loaded extension or custom tools stay available).

Execution model

• Interactive (TUI) & RPC modes: async:true (default) runs the child in the background; a short completion notification is injected into the chat when it finishes — unless the model already read the result file after the run finished (detected via the read tool or a bash command referencing the file), in which case the notification is skipped: the model already has the result, so re-injecting it would only waste context. Set delegate: { notifyIfRead: "always" } in acp.json to restore always-inject.
• Print / JSON modes (pi -p, SDK): async:true auto-downgrades to synchronous — the result returns as the tool result in the same turn.
• Failures are loud, never silent. A failed run (nonzero exit, spawn error, watchdog timeout) injects a FAILED ⚠️ notification carrying a short error excerpt. If a notification cannot be delivered at all, a recovery notice is attached to the next delegate notification or tool result.
• Result delivery: the full delegate output is saved to $TMPDIR/acp-delegate/<runId>.out; the tool result and notification carry only the task title + file path (no preview) — use read for the details.
• Live visibility (TUI): async runs show a status widget below the editor and a footer line with cumulative token/cost usage. /acp-fleet (or the ctrl+alt+d shortcut) opens the interactive fleet inspector: live list + transcript overlay. Disabled automatically in RPC/print/JSON.
• Resumable runs: a run can be resumed from its saved session (.session.jsonl next to the result file) — earlier tool calls are restored instead of replayed.

Configuration

Same file convention as billion-context-pi: ~/.pi/acp.json (global) and <project>/.pi/acp.json (project overrides global). This package reads only the keys below; all other keys in the same file belong to other packages and are ignored here.

{ "delegate": false }

or object form:

{
  "delegate": {
    "enabled": true,
    "maxDepth": 2,
    "maxConcurrent": 3,
    "syncTimeoutMinutes": 5,
    "idleTimeoutMinutes": 5,
    "asyncTimeoutMinutes": 30,
    "thinkingLevel": "medium",
    "notifyIfRead": "skip",
    "displayUsage": "separate",
    "forceEnable": false,
    "fleetShortcut": "ctrl+alt+d",
    "agents": {
      "reviewer": { "model": "anthropic/claude-sonnet-4-5", "thinkingLevel": "high" },
      "worker":   { "model": "zhipu/glm-4.7" }
    }
  }
}

Invalid values never fail the session — they warn in ~/.pi/acp.log and fall back to defaults. Precedence: env > project acp.json > global acp.json > default.

A change to any delegate.* key takes effect on a new session (tools register at session start).

Using your own sub-agent instead

If you also run pi-subagents (or similar), two overlapping sub-agent systems make the model's choice noisier. Detection happens at session start:

• Project-scope install (<cwd>/.pi/npm/node_modules/pi-subagents or <cwd>/.pi/extensions/pi-subagents) → acp_delegate stands down automatically for that project (tools, shortcut and prompt section skipped); a reminder points at /acp-subagents (from billion-context-pi) so the third-party agents still get ACP compression.
• User-scope-only install (~/.pi/npm, user extensions dir) → acp_delegate stays active; a warning is logged instead.
• Keep both anyway: { "delegate": { "forceEnable": true } }.
• Drop this package entirely: pi remove npm:billion-context-pi-subagents.

Pi's --exclude-tools acp_delegate,acp_delegate_wait,acp_delegate_cancel is not a substitute for delegate: false: it hides the tools but the model still receives the ACP_DELEGATE NOTIFICATIONS section describing tools it cannot call.

Host support

Built for Pi (@earendil-works/pi-coding-agent >= 0.83). On hosts without Pi's buildContextEntries() session API (e.g. OMP), nothing is registered and a warning is printed once per process; Pi-compatible forks can opt in with PI_ACP_FORK_HOST=1 (same contract as billion-context-pi's docs/host-adapter.md).

Logging

Writes to the shared ACP log ~/.pi/acp.log (override with ACP_LOG_FILE), same format as billion-context-pi:

tail -f ~/.pi/acp.log                 # watch the session live
grep '\[error\]' ~/.pi/acp.log        # surface every recorded failure

Delegate lifecycle events (spawn/done/fail/cancel, stand-down decisions, config warnings) are always-on; debug: true adds verbose diagnostics.

License

MIT.