@duckmind/dm-windows-x64 0.61.4 → 0.61.9

package/extensions/dm-subagents/src/agents/agents.js

@@ -1,27 +1,23 @@
 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 { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, parseExternalCliCapabilityNarrowing, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.js";
 import { getAgentDir, getProjectConfigDir } from "../shared/utils.js";
 import { KNOWN_FIELDS } from "./agent-serializer.js";
 import { parseChain, parseJsonChain } from "./chain-serializer.js";
 import { mergeAgentsForScope } from "./agent-selection.js";
-import { parseFrontmatter } from "./frontmatter.js";
+import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.js";
 import { buildRuntimeName, parsePackageName } from "./identity.js";
 import { parseModelScopeConfig } from "../runs/shared/model-scope.js";
+export { BUILTIN_AGENT_NAMES } from "./builtin-names.js";
 export { buildRuntimeName, frontmatterNameForConfig, parsePackageName } from "./identity.js";
 import { parseMemoryFrontmatter } from "./agent-memory.js";
-export const BUILTIN_AGENT_NAMES = [
-  "context-builder",
-  "delegate",
-  "oracle",
-  "planner",
-  "researcher",
-  "reviewer",
-  "scout",
-  "worker"
-];
+import { validateAcceptanceInput } from "../runs/shared/acceptance.js";
+import { validatePermissionRules } from "../runs/shared/permissions.js";
+import { parseThinkingLevel } from "../shared/thinking-ceiling.js";
 export function defaultSystemPromptMode(name) {
   return name === "delegate" ? "append" : "replace";
 }
@@ -31,8 +27,54 @@ export function defaultInheritProjectContext(name) {
 export function defaultInheritSkills() {
   return false;
 }
-const EMPTY_SUBAGENT_SETTINGS = { overrides: {} };
+const EMPTY_SUBAGENT_SETTINGS = { overrides: {}, providerOverrides: {} };
 const agentFrontmatterFields = new WeakMap;
+const AGENT_SOURCE_PRIORITY = {
+  builtin: 0,
+  package: 1,
+  user: 2,
+  project: 3,
+  runtime: 4
+};
+function agentDefinitionPriority(definition) {
+  return AGENT_SOURCE_PRIORITY[definition.source] * 1e6 + (definition.discoveryPriority ?? 0);
+}
+export function findBlockingAgentDiagnostic(name, agent, diagnostics) {
+  const normalizedName = name.trim();
+  const agents = Array.isArray(agent) ? agent : agent ? [agent] : [];
+  let match;
+  for (const diagnostic of diagnostics ?? []) {
+    if ((diagnostic.runtimeName === normalizedName || diagnostic.name === normalizedName && (!diagnostic.packageSpecified || diagnostic.runtimeName === undefined || agents.some((agent) => agent.name === diagnostic.runtimeName && agent.localName === diagnostic.name))) && (!match || agentDefinitionPriority(diagnostic) > agentDefinitionPriority(match))) {
+      match = diagnostic;
+    }
+  }
+  const highestPriority = Math.max(...agents.map(agentDefinitionPriority), -1 / 0);
+  return !agents.length || match && agentDefinitionPriority(match) > highestPriority ? match : undefined;
+}
+export function unknownAgentDiagnosticContext(discovered) {
+  return {
+    cwd: discovered.cwd,
+    scope: discovered.scope,
+    directories: discovered.directories,
+    agents: discovered.agents
+  };
+}
+export function formatUnknownAgentError(name, context, prefix = "Unknown agent") {
+  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(`
+`);
+}
 function getUserChainDir() {
   return path.join(getAgentDir(), "chains");
 }
@@ -44,16 +86,6 @@ function readJsonFileBestEffort(filePath) {
     return null;
   }
 }
-function readOptionalJsonFile(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
-  } catch (error) {
-    const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
-    if (code === "ENOENT")
-      return null;
-    throw error;
-  }
-}
 function isSafePackagePath(value) {
   return value.length > 0 && !path.isAbsolute(value) && value.split(/[\\/]/).every((part) => part.length > 0 && part !== "." && part !== "..");
 }
