@henryqw/pi-subagent 2.9.5 → 2.10.1

package/CONTEXT.md

@@ -17,12 +17,12 @@ Provide validated user Roles, shared task-model Pi launch policy, generic manage
 
 ## Invariants
 
-- One Delegated Task creates one ephemeral child process and no saved session. Default timeouts: 10-minute soft deadline; active model/tool execution or activity within the last minute grants one 5-minute grace period before a hard stop. Every value is configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent.json` (`softMinutes`, `graceMinutes`, `activeWindowSeconds`).
-- Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/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.
+- One Delegated Task creates one ephemeral child process and no saved session. Default timeouts: 10-minute soft deadline; active model/tool execution or activity within the last minute grants one 5-minute grace period before a hard stop. Every value is configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`softMinutes`, `graceMinutes`, `activeWindowSeconds`).
+- 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; Role explicitly selects extension sources and named Skills. Pi loads Skills supplied by those extension packages or their resource discovery. Omitted Role tools use Pi's effective `defaultTools`; an explicit list sets base tools while loaded extension tools activate automatically.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
-- Main selects Role and may override Model Class per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
+- Main selects Role and may override Model Class and thinking level per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
 - 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.
-- Role config lives only in user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
+- Role and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
 - Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -21,13 +21,13 @@ pi install npm:@henryqw/pi-subagent
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `delegate_task` | tool | Start one isolated child for `role`, `task`, and optional `model` or `modelClass`. |
+| `delegate_task` | tool | Start one isolated child for `role`, `task`, and optional `model`, `modelClass`, or `thinking`. |
 
-An explicit `model` (`provider/modelId`) overrides `modelClass` and resolves against the currently available text models; an unknown reference rejects with the list of available models. Thinking level defaults to `medium` when supported, otherwise the highest supported level.
+An explicit `model` (`provider/modelId`) overrides `modelClass` and resolves against the currently available text models; an unknown reference rejects with the list of available models. Thinking level defaults to `medium` when supported, otherwise the highest supported level; a designated model with no usable level rejects before launch. An explicit `thinking` level participates in route resolution itself: routes that cannot honor it are skipped so fallback routes get considered, and delegation rejects when no route supports the level.
 
 `modelClass` is `fast`, `balanced`, `frontier`, or `fav`. Omitted class uses the shared `pi-subagent/delegateTask` assignment, which defaults to `balanced`. Primary route is resolved against current scoped text models; fallback is tried only before launch. If no route is usable, delegation rejects with `Run /task-models`. A started child is never retried.
 
-Main splits broad work into independent bounded tasks and keeps integration and cross-cutting decisions. Each `task` states its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation. Each call uses the least capable `modelClass` that can reliably complete its task. Independent sibling calls can run concurrently; concurrent edit tasks must own non-overlapping files. Up to five active ephemeral `delegate_task` subagents run per Main; excess calls wait FIFO. Configure the cap with `"maxSubagents"` (positive integer) in `~/.pi/agent/config/pi-subagent.json`, or override per session with the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable. Child timeouts are configurable with a `"timeout"` object: `{ "softMinutes": 20, "graceMinutes": 10, "activeWindowSeconds": 90 }` (all keys optional; defaults 10/5/60). Invalid config values fall back to the default with a warning; an invalid environment variable fails fast. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
+Main splits broad work into independent bounded tasks and keeps integration and cross-cutting decisions. Each `task` states its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation. Each call uses the least capable `modelClass` that can reliably complete its task. Independent sibling calls can run concurrently; concurrent edit tasks must own non-overlapping files. Up to five active ephemeral `delegate_task` subagents run per Main; excess calls wait FIFO. Configure the cap with `"maxSubagents"` (positive integer) in `~/.pi/agent/config/pi-subagent/pi-subagent.json`, or override per session with the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable. Child timeouts are configurable with a `"timeout"` object: `{ "softMinutes": 20, "graceMinutes": 10, "activeWindowSeconds": 90 }` (all keys optional; defaults 10/5/60). Invalid config values fall back to the default with a warning; an invalid environment variable fails fast. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
 
 Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and Skills are off. Role/caller extensions load; those packages' tools and Skills auto-load, plus any extra `skills` names. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. An inactive child times out after 10 minutes; current model/tool execution or activity in the last minute grants one 5-minute grace period, then the child stops. Streaming output is capped at 50 KiB. Unused JSON event types are discarded before payload buffering; consumed or unclassifiable events above 1 MiB fail delegation.
 
@@ -35,7 +35,7 @@ TUI shows one row per Subagent with role, route, task, tokens, and elapsed time.
 
 ## Config
 
-Role files live in `~/.pi/agent/config/pi-subagent/*.md`. Model routes live in `~/.pi/agent/config/pi-task-models.json`.
+Role files and `pi-subagent.json` live in `~/.pi/agent/config/pi-subagent/`. Model routes live in `~/.pi/agent/config/pi-task-models.json`.
 
 ```markdown
 ---

package/dist/index.d.ts

@@ -35,7 +35,7 @@ export interface ResolvedRoleSkills {
 }
 export declare const isProfileName: (value: unknown) => value is ProfileName;
 export declare function loadRoles(agentDir?: string): Role[];
-export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
+export declare function resolveTaskRoute(ctx: ExtensionContext, profileName: ProfileName, agentDir?: string, thinking?: ThinkingLevel): 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

@@ -81,7 +81,7 @@ export function loadRoles(agentDir = getAgentDir()) {
     }
     return roles;
 }
-export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
+export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir(), thinking) {
     let config;
     try {
         config = readTaskModelsConfig(agentDir);
@@ -89,17 +89,17 @@ export function resolveTaskRoute(ctx, profileName, agentDir = getAgentDir()) {
     catch {
         throw new Error("Couldn't read task model config. Run /task-models.");
     }
-    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName], agentDir);
+    return resolveConfiguredRoute(ctx, profileName, config.profiles[profileName], agentDir, thinking);
 }
-function resolveConfiguredRoute(ctx, profileName, profile, agentDir = getAgentDir()) {
+function resolveConfiguredRoute(ctx, profileName, profile, agentDir = getAgentDir(), thinking) {
     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);
+        const resolved = resolveTaskModelRoute(ctx, route, agentDir, thinking);
         if (resolved)
             return resolved;
     }
-    throw new Error(`No usable ${profileName} task model route. Run /task-models.`);
+    throw new Error(`No usable ${profileName} task model route${thinking ? ` supporting thinking ${thinking}` : ""}. Run /task-models.`);
 }
 export function resolveRoleSkills(pi, role) {
     const skills = new Map(pi.getCommands()

package/extensions/config.ts

@@ -39,14 +39,14 @@ const TIMEOUT_FIELDS: Array<[keyof SubagentTimeoutConfig, number, string]> = [
 ];
 
 /**
- * Required single-extension config path form (AGENTS.md); agentDir is
- * injectable so tests can point at a temp directory.
+ * All pi-subagent config lives in its existing extension-named directory;
+ * agentDir is injectable so tests can point at a temp directory.
  */
 export const configPath = (agentDir = getAgentDir()): string =>
