@henryqw/pi-subagent 5.0.0 → 6.0.0

package/CONTEXT.md

@@ -2,21 +2,21 @@
 
 ## Purpose
 
-Provide validated built-in and user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, generic `delegate_task` delegation, and package-owned `delegate_flow` Git orchestration. `delegate_task` remains a flat bounded delegation tool; Flow uses effective Implementer and Reviewer Roles while owning its fixed implementation, validation, exact review, integration, and cleanup mechanics. The bundled Main-side Skill adds no runtime behavior or changes generic fallback.
+Provide validated built-in and user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, generic `delegate_task` delegation, and package-owned `delegate_flow` Git orchestration. Main plans and orchestrates; `delegate_task` remains a flat bounded delegation tool, while Flow uses the effective Implementer and only invokes its effective Reviewer for explicit judgment criteria after authoritative validation. The bundled Main-side Skill adds no runtime behavior or changes generic fallback.
 
 ## Domain glossary
 
-- **Main**: Pi session delegating work.
+- **Main**: Pi session that plans and orchestrates delegated work.
 - **Subagent**: isolated Pi child process handling one task.
 - **Role**: package-shipped built-in or user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, required `tools`, `extensions`, and `skills` arrays, and optional isolation.
-- **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, assigned in shared task-model settings or overridden by Main from task complexity.
+- **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, resolved through shared task-model settings; Main normally selects `fast`, may select `balanced` upfront for obvious complexity, and leaves direct model/thinking overrides to explicit user requests.
 - **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
 - **Delegated Task**: one bounded work request sent from Main to one Role.
 - **Workflow**: generic orchestration of one or more Delegated Tasks; `delegate_task` owns its selected mode, while library callers compose executor runs in JavaScript.
 - **Workflow Mode**: `delegate_task` tool policy selected per call for `single`, `parallel`, or `chain` execution; not a Role property or executor API.
 - **Flow**: package-owned, memory-only Git implementation and integration workflow started by `delegate_flow`.
-- **Unit Worktree**: one Flow-owned worktree and branch for one Flow unit; it is reused for rebase, validation, review, and one repair.
-- **Review Packet**: exact `{base, tip, patchPath}` evidence delivered to the Flow Reviewer in the Unit Worktree.
+- **Unit Worktree**: one Flow-owned worktree and branch for one Flow unit; it is reused for rebase, validation, optional exact review, and one repair.
+- **Review Packet**: exact `{base, tip, patchPath}` evidence delivered to the Flow Reviewer only for a unit's explicit `review` criterion.
 - **Resource Policy**: Role ownership of base tools, extensions, and Skill names, plus explicit caller additions of tools, extensions, and environment through `createRoleLaunch`.
 - **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
 - **Ephemeral Executor**: mechanism that receives a prepared Pi Launch, runs one bounded Delegated Task in one no-session child process, and returns its result without discovering resources or composing a Workflow.
@@ -28,11 +28,11 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - 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.
-- Main selects Role and may override Model Class and thinking level per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
+- Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses the shared `pi-subagent/delegateTask` assignment; library callers select a Role plus their own shared task ID.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
 - User Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`. Package-shipped built-in Roles (`implementer`, `reviewer`) resolve from the package's own `examples/roles/` Markdown through the same parser; a same-named user file explicitly overrides a built-in for `delegate_task` and `delegate_flow`.
-- `delegate_flow` accepts 1–8 independent units with direct validation commands. At Flow start, it resolves and freezes the effective Implementer and Reviewer Roles through any continuation. One active Flow creates every Unit Worktree before launching Implementers in parallel, then processes settled units in declared order. For each unit Flow rebases in place when earlier units advanced Main, validates in that worktree, sends the exact Review Packet to the Reviewer in the same worktree, and integrates only exact `PASS` using `git merge --ff-only` with the full reviewed OID.
-- Flow is memory-only. Only a post-rebase commit drop produces a no-op (`base === tip`); it validates, skips Reviewer and merge, then cleans up ordinarily. Initial zero-commit implementations block. Implementer, validation, or reviewer blocks allow one `delegate_flow_continue({ guidance })` repair in the same worktree; a second block is terminal. Rebase and evidence/Reviewer/infrastructure failures retain worktrees. A reported fast-forward failure retains its worktree unless Main is clean at the exact reviewed tip, which completes with the merge diagnostic as a warning. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal is a completion warning.
+- `delegate_flow` accepts 1–8 independent units with direct validation commands, optional `modelClass`, and optional non-empty `review` judgment text. Omitted classes use the shared `pi-subagent/delegateTask` assignment; each unit's current class resolves through its shared profile route for its Implementer and, when `review` exists, Reviewer. At Flow start it always resolves/freezes the effective Implementer and resolves/freezes a Reviewer only when at least one requested unit has `review`. One active Flow creates every Unit Worktree before launching Implementers in parallel, then processes settled units in declared order. For each unit Flow rebases in place when earlier units advanced Main, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification: units without `review` fast-forward their exact validated tip; units with `review` send the exact Review Packet to the Reviewer in the same worktree and require exact `PASS` before the same guarded `git merge --ff-only` path.
+- Flow is memory-only. Only a post-rebase commit drop produces a no-op (`base === tip`); it validates, skips Reviewer and merge, then cleans up ordinarily. Initial zero-commit implementations block. Implementer, validation, or reviewer blocks allow one `delegate_flow_continue({ guidance, modelClass? })` repair in the same worktree; omission retains the Unit's current class and presence replaces it for that repair. A second block is terminal. Rebase and evidence/Reviewer/infrastructure failures retain worktrees. A reported fast-forward failure retains its worktree unless Main is clean at the exact integrated tip, which completes with the merge diagnostic as a warning. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal is a completion warning.
 - Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge validation. It never changes generic `delegate_task` Role resolution, isolation, non-Git fallback, or ordinary direct plan/file review.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
 - Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -1,6 +1,6 @@
 # `@henryqw/pi-subagent`
 
-Delegate bounded work to isolated Pi child processes. Generic `delegate_task` selects one flat single, parallel, or chain mode. Package-owned `delegate_flow` runs a fixed Git implementation-and-review Flow. Package authors can reuse the same Role launch policy and active-Pi executor from JavaScript.
+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.
 
 ## Why
 
@@ -45,7 +45,7 @@ Select exactly one shape:
 { chain: [{ role, task, model?, modelClass?, thinking? }], background? }
 ```
 
