pi-herdr-agents 0.1.3 → 1.0.0

package/AGENTS.md

@@ -4,7 +4,7 @@ These instructions apply to humans and coding agents changing `pi-herdr-agents`.
 
 ## What this package is
 
-`pi-herdr-agents` (Pi Herdr Agents) is a Pi extension that launches asynchronous child agents and approved read-only review workflows exclusively in Herdr. Ordinary runs use dedicated Herdr panes/tabs. Writing tasks may opt into one isolated Herdr-managed Git worktree per branch.
+`pi-herdr-agents` (Pi Herdr Agents) is a Pi extension that launches asynchronous Pi child agents and approved read-only review workflows exclusively in Herdr. Ordinary runs use dedicated Herdr panes/tabs. Writing tasks may opt into one isolated Herdr-managed Git worktree per branch. Legacy role definitions that request an external CLI fail before Herdr creates resources.
 
 The extension is fire-and-forget: `subagent` returns an acknowledgement, and completion is delivered to the parent automatically. Never add polling guidance that tells callers to sleep, tail sessions, or repeatedly check status.
 
@@ -93,6 +93,8 @@ Run LSP diagnostics on every changed TypeScript file; lint and tests do not catc
 
 For Herdr or lifecycle changes, run the deterministic suite from inside Herdr. Run only one integration suite at a time on a Herdr instance; concurrent suites compete for terminal focus and process capacity and can cause false timeouts or leaked test resources.
 
+When a test reports that a `pi-integ-*` worktree path already exists, first check whether the same test already created that worktree and the deterministic provider dispatched the tool twice after asynchronous completion. Deterministic providers must make each requested tool call one-shot after its started result appears. Remove only verified test-owned residue after confirming that no workspace or process owns it.
+
 ```bash
 npm run test:integration
 ```

package/CONTEXT.md

@@ -17,24 +17,16 @@ The JSON block at the start of a workflow script that the runner parses and vali
 _Avoid_: Evaluated metadata, inferred policy
 
 **Approved runtime**:
-A mandatory exact `provider/model` reference and thinking level declared in workflow metadata; every execution node must resolve to one of these approved runtimes. Missing values fail preparation rather than inheriting parent or role defaults. The first workflow supports Pi-backed agents only; existing public Claude subagents remain unchanged.
-_Avoid_: Runtime tiers, silent fallback, inherited runtime, v1 Claude workflow adapter
+A mandatory exact `provider/model` reference and thinking level declared in workflow metadata; every execution node must resolve to one of these approved runtimes. Missing values fail preparation rather than inheriting parent or role defaults. All subagent and workflow execution is Pi-backed.
+_Avoid_: Runtime tiers, external CLI adapter, silent fallback, inherited runtime
 
-**External CLI runtime adapter**:
-A runtime-specific module selected by a known local role `cli` value. The MVP dispatches `cli: claude` to the built-in Claude adapter; a future registry needs a proven second CLI.
-_Avoid_: Raw flag template, plugin system before a second CLI
+**Pi subagent runtime**:
+The single execution path for fresh and resumed children. `launchPiSubagent()` owns the complete Pi and Herdr launch transaction; completion uses Pi sidecar evidence first and the terminal exit marker as fallback.
+_Avoid_: Runtime dispatch, adapter registry, split launch ownership
 
-**Adapter permission policy**:
-The runtime adapter owns its fixed vendor flags for the MVP. A local role selects the CLI, not raw flags or a policy profile.
-_Avoid_: Implied permission bypass, raw flag values
-
-**Adapter seam**:
-`index.ts` retains pane, worktree, lifecycle, and delivery ownership. The Claude adapter owns Claude command construction, completion/result extraction, transcript copying, and workspace cleanup.
-_Avoid_: Vendor behavior in the shared lifecycle
-
-**Runtime dispatch**:
-The core validates a role's `cli` value before pane creation and dispatches each known value to its internal adapter. The MVP recognizes `claude` only; unknown values fail closed.
-_Avoid_: Silent Pi fallback, speculative runtime registry
+**Legacy external CLI role**:
+An old role definition that contains `cli`. Discovery reports a migration diagnostic, and launch fails before Herdr creates a pane or worktree. Remove `cli` and `cli-model`, then select the model through Pi provider/model routing.
+_Avoid_: Silent Pi reinterpretation, compatibility adapter
 
 **Run journal**:
 The runner-owned append-only `run.jsonl` that starts with approval binding the workflow-script hash, canonical repository identity, and committed base, then records observed node calls and results. Exactly one terminal event contains the bounded runtime envelope; a following delivery event references it without duplicating the task result.

