@narumitw/pi-subagents 0.49.3 → 0.51.0

package/README.md

@@ -12,17 +12,25 @@ Use it to split independent research, planning, implementation, and review work
 - Adds `subagent_inspect` for bounded metadata without child launch, mailbox-content access, acknowledgement, or mutation.
 - Adds `subagent_consult` for one synchronous ephemeral child constrained to built-in `read`, `grep`, `find`, and `ls` tools (or a narrower agent allow-list).
 - Keeps batch workers isolated in `pi --mode json -p --no-session` subprocesses.
+- Lets users set a blocking parallel call's maximum worker count from 1 through 64 while keeping four-at-a-time execution.
 - 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 an opt-in persistent `rpc` transport with one isolated Pi RPC process per active retained agent and `pi-subagents:v1` lifecycle metadata.
+- Supports deterministic opt-in `auto` routing: read-only built-ins use in-process, write-capable built-ins use RPC, and custom tools use the compatibility subprocess path.
 - 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 a current-session-first `/subagents` manager, direct `settings|status|help` routes, and compatibility aliases for agent tools and retained agents.
-- Supports trust-aware per-task `cwd` policies, hard subprocess `timeoutMs`, task-selected `thinkingLevel`, abort propagation, and streaming progress.
+- Supports trust-aware per-task `cwd` policies, task-selected work, workflow, idle, turn, and tool-call budgets, deterministic timeout checkpoints, bounded abort-then-summary recovery, progress telemetry, and explicit Fast, Balanced, or Deep thinking profiles.
 - Renders all seven tools with Pi-native compact/expanded transcript rows; long-running blocking and consultation calls show bounded live activity.
 - 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, consolidated mailbox/management actions, context selection, and persistence.
+- Provides addressable stateful agents with follow-up, consolidated mailbox/management actions, idempotent spawn retries, context selection and preview, versioned structured outcomes, and persistence.
+- Publishes built-in and custom agent capability manifests, then records the executor-owned `ExecutionPlan` that resolves requested authority to effective tools, model, thinking, timeout, transport, trust, and workspace controls.
+- Runs explicit dependency workflows through a persistent `WorkItem` ledger, dependency-aware scheduler, declared scope-conflict checks, artifact provenance, stale-result invalidation, and bounded overall deadlines.
+- Runs first-class blocking panels with two or more independent reviewers, incremental bounded evidence artifacts, preserved blockers and dissent, a minimum-valid-review barrier, reserved synthesis and cleanup budgets, and one evidence-preserving synthesis.
+- Supports bounded retries only for explicitly idempotent work and hedged execution only for explicitly read-only work.
+- Detects retained-agent semantic skew across agent definitions, role prompts, tools, model resolution, transport, trust, repository generation, artifacts, and scheduler policy before follow-up work starts.
 - 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.
 
@@ -41,7 +49,7 @@ pi -e npm:@narumitw/pi-subagents
 Try this package locally from the repository root:
 
 ```bash
-pi -e ./extensions/pi-subagents
+pi -e ./packages/pi-subagents
 ```
 
 ## 🛠️ Pi tool
@@ -59,7 +67,7 @@ The preview compares the selection with the tools registered in the current sess
 
 The available tools are:
 
-- `subagent` — delegate blocking single, parallel, fan-in, or chained batch work. The main agent cannot process queued steering until the call returns.
+- `subagent` — delegate blocking single, parallel, fan-in, chained, panel-review, or explicit dependency-workflow tasks. 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.
 - `subagent_inspect` — inspect agent/model/run/runtime metadata without launching work or changing state.
 - `subagent_consult` — run one ephemeral read-only consultation and wait for its answer.
@@ -102,14 +110,22 @@ Execution modes:
 - **parallel** — run multiple `{ agent, task }` jobs independently.
 - **parallel + aggregator** — run parallel jobs, then pass all outputs into one fan-in agent.
 - **chain** — run sequential steps, passing prior output with `{previous}`.
+- **workflow** — run named tasks only after declared `dependsOn` tasks and required `inputArtifacts` are ready; independent conflict-free tasks may run concurrently.
+- **panel** — run at least two independent reviewers over one shared task and snapshot, then run one synthesizer only when `minValidReviews` valid evidence artifacts remain.
 
 Common controls:
 
 - `cwd` — choose a launch directory subject to the user-owned trust-aware target policy described below.
-- `timeoutMs` — set a hard subprocess timeout.
-- `thinkingLevel` — request `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` thinking for the spawned Pi process or in-process child.
+- `timeoutMs` — choose the per-turn work deadline for the task difficulty.
+- `totalTimeoutMs` — cap an entire blocking single, parallel, chain, panel, or fan-in workflow, including queued work and reserved panel phases.
+- `idleTimeoutMs` — stop work that produces no completed assistant turn or tool result within the selected interval.
+- `maxTurns` / `maxToolCalls` — stop unfinished repeated work after bounded assistant turns or tool calls.
+- `thinkingLevel` — request `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` thinking for the spawned Pi process or retained child.
+- `idempotencyKey` — make an exact `subagent_spawn` retry return the existing retained `agentId`; reuse with different parameters fails before confirmation, worktree creation, or child launch.
+- `resultFormat` — keep bounded text by default, request legacy `structured-v1`, or request `structured-v2` with explicit outcome status, reason code, claims, artifacts, verification, limitations, and unresolved dependencies.
+- `totalTimeoutMs` — bound a whole explicit blocking workflow; no new task starts after the budget is exhausted.
 
-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.
+For `subagent_spawn`, the root agent selects the lowest thinking level and shortest realistic work deadline sufficient for the delegated task. These are tool-argument decisions made from the task already in context; `pi-subagents` does not run a string heuristic or an extra classifier model call.
 
 ## 🔐 Working-directory trust policy
 
@@ -122,7 +138,7 @@ The default target policies are:
 | `cwdPolicy.consultation` | `"anywhere"`, `"current-workspace"` | `"anywhere"`: consultation may start in any existing directory, but a target without effective trust is forced to `resources: "none"` |
 | `cwdPolicy.delegation` | `"trusted-targets"`, `"current-workspace"`, `"anywhere"` | `"trusted-targets"`: blocking and detached delegation may target the current workspace or an external folder covered by a saved `true` decision |
 
