@henryqw/pi-subagent 7.0.1 → 8.0.1

package/CONTEXT.md

@@ -24,7 +24,7 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Timeout behavior: `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). 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 via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`idleMinutes`, `maxMinutes`; defaults 10/30).
+- 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.
 - 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.

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,21 +145,38 @@ 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 timeouts. 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 |
 | --- | --- | --- | --- |
 | `maxSubagents` | No | Safe integer ≥ 1 | `5` |
+| `maxTurns` | No | Safe integer ≥ 1 | `50` |
 | `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. `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
 
@@ -118,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.
 
@@ -134,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. 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`, worktree helpers, and generic managed Herdr lifecycle 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/ephemeral.d.ts

@@ -1,11 +1,14 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import type { PiLaunch } from "./index.ts";
+export declare const DEFAULT_MAX_TURNS = 50;
+export declare const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
 export interface EphemeralSubagentTimeout {
     idleMs: number;
     maxMs: number;
 }
 export interface EphemeralSubagentExecutorOptions {
     maxConcurrency: number;
+    maxTurns?: number;
     timeout: EphemeralSubagentTimeout;
 }
 export type EphemeralSubagentActivityEvent = {
@@ -44,12 +47,13 @@ export type EphemeralSubagentResult = (EphemeralSubagentResultBase & {
 }) | (EphemeralSubagentResultBase & {
     outcome: "failure";
 });
-export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "spawn" | "protocol" | "prepare" | "callback";
+export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "turn_limit" | "spawn" | "protocol" | "prepare" | "callback";
 export declare class EphemeralSubagentError extends Error {
     name: string;
     readonly code: EphemeralSubagentErrorCode;
     readonly usage?: Usage;
-    constructor(code: EphemeralSubagentErrorCode, message: string, cause?: unknown, usage?: Usage);
+    readonly output?: string;
+    constructor(code: EphemeralSubagentErrorCode, message: string, cause?: unknown, usage?: Usage, output?: string);
 }
 export interface EphemeralSubagentExecutor {
     run(input: EphemeralSubagentRunInput): Promise<EphemeralSubagentResult>;

package/dist/ephemeral.js

@@ -4,6 +4,8 @@ import { basename } from "node:path";
 import { StringDecoder } from "node:string_decoder";
 const MAX_OUTPUT_BYTES = 50 * 1024;
 const MAX_JSON_EVENT_BYTES = 1024 * 1024;
+export const DEFAULT_MAX_TURNS = 50;
+export const EXECUTION_BUDGET_ENV = "PI_SUBAGENT_EXECUTION_BUDGET";
 const MAX_ACTIVITY_TEXT_BYTES = 4 * 1024;
 // A JSON string byte can take six source bytes (for example, \u0000).
 const MAX_ACTIVITY_PREFIX_BYTES = 2 * MAX_ACTIVITY_TEXT_BYTES * 6 + 1024;
@@ -43,10 +45,12 @@ export class EphemeralSubagentError extends Error {
     name = "EphemeralSubagentError";
     code;
     usage;
-    constructor(code, message, cause, usage) {
+    output;
+    constructor(code, message, cause, usage, output) {
         super(message, cause === undefined ? undefined : { cause });
         this.code = code;
         this.usage = usage;
+        this.output = output;
     }
 }
 function positiveDelay(value, field) {
@@ -61,6 +65,9 @@ function validateOptions(options) {
     if (!Number.isSafeInteger(options.maxConcurrency) || options.maxConcurrency < 1) {
         throw new RangeError("maxConcurrency must be a positive safe integer.");
     }
+    const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+    if (!Number.isSafeInteger(maxTurns) || maxTurns < 1)
+        throw new RangeError("maxTurns must be a positive safe integer.");
     if (!options.timeout || typeof options.timeout !== "object")
         throw new TypeError("timeout is required.");
     const timeout = {
@@ -69,7 +76,7 @@ function validateOptions(options) {
     };
     if (timeout.maxMs <= timeout.idleMs)
         throw new RangeError("timeout.maxMs must be greater than timeout.idleMs.");
-    return { maxConcurrency: options.maxConcurrency, timeout };
+    return { maxConcurrency: options.maxConcurrency, maxTurns, timeout };
 }
 function abortError(signal, cause = signal?.reason, usage) {
     return new EphemeralSubagentError("aborted", "Subagent was aborted.", cause, usage);
@@ -202,7 +209,7 @@ export function createEphemeralSubagentExecutor(options) {
                 }
                 if (input.signal?.aborted)
                     throw abortError(input.signal);
-                return await runPi(prepared, input, validated.timeout, invocation);
+                return await runPi(prepared, input, validated, invocation);
             }
             finally {
                 release();
@@ -362,16 +369,23 @@ export function formatDuration(milliseconds) {
     const minutes = Math.floor(seconds % 3_600 / 60);
     return hours ? `${hours}h ${minutes}m` : minutes ? `${minutes}m ${seconds % 60}s` : `${seconds}s`;
 }
-async function runPi(prepared, input, timeoutPolicy, invocation) {
+async function runPi(prepared, input, budget, invocation) {
     if (input.signal?.aborted)
         throw abortError(input.signal);
+    const timeoutPolicy = budget.timeout;
     return await new Promise((resolve, reject) => {
         const args = [...invocation.args, "--mode", "json", "-p", ...prepared.launch.args, `Task: ${prepared.task}`];
+        const startedAt = Date.now();
+        const maxDeadline = startedAt + timeoutPolicy.maxMs;
         let child;
         try {
             child = spawn(invocation.command, args, {
                 cwd: prepared.cwd,
-                env: { ...process.env, ...prepared.launch.env },
+                env: {
+                    ...process.env,
+                    ...prepared.launch.env,
+                    [EXECUTION_BUDGET_ENV]: JSON.stringify({ maxTurns: budget.maxTurns, maxMs: timeoutPolicy.maxMs, startedAt }),
+                },
                 shell: false,
                 stdio: ["ignore", "pipe", "pipe"],
                 detached: process.platform !== "win32",
@@ -397,8 +411,8 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
         let spawnError;
         let protocolError;
         let aborted = false;
-        const startedAt = Date.now();
-        const maxDeadline = startedAt + timeoutPolicy.maxMs;
+        let turnLimited = false;
+        let startedTurns = 0;
         let lastEventAt = startedAt;
         let deadline = Math.min(startedAt + timeoutPolicy.idleMs, maxDeadline);
         let timedOutAfterMs;
@@ -480,6 +494,11 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
                     : `Subagent timed out after ${formatDuration(timeoutPolicy.idleMs)} without a recognized Pi event.`;
                 reject(new EphemeralSubagentError("timeout", message, new Error(message), accumulatedUsage()));
             }
+            else if (turnLimited) {
+                const summary = `Subagent reached its maximum turn limit of ${budget.maxTurns}.`;
+                const message = output ? capEphemeralSubagentOutput(`${summary}\n\nLast assistant output:\n${output}`) : summary;
+                reject(new EphemeralSubagentError("turn_limit", message, new Error(message), accumulatedUsage(), output));
+            }
             else if (protocolError) {
                 reject(new EphemeralSubagentError("protocol", protocolError.message, protocolError, accumulatedUsage()));
             }
@@ -551,7 +570,7 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             scheduleDeadline();
         };
         const processLine = (line) => {
-            if (!line.trim())
+            if (turnLimited || !line.trim())
                 return;
             let event;
             try {
@@ -566,6 +585,12 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             if (typeof record.type !== "string" || !Object.hasOwn(PI_JSON_EVENTS, record.type))
                 return;
             observeEvent();
+            if (record.type === "turn_start" && ++startedTurns > budget.maxTurns) {
+                if (!callbackFailure && !aborted && timedOutAfterMs === undefined)
+                    turnLimited = true;
+                stop(true);
+                return;
+            }
             if (record.type === "message_start") {
                 partial.prefix = "";
                 partial.totalBytes = 0;
@@ -690,7 +715,7 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
         };
         onStdoutData = (data) => {
             armPostExitIdleDeadline();
-            if (callbackFailure || protocolError)
+            if (callbackFailure || protocolError || turnLimited)
                 return;
             let offset = 0;
             while (offset < data.length) {
@@ -731,7 +756,7 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
                         invokeCallback("onActivity", input.onActivity, activity);
                     }
                 }
-                if (callbackFailure)
+                if (callbackFailure || turnLimited)
                     return;
                 lineParts = [];
                 lineBytes = 0;
@@ -771,13 +796,13 @@ async function runPi(prepared, input, timeoutPolicy, invocation) {
             killTimer.unref();
         }
         const abort = () => {
-            if (timedOutAfterMs !== undefined || childExited)
+            if (timedOutAfterMs !== undefined || turnLimited || childExited)
                 return;
             aborted = true;
             stop();
         };
         function timeout(afterMs, reason) {
-            if (timedOutAfterMs !== undefined || childExited)
+            if (timedOutAfterMs !== undefined || turnLimited || childExited)
                 return;
             if (reason === "maximum") {
                 if (!aborted) {

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 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, EphemeralSubagentError, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
+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";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";

package/dist/index.js

@@ -5,7 +5,7 @@ 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, EphemeralSubagentError, formatDuration, } from "./ephemeral.js";
+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";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
 const CODEX_ALIAS = /^openai-codex-(?:[2-9]|[1-9]\d+)$/;

package/docs/orchestration.md

@@ -161,11 +161,12 @@ A loaded `Role` contains `name`, `description`, required normalized `tools`, `ex
 ```js
 const executorOptions = {
   maxConcurrency: 4,
+  maxTurns: 50,
   timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
 };
 ```
 
-Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, `onTokens(number)`, and `onActivity(event)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency`, `idleMs`, and `maxMs` must be positive; `maxMs` must exceed `idleMs`.
+Concurrency is FIFO. `run` accepts optional `signal`, `onUpdate(text)`, `onTokens(number)`, and `onActivity(event)` callbacks plus required `prepare()`. A queued run receives its permit before `prepare` executes, so resource and route resolution can use the latest Pi state. Queued time does not consume child timeout. `maxConcurrency`, `maxTurns`, `idleMs`, and `maxMs` must be positive; integer limits must be safe integers, `maxMs` must exceed `idleMs`, and omitted `maxTurns` defaults to 50.
 
 The executor is **active-Pi-only**. It reuses the currently running Pi invocation and does not locate or support a standalone Node.js Pi installation. Once direct Pi exits, stdout/stderr drain normally until EOF; an escaped descendant retaining either stream is cut off after short output inactivity or a one-second hard deadline so it cannot retain the FIFO permit.
 
@@ -193,6 +194,7 @@ export function createRunRole(pi) {
 
   const executor = createEphemeralSubagentExecutor({
     maxConcurrency: 4,
+    maxTurns: 50,
     timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
   });
 
@@ -244,7 +246,7 @@ export function createRunRole(pi) {
 }
 ```
 
-`run` resolves to `EphemeralSubagentResult`. Both outcome variants contain `exitCode`, `output`, `stderr`, and optional `stopReason`, `errorMessage`, and `usage`. A launched child/model failure is a typed `{ outcome: "failure", ... }` result. Abort, timeout, spawn, protocol, preparation, and callback failures reject with `EphemeralSubagentError` and a stable `code`. Assistant `output` and `stderr` are bounded, and `usage` contains aggregate child usage when Pi supplies it.
+`run` resolves to `EphemeralSubagentResult`. Both outcome variants contain `exitCode`, `output`, `stderr`, and optional `stopReason`, `errorMessage`, and `usage`. A launched child/model failure is a typed `{ outcome: "failure", ... }` result. Abort, timeout, turn-limit, spawn, protocol, preparation, and callback failures reject with `EphemeralSubagentError` and a stable `code`. A terminal response at `maxTurns` succeeds; an attempted continuation rejects with `turn_limit`, accumulated `usage`, and bounded `output`. The executor supplies the same turn/maximum-runtime budget to the existing child Role tool extension, which steers the fixed convergence warning before another model turn once at each 80% threshold, combines thresholds first due together, and uses no timer or extra turn. Assistant `output` and `stderr` are bounded, and `usage` contains aggregate child usage when Pi supplies it.
 
 ### Activity callbacks
 

package/extensions/config.ts

@@ -11,6 +11,7 @@ export interface SubagentTimeoutConfig {
 
 export interface SubagentConfig {
 	maxSubagents?: number;
+	maxTurns?: number;
 	timeout?: SubagentTimeoutConfig;
 }
 
@@ -66,16 +67,18 @@ export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConf
 	const problems: string[] = [];
 	const config: SubagentConfig = {};
 	for (const key of Object.keys(record)) {
-		if (key !== "maxSubagents" && key !== "timeout") {
-			problems.push(`unknown config key ${JSON.stringify(key)}; expected maxSubagents, timeout`);
+		if (key !== "maxSubagents" && key !== "maxTurns" && key !== "timeout") {
+			problems.push(`unknown config key ${JSON.stringify(key)}; expected maxSubagents, maxTurns, timeout`);
 		}
 	}
 
-	if (record.maxSubagents !== undefined) {
-		if (typeof record.maxSubagents === "number" && Number.isSafeInteger(record.maxSubagents) && record.maxSubagents >= 1) {
-			config.maxSubagents = record.maxSubagents;
+	for (const key of ["maxSubagents", "maxTurns"] as const) {
+		const value = record[key];
+		if (value === undefined) continue;
+		if (typeof value === "number" && Number.isSafeInteger(value) && value >= 1) {
+			config[key] = value;
 		} else {
-			problems.push(`maxSubagents must be a safe integer >= 1, got ${JSON.stringify(record.maxSubagents)}`);
+			problems.push(`${key} must be a safe integer >= 1, got ${JSON.stringify(value)}`);
 		}
 	}
 

package/extensions/delegate-flow.ts

@@ -795,8 +795,8 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		description: "Run 1–8 independent Implementers in isolated Unit Worktrees, validate and serially fast-forward each tip, with exact review only for units that declare a judgment criterion.",
 		promptSnippet: "Run a deterministic parallel-implementation, serial-verification Flow",
 		promptGuidelines: [
-			"Use delegate_flow only for cohesive units expected to commute; combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
-			"Each unit must include explicit bounded requirements and its authoritative direct command/argument validation gate. Add review only for an explicit judgment that validation cannot establish.",
+			"Use delegate_flow only for cohesive units expected to commute: split independent outcomes into units, sequence dependent work outside delegate_flow, and never divide one invariant across multiple units. Combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
+			"Each delegate_flow unit must own one concrete outcome with one focused validation story: include explicit bounded requirements and its authoritative direct command/argument validation gate. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Add review only for an explicit judgment that validation cannot establish.",
 			"If a Flow blocks, inspect its classification and call delegate_flow_continue once with explicit repair guidance; modelClass may replace that one repair's current class.",
 		],
 		parameters: DelegateFlowSchema,

package/extensions/role-tools.ts

@@ -1,7 +1,9 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { CHILD_EXCLUDED_TOOL_NAMES, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
+import { CHILD_EXCLUDED_TOOL_NAMES, EXECUTION_BUDGET_ENV, ROLE_TOOL_POLICY_FLAG } from "@henryqw/pi-subagent";
 
 const childExcludedTools: ReadonlySet<string> = new Set(CHILD_EXCLUDED_TOOL_NAMES);
+const WARNING_RATIO = 0.8;
+const WARNING_MESSAGE_TYPE = "pi-subagent-execution-budget";
 
 function configuredTools(value: unknown): string[] {
 	if (typeof value !== "string") throw new Error(`${ROLE_TOOL_POLICY_FLAG} must be JSON tool names.`);
@@ -17,6 +19,35 @@ function configuredTools(value: unknown): string[] {
 	return [...new Set(parsed.map((name) => name.trim()))];
 }
 
+function executionBudget(value: string | undefined): { maxTurns: number; maxMs: number; startedAt: number } | undefined {
+	if (value === undefined) return;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(value);
+	} catch {
+		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
+	}
+	const budget = parsed as Record<string, unknown>;
+	if (Object.keys(budget).length !== 3 || !("maxTurns" in budget) || !("maxMs" in budget) || !("startedAt" in budget)
+		|| !Number.isSafeInteger(budget.maxTurns) || (budget.maxTurns as number) < 1
+		|| typeof budget.maxMs !== "number" || !Number.isFinite(budget.maxMs) || budget.maxMs <= 0
+		|| !Number.isSafeInteger(budget.startedAt) || (budget.startedAt as number) < 0) {
+		throw new Error(`${EXECUTION_BUDGET_ENV} must be a JSON execution budget.`);
+	}
+	return { maxTurns: budget.maxTurns as number, maxMs: budget.maxMs, startedAt: budget.startedAt as number };
+}
+
+function expectsAnotherTurn(message: unknown): boolean {
+	if (!message || typeof message !== "object" || Array.isArray(message)) return false;
+	const record = message as Record<string, unknown>;
+	return record.role === "assistant" && Array.isArray(record.content)
+		&& record.content.some((part) => part && typeof part === "object" && !Array.isArray(part)
+			&& (part as Record<string, unknown>).type === "toolCall");
+}
+
 export default function roleTools(pi: ExtensionAPI): void {
 	pi.registerFlag(ROLE_TOOL_POLICY_FLAG, {
 		description: "Internal Pi Subagent Role tool policy",
@@ -36,4 +67,29 @@ export default function roleTools(pi: ExtensionAPI): void {
 			throw new Error(`Subagent requested unavailable tools: ${unavailable.join(", ")}. Check spelling and load the provider extension that registers them.`);
 		}
 	});
+
+	const budget = executionBudget(process.env[EXECUTION_BUDGET_ENV]);
+	if (!budget) return;
+	const warningTurn = Math.ceil(budget.maxTurns * WARNING_RATIO);
+	let completedTurns = 0;
+	let turnWarningSent = false;
+	let runtimeWarningSent = false;
+	pi.on("turn_end", (event) => {
+		completedTurns += 1;
+		if (!expectsAnotherTurn(event.message)) return;
+		const elapsedMs = Math.max(0, Date.now() - budget.startedAt);
+		const turnWarningDue = !turnWarningSent && completedTurns >= warningTurn;
+		const runtimeWarningDue = !runtimeWarningSent && elapsedMs >= budget.maxMs * WARNING_RATIO;
+		if (!turnWarningDue && !runtimeWarningDue) return;
+		if (turnWarningDue) turnWarningSent = true;
+		if (runtimeWarningDue) runtimeWarningSent = true;
+		const remainingTurns = Math.max(0, budget.maxTurns - completedTurns);
+		const remainingMinutes = Math.max(0, Math.ceil((budget.maxMs - elapsedMs) / 60_000));
+		const maxMinutes = budget.maxMs / 60_000;
+		pi.sendMessage({
+			customType: WARNING_MESSAGE_TYPE,
+			content: `**Execution budget warning:** ${remainingTurns} of ${budget.maxTurns} turns and approximately ${remainingMinutes} of ${maxMinutes} minutes remain before forced termination.\nConverge now: stop expanding scope, complete the highest-priority required work, perform only essential validation, and return a concise final result. If completion is impossible, follow your role’s recovery requirements and report the blocker and exact remaining work. This warning does not change your role, scope, or permissions.`,
+			display: true,
+		}, { deliverAs: "steer", triggerTurn: false });
+	});
 }

package/extensions/subagent.ts

@@ -18,6 +18,7 @@ import {
 	createEphemeralSubagentExecutor,
 	DELEGATE_TASK,
 	createRoleLaunch,
+	DEFAULT_MAX_TURNS,
 	EphemeralSubagentError,
 	finalizeChildWorktree,
 	formatDuration,
@@ -331,7 +332,11 @@ export default function subagentExtension(
 	// Explicit policy argument (tests/embedders) wins; otherwise resolve from
 	// config file over defaults.
 	const timeoutPolicy: TimeoutPolicy = overrideTimeoutPolicy ?? resolveTimeoutPolicy(loadedConfig.config.timeout);
-	const executor = createEphemeralSubagentExecutor({ maxConcurrency: maxActiveSubagents, timeout: timeoutPolicy });
+	const executor = createEphemeralSubagentExecutor({
+		maxConcurrency: maxActiveSubagents,
+		maxTurns: loadedConfig.config.maxTurns ?? DEFAULT_MAX_TURNS,
+		timeout: timeoutPolicy,
+	});
 	// Background children outlive the launching tool call, so they get their own
 	// abort signal: tied to the session, not to the turn that started them.
 	const backgroundTasks = new Map<string, { controller: AbortController; settled: Promise<void> }>();
@@ -602,8 +607,8 @@ export default function subagentExtension(
 		description: `Delegate one selected single, parallel, or chain workflow of bounded tasks to isolated Pi Subagents. Roles: ${roleSummary()}.`,
 		promptSnippet: "Delegate one bounded single, parallel, or chain workflow to isolated roles",
 		promptGuidelines: [
-			"Call delegate_task with exactly one mode: role+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output.",
-			"Every delegate_task entry must state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; never pass the parent request unchanged.",
+			"Call delegate_task with exactly one mode: role+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output; split independent, commuting outcomes into parallel entries, sequence dependent work in chain entries, and never divide one invariant across multiple entries.",
+			"Every delegate_task entry must own one concrete outcome with one focused validation story: state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; if the affected flow or scope is not yet known, perform bounded read-only discovery first; never pass the parent request unchanged.",
 			"For each delegate_task entry, populate model and thinking only for an explicit user override; otherwise choose only modelClass: fast normally, or balanced upfront for obviously complex work. This is Main policy, not runtime enforcement.",
 			"Parallel delegate_task entries must own non-overlapping files. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.",
 			"delegate_task background applies to the whole selected workflow and returns before results exist; use it only when the user explicitly asks for non-blocking work.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "7.0.1",
+  "version": "8.0.1",
   "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": {

package/skills/pi-subagent-delegated-development/SKILL.md

@@ -11,9 +11,9 @@ You are Main, the planner/orchestrator: slice work and call `delegate_flow`. Do
 
 Before slicing, identify applicable repository prohibitions. If the request or plan conflicts with them, stop and resolve the conflict before delegation. Copy them into every affected task and into `review` when automated validation cannot establish compliance; never replace repository policy with generic preservation or migration assumptions. When compatibility is disallowed, require deletion of replaced paths and forbid legacy readers, aliases, adapters, dual schemas, deprecation paths, and compatibility fallbacks.
 
-Use the fewest cohesive units. `delegate_flow` is for independent units expected to commute; combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants. Dependent work remains outside Flow, in one task or ordinary caller-controlled sequencing.
+Use the fewest cohesive units. `delegate_flow` is for independent units expected to commute: split independent outcomes into units, combine or sequence work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants, and never divide one invariant across multiple units. Dependent work remains outside Flow; sequence it in one task or ordinary caller-controlled sequencing.
 
-Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array. Do not pass the parent request unchanged. Use `modelClass: "fast"` normally; use `"balanced"` upfront only for obviously complex work. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
+Give every unit a bounded objective, owned scope and exclusions, and its direct validation command/argument array; each delegation must own one concrete outcome with one focused validation story. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Do not pass the parent request unchanged. Use `modelClass: "fast"` normally; use `"balanced"` upfront only for obviously complex work. Add non-empty `review` only for an explicit judgment that automated validation cannot establish. Call `delegate_flow` with 1–8 units; the runtime always supplies the effective Implementer and supplies the Reviewer only when a unit needs review.
 
 ## Runtime Flow