@narumitw/pi-subagents 0.11.0 → 0.13.0

package/README.md

@@ -14,7 +14,7 @@ Use it to split research, planning, implementation, and review work across focus
 - Loads custom user agents from `~/.pi/agent/agents/*.md`.
 - Optionally loads project agents from `.pi/agents/*.md` with confirmation.
 - Provides `/subagents:config` to persist per-agent tool allow-lists.
-- Supports per-task `cwd`, hard subprocess `timeoutMs`, abort propagation, and streaming progress.
+- Supports per-task `cwd`, hard subprocess `timeoutMs`, `thinkingLevel`, abort propagation, and streaming progress.
 - Publishes transient runtime status through Pi's generic extension status API while subagents are running.
 - Returns complete worker output in tool details and a concise result for the main agent.
 
@@ -49,29 +49,50 @@ Execution modes:
 - **parallel + aggregator** — run parallel jobs, then pass all outputs into one fan-in agent.
 - **chain** — run sequential steps, passing prior output with `{previous}`.
 
+Common controls:
+
+- `cwd` — run a job from a different working directory.
+- `timeoutMs` — set a hard subprocess timeout.
+- `thinkingLevel` — request `off`, `minimal`, `low`, `medium`, `high`, or `xhigh` thinking for the spawned Pi process.
+
 ## 🧭 Proactive use
 
-The `subagent` tool now advertises concise prompt guidance so the main Pi agent can choose it
-without an explicit user request when delegation is a good fit.
+The `subagent` tool advertises concise prompt guidance so the main Pi agent can decide
+whether to spawn 0, 1, or multiple subagents without an explicit user-specified count.
+
+Count-selection guidance:
 
-Use `subagent` proactively for:
+- Use **no subagent** for simple answers, quick targeted edits, latency-sensitive one-step work, or
+  tasks that need frequent user back-and-forth.
+- Use **one subagent** for isolated research, high-volume command output, planning, or independent
+  review/verification after implementation.
+- Prefer **2–4 parallel read-only subagents** when a broad task naturally splits into independent
+  branches that can each return a concise summary.
+- Exceed 4 tasks only when the branches are clearly distinct and worth the extra cost, while staying
+  within the existing hard max of 8 parallel tasks.
+- Do not parallelize implementation that may edit the same files or shared state; serialize
+  write-heavy work instead.
+- Do not use project-local agents unless the user explicitly opts into them with
+  `agentScope: "project"` or `"both"`; keep confirmation enabled for untrusted repositories.
 
-- Independent read-only research, broad codebase reconnaissance, or high-volume command output
-  that would clutter the main context.
-- Parallel multi-domain investigation where each branch can return a concise summary.
-- Independent review or verification after implementation, especially with the read-only
-  `reviewer` agent.
+Examples where the main agent chooses the count:
 
-Do not use `subagent` for:
+No subagent for a known-file edit:
 
-- Simple answers, quick targeted edits, latency-sensitive one-step work, or tasks that need
-  frequent user back-and-forth.
-- Parallel implementation that may edit the same files or shared state; serialize write-heavy work
-  instead.
-- Project-local agents unless the user explicitly opts into them with `agentScope: "project"` or
-  `"both"`; keep confirmation enabled for untrusted repositories.
+```txt
+Rename one symbol in src/foo.ts.
+```
 
-Good delegation example:
+One subagent for an independent review:
+
+```json
+{
+  "agent": "reviewer",
+  "task": "Review the current changes for release blockers. Do not edit files. Report PASS/FAIL/PARTIAL with evidence."
+}
+```
+
+Two to four parallel subagents for broad independent reconnaissance:
 
 ```json
 {
@@ -83,6 +104,10 @@ Good delegation example:
     {
       "agent": "scout",
       "task": "Research auth-related tests. Report coverage gaps. Do not edit files."
+    },
+    {
+      "agent": "scout",
+      "task": "Research API entry points that depend on auth. Report integration risks. Do not edit files."
     }
   ],
   "aggregator": {
@@ -92,9 +117,6 @@ Good delegation example:
 }
 ```
 
-Bad delegation example: do not spawn a worker just to rename one symbol in a known file; edit it
-directly in the main conversation.
-
 ## 🚀 Examples
 
 Run one read-only reconnaissance agent:
