@narumitw/pi-subagents 2.0.6 → 2.1.1

package/docs/async-runtime-protocol.md

@@ -0,0 +1,83 @@
+# Async runtime protocol
+
+This document defines `pi-subagents:completion-requirement:v1` and the current runtime boundary for final-answer-dependent detached work.
+
+## Requirement identity
+
+A caller marks one `subagent_spawn` or `subagent_send` turn with `completionRequirement: "required"`.
+The runtime binds that requirement to the accepted `agentId`, executor-owned `runId`, and monotonically increasing turn generation.
+Agent names and task paths are display and addressing aids and never replace exact run identity.
+Omitting the field or using `background` preserves prior behavior and does not create a final-answer dependency.
+
+## State ownership
+
+`AgentRegistry` owns requirement transitions with the child turn and persisted completion outbox.
+Tool-result `details.agent.completionRequirements` provides fork-sensitive branch evidence.
+Session restoration retains exact requirements found on the active branch and treats sessions without visible subagent state as a possible compacted continuation.
+The successful lifecycle tool result and delivered completion message are the ordinary model-visible requirement handoff.
+When a resume changes a pending run to cancelled and interrupted while its stale handoff remains in model context, `before_agent_start` appends one hidden versioned transition after that handoff.
+This append-only transition also applies when leading summaries retain the stale handoff, prevents duplicate publication on later turns, and participates in fork-sensitive branch reconstruction.
+If leading compaction or branch summaries remove the handoff, the `context` hook restores one canonical hidden `pi-subagent-required-completions` fallback immediately after the summaries.
+The fallback remains at that fixed boundary for the leading-summary epoch, while a later completion or cancellation transition supersedes it at the conversation tail.
+`CompletionDeliveryBroker` owns exact completion visibility acknowledgement and asks the registry to mark the corresponding requirement visible.
+No timer, waiter, or UI object owns requirement truth.
+
+## States
+
+A newly accepted exact run enters `pending`.
+A durably persisted terminal completion moves the exact run to `available` and records its completion ID and terminal child state.
+Observation of that exact completion ID in the intended parent context moves the run to `visible`.
+Interruption, close, restore of a non-running owner, or shutdown moves an unfinished requirement to `cancelled` with an explicit terminal state.
+Duplicate completion delivery and acknowledgement are idempotent.
+A follow-up receives a new run ID and generation and creates a requirement only when that follow-up explicitly requests one.
+The runtime bounds retained requirement records per agent and rejects a sixty-fifth unresolved required run before acceptance so every unresolved exact identity fits in the canonical parent context.
+
+## Parent behavior
+
+Pending and available requirements remain final-answer dependencies.
+A newly established canonical fallback omits requirements already visible at that boundary.
+A fallback retained from an earlier request remains historical prefix context after visibility changes, and the later completion message supplies the superseding state.
+Cancelled requirements are terminal and must be reported rather than silently treated as successful evidence.
+A failed, partial, interrupted, stale, or cancelled child never satisfies mutating acceptance or independent-verification requirements merely because its turn settled.
+
+## Prompt-cache boundary
+
+Provider-visible subagent tool definitions and prompt metadata remain stable within one configured tool-surface epoch.
+A versioned hidden session-guidance message carries the bounded agent catalog, completion delivery, capacity, cwd policy, and consultation resource policy without placing mutable values in leading tool metadata.
+The initial guidance contract is persisted once before the first agent turn when no equivalent retained contract exists.
+A successfully applied live policy change appends a superseding guidance contract without triggering a model turn.
+Compaction restores missing guidance and required-completion fallbacks in deterministic order after leading summaries.
+These rules preserve normalized cache-eligible prefixes across ordinary turns but do not guarantee a provider-reported cache hit.
+
+## Budget termination
+
+Omitted limits use runtime or agent policy and are recorded as runtime-sourced telemetry.
+Explicit timeout, idle, turn, and tool-call limits remain compatible and are recorded as explicit sources.
+A limit stop with non-empty successful bounded finalization becomes a typed `partial` outcome with the exact termination reason.
+Empty finalization, failed finalization, malformed required structured output, and transport failures remain failed or contract-invalid.
+Partial evidence is available to the parent but is not successful verification or mutating acceptance.
+
+## Pi core boundary
+
+The inspected supported Pi runtime emits provider `message_update` events before the TUI, RPC, JSON, and SDK surfaces display them.
+An extension `message_end` handler can replace the finalized same-role message but cannot retract previously displayed deltas.
+Steering is queued after the extension `input` event, direct RPC steering bypasses that event, and tool abort signals do not observe every accepted steer.
+Therefore an extension cannot provide a hard pre-display final-answer barrier or a reliably steer-interruptible join across all supported modes.
+`subagent_await` remains the bounded non-polling compatibility join and accurately states that queued steering is blocked until the tool settles.
+
+A future core implementation would need replay-safe post-enqueue input activity, exact session-owned blocker handles, pre-display buffering or suppression, bounded timeout, and abort, replacement, reload, shutdown, and headless-mode semantics.
+This repository does not modify or publish Pi core packages for this work.
+
+## Codex reference
+
+Codex `wait_agent` uses replay-safe pending activity plus an event-driven watch receiver for mailbox and steering activity.
+Codex completion context uses a typed `FINAL_ANSWER` envelope with explicit task, sender, and payload fields.
+Codex rollout budgets use shared runtime-owned accounting and acknowledge reminders only after context insertion.
+These patterns inform waiting, completion identity, and budget ownership, but Codex also does not provide an absolute pre-display final-answer barrier.
+
+## Compatibility fallback
+
+Older persisted agents without requirement metadata behave as background work.
+Current Pi versions continue using bounded persisted at-least-once completion delivery and optional idle-root auto-resume.
+The package must not claim that prompt guidance, context injection, automatic delivery, or finalized-message replacement is a hard barrier.
+The deprecated synchronous `subagent` tool remains available for unmatched chain, fan-in, panel, workflow, and compatibility callers.