-`model` is `provider/modelId` and overrides `modelClass`. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses the shared `pi-subagent/delegateTask` assignment. `background` applies to the entire selected mode and is never a per-delegation field.
+`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 the shared `pi-subagent/delegateTask` assignment. `background` applies to the entire selected mode and is never a per-delegation field.
 
 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.
 
@@ -59,18 +59,20 @@ See [Orchestration, isolation, and the public API](./docs/orchestration.md) for
 
 ### `delegate_flow`
 
-Use Flow only for independent, commuting Git changes. It accepts 1–8 uniquely identified units, each with a bounded task and direct command/argument validation gate:
+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:
 
 ```text
-delegate_flow({ units: [{ id, task, validation: [{ command, args }] }] })
-delegate_flow_continue({ guidance })
+delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] })
+delegate_flow_continue({ guidance, modelClass? })
 ```
 
-One memory-only Flow may be active. At start it resolves the effective `implementer` and `reviewer` Roles, including same-named user overrides, and freezes them through any continuation. Overrides must remain compatible with Flow: Implementers commit scoped work, and Reviewers inspect the exact packet and emit exactly `PASS` only with zero findings. It creates one Unit Worktree per unit, runs Implementers in parallel, then processes settled results in declared order. For each unit, Flow rebases onto the current Flow Main when needed, runs its declared validation, gives the Reviewer the exact `{base, tip, patchPath}` packet in that same worktree, and only exact `PASS` permits `git merge --ff-only` of the full reviewed OID. It removes the worktree and branch non-forcibly after integration; a refusal is a completion warning with the retained worktree path and/or branch.
+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.
 
-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. 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 reviewed tip; otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
+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 the shared `pi-subagent/delegateTask` assignment; 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.
 
-`delegate_task` remains generic with its ordinary isolation behavior. Flow uses the same effective Role resolution for `implementer` and `reviewer`; without user overrides, the package-shipped Roles remain the defaults.
+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.
+
+`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.
 
 ## Config
 
@@ -109,7 +111,7 @@ An unreadable or invalid Role file fails role loading fast; duplicate role names
 The package ships two working built-in Roles, always available without any 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 of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
+- `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
 
 A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
 
@@ -131,7 +133,7 @@ The package never installs or writes Role configuration. Sample names are not bu
 
 ## Skill
 
-The bundled [`pi-subagent-delegated-development`](./skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side policy only. `delegate_flow` owns its fixed Git mechanics; 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/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).
 
 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.
 

package/docs/adr/001-composable-ephemeral-execution.md

@@ -2,7 +2,7 @@
 
 ## Decision
 
-The public task executor is an execution mechanism: it receives a prepared Pi Launch, runs one bounded Delegated Task, and returns the result. `delegate_task` selects its flat `single`, `parallel`, or `chain` tool policy; those modes are not executor primitives.
+The public task executor is an execution mechanism: it receives a prepared Pi Launch, runs one bounded Delegated Task, and returns the result. Main plans and orchestrates; `delegate_task` selects its flat `single`, `parallel`, or `chain` tool policy, while those modes are not executor primitives.
 
 Generic callers compose workflows with JavaScript. Fan-out and fan-in use promises and collections; sequencing uses ordinary control flow; review loops use explicit caller-owned bounds. The package does not define a recursive workflow AST.
 
@@ -14,6 +14,8 @@ Resource Policy is split at launch preparation:
 
 Built-in `implementer` and `reviewer` Roles ship as Markdown in `examples/roles/` and use the same parser as user Roles. For generic delegation, a same-named user Role explicitly overrides a built-in. The package does not install, copy, or write user configuration.
 
+Main populates direct `model` and `thinking` only for explicit user overrides; otherwise it chooses only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This is tool policy, not executor provenance tracking or runtime enforcement.
+
 ## Scope boundary
 
 `delegate_flow` is a fixed package-owned Git workflow, documented in [ADR 002](./002-package-owned-delegate-flow-orchestration.md). It reuses the prepared-child runner but is not a general executor workflow primitive: it has its own fixed unit, worktree, validation, review, integration, and cleanup contract. `delegate_task` and library callers remain generic.

package/docs/adr/002-package-owned-delegate-flow-orchestration.md

@@ -2,21 +2,21 @@
 
 ## Decision
 
-`delegate_task` remains the generic bounded Role tool described by [ADR 001](./001-composable-ephemeral-execution.md). `delegate_flow` is a separate package-owned Git workflow with this fixed interface:
+`delegate_task` remains the generic bounded Role tool described by [ADR 001](./001-composable-ephemeral-execution.md). Main plans and orchestrates; `delegate_flow` is a separate package-owned Git workflow with this fixed interface:
 
 ```ts
