pi-subagents 0.12.2 → 0.12.4

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## [Unreleased]
 
+## [0.12.4] - 2026-04-04
+
+### Added
+- Added configurable subagent recursion depth controls with global `maxSubagentDepth` config and per-agent `maxSubagentDepth` frontmatter overrides. Child delegation now honors stricter inherited limits while still allowing per-agent tightening.
+- Added optional worktree setup hooks via extension config (`worktreeSetupHook`, `worktreeSetupHookTimeoutMs`). Hooks run once per created worktree, receive JSON over stdin, return JSON on stdout, and can declare synthetic helper paths (e.g. `.venv`, copied local config files) to exclude from patch capture.
+
+### Fixed
+- Added support for loading agents and skills from `.agents/` and `~/.agents/` directories.
+- Switched internal source imports from `.js` to `.ts` so the extension can be loaded directly from TypeScript sources under the strip-types/transform-types runtime path.
+- Declared pi runtime packages and `@sinclair/typebox` as peer dependencies so direct source-loading environments fail less often from missing package resolution.
+- Single-output runs now preserve agent-written file contents instead of overwriting them with the final assistant receipt, and artifacts/truncation now follow the authoritative saved file content.
+- Async/background runs now reuse the current Node executable and prefer the resolved current pi CLI path on all platforms, avoiding PATH drift from wrapped or version-pinned parent launches.
+
+### Changed
+- Added release documentation for TypeScript direct-runtime loading support and related package requirements.
+
 ## [0.12.2] - 2026-04-04
 
 ### Changed

package/README.md

@@ -69,6 +69,7 @@ output: context.md           # writes to {chain_dir}/context.md
 defaultReads: context.md     # comma-separated files to read
 defaultProgress: true        # maintain progress.md
 interactive: true            # (parsed but not enforced in v1)
+maxSubagentDepth: 1          # tighten nested delegation for this agent's children
 ---
 
 Your system prompt goes here (the markdown body after frontmatter).
@@ -303,7 +304,7 @@ Chains can be created from the Agents Manager template picker ("Blank Chain"), o
 - **Parallel-in-Chain**: Fan-out/fan-in patterns with `{ parallel: [...] }` steps within chains
 - **Worktree Isolation**: `worktree: true` gives each parallel agent its own git worktree, preventing filesystem conflicts during concurrent execution
 - **Chain Clarification TUI**: Interactive preview/edit of chain templates and behaviors before execution