-All paths are resolved relative to the current session workspace and canonicalized before containment and trust checks. Missing paths, non-directories, sibling paths, and symlink escapes cannot bypass the policy. Blocking parallel, chain, and fan-in calls preflight every target before any child starts. A generated `workspaceMode: "worktree"` inherits the resolved trust of its approved base cwd.
+All paths are resolved relative to the current session workspace and canonicalized before containment and trust checks. Missing paths, non-directories, sibling paths, and symlink escapes cannot bypass the policy. Blocking parallel, chain, panel, and fan-in calls preflight every target before any child starts. A generated `workspaceMode: "worktree"` inherits the resolved trust of its approved base cwd.
 
 `"anywhere"` for general delegation restores the previous external-target flexibility. An external target without effective trust starts with `projectTrusted: false`, so Pi-protected project settings, packages, extensions, skills, prompts, and system resources stay disabled. General agents still have their configured tools and ordinary Pi/OS permissions, and Pi may still load `AGENTS.md` or `CLAUDE.md` because those context files are not protected by project trust. Resource-free consultation is stricter: it also passes `--no-context-files`, `--no-skills`, `--no-prompt-templates`, `--no-approve`, and `--no-extensions`.
 
@@ -163,10 +179,9 @@ Count-selection guidance:
 - 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.
+- 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 configured `blocking.maxParallelTasks` limit, and do not parallelize implementation that may edit the same files or shared state.
+  The limit defaults to 8, accepts 1 through 64, and bounds total worker tasks in one call rather than the four-at-a-time execution concurrency.
 - Do not use project-local agents unless the user explicitly opts into them with
   `agentScope: "project"` or `"both"`; keep confirmation enabled for untrusted repositories.
 
@@ -218,12 +233,15 @@ A blocking fan-out is reserved for output that must be synthesized before the ro
 | `list_agents` | Optional `agentScope` (default `user`) and `limit` (default 32, maximum 100) | Bounded agent metadata and omission counts |
 | `get_agent` | Required `agent`; optional `agentScope` | One resolved definition, safe source path, configured tools, and consultation-effective tools; never the system prompt |
 | `list_runs` | Optional `includeClosed` and `limit` (default 50, maximum 100) | Metadata-only retained-run summaries and unread counts |
-| `get_run` | Required `agentId` | Safe `cwd`, current-task/error summaries, thinking level, policy, history count, and unread count |
+| `get_run` | Required `agentId` | Safe `cwd`, current-task/error summaries, thinking level, context footprint, protocol, effective transport, bounded timing/usage telemetry, structured result when valid, policy, history count, and unread count |
+| `list_workflows` | Optional `limit` (default 50, maximum 100) | Metadata-only persisted blocking-workflow summaries for the current session |
+| `get_workflow` | Required `workflowId` | Bounded task states, generations, dependencies, plan identities, artifact metadata, verification state, and outcome reasons without artifact contents |
 | `list_models` | Optional `limit` (default 50, maximum 100) | Session-scoped models, or the already-loaded available snapshot |
-| `status` | No additional fields | Effective workflow, runtime counts/transport, completion delivery, consultation resources, and configured/runtime cwd policies with per-field sources |
+| `preview_context` | Optional `context` and `contextEntryIds` | Selected mode, user turns, source count, UTF-8 bytes, and truncation without returning context text |
+| `status` | No additional fields | Effective workflow, runtime counts/transport, detached limit values, completion delivery, consultation resources, and configured/runtime settings with per-field sources |
 | `diagnose` | No additional fields | Structured `pass`, `warning`, and `fail` checks; failed checks are report data rather than a tool error |
 
-The schema rejects fields that do not belong to the selected action. Explicit `project` or `both` scope fails before project-agent discovery unless Pi already trusts the project. Run inspection never returns history output, stored context, or mailbox content; unread counts come from a metadata-only snapshot and do not acknowledge messages. Paths beneath the Pi agent directory use `~`, project paths are workspace-relative, model objects are projected through an allow-list, and model-facing text is bounded to 50 KiB or 2,000 lines.
+The schema rejects fields that do not belong to the selected action. Explicit `project` or `both` scope fails before project-agent discovery unless Pi already trusts the project. Run inspection never returns history output, stored context, or mailbox content; unread counts come from a metadata-only snapshot and do not acknowledge messages. Workflow inspection reads validated, redacted snapshots without quarantining or rewriting invalid files. Paths beneath the Pi agent directory use `~`, project paths are workspace-relative, model objects are projected through an allow-list, and model-facing text is bounded to 50 KiB or 2,000 lines.
 
 Compatibility: `subagent_manage({ "action": "list" })` remains supported with its existing behavior. Prefer `subagent_inspect` when a whole tool must be safe to activate on a read-only surface.
 
@@ -261,7 +279,7 @@ Extensions remain disabled for all three values. Pi core owns system-prompt sour
 
 Both settings are user-owned in `~/.pi/agent/pi-subagents.json`; projects cannot override them. `cwdPolicy.consultation: "current-workspace"` rejects every canonical external target before agent discovery or launch even when that target is saved-trusted. This is not a path sandbox: read-only tools can still read an explicitly requested accessible absolute path.
 
-Result details report the canonical safe cwd, current/external boundary, bounded target-trust decision/source/warning, requested and effective tools/resources, downgrade reason, agent/model/thinking/timeout metadata, and the facts that extensions, session persistence, and retained-agent state are disabled. They never dump prompt contents or the full trust store. Nested model usage is returned through Pi's usage field, so footer, `/session`, and RPC totals include consultation cost. Validation, disallowed targets, and launch failures throw. Failures after model launch preserve bounded partial evidence and usage while the finalized Pi tool result is marked as an error. Abort, timeout, session replacement, and shutdown use the existing process-tree termination and temporary-file cleanup path.
+Result details report the canonical safe cwd, current/external boundary, bounded target-trust decision/source/warning, requested and effective tools/resources, downgrade reason, agent/model/thinking/timeout metadata, and the facts that extensions, session persistence, and retained-agent state are disabled. They never dump prompt contents or the full trust store. Nested model usage is returned through Pi's usage field, so footer, `/session`, and RPC totals include consultation cost. Validation, disallowed targets, and launch failures throw. Failures after model launch preserve bounded partial evidence and usage while the finalized Pi tool result is marked as an error. Explicit abort, session replacement, and shutdown use the existing process-tree termination and temporary-file cleanup path; a work timeout additionally makes one separately bounded, tool-less summary attempt after abort.
 
 ## 🚀 Blocking batch examples
 