package/README.md

@@ -65,7 +65,7 @@ Use `pi install -l npm:pi-herdr-agents` for a project-local installation, or try
 pi -e npm:pi-herdr-agents
 ```
 
-Pi packages execute with your user account's full system access. Review the package source before installation. A locally installed Claude CLI adapter launches with `--dangerously-skip-permissions`, so those runs skip Claude's interactive permission prompts.
+Pi packages execute with your user account's full system access. Review the package source before installation.
 
 After the one-time first-package bootstrap, changing the `package.json` version on `main` automatically publishes to npm and creates the matching Git tag and GitHub Release. For bootstrap authentication, versioning, verification, and troubleshooting, see [RELEASING.md](RELEASING.md).
 
@@ -136,9 +136,8 @@ This package uses five distinct concepts:
   artifacts, and runtime policy.
 - A **skill** is a Pi-native procedure loaded into the current agent. Skills are
   dependencies of roles or workflows, not subagent definitions.
-- A **runtime** is how an invocation executes: Pi or an external CLI, plus its
-  model and thinking policy.
-- An **adapter** is a hidden runtime-specific definition supplied locally or optionally used by a workflow.
+- A **runtime** is the authenticated Pi provider/model and thinking policy used
+  for one invocation.
 
 See [ADR-0002](docs/adr/0002-agent-workflow-skill-runtime-taxonomy.md) for the
 accepted decision, rationale, migration boundaries, and evidence.
@@ -165,13 +164,10 @@ The current workflow inventory is:
 | **poteto** | Coordinator agent role | Config, then parent | Autonomously investigates, edits minimally, delegates independent work, and verifies. |
 | **adversarial-reviewer** | Transitional workflow implementation | Three distinct authenticated Pi model IDs, preferring provider diversity | Runs evidence-backed Optimizer and Skeptic review passes through generic `reviewer` children. |
 
-Bundled definitions are portable Pi roles. Vendor-specific external CLI adapters
-are local or optional definitions, not bundled roles. The existing external CLI
-path supports a local hidden Claude adapter (`cli: claude`) and always adds
-`--dangerously-skip-permissions`; it does not provide an adapter registry or
-Cursor/OpenCode support. Put an adapter in
-`$PI_CODING_AGENT_DIR/agents/` or `.pi/agents/` with
-`disable-model-invocation: true` when direct exact-name invocation needs it.
+All subagents execute through Pi. Claude models remain available through normal
+Pi provider/model routing. Legacy role definitions that contain `cli` fail before
+Herdr creates a pane or worktree; remove `cli` and `cli-model`, then select an
+authenticated Pi `provider/model-id`.
 
 Optional prerequisites fail closed and are not bundled:
 
@@ -223,7 +219,7 @@ Multiple subagents run concurrently — each steers its result back independentl
 ╰─────────────────────────────────────────────────────────╯
 ```
 
-Completion messages render with a colored background and are expandable with `Ctrl+O`. Results larger than 16,000 characters are abbreviated in the parent context while preserving their beginning, conclusion, and session path; the complete result remains in the child session. The extension includes that bounded result directly in the user message that wakes Pi, avoiding empty turns caused by a separate context-free follow-up. Completed rows are removed from the widget as soon as their result is delivered or suppressed.
+Completion messages render with a colored background and are expandable with `Ctrl+O`. Results larger than 16,000 characters are abbreviated in the parent context while preserving their beginning, conclusion, and session path; the complete result remains in the child session. The extension includes that bounded result and a continuation instruction directly in the single custom `subagent_result` message that triggers or steers Pi, avoiding empty turns caused by a separate context-free wake-up. The renderer uses the unadorned bounded result from structured details. Completed rows are removed from the widget as soon as their result is delivered or suppressed.
 
 ### In-progress status updates
 
