pi-subagents 0.12.2 → 0.12.4

package/subagent-executor.ts

@@ -23,7 +23,7 @@ import { discoverAvailableSkills, normalizeSkillInput } from "./skills.js";
 import { executeAsyncChain, executeAsyncSingle, isAsyncAvailable } from "./async-execution.js";
 import { createForkContextResolver } from "./fork-context.js";
 import { finalizeSingleOutput, injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
-import { getFinalOutput, mapConcurrent } from "./utils.js";
+import { getSingleResultOutput, mapConcurrent } from "./utils.js";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -46,6 +46,8 @@ import {
 	MAX_CONCURRENCY,
 	MAX_PARALLEL,
 	checkSubagentDepth,
+	resolveChildMaxSubagentDepth,
+	resolveCurrentMaxSubagentDepth,
 	wrapForkTask,
 } from "./types.js";
 
@@ -362,6 +364,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 	}
 	const id = randomUUID();
 	const asyncCtx = { pi: deps.pi, cwd: ctx.cwd, currentSessionId: deps.state.currentSessionId! };
+	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 
 	if (hasChain && params.chain) {
 		const normalized = normalizeSkillInput(params.skill);
@@ -379,6 +382,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			sessionRoot,
 			chainSkills,
 			sessionFilesByFlatIndex: collectChainSessionFiles(chain, sessionFileForIndex),
+			maxSubagentDepth: currentMaxSubagentDepth,
+			worktreeSetupHook: deps.config.worktreeSetupHook,
+			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 		});
 	}
 
@@ -395,6 +401,7 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 		const effectiveOutput: string | false | undefined = rawOutput === true ? a.output : (rawOutput as string | false | undefined);
 		const normalizedSkills = normalizeSkillInput(params.skill);
 		const skills = normalizedSkills === false ? [] : normalizedSkills;
+		const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, a.maxSubagentDepth);
 		return executeAsyncSingle(id, {
 			agent: params.agent!,
 			task: params.context === "fork" ? wrapForkTask(params.task!) : params.task!,
@@ -409,6 +416,9 @@ function runAsyncPath(data: ExecutionContextData, deps: ExecutorDeps): AgentTool
 			sessionFile: sessionFileForIndex(0),
 			skills,
 			output: effectiveOutput,
+			maxSubagentDepth,
+			worktreeSetupHook: deps.config.worktreeSetupHook,
+			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 		});
 	}
 
@@ -433,6 +443,7 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 	const normalized = normalizeSkillInput(params.skill);
 	const chainSkills = normalized === false ? [] : (normalized ?? []);
 	const chain = wrapChainTasksForFork(params.chain as ChainStep[], params.context);
+	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
 	const chainResult = await executeChain({
 		chain,
 		task: params.task,
@@ -451,6 +462,9 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 		onUpdate,
 		chainSkills,
 		chainDir: params.chainDir,
+		maxSubagentDepth: currentMaxSubagentDepth,
+		worktreeSetupHook: deps.config.worktreeSetupHook,
+		worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 	});
 
 	if (chainResult.requestedAsync) {
@@ -476,6 +490,9 @@ async function runChainPath(data: ExecutionContextData, deps: ExecutorDeps): Pro
 			sessionRoot,
 			chainSkills: chainResult.requestedAsync.chainSkills,
 			sessionFilesByFlatIndex: collectChainSessionFiles(asyncChain, sessionFileForIndex),
+			maxSubagentDepth: currentMaxSubagentDepth,
+			worktreeSetupHook: deps.config.worktreeSetupHook,
+			worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 		});
 	}
 