@@ -334,6 +352,73 @@ Run a chain where each step receives the previous output:
 }
 ```
 
+Run an evidence-preserving panel:
+
+```json
+{
+  "panel": {
+    "id": "auth-panel",
+    "preset": "code-review",
+    "task": "Review the authentication change for correctness and regressions.",
+    "context": "Inspect the current repository snapshot and existing test evidence.",
+    "reviewers": [
+      { "id": "correctness", "agent": "reviewer", "focus": "Control flow and edge cases" },
+      { "id": "tests", "agent": "reviewer", "focus": "Coverage and regression risk" }
+    ],
+    "synthesizer": { "agent": "reviewer" },
+    "minValidReviews": 2
+  },
+  "totalTimeoutMs": 120000
+}
+```
+
+Every reviewer receives the same shared task, context, target snapshot, and scope, but never receives sibling output.
+Reviewer-specific `focus` text is appended after the shared block.
+The executor accepts only strict `pi-subagents:panel-review:v1` artifacts, stamps reviewer provenance, and starts synthesis only after the valid-review barrier.
+Agreement is corroboration rather than proof, and a vote cannot clear a correctness, safety, security, or explicit-requirement blocker.
+If too few valid reviews remain, the tool returns `insufficient-panel` with bounded partial evidence and failure classes without running synthesis or claiming consensus.
+Review, evidence-finalization, synthesis, and cleanup receive explicit phase allocations, and reviewer work cannot consume the synthesis or cleanup reserve.
+Only transient launch or transport failures receive one bounded retry; invalid contracts, semantic stalls, permission failures, exhausted budgets, cancellation, and deterministic task failures do not.
+Read-only reviewers share the approved target, while conservatively write-capable reviewers receive separate disposable Git worktrees from one clean base.
+Worktrees isolate repository writes but do not isolate processes, the network, secrets, credentials, or the rest of the filesystem.
+The blocking panel owns every reviewer, synthesizer, timer, generation, transport, and worktree and closes them when the call settles or Pi emits graceful session replacement or shutdown.
+An uncatchable host kill or forced process termination cannot guarantee cleanup; inspect `git worktree list`, remove any confirmed generated `pi-subagent-worktree-*` entry, and run `git worktree prune` if the host terminated before Pi dispatched lifecycle cleanup.
+Panel WorkItem snapshots persist metadata and artifact references for current-session inspection without storing raw review bodies.
+
+Run an explicit dependency workflow:
+
+```json
+{
+  "workflow": {
+    "id": "auth-review",
+    "tasks": [
+      {
+        "id": "inventory",
+        "agent": "scout",
+        "task": "Produce the auth inventory artifact.",
+        "resultFormat": "structured-v2",
+        "readPaths": ["src/auth"]
+      },
+      {
+        "id": "review",
+        "agent": "reviewer",
+        "task": "Review the inventory and report verification evidence.",
+        "dependsOn": ["inventory"],
+        "inputArtifacts": ["auth-inventory"],
+        "resultFormat": "structured-v2"
+      }
+    ]
+  },
+  "totalTimeoutMs": 120000
+}
+```
+
+Cycles, missing dependencies, conflicting integration owners, recursive workflow grandchildren, and unsafe retry or hedge policies fail before child launch.
+Workflow scheduling starts at most two mutating tasks concurrently, while declared read-only work may use the existing four-child ceiling.
+Set `workflow.honorAdmission: true` only when explicit contract admission metadata should be allowed to decline parent-owned or insufficient-evidence work before launch; admission never silently widens the requested architecture.
+Workflow result details include the final ledger, scheduling decisions, artifact versions, task generations, attempts, hedge use, accepted plan identity, and bounded capability-grant metadata.
+Explicit workflow transitions are also atomically persisted as mode-0600, private-text-redacted snapshots for current-session `list_workflows` and `get_workflow` inspection; in-flight tasks inspect as `interrupted`, and no prior side effect is automatically resumed.
+
 ## 🔁 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 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.
@@ -349,24 +434,35 @@ A detached agent additionally needs a concrete isolation or specialization benef
 
 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.
-
-Run `/subagents` in TUI mode to open the standard primary manager. It leads with the current
-delegation workflow, human-readable async completion behavior, consultation/delegation target policies, consultation-resource policy, and active/retained counts. **Change delegation**, **Current agents**, and **Settings** cover the common workflows; agent permissions, transport/runtime details, source, and settings path remain under **Advanced settings**.
-Escape returns from a nested screen to a newly refreshed manager; Ctrl+C closes the full flow.
-Exact workflow/reload and project-agent safety confirmations remain extension-owned because they
-guard live agent and trust-boundary policy rather than ordinary navigation.
+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.
+Set it to `rpc` to retain one `pi --mode rpc --no-session --no-extensions` process per active retained agent, preserving native child history with a separate process boundary.
+Set it to `auto` for deterministic preflight selection: read-only built-in tools use in-process, write-capable built-in tools use RPC, and extension/custom tools use subprocess.
+Automatic selection never falls back after child creation or prompt acceptance.
+
+Run `/subagents` in TUI mode to open the standard primary manager.
+It leads with the current delegation workflow, human-readable async completion behavior, consultation/delegation target policies, consultation-resource policy, parallel-worker limit, and active/retained counts.
+**Change delegation**, **Current agents**, and **Settings** cover the common workflows.
+Agent permissions, **Maximum parallel workers**, **Detached agent limits**, **Performance and execution**, transport/runtime details, source, and settings path remain under **Advanced settings**.
+**Performance and execution** provides responsiveness guidance, transport previews, Fast/Balanced/Deep thinking profiles, and per-agent model/thinking/timeout defaults.
+Profiles are explicit atomic thinking patches, preserve model/tool/timeout/context settings, never select `max`, and can be customized afterward.
+The parallel-worker input rejects invalid values without discarding the draft and applies a successful save immediately.
+The detached-limit screen edits retained capacity, active-turn concurrency, direct children, tree depth, and stored-record capacity.
+Detached-limit saves are durable immediately but apply to the runtime after `/reload` or the next Pi session.
+Escape returns from a nested screen to a newly refreshed manager, while Ctrl+C closes the full flow.
+Exact workflow/reload and project-agent safety confirmations remain extension-owned because they guard live agent and trust-boundary policy rather than ordinary navigation.
 
 The direct routes remain predictable: `/subagents settings` changes both target policies, consultation resources, and completion delivery and applies them immediately, including refreshing model-facing tool guidance; `/subagents status` reports current-session runtime values separately from configured values, per-field sources, and path; `/subagents help` summarizes the single-command interface and the non-sandbox limitation. 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
 {
   "blocking": {
-    "enabled": false
+    "enabled": false,
+    "maxParallelTasks": 8
   },
   "stateful": {
     "enabled": true,
-    "transport": "in-process",
+    "transport": "auto",
     "completionDelivery": "auto-resume",
     "maxAgents": 16,
     "maxActiveTurns": 4,
@@ -388,12 +484,31 @@ The direct routes remain predictable: `/subagents settings` changes both target
 }
 ```
 