-delegate_flow({ units: [{ id, task, validation: [{ command, args }] }] });
-delegate_flow_continue({ guidance });
+delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] });
+delegate_flow_continue({ guidance, modelClass? });
 ```
 
-A Flow accepts 1–8 independent units with unique IDs. Only one memory-only Flow may be active. At start it resolves the effective `implementer` and `reviewer` Roles, including same-named user overrides, and freezes them through any continuation. It requires a clean committed attached Main branch and creates one Unit Worktree per unit before launching Implementers in parallel. All started Implementers settle; Flow then processes units in declared order.
+A Flow accepts 1–8 independent units with unique IDs. `modelClass` is optional and otherwise uses the shared `pi-subagent/delegateTask` assignment; its class resolves through the existing `pi-task-models` profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. `review` is optional non-empty text for the explicit judgment that declared validation cannot establish.
 
-For each unit, Flow verifies Main, rebases the Unit Worktree in place when earlier Flow units advanced Main, runs the declared validation commands there, and gives the Reviewer the exact `{base, tip, patchPath}` packet in that same worktree. Reviewer output whose trimmed text equals `PASS` approves. Flow then fast-forwards Main with the full reviewed OID and uses non-forced worktree removal and branch deletion. Cleanup refusal does not undo integration; it returns completion with retained worktree path and/or branch warnings.
+Only one memory-only Flow may be active. At start it resolves/freezes the effective `implementer` Role, including a same-named user override. It resolves/freezes the effective `reviewer` Role only when at least one requested unit has `review`. It requires a clean committed attached Main branch and creates one Unit Worktree per unit before launching Implementers in parallel. All started Implementers settle; Flow then processes units in declared order.
 
-If rebase drops all unit commits, `base === tip` is a no-op. Flow validates the state, skips Reviewer and merge, then cleans up ordinarily.
+For each unit, Flow verifies Main, rebases the Unit Worktree in place when earlier Flow units advanced Main, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification. Without `review`, Flow skips exact evidence and Reviewer launch, then fast-forwards the exact validated tip through the existing guarded `git merge --ff-only` path. With `review`, it gives the Reviewer the exact `{base, tip, patchPath}` packet in that same worktree; only trimmed output exactly equal to `PASS` permits the same full-OID fast-forward. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal does not undo integration and returns completion with retained-work warnings.
 
-Implementer failure, dirty or missing committed work, validation failure, and reviewer findings block the first affected declared unit. `delegate_flow_continue({ guidance })` reruns the Flow's frozen Implementer Role in that same Unit Worktree once and derives, validates, and reviews again. A second block is terminal. A failed rebase is aborted and terminates as an infrastructure failure with Git diagnostics; other infrastructure failures also terminate it. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact reviewed tip; otherwise it is terminal. Terminal outcomes retain worktrees for Main to reslice, and earlier integrations are never rolled back.
+If rebase drops all unit commits, `base === tip` is a no-op. Flow validates the state, skips Reviewer and merge, then cleans up ordinarily. Implementer failure, dirty or missing committed work, validation failure, and reviewer findings block the first affected declared unit. `delegate_flow_continue({ guidance, modelClass? })` launches a fresh ephemeral child with the frozen Implementer Role in that same Unit Worktree once, with original requirements, authoritative validation, previous block evidence, and Main guidance. Omitted continuation class retains the Unit's current class; a supplied class replaces it for that one repair, including any subsequent Reviewer launch. A second block is terminal. Failed rebase, evidence/Reviewer, and other infrastructure failures retain worktrees. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact integrated tip; otherwise it is terminal. Earlier integrations are never rolled back.
 
 ## Consequences
 
-Flow owns its narrow deterministic Git protocol while allowing user-owned Implementer and Reviewer policy through same-named Role overrides. Overrides do not change Flow's validation, exact review packet, approval, integration, or cleanup protocol. Flow has no dependency graph, saved recovery, automatic retry, aggregate review, or post-merge validation. Units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants must be combined or sequenced outside Flow.
+Flow owns narrow deterministic Git mechanics while allowing user-owned Implementer and conditional Reviewer policy through same-named Role overrides. Overrides do not change validation authority, exact review protocol, approval, integration, or cleanup. Flow has no dependency graph, saved recovery, automatic retry, aggregate review, post-merge validation, Planner Role, or generic-role restriction. Units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants must be combined or sequenced outside Flow.

package/docs/orchestration.md

@@ -10,9 +10,9 @@ caller-owned task, cwd, signal ────────────────
                                      active-Pi ephemeral executor
 ```
 
-`delegate_task` owns its flat single/parallel/chain policy. The public executor runs one prepared delegation. Downstream packages compose their own workflows with ordinary JavaScript and own semantic protocols, shared workspace/state, retry decisions, and bounds. There is no recursive workflow AST.
+Main plans and orchestrates. `delegate_task` owns its flat single/parallel/chain policy, while the public executor runs one prepared delegation. Downstream packages compose their own workflows with ordinary JavaScript and own semantic protocols, shared workspace/state, retry decisions, and bounds. There is no recursive workflow AST.
 
-`delegate_flow` is the exception: it is a fixed package-owned Git workflow, not an executor primitive or general workflow language. It uses the effective `implementer` and `reviewer` Roles and the same prepared-child runner; its contract is below.
+`delegate_flow` is the exception: it is a fixed package-owned Git workflow, not an executor primitive or general workflow language. It uses the effective `implementer` Role and, only for explicit judgment review, the effective `reviewer` Role through the same prepared-child runner; its contract is below.
 
 ## Frozen `delegate_task` contract
 
@@ -67,11 +67,11 @@ Single mode puts one delegation's fields at the top level.
 | --- | --- | --- |
 | `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`); a same-named user file overrides the built-in. |
 | `task` | yes | Non-empty bounded task packet. |
-| `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`. |
-| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; omission uses shared task assignment. |
-| `thinking` | no | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; route selection skips models that cannot honor it. |
+| `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`, and Main supplies it only for an explicit user override. |
+| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; Main normally chooses `fast`, may choose `balanced` upfront for obvious complexity, and omission uses shared task assignment. |
+| `thinking` | no | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; Main supplies it only for an explicit user override. Route selection skips models that cannot honor it. |
 
