@hheei/pi-subagents

Run several independent Pi child sessions from one Pi session, each with its own Pi session file, its own runtime, and its own durable identity.

The package is a single concrete extension with one pi.extensions entry (dist/extension.js). The same entry runs on both sides: the parent branch registers the model-facing tools, commands, compact footer status, and info entries; the child branch registers only the reporting bridge and session-leave reporting.

Parent tools

The extension registers no global keyboard shortcuts. Use /subagents to manage children and /subagents stop [id] to stop one without conflicting with other extensions.

Unified Task Management

agents_delegate returns { id, revision, status, task, hasOutput }: revision identifies that delegation of the agent, and a settled delegation carries its result when wait is true. agents_stop returns the same projection for the agent it stopped. Failures return only their reason. There is no public title or mode: the child session title is derived from the agent name and id, and continuing an agent always steers.

SubagentManager and its SQLite ledger own child conversation state, runtime leases, recovery, and reports. No pi-ext-tools task service is required. Only delivery batching is shared through ext-core BackgroundDelivery. Child reports arrive automatically; do not poll status to detect completion. Bash uses separate bg_bash_* tools. Deferred agent tools are loaded via tool_search; before_agent_start writes the subagents bullet into the structured prompt's optional_tools section. Diagnostics describe blockers, failed turns, or uncertain runtime state.

Child execution and reporting

Subagents communicate with the parent through the commands table in state.sqlite, with each child holding a SQLite process lock that proves its writer is alive:

• Completion by Direct Output: Subagents do not need to call any reporting tool upon successful completion. The subagent simply outputs its final answer as normal assistant text.
• Settlement Batching: When a subagent settles, the harness captures the trailing assistant text and delivers it to the parent conversation as a subagent-report. Reports flush within 500ms when no other child is working, and are batched for up to 10 seconds while another child is still running.
• Blockers & Decisions: The child registers contact_parent({ message, reason? }) strictly for reporting when it is blocked or urgently requires a parent decision midway (reason defaults to 'blocked'). Blocked reports wake the parent immediately.
• Direct /compact Command: Sending "/compact" (or "/compact [instructions]") via agents_delegate intercepts the command on the child side without passing it as prompt text to the LLM. The child executes native context compaction and reports completion status back to the parent via contact_parent. Duplicate /compact requests while a compaction is already in flight are safely acknowledged and ignored.
• Context Trim Hint: When a subagent completes a task with context usage exceeding 100,000 tokens, its report includes a hint advising the parent to trim memory via agents_delegate({ id, task: "/compact" }) if the child session will be retained for future work.
• Automatic Retry: Pi's own auto-retry is observed, not invented: reports are suppressed while a retry is in flight, and a retry that succeeds clears the previous error instead of reporting it.
• Panel Failure Auto-Close: When a subagent running in a panel encounters a fatal error or reports a blocker, the manager starts a 15-second countdown after notifying the parent, automatically closing the panel tab to avoid workspace clutter unless new instructions are dispatched.

Compact status and reports

Running children use the native Pi status line: agents xN (e.g. agents x3). With pi-status installed, this appears at the bottom right before the existing TODO segment, separated by ‧. No running children means no agent segment; no multi-line parent widget is mounted.

Confirmed done, error, and blocked reports appear once as subagent-info transcript entries. Collapsed entries show the outcome, child ID, and agent name; expand to read the complete report. They survive resume and do not enter model context. The original automatic subagent-report still reaches the model, with its duplicate transcript display hidden. Transient errors remain subject to settlement and retry checks before reporting.

Use /subagents for complete status and management. agents_delegate with an existing id can resume a done, blocked, errored, or stopped child with its session context intact; retrying does not guarantee the underlying failure is resolved.

Host Integration and Isolation

• A Panel Host Is Chosen By Fact: Herdr, cmux, and Rex are probed in that order. A host is only chosen when it can prove this process runs in one of its containers: Herdr from herdr pane process-info, Rex from rex block call process (REX_BLOCK is a hint, never the answer). cmux has no such query and answers with its own ping. No host means a headless child.
• Herdr Attachment Is A Fact: A pane is only this parent's pane when the kernel says so — one of the pane's foreground processes (herdr pane process-info) must be this process or one of its ancestors, and only then is a tab created there (--workspace <WORKSPACE_ID>). The pane's own shell does not count, so pi & stays out. Inherited HERDR_ENV/HERDR_PANE_ID merely order the candidates, and herdr pane current --current (which answers where a human is looking) is never used as identity. No match means no panel and a headless child.
• Panel Failures Degrade: When the panel cannot be opened and no explicit panel presentation was requested, the child runs in the background and the spawn result says why. Host error codes are surfaced instead of being folded into a generic message.
• Memory Isolation: Both PI_HINDSIGHT_DISABLE=1 and PI_OBSERVATIONAL_MEMORY_DISABLE=1 are injected into child processes. Hindsight memory auto-registration, recall, and writeback are disabled, and the child bridge blocks all mcp__hindsight__* calls. Background Observational Memory workers (observation, reflection, compaction triggers) are suppressed in passive mode.

Agent definitions

Agent Markdown files are discovered in this order, most specific first, by name:

<cwd>/.pi/agents/*.md
<cwd>/.pi/agents/*.md
~/.pi/agent/agents/*.md

Frontmatter is parsed with Pi's parseFrontmatter and validated against this package's schema. Supported fields: name, display_name, description, hidden, model, thinking, tools, exclude_tools, extensions, skills, mcp, codemode.

Unified Resource Selection (Pi Semantics)

tools, skills, and mcp follow Pi's unified selection semantics:

• boolean toggle:
  • true (or omitted): Full inheritance from host defaults.
  • false: Completely disabled (passes --no-mcp, --no-skills, --no-tools respectively; --no-mcp physically shuts down the MCP subsystem so no server processes or network connections start).
  • MCP selection (mcp: [server1]) acts at the tool exposure and execution boundary via --tools / --exclude-tools patterns and child-bridge tool call gating. Non-whitelisted or excluded server tools cannot be viewed or called.
• Exact list (Whitelist / Replace):
  • [item1, item2]: Activates only the named entries.
• Incremental modifiers (+ / -):
  • ["+itemA", "-itemB"]: Adds or excludes entries relative to base defaults. Exact names and modifiers cannot be mixed.

Built-in Agents

• scout: Read-only reconnaissance agent. Disabled by default until the user explicitly configures a model in ~/.pi/agent/agents/scout.md.
• worker: General implementation agent. Configured with model: inherit to inherit the parent session's model and thinking level.
• reviewer: Code review agent. Configured with model: inherit and leverages skill discovery to run review skills.