-The settings UI patches the raw JSON atomically and preserves unknown fields; it refuses to overwrite malformed or invalid settings. Supported Pi writers serialize the latest-document read and same-directory temporary-file rename through `pi-subagents.json.mutation-lock`. Editors and older extension versions do not participate in that lock, so avoid manual edits while a settings save is in progress. `blocking.enabled` defaults to `true`; set it to `false` for async-only delegation. `stateful.enabled` also defaults to `true`; its existing `false` value remains the blocking-only workflow. `cwdPolicy.consultation` defaults to `"anywhere"`, `cwdPolicy.delegation` defaults to `"trusted-targets"`, and `consult.resources` defaults to `"project-context"`. The Settings UI applies a saved change immediately to subsequent launches and refreshes the affected tool descriptions; manual edits take effect on session start or `/reload`. The UI explicitly states that target/trust settings are not filesystem sandboxing and directs trust changes to Pi `/trust`. When stateful tools are enabled, their membership stays fixed across spawn, completion, interrupt, close, and mailbox transitions. This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
+The settings UI patches the raw JSON atomically and preserves unknown fields.
+It refuses to overwrite malformed or invalid settings.
+Supported Pi writers serialize the latest-document read and same-directory temporary-file rename through `pi-subagents.json.mutation-lock`.
+Editors and older extension versions do not participate in that lock, so avoid manual edits while a settings save is in progress.
+`blocking.enabled` defaults to `true`; set it to `false` for async-only delegation.
+`blocking.maxParallelTasks` defaults to `8` and accepts positive integers from `1` through `64`.
+It limits worker tasks in one blocking parallel call, while execution still starts at most four workers at once and treats an optional aggregator separately.
+`stateful.enabled` also defaults to `true`; its existing `false` value remains the blocking-only workflow.
+The detached defaults are `maxAgents: 16`, `maxActiveTurns: 4`, `maxChildrenPerAgent: 8`, `maxDepth: 3`, and `maxStoredAgents: 50`.
+`maxDepth` accepts zero or a positive safe integer, while the other four detached limits accept positive safe integers.
+Use `/subagents` → **Advanced settings** → **Detached agent limits** to edit them without replacing unknown JSON fields.
+The screen shows current-session and configured values separately because changes apply after `/reload`.
+It never reloads automatically, because reload can interrupt retained detached work.
+Lowering retained, depth, or stored capacity shows a projected recovery warning when current records would be omitted.
+Restored parents that already exceed a lowered `maxChildrenPerAgent` remain available, but they cannot gain another child until they fall below the configured limit.
+`cwdPolicy.consultation` defaults to `"anywhere"`, `cwdPolicy.delegation` defaults to `"trusted-targets"`, and `consult.resources` defaults to `"project-context"`.
+The Settings UI applies a saved change immediately to subsequent launches and refreshes the affected tool descriptions; manual edits take effect on session start or `/reload`.
+The UI explicitly states that target/trust settings are not filesystem sandboxing and directs trust changes to Pi `/trust`.
+When stateful tools are enabled, their membership stays fixed across spawn, completion, interrupt, close, and mailbox transitions.
+This avoids lifecycle-driven tool-schema churn and preserves a stable provider prompt prefix for KV caching.
 
 | Tool | Purpose |
 | --- | --- |
-| `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 and trigger a new turn on a reusable agent; shared-workspace write conflicts are guarded unless explicitly overridden. |
+| `subagent_spawn` | Start detached work with optional task-selected thinking and retained timeout, exact-retry `idempotencyKey`, and `text`, `structured-v1`, or `structured-v2` result format; return an opaque `agentId` immediately and deliver completion asynchronously. |
+| `subagent_send` | Send follow-up work with an optional one-turn timeout override and trigger a new turn on a reusable agent; semantic skew requires explicit `revalidate: true`, and shared-workspace write conflicts are guarded unless explicitly overridden. |
 | `subagent_manage` | Use `action: "list"` to inspect agents, `"interrupt"` to retain an agent after aborting active work, or `"close"` to release it; interrupt/close accept optional `subtree`. |
 | `subagent_mailbox` | Use `action: "send"` for queue-only messages that do not start a turn, or `"read"` to read and optionally acknowledge unread messages. |
 
@@ -415,7 +530,12 @@ The action schemas are flat for provider compatibility and reject parameters tha
 }
 ```
 
-Use the **Current agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents. 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 agents** action in `/subagents` to inspect the indented agent tree, lifecycle state, unread count, and available actions, or to confirm clearing retained agents.
+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.
+`maxChildrenPerAgent` bounds direct children, while `maxDepth` counts nested levels below a depth-zero root.
+`maxStoredAgents` bounds sanitized records persisted per session and does not increase live runtime capacity.
+`parentId` creates a bounded child relationship; subtree interrupt and close operate child-first.
 
 ### Migrating from the previous seven-tool lifecycle surface
 
