@henryqw/pi-subagent 6.1.1 → 7.0.0

package/CONTEXT.md

@@ -28,10 +28,10 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
 - Ambient child extensions and Skills stay disabled. Every Role requires `tools`, `extensions`, and `skills` YAML arrays, and every launch installs the Role tool policy. `tools: []` activates no base built-ins but does activate all tools from explicitly selected trusted extension bundles and explicit caller tool additions; `skills: []` selects no separately named Role Skills but trusted selected extension Skills still load; `extensions: []` selects no Role extension bundle. A Role/caller explicitly selected extension is a trusted atomic capability bundle: all tools it registers and all Skills supplied through its Pi package metadata or dynamic `resources_discover` load alongside separately named Role Skills. This intentionally includes the extension's executable lifecycle/prompt behavior; pi-subagent does not infer or externally narrow undocumented dependencies, and loading an extension is not sandboxing. Scope children by selecting fewer trusted extensions; finer granularity requires separate entry points/configuration or an upstream split. Explicit Role/caller tool names still verify against the final filtered registry, while parent-only recursive orchestration tools remain excluded.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation. Explicit Role/caller tool names verify against the final filtered child registry after explicit provider `session_start` handlers, and unavailable names fail before the first turn.
-- Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses the shared `pi-subagent/delegateTask` assignment; library callers select a Role plus their own shared task ID.
+- Main policy populates direct `model` and `thinking` only for explicit user overrides; otherwise it selects only `modelClass` (`fast` normally, `balanced` upfront for obvious complexity). This has no provenance tracking or runtime enforcement. An omitted class uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`); library callers select a Role plus their own Model Task declaration.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
 - User Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`. Package-shipped built-in Roles (`implementer`, `reviewer`) resolve from the package's own `examples/roles/` Markdown through the same parser; a same-named user file explicitly overrides a built-in for `delegate_task` and `delegate_flow`.
-- `delegate_flow` accepts 1–8 independent units with direct validation commands, optional `modelClass`, and optional non-empty `review` judgment text. Omitted classes use the shared `pi-subagent/delegateTask` assignment; each unit's current class resolves through its shared profile route for its Implementer and, when `review` exists, Reviewer. At Flow start it always resolves/freezes the effective Implementer and resolves/freezes a Reviewer only when at least one requested unit has `review`. One active Flow creates every Unit Worktree before launching Implementers in parallel, then processes settled units in declared order. For each unit Flow rebases in place when earlier units advanced Main, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification: units without `review` fast-forward their exact validated tip; units with `review` send the exact Review Packet to the Reviewer in the same worktree and require exact `PASS` before the same guarded `git merge --ff-only` path.
+- `delegate_flow` accepts 1–8 independent units with direct validation commands, optional `modelClass`, and optional non-empty `review` judgment text. Omitted classes use pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); each unit's current class resolves through its shared profile route for its Implementer and, when `review` exists, Reviewer. At Flow start it always resolves/freezes the effective Implementer and resolves/freezes a Reviewer only when at least one requested unit has `review`. One active Flow creates every Unit Worktree before launching Implementers in parallel, then processes settled units in declared order. For each unit Flow rebases in place when earlier units advanced Main, inspects committed Git state, and runs declared validation. Validation is authoritative for objective verification: units without `review` fast-forward their exact validated tip; units with `review` send the exact Review Packet to the Reviewer in the same worktree and require exact `PASS` before the same guarded `git merge --ff-only` path.
 - Flow is memory-only. Only a post-rebase commit drop produces a no-op (`base === tip`); it validates, skips Reviewer and merge, then cleans up ordinarily. Initial zero-commit implementations block. Implementer, validation, or reviewer blocks allow one `delegate_flow_continue({ guidance, modelClass? })` repair in the same worktree; omission retains the Unit's current class and presence replaces it for that repair. A second block is terminal. Rebase and evidence/Reviewer/infrastructure failures retain worktrees. A reported fast-forward failure retains its worktree unless Main is clean at the exact integrated tip, which completes with the merge diagnostic as a warning. Cleanup uses non-forced worktree removal and branch deletion; cleanup refusal is a completion warning.
 - Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge validation. It never changes generic `delegate_task` Role resolution, isolation, non-Git fallback, or ordinary direct plan/file review.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.

package/README.md

