pi-subagents 0.12.2 → 0.12.4

package/chain-clarify.ts

@@ -11,12 +11,12 @@ import { matchesKey, visibleWidth, truncateToWidth } from "@mariozechner/pi-tui"
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { AgentConfig, ChainConfig, ChainStepConfig } from "./agents.js";
-import type { ResolvedStepBehavior } from "./settings.js";
-import type { TextEditorState } from "./text-editor.js";
-import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.js";
-import { updateFrontmatterField } from "./agent-serializer.js";
-import { serializeChain } from "./chain-serializer.js";
+import type { AgentConfig, ChainConfig, ChainStepConfig } from "./agents.ts";
+import type { ResolvedStepBehavior } from "./settings.ts";
+import type { TextEditorState } from "./text-editor.ts";
+import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.ts";
+import { updateFrontmatterField } from "./agent-serializer.ts";
+import { serializeChain } from "./chain-serializer.ts";
 
 /** Clarify TUI mode */
 export type ClarifyMode = 'single' | 'parallel' | 'chain';
@@ -92,20 +92,42 @@ export class ChainClarifyComponent implements Component {
 	private savingChain = false;
 	/** Run in background (async) mode */
 	private runInBackground = false;
+	private tui: TUI;
+	private theme: Theme;
+	private agentConfigs: AgentConfig[];
+	private templates: string[];
+	private originalTask: string;
+	private chainDir: string | undefined;
+	private resolvedBehaviors: ResolvedStepBehavior[];
+	private availableModels: ModelInfo[];
+	private availableSkills: Array<{ name: string; source: string; description?: string }>;
+	private done: (result: ChainClarifyResult) => void;
+	private mode: ClarifyMode;
 
 	constructor(
-		private tui: TUI,
-		private theme: Theme,
-		private agentConfigs: AgentConfig[],
-		private templates: string[],
-		private originalTask: string,
-		private chainDir: string | undefined,  // undefined for single/parallel modes
-		private resolvedBehaviors: ResolvedStepBehavior[],
-		private availableModels: ModelInfo[],
-		private availableSkills: Array<{ name: string; source: string; description?: string }>,
-		private done: (result: ChainClarifyResult) => void,
-		private mode: ClarifyMode = 'chain',   // Mode: 'single', 'parallel', or 'chain'
+		tui: TUI,
+		theme: Theme,
+		agentConfigs: AgentConfig[],
+		templates: string[],
+		originalTask: string,
+		chainDir: string | undefined,  // undefined for single/parallel modes
+		resolvedBehaviors: ResolvedStepBehavior[],
+		availableModels: ModelInfo[],
+		availableSkills: Array<{ name: string; source: string; description?: string }>,
+		done: (result: ChainClarifyResult) => void,
+		mode: ClarifyMode = 'chain',   // Mode: 'single', 'parallel', or 'chain'
 	) {
+		this.tui = tui;
+		this.theme = theme;
+		this.agentConfigs = agentConfigs;
+		this.templates = templates;
+		this.originalTask = originalTask;
+		this.chainDir = chainDir;
+		this.resolvedBehaviors = resolvedBehaviors;
+		this.availableModels = availableModels;
+		this.availableSkills = availableSkills;
+		this.done = done;
+		this.mode = mode;
 		// Initialize filtered models
 		this.filteredModels = [...availableModels];
 		this.filteredSkills = [...availableSkills];

package/chain-execution.ts

@@ -6,8 +6,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { AgentConfig } from "./agents.js";
-import { ChainClarifyComponent, type ChainClarifyResult, type BehaviorOverride, type ModelInfo } from "./chain-clarify.js";
+import type { AgentConfig } from "./agents.ts";
+import { ChainClarifyComponent, type ChainClarifyResult, type BehaviorOverride, type ModelInfo } from "./chain-clarify.ts";
 import {
 	resolveChainTemplates,
 	createChainDir,
@@ -24,12 +24,12 @@ import {
 	type ParallelTaskResult,
 	type ResolvedStepBehavior,
 	type ResolvedTemplates,
-} from "./settings.js";
-import { discoverAvailableSkills, normalizeSkillInput } from "./skills.js";
-import { runSync } from "./execution.js";
-import { buildChainSummary } from "./formatters.js";
-import { getFinalOutput, mapConcurrent } from "./utils.js";
-import { recordRun } from "./run-history.js";
+} from "./settings.ts";
+import { discoverAvailableSkills, normalizeSkillInput } from "./skills.ts";
+import { runSync } from "./execution.ts";
+import { buildChainSummary } from "./formatters.ts";
+import { getSingleResultOutput, mapConcurrent } from "./utils.ts";
+import { recordRun } from "./run-history.ts";
 import {
 	cleanupWorktrees,
 	createWorktrees,
@@ -46,7 +46,8 @@ import {
 	type Details,
 	type SingleResult,
 	MAX_CONCURRENCY,
-} from "./types.js";
+	resolveChildMaxSubagentDepth,
+} from "./types.ts";
 
 /** Resolve a model name to its full provider/model format */
 function resolveModelFullId(modelName: string | undefined, availableModels: ModelInfo[]): string | undefined {
@@ -102,6 +103,7 @@ interface ParallelChainRunInput {
 	chainAgents: string[];
 	totalSteps: number;
 	worktreeSetup?: WorktreeSetup;
+	maxSubagentDepth: number;
 }
 
 function buildChainExecutionDetails(input: ChainExecutionDetailsInput): Details {
@@ -191,11 +193,16 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 			const effectiveModel =
 				(task.model ? resolveModelFullId(task.model, input.availableModels) : null)
 				?? resolveModelFullId(taskAgentConfig?.model, input.availableModels);
+			const maxSubagentDepth = resolveChildMaxSubagentDepth(input.maxSubagentDepth, taskAgentConfig?.maxSubagentDepth);
 
 			const taskCwd = input.worktreeSetup
 				? input.worktreeSetup.worktrees[taskIndex]!.agentCwd
 				: (task.cwd ?? input.cwd);
 
+			const outputPath = typeof behavior.output === "string"
+				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(input.chainDir, behavior.output))
+				: undefined;
+
 			const result = await runSync(input.ctx.cwd, input.agents, task.agent, taskStr, {
 				cwd: taskCwd,
 				signal: input.signal,
@@ -206,6 +213,8 @@ async function runParallelChainTasks(input: ParallelChainRunInput): Promise<Sing
 				share: input.shareEnabled,
 				artifactsDir: input.artifactConfig.enabled ? input.artifactsDir : undefined,
 				artifactConfig: input.artifactConfig,
+				outputPath,
+				maxSubagentDepth,
 				modelOverride: effectiveModel,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: input.onUpdate
@@ -256,6 +265,9 @@ export interface ChainExecutionParams {
 	onUpdate?: (r: AgentToolResult<Details>) => void;
 	chainSkills?: string[];
 	chainDir?: string;
+	maxSubagentDepth: number;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
 }
 
 export interface ChainExecutionResult {
@@ -458,7 +470,12 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					);
 				}
 				try {
-					worktreeSetup = createWorktrees(parallelCwd, `${runId}-s${stepIndex}`, step.parallel.length);
+					worktreeSetup = createWorktrees(parallelCwd, `${runId}-s${stepIndex}`, step.parallel.length, {
+						agents: step.parallel.map((task) => task.agent),
+						setupHook: params.worktreeSetupHook
+							? { hookPath: params.worktreeSetupHook, timeoutMs: params.worktreeSetupHookTimeoutMs }
+							: undefined,
+					});
 				} catch (error) {
 					const message = error instanceof Error ? error.message : String(error);
 					return buildChainExecutionErrorResult(message, {
@@ -506,6 +523,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					chainAgents,
 					totalSteps,
 					worktreeSetup,
+					maxSubagentDepth: params.maxSubagentDepth,
 				});
 				globalTaskIndex += step.parallel.length;
 
@@ -551,7 +569,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 					return {
 						agent: result.agent,
 						taskIndex: i,
-						output: getFinalOutput(result.messages),
+						output: getSingleResultOutput(result),
 						exitCode: result.exitCode,
 						error: result.error,
 						outputTargetPath,
@@ -629,6 +647,11 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				?? resolveModelFullId(agentConfig.model, availableModels);
 
 			// Run step
+			const outputPath = typeof behavior.output === "string"
+				? (path.isAbsolute(behavior.output) ? behavior.output : path.join(chainDir, behavior.output))
+				: undefined;
+			const maxSubagentDepth = resolveChildMaxSubagentDepth(params.maxSubagentDepth, agentConfig.maxSubagentDepth);
+
 			const r = await runSync(ctx.cwd, agents, seqStep.agent, stepTask, {
 				cwd: seqStep.cwd ?? cwd,
 				signal,
@@ -639,6 +662,8 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				share: shareEnabled,
 				artifactsDir: artifactConfig.enabled ? artifactsDir : undefined,
 				artifactConfig,
+				outputPath,
+				maxSubagentDepth,
 				modelOverride: effectiveModel,
 				skills: behavior.skills === false ? [] : behavior.skills,
 				onUpdate: onUpdate
@@ -709,7 +734,7 @@ export async function executeChain(params: ChainExecutionParams): Promise<ChainE
 				};
 			}
 
-			prev = getFinalOutput(r.messages);
+			prev = getSingleResultOutput(r);
 		}
 	}
 

package/chain-serializer.ts

@@ -1,5 +1,5 @@
-import type { ChainConfig, ChainStepConfig } from "./agents.js";
-import { parseFrontmatter } from "./frontmatter.js";
+import type { ChainConfig, ChainStepConfig } from "./agents.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
 
 function parseStepBody(agent: string, sectionBody: string): ChainStepConfig {
 	const lines = sectionBody.split("\n");

package/execution.ts

@@ -4,13 +4,13 @@
 
 import { spawn } from "node:child_process";
 import type { Message } from "@mariozechner/pi-ai";
-import type { AgentConfig } from "./agents.js";
+import type { AgentConfig } from "./agents.ts";
 import {
 	ensureArtifactsDir,
 	getArtifactPaths,
 	writeArtifact,
 	writeMetadata,
-} from "./artifacts.js";
+} from "./artifacts.ts";
 import {
 	type AgentProgress,
 	type ArtifactPaths,
@@ -19,18 +19,19 @@ import {
 	DEFAULT_MAX_OUTPUT,
 	truncateOutput,
 	getSubagentDepthEnv,
-} from "./types.js";
+} from "./types.ts";
 import {
 	getFinalOutput,
 	findLatestSessionFile,
 	detectSubagentError,
 	extractToolArgsPreview,
 	extractTextFromContent,
-} from "./utils.js";
-import { buildSkillInjection, resolveSkills } from "./skills.js";
-import { getPiSpawnCommand } from "./pi-spawn.js";
-import { createJsonlWriter } from "./jsonl-writer.js";
-import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "./pi-args.js";
+} from "./utils.ts";
+import { buildSkillInjection, resolveSkills } from "./skills.ts";
+import { getPiSpawnCommand } from "./pi-spawn.ts";
+import { createJsonlWriter } from "./jsonl-writer.ts";
+import { applyThinkingSuffix, buildPiArgs, cleanupTempDir } from "./pi-args.ts";
+import { captureSingleOutputSnapshot, resolveSingleOutput } from "./single-output.ts";
 
 /**
  * Run a subagent synchronously (blocking until complete)
@@ -59,6 +60,7 @@ export async function runSync(
 	const sessionEnabled = Boolean(options.sessionFile || options.sessionDir) || shareEnabled;
 	const effectiveModel = modelOverride ?? agent.model;
 	const modelArg = applyThinkingSuffix(effectiveModel, agent.thinking);
+	const outputSnapshot = captureSingleOutputSnapshot(options.outputPath);
 
 	const skillNames = options.skills ?? agent.skills ?? [];
 	const { resolved: resolvedSkills, missing: missingSkills } = resolveSkills(skillNames, runtimeCwd);
@@ -125,7 +127,7 @@ export async function runSync(
 		}
 	}
 
-	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv() };
+	const spawnEnv = { ...process.env, ...sharedEnv, ...getSubagentDepthEnv(options.maxSubagentDepth) };
 
 	let closeJsonlWriter: (() => Promise<void>) | undefined;
 	const exitCode = await new Promise<number>((resolve) => {
@@ -299,9 +301,17 @@ export async function runSync(
 		durationMs: progress.durationMs,
 	};
 
+	let fullOutput = getFinalOutput(result.messages);
+	if (options.outputPath && result.exitCode === 0) {
+		const resolvedOutput = resolveSingleOutput(options.outputPath, fullOutput, outputSnapshot);
+		fullOutput = resolvedOutput.fullOutput;
+		result.savedOutputPath = resolvedOutput.savedPath;
+		result.outputSaveError = resolvedOutput.saveError;
+	}
+	result.finalOutput = fullOutput;
+
 	if (artifactPathsResult && artifactConfig?.enabled !== false) {
 		result.artifactPaths = artifactPathsResult;
-		const fullOutput = getFinalOutput(result.messages);
 
 		if (artifactConfig?.includeOutput !== false) {
 			writeArtifact(artifactPathsResult.outputPath, fullOutput);
@@ -332,7 +342,6 @@ export async function runSync(
 		}
 	} else if (maxOutput) {
 		const config = { ...DEFAULT_MAX_OUTPUT, ...maxOutput };
-		const fullOutput = getFinalOutput(result.messages);
 		const truncationResult = truncateOutput(fullOutput, config);
 		if (truncationResult.truncated) {
 			result.truncation = truncationResult;

package/formatters.ts

@@ -4,9 +4,9 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { Usage, SingleResult } from "./types.js";
-import type { ChainStep, SequentialStep } from "./settings.js";
-import { isParallelStep } from "./settings.js";
+import type { Usage, SingleResult } from "./types.ts";
+import type { ChainStep, SequentialStep } from "./settings.ts";
+import { isParallelStep } from "./settings.ts";
 
 /**
  * Format token count with k suffix for large numbers

package/index.ts

@@ -9,7 +9,7 @@
  * Toggle: async parameter (default: false, configurable via config.json)
  *
  * Config file: ~/.pi/agent/extensions/subagent/config.json
- *   { "asyncByDefault": true }
+ *   { "asyncByDefault": true, "maxSubagentDepth": 1, "worktreeSetupHook": "./scripts/setup-worktree.mjs" }
  */
 
 import * as fs from "node:fs";
@@ -18,20 +18,20 @@ import * as path from "node:path";
 import type { AgentToolResult } from "@mariozechner/pi-agent-core";
 import { type ExtensionAPI, type ExtensionContext, type ToolDefinition } from "@mariozechner/pi-coding-agent";
 import { Box, Container, Spacer, Text } from "@mariozechner/pi-tui";
-import { discoverAgents } from "./agents.js";
-import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "./artifacts.js";
-import { cleanupOldChainDirs } from "./settings.js";
-import { renderWidget, renderSubagentResult } from "./render.js";
-import { SubagentParams, StatusParams } from "./schemas.js";
-import { findByPrefix, readStatus } from "./utils.js";
-import { createSubagentExecutor } from "./subagent-executor.js";
-import { createAsyncJobTracker } from "./async-job-tracker.js";
-import { createResultWatcher } from "./result-watcher.js";
-import { registerSlashCommands } from "./slash-commands.js";
-import { registerPromptTemplateDelegationBridge } from "./prompt-template-bridge.js";
-import { registerSlashSubagentBridge } from "./slash-bridge.js";
-import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "./slash-live-state.js";
-import { formatAsyncRunList, listAsyncRuns } from "./async-status.js";
+import { discoverAgents } from "./agents.ts";
+import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "./artifacts.ts";
+import { cleanupOldChainDirs } from "./settings.ts";
+import { renderWidget, renderSubagentResult } from "./render.ts";
+import { SubagentParams, StatusParams } from "./schemas.ts";
+import { findByPrefix, readStatus } from "./utils.ts";
+import { createSubagentExecutor } from "./subagent-executor.ts";
+import { createAsyncJobTracker } from "./async-job-tracker.ts";
+import { createResultWatcher } from "./result-watcher.ts";
+import { registerSlashCommands } from "./slash-commands.ts";
+import { registerPromptTemplateDelegationBridge } from "./prompt-template-bridge.ts";
+import { registerSlashSubagentBridge } from "./slash-bridge.ts";
+import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "./slash-live-state.ts";
+import { formatAsyncRunList, listAsyncRuns } from "./async-status.ts";
 import {
 	type Details,
 	type ExtensionConfig,
@@ -41,7 +41,7 @@ import {
 	RESULTS_DIR,
 	SLASH_RESULT_TYPE,
 	WIDGET_KEY,
-} from "./types.js";
+} from "./types.ts";
 
 /**
  * Derive subagent session base directory from parent session file.

package/notify.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "./completion-dedupe.js";
+import { buildCompletionKey, getGlobalSeenMap, markSeenWithTtl } from "./completion-dedupe.ts";
 
 interface ChainStepResult {
 	agent: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "description": "Pi extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
   "author": "Nico Bailon",
   "license": "MIT",
@@ -46,6 +46,13 @@
       "./notify.ts"
     ]
   },
+  "peerDependencies": {
+    "@mariozechner/pi-agent-core": "*",
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*",
+    "@sinclair/typebox": "*"
+  },
   "devDependencies": {
     "@marcfargas/pi-test-harness": "^0.5.0",
     "@mariozechner/pi-agent-core": "^0.65.0",

package/parallel-utils.ts

@@ -17,6 +17,7 @@ export interface RunnerSubagentStep {
 	skills?: string[];
 	outputPath?: string;
 	sessionFile?: string;
+	maxSubagentDepth?: number;
 }
 
 /** Parallel step group — multiple agents running concurrently */

package/pi-spawn.ts

@@ -83,15 +83,12 @@ export function resolveWindowsPiCliScript(deps: PiSpawnDeps = {}): string | unde
 }
 
 export function getPiSpawnCommand(args: string[], deps: PiSpawnDeps = {}): PiSpawnCommand {
-	const platform = deps.platform ?? process.platform;
-	if (platform === "win32") {
-		const piCliPath = resolveWindowsPiCliScript(deps);
-		if (piCliPath) {
-			return {
-				command: deps.execPath ?? process.execPath,
-				args: [piCliPath, ...args],
-			};
-		}
+	const piCliPath = resolveWindowsPiCliScript(deps);
+	if (piCliPath) {
+		return {
+			command: deps.execPath ?? process.execPath,
+			args: [piCliPath, ...args],
+		};
 	}
 
 	return { command: "pi", args };

package/render.ts

@@ -10,9 +10,9 @@ import {
 	type Details,
 	MAX_WIDGET_JOBS,
 	WIDGET_KEY,
-} from "./types.js";
-import { formatTokens, formatUsage, formatDuration, formatToolCall, shortenPath } from "./formatters.js";
-import { getFinalOutput, getDisplayItems, getOutputTail, getLastActivity } from "./utils.js";
+} from "./types.ts";
+import { formatTokens, formatUsage, formatDuration, formatToolCall, shortenPath } from "./formatters.ts";
+import { getDisplayItems, getLastActivity, getOutputTail, getSingleResultOutput } from "./utils.ts";
 
 type Theme = ExtensionContext["ui"]["theme"];
 
@@ -199,7 +199,7 @@ export function renderSubagentResult(
 				? theme.fg("success", "ok")
 				: theme.fg("error", "X");
 		const contextBadge = d.context === "fork" ? theme.fg("warning", " [fork]") : "";
-		const output = r.truncation?.text || getFinalOutput(r.messages);
+		const output = r.truncation?.text || getSingleResultOutput(r);
 
 		const progressInfo = isRunning && r.progress
 			? ` | ${r.progress.toolCount} tools, ${formatTokens(r.progress.tokens)} tok, ${formatDuration(r.progress.durationMs)}`
@@ -283,7 +283,7 @@ export function renderSubagentResult(
 	const hasEmptyWithoutTarget = d.results.some((r) =>
 		r.exitCode === 0
 		&& r.progress?.status !== "running"
-		&& hasEmptyTextOutputWithoutOutputTarget(r.task, getFinalOutput(r.messages)),
+		&& hasEmptyTextOutputWithoutOutputTarget(r.task, getSingleResultOutput(r)),
 	);
 	const icon = hasRunning
 		? theme.fg("warning", "...")
@@ -337,7 +337,7 @@ export function renderSubagentResult(
 					const isComplete = result && result.exitCode === 0 && result.progress?.status !== "running";
 					const isEmptyWithoutTarget = Boolean(result)
 						&& Boolean(isComplete)
-						&& hasEmptyTextOutputWithoutOutputTarget(result.task, getFinalOutput(result.messages));
+						&& hasEmptyTextOutputWithoutOutputTarget(result.task, getSingleResultOutput(result));
 					const isCurrent = i === (d.currentStepIndex ?? d.results.length);
 					const stepIcon = isFailed
 						? theme.fg("error", "✗")
@@ -395,7 +395,7 @@ export function renderSubagentResult(
 		const rProg = r.progress || progressFromArray || r.progressSummary;
 		const rRunning = rProg?.status === "running";
 
-		const resultOutput = getFinalOutput(r.messages);
+		const resultOutput = getSingleResultOutput(r);
 		const statusIcon = rRunning
 			? theme.fg("warning", "●")
 			: r.exitCode !== 0

package/schemas.ts

@@ -70,7 +70,7 @@ export const SubagentParams = Type.Object({
 	})),
 	// Agent/chain configuration for create/update (nested to avoid conflicts with execution fields)
 	config: Type.Optional(Type.Any({
-		description: "Agent or chain config for create/update. Agent: name, description, scope ('user'|'project', default 'user'), systemPrompt, model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress. Chain: name, description, scope, steps (array of {agent, task?, output?, reads?, model?, skills?, progress?}). Presence of 'steps' creates a chain instead of an agent."
+		description: "Agent or chain config for create/update. Agent: name, description, scope ('user'|'project', default 'user'), systemPrompt, model, tools (comma-separated), extensions (comma-separated), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, description, scope, steps (array of {agent, task?, output?, reads?, model?, skills?, progress?}). Presence of 'steps' creates a chain instead of an agent."
 	})),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?}, ...]" })),
 	worktree: Type.Optional(Type.Boolean({

package/settings.ts

@@ -5,8 +5,8 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { AgentConfig } from "./agents.js";
-import { normalizeSkillInput } from "./skills.js";
+import type { AgentConfig } from "./agents.ts";
+import { normalizeSkillInput } from "./skills.ts";
 
 const CHAIN_RUNS_DIR = path.join(os.tmpdir(), "pi-chain-runs");
 const CHAIN_DIR_MAX_AGE_MS = 24 * 60 * 60 * 1000; // 24 hours

package/single-output.ts

@@ -1,6 +1,12 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+export interface SingleOutputSnapshot {
+	exists: boolean;
+	mtimeMs?: number;
+	size?: number;
+}
+
 export function resolveSingleOutputPath(
 	output: string | false | undefined,
 	runtimeCwd: string,
@@ -19,6 +25,16 @@ export function injectSingleOutputInstruction(task: string, outputPath: string |
 	return `${task}\n\n---\n**Output:** Write your findings to: ${outputPath}`;
 }
 
+export function captureSingleOutputSnapshot(outputPath: string | undefined): SingleOutputSnapshot | undefined {
+	if (!outputPath) return undefined;
+	try {
+		const stat = fs.statSync(outputPath);
+		return { exists: true, mtimeMs: stat.mtimeMs, size: stat.size };
+	} catch {
+		return { exists: false };
+	}
+}
+
 export function persistSingleOutput(
 	outputPath: string | undefined,
 	fullOutput: string,
@@ -33,23 +49,47 @@ export function persistSingleOutput(
 	}
 }
 
+export function resolveSingleOutput(
+	outputPath: string | undefined,
+	fallbackOutput: string,
+	beforeRun: SingleOutputSnapshot | undefined,
+): { fullOutput: string; savedPath?: string; saveError?: string } {
+	if (!outputPath) return { fullOutput: fallbackOutput };
+
+	try {
+		const stat = fs.statSync(outputPath);
+		const changedSinceStart = !beforeRun?.exists
+			|| stat.mtimeMs !== beforeRun.mtimeMs
+			|| stat.size !== beforeRun.size;
+		if (changedSinceStart) {
+			return {
+				fullOutput: fs.readFileSync(outputPath, "utf-8"),
+				savedPath: outputPath,
+			};
+		}
+	} catch {}
+
+	const save = persistSingleOutput(outputPath, fallbackOutput);
+	if (save.savedPath) return { fullOutput: fallbackOutput, savedPath: save.savedPath };
+	return { fullOutput: fallbackOutput, saveError: save.error };
+}
+
 export function finalizeSingleOutput(params: {
 	fullOutput: string;
 	truncatedOutput?: string;
 	outputPath?: string;
 	exitCode: number;
+	savedPath?: string;
+	saveError?: string;
 }): { displayOutput: string; savedPath?: string; saveError?: string } {
 	let displayOutput = params.truncatedOutput || params.fullOutput;
-	if (params.outputPath && params.exitCode === 0) {
-		const save = persistSingleOutput(params.outputPath, params.fullOutput);
-		if (save.savedPath) {
-			displayOutput += `\n\n📄 Output saved to: ${save.savedPath}`;
-			return { displayOutput, savedPath: save.savedPath };
-		}
-		if (save.error) {
-			displayOutput += `\n\n⚠️ Failed to save output to: ${params.outputPath}\n${save.error}`;
-			return { displayOutput, saveError: save.error };
-		}
+	if (params.exitCode === 0 && params.savedPath) {
+		displayOutput += `\n\n📄 Output saved to: ${params.savedPath}`;
+		return { displayOutput, savedPath: params.savedPath };
+	}
+	if (params.exitCode === 0 && params.saveError && params.outputPath) {
+		displayOutput += `\n\n⚠️ Failed to save output to: ${params.outputPath}\n${params.saveError}`;
+		return { displayOutput, saveError: params.saveError };
 	}
 	return { displayOutput };
 }

package/skills.ts

@@ -187,7 +187,9 @@ function collectSettingsSkillPaths(cwd: string): string[] {
 function buildSkillPaths(cwd: string): string[] {
 	const defaultSkillPaths = [
 		path.join(cwd, CONFIG_DIR, "skills"),
+		path.join(cwd, ".agents", "skills"),
 		path.join(AGENT_DIR, "skills"),
+		path.join(os.homedir(), ".agents", "skills"),
 	];
 	const packagePaths = collectPackageSkillPaths(cwd);
 	const settingsPaths = collectSettingsSkillPaths(cwd);
@@ -203,10 +205,11 @@ function inferSkillSource(sourceInfo: { source: string; scope: string }, filePat
 	// Fallback: infer from file path when sourceInfo isn't specific enough
 	// (e.g. scope === "temporary" for skills loaded via explicit skillPaths)
 	const projectRoot = path.resolve(cwd, CONFIG_DIR);
-	const isProjectScoped = isWithinPath(filePath, projectRoot);
+	const altProjectRoot = path.resolve(cwd, ".agents");
+	const isProjectScoped = isWithinPath(filePath, projectRoot) || isWithinPath(filePath, altProjectRoot);
 	if (isProjectScoped) return "project";
 
-	const isUserScoped = isWithinPath(filePath, AGENT_DIR);
+	const isUserScoped = isWithinPath(filePath, AGENT_DIR) || isWithinPath(filePath, path.join(os.homedir(), ".agents"));
 	if (isUserScoped) return "user";
 
 	const globalRoot = getGlobalNpmRoot();