-- **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`, `skill`)
+- **Agent Frontmatter Extensions**: Agents declare default chain behavior (`output`, `defaultReads`, `defaultProgress`, `skill`) plus optional recursion limits via `maxSubagentDepth`
 - **Chain Artifacts**: Shared directory at `<tmpdir>/pi-chain-runs/{runId}/` for inter-step files
 - **Solo Agent Output**: Agents with `output` write to temp dir and return path to caller
 - **Live Progress Display**: Real-time visibility during sync execution showing current tool, recent output, tokens, and duration
@@ -589,7 +590,7 @@ Agent definitions are not loaded into LLM context by default. Management actions
 Notes:
 - `create` uses `config.scope` (`"user"` or `"project"`), not `agentScope`.
 - `update`/`delete` use `agentScope` only for scope disambiguation when the same name exists in both scopes.
-- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, and `tools` supports `mcp:` entries that map to direct MCP tools.
+- Agent config mapping: `reads -> defaultReads`, `progress -> defaultProgress`, `extensions` controls extension sandboxing, `maxSubagentDepth` maps directly to agent frontmatter, and `tools` supports `mcp:` entries that map to direct MCP tools.
 - To clear any optional field, set it to `false` or `""` (e.g., `{ model: false }` or `{ skills: "" }`). Both work for all string-typed fields.
 
 ## Parameters
@@ -695,14 +696,17 @@ After the parallel step completes, per-agent diff stats are appended to the outp
 - Working tree must be clean (no uncommitted changes) — commit or stash first
 - `node_modules/` is symlinked into each worktree to avoid reinstalling
 - Worktree runs use the shared parallel/step `cwd`. Task-level `cwd` overrides must be omitted or match that shared `cwd`; if you need different working directories, disable `worktree` or split the run.
+- If `worktreeSetupHook` is configured, it must return valid JSON and complete before timeout
 
 **What happens under the hood:**
 
 1. `git worktree add` creates a temporary worktree per agent in `<tmpdir>/pi-worktree-*`
-2. Each agent runs in its worktree's cwd (preserving subdirectory context)
-3. After execution, `git add -A && git diff --cached` captures all changes (committed, modified, and new files)
-4. Diff stats appear in the aggregated output; full `.patch` files are written to the artifacts directory
-5. Worktrees and temp branches are cleaned up in a `finally` block
+2. Optional `worktreeSetupHook` runs once per worktree (JSON in on stdin, JSON out on stdout)
+3. Each agent runs in its worktree's cwd (preserving subdirectory context)
+4. Before diff capture, declared synthetic helper paths (for example `.venv` or copied local config files) are removed
+5. After execution, `git add -A && git diff --cached` captures all real changes (committed, modified, and new files)
+6. Diff stats appear in the aggregated output; full `.patch` files are written to the artifacts directory
+7. Worktrees and temp branches are cleaned up in a `finally` block
 
 If you use [pi-prompt-template-model](https://github.com/nicobailon/pi-prompt-template-model), worktree isolation is also available via `worktree: true` in chain template frontmatter or the `--worktree` CLI flag on `chain-prompts`. `pi-prompt-template-model` compare-style prompts can route through the same worktree machinery too; see the `pi-prompt-template-model` README and `examples/` directory for the installable prompt templates.
 
@@ -749,6 +753,54 @@ Session root resolution follows this precedence:
 
 Sessions are always enabled — every subagent run gets a session directory for tracking.
 
+### `maxSubagentDepth`
+
+`maxSubagentDepth` sets the default recursion limit for nested delegation when no inherited `PI_SUBAGENT_MAX_DEPTH` is already in effect. Eg:
+
+```json
+{
+  "maxSubagentDepth": 1
+}
+```
+
+Per-agent `maxSubagentDepth` can tighten that limit further for child runs, but it does not relax an already inherited stricter limit.
+
+### `worktreeSetupHook`
+
+`worktreeSetupHook` configures an optional setup hook for worktree-isolated parallel runs. The hook runs once per created worktree, after `git worktree add` succeeds and before the agent starts.
+
+```json
+{
+  "worktreeSetupHook": "./scripts/setup-worktree.mjs"
+}
+```
+
+Path rules:
+- Must be an absolute path or a repo-relative path
+- Bare command names from `PATH` are rejected
+- `~/...` is supported for home-directory hooks
+
+Hook I/O contract (JSON only):
+- stdin: one JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `index`, `runId`, and `baseCommit`
+- stdout: one JSON object, e.g. `{ "syntheticPaths": [".venv", ".env.local"] }`
+
+`syntheticPaths` must be relative to the worktree root. These paths are removed before diff capture so helper files/symlinks do not pollute generated patches.
+
+Tracked-file edits are never excluded. If the hook tries to mark tracked paths as synthetic, setup fails.
+
+### `worktreeSetupHookTimeoutMs`
+
+Optional timeout (milliseconds) for each worktree hook invocation.
+
+```json
+{
+  "worktreeSetupHook": "./scripts/setup-worktree.mjs",
+  "worktreeSetupHookTimeoutMs": 45000
+}
+```
+
+Default: `30000` ms.
+
 ## Chain Directory
 Each chain run creates `<tmpdir>/pi-chain-runs/{runId}/` containing:
 - `context.md` - Scout/context-builder output
@@ -821,6 +873,14 @@ Subagents can themselves call the `subagent` tool, which risks unbounded recursi
 
 By default nesting is limited to **2 levels**: `main session → subagent → sub-subagent`. Any deeper `subagent` calls are blocked and return an error with guidance to the calling agent.
 
+You can configure the limit in three places:
+
+1. `PI_SUBAGENT_MAX_DEPTH` in the environment before starting `pi`
+2. `config.maxSubagentDepth` in `~/.pi/agent/extensions/subagent/config.json`
+3. `maxSubagentDepth` in an agent's frontmatter to tighten the limit for that agent's child runs
+
+Environment inherits downward and wins for the current process. Per-agent limits can tighten child delegation but do not relax an already inherited stricter limit.
+
 Override the limit with `PI_SUBAGENT_MAX_DEPTH` **set before starting `pi`**:
 
 ```bash