-	join(agentDir, "config", "pi-subagent.json");
+	join(agentDir, "config", "pi-subagent", "pi-subagent.json");
 
 /**
- * Read the optional user config at `<agentDir>/config/pi-subagent.json`.
+ * 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.
  */

package/extensions/subagent.ts

@@ -7,15 +7,18 @@ import { type Component, truncateToWidth, type TUI, visibleWidth } from "@earend
 import { readSubagentConfig, type SubagentTimeoutConfig } from "./config.ts";
 import {
 	availableTaskModels,
+	THINKING_LEVELS,
+	type ThinkingLevel,
 	modelReference,
 	PROFILE_NAMES,
 	type ProfileName,
 	resolveAvailableModel,
+	resolveConfiguredTaskRoute,
 	type ResolvedTaskRoute,
 	taskThinkingLevels,
 } from "@henryqw/pi-task-models";
 import { Type } from "typebox";
-import { createRoleLaunch, isProfileName, loadRoles, resolveRoleLaunch, resolveTaskRoute } from "@henryqw/pi-subagent";
+import { createRoleLaunch, isProfileName, loadRoles, resolveTaskRoute } from "@henryqw/pi-subagent";
 
 const MODEL_CLASSES = PROFILE_NAMES;
 const SUBAGENT_TASK = "pi-subagent/delegateTask";
