pi-subagents 0.29.0 → 0.31.0

package/src/agents/proactive-skills.ts

@@ -0,0 +1,191 @@
+import type { AgentConfig, ChainConfig, ChainStepConfig } from "./agents.ts";
+import type { ProactiveSkillSubagentsConfig } from "../shared/types.ts";
+
+const SUBAGENT_ORCHESTRATION_SKILL = "pi-subagents";
+const DEFAULT_MIN_REFERENCES = 2;
+const DEFAULT_MAX_RECOMMENDATIONS = 3;
+const DEFAULT_PREFERRED_AGENT = "reviewer";
+const FALLBACK_AGENT_ORDER = ["reviewer", "context-builder", "delegate"];
+const MAX_RECOMMENDATION_CAP = 5;
+
+export interface ResolvedProactiveSkillSubagentsConfig {
+	enabled: boolean;
+	minReferences: number;
+	maxRecommendations: number;
+	preferredAgent: string;
+}
+
+export interface ProactiveSkillSubagentRecommendation {
+	skill: string;
+	agent: string;
+	references: number;
+	sources: string[];
+	description?: string;
+	reason: string;
+}
+
+export interface AvailableSkill {
+	name: string;
+	description?: string;
+}
+
+function positiveInteger(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isInteger(value) || !Number.isFinite(value) || value < 1) return undefined;
+	return value;
+}
+
+export function resolveProactiveSkillSubagentsConfig(
+	config?: ProactiveSkillSubagentsConfig | false,
+): ResolvedProactiveSkillSubagentsConfig {
+	if (config === false) {
+		return {
+			enabled: false,
+			minReferences: DEFAULT_MIN_REFERENCES,
+			maxRecommendations: DEFAULT_MAX_RECOMMENDATIONS,
+			preferredAgent: DEFAULT_PREFERRED_AGENT,
+		};
+	}
+
+	const maxRecommendations = positiveInteger(config?.maxRecommendations) ?? DEFAULT_MAX_RECOMMENDATIONS;
+	return {
+		enabled: config?.enabled ?? true,
+		minReferences: positiveInteger(config?.minReferences) ?? DEFAULT_MIN_REFERENCES,
+		maxRecommendations: Math.min(maxRecommendations, MAX_RECOMMENDATION_CAP),
+		preferredAgent: typeof config?.preferredAgent === "string" && config.preferredAgent.trim()
+			? config.preferredAgent.trim()
+			: DEFAULT_PREFERRED_AGENT,
+	};
+}
+
+function normalizeSkillNames(value: unknown): string[] {
+	if (value === false || value === true || value === undefined || value === null) return [];
+	if (Array.isArray(value)) {
+		return [...new Set(value.filter((entry): entry is string => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean))];
+	}
+	if (typeof value === "string") {
+		return [...new Set(value.split(",").map((entry) => entry.trim()).filter(Boolean))];
+	}
+	return [];
+}
+
+function collectStepSkills(step: ChainStepConfig, out: Set<string>): void {
+	for (const skill of normalizeSkillNames(step.skills ?? (step as { skill?: unknown }).skill)) {
+		out.add(skill);
+	}
+
+	const parallel = step.parallel;
+	if (!parallel) return;
+	if (Array.isArray(parallel)) {
+		for (const child of parallel) {
+			if (child && typeof child === "object" && !Array.isArray(child)) {
+				collectStepSkills(child as ChainStepConfig, out);
+			}
+		}
+		return;
+	}
+	if (typeof parallel === "object") {
+		collectStepSkills(parallel as ChainStepConfig, out);
+	}
+}
+
+function chooseRecommendationAgent(agents: AgentConfig[], preferredAgent: string): string | undefined {
+	const enabled = agents.filter((agent) => !agent.disabled);
+	if (enabled.some((agent) => agent.name === preferredAgent)) return preferredAgent;
+	for (const name of FALLBACK_AGENT_ORDER) {
+		if (enabled.some((agent) => agent.name === name)) return name;
+	}
+	return enabled[0]?.name;
+}
+
+function addSource(counts: Map<string, Set<string>>, skill: string, source: string): void {
+	if (skill === SUBAGENT_ORCHESTRATION_SKILL) return;
+	const sources = counts.get(skill) ?? new Set<string>();
+	sources.add(source);
+	counts.set(skill, sources);
+}
+
+export function recommendProactiveSkillSubagents(input: {
+	agents: AgentConfig[];
+	chains?: ChainConfig[];
+	availableSkills?: AvailableSkill[];
+	config?: ProactiveSkillSubagentsConfig | false;
+}): ProactiveSkillSubagentRecommendation[] {
+	const config = resolveProactiveSkillSubagentsConfig(input.config);
+	if (!config.enabled) return [];
+
+	const agent = chooseRecommendationAgent(input.agents, config.preferredAgent);
+	if (!agent) return [];
+
+	const availableByName = input.availableSkills
+		? new Map(input.availableSkills.map((skill) => [skill.name, skill]))
+		: undefined;
+	const counts = new Map<string, Set<string>>();
+
+	for (const candidate of input.agents) {
+		if (candidate.disabled) continue;
+		for (const skill of candidate.skills ?? []) {
+			addSource(counts, skill, `agent:${candidate.name}`);
+		}
+	}
+
+	for (const chain of input.chains ?? []) {
+		const chainSkills = new Set<string>();
+		for (const step of chain.steps) {
+			collectStepSkills(step, chainSkills);
+		}
+		for (const skill of chainSkills) {
+			addSource(counts, skill, `chain:${chain.name}`);
+		}
+	}
+
+	return [...counts.entries()]
+		.filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)))
+		.map(([skill, sources]) => ({
+			skill,
+			agent,
+			references: sources.size,
+			sources: [...sources].sort((a, b) => a.localeCompare(b)),
+			description: availableByName?.get(skill)?.description,
+			reason: `referenced by ${sources.size} configured agents/chains`,
+		}))
+		.sort((a, b) => b.references - a.references || a.skill.localeCompare(b.skill))
+		.slice(0, config.maxRecommendations);
+}
+
+export function formatProactiveSkillSubagentRecommendations(
+	recommendations: ProactiveSkillSubagentRecommendation[],
+): string[] {
+	if (recommendations.length === 0) return [];
+	return [
+		"Proactive skill subagent suggestions:",
+		...recommendations.map((recommendation) => {
+			const sampleSources = recommendation.sources.slice(0, 3).join(", ");
+			const extra = recommendation.sources.length > 3 ? `, +${recommendation.sources.length - 3} more` : "";
+			const description = recommendation.description ? ` - ${recommendation.description}` : "";
+			return `- ${recommendation.skill} via ${recommendation.agent} (${recommendation.reason}; ${sampleSources}${extra})${description}`;
+		}),
+		"Guardrails: use these for broad tasks where a skill-specialist pass is useful; keep fanout small, use fresh context unless private/session context is explicitly needed, and skip when the user asks for a direct answer.",
+	];
+}
+
+export function buildProactiveSkillSubagentRecommendationLines(input: {
+	agents: AgentConfig[];
+	chains?: ChainConfig[];
+	config?: ProactiveSkillSubagentsConfig | false;
+	discoverAvailableSkills: () => AvailableSkill[];
+}): string[] {
+	if (!resolveProactiveSkillSubagentsConfig(input.config).enabled) return [];
+	let availableSkills: AvailableSkill[];
+	try {
+		availableSkills = input.discoverAvailableSkills();
+	} catch {
+		availableSkills = [];
+	}
+	return formatProactiveSkillSubagentRecommendations(recommendProactiveSkillSubagents({
+		agents: input.agents,
+		chains: input.chains,
+		availableSkills,
+		config: input.config,
+	}));
+}

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(),
@@ -156,7 +157,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
 		label: "Subagent",
 		description: [
 			"Delegate to subagents from child-safe fanout mode.",
-			"Allowed management/control actions: list, get, status, interrupt, resume, doctor.",
+			"Allowed management/control actions: list, get, status, interrupt, resume, append-step, doctor.",
 			"Agent config mutation actions create, update, and delete are blocked in this mode.",
 		].join("\n"),
 		parameters: SubagentParams,

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,8 @@ 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):
 • {task} - The original task/request from the user
@@ -404,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" }
@@ -412,7 +439,8 @@ MANAGEMENT (use action field, omit agent/task/chain/tasks):
 CONTROL:
 • { action: "status", id: "..." } - inspect an async/background run by id or prefix
 • { action: "interrupt", id?: "..." } - soft-interrupt the current child turn and leave the run paused
-• { action: "resume", id: "...", message: "...", index?: 0 } - follow up with a live async child or revive a completed async/foreground child from its session
+• { action: "resume", id: "...", message: "...", index?: 0 } - interrupt then follow up with a live async child, or revive a completed async/foreground child from its session
+• { action: "append-step", id: "...", chain: [{agent:"agent-c", task:"Use {previous}"}] } - append one step to the tail of a running async chain
 
 DIAGNOSTICS:
 • { action: "doctor" } - read-only report for runtime paths, discovery, sessions, and intercom`,
@@ -453,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);
 		},
 
 	};
@@ -520,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);
@@ -533,6 +577,7 @@ DIAGNOSTICS:
 	});
 
 	pi.on("session_shutdown", () => {
+		delete process.env[SUBAGENT_PARENT_SESSION_ENV];
 		for (const unsubscribe of eventUnsubscribes) {
 			try {
 				unsubscribe();