package/agent-management.ts

@@ -9,11 +9,11 @@ import {
 	type ChainConfig,
 	type ChainStepConfig,
 	discoverAgentsAll,
-} from "./agents.js";
-import { serializeAgent } from "./agent-serializer.js";
-import { serializeChain } from "./chain-serializer.js";
-import { discoverAvailableSkills } from "./skills.js";
-import type { Details } from "./types.js";
+} from "./agents.ts";
+import { serializeAgent } from "./agent-serializer.ts";
+import { serializeChain } from "./chain-serializer.ts";
+import { discoverAvailableSkills } from "./skills.ts";
+import type { Details } from "./types.ts";
 
 type ManagementAction = "list" | "get" | "create" | "update" | "delete";
 type ManagementScope = "user" | "project";
@@ -235,6 +235,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		if (typeof cfg.progress !== "boolean") return "config.progress must be a boolean when provided.";
 		target.defaultProgress = cfg.progress;
 	}
+	if (hasKey(cfg, "maxSubagentDepth")) {
+		if (cfg.maxSubagentDepth === false || cfg.maxSubagentDepth === "") target.maxSubagentDepth = undefined;
+		else if (typeof cfg.maxSubagentDepth === "number" && Number.isInteger(cfg.maxSubagentDepth) && cfg.maxSubagentDepth >= 0) {
+			target.maxSubagentDepth = cfg.maxSubagentDepth;
+		} else return "config.maxSubagentDepth must be an integer >= 0 or false when provided.";
+	}
 	return undefined;
 }
 
@@ -293,6 +299,7 @@ export function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.output) lines.push(`Output: ${agent.output}`);
 	if (agent.defaultReads?.length) lines.push(`Reads: ${agent.defaultReads.join(", ")}`);
 	if (agent.defaultProgress) lines.push("Progress: true");
+	if (agent.maxSubagentDepth !== undefined) lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
 	if (agent.systemPrompt.trim()) lines.push("", "System Prompt:", agent.systemPrompt);
 	return lines.join("\n");
 }

package/agent-manager-chain-detail.ts

