pi-subagents 0.34.0 → 0.35.0

package/src/agents/agent-management.ts

@@ -21,8 +21,9 @@ import {
 	removeBuiltinAgentOverrideFields,
 } from "./agents.ts";
 import { serializeAgent } from "./agent-serializer.ts";
+import { mergeAgentsForScope } from "./agent-selection.ts";
 import { serializeChain, serializeJsonChain } from "./chain-serializer.ts";
-import { discoverAvailableSkills } from "./skills.ts";
+import { discoverAvailableSkills, resolveSkills } from "./skills.ts";
 import {
 	buildProactiveSkillSubagentRecommendationLines,
 } from "./proactive-skills.ts";
@@ -30,7 +31,9 @@ import { parseFrontmatter } from "./frontmatter.ts";
 import { toModelInfo } from "../shared/model-info.ts";
 import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
 import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
-import type { Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
+import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
+import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
+import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
 import { getProjectConfigDir } from "../shared/utils.ts";
 
 type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete" | "eject" | "disable" | "enable" | "reset";
@@ -119,7 +122,7 @@ function findChains(name: string, cwd: string, scope: AgentScope = "both"): Chai
 	const raw = name.trim();
 	const sanitized = sanitizeName(raw);
 	return discoverAgentsAll(cwd).chains
-		.filter((c) => (scope === "both" || c.source === scope) && (c.name === raw || c.name === sanitized))
+		.filter((c) => (scope === "both" || c.source === "package" || c.source === scope) && (c.name === raw || c.name === sanitized))
 		.sort((a, b) => a.source.localeCompare(b.source));
 }
 
@@ -187,14 +190,18 @@ function fallbackModelsWarning(ctx: ManagementContext, fallbackModels: string[]
 	return missing.length ? `Warning: fallback models not in the current model registry: ${missing.join(", ")}.` : undefined;
 }
 