package/docs/implementation-notes/pi-subagents-capability-matrix.md

@@ -0,0 +1,62 @@
+# pi-subagents capability matrix
+
+This matrix records the maintained capability boundaries of `@narumitw/pi-subagents`.
+The package README owns public schemas and usage.
+Source and focused tests are the executable authority.
+
+| Capability | Status and boundary | Evidence |
+| --- | --- | --- |
+| Blocking orchestration | Deprecated `subagent` remains a compatibility tool for single, parallel, chain, fan-in, panel, and explicit dependency workflows; the complete request is preflighted before launch and its schema and execution contract remain supported | `src/execution.ts`, `src/panel-execution.ts`, blocking execution and workflow tests |
+| Detached addressable agents | `subagent_spawn` returns an opaque id and canonical task path without waiting for completion | `src/stateful-registration.ts`, registry and stateful registration tests |
+| Follow-up and retained lifecycle | `subagent_send` starts follow-up work; `subagent_await` blocks for one current turn without interrupting on wait timeout or cancellation; `subagent_manage` supports only interrupt and close; `subagent_mailbox` owns queue-only send and acknowledged read | `src/stateful-tool-params.ts`, registry and lifecycle tests |
+| Metadata-only inspection | `subagent_inspect` is registered in every workflow and never launches children, changes lifecycle state, or reads or acknowledges mailbox content | `src/inspect.ts`, `test/inspect.test.ts` |
+| Synchronous read-only consultation | `subagent_consult` runs one ephemeral child with extensions disabled and only the effective subset of `read`, `grep`, `find`, and `ls` | `src/consult.ts`, `src/consult-policy.ts`, `test/consult.test.ts` |
+| Workflow-dependent tool surface | `all` registers eight tools including supported `subagent_await` and `subagent_consult` plus deprecated `subagent`; `async-only` registers detached lifecycle plus inspection; `blocking-only` registers deprecated `subagent` plus supported consultation and inspection; `disabled` registers inspection only | `src/subagents-extension.ts`, settings UI and registration tests |
+| Transport selection | Stateful execution supports `subprocess`, `in-process`, `rpc`, and `auto`; subprocess remains the compatibility default and selection never falls back after acceptance | `src/create-stateful-transport.ts`, transport tests |
+| Automatic transport | Read-only built-in tools select in-process, write-capable built-ins select RPC, and extension or custom tools select fresh subprocess execution | `src/auto-transport.ts`, automatic transport tests |
+| In-process SDK boundary | In-process children use public session-service and model-resolution APIs, disable child extensions, and reject unsupported tools without widening or fallback | `src/in-process-transport.ts`, in-process transport tests |
+| Persistent RPC transport | One retained agent lazily owns at most one exact-loaded Pi RPC child; `agent_settled` is the completion boundary and accepted work is never replayed automatically | `src/rpc-transport.ts`, [`pi-subagents-rpc-v1.md`](pi-subagents-rpc-v1.md) |
+| Detached completion delivery | `next-turn` is the default non-waking delivery; opt-in `auto-resume` steers completion into active root context without a wake, or requests at most one in-flight synthesis turn when the root is idle and has no pending input; exact completion IDs remain pending until context acknowledgement | `src/completion-delivery.ts`, completion-delivery tests |
+| Deterministic timeout and cleanup | Work, idle, turn, and tool budgets use bounded abort and process or session cleanup; explicit parent interruption never starts timeout finalization | runner, transport, timeout, and cleanup tests |
+| Bounded protocol and output | Model-facing content and safe projections are bounded to 50 KiB or 2,000 lines | `src/protocol.ts`, `src/limits.ts`, rendering and inspection tests |
+| Partial structured outcomes | Blocking, detached, and consultation paths preserve bounded post-launch evidence and usage; structured-v2 keeps claims, artifacts, verification, limitations, and unresolved dependencies | result-contract, runner, consultation, and orchestration tests |
+| Enforced delegation contracts | Optional `pi-subagents:delegation:v2` contracts validate declared capabilities, dependencies, evidence, side-effect policy, and supported enforcement without claiming unsupported path, network, or secret guarantees | `src/delegation-contract.ts`, contract and workflow tests |
+| Recursion guard | `PI_SUBAGENT_DEPTH` and `PI_SUBAGENT_MAX_DEPTH` bound nested delegation | `src/execution.ts`, runtime policy and runner tests |
+| Hierarchical ownership | Parent, root, depth, children, and authenticated task paths are persisted; subtree interrupt and close run child-first | `src/registry.ts`, registry and orchestration tests |
+| Bounded mailbox and peer delivery | Mailboxes support acknowledgement and deduplication; inspection exposes only counts; nested peer delivery uses session-scoped authenticated channels | registry, peer transport, mailbox, and inspection tests |
+| Shared and isolated workspaces | Shared-workspace agents may write concurrently by default; deprecated `allowConcurrentWrites` is a no-op; opt-in clean-Git worktrees provide disposable repository isolation | `src/stateful-registration.ts`, `src/workspace.ts`, workspace tests |
+| Separate active and retained capacity | FIFO active-turn scheduling and retained-agent limits are independent and hierarchy depth and child counts are bounded separately | `src/registry.ts`, capacity and fairness tests |
+| Parent context selection | Context supports none, all, summary, recent N user turns, and selected entry ids; projection is text-only, sanitized, and bounded | `src/context.ts`, context protocol tests |
+| Target trust resolution | Current workspace uses session trust; external targets use the nearest saved `ProjectTrustStore` decision, with a nearer denial winning | `src/cwd-policy.ts`, `test/cwd-policy.test.ts` |
+| Consultation target policy | Consultation defaults to any existing target and removes inherited target and project resources when effective trust is absent | `src/consult.ts`, consultation cwd and trust tests |
+| General delegation target policy | Delegation defaults to trusted targets; blocking and detached requests are preflighted and every transport receives the same resolved trust decision | execution, stateful, cwd-policy, and transport tests |
+| Durable logical history | Versioned private state restores inert; retained transports seed bounded sanitized context and logical history once after explicit follow-up | `src/persistence.ts`, persistence and orchestration tests |
+| Automatic side-effect resume | Restored records never restart work; semantic resource skew requires explicit revalidation before a follow-up | persistence, semantic snapshot, and lifecycle tests |
+| Stable tool schema | Registered tool membership does not change across retained-agent state transitions; workflow changes require reload | registration and settings UI tests |
+| Native transcript switching | Unsupported because Pi exposes no supported child transcript or session switch handle | public SDK boundary review |
+| Approval, sandbox, and header inheritance | Unsupported as a general guarantee and reported explicitly in result policy metadata | result policy and transport tests |
+| Filesystem isolation | Optional disposable worktree only; cwd and trust policies are not OS sandboxes and do not restrict absolute paths, processes, network, or credentials | `src/workspace.ts`, README security boundary |
+| Extension-owned autonomous planning | Removed; topology belongs to the main agent or a caller-authored workflow request | built-in catalog, execution, and registration tests |
+
+## Read-only boundary
+
+`subagent_inspect` is side-effect-free at the extension capability boundary.
+It uses pure settings and metadata snapshots, applies project-trust gates before project discovery, and omits prompts, history, context content, mailbox content, credential-bearing model fields, and unsafe paths.
+
+`subagent_consult` is synchronous and non-retained.
+Missing agent tool configuration selects the read-only default set, an explicit empty list selects no tools, and any explicit list is intersected with the supported read-only built-ins.
+Extensions, sessions, lifecycle tools, shell execution, and file mutation tools are disabled.
+Pre-launch failures throw.
+Once a child starts, bounded partial evidence and nested usage are retained and the finalized Pi tool result is marked as an error when consultation fails.
+
+These are executor and resource-loading guarantees, not filesystem, network, process, or confidentiality sandboxes.
+A consultation can read an accessible absolute path when explicitly asked and calls the configured model over the network.
+
+## Runtime ownership boundary
+
+The logical registry owns ids, hierarchy, capacity, mailboxes, completion delivery, persistence, semantic revalidation, and workspace cleanup.
+Each retained turn owns one transport session or process according to its fixed effective transport.
+Close, expiry, replacement, reload, and shutdown abort work and release transport and disposable-workspace ownership.
+
+Pi core still owns provider execution, active-turn admission, message ordering, retries, compaction, interactive transcript selection, and global scheduling.
+The extension does not claim inherited approval or sandbox policy, provider-header hooks, extension state, or a core-owned child-session tree.