@@ -106,7 +128,7 @@ Run one read-only reconnaissance agent:
 }
 ```
 
-Run multiple agents in parallel:
+Run multiple agents in parallel with a shared thinking level and one per-task override:
 
 ```json
 {
@@ -114,14 +136,16 @@ Run multiple agents in parallel:
     {
       "agent": "scout",
       "task": "Map package metadata files",
-      "timeoutMs": 30000
+      "timeoutMs": 30000,
+      "thinkingLevel": "low"
     },
     {
       "agent": "reviewer",
       "task": "Review TypeScript config consistency"
     }
   ],
-  "timeoutMs": 120000
+  "timeoutMs": 120000,
+  "thinkingLevel": "medium"
 }
 ```
 
@@ -196,6 +220,7 @@ name: api-reviewer
 description: Review API changes for compatibility and tests
 tools: read, grep, find, ls, bash
 model: sonnet
+thinkingLevel: high
 ---
 
 You are an API review subagent. Do not edit files. Check compatibility,
@@ -204,7 +229,7 @@ test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
 
 By default, `subagent` loads user agents only. Set `agentScope` to `"project"` or `"both"` to load project-local agents. Interactive sessions ask for confirmation before using project agents unless `confirmProjectAgents` is disabled.
 
-## ⏱️ Runtime limits
+## ⏱️ Runtime limits and thinking levels
 
 Each subprocess has a hard timeout to avoid runaway workers.
 
@@ -212,6 +237,10 @@ Each subprocess has a hard timeout to avoid runaway workers.
 - Set `timeoutMs` on a task, chain step, or aggregator to override it locally.
 - If omitted, the default is `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when unset.
 
+Set `thinkingLevel` to pass Pi's `--thinking <level>` to a subprocess. Supported values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`.
+
+Thinking-level precedence is: task/chain step/aggregator `thinkingLevel` → top-level `thinkingLevel` → agent default from config or frontmatter → Pi subprocess default. Omit `thinkingLevel` to preserve existing behavior. Pi still owns model capability clamping, so unsupported thinking levels are handled by the spawned Pi process.
+
 On timeout, the extension sends `SIGTERM`, escalates to `SIGKILL` after a short grace period, and returns any partial messages or stderr collected so far.
 
 ## 📡 Runtime status

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-subagents",
-	"version": "0.11.0",
+	"version": "0.13.0",
 	"description": "Pi extension for delegating work to specialized isolated subagents.",
 	"type": "module",
 	"license": "MIT",

package/src/agents.ts

@@ -4,8 +4,17 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh"] as const satisfies readonly ThinkingLevel[];
+
+export type SubagentThinkingLevel = (typeof THINKING_LEVELS)[number];
+
+export function isThinkingLevel(value: unknown): value is SubagentThinkingLevel {
+	return typeof value === "string" && THINKING_LEVELS.includes(value as SubagentThinkingLevel);
+}
+
 export type AgentScope = "user" | "project" | "both";
 
 export type AgentSource = "built-in" | "user" | "project";
@@ -15,6 +24,7 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	thinkingLevel?: SubagentThinkingLevel;
 	timeoutMs?: number;
 	systemPrompt: string;
 	source: AgentSource;
