pi-subagents 0.62.0 → 0.64.0

package/src/agents/agent-management.ts

@@ -250,13 +250,25 @@ function withDeclaredExtensionPaths(config: AgentConfig, filePath: string): Agen
 export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 	const { extensions: _extensions, ...withoutExtensions } = agent;
 	const base = agent.override?.base;
+	const description = base?.description ?? agent.description;
+	const frontmatterFields = agent.source === "builtin" || agent.source === "runtime" ? undefined : readAgentFrontmatterFields(agent.filePath);
+	const hasDeclaredField = (...fields: string[]) => frontmatterFields === undefined || fields.some((field) => frontmatterFields.has(field));
+	const withoutSettingsDefaults = (config: AgentConfig): AgentConfig => {
+		if (!frontmatterFields) return config;
+		const next = { ...config };
+		if (!hasDeclaredField("model")) delete next.model;
+		if (!hasDeclaredField("thinking")) delete next.thinking;
+		return next;
+	};
 	const {
 		override: _override,
+		description: _description,
 		output: _output,
 		outputMode: _outputMode,
 		defaultReads: _defaultReads,
 		model: _model,
 		fallbackModels: _fallbackModels,
+		fast: _fast,
 		thinking: _thinking,
 		systemPromptMode: _systemPromptMode,
 		inheritProjectContext: _inheritProjectContext,
@@ -271,26 +283,30 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		tools: _tools,
 		excludeTools: _excludeTools,
 		mcpDirectTools: _mcpDirectTools,
+		allowNestedSubagents: _allowNestedSubagents,
 		subagentOnlyExtensions: _subagentOnlyExtensions,
 		mutationTools: _mutationTools,
 		completionGuard: _completionGuard,
+		toolBudget: _toolBudget,
 		...editable
 	} = withoutExtensions;
 	if (!base) {
-		return withDeclaredExtensionPaths({
+		return withDeclaredExtensionPaths(withoutSettingsDefaults({
 			...withoutExtensions,
 			...(agent.extensionsFromDefault ? {} : agent.extensions !== undefined ? { extensions: [...agent.extensions] } : {}),
-		}, agent.filePath);
+		}), agent.filePath);
 	}
 
 	return withDeclaredExtensionPaths({
 		...editable,
+		description,
 		...(base.output !== undefined ? { output: base.output } : {}),
 		...(base.outputMode !== undefined ? { outputMode: base.outputMode } : {}),
 		...(base.defaultReads !== undefined ? { defaultReads: [...base.defaultReads] } : {}),
-		...(base.model !== undefined ? { model: base.model } : {}),
+		...(base.model !== undefined && hasDeclaredField("model") ? { model: base.model } : {}),
 		...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
-		...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
+		...(base.fast !== undefined ? { fast: base.fast } : {}),
+		...(base.thinking !== undefined && hasDeclaredField("thinking") ? { thinking: base.thinking } : {}),
 		systemPromptMode: base.systemPromptMode,
 		inheritProjectContext: base.inheritProjectContext,
 		inheritGlobalContext: base.inheritGlobalContext,
@@ -304,10 +320,12 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		...(base.tools !== undefined ? { tools: [...base.tools] } : {}),
 		...(base.excludeTools !== undefined ? { excludeTools: [...base.excludeTools] } : {}),
 		...(base.mcpDirectTools !== undefined ? { mcpDirectTools: [...base.mcpDirectTools] } : {}),
+		...(base.allowNestedSubagents !== undefined ? { allowNestedSubagents: base.allowNestedSubagents } : {}),
 		...(base.extensions !== undefined ? { extensions: [...base.extensions] } : {}),
 		...(base.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...base.subagentOnlyExtensions] } : {}),
 		...(base.mutationTools !== undefined ? { mutationTools: [...base.mutationTools] } : {}),
 		...(base.completionGuard !== undefined ? { completionGuard: base.completionGuard } : {}),
+		...(base.toolBudget !== undefined ? { toolBudget: base.toolBudget } : {}),
 	}, agent.filePath);
 }
 

package/src/agents/agents.ts