package/docs/implementation-notes/pi-subagents-current-direction.md

@@ -0,0 +1,99 @@
+# pi-subagents current direction
+
+This note is the entry point for current `@narumitw/pi-subagents` planning.
+
+## Current product shape
+
+`pi-subagents` is a delegation runtime, not an automatic planner.
+
+The main agent decides whether to delegate and how to split work.
+
+The built-in catalog is intentionally small:
+
+| Built-in | Purpose | Default tools |
+| --- | --- | --- |
+| `explorer` | Bounded read-only repository exploration with cited paths and evidence. | `read`, `grep`, `find`, `ls` |
+| `worker` | Write-capable parallel implementation, command execution, and fixes. | Pi default tools |
+
+Removed built-ins and tools are not part of the active surface:
+
+- `planner`;
+- `reviewer`;
+- `general`;
+- `general-purpose`; and
+- `subagent_auto`.
+
+## Delegation rules
+
+Use no subagent for simple, latency-sensitive, conversational, tightly coupled, or single-lane implementation work that the main agent can do directly.
+
+Use `explorer` when a bounded read-only search can save main-context space or run independently.
+
+Keep overall planning, immediate critical-path work, integration, final verification, and the final answer in the main agent.
+
+A worker may directly implement a bounded slice with clear ownership when it can run independently beside useful non-overlapping main-agent work.
+
+Use one async `worker` only when the main agent has named that local work to continue immediately and the worker result has a supported delivery and integration path.
+
+If the main agent has no such local work, it should implement directly instead of spawning one worker.
+
+Use two or more workers only for disjoint implementation slices whose parallel progress justifies coordination, and keep integration ownership in the main agent.
+
+A single worker without concurrent main-agent work remains an explicit escape hatch for a user-requested specialist model, tool profile, or isolation boundary rather than the ordinary implementation path.
+
+Use custom user or project agents for specialist review, verification, or shell-capable read-mostly work.
+
+Custom project agents remain subject to existing trust and confirmation behavior.
+
+Review should usually be handled by the main agent plus review skills and deterministic checks.
+
+Use custom verifier agents only when independent child verification is explicitly worth the added cost and coordination.
+
+## Tool-surface direction
+
+`all` remains the compatibility default, while `async-only` remains an optional smaller tool surface.
+
+`async-only` exposes `subagent_spawn`, `subagent_send`, `subagent_manage`, `subagent_mailbox`, and `subagent_inspect`.
+`all` additionally exposes supported `subagent_await` and `subagent_consult` plus deprecated blocking `subagent` for compatibility.
+
+`subagent_spawn` is preferred only when detached execution creates real parallelism rather than moving the main agent's only useful task into a child.
+
+After spawning one worker, the main agent should immediately continue the named non-overlapping work instead of only announcing the spawn, waiting, polling, or ending the turn.
+
+Final-answer-dependent detached work needs a supported synthesis path such as opt-in `auto-resume`; default `next-turn` delivery remains appropriate only when the current response does not depend on the result.
+
+Blocking `subagent` is deprecated for new work but remains available with its existing schema and execution behavior for established callers and explicit requests whose chain, fan-in, panel, or workflow semantics lack a detached replacement.
+
+No removal release or date is set until those compatibility modes have a separately approved replacement or migration.
+
+`subagent_consult` remains a supported synchronous read-only exception.
+
+`subagent_await` remains a supported intentional join after useful overlapping parent work is complete.
+
+The four async lifecycle tools remain split because start, follow-up, lifecycle, and queue operations have distinct contracts.
+`subagent_await` remains separate because waiting blocks the parent, its timeout never interrupts the child, and the async-only workflow must omit it.
+
+Changing the default, removing deprecated `subagent`, or consolidating lifecycle tools needs a separate approved migration decision.
+
+## Active follow-ups
+
+None.
+
+New implementation work should respond to demonstrated user needs rather than extending automatic or adaptive routing speculatively.
+
+## Current reference notes
+
+- Git history for the completed main-agent-led delegation guidance records the accepted delegation rubric and verification evidence.
+- Git history for the completed async-first tool-surface work records the earlier tool-surface decision and implementation evidence.
+- [`pi-subagents-capability-matrix.md`](pi-subagents-capability-matrix.md) records maintained capability, detached lifecycle, transport, trust, and runtime-ownership boundaries.
+- [`pi-subagents-rpc-v1.md`](pi-subagents-rpc-v1.md) records the persistent RPC transport contract.
+
+## Historical evidence
+
+The consolidated [research synthesis](../../../../docs/research/coding-agent-subagents-research.md) records the architecture conclusions available at the research cutoff.
+
+The companion [evidence catalog](../../../../docs/research/coding-agent-subagents-evidence-catalog.md) preserves paper-level results, caveats, and primary sources.
+
+Superseded automation, proactivity, and old runtime notes were removed to keep the active docs small.
+
+Git history remains the record of earlier research drafts and raw search transcripts.