@@ -124,13 +156,29 @@ function resolveSettingsPackageRoot(source, baseDir) {
   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;
 }
 function getGlobalNpmRoot() {
+  const offline = process.env.PI_OFFLINE?.toLowerCase();
+  if (offline === "1" || offline === "true" || offline === "yes")
+    return null;
   if (cachedGlobalNpmRoot !== null)
     return cachedGlobalNpmRoot;
+  const windowsGlobalRoot = process.platform === "win32" && process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules") : undefined;
+  if (windowsGlobalRoot) {
+    try {
+      if (fs.statSync(windowsGlobalRoot).isDirectory()) {
+        cachedGlobalNpmRoot = fs.realpathSync(windowsGlobalRoot);
+        return cachedGlobalNpmRoot;
+      }
+    } catch {}
+  }
   try {
-    cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim());
+    cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
     return cachedGlobalNpmRoot;
   } catch {
     cachedGlobalNpmRoot = "";
@@ -142,19 +190,30 @@ function stringArray(value) {
     return [];
   return value.filter((entry) => typeof entry === "string" && entry.trim().length > 0);
 }
-function extractSubagentPathsFromPackageRoot(packageRoot) {
+function packageMetadata(pkg, packageRoot) {
+  const name = typeof pkg.name === "string" && pkg.name.trim() ? pkg.name.trim() : undefined;
+  const version = typeof pkg.version === "string" && pkg.version.trim() ? pkg.version.trim() : undefined;
+  return {
+    packageRoot,
+    ...name ? { packageName: name } : {},
+    ...version ? { packageVersion: version } : {}
+  };
+}
+function extractSubagentPathsFromPackageRoot(packageRoot, scope) {
   const packageJsonPath = path.join(packageRoot, "package.json");
   const pkg = readJsonFileBestEffort(packageJsonPath);
   if (!pkg || typeof pkg !== "object" || Array.isArray(pkg))
-    return { agents: [], chains: [] };
+    return { agents: [], chains: [], watchPaths: [packageJsonPath], settingsErrors: {} };
+  const pkgRecord = pkg;
+  const metadata = packageMetadata(pkgRecord, packageRoot);
   const roots = [];
-  const piSubagents = pkg["dm-subagents"];
+  const piSubagents = pkgRecord["dm-subagents"];
   if (piSubagents && typeof piSubagents === "object" && !Array.isArray(piSubagents)) {
     roots.push(piSubagents);
   }
-  const pi = pkg.pi;
-  if (pi && typeof pi === "object" && !Array.isArray(pi)) {
-    const subagents = pi.subagents;
+  const dm = pkgRecord.dm;
+  if (dm && typeof dm === "object" && !Array.isArray(dm)) {
+    const subagents = dm.subagents;
     if (subagents && typeof subagents === "object" && !Array.isArray(subagents)) {
       roots.push(subagents);
     }
@@ -163,14 +222,15 @@ function extractSubagentPathsFromPackageRoot(packageRoot) {
   const chains = [];
   for (const root of roots) {
     for (const entry of stringArray(root.agents))
-      agents.push(path.resolve(packageRoot, entry));
+      agents.push({ dir: path.resolve(packageRoot, entry), scope, ...metadata });
     for (const entry of stringArray(root.chains))
-      chains.push(path.resolve(packageRoot, entry));
+      chains.push({ dir: path.resolve(packageRoot, entry), scope, packageRoot });
   }
-  return { agents, chains };
+  return { agents, chains, watchPaths: [packageJsonPath], settingsErrors: {} };
 }
-function collectPackageRootsFromNodeModules(nodeModulesDir) {
+function collectPackageRootsFromNodeModules(nodeModulesDir, watchPaths) {
   const roots = [];
+  watchPaths?.push(nodeModulesDir);
   if (!fs.existsSync(nodeModulesDir))
     return roots;
   let entries;
@@ -186,6 +246,7 @@ function collectPackageRootsFromNodeModules(nodeModulesDir) {
       continue;
     if (entry.name.startsWith("@")) {
       const scopeDir = path.join(nodeModulesDir, entry.name);
+      watchPaths?.push(scopeDir);
       let scopeEntries;
       try {
         scopeEntries = fs.readdirSync(scopeDir, { withFileTypes: true });
@@ -206,9 +267,7 @@ function collectPackageRootsFromNodeModules(nodeModulesDir) {
   return roots;
 }
 function collectSettingsPackageRoots(settingsFile, baseDir) {
-  const settings = readOptionalJsonFile(settingsFile);
-  if (!settings || typeof settings !== "object" || Array.isArray(settings))
-    return [];
+  const settings = readSettingsFileStrict(settingsFile);
   const packages = settings.packages;
   if (!Array.isArray(packages))
     return [];
@@ -225,47 +284,112 @@ function collectSettingsPackageRoots(settingsFile, baseDir) {
 }
 function collectPackageSubagentPaths(cwd, options = { includeUser: true, includeProject: true }) {
   const agentDir = getAgentDir();
-  const projectRoot = findNearestProjectRoot(cwd) ?? cwd;
+  const projectRoot = findConfiguredProjectRoot(cwd) ?? cwd;
   const packageRoots = [
-    projectRoot
+    { root: projectRoot, scope: "root" }
   ];
+  const watchPaths = [path.join(projectRoot, "package.json")];
+  const settingsErrors = {};
+  const collectScopedSettingsRoots = (scope, settingsFile, baseDir) => {
+    try {
+      return collectSettingsPackageRoots(settingsFile, baseDir);
+    } catch (error) {
+      settingsErrors[scope] = error instanceof Error ? error : new Error(`Failed to read settings file '${settingsFile}': ${String(error)}`, { cause: error });
+      return [];
+    }
+  };
   if (options.includeProject) {
     const projectConfigDir = getProjectConfigDir(projectRoot);
-    packageRoots.push(...collectPackageRootsFromNodeModules(path.join(projectConfigDir, "npm", "node_modules")), ...collectSettingsPackageRoots(path.join(projectConfigDir, "settings.json"), projectConfigDir));
+    const nodeModulesDir = path.join(projectConfigDir, "npm", "node_modules");
+    packageRoots.push(...collectPackageRootsFromNodeModules(nodeModulesDir, watchPaths).map((root) => ({ root, scope: "project" })));
+    packageRoots.push(...collectScopedSettingsRoots("project", path.join(projectConfigDir, "settings.json"), projectConfigDir).map((root) => ({ root, scope: "project" })));
   }
   if (options.includeUser) {
-    packageRoots.push(...collectPackageRootsFromNodeModules(path.join(agentDir, "npm", "node_modules")), ...collectSettingsPackageRoots(path.join(agentDir, "settings.json"), agentDir));
+    const nodeModulesDir = path.join(agentDir, "npm", "node_modules");
+    packageRoots.push(...collectPackageRootsFromNodeModules(nodeModulesDir, watchPaths).map((root) => ({ root, scope: "user" })));
+    packageRoots.push(...collectScopedSettingsRoots("user", path.join(agentDir, "settings.json"), agentDir).map((root) => ({ root, scope: "user" })));
   }
   if (options.includeUser) {
     const globalRoot = getGlobalNpmRoot();
-    if (globalRoot)
-      packageRoots.push(...collectPackageRootsFromNodeModules(globalRoot));
+    if (globalRoot) {
+      packageRoots.push(...collectPackageRootsFromNodeModules(globalRoot, watchPaths).map((root) => ({ root, scope: "user" })));
+    }
   }
-  const seenRoots = new Set;
-  const seenAgents = new Set;
-  const seenChains = new Set;
+  const seenRoots = new Map;
+  const seenAgents = new Map;
+  const seenChains = new Map;
   const agents = [];
   const chains = [];
-  for (const packageRoot of packageRoots) {
+  for (const { root: packageRoot, scope } of packageRoots) {
     const resolvedRoot = path.resolve(packageRoot);
-    if (seenRoots.has(resolvedRoot))
+    const scopes = seenRoots.get(resolvedRoot);
+    if (scopes !== undefined) {
+      scopes.add(scope);
       continue;
-    seenRoots.add(resolvedRoot);
-    const paths = extractSubagentPathsFromPackageRoot(resolvedRoot);
-    for (const agentDir of paths.agents) {
-      if (seenAgents.has(agentDir))
+    }
+    const packageScopes = new Set([scope]);
+    seenRoots.set(resolvedRoot, packageScopes);
+    const paths = extractSubagentPathsFromPackageRoot(resolvedRoot, packageScopes);
+    watchPaths.push(...paths.watchPaths);
+    for (const agentPath of paths.agents) {
+      const agentKey = `${agentPath.dir}\x00${agentPath.packageRoot}`;
+      const existing = seenAgents.get(agentKey);
+      if (existing) {
+        for (const packageScope of agentPath.scope)
+          existing.scope.add(packageScope);
         continue;
-      seenAgents.add(agentDir);
-      agents.push(agentDir);
+      }
+      seenAgents.set(agentKey, agentPath);
+      agents.push(agentPath);
     }
     for (const chainDir of paths.chains) {
-      if (seenChains.has(chainDir))
+      const chainKey = `${chainDir.dir}\x00${chainDir.packageRoot}`;
+      const existing = seenChains.get(chainKey);
+      if (existing) {
+        for (const packageScope of chainDir.scope)
+          existing.scope.add(packageScope);
         continue;
-      seenChains.add(chainDir);
+      }
+      seenChains.set(chainKey, chainDir);
       chains.push(chainDir);
     }
   }
-  return { agents, chains };
+  return { agents, chains, watchPaths, settingsErrors };
+}
+function normalizeAgentAliases(rawAliases, agentName) {
+  const aliases = [...new Set((rawAliases ?? []).map((alias) => alias.trim()).filter(Boolean))].filter((alias) => alias !== agentName);
+  return aliases.length > 0 ? aliases : undefined;
+}
+function effectiveAgentMatch(matches) {
+  const distinctNames = [...new Set(matches.map((agent) => agent.name))];
+  if (distinctNames.length === 1) {
+    const sourceRank = new Map([["builtin", 0], ["package", 1], ["user", 2], ["project", 3], ["runtime", 4]]);
+    const agent = [...matches].sort((a, b) => (sourceRank.get(b.source) ?? 0) - (sourceRank.get(a.source) ?? 0))[0];
+    return agent ? { agent } : {};
+  }
+  return {};
+}
+export function resolveAgentName(name, agents) {
+  const raw = name.trim();
+  const exact = agents.filter((agent) => agent.name === raw || agent.localName === raw);
+  if (exact.length === 1)
+    return exact[0] ? { agent: exact[0] } : {};
+  if (exact.length > 1) {
+    const effective = effectiveAgentMatch(exact);
+    if (effective.agent)
+      return effective;
+    return { error: `Ambiguous agent name '${name}': ${exact.map((agent) => agent.name).join(", ")}` };
+  }
+  const aliases = agents.filter((agent) => agent.aliases?.includes(raw));
+  if (aliases.length === 1)
+    return aliases[0] ? { agent: aliases[0] } : {};
+  if (aliases.length > 1) {
+    const effective = effectiveAgentMatch(aliases);
+    if (effective.agent)
+      return effective;
+    return { error: `Ambiguous agent alias '${name}': ${aliases.map((agent) => agent.name).join(", ")}` };
+  }
+  return {};
 }
 function splitToolList(rawTools) {
   const mcpDirectTools = [];
@@ -278,7 +402,7 @@ function splitToolList(rawTools) {
     }
   }
   return {
-    ...tools.length > 0 ? { tools } : {},
+    ...rawTools !== undefined ? { tools } : {},
     ...mcpDirectTools.length > 0 ? { mcpDirectTools } : {}
   };
 }
@@ -304,58 +428,137 @@ function arraysEqual(a, b) {
 }
 function cloneOverrideBase(agent) {
   return {
-    model: agent.model,
-    fallbackModels: agent.fallbackModels ? [...agent.fallbackModels] : undefined,
-    thinking: agent.thinking,
+    description: agent.description,
+    ...agent.output !== undefined ? { output: agent.output } : {},
+    ...agent.outputMode !== undefined ? { outputMode: agent.outputMode } : {},
+    ...agent.defaultReads !== undefined ? { defaultReads: [...agent.defaultReads] } : {},
+    ...agent.model !== undefined ? { model: agent.model } : {},
+    ...agent.modelProvider !== undefined ? { modelProvider: agent.modelProvider } : {},
+    ...agent.fallbackModels ? { fallbackModels: [...agent.fallbackModels] } : {},
+    ...agent.fast !== undefined ? { fast: agent.fast } : {},
+    ...agent.thinking !== undefined ? { thinking: agent.thinking } : {},
     systemPromptMode: agent.systemPromptMode,
     inheritProjectContext: agent.inheritProjectContext,
+    inheritGlobalContext: agent.inheritGlobalContext,
     inheritSkills: agent.inheritSkills,
-    defaultContext: agent.defaultContext,
-    disabled: agent.disabled,
+    ...agent.defaultContext !== undefined ? { defaultContext: agent.defaultContext } : {},
+    ...agent.acceptanceRole !== undefined ? { acceptanceRole: agent.acceptanceRole } : {},
+    ...agent.disabled !== undefined ? { disabled: agent.disabled } : {},
     systemPrompt: agent.systemPrompt,
-    skills: agent.skills ? [...agent.skills] : undefined,
-    tools: agent.tools ? [...agent.tools] : undefined,
-    mcpDirectTools: agent.mcpDirectTools ? [...agent.mcpDirectTools] : undefined,
-    subagentOnlyExtensions: agent.subagentOnlyExtensions ? [...agent.subagentOnlyExtensions] : undefined,
-    completionGuard: agent.completionGuard,
-    toolBudget: agent.toolBudget
+    ...agent.skills ? { skills: [...agent.skills] } : {},
+    ...agent.skillPath ? { skillPath: [...agent.skillPath] } : {},
+    ...agent.tools ? { tools: [...agent.tools] } : {},
+    ...agent.allowNestedSubagents !== undefined ? { allowNestedSubagents: agent.allowNestedSubagents } : {},
+    ...agent.mcpDirectTools ? { mcpDirectTools: [...agent.mcpDirectTools] } : {},
+    ...!agent.extensionsFromDefault && agent.extensions ? { extensions: [...agent.extensions] } : {},
+    ...agent.subagentOnlyExtensions ? { subagentOnlyExtensions: [...agent.subagentOnlyExtensions] } : {},
+    ...agent.mutationTools ? { mutationTools: [...agent.mutationTools] } : {},
+    ...agent.completionGuard !== undefined ? { completionGuard: agent.completionGuard } : {},
+    ...agent.toolBudget !== undefined ? { toolBudget: agent.toolBudget } : {}
   };
 }
 function cloneOverrideValue(override) {
   return {
+    ...override.description !== undefined ? { description: override.description } : {},
+    ...override.output !== undefined ? { output: override.output } : {},
+    ...override.outputMode !== undefined ? { outputMode: override.outputMode } : {},
+    ...override.defaultReads !== undefined ? { defaultReads: override.defaultReads === false ? false : [...override.defaultReads] } : {},
     ...override.model !== undefined ? { model: override.model } : {},
+    ...override.defaultProvider !== undefined ? { defaultProvider: override.defaultProvider } : {},
     ...override.fallbackModels !== undefined ? { fallbackModels: override.fallbackModels === false ? false : [...override.fallbackModels] } : {},
+    ...override.fast !== undefined ? { fast: override.fast } : {},
     ...override.thinking !== undefined ? { thinking: override.thinking } : {},
     ...override.systemPromptMode !== undefined ? { systemPromptMode: override.systemPromptMode } : {},
     ...override.inheritProjectContext !== undefined ? { inheritProjectContext: override.inheritProjectContext } : {},
+    ...override.inheritGlobalContext !== undefined ? { inheritGlobalContext: override.inheritGlobalContext } : {},
     ...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] } : {},
-    ...override.tools !== undefined ? { tools: override.tools === false ? false : [...override.tools] } : {},
+    ...override.tools !== undefined ? { tools: Array.isArray(override.tools) ? [...override.tools] : override.tools } : {},
+    ...override.allowNestedSubagents !== undefined ? { allowNestedSubagents: override.allowNestedSubagents } : {},
+    ...override.extensions !== undefined ? { extensions: override.extensions === false ? false : [...override.extensions] } : {},
     ...override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {},
+    ...override.mutationTools !== undefined ? { mutationTools: override.mutationTools === false ? false : [...override.mutationTools] } : {},
     ...override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {},
     ...override.toolBudget !== undefined ? { toolBudget: override.toolBudget === false ? false : { ...override.toolBudget, ...Array.isArray(override.toolBudget.block) ? { block: [...override.toolBudget.block] } : {} } } : {}
   };
 }
-export function findNearestProjectRoot(cwd) {
+function isProjectRootCandidate(dir) {
+  return isDirectory(getProjectConfigDir(dir)) || isDirectory(path.join(dir, ".agents"));
+}
+function findProjectRootCandidates(cwd) {
+  const roots = [];
+  let currentDir = cwd;
+  while (true) {
+    if (isProjectRootCandidate(currentDir))
+      roots.push(currentDir);
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir)
+      return roots;
+    currentDir = parentDir;
+  }
+}
+function findNearestGitRoot(cwd) {
   let currentDir = cwd;
   while (true) {
-    if (isDirectory(getProjectConfigDir(currentDir)) || isDirectory(path.join(currentDir, ".agents"))) {
+    if (fs.existsSync(path.join(currentDir, ".git")))
       return currentDir;
-    }
     const parentDir = path.dirname(currentDir);
     if (parentDir === currentDir)
       return null;
     currentDir = parentDir;
   }
 }
+function readProjectRootResolution(projectRoot) {
+  const settingsPath = path.join(getProjectConfigDir(projectRoot), "settings.json");
+  if (!fs.existsSync(settingsPath))
+    return;
+  const settings = readSettingsFileStrict(settingsPath);
+  const subagents = settings.subagents;
+  if (!subagents || typeof subagents !== "object" || Array.isArray(subagents))
+    return;
+  const value = subagents.projectRootResolution;
+  if (value === undefined)
+    return;
+  if (value === "nearest" || value === "git-root")
+    return value;
+  throw new Error(`Subagent settings in '${settingsPath}' have invalid 'projectRootResolution'; expected 'nearest' or 'git-root'.`);
+}
+export function findNearestProjectRoot(cwd) {
+  return findProjectRootCandidates(cwd)[0] ?? null;
+}
+export function findConfiguredProjectRoot(cwd) {
+  const candidates = findProjectRootCandidates(cwd);
+  const nearestRoot = candidates[0];
+  if (!nearestRoot)
+    return null;
+  let policyRoot;
+  let policyRootIndex = -1;
+  for (const [index, candidate] of candidates.entries()) {
+    const mode = readProjectRootResolution(candidate);
+    if (mode === "nearest")
+      return nearestRoot;
+    if (mode === "git-root") {
+      policyRoot = candidate;
+      policyRootIndex = index;
+      break;
+    }
+  }
+  if (!policyRoot)
+    return nearestRoot;
+  const gitRoot = findNearestGitRoot(cwd);
+  const gitProjectRoot = gitRoot ? candidates.slice(policyRootIndex).find((candidate) => path.resolve(candidate) === path.resolve(gitRoot)) : undefined;
+  const configuredGitRoot = fs.existsSync(path.join(policyRoot, ".git")) ? policyRoot : undefined;
+  return gitProjectRoot ?? configuredGitRoot ?? nearestRoot;
+}
 function getUserAgentSettingsPath() {
   return path.join(getAgentDir(), "settings.json");
 }
 function getProjectAgentSettingsPath(cwd) {
-  const projectRoot = findNearestProjectRoot(cwd);
+  const projectRoot = findConfiguredProjectRoot(cwd);
   return projectRoot ? path.join(getProjectConfigDir(projectRoot), "settings.json") : null;
 }
 function readSettingsFileStrict(filePath) {
@@ -404,18 +607,52 @@ function parseOverrideStringArrayOrFalse(value, meta) {
   }
   return items;
 }
+function parseToolsOverride(value, meta) {
+  if (typeof value === "string" && value.trim() === "inherit")
+    return "inherit";
+  if (value === undefined || value === false || Array.isArray(value)) {
+    return parseOverrideStringArrayOrFalse(value, { ...meta, field: "tools" });
+  }
+  throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid 'tools'; expected an array of strings, "inherit", or false.`);
+}
 function parseBuiltinOverrideEntry(name, value, filePath) {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     throw new Error(`Builtin override '${name}' in '${filePath}' must be an object.`);
   }
   const input = value;
   const override = {};
+  if ("description" in input) {
+    if (typeof input.description === "string" && input.description.trim()) {
+      override.description = input.description.trim();
+    } else {
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'description'; expected a non-empty string.`);
+    }
+  }
+  if ("output" in input) {
+    if (typeof input.output === "string" && input.output.trim() || input.output === false)
+      override.output = input.output;
+    else
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'output'; expected a non-empty string or false.`);
+  }
+  if ("outputMode" in input) {
+    if (input.outputMode === "inline" || input.outputMode === "file-only") {
+      override.outputMode = input.outputMode;
+    } else {
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'outputMode'; expected 'inline' or 'file-only'.`);
+    }
+  }
   if ("model" in input) {
     if (typeof input.model === "string" || input.model === false)
       override.model = input.model;
     else
       throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'model'; expected a string or false.`);
   }
+  if ("fast" in input) {
+    if (typeof input.fast === "boolean")
+      override.fast = input.fast;
+    else
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'fast'; expected a boolean.`);
+  }
   if ("thinking" in input) {
     if (typeof input.thinking === "string" || input.thinking === false)
       override.thinking = input.thinking;
@@ -436,6 +673,13 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
       throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritProjectContext'; expected a boolean.`);
     }
   }
+  if ("inheritGlobalContext" in input) {
+    if (typeof input.inheritGlobalContext === "boolean") {
+      override.inheritGlobalContext = input.inheritGlobalContext;
+    } else {
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'inheritGlobalContext'; expected a boolean.`);
+    }
+  }
   if ("inheritSkills" in input) {
     if (typeof input.inheritSkills === "boolean") {
       override.inheritSkills = input.inheritSkills;
@@ -450,6 +694,13 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
       throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'defaultContext'; expected 'fresh', 'fork', or false.`);
     }
   }
+  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;
@@ -479,18 +730,41 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
     else
       throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
   }
+  const defaultReads = parseOverrideStringArrayOrFalse(input.defaultReads, { filePath, name, field: "defaultReads" });
+  if (defaultReads !== undefined)
+    override.defaultReads = defaultReads;
   const fallbackModels = parseOverrideStringArrayOrFalse(input.fallbackModels, { filePath, name, field: "fallbackModels" });
   if (fallbackModels !== undefined)
     override.fallbackModels = fallbackModels;
+  if ("defaultProvider" in input) {
+    if (input.defaultProvider === false)
+      override.defaultProvider = false;
+    else if (typeof input.defaultProvider === "string" && input.defaultProvider.trim())
+      override.defaultProvider = input.defaultProvider.trim();
+    else
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'defaultProvider'; expected a non-empty string or false.`);
+  }
   const skills = parseOverrideStringArrayOrFalse(input.skills, { filePath, name, field: "skills" });
   if (skills !== undefined)
     override.skills = skills;
-  const tools = parseOverrideStringArrayOrFalse(input.tools, { filePath, name, field: "tools" });
+  const tools = parseToolsOverride(input.tools, { filePath, name });
   if (tools !== undefined)
     override.tools = tools;
+  if ("allowNestedSubagents" in input) {
+    if (typeof input.allowNestedSubagents === "boolean")
+      override.allowNestedSubagents = input.allowNestedSubagents;
+    else
+      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'allowNestedSubagents'; expected a boolean.`);
+  }
+  const extensions = parseOverrideStringArrayOrFalse(input.extensions, { filePath, name, field: "extensions" });
+  if (extensions !== undefined)
+    override.extensions = extensions;
   const subagentOnlyExtensions = parseOverrideStringArrayOrFalse(input.subagentOnlyExtensions, { filePath, name, field: "subagentOnlyExtensions" });
   if (subagentOnlyExtensions !== undefined)
     override.subagentOnlyExtensions = subagentOnlyExtensions;
+  const mutationTools = parseOverrideStringArrayOrFalse(input.mutationTools, { filePath, name, field: "mutationTools" });
+  if (mutationTools !== undefined)
+    override.mutationTools = mutationTools;
   return Object.keys(override).length > 0 ? override : undefined;
 }
 function readSubagentSettings(filePath) {
@@ -525,86 +799,300 @@ function readSubagentSettings(filePath) {
       throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultModel'; expected a non-empty string.`);
     }
   }