-Those five fields are the complete delegation object. `tasks`, `chain`, and `background` cannot be nested. Route fallback occurs only before launch; a started child is never retried by this package.
+Those five fields are the complete delegation object. The direct-model/thinking rule is Main-facing policy only: the runtime adds no provenance tracking or enforcement. `tasks`, `chain`, and `background` cannot be nested. Route fallback occurs only before launch; a started child is never retried by this package.
 
 ### Background, failures, and transport
 
@@ -83,9 +83,9 @@ All Main-visible text for one tool call shares one aggregate 50 KiB UTF-8 transp
 
 ## `delegate_flow`
 
-`delegate_flow({ units })` accepts 1–8 units with unique non-empty `id` and `task` fields plus one or more direct `{command, args}` validation commands. `delegate_flow_continue({ guidance })` is available only for the one blocked unit of the active Flow.
+`delegate_flow({ units })` accepts 1–8 units with unique non-empty `id` and `task`, one or more direct `{command, args}` validation commands, optional `modelClass`, and optional non-empty `review` text. `delegate_flow_continue({ guidance, modelClass? })` is available only for the one blocked unit of the active Flow.
 
-A Flow is memory-only and permits one active Flow. At start it resolves the effective `implementer` and `reviewer` Roles, including same-named user overrides, and freezes them through any continuation. Overrides must preserve the Flow Role protocols: Implementers commit scoped work, and Reviewers inspect the exact packet and emit exactly `PASS` only with zero findings. It requires clean committed Git Main and creates every Unit Worktree before launching work; setup failure launches no Implementer. Each unit gets exactly one worktree and one Implementer. Implementers run in parallel and all settle. Flow then processes units in declared order:
+A Flow is memory-only and permits one active Flow. At start it always resolves/freezes the effective `implementer` Role, including a same-named user override. It resolves/freezes the effective `reviewer` only if at least one requested unit declares `review`. Omitted unit classes use the shared `pi-subagent/delegateTask` assignment; a selected class resolves through its existing `pi-task-models` profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It requires clean committed Git Main and creates every Unit Worktree before launching work; setup failure launches no Implementer. Each unit gets exactly one worktree and one Implementer. Implementers run in parallel and all settle. Flow then processes units in declared order:
 
 ```text
 Implementers (parallel, one Unit Worktree each)
@@ -93,19 +93,20 @@ Implementers (parallel, one Unit Worktree each)
                  v
 for each declared unit:
   rebase in its Unit Worktree when earlier units advanced Main
-  run declared validation in that worktree
-  read-only Reviewer receives exact {base, tip, patchPath} there
-  exact PASS → git merge --ff-only <full reviewed OID>
+  inspect committed state; run declared validation (objective authority)
+  ├─ no review: git merge --ff-only <exact validated tip>
+  └─ review: Reviewer receives exact {base, tip, patchPath}
+             exact PASS → git merge --ff-only <full reviewed OID>
   git worktree remove; git branch -d
 ```
 
-Flow derives identity from Git, not child output. Reviewer reads the exact patch as authoritative and may use the same worktree only for referenced context. A full-OID fast-forward is the only integration path. Cleanup is non-forced; after a successful integration, cleanup refusal returns `completed` with a retained path/branch warning.
+Flow derives identity from Git, not child output. Add `review` only for an explicit judgment criterion that automated validation cannot establish; it is not a second generic verification pass. The Reviewer reads the exact patch as authoritative and may use the same worktree only for referenced context. A full-OID fast-forward is the only integration path. Cleanup is non-forced; after a successful integration, cleanup refusal returns `completed` with a retained path/branch warning.
 
-If rebase drops all unit commits, `base === tip` is a no-op: Flow validates current state, skips Reviewer and merge, then cleans up ordinarily. Implementer failure, dirty or missing committed work, validation failure, or reviewer findings block the first affected declared unit. `delegate_flow_continue({ guidance })` reruns the Flow's frozen Implementer Role in that same worktree once, then repeats derivation, validation, and review with fresh exact evidence. A second block is terminal. A failed rebase is aborted and terminates as an infrastructure failure with Git diagnostics; other infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact reviewed tip; otherwise it is terminal. Terminal outcomes retain worktrees for Main to reslice. Earlier integrated units are never rolled back.
+If rebase drops all unit commits, `base === tip` is a no-op: Flow validates current state, skips Reviewer and merge, then cleans up ordinarily. Implementer failure, dirty or missing committed work, validation failure, or reviewer findings block the first affected declared unit. `delegate_flow_continue({ guidance, modelClass? })` reruns the Flow's frozen Implementer Role in that same worktree once, then repeats derivation, validation, and conditional review with fresh exact evidence. Omitting continuation `modelClass` retains the blocked unit's current class; providing it replaces that class for the one repair. A second block is terminal. A failed rebase is aborted and terminates as an infrastructure failure with Git diagnostics; other infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Main is clean at the exact integrated tip; otherwise it is terminal. Terminal outcomes retain worktrees for Main to reslice. Earlier integrated units are never rolled back.
 
 Flow has no dependency graph, saved state, automatic retry, aggregate review, or post-merge validation. Use it only for commuting changes; combine or sequence units that overlap files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.
 
-`delegate_task` remains generic: its optional worktree isolation, non-Git behavior, and direct plan/file review are unchanged. Flow uses the same effective Role resolution for `implementer` and `reviewer`, with package-shipped Roles as defaults.
+`delegate_task` remains generic: its optional worktree isolation, non-Git behavior, and direct plan/file review are unchanged. Flow uses package-shipped Roles as defaults while retaining same-named user Role overrides; the Reviewer is needed only for a requested review criterion.
 
 ## Per-delegation resources and isolation
 
@@ -356,7 +357,7 @@ The package ships two working built-in Roles, validated by the same parser as us
 | Built-in | Behavior |
 | --- | --- |
 | `implementer` | Focused implementation requesting `isolation: worktree`; commits scoped changes locally, never pushes or opens PRs without authorization. Non-Git or unborn-`HEAD` contexts may use Main's cwd. |
