@henryqw/pi-subagent 6.1.0 → 7.0.0

package/CONTEXT.md

@@ -28,10 +28,10 @@ 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 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.
+- Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`); library callers select a Role plus their own Model Task declaration.
 - 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, 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.
+- `delegate_flow` accepts 1–8 independent units with direct validation commands, optional `modelClass`, and optional non-empty `review` judgment text. Omitted classes use pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); 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.

package/README.md

@@ -30,7 +30,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 a compact self-rendered shell and never exceed five physical lines, including Pi's leading spacer: one call line plus at most three result lines in either collapsed or 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—no expanded view.
 
 ### `delegate_task`
 
@@ -47,13 +47,13 @@ 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 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 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.
 
 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.
 
 Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
 
-The transient two-line status widget owns deterministic live progress: status and task summary above thinking or the active tool (with elapsed time and path basename), completed turns, started tools, model, thinking level, tokens, and total duration; terminal activity is Done, Failed, or Stopped. At capacity, it evicts the oldest terminal row so new active work remains visible, and terminal rows otherwise clear on the next real user input. The final `delegate_task` block is deliberately minimal: bounded final summaries, role attribution for parallel/chain, and only retained-worktree recovery paths. It has no expanded view.
+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.
 
 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.
 
@@ -70,15 +70,27 @@ 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.
 
-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.
+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.
 
 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.
 
+### Delegate UI summary
+
+| Aspect | Behavior |
+| --- | --- |
+| Call label | `delegate_task · single/parallel/chain · N task(s)`; `delegate_flow · parallel→serial · N unit(s)`; `delegate_flow_continue · repair continuation` |
+| Partial progress | `delegate_task`: aggregate counts (running/pending/complete/failed/skipped); `delegate_flow`: phase transitions (setup → implement → verify/integrate → review → repair) |
+| Widget rows | One line per child: glyph, role, status, task, activity, metrics |
+| Ordering | Active-first stable (working first, then insertion order) |
+| Line cap | 6 physical lines max (≤6 items: all child rows; >6 items: 5 rows + 1 status-aware overflow) |
+| Terminal retention | Active rows persist; terminal rows clear on next user input |
+| Final result | Bounded summaries with recovery paths; no expanded view |
+
 ## 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`.
+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/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and timeouts. All fields are optional; a missing file uses defaults.
 
@@ -143,4 +155,4 @@ A Role explicitly owns base tools, extensions, named Skills, instructions, and o
 
 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.
 
-Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` against the latest Pi context.
+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.

package/dist/index.d.ts

@@ -1,12 +1,18 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type HerdrExecutor } from "@henryqw/pi-herdr";
-import { type AvailableModel, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
+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 { 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";
 export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "delegate_flow", "delegate_flow_continue", "ask_question"];
 export declare const CHILD_EXCLUDED_TOOLS: string;
+export declare const DELEGATE_TASK: {
+    readonly id: "pi-subagent/delegateTask";
+    readonly label: "Subagent delegation";
+    readonly purpose: "Launch an isolated Pi subagent.";
+    readonly defaultProfile: "fast";
+};
 export interface Role {
     name: string;
     description: string;
@@ -33,7 +39,7 @@ export interface CreateRoleLaunchInput {
     env?: Readonly<Record<string, string>>;
 }
 export interface ResolveRoleLaunchInput extends Omit<CreateRoleLaunchInput, "route"> {
-    taskId: string;
+    task: ModelTask;
     agentDir?: string;
 }
 export interface ResolvedRoleSkills {

package/dist/index.js

@@ -15,6 +15,12 @@ export const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 export const CHILD_EXCLUDED_TOOL_NAMES = ["delegate_task", "delegate_flow", "delegate_flow_continue", "ask_question"];
 export const CHILD_EXCLUDED_TOOLS = CHILD_EXCLUDED_TOOL_NAMES.join(",");
 const CHILD_IDENTITY_POLICY = "You are a delegated Pi Subagent, not Main. Execute the assigned Role and task directly. Main-only delegation rules do not apply. Recursive delegation is unavailable; do not seek or invoke delegation tools.";
+export const DELEGATE_TASK = {
+    id: "pi-subagent/delegateTask",
+    label: "Subagent delegation",
+    purpose: "Launch an isolated Pi subagent.",
+    defaultProfile: "fast",
+};
 const cleanText = (value, field, source) => {
     if (typeof value !== "string" || !value.trim() || value.includes("\0")) {
         throw new Error(`${source}: ${field} must be non-empty text.`);
@@ -186,10 +192,9 @@ export function createRoleLaunch(pi, ctx, input) {
     };
 }
 export function resolveRoleLaunch(pi, ctx, input) {
-    const taskId = cleanText(input.taskId, "task ID", "Role launch");
     return createRoleLaunch(pi, ctx, {
         ...input,
-        route: resolveConfiguredTaskRoute(ctx, taskId, input.agentDir),
+        route: resolveConfiguredTaskRoute(ctx, input.task, input.agentDir),
     });
 }
 function launchEnvironmentArgs(launch) {

package/docs/orchestration.md

@@ -5,7 +5,7 @@
 ```text
 Role (built-in or user override) + latest Pi registries ── resolveRoleLaunch ──> PiLaunch
                                                         │
