@ferris1225/pi-subagents 0.9.0 → 0.10.0

package/README.md

@@ -21,8 +21,8 @@ agent, and keep the workflow moving without manual polling.
 - **Parallel fan-out** — run independent tasks together, with a bounded background queue.
 - **Live progress** — a TUI widget shows each agent's status, activity, model, usage, and
   elapsed time; completion also produces a concise notification.
-- **Per-agent configuration** — enable agents, select models, set thinking strength, tune
-  concurrency limits, and choose discovery scope from `/subagents-setup`.
+- **Per-agent configuration** — enable agents, pick model and thinking strength per agent,
+  tune concurrency limits, and choose discovery scope from `/subagents-setup`.
 - **Leaf processes** — child agents cannot access the `subagent` tool, so delegation cannot
   recurse.
 
@@ -122,13 +122,25 @@ Start dependent work after the relevant result has been delivered to the main ag
 Configuration is stored at `~/.pi/agent/pi-subagents.json`. The location follows
 `PI_CODING_AGENT_DIR` when set.
 
+The `/subagents-setup` wizard drives the main fields interactively: for each agent, picking a
+model is immediately followed by picking that agent's thinking strength (or inheriting the
+agent's default — its frontmatter `thinking`, else the global default). The global
+`thinkingLevel` is set first and applies as the final fallback. `notifyOnReviewPass` and
+`maxResultLines` are edited directly in `pi-subagents.json`.
+
 ```json
 {
   "enabledAgents": ["explore", "worker", "reviewer"],
   "agentModels": {
     "explore": "anthropic/claude-haiku-4-5"
   },
-  "thinkingLevel": "max",
+  "agentThinkingLevels": {
+    "explore": "low",
+    "worker": "high"
+  },
+  "thinkingLevel": "high",
+  "notifyOnReviewPass": false,
+  "maxResultLines": 80,
   "proactiveInjection": true,
   "agentScope": "user",
   "maxConcurrency": 4,
@@ -141,7 +153,10 @@ Configuration is stored at `~/.pi/agent/pi-subagents.json`. The location follows
 | --- | --- |
 | `enabledAgents` | Agent names exposed to discovery and prompt injection. An empty array disables all agents. |
 | `agentModels` | Optional `provider/model-id` override per agent. |
-| `thinkingLevel` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. |
+| `agentThinkingLevels` | Optional thinking level per agent; agents without an entry use the agent's frontmatter `thinking`, then `thinkingLevel`. |
+| `thinkingLevel` | Default thinking level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` (default `high`). |
+| `notifyOnReviewPass` | When `true`, a passing reviewer result is delivered without waking the main agent (default `false`). |
+| `maxResultLines` | Max lines of a sub-agent result carried in the completion message (default `80`). Longer results are truncated; the full text is written to a temp file whose path is included in the message. |
 | `proactiveInjection` | Whether to add the delegation directive to the main system prompt. |
 | `agentScope` | `user`, `project`, or `both`; controls which user/project agent directories are discovered. |
 | `maxConcurrency` | How many sub-agent processes run at once (1–16, default 4). Extra work waits in the queue. |
@@ -155,7 +170,7 @@ The config file migrates itself on load — no manual steps after an upgrade:
 - **Schema upgrades** — a config written by an older version (missing newer keys or
   holding invalid values) is normalized and saved back with the new fields filled in.
 - **Removed agents** — agents no longer shipped (e.g. the old `plan` agent) are stripped
-  from `enabledAgents` and `agentModels` automatically.
+  from `enabledAgents`, `agentModels`, and `agentThinkingLevels` automatically.
 
 Model selection uses this precedence:
 
@@ -166,6 +181,8 @@ configured agent model → current main-session model → agent frontmatter mode
 Unavailable configured models are replaced with a usable current-session model when possible
 and the repaired configuration is saved.
 
+Thinking strength uses this precedence: `agentThinkingLevels` entry → agent frontmatter `thinking` → `thinkingLevel` default.
+
 ## Agent discovery and overrides
 
 - Built-in agents are shipped with the package.
@@ -176,6 +193,10 @@ and the repaired configuration is saved.
 Use a matching Markdown filename and `name` field to replace a built-in agent. Keep the task
 brief explicit: include the goal, relevant paths, constraints, and expected handoff.
 
