@zhcsyncer/pi-subagents

简体中文

Maintained fork of @tintinweb/pi-subagents, pinned to v0.14.3. Available standalone and embedded in @zhcsyncer/pi-extensions.

Upstream snapshot · Source and upstream differences · Upstream license

Install

Choose one:

pi install npm:@zhcsyncer/pi-subagents
# Or install the bundle:
pi install npm:@zhcsyncer/pi-extensions

Remove any existing @tintinweb/pi-subagents installation from Pi settings before loading this fork: both register the same tools and FleetView.

Core features and upstream differences

• Delegate work: Agent, get_subagent_result, and steer_subagent; custom agent roles, model/thinking selection, inherited context, schedules, and concurrency limits.
• Useful background reports: notifications include the final report, not just a short preview. Manual Agent-tool background completions reach the parent's next reasoning step; scheduled/RPC completions wait until its current loop finishes.
• Continue the same agent: steering a completed or soft-turn-limit agent automatically continues it in the background. Explicit Agent(resume=...) supports foreground or background continuation, including eligible saved history.
• Readable progress: compact Claude Code-style rows for all three tools, honest queued/working states, readable durations, effective model/effort, separate lifetime usage and current context, and expandable Markdown results.
• Browse finished work: ordinary sessions persist by default, nest beneath the parent in Pi's /resume for same-directory runs, and remain openable from /agents finished history.
• Worktrees are opt-in: selected upstream 0.17 session/isolation behavior, but worktreeIsolation defaults to false here rather than upstream's enabled default.
• Integrate with other extensions: protocol-v3 in-process spawn with inline roles, caller-owned completion, route correlation, and concurrency discovery; an importable runtime without automatic UI/tool registration.
• Keep trusted observers active: pinnedExtensions loads observers even in isolated agents without granting their tools.

The upstream snapshot covers custom agents, schedules, and other baseline features. For delivery, continuation, persistence, configuration locations, and worktree defaults, use this fork's documentation instead.

Delegate and receive results

Use foreground (default) when the result is a prerequisite for your next read, edit, or decision. Use run_in_background: true only when you have genuinely disjoint work to do. Do not poll, sleep, or duplicate the subagent's evidence collection while it runs. You still own synthesis and final verification; check high-risk claims rather than repeating the whole investigation.

Background notifications include the complete final report when it fits within 16 KiB of UTF-8 per emitted message, including metadata and escaping. Grouped reports share that total budget, not one budget per agent. Oversized reports are explicitly marked as truncated and direct you to get_subagent_result(agent_id) for the full result. Add verbose: true for the conversation, including tool outputs.

get_subagent_result with wait: true waits for completion. Cancelling that wait cancels only the waiter, not the child or its eventual completion notification. Use FleetView's stop action to stop the child.

Manual Agent-tool background completion (including custom roles that default to background) uses steer: while the parent is busy, it arrives after currently issued tools finish and before the next model call; while idle, triggerTurn: true starts reasoning. It cannot retract sibling tools already issued in the same turn. Scheduler/RPC completion uses followUp: while busy, it waits for the loop to finish; while idle, it also triggers reasoning. Caller-owned completion suppresses this parent nudge. Foreground results return inline without a background nudge.

Session usage and Glance

reportUsage defaults to on in this fork (unlike upstream 0.18). Pi 0.81.0 or newer counts collected child usage in native session totals and Glance:

• Foreground: usage is attached to the completed Agent tool result.
• Background: the launch acknowledgement carries no usage; the completed get_subagent_result reports it once. A notification alone does not yet update parent totals.
• Repeated retrievals and resumes report only previously unreported lifetime usage, including cache reads and provider-reported cost.

Keep pi-meter pinned for live child-session accounting. Meter ignores the parent rollup rather than charging it again; child messages and history imports retain their original session/model attribution. Disable Report usage in /agents → Settings (or reportUsage: false) to opt out of parent totals without disabling the pin.

Steer, continue, or retry

Use steer_subagent with the same agent ID and a message:

Agent state	What happens
Running	Appends steering to the current run
Queued or initializing	Saves the message for delivery when the child is ready
Completed or steered (soft turn limit)	Starts a background continuation with the same ID and context, subject to concurrency limits
Error, aborted, or stopped	Rejects steering; an explicit resume is required to retry

For explicit continuation, use Agent with resume: "<agent-id>" and prompt: "<follow-up>". Resume defaults to foreground, even if the earlier run was background. Add run_in_background: true to return immediately with queued/running status and use the same automatic completion, wait, and stop lifecycle as a new background run. Background resumes respect the concurrency limit; foreground resumes bypass the background queue, like new foreground runs.

A new Agent call without resume starts fresh; it does not inherit the old agent's conversation. Failure and stopped states are never automatically retried. If a continuation fails or is stopped, result retrieval retains the previous completed report under an explicit history label; it is not presented as the failed run's output. Resuming the same ID does not redeliver the previous run's pending completion as a new result.

Saved versus live-only agents

Ordinary runs persist by default. Set persist_session: false in an agent file for a live-only run, or rememberAgents: false in /agents → Settings for a memory-only default; explicit persist_session: true overrides that default. Live-only agents can continue while retained, but not reliably after eviction or restart.

Recovery of saved terminal work requires eligible new-format history on the current parent-session branch and an intact child session. Older history remains viewable but cannot be resumed through these tools without recovery information. Failed/stopped saved runs still require explicit Agent(resume=...).

Missing or corrupt recovery files, an unavailable original working directory (including a cleaned-up worktree), or an unavailable original model cause an explicit error—never a fresh session or substitute model. Recovery uses currently installed extensions and current credentials; it is not a process/memory snapshot or a sandbox. In-flight work and queued follow-ups are not durably replayed after an unclean crash; no crash-exactly-once guarantee is provided.

Inspect progress and settings

Open /agents / FleetView and select an agent to see Prompt → Usage → Steps → Result. Tool bodies are folded by default; failure and turn-limit outcomes remain explicit.

Key	Action
Esc / q / Ctrl+C	Close
↑↓ / PgUp/PgDn	Scroll
Enter in the conversation view	Steer a running agent
x x	Confirm stop
o	Expand/fold tool arguments and results
Ctrl+O in the main transcript	Expand the tool's Markdown result

Compact lifetime tokens mean input + output + cache write; cache reads remain in the full Usage breakdown (upstream issue #38). Current context is context-window usage, not a percentage of lifetime tokens. effort is the display name for thinking. Compact progress shows stable coarse phases rather than streaming paths, commands, or assistant text.

Manage project preferences in /agents → Settings:

• Worktree isolation: off by default. When disabled, the Agent tool omits worktree options and worktree requests from agent files, schedules, or RPC run in the real checkout. Enable it for isolation: "off" | "worktree" in the next Pi session. Once enabled, worktree creation failure is an error, not a checkout fallback.
• Pinned observers: only user-owned global configuration can grant names such as pi-meter; projects can inherit or clear pins, not add observers. Pinning is not a sandbox: handlers still run, so pin only trusted observers. Their tools remain subject to the agent's normal tool policy, including isolated / extensions: false.
• Agent description: use the example template for custom delegation guidance.

Configuration and integration reference · Delivery and recovery contract

License

MIT — LICENSE and UPSTREAM_LICENSE.