@@ -496,6 +513,7 @@ interface ForegroundParallelRunInput {
 	artifactsDir: string;
 	maxOutput?: MaxOutputConfig;
 	paramsCwd?: string;
+	maxSubagentDepths: number[];
 	modelOverrides: (string | undefined)[];
 	skillOverrides: (string[] | false | undefined)[];
 	behaviors: Array<ReturnType<typeof resolveStepBehavior>>;
@@ -517,11 +535,20 @@ function createParallelWorktreeSetup(
 	enabled: boolean | undefined,
 	cwd: string,
 	runId: string,
-	taskCount: number,
+	tasks: TaskParam[],
+	setupHook: ExtensionConfig["worktreeSetupHook"],
+	setupHookTimeoutMs: ExtensionConfig["worktreeSetupHookTimeoutMs"],
 ): { setup?: WorktreeSetup; errorResult?: AgentToolResult<Details> } {
 	if (!enabled) return {};
 	try {
-		return { setup: createWorktrees(cwd, runId, taskCount) };
+		return {
+			setup: createWorktrees(cwd, runId, tasks.length, {
+				agents: tasks.map((task) => task.agent),
+				setupHook: setupHook
+					? { hookPath: setupHook, timeoutMs: setupHookTimeoutMs }
+					: undefined,
+			}),
+		};
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
 		return { errorResult: buildParallelModeError(message) };
@@ -587,6 +614,7 @@ async function runForegroundParallelTasks(input: ForegroundParallelRunInput): Pr
 			artifactsDir: input.artifactConfig.enabled ? input.artifactsDir : undefined,
 			artifactConfig: input.artifactConfig,
 			maxOutput: input.maxOutput,
+			maxSubagentDepth: input.maxSubagentDepths[index],
 			modelOverride: input.modelOverrides[index],
 			skills: effectiveSkills === false ? [] : effectiveSkills,
 			onUpdate: input.onUpdate
@@ -652,6 +680,11 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		agentConfigs.push(config);
 	}
 
+	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
+	const maxSubagentDepths = agentConfigs.map((config) =>
+		resolveChildMaxSubagentDepth(currentMaxSubagentDepth, config.maxSubagentDepth),
+	);
+
 	const effectiveCwd = params.cwd ?? ctx.cwd;
 	if (params.worktree) {
 		const worktreeTaskCwdError = buildParallelWorktreeTaskCwdError(tasks, effectiveCwd);
@@ -733,6 +766,9 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 				sessionRoot,
 				chainSkills: [],
 				sessionFilesByFlatIndex: tasks.map((_, index) => sessionFileForIndex(index)),
+				maxSubagentDepth: currentMaxSubagentDepth,
+				worktreeSetupHook: deps.config.worktreeSetupHook,
+				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 			});
 		}
 	}
@@ -744,7 +780,9 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		params.worktree,
 		effectiveCwd,
 		runId,
-		tasks.length,
+		tasks,
+		deps.config.worktreeSetupHook,
+		deps.config.worktreeSetupHookTimeoutMs,
 	);
 	if (errorResult) return errorResult;
 
@@ -772,6 +810,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 			modelOverrides,
 			skillOverrides,
 			behaviors,
+			maxSubagentDepths,
 			liveResults,
 			liveProgress,
 			onUpdate,