@@ -441,7 +561,26 @@ A spawn can request a thinking level explicitly:
 }
 ```
 
-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.
+The requested level and spawn `timeoutMs`, `idleTimeoutMs`, `maxTurns`, and `maxToolCalls` are stored with the stateful agent and remain in effect for all follow-ups and after persisted restore. The same fields on `subagent_send` override only that follow-up turn. `subagent_send` does not provide a per-turn thinking override; create a new agent when a later task needs a different level.
+
+An exact retry can use a bounded session-owned idempotency key:
+
+```json
+{
+  "agent": "worker",
+  "task": "Implement the approved change",
+  "idempotencyKey": "approved-change-1"
+}
+```
+
+The same key and canonical request returns the existing retained `agentId` without another confirmation, worktree, or child.
+Reusing the key with different behavior-affecting parameters fails.
+Closing the retained record releases the key.
+
+Set `resultFormat: "structured-v1"` to ask for legacy `summary`, `evidence`, `changes`, `verification`, and `risks` fields.
+Prefer `resultFormat: "structured-v2"` when orchestration must distinguish `completed`, `partial`, `blocked`, `needs-input`, `failed`, `interrupted`, `abstained`, `stale`, or `contract-invalid` outcomes and consume typed artifact evidence.
+Valid structured data and deterministic recovery classification appear in completion and inspection details, while malformed structured output becomes `contract-invalid` instead of being treated as success.
+The executor stamps task generation, cancellation lineage, and accepted `ExecutionPlan` identity after parsing, so model output cannot forge the provenance used for stale-result containment.
 
 `subagent_spawn.context` accepts:
 
@@ -450,21 +589,31 @@ The requested level is stored with the stateful agent and remains in effect for
 - `"summary"` — a bounded earlier-context checkpoint plus recent messages verbatim.
 - A positive number — the most recent N user turns and related assistant text.
 
-Use `contextEntryIds` to select exact session entries. Supplying IDs without `context` implies `context: "all"`; an explicit `context: "none"` still disables parent context. Stable source IDs are retained so repeated follow-ups do not need to duplicate parent context.
+Use `contextEntryIds` to select exact session entries.
+Supplying IDs without `context` implies `context: "all"`; an explicit `context: "none"` still disables parent context.
+Stable source IDs are retained so repeated follow-ups do not need to duplicate parent context.
+Use `subagent_inspect` with `action: "preview_context"` to inspect selected turns, source count, UTF-8 bytes, and truncation before spawning without returning the context text.
+The byte count is not a provider token estimate.
 
 Reasoning, tool results, custom transport messages, and non-text parts are excluded. Text inside `<private>...</private>` and lines containing `[subagent-private]` are omitted before context, mailbox content, or history is persisted.
 
 Stateful execution uses a transport boundary:
 
-- `subprocess` is the default compatibility and rollback path.
+- `subprocess` is the default compatibility and rollback path and starts a fresh child for every turn.
 - `in-process` uses only public Pi SDK APIs: `createAgentSessionServices()`, `createAgentSessionFromServices()`, `SessionManager.inMemory()`, and normal session lifecycle methods. It isolates conversation/tool selection, not memory or crashes; child failures share the parent Node.js process.
-- Child resource loading sets `noExtensions: true`, preventing recursive `pi-subagents` loading and duplicate extension side effects while retaining trust-eligible context/skill resources and the selected agent prompt. Both transports receive the same resolved target-trust boolean: subprocess children get explicit `--approve`/`--no-approve`, and in-process children set the same `SettingsManager.projectTrusted` value.
+- `rpc` uses strict bounded JSONL over one lazy child process per active retained agent. A `get_state` response proves readiness, prompt response means accepted only, and `agent_settled` is the completion boundary after retry or compaction.
+- `auto` selects one transport before launch and retains the choice for that agent's runtime lifetime. It never retries through another transport after startup or accepted work.
+- In-process and RPC child resource loading disables extensions to prevent recursive `pi-subagents` loading and duplicate extension side effects while retaining trust-eligible context/skill resources and the selected agent prompt. The compatibility subprocess path retains its recursion-depth guard and configured tool behavior. Transports receive the same resolved target-trust boolean through their public SDK or explicit CLI trust controls.
 - Agent model strings use Pi core's CLI resolver, including provider/model patterns, fuzzy matching, custom provider model IDs, and `:<thinking>` suffixes. Thinking level and built-in tool allow-list overrides are applied when the child is created. Parent model/thinking changes are snapshotted for subsequently created children; an existing child keeps its own session configuration.
-- Extension/custom tool names are rejected in-process with an actionable recommendation to use `subprocess`; permissions are never silently widened.
-- Timeout, parent abort, close, expiry, and session shutdown abort/dispose owned child sessions. A child that does not settle after abort grace is discarded rather than reused.
+- Extension/custom tool names are rejected by in-process and RPC v1 before child creation; automatic mode selects `subprocess` for them, and permissions are never silently widened.
+- Timeout, parent abort, close, expiry, and session shutdown abort/dispose owned child sessions or process groups. A child that does not settle after abort grace is discarded rather than reused.
+- RPC progress uses `pi-subagents:v1` metadata and reports only bounded phase, queue, timing, effective model/thinking, and validated usage fields; it never exposes raw prompts, reasoning, credentials, environment values, or full RPC events.
+- A successful RPC prompt response is never treated as completion, and accepted or ambiguously accepted work is never replayed automatically.
 - In-process startup failures do not silently retry through subprocesses, preventing duplicate side effects. If the loaded Pi core lacks public `createAgentSessionServices()`, `createAgentSessionFromServices()`, or `resolveCliModel()` support, startup fails with an actionable instruction to select `stateful.transport: "subprocess"`.
 
-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.
+No private Pi imports, runtime casts, or `ExtensionAPI` monkey-patching are used.
+The package uses public Pi root RPC types but owns exact CLI resolution, bounded framing, readiness, stderr, cancellation, and process-group cleanup because the stock client does not provide those package-specific guarantees.
+Approval policy, sandbox profile, provider-header hooks, extension state, global scheduling, and parent/child transcript switching are not inherited or provided by in-process or RPC 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. 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.
 
@@ -472,19 +621,26 @@ Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree;
 
 ## 📜 Compatibility and failure contract
 
-Existing `subagent` input schemas remain unchanged. The intentional compatibility change is that an external target without saved trust is rejected by the new default `cwdPolicy.delegation: "trusted-targets"`; set the user-owned policy to `"anywhere"` to restore the preceding target flexibility.
+Existing accepted `subagent` payload shapes remain unchanged.
+`subagent_spawn` adds optional `idempotencyKey` and `resultFormat` fields without changing omitted behavior.
+Older releases do not recognize `stateful.transport: "rpc"` or `"auto"`; change the value to `"subprocess"` and reload before downgrading.
+Retained records remain transport-neutral, and older readers ignore the additive idempotency and context-footprint fields while the state version remains compatible.
+The `tasks` schema now advertises the absolute 64-item safety bound, while the effective `blocking.maxParallelTasks` value may be lower.
+The intentional compatibility change is that an external target without saved trust is rejected by the new default `cwdPolicy.delegation: "trusted-targets"`; set the user-owned policy to `"anywhere"` to restore the preceding target flexibility.
 
 | Mode | Ordering | Failure behavior |
 | --- | --- | --- |
 | Single | One result. | A failed/aborted/timed-out worker is marked as a tool error while preserving bounded details. |
 | Chain | Input order. | Stops at the first failed step; completed steps remain in details. |
-| 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. |
+| Parallel | Input order, up to `blocking.maxParallelTasks` total workers and at most four active children. | Rejects calls above the configured limit; otherwise collects all task results, and partial worker failure does not discard successful results. |
+| Parallel + aggregator | Source input order, then aggregator. | The aggregator runs with successful outputs and failure descriptions only when total budget remains; aggregator failure or orchestration expiry marks the tool result as an error. |
+| Workflow | Deterministic dependency-ready and critical-path order, with results returned in declared task order. | Invalid graphs fail before launch; blocked or failed dependencies prevent downstream start; bounded retry and hedging require explicit side-effect contracts. |
+| Panel | Reviewer declaration order, then at most one synthesizer. | Invalid or failed reviews remain visible; synthesis requires `minValidReviews`; insufficient panels preserve partial evidence without a consensus claim; synthesis contract failure marks the tool result as an error. |
 
 An aggregator whose `agent` or `task` is empty or whitespace-only is treated as absent, so successful
 parallel outputs remain available instead of being replaced by a malformed fan-in failure.
 
-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 after target preflight. Blocking and retained result/inspection details add bounded target boundary and effective trust metadata.
+Blocking work-timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms, then `totalTimeoutMs` caps the effective remaining time. Blocking idle, turn, and tool-call precedence is task/step/aggregator → call → omitted. Stateful budget precedence is the explicit `subagent_send` field for one follow-up → retained `subagent_spawn` field → timeout-only agent/environment fallback where applicable. 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 after target preflight. Blocking and retained result/inspection details add bounded target, budget, termination, and effective trust metadata.
 
 ## 🤖 Built-in agents
 
@@ -500,12 +656,24 @@ Built-in agents are available without setup and can be overridden by user or pro
 
 The built-in `reviewer` does not run tests, builds, benchmarks, or formatters. It recommends additional verification commands for the main agent to run instead. Custom agents can override this behavior.
 
-Built-in agents inherit the active/default Pi model instead of forcing a provider-specific model alias, which keeps subprocesses usable across different Pi setups.
+Built-in agents inherit the active/default Pi model instead of forcing a provider-specific model alias, which keeps every transport usable across different Pi setups.
+Built-ins also have no fixed thinking override until a caller, frontmatter, per-agent setting, or execution profile selects one.
+
+The optional profiles apply these provider-neutral thinking defaults:
+
+| Profile | `scout` | `planner` | `reviewer` | `worker` and aliases |
+| --- | --- | --- | --- | --- |
+| Fast | `low` | `low` | `medium` | `low` |
+| Balanced | `low` | `medium` | `medium` | `medium` |
+| Deep | `medium` | `high` | `high` | `high` |
+
+Profiles preserve model, timeout, tools, transport, completion delivery, and parent-context behavior.
 
 ## ⚙️ Configure agent tools
 
 Open `/subagents`, choose **Advanced settings**, then **Agent tool permissions** in an interactive
-Pi session to edit the tools each subagent may use. The standard bounded multi-select keeps a
+Pi session to edit the tools each subagent may use.
+Choose **Performance and execution** → **Agent execution defaults** to edit provider-neutral inherited model patterns, thinking levels, and timeouts without changing tools. The standard bounded multi-select keeps a
 one-save draft: toggles do not write until **Save changes**, Escape leaves the draft without writing,
 and unavailable configured tool names remain visible and preserved. In TUI mode, type to fuzzy-search
 tool names and availability metadata; Save and Discard remain pinned below the matches. These are user
@@ -538,6 +706,17 @@ description: Review API changes for compatibility and tests
 tools: read, grep, find, ls, bash
 model: sonnet
 thinkingLevel: high
+capabilityManifest:
+  version: pi-subagents:capabilities:v1
+  capabilities: [code-review, evidence-review]
+  modalities: [text]
+  resultFormats: [text, structured-v2]
+  authority:
+    filesystem: read
+  verificationRoles: [independent-review]
+  contextStrengths: [repository]
+  costHint: medium
+  latencyHint: medium
 ---
 
 You are an API review subagent. Do not edit files. Check compatibility,
@@ -546,6 +725,10 @@ test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
 
 `tools` accepts either the comma-separated form above or a YAML string array such as `tools: [read, grep]`. An omitted field keeps the agent's default tools; blank, `null`, or `[]` explicitly selects no tools.
 
+`capabilityManifest` is optional for legacy custom agents and never grants authority by itself.
+Explicit workflow routing can match declared capabilities, configured tools, filesystem authority, verification roles, and low/medium/high cost or latency hints.
+A missing or malformed manifest remains unknown and cannot satisfy a capability-routed task.
+
 `agentScope` is a top-level tool argument supplied per invocation. It is not a setting in
 `~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter. The parent-facing tool
 metadata discovers these definitions after session start and labels their source and required scope.
