pi-subagents 0.30.0 → 0.31.0

package/src/agents/skills.ts

@@ -6,7 +6,7 @@ import { execSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir } from "../shared/utils.ts";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 
 export type SkillSource =
 	| "project"
@@ -23,6 +23,7 @@ interface ResolvedSkill {
 	name: string;
 	path: string;
 	content: string;
+	description?: string;
 	source: SkillSource;
 }
 
@@ -50,7 +51,6 @@ const MAX_CACHE_SIZE = 50;
 let loadSkillsCache: { cwd: string; agentDir: string; skills: CachedSkillEntry[]; timestamp: number } | null = null;
 const LOAD_SKILLS_CACHE_TTL_MS = 5000;
 
-const CONFIG_DIR = ".pi";
 const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
 
 const SOURCE_PRIORITY: Record<SkillSource, number> = {
@@ -134,8 +134,9 @@ function getGlobalNpmRoot(): string | null {
 }
 
 function collectInstalledPackageSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
+	const projectConfigDir = getProjectConfigDir(cwd);
 	const dirs: SkillSearchPath[] = [
-		{ path: path.join(cwd, CONFIG_DIR, "npm", "node_modules"), source: "project-package" },
+		{ path: path.join(projectConfigDir, "npm", "node_modules"), source: "project-package" },
 		{ path: path.join(agentDir, "npm", "node_modules"), source: "user-package" },
 	];
 
@@ -186,8 +187,9 @@ function collectInstalledPackageSkillPaths(cwd: string, agentDir: string): Skill
 
 function collectSettingsSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 	const results: SkillSearchPath[] = [];
+	const projectConfigDir = getProjectConfigDir(cwd);
 	const settingsFiles = [
-		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-settings" as const },
+		{ file: path.join(projectConfigDir, "settings.json"), base: projectConfigDir, source: "project-settings" as const },
 		{ file: path.join(agentDir, "settings.json"), base: agentDir, source: "user-settings" as const },
 	];
 
@@ -286,8 +288,9 @@ function resolveSettingsPackageRoot(source: string, baseDir: string): string | u
 }
 
 function collectSettingsPackageSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
+	const projectConfigDir = getProjectConfigDir(cwd);
 	const settingsFiles = [
-		{ file: path.join(cwd, CONFIG_DIR, "settings.json"), base: path.join(cwd, CONFIG_DIR), source: "project-package" as const },
+		{ file: path.join(projectConfigDir, "settings.json"), base: projectConfigDir, source: "project-package" as const },
 		{ file: path.join(agentDir, "settings.json"), base: agentDir, source: "user-package" as const },
 	];
 	const results: SkillSearchPath[] = [];
@@ -316,8 +319,9 @@ function collectSettingsPackageSkillPaths(cwd: string, agentDir: string): SkillS
 }
 
 function buildSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