+  let defaultProvider;
+  if ("defaultProvider" in subagentsObject) {
+    if (typeof subagentsObject.defaultProvider === "string" && subagentsObject.defaultProvider.trim()) {
+      defaultProvider = subagentsObject.defaultProvider.trim();
+    } else {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultProvider'; expected a non-empty string.`);
+    }
+  }
+  let defaultThinking;
+  if ("defaultThinking" in subagentsObject) {
+    if (typeof subagentsObject.defaultThinking === "string" && subagentsObject.defaultThinking.trim()) {
+      defaultThinking = subagentsObject.defaultThinking.trim();
+    } else {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultThinking'; expected a non-empty string.`);
+    }
+  }
+  let maxThinking;
+  if ("maxThinking" in subagentsObject) {
+    try {
+      maxThinking = parseThinkingLevel(subagentsObject.maxThinking, `'${filePath}' subagents.maxThinking`);
+    } catch (error) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'maxThinking'; expected one of off, minimal, low, medium, high, xhigh, or max.`, { cause: error instanceof Error ? error : undefined });
+    }
+  }
+  let defaultExtensions;
+  if ("defaultExtensions" in subagentsObject) {
+    if (!Array.isArray(subagentsObject.defaultExtensions) || subagentsObject.defaultExtensions.some((item) => typeof item !== "string" || !item.trim())) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultExtensions'; expected an array of non-empty strings.`);
+    }
+    defaultExtensions = subagentsObject.defaultExtensions.map((item) => item.trim());
+  }
   const modelScope = parseModelScopeConfig(subagentsObject.modelScope, { filePath });
   const parsed = {};
+  const providerOverrides = {};
   const agentOverrides = subagentsObject.agentOverrides;