-| `reviewer` | Read-only correctness review of supplied plans/files, or Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits. |
+| `reviewer` | Read-only correctness review of supplied plans/files, or—when a Flow unit declares `review`—Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits. |
 
 A same-named Markdown file in `config/pi-subagent/` explicitly overrides the built-in default.
 
@@ -376,6 +377,6 @@ cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
 
 The package never creates, copies, updates, or removes files in `~/.pi/agent/config/pi-subagent/`. Once copied, the files and their names are entirely user-owned.
 
-The bundled [`pi-subagent-delegated-development`](../skills/pi-subagent-delegated-development/SKILL.md) Skill is Main-side policy only. `delegate_flow` owns its fixed Git mechanics; the Skill defines no runtime code or configuration. `delegate_task` remains the generic flat single/parallel/chain mechanism.
+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 objective validation authority; the Skill defines no runtime code or configuration. `delegate_task` remains the generic flat single/parallel/chain mechanism.
 
 See [ADR 001](./adr/001-composable-ephemeral-execution.md) for the executor boundary and [ADR 002](./adr/002-package-owned-delegate-flow-orchestration.md) for Flow.

package/examples/roles/reviewer.md

@@ -15,9 +15,9 @@ Perform a read-only correctness review of one bounded change.
 Support exactly two review modes:
 
 1. For ordinary delegation, review the supplied plan and explicitly named files directly. Do not prepare Git, require commits, or require a patch packet.
-2. For Flow exact review, require a Review Packet `{base, tip, patchPath}` and the same assigned Unit Worktree context. Read that exact patch as authoritative, then read only the files it references and relevant contract context. Do not infer a diff from a branch or another worktree.
+2. For Flow exact review, only when the task supplies an explicit judgment criterion, require a Review Packet `{base, tip, patchPath}` and the same assigned Unit Worktree context. Declared validation is authoritative for objective verification; judge only that criterion. Read the exact patch as authoritative, then read only the files it references and relevant criterion context. Do not infer a diff from a branch or another worktree.
 
-In either mode, review only the supplied requirements and explicitly referenced context. Use only `read`, `grep`, `find`, or `ls` for that review. Check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not run commands or tests. Never manage Main, Git, or tests; never edit or write files, commit, push, or otherwise modify state.
+In either mode, review only the supplied requirements and explicitly referenced context. Use only `read`, `grep`, `find`, or `ls` for that review. For ordinary delegation, check correctness, regressions, trust-boundary validation, error handling, and missing high-value tests. Do not run commands or tests. Never manage Main, Git, or tests; never edit or write files, commit, push, or otherwise modify state.
 
 Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 

package/extensions/delegate-flow.ts