package/docs/implementation-notes/pi-subagents-rpc-v1.md

@@ -0,0 +1,153 @@
+# pi-subagents RPC v1
+
+`pi-subagents:v1` is the extension-owned transport and metadata contract layered over Pi's built-in RPC JSONL protocol.
+
+It does not add commands to Pi RPC or alter Pi command and event payloads.
+
+## Envelope
+
+Extension-owned progress, run inspection, and completion metadata may include these bounded fields:
+
+```json
+{
+  "protocol": "pi-subagents:v1",
+  "agentId": "sa_…",
+  "transport": "rpc",
+  "phase": "starting | ready | accepted | running | finalizing | retrying | compacting | settled | failed | interrupted",
+  "timing": {},
+  "provider": "…",
+  "model": "…",
+  "thinkingLevel": "medium",
+  "usage": {}
+}
+```
+
+Fields are additive and optional within v1.
+
+A breaking lifecycle or envelope change requires another protocol identifier.
+
+Raw prompts, chain-of-thought, credentials, headers, environment values, full stderr, and raw tool arguments never enter the envelope.
+
+## Usage accounting
+
+Pi 0.84.2 RPC `message_update.usage` values are cumulative for the current assistant message.
+
+RPC v1 keeps the latest validated update as one replaceable in-flight snapshot instead of adding successive updates together.
+
+A valid `message_end.message.usage` is authoritative for the finalized assistant message.
+
+When final usage has no valid token or total-cost field, RPC v1 commits the latest valid in-flight snapshot instead.
+
+A new assistant `message_start` commits usage from an interrupted prior attempt before tracking the new cumulative stream.
+
+Timeout finalization commits the interrupted work snapshot before clearing captured output and starting the bounded summary attempt.
+
+Progress and terminal outcomes expose the safe sum of committed usage plus the current in-flight snapshot.
+
+Only non-negative finite values no larger than `Number.MAX_SAFE_INTEGER` enter telemetry, and `totalTokens` is derived from valid components only when no valid reported total exists.
+
+The `turns` field continues to count finalized assistant messages only, so interrupted attempts and tool-result messages do not increment it.
+
+Usage progress contains only normalized token counts, total cost, and finalized-turn count, and never adds raw RPC events, prompts, content, reasoning, credentials, headers, or environment values to the envelope.
+
+## Lifecycle
+
+One retained `agentId` lazily owns at most one RPC child.
+
+The child starts through the exact loaded Pi package with `--mode rpc --no-session --no-extensions`.
+
+A correlated `get_state` response is the readiness handshake.
+
+The task timeout begins only after readiness.
+
+Optional idle, assistant-turn, and tool-call budgets begin with prompt execution and observe only completed assistant messages or tool results as meaningful progress.
+
+The transport subscribes before sending `prompt`.
+
+A successful prompt response means accepted, not completed.
+
+`agent_end` is a low-level run boundary and cannot complete a retained turn.
+
+`agent_settled` is the authoritative completion boundary after retries, compaction, and queued continuations settle.
+
+Abort and timeout send the Pi RPC `abort` command and wait for settlement within a bounded grace period.
+
+After a work, idle, assistant-turn, or tool-call budget stop settles, the transport creates a bounded redacted checkpoint and sends one bounded finalization prompt that requests only a summary of already gathered evidence and explicitly forbids further tool use.
+
+Pi RPC does not currently replace an existing child session's active tool set for one turn, so the finalization deadline and abort path remain authoritative if the model disregards that instruction.
+
+The finalization turn has a separate model-work deadline of at most 45 seconds, followed only by bounded abort and process-cleanup grace, and never replays the timed-out task.
+
+Explicit parent interruption does not start finalization.
+
+A child that does not settle after work or finalization abort is terminated and cannot be reused.
+
+An accepted or ambiguously accepted task is never replayed automatically.
+
+Process exit marks the turn failed or interrupted with bounded partial evidence.
+
+Budget-stopped outcomes keep exit `124` and add a `pi-subagents:termination:v1` report with the stop reason, selected limit, deterministic `pi-subagents:checkpoint:v1`, side-effect warning, and finalization status.
+
+Release, expiry, close, session replacement, reload, and shutdown abort owned work and terminate the process group until captured streams close.
+
+Extension UI requests fail closed in v1.
+
+## Resources and tools
+
+RPC v1 supports Pi built-in tools only.
+
+Child extensions stay disabled to prevent recursive `pi-subagents` loading and duplicate extension side effects.
+
+Custom or extension tools fail before RPC child creation with a subprocess recommendation.
+
+The selected cwd, project-trust decision, role prompt, model, thinking level, context, mailbox input, execution budgets, recursion depth, and output bounds retain their existing owners.
+
+`subagent_spawn.timeoutMs`, `idleTimeoutMs`, `maxTurns`, and `maxToolCalls` are retained as agent defaults, while the same fields on `subagent_send` override only one follow-up turn.
+
+RPC session-file persistence stays disabled because `AgentPersistence` owns sanitized logical recovery records.
+
+A restored record starts no process until an explicit follow-up arrives.
+
+Its first new RPC turn seeds bounded sanitized parent context and logical history exactly once.
+
+## Automatic selection
+
+`stateful.transport: "auto"` selects exactly one transport before child creation.
+
+Read-only built-in tool sets select `in-process` for the lowest startup overhead.
+
+The current built-in `explorer` default uses only `read`, `grep`, `find`, and `ls`, so it remains eligible for this route.
+
+Write-capable built-in tool sets select `rpc` for a persistent separate process.
+
+Extension or custom tools select the existing fresh `subprocess` path.
+
+The selection remains fixed for the retained agent's current runtime lifetime.
+
+A restored inert record is preflighted again on its first explicit follow-up.
+
+No startup or post-acceptance failure triggers automatic fallback.
+
+## Execution defaults
+
+Fast, Balanced, and Deep execution profiles were removed.
+
+The built-in `explorer` defaults to `low` thinking for bounded read-only exploration.
+
+The built-in `worker` inherits model and thinking unless a caller, frontmatter, or per-agent setting selects a value.
+
+Execution defaults do not change tools, transport, completion delivery, parent context, or explicit tool-call limits.
+
+## Measurement
+
+Run `just benchmark-subagents` for serial offline startup and retained state-command measurements.
+
+The benchmark makes no provider request and therefore measures transport overhead rather than model quality or latency.
+
+A provider-backed smoke is optional and must stop after one clear external quota, credential, or entitlement failure.
+
+A seven-sample isolated-agent run on 2026-08-09 recorded 27.728 ms median deterministic fresh subprocess turn overhead with 0.782 ms MAD, 0.073 ms first retained RPC turn with 0.006 ms MAD, 0.037 ms retained RPC follow-up with 0.004 ms MAD, 445.631 ms real Pi RPC readiness with 9.765 ms MAD, 0.893 ms retained real Pi RPC `get_state` with 0.036 ms MAD, 3.759 ms in-process session creation with 0.198 ms MAD, and 0.001 ms retained in-process state access with 0.000 ms MAD.
+
+The deterministic turn measurements use a fake Pi while the readiness and SDK measurements use an isolated real Pi installation without credentials.
+
+The measurement supports retained transports as startup-overhead improvements without claiming provider-turn latency or quality.

