@henryqw/pi-subagent

Delegate bounded work to configured Pi Roles through Herdr. Direct tasks share your checkout; isolated tasks produce checked candidates for explicit integration. Both return a handle so Main can continue working.

Install

Isolated work requires Herdr 0.9.3 or later for both the client and server. The server must run on API protocol 22 or later. Pi Subagent checks Herdr and server support before it starts.

pi install npm:@henryqw/pi-task-models
pi install npm:@henryqw/pi-subagent

Configure the profiles that your Roles use in /task-models. Direct writer termination proof requires native lsof.

Works with

Use

Ask Main: “Have a scout trace sign-in without editing files.” Main calls delegate_task and stays available until progress and results arrive.

Commands, prompts, and UI are for you. Tools and the packaged skill are for Main, except git_read, which is only for Role-declared children.

delegate_task, subagent_resume, subagent_stage, subagent_integrate, and subagent_abort are model-only. Main must make these decisions visibly; codemode scripts can call only subagent_status.

Direct workflow

A read-only task:

{
  "mode": "direct",
  "role": "scout",
  "name": "Map sign-in flow",
  "task": "Trace sign-in through session creation. Report files and risks. Do not edit files.",
  "access": "read"
}

Choose exactly one shape:

Single:   { mode: "direct", role, name, task, access, ... }
Parallel: { mode: "direct", tasks: [{ role, name, task, access, ... }] }
Chain:    { mode: "direct", chain: [{ role, name, task, access, ... }] }

Every task requires access: "read" or access: "write". Declare write for file, Git, or external-resource changes. Read access is not enforced and is not a sandbox. The worker keeps its Role's tools.

Read requests run parallel tasks up to maxSubagents. Chains run in order, replace literal {previous} with the preceding successful answer, and stop on failure. Any write task makes the whole request serial and reserves checkout admission until all owned workers stop.

Direct writes change Main's checkout immediately, including dirty checkouts, and have no automatic checks or rollback. Preserve unrelated edits. See Direct contract for write scope and checkout-admission rules.

Tasks in write requests must return one JSON completion object:

{"outcome":"succeeded","answer":"Scoped commit completed."}

outcome accepts succeeded, failed, or blocked; answer must be non-empty. Plain text, malformed completion, blocked work, or failure stops later dispatch. Success is the worker's report, not independent validation. Checkout admission depends on proved termination, not the reported outcome.

A write task can declare "paths": ["src/**"] with repo-relative globs. For each task in a write request, the result lists new commits and changed paths, and it flags changed paths outside paths. This is a report only, not enforcement, and it cannot exclude changes from other processes. For a read request, the result warns checkout changed during task; result may be stale when the checkout changed while the task ran. Outside a Git repository, the extension makes no report. See Checkout change reports.

To check a request before a launch, add "dryRun": true. The dry run does the launch checks and shows each task's Role, model, thinking level, access, and dependencies. It starts no worker and opens no tab. It also reserves no checkout and sends no follow-up. A failed check gives the same error as a launch. For the full list of checks, see Dry run.

The launch returns a task ID and first Herdr tab, not the answer. One follow-up delivers results when the workflow finishes. The results show the tokens and cost of each worker and the total cost of the request. Busy Main receives it after its current turn; idle Main starts a turn. Failed partial output stays marked as partial, never success. Worker output carries no user authority.

To continue a finished worker, add "continueFrom": "D7.1" with the same role. This opens a new tab with the saved conversation and a new reference. Continue the newest reference from the original checkout and workspace. For eligibility and stop behavior, see Continue or stop one direct worker.

Review a change

Run /review to review uncommitted changes against HEAD. To review other work, give one target:

Text after the target adds a review focus, for example /review #42 cache invalidation. If the first word is not a target, Main reviews uncommitted changes and uses all text as the focus. Main changes the target to exact local commit IDs. Reviewers can read only local Git. So, for a pull request, Main fetches the head and base from the pull request repository to refs/pi-review/. Main groups changed files by location, starts one read-only reviewer task for each group, and merges the findings.

The verdict is Ship only if each reviewer task succeeded and answered exactly PASS. Otherwise, the verdict is Do not ship, with the findings in priority order. If the checkout changed during a review task, the verdict is also Do not ship, and you must run the review again. Main does not fix findings. If another /review prompt template loads first, Pi keeps that template and reports a name collision.

Isolated workflow

Use isolated mode for checked implementation. An isolated request has one durable ID, one goal, and 1 to 8 text or changeset tasks:

{
  "mode": "isolated",
  "id": "refresh-repair",
  "goal": "Repair token refresh.",
  "tasks": [{
    "id": "repair",
    "kind": "changeset",
    "role": "implementer",
    "modelClass": "balanced",
    "requirements": "Implement the smallest correct repair.",
    "deliverable": "A committed candidate in the owned worktree.",
    "dependsOn": [],
    "contextFrom": [],
    "checks": [{ "command": "pnpm", "args": ["test", "--", "refresh"] }]
  }],
  "finalChecks": [{ "command": "pnpm", "args": ["test", "--", "refresh"] }]
}