+	const projectConfigDir = getProjectConfigDir(cwd);
 	const skillPaths: SkillSearchPath[] = [
-		{ path: path.join(cwd, CONFIG_DIR, "skills"), source: "project" },
+		{ path: path.join(projectConfigDir, "skills"), source: "project" },
 		{ path: path.join(cwd, ".agents", "skills"), source: "project" },
 		{ path: path.join(agentDir, "skills"), source: "user" },
 		{ path: path.join(os.homedir(), ".agents", "skills"), source: "user" },
@@ -330,7 +334,8 @@ function buildSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 	const deduped = new Map<string, SkillSearchPath>();
 	for (const entry of skillPaths) {
 		const resolvedPath = path.resolve(entry.path);
-		if (!deduped.has(resolvedPath)) {
+		const existing = deduped.get(resolvedPath);
+		if (!existing || (SOURCE_PRIORITY[entry.source] ?? 0) > (SOURCE_PRIORITY[existing.source] ?? 0)) {
 			deduped.set(resolvedPath, { path: resolvedPath, source: entry.source });
 		}
 	}
@@ -340,9 +345,9 @@ function buildSkillPaths(cwd: string, agentDir: string): SkillSearchPath[] {
 function inferSkillSource(filePath: string, cwd: string, agentDir: string, sourceHint?: SkillSource): SkillSource {
 	if (sourceHint) return sourceHint;
 
-	const projectConfigRoot = path.resolve(cwd, CONFIG_DIR);
-	const projectSkillsRoot = path.resolve(cwd, CONFIG_DIR, "skills");
-	const projectPackagesRoot = path.resolve(cwd, CONFIG_DIR, "npm", "node_modules");
+	const projectConfigRoot = path.resolve(getProjectConfigDir(cwd));
+	const projectSkillsRoot = path.resolve(projectConfigRoot, "skills");
+	const projectPackagesRoot = path.resolve(projectConfigRoot, "npm", "node_modules");
 	const projectAgentsRoot = path.resolve(cwd, ".agents");
 	const userSkillsRoot = path.resolve(agentDir, "skills");
 	const userPackagesRoot = path.resolve(agentDir, "npm", "node_modules");
@@ -393,23 +398,86 @@ function maybeReadSkillDescription(filePath: string): string | undefined {
 
 function collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: SkillSearchPath[]): CachedSkillEntry[] {
 	const entries: CachedSkillEntry[] = [];
-	const seen = new Set<string>();
+	const seen = new Map<string, number>();
+	const visitedDirectories = new Map<string, number>();
 	let order = 0;
 
 	const pushEntry = (name: string, filePath: string, sourceHint?: SkillSource) => {
 		const resolvedFile = path.resolve(filePath);
-		if (seen.has(resolvedFile)) return;
 		if (!fs.existsSync(resolvedFile)) return;
-		seen.add(resolvedFile);
+		const source = inferSkillSource(resolvedFile, cwd, agentDir, sourceHint);
+		const existingIndex = seen.get(resolvedFile);
+		if (existingIndex !== undefined) {
+			const existing = entries[existingIndex];
+			if (existing && (SOURCE_PRIORITY[source] ?? 0) > (SOURCE_PRIORITY[existing.source] ?? 0)) {
+				entries[existingIndex] = {
+					...existing,
+					name,
+					source,
+					description: maybeReadSkillDescription(resolvedFile),
+				};
+			}
+			return;
+		}
+		seen.set(resolvedFile, entries.length);
 		entries.push({
 			name,
 			filePath: resolvedFile,
-			source: inferSkillSource(resolvedFile, cwd, agentDir, sourceHint),
+			source,
 			description: maybeReadSkillDescription(resolvedFile),
 			order: order++,
 		});
 	};
 
+	const shouldSkipDirectory = (name: string) => name.startsWith(".") || name === "node_modules";
+
+	const markDirectoryVisited = (dirPath: string, sourceHint?: SkillSource): boolean => {
+		let resolvedDir: string;
+		try {
+			resolvedDir = fs.realpathSync(dirPath);
+		} catch {
+			resolvedDir = path.resolve(dirPath);
+		}
+		const priority = sourceHint ? SOURCE_PRIORITY[sourceHint] ?? 0 : SOURCE_PRIORITY.unknown;
+		const previousPriority = visitedDirectories.get(resolvedDir);
+		if (previousPriority !== undefined && previousPriority >= priority) return false;
+		visitedDirectories.set(resolvedDir, priority);
+		return true;
+	};
+
+	const walkSkillDirectories = (dirPath: string, sourceHint?: SkillSource) => {
+		if (!markDirectoryVisited(dirPath, sourceHint)) return;
+
+		const skillFile = path.join(dirPath, "SKILL.md");
+		if (fs.existsSync(skillFile)) {
+			pushEntry(path.basename(dirPath), skillFile, sourceHint);
+			return;
+		}
+
+		let entriesInDir: fs.Dirent[];
+		try {
+			entriesInDir = fs.readdirSync(dirPath, { withFileTypes: true });
+		} catch {
+			return;
+		}
+
+		for (const entry of entriesInDir) {
+			if (shouldSkipDirectory(entry.name)) continue;
+			if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+
+			const entryPath = path.join(dirPath, entry.name);
+			let stat: fs.Stats;
+			try {
+				stat = fs.statSync(entryPath);
+			} catch {
+				continue;
+			}
+			if (stat.isDirectory()) {
+				walkSkillDirectories(entryPath, sourceHint);
+			}
+		}
+	};
+
 	for (const skillPath of skillPaths) {
 		if (!fs.existsSync(skillPath.path)) continue;
 
@@ -435,8 +503,11 @@ function collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: Skil
 		const rootSkillFile = path.join(skillPath.path, "SKILL.md");
 		if (fs.existsSync(rootSkillFile)) {
 			pushEntry(path.basename(skillPath.path), rootSkillFile, skillPath.source);
+			continue;
 		}
 
+		markDirectoryVisited(skillPath.path, skillPath.source);
+
 		let childEntries: fs.Dirent[];
 		try {
 			childEntries = fs.readdirSync(skillPath.path, { withFileTypes: true });
@@ -448,10 +519,14 @@ function collectFilesystemSkills(cwd: string, agentDir: string, skillPaths: Skil
 			if (child.name.startsWith(".")) continue;
 			const childPath = path.join(skillPath.path, child.name);
 			if (child.isDirectory() || child.isSymbolicLink()) {
-				const nestedSkillPath = path.join(childPath, "SKILL.md");
-				if (fs.existsSync(nestedSkillPath)) {
-					pushEntry(child.name, nestedSkillPath, skillPath.source);
+				if (shouldSkipDirectory(child.name)) continue;
+				let childStat: fs.Stats;
+				try {
+					childStat = fs.statSync(childPath);
+				} catch {
+					continue;
 				}
+				if (childStat.isDirectory()) walkSkillDirectories(childPath, skillPath.source);
 				continue;
 			}
 			if (child.isFile() && child.name.toLowerCase().endsWith(".md")) {
@@ -508,10 +583,12 @@ function readSkill(
 
 		const raw = fs.readFileSync(skillPath, "utf-8");
 		const content = stripSkillFrontmatter(raw);
+		const description = maybeReadSkillDescription(skillPath);
 		const skill: ResolvedSkill = {
 			name: skillName,
 			path: skillPath,
 			content,
+			description,
 			source,
 		};
 
@@ -579,9 +656,29 @@ export function resolveSkillsWithFallback(
 export function buildSkillInjection(skills: ResolvedSkill[]): string {
 	if (skills.length === 0) return "";
 
-	return skills
-		.map((s) => `<skill name="${s.name}">\n${s.content}\n</skill>`)
-		.join("\n\n");
+	const lines = [
+		"The following configured skills are available to this subagent.",
+		"Use the read tool to load a skill's file when the task matches its description.",
+		"When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.",
+		"",
+		"<available_skills>",
+	];
+	for (const skill of skills) {
+		lines.push("  <skill>");
+		lines.push(`    <name>${escapeXmlText(skill.name)}</name>`);
+		lines.push(`    <description>${escapeXmlText(skill.description ?? "")}</description>`);
+		lines.push(`    <location>${escapeXmlText(skill.path)}</location>`);
+		lines.push("  </skill>");
+	}
+	lines.push("</available_skills>");
+	return lines.join("\n");
+}
+
+function escapeXmlText(value: string): string {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
 }
 
 export function normalizeSkillInput(

package/src/extension/doctor.ts

@@ -168,6 +168,23 @@ function formatIntercomDiagnostic(diagnostic: IntercomBridgeDiagnostic, context:
 	return lines;
 }
 
+function formatPermissionSystemSection(): string[] {
+	const lines: string[] = [];
+	const parentSession = process.env["PI_SUBAGENT_PARENT_SESSION"] ?? "";
+	const trimmed = parentSession.trim();
+	if (trimmed) {
+		lines.push(`- parent session: set (${trimmed})`);
+	} else {
+		lines.push("- parent session: not set — ask forwarding from subprocess children will not reach a parent UI");
+	}
+	const isChild = process.env["PI_SUBAGENT_CHILD"] === "1";
+	lines.push(`- subagent process: ${isChild ? "yes (PI_SUBAGENT_CHILD=1)" : "no"}`);
+	// Whether pi-permission-system is installed and where it stores config is
+	// outside pi-subagents' control, so we only report the forwarding signal we
+	// own. Run `pi list` to confirm the permission extension is installed.
+	return lines;
+}
+
 export function buildDoctorReport(input: DoctorReportInput): string {
 	const paths = input.paths ?? DEFAULT_PATHS;
 	const deps = { ...DEFAULT_DEPS, ...input.deps };
@@ -188,6 +205,9 @@ export function buildDoctorReport(input: DoctorReportInput): string {
 		"Discovery",
 		...formatDiscovery(input, deps),
 		"",
+		"Permission system",
+		...formatPermissionSystemSection(),
+		"",
 		"Intercom bridge",
 		...lineFromCheck("intercom bridge", () => formatIntercomDiagnostic(deps.diagnoseIntercomBridge({
 			config: input.config.intercomBridge,

package/src/extension/fanout-child.ts

@@ -30,6 +30,7 @@ function createChildSafeState(): SubagentState {
 	return {
 		baseCwd: "",
 		currentSessionId: null,
+		subagentInProgress: false,
 		asyncJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),

package/src/extension/index.ts

@@ -33,7 +33,7 @@ import { registerSlashSubagentBridge } from "../slash/slash-bridge.ts";
 import { clearSlashSnapshots, getSlashRenderableSnapshot, resolveSlashMessageDetails, restoreSlashFinalSnapshots, type SlashMessageDetails } from "../slash/slash-live-state.ts";
 import { inspectSubagentStatus } from "../runs/background/run-status.ts";
 import registerSubagentNotify, { type SubagentNotifyDetails } from "../runs/background/notify.ts";
-import { SUBAGENT_CHILD_ENV } from "../runs/shared/pi-args.ts";
+import { SUBAGENT_CHILD_ENV, SUBAGENT_PARENT_SESSION_ENV } from "../runs/shared/pi-args.ts";
 import { formatDuration, shortenPath } from "../shared/formatters.ts";
 import { loadConfig } from "./config.ts";
 import {
@@ -106,6 +106,30 @@ function isSlashResultRunning(result: { details?: Details }): boolean {
 		|| false;
 }
 
+// Drives the inline running-indicator braille animation for foreground subagent
+// results. Foreground runs receive progress only on child events, so the glyph
+// (derived from progress fields) would freeze between events. While a result is
+// running we tick a frame counter + invalidate() every 80ms so renderSubagentResult
+// can blend the frame into runningGlyph and produce a smooth spinner.
+function subagentResultIsRunning(result: { details?: Details }): boolean {
+	return result.details?.progress?.some((entry) => entry.status === "running")
+		|| result.details?.results.some((entry) => entry.progress?.status === "running")
+		|| false;
+}
+
+function ensureSubagentResultAnimation(context: { state: Record<string, unknown>; invalidate?: () => void }): void {
+	const state = context.state as { subagentResultAnimationTimer?: ReturnType<typeof setInterval>; frame?: number };
+	if (state.subagentResultAnimationTimer) return;
+	if (typeof context.invalidate !== "function") return;
+	if (state.frame === undefined) state.frame = 0;
+	state.subagentResultAnimationTimer = setInterval(() => {
+		state.frame = ((state.frame ?? 0) + 1) % 10;
+		try {
+			context.invalidate();
+		} catch {}
+	}, 80);
+}
+
 function isSlashResultError(result: { details?: Details }): boolean {
 	return result.details?.results.some((entry) => entry.exitCode !== 0 && entry.progress?.status !== "running") || false;
 }
@@ -233,6 +257,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
 	const state: SubagentState = {
 		baseCwd: "",
 		currentSessionId: null,
+		subagentInProgress: false,
 		asyncJobs: new Map(),
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
@@ -392,7 +417,7 @@ EXECUTION (use exactly ONE mode):
 • SINGLE: { agent, task? } - one task; omit task for self-contained agents
 • CHAIN: { chain: [{agent:"agent-a"}, {parallel:[{agent:"agent-b",count:3}]}] } - sequential pipeline with optional parallel fan-out
 • PARALLEL: { tasks: [{agent,task,count?,output?,reads?,progress?}, ...], concurrency?: number, worktree?: true } - concurrent execution (worktree: isolate each task in a git worktree)
-• Optional context: { context: "fresh" | "fork" } (default: if any requested agent has defaultContext: "fork", the whole invocation uses fork; otherwise "fresh"; inspect agent defaults via { action: "list" })
+• Optional context: { context: "fresh" | "fork" } (explicit value overrides every child; when omitted, each requested agent uses its own defaultContext, otherwise "fresh"; inspect agent defaults via { action: "list" })
 • If { action: "list" } shows proactive skill subagent suggestions, consider a small fresh-context fanout for broad tasks where one of those skills would materially help
 
 CHAIN TEMPLATE VARIABLES (use in task strings):
@@ -405,6 +430,7 @@ Example: { chain: [{agent:"agent-a", task:"Analyze {task}"}, {agent:"agent-b", t
 MANAGEMENT (use action field, omit agent/task/chain/tasks):
 • { action: "list" } - discover executable agents/chains
 • { action: "get", agent: "name" } - full detail; packaged agents use dotted runtime names like "package.agent"
+• { action: "models", agent?: "name" } - show the runtime-loaded builtin subagent model mapping, optionally filtered to one builtin
 • { action: "create", config: { name: "custom-agent", package: "code-analysis", systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext, ... } }
 • { action: "update", agent: "code-analysis.custom-agent", config: { package: "analysis", ... } } - merge
 • { action: "delete", agent: "code-analysis.custom-agent" }
@@ -455,8 +481,13 @@ DIAGNOSTICS:
 		},
 
 		renderResult(result, options, theme, context) {
-			clearLegacyResultAnimationTimer(context);
-			return renderSubagentResult(result, options, theme);
+			if (subagentResultIsRunning(result)) {
+				ensureSubagentResultAnimation(context);
+			} else {
+				clearLegacyResultAnimationTimer(context);
+			}
+			const frame = (context.state as { frame?: number } | undefined)?.frame ?? 0;
+			return renderSubagentResult(result, options, theme, frame);
 		},
 
 	};
@@ -522,6 +553,17 @@ DIAGNOSTICS:
 	const resetSessionState = (ctx: ExtensionContext) => {
 		state.baseCwd = ctx.cwd;
 		state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+		// Set PI_SUBAGENT_PARENT_SESSION for permission-system forwarding.
+		// Only set in the root session (the interactive UI session), not in
+		// child subagent processes — children inherit the parent's value
+		// through the process environment at spawn time and must not overwrite
+		// it with their own session identity.
+		if (!process.env[SUBAGENT_CHILD_ENV]) {
+			const sessionId = ctx.sessionManager.getSessionId();
+			if (sessionId) {
+				process.env[SUBAGENT_PARENT_SESSION_ENV] = sessionId;
+			}
+		}
 		state.lastUiContext = ctx;
 		cleanupSessionArtifacts(ctx);
 		clearPendingForegroundControlNotices(state);
@@ -535,6 +577,7 @@ DIAGNOSTICS:
 	});
 
 	pi.on("session_shutdown", () => {
+		delete process.env[SUBAGENT_PARENT_SESSION_ENV];
 		for (const unsubscribe of eventUnsubscribes) {
 			try {
 				unsubscribe();

package/src/extension/schemas.ts

@@ -36,7 +36,7 @@ const SkillOverride = Type.Unsafe({
 		{ type: "boolean" },
 		{ type: "string" },
 	],
-	description: "Skill name(s) to inject (comma-separated), array of strings, or boolean (false disables, true uses default)",
+	description: "Skill name(s) to make available (comma-separated), array of strings, or boolean (false disables, true uses default)",
 });
 
 const OutputOverride = Type.Unsafe({
@@ -66,72 +66,11 @@ const JsonSchemaObject = Type.Unsafe({
 	description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
 });
 
-const AcceptanceEvidenceKind = Type.String({
-	enum: [
-		"changed-files",
-		"tests-added",
-		"commands-run",
-		"validation-output",
-		"residual-risks",
-		"no-staged-files",
-		"diff-summary",
-		"review-findings",
-		"manual-notes",
-	],
-});
-
-const AcceptanceGateSchema = Type.Object({
-	id: Type.String(),
-	must: Type.String(),
-	evidence: Type.Optional(Type.Array(AcceptanceEvidenceKind)),
-	severity: Type.Optional(Type.String({ enum: ["required", "recommended"] })),
-}, { additionalProperties: false });
-
-const AcceptanceVerifyCommandSchema = Type.Object({
-	id: Type.String(),
-	command: Type.String(),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1 })),
-	cwd: Type.Optional(Type.String()),
-	env: Type.Optional(Type.Unsafe({ type: "object", additionalProperties: { type: "string" } })),
-	allowFailure: Type.Optional(Type.Boolean()),
-}, { additionalProperties: false });
-
-const AcceptanceReviewGateSchema = Type.Object({
-	agent: Type.Optional(Type.String()),
-	focus: Type.Optional(Type.String()),
-	required: Type.Optional(Type.Boolean()),
-}, { additionalProperties: false });
-
 const AcceptanceOverride = Type.Unsafe({
 	anyOf: [
 		{ type: "string", enum: ["auto", "none", "attested", "checked", "verified", "reviewed"] },
-		{ const: false },
-		{
-			type: "object",
-			properties: {
-				level: { type: "string", enum: ["auto", "none", "attested", "checked", "verified", "reviewed"] },
-				criteria: {
-					type: "array",
-					items: {
-						anyOf: [
-							{ type: "string" },
-							AcceptanceGateSchema,
-						],
-					},
-				},
-				evidence: { type: "array", items: AcceptanceEvidenceKind },
-				verify: { type: "array", items: AcceptanceVerifyCommandSchema },
-				review: {
-					anyOf: [
-						{ const: false },
-						AcceptanceReviewGateSchema,
-					],
-				},
-				stopRules: { type: "array", items: { type: "string" } },
-				reason: { type: "string" },
-			},
-			additionalProperties: false,
-		},
+		{ type: "boolean", enum: [false] },
+		{ type: "object", additionalProperties: true },
 	],
 	description: "Optional acceptance policy. Omitted means auto-inferred; verified requires configured runtime commands.",
 });
@@ -236,11 +175,6 @@ const ChainItem = Type.Object({
 }, {
 	description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, or {expand, parallel: {...}, collect} for dynamic fanout.",
 	additionalProperties: false,
-	allOf: [
-		{ if: { required: ["expand"] }, then: { required: ["parallel", "collect"], properties: { parallel: { type: "object" } } } },
-		{ if: { required: ["collect"] }, then: { required: ["expand", "parallel"], properties: { parallel: { type: "object" } } } },
-		{ not: { required: ["expand"], properties: { parallel: { type: "array", items: {} } } } },
-	],
 });
 
 const ControlOverrides = Type.Object({
@@ -287,22 +221,22 @@ const SubagentParamsSchema = Type.Object({
 			{ type: "object", additionalProperties: true },
 			{ type: "string" },
 		],
-		description: "Agent or chain config for create/update. Agent: name, package (optional namespace; runtime name becomes package.name), description, scope ('user'|'project', default 'user'), systemPrompt, systemPromptMode, inheritProjectContext, inheritSkills, defaultContext ('fresh'|'fork'), model, tools (comma-separated), extensions (comma-separated), subagentOnlyExtensions (comma-separated child-only extension paths), skills (comma-separated), thinking, output, reads, progress, maxSubagentDepth. Chain: name, package, description, scope, steps (array of {agent, task?, output?, outputMode?, reads?, model?, skill?, progress?}). Presence of 'steps' creates a chain instead of an agent. String values must be valid JSON."
+		description: "Agent/chain config for create/update. Object or JSON string; presence of steps creates a chain."
 	})),
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "PARALLEL mode: [{agent, task, count?, output?, outputMode?, reads?, progress?}, ...]" })),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Top-level PARALLEL mode only: max concurrent tasks. Defaults to config.parallel.concurrency or 4." })),
 	worktree: Type.Optional(Type.Boolean({
-		description: "Create isolated git worktrees for each parallel task. " +
-			"Prevents filesystem conflicts. Requires clean git state. " +
-			"Per-worktree diffs included in output."
+		description: "Create isolated git worktrees for parallel tasks; requires clean git state."
 	})),
-	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential pipeline where each step's response becomes {previous} for the next. With action='append-step', provide exactly one step to append to an active async chain; it can use {previous}, {chain_dir}, and existing {outputs.name} references." })),
+	chain: Type.Optional(Type.Array(ChainItem, { description: "CHAIN mode: sequential steps; each result becomes {previous}. append-step takes one tail step and may use {chain_dir}/{outputs.name}." })),
 	context: Type.Optional(Type.String({
 		enum: ["fresh", "fork"],
-		description: "'fresh' or 'fork' to branch from parent session. If omitted, any requested agent with defaultContext: 'fork' makes the whole invocation forked; otherwise the default is 'fresh'.",
+		description: "'fresh' or 'fork' to branch from parent session. Explicit context overrides every child in the invocation. If omitted, each requested agent uses its own defaultContext; agents without defaultContext: 'fork' run fresh.",
 	})),
-	chainDir: Type.Optional(Type.String({ description: "Persistent directory for chain artifacts. Default: a user-scoped temp directory under <tmpdir>/ (auto-cleaned after 24h)" })),
+	chainDir: Type.Optional(Type.String({ description: "Persistent chain artifact directory; defaults to user-scoped temp storage." })),
 	async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Foreground timeout ms; alias of maxRuntimeMs." })),
+	maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias of timeoutMs for foreground timeout." })),
 	agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
 	cwd: Type.Optional(Type.String()),
 	artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),

package/src/intercom/intercom-bridge.ts

@@ -4,10 +4,9 @@ import * as os from "node:os";
 import * as path from "node:path";
 import type { AgentConfig } from "../agents/agents.ts";
 import type { ExtensionConfig, IntercomBridgeConfig, IntercomBridgeMode } from "../shared/types.ts";
-import { getAgentDir } from "../shared/utils.ts";
+import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 
 const PI_INTERCOM_PACKAGE_NAME = "pi-intercom";
-const CONFIG_DIR = ".pi";
 
 function defaultAgentDir(): string {
 	return getAgentDir();
@@ -179,7 +178,7 @@ function packageEntryAllowsExtensions(entry: unknown): boolean {
 function findNearestProjectConfigDir(cwd: string): string | undefined {
 	let current = path.resolve(cwd);
 	while (true) {
-		const configDir = path.join(current, CONFIG_DIR);
+		const configDir = getProjectConfigDir(current);
 		if (fs.existsSync(path.join(configDir, "settings.json"))) return configDir;
 		const parent = path.dirname(current);
 		if (parent === current) return undefined;

package/src/runs/background/async-execution.ts

@@ -11,7 +11,7 @@ import { createRequire } from "node:module";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AgentConfig } from "../../agents/agents.ts";
 import { applyThinkingSuffix } from "../shared/pi-args.ts";
-import { injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
+import { injectOutputPathSystemPrompt, injectSingleOutputInstruction, normalizeSingleOutputOverride, resolveSingleOutputPath, validateFileOnlyOutputMode } from "../shared/single-output.ts";
 import { buildChainInstructions, isDynamicParallelStep, isParallelStep, resolveStepBehavior, suppressProgressForReadOnlyTask, writeInitialProgressFile, type ChainStep, type ResolvedStepBehavior, type SequentialStep, type StepOverrides } from "../../shared/settings.ts";
 import type { RunnerStep } from "../shared/parallel-utils.ts";
 import { resolvePiPackageRoot } from "../shared/pi-spawn.ts";
@@ -95,6 +95,8 @@ interface AsyncExecutionContext {
 	pi: ExtensionAPI;
 	cwd: string;
 	currentSessionId: string;
+	/** Parent session id used by permission-system ask forwarding. */
+	parentSessionId?: string;
 	currentModelProvider?: string;
 	currentModel?: ParentModel;
 }
@@ -115,6 +117,7 @@ interface AsyncChainParams {
 	sessionRoot?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	progressDir?: string;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	worktreeSetupHook?: string;
@@ -170,6 +173,7 @@ export interface AsyncRunnerStepBuildParams {
 	cwd?: string;
 	chainSkills?: string[];
 	sessionFilesByFlatIndex?: (string | undefined)[];
+	progressDir?: string;
 	dynamicFanoutMaxItems?: number;
 	maxSubagentDepth: number;
 	asyncDir: string;
@@ -277,6 +281,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 	const chainSkills = params.chainSkills ?? [];
 	const availableModels = params.availableModels;
 	const runnerCwd = resolveChildCwd(ctx.cwd, cwd);
+	const progressDir = params.progressDir ?? runnerCwd;
 	const graphChain: ChainStep[] = params.attachRoot
 		? [{
 				agent: params.attachRoot.agent,
@@ -346,8 +351,9 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const readInstructions = buildChainInstructions({ ...behavior, output: false, progress: false }, instructionCwd, false);
 		const isFirstProgressAgent = behavior.progress && !progressPrecreated && !progressInstructionCreated;
 		if (behavior.progress) progressInstructionCreated = true;
-		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, runnerCwd, isFirstProgressAgent);
+		const progressInstructions = buildChainInstructions({ ...behavior, output: false, reads: false }, progressDir, isFirstProgressAgent);
 		const outputPath = resolveSingleOutputPath(behavior.output, ctx.cwd, instructionCwd);
+		systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath);
 		const validationError = validateFileOnlyOutputMode(behavior.outputMode, outputPath, `Async step (${s.agent})`);
 		if (validationError) throw new AsyncStartValidationError(validationError);
 		let taskTemplate = s.task ?? "{previous}";
@@ -359,6 +365,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 		const primaryModel = resolveSubagentModelOverride(requestedModel, ctx.currentModel, availableModels, ctx.currentModelProvider);
 		const model = applyThinkingSuffix(primaryModel, a.thinking);
 		return {
+			parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
 			agent: s.agent,
 			task,
 			phase: s.phase,
@@ -414,7 +421,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				});
 				const progressPrecreated = parallelBehaviors.some((behavior) => behavior.progress);
 				if (progressPrecreated) {
-					if (!s.worktree) writeInitialProgressFile(runnerCwd);
+					if (!s.worktree || params.progressDir) writeInitialProgressFile(progressDir);
 					progressInstructionCreated = true;
 				}
 				return {
@@ -439,7 +446,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
 				const behavior = suppressProgressForReadOnlyTask(resolveStepBehavior(agent, buildStepOverrides(s.parallel), chainSkills), s.parallel.task, originalTask);
 				const progressPrecreated = behavior.progress;
 				if (progressPrecreated) {
-					writeInitialProgressFile(runnerCwd);
+					writeInitialProgressFile(progressDir);
 					progressInstructionCreated = true;
 				}
 				return {
@@ -539,6 +546,7 @@ export function executeAsyncChain(
 		cwd,
 		chainSkills: params.chainSkills,
 		sessionFilesByFlatIndex,
+		progressDir: params.progressDir ?? (resultMode === "parallel" ? path.join(asyncDir, "progress") : undefined),
 		dynamicFanoutMaxItems: params.dynamicFanoutMaxItems,
 		maxSubagentDepth,
 		asyncDir,
@@ -765,6 +773,7 @@ export function executeAsyncSingle(
 
 	const effectiveOutput = normalizeSingleOutputOverride(params.output, agentConfig.output);
 	const outputPath = resolveSingleOutputPath(effectiveOutput, ctx.cwd, runnerCwd);
+	systemPrompt = injectOutputPathSystemPrompt(systemPrompt, outputPath);
 	const outputMode = params.outputMode ?? "inline";
 	const validationError = validateFileOnlyOutputMode(outputMode, outputPath, `Async single run (${agent})`);
 	if (validationError) return formatAsyncStartError("single", validationError);
@@ -783,6 +792,7 @@ export function executeAsyncSingle(
 				id,
 				steps: [
 					{
+						parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
 						agent,
 						task: taskWithOutputInstruction,
 						cwd: runnerCwd,