+Optional frontmatter fields: `model` (default model reference) and `thinking` (default
+thinking strength). Both are overridden by `agentModels` / `agentThinkingLevels` in
+`pi-subagents.json` when set.
+
 ## Development
 
 ```bash

package/agents/explore.md

@@ -3,6 +3,7 @@ name: explore
 description: Fast read-only codebase reconnaissance. Use PROACTIVELY for broad or open-ended search — locating files/symbols, answering "where is X defined / which files reference Y", multi-file concept lookups, or mapping unfamiliar code before a change. Returns compressed, structured findings so the caller does not re-read everything.
 tools: read, grep, find, ls, bash
 model: claude-haiku-4-5
+thinking: low
 # Model selection: SPEED over depth. Pick the fastest available model.
 # What matters: fast grep/find/read, structured output. What doesn't: deep reasoning.
 ---

package/agents/reviewer.md

@@ -1,45 +1,63 @@
----
-name: reviewer
-description: Adversarial code reviewer and pre-commit quality gate. Use PROACTIVELY before reporting work done or committing — reviews a diff or a set of changed files for correctness, security, concurrency/unsafe-FFI, encoding/Unicode boundaries, and convention violations. Runs in a separate context from the worker to avoid self-confirmation bias. Read-only; never edits, builds, or runs tests.
-tools: read, grep, find, ls, bash
-model: claude-sonnet-4-5
-# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
-# use the strongest available reasoning model.
----
-
-You are a senior, adversarial code reviewer. Your job is to FIND WHAT IS WRONG, not to validate. Assume the author's summary describes intent, not outcome — verify against the actual code. You run in a separate context from the worker on purpose, so you bring no bias toward the change. You have NOT got the caller's conversation history.
-
-## Hard constraints
-- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
-- Bash is for read-only commands only: `git diff`, `git status`, `git log`, `git show`, `grep`, `find`, `cat`.
-- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
-
-## When invoked
-1. Run `git diff` and `git status` to see the recent changes. If a specific file set was given, read those files.
-2. Read the modified files in full where needed; judge the change in the context of the surrounding code.
-3. Hunt across these categories:
-   - Logic bugs, off-by-one, wrong edge-case handling.
-   - Error handling gaps; swallowed failures; unreported unrun checks.
-   - Security: injection, path traversal, secrets in code/logs, trusting untrusted input.
-   - Concurrency: shared mutable state, locks held across await, races.
-   - Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
-   - Resource leaks; violations of the project's stated conventions.
-4. Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
-
-## Collaboration
-- Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
-
-## Output format
-## Files Reviewed
-- `path/to/file.ts`
-## Critical (must fix)
-- `file.ts:42` — concrete issue and why it breaks.
-## Warnings (should fix)
-- `file.ts:10` — issue and suggested direction.
-## Suggestions (consider)
-- Optional improvements.
-## Verdict
-One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
-
-## Quality standards
-Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.
+---
+name: reviewer
+description: Adversarial code reviewer and pre-commit quality gate. Use PROACTIVELY before reporting work done or committing — reviews a diff or a set of changed files for correctness, security, concurrency/unsafe-FFI, encoding/Unicode boundaries, and convention violations. Runs in a separate context from the worker to avoid self-confirmation bias. Read-only; never edits, builds, or runs tests. Also handles plans, proposed solutions, codebase health, and PR/issue validation when the brief asks.
+tools: read, grep, find, ls, bash
+model: claude-sonnet-4-5
+thinking: high
+# Model selection: ATTENTION TO DETAIL + SECURITY AWARENESS. This is the quality gate —
+# use the strongest available reasoning model.
+---
+
+You are a senior, adversarial code reviewer. Your job is to FIND WHAT IS WRONG, not to validate. Assume the author's summary describes intent, not outcome — verify against the actual code. You run in a separate context from the worker on purpose, so you bring no bias toward the change. You have NOT got the caller's conversation history.
+
+## Hard constraints
+- You are READ-ONLY. Do NOT modify files, run builds, or run tests.
+- Bash is for read-only commands only: `git diff`, `git status`, `git log`, `git show`, `grep`, `find`, `cat`.
+- Assume tool permissions are not perfectly enforceable; keep every command strictly read-only by intent.
+
+## Review types you handle
+Match the type to the task brief; the hunt checklist below applies to every type.
+
+### 1. Code diffs (default)
+1. Run `git diff` and `git status` to see the recent changes. If a specific file set was given, read those files.
+2. Read the modified files in full where needed; judge the change in the context of the surrounding code.
+
+### 2. Plans
+Validate a proposed plan for feasibility and completeness: missing steps, hidden risks, alignment with the existing architecture, and whether the scope is appropriately bounded.
+
+### 3. Proposed solutions
+Evaluate a suggested approach: correctness and tradeoffs, fit with existing codebase patterns, simpler alternatives, edge cases the proposal may miss.
+
+### 4. Codebase health
+Assess key files, tests, and structure: architecture drift or tech debt, inconsistent patterns, untested or undocumented areas, obvious bugs, fragile code.
+
+### 5. Specific PR or issue
+Understand the context first, then verify: the fix addresses the root cause, changes are minimal and focused, no regressions, tests and docs updated as needed.
+
+## Hunt across these categories
+- Logic bugs, off-by-one, wrong edge-case handling.
+- Error handling gaps; swallowed failures; unreported unrun checks.
+- Security: injection, path traversal, secrets in code/logs, trusting untrusted input.
+- Concurrency: shared mutable state, locks held across await, races.
+- Encoding/Unicode: assuming `char*`/files/CLI text is UTF-8; wrong `A` vs `W` Win32 APIs; boundary conversions.
+- Resource leaks; violations of the project's stated conventions.
+- Classify severity honestly. Distinguish blockers from nits; do not pad with style preferences.
+
+## Collaboration
+- Independent of `worker` by design — your verdict is the gate before commit. Fix nothing yourself; report so the caller can dispatch a worker.
+
+## Output format
+## Files Reviewed
+- `path/to/file.ts`
+## Critical (must fix)
+- `file.ts:42` — concrete issue and why it breaks.
+## Warnings (should fix)
+- `file.ts:10` — issue and suggested direction.
+## Suggestions (consider)
+- Optional improvements.
+## Verdict
+One of: APPROVE / APPROVE_WITH_NITS / REQUEST_CHANGES, plus a 2-3 sentence rationale.
+End with exactly one machine-readable line: `VERDICT: REVIEW_PASS` for APPROVE or APPROVE_WITH_NITS; `VERDICT: REVIEW_FAIL` for REQUEST_CHANGES.
+
+## Quality standards
+Specific file paths and line numbers. No vague feedback. A clean report means you looked hard, not that you found nothing to say.

package/agents/worker.md

@@ -2,6 +2,7 @@
 name: worker
 description: General-purpose implementation agent with full tools in an isolated context. Use PROACTIVELY to execute a well-scoped, self-contained coding task — implement, fix, refactor, or add tests — without polluting the main conversation. Plans internally, then implements and verifies. Give it a complete, self-contained brief.
 model: claude-sonnet-4-5
+thinking: high
 # Model selection: CODING ABILITY + TOOL USE. The primary implementation model —
 # balance quality against cost. No `tools` field => inherits all tools (full capability).
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/agents.ts

@@ -15,7 +15,7 @@ import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from "no
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
-import type { AgentScope } from "./config.ts";
+import { THINKING_LEVEL_VALUES, type AgentScope, type ThinkingLevel } from "./config.ts";
 
 export type AgentSource = "builtin" | "user" | "project";
 
@@ -24,6 +24,8 @@ export interface AgentConfig {
 	description: string;
 	tools?: string[];
 	model?: string;
+	/** Per-agent default thinking strength (frontmatter `thinking`); config override wins. */
+	thinking?: ThinkingLevel;
 	systemPrompt: string;
 	source: AgentSource;
 	filePath: string;
@@ -38,6 +40,11 @@ const here = dirname(fileURLToPath(import.meta.url));
 /** <package>/agents — the agents shipped with this extension. */
 export const BUILTIN_AGENTS_DIR = join(here, "..", "agents");
 
+/** Agents shipped with the package (used by the setup wizard for per-agent defaults). */
+export function loadBuiltinAgents(): AgentConfig[] {
+	return loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
+}
+
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 	if (!existsSync(dir)) return agents;
@@ -62,19 +69,29 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		}
 
 		const { frontmatter, body } = parseFrontmatter<Record<string, string>>(content);
+		// YAML values are not guaranteed strings; anything non-string is invalid for these fields.
+		const str = (value: unknown): string | undefined => (typeof value === "string" ? value : undefined);
+		const name = str(frontmatter.name);
+		const description = str(frontmatter.description);
 		// name + description are required; skip malformed files silently.
-		if (!frontmatter.name || !frontmatter.description) continue;
+		if (!name || !description) continue;
 
-		const tools = frontmatter.tools
+		const rawTools = str(frontmatter.tools);
+		const tools = rawTools
 			?.split(",")
 			.map((t) => t.trim())
 			.filter(Boolean);
+		const rawThinking = str(frontmatter.thinking)?.trim();
+		const thinking = (THINKING_LEVEL_VALUES as readonly string[]).includes(rawThinking ?? "")
+			? (rawThinking as ThinkingLevel)
+			: undefined;
 
 		agents.push({
-			name: frontmatter.name,
-			description: frontmatter.description,
+			name,
+			description,
 			tools: tools && tools.length > 0 ? tools : undefined,
-			model: frontmatter.model,
+			model: str(frontmatter.model),
+			...(thinking ? { thinking } : {}),
 			systemPrompt: body,
 			source,
 			filePath,

package/src/completion.ts

@@ -0,0 +1,153 @@
+/**
+ * Smart batching for successful background completions.
+ *
+ * A short debounce coalesces sibling runs while a max-wait timer, measured from
+ * the first item in the open group, bounds delivery latency. Runs that finish
+ * shortly after an emitted group use a smaller straggler window. Failures are
+ * intentionally handled by the caller: flush held successes, then emit the
+ * failure directly so it is never delayed.
+ */
+
+import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+
+export interface CompletionBatchTimings {
+	debounceMs: number;
+	maxWaitMs: number;
+	stragglerDebounceMs: number;
+	stragglerMaxWaitMs: number;
+	stragglerWindowMs: number;
+}
+
+export const DEFAULT_COMPLETION_BATCH_TIMINGS: CompletionBatchTimings = {
+	debounceMs: 150,
+	maxWaitMs: 1_000,
+	stragglerDebounceMs: 75,
+	stragglerMaxWaitMs: 400,
+	stragglerWindowMs: 2_000,
+};
+
+type TimerHandle = unknown;
+
+export interface TimerApi {
+	setTimeout(handler: () => void, delayMs: number): TimerHandle;
+	clearTimeout(handle: TimerHandle): void;
+}
+
+const defaultTimers: TimerApi = {
+	setTimeout: (handler, delayMs) => setTimeout(handler, delayMs),
+	clearTimeout: (handle) => clearTimeout(handle as ReturnType<typeof setTimeout>),
+};
+
+function unrefHandle(handle: TimerHandle): void {
+	if (
+		handle &&
+		typeof handle === "object" &&
+		"unref" in handle &&
+		typeof (handle as { unref: unknown }).unref === "function"
+	) {
+		(handle as { unref: () => void }).unref();
+	}
+}
+
+export interface CompletionBatcherOptions<T> {
+	emit: (items: T[]) => void;
+	timings?: Partial<CompletionBatchTimings>;
+	timers?: TimerApi;
+	now?: () => number;
+}
+
+export interface CompletionBatcher<T> {
+	/** Add an item to the current debounced group. */
+	push(item: T): void;
+	/** Emit any held items immediately as one group. */
+	flush(): void;
+	/** Clear timers and return held items without emitting them. */
+	dispose(): T[];
+}
+
+export function createCompletionBatcher<T>(options: CompletionBatcherOptions<T>): CompletionBatcher<T> {
+	const timers = options.timers ?? defaultTimers;
+	const now = options.now ?? Date.now;
+	const timings = { ...DEFAULT_COMPLETION_BATCH_TIMINGS, ...options.timings };
+	let pending: T[] = [];
+	let debounceTimer: TimerHandle | null = null;
+	let maxWaitTimer: TimerHandle | null = null;
+	let straggler = false;
+	let lastEmitAt: number | null = null;
+
+	const clearTimers = (): void => {
+		if (debounceTimer !== null) {
+			timers.clearTimeout(debounceTimer);
+			debounceTimer = null;
+		}
+		if (maxWaitTimer !== null) {
+			timers.clearTimeout(maxWaitTimer);
+			maxWaitTimer = null;
+		}
+	};
+
+	const emitGroup = (): void => {
+		clearTimers();
+		if (pending.length === 0) return;
+		const items = pending;
+		pending = [];
+		lastEmitAt = now();
+		options.emit(items);
+	};
+
+	return {
+		push(item: T): void {
+			if (pending.length === 0) {
+				straggler = lastEmitAt !== null && now() - lastEmitAt < timings.stragglerWindowMs;
+			}
+			pending.push(item);
+
+			if (debounceTimer !== null) timers.clearTimeout(debounceTimer);
+			const debounceDelay = straggler ? timings.stragglerDebounceMs : timings.debounceMs;
+			debounceTimer = timers.setTimeout(emitGroup, debounceDelay);
+			unrefHandle(debounceTimer);
+
+			if (maxWaitTimer === null) {
+				const maxWaitDelay = straggler ? timings.stragglerMaxWaitMs : timings.maxWaitMs;
+				maxWaitTimer = timers.setTimeout(emitGroup, maxWaitDelay);
+				unrefHandle(maxWaitTimer);
+			}
+		},
+		flush: emitGroup,
+		dispose(): T[] {
+			clearTimers();
+			const abandoned = pending;
+			pending = [];
+			return abandoned;
+		},
+	};
+}
+
+export interface CompletionMessageItem {
+	agent: string;
+	block: string;
+	triggerTurn: boolean;
+}
+
+/** Keep the established single-result shape; add a summary only for real groups. */
+export function formatCompletionMessage(items: readonly CompletionMessageItem[]): string {
+	if (items.length === 0) return "";
+	if (items.length === 1) return items[0].block;
+	const agents = items.map((item) => item.agent).join(", ");
+	return `### Subagents completed (${items.length}): ${agents}\n\n${items.map((item) => item.block).join("\n\n")}`;
+}
+
+/** A grouped completion wakes the main agent when any member requires a turn. */
+export function completionGroupTriggersTurn(items: readonly CompletionMessageItem[]): boolean {
+	return items.some((item) => item.triggerTurn);
+}
+
+/** Passing reviewer notifications may opt out of waking; every other result wakes. */
+export function completionTriggersTurn(result: SingleResult, notifyOnReviewPass: boolean): boolean {
+	if (isFailedResult(result)) return true;
+	return !(
+		notifyOnReviewPass &&
+		result.agent === "reviewer" &&
+		reviewVerdict(getResultOutput(result)) === "pass"
+	);
+}

