@henryqw/pi-subagent 9.0.0 → 10.1.0

package/CONTEXT.md

@@ -23,13 +23,13 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns`, positive safe integer) or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. On continuing `turn_end`, the existing child Role tool extension steers the fixed convergence warning once at 80% of completed turns and once at 80% of maximum runtime, combining thresholds first due together and never starting a warning timer or extra turn. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`maxTurns` default 50; `timeout.idleMinutes`/`maxMinutes` defaults 10/30).
-- Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout.
+- One Delegated Task creates one ephemeral child process and no saved session. Execution ends at the first hard budget: attempted turn 51 by default (`maxTurns`, positive safe integer) or `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). A terminal turn 50 succeeds; attempted continuation rejects with `turn_limit`, accumulated usage, and bounded output. On continuing `turn_end`, the existing child Role tool extension steers the fixed convergence warning once at 80% of completed turns and once at 80% of maximum runtime, combining thresholds first due together and never starting a warning timer or extra turn. After direct Pi exits, inherited stdout/stderr drain until EOF unless an escaped descendant holds them past short inactivity or a one-second hard deadline. Configurable in `~/.pi/agent/config/pi-subagent/config.json` (`maxTurns` default 50; `timeout.idleMinutes`/`maxMinutes` defaults 10/30).
+- Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/config.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout.
 - Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.
 - Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`); library callers select a Role plus their own Model Task declaration.
-- 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`.
+- The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. A missing local JSON config uses defaults quietly. Missing shared task-model config warns once per session because delegation needs a route. 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 (`config/pi-subagent/config.json`) live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models/config.json`. Package-shipped built-in Roles (`implementer`, `reviewer`, `scout`) resolve from the package's own `examples/roles/` Markdown through the same parser; same-named user files override built-ins for `delegate_task`, while same-named `implementer` and `reviewer` files override Flow defaults. The `synthesizer` Markdown remains the only optional inert sample.
 - `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.

package/README.md

@@ -22,7 +22,9 @@ pi install npm:@henryqw/pi-subagent
 | `@henryqw/pi-multi-codex` | Required. Children can use Main's active Codex slot. |
 | `@henryqw/pi-task-models` | Required. Shared `fast` / `balanced` / `frontier` / `fav` routes. |
 
-Model routing is not configured here. Children resolve routes through shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
+Model routing is not configured here. Children resolve routes through shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models/config.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
+
+The local config is optional and uses defaults quietly when missing. If shared task-model config is missing, pi-subagent warns once at session start because delegation needs a route.
 
 ## Use
 
@@ -32,7 +34,7 @@ Model routing is not configured here. Children resolve routes through shared `@h
 | `delegate_flow` | tool | Package-owned parallel implementation and declared-order Git integration for 1–8 independent units. |
 | `delegate_flow_continue` | tool | Repair the blocked Flow unit once in its existing worktree. |
 
-All three delegation tool blocks use Pi's default boxed shell and background. Their compact custom content is an immutable call label, foreground aggregate partial-result status, and bounded final summaries. There is no expanded view.
+All three delegation tools use Pi's built-in renderer. Its tool-execution block shows live updates and Pi's configured expansion hint; expanding shows the call and result content.
 
 ### `delegate_task`
 
@@ -40,15 +42,17 @@ Select exactly one shape:
 
 ```text
 // Single
-{ role, task, model?, modelClass?, thinking?, background? }
+{ role, name, task, model?, modelClass?, thinking?, background? }
 
 // Parallel: 1–8 independent delegations
-{ tasks: [{ role, task, model?, modelClass?, thinking? }], background? }
+{ tasks: [{ role, name, task, model?, modelClass?, thinking? }], background? }
 
 // Chain: 1–8 dependent delegations
-{ chain: [{ role, task, model?, modelClass?, thinking? }], background? }
+{ chain: [{ role, name, task, model?, modelClass?, thinking? }], background? }
 ```
 
+Main supplies every delegation's required `name`: a short description of about five words and fewer than 30 characters. Names must not contain C0/C1 control characters, including newlines and terminal escape characters.
+
 #### Model precedence
 
 1. An explicit `model` is `provider/modelId` and overrides `modelClass`.
@@ -60,6 +64,8 @@ Select exactly one shape:
 
 This is Main policy only. The runtime records no provenance and does not enforce it. `background` applies to the whole selected mode and is never a per-delegation field.
 
+The transient status widget renders one line per child with: status glyph, bracketed uppercase role initial (`[I]` for `implementer`, `[R]` for `reviewer`, and likewise for custom Roles), Main-supplied short name, activity (thinking… or active tool with elapsed time and path basename), and metrics (completed turns, started tools, compact `model·thinking` pair, 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. It is separate from Pi's built-in tool-execution block.
+
 #### Modes, limits, and isolation
 
 - Parallel mode starts entries concurrently, waits for every entry, and reports them in input order.
@@ -77,10 +83,10 @@ See [Orchestration, isolation, and the public API](./docs/orchestration.md) for
 
 Use Flow only for independent, commuting Git changes. Commuting changes can integrate in any order.
 
-Flow accepts 1–8 uniquely identified units. Each unit has a bounded task, optional `modelClass`, direct command/argument validation gate, and optional non-empty `review` judgment criterion:
+Flow accepts 1–8 uniquely identified units. Each unit has a required Main-supplied short `name`, bounded task, optional `modelClass`, direct command/argument validation gate, and optional non-empty `review` judgment criterion. Names must not contain C0/C1 control characters, including newlines and terminal escape characters.
 
 ```text
-delegate_flow({ units: [{ id, task, modelClass?, validation: [{ command, args }], review? }] })
+delegate_flow({ units: [{ id, name, task, modelClass?, validation: [{ command, args }], review? }] })
 delegate_flow_continue({ guidance, modelClass? })
 ```
 
@@ -129,7 +135,7 @@ Rebase and infrastructure failures are terminal. A reported fast-forward failure
 
 Otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
 
-`delegate_task` keeps its generic isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review. Same-named user Roles remain supported overrides.
+`delegate_task` keeps its generic isolation behavior. Flow uses the package-shipped Implementer by default and the package-shipped Reviewer only when a unit requests review; the built-in Scout is not part of Flow. Same-named user Roles remain supported overrides.
 
 ### Delegate UI summary
 
@@ -137,13 +143,11 @@ The transient status widget shows status glyph, role, status label, task 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 |
+| Tool-execution block | Pi's built-in renderer: live updates and expandable call/result content |
+| Widget rows | One line per child: glyph, `[role initial]`, short name, 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 |
 
 - Rows are active-first: working items first, then stable insertion order.
 - The hard six-physical-line maximum shows all child rows for six or fewer items.
@@ -157,7 +161,7 @@ pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-sub
 
 One Markdown file belongs to each Role (see [Roles](#roles)). The other is its own optional JSON file below.
 
-`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the child pool and execution limits. All fields are optional. A missing file uses defaults.
+`~/.pi/agent/config/pi-subagent/config.json` controls the child pool and execution limits. All fields are optional. A missing file uses defaults without a warning.
 
 | Field | Required | Possible values | Default |
 | --- | --- | --- | --- |