@@ -357,10 +353,9 @@ subagent({
 | `agent`                | string  | —              | Load defaults from agent definition                                                               |
 | `fork`                 | boolean | `false`        | Force the full-context fork mode for this spawn, overriding any agent `session-mode` frontmatter  |
 | `interactive`          | boolean | derived        | Mark this spawn as interactive (don't wake the parent on stall/recovery). Defaults to the agent's `interactive` frontmatter, otherwise the inverse of `auto-exit`. |
-| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, or an ordered comma-separated Pi fallback list; unavailable for Claude CLI and worktree spawns. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
+| `model`                | string  | configured or parent | Exact authenticated `provider/model-id`, or an ordered comma-separated Pi fallback list; fallback lists are unavailable for worktree spawns. Resolution is tool argument → agent frontmatter → per-agent config → global config → parent |
 | `thinking`             | string  | parent level   | Pi thinking level (`off` through `max`); omit to inherit the parent                                |
-| `systemPrompt`         | string  | —              | Role/system-prompt text for a bare spawn; overrides the body for Claude CLI agents, while named Pi agents keep their definition body |
-| `resumeSessionId`      | string  | —              | Claude CLI session ID to resume; separate from the Pi `subagent_resume` tool                       |
+| `systemPrompt`         | string  | —              | Role/system-prompt text for a bare spawn; named agents keep their definition body                  |
 | `skills`               | string  | —              | Comma-separated skill names                                                                       |
 | `tools`                | string  | —              | Comma-separated tool names                                                                        |
 | `cwd`                  | string  | —              | Working directory, or source repository when `worktree` is set (see [Role Folders](#role-folders)) |
@@ -370,6 +365,8 @@ subagent({
 
 Use one worktree per independent writing task; keep read-only agents in ordinary panes. `cwd` selects the source Git repository, `branch` must be unique, and `base` is resolved to an exact commit before creation. If `base` is omitted, the source checkout's committed `HEAD` is used. Parent-checkout changes that have not been committed are not copied.
 
+A launch with `worktree` and an effective bundled `scout`, `reviewer`, or `adversarial-reviewer` returns a non-blocking warning. Scouts and reviewers normally need an ordinary pane; the adversarial reviewer is a coordinator that normally uses an ordinary pane for its review artifacts and child reviewers. To inspect or review an existing worker result, start an ordinary child in that retained worktree path. Project or global role overrides do not receive these bundled-role warnings.
+
 The child starts at the returned worktree root. Tell writing agents to test and commit when you want a commit-based handoff, and tell them not to push, merge, switch branches, or remove the worktree. The parent owns review and integration.
 
 Successful, failed, and help-requesting runs retain their workspace. Completion includes the worktree path, Herdr workspace, branch, base/head SHAs, commits ahead, changed and untracked files, and clean/dirty/conflicted state. Here, `clean` means no uncommitted files; the branch may still contain commits. If Git inspection fails, state is reported as unknown rather than guessed.
@@ -394,8 +391,6 @@ This sends Escape to the child pane, cancelling the in-progress model turn. The
 
 This is a turn-level interrupt, not a method for forcibly terminating a subagent session.
 
-> **Note:** Only Pi-backed subagents are supported. Claude-backed runs will return an error.
-
 ---
 
 ## Workflow control (`herdr_workflow`)
@@ -685,10 +680,8 @@ and verify them with `/subagent list` plus a smoke launch.
 | `name`        | string  | Optional explicit agent name used in `agent: "my-agent"`; defaults to the filename stem and must match it in role packs                                                                                                                                                                                            |
 | `description` | string  | Shown in `subagents_list` output                                                                                                                                                                                                                                            |
 | `model`       | string  | Optional exact authenticated Pi model default or ordered comma-separated fallback list; omit to use per-agent config, global config, then the parent                                                                                                                       |
-| `cli`         | string  | Set to `claude` to launch the Claude CLI instead of Pi                                                                                                                                                                                                                       |
-| `cli-model`   | string  | Optional model name passed to a Claude CLI agent; separate from Pi model routing                                                                                                                                                                             |
-| `thinking`    | string  | Optional Pi thinking default (`off` through `max`); omit to inherit the parent. Thinking overrides are not supported for Claude CLI agents                                                                                                                                   |
-| `system-prompt` | string | `append` passes the agent body through Pi's appended system prompt; `replace` replaces Pi's default system prompt. Without this field, the body is included in the task wrapper. Claude CLI agents always append their body/override                                                                                                                                                                                                                                 |
+| `thinking`    | string  | Optional Pi thinking default (`off` through `max`); omit to inherit the parent                                                                                                                                   |
+| `system-prompt` | string | `append` passes the agent body through Pi's appended system prompt; `replace` replaces Pi's default system prompt. Without this field, the body is included in the task wrapper                                                                                                                                                                                                                                 |
 | `tools`       | string  | Comma-separated Pi `--tools` allowlist; may contain any registered built-in, extension, or custom tool name                                                                                                                                                                 |
 | `skills`      | string  | Comma-separated installed skill names to auto-load. Use this plural form for new definitions; legacy project/global definitions using singular `skill` remain compatible. |
 | `session-mode` | string | Default child-session mode: `standalone`, `lineage-only`, or `fork` |
@@ -697,7 +690,7 @@ and verify them with `/subagent list` plus a smoke launch.
 | `auto-exit`   | boolean | Auto-shutdown when the agent finishes its turn — no `subagent_done` call needed. If the user sends any input, auto-exit is permanently disabled and the user takes over the session. Recommended for autonomous agents (scout, worker); not for interactive ones (planner). Also determines the default value of `interactive` (see below). |
 | `interactive` | boolean | Override whether stall/recovery transitions wake the parent session. Defaults to the inverse of `auto-exit`: autonomous agents (`auto-exit: true`) are non-interactive and get stall pings; agents without `auto-exit` are interactive and stay quiet. Explicit values take precedence. |
 | `cwd`         | string  | Default working directory. Absolute paths are unambiguous; relative agent-frontmatter paths resolve from Pi's agent config directory (`PI_CODING_AGENT_DIR` or `~/.pi/agent`), not the project root                                                                                                                                                                                                            |
-| `disable-model-invocation` | boolean | Hide an internal adapter from discovery surfaces like `subagents_list`. The definition remains directly invocable by exact name via `subagent({ agent: "name", ... })`. |
+| `disable-model-invocation` | boolean | Hide a role from discovery surfaces like `subagents_list`. The definition remains directly invocable by exact name via `subagent({ agent: "name", ... })`. |
 
 ---
 
@@ -865,7 +858,7 @@ herdr
 pi
 ```
 
-Other multiplexers and terminal backends are not supported. Worktrees provide Git checkout isolation only, not process or security isolation; child agents and installed Pi packages run with your user's filesystem and command permissions. Locally configured Claude CLI adapters always launch with `--dangerously-skip-permissions` and therefore skip Claude's interactive permission prompts.
+Other multiplexers and terminal backends are not supported. Worktrees provide Git checkout isolation only, not process or security isolation; child agents and installed Pi packages run with your user's filesystem and command permissions.
 
 ---
 

package/agents/scout.md

@@ -2,7 +2,6 @@
 name: scout
 description: Fast codebase reconnaissance - maps existing code, conventions, and patterns for a task
 tools: read, bash
-deny-tools: claude
 spawning: false
 auto-exit: true
 system-prompt: append

package/agents/worker.md

@@ -2,7 +2,6 @@
 name: worker
 description: Implements a complete task or plan section - writes code, runs tests, commits only when asked
 tools: read, bash, write, edit
-deny-tools: claude
 spawning: false
 auto-exit: true
 system-prompt: append

package/docs/README.md

@@ -26,12 +26,13 @@ Workflow preparation, exact approval, Worker execution, isolated read-only child
 | ADR | Status | Decision |
 | --- | --- | --- |
 | [`0001`](adr/0001-btw-ephemeral-side-questions.md) | Accepted | Add `/btw` as an ephemeral side-question child. |
-| [`0002`](adr/0002-agent-workflow-skill-runtime-taxonomy.md) | Accepted | Keep agent execution, workflows, skills, and runtimes distinct. |
+| [`0002`](adr/0002-agent-workflow-skill-runtime-taxonomy.md) | Accepted in part; external CLI provisions superseded | Keep agent execution, workflows, skills, and Pi runtimes distinct. |
 | [`0003`](adr/0003-installable-role-packs.md) | Accepted | Discover installable role packs through Pi's event bus. |
 | [`0004`](adr/0004-require-active-user-approval-for-workflow-execution.md) | Accepted | Require active approval for exact workflow-script execution. |
 | [`0005`](adr/0005-parent-owns-workflow-script-authority.md) | Accepted | Keep workflow-script authority with the parent. |
 | [`0006`](adr/0006-limit-v1-execution-effects-to-isolated-worktrees.md) | Accepted | Limit the first workflow to read-only effects. |
 | [`0007`](adr/0007-require-fresh-review-for-workflow-scripts.md) | Accepted | Require fresh review in skill-authored review workflows. |
+| [`0008`](adr/0008-adopt-pi-only-subagent-execution.md) | Accepted; implemented | Remove the external CLI adapter and make subagent execution Pi-only. |
 
 ## Research
 

package/docs/adr/0002-agent-workflow-skill-runtime-taxonomy.md

@@ -1,10 +1,11 @@
 # ADR-0002: Adopt the agent, workflow, skill, and runtime taxonomy
 
-- **Status:** Accepted
+- **Status:** Accepted in part; external CLI provisions superseded
 - **Date:** 2026-08-02
 - **Decision owners:** `acrnm`
 - **Scope:** `giuseppecrj/pi-herdr-agents`
 - **Historical tracking:** legacy issues #4 and #5 (not carried into the clean repository)
+- **Superseded in part by:** ADR-0008 removes the external CLI runtime adapter
 
 ## Decision
 
@@ -22,10 +23,8 @@ Use these terms consistently:
 - **Skill** — A Pi-native instruction set that teaches the current agent a
   reusable procedure. It may invoke workflows or roles. Owned by Pi or the
   skill author and user-facing.
-- **Runtime** — How a role executes: Pi or an external CLI, plus model and
-  thinking selection. Owned by invocation/configuration and not user-facing.
-- **Adapter** — A local or optional runtime-specific role for direct invocation.
-  Owned by the caller or local configuration and not user-facing.
+- **Runtime** — The authenticated Pi provider/model and thinking selection for
+  one invocation. Owned by invocation/configuration and not user-facing.
 
 An agent role is **not** a workflow merely because it can spawn other agents.
 A coordinator role is allowed when it owns an interactive or multi-stage child
@@ -39,8 +38,8 @@ surface:
 - Agent definitions are discovered from package, global, and project folders,
   with project definitions overriding global and bundled definitions.
 - The bundled list includes reusable roles (`scout`, `worker`, `reviewer`) and
-  a multi-stage orchestration (`adversarial-reviewer`). Runtime-specific
-  implementations are local optional adapters, not bundled definitions.
+  a multi-stage orchestration (`adversarial-reviewer`). Every definition runs
+  through Pi.
 - The extension can request Pi skills, select model defaults, and start
   sessions, but it has no first-class workflow definition or agent-definition
   schema validation.
@@ -130,42 +129,34 @@ the package's `/plan` workflow, not as a second kind of subagent definition.
 
 ### 4. Runtimes are selected by policy, not role identity
 
-A role describes the work; a runtime describes how one invocation performs it.
-For Pi-backed agents, the current model-resolution chain is the correct
-foundation: explicit invocation choice, agent default, per-agent configuration,
-global configuration, then the parent model. A local Claude CLI adapter instead
-uses `cli` and `cli-model`; do not set a Pi `model` on an adapter expecting it
-to select the CLI model.
+A role describes the work; a runtime describes which authenticated Pi
+provider/model and thinking level one invocation uses. The model-resolution
+chain is explicit invocation choice, agent default, per-agent configuration,
+global configuration, then the parent model.
 
 Apply these rules:
 
 1. Prefer per-invocation `model` and `thinking` for a workflow's deliberate
    diversity or cost/quality policy.
 2. Use ignored local `config.json` for a person's durable role preferences.
-3. Leave bundled Pi-role `model` unset unless a particular model is a functional
+3. Leave bundled role `model` unset unless a particular model is a functional
    prerequisite.
-4. Treat `cli` and `cli-model` as a runtime adapter concern, not a review or
-   planning policy.
-5. State runtime prerequisites before launch and fail closed when a required
-   runtime is unavailable.
+4. State runtime prerequisites before launch and fail closed when a required
+   Pi runtime is unavailable.
+5. Reject legacy role definitions that contain `cli` before Herdr resource
+   creation; do not reinterpret them as Pi roles.
 
 This preserves the useful multi-model review behavior without baking a
 particular vendor choice into the generic `reviewer` role. Adversarial review
 selects three distinct exact authenticated Pi model IDs at runtime, preferring
 provider diversity, and launches generic `reviewer` children.
 
-### 5. Local adapters are hidden from task discovery
+### 5. Subagent execution is Pi-only
 
-An adapter exists to satisfy a workflow's runtime contract, not to ask a user
-what they want to do. It is a local or optional definition, must use
-`disable-model-invocation: true`, and should have a name that makes its internal
-nature clear. Hidden adapters remain explicitly invokable by exact name.
-
-The package preserves its existing external CLI launch path for local adapters;
-it does not bundle vendor-specific adapters, provide an adapter registry, or add
-Cursor/OpenCode support. Move callers that invoke `claude-reviewer` by exact
-name to `$PI_CODING_AGENT_DIR/agents/claude-reviewer.md` or
-`.pi/agents/claude-reviewer.md` with the same hidden frontmatter.
+Every visible or hidden role executes through Pi. Claude models remain available
+through normal Pi provider/model routing. A legacy role that contains `cli`
+receives a migration diagnostic and cannot create a Herdr pane or worktree.
+There is no runtime adapter registry or compatibility path.
 
 ### 6. Agent frontmatter is a constrained contract
 
@@ -182,10 +173,9 @@ validation that does not exist yet.
 For a future validation pass, require at least `name` and `description`, reject
 unknown package-owned fields, validate tool/skill list syntax, and report the
 source path in errors. The authoring template must cover the complete existing
-README frontmatter reference (`tools`, `deny-tools`, `thinking`, `system-prompt`,
-`spawning`, `auto-exit`, `interactive`, `session-mode`, `cwd`, `cli`,
-`cli-model`, and `disable-model-invocation`) rather than introduce a partial
-second schema. Keep extension fields separate from arbitrary prompt metadata so
+README frontmatter reference (`tools`, `deny-tools`, `thinking`, `system-prompt`, `spawning`, `auto-exit`,
+`interactive`, `session-mode`, `cwd`, and `disable-model-invocation`) rather
+than introduce a partial second schema. Keep extension fields separate from arbitrary prompt metadata so
 project authors can still add their own namespaced fields.
 
 ## Current mapping
@@ -199,8 +189,8 @@ project authors can still add their own namespaced fields.
   engineering responsibility remains intentional.
 - `visual-tester` — Leaf agent role with skill prerequisite. Keep its
   `chrome-cdp` dependency declared through canonical `skills` metadata.
-- `claude-reviewer` — No longer bundled. Callers that need this exact local
-  Claude CLI adapter must provide it in a global or project agent directory.
+- `claude-reviewer` — Removed. Use the generic `reviewer` role with an
+  authenticated Claude model through Pi provider/model routing.
 - `adversarial-reviewer` — Workflow implementation pending a workflow surface.
   It selects three distinct exact authenticated Pi model IDs at runtime,
   preferring provider diversity, and launches generic `reviewer` children. Do
@@ -228,8 +218,8 @@ not a general workflow registry.
    policy in one place. Adversarial review selects three distinct exact
    authenticated Pi model IDs at runtime, prefers provider diversity, and uses
    generic `reviewer` children.
-5. Remove bundled `claude-reviewer`; exact-name callers supply the hidden local
-   adapter from their global or project agent directory.
+5. Remove bundled `claude-reviewer`; callers use the generic `reviewer` role
+   with Pi provider/model routing.
 
 ### Phase 2 — improve discovery without a new framework
 
@@ -251,7 +241,7 @@ language before that repeated need exists.
 
 - A user can distinguish a workflow from a directly runnable role before
   launching either.
-- `subagents_list` does not advertise internal runtime adapters as peer tasks.
+- Legacy external CLI roles fail with a migration diagnostic before launch.
 - A role author can create and smoke-test a valid definition from one documented
   template; schema-level frontmatter errors remain a deferred validation pass.
 - A workflow can select different authenticated runtimes per child without
@@ -271,4 +261,4 @@ This decision is based on the current implementation:
   defaults; launch-time arguments remain the appropriate workflow override.
 - `README.md` documents `/plan`, `/iterate`, `/btw`, agent discovery,
   frontmatter, and runtime precedence.
-- `agents/` contains the mixed role/coordinator/adapter set mapped above.
+- `agents/` contains the role/coordinator set mapped above.

package/docs/adr/0008-adopt-pi-only-subagent-execution.md

@@ -0,0 +1,22 @@
+# ADR-0008: Adopt Pi-only subagent execution
+
+- **Status:** Accepted (implemented)
+- **Date:** 2026-08-10
+- **Scope:** `giuseppecrj/pi-herdr-agents`
+- **Supersedes:** The external CLI runtime-adapter provisions of ADR-0002
+
+## Decision
+
+Make every public subagent run Pi-backed. Remove the Claude terminal adapter and its `cli`, `cli-model`, and `resumeSessionId` interface fields. Existing role files that request an external CLI must fail with a clear error instead of silently running through Pi.
+
+A single deep launch module will own the complete launch transaction behind one small interface. Pi and Herdr remain implementation details of that module; do not add a runtime adapter seam without a second real execution path.
+
+Completion delivery will use one custom message whose content contains the bounded result and triggers the parent turn. Completion detection will keep the Pi sidecar as primary evidence and the terminal exit marker as its best-effort fallback.
+
+## Why
+
+The Claude terminal path duplicates launch, completion, transcript, cleanup, status, resume, and interruption behavior. It also requires `--dangerously-skip-permissions`, has no bundled role, and reduces locality and test leverage. Pi already provides Claude models through normal provider/model routing.
+
+## Consequences
+
+This is an immediate pre-1.0 breaking change; no deprecation adapter remains. The agent/workflow/skill/runtime taxonomy in ADR-0002 remains accepted, but its external CLI adapter rules no longer apply. Shipped-behavior documentation and `CONTEXT.md` now describe the Pi-only contract.

package/docs/orchestrated-review-workflow-plan.md

@@ -417,7 +417,7 @@ All slices are sequential because they touch the same runtime and lifecycle seam
 
 - Metadata header must be first, valid JSON, version 1, strict, and within hard caps.
 - Paths outside `.pi/plans/<run>/workflow.js`, symlinks, reused journals, and missing files fail.
-- Unknown, duplicate, Claude-backed, unauthenticated, or non-review roles fail.
+- Unknown, duplicate, legacy external-CLI, unauthenticated, or non-review roles fail.
 - Script syntax failure does not evaluate code.
 - Prepare records exact bytes, full hash, base SHA, session identity/leaf, role-policy fingerprints, runtimes, and effective tools in pending memory without creating the journal.
 - A matching later user message in the same session starts; assistant text, pre-prepare or other-session user text, malformed text, uppercase/short/long prefixes, and surrounding whitespace fail.

package/docs/worktree-subagents.md

@@ -121,7 +121,27 @@ The parent receives the normal child summary plus:
 
 `clean` means there are no staged, unstaged, or untracked files. It does **not** mean the branch has no commits or diff relative to its base.
 
-If Git inspection fails, SHA/count/state/file fields are reported as unknown rather than guessed, and the warning is included in the handoff. Inspect the retained workspace directly before integrating or deleting it.
+If Git inspection fails, SHA/count/state/file fields are reported as unknown rather than guessed, and the warning is included in the handoff. Inspect the retained workspace directly before integrating or deleting it. Every retained handoff also includes the exact `herdr worktree remove --workspace <workspace-id>` command, but run it only after useful state is preserved.
+
+## Parallel pull-request review without new worktrees
+
+For parallel read-only review, prepare one stable existing checkout of the pull request or retained worker result. Do not create one managed worktree per reviewer.
+
+1. The parent records the exact base and head SHAs and makes sure no writer changes the checkout while review runs.
+2. Start each read-only child in an ordinary pane with `cwd` set to that checkout. Omit `worktree`.
+3. Give every reviewer the same exact base and head SHAs. Require it to report `git rev-parse HEAD` before its review result.
+4. Before the parent reports or publishes the review, recheck the checkout SHA. If it changed, treat the prior reviews as stale and review the new commit again.
+
+```typescript
+subagent({
+  name: "PR reviewer",
+  agent: "reviewer",
+  cwd: "/path/to/pr-checkout",
+  task: "Review base <base-sha> through head <head-sha>. First report git rev-parse HEAD. Do not modify files.",
+});
+```
+
+A retained worker worktree can be this checkout. The parent owns any final report, PR action, integration, and cleanup.
 
 ## Review and integration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-herdr-agents",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "Asynchronous Pi subagents and approved review workflows in Herdr, with optional isolated Git worktrees",
   "keywords": [
     "pi-package",
@@ -30,7 +30,7 @@
   "type": "module",
   "scripts": {
     "lint": "oxlint pi-extension test",
-    "test": "node --experimental-strip-types --test test/test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/workflow.test.ts test/package-skill.test.js",
+    "test": "node --experimental-strip-types --test test/test.ts test/launch.test.ts test/runtime-routing.test.ts test/release-workflow.test.ts test/workflow.test.ts test/package-skill.test.js",
     "test:integration": "node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts",
     "test:integration:live": "PI_TEST_LIVE=1 node --experimental-strip-types --test --test-concurrency=1 test/integration/*.test.ts"
   },

package/pi-extension/subagents/completion.ts

@@ -21,7 +21,6 @@ export interface CompletionOptions {
     observedAt: number,
   ) => void;
   sessionFile?: string;
-  sentinelFile?: string;
   onTick?: (elapsedSeconds: number) => void;
 }
 
@@ -83,12 +82,7 @@ function terminalExitCode(screen: string): number | null {
 }
 
 function completionArtifact(options: CompletionOptions): CompletionResult | null {
-  const sidecar = consumeExitSidecar(options.sessionFile);
-  if (sidecar) return sidecar;
-  if (options.sentinelFile && existsSync(options.sentinelFile)) {
-    return { reason: "sentinel", exitCode: 0 };
-  }
-  return null;
+  return consumeExitSidecar(options.sessionFile);
 }
 
 async function waitForDisappearanceArtifacts(
@@ -137,10 +131,6 @@ export async function waitForCompletion(
     const sidecarResult = consumeExitSidecar(options.sessionFile);
     if (sidecarResult) return sidecarResult;
 
-    if (options.sentinelFile && existsSync(options.sentinelFile)) {
-      return { reason: "sentinel", exitCode: 0 };
-    }
-
     try {
       const exitCode = terminalExitCode(await options.readTerminalTail());
       if (exitCode !== null) return { reason: "sentinel", exitCode };