@narumitw/pi-subagents 0.25.0 → 0.26.0

package/README.md

@@ -4,22 +4,22 @@
 
 `@narumitw/pi-subagents` is a native [Pi coding agent](https://pi.dev) extension for delegating work to specialized agents. The batch `subagent` tool keeps isolated Pi subprocesses, while addressable lifecycle tools can run reusable agents either as subprocess-backed logical sessions or as public-SDK in-process child sessions.
 
-Use it to split independent research, planning, implementation, and review work across focused workers. Background delegation is intended for sidecar work the main agent can overlap with useful local work—not for handing off one critical-path task and waiting.
+Use it to split independent research, planning, implementation, and review work across focused workers. Under the default next-turn delivery policy, background delegation is for work the current response does not depend on. Opt-in auto-resume also supports final-answer-dependent background work by requesting a synthesis turn after completion.
 
 ## ✨ Features
 
 - Registers a `subagent` tool for single-agent, parallel, fan-in, and chained delegation.
 - Keeps batch workers isolated in `pi --mode json -p --no-session` subprocesses.
-- Registers detached stateful lifecycle tools by default; spawn returns immediately and completion is delivered asynchronously without starting a new root turn.
+- Registers detached stateful lifecycle tools by default; completion can stay queued for the next turn or opt into an idle root synthesis turn.
 - Supports an opt-in public-SDK `in-process` stateful transport with one reusable child `AgentSession` per `agentId`.
 - Supports built-in `scout`, `planner`, `reviewer`, and `worker` agents.
 - Loads custom user agents from `~/.pi/agent/agents/*.md`.
 - Optionally loads project agents from `.pi/agents/*.md` with confirmation.
-- Provides `/subagents:config` to persist per-agent tool allow-lists.
-- Supports per-task `cwd`, hard subprocess `timeoutMs`, `thinkingLevel`, abort propagation, and streaming progress.
+- Provides a current-session-first `/subagents` manager, direct `settings|status|help` routes, and compatibility aliases for agent tools and retained agents.
+- Supports per-task `cwd`, hard subprocess `timeoutMs`, task-selected `thinkingLevel`, abort propagation, and streaming progress.
 - Bounds JSON lines, captured messages, stderr, final output, chain substitution, and fan-in context.
 - Enforces a recursion-depth guard and deterministic process-group termination.
-- Provides addressable stateful agents with follow-up, wait, list, interrupt, close, context selection, and persistence.
+- Provides addressable stateful agents with follow-up, mailbox, list, interrupt, close, context selection, and persistence.
 - Publishes transient runtime status through Pi's generic extension status API while subagents are running.
 - Returns complete bounded worker output in tool details and a concise result for the main agent.
 
@@ -43,17 +43,19 @@ pi -e ./extensions/pi-subagents
 
 ## 🛠️ Pi tool
 
-`pi-subagents` registers a primary batch tool plus the stateful lifecycle tools documented below:
+`pi-subagents` always registers the primary batch tool and registers the stateful lifecycle tools unless `stateful.enabled` is `false`:
 
-- `subagent` — delegate blocking single, parallel, fan-in, or chained batch work.
-- `subagent_spawn` and related lifecycle tools — start reusable detached work, return immediately, and receive bounded completion messages automatically.
+- `subagent` — delegate blocking single, parallel, fan-in, or chained batch work. The main agent cannot process queued steering until the call returns.
+- `subagent_spawn` and related lifecycle tools — when enabled, start reusable detached work, return immediately, and receive bounded completion messages automatically.
 
 Choose the API by lifecycle:
 
 | Need | Use |
 | --- | --- |
-| One or more independent, one-shot results needed before the root responds | One blocking `subagent` call (`tasks` for parallel work) |
-| Reusable history, follow-ups, mailboxes, or work that overlaps useful root work | `subagent_spawn` and lifecycle tools |
+| A delegated result is required before the root's next action under default next-turn delivery | One blocking `subagent` call (`tasks` for synchronous parallel work) |
+| Broad research/review the current response does not depend on | Prefer one `subagent_spawn` covering related branches, when lifecycle tools are enabled |
+| Final-answer-dependent broad work with `completionDelivery: "auto-resume"` | Prefer one `subagent_spawn`; completion requests a synthesis turn |
+| Reusable history, follow-ups, or mailboxes | `subagent_spawn` and lifecycle tools, when enabled |
 | One simple or critical-path action the root can perform directly | No subagent |
 
 Execution modes:
@@ -67,31 +69,35 @@ Common controls:
 
 - `cwd` — run a job from a different working directory.
 - `timeoutMs` — set a hard subprocess timeout.
-- `thinkingLevel` — request `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` thinking for the spawned Pi process.
+- `thinkingLevel` — request `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` thinking for the spawned Pi process or in-process child.
+
+For `subagent_spawn`, the root agent selects the lowest thinking level sufficient for the delegated task. This is a tool-argument decision made from the task already in context; `pi-subagents` does not run a string heuristic or an extra classifier model call.
 
 ## 🧭 Proactive use
 
-The `subagent` tool advertises concise prompt guidance so the main Pi agent can decide
-whether to spawn 0, 1, or multiple subagents without an explicit user-specified count.
+The always-available `subagent` tool advertises only blocking guidance. When stateful lifecycle tools
+are registered, `subagent_spawn` adds detached guidance for the active completion-delivery policy.
+Changing the policy through `/subagents settings` refreshes that guidance immediately.
 
 Count-selection guidance:
 
 - Use **no subagent** for simple answers, quick targeted edits, latency-sensitive one-step work, or
-  tasks that need frequent user back-and-forth.
-- A single `subagent` call is blocking. Use one only when context isolation, high-volume output
-  isolation, or independent review is worth waiting for; otherwise the main agent should do the work.
-- Do not delegate ordinary critical-path work merely to wait for it. Use detached `subagent_spawn`
-  only for a concrete bounded subtask that can run independently alongside useful main-agent work
-  and when parallel work, bounded context/output, independent review, a distinct model/tool profile,
-  or workspace isolation provides concrete value. After spawning, do useful non-overlapping work
-  immediately. Call `subagent_wait` sparingly, only when the immediate next critical-path step needs
-  the result and is blocked until it arrives; do not wait repeatedly by reflex.
-- Prefer **2–4 parallel read-only subagents** when a broad task naturally splits into independent
-  branches that can each return a concise summary.
-- Exceed 4 tasks only when the branches are clearly distinct and worth the extra cost, while staying
-  within the existing hard max of 8 parallel tasks.
-- Do not parallelize implementation that may edit the same files or shared state; serialize
-  write-heavy work instead.
+  critical-path work the main agent can perform directly.
+- `subagent` is deliberately blocking: while it runs, the main agent cannot answer queued steering.
+  Use it when delegated outputs are required before the next root action and waiting is intentional.
+- With default `completionDelivery: "next-turn"`, prefer **one detached `subagent_spawn`** for broad
+  research or review only when the current response does not depend on its result. Keep
+  final-answer-dependent delegated work on the blocking path because an idle root is not awakened.
+- With `completionDelivery: "auto-resume"`, prefer one detached `subagent_spawn` for broad related
+  research or review even when the final answer depends on it; completion requests a later synthesis
+  turn. Do not choose blocking parallel fan-out merely to keep delegation in one turn.
+- Use detached `subagent_spawn` only when lifecycle tools are enabled and a bounded independent task
+  has a concrete isolation or specialization benefit. After spawning, do useful non-overlapping work
+  immediately. Do not poll lifecycle tools for progress or duplicate the delegated work.
+- Add another detached agent only for truly independent work with safe workspace concurrency. If
+  synchronous parallel or fan-in output is genuinely required, keep blocking `subagent` tasks
+  independent, stay within the hard max of 8, and do not parallelize implementation that may edit
+  the same files or shared state.
 - Do not use project-local agents unless the user explicitly opts into them with
   `agentScope: "project"` or `"both"`; keep confirmation enabled for untrusted repositories.
 
@@ -103,16 +109,17 @@ No subagent for a known-file edit:
 Rename one symbol in src/foo.ts.
 ```
 
-One subagent for an independent review:
+One detached agent for a broad asynchronous review that the current response does not require, or when auto-resume is enabled (call `subagent_spawn`):
 
 ```json
 {
   "agent": "reviewer",
-  "task": "Review the current changes for release blockers. Do not edit files. Report PASS/FAIL/PARTIAL with evidence."
+  "task": "Review source, tests, and integration risks for the current changes. Do not edit files. Report PASS/FAIL/PARTIAL with evidence."
 }
 ```
 
-Two to four parallel subagents for broad independent reconnaissance:
+A blocking fan-out is reserved for output that must be synthesized before the root continues (call
+`subagent`):
 
 ```json
 {
@@ -124,10 +131,6 @@ Two to four parallel subagents for broad independent reconnaissance:
     {
       "agent": "scout",
       "task": "Research auth-related tests. Report coverage gaps. Do not edit files."
-    },
-    {
-      "agent": "scout",
-      "task": "Research API entry points that depend on auth. Report integration risks. Do not edit files."
     }
   ],
   "aggregator": {
@@ -137,7 +140,11 @@ Two to four parallel subagents for broad independent reconnaissance:
 }
 ```
 
-## 🚀 Examples
+## 🚀 Blocking batch examples
+
+Every example in this section calls `subagent` and keeps the main agent unavailable until the batch
+finishes. Use `subagent_spawn` instead when the work can complete asynchronously and its configured
+completion policy supports when synthesis is needed.
 
 Run one read-only reconnaissance agent:
 
@@ -202,22 +209,30 @@ Run a chain where each step receives the previous output:
 
 ## 🔁 Stateful agents
 
-Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects one bounded `pi-subagent-completion` message per settled turn. The message uses `deliverAs: "steer"` with `triggerTurn: false`, so an active root turn can consume it naturally.
+Stateful lifecycle tools are available by default. `subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId`, and later injects a bounded `pi-subagent-completion` custom message. Completions that settle in the same dispatch window are batched, and the broker allows at most one in-flight root wake until that parent turn starts.
+
+Detached work follows a non-polling policy. With default `next-turn` delivery, prefer one bounded `subagent_spawn` for related asynchronous research or review only when the current response does not depend on its result; if it does, use blocking `subagent`. With opt-in `auto-resume`, detached broad work may be final-answer-dependent because completion requests a synthesis turn after the root settles. In either mode, do useful non-overlapping main-agent work immediately, do not poll `subagent_list` or `subagent_messages`, and do not duplicate delegated work. Add another detached agent only for truly independent work with safe workspace concurrency. Detached lifecycle work intentionally has no `subagent_wait` tool.
 
-Detached work follows a critical-path policy: spawn only a concrete bounded subtask that can run independently alongside useful main-agent work, then do that non-overlapping work immediately. Use `subagent_wait` sparingly and only when the immediate next critical-path step requires the result and is blocked until it arrives. The extension does not start an autonomous recovery turn merely because delegated work remains live or completes. If the root turn has already ended, completion stays queued for the next turn instead of waking the root.
+A detached agent additionally needs a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
 
-A single detached agent additionally needs a concrete isolation or specialization benefit such as independent review, bounded context/output, a distinct model/tool profile, or workspace isolation. Simple work that the main agent can perform directly should not be delegated.
+`stateful.completionDelivery` controls settled completion delivery:
 
-When `subagent_wait` starts while a turn is running, that wait consumes the turn's completion: the terminal output is returned by the tool and is not also injected as a duplicate asynchronous completion. Multiple active waiters may all receive the terminal result. A timed-out or aborted wait does not consume it, so later settlement still delivers the normal asynchronous completion. If a turn has already settled and queued its completion before a wait starts, the queued message cannot be retracted safely.
+- `"next-turn"` (default) preserves the previous behavior: use `deliverAs: "steer"` with `triggerTurn: false`. An active root can consume completion naturally; an idle root is not awakened.
+- `"auto-resume"` holds completion while the root is active, then requests one synthesis turn after the parent settles when no user or extension messages are already pending. Simultaneous completions share that turn, active work is not interrupted, and pending input suppresses the autonomous wake.
+
+Auto-resume is best-effort because Pi's custom-message API is fire-and-forget. Session-generation checks, shutdown cleanup, batching, and the in-flight wake guard prevent stale or duplicate scheduling pressure, but they do not make completion delivery durable across process exit.
 
 The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history. Set `transport` to `in-process` to retain one public Pi SDK `AgentSession` per stateful `agentId`, avoiding repeated process startup while preserving native child history in memory.
 
-Configure the runtime in `~/.pi/agent/pi-subagents.json`, then reload Pi:
+Run `/subagents` in TUI mode to open the primary manager. It separates current-session lifecycle state, transport, completion delivery, and active/retained counts from user settings that persist across sessions. Its actions open completion settings, per-agent tool settings, current-session agent inspection/clear, status, and help. Escape returns from a nested screen to a newly refreshed manager and then closes it.
+
+The direct routes remain predictable: `/subagents settings` changes user completion delivery and applies it immediately, including refreshing the model-facing spawn guidance; `/subagents status` reports current-session runtime values separately from the configured value, source, and path; `/subagents help` summarizes commands and compatibility routes. In RPC mode, bare `/subagents` emits the same bounded status through Pi's notification protocol instead of opening a custom TUI. JSON and print modes do not emit ad hoc command output. Manual edits use `~/.pi/agent/pi-subagents.json` and take effect after reloading Pi:
 
 ```json
 {
   "stateful": {
     "transport": "in-process",
+    "completionDelivery": "auto-resume",
     "maxAgents": 16,
     "maxActiveTurns": 4,
     "maxDepth": 3,
@@ -231,20 +246,31 @@ Configure the runtime in `~/.pi/agent/pi-subagents.json`, then reload Pi:
 }
 ```
 
-Set `"enabled": false` to remove all stateful lifecycle tools. Otherwise, the extension registers:
+The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Set `"enabled": false` to remove all stateful lifecycle tools. Otherwise, the extension registers:
 
 | Tool | Purpose |
 | --- | --- |
-| `subagent_spawn` | Start detached work, return an opaque `agentId` immediately, and deliver completion asynchronously. |
+| `subagent_spawn` | Start detached work with an optional task-selected thinking level, return an opaque `agentId` immediately, and deliver completion asynchronously. |
 | `subagent_send` | Send follow-up work to a reusable agent; shared-workspace write conflicts are guarded unless explicitly overridden. |
 | `subagent_message` | Queue a bounded mailbox message without starting a turn; sender IDs must be `root` or an agent in the same tree. |
 | `subagent_messages` | Read and optionally acknowledge unread mailbox messages. |
-| `subagent_wait` | Wait sparingly when the immediate next critical-path step is blocked on a result; timeout does not terminate the agent, and parent abort/user steering cancels only the wait. Already-terminal agents return immediately. |
 | `subagent_list` | List retained agents and lifecycle states. |
 | `subagent_interrupt` | Abort the current turn while retaining its identity and history. |
 | `subagent_close` | Abort if necessary, close the agent, and remove it from retained persistence. |
 
-Use `/subagents:agents list` to inspect the indented agent tree, lifecycle state, unread count, and available actions. Use `/subagents:agents clear` to close and delete all retained agents for the session. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
+Use the **Current-session agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents. `/subagents:agents list|clear` remains the compatibility command for the same current-session operations. Active turns are FIFO-limited by `maxActiveTurns`; excess retained work remains in `starting` state until a slot is available. `maxAgents` separately bounds running, queued, and idle records. `parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
+
+A spawn can request a thinking level explicitly:
+
+```json
+{
+  "agent": "reviewer",
+  "task": "Analyze the cross-package concurrency failure and identify the safest fix",
+  "thinkingLevel": "high"
+}
+```
+
+The requested level is stored with the stateful agent and remains in effect for all follow-ups and after persisted restore. `subagent_send` does not provide a per-turn thinking override; create a new agent when a later task needs a different level.
 
 `subagent_spawn.context` accepts:
 
@@ -269,7 +295,7 @@ Stateful execution uses a transport boundary:
 
 No private Pi imports, runtime casts, or `ExtensionAPI` monkey-patching are used. Approval policy, sandbox profile, provider-header hooks, extension state, global scheduling, and parent/child transcript switching are not inherited or provided by the in-process transport.
 
-Write-capable agents share the workspace by default. Concurrent write-capable starts in the same cwd are rejected unless `allowConcurrentWrites` is explicitly set. Classification is intentionally conservative: an agent with `bash`, `write`, or `edit` is write-capable even when its task prompt says “read only,” because prompt wording is not a filesystem sandbox. For independent one-shot work, use batch parallel mode. Otherwise wait for or close the active agent, explicitly accept safe overlap with `allowConcurrentWrites`, or use an isolated worktree when repository isolation is actually needed.
+Write-capable agents share the workspace by default. Concurrent write-capable starts in the same cwd are rejected unless `allowConcurrentWrites` is explicitly set. Classification is intentionally conservative: an agent with `bash`, `write`, or `edit` is write-capable even when its task prompt says “read only,” because prompt wording is not a filesystem sandbox. Prefer one detached agent when asynchronous work can be combined. If concurrent work is genuinely required, use the blocking batch only when synchronous outputs justify making the root unavailable, explicitly accept safe detached overlap with `allowConcurrentWrites`, or use isolated worktrees when repository isolation is needed.
 
 Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree; this requires a clean repository and the worktree is removed on close or session shutdown. Isolated worktree agents are intentionally not restored after shutdown.
 
@@ -284,7 +310,7 @@ Existing `subagent` requests remain unchanged:
 | Parallel | Input order, with at most four active children. | Collects all task results; partial worker failure is reported in summaries but does not discard successful results. |
 | Parallel + aggregator | Source input order, then aggregator. | The aggregator runs with both successful outputs and failure descriptions; aggregator failure marks the tool result as an error. |
 
-Timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms. Thinking precedence remains: task/step/aggregator → call → agent setting → child default. Project-agent resolution and confirmation behavior is unchanged.
+Timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms. Blocking thinking precedence remains: task/step/aggregator → call → agent setting → child default. Stateful spawn thinking precedence is: `subagent_spawn.thinkingLevel` → agent setting → transport fallback. Project-agent resolution and confirmation behavior is unchanged.
 
 ## 🤖 Built-in agents
 
@@ -304,8 +330,7 @@ Built-in agents inherit the active/default Pi model instead of forcing a provide
 
 ## ⚙️ Configure agent tools
 
-Run `/subagents:config` in an interactive Pi session to edit the tools each subagent may use.
-The command stores settings in `~/.pi/agent/pi-subagents.json`.
+Open `/subagents` and choose **Agent tool settings** in an interactive Pi session to edit the tools each subagent may use. `/subagents:config` remains a documented compatibility route to the same screen. These are user settings stored in `~/.pi/agent/pi-subagents.json` and affect future sessions.
 
 Compatibility: a valid legacy `pi-subagents-config.json` is migrated automatically to `pi-subagents.json`. If both files exist, the new filename takes precedence.
 
@@ -385,9 +410,24 @@ Each subprocess has a hard timeout to avoid runaway workers.
 - Set `timeoutMs` on a task, chain step, or aggregator to override it locally.
 - If omitted, the default is `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when unset.
 
-Set `thinkingLevel` to pass Pi's `--thinking <level>` to a subprocess. Supported values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
+Set `thinkingLevel` to request one of Pi's supported levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. Blocking subprocess calls pass the resolved value through `--thinking <level>`.
+
+For `subagent_spawn`, the root agent should choose the lowest sufficient level:
+
+| Level | Appropriate delegated work |
+| --- | --- |
+| `off` / `minimal` | Extraction, formatting, or mechanical work requiring almost no reasoning. |
+| `low` | Straightforward, bounded tasks with direct steps. |
+| `medium` | Ordinary multi-step research or implementation. |
+| `high` | Complex debugging, design, review, or cross-file analysis. |
+| `xhigh` | Highly ambiguous, cross-system, or high-risk analysis. |
+| `max` | Exceptional hardest tasks where quality clearly outweighs latency and cost. |
+
+Blocking thinking precedence is: task/chain step/aggregator `thinkingLevel` → top-level `thinkingLevel` → agent default from config or frontmatter → Pi subprocess default.
+
+Stateful spawn precedence is: `subagent_spawn.thinkingLevel` → agent default from config or frontmatter → transport fallback. The subprocess transport then uses spawned Pi model/default resolution. The in-process transport uses a configured model thinking suffix and then the parent thinking snapshot captured when the child is created. An explicit spawn value is retained for the agent lifecycle and wins over all of those fallbacks.
 
-Thinking-level precedence is: task/chain step/aggregator `thinkingLevel` → top-level `thinkingLevel` → agent default from config or frontmatter → Pi subprocess default. Omit `thinkingLevel` to preserve existing behavior. Pi still owns model capability clamping, so unsupported thinking levels are handled by the spawned Pi process.
+Omit `thinkingLevel` to preserve existing behavior. Reported stateful details show the requested level, not a guarantee of the provider's effective value. Pi still owns model capability clamping; `pi-subagents` does not duplicate capability detection.
 
 On timeout, the extension sends process-group `SIGTERM`, escalates to `SIGKILL` after a five-second grace period if the process has not actually closed, and returns partial bounded messages or stderr collected so far. Parent abort uses the same cleanup path and preserves a structured result.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.25.0",
+	"version": "0.26.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents.ts

@@ -47,9 +47,12 @@ export interface SubagentAgentConfig {
 
 export type SubagentTransportKind = "subprocess" | "in-process";
 
+export type CompletionDelivery = "next-turn" | "auto-resume";
+
 export interface SubagentRuntimeSettings {
 	enabled?: boolean;
 	transport?: SubagentTransportKind;
+	completionDelivery?: CompletionDelivery;
 	maxAgents?: number;
 	maxActiveTurns?: number;
 	maxDepth?: number;