pi-subagents 0.56.0 → 0.57.0

package/src/agents/agents.ts

@@ -9,6 +9,7 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import type { AcceptanceInput, AcceptanceRole, AgentRunnerConfig, OutputMode, ToolBudgetConfig, TurnBudgetConfig } from "../shared/types.ts";
+import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, parseExternalCliCapabilityNarrowing, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain, parseJsonChain } from "./chain-serializer.ts";
@@ -262,14 +263,72 @@ export function findBlockingAgentDiagnostic(name: string, agent: AgentConfig | r
 	return !agents.length || (match && agentDefinitionPriority(match) > highestPriority) ? match : undefined;
 }
 
-interface AgentDiscoveryResult {
+export type AgentDefinitionDirectoryState = "absent" | "empty" | "candidates" | "unreadable" | "not-directory";
+
+/** A definition directory actually inspected during one agent-discovery operation. */
+export interface AgentDefinitionDirectoryReport {
+	source: AgentSource;
+	path: string;
+	state: AgentDefinitionDirectoryState;
+	candidateCount?: number;
+}
+
+/**
+ * Filesystem provenance for a failed agent resolution. Context is created from
+ * the discovery result that supplied the effective agents; callers must not
+ * pair arbitrary agent arrays with these directory reports.
+ */
+export interface UnknownAgentDiagnosticContext {
+	cwd: string;
+	scope: AgentScope;
+	directories: readonly AgentDefinitionDirectoryReport[];
+	agents: readonly AgentConfig[];
+}
+
+export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	agentDiagnostics?: AgentDiscoveryDiagnostic[];
 	projectAgentsDir: string | null;
+	cwd: string;
+	scope: AgentScope;
+	directories: readonly AgentDefinitionDirectoryReport[];
 	modelScope?: ModelScopeConfig;
 	maxThinking?: ThinkingLevel;
 }
 
+/** Create formatter input from the exact discovery operation used for resolution. */
+export function unknownAgentDiagnosticContext(discovered: Pick<AgentDiscoveryResult, "cwd" | "scope" | "directories" | "agents">): UnknownAgentDiagnosticContext {
+	return {
+		cwd: discovered.cwd,
+		scope: discovered.scope,
+		directories: discovered.directories,
+		agents: discovered.agents,
+	};
+}
+
+/** Render local discovery evidence without exposing filesystem error details. */
+export function formatUnknownAgentError(name: string, context: UnknownAgentDiagnosticContext, prefix = "Unknown agent"): string {
+	const directories = context.directories.map((directory) => {
+		const state = directory.state === "candidates"
+			? `${directory.candidateCount ?? 0} candidate${directory.candidateCount === 1 ? "" : "s"}`
+			: directory.state === "empty" ? "present but empty"
+				: directory.state === "not-directory" ? "not a directory"
+					: directory.state;
+		return `- ${directory.source}: ${directory.path} (${state})`;
+	});
+	const agents = [...context.agents]
+		.sort((left, right) => left.name.localeCompare(right.name) || left.source.localeCompare(right.source))
+		.map((agent) => `- ${agent.name} (${agent.source})`);
+	return [
+		`${prefix}: ${name}`,
+		`Effective cwd: ${path.resolve(context.cwd)}`,
+		"Consulted agent-definition directories:",
+		...(directories.length ? directories : ["- (none)"]),
+		"Discovered agents:",
+		...(agents.length ? agents : ["- (none)"]),
+	].join("\n");
+}
+
 function getUserChainDir(): string {
 	return path.join(getAgentDir(), "chains");
 }
@@ -381,6 +440,10 @@ function resolveSettingsPackageRoot(source: string, baseDir: string): string | u
 	if (normalized === "." || normalized === ".." || normalized.startsWith("./") || normalized.startsWith("../")) {
 		return path.resolve(baseDir, normalized);
 	}
+	if (/^https?:\/\//i.test(trimmed)) {
+		const parsed = parseGitPackagePath(`git:${trimmed}`);
+		return parsed ? path.join(baseDir, "git", parsed.host, parsed.repoPath) : undefined;
+	}
 	return undefined;
 }
 
@@ -1598,9 +1661,22 @@ function shouldPruneDiscoveryDir(rootDir: string, dir: string, dirName: string):
 	return path.resolve(dir) !== path.resolve(rootDir) && isDiscoveryNestedProjectRoot(dir);
 }
 
