@henryqw/pi-subagent 10.1.1 → 11.0.0

package/CONTEXT.md

@@ -9,8 +9,8 @@ Provide validated built-in and user Roles, shared task-model Pi launch policy, g
 - **Main**: Pi session that plans and orchestrates delegated work.
 - **Subagent**: isolated Pi child process handling one task.
 - **Role**: package-shipped built-in or user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, required `tools`, `extensions`, and `skills` arrays, and optional isolation.
-- **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, resolved through shared task-model settings; direct model/thinking overrides remain explicit user choices.
-- **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
+- **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, resolved through shared task-model settings.
+- **Route**: configured model and exact thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback. A direct model can replace only its model.
 - **Delegated Task**: one bounded work request sent from Main to one Role.
 - **Workflow**: generic orchestration of one or more Delegated Tasks; `delegate_task` owns its selected mode, while library callers compose executor runs in JavaScript.
 - **Workflow Mode**: `delegate_task` tool policy selected per call for `single`, `parallel`, or `chain` execution; not a Role property or executor API.
@@ -27,8 +27,8 @@ 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/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`. 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. 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.
+- Main selects `modelClass`; an omitted class uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration (default `fast`). A direct model replaces only the selected route model and must honor its exact thinking level. 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. A direct model never changes the route level and fails before launch if it cannot honor it. 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.

package/README.md

@@ -44,27 +44,25 @@ Select exactly one shape:
 
 ```text
 // Single
-{ role, name, task, model?, modelClass?, thinking?, background? }
+{ role, name, task, model?, modelClass?, background? }
 
 // Parallel: 1–8 independent delegations
-{ tasks: [{ role, name, task, model?, modelClass?, thinking? }], background? }
+{ tasks: [{ role, name, task, model?, modelClass? }], background? }
 
 // Chain: 1–8 dependent delegations