-  if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides)) {
-    return { overrides: parsed, defaultModel, disableBuiltins, disableThinking, modelScope };
+  const agentOverridesByProvider = subagentsObject.agentOverridesByProvider;
+  const parsedSettings = {
+    overrides: parsed,
+    providerOverrides,
+    ...defaultModel !== undefined ? { defaultModel } : {},
+    ...defaultProvider !== undefined ? { defaultProvider } : {},
+    ...defaultThinking !== undefined ? { defaultThinking } : {},
+    ...maxThinking !== undefined ? { maxThinking } : {},
+    ...defaultExtensions !== undefined ? { defaultExtensions } : {},
+    ...disableBuiltins !== undefined ? { disableBuiltins } : {},
+    ...disableThinking !== undefined ? { disableThinking } : {},
+    ...modelScope !== undefined ? { modelScope } : {}
+  };
+  if (agentOverrides && typeof agentOverrides === "object" && !Array.isArray(agentOverrides)) {
+    for (const [name, value] of Object.entries(agentOverrides)) {
+      const override = parseBuiltinOverrideEntry(name, value, filePath);
+      if (override)
+        parsed[name] = override;
+    }
   }
-  for (const [name, value] of Object.entries(agentOverrides)) {
-    const override = parseBuiltinOverrideEntry(name, value, filePath);
-    if (override)
-      parsed[name] = override;
+  if (agentOverridesByProvider !== undefined) {
+    if (!agentOverridesByProvider || typeof agentOverridesByProvider !== "object" || Array.isArray(agentOverridesByProvider)) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'agentOverridesByProvider'; expected an object keyed by provider.`);
+    }
+    for (const [provider, value] of Object.entries(agentOverridesByProvider)) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`Subagent settings in '${filePath}' have invalid 'agentOverridesByProvider.${provider}'; expected an object keyed by agent.`);
+      }
+      const entries = {};
+      for (const [agentName, agentValue] of Object.entries(value)) {
+        const override = parseBuiltinOverrideEntry(`agentOverridesByProvider.${provider}.${agentName}`, agentValue, filePath);
+        if (override)
+          entries[agentName] = override;
+      }
+      providerOverrides[provider] = entries;
+    }
   }
-  return { overrides: parsed, defaultModel, disableBuiltins, disableThinking, modelScope };
+  return parsedSettings;
+}
+function selectProviderOverrides(settings, provider) {
+  if (!provider)
+    return settings;
+  const selected = settings.providerOverrides[provider];
+  if (!selected)
+    return settings;
+  const overrides = { ...settings.overrides };
+  for (const [name, override] of Object.entries(selected)) {
+    overrides[name] = { ...overrides[name], ...override };
+  }
+  return { ...settings, overrides };
 }
-function resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath) {
+function resolveSubagentDefaultProvider(userSettings, projectSettings, projectSettingsPath) {
+  if (projectSettingsPath && projectSettings.defaultProvider !== undefined)
+    return projectSettings.defaultProvider;
+  return userSettings.defaultProvider;
+}
+function resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath, defaultProvider) {
   if (projectSettingsPath && projectSettings.defaultModel !== undefined) {
-    return { type: "subagents.defaultModel", scope: "project", path: projectSettingsPath, model: projectSettings.defaultModel };
+    return { type: "subagents.defaultModel", scope: "project", path: projectSettingsPath, model: projectSettings.defaultModel, ...defaultProvider ? { defaultProvider } : {} };
   }
-  return userSettings.defaultModel !== undefined ? { type: "subagents.defaultModel", scope: "user", path: userSettingsPath, model: userSettings.defaultModel } : undefined;
+  return userSettings.defaultModel !== undefined ? { type: "subagents.defaultModel", scope: "user", path: userSettingsPath, model: userSettings.defaultModel, ...defaultProvider ? { defaultProvider } : {} } : undefined;
+}
+function applySubagentDefaultModel(agents, defaultModel, defaultProvider) {
+  if (!defaultModel && !defaultProvider)
+    return agents;
+  return agents.map((agent) => {
+    if (agent.model !== undefined && (agent.modelProvider !== undefined || !defaultProvider))
+      return agent;
+    const next = {
+      ...agent,
+      ...agent.model === undefined && defaultModel ? { model: defaultModel.model, modelSource: defaultModel } : {},
+      ...defaultProvider ? { modelProvider: defaultProvider } : {}
+    };
+    const frontmatterFields = agentFrontmatterFields.get(agent);
+    if (frontmatterFields)
+      agentFrontmatterFields.set(next, frontmatterFields);
+    return next;
+  });
+}
+function resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath) {
+  if (projectSettingsPath && projectSettings.defaultThinking !== undefined)
+    return projectSettings.defaultThinking;
+  return userSettings.defaultThinking;
 }
-function applySubagentDefaultModel(agents, defaultModel) {
-  if (!defaultModel)
+function applySubagentDefaultThinking(agents, defaultThinking) {
+  if (defaultThinking === undefined)
     return agents;
   return agents.map((agent) => {
-    if (agent.model !== undefined)
+    if (agent.thinking !== undefined)
       return agent;
-    const next = { ...agent, model: defaultModel.model, modelSource: defaultModel };
+    const next = { ...agent, thinking: defaultThinking };
     const frontmatterFields = agentFrontmatterFields.get(agent);
     if (frontmatterFields)
       agentFrontmatterFields.set(next, frontmatterFields);
     return next;
   });
 }
+function resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath) {
+  if (projectSettingsPath && projectSettings.maxThinking !== undefined)
+    return projectSettings.maxThinking;
+  return userSettings.maxThinking;
+}
+function applySubagentMaxThinking(agents, maxThinking) {
+  if (maxThinking === undefined)
+    return agents;
+  return agents.map((agent) => agent.maxThinking === maxThinking ? agent : { ...agent, maxThinking });
+}
+function resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath) {
+  if (projectSettingsPath && projectSettings.defaultExtensions !== undefined)
+    return projectSettings.defaultExtensions;
+  return userSettings.defaultExtensions;
+}
+function applySubagentDefaultExtensions(agents, defaultExtensions) {
+  if (defaultExtensions === undefined)
+    return agents;
+  return agents.map((agent) => {
+    if (agent.extensions !== undefined)
+      return agent;
+    const next = { ...agent, extensions: [...defaultExtensions], extensionsFromDefault: true };
+    const frontmatterFields = agentFrontmatterFields.get(agent);
+    if (frontmatterFields)
+      agentFrontmatterFields.set(next, frontmatterFields);
+    return next;
+  });
+}
+function applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions) {
+  return applySubagentDefaultExtensions(applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking), defaultExtensions);
+}
+function applyToolsOverride(target, toolsOverride) {
+  if (toolsOverride === "inherit") {
+    delete target.tools;
+    delete target.mcpDirectTools;
+    return;
+  }
+  const { tools, mcpDirectTools } = splitToolList(toolsOverride === false ? [] : toolsOverride);
+  if (tools === undefined)
+    delete target.tools;
+  else
+    target.tools = tools;
+  if (mcpDirectTools === undefined)
+    delete target.mcpDirectTools;
+  else
+    target.mcpDirectTools = mcpDirectTools;
+}
 function applyBuiltinOverride(agent, override, meta) {
   const next = {
     ...agent,
     override: { ...meta, base: cloneOverrideBase(agent) }
   };
-  if (override.model !== undefined)
-    next.model = override.model === false ? undefined : override.model;
+  if (override.description !== undefined)
+    next.description = override.description;
+  if (override.output !== undefined) {
+    if (override.output === false)
+      delete next.output;
+    else
+      next.output = override.output;
+  }
+  if (override.outputMode !== undefined)
+    next.outputMode = override.outputMode;
+  if (override.defaultReads !== undefined) {
+    if (override.defaultReads === false)
+      delete next.defaultReads;
+    else
+      next.defaultReads = [...override.defaultReads];
+  }
+  if (override.model !== undefined) {
+    if (override.model === false)
+      delete next.model;
+    else
+      next.model = override.model;
+    delete next.modelSource;
+  }
+  if (override.defaultProvider !== undefined) {
+    if (override.defaultProvider === false)
+      delete next.modelProvider;
+    else
+      next.modelProvider = override.defaultProvider;
+  }
   if (override.fallbackModels !== undefined) {
-    next.fallbackModels = override.fallbackModels === false ? undefined : [...override.fallbackModels];
+    if (override.fallbackModels === false)
+      delete next.fallbackModels;
+    else
+      next.fallbackModels = [...override.fallbackModels];
+  }
+  if (override.fast !== undefined)
+    next.fast = override.fast;
+  if (override.thinking !== undefined) {
+    if (override.thinking === false)
+      delete next.thinking;
+    else
+      next.thinking = override.thinking;
   }
-  if (override.thinking !== undefined)
-    next.thinking = override.thinking === false ? undefined : override.thinking;
   if (override.systemPromptMode !== undefined)
     next.systemPromptMode = override.systemPromptMode;
   if (override.inheritProjectContext !== undefined)
     next.inheritProjectContext = override.inheritProjectContext;
+  if (override.inheritGlobalContext !== undefined)
+    next.inheritGlobalContext = override.inheritGlobalContext;
   if (override.inheritSkills !== undefined)
     next.inheritSkills = override.inheritSkills;
-  if (override.defaultContext !== undefined)
-    next.defaultContext = override.defaultContext === false ? undefined : override.defaultContext;
+  if (override.defaultContext !== undefined) {
+    if (override.defaultContext === false)
+      delete next.defaultContext;
+    else
+      next.defaultContext = override.defaultContext;
+  }
+  if (override.acceptanceRole !== undefined) {
+    if (override.acceptanceRole === false)
+      delete next.acceptanceRole;
+    else
+      next.acceptanceRole = 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];
-  if (override.tools !== undefined) {
-    const { tools, mcpDirectTools } = splitToolList(override.tools === false ? [] : override.tools);
-    next.tools = tools;
-    next.mcpDirectTools = mcpDirectTools;
+  if (override.skills !== undefined) {
+    if (override.skills === false)
+      delete next.skills;
+    else
+      next.skills = [...override.skills];
+  }
+  if (override.tools !== undefined)
+    applyToolsOverride(next, override.tools);
+  if (override.allowNestedSubagents !== undefined)
+    next.allowNestedSubagents = override.allowNestedSubagents;
+  if (override.extensions !== undefined) {
+    if (override.extensions === false)
+      delete next.extensions;
+    else
+      next.extensions = [...override.extensions];
   }
   if (override.subagentOnlyExtensions !== undefined) {
-    next.subagentOnlyExtensions = override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions];
+    if (override.subagentOnlyExtensions === false)
+      delete next.subagentOnlyExtensions;
+    else
+      next.subagentOnlyExtensions = [...override.subagentOnlyExtensions];
+  }
+  if (override.mutationTools !== undefined) {
+    if (override.mutationTools === false)
+      delete next.mutationTools;
+    else
+      next.mutationTools = [...override.mutationTools];
   }
   if (override.completionGuard !== undefined)
     next.completionGuard = override.completionGuard;
-  if (override.toolBudget !== undefined)
-    next.toolBudget = override.toolBudget === false ? undefined : override.toolBudget;
+  if (override.toolBudget !== undefined) {
+    if (override.toolBudget === false)
+      delete next.toolBudget;
+    else
+      next.toolBudget = override.toolBudget;
+  }
   return next;
 }
 function clearBuiltinThinking(agent, meta) {
   if (agent.thinking === undefined)
     return agent;
-  return {
-    ...agent,
-    thinking: undefined,
-    override: agent.override ?? { ...meta, base: cloneOverrideBase(agent) }
-  };
+  const { thinking: _thinking, ...next } = agent;
+  return { ...next, override: agent.override ?? { ...meta, base: cloneOverrideBase(agent) } };
 }
 function applyBuiltinOverrides(builtinAgents, userSettings, projectSettings, userSettingsPath, projectSettingsPath) {
   const projectBulkDisabled = projectSettings.disableBuiltins === true && projectSettingsPath !== null;
@@ -635,7 +1123,7 @@ function applyBuiltinOverrides(builtinAgents, userSettings, projectSettings, use
     return applyGlobalThinking(agent, false);
   });
 }
-function customAgentHasFrontmatterField(agent, ...fields) {
+export function agentHasFrontmatterField(agent, ...fields) {
   const frontmatterFields = agentFrontmatterFields.get(agent);
   return frontmatterFields ? fields.some((field) => frontmatterFields.has(field)) : false;
 }
@@ -647,17 +1135,46 @@ function applyCustomAgentOverride(agent, override, meta) {
     return next;
   };
   const fill = (field, frontmatterFields, value) => {
-    if (customAgentHasFrontmatterField(agent, ...frontmatterFields))
+    if (agentHasFrontmatterField(agent, ...frontmatterFields))
       return;
-    mutable()[field] = value;
+    const target = mutable();
+    if (value === undefined)
+      delete target[field];
+    else
+      target[field] = value;
     anyFilled = true;
   };
-  if (override.model !== undefined) {
-    fill("model", ["model"], override.model === false ? undefined : override.model);
+  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);
   }
@@ -667,29 +1184,41 @@ function applyCustomAgentOverride(agent, override, meta) {
   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.disabled !== undefined && agent.disabled === undefined) {
+  if (override.acceptanceRole !== undefined) {
+    fill("acceptanceRole", ["acceptanceRole"], override.acceptanceRole === false ? undefined : override.acceptanceRole);
+  }
+  if (override.disabled !== undefined) {
     mutable().disabled = override.disabled;
     anyFilled = true;
   }
   if (override.skills !== undefined) {
     fill("skills", ["skill", "skills"], override.skills === false ? undefined : [...override.skills]);
   }
-  if (override.tools !== undefined && !customAgentHasFrontmatterField(agent, "tools")) {
-    const { tools, mcpDirectTools } = splitToolList(override.tools === false ? [] : override.tools);
-    const target = mutable();
-    target.tools = tools;
-    target.mcpDirectTools = mcpDirectTools;
+  if (override.tools !== undefined && !agentHasFrontmatterField(agent, "tools")) {
+    applyToolsOverride(mutable(), override.tools);
     anyFilled = true;
   }
+  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);
   }
@@ -698,38 +1227,58 @@ function applyCustomAgentOverride(agent, override, meta) {
   }
   if (!anyFilled || !next)
     return agent;
-  next.override = { ...meta, base: cloneOverrideBase(agent) };
+  next.override = { ...meta, base: agent.override?.base ?? cloneOverrideBase(agent) };
+  const frontmatterFields = agentFrontmatterFields.get(agent);
+  if (frontmatterFields)
+    agentFrontmatterFields.set(next, frontmatterFields);
   return next;
 }
 function applyCustomAgentOverrides(agents, userSettings, projectSettings, userSettingsPath, projectSettingsPath) {
   return agents.map((agent) => {
+    const userOverride = userSettings.overrides[agent.name];
+    const withUserOverride = userOverride ? applyCustomAgentOverride(agent, userOverride, { scope: "user", path: userSettingsPath }) : agent;
     const projectOverride = projectSettings.overrides[agent.name];
     if (projectOverride && projectSettingsPath) {
-      return applyCustomAgentOverride(agent, projectOverride, { scope: "project", path: projectSettingsPath });
+      return applyCustomAgentOverride(withUserOverride, projectOverride, { scope: "project", path: projectSettingsPath });
     }
-    const userOverride = userSettings.overrides[agent.name];
-    if (userOverride) {
-      return applyCustomAgentOverride(agent, userOverride, { scope: "user", path: userSettingsPath });
-    }
-    return agent;
+    return withUserOverride;
   });
 }
 export function buildBuiltinOverrideConfig(base, draft) {
   const override = {};
+  if (draft.description !== undefined) {
+    const description = draft.description.trim();
+    if (description && description !== base.description)
+      override.description = description;
+  }
+  if (draft.output !== base.output)
+    override.output = draft.output ?? false;
+  if (draft.outputMode !== undefined && draft.outputMode !== base.outputMode)
+    override.outputMode = draft.outputMode;
+  if (!arraysEqual(draft.defaultReads, base.defaultReads))
+    override.defaultReads = draft.defaultReads ? [...draft.defaultReads] : false;
   if (draft.model !== base.model)
     override.model = draft.model ?? false;
+  if (draft.modelProvider !== base.modelProvider)
+    override.defaultProvider = draft.modelProvider ?? false;
   if (!arraysEqual(draft.fallbackModels, base.fallbackModels))
     override.fallbackModels = draft.fallbackModels ? [...draft.fallbackModels] : false;
+  if (draft.fast !== base.fast)
+    override.fast = draft.fast === true;
   if (draft.thinking !== base.thinking)
     override.thinking = draft.thinking ?? false;
   if (draft.systemPromptMode !== base.systemPromptMode)
     override.systemPromptMode = draft.systemPromptMode;
   if (draft.inheritProjectContext !== base.inheritProjectContext)
     override.inheritProjectContext = draft.inheritProjectContext;
+  if (draft.inheritGlobalContext !== base.inheritGlobalContext)
+    override.inheritGlobalContext = draft.inheritGlobalContext;
   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)
@@ -740,9 +1289,15 @@ export function buildBuiltinOverrideConfig(base, draft) {
   const draftTools = joinToolList(draft);
   if (!arraysEqual(draftTools, baseTools))
     override.tools = draftTools ? [...draftTools] : false;
+  if (draft.allowNestedSubagents !== base.allowNestedSubagents)
+    override.allowNestedSubagents = draft.allowNestedSubagents === true;
+  if (!arraysEqual(draft.extensions, base.extensions))
+    override.extensions = draft.extensions ? [...draft.extensions] : false;
   if (!arraysEqual(draft.subagentOnlyExtensions, base.subagentOnlyExtensions)) {
     override.subagentOnlyExtensions = draft.subagentOnlyExtensions ? [...draft.subagentOnlyExtensions] : false;
   }
+  if (!arraysEqual(draft.mutationTools, base.mutationTools))
+    override.mutationTools = draft.mutationTools ? [...draft.mutationTools] : false;
   if (draft.completionGuard !== false !== (base.completionGuard !== false)) {
     override.completionGuard = draft.completionGuard !== false;
   }
@@ -851,10 +1406,31 @@ export function removeBuiltinAgentOverrideFields(cwd, name, scope, fields) {
   writeSettingsFile(filePath, settings);
   return { path: filePath, removed: true };
 }
-function listFilesRecursive(dir, predicate) {
+const DISCOVERY_PRUNED_DIR_NAMES = new Set([".git", "node_modules", ".dm", "sync-backups"]);
+function isDiscoveryNestedProjectRoot(dir) {
+  return isDirectory(getProjectConfigDir(dir)) || isDirectory(path.join(dir, ".agents"));
+}
+function shouldPruneDiscoveryDir(rootDir, dir, dirName) {
+  if (DISCOVERY_PRUNED_DIR_NAMES.has(dirName))
+    return true;
+  if (fs.existsSync(path.join(dir, ".git")))
+    return true;
+  return path.resolve(dir) !== path.resolve(rootDir) && isDiscoveryNestedProjectRoot(dir);
+}
+function listFilesRecursive(dir, predicate, rootDir = dir, visitedDirectories = new Set, inspectedDirectories = new Set) {
   const files = [];
   if (!fs.existsSync(dir))
     return files;
+  inspectedDirectories.add(path.resolve(dir));
+  let realDir;
+  try {
+    realDir = fs.realpathSync(dir);
+  } catch {
+    return files;
+  }
+  if (visitedDirectories.has(realDir))
+    return files;
+  visitedDirectories.add(realDir);
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
@@ -863,8 +1439,18 @@ function listFilesRecursive(dir, predicate) {
   }
   for (const entry of entries) {
     const filePath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...listFilesRecursive(filePath, predicate));
+    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, visitedDirectories, inspectedDirectories));
+      }
       continue;
     }
     if (!entry.isFile() && !entry.isSymbolicLink())
@@ -875,6 +1461,75 @@ function listFilesRecursive(dir, predicate) {
   }
   return files;
 }
+const agentDefinitionInspectionDirectories = new WeakMap;
+function rememberAgentDefinitionInspection(inspection, directories) {
+  agentDefinitionInspectionDirectories.set(inspection, [...new Set([...directories].map((directory) => path.resolve(directory)))]);
+  return inspection;
+}
+function inspectedAgentDefinitionDirectories(inspection, root) {
+  return agentDefinitionInspectionDirectories.get(inspection) ?? [path.resolve(root)];
+}
+const DEFAULT_AGENT_DEFINITION_INSPECTION_FS = {
+  existsSync: fs.existsSync,
+  realpathSync: fs.realpathSync,
+  statSync: fs.statSync,
+  readdirSync: (dir) => fs.readdirSync(dir, { withFileTypes: true })
+};
+export function inspectAgentDefinitionDirectory(dir, operations = DEFAULT_AGENT_DEFINITION_INSPECTION_FS) {
+  const root = path.resolve(dir);
+  try {
+    if (!operations.existsSync(root))
+      return rememberAgentDefinitionInspection({ files: [], state: "absent" }, [root]);
+    if (!operations.statSync(root).isDirectory())
+      return rememberAgentDefinitionInspection({ files: [], state: "not-directory" }, [root]);
+  } catch {
+    return rememberAgentDefinitionInspection({ files: [], state: "unreadable" }, [root]);
+  }
+  const files = [];
+  let unreadable = false;
+  const visitedDirectories = new Set;
+  const inspectedDirectories = new Set;
+  const visit = (current) => {
+    inspectedDirectories.add(path.resolve(current));
+    let realDir;
+    try {
+      realDir = operations.realpathSync?.(current) ?? path.resolve(current);
+    } catch {
+      unreadable = true;
+      return;
+    }
+    if (visitedDirectories.has(realDir))
+      return;
+    visitedDirectories.add(realDir);
+    let entries;
+    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 rememberAgentDefinitionInspection({ files, state: unreadable ? "unreadable" : files.length ? "candidates" : "empty" }, inspectedDirectories);
+}
 function isLegacyAgentSkillPath(rootDir, filePath) {
   const relative = path.relative(rootDir, filePath);
   const parts = relative.split(path.sep).map((part) => part.toLowerCase());
@@ -883,110 +1538,327 @@ function isLegacyAgentSkillPath(rootDir, filePath) {
   }
   return parts.some((part, index) => part === ".agents" && parts[index + 1] === "skills");
 }
-function loadAgentsFromDir(dir, source) {
-  const agents = [];
-  for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".md") && !fileName.endsWith(".chain.md"))) {
+function isJsonSerializable(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return true;
+  if (typeof value === "number")
+    return Number.isFinite(value);
+  if (Array.isArray(value))
+    return value.every(isJsonSerializable);
+  if (value && typeof value === "object")
+    return Object.values(value).every(isJsonSerializable);
+  return false;
+}
+function parseAgentRunnerFrontmatter(raw, agentName) {
+  if (raw === undefined || !raw.trim())
+    return;
+  let parsed;
+  try {
+    parsed = parseYaml(raw);
+  } catch (error) {
+    throw new Error(`Agent '${agentName}' has invalid runner frontmatter: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`Agent '${agentName}' has invalid runner frontmatter; expected an object.`);
+  }
+  const runner = parsed;
+  if (runner.type === "dm") {
+    if (Object.keys(runner).some((key) => key !== "type"))
+      throw new Error(`Agent '${agentName}' has invalid DM runner frontmatter; only 'type' is supported.`);
+    return { type: "dm" };
+  }
+  if (runner.type === "external-job") {
+    if (typeof runner.provider !== "string" || !runner.provider.trim() || runner.provider.trim() !== runner.provider) {
+      throw new Error(`Agent '${agentName}' external-job runner requires a non-empty trimmed provider string.`);
+    }
+    if (runner.options !== undefined && (!runner.options || typeof runner.options !== "object" || Array.isArray(runner.options) || !isJsonSerializable(runner.options))) {
+      throw new Error(`Agent '${agentName}' external-job runner options must be a JSON-serializable object.`);
+    }
+    const supported = new Set(["type", "provider", "options"]);
+    const unknown = Object.keys(runner).filter((key) => !supported.has(key));
+    if (unknown.length > 0)
+      throw new Error(`Agent '${agentName}' external-job runner has unsupported fields: ${unknown.join(", ")}.`);
+    return {
+      type: "external-job",
+      provider: runner.provider,
+      ...runner.options ? { options: runner.options } : {}
+    };
+  }
+  if (runner.type !== "external-cli") {
+    throw new Error(`Agent '${agentName}' has invalid runner.type; expected 'dm', 'external-cli', or 'external-job'.`);
+  }
+  if (typeof runner.command !== "string" || !runner.command.trim()) {
+    throw new Error(`Agent '${agentName}' 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(`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 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) => 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" } : {},
+    ...capabilities ? { capabilities } : {}
+  };
+}
+function validateExternalRunnerProfile(frontmatter, agentName, runner) {
+  if (runner?.type !== "external-cli" && runner?.type !== "external-job")
+    return;
+  const unsupported = ["tools", "allowNestedSubagents", "model", "fallbackModels", "thinking", "extensions", "subagentOnlyExtensions", "mutationTools", "maxSubagentDepth", "completionGuard", "skills", "skill", "skillPath", "toolBudget", "permission", "permissions"].filter((field) => frontmatter[field] !== undefined);
+  if (unsupported.length > 0) {
+    throw new Error(`Agent '${agentName}' uses runner.type='${runner.type}' and declares unsupported DM-only fields: ${unsupported.join(", ")}.`);
+  }
+}
+function parseAgentAcceptanceFrontmatter(raw, agentName) {
+  if (raw === undefined || !raw.trim())
+    return;
+  let parsed;
+  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;
+}
+function readAgentDefinitionFiles(dir, inspection = inspectAgentDefinitionDirectory(dir)) {
+  const files = [];
+  for (const filePath of inspection.files) {
     if (isLegacyAgentSkillPath(dir, filePath)) {
       continue;
     }
-    let content;
     try {
-      content = fs.readFileSync(filePath, "utf-8");
+      files.push({ filePath, content: fs.readFileSync(filePath, "utf-8") });
     } catch {
       continue;
     }
-    const { frontmatter, body } = parseFrontmatter(content);
-    if (!frontmatter.name || !frontmatter.description) {
-      continue;
+  }
+  return files;
+}
+function resolveAgentRelativeExtensionPaths(paths, agentFilePath) {
+  if (paths === undefined)
+    return;
+  const baseDir = path.dirname(agentFilePath);
+  return paths.map((entry) => {
+    const trimmed = entry.trim();
+    if (trimmed === "." || trimmed === ".." || trimmed.startsWith("./") || trimmed.startsWith("../")) {
+      return path.resolve(baseDir, trimmed);
     }
-    const localName = frontmatter.name;
-    const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
-    if (parsedPackage.error)
-      continue;
-    const packageName = parsedPackage.packageName;
-    const runtimeName = buildRuntimeName(localName, packageName);
-    const rawTools = frontmatter.tools?.split(",").map((t) => t.trim()).filter(Boolean);
-    const mcpDirectTools = [];
-    const tools = [];
-    if (rawTools) {
-      for (const tool of rawTools) {
-        if (tool.startsWith("mcp:")) {
-          mcpDirectTools.push(tool.slice(4));
-        } else {
-          tools.push(tool);
+    return entry;
+  });
+}
+function loadAgentsFromDefinitionFiles(files, source, discoveryPriority, packageSource) {
+  const agents = [];
+  const diagnostics = [];
+  for (const { filePath, content } of files) {
+    let name;
+    let runtimeName;
+    let packageSpecified = false;
+    try {
+      const { frontmatter, body } = parseFrontmatter(content);
+      if (!frontmatter.name || !frontmatter.description) {
+        continue;
+      }
+      const localName = frontmatter.name;
+      name = localName;
+      const parsedPackage = parsePackageName(frontmatter.package, `Agent '${localName}' package`);
+      packageSpecified = parsedPackage.packageName !== undefined || parsedPackage.error !== undefined;
+      if (parsedPackage.error)
+        throw new Error(parsedPackage.error);
+      const packageName = parsedPackage.packageName;
+      runtimeName = buildRuntimeName(localName, packageName);
+      const runner = parseAgentRunnerFrontmatter(frontmatter.runner, localName);
+      validateExternalRunnerProfile(frontmatter, localName, runner);
+      const rawTools = parseFrontmatterList(frontmatter.tools);
+      const parsedTools = splitToolList(rawTools);
+      const tools = parsedTools.tools ?? [];
+      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);
+      const fallbackModels = parseFrontmatterList(frontmatter.fallbackModels);
+      const systemPromptMode = frontmatter.systemPromptMode === "replace" ? "replace" : frontmatter.systemPromptMode === "append" ? "append" : defaultSystemPromptMode(localName);
+      const inheritProjectContext = frontmatter.inheritProjectContext === "true" ? true : frontmatter.inheritProjectContext === "false" ? false : defaultInheritProjectContext(localName);
+      const inheritGlobalContext = frontmatter.inheritGlobalContext === "true";
+      const inheritSkills = frontmatter.inheritSkills === "true" ? true : frontmatter.inheritSkills === "false" ? false : defaultInheritSkills();
+      const defaultContext = frontmatter.defaultContext === "fork" ? "fork" : frontmatter.defaultContext === "fresh" ? "fresh" : undefined;
+      let defaultAsync;
+      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;
+      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;
       }
-    }
-    const defaultReads = frontmatter.defaultReads?.split(",").map((f) => f.trim()).filter(Boolean);
-    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 systemPromptMode = frontmatter.systemPromptMode === "replace" ? "replace" : frontmatter.systemPromptMode === "append" ? "append" : defaultSystemPromptMode(localName);
-    const inheritProjectContext = frontmatter.inheritProjectContext === "true" ? true : frontmatter.inheritProjectContext === "false" ? false : defaultInheritProjectContext(localName);
-    const inheritSkills = frontmatter.inheritSkills === "true" ? true : frontmatter.inheritSkills === "false" ? false : defaultInheritSkills();
-    const defaultContext = frontmatter.defaultContext === "fork" ? "fork" : frontmatter.defaultContext === "fresh" ? "fresh" : undefined;
-    let extensions;
-    if (frontmatter.extensions !== undefined) {
-      extensions = frontmatter.extensions.split(",").map((e) => e.trim()).filter(Boolean);
-    }
-    let subagentOnlyExtensions;
-    if (frontmatter.subagentOnlyExtensions !== undefined) {
-      subagentOnlyExtensions = frontmatter.subagentOnlyExtensions.split(",").map((e) => e.trim()).filter(Boolean);
-    }
-    const extraFields = {};
-    for (const [key, value] of Object.entries(frontmatter)) {
-      if (!KNOWN_FIELDS.has(key))
-        extraFields[key] = value;
-    }
-    const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
-    let toolBudget;
-    if (frontmatter.toolBudget !== undefined && frontmatter.toolBudget.trim()) {
-      const parsed = JSON.parse(frontmatter.toolBudget);
-      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new Error(`Agent '${localName}' has invalid toolBudget frontmatter; expected a JSON object.`);
+      let defaultToolTimeoutMs;
+      if (frontmatter.toolTimeoutMs !== undefined) {
+        const parsed = Number(frontmatter.toolTimeoutMs);
+        if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 2147483647) {
+          throw new Error(`Agent '${localName}' has invalid toolTimeoutMs frontmatter; expected a positive integer no larger than 2147483647.`);
+        }
+        defaultToolTimeoutMs = parsed;
+      }
+      const defaultAcceptance = parseAgentAcceptanceFrontmatter(frontmatter.acceptance, localName);
+      let outputMode;
+      if (frontmatter.outputMode !== undefined) {
+        if (frontmatter.outputMode === "inline" || frontmatter.outputMode === "file-only")
+          outputMode = frontmatter.outputMode;
+        else
+          throw new Error(`Agent '${localName}' has invalid outputMode frontmatter; expected 'inline' or 'file-only'.`);
       }
-      toolBudget = parsed;
+      let acceptanceRole;
+      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 = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.extensions), filePath);
+      const subagentOnlyExtensions = resolveAgentRelativeExtensionPaths(parseFrontmatterList(frontmatter.subagentOnlyExtensions), filePath);
+      const mutationTools = parseFrontmatterList(frontmatter.mutationTools);
+      let fast;
+      if (frontmatter.fast !== undefined) {
+        if (frontmatter.fast === "true")
+          fast = true;
+        else if (frontmatter.fast === "false")
+          fast = false;
+        else
+          throw new Error(`Agent '${localName}' has invalid fast frontmatter; expected true or false.`);
+      }
+      let allowNestedSubagents;
+      if (frontmatter.allowNestedSubagents !== undefined) {
+        if (frontmatter.allowNestedSubagents === "true")
+          allowNestedSubagents = true;
+        else if (frontmatter.allowNestedSubagents === "false")
+          allowNestedSubagents = false;
+        else
+          throw new Error(`Agent '${localName}' has invalid allowNestedSubagents frontmatter; expected true or false.`);
+      }
+      const extraFields = {};
+      for (const [key, value] of Object.entries(frontmatter)) {
+        if (!KNOWN_FIELDS.has(key))
+          extraFields[key] = value;
+      }
+      const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+      if (frontmatter.permission !== undefined && frontmatter.permissions !== undefined) {
+        throw new Error(`Agent '${localName}' cannot declare both permission and permissions frontmatter.`);
+      }
+      const permissionSource = frontmatter.permissions ?? frontmatter.permission;
+      const permissions = permissionSource?.trim() ? validatePermissionRules(parseYaml(permissionSource), `Agent '${localName}' permissions`) : undefined;
+      let toolBudget;
+      if (frontmatter.toolBudget !== undefined && frontmatter.toolBudget.trim()) {
+        const parsed = JSON.parse(frontmatter.toolBudget);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+          throw new Error(`Agent '${localName}' has invalid toolBudget frontmatter; expected a JSON object.`);
+        }
+        toolBudget = parsed;
+      }
+      const completionGuard = frontmatter.completionGuard === "false" ? false : frontmatter.completionGuard === "true" ? true : undefined;
+      const maxSubagentDepth = Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0 ? parsedMaxSubagentDepth : undefined;
+      const memory = parseMemoryFrontmatter(frontmatter.memory);
+      const agent = {
+        name: runtimeName,
+        ...runner !== undefined ? { runner } : {},
+        localName,
+        ...packageName !== undefined ? { packageName } : {},
+        ...packageSource?.packageName ? { packageSourceName: packageSource.packageName } : {},
+        ...packageSource?.packageVersion ? { packageSourceVersion: packageSource.packageVersion } : {},
+        ...packageSource?.packageRoot ? { packageSourceRoot: packageSource.packageRoot } : {},
+        description: frontmatter.description,
+        ...aliases !== undefined ? { aliases } : {},
+        ...rawTools !== undefined ? { tools } : {},
+        ...allowNestedSubagents !== undefined ? { allowNestedSubagents } : {},
+        ...mcpDirectTools.length > 0 ? { mcpDirectTools } : {},
+        ...frontmatter.model !== undefined ? { model: frontmatter.model } : {},
+        ...fallbackModels?.length ? { fallbackModels } : {},
+        ...fast !== undefined ? { fast } : {},
+        ...frontmatter.thinking !== undefined ? { thinking: frontmatter.thinking === "false" ? false : frontmatter.thinking } : {},
+        systemPromptMode,
+        inheritProjectContext,
+        inheritGlobalContext,
+        inheritSkills,
+        ...defaultContext !== undefined ? { defaultContext } : {},
+        ...defaultAsync !== undefined ? { defaultAsync } : {},
+        ...defaultTimeoutMs !== undefined ? { defaultTimeoutMs } : {},
+        ...defaultToolTimeoutMs !== undefined ? { defaultToolTimeoutMs } : {},
+        ...defaultAcceptance !== undefined ? { defaultAcceptance } : {},
+        ...acceptanceRole !== undefined ? { acceptanceRole } : {},
+        systemPrompt: body,
+        source,
+        filePath,
+        ...discoveryPriority !== undefined ? { discoveryPriority } : {},
+        ...skills?.length ? { skills } : {},
+        ...skillPath?.length ? { skillPath } : {},
+        ...extensions !== undefined ? { extensions } : {},
+        ...subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions } : {},
+        ...mutationTools?.length ? { mutationTools } : {},
+        ...frontmatter.output !== undefined ? { output: frontmatter.output } : {},
+        ...outputMode !== undefined ? { outputMode } : {},
+        ...defaultReads?.length ? { defaultReads } : {},
+        defaultProgress: frontmatter.defaultProgress === "true",
+        interactive: frontmatter.interactive === "true",
+        ...maxSubagentDepth !== undefined ? { maxSubagentDepth } : {},
+        ...completionGuard !== undefined ? { completionGuard } : {},
+        ...toolBudget !== undefined ? { toolBudget } : {},
+        ...permissions !== undefined ? { permissions } : {},
+        ...memory !== undefined ? { memory } : {},
+        ...Object.keys(extraFields).length > 0 ? { extraFields } : {}
+      };
+      agentFrontmatterFields.set(agent, new Set(Object.keys(frontmatter)));
+      agents.push(agent);
+    } catch (error) {
+      diagnostics.push({ source, filePath, ...name ? { name } : {}, ...runtimeName && runtimeName !== name ? { runtimeName } : {}, ...packageSpecified ? { packageSpecified: true } : {}, ...discoveryPriority !== undefined ? { discoveryPriority } : {}, error: error instanceof Error ? error.message : String(error) });
     }