-function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean, rootDir = dir): string[] {
+function listFilesRecursive(
+	dir: string,
+	predicate: (fileName: string) => boolean,
+	rootDir = dir,
+	visitedDirectories = new Set<string>(),
+): string[] {
 	const files: string[] = [];
 	if (!fs.existsSync(dir)) return files;
+	let realDir: string;
+	try {
+		realDir = fs.realpathSync(dir);
+	} catch {
+		return files;
+	}
+	if (visitedDirectories.has(realDir)) return files;
+	visitedDirectories.add(realDir);
 
 	let entries: fs.Dirent[];
 	try {
@@ -1611,9 +1687,17 @@ function listFilesRecursive(dir: string, predicate: (fileName: string) => boolea
 
 	for (const entry of entries) {
 		const filePath = path.join(dir, entry.name);
-		if (entry.isDirectory()) {
+		let isDirectory = entry.isDirectory();
+		if (entry.isSymbolicLink()) {
+			try {
+				isDirectory = fs.statSync(filePath).isDirectory();
+			} catch {
+				isDirectory = false;
+			}
+		}
+		if (isDirectory) {
 			if (!shouldPruneDiscoveryDir(rootDir, filePath, entry.name)) {
-				files.push(...listFilesRecursive(filePath, predicate, rootDir));
+				files.push(...listFilesRecursive(filePath, predicate, rootDir, visitedDirectories));
 			}
 			continue;
 		}
@@ -1624,6 +1708,81 @@ function listFilesRecursive(dir: string, predicate: (fileName: string) => boolea
 	return files;
 }
 
+export interface AgentDefinitionInspection {
+	files: string[];
+	state: AgentDefinitionDirectoryState;
+}
+
+/** Narrow filesystem seam so unavailable paths can be tested without permissions. */
+export interface AgentDefinitionInspectionFs {
+	existsSync(filePath: string): boolean;
+	realpathSync?(filePath: string): string;
+	statSync(filePath: string): { isDirectory(): boolean };
+	readdirSync(dir: string): fs.Dirent[];
+}
+
+const DEFAULT_AGENT_DEFINITION_INSPECTION_FS: AgentDefinitionInspectionFs = {
+	existsSync: fs.existsSync,
+	realpathSync: fs.realpathSync,
+	statSync: fs.statSync,
+	readdirSync: (dir) => fs.readdirSync(dir, { withFileTypes: true }),
+};
+
+/**
+ * Inspect one agent-definition directory while retaining traversal failure
+ * state. A nested unreadable directory makes the whole inspection unavailable,
+ * preventing a partial traversal from being reported as empty or complete.
+ */
+export function inspectAgentDefinitionDirectory(dir: string, operations: AgentDefinitionInspectionFs = DEFAULT_AGENT_DEFINITION_INSPECTION_FS): AgentDefinitionInspection {
+	const root = path.resolve(dir);
+	try {
+		if (!operations.existsSync(root)) return { files: [], state: "absent" };
+		if (!operations.statSync(root).isDirectory()) return { files: [], state: "not-directory" };
+	} catch {
+		return { files: [], state: "unreadable" };
+	}
+	const files: string[] = [];
+	let unreadable = false;
+	const visitedDirectories = new Set<string>();
+	const visit = (current: string): void => {
+		let realDir: string;
+		try {
+			realDir = operations.realpathSync?.(current) ?? path.resolve(current);
+		} catch {
+			unreadable = true;
+			return;
+		}
+		if (visitedDirectories.has(realDir)) return;
+		visitedDirectories.add(realDir);
+
+		let entries: fs.Dirent[];
+		try {
+			entries = operations.readdirSync(current).sort((a, b) => a.name.localeCompare(b.name));
+		} catch {
+			unreadable = true;
+			return;
+		}
+		for (const entry of entries) {
+			const filePath = path.join(current, entry.name);
+			let isDirectory = entry.isDirectory();
+			if (entry.isSymbolicLink()) {
+				try {
+					isDirectory = operations.statSync(filePath).isDirectory();
+				} catch {
+					isDirectory = false;
+				}
+			}
+			if (isDirectory) {
+				if (!shouldPruneDiscoveryDir(root, filePath, entry.name)) visit(filePath);
+				continue;
+			}
+			if ((entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith(".md") && !entry.name.endsWith(".chain.md") && !isLegacyAgentSkillPath(root, filePath)) files.push(filePath);
+		}
+	};
+	visit(root);
+	return { files, state: unreadable ? "unreadable" : files.length ? "candidates" : "empty" };
+}
+
 function isLegacyAgentSkillPath(rootDir: string, filePath: string): boolean {
 	const relative = path.relative(rootDir, filePath);
 	const parts = relative.split(path.sep).map((part) => part.toLowerCase());
@@ -1682,18 +1841,23 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
 	if (runner.args !== undefined && (!Array.isArray(runner.args) || runner.args.some((arg) => typeof arg !== "string"))) {
 		throw new Error(`Agent '${agentName}' external-cli runner args must be an array of strings.`);
 	}
+	if (runner.adapter !== undefined && !isCodeOwnedExternalCliAdapterId(runner.adapter)) throw new Error(`Agent '${agentName}' external-cli runner adapter must be ${CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL}.`);
+	if (runner.adapter !== undefined && Array.isArray(runner.args) && runner.args.length > 0) throw new Error(`Agent '${agentName}' ${runner.adapter} adapter owns its argv; runner args are not supported.`);
 	if (runner.promptDelivery !== undefined && runner.promptDelivery !== "stdin") {
 		throw new Error(`Agent '${agentName}' external-cli runner promptDelivery must be 'stdin'.`);
 	}
-	const supported = new Set(["type", "command", "args", "promptDelivery"]);
+	const capabilities = parseExternalCliCapabilityNarrowing(runner.capabilities, `Agent '${agentName}' external-cli runner capabilities`);
+	const supported = new Set(["type", "adapter", "command", "args", "promptDelivery", "capabilities"]);
 	const unknown = Object.keys(runner).filter((key) => !supported.has(key));
 	if (unknown.length > 0) throw new Error(`Agent '${agentName}' external-cli runner has unsupported fields: ${unknown.join(", ")}.`);
 	const runnerArgs = Array.isArray(runner.args) ? runner.args.filter((arg): arg is string => typeof arg === "string") : undefined;
 	return {
 		type: "external-cli",
+		...(isCodeOwnedExternalCliAdapterId(runner.adapter) ? { adapter: runner.adapter } : {}),
 		command: runner.command.trim(),
 		...(runnerArgs?.length ? { args: runnerArgs } : {}),
 		...(runner.promptDelivery ? { promptDelivery: "stdin" as const } : {}),
+		...(capabilities ? { capabilities } : {}),
 	};
 }
 
@@ -1724,9 +1888,9 @@ interface AgentDefinitionFile {
 	content: string;
 }
 
-function readAgentDefinitionFiles(dir: string): AgentDefinitionFile[] {
+function readAgentDefinitionFiles(dir: string, inspection = inspectAgentDefinitionDirectory(dir)): AgentDefinitionFile[] {
 	const files: AgentDefinitionFile[] = [];
-	for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
+	for (const filePath of inspection.files) {
 		if (isLegacyAgentSkillPath(dir, filePath)) {
 			continue;
 		}
@@ -1783,6 +1947,8 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 		const mcpDirectTools = parsedTools.mcpDirectTools ?? [];
 		const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
 		const aliases = normalizeAgentAliases(parseFrontmatterList(frontmatter.aliases ?? frontmatter.alias), runtimeName);
+		const profileError = validateCodeOwnedProfileRunner({ name: runtimeName, localName, aliases, runner });
+		if (profileError) throw new Error(profileError);
 		const skillStr = frontmatter.skill || frontmatter.skills;
 		const skills = parseFrontmatterList(skillStr);
 		const skillPath = parseFrontmatterList(frontmatter.skillPath);
@@ -1944,8 +2110,17 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
 	return { agents, diagnostics };
 }
 
-function loadAgentsFromDir(dir: string, source: AgentSource, discoveryPriority?: number, packageSource?: Omit<PackageSubagentPath, "dir">): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
-	return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir), source, discoveryPriority, packageSource);
+function loadAgentsFromDir(dir: string, source: AgentSource, discoveryPriority?: number, packageSource?: Omit<PackageSubagentPath, "dir">, inspection = inspectAgentDefinitionDirectory(dir)): { agents: AgentConfig[]; diagnostics: AgentDiscoveryDiagnostic[] } {
+	return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir, inspection), source, discoveryPriority, packageSource);
+}
+
+function reportAgentDefinitionDirectory(source: AgentSource, dir: string, inspection: AgentDefinitionInspection): AgentDefinitionDirectoryReport {
+	return {
+		source,
+		path: path.resolve(dir),
+		state: inspection.state,
+		...(inspection.state === "candidates" ? { candidateCount: inspection.files.length } : {}),
+	};
 }
 
 function loadChainsFromDir(dir: string, source: AgentSource): { chains: ChainConfig[]; diagnostics: ChainDiscoveryDiagnostic[] } {
@@ -1982,20 +2157,18 @@ function isDirectory(p: string): boolean {
 	}
 }
 
-function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
+function resolveNearestProjectAgentDirs(cwd: string): { readDirs: string[]; candidateDirs: string[]; preferredDir: string | null } {
 	const projectRoot = findConfiguredProjectRoot(cwd);
-	if (!projectRoot) return { readDirs: [], preferredDir: null };
+	if (!projectRoot) return { readDirs: [], candidateDirs: [], preferredDir: null };
 
 	const legacyDir = path.join(projectRoot, ".agents");
 	const preferredDir = path.join(getProjectConfigDir(projectRoot), "agents");
+	const candidateDirs = [legacyDir, preferredDir];
 	const readDirs: string[] = [];
 	if (isDirectory(legacyDir)) readDirs.push(legacyDir);
 	if (isDirectory(preferredDir)) readDirs.push(preferredDir);
 
-	return {
-		readDirs,
-		preferredDir,
-	};
+	return { readDirs, candidateDirs, preferredDir };
 }
 
 function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; preferredDir: string | null } {
@@ -2009,7 +2182,9 @@ function resolveNearestProjectChainDirs(cwd: string): { readDirs: string[]; pref
 	};
 }
 const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
-const BUILTIN_AGENT_DEFINITION_FILES = readAgentDefinitionFiles(BUILTIN_AGENTS_DIR);
+// Candidate files and inspection state must describe the same cached builtin scan.
+const BUILTIN_AGENT_DEFINITION_INSPECTION = inspectAgentDefinitionDirectory(BUILTIN_AGENTS_DIR);
+const BUILTIN_AGENT_DEFINITION_FILES = readAgentDefinitionFiles(BUILTIN_AGENTS_DIR, BUILTIN_AGENT_DEFINITION_INSPECTION);
 
 export const EXTRA_AGENT_DIRS_ENV = "PI_SUBAGENT_EXTRA_AGENT_DIRS";
 
@@ -2028,11 +2203,12 @@ function extraUserAgentDirs(): string[] {
 }
 
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
+	const effectiveCwd = path.resolve(cwd);
 	const userDirOld = path.join(getAgentDir(), "agents");
 	const userDirNew = path.join(os.homedir(), ".agents");
-	const { readDirs: projectAgentDirs, preferredDir: projectAgentsDir } = resolveNearestProjectAgentDirs(cwd);
+	const { readDirs: projectAgentDirs, candidateDirs: projectCandidateDirs, preferredDir: projectAgentsDir } = resolveNearestProjectAgentDirs(effectiveCwd);
 	const userSettingsPath = getUserAgentSettingsPath();
-	const projectSettingsPath = getProjectAgentSettingsPath(cwd);
+	const projectSettingsPath = getProjectAgentSettingsPath(effectiveCwd);
 	const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
 	const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
 	const defaultProvider = resolveSubagentDefaultProvider(userSettings, projectSettings, projectSettingsPath);
@@ -2041,65 +2217,60 @@ export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryRe
 	const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
 	const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
 	const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
-	const packageSubagentPaths = collectPackageSubagentPaths(cwd, {
+	const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, {
 		includeUser: scope !== "project",
 		includeProject: scope !== "user",
 	});
+	const directories: AgentDefinitionDirectoryReport[] = [reportAgentDefinitionDirectory("builtin", BUILTIN_AGENTS_DIR, BUILTIN_AGENT_DEFINITION_INSPECTION)];
 
 	const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
 	const builtinAgents = applyBuiltinOverrides(
 		applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions),
-		userSettings,
-		projectSettings,
-		userSettingsPath,
-		projectSettingsPath,
+		userSettings, projectSettings, userSettingsPath, projectSettingsPath,
 	);
 
-	const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), userDirOld, userDirNew]
-		.map((dir, discoveryPriority) => loadAgentsFromDir(dir, "user", discoveryPriority));
+	const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), userDirOld, userDirNew].map((dir, discoveryPriority) => {
+		const inspection = inspectAgentDefinitionDirectory(dir);
+		directories.push(reportAgentDefinitionDirectory("user", dir, inspection));
+		return loadAgentsFromDir(dir, "user", discoveryPriority, undefined, inspection);
+	});
 	const userAgents = applyCustomAgentOverrides(
 		applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
-		userSettings,
-		projectSettings,
-		userSettingsPath,
-		projectSettingsPath,
+		userSettings, projectSettings, userSettingsPath, projectSettingsPath,
 	);
 