package/docs/pi-subagents-diagrams.md

@@ -0,0 +1,183 @@
+# pi-subagents Architecture Diagrams
+
+These diagrams describe the main `pi-subagents` components, detached-agent lifecycle, transport selection, and verified workflow.
+
+## Overall architecture
+
+```mermaid
+flowchart TB
+    Root["Main Pi Agent<br/>Planning, integration, verification, and final answer"]
+    Extension["pi-subagents Extension"]
+    Settings["User Settings<br/>pi-subagents.json"]
+    Catalog["Agent Catalog<br/>built-in / user / project"]
+    UI["/subagents Manager<br/>pi-tui-kit"]
+
+    Root --> Extension
+    Settings --> Extension
+    Catalog --> Extension
+    UI <--> Extension
+
+    subgraph Surfaces["Tool Surfaces"]
+        Blocking["subagent<br/>Blocking workflows"]
+        Consult["subagent_consult<br/>Synchronous read-only consultation"]
+        Stateful["Detached lifecycle<br/>spawn / send / manage / mailbox"]
+        Inspect["subagent_inspect<br/>Read-only diagnostics"]
+    end
+
+    Extension --> Blocking
+    Extension --> Consult
+    Extension --> Stateful
+    Extension --> Inspect
+
+    Blocking --> BlockingExecution["Blocking Execution<br/>single / parallel / chain / workflow / panel"]
+    Consult --> ConsultPolicy["Read-only tool intersection<br/>read / grep / find / ls"]
+    Stateful --> Registry["Agent Registry<br/>queue / generations / hierarchy"]
+    Inspect --> Snapshots["Safe projections<br/>runs / workflows / models / status"]
+
+    Registry --> Persistence["Persistent State and Completion Outbox"]
+    Registry --> TransportSelector["Transport Selector"]
+    BlockingExecution --> Runner["Subprocess Runner"]
+    ConsultPolicy --> Runner
+
+    TransportSelector --> InProcess["In-process<br/>Low startup overhead"]
+    TransportSelector --> RPC["Retained RPC process<br/>Process isolation and retained history"]
+    TransportSelector --> Subprocess["Fresh subprocess<br/>Custom-tool compatibility"]
+
+    Registry --> Delivery["Completion Routing"]
+    Delivery --> Root
+```
+
+## Detached-agent execution and completion delivery
+
+```mermaid
+sequenceDiagram
+    participant R as Root Agent
+    participant E as Extension
+    participant P as Policy / Preflight
+    participant G as Agent Registry
+    participant T as Transport
+    participant S as Persistent State
+    participant D as Completion Broker
+
+    R->>E: subagent_spawn(task, contract, budgets)
+    E->>P: Check cwd, trust, agent scope, and capacity
+    P-->>E: Approved execution plan
+    E->>G: Create agent, generation, and runId
+    G->>S: Persist starting / queued state
+    E-->>R: Immediately return agentId and taskPath
+
+    Note over R: Root continues non-overlapping local work
+
+    G->>T: runTurn() when capacity is available
+    T-->>G: Bounded progress / telemetry
+    T-->>G: Terminal outcome
+
+    G->>G: Classify completed / failed / blocked / interrupted
+    G->>G: Create completionId and outbox record
+    G->>S: Persist terminal state and completion first
+    S-->>G: Durable
+
+    G->>D: Route to the direct parent or nearest live ancestor
+
+    alt next-turn
+        D-->>R: Steer without waking an idle root
+    else auto-resume
+        D-->>R: Trigger a synthesis turn after the root settles
+    end
+
+    R->>E: subagent_send(agentId, follow-up)
+    E->>G: Start a new generation while retaining agent history
+    G->>T: Execute the follow-up
+
+    R->>E: subagent_manage(close)
+    E->>G: Release descendants child-first
+    G->>T: Shutdown / release
+    G->>S: Update or remove retained state
+```
+
+The system persists each completion before notifying its parent so that a process interruption does not permanently lose the result.
+
+## Automatic transport selection
+
+```mermaid
+flowchart TD
+    Start["Create a detached agent"]
+    Explicit{"Was transport explicitly selected?"}
+    UseExplicit["Use the selected transport"]
+    BuiltIn{"Are all effective tools<br/>Pi built-in tools?"}
+    ReadOnly{"Is the tool set read-only?"}
+    InProcess["in-process<br/>Retained SDK session"]
+    RPC["rpc<br/>Retained independent Pi process"]
+    Subprocess["subprocess<br/>Fresh process for each turn"]
+    Run["Create the child and accept the prompt"]
+    Failure["Startup or execution failure<br/>Report failure without switching transport"]
+    Note["After a child is created or may have accepted work,<br/>automatic fallback is forbidden to prevent duplicate side effects"]
+
+    Start --> Explicit
+    Explicit -- "Yes" --> UseExplicit
+    Explicit -- "No, use auto" --> BuiltIn
+
+    BuiltIn -- "No, includes extension/custom tools" --> Subprocess
+    BuiltIn -- "Yes" --> ReadOnly
+
+    ReadOnly -- "Yes" --> InProcess
+    ReadOnly -- "No, includes bash/edit/write" --> RPC
+
+    UseExplicit --> Run
+    InProcess --> Run
+    RPC --> Run
+    Subprocess --> Run
+    Run --> Failure
+    Failure -.-> Note
+```
+
+Read-only classification is based on effective tool permissions rather than promises written in the task prompt.
+
+## Verified workflow and acceptance barrier
+
+```mermaid
+flowchart TD
+    Request["Caller-authored workflow"]
+    Validate["Validate DAG, contracts, dependencies, and budgets"]
+    Preflight["Preflight every cwd, agent, scope, and authority"]
+    Ledger["Create the WorkItem Ledger"]
+    Scheduler["Adaptive Scheduler<br/>dependency / capacity / budget / conflict"]
+    Worker["Execute Worker"]
+    Result["Parse structured-v2<br/>Record artifacts and tree identity"]
+    NeedsVerify{"Is independent verification required?"}
+    OrdinaryDone["Complete the ordinary workflow item"]
+
+    Checks["Run executor-owned checks<br/>in a disposable worktree"]
+    ChecksPass{"Did every check pass?"}
+    Verifier["Independent read-only Verifier<br/>Different agent and generation"]
+    Receipt["Create verification receipt<br/>Bind patch, tree, plan, and evidence"]
+    Decision{"Verifier decision"}
+
+    Accept["Acceptance Controller<br/>Mark accepted"]
+    Rework{"Is rework capacity available?"}
+    Rotate["Revoke old grants<br/>Rotate worker/verifier generations"]
+    Reject["rejected / non-success"]
+    Finish["Workflow terminal result"]
+
+    Request --> Validate --> Preflight --> Ledger --> Scheduler
+    Scheduler --> Worker --> Result --> NeedsVerify
+
+    NeedsVerify -- "No" --> OrdinaryDone --> Finish
+    NeedsVerify -- "Yes" --> Checks
+    Checks --> ChecksPass
+    ChecksPass -- "No" --> Reject
+    ChecksPass -- "Yes" --> Verifier
+    Verifier --> Receipt --> Decision
+
+    Decision -- "accepted" --> Accept --> Finish
+    Decision -- "rework" --> Rework
+    Decision -- "rejected" --> Reject
+
+    Rework -- "Yes, at most once" --> Rotate --> Scheduler
+    Rework -- "No" --> Reject
+    Reject --> Finish
+```
+
+A worker's own claim that verification passed cannot move acceptance from `pending` to `accepted`.
+
+Only executor-owned checks, an independent verifier, and the acceptance controller can complete acceptance.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "2.0.6",
+	"version": "2.1.1",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",
@@ -16,6 +16,7 @@
 	"files": [
 		"src",
 		"dist",
+		"docs",
 		"README.md",
 		"LICENSE"
 	],