-    const completionGuard = frontmatter.completionGuard === "false" ? false : frontmatter.completionGuard === "true" ? true : undefined;
-    const agent = {
-      name: runtimeName,
-      localName,
-      packageName,
-      description: frontmatter.description,
-      tools: tools.length > 0 ? tools : undefined,
-      mcpDirectTools: mcpDirectTools.length > 0 ? mcpDirectTools : undefined,
-      model: frontmatter.model,
-      fallbackModels: fallbackModels && fallbackModels.length > 0 ? fallbackModels : undefined,
-      thinking: frontmatter.thinking,
-      systemPromptMode,
-      inheritProjectContext,
-      inheritSkills,
-      defaultContext,
-      systemPrompt: body,
-      source,
-      filePath,
-      skills: skills && skills.length > 0 ? skills : undefined,
-      extensions,
-      subagentOnlyExtensions,
-      output: frontmatter.output,
-      defaultReads: defaultReads && defaultReads.length > 0 ? defaultReads : undefined,
-      defaultProgress: frontmatter.defaultProgress === "true",
-      interactive: frontmatter.interactive === "true",
-      maxSubagentDepth: Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0 ? parsedMaxSubagentDepth : undefined,
-      completionGuard,
-      toolBudget,
-      memory: parseMemoryFrontmatter(frontmatter.memory),
-      extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined
-    };
-    agentFrontmatterFields.set(agent, new Set(Object.keys(frontmatter)));
-    agents.push(agent);
   }