-	const projectLoaded = scope === "user" ? [] : projectAgentDirs.map((dir) => loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0));
+	// Report both legacy and preferred project definition paths only after the
+	// existing configured-root resolver found a root; never synthesize cwd paths.
+	const projectInspections = scope === "user" ? new Map<string, AgentDefinitionInspection>() : new Map(projectCandidateDirs.map((dir) => [dir, inspectAgentDefinitionDirectory(dir)]));
+	if (scope !== "user") for (const dir of projectCandidateDirs) directories.push(reportAgentDefinitionDirectory("project", dir, projectInspections.get(dir)!));
+	const projectLoaded = scope === "user" ? [] : projectAgentDirs.map((dir) => loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0, undefined, projectInspections.get(dir)!));
 	const projectAgents = applyCustomAgentOverrides(
 		applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
-		userSettings,
-		projectSettings,
-		userSettingsPath,
-		projectSettingsPath,
+		userSettings, projectSettings, userSettingsPath, projectSettingsPath,
 	);
-	const packageLoaded = packageSubagentPaths.agents.map((entry, index) => loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry));
+
+	const packageLoaded = packageSubagentPaths.agents.map((entry, index) => {
+		const inspection = inspectAgentDefinitionDirectory(entry.dir);
+		directories.push(reportAgentDefinitionDirectory("package", entry.dir, inspection));
+		return loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry, inspection);
+	});
 	const packageMap = new Map<string, AgentConfig>();