@@ -196,28 +200,28 @@ An unreadable or invalid Role file fails role loading fast. Duplicate role names
 
 ## Roles
 
-The package ships two working built-in Roles. They are always available without configuration.
+The package ships three working built-in Roles. They are always available without configuration.
 
 - `implementer`: focused edits requesting worktree isolation; commits completed scoped changes locally and never pushes or opens PRs without authorization
 - `reviewer`: read-only correctness review of supplied plans or files, or—only when a Flow unit declares `review`—of Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits
+- `scout`: read-only code and evidence mapping for one bounded task; never changes files
 
-A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default.
+A same-named Markdown file in `~/.pi/agent/config/pi-subagent/` explicitly overrides the built-in default. The built-in `scout` is available to generic `delegate_task`; `delegate_flow` remains limited to its fixed Implementer/Reviewer protocol.
 
-The repository also includes optional inert samples:
+The repository also includes one optional inert sample:
 
-- [`scout`](./examples/roles/scout.md): read-only discovery
 - [`synthesizer`](./examples/roles/synthesizer.md): reconcile supplied reports
 
-Copy them manually from your installed `@henryqw/pi-subagent` package if you want a starting point. npm installs ship the `examples/roles/` directory.
+Copy it manually from your installed `@henryqw/pi-subagent` package if you want a starting point. npm installs ship the `examples/roles/` directory.
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
-cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
+cp <package-install-dir>/examples/roles/synthesizer.md ~/.pi/agent/config/pi-subagent/
 ```
 
 Locate the install directory with `npm root` inside your project, or through Pi's package installation path.
 
-The package never installs or writes Role configuration. Sample names are not built-ins. After copying, edit or replace them as your own Roles.
+The package never installs or writes Role configuration. After copying, edit or replace `synthesizer.md` as your own Role.
 
 ## Skill
 

package/dist/index.d.ts

@@ -45,14 +45,13 @@ export interface ResolvedRoleSkills {
     paths: string[];
     missing: string[];
 }
-declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer"];
+declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer", "scout"];
 export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
 export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
 /**
- * Validated built-in implementer/reviewer Roles plus valid user roles from
- * `config/pi-subagent`. A user role with a built-in name overrides the default;
- * duplicate names among user files are an error. Missing user directory returns
- * the built-ins.
+ * Validated package-shipped Roles plus valid user roles from `config/pi-subagent`.
+ * A user role with a built-in name overrides the default; duplicate names among
+ * user files are an error. Missing user directory returns the built-ins.
  */
 export declare function loadRoles(agentDir?: string): Role[];
 export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string, thinking?: ThinkingLevel): ResolvedTaskRoute;

package/dist/index.js

@@ -2,7 +2,8 @@ import { readFileSync, readdirSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import { modelReference, orderedProfileRoutes, readTaskModelsConfig, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
+import { extensionConfigDir } from "@henryqw/pi-config-store";
+import { loadTaskModelsConfig, modelReference, orderedProfileRoutes, resolveConfiguredTaskRoute, resolveTaskModelRoute, } from "@henryqw/pi-task-models";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, } from "./ephemeral.js";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, } from "./worktree.js";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, } from "./review-evidence.js";
@@ -45,9 +46,8 @@ function validateExtension(extension, source) {
 function extensionList(value, source) {
     return stringList(value, "extensions", source).map((extension) => validateExtension(extension, source));
 }
-// Built-in Roles required by the bundled pi-subagent-delegated-development Skill;
-// resolved from the package-shipped Markdown relative to this module.
-const BUILTIN_ROLE_NAMES = ["implementer", "reviewer"];
+// Built-in Roles resolved from the package-shipped Markdown relative to this module.
+const BUILTIN_ROLE_NAMES = ["implementer", "reviewer", "scout"];
 /** Single-file Role parser shared by built-in and user roles. */
 function parseRoleFile(file, raw) {
     let parsed;
@@ -88,14 +88,13 @@ function builtinRoles() {
     return BUILTIN_ROLE_NAMES.map(loadBuiltinRole);
 }
 /**
- * Validated built-in implementer/reviewer Roles plus valid user roles from
- * `config/pi-subagent`. A user role with a built-in name overrides the default;
- * duplicate names among user files are an error. Missing user directory returns
- * the built-ins.
+ * Validated package-shipped Roles plus valid user roles from `config/pi-subagent`.
+ * A user role with a built-in name overrides the default; duplicate names among
+ * user files are an error. Missing user directory returns the built-ins.
  */
 export function loadRoles(agentDir = getAgentDir()) {
     const byName = new Map(builtinRoles().map((role) => [role.name, role]));
-    const dir = join(agentDir, "config", "pi-subagent");
+    const dir = extensionConfigDir("pi-subagent", agentDir);
     let entries;
     try {
         entries = readdirSync(dir, { withFileTypes: true });
@@ -121,7 +120,7 @@ export function loadRoles(agentDir = getAgentDir()) {
 export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir(), thinking) {
     let config;
     try {
-        config = readTaskModelsConfig(agentDir);
+        config = loadTaskModelsConfig(agentDir).value;
     }
     catch {
         throw new Error("Couldn't read task model config. Run /task-models.");

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

@@ -12,7 +12,7 @@ Resource Policy is split at launch preparation:
 - Caller may add explicit tools, extensions, and environment through `createRoleLaunch`.
 - The executor receives the resulting Pi Launch and does not discover resources.
 
-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.
+Built-in `implementer`, `reviewer`, and `scout` 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.
 

package/docs/orchestration.md

@@ -23,6 +23,7 @@ A call selects exactly one of these shapes. Unknown properties and nested modes
 ```json
 {
   "role": "user-configured-role",
+  "name": "Inspect authentication flow",
   "task": "One bounded task packet",
   "modelClass": "balanced",
   "thinking": "high",
@@ -37,8 +38,8 @@ Single mode puts one delegation's fields at the top level.
 ```json
 {
   "tasks": [
-    { "role": "user-role-a", "task": "Inspect subsystem A", "modelClass": "fast" },
-    { "role": "user-role-b", "task": "Inspect subsystem B", "model": "provider/model-id" }
+    { "role": "user-role-a", "name": "Inspect subsystem A", "task": "Inspect subsystem A", "modelClass": "fast" },
+    { "role": "user-role-b", "name": "Inspect subsystem B", "task": "Inspect subsystem B", "model": "provider/model-id" }
   ],
   "background": false
 }
@@ -51,9 +52,9 @@ Single mode puts one delegation's fields at the top level.
 ```json
 {
   "chain": [
-    { "role": "user-role-a", "task": "Collect evidence" },
-    { "role": "user-role-b", "task": "Review this evidence:\n{previous}" },
-    { "role": "user-role-c", "task": "Summarize this review:\n{previous}" }
+    { "role": "user-role-a", "name": "Collect evidence", "task": "Collect evidence" },
+    { "role": "user-role-b", "name": "Review collected evidence", "task": "Review this evidence:\n{previous}" },
+    { "role": "user-role-c", "name": "Summarize evidence review", "task": "Summarize this review:\n{previous}" }
   ],
   "background": false
 }
@@ -65,13 +66,14 @@ Single mode puts one delegation's fields at the top level.
 
 | Field | Required | Contract |
 | --- | --- | --- |
-| `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. |
+| `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`, `scout`); a same-named user file overrides the built-in. |
+| `name` | yes | Main-supplied short task name: about five words and fewer than 30 characters; C0/C1 control characters are rejected. |
 | `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 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.
+Those six 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,7 +85,7 @@ 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`, 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.
+`delegate_flow({ units })` accepts 1–8 units with unique non-empty `id`, a required Main-supplied short `name` (about five words and fewer than 30 characters, without C0/C1 control characters), a non-empty `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 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:
 
@@ -106,7 +108,7 @@ If rebase drops all unit commits, `base === tip` is a no-op: Flow validates curr
 
 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 package-shipped Roles as defaults while retaining same-named user Role overrides; the Reviewer is needed only for a requested review criterion.
+`delegate_task` remains generic: its optional worktree isolation, non-Git behavior, and direct plan/file review are unchanged. The built-in `scout` is available only through generic `delegate_task`; Flow uses package-shipped Implementer and conditional Reviewer Roles as defaults while retaining same-named user Role overrides.
 
 ## Per-delegation resources and isolation
 
@@ -389,30 +391,30 @@ The verdict schema, parser, round state, shared workspace, and terminal decision
 
 ## Built-in Roles and samples
 
-The package ships two working built-in Roles, validated by the same parser as user roles and always present even with no `config/pi-subagent` directory:
+The package ships three working built-in Roles, validated by the same parser as user roles and always present even with no `config/pi-subagent` directory:
 
 | 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—when a Flow unit declares `review`—Flow's exact `{base, tip, patchPath}` packet in its Unit Worktree; never edits or commits. |
+| `scout` | Read-only code and evidence mapping for one bounded task; never changes files. |
 
 A same-named Markdown file in `config/pi-subagent/` explicitly overrides the built-in default.
 
-Additional repository samples are inert starting points, not installed configuration:
+The repository includes one optional inert sample, not installed configuration:
 
 | Sample | Intended starting point |
 | --- | --- |
-| [`scout`](../examples/roles/scout.md) | Read-only code/evidence mapping. |
 | [`synthesizer`](../examples/roles/synthesizer.md) | Reconcile supplied reports without broad discovery. |
 
-Copy the package-shipped samples from your installed `@henryqw/pi-subagent` package (npm installs include `examples/roles/`) if you want them:
+Copy the package-shipped sample from your installed `@henryqw/pi-subagent` package (npm installs include `examples/roles/`) if you want it:
 
 ```bash
 mkdir -p ~/.pi/agent/config/pi-subagent
-cp <package-install-dir>/examples/roles/scout.md ~/.pi/agent/config/pi-subagent/
+cp <package-install-dir>/examples/roles/synthesizer.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 package never creates, copies, updates, or removes files in `~/.pi/agent/config/pi-subagent/`. Once copied, the file and its name are entirely user-owned.
 
 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.
 

package/examples/roles/implementer.md

@@ -14,12 +14,12 @@ skills: []
 isolation: worktree
 ---
 
-Implement one bounded task.
+Implement the bounded outcome, not a preassigned file list. Work in the assigned cwd. Read applicable repository instructions and domain context first; inspect the relevant flow, callers, and tests before editing. Preserve unrelated work. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies. Do not add speculative work. Stop when the outcome is complete or blocked.
 
-Read applicable repository instructions and domain context first. Inspect the existing flow and its callers before editing. Work only in the assigned cwd and explicitly assigned files; preserve unrelated changes. Fix the root cause with the smallest complete diff, reusing existing patterns and dependencies.
+For ordinary delegation, run focused validation needed to establish correctness. For Flow, the declared validation gate is authoritative: run only narrow development checks while implementing and do not duplicate that final gate.
 
-For ordinary delegation, run the focused validation needed to establish that the change is correct. When a Flow packet declares an authoritative validation gate, treat that gate as the final validation: run only narrow development checks needed while implementing, and do not duplicate the declared gate. Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs; deterministic developer tools remain allowed.
+Do not access credentials, use the network, generate artifacts, or broaden scope unless the task explicitly requires it. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-Commit completed scoped changes locally unless the task forbids it. Never create or manage another worktree. Never push or open pull requests without explicit authorization.
+Commit completed scoped changes locally unless the task says otherwise. Do not create or manage another worktree. Never push or open a pull request without explicit authorization. For Flow, leave the assigned worktree and branch intact.
 
-For ordinary delegation, report the completed change, validation, and remaining risks. For Flow, return the retained assigned cwd, branch, base commit, tip commit, changed files from the base-to-tip committed diff, clean `git status --porcelain=v1 --untracked-files=all` result, and validation results. Do not remove the retained worktree or task branch; Main cleans them only after successful integration and validation.
+Report briefly: outcome, commit, checks run, and remaining risks. Do not repeat Flow's Git-derived evidence.

package/examples/roles/reviewer.md

@@ -10,15 +10,11 @@ extensions: []
 skills: []
 ---
 
-Perform a read-only correctness review of one bounded change.
+Review read-only in exactly two modes:
 
-Support exactly two review modes:
+1. Ordinary delegation: use supplied requirements and named files/evidence only. Do not prepare Git, require a commit/Review Packet, or broaden discovery. If evidence is insufficient, say so and stop.
+2. Flow exact review: only with an explicit judgment criterion, use the same assigned Unit Worktree and exact Review Packet `{base, tip, patchPath}`. Treat the exact patch at `patchPath` as authoritative; read only referenced files/context. Declared validation is authoritative for objective verification. Judge only the explicit criterion; never infer a diff from another branch/worktree.
 
-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, 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.
+Report only actionable correctness risks introduced by the change—not style preferences, speculative hypotheticals, or unrelated pre-existing issues. Use only `read`, `grep`, `find`, and `ls`; run no commands/tests and never edit, write, commit, push, or manage Git/worktrees. Never invoke external LLM APIs, SDKs, agent harnesses, or model CLIs.
 
-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.
-
-Emit exactly `PASS` when there are zero findings. Any finding must block approval: return findings first, ordered by severity, with file and line evidence, impact, and the smallest valid fix. Do not emit `PASS` alongside findings.
+Output exactly `PASS` when there are no findings. Otherwise output findings only, ordered by severity, with file:line evidence, impact, and smallest valid fix; any finding blocks approval. Never combine `PASS` with findings. Stop when supplied evidence is covered; in Flow, stop after its criterion.

package/examples/roles/scout.md

@@ -1,19 +1,23 @@
 ---
 name: scout
 description: Maps relevant code and evidence for one bounded task without changing files
-tools: [read, grep, find, ls]
+tools:
+  - read
+  - grep
+  - find
+  - ls
 extensions: []
 skills: []
 ---
 
-Perform read-only discovery for one bounded task.
+Answer only the bounded discovery questions.
 
-Stay within the paths and questions named in the task. Read applicable repository instructions and domain context before tracing the concrete execution or data flow far enough to identify affected files, callers, tests, and constraints. Do not design or implement changes.
+Read applicable repository instructions and domain context first. Trace the relevant execution/data flow, callers, tests, and constraints only far enough to answer. Separate observed facts, supported inferences, and unknowns. Stop when answered; if blocked, state what is missing.
 
-Do not edit files or run shell commands. Return:
+Do not design, recommend, implement, edit, or run shell commands.
 
-- a concise map of relevant files and symbols and how they connect;
-- evidence with file paths and line numbers;
-- uncertainties or missing context.
+Return concisely:
 
-Stop when the task's questions are answered.
+- a map of relevant files and symbols and how they connect;
+- path:line evidence;
+- uncertainties or missing context.

package/examples/roles/synthesizer.md

@@ -1,7 +1,8 @@
 ---
 name: synthesizer
 description: Reconciles bounded worker reports into one evidence-based result
-tools: [read]
+tools:
+  - read
 extensions: []
 skills: []
 ---

package/extensions/config.ts

@@ -1,6 +1,5 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { createConfigStore, extensionConfigPath } from "@henryqw/pi-config-store";
 
 export interface SubagentTimeoutConfig {
 	/** Minutes a child may stay idle before it is asked to stop. */
@@ -16,11 +15,15 @@ export interface SubagentConfig {
 }
 
 export interface LoadedSubagentConfig {
+	source: "file" | "missing";
 	config: SubagentConfig;
 	/** Human-readable problems when the file exists but is partly unusable; the file is never rewritten. */
 	error?: string;
 }
 
+type ParsedSubagentConfig = Omit<LoadedSubagentConfig, "source">;
+
+const EXTENSION_ID = "pi-subagent";
 const positive = (value: unknown): value is number =>
 	typeof value === "number" && Number.isFinite(value) && value > 0;
 
@@ -30,36 +33,11 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export const DEFAULT_TIMEOUT_CONFIG = { idleMinutes: 10, maxMinutes: 30 } as const;
 const TIMEOUT_FIELDS = ["idleMinutes", "maxMinutes"] as const;
 
-/**
- * All pi-subagent config lives in its existing extension-named directory;
- * agentDir is injectable so tests can point at a temp directory.
- */
+/** Return the canonical default JSON path for pi-subagent's config home. */
 export const configPath = (agentDir = getAgentDir()): string =>
-	join(agentDir, "config", "pi-subagent", "pi-subagent.json");
+	extensionConfigPath(EXTENSION_ID, agentDir);
 
-/**
- * Read the optional user config at `<agentDir>/config/pi-subagent/pi-subagent.json`.
- * Treated as untrusted user data: malformed files are preserved untouched and
- * reported instead of crashing the session; callers fall back to defaults.
- */
-export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConfig {
-	const path = configPath(agentDir);
-	let raw: string;
-	try {
-		raw = readFileSync(path, "utf8");
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { config: {} };
-		throw error;
-	}
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(raw);
-	} catch (error) {
-		return {
-			config: {},
-			error: `${path} is not valid JSON (${error instanceof Error ? error.message : String(error)}); using defaults.`,
-		};
-	}
+function parseSubagentConfig(parsed: unknown, path: string): ParsedSubagentConfig {
 	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
 		return { config: {}, error: `${path} must contain a JSON object; using defaults.` };
 	}
@@ -122,3 +100,42 @@ export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConf
 
 	return { config, error: problems.length ? `${path}: ${problems.join("; ")}; using defaults.` : undefined };
 }
+
+/**
+ * Read the optional user config at `<agentDir>/config/pi-subagent/config.json`.
+ * Treated as untrusted user data: malformed files are preserved untouched and
+ * reported instead of crashing the session; callers fall back to defaults.
+ */
+export function readSubagentConfig(agentDir = getAgentDir()): LoadedSubagentConfig {
+	const path = configPath(agentDir);
+	let validationError: string | undefined;
+	const store = createConfigStore<SubagentConfig>({
+		extensionId: EXTENSION_ID,
+		agentDir,
+		defaults: () => ({}),
+		parse(value) {
+			const parsed = parseSubagentConfig(value, path);
+			validationError = parsed.error;
+			return parsed.config;
+		},
+	});
+	try {
+		const loaded = store.loadSync();
+		return {
+			source: loaded.source,
+			config: loaded.value,
+			...(validationError === undefined ? {} : { error: validationError }),
+		};
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+		if (code !== undefined && code !== "ERR_ENCODING_INVALID_ENCODED_DATA") throw error;
+		const reason = error instanceof Error ? error.message : String(error);
+		return {
+			source: "file",
+			config: {},
+			error: error instanceof SyntaxError
+				? `${path} is not valid JSON (${reason}); using defaults.`
+				: `${path} couldn't be read (${reason}); using defaults.`,
+		};
+	}
+}