@@ -440,17 +443,29 @@ const Parameters = Type.Object({
 		description: "Classify task complexity: fast for narrow lookups or mechanical edits; balanced for normal bounded work; frontier for ambiguous, cross-cutting, or high-risk reasoning; fav for the user's favorite model when they ask for it. Defaults to the shared pi-subagent/delegateTask assignment.",
 	})),
 	background: Type.Optional(Type.Boolean({
-		description: "Run without blocking: returns a task ID immediately and delivers the outcome as a message when the Subagent settles. Prefer blocking delegation whenever the parent needs the result to continue.",
+		description: "Run without blocking: returns a task ID immediately and delivers the outcome as a message when the Subagent settles; the result cannot be waited on. Set only when the user explicitly asks for non-blocking delegation. Prefer blocking delegation whenever the parent needs the result to continue.",
+	})),
+	thinking: Type.Optional(StringEnum(THINKING_LEVELS, {
+		description: "Override the resolved route's thinking level (e.g. when the user asks for deeper or lighter reasoning). Must be supported by the resolved model.",
 	})),
 });
 
-function resolveDesignatedRoute(ctx: ExtensionContext, reference: string): ResolvedTaskRoute {
+function resolveDesignatedRoute(ctx: ExtensionContext, reference: string, thinking?: ThinkingLevel): 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.`);
+	}
 	return { model, thinkingLevel: levels.includes("medium") ? "medium" : levels.at(-1)! };
 }
 
@@ -471,7 +486,7 @@ export default function subagentExtension(
 ): void {
 	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.json
+	// 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.
 	const loadedConfig = readSubagentConfig();
@@ -660,7 +675,7 @@ export default function subagentExtension(
 	pi.registerTool({
 		name: "delegate_task",
 		label: "Subagent",
-		description: `Delegate one bounded, independently executable task to one isolated Pi Subagent. Roles: ${roleSummary()}. Choose fast for narrow work, balanced for normal work, frontier for ambiguous and high-risk work, or fav when the user asks for their favorite model; omit modelClass to use shared task-model settings. When the user designates a specific model, pass it as provider/modelId in model. Set background only when the user explicitly wants the task to run without blocking; background tasks report results later and cannot be waited on.`,
+		description: `Delegate one bounded, independently executable task to one isolated Pi Subagent. Roles: ${roleSummary()}.`,
 		promptSnippet: "Delegate one bounded, independently executable task to an isolated role",
 		promptGuidelines: [
 			"Before calling delegate_task, split broad work into the smallest independent bounded tasks; keep integration and cross-cutting decisions in Main.",
@@ -685,11 +700,16 @@ export default function subagentExtension(
 			// the cap must pick up model or Codex account changes that happened
 			// while it waited.
 			const launchCtx = () => latestCtx ?? ctx;
-			const resolveLaunch = () => params.model !== undefined
-				? createRoleLaunch(pi, launchCtx(), { role, route: resolveDesignatedRoute(launchCtx(), cleanText(params.model, "model", "delegate_task")) })
-				: params.modelClass === undefined
-					? resolveRoleLaunch(pi, launchCtx(), { role, taskId: SUBAGENT_TASK })
-					: createRoleLaunch(pi, launchCtx(), { role, route: resolveTaskRoute(launchCtx(), params.modelClass) });
+			// The explicit thinking override participates in route resolution itself:
+			// routes that cannot honor it are skipped so fallback routes get considered.
+			const resolveLaunch = () => createRoleLaunch(pi, launchCtx(), {
+				role,
+				route: params.model !== undefined
+					? resolveDesignatedRoute(launchCtx(), cleanText(params.model, "model", "delegate_task"), params.thinking)
+					: params.modelClass === undefined
+						? resolveConfiguredTaskRoute(launchCtx(), SUBAGENT_TASK, undefined, params.thinking)
+						: resolveTaskRoute(launchCtx(), params.modelClass, undefined, params.thinking),
+			});
 			const notifyMissingSkills = (launch: ReturnType<typeof resolveLaunch>) => {
 				if (launch.missingSkills.length) {
 					ctx.ui.notify(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "2.9.5",
+  "version": "2.10.1",
   "description": "Delegate one task to an isolated Pi role with explicit extensions and skills.",
   "keywords": [
     "pi-package",
@@ -59,6 +59,6 @@
   "dependencies": {
     "@henryqw/pi-herdr": "^0.1.1",
     "@henryqw/pi-multi-codex": "^0.3.8",
-    "@henryqw/pi-task-models": "^0.5.0"
+    "@henryqw/pi-task-models": "^0.6.0"
   }
 }