-	for (const loaded of packageLoaded) {
-		for (const agent of loaded.agents) {
-			if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
-		}
-	}
+	for (const loaded of packageLoaded) for (const agent of loaded.agents) if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
 	const packageAgents = applyCustomAgentOverrides(
 		applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultProvider, defaultThinking, defaultExtensions),
-		userSettings,
-		projectSettings,
-		userSettingsPath,
-		projectSettingsPath,
+		userSettings, projectSettings, userSettingsPath, projectSettingsPath,
 	);
 	const agents = applySubagentMaxThinking(
-		mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents)
-			.filter((agent) => agent.disabled !== true),
+		mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents).filter((agent) => agent.disabled !== true),
 		maxThinking,
 	);
-
 	const agentDiagnostics = [
 		...builtinLoaded.diagnostics,
 		...userLoaded.flatMap((loaded) => loaded.diagnostics),
 		...projectLoaded.flatMap((loaded) => loaded.diagnostics),
 		...packageLoaded.flatMap((loaded) => loaded.diagnostics),
 	];
-	return { agents, agentDiagnostics, projectAgentsDir, ...(modelScope !== undefined ? { modelScope } : {}), ...(maxThinking !== undefined ? { maxThinking } : {}) };
+	return { agents, agentDiagnostics, projectAgentsDir, cwd: effectiveCwd, scope, directories, ...(modelScope !== undefined ? { modelScope } : {}), ...(maxThinking !== undefined ? { maxThinking } : {}) };
 }
 
 export function discoverAgentsAll(cwd: string): {

package/src/agents/builtin-names.ts

@@ -1,5 +1,11 @@
 export const BUILTIN_AGENT_NAMES = [
 	"advisor",
+	"claude-code",
+	"claude-code-writer",
+	"codex-exec",
+	"codex-exec-writer",
+	"cursor-agent",
+	"cursor-agent-writer",
 	"delegate",
 	"oracle",
 	"researcher",

package/src/agents/runtime-agent-registry.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { AcceptanceInput, AcceptanceRole, AgentRunnerConfig, OutputMode, ToolBudgetConfig, TurnBudgetConfig } from "../shared/types.ts";
+import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, parseExternalCliCapabilityNarrowing, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
 import { validatePermissionRules, type PermissionRules } from "../runs/shared/permissions.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
@@ -169,12 +170,15 @@ function validateRunner(value: unknown): AgentRunnerConfig | undefined {
 	if (runner.type !== "external-cli") throw new Error("Runtime agent definition runner.type must be 'pi', 'external-cli', or 'external-job'.");
 	if (typeof runner.command !== "string" || !runner.command.trim()) throw new Error("Runtime agent definition external-cli runner requires a non-empty command string.");
 	if (runner.args !== undefined && (!Array.isArray(runner.args) || runner.args.some((arg) => typeof arg !== "string"))) throw new Error("Runtime agent definition external-cli runner args must be an array of strings.");
+	if (runner.adapter !== undefined && !isCodeOwnedExternalCliAdapterId(runner.adapter)) throw new Error(`Runtime agent definition external-cli runner adapter must be ${CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL}.`);
+	if (runner.adapter !== undefined && Array.isArray(runner.args) && runner.args.length > 0) throw new Error(`Runtime agent definition ${runner.adapter} adapter owns its argv; runner args are not supported.`);
 	if (runner.promptDelivery !== undefined && runner.promptDelivery !== "stdin") throw new Error("Runtime agent definition external-cli runner promptDelivery must be 'stdin'.");
-	const supported = new Set(["type", "command", "args", "promptDelivery"]);
+	const capabilities = parseExternalCliCapabilityNarrowing(runner.capabilities, "Runtime agent definition external-cli runner capabilities");
+	const supported = new Set(["type", "adapter", "command", "args", "promptDelivery", "capabilities"]);
 	const unknown = Object.keys(runner).filter((key) => !supported.has(key));
 	if (unknown.length > 0) throw new Error(`Runtime agent definition external-cli runner has unsupported fields: ${unknown.join(", ")}.`);
 	const args = runner.args as string[] | undefined;
-	return { type: "external-cli", command: runner.command.trim(), ...(args?.length ? { args } : {}), ...(runner.promptDelivery ? { promptDelivery: "stdin" as const } : {}) };
+	return { type: "external-cli", ...(isCodeOwnedExternalCliAdapterId(runner.adapter) ? { adapter: runner.adapter } : {}), command: runner.command.trim(), ...(args?.length ? { args } : {}), ...(runner.promptDelivery ? { promptDelivery: "stdin" as const } : {}), ...(capabilities ? { capabilities } : {}) };
 }
 
 function validateTurnBudget(value: unknown): TurnBudgetConfig | undefined {
@@ -364,6 +368,8 @@ export function registerRuntimeAgent(input: RegisterRuntimeAgentInput): RuntimeA
 	const name = validateString(input.name, "Runtime agent name", MAX_AGENT_NAME_LENGTH);
 	const definition = validateDefinition(input.definition);
 	const agent = toAgentConfig(name, definition);
+	const profileError = validateCodeOwnedProfileRunner(agent);
+	if (profileError) throw new Error(profileError);
 	assertNoBuiltinCollision(agent);
 	const current = registry();
 	const records = current.byPi.get(pi) ?? [];

package/src/api/preflight.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import { discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, resolveAgentName, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
+import { discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, formatUnknownAgentError, resolveAgentName, unknownAgentDiagnosticContext, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
 import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
 import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
 import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
@@ -251,7 +251,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
 		return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
 	}
 	if (!resolvedAgent.agent) {
-		return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
+		return { ok: false, code: "missing_agent", message: formatUnknownAgentError(input.agent, unknownAgentDiagnosticContext(discovered)), diagnostics };
 	}
 	const agent = resolvedAgent.agent;
 	let extensionBindings: ExtensionBindings | undefined;

package/src/extension/config.ts

@@ -6,7 +6,9 @@ import { FLEET_KEYBINDING_ACTIONS, type ArtifactDirPreference, type ExtensionCon
 import { validateMissionStoreConfig } from "../missions/store.ts";
 import { validateAuthorityPolicy } from "../policy/authority.ts";
 import { getAgentDir } from "../shared/utils.ts";
+import { DEFAULT_MODEL_EXCLUSION_TTL_MS, MAX_MODEL_EXCLUSION_TTL_MS, setDefaultTTL } from "../runs/shared/model-exclusions.ts";
 import { validatePermissionConfig } from "../runs/shared/permissions.ts";
+import { MAX_ABANDONED_SLOT_RELEASE_AFTER_MS, MIN_ABANDONED_SLOT_RELEASE_AFTER_MS } from "../runs/background/active-async-capacity.ts";
 
 const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
 const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
@@ -16,6 +18,23 @@ const BASE_KEY_IDS = new Set([
 	...Object.values(Key).flatMap((value) => typeof value === "string" ? [value.toLowerCase()] : []),
 ]);
 
+class PrunedForkConfigError extends Error {}
+
+function validateForkContextConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.forkContext must be a JSON object");
+	const config = value as Record<string, unknown>;
+	if (config.mode !== undefined && config.mode !== "full" && config.mode !== "pruned") {
+		throw new Error('config.forkContext.mode must be "full" or "pruned"');
+	}
+	if (config.model !== undefined && (typeof config.model !== "string" || !config.model.trim())) {
+		throw new PrunedForkConfigError("config.forkContext.model must be a non-empty string");
+	}
+	if (config.mode === "pruned" && config.model === undefined) {
+		throw new PrunedForkConfigError('config.forkContext.model is required when config.forkContext.mode is "pruned"');
+	}
+}
+
 function isValidKeyId(value: string): boolean {
 	if (value !== value.trim()) return false;
 	const parts = value.toLowerCase().split("+");
@@ -62,6 +81,31 @@ function validateArtifactConfig(value: unknown): void {
 	}
 }
 
+function validateCapacityConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.capacity must be a JSON object");
+	const abandonedSlotReleaseAfterMs = (value as Record<string, unknown>).abandonedSlotReleaseAfterMs;
+	if (abandonedSlotReleaseAfterMs !== undefined
+		&& abandonedSlotReleaseAfterMs !== false
+		&& (typeof abandonedSlotReleaseAfterMs !== "number"
+			|| !Number.isInteger(abandonedSlotReleaseAfterMs)
+			|| abandonedSlotReleaseAfterMs < MIN_ABANDONED_SLOT_RELEASE_AFTER_MS
+			|| abandonedSlotReleaseAfterMs > MAX_ABANDONED_SLOT_RELEASE_AFTER_MS)) {
+		throw new Error(`config.capacity.abandonedSlotReleaseAfterMs must be false or an integer from ${MIN_ABANDONED_SLOT_RELEASE_AFTER_MS} to ${MAX_ABANDONED_SLOT_RELEASE_AFTER_MS}`);
+	}
+}
+
+/** Validate the user-controlled TTL policy before it reaches the exclusion store. */
+// TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
+function validateModelExclusionsConfig(value: unknown): void {
+	if (value === undefined) return;
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.modelExclusions must be a JSON object");
+	const defaultTtlMs = (value as Record<string, unknown>).defaultTtlMs;
+	if (defaultTtlMs !== undefined && (typeof defaultTtlMs !== "number" || !Number.isFinite(defaultTtlMs) || defaultTtlMs <= 0 || defaultTtlMs > MAX_MODEL_EXCLUSION_TTL_MS)) {
+		throw new Error(`config.modelExclusions.defaultTtlMs must be a finite positive number no greater than ${MAX_MODEL_EXCLUSION_TTL_MS}`);
+	}
+}
+
 function validateOrcaProgressTabsConfig(value: unknown): void {
 	if (value === undefined) return;
 	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.orcaProgressTabs must be a JSON object");
@@ -97,6 +141,7 @@ function validateConfig(config: Record<string, unknown>): void {
 	if (config.defaultSubagentContext !== undefined && config.defaultSubagentContext !== "fresh" && config.defaultSubagentContext !== "fork") {
 		throw new Error('config.defaultSubagentContext must be "fresh" or "fork"');
 	}
+	validateForkContextConfig(config.forkContext);
 	if (config.foregroundDetachShortcut !== undefined
 		&& (typeof config.foregroundDetachShortcut !== "string" || !isValidKeyId(config.foregroundDetachShortcut))) {
 		throw new Error("config.foregroundDetachShortcut must be a valid keybinding string such as \"ctrl+b\"");
@@ -119,6 +164,8 @@ function validateConfig(config: Record<string, unknown>): void {
 	validateScheduledRunsConfig(config.scheduledRuns);
 	validateFleetKeybindingsConfig(config.fleetKeybindings);
 	validateArtifactConfig(config.artifactConfig);
+	validateCapacityConfig(config.capacity);
+	validateModelExclusionsConfig(config.modelExclusions);
 	validateMainWindowRendererConfig(config.mainWindowRenderer);
 	validateOrcaProgressTabsConfig(config.orcaProgressTabs);
 }
@@ -150,6 +197,28 @@ export function updateConfig(updater: (config: ExtensionConfig) => ExtensionConf
 	return next;
 }
 
+/**
+ * Resolve the default TTL that the process-wide exclusion store should use.
+ *
+ * @param config Extension configuration after validation.
+ * @returns The configured TTL in milliseconds, or the built-in 24-hour default.
+ */
+// TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
+export function resolveModelExclusionTTL(config: Pick<ExtensionConfig, "modelExclusions">): number {
+	return config.modelExclusions?.defaultTtlMs ?? DEFAULT_MODEL_EXCLUSION_TTL_MS;
+}
+
+/**
+ * Apply the configured exclusion policy to the process-wide model store.
+ *
+ * @param config Extension configuration after validation.
+ * @returns Nothing.
+ */
+// TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
+export function applyModelExclusionsConfig(config: Pick<ExtensionConfig, "modelExclusions">): void {
+	setDefaultTTL(resolveModelExclusionTTL(config), { shortenExisting: config.modelExclusions?.defaultTtlMs !== undefined });
+}
+
 export function resolveAsyncByDefault(config: Pick<ExtensionConfig, "asyncByDefault">): boolean {
 	return config.asyncByDefault !== false;
 }
@@ -159,6 +228,7 @@ export function loadConfig(): ExtensionConfig {
 	try {
 		return readConfigForUpdate(configPath);
 	} catch (error) {
+		if (error instanceof PrunedForkConfigError) throw error;
 		console.error(`Failed to load subagent config from '${configPath}':`, error);
 	}
 	return {};

package/src/extension/doctor.ts

@@ -3,7 +3,7 @@ import * as path from "node:path";
 import { discoverAgentsAll, type AgentSource } from "../agents/agents.ts";
 import { isAsyncAvailable } from "../runs/background/async-execution.ts";
 import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared/spawn-budget.ts";
-import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
+import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
 import { decodeRunFanoutBudgetDescriptor, formatRunFanoutBudget, getRunFanoutBudgetSnapshot, RUN_FANOUT_BUDGET_ENV } from "../runs/shared/run-fanout-budget.ts";
 import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
 import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
@@ -197,13 +197,13 @@ function formatActiveAsyncCapacitySection(input: DoctorReportInput): string[] {
 	const limit = resolveMaxActiveAsyncRunsPerSession(input.config.maxActiveAsyncRunsPerSession);
 	const sessionId = input.currentSessionId ?? input.state.currentSessionId;
 	const snapshot = sessionId
-		? getActiveAsyncCapacitySnapshot(sessionId, limit, { liveWorkflowRunIds: new Set(input.state.workflowControllers?.keys() ?? []) })
+		? getActiveAsyncCapacitySnapshot(sessionId, limit, { liveWorkflowRunIds: new Set(input.state.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: resolveAbandonedSlotReleaseAfterMs(input.config.capacity?.abandonedSlotReleaseAfterMs) })
 		: { used: 0, limit: limit ?? 0 };
 	input.state.activeAsyncCapacity = snapshot;
 	return [
 		`- usage: ${snapshot.used}/${snapshot.limit || "unlimited"} used`,
 		"- scope: top-level async runs in the current parent session; foreground and nested workflow children are not charged again",
-		"- release: terminal logical state plus verified process exit; missing or unknown cleanup proof retains capacity",
+		"- release: terminal state plus matching observed process-terminal proof, or abandoned-timeout for failed runs with a dead runner PID and stale activity when enabled; false keeps unknown-proof slots",
 	];
 }