-caller-owned task, cwd, signal ─────────────────────────┤
+caller-owned Model Task declaration, cwd, signal ────────┤
                                                         v
                                      active-Pi ephemeral executor
 ```
@@ -68,7 +68,7 @@ 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`, 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. |
+| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; Main normally chooses `fast`, may choose `balanced` upfront for obvious complexity, and omission uses pi-subagent's local Model Task declaration. |
 | `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. 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.
@@ -85,7 +85,7 @@ All Main-visible text for one tool call shares one aggregate 50 KiB UTF-8 transp
 
 `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 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:
+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 pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); 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)
@@ -149,12 +149,12 @@ The package root exports the following mechanism-level APIs:
 | --- | --- |
 | `loadRoles(agentDir?)` | Validate and load package-shipped built-in and user Role Markdown. |
 | `resolveRoleSkills(pi, role)` | Resolve Role Skill names from Pi's effective registry. |
-| `resolveRoleLaunch(pi, ctx, input)` | Resolve a shared task route and produce `ResolvedRoleLaunch`. |
+| `resolveRoleLaunch(pi, ctx, input)` | Resolve a caller-owned Model Task route and produce `ResolvedRoleLaunch`. |
 | `createRoleLaunch(pi, ctx, input)` | Produce the same launch from a caller-supplied resolved route. |
 | `createEphemeralSubagentExecutor(options)` | Queue and run one prepared no-session child per `run`. |
 | `createChildWorktree` / `finalizeChildWorktree` | Optional caller-managed worktree lifecycle. |
 
-A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, `taskId`, and optional caller `agentDir`, `extensions`, `tools`, and `env`. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
+A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, a caller-owned `task` Model Task declaration, and optional caller `agentDir`, `extensions`, `tools`, and `env`. At extension load, callers invoke `registerModelTask(pi, task)` from `@henryqw/pi-task-models` once to expose that declaration in the shared control plane. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
 
 `createEphemeralSubagentExecutor` requires:
 
@@ -178,54 +178,69 @@ import {
   createEphemeralSubagentExecutor,
   resolveRoleLaunch,
 } from "@henryqw/pi-subagent";
+import { registerModelTask } from "@henryqw/pi-task-models";
 
-const executor = createEphemeralSubagentExecutor({
-  maxConcurrency: 4,
-  timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
-});
+const MODEL_TASK = {
+  id: "your-package/delegate",
+  label: "Package delegation",
+  purpose: "Run one package-owned delegated task.",
+  defaultProfile: "fast",
+};
 