@@ -42,17 +43,17 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "2.5.9",
-		"@earendil-works/pi-agent-core": "0.84.2",
-		"@earendil-works/pi-ai": "0.84.2",
-		"@earendil-works/pi-coding-agent": "0.84.2",
-		"@earendil-works/pi-tui": "0.84.2",
+		"@biomejs/biome": "2.5.10",
+		"@earendil-works/pi-agent-core": "0.84.3",
+		"@earendil-works/pi-ai": "0.84.3",
+		"@earendil-works/pi-coding-agent": "0.84.3",
+		"@earendil-works/pi-tui": "0.84.3",
 		"esbuild": "0.28.2",
-		"typebox": "1.3.16",
+		"typebox": "1.3.18",
 		"typescript": "7.0.2"
 	},
 	"dependencies": {
-		"@narumitw/pi-tui-kit": "^0.57.0",
+		"@narumitw/pi-tui-kit": "^0.58.0",
 		"proper-lockfile": "^4.1.2"
 	},
 	"repository": {

package/src/agents/types.ts

@@ -3,6 +3,7 @@
  */
 
 import type { AgentCapabilityManifest } from "../capabilities.js";
+import type { SubagentUsageRecordingSettings } from "../usage-recording-config.js";
 
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
@@ -95,4 +96,5 @@ export interface SubagentSettings {
 	stateful?: SubagentRuntimeSettings;
 	consult?: SubagentConsultSettings;
 	cwdPolicy?: SubagentCwdPolicySettings;
+	usageRecording?: SubagentUsageRecordingSettings;
 }