@henryqw/pi-subagent 8.0.0 → 9.0.0

package/CONTEXT.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-Provide validated built-in and user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, generic `delegate_task` delegation, and package-owned `delegate_flow` Git orchestration. Main plans and orchestrates; `delegate_task` remains a flat bounded delegation tool, while Flow uses the effective Implementer and only invokes its effective Reviewer for explicit judgment criteria after authoritative validation. The bundled Main-side Skill adds no runtime behavior or changes generic fallback.
+Provide validated built-in and user Roles, shared task-model Pi launch policy, generic `delegate_task` delegation, and package-owned `delegate_flow` Git orchestration. Main plans and orchestrates; `delegate_task` remains a flat bounded delegation tool, while Flow uses the effective Implementer and only invokes its effective Reviewer for explicit judgment criteria after authoritative validation. The bundled Main-side Skill adds no runtime behavior or changes generic fallback.
 
 ## Domain glossary
 
@@ -20,12 +20,11 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - **Resource Policy**: Role ownership of base tools, extensions, and Skill names, plus explicit caller additions of tools, extensions, and environment through `createRoleLaunch`.
 - **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
 - **Ephemeral Executor**: mechanism that receives a prepared Pi Launch, runs one bounded Delegated Task in one no-session child process, and returns its result without discovering resources or composing a Workflow.
-- **Managed Subagent**: Pi agent hosted in a reconciled Herdr tab or pane; lifecycle orchestration remains with the caller.
 
 ## Invariants
 
 - One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns`, positive safe integer) or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. On continuing `turn_end`, the existing child Role tool extension steers the fixed convergence warning once at 80% of completed turns and once at 80% of maximum runtime, combining thresholds first due together and never starting a warning timer or extra turn. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`maxTurns` default 50; `timeout.idleMinutes`/`maxMinutes` defaults 10/30).
-- Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
+- Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout.
 - Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.
 - Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`); library callers select a Role plus their own Model Task declaration.
@@ -35,4 +34,3 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - Flow is memory-only. Only a post-rebase commit drop produces a no-op (`base === tip`); it validates, skips Reviewer and merge, then cleans up ordinarily. Initial zero-commit implementations block. Implementer, validation, or reviewer blocks allow one `delegate_flow_continue({ guidance, modelClass? })` repair in the same worktree; omission retains the Unit's current class and presence replaces it for that repair. A second block is terminal. Rebase and evidence/Reviewer/infrastructure failures retain worktrees. A reported fast-forward failure retains its worktree unless Main is clean at the exact integrated tip, which completes with the merge diagnostic as a warning. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal is a completion warning.
 - Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge validation. It never changes generic `delegate_task` Role resolution, isolation, non-Git fallback, or ordinary direct plan/file review.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
-- Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -1,11 +1,11 @@
 # `@henryqw/pi-subagent`
 
-Delegate bounded work to isolated Pi child processes. Main plans and orchestrates; generic `delegate_task` selects one flat single, parallel, or chain mode. Package-owned `delegate_flow` runs a fixed Git implementation-and-verification Flow. Package authors can reuse the same Role launch policy and active-Pi executor from JavaScript.
+Main is the parent Pi session. It can delegate bounded single, parallel, and chained tasks, plus package-owned Git Flow work, to isolated Pi child roles.
 
 ## Why
 
-- **Created for**: Pi users who need to delegate bounded work to isolated child Pi processes without losing Main's context.
-- **Advantage**: Generic bounded delegation plus a deterministic package-owned Git Flow, with reusable Role launch policies for package authors.
+- **Created for**: Delegate bounded work to isolated child Pi processes without losing Main's context.
+- **Advantage**: Generic bounded delegation and a deterministic package-owned Git Flow use reusable Role launch policies for package authors.
 
 ## Install
 
@@ -19,8 +19,10 @@ pi install npm:@henryqw/pi-subagent
 
 | Package | Why |
 | --- | --- |
-| `@henryqw/pi-task-models` | Required shared `fast` / `balanced` / `frontier` / `fav` routes. |
-| `@henryqw/pi-multi-codex` | Required so children can use Main's active Codex slot. |
+| `@henryqw/pi-multi-codex` | Required. Children can use Main's active Codex slot. |
+| `@henryqw/pi-task-models` | Required. Shared `fast` / `balanced` / `frontier` / `fav` routes. |
+
+Model routing is not configured here. Children resolve routes through shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
 
 ## Use
 
@@ -30,7 +32,7 @@ pi install npm:@henryqw/pi-subagent
 | `delegate_flow` | tool | Package-owned parallel implementation and declared-order Git integration for 1–8 independent units. |
 | `delegate_flow_continue` | tool | Repair the blocked Flow unit once in its existing worktree. |
 
-All three delegation tool blocks use Pi's default boxed shell and background. Their compact custom content is an immutable call label, foreground aggregate partial-result status, and bounded final summaries—no expanded view.
+All three delegation tool blocks use Pi's default boxed shell and background. Their compact custom content is an immutable call label, foreground aggregate partial-result status, and bounded final summaries. There is no expanded view.
 
 ### `delegate_task`
 