package/extensions/delegate-flow.ts

@@ -19,8 +19,8 @@ import {
 } from "@henryqw/pi-subagent";
 import { Type, type Static } from "typebox";
 import { Check } from "typebox/value";
+import { TASK_NAME_CONTRACT, TaskNameSchema, normalizeTaskName } from "./task-name.ts";
 import { runDelegation } from "./delegation.ts";
-import { renderToolLines } from "./tool-render.ts";
 
 const MAX_UNITS = 8;
 const GIT_TIMEOUT_MS = 30_000;
@@ -35,6 +35,7 @@ const ModelClassSchema = StringEnum(PROFILE_NAMES, { description: "Task model pr
 
 const UnitSchema = Type.Object({
 	id: Type.String({ minLength: 1 }),
+	name: TaskNameSchema,
 	task: Type.String({ minLength: 1 }),
 	validation: Type.Array(ValidationSchema, { minItems: 1 }),
 	modelClass: Type.Optional(ModelClassSchema),
@@ -108,7 +109,6 @@ type FlowState = {
 };
 
 type UsageMeter = { usage?: Usage };
-type FlowProgress = { line: string };
 
 type CommandResult = {
 	stdout: string;
@@ -128,7 +128,7 @@ export interface DelegateFlowRuntime {
 		role: string,
 		model: string,
 		thinkingLevel: string | undefined,
-		task: string,
+		name: string,
 		ctx: ExtensionContext,
 	) => void;
 	updateWidgetTokens: (id: string, tokens: number) => void;
@@ -157,6 +157,7 @@ export function parseDelegateFlow(value: unknown): FlowRequest {
 			ids.add(id);
 			return {
 				id,
+				name: normalizeTaskName(unit.name, `units[${unitIndex}].name`),
 				task: text(unit.task, `units[${unitIndex}].task`),
 				validation: unit.validation.map((validation, validationIndex) => ({
 					command: text(validation.command, `units[${unitIndex}].validation[${validationIndex}].command`),
@@ -181,40 +182,6 @@ 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 · 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[] {
-	const lines = text.split(/\r?\n/).filter((line) => line.trim());
-	const diagnosticHeader = lines.findIndex((line) => line.trim() === "Diagnostic:");
-	const diagnostic = diagnosticHeader === -1 ? undefined : lines[diagnosticHeader + 1];
-	const recoveryHeader = lines.findIndex((line) => line.trim() === "Retained Flow state:" || line.trim() === "Attempted allocations preserved without cleanup:");
-	const recovery = recoveryHeader === -1 || !lines[recoveryHeader + 1]?.trim().startsWith("- unit=")
-		? undefined
-		: lines[recoveryHeader + 1];
-	if (diagnostic === undefined) {
-		if (recovery === undefined) return lines;
-		const recoveryIndex = lines.indexOf(recovery);
-		return [lines[0]!, recovery, ...lines.filter((_, index) => index !== 0 && index !== recoveryIndex)];
-	}
-	const leading = lines.slice(0, Math.min(1, diagnosticHeader));
-	if (recovery !== undefined) return [...leading, `Diagnostic: ${diagnostic}`, recovery];
-	// Promote the first diagnostic ahead of the result cap.
-	return [
-		...leading,
-		`Diagnostic: ${diagnostic}`,
-		...lines.slice(leading.length, diagnosticHeader),
-		...lines.slice(diagnosticHeader + 2),
-	];
-}
-
 function errorText(error: unknown): string {
 	return capOutput(error instanceof Error ? error.message : String(error));
 }
@@ -378,7 +345,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		role: Role,
 		modelClass: FlowModelClass,
 		task: string,
-		widgetTask: string,
+		widgetName: string,
 		cwd: string,
 		widgetId: string,
 		signal: AbortSignal | undefined,
@@ -398,7 +365,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					if (launch.missingSkills.length) {
 						ctx.ui.notify(`Subagent role ${role.name} skipped unavailable Pi skills: ${launch.missingSkills.join(", ")}.`, "warning");
 					}
-					runtime.startWidget(widgetId, role.name, launch.model.id, launch.thinkingLevel, widgetTask, ctx);
+					runtime.startWidget(widgetId, role.name, launch.model.id, launch.thinkingLevel, widgetName, ctx);
 					started = true;
 					return { launch, task, cwd };
 				},
@@ -719,7 +686,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 						reviewer,
 						unit.modelClass,
 						reviewerTask(unit.request, reviewCriterion, { base: evidence.base, tip: evidence.tip, patchPath: evidence.patchPath }),
-						unit.request.task,
+						unit.request.name,
 						unit.worktree.cwd,
 						`${toolCallId}:flow:${flow.index}:review`,
 						signal,
@@ -796,18 +763,10 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 		promptSnippet: "Run a deterministic parallel-implementation, serial-verification Flow",
 		promptGuidelines: [
 			"Use delegate_flow only for cohesive units expected to commute: split independent outcomes into units, sequence dependent work outside delegate_flow, and never divide one invariant across multiple units. Combine work that overlaps files, APIs, schemas, generated output, package metadata, lockfiles, or invariants.",
-			"Each delegate_flow unit must own one concrete outcome with one focused validation story: include explicit bounded requirements and its authoritative direct command/argument validation gate. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Add review only for an explicit judgment that validation cannot establish.",
+			`${TASK_NAME_CONTRACT.promptGuidance} Each delegate_flow unit must own one concrete outcome with one focused validation story: include explicit bounded requirements and its authoritative direct command/argument validation gate. If the affected flow or scope is not yet known, perform bounded read-only discovery first. Add review only for an explicit judgment that validation cannot establish.`,
 			"If a Flow blocks, inspect its classification and call delegate_flow_continue once with explicit repair guidance; modelClass may replace that one repair's current class.",
 		],
 		parameters: DelegateFlowSchema,
-		renderCall(args, theme, _context) {
-			return renderToolLines([theme.fg("toolTitle", flowCallLabel(args))], theme);
-		},
-		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) {
 			const request = parseDelegateFlow(params);
@@ -819,8 +778,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			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 });
+				onUpdate?.({ content: [{ type: "text", text: line }], details: { line } });
 			};
 			const flow: FlowState = {
 				phase: "running",
@@ -879,7 +837,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					flow.implementer,
 					unit.modelClass,
 					implementerTask(unit.request),
-					unit.request.task,
+					unit.request.name,
 					unit.worktree.cwd,
 					`${toolCallId}:flow:${index}:implement`,
 					operationSignal,
@@ -915,14 +873,6 @@ 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,
-		renderCall(_args, theme, _context) {
-			return renderToolLines([theme.fg("toolTitle", "delegate_flow_continue · repair continuation")], theme);
-		},
-		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) {
 			const { guidance, modelClass } = parseDelegateFlowContinue(params);
@@ -940,8 +890,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 			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 });
+				onUpdate?.({ content: [{ type: "text", text: line }], details: { line } });
 			};
 			try {
 				emitProgress(`repair · unit ${flow.index + 1}/${flow.units.length}`);
@@ -950,7 +899,7 @@ export function registerDelegateFlow(pi: ExtensionAPI, runtime: DelegateFlowRunt
 					flow.implementer,
 					unit.modelClass,
 					repairTask(unit.request, blocked, guidance),
-					unit.request.task,
+					unit.request.name,
 					unit.worktree.cwd,
 					`${toolCallId}:flow:${flow.index}:repair`,
 					operationSignal,

package/extensions/subagent.ts

@@ -4,6 +4,7 @@ import { type ExtensionAPI, type ExtensionContext, type Theme } from "@earendil-
 import { type Component, type TUI, truncateToWidth } from "@earendil-works/pi-tui";
 import {
 	availableTaskModels,
+	loadTaskModelsConfig,
 	type ThinkingLevel,
 	modelReference,
 	registerModelTask,
@@ -34,7 +35,6 @@ import {
 } from "@henryqw/pi-subagent";
 import { DEFAULT_TIMEOUT_CONFIG, readSubagentConfig, type SubagentTimeoutConfig } from "./config.ts";
 import { registerDelegateFlow } from "./delegate-flow.ts";
-import { renderToolLines } from "./tool-render.ts";
 import { runDelegation } from "./delegation.ts";
 import {
 	formatBackgroundWorkflowResult,
@@ -42,13 +42,10 @@ import {
 	formatWorkflowUpdate,
 	WorkflowAbortedError,
 	WorkflowFailureError,
-	displaySummary,
 	type WorkflowTransportEntry,
-	type WorkflowTransportDetails,
 } from "./result-transport.ts";
 import {
 	identifyWorkflowEntries,
-	MAX_WORKFLOW_ENTRIES,
 	parseWorkflow,
 	runForegroundWorkflow,
 	WorkflowSchema,
@@ -56,6 +53,7 @@ import {
 	type ParsedWorkflow,
 	type WorkflowEntry,
 } from "./workflow.ts";
+import { TASK_NAME_CONTRACT } from "./task-name.ts";
 
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
@@ -88,7 +86,7 @@ type WidgetItem = {
 	role: string;
 	model: string;
 	thinkingLevel: string;
-	task: string;
+	name: string;
 	tokens: number;
 	startedAt: number;
 	status: WidgetStatus;
@@ -100,8 +98,9 @@ type WidgetItem = {
 	activityOrder: number;
 };
 
-function taskSummary(task: string): string {
-	return Array.from(task.replace(/[\u0000-\u001f\u007f-\u009f]/g, " ").trim().split(/\s+/).slice(0, 4).join(" ")).slice(0, 160).join("");
+function roleBadge(role: string): string {
+	const initial = Array.from(role)[0]!.toUpperCase();
+	return `[${Array.from(initial)[0]!}]`;
 }
 
 function formatTokens(tokens: number): string {
@@ -150,88 +149,12 @@ function activityMetrics(item: WidgetItem, now: number): string {
 		...(item.startedToolCount === 0
 			? []
 			: [`${item.startedToolCount} tool${item.startedToolCount === 1 ? "" : "s"}`]),
-		item.model,
-		item.thinkingLevel,
+		`${item.model}·${item.thinkingLevel}`,
 		`${formatTokens(item.tokens)} tok`,
 		formatDuration((item.finishedAt ?? now) - item.startedAt),
 	].join(" · ");
 }
 
-function isWorkflowTransportDetails(value: unknown): value is WorkflowTransportDetails {
-	const isRecord = (candidate: unknown): candidate is Record<string, unknown> => typeof candidate === "object" && candidate !== null && !Array.isArray(candidate);
-	const isOptionalString = (candidate: unknown) => candidate === undefined || typeof candidate === "string";
-	if (!isRecord(value) || !(value.mode === "single" || value.mode === "parallel" || value.mode === "chain") || !Array.isArray(value.entries)) return false;
-	const entries = value.entries;
-	return entries.length >= 1 && entries.length <= MAX_WORKFLOW_ENTRIES
-		&& (value.mode !== "single" || entries.length === 1)
-		&& entries.every((entry) => isRecord(entry)
-			&& typeof entry.id === "string" && typeof entry.index === "number" && Number.isFinite(entry.index) && Number.isInteger(entry.index) && entry.index >= 0
-			&& typeof entry.role === "string" && ["pending", "running", "succeeded", "failed", "rejected", "skipped"].includes(entry.status as string)
-			&& (["running", "succeeded", "failed", "rejected"].includes(entry.status as string)
-				? typeof entry.summary === "string" && entry.summary === displaySummary(entry.summary)
-				: entry.summary === undefined)
-			&& isOptionalString(entry.model) && isOptionalString(entry.thinkingLevel)
-			&& (entry.worktree === undefined || isRecord(entry.worktree)
-				&& typeof entry.worktree.path === "string" && typeof entry.worktree.branch === "string"
-				&& typeof entry.worktree.commits === "number" && Number.isFinite(entry.worktree.commits) && Number.isInteger(entry.worktree.commits) && entry.worktree.commits >= 0
-				&& typeof entry.worktree.dirty === "boolean" && typeof entry.worktree.pruned === "boolean"
-				&& (entry.worktree.inspection_failed === undefined || typeof entry.worktree.inspection_failed === "boolean")
-				&& (entry.worktree.note === undefined || typeof entry.worktree.note === "string")))
-		&& entries.every((entry, index) => index === 0 || (entry as { index: number }).index > (entries[index - 1] as { index: number }).index);
-}
-
-function workflowCallLabel(args: { tasks?: unknown; chain?: unknown }): string {
-	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[] {
-	if (details.entries.some(({ status }) => status === "pending" || status === "running")) return [];
-	const entries = details.entries.filter(({ status }) => status !== "skipped");
-	const withRecovery = (entry: typeof entries[0]) => entry.worktree && !entry.worktree.pruned;
-	const isTerminalFailure = (entry: typeof entries[0]) => entry.status === "failed" || entry.status === "rejected";
-	const sorted = [...entries].sort((a, b) => {
-		const aFailure = isTerminalFailure(a);
-		const bFailure = isTerminalFailure(b);
-		if (aFailure !== bFailure) return aFailure ? -1 : 1;
-		const aRecovery = !aFailure && withRecovery(a);
-		const bRecovery = !bFailure && withRecovery(b);
-		if (aRecovery !== bRecovery) return aRecovery ? -1 : 1;
-		return 0;
-	});
-	return sorted.map((entry) => {
-		const summary = entry.summary || "(no output)";
-		const text = details.mode === "single" ? summary : `${entry.role}: ${summary}`;
-		const style = entry.status === "failed" || entry.status === "rejected" ? "error" : "text";
-		const recovery = withRecovery(entry) ? `Recovery: ${entry.worktree!.path}` : undefined;
-		return recovery === undefined
-			? theme.fg(style, text)
-			: `${theme.fg("warning", recovery)} · ${theme.fg(style, text)}`;
-	});
-}
-
 function renderWidgetRows(
 	items: WidgetItem[],
 	width: number,
@@ -244,7 +167,7 @@ function renderWidgetRows(
 	if (!visible.length) return [];
 	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))}`,
+		`${statusGlyph(item.status, spinnerIndex, theme)} ${theme.fg("accent", item.role)} ${theme.fg("text", item.name)} · ${theme.fg("text", activityLabel(item, now))} · ${theme.fg("muted", activityMetrics(item, now))}`,
 		width,
 	));
 	if (hidden.length) {
@@ -309,11 +232,10 @@ export default function subagentExtension(
 	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
-	// maxSubagents > default 5. Invalid config falls back to the default and is
-	// reported once the UI exists; an invalid env value fails fast.
+	// spend. Precedence: PI_SUBAGENT_MAX_SUBAGENTS env > config/pi-subagent/config.json
+	// maxSubagents > default 5. Invalid present config falls back to the default
+	// and is reported at session start; an invalid env value fails fast.
 	const loadedConfig = readSubagentConfig();
-	const startupWarnings = [loadedConfig.error].filter((message): message is string => message !== undefined);
 	let maxActiveSubagents = loadedConfig.config.maxSubagents ?? 5;
 	const maxSubagentsRaw = process.env.PI_SUBAGENT_MAX_SUBAGENTS;
 	if (maxSubagentsRaw !== undefined) {
@@ -386,7 +308,7 @@ export default function subagentExtension(
 		role: string,
 		model: string,
 		thinkingLevel: string | undefined,
-		task: string,
+		name: string,
 		ctx: ExtensionContext,
 	) => {
 		if (!ctx.hasUI) return;
@@ -399,10 +321,10 @@ export default function subagentExtension(
 			}
 		}
 		widgetItems.set(id, {
-			role,
+			role: roleBadge(role),
 			model,
 			thinkingLevel: thinkingLevel ?? "default",
-			task: taskSummary(task),
+			name,
 			tokens: 0,
 			startedAt: Date.now(),
 			status: "working",
@@ -480,7 +402,14 @@ export default function subagentExtension(
 		invalidateDelegateFlow();
 		latestCtx = ctx;
 		ensureWidget(ctx);
-		for (const warning of startupWarnings.splice(0)) ctx.ui.notify(warning, "warning");
+		if (loadedConfig.error !== undefined) ctx.ui.notify(loadedConfig.error, "warning");
+		try {
+			if (loadTaskModelsConfig().source === "missing") {
+				ctx.ui.notify("Task model config is missing; run /task-models to configure it.", "warning");
+			}
+		} catch {
+			// Route resolution retains the existing malformed shared-config error.
+		}
 	});
 	pi.on("session_shutdown", async (_event, ctx) => {
 		failedToolPatches.clear();
@@ -607,28 +536,13 @@ export default function subagentExtension(
 		description: `Delegate one selected single, parallel, or chain workflow of bounded tasks to isolated Pi Subagents. Roles: ${roleSummary()}.`,
 		promptSnippet: "Delegate one bounded single, parallel, or chain workflow to isolated roles",
 		promptGuidelines: [
-			"Call delegate_task with exactly one mode: role+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output; split independent, commuting outcomes into parallel entries, sequence dependent work in chain entries, and never divide one invariant across multiple entries.",
-			"Every delegate_task entry must own one concrete outcome with one focused validation story: state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; if the affected flow or scope is not yet known, perform bounded read-only discovery first; never pass the parent request unchanged.",
+			"Call delegate_task with exactly one mode: role+name+task for one task, tasks for 1–8 independent parallel tasks, or chain for 1–8 dependent sequential tasks using {previous} for the immediately preceding assistant output; split independent, commuting outcomes into parallel entries, sequence dependent work in chain entries, and never divide one invariant across multiple entries.",
+			`${TASK_NAME_CONTRACT.promptGuidance} Every delegate_task entry must own one concrete outcome with one focused validation story: state its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation; if the affected flow or scope is not yet known, perform bounded read-only discovery first; never pass the parent request unchanged.`,
 			"For each delegate_task entry, populate model and thinking only for an explicit user override; otherwise choose only modelClass: fast normally, or balanced upfront for obviously complex work. This is Main policy, not runtime enforcement.",
 			"Parallel delegate_task entries must own non-overlapping files. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.",
 			"delegate_task background applies to the whole selected workflow and returns before results exist; use it only when the user explicitly asks for non-blocking work.",
 		],
 		parameters: WorkflowSchema,
-		renderCall(args, theme, _context) {
-			return renderToolLines([theme.fg("toolTitle", workflowCallLabel(args))], theme);
-		},
-		renderResult(result, { isPartial }, theme, _context) {
-			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);
-			}
-			const text = result.content.find((part) => part.type === "text")?.text ?? "(no output)";
-			return renderToolLines([theme.fg("muted", text)], theme);
-		},
 		prepareArguments(args) {
 			try {
 				const workflow = parseWorkflow(args);
@@ -749,7 +663,7 @@ export default function subagentExtension(
 								if (role.isolation === "worktree") {
 									worktree = await createChildWorktree(ctx.cwd, entry.id, undefined, workflowSignal);
 								}
-								startWidgetItem(entry.id, role.name, launch.model.id, launch.thinkingLevel, entry.delegation.task, ctx);
+								startWidgetItem(entry.id, role.name, launch.model.id, launch.thinkingLevel, entry.delegation.name, ctx);
 								setState("running", "");
 								emitUpdate(emitToolUpdates);
 								return {

package/extensions/task-name.ts

@@ -0,0 +1,33 @@
+import { Type, type Static } from "typebox";
+
+const TASK_NAME_MAX_LENGTH = 29 as const;
+const TASK_NAME_CONTROL_RANGES = "\\u0000-\\u001F\\u007F-\\u009F" as const;
+const TASK_NAME_LIMIT_WORDING = `about five words and fewer than ${TASK_NAME_MAX_LENGTH + 1} characters`;
+const TASK_NAME_WORDING = `short descriptive name of ${TASK_NAME_LIMIT_WORDING}`;
+
+export const TASK_NAME_CONTRACT = {
+	minLength: 1,
+	maxLength: TASK_NAME_MAX_LENGTH,
+	description: `Short descriptive task name, ${TASK_NAME_LIMIT_WORDING}; C0/C1 control characters are rejected.`,
+	promptGuidance: `Use a ${TASK_NAME_WORDING} without C0/C1 control characters.`,
+	controlRanges: TASK_NAME_CONTROL_RANGES,
+	pattern: `^(?![\\s\\S]*[${TASK_NAME_CONTROL_RANGES}])[\\s\\S]+$`,
+} as const;
+
+export const TaskNameSchema = Type.String({
+	minLength: TASK_NAME_CONTRACT.minLength,
+	maxLength: TASK_NAME_CONTRACT.maxLength,
+	description: TASK_NAME_CONTRACT.description,
+	pattern: TASK_NAME_CONTRACT.pattern,
+});
+
+export type TaskName = Static<typeof TaskNameSchema>;
+
+const TASK_NAME_CONTROL_PATTERN = new RegExp(`[${TASK_NAME_CONTRACT.controlRanges}]`, "u");
+
+export function normalizeTaskName(value: TaskName, path: string): TaskName {
+	if (TASK_NAME_CONTROL_PATTERN.test(value)) throw new Error(`${path} must not contain C0/C1 control characters.`);
+	const normalized = value.trim();
+	if (!normalized) throw new Error(`${path} must be non-empty text.`);
+	return normalized;
+}

package/extensions/workflow.ts

@@ -2,6 +2,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { PROFILE_NAMES, THINKING_LEVELS } from "@henryqw/pi-task-models";
 import { Type, type Static } from "typebox";
 import { Check } from "typebox/value";
+import { TaskNameSchema, normalizeTaskName } from "./task-name.ts";
 
 export const MAX_WORKFLOW_ENTRIES = 8;
 
@@ -13,6 +14,7 @@ const ThinkingSchema = StringEnum(THINKING_LEVELS, { description: "Task thinking
 
 export const DelegationSchema = Type.Object({
 	role: RoleSchema,
+	name: TaskNameSchema,
 	task: TaskSchema,
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
@@ -21,6 +23,7 @@ export const DelegationSchema = Type.Object({
 
 export const WorkflowSchema = Type.Object({
 	role: Type.Optional(RoleSchema),
+	name: Type.Optional(TaskNameSchema),
 	task: Type.Optional(TaskSchema),
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
@@ -38,7 +41,7 @@ export const WorkflowSchema = Type.Object({
 	background: Type.Optional(Type.Boolean({ description: "Run the selected workflow without blocking" })),
 }, {
 	additionalProperties: false,
-	description: "Exactly one mode: role and task, tasks, or chain",
+	description: "Exactly one mode: role, name, and task; tasks; or chain",
 });
 
 export type Delegation = Static<typeof DelegationSchema>;
@@ -50,7 +53,7 @@ export type ParsedWorkflow =
 
 type WorkflowInput = Static<typeof WorkflowSchema>;
 
-const DELEGATION_KEYS = ["role", "task", "model", "modelClass", "thinking"] as const;
+const DELEGATION_KEYS = ["role", "name", "task", "model", "modelClass", "thinking"] as const;
 
 function text(value: string, path: string): string {
 	const normalized = value.trim();
@@ -61,6 +64,7 @@ function text(value: string, path: string): string {
 function normalizeDelegation(value: Delegation, path: string): Delegation {
 	return {
 		role: text(value.role, `${path}.role`),
+		name: normalizeTaskName(value.name, `${path}.name`),
 		task: text(value.task, `${path}.task`),
 		...(value.model === undefined ? {} : { model: text(value.model, `${path}.model`) }),
 		...(value.modelClass === undefined ? {} : { modelClass: value.modelClass }),
@@ -69,7 +73,7 @@ function normalizeDelegation(value: Delegation, path: string): Delegation {
 }
 
 function hasDelegation(value: WorkflowInput): value is WorkflowInput & Delegation {
-	return Object.hasOwn(value, "role") && Object.hasOwn(value, "task");
+	return Object.hasOwn(value, "role") && Object.hasOwn(value, "name") && Object.hasOwn(value, "task");
 }
 
 function workflowMode(value: unknown): WorkflowMode | undefined {
@@ -78,7 +82,7 @@ function workflowMode(value: unknown): WorkflowMode | undefined {
 	const parallel = Object.hasOwn(value, "tasks");
 	const chain = Object.hasOwn(value, "chain");
 	if (Number(single) + Number(parallel) + Number(chain) !== 1) {
-		throw new Error("workflow must select exactly one mode: role and task, tasks, or chain.");
+		throw new Error("workflow must select exactly one mode: role, name, and task; tasks; or chain.");
 	}
 	return single ? "single" : parallel ? "parallel" : "chain";
 }
@@ -86,11 +90,11 @@ function workflowMode(value: unknown): WorkflowMode | undefined {
 export function parseWorkflow(value: unknown): ParsedWorkflow {
 	const mode = workflowMode(value);
 	if (!Check(WorkflowSchema, value)) throw new Error("workflow must match the declared tool schema.");
-	if (!mode) throw new Error("workflow must select exactly one mode: role and task, tasks, or chain.");
+	if (!mode) throw new Error("workflow must select exactly one mode: role, name, and task; tasks; or chain.");
 	const input = value;
 	const background = input.background ?? false;
 	if (mode === "single") {
-		if (!hasDelegation(input)) throw new Error("workflow requires both role and task.");
+		if (!hasDelegation(input)) throw new Error("workflow requires role, name, and task.");
 		return { mode, background, delegations: [normalizeDelegation(input, "workflow")] };
 	}
 	if (mode === "parallel") return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "9.0.0",
+  "version": "10.1.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -64,7 +64,8 @@
     ]
   },
   "dependencies": {
+    "@henryqw/pi-config-store": "^0.1.0",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^3.0.0"
+    "@henryqw/pi-task-models": "^4.0.0"
   }
 }

package/extensions/tool-render.ts

@@ -1,16 +0,0 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-import { type Component, truncateToWidth } from "@earendil-works/pi-tui";
-
-export const MAX_RENDERED_RESULT_LINES = 3;
-
-export function renderToolLines(lines: readonly string[], theme: Theme): Component {
-	return {
-		invalidate() {},
-		render: (width) => {
-			const shown = lines.length > MAX_RENDERED_RESULT_LINES
-				? [...lines.slice(0, MAX_RENDERED_RESULT_LINES - 1), theme.fg("muted", `… ${lines.length - MAX_RENDERED_RESULT_LINES + 1} more`)]
-				: lines;
-			return shown.map((line) => truncateToWidth(line.replace(/[\r\n]+/g, " "), width));
-		},
-	};
-}