@@ -588,12 +771,21 @@ argument skips that confirmation dialog, but it does not bypass the project trus
 
 ## ⏱️ Runtime limits and thinking levels
 
-Each subprocess has a hard timeout to avoid runaway workers.
+Every turn can combine main-agent-selected wall-clock, idle, assistant-turn, and tool-call budgets with an extension-owned hard-bounded finalization deadline.
 
-- Set `timeoutMs` on the top-level call to apply a default for all jobs.
+- Set `blocking.maxParallelTasks` in `~/.pi/agent/pi-subagents.json`, or use `/subagents` → **Advanced settings** → **Maximum parallel workers**, to allow 1 through 64 worker tasks in one blocking parallel call.
+- The worker-count limit defaults to 8 and does not change the fixed four-at-a-time execution concurrency.
+- Set `timeoutMs` on the top-level blocking call to apply a work deadline to all jobs.
 - Set `timeoutMs` on a task, chain step, or aggregator to override it locally.
-- Valid timeout values range from 1 to 2,147,483,647 milliseconds, matching the runtime timer limit.
-- If omitted, the default is `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when unset.
+- Set top-level blocking `totalTimeoutMs` to cap model work across the whole call; each child receives at most the remaining budget, queued work is not started after expiry, fan-in receives only remaining time, and an orchestration-expired child skips model finalization. Bounded process-cleanup grace may follow the deadline.
+- Set `idleTimeoutMs` to stop a turn that has produced no completed assistant turn or tool result within that interval.
+- Set `maxTurns` or `maxToolCalls` to stop unfinished repeated work; a terminal answer at the exact turn limit remains successful.
+- Set spawn budgets as retained defaults, or the same fields on `subagent_send` to override one follow-up turn.
+- Top-level blocking turn budgets apply to every job, while a task, chain step, or aggregator can override them locally.
+- Choose the shortest realistic budgets for the task difficulty; split an oversized task instead of extending limits merely to compensate for broad scope.
+- Valid time values range from 1 to 2,147,483,647 milliseconds, matching the runtime timer limit.
+- `maxTurns` and `maxToolCalls` accept integers from 1 through 1,000,000.
+- If `timeoutMs` is omitted, the default is the retained or agent setting, then `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when unset; the other new budgets remain opt-in.
 
 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>`.
 
@@ -610,11 +802,17 @@ For `subagent_spawn`, the root agent should choose the lowest sufficient level:
 
 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 delegates configured model parsing to the loaded Pi core and uses its model thinking suffix before 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.
+Stateful spawn precedence is: `subagent_spawn.thinkingLevel` → agent default from settings or frontmatter → model suffix → transport fallback.
+Subprocess uses spawned Pi model/default resolution.
+In-process delegates configured model parsing to loaded Pi core and then uses the parent thinking snapshot captured at child creation.
+RPC passes the selected CLI model and thinking controls before its readiness handshake and reports the effective state returned by Pi.
+An explicit spawn value is retained for the agent lifecycle and wins over every fallback.
 
 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.
+When any execution budget expires, the extension aborts the active run first and creates a versioned, bounded, redacted checkpoint containing partial assistant notes, completed tool evidence, changed-file hints, and whether side effects may already have occurred. After authoritative settlement it may make one concise summary attempt over that checkpoint without replaying the stopped task. The summary attempt has its own extension-owned model-work deadline of at most 45 seconds, followed only by bounded abort and process-cleanup grace. Fresh subprocess summaries run with no tools or project resources. Retained RPC and in-process summaries reuse their child context and are explicitly instructed not to call tools; the current child APIs do not support replacing an existing session's tool set for one turn, so their separate deadline and abort path remain the enforcement boundary. The deterministic checkpoint remains available when finalization or the provider fails, and results retain exit `124` plus a structured termination reason and finalization status. Explicit parent or user abort stops immediately, never starts finalization, and is not mislabeled as a budget stop.
+
+This release does not claim a cooperative soft-wrap-up phase because print-mode subprocess children cannot receive steering while they are running. It also does not retry budget-stopped work automatically because file or external side effects may already have occurred.
 
 The child event protocol limits each JSON line to 256 KiB. Captured output uses these defaults:
 
@@ -626,11 +824,26 @@ Truncated text includes a `truncated by pi-subagents` marker and details expose
 
 ## 📡 Runtime status
 
+Run the offline transport benchmark from the repository root when comparing startup overhead:
+
+```bash
+just benchmark-subagents
+```
+
+It reports serial median and median absolute deviation for deterministic fake fresh-subprocess and retained-RPC turns plus isolated real Pi RPC readiness, retained commands, in-process session creation, and retained in-process state access without making a provider request.
+Queue time starts when the registry accepts work, transport startup starts when execution begins, RPC readiness comes from `get_state`, RPC acceptance comes from the correlated `prompt` response, first activity comes from a bounded lifecycle event, settlement comes from `agent_settled`, and delivery is recorded after the parent accepts the completion message.
+Subprocess and in-process timing fields use the nearest public lifecycle boundary and may be coarser than RPC.
+Timing and progress are current-session diagnostics and are not persisted.
+The benchmark measures transport overhead rather than model latency or output quality.
+
 While the `subagent` tool is running, `pi-subagents` publishes compact activity status with `ctx.ui.setStatus("subagents", "...")`. Any statusline extension that reads Pi's generic extension status API can display it; no package-to-package dependency is required.
 
 ## 🔒 Safety notes
 
-Subagents have separate processes and context windows, but they are **not security sandboxes**. They run as the same OS user, share the host filesystem and network access, and may conflict if they edit the same files. Tool allow-lists reduce available Pi tools but do not reduce operating-system permissions. `subagent_consult` prevents writes through its Pi tool surface and disables extensions, but it can read accessible paths, call the configured model over the network, and incur cost; its instruction-resource policy is not a filesystem or confidentiality boundary.
+Subagents have separate processes and context windows, but they are **not security sandboxes**. They run as the same OS user, share the host filesystem and network access, and may conflict if they edit the same files. Tool allow-lists reduce available Pi tools but do not reduce operating-system permissions. `subagent_consult` prevents writes through its Pi tool surface and disables extensions, but it can read accessible paths, call the configured model over the network, and incur cost; its instruction-resource policy is not a filesystem or confidentiality boundary. Panel write-capable reviewers use separate disposable Git worktrees, but those worktrees provide repository-write isolation only.
+
+Every contracted execution records a hashed immutable `ExecutionPlan` and an executor-owned capability grant bound to its task generation, effective tools, issuance time, and expiry.
+Interrupt, close, shutdown, replacement, persistence, and restore revoke active grants before signalling work or accepting another generation, and late old-plan results become `stale` diagnostic evidence.
 
 The runner explicitly reports policy continuity in result details:
 
@@ -640,12 +853,21 @@ The runner explicitly reports policy continuity in result details:
 
 Treat project-local agent prompts like executable project configuration: only enable them in trusted repositories. Stateful project agents require Pi's project trust; interactive use also keeps confirmation enabled by default.
 
-Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-subagents-state/` (or the configured Pi agent directory). Records contain sanitized logical history, never process IDs or credentials. Corrupt or unsupported state is quarantined, restored agents are always inert `idle` records, and no prior side effect is automatically resumed. Retention and count limits are configurable. Downgrading is safe: older extension versions ignore this separate state directory; clear **Current agents** from `/subagents` before downgrade if the histories should be removed.
+Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-subagents-state/` (or the configured Pi agent directory).
+Explicit blocking-workflow snapshots use separate mode-0600 files under `~/.pi/agent/pi-subagents-workflows/`, retain at most 64 workflows per session for 30 days, and are available only through current-session workflow inspection.
+Records contain sanitized logical history, never process IDs or credentials.
+Corrupt or unsupported state is quarantined, completed and actionable terminal outcomes are preserved, in-flight records restore as `interrupted`, and no prior side effect is automatically resumed.
+Retained follow-ups compare a privacy-safe hashed semantic snapshot before model work; incompatible resource changes require explicit `revalidate: true`, while unknown snapshot versions fail closed.
+Snapshots hash agent manifests, prompts, effective tools, model/thinking, transport, trust, Git tracked and untracked state, and bounded user/project skill and prompt resources without persisting their contents.
+A non-Git target has no stable repository generation proof, so each later follow-up requires explicit revalidation.
+Count projection keeps complete ancestor chains together when stored or restored limits omit older trees.
+Retention and count limits are configurable.
+Downgrading is safe: older extension versions ignore this separate state directory; clear **Current agents** from `/subagents` before downgrade if the histories should be removed.
 
 ## 🗂️ Package layout
 
 ```txt