@@ -793,7 +832,7 @@ async function runParallelPath(data: ExecutionContextData, deps: ExecutorDeps):
 		const aggregatedOutput = aggregateParallelOutputs(
 			results.map((result) => ({
 				agent: result.agent,
-				output: result.truncation?.text || getFinalOutput(result.messages),
+				output: result.truncation?.text || getSingleResultOutput(result),
 				exitCode: result.exitCode,
 				error: result.error,
 			})),
@@ -850,6 +889,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	let skillOverride: string[] | false | undefined = normalizeSkillInput(params.skill);
 	const rawOutput = params.output !== undefined ? params.output : agentConfig.output;
 	let effectiveOutput: string | false | undefined = rawOutput === true ? agentConfig.output : (rawOutput as string | false | undefined);
+	const currentMaxSubagentDepth = resolveCurrentMaxSubagentDepth(deps.config.maxSubagentDepth);
+	const maxSubagentDepth = resolveChildMaxSubagentDepth(currentMaxSubagentDepth, agentConfig.maxSubagentDepth);
 
 	if (params.clarify === true && ctx.hasUI) {
 		const availableModels: ModelInfo[] = ctx.modelRegistry.getAvailable().map((m) => ({
@@ -912,6 +953,9 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 				sessionFile: sessionFileForIndex(0),
 				skills: skillOverride === false ? [] : skillOverride,
 				output: effectiveOutput,
+				maxSubagentDepth,
+				worktreeSetupHook: deps.config.worktreeSetupHook,
+				worktreeSetupHookTimeoutMs: deps.config.worktreeSetupHookTimeoutMs,
 			});
 		}
 	}
@@ -940,6 +984,8 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 		artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 		artifactConfig,
 		maxOutput: params.maxOutput,
+		outputPath,
+		maxSubagentDepth,
 		onUpdate,
 		modelOverride,
 		skills: effectiveSkills,
@@ -949,12 +995,14 @@ async function runSinglePath(data: ExecutionContextData, deps: ExecutorDeps): Pr
 	if (r.progress) allProgress.push(r.progress);
 	if (r.artifactPaths) allArtifactPaths.push(r.artifactPaths);
 
-	const fullOutput = getFinalOutput(r.messages);
+	const fullOutput = getSingleResultOutput(r);
 	const finalizedOutput = finalizeSingleOutput({
 		fullOutput,
 		truncatedOutput: r.truncation?.text,
 		outputPath,
 		exitCode: r.exitCode,
+		savedPath: r.savedOutputPath,
+		saveError: r.outputSaveError,
 	});
 
 	if (r.exitCode !== 0)
@@ -1010,7 +1058,7 @@ export function createSubagentExecutor(deps: ExecutorDeps): {
 			return handleManagementAction(params.action, params, ctx);
 		}
 
-		const { blocked, depth, maxDepth } = checkSubagentDepth();
+		const { blocked, depth, maxDepth } = checkSubagentDepth(deps.config.maxSubagentDepth);
 		if (blocked) {
 			return {
 				content: [

package/subagent-runner.ts

@@ -3,9 +3,9 @@ import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import * as path from "node:path";
 import { pathToFileURL } from "node:url";
-import { appendJsonl, getArtifactPaths } from "./artifacts.js";
-import { getPiSpawnCommand } from "./pi-spawn.js";
-import { persistSingleOutput } from "./single-output.js";
+import { appendJsonl, getArtifactPaths } from "./artifacts.ts";
+import { getPiSpawnCommand } from "./pi-spawn.ts";
+import { captureSingleOutputSnapshot, resolveSingleOutput } from "./single-output.ts";
 import {
 	type ArtifactConfig,
 	type ArtifactPaths,
@@ -13,7 +13,7 @@ import {
 	type MaxOutputConfig,
 	truncateOutput,
 	getSubagentDepthEnv,
-} from "./types.js";
+} from "./types.ts";
 import {
 	type RunnerSubagentStep as SubagentStep,
 	type RunnerStep,
@@ -22,8 +22,8 @@ import {
 	mapConcurrent,
 	aggregateParallelOutputs,
 	MAX_PARALLEL_CONCURRENCY,
-} from "./parallel-utils.js";
-import { buildPiArgs, cleanupTempDir } from "./pi-args.js";
+} from "./parallel-utils.ts";
+import { buildPiArgs, cleanupTempDir } from "./pi-args.ts";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -32,7 +32,7 @@ import {
 	formatWorktreeDiffSummary,
 	formatWorktreeTaskCwdConflict,
 	type WorktreeSetup,
-} from "./worktree.js";
+} from "./worktree.ts";
 
 interface SubagentRunConfig {
 	id: string;
@@ -50,6 +50,8 @@ interface SubagentRunConfig {
 	asyncDir: string;
 	sessionId?: string | null;
 	piPackageRoot?: string;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
 }
 
 interface StepResult {
@@ -116,10 +118,11 @@ function runPiStreaming(
 	outputFile: string,
 	env?: Record<string, string | undefined>,
 	piPackageRoot?: string,
+	maxSubagentDepth?: number,
 ): Promise<{ stdout: string; exitCode: number | null }> {
 	return new Promise((resolve) => {
 		const outputStream = fs.createWriteStream(outputFile, { flags: "w" });
-		const spawnEnv = { ...process.env, ...(env ?? {}), ...getSubagentDepthEnv() };
+		const spawnEnv = { ...process.env, ...(env ?? {}), ...getSubagentDepthEnv(maxSubagentDepth) };
 		const spawnSpec = getPiSpawnCommand(args, piPackageRoot ? { piPackageRoot } : undefined);
 		const child = spawn(spawnSpec.command, spawnSpec.args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: spawnEnv });
 		let stdout = "";
@@ -307,6 +310,7 @@ async function runSingleStep(
 	const task = step.task.replace(placeholderRegex, () => ctx.previousOutput);
 	const sessionEnabled = Boolean(step.sessionFile) || ctx.sessionEnabled;
 	const sessionDir = step.sessionFile ? undefined : ctx.sessionDir;
+	const outputSnapshot = captureSingleOutputSnapshot(step.outputPath);
 	const { args, env, tempDir } = buildPiArgs({
 		baseArgs: ["-p"],
 		task,
@@ -332,22 +336,23 @@ async function runSingleStep(
 		}
 	}
 
-	const result = await runPiStreaming(args, step.cwd ?? ctx.cwd, ctx.outputFile, env, ctx.piPackageRoot);
+	const result = await runPiStreaming(args, step.cwd ?? ctx.cwd, ctx.outputFile, env, ctx.piPackageRoot, step.maxSubagentDepth);
 	cleanupTempDir(tempDir);
 
-	const output = (result.stdout || "").trim();
+	const rawOutput = (result.stdout || "").trim();
+	const resolvedOutput = step.outputPath && result.exitCode === 0
+		? resolveSingleOutput(step.outputPath, rawOutput, outputSnapshot)
+		: { fullOutput: rawOutput };
+	const output = resolvedOutput.fullOutput;
 	let outputForSummary = output;
-	if (step.outputPath && result.exitCode === 0) {
-		const persisted = persistSingleOutput(step.outputPath, output);
-		if (persisted.savedPath) {
-			outputForSummary = output
-				? `${output}\n\n📄 Output saved to: ${persisted.savedPath}`
-				: `📄 Output saved to: ${persisted.savedPath}`;
-		} else if (persisted.error) {
-			outputForSummary = output
-				? `${output}\n\n⚠️ Failed to save output to: ${step.outputPath}\n${persisted.error}`
-				: `⚠️ Failed to save output to: ${step.outputPath}\n${persisted.error}`;
-		}
+	if (resolvedOutput.savedPath) {
+		outputForSummary = output
+			? `${output}\n\n📄 Output saved to: ${resolvedOutput.savedPath}`
+			: `📄 Output saved to: ${resolvedOutput.savedPath}`;
+	} else if (resolvedOutput.saveError && step.outputPath && result.exitCode === 0) {
+		outputForSummary = output
+			? `${output}\n\n⚠️ Failed to save output to: ${step.outputPath}\n${resolvedOutput.saveError}`
+			: `⚠️ Failed to save output to: ${step.outputPath}\n${resolvedOutput.saveError}`;
 	}
 
 	if (artifactPaths && ctx.artifactConfig?.enabled !== false) {
@@ -580,7 +585,12 @@ async function runSubagent(config: SubagentRunConfig): Promise<void> {
 					break;
 				}
 				try {
-					worktreeSetup = createWorktrees(cwd, `${id}-s${stepIndex}`, group.parallel.length);
+					worktreeSetup = createWorktrees(cwd, `${id}-s${stepIndex}`, group.parallel.length, {
+						agents: group.parallel.map((task) => task.agent),
+						setupHook: config.worktreeSetupHook
+							? { hookPath: config.worktreeSetupHook, timeoutMs: config.worktreeSetupHookTimeoutMs }
+							: undefined,
+					});
 				} catch (error) {
 					const setupError = error instanceof Error ? error.message : String(error);
 					const failedAt = Date.now();

package/types.ts

@@ -97,6 +97,9 @@ export interface SingleResult {
 	progressSummary?: ProgressSummary;
 	artifactPaths?: ArtifactPaths;
 	truncation?: TruncationResult;
+	finalOutput?: string;
+	savedOutputPath?: string;
+	outputSaveError?: string;
 }
 
 export interface Details {
@@ -230,6 +233,8 @@ export interface RunSyncOptions {
 	sessionDir?: string;
 	sessionFile?: string;
 	share?: boolean;
+	outputPath?: string;
+	maxSubagentDepth?: number;
 	/** Override the agent's default model (format: "provider/id" or just "id") */
 	modelOverride?: string;
 	/** Skills to inject (overrides agent default if provided) */
@@ -239,6 +244,9 @@ export interface RunSyncOptions {
 export interface ExtensionConfig {
 	asyncByDefault?: boolean;
 	defaultSessionDir?: string;
+	maxSubagentDepth?: number;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
 }
 
 // ============================================================================
@@ -291,19 +299,37 @@ export function wrapForkTask(task: string, preamble?: string | false): string {
 // Recursion Depth Guard
 // ============================================================================
 
-export function checkSubagentDepth(): { blocked: boolean; depth: number; maxDepth: number } {
+export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
+	const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+	if (!Number.isInteger(parsed) || parsed < 0) return undefined;
+	return parsed;
+}
+
+export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
+	return normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH)
+		?? normalizeMaxSubagentDepth(configMaxDepth)
+		?? DEFAULT_SUBAGENT_MAX_DEPTH;
+}
+
+export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDepth?: number): number {
+	const normalizedParent = normalizeMaxSubagentDepth(parentMaxDepth) ?? DEFAULT_SUBAGENT_MAX_DEPTH;
+	const normalizedAgent = normalizeMaxSubagentDepth(agentMaxDepth);
+	return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
+}
+
+export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
 	const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
-	const maxDepth = Number(process.env.PI_SUBAGENT_MAX_DEPTH ?? String(DEFAULT_SUBAGENT_MAX_DEPTH));
-	const blocked = Number.isFinite(depth) && Number.isFinite(maxDepth) && depth >= maxDepth;
+	const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
+	const blocked = Number.isFinite(depth) && depth >= maxDepth;
 	return { blocked, depth, maxDepth };
 }
 
-export function getSubagentDepthEnv(): Record<string, string> {
+export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
 	const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
 	const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
 	return {
 		PI_SUBAGENT_DEPTH: String(nextDepth),
-		PI_SUBAGENT_MAX_DEPTH: process.env.PI_SUBAGENT_MAX_DEPTH ?? String(DEFAULT_SUBAGENT_MAX_DEPTH),
+		PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
 	};
 }
 

package/utils.ts

@@ -6,7 +6,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import type { Message } from "@mariozechner/pi-ai";
-import type { AsyncStatus, DisplayItem, ErrorInfo } from "./types.js";
+import type { AsyncStatus, DisplayItem, ErrorInfo, SingleResult } from "./types.ts";
 
 // ============================================================================
 // File System Utilities
@@ -200,6 +200,10 @@ export function getFinalOutput(messages: Message[]): string {
 	return "";
 }
 
+export function getSingleResultOutput(result: Pick<SingleResult, "finalOutput" | "messages">): string {
+	return result.finalOutput ?? getFinalOutput(result.messages);
+}
+
 /**
  * Extract display items (text and tool calls) from messages
  */