-let latestCtx;
-pi.on("session_start", (_event, ctx) => { latestCtx = ctx; });
-pi.on("model_select", (event, ctx) => {
-  latestCtx = { ...ctx, model: event.model };
-});
-pi.on("agent_settled", (_event, ctx) => { latestCtx = ctx; });
+export function createRunRole(pi) {
+  // Register the Model Task at extension load so /task-models discovery works.
+  registerModelTask(pi, MODEL_TASK);
 
-function latestContext() {
-  if (!latestCtx) throw new Error("Pi session has not started.");
-  return latestCtx;
-}
+  const executor = createEphemeralSubagentExecutor({
+    maxConcurrency: 4,
+    timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
+  });
 
-async function runRole(role, task, options = {}) {
-  const {
-    signal,
-    cwd,
-    extensions = [],
-    tools,
-    env = {},
-  } = options;
-
-  return executor.run({
-    signal,
-    prepare: async () => {
-      // prepare runs only after this delegation owns a FIFO permit.
-      const ctx = latestContext();
-      const launch = resolveRoleLaunch(pi, ctx, {
-        role,
-        taskId: "your-package/delegate",
-        extensions,
-        tools,
-        env,
-      });
-      if (launch.missingSkills.length && ctx.hasUI) {
-        ctx.ui.notify(
-          `Skipped unavailable Skills: ${launch.missingSkills.join(", ")}`,
-          "warning",
-        );
-      }
-      return { launch, task, cwd: cwd ?? ctx.cwd };
-    },
+  let latestCtx;
+  pi.on("session_start", (_event, ctx) => { latestCtx = ctx; });
+  pi.on("model_select", (event, ctx) => {
+    latestCtx = { ...ctx, model: event.model };
   });
+  pi.on("agent_settled", (_event, ctx) => { latestCtx = ctx; });
+
+  function latestContext() {
+    if (!latestCtx) throw new Error("Pi session has not started.");
+    return latestCtx;
+  }
+
+  async function runRole(role, task, options = {}) {
+    const {
+      signal,
+      cwd,
+      extensions = [],
+      tools,
+      env = {},
+    } = options;
+
+    return executor.run({
+      signal,
+      prepare: async () => {
+        // prepare runs only after this delegation owns a FIFO permit.
+        const ctx = latestContext();
+        const launch = resolveRoleLaunch(pi, ctx, {
+          role,
+          task: MODEL_TASK,
+          extensions,
+          tools,
+          env,
+        });
+        if (launch.missingSkills.length && ctx.hasUI) {
+          ctx.ui.notify(
+            `Skipped unavailable Skills: ${launch.missingSkills.join(", ")}`,
+            "warning",
+          );
+        }
+        return { launch, task, cwd: cwd ?? ctx.cwd };
+      },
+    });
+  }
+
+  return { runRole };
 }
 ```
 
@@ -249,7 +264,17 @@ Generic managed Herdr exports (`managedSubagentWorkspaceId`, reconciliation help
 
 ## JavaScript composition
 
-The examples below use caller-selected `Role` objects and the `runRole` helper above. Variable names such as `reviewRole` are local bindings, not reserved Role names. The executor's `maxConcurrency` bounds launches; callers must also bound collections and loops.
+The examples below use caller-selected `Role` objects and the `runRole` function returned by the package's initializer. A consuming Pi extension calls the initializer once at startup:
+
+```js
+import { createRunRole } from "your-package";
+
+export default function yourExtension(pi) {
+  const { runRole } = createRunRole(pi);
+}
+```
+
+Variable names such as `reviewRole` are local bindings, not reserved Role names. The executor's `maxConcurrency` bounds launches; callers must also bound collections and loops.
 
 A small caller-owned failure policy keeps the examples readable:
 

package/extensions/delegate-flow.ts

@@ -108,6 +108,7 @@ type FlowState = {
 };
 
 type UsageMeter = { usage?: Usage };
+type FlowProgress = { line: string };
 
 type CommandResult = {
 	stdout: string;
@@ -176,9 +177,18 @@ export function parseDelegateFlowContinue(value: unknown): Static<typeof Delegat
 	};
 }
 
+function unitCount(count: number): string {
+	return `${count} unit${count === 1 ? "" : "s"}`;
+}
+
 function flowCallLabel(args: { units?: unknown }): string {
 	const count = Array.isArray(args.units) ? args.units.length : 0;
-	return `delegate_flow · working: ${count} unit${count === 1 ? "" : "s"}`;
+	return `delegate_flow · parallel→serial · ${unitCount(count)}`;
+}
+
+function isFlowProgress(value: unknown): value is FlowProgress {
+	return typeof value === "object" && value !== null && !Array.isArray(value)
+		&& typeof (value as { line?: unknown }).line === "string";
 }
 
 function flowResultLines(text: string): string[] {
@@ -609,6 +619,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		signal: AbortSignal | undefined,
 		ctx: ExtensionContext,
 		meter: UsageMeter,
+		emitProgress: (line: string) => void,
 	) => {
 		assertCurrent(flow);
 		const main = flow.main!;
@@ -624,6 +635,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 
 			const implementationFailure = settlementFailure(unit.implementation!);
 			if (implementationFailure) return block(flow, unit, "implementer", implementationFailure, meter);
+			emitProgress(`verify/integrate · unit ${flow.index + 1}/${flow.units.length}`);
 
 			let inspected = await inspectUnit(unit, false, signal);
 			assertCurrent(flow);
@@ -690,6 +702,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			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);
+				emitProgress(`review · unit ${flow.index + 1}/${flow.units.length}`);
 				let evidence;
 				try {
 					evidence = await prepareExactReviewEvidence({ base: main.expectedHead, tip, worktree: unit.worktree.path }, signal);
@@ -787,16 +800,16 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			"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,
-		renderShell: "self",
 		renderCall(args, theme, _context) {
 			return renderToolLines([theme.fg("toolTitle", flowCallLabel(args))], theme);
 		},
-		renderResult(result, _options, theme, _context) {
+		renderResult(result, { isPartial }, theme, _context) {
+			if (isPartial) return renderToolLines(isFlowProgress(result.details) ? [theme.fg("muted", result.details.line)] : [], theme);
 			const text = result.content.find((part) => part.type === "text")?.text ?? "(no output)";
 			return renderToolLines(flowResultLines(text), theme);
 		},
 		prepareArguments: parseDelegateFlow,
-		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const request = parseDelegateFlow(params);
 			if (active) throw new Error("delegate_flow rejected because another Flow is active.");
 			const roles = runtime.loadRoles();
@@ -805,6 +818,10 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			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 emitProgress = (line: string) => {
+				const progress: FlowProgress = { line };
+				onUpdate?.({ content: [{ type: "text", text: progress.line }], details: progress });
+			};
 			const flow: FlowState = {
 				phase: "running",
 				generation: runtime.getSessionGeneration(),
@@ -818,6 +835,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				warnings: [],
 			};
 			active = flow;
+			emitProgress(`setup · ${unitCount(request.units.length)}`);
 			const operationSignal = bindSignal(flow, signal);
 			const meter: UsageMeter = {};
 			let setupComplete = false;
@@ -855,6 +873,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				await checkMain(flow.main, operationSignal);
 				assertCurrent(flow);
 				setupComplete = true;
+				let completedImplementers = 0;
 				const settlements = await Promise.all(flow.units.map((unit, index) => runChild(
 					flow,
 					flow.implementer,
@@ -866,11 +885,15 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					operationSignal,
 					ctx,
 					meter,
-				)));
+				).then((settlement) => {
+					completedImplementers += 1;
+					emitProgress(`implement · ${completedImplementers}/${flow.units.length} complete`);
+					return settlement;
+				})));
 				for (const [index, settlement] of settlements.entries()) flow.units[index]!.implementation = settlement;
 				assertCurrent(flow);
 				if (operationSignal.aborted) operationSignal.throwIfAborted();
-				return await processFlow(flow, toolCallId, operationSignal, ctx, meter);
+				return await processFlow(flow, toolCallId, operationSignal, ctx, meter, emitProgress);
 			} catch (error) {
 				if (!setupComplete) {
 					for (const unit of [...flow.units].reverse()) {
@@ -892,16 +915,16 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		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,
-		renderShell: "self",
 		renderCall(_args, theme, _context) {
-			return renderToolLines([theme.fg("toolTitle", "delegate_flow_continue · working: repair continuation")], theme);
+			return renderToolLines([theme.fg("toolTitle", "delegate_flow_continue · repair continuation")], theme);
 		},
-		renderResult(result, _options, theme, _context) {
+		renderResult(result, { isPartial }, theme, _context) {
+			if (isPartial) return renderToolLines(isFlowProgress(result.details) ? [theme.fg("muted", result.details.line)] : [], theme);
 			const text = result.content.find((part) => part.type === "text")?.text ?? "(no output)";
 			return renderToolLines(flowResultLines(text), theme);
 		},
 		prepareArguments: parseDelegateFlowContinue,
-		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
 			const { guidance, modelClass } = parseDelegateFlowContinue(params);
 			const flow = active;
 			if (!flow) throw new Error("delegate_flow_continue requires an active blocked Flow.");
@@ -916,7 +939,12 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			if (modelClass !== undefined) unit.modelClass = modelClass;
 			const operationSignal = bindSignal(flow, signal);
 			const meter: UsageMeter = {};
+			const emitProgress = (line: string) => {
+				const progress: FlowProgress = { line };
+				onUpdate?.({ content: [{ type: "text", text: progress.line }], details: progress });
+			};
 			try {
+				emitProgress(`repair · unit ${flow.index + 1}/${flow.units.length}`);
 				unit.implementation = await runChild(
 					flow,
 					flow.implementer,
@@ -931,7 +959,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 				);
 				assertCurrent(flow);
 				if (operationSignal.aborted) operationSignal.throwIfAborted();
-				return await processFlow(flow, toolCallId, operationSignal, ctx, meter);
+				return await processFlow(flow, toolCallId, operationSignal, ctx, meter, emitProgress);
 			} catch (error) {
 				return terminal(flow, "infrastructure", errorText(error), meter);
 			}

package/extensions/subagent.ts

@@ -6,6 +6,7 @@ import {
 	availableTaskModels,
 	type ThinkingLevel,
 	modelReference,
+	registerModelTask,
 	resolveAvailableModel,
 	resolveConfiguredTaskRoute,
 	type ResolvedTaskRoute,
@@ -15,6 +16,7 @@ import {
 	capEphemeralSubagentOutput as capOutput,
 	createChildWorktree,
 	createEphemeralSubagentExecutor,
+	DELEGATE_TASK,
 	createRoleLaunch,
 	EphemeralSubagentError,
 	finalizeChildWorktree,
@@ -54,10 +56,10 @@ import {
 	type WorkflowEntry,
 } from "./workflow.ts";
 
-const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
-const MAX_WIDGET_ROWS = 8;
+const MAX_WIDGET_ITEMS = 8;
+const MAX_WIDGET_LINES = 6;
 export const MAX_WIDGET_ACTIVE_TOOLS = 8;
 const DEFAULT_TIMEOUT_POLICY = {
 	idleMs: DEFAULT_TIMEOUT_CONFIG.idleMinutes * 60_000,
@@ -178,9 +180,30 @@ function isWorkflowTransportDetails(value: unknown): value is WorkflowTransportD
 }
 
 function workflowCallLabel(args: { tasks?: unknown; chain?: unknown }): string {
-	if (Array.isArray(args.chain)) return `delegate_task · working: chain · ${args.chain.length} task${args.chain.length === 1 ? "" : "s"}`;
-	if (Array.isArray(args.tasks)) return `delegate_task · working: parallel · ${args.tasks.length} task${args.tasks.length === 1 ? "" : "s"}`;
-	return "delegate_task · working: single · 1 task";
+	if (Array.isArray(args.chain)) return `delegate_task · chain · ${args.chain.length} task${args.chain.length === 1 ? "" : "s"}`;
+	if (Array.isArray(args.tasks)) return `delegate_task · parallel · ${args.tasks.length} task${args.tasks.length === 1 ? "" : "s"}`;
+	return "delegate_task · single · 1 task";
+}
+
+function workflowProgressLine(details: WorkflowTransportDetails): string {
+	let running = 0;
+	let pending = 0;
+	let complete = 0;
+	let failed = 0;
+	let skipped = 0;
+	for (const { status } of details.entries) {
+		switch (status) {
+			case "running": running += 1; break;
+			case "pending": pending += 1; break;
+			case "succeeded": complete += 1; break;
+			case "failed":
+			case "rejected": failed += 1; break;
+			case "skipped": skipped += 1; break;
+		}
+	}
+	return [[running, "running"], [pending, "pending"], [complete, "complete"], [failed, "failed"], [skipped, "skipped"]]
+		.flatMap(([count, label]) => count ? [`${count} ${label}`] : [])
+		.join(" · ");
 }
 
 function workflowResultLines(details: WorkflowTransportDetails, theme: Theme): string[] {
@@ -215,18 +238,23 @@ function renderWidgetRows(
 	spinnerIndex: number,
 	theme: Theme,
 ): string[] {
-	const visible = items.slice(0, MAX_WIDGET_ROWS);
+	const ordered = [...items.filter(({ status }) => status === "working"), ...items.filter(({ status }) => status !== "working")];
+	const visible = ordered.slice(0, ordered.length > MAX_WIDGET_LINES ? MAX_WIDGET_LINES - 1 : MAX_WIDGET_LINES);
 	if (!visible.length) return [];
-	const indent = " ".repeat(Math.min(2, Math.max(0, width - 1)));
-	const contentWidth = Math.max(0, width - indent.length);
-	const lines = visible.flatMap((item) => [
-		truncateToWidth(
-			`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} · ${statusLabel(item.status)} · ${theme.fg("text", item.task)}`,
-			width,
-		),
-		`${indent}${truncateToWidth(`${theme.fg("text", activityLabel(item, now))} · ${theme.fg("muted", activityMetrics(item, now))}`, contentWidth)}`,
-	]);
-	if (items.length > visible.length) lines.push(truncateToWidth(theme.fg("muted", `… ${items.length - visible.length} more`), width));
+	const hidden = ordered.slice(visible.length);
+	const lines = visible.map((item) => truncateToWidth(
+		`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} · ${statusLabel(item.status)} · ${theme.fg("text", item.task)} · ${theme.fg("text", activityLabel(item, now))} · ${theme.fg("muted", activityMetrics(item, now))}`,
+		width,
+	));
+	if (hidden.length) {
+		const counts: Record<WidgetStatus, number> = { working: 0, success: 0, failure: 0, aborted: 0 };
+		for (const { status } of hidden) counts[status] += 1;
+		lines.push(truncateToWidth(theme.fg("muted", [
+			`… ${hidden.length} more`,
+			...(["working", "success", "failure", "aborted"] as const).flatMap((status) =>
+				counts[status] ? [`${counts[status]} ${statusLabel(status)}`] : []),
+		].join(" · ")), width));
+	}
 	return lines;
 }
 
@@ -277,6 +305,7 @@ export default function subagentExtension(
 	pi: ExtensionAPI,
 	overrideTimeoutPolicy?: TimeoutPolicy,
 ): void {
+	registerModelTask(pi, DELEGATE_TASK);
 	const widgetItems = new Map<string, WidgetItem>();
 	// Each child is a full Pi process issuing its own model calls; cap parallel
 	// spend. Precedence: PI_SUBAGENT_MAX_SUBAGENTS env > config/pi-subagent/pi-subagent.json
@@ -357,11 +386,11 @@ export default function subagentExtension(
 	) => {
 		if (!ctx.hasUI) return;
 		ensureWidget(ctx);
-		if (!widgetItems.has(id) && widgetItems.size >= MAX_WIDGET_ROWS) {
+		if (!widgetItems.has(id) && widgetItems.size >= MAX_WIDGET_ITEMS) {
 			for (const [oldestId, item] of widgetItems) {
 				if (item.status === "working") continue;
 				widgetItems.delete(oldestId);
-				if (widgetItems.size < MAX_WIDGET_ROWS) break;
+				if (widgetItems.size < MAX_WIDGET_ITEMS) break;
 			}
 		}
 		widgetItems.set(id, {
@@ -557,7 +586,7 @@ export default function subagentExtension(
 			return createRoleLaunch(pi, launchCtx, {
 				role,
 				route: modelClass === undefined
-					? resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK)
+					? resolveConfiguredTaskRoute(launchCtx, DELEGATE_TASK)
 					: resolveTaskRoute(launchCtx, modelClass),
 			});
 		},
@@ -580,13 +609,14 @@ export default function subagentExtension(
 			"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.",
 		],
 		parameters: WorkflowSchema,
-		renderShell: "self",
 		renderCall(args, theme, _context) {
 			return renderToolLines([theme.fg("toolTitle", workflowCallLabel(args))], theme);
 		},
 		renderResult(result, { isPartial }, theme, _context) {
-			if (isPartial) return renderToolLines([], theme);
 			const details = result.details;
+			if (isPartial) return renderToolLines(isWorkflowTransportDetails(details)
+				? [theme.fg("muted", workflowProgressLine(details))]
+				: [], theme);
 			if (isWorkflowTransportDetails(details)) return renderToolLines(workflowResultLines(details, theme), theme);
 			if (typeof details === "object" && details !== null && (details as { background?: unknown }).background === true) {
 				return renderToolLines([theme.fg("muted", "Background workflow accepted.")], theme);
@@ -633,7 +663,7 @@ export default function subagentExtension(
 				route: delegation.model !== undefined
 					? resolveDesignatedRoute(launchCtx(), delegation.model, delegation.thinking)
 					: delegation.modelClass === undefined
-						? resolveConfiguredTaskRoute(launchCtx(), SUBAGENT_TASK, undefined, delegation.thinking)
+						? resolveConfiguredTaskRoute(launchCtx(), DELEGATE_TASK, undefined, delegation.thinking)
 						: resolveTaskRoute(launchCtx(), delegation.modelClass, undefined, delegation.thinking),
 			});
 			const notifyMissingSkills = (role: Role, launch: ReturnType<typeof resolveLaunch>) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "6.1.0",
+  "version": "7.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": "^2.0.0"
+    "@henryqw/pi-task-models": "^3.0.0"
   }
 }

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

@@ -9,6 +9,8 @@ You are Main, the planner/orchestrator: slice work and call `delegate_flow`. Do
 
 ## Slice
 
+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.
 
 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.