@@ -11,6 +11,7 @@ import { fileURLToPath } from "node:url";
 import type { AcceptanceInput, AcceptanceRole, AgentRunnerConfig, OutputMode, ToolBudgetConfig } 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 { expandHomePath } from "../shared/settings.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain, parseJsonChain } from "./chain-serializer.ts";
 import { mergeAgentsForScope } from "./agent-selection.ts";
@@ -113,6 +114,8 @@ interface BuiltinAgentOverrideInfo {
 	scope: "user" | "project";
 	path: string;
 	base: BuiltinAgentOverrideBase;
+	fields?: string[];
+	fieldScopes?: Record<string, Array<"user" | "project">>;
 }
 
 export interface AgentModelSourceInfo {
@@ -184,6 +187,7 @@ type ProjectRootResolution = "nearest" | "git-root";
 interface SubagentSettings {
 	overrides: Record<string, BuiltinAgentOverrideConfig>;
 	providerOverrides: Record<string, Record<string, BuiltinAgentOverrideConfig>>;
+	agentScanDirs?: string[];
 	defaultModel?: string;
 	defaultProvider?: string;
 	defaultThinking?: string;
@@ -1172,6 +1176,14 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 		}
 		defaultExtensions = subagentsObject.defaultExtensions.map((item) => item.trim());
 	}
+	let agentScanDirs: string[] | undefined;
+	if ("agentScanDirs" in subagentsObject) {
+		if (!Array.isArray(subagentsObject.agentScanDirs)
+			|| subagentsObject.agentScanDirs.some((item) => typeof item !== "string" || !item.trim())) {
+			throw new Error(`Subagent settings in '${filePath}' have invalid 'agentScanDirs'; expected an array of non-empty strings.`);
+		}
+		agentScanDirs = subagentsObject.agentScanDirs.map((item) => item.trim());
+	}
 	const modelScope = parseModelScopeConfig(subagentsObject.modelScope, { filePath });
 
 	const parsed: Record<string, BuiltinAgentOverrideConfig> = {};
@@ -1186,6 +1198,7 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
 		...(defaultThinking !== undefined ? { defaultThinking } : {}),
 		...(maxThinking !== undefined ? { maxThinking } : {}),
 		...(defaultExtensions !== undefined ? { defaultExtensions } : {}),
+		...(agentScanDirs !== undefined ? { agentScanDirs } : {}),
 		...(disableBuiltins !== undefined ? { disableBuiltins } : {}),
 		...(disableThinking !== undefined ? { disableThinking } : {}),
 		...(modelScope !== undefined ? { modelScope } : {}),
@@ -1348,9 +1361,19 @@ function applyBuiltinOverride(
 	override: BuiltinAgentOverrideConfig,
 	meta: { scope: "user" | "project"; path: string },
 ): AgentConfig {
+	const overrideInfo: BuiltinAgentOverrideInfo = {
+		...meta,
+		base: agent.override?.base ?? cloneOverrideBase(agent),
+		fields: [...new Set([...(agent.override?.fields ?? []), ...Object.keys(override)])].sort(),
+		fieldScopes: Object.fromEntries(Object.entries({ ...(agent.override?.fieldScopes ?? {}) }).map(([field, scopes]) => [field, [...scopes]])),
+	};
+	for (const field of Object.keys(override)) {
+		const scopes = overrideInfo.fieldScopes![field] ?? [];
+		overrideInfo.fieldScopes![field] = [...new Set([...scopes, meta.scope])].sort();
+	}
 	const next: AgentConfig = {
 		...agent,
-		override: { ...meta, base: cloneOverrideBase(agent) },
+		override: overrideInfo,
 	};
 
 	if (override.description !== undefined) next.description = override.description;
@@ -1450,128 +1473,12 @@ function applyBuiltinOverrides(
 	});
 }
 