@@ -1,7 +1,7 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import type { ChainConfig, ChainStepConfig } from "./agents.js";
-import { row, renderFooter, renderHeader, formatPath, formatScrollInfo } from "./render-helpers.js";
+import type { ChainConfig, ChainStepConfig } from "./agents.ts";
+import { row, renderFooter, renderHeader, formatPath, formatScrollInfo } from "./render-helpers.ts";
 
 export interface ChainDetailState {
 	scrollOffset: number;

package/agent-manager-detail.ts

@@ -1,12 +1,12 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import type { AgentConfig } from "./agents.js";
-import { formatDuration } from "./formatters.js";
-import type { RunEntry } from "./run-history.js";
-import { buildSkillInjection, resolveSkills } from "./skills.js";
-import { ensureCursorVisible, getCursorDisplayPos, renderEditor, wrapText } from "./text-editor.js";
-import type { TextEditorState } from "./text-editor.js";
-import { pad, row, renderHeader, renderFooter, formatPath, formatScrollInfo } from "./render-helpers.js";
+import type { AgentConfig } from "./agents.ts";
+import { formatDuration } from "./formatters.ts";
+import type { RunEntry } from "./run-history.ts";
+import { buildSkillInjection, resolveSkills } from "./skills.ts";
+import { ensureCursorVisible, getCursorDisplayPos, renderEditor, wrapText } from "./text-editor.ts";
+import type { TextEditorState } from "./text-editor.ts";
+import { pad, row, renderHeader, renderFooter, formatPath, formatScrollInfo } from "./render-helpers.ts";
 
 export interface DetailState {
 	resolved: boolean;
@@ -58,6 +58,7 @@ function buildDetailLines(
 	const output = agent.output ?? "(none)";
 	const reads = agent.defaultReads && agent.defaultReads.length > 0 ? agent.defaultReads.join(", ") : "(none)";
 	const progress = agent.defaultProgress ? "on" : "off";
+	const maxSubagentDepth = agent.maxSubagentDepth !== undefined ? String(agent.maxSubagentDepth) : "(default)";
 
 	lines.push(renderFieldLine("Model:", agent.model ?? "default", contentWidth, theme));
 	lines.push(renderFieldLine("Thinking:", agent.thinking ?? "off", contentWidth, theme));
@@ -71,6 +72,7 @@ function buildDetailLines(
 	lines.push(renderFieldLine("Output:", output, contentWidth, theme));
 	lines.push(renderFieldLine("Reads:", reads, contentWidth, theme));
 	lines.push(renderFieldLine("Progress:", progress, contentWidth, theme));
+	lines.push(renderFieldLine("Max depth:", maxSubagentDepth, contentWidth, theme));
 
 	if (agent.extraFields) {
 		for (const [key, value] of Object.entries(agent.extraFields)) {

package/agent-manager-edit.ts

@@ -1,9 +1,9 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@mariozechner/pi-tui";
-import type { AgentConfig } from "./agents.js";
-import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.js";
-import type { TextEditorState } from "./text-editor.js";
-import { pad, row, renderHeader, renderFooter, formatScrollInfo } from "./render-helpers.js";
+import type { AgentConfig } from "./agents.ts";
+import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.ts";
+import type { TextEditorState } from "./text-editor.ts";
+import { pad, row, renderHeader, renderFooter, formatScrollInfo } from "./render-helpers.ts";
 
 export interface ModelInfo { provider: string; id: string; fullId: string; }
 export interface SkillInfo { name: string; source: string; description?: string; }

package/agent-manager-list.ts

@@ -1,7 +1,7 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
-import type { AgentSource } from "./agents.js";
+import type { AgentSource } from "./agents.ts";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import { pad, row, renderHeader, renderFooter, fuzzyFilter, formatScrollInfo } from "./render-helpers.js";
+import { pad, row, renderHeader, renderFooter, fuzzyFilter, formatScrollInfo } from "./render-helpers.ts";
 
 export interface ListAgent {
 	id: string;

package/agent-manager-parallel.ts

@@ -1,8 +1,8 @@
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import type { TextEditorState } from "./text-editor.js";
-import { createEditorState, handleEditorInput, renderEditor, wrapText, getCursorDisplayPos, ensureCursorVisible } from "./text-editor.js";
-import { pad, row, renderHeader, renderFooter, fuzzyFilter } from "./render-helpers.js";
+import type { TextEditorState } from "./text-editor.ts";
+import { createEditorState, handleEditorInput, renderEditor, wrapText, getCursorDisplayPos, ensureCursorVisible } from "./text-editor.ts";
+import { pad, row, renderHeader, renderFooter, fuzzyFilter } from "./render-helpers.ts";
 
 export interface ParallelSlot {
 	agentName: string;

package/agent-manager.ts

@@ -3,19 +3,19 @@ import * as path from "node:path";
 import type { Theme } from "@mariozechner/pi-coding-agent";
 import type { Component, TUI } from "@mariozechner/pi-tui";
 import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
-import type { AgentConfig, ChainConfig } from "./agents.js";
-import { serializeAgent } from "./agent-serializer.js";
-import { TEMPLATE_ITEMS, type AgentTemplate, type TemplateItem } from "./agent-templates.js";
-import { parseChain, serializeChain } from "./chain-serializer.js";
-import { renderList, handleListInput, type ListAgent, type ListState, type ListAction } from "./agent-manager-list.js";
-import { createParallelState, handleParallelInput, renderParallel, formatParallelTitle, type ParallelState, type AgentOption } from "./agent-manager-parallel.js";
-import { renderDetail, handleDetailInput, renderTaskInput, type DetailState, type DetailAction } from "./agent-manager-detail.js";
-import { renderChainDetail, handleChainDetailInput, type ChainDetailAction, type ChainDetailState } from "./agent-manager-chain-detail.js";
-import { createEditState, handleEditInput, renderEdit, type EditScreen, type EditState, type ModelInfo, type SkillInfo } from "./agent-manager-edit.js";
-import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.js";
-import type { TextEditorState } from "./text-editor.js";
-import { loadRunsForAgent } from "./run-history.js";
-import { pad, row, renderHeader, renderFooter } from "./render-helpers.js";
+import type { AgentConfig, ChainConfig } from "./agents.ts";
+import { serializeAgent } from "./agent-serializer.ts";
+import { TEMPLATE_ITEMS, type AgentTemplate, type TemplateItem } from "./agent-templates.ts";
+import { parseChain, serializeChain } from "./chain-serializer.ts";
+import { renderList, handleListInput, type ListAgent, type ListState, type ListAction } from "./agent-manager-list.ts";
+import { createParallelState, handleParallelInput, renderParallel, formatParallelTitle, type ParallelState, type AgentOption } from "./agent-manager-parallel.ts";
+import { renderDetail, handleDetailInput, renderTaskInput, type DetailState, type DetailAction } from "./agent-manager-detail.ts";
+import { renderChainDetail, handleChainDetailInput, type ChainDetailAction, type ChainDetailState } from "./agent-manager-chain-detail.ts";
+import { createEditState, handleEditInput, renderEdit, type EditScreen, type EditState, type ModelInfo, type SkillInfo } from "./agent-manager-edit.ts";
+import { createEditorState, ensureCursorVisible, getCursorDisplayPos, handleEditorInput, renderEditor, wrapText } from "./text-editor.ts";
+import type { TextEditorState } from "./text-editor.ts";
+import { loadRunsForAgent } from "./run-history.ts";
+import { pad, row, renderHeader, renderFooter } from "./render-helpers.ts";
 
 export type ManagerResult =
 	| { action: "launch"; agent: string; task: string; skipClarify?: boolean }
@@ -61,8 +61,22 @@ export class AgentManagerComponent implements Component {
 	private templateCursor = 0;
 	private statusMessage?: StatusMessage;
 	private nextId = 1;
+	private tui: TUI;
+	private theme: Theme;
+	private agentData: AgentData;
+	private models: ModelInfo[];
+	private skills: SkillInfo[];
+	private done: (result: ManagerResult) => void;
 
-	constructor(private tui: TUI, private theme: Theme, private agentData: AgentData, private models: ModelInfo[], private skills: SkillInfo[], private done: (result: ManagerResult) => void) { this.loadEntries(); }
+	constructor(tui: TUI, theme: Theme, agentData: AgentData, models: ModelInfo[], skills: SkillInfo[], done: (result: ManagerResult) => void) {
+		this.tui = tui;
+		this.theme = theme;
+		this.agentData = agentData;
+		this.models = models;
+		this.skills = skills;
+		this.done = done;
+		this.loadEntries();
+	}
 
 	private loadEntries(): void {
 		const overridden = new Set([...this.agentData.user, ...this.agentData.project].map((c) => c.name));

package/agent-scope.ts

@@ -1,4 +1,4 @@
-import type { AgentScope } from "./agents.js";
+import type { AgentScope } from "./agents.ts";
 
 export function resolveExecutionAgentScope(scope: unknown): AgentScope {
 	if (scope === "user" || scope === "project" || scope === "both") return scope;

package/agent-selection.ts

@@ -1,4 +1,4 @@
-import type { AgentScope, AgentConfig } from "./agents.js";
+import type { AgentScope, AgentConfig } from "./agents.ts";
 
 export function mergeAgentsForScope(
 	scope: AgentScope,

package/agent-serializer.ts

@@ -1,5 +1,5 @@
 import * as fs from "node:fs";
-import type { AgentConfig } from "./agents.js";
+import type { AgentConfig } from "./agents.ts";
 
 export const KNOWN_FIELDS = new Set([
 	"name",
@@ -14,6 +14,7 @@ export const KNOWN_FIELDS = new Set([
 	"defaultReads",
 	"defaultProgress",
 	"interactive",
+	"maxSubagentDepth",
 ]);
 
 function joinComma(values: string[] | undefined): string | undefined {
@@ -52,6 +53,9 @@ export function serializeAgent(config: AgentConfig): string {
 
 	if (config.defaultProgress) lines.push("defaultProgress: true");
 	if (config.interactive) lines.push("interactive: true");
+	if (Number.isInteger(config.maxSubagentDepth) && config.maxSubagentDepth >= 0) {
+		lines.push(`maxSubagentDepth: ${config.maxSubagentDepth}`);
+	}
 
 	if (config.extraFields) {
 		for (const [key, value] of Object.entries(config.extraFields)) {

package/agent-templates.ts

@@ -1,4 +1,4 @@
-import type { AgentConfig } from "./agents.js";
+import type { AgentConfig } from "./agents.ts";
 
 export interface AgentTemplate {
 	name: string;

package/agents.ts

@@ -6,10 +6,10 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { KNOWN_FIELDS } from "./agent-serializer.js";
-import { parseChain } from "./chain-serializer.js";
-import { mergeAgentsForScope } from "./agent-selection.js";
-import { parseFrontmatter } from "./frontmatter.js";
+import { KNOWN_FIELDS } from "./agent-serializer.ts";
+import { parseChain } from "./chain-serializer.ts";
+import { mergeAgentsForScope } from "./agent-selection.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -32,6 +32,7 @@ export interface AgentConfig {
 	defaultReads?: string[];
 	defaultProgress?: boolean;
 	interactive?: boolean;
+	maxSubagentDepth?: number;
 	extraFields?: Record<string, string>;
 }
 
@@ -134,6 +135,8 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			if (!KNOWN_FIELDS.has(key)) extraFields[key] = value;
 		}
 
+		const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+
 		agents.push({
 			name: frontmatter.name,
 			description: frontmatter.description,
@@ -151,6 +154,10 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,
 			defaultProgress: frontmatter.defaultProgress === "true",
 			interactive: frontmatter.interactive === "true",
+			maxSubagentDepth:
+				Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0
+					? parsedMaxSubagentDepth
+					: undefined,
 			extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
 		});
 	}
@@ -205,6 +212,9 @@ function isDirectory(p: string): boolean {
 function findNearestProjectAgentsDir(cwd: string): string | null {
 	let currentDir = cwd;
 	while (true) {
+		const candidateAlt = path.join(currentDir, ".agents");
+		if (isDirectory(candidateAlt)) return candidateAlt;
+
 		const candidate = path.join(currentDir, ".pi", "agents");
 		if (isDirectory(candidate)) return candidate;
 
@@ -217,11 +227,16 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 const BUILTIN_AGENTS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), "agents");
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
-	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const userDirOld = path.join(os.homedir(), ".pi", "agent", "agents");
+	const userDirNew = path.join(os.homedir(), ".agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
 	const builtinAgents = loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
-	const userAgents = scope === "project" ? [] : loadAgentsFromDir(userDir, "user");
+	
+	const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
+	const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
+	const userAgents = [...userAgentsOld, ...userAgentsNew];
+
 	const projectAgents = scope === "user" || !projectAgentsDir ? [] : loadAgentsFromDir(projectAgentsDir, "project");
 	const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents);
 
@@ -236,16 +251,23 @@ export function discoverAgentsAll(cwd: string): {
 	userDir: string;
 	projectDir: string | null;
 } {
-	const userDir = path.join(os.homedir(), ".pi", "agent", "agents");
+	const userDirOld = path.join(os.homedir(), ".pi", "agent", "agents");
+	const userDirNew = path.join(os.homedir(), ".agents");
 	const projectDir = findNearestProjectAgentsDir(cwd);
 
 	const builtin = loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin");
-	const user = loadAgentsFromDir(userDir, "user");
+	const user = [
+		...loadAgentsFromDir(userDirOld, "user"),
+		...loadAgentsFromDir(userDirNew, "user"),
+	];
 	const project = projectDir ? loadAgentsFromDir(projectDir, "project") : [];
 	const chains = [
-		...loadChainsFromDir(userDir, "user"),
+		...loadChainsFromDir(userDirOld, "user"),
+		...loadChainsFromDir(userDirNew, "user"),
 		...(projectDir ? loadChainsFromDir(projectDir, "project") : []),
 	];
 
+	const userDir = fs.existsSync(userDirNew) ? userDirNew : userDirOld;
+
 	return { builtin, user, project, chains, userDir, projectDir };
 }

package/artifacts.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import type { ArtifactPaths } from "./types.js";
+import type { ArtifactPaths } from "./types.ts";
 
 const TEMP_ARTIFACTS_DIR = path.join(os.tmpdir(), "pi-subagent-artifacts");
 const CLEANUP_MARKER_FILE = ".last-cleanup";

package/async-execution.ts

@@ -9,20 +9,21 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import type { AgentConfig } from "./agents.js";
-import { applyThinkingSuffix } from "./pi-args.js";
-import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.js";
-import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.js";
-import type { RunnerStep } from "./parallel-utils.js";
-import { resolvePiPackageRoot } from "./pi-spawn.js";
-import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.js";
+import type { AgentConfig } from "./agents.ts";
+import { applyThinkingSuffix } from "./pi-args.ts";
+import { injectSingleOutputInstruction, resolveSingleOutputPath } from "./single-output.ts";
+import { isParallelStep, resolveStepBehavior, type ChainStep, type SequentialStep, type StepOverrides } from "./settings.ts";
+import type { RunnerStep } from "./parallel-utils.ts";
+import { resolvePiPackageRoot } from "./pi-spawn.ts";
+import { buildSkillInjection, normalizeSkillInput, resolveSkills } from "./skills.ts";
 import {
 	type ArtifactConfig,
 	type Details,
 	type MaxOutputConfig,
 	ASYNC_DIR,
 	RESULTS_DIR,
-} from "./types.js";
+	resolveChildMaxSubagentDepth,
+} from "./types.ts";
 
 const require = createRequire(import.meta.url);
 const piPackageRoot = resolvePiPackageRoot();
@@ -65,6 +66,9 @@ export interface AsyncChainParams {
 	sessionRoot?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	maxSubagentDepth: number;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
 }
 
 export interface AsyncSingleParams {
@@ -81,6 +85,9 @@ export interface AsyncSingleParams {
 	sessionFile?: string;
 	skills?: string[];
 	output?: string | false;
+	maxSubagentDepth: number;
+	worktreeSetupHook?: string;
+	worktreeSetupHookTimeoutMs?: number;
 }
 
 export interface AsyncExecutionResult {
@@ -106,7 +113,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string): number | undefin
 	fs.writeFileSync(cfgPath, JSON.stringify(cfg));
 	const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
 	
-	const proc = spawn("node", [jitiCliPath, runner, cfgPath], {
+	const proc = spawn(process.execPath, [jitiCliPath, runner, cfgPath], {
 		cwd,
 		detached: true,
 		stdio: "ignore",
@@ -134,6 +141,9 @@ export function executeAsyncChain(
 		shareEnabled,
 		sessionRoot,
 		sessionFilesByFlatIndex,
+		maxSubagentDepth,
+		worktreeSetupHook,
+		worktreeSetupHookTimeoutMs,
 	} = params;
 	const chainSkills = params.chainSkills ?? [];
 
@@ -197,6 +207,7 @@ export function executeAsyncChain(
 			skills: resolvedSkills.map((r) => r.name),
 			outputPath,
 			sessionFile,
+			maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, a.maxSubagentDepth),
 		};
 	};
 
@@ -244,6 +255,8 @@ export function executeAsyncChain(
 			asyncDir,
 			sessionId: ctx.currentSessionId,
 			piPackageRoot,
+			worktreeSetupHook,
+			worktreeSetupHookTimeoutMs,
 		},
 		id,
 		runnerCwd,
@@ -301,6 +314,9 @@ export function executeAsyncSingle(
 		shareEnabled,
 		sessionRoot,
 		sessionFile,
+		maxSubagentDepth,
+		worktreeSetupHook,
+		worktreeSetupHookTimeoutMs,
 	} = params;
 	const skillNames = params.skills ?? agentConfig.skills ?? [];
 	const { resolved: resolvedSkills } = resolveSkills(skillNames, ctx.cwd);
@@ -341,6 +357,7 @@ export function executeAsyncSingle(
 					skills: resolvedSkills.map((r) => r.name),
 					outputPath,
 					sessionFile,
+					maxSubagentDepth: resolveChildMaxSubagentDepth(maxSubagentDepth, agentConfig.maxSubagentDepth),
 				},
 			],
 			resultPath: path.join(RESULTS_DIR, `${id}.json`),
@@ -354,6 +371,8 @@ export function executeAsyncSingle(
 			asyncDir,
 			sessionId: ctx.currentSessionId,
 			piPackageRoot,
+			worktreeSetupHook,
+			worktreeSetupHookTimeoutMs,
 		},
 		id,
 		runnerCwd,