dependsOn controls scheduling. contextFrom also schedules dependencies and supplies completed text outputs in order. Do not repeat a task in both fields. Changesets require focused checks; graphs with changesets require final checks. The canonical root package.json must have a test script. The runner adds pnpm test to final checks if absent.

Workers use Main's pinned committed branch, HEAD, and tree, not staged, unstaged, or untracked edits. Branch or HEAD changes block new waves. Candidates must be committed with no tracked or untracked changes. Ignored generated files permit candidacy but prevent automatic cleanup.

Keep the durable ID; Main can work or end its turn without polling. Inspect ready candidates with subagent_status.

• subagent_stage stages exact candidates while siblings run; resolve conflicts in the integration checkout.
• subagent_integrate advance runs dependents on a staged snapshot.
• subagent_integrate validate checks the combined integration tip after the wave settles, with final checks and any final judgment.
• subagent_integrate promote explicitly promotes passing work.

Readiness requires preliminary checks and any task judgment; it does not permit promotion. Checks and judgments bind to exact Git identities. Staging, combined validation, and promotion require unchanged, clean Main at the pinned identity. Changed identities, conflicts, or uncertain outcomes block promotion and preserve evidence. A definitive combined check or review failure permits one committed integration correction, recorded with subagent_integrate correct, and another validation.

Combined validation can reuse a passed preliminary check of a staged candidate. The candidate must have the same tree as the combined tip, and the check must have the identical command and argv. Then the final check does not run again. This usually occurs when you stage one candidate onto unchanged Main. Status shows each reused result and its candidate. Final judgment still runs.

Reuse assumes that checks use only tracked content. Ignored files, for example node_modules, can be different between worktrees.

The extension sends follow-ups when a candidate becomes ready, a worker needs attention, and the wave finishes. A missed follow-up does not authorize replay. Read Isolated contract and Exact integration actions for graph, judgment, revision, refresh, and release details.

Inspect work

Open /subagent to browse direct work on this session branch and isolated requests in the current canonical Git checkout, including other sessions. The menu groups rows under Direct, Isolated, and Orphaned headers. Each isolated row shows the request ID, the status, and a short goal summary. Refresh or a header reloads saved status without recovery or mutation. Invalid state IDs stay preserved with a warning. Direct recovery remains available outside Git or without isolated inventory.

Before the menu opens, and after each Refresh, a Current subagent work report shows which subagents are working. The extension calculates it from local and saved evidence without a model call. Without interactive UI, /subagent sends this report before the request list.

A direct workflow is working only when this Pi process owns it and has a running worker. Direct work with a delivered result shows its outcome under Completed / history and is not in the report. Other recorded-only direct work shows as unverified. An isolated request is working only when its status is active and a live run holds the repository lease. Without a live lease, an active request shows as interrupted; run /subagent recover.

Each row starts with a status symbol: ● active, ✓ completed, ⚠ needs attention, ✗ failed. In the terminal UI, /subagent reports (Roles, details, reviews, and results) show as colored transcript entries. The model does not get these entries. In RPC mode, they show as notifications. Without interactive UI, they show as plain text messages.

Requests whose parent checkout was removed show in the Orphaned · parent checkout removed group from any checkout of the same repository. Every isolated request, including an orphaned request, has Close and delete worktrees (discard work). Select it to review owned resources and confirm deletion. This permanently deletes committed, uncommitted, and ignored content in the listed checkouts. Cancel makes no change.

Select Select multiple… to apply one action to many rows. Select a row to mark it [x] or clear it, or use Select all or Clear, then select Continue. The next menu shows only the actions that apply. Close and delete worktrees (discard work) applies to isolated requests. Close/cancel-and-release ALL owned workers applies to direct workflows that can close. Each request shows its review, then one confirmation covers all of them.

The command reports the number of selected rows that the action skipped.

Only shown resources can be removed; live jobs, uncertain ownership, or other Herdr panes can block removal. Agents and tools cannot trigger this action. See Close and delete isolated worktrees for guards and partial cleanup.

Inspection needs a Herdr pane, the configured scout Role, and the fast route. If it cannot start, the request stays unchanged; Main can use subagent_status to read state. See Inspect and revise active work for inspection and follow-up details.

See Status widgets for reference numbering, token counts, and activity metrics, and Choose a delegation mode for routing guidance.

Config

Package-owned: ~/.pi/agent/config/pi-subagent/config.json. Missing files silently use defaults. No key is required; the extension preserves the file and never rewrites it automatically.

roleDefaults entries precede Role entries; merging removes duplicates before resource resolution. Use it for a provider extension that every child needs. Limits come only from this file. Requests cannot override or replenish them. Durable requests keep recorded policy; a lower current correction limit can tighten recovery. There is no whole-run timeout.

The extension reports each new problem once per session. It reads config at launch, delegate_task, later direct workers, isolated Role launches, /subagent roles, and status inspection.