-export function agentHasFrontmatterField(agent: AgentConfig, ...fields: string[]): boolean {
-	const frontmatterFields = agentFrontmatterFields.get(agent);
-	return frontmatterFields ? fields.some((field) => frontmatterFields.has(field)) : false;
-}
-
 function applyCustomAgentOverride(
 	agent: AgentConfig,
 	override: BuiltinAgentOverrideConfig,
 	meta: { scope: "user" | "project"; path: string },
 ): AgentConfig {
-	let next: AgentConfig | undefined;
-	let anyFilled = false;
-
-	const mutable = (): AgentConfig => {
-		next ??= { ...agent };
-		return next;
-	};
-
-	const fill = <K extends keyof AgentConfig>(
-		field: K,
-		frontmatterFields: string[],
-		value: AgentConfig[K],
-	): void => {
-		if (agentHasFrontmatterField(agent, ...frontmatterFields)) return;
-		const target = mutable();
-		if (value === undefined) delete target[field]; else target[field] = value;
-		anyFilled = true;
-	};
-
-	if (override.description !== undefined) {
-		mutable().description = override.description;
-		anyFilled = true;
-	}
-	if (override.output !== undefined) {
-		fill("output", ["output"], override.output === false ? undefined : override.output);
-	}
-	if (override.outputMode !== undefined) {
-		fill("outputMode", ["outputMode"], override.outputMode);
-	}
-	if (override.defaultReads !== undefined) {
-		fill("defaultReads", ["defaultReads"], override.defaultReads === false ? undefined : [...override.defaultReads]);
-	}
-	if (override.model !== undefined && !agentHasFrontmatterField(agent, "model")) {
-		const target = mutable();
-		if (override.model === false) delete target.model; else target.model = override.model;
-		delete target.modelSource;
-		anyFilled = true;
-	}
-	if (override.defaultProvider !== undefined) {
-		fill("modelProvider", ["modelProvider", "defaultProvider"], override.defaultProvider === false ? undefined : override.defaultProvider);
-	}
-	if (override.fallbackModels !== undefined) {
-		fill(
-			"fallbackModels",
-			["fallbackModels"],
-			override.fallbackModels === false ? undefined : [...override.fallbackModels],
-		);
-	}
-	if (override.fast !== undefined) {
-		fill("fast", ["fast"], override.fast);
-	}
-	if (override.thinking !== undefined) {
-		fill("thinking", ["thinking"], override.thinking === false ? undefined : override.thinking);
-	}
-	if (override.systemPromptMode !== undefined) {
-		fill("systemPromptMode", ["systemPromptMode"], override.systemPromptMode);
-	}
-	if (override.inheritProjectContext !== undefined) {
-		fill("inheritProjectContext", ["inheritProjectContext"], override.inheritProjectContext);
-	}
-	if (override.inheritGlobalContext !== undefined) {
-		fill("inheritGlobalContext", ["inheritGlobalContext"], override.inheritGlobalContext);
-	}
-	if (override.inheritSkills !== undefined) {
-		fill("inheritSkills", ["inheritSkills"], override.inheritSkills);
-	}
-	if (override.defaultContext !== undefined) {
-		fill("defaultContext", ["defaultContext"], override.defaultContext === false ? undefined : override.defaultContext);
-	}
-	if (override.acceptanceRole !== undefined) {
-		fill("acceptanceRole", ["acceptanceRole"], override.acceptanceRole === false ? undefined : override.acceptanceRole);
-	}
-	if (override.disabled !== undefined) {
-		// Custom agent files cannot set `disabled`, so project overrides replace user overrides.
-		mutable().disabled = override.disabled;
-		anyFilled = true;
-	}
-	if (override.skills !== undefined) {
-		fill("skills", ["skill", "skills"], override.skills === false ? undefined : [...override.skills]);
-	}
-	if (override.tools !== undefined && !agentHasFrontmatterField(agent, "tools")) {
-		applyToolsOverride(mutable(), override.tools);
-		anyFilled = true;
-	}
-	if (override.excludeTools !== undefined) {
-		fill("excludeTools", ["excludeTools"], override.excludeTools === false ? undefined : [...override.excludeTools]);
-	}
-	if (override.allowNestedSubagents !== undefined) {
-		fill("allowNestedSubagents", ["allowNestedSubagents"], override.allowNestedSubagents);
-	}
-	if (override.extensions !== undefined) {
-		fill("extensions", ["extensions"], override.extensions === false ? undefined : [...override.extensions]);
-	}
-	if (override.subagentOnlyExtensions !== undefined) {
-		fill(
-			"subagentOnlyExtensions",
-			["subagentOnlyExtensions"],
-			override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions],
-		);
-	}
-	if (override.mutationTools !== undefined) {
-		fill("mutationTools", ["mutationTools"], override.mutationTools === false ? undefined : [...override.mutationTools]);
-	}
-	if (override.completionGuard !== undefined) {
-		fill("completionGuard", ["completionGuard"], override.completionGuard);
-	}
-	if (override.toolBudget !== undefined) {
-		fill("toolBudget", ["toolBudget"], override.toolBudget === false ? undefined : override.toolBudget);
-	}
-
-	if (!anyFilled || !next) return agent;
-	next.override = { ...meta, base: agent.override?.base ?? cloneOverrideBase(agent) };
+	const next = applyBuiltinOverride(agent, override, meta);
 	const frontmatterFields = agentFrontmatterFields.get(agent);
 	if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
 	return next;