-  return agents;
+  return { agents, diagnostics };
+}
+function loadAgentsFromDir(dir, source, discoveryPriority, packageSource, inspection = inspectAgentDefinitionDirectory(dir)) {
+  return loadAgentsFromDefinitionFiles(readAgentDefinitionFiles(dir, inspection), source, discoveryPriority, packageSource);
+}
+function reportAgentDefinitionDirectory(source, dir, inspection) {
+  return {
+    source,
+    path: path.resolve(dir),
+    state: inspection.state,
+    ...inspection.state === "candidates" ? { candidateCount: inspection.files.length } : {}
+  };
 }
 function loadChainsFromDir(dir, source) {
   const chains = new Map;
   const diagnostics = [];
-  for (const filePath of listFilesRecursive(dir, (fileName) => fileName.endsWith(".chain.md") || fileName.endsWith(".chain.json"))) {
+  const directories = new Set;
+  const files = listFilesRecursive(dir, (fileName) => fileName.endsWith(".chain.md") || fileName.endsWith(".chain.json"), dir, new Set, directories);
+  for (const filePath of files) {
     let content;
     try {
       content = fs.readFileSync(filePath, "utf-8");
@@ -1004,7 +1876,7 @@ function loadChainsFromDir(dir, source) {
       continue;
     }
   }
-  return { chains: Array.from(chains.values()), diagnostics };
+  return { chains: Array.from(chains.values()), diagnostics, files, directories: [...directories] };
 }
 function isDirectory(p) {
   try {
@@ -1014,23 +1886,21 @@ function isDirectory(p) {
   }
 }
 function resolveNearestProjectAgentDirs(cwd) {
-  const projectRoot = findNearestProjectRoot(cwd);
+  const projectRoot = findConfiguredProjectRoot(cwd);
   if (!projectRoot)
-    return { readDirs: [], preferredDir: null };
+    return { readDirs: [], candidateDirs: [], preferredDir: null };
   const legacyDir = path.join(projectRoot, ".agents");
   const preferredDir = path.join(getProjectConfigDir(projectRoot), "agents");
+  const candidateDirs = [legacyDir, preferredDir];
   const readDirs = [];
   if (isDirectory(legacyDir))
     readDirs.push(legacyDir);
   if (isDirectory(preferredDir))
     readDirs.push(preferredDir);
-  return {
-    readDirs,
-    preferredDir
-  };
+  return { readDirs, candidateDirs, preferredDir };
 }
 function resolveNearestProjectChainDirs(cwd) {
-  const projectRoot = findNearestProjectRoot(cwd);
+  const projectRoot = findConfiguredProjectRoot(cwd);
   if (!projectRoot)
     return { readDirs: [], preferredDir: null };
   const preferredDir = path.join(getProjectConfigDir(projectRoot), "chains");
@@ -1040,6 +1910,8 @@ function resolveNearestProjectChainDirs(cwd) {
   };
 }
 const BUILTIN_AGENTS_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "agents");
+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 = "DM_SUBAGENT_EXTRA_AGENT_DIRS";
 function extraUserAgentDirs() {
   const raw = process.env[EXTRA_AGENT_DIRS_ENV];
@@ -1047,93 +1919,369 @@ function extraUserAgentDirs() {
     return [];
   return raw.split(path.delimiter).map((dir) => dir.trim()).filter((dir) => dir.length > 0);
 }
-export function discoverAgents(cwd, scope) {
-  const userDirOld = path.join(getAgentDir(), "agents");
-  const userDirNew = path.join(os.homedir(), ".agents");
-  const { readDirs: projectAgentDirs, preferredDir: projectAgentsDir } = resolveNearestProjectAgentDirs(cwd);
-  const userSettingsPath = getUserAgentSettingsPath();
-  const projectSettingsPath = getProjectAgentSettingsPath(cwd);
-  const userSettings = scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath);
-  const projectSettings = scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath);
-  const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
-  const packageSubagentPaths = collectPackageSubagentPaths(cwd, {
-    includeUser: scope !== "project",
-    includeProject: scope !== "user"
-  });
-  const builtinAgents = applyBuiltinOverrides(applySubagentDefaultModel(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const userAgentsExtra = scope === "project" ? [] : extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user"));
-  const userAgentsOld = scope === "project" ? [] : loadAgentsFromDir(userDirOld, "user");
-  const userAgentsNew = scope === "project" ? [] : loadAgentsFromDir(userDirNew, "user");
-  const userAgents = applyCustomAgentOverrides(applySubagentDefaultModel([...userAgentsExtra, ...userAgentsOld, ...userAgentsNew], defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const projectAgents = applyCustomAgentOverrides(applySubagentDefaultModel(scope === "user" ? [] : projectAgentDirs.flatMap((dir) => loadAgentsFromDir(dir, "project")), defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const packageAgents = applyCustomAgentOverrides(applySubagentDefaultModel(packageSubagentPaths.agents.flatMap((dir) => loadAgentsFromDir(dir, "package")), defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const agents = mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents).filter((agent) => agent.disabled !== true);
-  return { agents, projectAgentsDir, modelScope };
-}
-export function discoverAgentsAll(cwd) {
+const agentDiscoveryCache = new Map;
+function isPathWithin(root, candidate) {
+  const relative = path.relative(path.resolve(root), path.resolve(candidate));
+  return relative === "" || !relative.startsWith("..") && !path.isAbsolute(relative);
+}
+function addDirectoryWatchPaths(paths, root, files, directories = []) {
+  const resolvedRoot = path.resolve(root);
+  paths.add(resolvedRoot);
+  for (const directory of directories) {
+    if (isPathWithin(resolvedRoot, directory))
+      paths.add(path.resolve(directory));
+  }
+  for (const file of files) {
+    paths.add(path.resolve(file));
+    let current = path.resolve(path.dirname(file));
+    while (isPathWithin(resolvedRoot, current)) {
+      paths.add(current);
+      if (current === resolvedRoot)
+        break;
+      current = path.dirname(current);
+    }
+  }
+}
+function watchPathSignature(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (stat.isDirectory()) {
+      const entries = fs.readdirSync(filePath, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => `${entry.name}:${entry.isDirectory() ? "d" : entry.isSymbolicLink() ? "l" : "f"}`).join("|");
+      return `directory:${entries}`;
+    }
+    return `file:${stat.size}:${stat.mtimeMs}`;
+  } catch {
+    return "missing";
+  }
+}
+function discoveryFingerprint(paths) {
+  return [...new Set(paths)].sort((left, right) => left.localeCompare(right)).map((filePath) => `${filePath}:${watchPathSignature(filePath)}`).join(`
+`);
+}
+function discoveryCacheKey(cwd, preferredModelProvider) {
+  return JSON.stringify([
+    path.resolve(cwd),
+    preferredModelProvider ?? null,
+    getProjectConfigDir(path.resolve(cwd)),
+    getAgentDir(),
+    os.homedir(),
+    process.env.HOME ?? "",
+    process.env.USERPROFILE ?? "",
+    process.env[EXTRA_AGENT_DIRS_ENV] ?? "",
+    process.env.PI_OFFLINE ?? "",
+    process.env.APPDATA ?? ""
+  ]);
+}
+function projectDiscoveryWatchPaths(cwd) {
+  const paths = [];
+  let current = path.resolve(cwd);
+  while (true) {
+    paths.push(getProjectConfigDir(current), path.join(current, ".agents"), path.join(current, ".git"));
+    const parent = path.dirname(current);
+    if (parent === current)
+      break;
+    current = parent;
+  }
+  return paths;
+}
+function packageEntryIncluded(scope, packageScopes) {
+  if (scope === "both" || packageScopes.has("root"))
+    return true;
+  return packageScopes.has(scope);
+}
+function buildAgentDiscoverySources(cwd, preferredModelProvider) {
+  const effectiveCwd = path.resolve(cwd);
   const userDirOld = path.join(getAgentDir(), "agents");
   const userDirNew = path.join(os.homedir(), ".agents");
   const userChainDir = getUserChainDir();
-  const { readDirs: projectDirs, preferredDir: projectDir } = resolveNearestProjectAgentDirs(cwd);
-  const { readDirs: projectChainDirs, preferredDir: projectChainDir } = resolveNearestProjectChainDirs(cwd);
+  const { readDirs: projectAgentDirs, candidateDirs: projectCandidateDirs, preferredDir: projectAgentsDir } = resolveNearestProjectAgentDirs(effectiveCwd);
+  const { readDirs: projectChainDirs, preferredDir: projectChainDir } = resolveNearestProjectChainDirs(effectiveCwd);
   const userSettingsPath = getUserAgentSettingsPath();
-  const projectSettingsPath = getProjectAgentSettingsPath(cwd);
-  const userSettings = readSubagentSettings(userSettingsPath);
-  const projectSettings = readSubagentSettings(projectSettingsPath);
-  const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const packageSubagentPaths = collectPackageSubagentPaths(cwd);
-  const builtin = applyBuiltinOverrides(applySubagentDefaultModel(loadAgentsFromDir(BUILTIN_AGENTS_DIR, "builtin"), defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const user = applyCustomAgentOverrides(applySubagentDefaultModel([
-    ...extraUserAgentDirs().flatMap((dir) => loadAgentsFromDir(dir, "user")),
-    ...loadAgentsFromDir(userDirOld, "user"),
-    ...loadAgentsFromDir(userDirNew, "user")
-  ], defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const packageMap = new Map;
-  for (const dir of packageSubagentPaths.agents) {
-    for (const agent of loadAgentsFromDir(dir, "package")) {
-      if (!packageMap.has(agent.name))
-        packageMap.set(agent.name, agent);
+  const projectSettingsPath = getProjectAgentSettingsPath(effectiveCwd);
+  const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd);
+  const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
+  const userLoaded = [...extraUserAgentDirs(), userDirOld, userDirNew].map((dir, discoveryPriority) => {
+    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) => {
+    const inspection = projectInspections.get(dir);
+    return { dir, inspection, loaded: loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : 0, undefined, inspection) };
+  });
+  const packageLoaded = packageSubagentPaths.agents.map((entry, index) => {
+    const inspection = inspectAgentDefinitionDirectory(entry.dir);
+    return { dir: entry.dir, inspection, packageEntry: entry, loaded: loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry, inspection) };
+  });
+  const watchPaths = new Set([
+    userSettingsPath,
+    ...projectSettingsPath ? [projectSettingsPath] : [],
+    ...projectDiscoveryWatchPaths(effectiveCwd),
+    ...findProjectRootCandidates(effectiveCwd).map((root) => path.join(getProjectConfigDir(root), "settings.json")),
+    ...packageSubagentPaths.watchPaths
+  ]);
+  for (const directory of userLoaded)
+    addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
+  for (const dir of projectCandidateDirs) {
+    const inspection = projectInspections.get(dir);
+    addDirectoryWatchPaths(watchPaths, dir, inspection?.files ?? [], inspection ? inspectedAgentDefinitionDirectories(inspection, dir) : []);
+  }
+  for (const directory of packageLoaded)
+    addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
+  const userDir = process.env.DM_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
+  return {
+    cwd: effectiveCwd,
+    ...preferredModelProvider !== undefined ? { preferredModelProvider } : {},
+    userDir,
+    userDirOld,
+    userDirNew,
+    userChainDir,
+    projectAgentDirs,
+    projectCandidateDirs,
+    projectAgentsDir,
+    projectChainDirs,
+    projectChainDir,
+    userSettingsPath,
+    projectSettingsPath,
+    packageSubagentPaths,
+    builtinLoaded,
+    userLoaded,
+    projectLoaded,
+    projectInspections,
+    packageLoaded,
+    watchPaths: [...watchPaths]
+  };
+}
+function ensureDiscoveryChains(sources) {
+  if (sources.userChains)
+    return;
+  sources.packageChainLoaded = sources.packageSubagentPaths.chains.map((entry) => ({ entry, loaded: loadChainsFromDir(entry.dir, "package") }));
+  sources.userChains = loadChainsFromDir(sources.userChainDir, "user");
+  sources.projectChainLoaded = sources.projectChainDirs.map((dir) => ({ dir, loaded: loadChainsFromDir(dir, "project") }));
+  const watchPaths = new Set(sources.watchPaths);
+  addDirectoryWatchPaths(watchPaths, sources.userChainDir, sources.userChains.files, sources.userChains.directories);
+  for (const chain of sources.projectChainLoaded)
+    addDirectoryWatchPaths(watchPaths, chain.dir, chain.loaded.files, chain.loaded.directories);
+  for (const chain of sources.packageChainLoaded)
+    addDirectoryWatchPaths(watchPaths, chain.entry.dir, chain.loaded.files, chain.loaded.directories);
+  sources.watchPaths = [...watchPaths];
+}
+function getAgentDiscoverySources(cwd, preferredModelProvider, includeChains = false) {
+  const key = discoveryCacheKey(cwd, preferredModelProvider);
+  const cached = agentDiscoveryCache.get(key);
+  if (cached && cached.fingerprint === discoveryFingerprint(cached.sources.watchPaths)) {
+    if (includeChains) {
+      ensureDiscoveryChains(cached.sources);
+      cached.fingerprint = discoveryFingerprint(cached.sources.watchPaths);
     }
+    return cached.sources;
+  }
+  const sources = buildAgentDiscoverySources(cwd, preferredModelProvider);
+  const entry = { sources, fingerprint: discoveryFingerprint(sources.watchPaths) };
+  agentDiscoveryCache.set(key, entry);
+  if (includeChains) {
+    ensureDiscoveryChains(sources);
+    entry.fingerprint = discoveryFingerprint(sources.watchPaths);
+  }
+  return sources;
+}
+export function clearAgentDiscoveryCache() {
+  agentDiscoveryCache.clear();
+}
+function ensureSettingsForScope(sources, scope, preferredModelProvider) {
+  if (scope !== "project" && sources.userSettings === undefined) {
+    if (sources.packageSubagentPaths.settingsErrors.user)
+      throw sources.packageSubagentPaths.settingsErrors.user;
+    sources.userSettings = selectProviderOverrides(readSubagentSettings(sources.userSettingsPath), preferredModelProvider);
+  }
+  if (scope !== "user" && sources.projectSettings === undefined) {
+    if (sources.packageSubagentPaths.settingsErrors.project)
+      throw sources.packageSubagentPaths.settingsErrors.project;
+    sources.projectSettings = selectProviderOverrides(readSubagentSettings(sources.projectSettingsPath), preferredModelProvider);
   }
-  const packageAgents = applyCustomAgentOverrides(applySubagentDefaultModel(Array.from(packageMap.values()), defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+}
+function settingsForScope(sources, scope) {
+  ensureSettingsForScope(sources, scope, sources.preferredModelProvider);
+  return {
+    user: scope === "project" ? EMPTY_SUBAGENT_SETTINGS : sources.userSettings ?? EMPTY_SUBAGENT_SETTINGS,
+    project: scope === "user" ? EMPTY_SUBAGENT_SETTINGS : sources.projectSettings ?? EMPTY_SUBAGENT_SETTINGS
+  };
+}
+function configuredAgentsForScope(sources, scope, settingsScope = scope) {
+  const { user: userSettings, project: projectSettings } = settingsForScope(sources, settingsScope);
+  const defaultProvider = resolveSubagentDefaultProvider(userSettings, projectSettings, sources.projectSettingsPath);
+  const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath, defaultProvider);
+  const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, sources.projectSettingsPath);
+  const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, sources.projectSettingsPath);
+  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, sources.projectSettingsPath);
+  const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions);
+  const builtin = applyBuiltinOverrides(applyDefaults(sources.builtinLoaded.agents), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
+  const user = applyCustomAgentOverrides(applyDefaults(scope === "project" ? [] : sources.userLoaded.flatMap((loaded) => loaded.loaded.agents)), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
   const projectMap = new Map;
-  for (const dir of projectDirs) {
-    for (const agent of loadAgentsFromDir(dir, "project")) {
-      projectMap.set(agent.name, agent);
-    }
+  if (scope !== "user")
+    for (const loaded of sources.projectLoaded)
+      for (const agent of loaded.loaded.agents)
+        projectMap.set(agent.name, agent);
+  const project = applyCustomAgentOverrides(applyDefaults(Array.from(projectMap.values())), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
+  const packageMap = new Map;
+  for (const loaded of sources.packageLoaded) {
+    if (!loaded.packageEntry || !packageEntryIncluded(scope, loaded.packageEntry.scope))
+      continue;
+    for (const agent of loaded.loaded.agents)
+      if (!packageMap.has(agent.name))
+        packageMap.set(agent.name, agent);
   }
-  const project = applyCustomAgentOverrides(applySubagentDefaultModel(Array.from(projectMap.values()), defaultModel), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
-  const chainMap = new Map;
-  const packageChainDiagnostics = [];
+  const packageAgents = applyCustomAgentOverrides(applyDefaults(Array.from(packageMap.values())), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
+  return {
+    builtin,
+    package: packageAgents,
+    user,
+    project,
+    userSettings,
+    projectSettings,
+    maxThinking,
+    modelScope: projectSettings.modelScope ?? userSettings.modelScope
+  };
+}
+function discoveryDirectories(sources, scope) {
+  const directories = [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)));
+  for (const directory of sources.packageLoaded) {
+    if (directory.packageEntry && packageEntryIncluded(scope, directory.packageEntry.scope))
+      directories.push(reportAgentDefinitionDirectory("package", directory.dir, directory.inspection));
+  }
+  return directories;
+}
+function discoveryDiagnostics(sources, scope) {
+  return [
+    ...sources.builtinLoaded.diagnostics,
+    ...scope === "project" ? [] : sources.userLoaded.flatMap((loaded) => loaded.loaded.diagnostics),
+    ...scope === "user" ? [] : sources.projectLoaded.flatMap((loaded) => loaded.loaded.diagnostics),
+    ...sources.packageLoaded.filter((loaded) => loaded.packageEntry && packageEntryIncluded(scope, loaded.packageEntry.scope)).flatMap((loaded) => loaded.loaded.diagnostics)
+  ];
+}
+function buildEffectiveDiscovery(sources, scope) {
+  const configured = configuredAgentsForScope(sources, scope);
+  const agents = applySubagentMaxThinking(mergeAgentsForScope(scope, configured.user, configured.project, configured.builtin, configured.package).filter((agent) => agent.disabled !== true), configured.maxThinking);
+  return {
+    agents,
+    agentDiagnostics: discoveryDiagnostics(sources, scope),
+    projectAgentsDir: sources.projectAgentsDir,
+    cwd: sources.cwd,
+    scope,
+    directories: discoveryDirectories(sources, scope),
+    ...configured.modelScope !== undefined ? { modelScope: configured.modelScope } : {},
+    ...configured.maxThinking !== undefined ? { maxThinking: configured.maxThinking } : {}
+  };
+}
+function buildAllDiscovery(sources, includeChains, settingsScope) {
+  if (includeChains)
+    ensureDiscoveryChains(sources);
+  const configured = configuredAgentsForScope(sources, "both", settingsScope);
   const packageChainMap = new Map;
-  for (const dir of packageSubagentPaths.chains) {
-    const loaded = loadChainsFromDir(dir, "package");
-    packageChainDiagnostics.push(...loaded.diagnostics);
-    for (const chain of loaded.chains) {
-      if (!packageChainMap.has(chain.name))
-        packageChainMap.set(chain.name, chain);
-    }
+  const packageChainDiagnostics = [];
+  for (const chain of sources.packageChainLoaded ?? []) {
+    packageChainDiagnostics.push(...chain.loaded.diagnostics);
+    for (const definition of chain.loaded.chains)
+      if (!packageChainMap.has(definition.name))
+        packageChainMap.set(definition.name, definition);
   }
+  const projectChainMap = new Map;
   const projectChainDiagnostics = [];
-  for (const dir of projectChainDirs) {
-    const loaded = loadChainsFromDir(dir, "project");
-    projectChainDiagnostics.push(...loaded.diagnostics);
-    for (const chain of loaded.chains) {
-      chainMap.set(chain.name, chain);
-    }
+  for (const chain of sources.projectChainLoaded ?? []) {
+    projectChainDiagnostics.push(...chain.loaded.diagnostics);
+    for (const definition of chain.loaded.chains)
+      projectChainMap.set(definition.name, definition);
   }
-  const userChains = loadChainsFromDir(userChainDir, "user");
   const chains = [
     ...Array.from(packageChainMap.values()),
-    ...userChains.chains,
-    ...Array.from(chainMap.values())
+    ...sources.userChains?.chains ?? [],
+    ...Array.from(projectChainMap.values())
   ];
-  const chainDiagnostics = [
-    ...packageChainDiagnostics,
-    ...userChains.diagnostics,
-    ...projectChainDiagnostics
-  ];
-  const userDir = process.env.DM_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
-  return { builtin, package: packageAgents, user, project, chains, chainDiagnostics, userDir, projectDir, userChainDir, projectChainDir, userSettingsPath, projectSettingsPath };
+  return {
+    builtin: applySubagentMaxThinking(configured.builtin, configured.maxThinking),
+    package: applySubagentMaxThinking(configured.package, configured.maxThinking),
+    user: applySubagentMaxThinking(configured.user, configured.maxThinking),
+    project: applySubagentMaxThinking(configured.project, configured.maxThinking),
+    agentDiagnostics: [
+      ...sources.builtinLoaded.diagnostics,
+      ...sources.userLoaded.flatMap((loaded) => loaded.loaded.diagnostics),
+      ...sources.packageLoaded.flatMap((loaded) => loaded.loaded.diagnostics),
+      ...sources.projectLoaded.flatMap((loaded) => loaded.loaded.diagnostics)
+    ],
+    chains,
+    chainDiagnostics: [...packageChainDiagnostics, ...sources.userChains?.diagnostics ?? [], ...projectChainDiagnostics],
+    userDir: sources.userDir,
+    projectDir: sources.projectAgentsDir,
+    userChainDir: sources.userChainDir,
+    projectChainDir: sources.projectChainDir,
+    userSettingsPath: sources.userSettingsPath,
+    projectSettingsPath: sources.projectSettingsPath,
+    ...configured.maxThinking !== undefined ? { maxThinking: configured.maxThinking } : {}
+  };
+}
+export function discoverAgentSnapshot(cwd, scope, preferredModelProvider, options = {}) {
+  const includeChains = options.includeChains !== false;
+  const sources = getAgentDiscoverySources(cwd, preferredModelProvider, includeChains);
+  return { effective: buildEffectiveDiscovery(sources, scope), all: buildAllDiscovery(sources, includeChains, scope) };
+}
+function discoverAgentsUncached(cwd, scope, preferredModelProvider) {
+  const effectiveCwd = path.resolve(cwd);
+  const userDirOld = path.join(getAgentDir(), "agents");
+  const userDirNew = path.join(os.homedir(), ".agents");
+  const { readDirs: projectAgentDirs, candidateDirs: projectCandidateDirs, preferredDir: projectAgentsDir } = resolveNearestProjectAgentDirs(effectiveCwd);
+  const userSettingsPath = getUserAgentSettingsPath();
+  const projectSettingsPath = getProjectAgentSettingsPath(effectiveCwd);
+  const userSettings = selectProviderOverrides(scope === "project" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(userSettingsPath), preferredModelProvider);
+  const projectSettings = selectProviderOverrides(scope === "user" ? EMPTY_SUBAGENT_SETTINGS : readSubagentSettings(projectSettingsPath), preferredModelProvider);
+  const defaultProvider = resolveSubagentDefaultProvider(userSettings, projectSettings, projectSettingsPath);
+  const defaultModel = resolveSubagentDefaultModel(userSettings, projectSettings, userSettingsPath, projectSettingsPath, defaultProvider);
+  const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
+  const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
+  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
+  const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
+  const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: scope !== "project", includeProject: scope !== "user" });
+  const directories = [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 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);
+  const projectInspections = scope === "user" ? new Map : 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);
+  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;
+  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);
+  const agents = applySubagentMaxThinking(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, cwd: effectiveCwd, scope, directories, ...modelScope !== undefined ? { modelScope } : {}, ...maxThinking !== undefined ? { maxThinking } : {} };
+}
+export function discoverAgents(cwd, scope, preferredModelProvider) {
+  if (scope !== "both")
+    return discoverAgentsUncached(cwd, scope, preferredModelProvider);
+  const sources = getAgentDiscoverySources(cwd, preferredModelProvider);
+  return buildEffectiveDiscovery(sources, scope);
+}
+export function discoverAgentsAll(cwd, preferredModelProvider) {
+  return discoverAgentSnapshot(cwd, "both", preferredModelProvider).all;
 }