-extensions/pi-subagents/
+packages/pi-subagents/
 ├── src/
 │   ├── index.ts                  # Pi package entrypoint
 │   ├── subagents.ts              # Extension registration and blocking tool schema
@@ -653,10 +875,44 @@ extensions/pi-subagents/
 │   ├── consult.ts                # Synchronous read-only consultation tool
 │   ├── consult-policy.ts         # Enforced read-only tool intersection
 │   ├── cwd-policy.ts             # Canonical target and saved-trust resolution
+│   ├── prompt-resources.ts       # Core-selected SYSTEM and APPEND_SYSTEM resources
 │   ├── safe-text.ts              # Shared byte/line/path sanitization
 │   ├── stateful.ts               # Detached lifecycle registration and dispatch
+│   ├── rpc-transport.ts          # Persistent strict-JSONL Pi RPC child transport
+│   ├── rpc-timeout-finalization.ts # RPC abort-settle-summary recovery
+│   ├── rpc-transport-metadata.ts # RPC result policy and bounded metadata helpers
+│   ├── rpc-turn-capture.ts       # RPC evidence capture, usage, and budget events
+│   ├── auto-transport.ts         # Deterministic preflight transport routing
+│   ├── transport-types.ts        # Bounded pi-subagents:v1 progress and telemetry contract
+│   ├── completion-delivery.ts    # Completion batching and optional idle-root wake
+│   ├── admission-policy.ts       # Audit-only deterministic delegation admission
+│   ├── capability-grant.ts       # Generation-bound authority lifetime and revocation
+│   ├── execution-plan.ts         # Executor-owned authority and resource resolution
+│   ├── work-item-ledger.ts       # Persistent dependency and artifact state machine
+│   ├── work-item-persistence.ts  # Atomic redacted workflow state and inspection
+│   ├── integration-controller.ts # Fail-closed canonical integration admission
+│   ├── adaptive-scheduler.ts     # Dependency, capacity, budget, and conflict scheduling
+│   ├── semantic-snapshot.ts      # Privacy-safe continuation compatibility checks
+│   ├── supervision.ts            # Bounded idempotent retries and read-only hedging
+│   ├── panel-execution.ts        # Blocking review barrier, synthesis, and lifecycle owner
+│   ├── panel-contract.ts         # Strict review and synthesis evidence contracts
+│   ├── panel-evidence.ts         # Bounded monotonic reviewer evidence ledger
+│   ├── panel-planning.ts         # Panel validation, phase budgets, and WorkItems
+│   ├── panel-prompts.ts          # Shared-task reviewer and synthesis prompts
+│   ├── panel-reconciliation.ts   # Objection-preserving valid-review barrier
+│   ├── panel-child-group.ts      # Child signals and disposable-worktree cleanup
+│   ├── panel-render.ts           # Compact and expanded sanitized panel rows
+│   ├── execution-profiles.ts     # Provider-neutral thinking profile patches
+│   ├── execution-ui.ts           # Profile and per-agent execution settings screens
 │   ├── stateful-guidance.ts      # Detached model-facing workflow guidance
 │   ├── stateful-lifecycle.ts     # Runtime disposal and spawn ownership guards