@@ -2342,6 +2249,61 @@ function extraUserAgentDirs(): string[] {
 		.filter((dir) => dir.length > 0);
 }
 
+interface AgentScanDirs {
+	dirs: string[];
+	watchPaths: string[];
+}
+
+function readConfiguredAgentScanDirs(filePath: string | null): string[] {
+	if (!filePath) return [];
+	try {
+		const settings = readSettingsFileStrict(filePath);
+		const subagents = settings.subagents;
+		if (!subagents || typeof subagents !== "object" || Array.isArray(subagents)) return [];
+		const dirs = (subagents as { agentScanDirs?: unknown }).agentScanDirs;
+		return Array.isArray(dirs) ? dirs.filter((dir): dir is string => typeof dir === "string" && dir.trim().length > 0) : [];
+	} catch {
+		return [];
+	}
+}
+
+function expandAgentScanDirPattern(pattern: string): AgentScanDirs {
+	const expanded = expandHomePath(pattern.trim()).replace(/[\\/]+/g, path.sep);
+	if (!expanded) return { dirs: [], watchPaths: [] };
+	const wildcardMatches = [...expanded.matchAll(/\*/g)];
+	if (wildcardMatches.length === 0) {
+		const dir = path.resolve(expanded);
+		return { dirs: fs.existsSync(dir) ? [dir] : [], watchPaths: [dir] };
+	}
+	const parts = expanded.split(path.sep);
+	const wildcardIndex = parts.findIndex((part) => part.includes("*"));
+	if (wildcardMatches.length !== 1 || wildcardIndex === -1 || parts[wildcardIndex] !== "*") return { dirs: [], watchPaths: [] };
+	const base = path.resolve(parts.slice(0, wildcardIndex).join(path.sep) || path.sep);
+	const rest = parts.slice(wildcardIndex + 1);
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(base, { withFileTypes: true });
+	} catch {
+		return { dirs: [], watchPaths: [base] };
+	}
+	const candidateDirs = entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(base, entry.name, ...rest));
+	return {
+		dirs: candidateDirs.filter((dir) => fs.existsSync(dir)),
+		watchPaths: [base, ...candidateDirs],
+	};
+}
+
+function settingsAgentScanDirs(entries: string[]): AgentScanDirs {
+	const dirs = new Set<string>();
+	const watchPaths = new Set<string>();
+	for (const entry of entries) {
+		const expanded = expandAgentScanDirPattern(entry);
+		for (const dir of expanded.dirs) dirs.add(dir);
+		for (const watchPath of expanded.watchPaths) watchPaths.add(watchPath);
+	}
+	return { dirs: [...dirs], watchPaths: [...watchPaths] };
+}
+
 export interface AgentDiscoveryAllResult {
 	builtin: AgentConfig[];
 	package: AgentConfig[];
@@ -2502,16 +2464,18 @@ function buildAgentDiscoverySources(cwd: string, preferredModelProvider?: string
 	const userSettingsPath = getUserAgentSettingsPath();
 	const projectSettingsPath = getProjectAgentSettingsPath(effectiveCwd);
 	const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd);
+	const userScanDirs = settingsAgentScanDirs(readConfiguredAgentScanDirs(userSettingsPath));
+	const projectScanDirs = settingsAgentScanDirs(readConfiguredAgentScanDirs(projectSettingsPath));
 
 	const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
-	const userLoaded = [...extraUserAgentDirs(), userDirOld, userDirNew].map((dir, discoveryPriority): LoadedAgentDirectory => {
+	const userLoaded = [...extraUserAgentDirs(), ...userScanDirs.dirs, userDirOld, userDirNew].map((dir, discoveryPriority): LoadedAgentDirectory => {
 		const inspection = inspectAgentDefinitionDirectory(dir);
 		return { dir, inspection, loaded: loadAgentsFromDir(dir, "user", discoveryPriority, undefined, inspection) };
 	});
 	const projectInspections = new Map(projectCandidateDirs.map((dir) => [dir, inspectAgentDefinitionDirectory(dir)]));
-	const projectLoaded = projectAgentDirs.map((dir): LoadedAgentDirectory => {
-		const inspection = projectInspections.get(dir)!;
-		return { dir, inspection, loaded: loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0, undefined, inspection) };
+	const projectLoaded = [...projectScanDirs.dirs, ...projectAgentDirs].map((dir, discoveryPriority): LoadedAgentDirectory => {
+		const inspection = projectInspections.get(dir) ?? inspectAgentDefinitionDirectory(dir);
+		return { dir, inspection, loaded: loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : discoveryPriority, undefined, inspection) };
 	});
 	const packageLoaded = packageSubagentPaths.agents.map((entry, index): LoadedAgentDirectory => {
 		const inspection = inspectAgentDefinitionDirectory(entry.dir);
@@ -2523,6 +2487,8 @@ function buildAgentDiscoverySources(cwd: string, preferredModelProvider?: string
 		...(projectSettingsPath ? [projectSettingsPath] : []),
 		...projectDiscoveryWatchPaths(effectiveCwd),
 		...findProjectRootCandidates(effectiveCwd).map((root) => path.join(getProjectConfigDir(root), "settings.json")),
+		...userScanDirs.watchPaths,
+		...projectScanDirs.watchPaths,
 		...packageSubagentPaths.watchPaths,
 	]);
 	for (const directory of userLoaded) addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
@@ -2530,6 +2496,7 @@ function buildAgentDiscoverySources(cwd: string, preferredModelProvider?: string
 		const inspection = projectInspections.get(dir);
 		addDirectoryWatchPaths(watchPaths, dir, inspection?.files ?? [], inspection ? inspectedAgentDefinitionDirectories(inspection, dir) : []);
 	}
+	for (const directory of projectLoaded) addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
 	for (const directory of packageLoaded) addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
 
 	const userDir = process.env.PI_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
@@ -2665,7 +2632,16 @@ function configuredAgentsForScope(sources: AgentDiscoverySources, scope: AgentSc
 function discoveryDirectories(sources: AgentDiscoverySources, scope: AgentScope): AgentDefinitionDirectoryReport[] {
 	const directories: AgentDefinitionDirectoryReport[] = [reportAgentDefinitionDirectory("builtin", BUILTIN_AGENTS_DIR, BUILTIN_AGENT_DEFINITION_INSPECTION)];
 	if (scope !== "project") for (const directory of sources.userLoaded) directories.push(reportAgentDefinitionDirectory("user", directory.dir, directory.inspection));
-	if (scope !== "user") for (const dir of sources.projectCandidateDirs) directories.push(reportAgentDefinitionDirectory("project", dir, sources.projectInspections.get(dir)!));
+	if (scope !== "user") {
+		const reported = new Set<string>();
+		for (const dir of sources.projectCandidateDirs) {
+			reported.add(path.resolve(dir));
+			directories.push(reportAgentDefinitionDirectory("project", dir, sources.projectInspections.get(dir)!));
+		}
+		for (const directory of sources.projectLoaded) {
+			if (!reported.has(path.resolve(directory.dir))) directories.push(reportAgentDefinitionDirectory("project", directory.dir, directory.inspection));
+		}
+	}
 	for (const directory of sources.packageLoaded) {
 		if (directory.packageEntry && packageEntryIncluded(scope, directory.packageEntry.scope)) directories.push(reportAgentDefinitionDirectory("package", directory.dir, directory.inspection));
 	}
@@ -2774,7 +2750,9 @@ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelPr
 	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);
-	const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), userDirOld, userDirNew].map((dir, discoveryPriority) => {
+	const userScanDirs = settingsAgentScanDirs(userSettings.agentScanDirs ?? []);
+	const projectScanDirs = settingsAgentScanDirs(projectSettings.agentScanDirs ?? []);
+	const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), ...userScanDirs.dirs, userDirOld, userDirNew].map((dir, discoveryPriority) => {
 		const inspection = inspectAgentDefinitionDirectory(dir);
 		directories.push(reportAgentDefinitionDirectory("user", dir, inspection));
 		return loadAgentsFromDir(dir, "user", discoveryPriority, undefined, inspection);
@@ -2782,7 +2760,11 @@ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelPr
 	const userAgents = applyCustomAgentOverrides(applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
 	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 projectLoaded = scope === "user" ? [] : [...projectScanDirs.dirs, ...projectAgentDirs].map((dir, discoveryPriority) => {
+		const inspection = projectInspections.get(dir) ?? inspectAgentDefinitionDirectory(dir);
+		if (!projectInspections.has(dir)) directories.push(reportAgentDefinitionDirectory("project", dir, inspection));
+		return loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : discoveryPriority, undefined, inspection);
+	});
 	const projectAgents = applyCustomAgentOverrides(applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
 	const packageLoaded = packageSubagentPaths.agents.map((entry, index) => {
 		const inspection = inspectAgentDefinitionDirectory(entry.dir);

package/src/api/shared-types.ts

@@ -20,5 +20,8 @@ export {
 	type SubagentResultStatus,
 	type SubagentRunMode,
 	type Usage,
+	type ManagedWorktreeProvider,
+	type WorktreeNaming,
+	type WorktreeProvider,
 	type WorkflowResourceProvenanceV1,
 } from "../shared/types.ts";

package/src/extension/config.ts

@@ -9,6 +9,7 @@ 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";
+import { normalizeWorktreeBranchPrefix } from "../runs/shared/worktree.ts";
 
 const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
 const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
@@ -138,6 +139,16 @@ function validateMainWindowRendererConfig(value: unknown): void {
 }
 
 function validateConfig(config: Record<string, unknown>): void {
+	if (config.worktree !== undefined && typeof config.worktree !== "boolean") {
+		throw new Error("config.worktree must be a boolean");
+	}
+	if (config.worktreeProvider !== undefined && config.worktreeProvider !== "auto" && config.worktreeProvider !== "native" && config.worktreeProvider !== "worktrunk") {
+		throw new Error('config.worktreeProvider must be "auto", "native", or "worktrunk"');
+	}
+	if (config.worktreeBranchPrefix !== undefined) {
+		if (typeof config.worktreeBranchPrefix !== "string") throw new Error("config.worktreeBranchPrefix must be a string");
+		normalizeWorktreeBranchPrefix(config.worktreeBranchPrefix);
+	}
 	if (config.defaultSubagentContext !== undefined && config.defaultSubagentContext !== "fresh" && config.defaultSubagentContext !== "fork") {
 		throw new Error('config.defaultSubagentContext must be "fresh" or "fork"');
 	}
@@ -229,6 +240,15 @@ export function loadConfig(): ExtensionConfig {
 		return readConfigForUpdate(configPath);
 	} catch (error) {
 		if (error instanceof PrunedForkConfigError) throw error;
+		// An explicitly requested worktree provider/prefix must not be silently
+		// discarded and replaced by the built-in defaults after validation fails.
+		try {
+			const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
+			if (raw && typeof raw === "object" && !Array.isArray(raw)
+				&& (Object.hasOwn(raw, "worktreeProvider") || Object.hasOwn(raw, "worktreeBranchPrefix"))) throw error;
+		} catch (readError) {
+			if (readError === error) throw error;
+		}
 		console.error(`Failed to load subagent config from '${configPath}':`, error);
 	}
 	return {};

package/src/inspectors/herdr/inspector-runner.ts

@@ -41,7 +41,8 @@ export function formatInspectorDashboard(input: { status: AsyncStatus; asyncDir:
 		lines.push("");
 	}
 	lines.push(formatAsyncRunTranscript(status, asyncDir, { index: input.index, lines: 60, sessionRoots: input.sessionRoots }));
-	const controls = [input.allowSteer === false ? undefined : "steer <message>", input.allowStop === false ? undefined : "stop", "status"].filter(Boolean);
+	const acceptsPlainGuidance = input.index !== undefined || status.mode === "single";
+	const controls = [input.allowSteer === false || !acceptsPlainGuidance ? undefined : "type guidance", input.allowSteer === false ? undefined : "steer <message>", input.allowStop === false ? undefined : "stop", "status"].filter(Boolean);
 	lines.push("", `Controls: ${controls.join(" | ")}`, "Supervisor replies remain in the parent Pi session (subagent_supervisor/intercom).");
 	return lines.join("\n");
 }
@@ -81,6 +82,20 @@ function isTerminal(status: AsyncStatus): boolean {
 	return status.state !== "queued" && status.state !== "running";
 }
 
+function queueInspectorSteer(options: RunnerOptions, status: AsyncStatus, message: string): string {
+	if (options.allowSteer === false) throw new Error("Authority policy does not allow steer from this inspector.");
+	if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be steered.`);
+	const runningIndexes = (status.steps ?? []).map((step, index) => step.status === "running" ? index : undefined).filter((index): index is number => index !== undefined);
+	const targetIndex = options.index ?? (status.mode === "single" ? 0 : undefined);
+	if (targetIndex === undefined && runningIndexes.length === 0) throw new Error("No running child is available to steer. Open a child-specific inspector for a pending child.");
+	requestAsyncSteer(options.asyncDir, {
+		message,
+		...(targetIndex !== undefined ? { targetIndex } : { targetIndexes: runningIndexes }),
+		source: "herdr-inspector",
+	});
+	return steeringReceipt(message, `Steering queued for run ${options.runId}.`);
+}
+
 export function submitInspectorControl(options: RunnerOptions, line: string): string {
 	const command = line.trim();
 	if (!command || command === "status") return "Status refreshed.";
@@ -93,22 +108,13 @@ export function submitInspectorControl(options: RunnerOptions, line: string): st
 		return `Stop requested for run ${options.runId}.`;
 	}
 	if (command.startsWith("steer ")) {
-		if (options.allowSteer === false) throw new Error("Authority policy does not allow steer from this inspector.");
 		const message = command.slice("steer ".length).trim();
 		if (!message) throw new Error("steer requires a message.");
-		if (isTerminal(status)) throw new Error(`Run '${options.runId}' is ${status.state} and cannot be steered.`);
-		const runningIndexes = (status.steps ?? []).map((step, index) => step.status === "running" ? index : undefined).filter((index): index is number => index !== undefined);
-		const targetIndex = options.index ?? (status.mode === "single" ? 0 : undefined);
-		if (targetIndex === undefined && runningIndexes.length === 0) throw new Error("No running child is available to steer. Open a child-specific inspector for a pending child.");
-		requestAsyncSteer(options.asyncDir, {
-			message,
-			...(targetIndex !== undefined ? { targetIndex } : { targetIndexes: runningIndexes }),
-			source: "herdr-inspector",
-		});
-		return steeringReceipt(message, `Steering queued for run ${options.runId}.`);
+		return queueInspectorSteer(options, status, message);
 	}
 	if (command.startsWith("reply ")) throw new Error("Supervisor replies are owned by the parent Pi session; use subagent_supervisor/intercom there.");
-	throw new Error("Unknown control. Use steer <message>, stop, or status.");
+	if (options.index === undefined && status.mode !== "single") throw new Error("Plain guidance requires a child-specific inspector. Use steer <message> to target all running children from the aggregate inspector.");
+	return queueInspectorSteer(options, status, command);
 }
 
 export function runInspector(argv = process.argv.slice(2)): void {

package/src/runs/background/active-async-capacity.ts

@@ -271,7 +271,6 @@ function workflowReleaseVerdict(owner: ActiveAsyncCapacityOwnerV1, status: Async
 	if (liveWorkflowRunIds.has(owner.runId)) return { state: "retained", reason: "workflow controller is still live" };
 	for (const step of status.steps ?? []) {
 		const label = step.workflowKey ?? step.agent;
-		if (step.status === "pending" || step.status === "running" || step.status === "paused") return { state: "retained", reason: `workflow child ${label} is still ${step.status}` };
 		if (typeof step.async !== "boolean") return { state: "retained", reason: `workflow child ${label} is missing async classification` };
 		if (!step.async) continue;
 		if (!step.runId) return { state: "retained", reason: `async workflow child ${label} is missing run id` };