@ferris1225/pi-subagents 4.1.12 → 4.1.15

package/src/setup.ts

@@ -2,20 +2,24 @@
  * Interactive configuration wizard for /subagents-setup.
  *
  * The wizard stays one level deep and exposes only what most users touch:
- * which agents run, the model each runs on, and the delegation directive
- * toggle. Everything else (per-agent thinking, agent scope, idle timeout,
+ * which agents run, the model and thinking strength each runs on, and the
+ * delegation directive toggle. Everything else (agent scope, idle timeout,
  * result lines, notifications) is config-file-only; model failures hand
  * directly to the current main model, and thinking defaults to capability-
  * aware Auto.
  */
 
 import { stat } from "node:fs/promises";
+import type { Api, Model } from "@earendil-works/pi-ai";
 import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { discoverAgents } from "./agents.ts";
 import {
 	BUILTIN_AGENT_NAMES,
 	DEFAULT_CONFIG,
 	DEFAULT_ENABLED_AGENTS,
+	DEFAULT_THINKING_LEVEL,
 	type SubagentsConfig,
+	type ThinkingLevel,
 	errorMessage,
 	getConfigPath,
 	loadConfig,
@@ -27,7 +31,10 @@ import {
 	availableModelsInScope,
 	buildModelPickerItems,
 	currentModelRef,
+	findModelByRef,
 	modelRef,
+	resolveThinkingLevel,
+	supportedThinkingLevels,
 } from "./models.ts";
 import { promptSelectMany, promptSelectOne } from "./ui.ts";
 
@@ -98,6 +105,76 @@ async function pickAgentModel(
 	return pickConfiguredModel(ctx, `Model for "${agentName}"?`, currentRef, escNote);
 }
 
+const AUTO_THINKING = "__auto_thinking__";
+
+function actualAgentThinkingDefault(
+	ctx: ExtensionCommandContext,
+	config: SubagentsConfig,
+	agentName: string,
+): ThinkingLevel {
+	const { agents } = discoverAgents(ctx.cwd, {
+		scope: config.agentScope,
+		enabledNames: config.enabledAgents,
+		projectTrusted: ctx.isProjectTrusted(),
+	});
+	return agents.find((agent) => agent.name === agentName)?.thinking ?? DEFAULT_THINKING_LEVEL;
+}
+
+const THINKING_LEVEL_HINTS: Record<ThinkingLevel, string> = {
+	off: "no reasoning tokens",
+	minimal: "minimal reasoning",
+	low: "light reasoning",
+	medium: "balanced reasoning",
+	high: "deep reasoning",
+	xhigh: "extra-deep reasoning",
+	max: "strongest reasoning",
+};
+
+function effectiveModelForChoice(
+	ctx: ExtensionCommandContext,
+	choice: string,
+): Model<Api> | undefined {
+	if (choice === CURRENT_MAIN_MODEL) return ctx.model;
+	return findModelByRef(availableModelsInScope(ctx), choice);
+}
+
+/** Auto is the default. Manual rows are exactly the levels Pi exposes for the
+ * selected model; unsupported xhigh/max entries never appear. */
+async function pickAgentStrength(
+	ctx: ExtensionCommandContext,
+	agentName: string,
+	model: Model<Api> | undefined,
+	current: ThinkingLevel | undefined,
+	agentDefault: ThinkingLevel,
+	escNote = "cancels this setup pass",
+): Promise<ThinkingLevel | typeof AUTO_THINKING | undefined> {
+	const supported = supportedThinkingLevels(model);
+	const automatic = resolveThinkingLevel(model, agentDefault);
+	// No model metadata, or a non-reasoning model whose only valid value is off:
+	// Auto is already the complete and least surprising choice.
+	if (supported.length <= 1) return AUTO_THINKING;
+
+	const currentEffective = current ? resolveThinkingLevel(model, current) : undefined;
+	const modelName = model ? modelRef(model) : "current main model";
+	const options = [
+		{
+			value: AUTO_THINKING,
+			label: `auto — ${automatic} for ${modelName}${current === undefined ? " (current, recommended)" : " (recommended)"}`,
+		},
+		...supported.map((level) => ({
+			value: level,
+			label: `${level} — ${THINKING_LEVEL_HINTS[level]}${current !== undefined && currentEffective === level ? " (current)" : ""}`,
+		})),
+	];
+	return promptSelectOne(
+		ctx,
+		`Thinking for "${agentName}"?`,
+		`Only levels supported by ${modelName} are shown • Enter selects • Esc ${escNote}`,
+		options,
+		current === undefined ? AUTO_THINKING : currentEffective,
+	) as Promise<ThinkingLevel | typeof AUTO_THINKING | undefined>;
+}
+
 async function pickAgentToConfigure(
 	ctx: ExtensionCommandContext,
 	enabledAgents: readonly string[],
@@ -117,10 +194,11 @@ async function pickAgentToConfigure(
 interface ConfiguredAgentChoice {
 	name: string;
 	model: string;
+	strength: ThinkingLevel | typeof AUTO_THINKING;
 }
 
-/** Configure agents while preserving the UI back stack: model selection returns
- * to the agent picker on Esc; agent-picker Esc ends this configuration pass. */
+/** Configure one agent while preserving the UI back stack: thinking → model →
+ * agent selection. Esc from agent selection ends this configuration pass. */
 async function configureOneAgent(
 	ctx: ExtensionCommandContext,
 	config: SubagentsConfig,
@@ -128,14 +206,27 @@ async function configureOneAgent(
 	while (true) {
 		const name = await pickAgentToConfigure(ctx, config.enabledAgents);
 		if (name === undefined) return undefined;
-		const model = await pickAgentModel(
-			ctx,
-			name,
-			config.agentModels[name],
-			"returns to agent selection",
-		);
-		if (model === undefined) continue;
-		return { name, model };
+
+		while (true) {
+			const modelChoice = await pickAgentModel(
+				ctx,
+				name,
+				config.agentModels[name],
+				"returns to agent selection",
+			);
+			if (modelChoice === undefined) break;
+			const model = effectiveModelForChoice(ctx, modelChoice);
+			const strength = await pickAgentStrength(
+				ctx,
+				name,
+				model,
+				config.agentThinkingLevels[name],
+				actualAgentThinkingDefault(ctx, config, name),
+				"returns to model selection",
+			);
+			if (strength === undefined) continue;
+			return { name, model: modelChoice, strength };
+		}
 	}
 }
 
@@ -186,7 +277,7 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 	while (true) {
 		const choice = await ctx.ui.select("pi-subagents settings", [
 			"Enable/disable agents",
-			"Configure agent models",
+			"Configure an agent (model + thinking)",
 			"Proactive injection",
 			"Full re-setup",
 		]);
@@ -216,9 +307,9 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 					next.agentThinkingLevels.cleaner = config.agentThinkingLevels.reviewer;
 				}
 			}
-			// Documenter intentionally follows the faster explorer route. Fresh
-			// installs leave it unselected; enabling it later inherits any explorer
-			// overrides instead of silently choosing a stronger model.
+			// Documenter intentionally follows the faster explorer route. When it
+			// is re-enabled after being explicitly disabled, it inherits any
+			// explorer overrides instead of silently choosing a stronger model.
 			if (!config.enabledAgents.includes("documenter") && enabled.includes("documenter")) {
 				if (!next.agentModels.documenter && config.agentModels.explorer) {
 					next.agentModels.documenter = config.agentModels.explorer;
@@ -230,14 +321,17 @@ async function runMenu(ctx: ExtensionCommandContext, configPath: string, config:
 			next.agentModels = keepAgentEntries(next.agentModels, enabled);
 			next.agentThinkingLevels = keepAgentEntries(next.agentThinkingLevels, enabled);
 		} else if (choice.startsWith("Configure")) {
-			// Per-agent loop: model Esc returns to the agent picker; agent-picker
-			// Esc saves completed choices and returns to this settings menu.
+			// Per-agent loop: thinking Esc returns to that agent's model picker;
+			// model Esc returns to the agent picker; agent-picker Esc saves completed
+			// choices and returns to this settings menu.
 			let configuredAny = false;
 			while (true) {
 				const picked = await configureOneAgent(ctx, next);
 				if (!picked) break;
 				configuredAny = true;
 				next.agentModels = applyAgentModelChoice(next.agentModels, picked.name, picked.model);
+				if (picked.strength === AUTO_THINKING) delete next.agentThinkingLevels[picked.name];
+				else next.agentThinkingLevels[picked.name] = picked.strength;
 			}
 			if (!configuredAny) continue;
 			await saveConfig(next, configPath);

package/src/thread-lifecycle.ts

@@ -42,6 +42,7 @@ import {
 	failedStartResult,
 	formatCompletionBlock,
 	modelLevelTakeoverNote,
+	reviewFailFollowUpNote,
 	queuedResult,
 } from "./format.ts";
 import {
@@ -220,16 +221,19 @@ export function ownsResumeReservation(
 	);
 }
 
-/** Fire-and-forget durable checkpoint write. The live session keeps working
- * when the manifest is unwritable; only cross-reload resume is degraded. */
+/** Fire-and-forget durable checkpoint. Parked threads stay resumable across
+ * reloads; a settled thread drops its record so the manifest only exists
+ * while unfinished work needs it. The live session keeps working when the
+ * manifest is unwritable; only cross-reload resume is degraded. */
 export function persistThreadCheckpoint(
 	runtime: SubagentRuntime,
 	thread: SubagentThread,
 	state: "parked" | "completed" | "failed",
 ): void {
-	void upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state)).catch(
-		() => undefined,
-	);
+	const write = state === "parked"
+		? upsertThreadRecord(runtime.configPath, threadRecordFromThread(thread, state))
+		: removeThreadRecord(runtime.configPath, thread.id);
+	void write.catch(() => undefined);
 }
 
 const WORKTREE_ISOLATION_INSTRUCTIONS =
@@ -246,27 +250,6 @@ export function isWorktreeCapableAgent(agent: AgentConfig): boolean {
 	return isWriteCapableAgent(agent);
 }
 
-/** A direct reviewer otherwise cannot infer enabled-role availability from its
- * isolated task. Managed internal gates receive the same contract in their
- * generated briefs. Advisory reviews still emit neither machine marker. */
-function withEnabledDocumenterReviewContract(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}\n\nRuntime workflow context: documenter is enabled. In gate reviews, documentation drift is non-gating: emit DOCUMENTATION: NEEDED with ## Documentation notes, or DOCUMENTATION: CLEAN when no sync is needed. Advisory reviews still emit neither VERDICT nor DOCUMENTATION markers.`.trim(),
-	};
-}
-
-/** The dispatcher explicitly requested a report-only review: forbid the gate
- * markers at the source and (in dispatch) refuse to chain on them anyway. */
-function withAdvisoryReviewContract(agent: AgentConfig): AgentConfig {
-	return {
-		...agent,
-		systemPrompt: `${agent.systemPrompt.trimEnd()}
-
-Runtime workflow context: this dispatch is advisory. Report findings only; do not emit VERDICT or DOCUMENTATION markers — the runtime will not act on them.`.trim(),
-	};
-}
-
 export interface DispatchEnvironment {
 	ctx: ExtensionContext;
 	config: SubagentsConfig;
@@ -296,7 +279,6 @@ export interface StartBackgroundOptions {
 	environment?: DispatchEnvironment;
 	seed?: SessionSeed;
 	resumeReservation?: ResumeReservation;
-	advisoryReview?: boolean;
 }
 
 export type StartBackgroundInternal = (
@@ -426,15 +408,7 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 		if (!discoveredAgent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
 		const resolveLiveAgentTools = (candidate: AgentConfig): AgentConfig =>
 			resolveAgentTools({ ...candidate, tools: discoveredAgent.tools }, runtime.getActiveTools());
-		const resolvedAgent = resolveLiveAgentTools(discoveredAgent);
-		const advisoryReview = startOptions.advisoryReview ?? existingThread?.advisoryReview ?? false;
-		const agent = agentName === "reviewer"
-			? advisoryReview
-				? withAdvisoryReviewContract(resolvedAgent)
-				: runAgents.some((candidate) => candidate.name === "documenter")
-					? withEnabledDocumenterReviewContract(resolvedAgent)
-					: resolvedAgent
-			: resolvedAgent;
+		const agent = resolveLiveAgentTools(discoveredAgent);
 		if (isolation === "worktree" && !isWorktreeCapableAgent(agent)) {
 			return {
 				...failedStartResult(agentName, task, `Agent "${agentName}" is read-only; worktree isolation is available only to write-capable agents such as worker, cleaner, or documenter.`),
@@ -528,7 +502,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 			thread.executionCwd = executionCwd;
 			thread.thinkingLevel = thinkingLevel;
 			thread.isolation = isolation;
-			thread.advisoryReview = advisoryReview;
 			thread.worktree = worktree;
 			thread.state = "queued";
 			thread.control = control;
@@ -552,7 +525,6 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				executionCwd,
 				thinkingLevel,
 				isolation,
-				advisoryReview,
 				worktree,
 				state: "queued",
 				control,
@@ -670,13 +642,13 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 				if (thread.lifecycleOperation === "stop") return;
 
 				// A shutdown can win in the microtask gap after the top-level RPC
-				// settles. Do not launch an obsolete documenter/reviewer or replace the
+				// settles. Do not launch an obsolete downstream gate or replace the
 				// stable top-level session with an aborted downstream attempt.
 				if (backgroundSignal.aborted || lifecycleInterrupted() || !runtime.sessionActive) return;
 
 				if (thread.retireOnSettle) runtime.retireThreadSession(thread);
 				let workflowOutcome: ManagedWorkflowOutcome | undefined;
-				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability, thread.advisoryReview);
+				const workflowPlan = getManagedWorkflowPlan(result, workflowAvailability);
 					if (workflowPlan && runtime.sessionActive) {
 						// The continuation is runtime-initiated (gate review,
 						// documentation sync): release this generation's
@@ -801,6 +773,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						if (needsFullFinal) {
 							block += `\n\n${formatCompletionBlock(result, runConfig.maxResultLines, originalCwd)}`;
 						}
+						if (finalVerdict === "fail") {
+							block += `\n\n${reviewFailFollowUpNote()}`;
+						}
 						if (modelLevel) block += `\n\n${modelLevelTakeoverNote(result, { runId })}`;
 						runtime.sendCompletionGroup([{
 							agent: `managed workflow (${result.agent})`,
@@ -816,7 +791,9 @@ export function createBackgroundDispatcher(options: BackgroundDispatcherOptions)
 						agent: result.agent,
 						block: modelLevel
 							? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${modelLevelTakeoverNote(result, { runId })}`
-							: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
+							: result.agent === "reviewer" && reviewVerdict(getResultOutput(result)) === "fail"
+								? `${formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd)}\n\n${reviewFailFollowUpNote()}`
+								: formatCompletionBlock(result, runConfig.maxResultLines, result.projectCwd ?? originalCwd),
 						triggerTurn: completionTriggersTurn(result, runConfig.notifyOnReviewPass),
 						usage: result.usage,
 					};
@@ -1290,7 +1267,6 @@ function createRestoredThread(
 		executionCwd: record.executionCwd,
 		...(record.thinkingLevel ? { thinkingLevel: record.thinkingLevel as ThinkingLevel } : {}),
 		isolation: record.isolation,
-		advisoryReview: false,
 		worktree,
 		state,
 		control: new RpcRunControl(record.task, record.generation),
@@ -1320,15 +1296,20 @@ function createRestoredThread(
 	return thread;
 }
 
-/** Rebuild parked and settled threads from the durable manifest after a reload
- * or restart. Orphaned children recorded by the previous process are killed
- * first; records whose retained session vanished drop out with their
- * artifacts. Returns the restored run ids. */
+/** Rebuild interrupted (parked) threads from the durable manifest after a
+ * reload or restart. Orphaned children recorded by the previous process are
+ * killed first; records whose retained session vanished — and settled records
+ * left by older versions, which hold no work worth resuming — drop out with
+ * their artifacts. Returns the restored run ids. */
 export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<number[]> {
 	const records = await readThreadRecords(runtime.configPath);
 	const restoredIds: number[] = [];
 	for (const record of records) {
 		if (runtime.threads.has(record.runId) || monitor.findRun(record.runId)) continue;
+		if (record.state !== "parked") {
+			await discardRestoredRecord(runtime, record);
+			continue;
+		}
 		// A child orphaned by reload/crash may still hold the retained session.
 		// The on-disk session checkpoint is what survives; kill the writer.
 		for (const pid of record.childPids) {
@@ -1348,33 +1329,29 @@ export async function restoreDurableThreads(runtime: SubagentRuntime): Promise<n
 		// A worktree thread whose isolated filesystem is gone cannot continue its
 		// isolation invariant; surface it as failed instead of pretending.
 		const state: ThreadState = worktree
-			? record.state
+			? "parked"
 			: record.isolation === "worktree" && record.worktree
 				? "failed"
-				: record.state;
+				: "parked";
 		const thread = createRestoredThread(runtime, record, worktree, state);
 		runtime.threads.set(record.runId, thread);
 		runtime.sessionDirs.add(record.sessionDir!);
-		if (state === "parked") {
-			monitor.restoreRun({
-				id: record.runId,
-				agent: record.agentName,
-				task: record.task,
-				status: "parked",
-				elapsedMs: record.elapsedMs,
-				isolation: record.isolation,
-				...(record.worktree
-					? {
-						integrationStatus: record.worktree.state === "active"
-							? ("pending" as const)
-							: record.worktree.state,
-						...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
-					}
-					: {}),
-			});
-		} else if (thread.lastResult) {
-			runtime.registerRunResult(record.runId, thread.lastResult);
-		}
+		monitor.restoreRun({
+			id: record.runId,
+			agent: record.agentName,
+			task: record.task,
+			status: "parked",
+			elapsedMs: record.elapsedMs,
+			isolation: record.isolation,
+			...(record.worktree
+				? {
+					integrationStatus: record.worktree.state === "active"
+						? ("pending" as const)
+						: record.worktree.state,
+					...(worktree ? { worktreeId: worktreeGroupId(worktree) } : {}),
+				}
+				: {}),
+		});
 		restoredIds.push(record.runId);
 	}
 	return restoredIds;

package/src/tools.ts

@@ -106,7 +106,7 @@ export function registerLookupTools(pi: ExtensionAPI, runtime: SubagentRuntime):
 						const context = hadRetainedSession
 							? "the same retained session and prior context are preserved"
 							: "no prior child session existed, so only the logical run and objective are continued";
-						return { content: [{ type: "text", text: `Resumed run #${thread.id}, ${mode}; ${context}, and cumulative active time is preserved. Completion will arrive automatically.` }], details: {}, terminate: true };
+						return { content: [{ type: "text", text: `Resumed run #${thread.id}, ${mode}; ${context}, and cumulative active time is preserved. It runs in the background — keep working; the result resumes you automatically.` }], details: {} };
 					}
 				}
 			} catch (error) {