-function skillsWarning(cwd: string, skills: string[] | undefined): string | undefined {
-	if (!skills || skills.length === 0) return undefined;
-	const available = new Set(discoverAvailableSkills(cwd).map((s) => s.name));
-	const missing = skills.filter((s) => !available.has(s));
+function skillsWarning(cwd: string, agent: Pick<AgentConfig, "skills" | "skillPath" | "filePath">): string | undefined {
+	if (!agent.skills?.length) return undefined;
+	const { missing } = resolveSkills(
+		agent.skills,
+		cwd,
+		agent.skillPath,
+		agent.filePath ? path.dirname(agent.filePath) : cwd,
+	);
 	return missing.length ? `Warning: skills not found: ${missing.join(", ")}.` : undefined;
 }
 
-function editableAgentConfig(agent: AgentConfig): AgentConfig {
+export function editableAgentConfig(agent: AgentConfig): AgentConfig {
 	const base = agent.override?.base;
 	if (!base) return { ...agent };
 
@@ -207,9 +214,11 @@ function editableAgentConfig(agent: AgentConfig): AgentConfig {
 		inheritProjectContext: base.inheritProjectContext,
 		inheritSkills: base.inheritSkills,
 		defaultContext: base.defaultContext,
+		acceptanceRole: base.acceptanceRole,
 		disabled: base.disabled,
 		systemPrompt: base.systemPrompt,
 		skills: base.skills ? [...base.skills] : undefined,
+		skillPath: base.skillPath ? [...base.skillPath] : undefined,
 		tools: base.tools ? [...base.tools] : undefined,
 		mcpDirectTools: base.mcpDirectTools ? [...base.mcpDirectTools] : undefined,
 		subagentOnlyExtensions: base.subagentOnlyExtensions ? [...base.subagentOnlyExtensions] : undefined,
@@ -227,7 +236,7 @@ function readAgentFrontmatterFields(filePath: string): Set<string> {
 	}
 }
 
-function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string, unknown>): Set<string> {
+export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string, unknown>): Set<string> {
 	const fields = readAgentFrontmatterFields(agent.filePath);
 	const changed = (...names: string[]) => {
 		for (const name of names) fields.delete(name);
@@ -241,6 +250,7 @@ function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string,
 	if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
 	if (hasKey(cfg, "tools")) changed("tools");
 	if (hasKey(cfg, "skills")) changed("skill", "skills");
+	if (hasKey(cfg, "skillPath")) changed("skillPath");
 	if (hasKey(cfg, "extensions")) changed("extensions");
 	if (hasKey(cfg, "subagentOnlyExtensions")) changed("subagentOnlyExtensions");
 	if (hasKey(cfg, "thinking")) {
@@ -260,6 +270,11 @@ function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<string,
 		fields.add("inheritSkills");
 	}
 	if (hasKey(cfg, "defaultContext")) changed("defaultContext");
+	if (hasKey(cfg, "async")) changed("async");
+	if (hasKey(cfg, "timeoutMs")) changed("timeoutMs");
+	if (hasKey(cfg, "turnBudget")) changed("turnBudget");
+	if (hasKey(cfg, "acceptance")) changed("acceptance");
+	if (hasKey(cfg, "acceptanceRole")) changed("acceptanceRole");
 	if (hasKey(cfg, "output")) changed("output");
 	if (hasKey(cfg, "reads")) changed("defaultReads");
 	if (hasKey(cfg, "progress")) changed("defaultProgress");
@@ -382,6 +397,14 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (typeof cfg.skills === "string") { const skills = parseCsv(cfg.skills); target.skills = skills.length ? skills : undefined; }
 		else return "config.skills must be a comma-separated string or false when provided.";
 	}
+	if (hasKey(cfg, "skillPath")) {
+		if (cfg.skillPath === false || cfg.skillPath === "") target.skillPath = undefined;
+		else if (typeof cfg.skillPath === "string") { const skillPath = parseCsv(cfg.skillPath); target.skillPath = skillPath.length ? skillPath : undefined; }
+		else if (Array.isArray(cfg.skillPath) && cfg.skillPath.every((entry) => typeof entry === "string")) {
+			const skillPath = [...new Set(cfg.skillPath.map((entry) => entry.trim()).filter(Boolean))];
+			target.skillPath = skillPath.length ? skillPath : undefined;
+		} else return "config.skillPath must be a comma-separated string, string array, or false when provided.";
+	}
 	if (hasKey(cfg, "extensions")) {
 		if (cfg.extensions === false) target.extensions = undefined;
 		else if (cfg.extensions === "") target.extensions = [];
@@ -416,6 +439,37 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
 		else if (cfg.defaultContext === "fresh" || cfg.defaultContext === "fork") target.defaultContext = cfg.defaultContext;
 		else return "config.defaultContext must be 'fresh', 'fork', or false when provided.";
 	}
+	if (hasKey(cfg, "async")) {
+		if (cfg.async === "") target.defaultAsync = undefined;
+		else if (typeof cfg.async === "boolean") target.defaultAsync = cfg.async;
+		else return "config.async must be a boolean or empty string when provided.";
+	}
+	if (hasKey(cfg, "timeoutMs")) {
+		if (cfg.timeoutMs === false || cfg.timeoutMs === "") target.defaultTimeoutMs = undefined;
+		else if (typeof cfg.timeoutMs === "number" && Number.isInteger(cfg.timeoutMs) && cfg.timeoutMs > 0) target.defaultTimeoutMs = cfg.timeoutMs;
+		else return "config.timeoutMs must be a positive integer or false when provided.";
+	}
+	if (hasKey(cfg, "turnBudget")) {
+		if (cfg.turnBudget === false || cfg.turnBudget === "") target.defaultTurnBudget = undefined;
+		else {
+			const resolved = resolveTurnBudgetConfig(cfg.turnBudget, "config.turnBudget");
+			if (resolved.error) return resolved.error;
+			target.defaultTurnBudget = resolved.turnBudget;
+		}
+	}
+	if (hasKey(cfg, "acceptance")) {
+		if (cfg.acceptance === "") target.defaultAcceptance = undefined;
+		else {
+			const errors = validateAcceptanceInput(cfg.acceptance, "config.acceptance");
+			if (errors.length > 0) return errors.join(" ");
+			target.defaultAcceptance = cfg.acceptance as AcceptanceInput;
+		}
+	}
+	if (hasKey(cfg, "acceptanceRole")) {
+		if (cfg.acceptanceRole === false || cfg.acceptanceRole === "") target.acceptanceRole = undefined;
+		else if (cfg.acceptanceRole === "read-only" || cfg.acceptanceRole === "writer") target.acceptanceRole = cfg.acceptanceRole;
+		else return "config.acceptanceRole must be 'read-only', 'writer', or false when provided.";
+	}
 	if (hasKey(cfg, "output")) {
 		if (cfg.output === false || cfg.output === "") target.output = undefined;
 		else if (typeof cfg.output === "string") target.output = cfg.output;
@@ -508,10 +562,16 @@ function formatAgentDetail(agent: AgentConfig): string {
 	if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
 	if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
 	if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
+	if (agent.skillPath?.length) lines.push(`Skill paths: ${agent.skillPath.join(", ")}`);
 	lines.push(`System prompt mode: ${agent.systemPromptMode}`);
 	lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
 	lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
 	if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
+	if (agent.defaultAsync !== undefined) lines.push(`Async: ${agent.defaultAsync ? "true" : "false"}`);
+	if (agent.defaultTimeoutMs !== undefined) lines.push(`Timeout: ${agent.defaultTimeoutMs}ms`);
+	if (agent.defaultTurnBudget) lines.push(`Turn budget: ${JSON.stringify(agent.defaultTurnBudget)}`);
+	if (agent.defaultAcceptance !== undefined) lines.push(`Acceptance: ${typeof agent.defaultAcceptance === "object" ? JSON.stringify(agent.defaultAcceptance) : String(agent.defaultAcceptance)}`);
+	if (agent.acceptanceRole) lines.push(`Acceptance role: ${agent.acceptanceRole}`);
 	if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
 	if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
 	if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
@@ -580,7 +640,8 @@ function formatChainDetail(chain: ChainConfig): string {
 export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	const scope = normalizeListScope(params.agentScope) ?? "both";
 	const d = discoverAgentsAll(ctx.cwd);
-	const scopedAgents = allAgents(d).filter((a) => scope === "both" || a.source === "builtin" || a.source === "package" || a.source === scope).sort((a, b) => a.name.localeCompare(b.name));
+	const scopedAgents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package)
+		.sort((a, b) => a.name.localeCompare(b.name));
 	const agents = scopedAgents.filter((a) => !a.disabled);
 	const chains = d.chains.filter((c) => scope === "both" || c.source === "package" || c.source === scope).sort((a, b) => a.name.localeCompare(b.name));
 	const diagnostics = d.chainDiagnostics.filter((entry) => scope === "both" || entry.source === scope);
@@ -687,11 +748,17 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
 
 function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
 	if (!params.agent && !params.chainName) return result("Specify 'agent' or 'chainName' for get.", true);
+	const scope = normalizeListScope(params.agentScope);
+	if (!scope) return result("agentScope must be 'user', 'project', or 'both' for get.", true);
 	const hasBoth = Boolean(params.agent && params.chainName);
 	const blocks: string[] = [];
 	let anyFound = false;
 	if (params.agent) {
-		const matches = findAgents(params.agent, ctx.cwd, "both");
+		const raw = params.agent.trim();
+		const sanitized = sanitizeName(raw);
+		const d = discoverAgentsAll(ctx.cwd);
+		const matches = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package)
+			.filter((agent) => agent.name === raw || agent.name === sanitized);
 		if (!matches.length) {
 			const msg = `Agent '${params.agent}' not found. Available: ${availableNames(ctx.cwd, "agent").join(", ") || "none"}.`;
 			if (!hasBoth) return result(msg, true);
@@ -702,7 +769,7 @@ function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolR
 		}
 	}
 	if (params.chainName) {
-		const matches = findChains(params.chainName, ctx.cwd, "both");
+		const matches = findChains(params.chainName, ctx.cwd, scope);
 		if (!matches.length) {
 			const msg = `Chain '${params.chainName}' not found. Available: ${availableNames(ctx.cwd, "chain").join(", ") || "none"}.`;
 			if (!hasBoth) return result(msg, true);
@@ -770,7 +837,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
 	if (mw) warnings.push(mw);
 	const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
 	if (fmw) warnings.push(fmw);
-	const sw = skillsWarning(ctx.cwd, agent.skills);
+	const sw = skillsWarning(ctx.cwd, agent);
 	if (sw) warnings.push(sw);
 	fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
 	return result([`Created agent '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
@@ -819,8 +886,8 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
 			const fmw = fallbackModelsWarning(ctx, updated.fallbackModels);
 			if (fmw) warnings.push(fmw);
 		}
-		if (hasKey(cfg, "skills")) {
-			const sw = skillsWarning(ctx.cwd, updated.skills);
+		if (hasKey(cfg, "skills") || hasKey(cfg, "skillPath")) {
+			const sw = skillsWarning(ctx.cwd, updated);
 			if (sw) warnings.push(sw);
 		}
 		if (updated.name !== oldName) {

package/src/agents/agent-serializer.ts

@@ -13,8 +13,14 @@ export const KNOWN_FIELDS = new Set([
 	"inheritProjectContext",
 	"inheritSkills",
 	"defaultContext",
+	"async",
+	"timeoutMs",
+	"turnBudget",
+	"acceptance",
+	"acceptanceRole",
 	"skill",
 	"skills",
+	"skillPath",
 	"extensions",
 	"subagentOnlyExtensions",
 	"output",
@@ -62,9 +68,22 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
 	if (!preservingExistingFrontmatter || preserve("inheritProjectContext")) lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
 	if (!preservingExistingFrontmatter || preserve("inheritSkills")) lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
 	if (config.defaultContext || preserve("defaultContext")) lines.push(`defaultContext: ${config.defaultContext ?? ""}`);
+	if (config.defaultAsync !== undefined || preserve("async")) lines.push(`async: ${config.defaultAsync === undefined ? "" : config.defaultAsync ? "true" : "false"}`);
+	if (config.defaultTimeoutMs !== undefined || preserve("timeoutMs")) lines.push(`timeoutMs: ${config.defaultTimeoutMs ?? ""}`);
+	if (config.defaultTurnBudget || preserve("turnBudget")) lines.push(`turnBudget: ${config.defaultTurnBudget ? JSON.stringify(config.defaultTurnBudget) : ""}`);
+	if (config.defaultAcceptance !== undefined || preserve("acceptance")) {
+		lines.push(`acceptance: ${config.defaultAcceptance === undefined
+			? ""
+			: typeof config.defaultAcceptance === "object"
+				? JSON.stringify(config.defaultAcceptance)
+				: String(config.defaultAcceptance)}`);
+	}
+	if (config.acceptanceRole || preserve("acceptanceRole")) lines.push(`acceptanceRole: ${config.acceptanceRole ?? ""}`);
 
 	const skillsValue = joinComma(config.skills);
 	if (skillsValue || preserve("skill", "skills")) lines.push(`skills: ${skillsValue ?? ""}`);
+	const skillPathValue = joinComma(config.skillPath);
+	if (skillPathValue || preserve("skillPath")) lines.push(`skillPath: ${skillPathValue ?? ""}`);
 
 	if (config.extensions !== undefined) {
 		const extensionsValue = joinComma(config.extensions);

package/src/agents/agents.ts

@@ -4,19 +4,22 @@
 
 import { execSync } from "node:child_process";
 import * as fs from "node:fs";
+import { parse as parseYaml } from "yaml";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AcceptanceInput, OutputMode, ToolBudgetConfig } from "../shared/types.ts";
+import type { AcceptanceInput, AcceptanceRole, OutputMode, ToolBudgetConfig, TurnBudgetConfig } from "../shared/types.ts";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
 import { KNOWN_FIELDS } from "./agent-serializer.ts";
 import { parseChain, parseJsonChain } from "./chain-serializer.ts";
 import { mergeAgentsForScope } from "./agent-selection.ts";
-import { parseFrontmatter } from "./frontmatter.ts";
+import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.ts";
 import { buildRuntimeName, parsePackageName } from "./identity.ts";
 import { parseModelScopeConfig, type ModelScopeConfig } from "../runs/shared/model-scope.ts";
 export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.ts";
 import { parseMemoryFrontmatter } from "./agent-memory.ts";
+import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
+import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
 
 export type AgentScope = "user" | "project" | "both";
 
@@ -62,9 +65,11 @@ export interface BuiltinAgentOverrideBase {
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
 	defaultContext?: AgentDefaultContext;
+	acceptanceRole?: AcceptanceRole;
 	disabled?: boolean;
 	systemPrompt: string;
 	skills?: string[];
+	skillPath?: string[];
 	tools?: string[];
 	mcpDirectTools?: string[];
 	subagentOnlyExtensions?: string[];
@@ -80,6 +85,7 @@ interface BuiltinAgentOverrideConfig {
 	inheritProjectContext?: boolean;
 	inheritSkills?: boolean;
 	defaultContext?: AgentDefaultContext | false;
+	acceptanceRole?: AcceptanceRole | false;
 	disabled?: boolean;
 	systemPrompt?: string;
 	skills?: string[] | false;
@@ -116,10 +122,16 @@ export interface AgentConfig {
 	inheritProjectContext: boolean;
 	inheritSkills: boolean;
 	defaultContext?: AgentDefaultContext;
+	defaultAsync?: boolean;
+	defaultTimeoutMs?: number;
+	defaultTurnBudget?: TurnBudgetConfig;
+	defaultAcceptance?: AcceptanceInput;
+	acceptanceRole?: AcceptanceRole;
 	systemPrompt: string;
 	source: AgentSource;
 	filePath: string;
 	skills?: string[];
+	skillPath?: string[];
 	extensions?: string[];
 	subagentOnlyExtensions?: string[];
 	output?: string;
@@ -301,6 +313,8 @@ function resolveSettingsPackageRoot(source: string, baseDir: string): string | u
 }
 
 function getGlobalNpmRoot(): string | null {
+	const offline = process.env.PI_OFFLINE?.toLowerCase();
+	if (offline === "1" || offline === "true" || offline === "yes") return null;
 	if (cachedGlobalNpmRoot !== null) return cachedGlobalNpmRoot;
 	try {
 		cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
@@ -494,9 +508,11 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
 		inheritProjectContext: agent.inheritProjectContext,
 		inheritSkills: agent.inheritSkills,
 		defaultContext: agent.defaultContext,
+		acceptanceRole: agent.acceptanceRole,
 		disabled: agent.disabled,
 		systemPrompt: agent.systemPrompt,
 		skills: agent.skills ? [...agent.skills] : undefined,
+		skillPath: agent.skillPath ? [...agent.skillPath] : undefined,
 		tools: agent.tools ? [...agent.tools] : undefined,
 		mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
 		subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : undefined,
@@ -516,6 +532,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
 		...(override.inheritProjectContext !== undefined ? { inheritProjectContext: override.inheritProjectContext } : {}),
 		...(override.inheritSkills !== undefined ? { inheritSkills: override.inheritSkills } : {}),
 		...(override.defaultContext !== undefined ? { defaultContext: override.defaultContext } : {}),
+		...(override.acceptanceRole !== undefined ? { acceptanceRole: override.acceptanceRole } : {}),
 		...(override.disabled !== undefined ? { disabled: override.disabled } : {}),
 		...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
 		...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
@@ -651,6 +668,14 @@ function parseBuiltinOverrideEntry(
 		}
 	}
 
+	if ("acceptanceRole" in input) {
+		if (input.acceptanceRole === "read-only" || input.acceptanceRole === "writer" || input.acceptanceRole === false) {
+			override.acceptanceRole = input.acceptanceRole;
+		} else {
+			throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'acceptanceRole'; expected 'read-only', 'writer', or false.`);
+		}
+	}
+
 	if ("disabled" in input) {
 		if (typeof input.disabled === "boolean") {
 			override.disabled = input.disabled;
@@ -786,6 +811,7 @@ function applyBuiltinOverride(
 	if (override.inheritProjectContext !== undefined) next.inheritProjectContext = override.inheritProjectContext;
 	if (override.inheritSkills !== undefined) next.inheritSkills = override.inheritSkills;
 	if (override.defaultContext !== undefined) next.defaultContext = override.defaultContext === false ? undefined : override.defaultContext;
+	if (override.acceptanceRole !== undefined) next.acceptanceRole = override.acceptanceRole === false ? undefined : override.acceptanceRole;
 	if (override.disabled !== undefined) next.disabled = override.disabled;
 	if (override.systemPrompt !== undefined) next.systemPrompt = override.systemPrompt;
 	if (override.skills !== undefined) next.skills = override.skills === false ? undefined : [...override.skills];
@@ -867,7 +893,7 @@ function applyBuiltinOverrides(
 	});
 }
 
-function customAgentHasFrontmatterField(agent: AgentConfig, ...fields: string[]): boolean {
+export function agentHasFrontmatterField(agent: AgentConfig, ...fields: string[]): boolean {
 	const frontmatterFields = agentFrontmatterFields.get(agent);
 	return frontmatterFields ? fields.some((field) => frontmatterFields.has(field)) : false;
 }
@@ -890,7 +916,7 @@ function applyCustomAgentOverride(
 		frontmatterFields: string[],
 		value: AgentConfig[K],
 	): void => {
-		if (customAgentHasFrontmatterField(agent, ...frontmatterFields)) return;
+		if (agentHasFrontmatterField(agent, ...frontmatterFields)) return;
 		mutable()[field] = value;
 		anyFilled = true;
 	};
@@ -920,6 +946,9 @@ function applyCustomAgentOverride(
 	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 && agent.disabled === undefined) {
 		mutable().disabled = override.disabled;
 		anyFilled = true;
@@ -927,7 +956,7 @@ function applyCustomAgentOverride(
 	if (override.skills !== undefined) {
 		fill("skills", ["skill", "skills"], override.skills === false ? undefined : [...override.skills]);
 	}
-	if (override.tools !== undefined && !customAgentHasFrontmatterField(agent, "tools")) {
+	if (override.tools !== undefined && !agentHasFrontmatterField(agent, "tools")) {
 		const { tools, mcpDirectTools } = splitToolList(override.tools === false ? [] : override.tools);
 		const target = mutable();
 		target.tools = tools;
@@ -950,6 +979,8 @@ function applyCustomAgentOverride(
 
 	if (!anyFilled || !next) return agent;
 	next.override = { ...meta, base: cloneOverrideBase(agent) };
+	const frontmatterFields = agentFrontmatterFields.get(agent);
+	if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
 	return next;
 }
 
@@ -977,7 +1008,7 @@ function applyCustomAgentOverrides(
 
 export function buildBuiltinOverrideConfig(
 	base: BuiltinAgentOverrideBase,
-	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget">,
+	draft: Pick<AgentConfig, "model" | "fallbackModels" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "mcpDirectTools" | "subagentOnlyExtensions" | "completionGuard" | "toolBudget">,
 ): BuiltinAgentOverrideConfig | undefined {
 	const override: BuiltinAgentOverrideConfig = {};
 
@@ -988,6 +1019,7 @@ export function buildBuiltinOverrideConfig(
 	if (draft.inheritProjectContext !== base.inheritProjectContext) override.inheritProjectContext = draft.inheritProjectContext;
 	if (draft.inheritSkills !== base.inheritSkills) override.inheritSkills = draft.inheritSkills;
 	if (draft.defaultContext !== base.defaultContext) override.defaultContext = draft.defaultContext ?? false;
+	if (draft.acceptanceRole !== base.acceptanceRole) override.acceptanceRole = draft.acceptanceRole ?? false;
 	if (draft.disabled !== base.disabled) override.disabled = draft.disabled ?? false;
 	if (draft.systemPrompt !== base.systemPrompt) override.systemPrompt = draft.systemPrompt;
 	if (!arraysEqual(draft.skills, base.skills)) override.skills = draft.skills ? [...draft.skills] : false;
@@ -1160,6 +1192,19 @@ function isLegacyAgentSkillPath(rootDir: string, filePath: string): boolean {
 	return parts.some((part, index) => part === ".agents" && parts[index + 1] === "skills");
 }
 
+function parseAgentAcceptanceFrontmatter(raw: string | undefined, agentName: string): AcceptanceInput | undefined {
+	if (raw === undefined || !raw.trim()) return undefined;
+	let parsed: unknown;
+	try {
+		parsed = parseYaml(raw);
+	} catch (error) {
+		throw new Error(`Agent '${agentName}' has invalid acceptance frontmatter: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+	}
+	const errors = validateAcceptanceInput(parsed, `Agent '${agentName}' acceptance frontmatter`);
+	if (errors.length > 0) throw new Error(errors.join(" "));
+	return parsed as AcceptanceInput;
+}
+
 function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 	const agents: AgentConfig[] = [];
 
@@ -1187,37 +1232,13 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 		const packageName = parsedPackage.packageName;
 		const runtimeName = buildRuntimeName(localName, packageName);
 
-		const rawTools = frontmatter.tools
-			?.split(",")
-			.map((t) => t.trim())
-			.filter(Boolean);
-
-		const mcpDirectTools: string[] = [];
-		const tools: string[] = [];
-		if (rawTools) {
-			for (const tool of rawTools) {
-				if (tool.startsWith("mcp:")) {
-					mcpDirectTools.push(tool.slice(4));
-				} else {
-					tools.push(tool);
-				}
-			}
-		}
-
-		const defaultReads = frontmatter.defaultReads
-			?.split(",")
-			.map((f) => f.trim())
-			.filter(Boolean);
-
+		const rawTools = parseFrontmatterList(frontmatter.tools);
+		const { tools = [], mcpDirectTools = [] } = splitToolList(rawTools);
+		const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
 		const skillStr = frontmatter.skill || frontmatter.skills;
-		const skills = skillStr
-			?.split(",")
-			.map((s) => s.trim())
-			.filter(Boolean);
-		const fallbackModels = frontmatter.fallbackModels
-			?.split(",")
-			.map((model) => model.trim())
-			.filter(Boolean);
+		const skills = parseFrontmatterList(skillStr);
+		const skillPath = parseFrontmatterList(frontmatter.skillPath);
+		const fallbackModels = parseFrontmatterList(frontmatter.fallbackModels);
 		const systemPromptMode = frontmatter.systemPromptMode === "replace"
 			? "replace"
 			: frontmatter.systemPromptMode === "append"
@@ -1238,21 +1259,36 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			: frontmatter.defaultContext === "fresh"
 				? "fresh" as const
 				: undefined;
-
-		let extensions: string[] | undefined;
-		if (frontmatter.extensions !== undefined) {
-			extensions = frontmatter.extensions
-				.split(",")
-				.map((e) => e.trim())
-				.filter(Boolean);
+		let defaultAsync: boolean | undefined;
+		if (frontmatter.async !== undefined) {
+			if (frontmatter.async === "true") defaultAsync = true;
+			else if (frontmatter.async === "false") defaultAsync = false;
+			else throw new Error(`Agent '${localName}' has invalid async frontmatter; expected true or false.`);
+		}
+		let defaultTimeoutMs: number | undefined;
+		if (frontmatter.timeoutMs !== undefined) {
+			const parsed = Number(frontmatter.timeoutMs);
+			if (!Number.isInteger(parsed) || parsed <= 0) {
+				throw new Error(`Agent '${localName}' has invalid timeoutMs frontmatter; expected a positive integer.`);
+			}
+			defaultTimeoutMs = parsed;
 		}
-		let subagentOnlyExtensions: string[] | undefined;
-		if (frontmatter.subagentOnlyExtensions !== undefined) {
-			subagentOnlyExtensions = frontmatter.subagentOnlyExtensions
-				.split(",")
-				.map((e) => e.trim())
-				.filter(Boolean);
+		let defaultTurnBudget: TurnBudgetConfig | undefined;
+		if (frontmatter.turnBudget !== undefined && frontmatter.turnBudget.trim()) {
+			const parsed = JSON.parse(frontmatter.turnBudget) as unknown;
+			const resolved = resolveTurnBudgetConfig(parsed, `Agent '${localName}' turnBudget frontmatter`);
+			if (resolved.error) throw new Error(resolved.error);
+			defaultTurnBudget = resolved.turnBudget;
 		}
+		const defaultAcceptance = parseAgentAcceptanceFrontmatter(frontmatter.acceptance, localName);
+		let acceptanceRole: AcceptanceRole | undefined;
+		if (frontmatter.acceptanceRole !== undefined && frontmatter.acceptanceRole.trim()) {
+			if (frontmatter.acceptanceRole === "read-only" || frontmatter.acceptanceRole === "writer") acceptanceRole = frontmatter.acceptanceRole;
+			else throw new Error(`Agent '${localName}' has invalid acceptanceRole frontmatter; expected 'read-only' or 'writer'.`);
+		}
+
+		const extensions = parseFrontmatterList(frontmatter.extensions);
+		const subagentOnlyExtensions = parseFrontmatterList(frontmatter.subagentOnlyExtensions);
 
 		const extraFields: Record<string, string> = {};
 		for (const [key, value] of Object.entries(frontmatter)) {
@@ -1288,10 +1324,16 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 			inheritProjectContext,
 			inheritSkills,
 			defaultContext,
+			defaultAsync,
+			defaultTimeoutMs,
+			defaultTurnBudget,
+			defaultAcceptance,
+			acceptanceRole,
 			systemPrompt: body,
 			source,
 			filePath,
 			skills: skills && skills.length > 0 ? skills : undefined,
+			skillPath: skillPath && skillPath.length > 0 ? skillPath : undefined,
 			extensions,
 			subagentOnlyExtensions,
 			output: frontmatter.output,