@henryqw/pi-subagent 9.0.0 → 10.0.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`) 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 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? })
 ```
 
@@ -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 |
 | --- | --- | --- | --- |

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";
@@ -95,7 +96,7 @@ function builtinRoles() {
  */
 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 +122,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/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
 }
@@ -66,12 +67,13 @@ 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. |
+| `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:
 

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.0.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));
-		},
-	};
-}