@@ -47,37 +49,92 @@ Select exactly one shape:
 { chain: [{ role, task, model?, modelClass?, thinking? }], background? }
 ```
 
-`model` is `provider/modelId` and overrides `modelClass`. Main populates `model` and `thinking` only for an explicit user override; otherwise it chooses only `modelClass`—`fast` normally, or `balanced` upfront for obviously complex work. This is Main policy only: the runtime records no provenance and does not enforce it. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`), which shared config can explicitly override. `background` applies to the entire selected mode and is never a per-delegation field.
+#### Model precedence
 
-Parallel mode starts entries concurrently, waits for every entry, and reports them in input order. Chain mode is sequential and fail-fast; every literal `{previous}` receives only the immediately preceding successful assistant output. Foreground failures throw after retaining bounded sibling and recovery evidence. One tool call has one aggregate 50 KiB Main-visible transport cap, not 50 KiB per child.
+1. An explicit `model` is `provider/modelId` and overrides `modelClass`.
+2. Main sets direct `model` and `thinking` only for an explicit user override.
+3. Otherwise, Main selects `modelClass`: `fast` normally or `balanced` upfront for obviously complex work.
+4. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`.
+   When omitted, it uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration.
+   That declaration defaults to `fast` and shared config can explicitly override it.
 
-Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
+This is Main policy only. The runtime records no provenance and does not enforce it. `background` applies to the whole selected mode and is never a per-delegation field.
 
-The transient status widget renders one line per child with: status glyph, role, status label, task summary, activity (thinking… or active tool with elapsed time and path basename), and metrics (completed turns, started tools, model, thinking level, tokens, total duration). Rows are ordered active-first (working items first, stable insertion order for the rest). A hard six-physical-line maximum applies: when total items are six or fewer, all child rows render; above six, five child rows plus one status-aware overflow line render (`… N more · X working · Y complete · Z failed · W stopped`). Terminal rows clear on the next real user input; active rows persist until the child settles. The final `delegate_task` block is deliberately minimal: bounded final summaries with role attribution for parallel/chain, and only retained-worktree recovery paths. It has no expanded view.
+#### Modes, limits, and isolation
 
-Each delegation resolves its own Role, resources, route, and optional worktree request. When available, `isolation: worktree` gives each entry a deterministic separate worktree; non-Git or unborn-`HEAD` contexts may use Main's cwd. Siblings and chain steps never implicitly share one created worktree.
+- Parallel mode starts entries concurrently, waits for every entry, and reports them in input order.
+- Chain mode is sequential and fail-fast. Each literal `{previous}` receives only the immediately preceding successful assistant output.
+- Foreground failures throw after retaining bounded sibling and recovery evidence.
+- One tool call has one aggregate 50 KiB Main-visible transport cap. It is not 50 KiB per child.
+- Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
+- Each delegation resolves its own Role, resources, route, and optional worktree request.
+- When available, `isolation: worktree` gives each entry a deterministic separate worktree. Non-Git or unborn-`HEAD` contexts may use Main's cwd.
+- Siblings and chain steps never implicitly share one created worktree.
 
 See [Orchestration, isolation, and the public API](./docs/orchestration.md) for generic delegation, Flow behavior, and JavaScript composition examples.
 
 ### `delegate_flow`
 
-Use Flow only for independent, commuting Git changes. It accepts 1–8 uniquely identified units, each with a bounded task, optional `modelClass`, direct command/argument validation gate, and optional non-empty `review` judgment criterion:
+Use Flow only for independent, commuting Git changes. Commuting changes can integrate in any order.
+
+Flow accepts 1–8 uniquely identified units. Each unit has a bounded task, optional `modelClass`, direct command/argument validation gate, and optional non-empty `review` judgment criterion:
 
 ```text
 delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] })
 delegate_flow_continue({ guidance, modelClass? })
 ```
 
-Objective verification is authoritative. Flow always inspects committed Git state and runs declared validation. A unit without `review` skips review evidence and Reviewer launch, then fast-forwards its exact validated tip through the existing guarded `git merge --ff-only` path. Add `review` only for an explicit judgment that automation cannot establish; that unit retains the exact `{base, tip, patchPath}` protocol and requires exact `PASS` before the same integration path.
+```mermaid
+flowchart LR
+  setup["Setup: resolve roles and create Unit Worktrees"] --> implement["Implementers in parallel"]
+  implement -->|Implementer block| repair["One repair: delegate_flow_continue"]
+  implement --> rebase["Rebase, inspect committed state, and validate"]
+  rebase -->|Post-rebase no-op| cleanup["Cleanup"]
+  rebase --> review{"Review requested?"}
+  review -->|No| integrate["Integrate in declared order"]
+  review -->|Yes| packet["Exact {base, tip, patchPath}; require PASS"]
+  packet -->|PASS| integrate
+  rebase -->|Validation block| repair
+  packet -->|Review block| repair
+  repair --> revalidate["Revalidate repaired work"]
+  revalidate -->|No review requested| integrate
+  revalidate -->|Review required| rereview["Re-review exact {base, tip, patchPath}; require PASS"]
+  rereview -->|PASS| integrate
+  revalidate -->|Second block| terminal["Terminal failure: retain worktree"]
+  rereview -->|Second block| terminal
+  rebase -->|Rebase or infrastructure failure| terminal
+  repair -->|Infrastructure failure| terminal
+  integrate --> cleanup
+```
+
+Objective verification is authoritative. Flow always inspects committed Git state and runs declared validation.
+
+A unit without `review` skips review evidence and Reviewer launch. It fast-forwards its exact validated tip through the existing guarded `git merge --ff-only` path.
+
+Add `review` only for judgment that automation cannot establish. That unit keeps the exact `{base, tip, patchPath}` protocol and requires exact `PASS` before the same integration path.
+
+Only one memory-only Flow may be active. At start, it resolves and freezes the effective `implementer` Role, including a same-named user override. It resolves and freezes the effective `reviewer` only when at least one unit requests `review`.
+
+An omitted `modelClass` uses the local `pi-subagent/delegateTask` declaration, which defaults to `fast`. A selected class resolves through its shared profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer.
 
-One memory-only Flow may be active. At start it resolves/freezes the effective `implementer` Role, including a same-named user override, and resolves/freezes the effective `reviewer` only if at least one requested unit has `review`. Omitted `modelClass` uses pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); a selected class resolves through its shared profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It creates one Unit Worktree per unit, runs Implementers in parallel, then processes settled results in declared order. It removes the worktree and branch non-forcibly after integration; a refusal is a completion warning with the retained worktree path and/or branch.
+Flow creates one Unit Worktree per unit before it launches Implementers. It runs Implementers in parallel, then processes settled results in declared order.
 
-A rebase that drops all unit commits is a no-op: Flow validates it, skips Reviewer and merge, then cleans up ordinarily. Implementer, validation, or review blocks can be repaired once through `delegate_flow_continue` in the same worktree. Omitted continuation `modelClass` retains the blocked unit's current class; a supplied class replaces it for that one repair. Rebase and infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Git left Main clean at the exact integrated tip; otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
+After integration, it removes the worktree and branch non-forcibly. A refusal is a completion warning with the retained worktree path and/or branch.
 
-`delegate_task` remains generic with its ordinary isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review; same-named user Roles remain supported overrides.
+A rebase that drops all unit commits is a no-op. Flow validates it, skips Reviewer and merge, then cleans up ordinarily.
+
+Implementer, validation, or review blocks can be repaired once through `delegate_flow_continue` in the same worktree. An omitted continuation `modelClass` retains the blocked unit's current class. A supplied class replaces it for that one repair.
+
+Rebase and infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Git left Main clean at the exact integrated tip.
+
+Otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
+
+`delegate_task` keeps its generic isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review. Same-named user Roles remain supported overrides.
 
 ### Delegate UI summary
 
+The transient status widget shows status glyph, role, status label, task summary, activity, and metrics for each child. Activity is `thinking…` or the active tool with elapsed time and path basename. Metrics are completed turns, started tools, model, thinking level, tokens, and total duration.
+
 | Aspect | Behavior |
 | --- | --- |
 | Call label | `delegate_task · single/parallel/chain · N task(s)`; `delegate_flow · parallel→serial · N unit(s)`; `delegate_flow_continue · repair continuation` |
@@ -88,11 +145,19 @@ A rebase that drops all unit commits is a no-op: Flow validates it, skips Review
 | Terminal retention | Active rows persist; terminal rows clear on next user input |
 | Final result | Bounded summaries with recovery paths; no expanded view |
 
+- Rows are active-first: working items first, then stable insertion order.
+- The hard six-physical-line maximum shows all child rows for six or fewer items.
+- Above six, it shows five child rows and one status-aware overflow line: `… N more · X working · Y complete · Z failed · W stopped`.
+- Terminal rows clear on the next real user input. Active rows persist until the child settles.
+- The final `delegate_task` block is deliberately minimal. It has bounded final summaries and role attribution for parallel and chain work. It shows only retained-worktree recovery paths.
+
 ## Config
 
-pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`, which holds two kinds of user-owned configuration: one Markdown file per Role (see [Roles](#roles)) and its own optional JSON file below. Model routing is *not* configured here; children resolve routes through the shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
+pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`. It holds two kinds of user-owned configuration.
+
+One Markdown file belongs to each Role (see [Roles](#roles)). The other is its own optional JSON file below.
 
-`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and execution budgets. All fields are optional; a missing file uses defaults.
+`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the child pool and execution limits. All fields are optional. A missing file uses defaults.
 
 | Field | Required | Possible values | Default |
 | --- | --- | --- | --- |
@@ -101,9 +166,17 @@ pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-sub
 | `timeout.idleMinutes` | No | Positive number of minutes where minutes × 60 000 ms ≤ 2,147,483,647 | `10` |
 | `timeout.maxMinutes` | No | Positive number within the same ms cap that must be greater than `timeout.idleMinutes`, otherwise the whole `timeout` object falls back to defaults | `30` |
 
-Excess children wait FIFO without consuming child timeout. A terminal response on turn 50 succeeds; an attempted continuation starts no model work and rejects with `turn_limit`. Before a continuing turn, the child receives the execution-budget warning once when completed turns reach 80% and once when elapsed time reaches 80% of the maximum runtime; thresholds first reached together produce one combined warning. `PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session (positive integer; an invalid value prevents the extension from loading, leaving `delegate_task` unavailable).
+- Excess children wait FIFO without consuming child timeout.
+- A terminal response on turn 50 succeeds.
+- An attempted continuation starts no model work and rejects with `turn_limit`.
+- Before a continuing turn, the child gets one warning when completed turns reach 80%.
+- It gets another warning when elapsed time reaches 80% of the maximum runtime.
+- If both thresholds are first reached together, the child gets one combined warning.
+- `PI_SUBAGENT_MAX_SUBAGENTS` overrides `maxSubagents` for the session. It must be a positive integer. An invalid value prevents the extension from loading and leaves `delegate_task` unavailable.
 
-This JSON is read leniently: malformed JSON, a non-object root, unknown keys, or invalid values are collected into one warning and the affected settings fall back to defaults; the file is never rewritten.
+This JSON is read leniently. Malformed JSON, a non-object root, unknown keys, or invalid values are collected into one warning.
+
+The affected settings fall back to defaults. The file is never rewritten.
 
 ### Role frontmatter
 
@@ -119,14 +192,14 @@ Each Role `.md` file in the same directory accepts these frontmatter fields:
 | `skills` | Yes | YAML array of non-empty Skill names | `[]` selects no separately named Role Skills; trusted extension Skills still load |
 | body | Yes | System-prompt Markdown after the frontmatter | — |
 
-An unreadable or invalid Role file fails role loading fast; duplicate role names are rejected.
+An unreadable or invalid Role file fails role loading fast. Duplicate role names are rejected.
 
 ## Roles
 
-The package ships two working built-in Roles, always available without any configuration:
+The package ships two working built-in Roles. They are always available without configuration.
 
 - `implementer`: focused edits requesting worktree isolation; commits completed scoped changes locally and never pushes or opens PRs without authorization
-- `reviewer`: read-only correctness review of supplied plans/files, or—only when a Flow unit declares `review`—of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
+- `reviewer`: read-only correctness review of supplied plans or files, or—only when a Flow unit declares `review`—of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
 
 A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
 
@@ -135,25 +208,58 @@ The repository also includes optional inert samples:
 - [`scout`](./examples/roles/scout.md): read-only discovery
 - [`synthesizer`](./examples/roles/synthesizer.md): reconcile supplied reports
 
-Copy them manually from your installed `@henryqw/pi-subagent` package (npm installs ship the `examples/roles/` directory) if you want them as a starting point:
+Copy them manually from your installed `@henryqw/pi-subagent` package if you want a starting point. npm installs ship the `examples/roles/` directory.
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
 cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
 ```
 
-Locate the install directory with `npm root` inside your project, or via Pi's package installation path.
+Locate the install directory with `npm root` inside your project, or through Pi's package installation path.
 
-The package never installs or writes Role configuration. Sample names are not built-ins; after copying, edit or replace them as your own Roles.
+The package never installs or writes Role configuration. Sample names are not built-ins. After copying, edit or replace them as your own Roles.
 
 ## Skill
 
-The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side planner/orchestrator policy only. `delegate_flow` owns its fixed Git mechanics and validation authority; the Skill adds no runtime code, configuration, or Role installation. Generic orchestration remains outside the executor under [ADR 001](./docs/adr/001-composable-ephemeral-execution.md).
+The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side planner and orchestrator policy only. `delegate_flow` owns its fixed Git mechanics and validation authority.
+
+The Skill adds no runtime code, configuration, or Role installation. Generic orchestration remains outside the executor under [ADR 001](./docs/adr/001-composable-ephemeral-execution.md).
+
+## Role, Skill, and resource trust
+
+### Role resources
+
+A Role explicitly owns base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Every launch installs its Role tool policy.
+
+Named Skills resolve through Main's effective Pi Skill registry. Ambient extension and Skill discovery is disabled in children.
+
+### Trusted extensions are not sandboxing
+
+Selecting an extension explicitly selects a trusted atomic capability bundle, not just a provider path. Every tool it registers and every Skill supplied through its Pi package metadata or dynamic `resources_discover` loads alongside separately named Role Skills.
 
-A Role explicitly owns base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Every launch installs its Role tool policy: `tools: []` activates no base built-ins, while trusted selected extension tools and explicit caller tool additions still activate. `skills: []` selects no separately named Role Skills, while trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. Ambient extension and Skill discovery is disabled in children. Selecting an extension explicitly is selecting a trusted atomic capability bundle, not just a provider path: every tool it registers and every Skill supplied through its Pi package metadata or dynamic `resources_discover` loads alongside separately named Role Skills. This is intentional because an extension may depend on its own tools, Skills, lifecycle, and prompt behavior; loading it permits that executable behavior and is not sandboxing. To scope a child, select fewer trusted extensions. Finer-grained selection requires separate extension entry points/configuration or an upstream split—pi-subagent does not infer or externally narrow undocumented dependencies. Parent-only recursive orchestration tools stay excluded. Explicit Role or caller tool names are verified against the child’s final filtered active registry after provider extensions finish `session_start`; all unavailable names fail before the first model turn with provider-extension guidance, while unavailable named Skills warn and skip.
+This is intentional. An extension may depend on its tools, Skills, lifecycle, and prompt behavior. Loading it permits that executable behavior and is not sandboxing.
+
+Scope a child by selecting fewer trusted extensions. Finer-grained selection requires separate extension entry points or configuration, or an upstream split. pi-subagent does not infer or externally narrow undocumented dependencies.
+
+### Tool filtering
+
+- `tools: []` activates no base built-ins. Trusted selected extension tools and explicit caller tool additions still activate.
+- `skills: []` selects no separately named Role Skills. Trusted selected extension Skills still load.
+- `extensions: []` selects no Role extension bundle.
+- Parent-only recursive orchestration tools and interactive `ask_question` are excluded from children.
+- Explicit Role or caller tool names are verified against the child’s final filtered active registry after provider extensions finish `session_start`.
+- Unavailable tool names fail before the first model turn with provider-extension guidance. Unavailable named Skills warn and skip.
 
 ## Library API
 
-The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support. It defaults to a 50-turn hard cap and rejects attempted continuation with `turn_limit` while preserving accumulated usage and bounded output. After Pi itself exits, it drains inherited stdout/stderr normally but destroys streams still held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
+The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, and worktree helpers.
+
+The executor is for code already running inside active Pi. It does not provide standalone Node.js Pi discovery or launch support.
+
+It defaults to a hard limit of 50 turns. An attempted continuation rejects with `turn_limit` while preserving accumulated usage and bounded output.
+
+After Pi exits, the executor drains inherited stdout and stderr normally. It destroys streams held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
+
+Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior.
 
-Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` with a caller-owned Model Task declaration against the latest Pi context.
+It includes a post-permit `prepare` example. The example uses `resolveRoleLaunch` with a caller-owned Model Task declaration against the latest Pi context.

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { type HerdrExecutor } from "@henryqw/pi-herdr";
 import { type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
@@ -60,40 +59,3 @@ export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: Pro
 export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
 export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
 export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
-export interface ManagedSubagentHost {
-    cwd: string;
-    workspaceId: string;
-}
-export interface ManagedSubagentCommandOptions {
-    cwd: string;
-}
-export type ManagedSubagentExecutor = HerdrExecutor<ManagedSubagentCommandOptions>;
-export interface ManagedSubagentHostOptions {
-    execute: ManagedSubagentExecutor;
-    delay?: (milliseconds: number) => Promise<void>;
-}
-export interface ManagedSubagentTab {
-    tabId: string;
-    paneId: string;
-}
-export declare function managedSubagentName(workspaceId: string, ...identity: string[]): string;
-export declare function managedSubagentWorkspaceId(cwd: string, mainPane: string, options: ManagedSubagentHostOptions): Promise<string>;
-/** Returns pane ID to Herdr status for agents owned by this workspace. */
-export declare function listManagedSubagents(host: ManagedSubagentHost, options: ManagedSubagentHostOptions): Promise<Map<string, string>>;
-export declare function createManagedSubagentTab(host: ManagedSubagentHost, cwd: string, launch: PiLaunch, label: string, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab>;
-export declare function reconcileManagedSubagentTab(host: ManagedSubagentHost, input: {
-    tabId?: string;
-    paneId?: string;
-    cwd: string;
-    launch: PiLaunch;
-    label: string;
-}, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab>;
-export declare function findManagedSubagentTab(host: ManagedSubagentHost, label: string, options: ManagedSubagentHostOptions): Promise<ManagedSubagentTab | undefined>;
-export declare function managedSubagentTabExists(host: ManagedSubagentHost, tabId: string, options: ManagedSubagentHostOptions): Promise<boolean>;
-export declare function reconcileManagedSubagentPane(host: ManagedSubagentHost, tabId: string, rootPaneId: string, cwd: string, launch: PiLaunch, label: string, options: ManagedSubagentHostOptions): Promise<string>;
-export declare function startManagedSubagent(host: ManagedSubagentHost, agent: string, pane: string, launch: PiLaunch, options: ManagedSubagentHostOptions, hooks?: {
-    beforeStart?: () => Promise<void>;
-    onStarted?: () => Promise<void>;
-}): Promise<"existing" | "started">;
-export declare function promptManagedSubagent(host: ManagedSubagentHost, agent: string, prompt: string | Record<string, unknown>, options: ManagedSubagentHostOptions): Promise<void>;
-export declare function retireManagedSubagentTab(host: ManagedSubagentHost, tabId: string, options: ManagedSubagentHostOptions): Promise<void>;

package/dist/index.js

@@ -1,9 +1,7 @@
-import { createHash } from "node:crypto";
 import { readFileSync, readdirSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { createHerdrClient, herdrCommandFailure, hasHerdrErrorCode, startPiAgent } from "@henryqw/pi-herdr";
 import { modelReference, orderedProfileRoutes, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, } from "./worktree.js";
@@ -197,231 +195,3 @@ export function resolveRoleLaunch(pi, ctx, input) {
         route: resolveConfiguredTaskRoute(ctx, input.task, input.agentDir),
     });
 }
-function launchEnvironmentArgs(launch) {
-    return Object.entries(launch.env).flatMap(([key, value]) => {
-        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== "string" || value.includes("\0")) {
-            throw new Error(`Invalid launch environment: ${key}`);
-        }
-        return ["--env", `${key}=${value}`];
-    });
-}
-export function managedSubagentName(workspaceId, ...identity) {
-    const parts = [nonEmptyString(workspaceId, "Herdr workspace id"), ...identity.map((part, index) => nonEmptyString(part, `Subagent identity ${index}`))];
-    if (!identity.length)
-        throw new Error("Managed Subagent identity is required");
-    return `subagent-${createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 23)}`;
-}
-export async function managedSubagentWorkspaceId(cwd, mainPane, options) {
-    const paneId = nonEmptyString(mainPane, "recorded main Herdr pane");
-    const pane = (await listPanes(cwd, options))
-        .map((entry, index) => object(entry, `Herdr pane ${index}`))
-        .find((entry) => entry.pane_id === paneId);
-    if (!pane)
-        throw new Error(`Recorded main Herdr pane is missing: ${paneId}`);
-    return nonEmptyString(pane.workspace_id, "recorded main Herdr workspace");
-}
-/** Returns pane ID to Herdr status for agents owned by this workspace. */
-export async function listManagedSubagents(host, options) {
-    const workspaceId = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
-    const response = object(await createHerdrClient(options.execute).json(["agent", "list"], { cwd: host.cwd }), "Herdr agent list response");
-    const result = object(response.result, "Herdr agent list result");
-    return new Map(array(result.agents, "Herdr agents").flatMap((entry, index) => {
-        const agent = object(entry, `Herdr agent ${index}`);
-        if (nonEmptyString(agent.workspace_id, `Herdr agent ${index} workspace`) !== workspaceId)
-            return [];
-        return [[
-                nonEmptyString(agent.pane_id, `Herdr agent ${index} pane`),
-                nonEmptyString(agent.agent_status, `Herdr agent ${index} status`),
-            ]];
-    }));
-}
-export async function createManagedSubagentTab(host, cwd, launch, label, options) {
-    const response = await createHerdrClient(options.execute).json([
-        "tab", "create", "--workspace", nonEmptyString(host.workspaceId, "recorded Herdr workspace"), "--cwd", cwd,
-        ...launchEnvironmentArgs(launch), "--label", nonEmptyString(label, "Herdr tab label"), "--no-focus",
-    ], { cwd: host.cwd });
-    const result = object(object(response, "Herdr tab response").result, "Herdr tab result");
-    return {
-        tabId: nonEmptyString(object(result.tab, "Herdr tab").tab_id, "Herdr tab id"),
-        paneId: nonEmptyString(object(result.root_pane, "Herdr root pane").pane_id, "Herdr root pane id"),
-    };
-}
-export async function reconcileManagedSubagentTab(host, input, options) {
-    if (input.tabId && input.paneId && await managedSubagentTabExists(host, input.tabId, options)) {
-        return { tabId: input.tabId, paneId: input.paneId };
-    }
-    return await findManagedSubagentTab(host, input.label, options)
-        ?? await createManagedSubagentTab(host, input.cwd, input.launch, input.label, options);
-}
-export async function findManagedSubagentTab(host, label, options) {
-    const workspaceId = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
-    const matches = (await listTabs(host.cwd, options))
-        .map((entry, index) => object(entry, `Herdr tab ${index}`))
-        .filter((tab, index) => nonEmptyString(tab.workspace_id, `Herdr tab ${index} workspace`) === workspaceId)
-        .filter((tab) => tab.label === label);
-    if (matches.length > 1)
-        throw new Error(`Multiple Herdr tabs match provisioning identity: ${label}`);
-    if (!matches.length)
-        return undefined;
-    const tabId = nonEmptyString(object(matches[0], "Herdr tab").tab_id, "Herdr tab id");
-    const panes = (await listPanes(host.cwd, options))
-        .filter((entry, index) => object(entry, `Herdr pane ${index}`).tab_id === tabId);
-    if (panes.length !== 1)
-        throw new Error(`Provisioned Herdr tab ${tabId} must contain exactly one root pane`);
-    return { tabId, paneId: nonEmptyString(object(panes[0], "Herdr pane").pane_id, "Herdr pane id") };
-}
-export async function managedSubagentTabExists(host, tabId, options) {
-    const expected = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
-    const id = nonEmptyString(tabId, "Herdr tab id");
-    const tab = (await listTabs(host.cwd, options))
-        .map((entry, index) => object(entry, `Herdr tab ${index}`))
-        .find((entry) => entry.tab_id === id);
-    if (!tab)
-        return false;
-    const actual = nonEmptyString(tab.workspace_id, `Herdr tab ${id} workspace`);
-    if (actual !== expected)
-        throw new Error(`Herdr tab ${id} belongs to workspace ${actual}, expected initiating workspace ${expected}`);
-    return true;
-}
-export async function reconcileManagedSubagentPane(host, tabId, rootPaneId, cwd, launch, label, options) {
-    const tab = nonEmptyString(tabId, "Herdr tab id");
-    const workspace = nonEmptyString(host.workspaceId, "recorded Herdr workspace");
-    const ownerTab = (await listTabs(host.cwd, options))
-        .map((entry, index) => object(entry, `Herdr tab ${index}`))
-        .find((entry) => entry.tab_id === tab);
-    if (!ownerTab)
-        throw new Error(`Herdr tab is missing: ${tab}`);
-    const ownerWorkspace = nonEmptyString(ownerTab.workspace_id, `Herdr tab ${tab} workspace`);
-    if (ownerWorkspace !== workspace)
-        throw new Error(`Herdr tab ${tab} belongs to workspace ${ownerWorkspace}, expected initiating workspace ${workspace}`);
-    const root = nonEmptyString(rootPaneId, "Herdr root pane");
-    const panes = (await listPanes(host.cwd, options)).map((entry, index) => object(entry, `Herdr pane ${index}`));
-    const owner = panes.find((pane) => pane.pane_id === root);
-    if (!owner)
-        throw new Error(`Herdr root pane is missing: ${root}`);
-    if (owner.tab_id !== tab)
-        throw new Error(`Herdr root pane ${root} does not belong to tab ${tab}`);
-    const siblings = panes.filter((pane) => pane.tab_id === tab && pane.pane_id !== root);
-    const named = siblings.filter((pane) => pane.label === label);
-    if (named.length > 1)
-        throw new Error(`Multiple Herdr panes match provisioning identity: ${label}`);
-    if (named.length)
-        return nonEmptyString(named[0].pane_id, "Herdr Subagent pane id");
-    if (siblings.length > 1)
-        throw new Error(`Provisioned Herdr tab ${tab} has multiple Subagent panes`);
-    if (siblings.length)
-        return nonEmptyString(siblings[0].pane_id, "Herdr Subagent pane id");
-    const herdr = createHerdrClient(options.execute);
-    const response = await herdr.json([
-        "pane", "split", "--pane", root, "--direction", "right", "--cwd", cwd,
-        ...launchEnvironmentArgs(launch), "--no-focus",
-    ], { cwd: host.cwd });
-    const result = object(object(response, "Herdr pane response").result, "Herdr pane result");
-    const pane = nonEmptyString(object(result.pane, "Herdr Subagent pane").pane_id, "Herdr Subagent pane id");
-    await herdr.run(["pane", "rename", pane, nonEmptyString(label, "Herdr pane label")], { cwd: host.cwd });
-    return pane;
-}
-export async function startManagedSubagent(host, agent, pane, launch, options, hooks = {}) {
-    assertAgentName(agent);
-    const name = nonEmptyString(agent, "Herdr agent name");
-    const paneId = nonEmptyString(pane, "Herdr agent pane");
-    const existing = await getManagedSubagent(host, name, options);
-    if (existing) {
-        assertAgentPane(name, paneId, existing);
-        return "existing";
-    }
-    await hooks.beforeStart?.();
-    const herdr = createHerdrClient(options.execute);
-    const startArgs = ["agent", "start", name, "--kind", "pi", "--pane", paneId, "--", ...launch.args];
-    const result = await startPiAgent(herdr, {
-        name,
-        pane: paneId,
-        args: launch.args,
-        options: { cwd: host.cwd },
-        delay: options.delay,
-    });
-    if (result.code === 0 && !result.killed) {
-        await hooks.onStarted?.();
-        return "started";
-    }
-    if (hasHerdrErrorCode(result, "agent_name_taken")) {
-        const raced = await getManagedSubagent(host, name, options);
-        if (!raced)
-            throw new Error(`Herdr agent ${name} reported agent_name_taken but could not be found; refusing to start a duplicate`);
-        assertAgentPane(name, paneId, raced);
-        return "existing";
-    }
-    throw new Error(herdrCommandFailure(startArgs, result));
-}
-export async function promptManagedSubagent(host, agent, prompt, options) {
-    assertAgentName(agent);
-    const text = typeof prompt === "string" ? nonEmptyString(prompt, "Subagent prompt") : JSON.stringify(prompt);
-    await createHerdrClient(options.execute).run(["agent", "prompt", agent, text], { cwd: host.cwd });
-}
-export async function retireManagedSubagentTab(host, tabId, options) {
-    const id = nonEmptyString(tabId, "Herdr tab id");
-    try {
-        if (!(await managedSubagentTabExists(host, id, options)))
-            return;
-        await createHerdrClient(options.execute).run(["tab", "close", id], { cwd: host.cwd });
-    }
-    catch (error) {
-        if (!(await confirmsTabAbsent(host, id, options)))
-            throw error;
-    }
-}
-function assertAgentName(agent) {
-    if (!/^[a-z][a-z0-9_-]{0,31}$/.test(agent))
-        throw new Error(`Invalid Herdr agent name: ${agent}`);
-}
-function object(value, label) {
-    if (!value || typeof value !== "object" || Array.isArray(value))
-        throw new Error(`${label} must be an object`);
-    return value;
-}
-function array(value, label) {
-    if (!Array.isArray(value))
-        throw new Error(`${label} must be an array`);
-    return value;
-}
-function nonEmptyString(value, label) {
-    if (typeof value !== "string")
-        throw new Error(`${label} must be a string`);
-    if (!value.trim() || value.includes("\0"))
-        throw new Error(`${label} must not be empty`);
-    return value;
-}
-async function listTabs(cwd, options) {
-    const response = await createHerdrClient(options.execute).json(["tab", "list"], { cwd });
-    return array(object(object(response, "Herdr tab list response").result, "Herdr tab list result").tabs, "Herdr tabs");
-}
-async function listPanes(cwd, options) {
-    const response = await createHerdrClient(options.execute).json(["pane", "list"], { cwd });
-    return array(object(object(response, "Herdr pane list response").result, "Herdr pane list result").panes, "Herdr panes");
-}
-async function getManagedSubagent(host, name, options) {
-    const arguments_ = ["agent", "get", name];
-    const result = await createHerdrClient(options.execute).exec(arguments_, { cwd: host.cwd });
-    if (result.code !== 0 || result.killed) {
-        if (hasHerdrErrorCode(result, "agent_not_found"))
-            return undefined;
-        throw new Error(herdrCommandFailure(arguments_, result));
-    }
-    const response = object(JSON.parse(result.stdout), "Herdr agent get response");
-    return object(object(response.result, "Herdr agent get result").agent, `Herdr agent ${name}`);
-}
-function assertAgentPane(name, expected, agent) {
-    const actual = typeof agent.pane_id === "string" ? agent.pane_id : "missing";
-    if (actual !== expected) {
-        throw new Error(`Herdr agent name collision for ${name}: expected pane ${expected}, found ${actual}; refusing to reuse or replace it`);
-    }
-}
-async function confirmsTabAbsent(host, tabId, options) {
-    try {
-        const result = await createHerdrClient(options.execute).exec(["tab", "get", tabId], { cwd: host.cwd });
-        return !result.killed && result.code !== 0 && hasHerdrErrorCode(result, "tab_not_found");
-    }
-    catch {
-        return false;
-    }
-}

package/docs/orchestration.md

@@ -262,8 +262,6 @@ Activity text is limited to 4 KiB per field. An invalid `toolCallId` or `toolNam
 
 The low-level executor does not interpret `Role.isolation`, discover resources, compose modes, create shared state, or promote child failure outcomes to tool errors. A direct caller that wants worktrees must call `createChildWorktree` after the permit, choose the returned `cwd`, call `finalizeChildWorktree` on every exit path, and preserve its recovery payload.
 
-Generic managed Herdr exports (`managedSubagentWorkspaceId`, reconciliation helpers, `startManagedSubagent`, prompting/listing, and retirement) consume the same launch policy for durable workers. They intentionally contain no workflow prompts, semantic state, or retry policy.
-
 ## JavaScript composition
 
 The examples below use caller-selected `Role` objects and the `runRole` function returned by the package's initializer. A consuming Pi extension calls the initializer once at startup:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "8.0.0",
+  "version": "9.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -14,14 +14,14 @@
   },
   "license": "MIT",
   "files": [
+    "LICENSE",
     "dist",
     "extensions",
     "docs",
     "examples",
     "skills",
     "README.md",
-    "CONTEXT.md",
-    "LICENSE"
+    "CONTEXT.md"
   ],
   "types": "./dist/index.d.ts",
   "exports": {
@@ -64,7 +64,6 @@
     ]
   },
   "dependencies": {
-    "@henryqw/pi-herdr": "^0.4.0",
     "@henryqw/pi-multi-codex": "^0.3.8",
     "@henryqw/pi-task-models": "^3.0.0"
   }