package/src/config.ts

@@ -36,7 +36,12 @@ export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 /** Thinking levels accepted by pi's `--thinking` option. */
 export const THINKING_LEVEL_VALUES = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = (typeof THINKING_LEVEL_VALUES)[number];
-export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "max";
+export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "high";
+
+/** How many lines of a sub-agent result the completion message may carry. Default: 80. */
+export const DEFAULT_MAX_RESULT_LINES = 80;
+/** Upper bound accepted for maxResultLines (defensive clamp). */
+export const MAX_RESULT_LINES_LIMIT = 2000;
 
 export const CONFIG_FILE_NAME = "pi-subagents.json";
 
@@ -61,8 +66,21 @@ export interface SubagentsConfig {
 	enabledAgents: string[];
 	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
 	agentModels: Record<string, string>;
-	/** Thinking level passed to every sub-agent. Default: "max". */
+	/** Per-agent thinking-level override, keyed by agent name. */
+	agentThinkingLevels: Record<string, ThinkingLevel>;
+	/** Thinking level for sub-agents without a per-agent override or frontmatter default. Default: "high". */
 	thinkingLevel: ThinkingLevel;
+	/**
+	 * When a review passes (REVIEW_PASS verdict), deliver it without waking the
+	 * main agent. Disabled by default so passing reviews still resume orchestration.
+	 */
+	notifyOnReviewPass: boolean;
+	/**
+	 * Max lines of a sub-agent result carried in the completion message. Longer
+	 * results are truncated; the full text is written to a temp file whose path
+	 * is included in the message. Default: 80.
+	 */
+	maxResultLines: number;
 	/** Whether to inject the delegation directive into the parent system prompt. Default: true. */
 	proactiveInjection: boolean;
 	/** Which agent directories to discover from. Default: "user". */
@@ -78,7 +96,10 @@ export interface SubagentsConfig {
 export const DEFAULT_CONFIG: SubagentsConfig = {
 	enabledAgents: [...DEFAULT_ENABLED_AGENTS],
 	agentModels: {},
+	agentThinkingLevels: {},
 	thinkingLevel: DEFAULT_THINKING_LEVEL,
+	notifyOnReviewPass: false,
+	maxResultLines: DEFAULT_MAX_RESULT_LINES,
 	proactiveInjection: true,
 	agentScope: "user",
 	maxConcurrency: DEFAULT_MAX_CONCURRENCY,
@@ -121,7 +142,10 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 	const config: SubagentsConfig = {
 		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
 		agentModels: {},
+		agentThinkingLevels: {},
 		thinkingLevel: DEFAULT_CONFIG.thinkingLevel,
+		notifyOnReviewPass: DEFAULT_CONFIG.notifyOnReviewPass,
+		maxResultLines: DEFAULT_CONFIG.maxResultLines,
 		proactiveInjection: DEFAULT_CONFIG.proactiveInjection,
 		agentScope: DEFAULT_CONFIG.agentScope,
 		maxConcurrency: DEFAULT_CONFIG.maxConcurrency,
@@ -147,10 +171,29 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		}
 	}
 
+	if (isRecord(raw.agentThinkingLevels)) {
+		for (const [key, value] of Object.entries(raw.agentThinkingLevels)) {
+			if (REMOVED_AGENT_NAMES.includes(key.trim())) continue;
+			if (
+				typeof value === "string" &&
+				(THINKING_LEVEL_VALUES as readonly string[]).includes(value)
+			) {
+				config.agentThinkingLevels[key.trim()] = value as ThinkingLevel;
+			}
+		}
+	}
+
 	if (typeof raw.thinkingLevel === "string" && (THINKING_LEVEL_VALUES as readonly string[]).includes(raw.thinkingLevel)) {
 		config.thinkingLevel = raw.thinkingLevel as ThinkingLevel;
 	}
 
+	if (typeof raw.notifyOnReviewPass === "boolean") {
+		config.notifyOnReviewPass = raw.notifyOnReviewPass;
+	}
+
+	const maxResultLines = clampCount(raw.maxResultLines, MAX_RESULT_LINES_LIMIT);
+	if (maxResultLines !== undefined) config.maxResultLines = maxResultLines;
+
 	if (typeof raw.proactiveInjection === "boolean") {
 		config.proactiveInjection = raw.proactiveInjection;
 	}
@@ -174,7 +217,12 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 }
 
 function defaultConfig(): SubagentsConfig {
-	return { ...DEFAULT_CONFIG, enabledAgents: [...DEFAULT_CONFIG.enabledAgents], agentModels: {} };
+	return {
+		...DEFAULT_CONFIG,
+		enabledAgents: [...DEFAULT_CONFIG.enabledAgents],
+		agentModels: {},
+		agentThinkingLevels: {},
+	};
 }
 
 /**

package/src/index.ts

@@ -18,6 +18,13 @@ import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { discoverAgents, type AgentConfig } from "./agents.ts";
 import { BackgroundTaskQueue } from "./background.ts";
+import {
+	completionGroupTriggersTurn,
+	completionTriggersTurn,
+	createCompletionBatcher,
+	formatCompletionMessage,
+	type CompletionMessageItem,
+} from "./completion.ts";
 import { getConfigPath, loadConfig, loadConfigSync, saveConfig } from "./config.ts";
 import { repairUnavailableModelOverrides } from "./models.ts";
 import { buildDelegationDirective } from "./prompt.ts";
@@ -28,6 +35,8 @@ import {
 	getResultOutput,
 	isFailedResult,
 	runSingleAgent,
+	truncateResultOutput,
+	writeResultArtifact,
 	type SingleResult,
 	type SubagentDetails,
 	type SubagentLiveEvent,
@@ -59,7 +68,7 @@ function emptyUsage(): UsageStats {
 	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 };
 }
 
-function queuedResult(agent: AgentConfig, task: string): SingleResult {
+function queuedResult(agent: AgentConfig, task: string, thinking?: string): SingleResult {
 	return {
 		agent: agent.name,
 		agentSource: agent.source,
@@ -69,6 +78,7 @@ function queuedResult(agent: AgentConfig, task: string): SingleResult {
 		stderr: "",
 		usage: emptyUsage(),
 		model: agent.model,
+		...(thinking ? { thinking } : {}),
 	};
 }
 
@@ -114,6 +124,19 @@ function formatUsage(usage: UsageStats): string {
 	return parts.join(" ");
 }
 
+function formatCompletionBlock(result: SingleResult, maxResultLines: number): string {
+	const status = isFailedResult(result) ? "failed" : "completed";
+	const usage = formatUsage(result.usage);
+	const output = getResultOutput(result);
+	const { text, truncated } = truncateResultOutput(output, maxResultLines);
+	const lines = [`### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}`, "", `Task: ${formatTaskSummary(result.task)}`, "", text];
+	if (truncated) {
+		// The full text lives on disk so the main agent can read it on demand.
+		lines.push("", `(output truncated to ${maxResultLines} lines; full result: ${writeResultArtifact(output, result.agent)})`);
+	}
+	return lines.join("\n");
+}
+
 export default function (pi: ExtensionAPI): void {
 	const configPath = getConfigPath(getAgentDir());
 	// Init-time decisions need the config synchronously; the full (migrating)
@@ -121,6 +144,23 @@ export default function (pi: ExtensionAPI): void {
 	const initialConfig = loadConfigSync(configPath);
 	const backgroundQueue = new BackgroundTaskQueue(initialConfig.maxConcurrency);
 	let sessionActive = true;
+	const sendCompletionGroup = (items: CompletionMessageItem[]): void => {
+		if (!sessionActive || items.length === 0) return;
+		const message = {
+			customType: "subagent-result",
+			content: formatCompletionMessage(items),
+			display: true,
+		};
+		if (completionGroupTriggersTurn(items)) {
+			pi.sendMessage(message, { deliverAs: "followUp", triggerTurn: true });
+		} else {
+			// No-wake delivery: nextTurn rides along with the next user turn and can
+			// never start a continuation by itself. followUp would auto-continue
+			// whenever pi is already streaming, defeating the opt-out.
+			pi.sendMessage(message, { deliverAs: "nextTurn" });
+		}
+	};
+	const completionBatcher = createCompletionBatcher<CompletionMessageItem>({ emit: sendCompletionGroup });
 
 	// Recursion guard: sub-agents at the configured depth are leaf processes and
 	// cannot delegate again. maxSubagentDepth 0 disables the tool entirely.
@@ -148,6 +188,7 @@ export default function (pi: ExtensionAPI): void {
 
 	pi.on("session_shutdown", () => {
 		sessionActive = false;
+		completionBatcher.dispose();
 		backgroundQueue.cancelAll();
 	});
 
@@ -162,11 +203,11 @@ export default function (pi: ExtensionAPI): void {
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output)."
 		].join(" "),
 		promptSnippet:
-			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent.",
+			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
 		promptGuidelines: [
-			"Use subagent to delegate discrete, self-contained tasks so the main context stays clean; do orchestration and verification yourself.",
-			"Use subagent with agent 'explore' for broad or open-ended code search before large changes.",
-			"Use subagent with agent 'worker' to implement a well-scoped task; it plans internally.",
+			"Delegate only when an isolated context genuinely pays: broad exploration, a self-contained implementation, or a review gate. Handle simple lookups and one-line edits inline with direct tools — never spawn a sub-agent for them.",
+			"Use subagent with agent 'explore' for broad or open-ended code search before large changes; a targeted 'where is X' is a direct grep/read.",
+			"Use subagent with agent 'worker' for a self-contained implementation task worth a separate context; it plans internally.",
 			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
 			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
 			"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
@@ -296,8 +337,10 @@ export default function (pi: ExtensionAPI): void {
 				const agent = agents.find((candidate) => candidate.name === agentName);
 				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 
-				const pending = queuedResult(agent, task);
-				const runId = monitor.addRun(agent.name, task, agent.model);
+				// Effective strength: config override > agent frontmatter default > global default.
+				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
+				const pending = queuedResult(agent, task, thinkingLevel);
+				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel);
 				const onLive = makeLiveHandler(runId);
 
 				backgroundQueue.enqueue(
@@ -310,7 +353,7 @@ export default function (pi: ExtensionAPI): void {
 								agentName,
 								task,
 								cwd,
-								thinkingLevel: config.thinkingLevel,
+								thinkingLevel,
 								signal: backgroundSignal,
 								onLive,
 								makeDetails: makeDetails("single", true),
@@ -328,18 +371,20 @@ export default function (pi: ExtensionAPI): void {
 						}
 
 						if (!sessionActive) return;
-						const status = isFailedResult(result) ? "failed" : "completed";
-						const usage = formatUsage(result.usage);
-						pi.sendMessage(
-							{
-								customType: "subagent-result",
-								content: `### [${result.agent}] ${status}${usage ? ` (${usage})` : ""}\n\nTask: ${formatTaskSummary(result.task)}\n\n${getResultOutput(result)}`,
-								display: true,
-							},
-							// The result is both durable context and a wake-up signal. If the
-							// main agent is busy, followUp queues it until the current turn ends.
-							{ deliverAs: "followUp", triggerTurn: true },
-						);
+						const failed = isFailedResult(result);
+						const completion: CompletionMessageItem = {
+							agent: result.agent,
+							block: formatCompletionBlock(result, config.maxResultLines),
+							triggerTurn: completionTriggersTurn(result, config.notifyOnReviewPass),
+						};
+						if (failed) {
+							// Failures never wait and never hide behind a success turn: deliver
+							// first so the wake-up leads with the failure; held successes follow.
+							sendCompletionGroup([completion]);
+							completionBatcher.flush();
+						} else {
+							completionBatcher.push(completion);
+						}
 					},
 					() => finishRun(runId, "failed"),
 				);
@@ -426,7 +471,7 @@ export default function (pi: ExtensionAPI): void {
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
 				const model = r.model ?? "?";
-				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
+				const line = `${theme.fg("toolTitle", theme.bold("subagent "))}${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`;
 				return new Text(line, 0, 0);
 			}
 
@@ -439,7 +484,7 @@ export default function (pi: ExtensionAPI): void {
 				const icon = statusIcon(pending ? "running" : isFailedResult(r) ? "failed" : "done", theme);
 				const usage = formatUsage(r.usage);
 				const model = r.model ?? "?";
-				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
+				lines.push(`  ${icon} ${theme.fg("accent", r.agent)} ${theme.fg("dim", `· ${model}${r.thinking ? ` · thinking ${r.thinking}` : ""}${pending ? " · background" : ""}${usage ? ` · ${usage}` : ""}`)}`);
 			}
 			return new Text(lines.join("\n"), 0, 0);
 		},

package/src/monitor.ts

@@ -26,6 +26,8 @@ export interface RunView {
 	agent: string;
 	task: string;
 	model?: string;
+	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
+	thinking?: string;
 	status: RunStatus;
 	usage: UsageStats;
 	/** Concise current activity ("thinking", "read src/index.ts"); last writer wins. */
@@ -166,13 +168,14 @@ export class MonitorStore {
 		this.notify();
 	}
 
-	addRun(agent: string, task: string, model?: string): number {
+	addRun(agent: string, task: string, model?: string, thinking?: string): number {
 		const id = this.nextId++;
 		this.runs.push({
 			id,
 			agent,
 			task,
 			model,
+			thinking,
 			status: "queued",
 			usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
 		});
@@ -231,6 +234,7 @@ export class MonitorStore {
 		const usage = formatUsageCompact(run.usage);
 		const parts = [run.agent];
 		if (run.model) parts.push(run.model);
+		if (run.thinking) parts.push(`thinking ${run.thinking}`);
 		if (usage) parts.push(usage);
 		const elapsed = formatElapsed(run);
 		if (elapsed) parts.push(elapsed);

package/src/prompt.ts

@@ -16,8 +16,8 @@ import { formatCatalogEntry } from "./agents.ts";
 
 /** Compact role routing hints, emitted only for roles that are enabled. */
 const ROLE_ROUTING: Record<string, string> = {
-	explore: "explore — broad/open-ended code search, \"where is X\", multi-file lookups (read-only, cheap).",
-	worker: "worker — implement/fix/refactor/test a well-scoped task (full tools; plans internally).",
+	explore: "explore — broad/open-ended code search, multi-file lookups (read-only, cheap); NOT for one-line lookups.",
+	worker: "worker — implement/fix/refactor/test a self-contained task worth a separate context (full tools; plans internally).",
 	reviewer: "reviewer — adversarial pre-commit review of a diff (read-only; independent context).",
 };
 
@@ -45,8 +45,9 @@ Available agents:
 ${catalog}
 
 ${routing ? `Routing:\n${routing}\n` : ""}Dispatch discipline:
-- Default to delegating every discrete task to a sub-agent; use the automatically delivered findings for orchestration and verification.
-- Only handle inline: pure Q&A, a single trivial edit/lookup, or when the user explicitly says to do it directly. When in doubt, delegate.
+- Handle SIMPLE work INLINE with direct tools: a single lookup, one-line edit, or a quick question is a grep/read/edit in the main context — never a sub-agent. Sub-agents cost startup time, tokens, and a context switch.
+- Delegate only when isolation genuinely pays: broad exploration of an unfamiliar area, a self-contained implementation/fix with its own validation, or a fresh-context review gate.
+- When in doubt, start with a direct tool call in the main context; escalate to a sub-agent only if the work turns out broad.
 - For an already-known or trivial target, use a direct search/read tool (e.g. grep/find/read) — do not over-delegate a one-line lookup.
 ${hasMultiple ? "- Run INDEPENDENT tasks in parallel: one subagent call with a `tasks` array, and track them with your todo list. Let the automatically resumed main agent launch dependent work only after its prerequisite result arrives (e.g. explore, then worker, then reviewer).\n" : ""}- Brief each sub-agent as self-contained: goal, exact paths, constraints, expected output. It has NO memory of this conversation.
 - Treat delegated agents as leaf workers: do not ask a sub-agent to dispatch another sub-agent; child processes do not have this tool.

package/src/setup.ts

@@ -27,9 +27,19 @@ import {
 } from "./config.ts";
 import { availableModelRefs, repairUnavailableModelOverrides } from "./models.ts";
 import { promptSelectMany, promptSelectOne } from "./ui.ts";
+import { loadBuiltinAgents } from "./agents.ts";
 
 const INHERIT = "__inherit__";
 
+/** Effective per-agent default strength from builtin frontmatter (config overrides win at spawn). */
+function builtinThinkingDefaults(): Map<string, ThinkingLevel> {
+	const map = new Map<string, ThinkingLevel>();
+	for (const agent of loadBuiltinAgents()) {
+		if (agent.thinking) map.set(agent.name, agent.thinking);
+	}
+	return map;
+}
+
 /** Short, selection-friendly descriptions for the built-in agents. */
 const MODULE_HINTS: Record<string, string> = {
 	explore: "read-only codebase recon (fast model)",
@@ -65,20 +75,24 @@ async function pickEnabledAgents(
 	);
 }
 
-async function pickAgentModels(
+async function pickAgentModelsAndStrength(
 	ctx: ExtensionCommandContext,
 	enabledAgents: readonly string[],
-	current: Record<string, string>,
-): Promise<Record<string, string> | undefined> {
+	currentModels: Record<string, string>,
+	currentStrengths: Record<string, ThinkingLevel>,
+	defaultLevel: ThinkingLevel,
+	defaults: ReadonlyMap<string, ThinkingLevel>,
+): Promise<{ models: Record<string, string>; strengths: Record<string, ThinkingLevel> } | undefined> {
 	const refs = availableModelRefs(ctx);
 	if (refs.length === 0) {
 		ctx.ui.notify("No Pi models are currently available; model overrides left unchanged.", "warning");
-		return { ...current };
+		return { models: { ...currentModels }, strengths: { ...currentStrengths } };
 	}
 
-	const result: Record<string, string> = {};
+	const models: Record<string, string> = {};
+	const strengths: Record<string, ThinkingLevel> = {};
 	for (const name of enabledAgents) {
-		const currentRef = current[name];
+		const currentRef = currentModels[name];
 		const items = [
 			{
 				value: INHERIT,
@@ -95,9 +109,15 @@ async function pickAgentModels(
 			items,
 		);
 		if (choice === undefined) return undefined; // Esc aborts the whole wizard
-		if (choice !== INHERIT) result[name] = choice;
+		if (choice !== INHERIT) models[name] = choice;
+
+		// Convenience: the model pick is immediately followed by the strength pick,
+		// so per-agent model + strength are configured in one pass.
+		const strength = await pickAgentStrength(ctx, name, currentStrengths[name], defaultLevel, defaults);
+		if (strength === undefined) return undefined; // Esc aborts the whole wizard
+		if (strength !== INHERIT) strengths[name] = strength;
 	}
-	return result;
+	return { models, strengths };
 }
 
 const THINKING_LEVEL_HINTS: Record<ThinkingLevel, string> = {
@@ -107,9 +127,52 @@ const THINKING_LEVEL_HINTS: Record<ThinkingLevel, string> = {
 	medium: "balanced reasoning",
 	high: "deep reasoning",
 	xhigh: "extra-deep reasoning",
-	max: "strongest reasoning (default)",
+	max: "strongest reasoning",
 };
 
+/** Single strength pick for one agent; the inherit option keeps the effective default. */
+async function pickAgentStrength(
+	ctx: ExtensionCommandContext,
+	agentName: string,
+	current: ThinkingLevel | undefined,
+	defaultLevel: ThinkingLevel,
+	defaults: ReadonlyMap<string, ThinkingLevel>,
+): Promise<ThinkingLevel | typeof INHERIT | undefined> {
+	const options = THINKING_LEVEL_VALUES.map((level) => ({
+		value: level,
+		label: current === level ? `${level} — ${THINKING_LEVEL_HINTS[level]} (current)` : `${level} — ${THINKING_LEVEL_HINTS[level]}`,
+	}));
+	const agentDefault = defaults.get(agentName);
+	const inheritLabel = agentDefault
+		? `(inherit agent default — ${agentDefault})`
+		: `(inherit global default — ${defaultLevel})`;
+	const choice = await promptSelectOne(
+		ctx,
+		`Thinking strength for "${agentName}"?`,
+		"Type to filter • ↑/↓ • Enter selects • Esc cancels setup",
+		[{ value: INHERIT, label: inheritLabel }, ...options],
+	);
+	if (choice === undefined) return undefined;
+	return choice === INHERIT ? INHERIT : (choice as ThinkingLevel);
+}
+
+/** Strength picks for every enabled agent (inherit keeps the effective default). */
+async function pickAgentStrengths(
+	ctx: ExtensionCommandContext,
+	enabledAgents: readonly string[],
+	currentStrengths: Record<string, ThinkingLevel>,
+	defaultLevel: ThinkingLevel,
+	defaults: ReadonlyMap<string, ThinkingLevel>,
+): Promise<Record<string, ThinkingLevel> | undefined> {
+	const strengths: Record<string, ThinkingLevel> = {};
+	for (const name of enabledAgents) {
+		const strength = await pickAgentStrength(ctx, name, currentStrengths[name], defaultLevel, defaults);
+		if (strength === undefined) return undefined; // Esc aborts
+		if (strength !== INHERIT) strengths[name] = strength;
+	}
+	return strengths;
+}
+
 async function pickThinkingLevel(
 	ctx: ExtensionCommandContext,
 	current: ThinkingLevel,
@@ -117,7 +180,7 @@ async function pickThinkingLevel(
 	const options = THINKING_LEVEL_VALUES.map((level) =>
 		level === current ? `${level} — ${THINKING_LEVEL_HINTS[level]} (current)` : `${level} — ${THINKING_LEVEL_HINTS[level]}`,
 	);
-	const choice = await ctx.ui.select("Sub-agent thinking strength?", options);
+	const choice = await ctx.ui.select("Default thinking strength for sub-agents?", options);
 	if (choice === undefined) return undefined;
 	return THINKING_LEVEL_VALUES.find((level) => choice.startsWith(`${level} —`));
 }
@@ -202,12 +265,14 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 	const enabled = await pickEnabledAgents(ctx, base.enabledAgents);
 	if (enabled === undefined) return notifyCancelled(ctx);
 
-	const models = await pickAgentModels(ctx, enabled, base.agentModels);
-	if (models === undefined) return notifyCancelled(ctx);
-
+	// Global default first, so per-agent strength picks can show "inherit" against it.
 	const thinkingLevel = await pickThinkingLevel(ctx, base.thinkingLevel);
 	if (thinkingLevel === undefined) return notifyCancelled(ctx);
 
+	const defaults = builtinThinkingDefaults();
+	const picked = await pickAgentModelsAndStrength(ctx, enabled, base.agentModels, base.agentThinkingLevels, thinkingLevel, defaults);
+	if (picked === undefined) return notifyCancelled(ctx);
+
 	const injection = await pickInjection(ctx, base.proactiveInjection);
 	if (injection === undefined) return notifyCancelled(ctx);
 
@@ -234,8 +299,11 @@ async function runFullSetup(ctx: ExtensionCommandContext, configPath: string, ba
 
 	const next: SubagentsConfig = {
 		enabledAgents: enabled,
-		agentModels: repairStaleModels(ctx, models),
+		agentModels: repairStaleModels(ctx, picked.models),
+		agentThinkingLevels: picked.strengths,
 		thinkingLevel,
+		notifyOnReviewPass: base.notifyOnReviewPass,
+		maxResultLines: base.maxResultLines,
 		proactiveInjection: injection,
 		agentScope: scope,
 		maxConcurrency,
@@ -268,13 +336,26 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 		if (enabled === undefined) return notifyCancelled(ctx);
 		next.enabledAgents = enabled;
 	} else if (choice.startsWith("Change agent models")) {
-		const models = await pickAgentModels(ctx, config.enabledAgents, config.agentModels);
-		if (models === undefined) return notifyCancelled(ctx);
-		next.agentModels = repairStaleModels(ctx, models);
+		const defaults = builtinThinkingDefaults();
+		const picked = await pickAgentModelsAndStrength(
+			ctx,
+			config.enabledAgents,
+			config.agentModels,
+			config.agentThinkingLevels,
+			config.thinkingLevel,
+			defaults,
+		);
+		if (picked === undefined) return notifyCancelled(ctx);
+		next.agentModels = repairStaleModels(ctx, picked.models);
+		next.agentThinkingLevels = picked.strengths;
 	} else if (choice.startsWith("Change thinking")) {
+		// Global first so per-agent "inherit" labels reflect the value that will be stored.
 		const thinkingLevel = await pickThinkingLevel(ctx, config.thinkingLevel);
 		if (thinkingLevel === undefined) return notifyCancelled(ctx);
 		next.thinkingLevel = thinkingLevel;
+		const strengths = await pickAgentStrengths(ctx, config.enabledAgents, config.agentThinkingLevels, thinkingLevel, builtinThinkingDefaults());
+		if (strengths === undefined) return notifyCancelled(ctx);
+		next.agentThinkingLevels = strengths;
 	} else if (choice.startsWith("Toggle")) {
 		const injection = await pickInjection(ctx, config.proactiveInjection);
 		if (injection === undefined) return notifyCancelled(ctx);

package/src/spawn.ts

@@ -11,8 +11,8 @@
  */
 
 import { spawn, type ChildProcess } from "node:child_process";
+import { existsSync, mkdirSync, unlinkSync, rmdirSync, writeFileSync } from "node:fs";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
-import { existsSync, unlinkSync, rmdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
@@ -51,6 +51,8 @@ export interface SingleResult {
 	stderr: string;
 	usage: UsageStats;
 	model?: string;
+	/** Effective thinking strength this run was launched with. */
+	thinking?: string;
 	stopReason?: string;
 	errorMessage?: string;
 }
@@ -88,6 +90,54 @@ export function getFinalOutput(messages: Message[]): string {
 	return "";
 }
 
+/**
+ * Parse the machine-readable verdict a reviewer emits (see agents/reviewer.md).
+ * Only the LAST standalone `VERDICT: REVIEW_PASS/FAIL` line counts, so a report
+ * that merely discusses the tokens cannot be misclassified. Returns undefined
+ * when no verdict marker is present, so non-review agents are never mistaken
+ * for reviews.
+ */
+export function reviewVerdict(output: string): "pass" | "fail" | undefined {
+	const lines = output.split("\n");
+	for (let index = lines.length - 1; index >= 0; index--) {
+		const match = /^\s*VERDICT:\s*REVIEW_(PASS|FAIL)\s*$/i.exec(lines[index]);
+		if (match) return match[1].toUpperCase() === "PASS" ? "pass" : "fail";
+	}
+	return undefined;
+}
+
+/** Hard cap for a single line inside a truncated result (minified blobs must not blow up). */
+export const RESULT_LINE_MAX = 200;
+
+export interface TruncatedOutput {
+	/** The result text that fits in the completion message. */
+	text: string;
+	/** True when lines were dropped or shortened, so the full text is written to disk. */
+	truncated: boolean;
+}
+
+/** Cap result text for the main conversation: keep the first `maxLines` lines, at most RESULT_LINE_MAX chars each. */
+export function truncateResultOutput(output: string, maxLines: number): TruncatedOutput {
+	const lines = output.split("\n");
+	if (lines.length <= maxLines && lines.every((line) => line.length <= RESULT_LINE_MAX)) {
+		return { text: output, truncated: false };
+	}
+	const kept = lines.slice(0, maxLines).map((line) =>
+		line.length > RESULT_LINE_MAX ? `${line.slice(0, RESULT_LINE_MAX)}…` : line,
+	);
+	return { text: kept.join("\n"), truncated: true };
+}
+
+/** Persist the full result where the main agent can read it on demand. Returns the file path. */
+export function writeResultArtifact(output: string, agentName: string): string {
+	const dir = join(tmpdir(), "pi-subagents-results");
+	mkdirSync(dir, { recursive: true });
+	const safeName = agentName.replace(/[^\w.-]+/g, "_");
+	const filePath = join(dir, `${Date.now()}-${safeName}.md`);
+	writeFileSync(filePath, output, "utf8");
+	return filePath;
+}
+
 export function isFailedResult(result: SingleResult): boolean {
 	return result.exitCode !== 0 || result.stopReason === "error" || result.stopReason === "aborted";
 }
@@ -238,6 +288,7 @@ export async function runSingleAgent(options: RunSingleOptions): Promise<SingleR
 		stderr: "",
 		usage: emptyUsage(),
 		model: agent.model,
+		thinking: thinkingLevel,
 	};
 
 	const emitUpdate = (): void => {