-{ chain: [{ role, name, task, model?, modelClass?, thinking? }], background? }
+{ chain: [{ role, name, task, model?, modelClass? }], 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
+#### Model routing
 
-1. An explicit `model` is `provider/modelId` and overrides `modelClass`.
-2. Main sets direct `model` and `thinking` only for an explicit user override.
-3. Otherwise, Main selects `modelClass` according to the [delegation policy](./docs/orchestration.md#delegation-fields).
-4. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`.
-   When omitted, it uses pi-subagent's local `pi-subagent/delegateTask` Model Task declaration.
-   That declaration defaults to `fast` and shared config can explicitly override it.
+1. `modelClass` selects a route. It is `fast`, `balanced`, `frontier`, or `fav`.
+2. An omitted class uses pi-subagent's `pi-subagent/delegateTask` declaration. Its default is `fast`.
+3. The route supplies the model and exact thinking level.
+4. An explicit `model` is `provider/modelId`. It replaces only the route model and must support its thinking level.
 
-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.
+`background` applies to the whole selected mode. It 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.
 

package/dist/index.d.ts

@@ -54,7 +54,7 @@ export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
  * 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;
+export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
 export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
 export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
 export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: ExtensionContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;

package/dist/index.js

@@ -117,7 +117,7 @@ export function loadRoles(agentDir = getAgentDir()) {
     }
     return [...byName.values()];
 }
-export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir(), thinking) {
+export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
     let config;
     try {
         config = loadTaskModelsConfig(agentDir).value;
@@ -125,17 +125,17 @@ export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir(), thi
     catch {
         throw new Error("Couldn't read task model config. Run /task-models.");
     }
-    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName], agentDir, thinking);
+    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName], agentDir);
 }
-function resolveConfiguredRoute(ctx, profileName, profile, agentDir = getAgentDir(), thinking) {
+function resolveConfiguredRoute(ctx, profileName, profile, agentDir = getAgentDir()) {
     if (!profile)
         throw new Error(`No ${profileName} task model profile is configured. Run /task-models.`);
     for (const route of orderedProfileRoutes(profile)) {
-        const resolved = resolveTaskModelRoute(ctx, route, agentDir, thinking);
+        const resolved = resolveTaskModelRoute(ctx, route, agentDir);
         if (resolved)
             return resolved;
     }
-    throw new Error(`No usable ${profileName} task model route${thinking ? ` supporting thinking ${thinking}` : ""}. Run /task-models.`);
+    throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
 }
 export function resolveRoleSkills(pi, role) {
     const skills = new Map(pi.getCommands()

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

@@ -14,7 +14,7 @@ Resource Policy is split at launch preparation:
 
 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` according to delegation tool policy. This is not executor provenance tracking or runtime enforcement.
+`modelClass` selects a task-model route. The route owns its exact thinking level. A direct `model` replaces only the route model and must honor that level.
 
 ## Scope boundary
 

package/docs/orchestration.md

@@ -26,7 +26,6 @@ A call selects exactly one of these shapes. Unknown properties and nested modes
   "name": "Inspect authentication flow",
   "task": "One bounded task packet",
   "modelClass": "balanced",
-  "thinking": "high",
   "background": false
 }
 ```
@@ -69,11 +68,10 @@ 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`, `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 prioritizes `fast` for straightforward work and `balanced` for complex work, reserves `frontier` for exceptionally complex or tricky work, 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. |
+| `model` | no | Designated `provider/modelId`; replaces only the selected route model and must support that route's thinking level. |
+| `modelClass` | no | `fast`, `balanced`, `frontier`, or `fav`; selects the route. Main prioritizes `fast` for straightforward work and `balanced` for complex work. It reserves `frontier` for exceptionally complex or tricky work. Omission uses pi-subagent's local Model Task declaration. |
 
-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.
+Those five fields are the complete delegation object. Routes set exact thinking levels. A direct model never changes that level and fails before launch if it cannot support it. `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
 

package/extensions/subagent.ts

@@ -5,7 +5,6 @@ import { type Component, type TUI, truncateToWidth } from "@earendil-works/pi-tu
 import {
 	availableTaskModels,
 	loadTaskModelsConfig,
-	type ThinkingLevel,
 	modelReference,
 	registerModelTask,
 	resolveAvailableModel,
@@ -183,23 +182,17 @@ function renderWidgetRows(
 	return lines;
 }
 
-function resolveDesignatedRoute(ctx: ExtensionContext, reference: string, thinking?: ThinkingLevel): ResolvedTaskRoute {
+function replaceRouteModel(ctx: ExtensionContext, reference: string, route: ResolvedTaskRoute): ResolvedTaskRoute {
 	const models = availableTaskModels(ctx);
 	const model = resolveAvailableModel(models, reference, ctx.model?.provider);
 	if (!model) {
 		throw new Error(`Unknown delegate_task model: ${reference}. Available models: ${models.map((candidate) => modelReference(candidate)).join(", ") || "none"}.`);
 	}
 	const levels = taskThinkingLevels(ctx, model);
-	if (thinking !== undefined) {
-		if (!levels.includes(thinking)) {
-			throw new Error(`delegate_task thinking ${thinking} is not usable for ${modelReference(model)} in this session. Usable levels here: ${levels.join(", ") || "none"}.`);
-		}
-		return { model, thinkingLevel: thinking };
-	}
-	if (!levels.length) {
-		throw new Error(`${modelReference(model)} has no usable thinking level in this session; pick another model or adjust the scoped thinking pin.`);
+	if (!levels.includes(route.thinkingLevel)) {
+		throw new Error(`delegate_task model ${modelReference(model)} cannot use route thinking ${route.thinkingLevel} in this session. Usable levels here: ${levels.join(", ") || "none"}.`);
 	}
-	return { model, thinkingLevel: levels.includes("medium") ? "medium" : levels.at(-1)! };
+	return { model, thinkingLevel: route.thinkingLevel };
 }
 
 const BACKGROUND_RESULT_TYPE = "subagent-background-result";
@@ -539,7 +532,7 @@ export default function subagentExtension(
 		promptGuidelines: [
 			"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, ${MODEL_CLASS_GUIDANCE} This is Main policy, not runtime enforcement.`,
+			`For each delegate_task entry, ${MODEL_CLASS_GUIDANCE} A direct model replaces only the selected route's model; its thinking level stays unchanged.`,
 			"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.",
 		],
@@ -578,14 +571,16 @@ export default function subagentExtension(
 
 			// Resolve against the latest known session context after each FIFO permit.
 			const launchCtx = () => latestCtx ?? ctx;
-			const resolveLaunch = (role: Role, delegation: Delegation) => createRoleLaunch(pi, launchCtx(), {
-				role,
-				route: delegation.model !== undefined
-					? resolveDesignatedRoute(launchCtx(), delegation.model, delegation.thinking)
-					: delegation.modelClass === undefined
-						? resolveConfiguredTaskRoute(launchCtx(), DELEGATE_TASK, undefined, delegation.thinking)
-						: resolveTaskRoute(launchCtx(), delegation.modelClass, undefined, delegation.thinking),
-			});
+			const resolveLaunch = (role: Role, delegation: Delegation) => {
+				const context = launchCtx();
+				const route = delegation.modelClass === undefined
+					? resolveConfiguredTaskRoute(context, DELEGATE_TASK)
+					: resolveTaskRoute(context, delegation.modelClass);
+				return createRoleLaunch(pi, context, {
+					role,
+					route: delegation.model === undefined ? route : replaceRouteModel(context, delegation.model, route),
+				});
+			};
 			const notifyMissingSkills = (role: Role, launch: ReturnType<typeof resolveLaunch>) => {
 				if (launch.missingSkills.length) {
 					ctx.ui.notify(

package/extensions/workflow.ts

@@ -1,5 +1,5 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { PROFILE_NAMES, THINKING_LEVELS } from "@henryqw/pi-task-models";
+import { PROFILE_NAMES } from "@henryqw/pi-task-models";
 import { Type, type Static } from "typebox";
 import { Check } from "typebox/value";
 import { TaskNameSchema, normalizeTaskName } from "./task-name.ts";
@@ -8,9 +8,8 @@ export const MAX_WORKFLOW_ENTRIES = 8;
 
 const RoleSchema = Type.String({ minLength: 1, description: "Configured Subagent role name" });
 const TaskSchema = Type.String({ minLength: 1, description: "Bounded task packet" });
-const ModelSchema = Type.String({ minLength: 1, description: "Designated model as provider/modelId; overrides modelClass" });
+const ModelSchema = Type.String({ minLength: 1, description: "Designated model as provider/modelId; replaces the selected route model" });
 const ModelClassSchema = StringEnum(PROFILE_NAMES, { description: "Task model profile" });
-const ThinkingSchema = StringEnum(THINKING_LEVELS, { description: "Task thinking-level override" });
 
 export const DelegationSchema = Type.Object({
 	role: RoleSchema,
@@ -18,7 +17,6 @@ export const DelegationSchema = Type.Object({
 	task: TaskSchema,
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
-	thinking: Type.Optional(ThinkingSchema),
 }, { additionalProperties: false });
 
 export const WorkflowSchema = Type.Object({
@@ -27,7 +25,6 @@ export const WorkflowSchema = Type.Object({
 	task: Type.Optional(TaskSchema),
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
-	thinking: Type.Optional(ThinkingSchema),
 	tasks: Type.Optional(Type.Array(DelegationSchema, {
 		minItems: 1,
 		maxItems: MAX_WORKFLOW_ENTRIES,
@@ -53,7 +50,7 @@ export type ParsedWorkflow =
 
 type WorkflowInput = Static<typeof WorkflowSchema>;
 
-const DELEGATION_KEYS = ["role", "name", "task", "model", "modelClass", "thinking"] as const;
+const DELEGATION_KEYS = ["role", "name", "task", "model", "modelClass"] as const;
 
 function text(value: string, path: string): string {
 	const normalized = value.trim();
@@ -68,7 +65,6 @@ function normalizeDelegation(value: Delegation, path: string): Delegation {
 		task: text(value.task, `${path}.task`),
 		...(value.model === undefined ? {} : { model: text(value.model, `${path}.model`) }),
 		...(value.modelClass === undefined ? {} : { modelClass: value.modelClass }),
-		...(value.thinking === undefined ? {} : { thinking: value.thinking }),
 	};
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "10.1.1",
+  "version": "11.0.0",
   "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
   "keywords": [
     "pi-package",

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

@@ -31,4 +31,4 @@ Make the guidance specific to the reported implementation, validation, or review
 
 ## Ordinary delegation
 
-Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Populate direct `model` and `thinking` only when the user explicitly asks for those overrides; otherwise choose `modelClass` according to the delegation tool's guidance. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.
+Use `delegate_task` for a single bounded task, independent parallel tasks, or dependent chain work that is not a Flow. Give each entry its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and focused validation. Choose `modelClass` according to the delegation tool's guidance. A direct `model` replaces only the selected route's model. The route keeps its thinking level. Keep integration and cross-cutting decisions in Main, and use the minimum number of Subagents needed.