• Unknown keys warn and are ignored. A likely misspelling, such as maxToken for missing maxTokens, counts as invalid for that key.
• Invalid maxSubagents, maxTurns, maxCorrections, or timeout values warn and use finite defaults. If maximum timeout does not exceed idle timeout, the whole timeout uses defaults.
• Unknown or invalid roleDefaults keys warn; only those keys are ignored, so Roles receive fewer default resources.
• Invalid or misspelled maxTokens blocks delegation. Malformed JSON, invalid UTF-8, files above 64 KiB, and unreadable files also block delegation. The extension does not fall back to unlimited tokens.

/subagent remains available during a block. Correct the file to enable delegation. The next worker or isolated Role launch fails while the block remains; running workers retain their original limits. If the problem existed at session start, also run /reload, because that session took default execution limits.

Roles

Role Markdown files in ~/.pi/agent/config/pi-subagent/ require frontmatter and a Markdown system prompt.

The package ships implementer, reviewer, and scout; same-name user Roles override built-ins. Roles define capabilities, not access or isolation. Unknown frontmatter keys invalidate that file and report its path and key. Other valid Roles load; duplicate names become unavailable. Delegation to an invalid file's claimed Role fails with that file's error. Inspect /subagent roles.

The built-in reviewer answers exactly PASS when it finds no actionable correctness risk. Otherwise, each finding starts with a priority and a confidence (high, medium, or low), for example [P1] confidence: high. Then it gives file and line evidence, the trigger, the impact, and the smallest fix. Each finding blocks approval.

• P0: breaks release or operation on ordinary input.
• P1: wrong behavior under a realistic condition.
• P2: wrong behavior in a narrow edge case with limited impact.

The built-in reviewer and scout include git_read; existing user reviewers and scouts must add it to tools. No additional extension or Bash access is necessary. See Reviewer Git inspection for operations, parameters, limits, and Git requirements.

Children load only declared resources and required adapters. Roles must list their model provider extension. codemode requires both builtin:codemode in extensions and codemode in tools. Missing Skills, tools, MCP servers, Roles, or routes fail before productive work. Main-only delegation/recovery tools and ask_question stay unavailable to children.

Read Role and resource policy for extension exposure, MCP validation, OAuth constraints, and child budgets. Project MCP overrides cannot change a Role's global allowlist or exposure.

API

Role helpers require model routing fields and isProjectTrusted(), plus cwd for configured package resources, not UI methods. See Role launch API for routing and worktree results.

The executor accepts concurrency, turn/token, idle/hard-runtime limits, and abort, output, token, and activity callbacks. Queue time uses no child timeout; resources resolve after admission. See Ephemeral executor API for bounded output, abort results, errors, and accounting.

State and storage

Private durable state lives under config/pi-subagent/state/. Isolated worker sessions use mode 0600 under config/pi-subagent/leases/; worker umask stays unchanged. Reads stop at 16 MiB. Larger sessions require inspection and cannot prove completion.

Sessions are removed only after exact worker-tab cleanup. They can contain prompts and answers: do not share them. State v5 rejects v4 and older files without migration. Preserve old state and recover its work manually.

Limits and recovery

Role extensions and MCP servers are trusted executable code, not a sandbox. Select the smallest resource set and authorize write scope explicitly. Admission coordinates this Main's Pi calls, not other sessions, trusted extension lifecycle code, or external processes. Concurrent edits can make direct reads stale.

For uncertain direct termination, open /subagent, select the exact workflow, and choose Close/cancel-and-release ALL owned workers in this workflow. This stops all owned workers, not only the selected one. Resolve reported blockers and repeat the action. Recorded-only tasks cannot release admission. Restarting Pi does not prove termination. Inspect partial changes before new writes; never blindly repeat commits or delete work.

Unverified tab allocations retain evidence but offer no Close action. Reconcile them manually against Herdr; do not recreate tabs, guess IDs, or restart to bypass admission. See Direct contract.

After coordinator interruption, restart Pi and run /subagent recover in the canonical repository. Use subagent_status for exact evidence; never take over a live productive lease or replay uncertain prompts, merges, or promotion. See Recover after interruption and Recovery and state.

Run /subagent prune for leftovers; merged items are selected first. Removing a checkout deletes its ignored files only after a separate confirmation naming those entries. If you select an item that an unfinished request owns, the command closes and deletes that whole request after its review and confirmation. If you select unowned work with unique commits or changes, a separate confirmation permits its permanent deletion. Uncertain resources, such as locked checkouts or checkouts that other Herdr panes use, cannot be selected. See Prune leftover worktrees before removal.

For aborted requests with retained resources, inspect status, resolve blockers, and repeat subagent_abort to reconcile cleanup without replaying work. Release rejected candidates and superseded generations explicitly. The extension never pushes, opens pull requests, publishes, deploys, or silently falls back to Main. It force-deletes recoverable work only after the user confirms Close and delete worktrees (discard work) in /subagent or a force removal in /subagent prune.