@@ -1,5 +1,6 @@
-import type { Usage } from "@earendil-works/pi-ai";
+import { StringEnum, type Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PROFILE_NAMES } from "@henryqw/pi-task-models";
 import {
 	addUsage,
 	capEphemeralSubagentOutput as capOutput,
@@ -28,10 +29,14 @@ const ValidationSchema = Type.Object({
 	args: Type.Array(Type.String()),
 }, { additionalProperties: false });
 
+const ModelClassSchema = StringEnum(PROFILE_NAMES, { description: "Task model profile" });
+
 const UnitSchema = Type.Object({
 	id: Type.String({ minLength: 1 }),
 	task: Type.String({ minLength: 1 }),
 	validation: Type.Array(ValidationSchema, { minItems: 1 }),
+	modelClass: Type.Optional(ModelClassSchema),
+	review: Type.Optional(Type.String({ minLength: 1 })),
 }, { additionalProperties: false });
 
 export const DelegateFlowSchema = Type.Object({
@@ -40,10 +45,12 @@ export const DelegateFlowSchema = Type.Object({
 
 export const DelegateFlowContinueSchema = Type.Object({
 	guidance: Type.String({ minLength: 1 }),
+	modelClass: Type.Optional(ModelClassSchema),
 }, { additionalProperties: false });
 
 type FlowRequest = Static<typeof DelegateFlowSchema>;
 type FlowUnitRequest = Static<typeof UnitSchema>;
+type FlowModelClass = FlowUnitRequest["modelClass"];
 type FlowClassification = "setup" | "implementer" | "validation" | "reviewer_findings" | "main" | "infrastructure" | "integration";
 type FlowPhase = "running" | "blocked";
 type WidgetStatus = "success" | "failure" | "aborted";
@@ -54,6 +61,7 @@ type ChildSettlement =
 
 type UnitState = {
 	request: FlowUnitRequest;
+	modelClass: FlowModelClass;
 	worktree: WorktreeInfo;
 	base: string;
 	implementation?: ChildSettlement;
@@ -87,7 +95,7 @@ type FlowState = {
 	generation: number;
 	sessionController: AbortController;
 	implementer: Role;
-	reviewer: Role;
+	reviewer?: Role;
 	main?: MainState;
 	units: UnitState[];
 	setupRecoveries: SetupRecovery[];
@@ -111,7 +119,7 @@ export interface DelegateFlowRuntime {
 	maxRuntimeMs: number;
 	getSessionGeneration: () => number;
 	loadRoles: () => Role[];
-	resolveLaunch: (role: Role, ctx: ExtensionContext) => ResolvedRoleLaunch;
+	resolveLaunch: (role: Role, modelClass: FlowModelClass, ctx: ExtensionContext) => ResolvedRoleLaunch;
 	startWidget: (
 		id: string,
 		role: string,
@@ -150,6 +158,8 @@ export function parseDelegateFlow(value: unknown): FlowRequest {
 					command: text(validation.command, `units[${unitIndex}].validation[${validationIndex}].command`),
 					args: validation.args.map((value, argumentIndex) => argument(value, `units[${unitIndex}].validation[${validationIndex}].args[${argumentIndex}]`)),
 				})),
+				...(unit.modelClass === undefined ? {} : { modelClass: unit.modelClass }),
+				...(unit.review === undefined ? {} : { review: text(unit.review, `units[${unitIndex}].review`) }),
 			};
 		}),
 	};
@@ -157,7 +167,10 @@ export function parseDelegateFlow(value: unknown): FlowRequest {
 
 export function parseDelegateFlowContinue(value: unknown): Static<typeof DelegateFlowContinueSchema> {
 	if (!Check(DelegateFlowContinueSchema, value)) throw new Error("delegate_flow_continue must match the declared tool schema.");
-	return { guidance: text(value.guidance, "guidance") };
+	return {
+		guidance: text(value.guidance, "guidance"),
+		...(value.modelClass === undefined ? {} : { modelClass: value.modelClass }),
+	};
 }
 
 function errorText(error: unknown): string {
@@ -176,6 +189,11 @@ function implementerTask(unit: FlowUnitRequest): string {
 	return [
 		`Flow Unit ${JSON.stringify(unit.id)} requirements:`,
 		unit.task,
+		...(unit.review === undefined ? [] : [
+			"",
+			"Review criterion to satisfy; the Reviewer alone decides approval:",
+			unit.review,
+		]),
 		"",
 		"Authoritative Flow validation (do not duplicate this final gate):",
 		...unit.validation.map((validation) => `- ${JSON.stringify(validation)}`),
@@ -188,6 +206,11 @@ function repairTask(unit: FlowUnitRequest, blocked: BlockedState, guidance: stri
 		"",
 		"Original requirements:",
 		unit.task,
+		...(unit.review === undefined ? [] : [
+			"",
+			"Review criterion to satisfy; the Reviewer alone decides approval:",
+			unit.review,
+		]),
 		"",
 		"Authoritative Flow validation (do not duplicate this final gate):",
 		...unit.validation.map((validation) => `- ${JSON.stringify(validation)}`),
@@ -200,16 +223,19 @@ function repairTask(unit: FlowUnitRequest, blocked: BlockedState, guidance: stri
 	].join("\n");
 }
 
-function reviewerTask(unit: FlowUnitRequest, packet: { base: string; tip: string; patchPath: string }): string {
+function reviewerTask(unit: FlowUnitRequest, review: string, packet: { base: string; tip: string; patchPath: string }): string {
 	return [
-		`Review Flow Unit ${JSON.stringify(unit.id)} against these requirements:`,
+		`Review Flow Unit ${JSON.stringify(unit.id)} for this explicit judgment criterion:`,
+		review,
+		"",
+		"Original requirements (context only):",
 		unit.task,
 		"",
-		"Declared validation already passed:",
+		"Declared validation already passed and is authoritative for objective verification:",
 		...unit.validation.map((validation) => `- ${JSON.stringify(validation)}`),
 		"",
 		`Review Packet: ${JSON.stringify(packet)}`,
-		"Read the exact patch as authoritative and emit exactly PASS only when there are zero findings.",
+		"Review only the criterion above. Read the exact patch as authoritative and emit exactly PASS only when there are zero findings.",
 	].join("\n");
 }
 
@@ -308,6 +334,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 	const runChild = async (
 		flow: FlowState,
 		role: Role,
+		modelClass: FlowModelClass,
 		task: string,
 		cwd: string,
 		widgetId: string,
@@ -323,7 +350,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				onTokens: (tokens) => runtime.updateWidgetTokens(widgetId, tokens),
 				prepare: async () => {
 					assertCurrent(flow);
-					const launch = runtime.resolveLaunch(role, ctx);
+					const launch = runtime.resolveLaunch(role, modelClass, ctx);
 					if (launch.missingSkills.length) {
 						ctx.ui.notify(`Subagent role ${role.name} skipped unavailable Pi skills: ${launch.missingSkills.join(", ")}.`, "warning");
 					}
@@ -624,45 +651,53 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				continue;
 			}
 
-			let evidence;
-			try {
-				evidence = await prepareExactReviewEvidence({ base: main.expectedHead, tip, worktree: unit.worktree.path }, signal);
-			} catch (error) {
-				return terminal(flow, "infrastructure", errorText(error), meter);
-			}
-
-			let review: ChildSettlement;
-			let cleanupError: unknown;
-			try {
-				assertCurrent(flow);
-				review = await runChild(
-					flow,
-					flow.reviewer,
-					reviewerTask(unit.request, { base: evidence.base, tip: evidence.tip, patchPath: evidence.patchPath }),
-					unit.worktree.cwd,
-					`${toolCallId}:flow:${flow.index}:review`,
-					signal,
-					ctx,
-					meter,
-				);
-			} finally {
+			let approvedTip = tip;
+			const reviewCriterion = unit.request.review;
+			if (reviewCriterion !== undefined) {
+				const reviewer = flow.reviewer;
+				if (!reviewer) return terminal(flow, "infrastructure", "Flow Reviewer was not resolved for a unit that requires review.", meter);
+				let evidence;
 				try {
-					await evidence.cleanup();
+					evidence = await prepareExactReviewEvidence({ base: main.expectedHead, tip, worktree: unit.worktree.path }, signal);
 				} catch (error) {
-					cleanupError = error;
+					return terminal(flow, "infrastructure", errorText(error), meter);
 				}
-			}
-			if (cleanupError !== undefined) return terminal(flow, "infrastructure", errorText(cleanupError), meter);
-			assertCurrent(flow);
-			if ("error" in review) return terminal(flow, "infrastructure", errorText(review.error), meter);
-			if (review.result.outcome !== "success") {
-				return terminal(flow, "infrastructure", settlementFailure(review)!, meter);
-			}
-			if (TRUNCATED_OUTPUT.test(review.result.output)) {
-				return terminal(flow, "infrastructure", "Reviewer transport output was truncated; approval is invalid.", meter);
-			}
-			if (review.result.output.trim() !== "PASS") {
-				return block(flow, unit, "reviewer_findings", review.result.output || "Reviewer returned no PASS approval.", meter);
+
+				let review: ChildSettlement;
+				let cleanupError: unknown;
+				try {
+					assertCurrent(flow);
+					review = await runChild(
+						flow,
+						reviewer,
+						unit.modelClass,
+						reviewerTask(unit.request, reviewCriterion, { base: evidence.base, tip: evidence.tip, patchPath: evidence.patchPath }),
+						unit.worktree.cwd,
+						`${toolCallId}:flow:${flow.index}:review`,
+						signal,
+						ctx,
+						meter,
+					);
+				} finally {
+					try {
+						await evidence.cleanup();
+					} catch (error) {
+						cleanupError = error;
+					}
+				}
+				if (cleanupError !== undefined) return terminal(flow, "infrastructure", errorText(cleanupError), meter);
+				assertCurrent(flow);
+				if ("error" in review) return terminal(flow, "infrastructure", errorText(review.error), meter);
+				if (review.result.outcome !== "success") {
+					return terminal(flow, "infrastructure", settlementFailure(review)!, meter);
+				}
+				if (TRUNCATED_OUTPUT.test(review.result.output)) {
+					return terminal(flow, "infrastructure", "Reviewer transport output was truncated; approval is invalid.", meter);
+				}
+				if (review.result.output.trim() !== "PASS") {
+					return block(flow, unit, "reviewer_findings", review.result.output || "Reviewer returned no PASS approval.", meter);
+				}
+				approvedTip = evidence.tip;
 			}
 
 			try {
@@ -671,12 +706,12 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				return terminal(flow, "main", errorText(error), meter);
 			}
 			assertCurrent(flow);
-			const merged = await git(["merge", "--no-overwrite-ignore", "--ff-only", evidence.tip], main.root, signal);
+			const merged = await git(["merge", "--no-overwrite-ignore", "--ff-only", approvedTip], main.root, signal);
 			assertCurrent(flow);
 			if (merged.code !== 0 || merged.killed) {
-				const diagnostic = commandFailure(`git merge --no-overwrite-ignore --ff-only ${evidence.tip}`, merged);
+				const diagnostic = commandFailure(`git merge --no-overwrite-ignore --ff-only ${approvedTip}`, merged);
 				const previousHead = main.expectedHead;
-				main.expectedHead = evidence.tip;
+				main.expectedHead = approvedTip;
 				try {
 					await checkMain(main);
 				} catch (error) {
@@ -688,7 +723,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					].join("\n")), meter);
 				}
 				flow.warnings.push(capOutput(`Unit ${JSON.stringify(unit.request.id)} integrated after merge reported failure: ${diagnostic}`));
-			} else main.expectedHead = evidence.tip;
+			} else main.expectedHead = approvedTip;
 			flow.completed.push({ id: unit.request.id, noOp: false });
 			try {
 				await checkMain(main);
@@ -696,7 +731,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				return terminal(flow, "integration", errorText(error), meter);
 			}
 			assertCurrent(flow);
-			const cleanupWarning = await cleanupUnit(unit, main, evidence.tip, flow.sessionController.signal);
+			const cleanupWarning = await cleanupUnit(unit, main, approvedTip, flow.sessionController.signal);
 			assertCurrent(flow);
 			if (cleanupWarning) flow.warnings.push(`Unit ${JSON.stringify(unit.request.id)} integrated, but cleanup refused: ${cleanupWarning}`);
 			flow.index += 1;
@@ -709,12 +744,12 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 	pi.registerTool({
 		name: "delegate_flow",
 		label: "Delegate Flow",
-		description: "Run 1–8 independent Implementers in isolated Unit Worktrees, then validate, exactly review, and serially fast-forward approved units.",
-		promptSnippet: "Run a deterministic parallel-implementation, serial-review Flow",
+		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.",
-			"If a Flow blocks, inspect its classification and call delegate_flow_continue once with explicit repair guidance.",
+			"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.",
+			"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,
 		prepareArguments: parseDelegateFlow,
@@ -723,14 +758,16 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			if (active) throw new Error("delegate_flow rejected because another Flow is active.");
 			const roles = runtime.loadRoles();
 			const implementer = roles.find(({ name }) => name === "implementer");
-			const reviewer = roles.find(({ name }) => name === "reviewer");
-			if (!implementer || !reviewer) throw new Error("delegate_flow requires implementer and reviewer Roles.");
+			const needsReviewer = request.units.some(({ review }) => review !== undefined);
+			const reviewer = needsReviewer ? roles.find(({ name }) => name === "reviewer") : undefined;
+			if (!implementer) throw new Error("delegate_flow requires an implementer Role.");
+			if (needsReviewer && !reviewer) throw new Error("delegate_flow requires a reviewer Role when a unit declares review.");
 			const flow: FlowState = {
 				phase: "running",
 				generation: runtime.getSessionGeneration(),
 				sessionController: new AbortController(),
 				implementer,
-				reviewer,
+				...(reviewer === undefined ? {} : { reviewer }),
 				units: [],
 				setupRecoveries: [],
 				index: 0,
@@ -762,6 +799,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					if (!worktree) throw new Error("Flow Unit Worktrees require a Git repository with a committed HEAD; generic cwd fallback is disabled.");
 					flow.units.push({
 						request: unit,
+						modelClass: unit.modelClass,
 						worktree,
 						base: worktree.baseCommit,
 						repairUsed: false,
@@ -777,6 +815,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				const settlements = await Promise.all(flow.units.map((unit, index) => runChild(
 					flow,
 					flow.implementer,
+					unit.modelClass,
 					implementerTask(unit.request),
 					unit.worktree.cwd,
 					`${toolCallId}:flow:${index}:implement`,
@@ -805,13 +844,13 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 	pi.registerTool({
 		name: "delegate_flow_continue",
 		label: "Continue Delegate Flow",
-		description: "Repair the one blocked Flow Unit in its existing Unit Worktree, then resume declared-order validation, exact review, and integration.",
+		description: "Repair the one blocked Flow Unit in its existing Unit Worktree, optionally replace its model class, then resume declared-order validation, conditional exact review, and integration.",
 		promptSnippet: "Repair and continue the blocked deterministic Flow",
 		promptGuidelines: ["Call delegate_flow_continue only after delegate_flow reports a repairable block, with explicit guidance addressing that block."],
 		parameters: DelegateFlowContinueSchema,
 		prepareArguments: parseDelegateFlowContinue,
 		async execute(toolCallId, params, signal, _onUpdate, ctx) {
-			const { guidance } = parseDelegateFlowContinue(params);
+			const { guidance, modelClass } = parseDelegateFlowContinue(params);
 			const flow = active;
 			if (!flow) throw new Error("delegate_flow_continue requires an active blocked Flow.");
 			assertCurrent(flow);
@@ -822,12 +861,14 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			flow.phase = "running";
 			flow.blocked = undefined;
 			unit.repairUsed = true;
+			if (modelClass !== undefined) unit.modelClass = modelClass;
 			const operationSignal = bindSignal(flow, signal);
 			const meter: UsageMeter = {};
 			try {
 				unit.implementation = await runChild(
 					flow,
 					flow.implementer,
+					unit.modelClass,
 					repairTask(unit.request, blocked, guidance),
 					unit.worktree.cwd,
 					`${toolCallId}:flow:${flow.index}:repair`,

package/extensions/subagent.ts

@@ -443,11 +443,13 @@ export default function subagentExtension(
 		maxRuntimeMs: timeoutPolicy.maxMs,
 		getSessionGeneration: () => sessionEpoch,
 		loadRoles,
-		resolveLaunch: (role, ctx) => {
+		resolveLaunch: (role, modelClass, ctx) => {
 			const launchCtx = latestCtx ?? ctx;
 			return createRoleLaunch(pi, launchCtx, {
 				role,
-				route: resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK),
+				route: modelClass === undefined
+					? resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK)
+					: resolveTaskRoute(launchCtx, modelClass),
 			});
 		},
 		startWidget: startWidgetItem,
@@ -463,7 +465,7 @@ export default function subagentExtension(
 		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.",
-			"For each delegate_task entry, use fav only when the user asks for their favorite model; otherwise choose fast for narrow work, balanced for normal work, and frontier only for ambiguous, cross-cutting, or high-risk work.",
+			"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": "5.0.0",
+  "version": "6.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -66,6 +66,6 @@
   "dependencies": {
     "@henryqw/pi-herdr": "^0.4.0",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^1.0.0"
+    "@henryqw/pi-task-models": "^2.0.0"
   }
 }

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

@@ -5,28 +5,28 @@ description: Run bounded independent implementation through the runtime-managed
 
 # Delegated Development
 
-You are Main: slice work and call `delegate_flow`. Do not implement child work yourself or use external model tools, push, publish, or release.
+You are Main, the planner/orchestrator: slice work and call `delegate_flow`. Do not implement child work yourself or use external model tools, push, publish, or release.
 
 ## Slice
 
 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.
 
-Give every unit a bounded objective, owned scope and exclusions, acceptance criteria, and its direct validation command/argument array. Do not pass the parent request unchanged. Call `delegate_flow` with 1–8 units; the runtime supplies the effective Implementer and Reviewer Roles.
+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.
 
 ## Runtime Flow
 
-The runtime owns the unit worktrees and all Git identity, rebasing, declared validation, exact read-only review, fast-forward integration, and cleanup. It records the clean committed Main state, runs independent Implementers in isolated unit worktrees, processes units in declared order, and integrates only the exact reviewed tip OID.
+The runtime owns the unit worktrees and all Git identity, rebasing, committed-state inspection, declared validation, conditional exact read-only review, fast-forward integration, and cleanup. Declared validation is the authority for objective verification. A validated unit without `review` skips review evidence and Reviewer launch, then integrates its exact validated tip. A unit with `review` receives the existing exact `{base, tip, patchPath}` protocol and must receive exactly `PASS` before integration.
 
 Trust the structured Flow outcome. Never edit a child worktree, manage its branches, prepare review evidence, reimplement Flow, or manually integrate its changes. Do not repeat Flow validation after it has completed or integrated a unit.
 
-A successful Flow owns integration and cleanup. A blocked outcome is repairable: provide one explicit continuation and no more:
+A successful Flow owns integration and cleanup. A blocked outcome is repairable once: provide one explicit continuation and no more:
 
 ```ts
-delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit." })
+delegate_flow_continue({ guidance: "Address the reported block and complete the bounded unit.", modelClass: "balanced" })
 ```
 
-Make the guidance specific to the reported implementation, validation, or review failure. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect every retained path reported by the runtime, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. A cleanup warning does not undo successful integration.
+Make the guidance specific to the reported implementation, validation, or review failure. Omit `modelClass` to retain the blocked unit's current class; supply it only to replace that one repair's class. Do not call continuation unless Flow reports a repairable block. If continuation or Flow returns a terminal failure, inspect every retained path reported by the runtime, then reslice or manually recover from Main; do not retry the Flow or guess a rebase resolution. A cleanup warning does not undo successful integration.
 
 ## Ordinary delegation
 
-Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Preserve ordinary Role selection and isolation behavior. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.
+Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Populate direct `model` and `thinking` only when the user explicitly asks for those overrides; otherwise choose only `modelClass` (`fast` normally, `balanced` upfront for obviously complex work). Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.