@@ -24,6 +34,7 @@ export interface AgentConfig {
 export interface SubagentAgentConfig {
 	tools?: string[];
 	model?: string | null;
+	thinkingLevel?: SubagentThinkingLevel | null;
 	timeoutMs?: number | null;
 }
 
@@ -146,6 +157,7 @@ function loadAgentsFromDir(dir: string, source: "user" | "project"): AgentConfig
 			description: frontmatter.description,
 			tools: tools && tools.length > 0 ? tools : undefined,
 			model: frontmatter.model,
+			thinkingLevel: isThinkingLevel(frontmatter.thinkingLevel) ? frontmatter.thinkingLevel : undefined,
 			systemPrompt: body,
 			source,
 			filePath,
@@ -217,6 +229,9 @@ export function discoverAgents(
 		if (hasOwn(override, "model")) {
 			nextAgent.model = override.model === null ? undefined : override.model;
 		}
+		if (hasOwn(override, "thinkingLevel")) {
+			nextAgent.thinkingLevel = override.thinkingLevel === null ? undefined : override.thinkingLevel;
+		}
 		if (hasOwn(override, "timeoutMs")) {
 			nextAgent.timeoutMs = override.timeoutMs === null ? undefined : override.timeoutMs;
 		}

package/src/subagents.ts

@@ -39,12 +39,15 @@ import {
 } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import {
+	THINKING_LEVELS,
 	type AgentConfig,
 	type AgentScope,
 	type AgentSource,
 	type SubagentAgentConfig,
 	type SubagentSettings,
+	type SubagentThinkingLevel,
 	discoverAgents,
+	isThinkingLevel,
 } from "./agents.js";
 
 const MAX_PARALLEL_TASKS = 8;
@@ -132,6 +135,7 @@ export function formatUsageStats(
 		turns?: number;
 	},
 	model?: string,
+	thinkingLevel?: SubagentThinkingLevel,
 ): string {
 	const parts: string[] = [];
 	if (usage.turns) parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
@@ -144,6 +148,7 @@ export function formatUsageStats(
 		parts.push(`ctx:${formatTokens(usage.contextTokens)}`);
 	}
 	if (model) parts.push(model);
+	if (thinkingLevel) parts.push(`thinking:${thinkingLevel}`);
 	return parts.join(" ");
 }
 
@@ -234,6 +239,7 @@ interface SingleResult {
 	stderr: string;
 	usage: UsageStats;
 	model?: string;
+	thinkingLevel?: SubagentThinkingLevel;
 	stopReason?: string;
 	errorMessage?: string;
 	step?: number;
@@ -326,6 +332,25 @@ async function writePromptToTempFile(agentName: string, prompt: string): Promise
 	return { dir: tmpDir, filePath };
 }
 
+export function buildPiArgs(options: {
+	model?: string;
+	thinkingLevel?: SubagentThinkingLevel;
+	tools?: string[];
+	systemPromptPath?: string;
+	task: string;
+}): string[] {
+	const args: string[] = ["--mode", "json", "-p", "--no-session"];
+	if (options.model) args.push("--model", options.model);
+	if (options.thinkingLevel) args.push("--thinking", options.thinkingLevel);
+	if (Array.isArray(options.tools)) {
+		if (options.tools.length > 0) args.push("--tools", options.tools.join(","));
+		else args.push("--no-tools");
+	}
+	if (options.systemPromptPath) args.push("--append-system-prompt", options.systemPromptPath);
+	args.push(`Task: ${options.task}`);
+	return args;
+}
+
 function getPiInvocation(args: string[]): { command: string; args: string[] } {
 	const currentScript = process.argv[1];
 	const isBunVirtualScript = currentScript?.startsWith("/$bunfs/root/");
@@ -378,6 +403,7 @@ async function runSingleAgent(
 	cwd: string | undefined,
 	step: number | undefined,
 	signal: AbortSignal | undefined,
+	thinkingLevel: SubagentThinkingLevel | undefined,
 	timeoutMs: number,
 	onUpdate: OnUpdateCallback | undefined,
 	makeDetails: (results: SingleResult[]) => SubagentDetails,
@@ -394,18 +420,12 @@ async function runSingleAgent(
 			messages: [],
 			stderr: `Unknown agent: "${agentName}". Available agents: ${available}.`,
 			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+			thinkingLevel,
 			step,
 			finalOutput: "",
 		};
 	}
 
-	const args: string[] = ["--mode", "json", "-p", "--no-session"];
-	if (agent.model) args.push("--model", agent.model);
-	if (Array.isArray(agent.tools)) {
-		if (agent.tools.length > 0) args.push("--tools", agent.tools.join(","));
-		else args.push("--no-tools");
-	}
-
 	let tmpPromptDir: string | null = null;
 	let tmpPromptPath: string | null = null;
 
@@ -418,6 +438,7 @@ async function runSingleAgent(
 		stderr: "",
 		usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 		model: agent.model ?? undefined,
+		thinkingLevel,
 		step,
 		timeoutMs,
 	};
@@ -437,10 +458,15 @@ async function runSingleAgent(
 			const tmp = await writePromptToTempFile(agent.name, agent.systemPrompt);
 			tmpPromptDir = tmp.dir;
 			tmpPromptPath = tmp.filePath;
-			args.push("--append-system-prompt", tmpPromptPath);
 		}
 
-		args.push(`Task: ${task}`);
+		const args = buildPiArgs({
+			model: agent.model,
+			thinkingLevel,
+			tools: agent.tools,
+			systemPromptPath: tmpPromptPath ?? undefined,
+			task,
+		});
 		let wasAborted = false;
 		let timedOut = false;
 
@@ -568,11 +594,16 @@ const TimeoutMs = Type.Number({
 	minimum: 1,
 });
 
+const ThinkingLevelSchema = StringEnum(THINKING_LEVELS, {
+	description: "Pi thinking level for the subagent process: off, minimal, low, medium, high, or xhigh.",
+});
+
 const TaskItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
 	task: Type.String({ description: "Task to delegate to the agent" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
 });
 
 const ChainItem = Type.Object({
@@ -580,6 +611,7 @@ const ChainItem = Type.Object({
 	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
 });
 
 const AggregatorItem = Type.Object({
@@ -587,6 +619,7 @@ const AggregatorItem = Type.Object({
 	task: Type.String({ description: "Fan-in task. Use {previous} to include all parallel outputs." }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the aggregator process" })),
 	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
 });
 
 const AgentScopeSchema = StringEnum(["user", "project", "both"] as const, {
@@ -606,6 +639,7 @@ const SubagentParams = Type.Object({
 	),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	timeoutMs: Type.Optional(TimeoutMs),
+	thinkingLevel: Type.Optional(ThinkingLevelSchema),
 });
 
 // ---- Settings helpers ----
@@ -644,6 +678,12 @@ export function normalizeAgentSettings(value: unknown): SubagentAgentConfig | un
 		hasKnownField = true;
 	}
 
+	if (hasOwn(value, "thinkingLevel")) {
+		if (value.thinkingLevel !== null && !isThinkingLevel(value.thinkingLevel)) return undefined;
+		config.thinkingLevel = value.thinkingLevel;
+		hasKnownField = true;
+	}
+
 	if (hasOwn(value, "timeoutMs")) {
 		if (value.timeoutMs !== null && !isPositiveNumber(value.timeoutMs)) return undefined;
 		config.timeoutMs = value.timeoutMs;
@@ -696,8 +736,22 @@ export function sameToolSet(left: string[], right: string[]): boolean {
 	return [...leftSet].every((tool) => rightSet.has(tool));
 }
 
+export function resolveSubagentThinkingLevel(
+	agents: readonly Pick<AgentConfig, "name" | "thinkingLevel">[],
+	agentName: string,
+	topLevelThinkingLevel?: SubagentThinkingLevel,
+	localThinkingLevel?: SubagentThinkingLevel,
+): SubagentThinkingLevel | undefined {
+	return localThinkingLevel ?? topLevelThinkingLevel ?? agents.find((agent) => agent.name === agentName)?.thinkingLevel;
+}
+
 function hasAnyAgentOverride(config: SubagentAgentConfig): boolean {
-	return hasOwn(config, "tools") || hasOwn(config, "model") || hasOwn(config, "timeoutMs");
+	return (
+		hasOwn(config, "tools") ||
+		hasOwn(config, "model") ||
+		hasOwn(config, "thinkingLevel") ||
+		hasOwn(config, "timeoutMs")
+	);
 }
 
 // ---- Tool toggle component ----
@@ -770,11 +824,14 @@ export default function (pi: ExtensionAPI) {
 			'To enable project-local agents in .pi/agents, set agentScope: "both" (or "project").',
 		].join(" "),
 		promptSnippet:
-			"Delegate independent research, review, verification, or multi-step work to isolated Pi subagents.",
+			"Decide whether to spawn 0, 1, or multiple subagents for independent research, review, verification, or multi-step work in isolated Pi processes.",
 		promptGuidelines: [
-			"Use subagent for independent read-only research, broad codebase reconnaissance, high-volume command output, multi-domain parallel investigation, or an independent reviewer after implementation.",
-			"Use subagent parallel mode when work splits into independent tasks; prefer read-only agents such as scout or reviewer for fan-out and serialize write-heavy implementation that touches the same files.",
-			"Do not use subagent for simple answers, quick targeted edits, latency-sensitive one-step work, or tasks requiring frequent user back-and-forth.",
+			"Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+			"Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, or tasks requiring frequent user back-and-forth.",
+			"Use one subagent for isolated research, broad command output, planning, or independent review/verification that benefits from a separate context.",
+			"Use subagent parallel mode with 2-4 parallel read-only subagents when work has broad independent branches; prefer scout or reviewer for fan-out and add an aggregator when synthesis helps.",
+			"Use more than 4 subagent tasks only when clearly justified by distinct independent branches, and stay within the existing hard max 8 parallel tasks.",
+			"Do not use subagent parallel mode for write-heavy implementation touching the same files or shared state; serialize those changes in the main agent or one worker.",
 			'Do not use subagent with project-local agents unless the user explicitly wants project agents or sets agentScope to "project" or "both"; keep confirmation enabled for untrusted repositories.',
 			"When using subagent, write self-contained tasks with file paths, context, expected output, and whether the subagent may edit files.",
 		],
@@ -791,6 +848,8 @@ export default function (pi: ExtensionAPI) {
 				params.timeoutMs ??
 				agents.find((agent) => agent.name === agentName)?.timeoutMs ??
 				DEFAULT_TIMEOUT_MS;
+			const resolveThinkingLevel = (agentName: string, localThinkingLevel?: SubagentThinkingLevel) =>
+				resolveSubagentThinkingLevel(agents, agentName, params.thinkingLevel, localThinkingLevel);
 
 			const hasChain = (params.chain?.length ?? 0) > 0;
 			const hasTasks = (params.tasks?.length ?? 0) > 0;
@@ -884,6 +943,7 @@ export default function (pi: ExtensionAPI) {
 							step.cwd,
 							i + 1,
 							signal,
+							resolveThinkingLevel(step.agent, step.thinkingLevel),
 							resolveTimeoutMs(step.agent, step.timeoutMs),
 							chainUpdate,
 							makeDetails("chain"),
@@ -939,6 +999,7 @@ export default function (pi: ExtensionAPI) {
 							messages: [],
 							stderr: "",
 							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+							thinkingLevel: resolveThinkingLevel(params.tasks[i].agent, params.tasks[i].thinkingLevel),
 							finalOutput: "",
 						};
 					}
@@ -970,6 +1031,7 @@ export default function (pi: ExtensionAPI) {
 							t.cwd,
 							undefined,
 							signal,
+							resolveThinkingLevel(t.agent, t.thinkingLevel),
 							resolveTimeoutMs(t.agent, t.timeoutMs),
 							// Per-task update callback
 							(partial) => {
@@ -1003,6 +1065,7 @@ export default function (pi: ExtensionAPI) {
 							aggregator.cwd,
 							undefined,
 							signal,
+							resolveThinkingLevel(aggregator.agent, aggregator.thinkingLevel),
 							resolveTimeoutMs(aggregator.agent, aggregator.timeoutMs),
 							(partial) => {
 								status.update(fanInStatus(aggregator.agent));
@@ -1060,6 +1123,7 @@ export default function (pi: ExtensionAPI) {
 						params.cwd,
 						undefined,
 						signal,
+						resolveThinkingLevel(params.agent, params.thinkingLevel),
 						resolveTimeoutMs(params.agent, params.timeoutMs),
 						onUpdate,
 						makeDetails("single"),
@@ -1203,7 +1267,7 @@ export default function (pi: ExtensionAPI) {
 							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
 						}
 					}
-					const usageStr = formatUsageStats(r.usage, r.model);
+					const usageStr = formatUsageStats(r.usage, r.model, r.thinkingLevel);
 					if (usageStr) {
 						container.addChild(new Spacer(1));
 						container.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
@@ -1219,7 +1283,7 @@ export default function (pi: ExtensionAPI) {
 					text += `\n${renderDisplayItems(displayItems, COLLAPSED_ITEM_COUNT)}`;
 					if (displayItems.length > COLLAPSED_ITEM_COUNT) text += `\n${theme.fg("muted", "(Ctrl+O to expand)")}`;
 				}
-				const usageStr = formatUsageStats(r.usage, r.model);
+				const usageStr = formatUsageStats(r.usage, r.model, r.thinkingLevel);
 				if (usageStr) text += `\n${theme.fg("dim", usageStr)}`;
 				return new Text(text, 0, 0);
 			}
@@ -1288,7 +1352,7 @@ export default function (pi: ExtensionAPI) {
 							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
 						}
 
-						const stepUsage = formatUsageStats(r.usage, r.model);
+						const stepUsage = formatUsageStats(r.usage, r.model, r.thinkingLevel);
 						if (stepUsage) container.addChild(new Text(theme.fg("dim", stepUsage), 0, 0));
 					}
 
@@ -1380,7 +1444,7 @@ export default function (pi: ExtensionAPI) {
 							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
 						}
 
-						const taskUsage = formatUsageStats(r.usage, r.model);
+						const taskUsage = formatUsageStats(r.usage, r.model, r.thinkingLevel);
 						if (taskUsage) container.addChild(new Text(theme.fg("dim", taskUsage), 0, 0));
 					}
 
@@ -1413,7 +1477,7 @@ export default function (pi: ExtensionAPI) {
 							container.addChild(new Spacer(1));
 							container.addChild(new Markdown(finalOutput.trim(), 0, 0, mdTheme));
 						}
-						const fanInUsage = formatUsageStats(aggregator.usage, aggregator.model);
+						const fanInUsage = formatUsageStats(aggregator.usage, aggregator.model, aggregator.thinkingLevel);
 						if (fanInUsage) container.addChild(new Text(theme.fg("dim", fanInUsage), 0, 0));
 					}