+│   ├── timeout-finalization.ts   # Abort-time bounded summary prompts and deadlines
+│   ├── timeout-checkpoint.ts     # Redacted deterministic termination evidence
+│   ├── turn-budget.ts            # Idle, assistant-turn, and tool-call enforcement
+│   ├── runner-usage.ts           # Bounded subprocess usage accumulation
+│   ├── runner-result.ts          # Shared subprocess result interpretation
+│   ├── stateful-limit-ui.ts      # Detached capacity settings and recovery previews
+│   ├── stateful-limits.ts        # Shared detached defaults, labels, and validation
 │   ├── stateful-safety.ts        # Project-agent and shared-write safety checks
 │   ├── stateful-tool-params.ts   # Consolidated action schemas and validation
 │   └── *.ts                      # Package-local discovery, execution, rendering, and settings modules
@@ -666,7 +922,11 @@ extensions/pi-subagents/
 └── package.json
 ```
 
-`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal. Workflow settings remain backward compatible: older files without `blocking.enabled` receive the seven-tool default, existing `stateful.enabled: false` files expose blocking delegation plus inspection/consultation, and older package releases ignore and preserve the optional `consult` and `cwdPolicy` objects. The package exposes its Pi extension through `package.json`:
+`index.ts` is the Pi entrypoint and forwards to `subagents.ts`; the other source modules are internal.
+Workflow settings remain backward compatible: older files without `blocking.enabled` receive the seven-tool default, and an absent `blocking.maxParallelTasks` keeps the previous eight-worker limit.
+Existing `stateful.enabled: false` files expose blocking delegation plus inspection/consultation.
+Older package releases ignore and preserve the optional `blocking.maxParallelTasks`, `consult`, and `cwdPolicy` fields.
+The package exposes its Pi extension through `package.json`:
 
 ```json
 {
@@ -678,7 +938,7 @@ extensions/pi-subagents/
 
 ## 🔎 Keywords
 
-Pi extension, Pi coding agent, subagents, agent delegation, parallel agents, fan-in aggregation, chained agents, isolated subprocesses, AI coding workflow, TypeScript Pi package.
+Pi extension, Pi coding agent, subagents, agent delegation, parallel agents, review panels, evidence synthesis, fan-in aggregation, chained agents, isolated subprocesses, AI coding workflow, TypeScript Pi package.
 
 ## 📄 License