@@ -47,7 +47,7 @@ Select exactly one shape:
 { chain: [{ role, task, model?, modelClass?, thinking? }], background? }
 ```
 
-`model` is `provider/modelId` and overrides `modelClass`. Main populates `model` and `thinking` only for an explicit user override; otherwise it chooses only `modelClass`—`fast` normally, or `balanced` upfront for obviously complex work. This is Main policy only: the runtime records no provenance and does not enforce it. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses the shared `pi-subagent/delegateTask` assignment. `background` applies to the entire selected mode and is never a per-delegation field.
+`model` is `provider/modelId` and overrides `modelClass`. Main populates `model` and `thinking` only for an explicit user override; otherwise it chooses only `modelClass`—`fast` normally, or `balanced` upfront for obviously complex work. This is Main policy only: the runtime records no provenance and does not enforce it. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`), which shared config can explicitly override. `background` applies to the entire selected mode and is never a per-delegation field.
 
 Parallel mode starts entries concurrently, waits for every entry, and reports them in input order. Chain mode is sequential and fail-fast; every literal `{previous}` receives only the immediately preceding successful assistant output. Foreground failures throw after retaining bounded sibling and recovery evidence. One tool call has one aggregate 50 KiB Main-visible transport cap, not 50 KiB per child.
 
@@ -70,7 +70,7 @@ delegate_flow_continue({ guidance, modelClass? })
 
 Objective verification is authoritative. Flow always inspects committed Git state and runs declared validation. A unit without `review` skips review evidence and Reviewer launch, then fast-forwards its exact validated tip through the existing guarded `git merge --ff-only` path. Add `review` only for an explicit judgment that automation cannot establish; that unit retains the exact `{base, tip, patchPath}` protocol and requires exact `PASS` before the same integration path.
 
-One memory-only Flow may be active. At start it resolves/freezes the effective `implementer` Role, including a same-named user override, and resolves/freezes the effective `reviewer` only if at least one requested unit has `review`. Omitted `modelClass` uses the shared `pi-subagent/delegateTask` assignment; a selected class resolves through its shared profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It creates one Unit Worktree per unit, runs Implementers in parallel, then processes settled results in declared order. It removes the worktree and branch non-forcibly after integration; a refusal is a completion warning with the retained worktree path and/or branch.
+One memory-only Flow may be active. At start it resolves/freezes the effective `implementer` Role, including a same-named user override, and resolves/freezes the effective `reviewer` only if at least one requested unit has `review`. Omitted `modelClass` uses pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); a selected class resolves through its shared profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It creates one Unit Worktree per unit, runs Implementers in parallel, then processes settled results in declared order. It removes the worktree and branch non-forcibly after integration; a refusal is a completion warning with the retained worktree path and/or branch.
 
 A rebase that drops all unit commits is a no-op: Flow validates it, skips Reviewer and merge, then cleans up ordinarily. Implementer, validation, or review blocks can be repaired once through `delegate_flow_continue` in the same worktree. Omitted continuation `modelClass` retains the blocked unit's current class; a supplied class replaces it for that one repair. Rebase and infrastructure failures are terminal. A reported fast-forward failure completes with its diagnostic as a warning only when Git left Main clean at the exact integrated tip; otherwise it is terminal and retains the affected worktree. Flow has no graph, saved recovery, automatic retry, aggregate review, or post-merge gate.
 
@@ -90,7 +90,7 @@ A rebase that drops all unit commits is a no-op: Flow validates it, skips Review
 
 ## Config
 
-pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`, which holds two kinds of user-owned configuration: one Markdown file per Role (see [Roles](#roles)) and its own optional JSON file below. Model routing is *not* configured here; children resolve routes through the shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`.
+pi-subagent owns the extension-named config directory `~/.pi/agent/config/pi-subagent/`, which holds two kinds of user-owned configuration: one Markdown file per Role (see [Roles](#roles)) and its own optional JSON file below. Model routing is *not* configured here; children resolve routes through the shared `@henryqw/pi-task-models` config at `~/.pi/agent/config/pi-task-models.json`, which stores only explicit task overrides. The local `pi-subagent/delegateTask` declaration supplies the omitted-class default.
 
 `~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and timeouts. All fields are optional; a missing file uses defaults.
 
@@ -155,4 +155,4 @@ A Role explicitly owns base tools, extensions, named Skills, instructions, and o
 
 The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support. After Pi itself exits, it drains inherited stdout/stderr normally but destroys streams still held by escaped descendants after a short inactivity deadline or one-second hard deadline, so they cannot retain a pool permit.
 
-Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` against the latest Pi context.
+Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` with a caller-owned Model Task declaration against the latest Pi context.

package/dist/index.d.ts

@@ -1,12 +1,18 @@
 import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type HerdrExecutor } from "@henryqw/pi-herdr";
-import { type AvailableModel, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
+import { type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@henryqw/pi-task-models";
 export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, EphemeralSubagentError, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
 export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, worktreeContextNote, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
 export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
 export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
 export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "delegate_flow", "delegate_flow_continue", "ask_question"];
 export declare const CHILD_EXCLUDED_TOOLS: string;
+export declare const DELEGATE_TASK: {
+    readonly id: "pi-subagent/delegateTask";
+    readonly label: "Subagent delegation";
+    readonly purpose: "Launch an isolated Pi subagent.";
+    readonly defaultProfile: "fast";
+};
 export interface Role {
     name: string;
     description: string;
@@ -33,7 +39,7 @@ export interface CreateRoleLaunchInput {
     env?: Readonly<Record<string, string>>;
 }
 export interface ResolveRoleLaunchInput extends Omit<CreateRoleLaunchInput, "route"> {
-    taskId: string;
+    task: ModelTask;
     agentDir?: string;
 }
 export interface ResolvedRoleSkills {

package/dist/index.js

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

package/docs/orchestration.md

@@ -5,7 +5,7 @@
 ```text
 Role (built-in or user override) + latest Pi registries ── resolveRoleLaunch ──> PiLaunch
                                                         │
-caller-owned task, cwd, signal ─────────────────────────┤
+caller-owned Model Task declaration, cwd, signal ────────┤
                                                         v
                                      active-Pi ephemeral executor
 ```
@@ -68,7 +68,7 @@ Single mode puts one delegation's fields at the top level.
 | `role` | yes | Name of a Role in the user's effective `config/pi-subagent` directory or a package-shipped built-in (`implementer`, `reviewer`); a same-named user file overrides the built-in. |
 | `task` | yes | Non-empty bounded task packet. |
 | `model` | no | Designated `provider/modelId`; takes precedence over `modelClass`, and Main supplies it only for an explicit user override. |
-| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; Main normally chooses `fast`, may choose `balanced` upfront for obvious complexity, and omission uses shared task assignment. |
+| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; Main normally chooses `fast`, may choose `balanced` upfront for obvious complexity, and omission uses pi-subagent's local Model Task declaration. |
 | `thinking` | no | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`; Main supplies it only for an explicit user override. Route selection skips models that cannot honor it. |
 
 Those five fields are the complete delegation object. The direct-model/thinking rule is Main-facing policy only: the runtime adds no provenance tracking or enforcement. `tasks`, `chain`, and `background` cannot be nested. Route fallback occurs only before launch; a started child is never retried by this package.
@@ -85,7 +85,7 @@ All Main-visible text for one tool call shares one aggregate 50 KiB UTF-8 transp
 
 `delegate_flow({ units })` accepts 1–8 units with unique non-empty `id` and `task`, one or more direct `{command, args}` validation commands, optional `modelClass`, and optional non-empty `review` text. `delegate_flow_continue({ guidance, modelClass? })` is available only for the one blocked unit of the active Flow.
 
-A Flow is memory-only and permits one active Flow. At start it always resolves/freezes the effective `implementer` Role, including a same-named user override. It resolves/freezes the effective `reviewer` only if at least one requested unit declares `review`. Omitted unit classes use the shared `pi-subagent/delegateTask` assignment; a selected class resolves through its existing `pi-task-models` profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It requires clean committed Git Main and creates every Unit Worktree before launching work; setup failure launches no Implementer. Each unit gets exactly one worktree and one Implementer. Implementers run in parallel and all settle. Flow then processes units in declared order:
+A Flow is memory-only and permits one active Flow. At start it always resolves/freezes the effective `implementer` Role, including a same-named user override. It resolves/freezes the effective `reviewer` only if at least one requested unit declares `review`. Omitted unit classes use pi-subagent's local `pi-subagent/delegateTask` declaration (default `fast`); a selected class resolves through its existing `pi-task-models` profile model-and-thinking route for the unit's Implementer and, when applicable, Reviewer. It requires clean committed Git Main and creates every Unit Worktree before launching work; setup failure launches no Implementer. Each unit gets exactly one worktree and one Implementer. Implementers run in parallel and all settle. Flow then processes units in declared order:
 
 ```text
 Implementers (parallel, one Unit Worktree each)
@@ -149,12 +149,12 @@ The package root exports the following mechanism-level APIs:
 | --- | --- |
 | `loadRoles(agentDir?)` | Validate and load package-shipped built-in and user Role Markdown. |
 | `resolveRoleSkills(pi, role)` | Resolve Role Skill names from Pi's effective registry. |
-| `resolveRoleLaunch(pi, ctx, input)` | Resolve a shared task route and produce `ResolvedRoleLaunch`. |
+| `resolveRoleLaunch(pi, ctx, input)` | Resolve a caller-owned Model Task route and produce `ResolvedRoleLaunch`. |
 | `createRoleLaunch(pi, ctx, input)` | Produce the same launch from a caller-supplied resolved route. |
 | `createEphemeralSubagentExecutor(options)` | Queue and run one prepared no-session child per `run`. |
 | `createChildWorktree` / `finalizeChildWorktree` | Optional caller-managed worktree lifecycle. |
 
-A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, `taskId`, and optional caller `agentDir`, `extensions`, `tools`, and `env`. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
+A loaded `Role` contains `name`, `description`, required normalized `tools`, `extensions`, and `skills` arrays, optional `isolation`, and `systemPrompt`. `resolveRoleLaunch` accepts `role`, a caller-owned `task` Model Task declaration, and optional caller `agentDir`, `extensions`, `tools`, and `env`. At extension load, callers invoke `registerModelTask(pi, task)` from `@henryqw/pi-task-models` once to expose that declaration in the shared control plane. Its result is a `PiLaunch` (`{ env, args }`) plus the selected `model`, `thinkingLevel`, and `missingSkills`.
 
 `createEphemeralSubagentExecutor` requires:
 
@@ -178,54 +178,69 @@ import {
   createEphemeralSubagentExecutor,
   resolveRoleLaunch,
 } from "@henryqw/pi-subagent";
+import { registerModelTask } from "@henryqw/pi-task-models";
 
-const executor = createEphemeralSubagentExecutor({
-  maxConcurrency: 4,
-  timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
-});
+const MODEL_TASK = {
+  id: "your-package/delegate",
+  label: "Package delegation",
+  purpose: "Run one package-owned delegated task.",
+  defaultProfile: "fast",
+};
 
-let latestCtx;
-pi.on("session_start", (_event, ctx) => { latestCtx = ctx; });
-pi.on("model_select", (event, ctx) => {
-  latestCtx = { ...ctx, model: event.model };
-});
-pi.on("agent_settled", (_event, ctx) => { latestCtx = ctx; });
+export function createRunRole(pi) {
+  // Register the Model Task at extension load so /task-models discovery works.
+  registerModelTask(pi, MODEL_TASK);
 
-function latestContext() {
-  if (!latestCtx) throw new Error("Pi session has not started.");
-  return latestCtx;
-}
+  const executor = createEphemeralSubagentExecutor({
+    maxConcurrency: 4,
+    timeout: { idleMs: 10 * 60_000, maxMs: 30 * 60_000 },
+  });
 
-async function runRole(role, task, options = {}) {
-  const {
-    signal,
-    cwd,
-    extensions = [],
-    tools,
-    env = {},
-  } = options;
-
-  return executor.run({
-    signal,
-    prepare: async () => {
-      // prepare runs only after this delegation owns a FIFO permit.
-      const ctx = latestContext();
-      const launch = resolveRoleLaunch(pi, ctx, {
-        role,
-        taskId: "your-package/delegate",
-        extensions,
-        tools,
-        env,
-      });
-      if (launch.missingSkills.length && ctx.hasUI) {
-        ctx.ui.notify(
-          `Skipped unavailable Skills: ${launch.missingSkills.join(", ")}`,
-          "warning",
-        );
-      }
-      return { launch, task, cwd: cwd ?? ctx.cwd };
-    },
+  let latestCtx;
+  pi.on("session_start", (_event, ctx) => { latestCtx = ctx; });
+  pi.on("model_select", (event, ctx) => {
+    latestCtx = { ...ctx, model: event.model };
   });
+  pi.on("agent_settled", (_event, ctx) => { latestCtx = ctx; });
+
+  function latestContext() {
+    if (!latestCtx) throw new Error("Pi session has not started.");
+    return latestCtx;
+  }
+
+  async function runRole(role, task, options = {}) {
+    const {
+      signal,
+      cwd,
+      extensions = [],
+      tools,
+      env = {},
+    } = options;
+
+    return executor.run({
+      signal,
+      prepare: async () => {
+        // prepare runs only after this delegation owns a FIFO permit.
+        const ctx = latestContext();
+        const launch = resolveRoleLaunch(pi, ctx, {
+          role,
+          task: MODEL_TASK,
+          extensions,
+          tools,
+          env,
+        });
+        if (launch.missingSkills.length && ctx.hasUI) {
+          ctx.ui.notify(
+            `Skipped unavailable Skills: ${launch.missingSkills.join(", ")}`,
+            "warning",
+          );
+        }
+        return { launch, task, cwd: cwd ?? ctx.cwd };
+      },
+    });
+  }
+
+  return { runRole };
 }
 ```
 
@@ -249,7 +264,17 @@ Generic managed Herdr exports (`managedSubagentWorkspaceId`, reconciliation help
 
 ## JavaScript composition
 
-The examples below use caller-selected `Role` objects and the `runRole` helper above. Variable names such as `reviewRole` are local bindings, not reserved Role names. The executor's `maxConcurrency` bounds launches; callers must also bound collections and loops.
+The examples below use caller-selected `Role` objects and the `runRole` function returned by the package's initializer. A consuming Pi extension calls the initializer once at startup:
+
+```js
+import { createRunRole } from "your-package";
+
+export default function yourExtension(pi) {
+  const { runRole } = createRunRole(pi);
+}
+```
+
+Variable names such as `reviewRole` are local bindings, not reserved Role names. The executor's `maxConcurrency` bounds launches; callers must also bound collections and loops.
 
 A small caller-owned failure policy keeps the examples readable:
 

package/extensions/subagent.ts

@@ -6,6 +6,7 @@ import {
 	availableTaskModels,
 	type ThinkingLevel,
 	modelReference,
+	registerModelTask,
 	resolveAvailableModel,
 	resolveConfiguredTaskRoute,
 	type ResolvedTaskRoute,
@@ -15,6 +16,7 @@ import {
 	capEphemeralSubagentOutput as capOutput,
 	createChildWorktree,
 	createEphemeralSubagentExecutor,
+	DELEGATE_TASK,
 	createRoleLaunch,
 	EphemeralSubagentError,
 	finalizeChildWorktree,
@@ -54,7 +56,6 @@ import {
 	type WorkflowEntry,
 } from "./workflow.ts";
 
-const SUBAGENT_TASK = "pi-subagent/delegateTask";
 const WIDGET_KEY = "subagent-status";
 const WIDGET_INTERVAL_MS = 80;
 const MAX_WIDGET_ITEMS = 8;
@@ -304,6 +305,7 @@ export default function subagentExtension(
 	pi: ExtensionAPI,
 	overrideTimeoutPolicy?: TimeoutPolicy,
 ): void {
+	registerModelTask(pi, DELEGATE_TASK);
 	const widgetItems = new Map<string, WidgetItem>();
 	// Each child is a full Pi process issuing its own model calls; cap parallel
 	// spend. Precedence: PI_SUBAGENT_MAX_SUBAGENTS env > config/pi-subagent/pi-subagent.json
@@ -584,7 +586,7 @@ export default function subagentExtension(
 			return createRoleLaunch(pi, launchCtx, {
 				role,
 				route: modelClass === undefined
-					? resolveConfiguredTaskRoute(launchCtx, SUBAGENT_TASK)
+					? resolveConfiguredTaskRoute(launchCtx, DELEGATE_TASK)
 					: resolveTaskRoute(launchCtx, modelClass),
 			});
 		},
@@ -661,7 +663,7 @@ export default function subagentExtension(
 				route: delegation.model !== undefined
 					? resolveDesignatedRoute(launchCtx(), delegation.model, delegation.thinking)
 					: delegation.modelClass === undefined
-						? resolveConfiguredTaskRoute(launchCtx(), SUBAGENT_TASK, undefined, delegation.thinking)
+						? resolveConfiguredTaskRoute(launchCtx(), DELEGATE_TASK, undefined, delegation.thinking)
 						: resolveTaskRoute(launchCtx(), delegation.modelClass, undefined, delegation.thinking),
 			});
 			const notifyMissingSkills = (role: Role, launch: ReturnType<typeof resolveLaunch>) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "6.1.1",
+  "version": "7.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",
@@ -66,6 +66,6 @@
   "dependencies": {
     "@henryqw/pi-herdr": "^0.4.0",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^2.0.0"
+    "@henryqw/pi-task-models": "^3.0.0"
   }
 }

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

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