@duckmind/dm-linux-x64 0.65.5 → 0.65.7

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

@@ -6,6 +6,7 @@ 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 { expandHomePath } from "../shared/settings.js";
 import { KNOWN_FIELDS } from "./agent-serializer.js";
 import { parseChain, parseJsonChain } from "./chain-serializer.js";
 import { mergeAgentsForScope } from "./agent-selection.js";
@@ -18,6 +19,8 @@ import { parseMemoryFrontmatter } from "./agent-memory.js";
 import { validateAcceptanceInput } from "../runs/shared/acceptance.js";
 import { validatePermissionRules } from "../runs/shared/permissions.js";
 import { parseThinkingLevel } from "../shared/thinking-ceiling.js";
+import { assertJsonSchemaObject } from "../runs/shared/structured-output.js";
+import { normalizeCapabilityCeilingAllowedAgents } from "../runs/shared/capability-ceiling.js";
 export function defaultSystemPromptMode(name) {
   return name === "delegate" ? "append" : "replace";
 }
@@ -178,7 +181,7 @@ function getGlobalNpmRoot() {
     } catch {}
   }
   try {
-    cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
+    cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }).trim());
     return cachedGlobalNpmRoot;
   } catch {
     cachedGlobalNpmRoot = "";
@@ -273,7 +276,7 @@ function collectSettingsPackageRoots(settingsFile, baseDir) {
     return [];
   const roots = [];
   for (const entry of packages) {
-    const packageSource = typeof entry === "string" ? entry : typeof entry === "object" && entry !== null && typeof entry.source === "string" ? entry.source : undefined;
+    const packageSource = typeof entry === "string" ? entry : typeof entry === "object" && entry !== null && ("source" in entry) && typeof entry.source === "string" ? entry.source : undefined;
     if (!packageSource)
       continue;
     const packageRoot = resolveSettingsPackageRoot(packageSource, baseDir);
@@ -310,7 +313,7 @@ function collectPackageSubagentPaths(cwd, options = { includeUser: true, include
     packageRoots.push(...collectScopedSettingsRoots("user", path.join(agentDir, "settings.json"), agentDir).map((root) => ({ root, scope: "user" })));
   }
   if (options.includeUser) {
-    const globalRoot = getGlobalNpmRoot();
+    const globalRoot = options.globalNpmRoot === undefined ? getGlobalNpmRoot() : options.globalNpmRoot;
     if (globalRoot) {
       packageRoots.push(...collectPackageRootsFromNodeModules(globalRoot, watchPaths).map((root) => ({ root, scope: "user" })));
     }
@@ -371,14 +374,23 @@ function effectiveAgentMatch(matches) {
 }
 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);
+  const canonical = agents.filter((agent) => agent.name === raw);
+  if (canonical.length === 1)
+    return canonical[0] ? { agent: canonical[0] } : {};
+  if (canonical.length > 1) {
+    const effective = effectiveAgentMatch(canonical);
     if (effective.agent)
       return effective;
-    return { error: `Ambiguous agent name '${name}': ${exact.map((agent) => agent.name).join(", ")}` };
+    return { error: `Ambiguous agent name '${name}': ${canonical.map((agent) => agent.name).join(", ")}` };
+  }
+  const local = agents.filter((agent) => agent.localName === raw);
+  if (local.length === 1)
+    return local[0] ? { agent: local[0] } : {};
+  if (local.length > 1) {
+    const effective = effectiveAgentMatch(local);
+    if (effective.agent)
+      return effective;
+    return { error: `Ambiguous local agent name '${name}': ${local.map((agent) => agent.name).join(", ")}` };
   }
   const aliases = agents.filter((agent) => agent.aliases?.includes(raw));
   if (aliases.length === 1)
@@ -429,12 +441,12 @@ function arraysEqual(a, b) {
 function cloneOverrideBase(agent) {
   return {
     description: agent.description,
+    ...agent.machine !== undefined ? { machine: agent.machine } : {},
     ...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,
@@ -448,24 +460,25 @@ function cloneOverrideBase(agent) {
     ...agent.skills ? { skills: [...agent.skills] } : {},
     ...agent.skillPath ? { skillPath: [...agent.skillPath] } : {},
     ...agent.tools ? { tools: [...agent.tools] } : {},
+    ...agent.excludeTools ? { excludeTools: [...agent.excludeTools] } : {},
     ...agent.allowNestedSubagents !== undefined ? { allowNestedSubagents: agent.allowNestedSubagents } : {},
+    ...agent.allowedAgents !== undefined ? { allowedAgents: [...agent.allowedAgents] } : {},
     ...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.machine !== undefined ? { machine: override.machine } : {},
     ...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 } : {},
@@ -478,11 +491,12 @@ function cloneOverrideValue(override) {
     ...override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {},
     ...override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {},
     ...override.tools !== undefined ? { tools: Array.isArray(override.tools) ? [...override.tools] : override.tools } : {},
+    ...override.excludeTools !== undefined ? { excludeTools: override.excludeTools === false ? false : [...override.excludeTools] } : {},
     ...override.allowNestedSubagents !== undefined ? { allowNestedSubagents: override.allowNestedSubagents } : {},
+    ...override.allowedAgents !== undefined ? { allowedAgents: override.allowedAgents === false ? false : [...override.allowedAgents] } : {},
     ...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] } : {} } } : {}
   };
 }
@@ -491,8 +505,12 @@ function isProjectRootCandidate(dir) {
 }
 function findProjectRootCandidates(cwd) {
   const roots = [];
+  const windowsProfile = process.env.HOMEDRIVE && process.env.HOMEPATH ? `${process.env.HOMEDRIVE}${process.env.HOMEPATH}` : undefined;
+  const homeDirs = new Set([os.homedir(), process.env.HOME, process.env.USERPROFILE, windowsProfile].filter((value) => Boolean(value?.trim())).filter(isDirectory).map((value) => fs.realpathSync.native(value)));
   let currentDir = cwd;
   while (true) {
+    if (isDirectory(currentDir) && homeDirs.has(fs.realpathSync.native(currentDir)))
+      return roots;
     if (isProjectRootCandidate(currentDir))
       roots.push(currentDir);
     const parentDir = path.dirname(currentDir);
@@ -501,7 +519,7 @@ function findProjectRootCandidates(cwd) {
     currentDir = parentDir;
   }
 }
-function findNearestGitRoot(cwd) {
+export function findNearestGitRoot(cwd) {
   let currentDir = cwd;
   while (true) {
     if (fs.existsSync(path.join(currentDir, ".git")))
@@ -615,11 +633,26 @@ function parseToolsOverride(value, meta) {
   }
   throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid 'tools'; expected an array of strings, "inherit", or false.`);
 }
+function validateOptionalMachine(value, label) {
+  if (value === undefined || value === false)
+    return;
+  if (typeof value !== "string" || !value.trim())
+    throw new Error(label + " must be a non-empty string or false.");
+  const machine = value.trim();
+  if (machine.length > 128)
+    throw new Error(label + " must be 128 characters or fewer.");
+  if (/[\u0000-\u001f\u007f]/u.test(machine))
+    throw new Error(label + " contains control characters.");
+  return machine;
+}
 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;
+  if (Object.hasOwn(input, "fallbackModels")) {
+    throw new Error(`Builtin override '${name}' in '${filePath}' uses removed field 'fallbackModels'; configure one model instead.`);
+  }
   const override = {};
   if ("description" in input) {
     if (typeof input.description === "string" && input.description.trim()) {
@@ -708,13 +741,6 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
       throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'disabled'; expected a boolean.`);
     }
   }
-  if ("completionGuard" in input) {
-    if (typeof input.completionGuard === "boolean") {
-      override.completionGuard = input.completionGuard;
-    } else {
-      throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'completionGuard'; expected a boolean.`);
-    }
-  }
   if ("toolBudget" in input) {
     if (input.toolBudget === false) {
       override.toolBudget = false;
@@ -730,12 +756,16 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
     else
       throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'systemPrompt'; expected a string.`);
   }
+  if (input.machine === false)
+    override.machine = false;
+  else {
+    const machine = validateOptionalMachine(input.machine, `Builtin override '${name}' in '${filePath}' field 'machine'`);
+    if (machine !== undefined)
+      override.machine = machine;
+  }
   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;
@@ -750,12 +780,18 @@ function parseBuiltinOverrideEntry(name, value, filePath) {
   const tools = parseToolsOverride(input.tools, { filePath, name });
   if (tools !== undefined)
     override.tools = tools;
+  const excludeTools = parseOverrideStringArrayOrFalse(input.excludeTools, { filePath, name, field: "excludeTools" });
+  if (excludeTools !== undefined)
+    override.excludeTools = excludeTools;
   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 allowedAgents = parseOverrideStringArrayOrFalse(input.allowedAgents, { filePath, name, field: "allowedAgents" });
+  if (allowedAgents !== undefined)
+    override.allowedAgents = allowedAgents === false ? false : normalizeCapabilityCeilingAllowedAgents(allowedAgents);
   const extensions = parseOverrideStringArrayOrFalse(input.extensions, { filePath, name, field: "extensions" });
   if (extensions !== undefined)
     override.extensions = extensions;
@@ -830,6 +866,27 @@ function readSubagentSettings(filePath) {
     }
     defaultExtensions = subagentsObject.defaultExtensions.map((item) => item.trim());
   }
+  let defaultSubagentOnlyExtensions;
+  if ("defaultSubagentOnlyExtensions" in subagentsObject) {
+    if (!Array.isArray(subagentsObject.defaultSubagentOnlyExtensions) || subagentsObject.defaultSubagentOnlyExtensions.some((item) => typeof item !== "string" || !item.trim())) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultSubagentOnlyExtensions'; expected an array of non-empty strings.`);
+    }
+    defaultSubagentOnlyExtensions = subagentsObject.defaultSubagentOnlyExtensions.map((item) => item.trim());
+  }
+  let agentScanDirs;
+  if ("agentScanDirs" in subagentsObject) {
+    if (!Array.isArray(subagentsObject.agentScanDirs) || subagentsObject.agentScanDirs.some((item) => typeof item !== "string" || !item.trim())) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'agentScanDirs'; expected an array of non-empty strings.`);
+    }
+    agentScanDirs = subagentsObject.agentScanDirs.map((item) => item.trim());
+  }
+  let agentExcludeDirs;
+  if ("agentExcludeDirs" in subagentsObject) {
+    if (!Array.isArray(subagentsObject.agentExcludeDirs) || subagentsObject.agentExcludeDirs.some((item) => typeof item !== "string" || !item.trim())) {
+      throw new Error(`Subagent settings in '${filePath}' have invalid 'agentExcludeDirs'; expected an array of non-empty strings.`);
+    }
+    agentExcludeDirs = subagentsObject.agentExcludeDirs.map((item) => item.trim());
+  }
   const modelScope = parseModelScopeConfig(subagentsObject.modelScope, { filePath });
   const parsed = {};
   const providerOverrides = {};
@@ -843,6 +900,9 @@ function readSubagentSettings(filePath) {
     ...defaultThinking !== undefined ? { defaultThinking } : {},
     ...maxThinking !== undefined ? { maxThinking } : {},
     ...defaultExtensions !== undefined ? { defaultExtensions } : {},
+    ...defaultSubagentOnlyExtensions !== undefined ? { defaultSubagentOnlyExtensions } : {},
+    ...agentScanDirs !== undefined ? { agentScanDirs } : {},
+    ...agentExcludeDirs !== undefined ? { agentExcludeDirs } : {},
     ...disableBuiltins !== undefined ? { disableBuiltins } : {},
     ...disableThinking !== undefined ? { disableThinking } : {},
     ...modelScope !== undefined ? { modelScope } : {}
@@ -959,8 +1019,26 @@ function applySubagentDefaultExtensions(agents, defaultExtensions) {
     return next;
   });
 }
-function applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions) {
-  return applySubagentDefaultExtensions(applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking), defaultExtensions);
+function resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, projectSettingsPath) {
+  if (projectSettingsPath && projectSettings.defaultSubagentOnlyExtensions !== undefined)
+    return projectSettings.defaultSubagentOnlyExtensions;
+  return userSettings.defaultSubagentOnlyExtensions;
+}
+function applySubagentDefaultSubagentOnlyExtensions(agents, defaultSubagentOnlyExtensions) {
+  if (defaultSubagentOnlyExtensions === undefined)
+    return agents;
+  return agents.map((agent) => {
+    if (agent.subagentOnlyExtensions !== undefined)
+      return agent;
+    const next = { ...agent, subagentOnlyExtensions: [...defaultSubagentOnlyExtensions] };
+    const frontmatterFields = agentFrontmatterFields.get(agent);
+    if (frontmatterFields)
+      agentFrontmatterFields.set(next, frontmatterFields);
+    return next;
+  });
+}
+function applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions) {
+  return applySubagentDefaultSubagentOnlyExtensions(applySubagentDefaultExtensions(applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking), defaultExtensions), defaultSubagentOnlyExtensions);
 }
 function applyToolsOverride(target, toolsOverride) {
   if (toolsOverride === "inherit") {
@@ -979,12 +1057,28 @@ function applyToolsOverride(target, toolsOverride) {
     target.mcpDirectTools = mcpDirectTools;
 }
 function applyBuiltinOverride(agent, override, meta) {
+  const overrideInfo = {
+    ...meta,
+    base: agent.override?.base ?? cloneOverrideBase(agent),
+    fields: [...new Set([...agent.override?.fields ?? [], ...Object.keys(override)])].sort(),
+    fieldScopes: Object.fromEntries(Object.entries({ ...agent.override?.fieldScopes ?? {} }).map(([field, scopes]) => [field, [...scopes]]))
+  };
+  for (const field of Object.keys(override)) {
+    const scopes = overrideInfo.fieldScopes[field] ?? [];
+    overrideInfo.fieldScopes[field] = [...new Set([...scopes, meta.scope])].sort();
+  }
   const next = {
     ...agent,
-    override: { ...meta, base: cloneOverrideBase(agent) }
+    override: overrideInfo
   };
   if (override.description !== undefined)
     next.description = override.description;
+  if (override.machine !== undefined) {
+    if (override.machine === false)
+      delete next.machine;
+    else
+      next.machine = override.machine;
+  }
   if (override.output !== undefined) {
     if (override.output === false)
       delete next.output;
@@ -1012,12 +1106,6 @@ function applyBuiltinOverride(agent, override, meta) {
     else
       next.modelProvider = override.defaultProvider;
   }
-  if (override.fallbackModels !== undefined) {
-    if (override.fallbackModels === false)
-      delete next.fallbackModels;
-    else
-      next.fallbackModels = [...override.fallbackModels];
-  }
   if (override.fast !== undefined)
     next.fast = override.fast;
   if (override.thinking !== undefined) {
@@ -1058,8 +1146,20 @@ function applyBuiltinOverride(agent, override, meta) {
   }
   if (override.tools !== undefined)
     applyToolsOverride(next, override.tools);
+  if (override.excludeTools !== undefined) {
+    if (override.excludeTools === false)
+      delete next.excludeTools;
+    else
+      next.excludeTools = [...override.excludeTools];
+  }
   if (override.allowNestedSubagents !== undefined)
     next.allowNestedSubagents = override.allowNestedSubagents;
+  if (override.allowedAgents !== undefined) {
+    if (override.allowedAgents === false)
+      delete next.allowedAgents;
+    else
+      next.allowedAgents = [...override.allowedAgents];
+  }
   if (override.extensions !== undefined) {
     if (override.extensions === false)
       delete next.extensions;
@@ -1078,8 +1178,6 @@ function applyBuiltinOverride(agent, override, meta) {
     else
       next.mutationTools = [...override.mutationTools];
   }
-  if (override.completionGuard !== undefined)
-    next.completionGuard = override.completionGuard;
   if (override.toolBudget !== undefined) {
     if (override.toolBudget === false)
       delete next.toolBudget;
@@ -1123,111 +1221,8 @@ function applyBuiltinOverrides(builtinAgents, userSettings, projectSettings, use
     return applyGlobalThinking(agent, false);
   });
 }
-export function agentHasFrontmatterField(agent, ...fields) {
-  const frontmatterFields = agentFrontmatterFields.get(agent);
-  return frontmatterFields ? fields.some((field) => frontmatterFields.has(field)) : false;
-}
 function applyCustomAgentOverride(agent, override, meta) {
-  let next;
-  let anyFilled = false;
-  const mutable = () => {
-    next ??= { ...agent };
-    return next;
-  };
-  const fill = (field, frontmatterFields, value) => {
-    if (agentHasFrontmatterField(agent, ...frontmatterFields))
-      return;
-    const target = mutable();
-    if (value === undefined)
-      delete target[field];
-    else
-      target[field] = value;
-    anyFilled = true;
-  };
-  if (override.description !== undefined) {
-    mutable().description = override.description;
-    anyFilled = true;
-  }
-  if (override.output !== undefined) {
-    fill("output", ["output"], override.output === false ? undefined : override.output);
-  }
-  if (override.outputMode !== undefined) {
-    fill("outputMode", ["outputMode"], override.outputMode);
-  }
-  if (override.defaultReads !== undefined) {
-    fill("defaultReads", ["defaultReads"], override.defaultReads === false ? undefined : [...override.defaultReads]);
-  }
-  if (override.model !== undefined && !agentHasFrontmatterField(agent, "model")) {
-    const target = mutable();
-    if (override.model === false)
-      delete target.model;
-    else
-      target.model = override.model;
-    delete target.modelSource;
-    anyFilled = true;
-  }
-  if (override.defaultProvider !== undefined) {
-    fill("modelProvider", ["modelProvider", "defaultProvider"], override.defaultProvider === false ? undefined : override.defaultProvider);
-  }
-  if (override.fallbackModels !== undefined) {
-    fill("fallbackModels", ["fallbackModels"], override.fallbackModels === false ? undefined : [...override.fallbackModels]);
-  }
-  if (override.fast !== undefined) {
-    fill("fast", ["fast"], override.fast);
-  }
-  if (override.thinking !== undefined) {
-    fill("thinking", ["thinking"], override.thinking === false ? undefined : override.thinking);
-  }
-  if (override.systemPromptMode !== undefined) {
-    fill("systemPromptMode", ["systemPromptMode"], override.systemPromptMode);
-  }
-  if (override.inheritProjectContext !== undefined) {
-    fill("inheritProjectContext", ["inheritProjectContext"], override.inheritProjectContext);
-  }
-  if (override.inheritGlobalContext !== undefined) {
-    fill("inheritGlobalContext", ["inheritGlobalContext"], override.inheritGlobalContext);
-  }
-  if (override.inheritSkills !== undefined) {
-    fill("inheritSkills", ["inheritSkills"], override.inheritSkills);
-  }
-  if (override.defaultContext !== undefined) {
-    fill("defaultContext", ["defaultContext"], override.defaultContext === false ? undefined : override.defaultContext);
-  }
-  if (override.acceptanceRole !== undefined) {
-    fill("acceptanceRole", ["acceptanceRole"], override.acceptanceRole === false ? undefined : override.acceptanceRole);
-  }
-  if (override.disabled !== undefined) {
-    mutable().disabled = override.disabled;
-    anyFilled = true;
-  }
-  if (override.skills !== undefined) {
-    fill("skills", ["skill", "skills"], override.skills === false ? undefined : [...override.skills]);
-  }
-  if (override.tools !== undefined && !agentHasFrontmatterField(agent, "tools")) {
-    applyToolsOverride(mutable(), override.tools);
-    anyFilled = true;
-  }
-  if (override.allowNestedSubagents !== undefined) {
-    fill("allowNestedSubagents", ["allowNestedSubagents"], override.allowNestedSubagents);
-  }
-  if (override.extensions !== undefined) {
-    fill("extensions", ["extensions"], override.extensions === false ? undefined : [...override.extensions]);
-  }
-  if (override.subagentOnlyExtensions !== undefined) {
-    fill("subagentOnlyExtensions", ["subagentOnlyExtensions"], override.subagentOnlyExtensions === false ? undefined : [...override.subagentOnlyExtensions]);
-  }
-  if (override.mutationTools !== undefined) {
-    fill("mutationTools", ["mutationTools"], override.mutationTools === false ? undefined : [...override.mutationTools]);
-  }
-  if (override.completionGuard !== undefined) {
-    fill("completionGuard", ["completionGuard"], override.completionGuard);
-  }
-  if (override.toolBudget !== undefined) {
-    fill("toolBudget", ["toolBudget"], override.toolBudget === false ? undefined : override.toolBudget);
-  }
-  if (!anyFilled || !next)
-    return agent;
-  next.override = { ...meta, base: agent.override?.base ?? cloneOverrideBase(agent) };
+  const next = applyBuiltinOverride(agent, override, meta);
   const frontmatterFields = agentFrontmatterFields.get(agent);
   if (frontmatterFields)
     agentFrontmatterFields.set(next, frontmatterFields);
@@ -1244,8 +1239,38 @@ function applyCustomAgentOverrides(agents, userSettings, projectSettings, userSe
     return withUserOverride;
   });
 }
+function runtimeAgentOverrides(settings) {
+  const overrides = {};
+  for (const [name, override] of Object.entries(settings.overrides)) {
+    const narrowed = {};
+    if (override.model !== undefined)
+      narrowed.model = override.model;
+    if (override.defaultProvider !== undefined)
+      narrowed.defaultProvider = override.defaultProvider;
+    if (override.fast !== undefined)
+      narrowed.fast = override.fast;
+    if (override.thinking !== undefined)
+      narrowed.thinking = override.thinking;
+    if (Object.keys(narrowed).length > 0)
+      overrides[name] = narrowed;
+  }
+  return { ...settings, overrides };
+}
+export function applyRuntimeAgentSettings(agents, context) {
+  if (agents.length === 0)
+    return agents;
+  const sources = getAgentDiscoverySources(context.cwd, context.preferredModelProvider);
+  const { user, project } = settingsForScope(sources, context.scope);
+  const defaultProvider = resolveSubagentDefaultProvider(user, project, sources.projectSettingsPath);
+  const defaultModel = resolveSubagentDefaultModel(user, project, sources.userSettingsPath, sources.projectSettingsPath, defaultProvider);
+  const defaultThinking = resolveSubagentDefaultThinking(user, project, sources.projectSettingsPath);
+  const withDefaults = applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking);
+  return applyCustomAgentOverrides(withDefaults, runtimeAgentOverrides(user), runtimeAgentOverrides(project), sources.userSettingsPath, sources.projectSettingsPath);
+}
 export function buildBuiltinOverrideConfig(base, draft) {
   const override = {};
+  if (draft.machine !== base.machine)
+    override.machine = draft.machine ?? false;
   if (draft.description !== undefined) {
     const description = draft.description.trim();
     if (description && description !== base.description)
@@ -1261,8 +1286,6 @@ export function buildBuiltinOverrideConfig(base, draft) {
     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)
@@ -1289,6 +1312,8 @@ export function buildBuiltinOverrideConfig(base, draft) {
   const draftTools = joinToolList(draft);
   if (!arraysEqual(draftTools, baseTools))
     override.tools = draftTools ? [...draftTools] : false;
+  if (!arraysEqual(draft.excludeTools, base.excludeTools))
+    override.excludeTools = draft.excludeTools ? [...draft.excludeTools] : false;
   if (draft.allowNestedSubagents !== base.allowNestedSubagents)
     override.allowNestedSubagents = draft.allowNestedSubagents === true;
   if (!arraysEqual(draft.extensions, base.extensions))
@@ -1298,9 +1323,6 @@ export function buildBuiltinOverrideConfig(base, draft) {
   }
   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;
-  }
   if (JSON.stringify(draft.toolBudget) !== JSON.stringify(base.toolBudget))
     override.toolBudget = draft.toolBudget ?? false;
   return Object.keys(override).length > 0 ? override : undefined;
@@ -1318,24 +1340,30 @@ export function saveBuiltinAgentOverride(cwd, name, scope, override) {
   writeSettingsFile(filePath, settings);
   return filePath;
 }
-export function removeBuiltinAgentOverride(cwd, name, scope) {
+export function removeBuiltinAgentOverride(cwd, name, scope, options) {
   const filePath = scope === "project" ? getProjectAgentSettingsPath(cwd) : getUserAgentSettingsPath();
   if (!filePath)
     throw new Error("Project override is not available here. No project config root was found.");
   if (!fs.existsSync(filePath))
-    return { path: filePath, removed: false };
+    return { path: filePath, removed: false, machinePreserved: false };
   const settings = readSettingsFileStrict(filePath);
   const subagents = settings.subagents;
   if (!subagents || typeof subagents !== "object" || Array.isArray(subagents))
-    return { path: filePath, removed: false };
+    return { path: filePath, removed: false, machinePreserved: false };
   const nextSubagents = { ...subagents };
   const agentOverrides = nextSubagents.agentOverrides;
   if (!agentOverrides || typeof agentOverrides !== "object" || Array.isArray(agentOverrides))
-    return { path: filePath, removed: false };
+    return { path: filePath, removed: false, machinePreserved: false };
   const nextOverrides = { ...agentOverrides };
+  const current = nextOverrides[name];
   if (!Object.prototype.hasOwnProperty.call(nextOverrides, name))
-    return { path: filePath, removed: false };
-  delete nextOverrides[name];
+    return { path: filePath, removed: false, machinePreserved: false };
+  const configuredMachine = current && typeof current === "object" && !Array.isArray(current) ? current.machine : undefined;
+  const machine = configuredMachine === false || typeof configuredMachine === "string" && configuredMachine.trim() ? configuredMachine : undefined;
+  if (options?.preserveMachine && machine !== undefined)
+    nextOverrides[name] = { machine };
+  else
+    delete nextOverrides[name];
   if (Object.keys(nextOverrides).length > 0)
     nextSubagents.agentOverrides = nextOverrides;
   else
@@ -1345,7 +1373,7 @@ export function removeBuiltinAgentOverride(cwd, name, scope) {
   else
     delete settings.subagents;
   writeSettingsFile(filePath, settings);
-  return { path: filePath, removed: true };
+  return { path: filePath, removed: true, machinePreserved: options?.preserveMachine === true && machine !== undefined };
 }
 export function mergeBuiltinAgentOverride(cwd, name, scope, fields) {
   const filePath = scope === "project" ? getProjectAgentSettingsPath(cwd) : getUserAgentSettingsPath();
@@ -1475,8 +1503,10 @@ const DEFAULT_AGENT_DEFINITION_INSPECTION_FS = {
   statSync: fs.statSync,
   readdirSync: (dir) => fs.readdirSync(dir, { withFileTypes: true })
 };
-export function inspectAgentDefinitionDirectory(dir, operations = DEFAULT_AGENT_DEFINITION_INSPECTION_FS) {
+export function inspectAgentDefinitionDirectory(dir, operations = DEFAULT_AGENT_DEFINITION_INSPECTION_FS, isExcluded = () => false) {
   const root = path.resolve(dir);
+  if (isExcluded(root))
+    return rememberAgentDefinitionInspection({ files: [], state: "empty" }, []);
   try {
     if (!operations.existsSync(root))
       return rememberAgentDefinitionInspection({ files: [], state: "absent" }, [root]);
@@ -1510,6 +1540,8 @@ export function inspectAgentDefinitionDirectory(dir, operations = DEFAULT_AGENT_
     }
     for (const entry of entries) {
       const filePath = path.join(current, entry.name);
+      if (isExcluded(filePath))
+        continue;
       let isDirectory = entry.isDirectory();
       if (entry.isSymbolicLink()) {
         try {
@@ -1618,7 +1650,7 @@ function parseAgentRunnerFrontmatter(raw, agentName) {
 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);
+  const unsupported = ["tools", "excludeTools", "allowNestedSubagents", "allowedAgents", "model", "thinking", "extensions", "subagentOnlyExtensions", "mutationTools", "maxSubagentDepth", "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(", ")}.`);
   }
@@ -1685,10 +1717,22 @@ function loadAgentsFromDefinitionFiles(files, source, discoveryPriority, package
       runtimeName = buildRuntimeName(localName, packageName);
       const runner = parseAgentRunnerFrontmatter(frontmatter.runner, localName);
       validateExternalRunnerProfile(frontmatter, localName, runner);
+      let advertise;
+      if (frontmatter.advertise !== undefined) {
+        if (frontmatter.advertise === "true")
+          advertise = true;
+        else if (frontmatter.advertise === "false")
+          advertise = false;
+        else
+          throw new Error(`Agent '${localName}' has invalid advertise frontmatter; expected true or false.`);
+      }
       const rawTools = parseFrontmatterList(frontmatter.tools);
       const parsedTools = splitToolList(rawTools);
       const tools = parsedTools.tools ?? [];
       const mcpDirectTools = parsedTools.mcpDirectTools ?? [];
+      const excludeTools = parseFrontmatterList(frontmatter.excludeTools);
+      const parsedAllowedAgents = parseFrontmatterList(frontmatter.allowedAgents);
+      const allowedAgents = parsedAllowedAgents === undefined ? undefined : normalizeCapabilityCeilingAllowedAgents(parsedAllowedAgents);
       const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
       const aliases = normalizeAgentAliases(parseFrontmatterList(frontmatter.aliases ?? frontmatter.alias), runtimeName);
       const profileError = validateCodeOwnedProfileRunner({ name: runtimeName, localName, aliases, runner });
@@ -1697,7 +1741,8 @@ function loadAgentsFromDefinitionFiles(files, source, discoveryPriority, package
       const skillStr = frontmatter.skill || frontmatter.skills;
       const skills = parseFrontmatterList(skillStr);
       const skillPath = parseFrontmatterList(frontmatter.skillPath);
-      const fallbackModels = parseFrontmatterList(frontmatter.fallbackModels);
+      if (frontmatter.fallbackModels !== undefined)
+        throw new Error(`Agent '${filePath}' uses removed frontmatter field 'fallbackModels'. Configure one model instead.`);
       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";
@@ -1783,9 +1828,15 @@ function loadAgentsFromDefinitionFiles(files, source, discoveryPriority, package
         }
         toolBudget = parsed;
       }
-      const completionGuard = frontmatter.completionGuard === "false" ? false : frontmatter.completionGuard === "true" ? true : undefined;
+      let outputSchema;
+      if (frontmatter.outputSchema !== undefined && frontmatter.outputSchema.trim()) {
+        const parsed = JSON.parse(frontmatter.outputSchema);
+        assertJsonSchemaObject(parsed, `Agent '${localName}' outputSchema`);
+        outputSchema = parsed;
+      }
       const maxSubagentDepth = Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0 ? parsedMaxSubagentDepth : undefined;
       const memory = parseMemoryFrontmatter(frontmatter.memory);
+      const machine = validateOptionalMachine(frontmatter.machine, `Agent '${runtimeName}' frontmatter 'machine'`);
       const agent = {
         name: runtimeName,
         ...runner !== undefined ? { runner } : {},
@@ -1795,12 +1846,14 @@ function loadAgentsFromDefinitionFiles(files, source, discoveryPriority, package
         ...packageSource?.packageVersion ? { packageSourceVersion: packageSource.packageVersion } : {},
         ...packageSource?.packageRoot ? { packageSourceRoot: packageSource.packageRoot } : {},
         description: frontmatter.description,
+        ...advertise !== undefined ? { advertise } : {},
         ...aliases !== undefined ? { aliases } : {},
         ...rawTools !== undefined ? { tools } : {},
+        ...excludeTools !== undefined ? { excludeTools } : {},
         ...allowNestedSubagents !== undefined ? { allowNestedSubagents } : {},
+        ...allowedAgents !== undefined ? { allowedAgents } : {},
         ...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,
@@ -1822,13 +1875,14 @@ function loadAgentsFromDefinitionFiles(files, source, discoveryPriority, package
         ...extensions !== undefined ? { extensions } : {},
         ...subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions } : {},
         ...mutationTools?.length ? { mutationTools } : {},
+        ...machine !== undefined ? { machine } : {},
         ...frontmatter.output !== undefined ? { output: frontmatter.output } : {},
         ...outputMode !== undefined ? { outputMode } : {},
+        ...outputSchema !== undefined ? { outputSchema } : {},
         ...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 } : {},
@@ -1919,10 +1973,90 @@ function extraUserAgentDirs() {
     return [];
   return raw.split(path.delimiter).map((dir) => dir.trim()).filter((dir) => dir.length > 0);
 }
+function readConfiguredAgentScanDirs(filePath, key = "agentScanDirs") {
+  if (!filePath)
+    return [];
+  try {
+    const settings = readSettingsFileStrict(filePath);
+    const subagents = settings.subagents;
+    if (!subagents || typeof subagents !== "object" || Array.isArray(subagents))
+      return [];
+    const dirs = subagents[key];
+    return Array.isArray(dirs) ? dirs.filter((dir) => typeof dir === "string" && dir.trim().length > 0) : [];
+  } catch {
+    return [];
+  }
+}
+function canonicalAgentPath(filePath) {
+  const resolved = path.resolve(filePath);
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    const parent = path.dirname(resolved);
+    return parent === resolved ? resolved : path.join(canonicalAgentPath(parent), path.basename(resolved));
+  }
+}
+function agentExclusionRoots(userSettingsPath, projectSettingsPath) {
+  return [userSettingsPath, projectSettingsPath].flatMap((settingsPath) => settingsPath ? readConfiguredAgentScanDirs(settingsPath, "agentExcludeDirs").map((entry) => {
+    const resolved = path.resolve(path.dirname(settingsPath), expandHomePath(entry.trim()).replace(/[\\/]+/g, path.sep));
+    return { resolved, real: canonicalAgentPath(resolved) };
+  }) : []);
+}
+function agentExclusions(roots) {
+  return (filePath) => {
+    if (!roots.length)
+      return false;
+    if (roots.some((root) => isPathWithin(root.resolved, filePath)))
+      return true;
+    const real = canonicalAgentPath(filePath);
+    return roots.some((root) => isPathWithin(root.real, real));
+  };
+}
+function expandAgentScanDirPattern(pattern, isExcluded) {
+  const expanded = expandHomePath(pattern.trim()).replace(/[\\/]+/g, path.sep);
+  if (!expanded)
+    return { dirs: [], watchPaths: [] };
+  const wildcardMatches = [...expanded.matchAll(/\*/g)];
+  if (wildcardMatches.length === 0) {
+    const dir = path.resolve(expanded);
+    return { dirs: !isExcluded(dir) && fs.existsSync(dir) ? [dir] : [], watchPaths: [dir] };
+  }
+  const parts = expanded.split(path.sep);
+  const wildcardIndex = parts.findIndex((part) => part.includes("*"));
+  if (wildcardMatches.length !== 1 || wildcardIndex === -1 || parts[wildcardIndex] !== "*")
+    return { dirs: [], watchPaths: [] };
+  const base = path.resolve(parts.slice(0, wildcardIndex).join(path.sep) || path.sep);
+  if (isExcluded(base))
+    return { dirs: [], watchPaths: [base] };
+  const rest = parts.slice(wildcardIndex + 1);
+  let entries;
+  try {
+    entries = fs.readdirSync(base, { withFileTypes: true });
+  } catch {
+    return { dirs: [], watchPaths: [base] };
+  }
+  const candidateDirs = entries.filter((entry) => entry.isDirectory()).map((entry) => path.join(base, entry.name, ...rest));
+  return {
+    dirs: candidateDirs.filter((dir) => !isExcluded(dir) && fs.existsSync(dir)),
+    watchPaths: [base, ...candidateDirs]
+  };
+}
+function settingsAgentScanDirs(entries, isExcluded) {
+  const dirs = new Set;
+  const watchPaths = new Set;
+  for (const entry of entries) {
+    const expanded = expandAgentScanDirPattern(entry, isExcluded);
+    for (const dir of expanded.dirs)
+      dirs.add(dir);
+    for (const watchPath of expanded.watchPaths)
+      watchPaths.add(watchPath);
+  }
+  return { dirs: [...dirs], watchPaths: [...watchPaths] };
+}
 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);
+  return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
 }
 function addDirectoryWatchPaths(paths, root, files, directories = []) {
   const resolvedRoot = path.resolve(root);
@@ -1942,11 +2076,11 @@ function addDirectoryWatchPaths(paths, root, files, directories = []) {
     }
   }
 }
-function watchPathSignature(filePath) {
+function watchPathSignature(filePath, isExcluded) {
   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("|");
+      const entries = fs.readdirSync(filePath, { withFileTypes: true }).filter((entry) => !isExcluded || !isExcluded(path.join(filePath, entry.name))).sort((left, right) => left.name.localeCompare(right.name)).map((entry) => `${entry.name}:${entry.isDirectory() ? "d" : entry.isSymbolicLink() ? isExcluded ? `l:${canonicalAgentPath(path.join(filePath, entry.name))}` : "l" : "f"}`).join("|");
       return `directory:${entries}`;
     }
     return `file:${stat.size}:${stat.mtimeMs}`;
@@ -1954,14 +2088,22 @@ function watchPathSignature(filePath) {
     return "missing";
   }
 }
-function discoveryFingerprint(paths) {
-  return [...new Set(paths)].sort((left, right) => left.localeCompare(right)).map((filePath) => `${filePath}:${watchPathSignature(filePath)}`).join(`
+function discoveryFingerprint(sources) {
+  const exclusionIdentity = JSON.stringify(sources.exclusionRoots.map((root) => ({ resolved: root.resolved, real: canonicalAgentPath(root.resolved) })));
+  if (exclusionIdentity !== JSON.stringify(sources.exclusionRoots))
+    return exclusionIdentity;
+  const rootIdentities = JSON.stringify(sources.identityWatchPaths.map((root) => [root, canonicalAgentPath(root)]));
+  const unfilteredPaths = new Set([...sources.packageSubagentPaths.watchPaths, ...sources.chainWatchPaths ?? []]);
+  return exclusionIdentity + `
+` + rootIdentities + `
+` + [...new Set([...sources.watchPaths, ...unfilteredPaths])].filter((filePath) => unfilteredPaths.has(filePath) || filePath === sources.userSettingsPath || filePath === sources.projectSettingsPath || !sources.isExcluded(filePath)).sort((left, right) => left.localeCompare(right)).map((filePath) => `${filePath}:${watchPathSignature(filePath, sources.exclusionRoots.length && !unfilteredPaths.has(filePath) ? sources.isExcluded : undefined)}`).join(`
 `);
 }
-function discoveryCacheKey(cwd, preferredModelProvider) {
+function discoveryCacheKey(cwd, preferredModelProvider, globalNpmRoot) {
   return JSON.stringify([
     path.resolve(cwd),
     preferredModelProvider ?? null,
+    globalNpmRoot === undefined ? ["default"] : ["override", globalNpmRoot],
     getProjectConfigDir(path.resolve(cwd)),
     getAgentDir(),
     os.homedir(),
@@ -1989,7 +2131,7 @@ function packageEntryIncluded(scope, packageScopes) {
     return true;
   return packageScopes.has(scope);
 }
-function buildAgentDiscoverySources(cwd, preferredModelProvider) {
+function buildAgentDiscoverySources(cwd, preferredModelProvider, globalNpmRoot) {
   const effectiveCwd = path.resolve(cwd);
   const userDirOld = path.join(getAgentDir(), "agents");
   const userDirNew = path.join(os.homedir(), ".agents");
@@ -1998,19 +2140,23 @@ function buildAgentDiscoverySources(cwd, preferredModelProvider) {
   const { readDirs: projectChainDirs, preferredDir: projectChainDir } = resolveNearestProjectChainDirs(effectiveCwd);
   const userSettingsPath = getUserAgentSettingsPath();
   const projectSettingsPath = getProjectAgentSettingsPath(effectiveCwd);
-  const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd);
+  const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: true, includeProject: true, globalNpmRoot });
+  const exclusionRoots = agentExclusionRoots(userSettingsPath, projectSettingsPath);
+  const isExcluded = agentExclusions(exclusionRoots);
+  const userScanDirs = settingsAgentScanDirs(readConfiguredAgentScanDirs(userSettingsPath), isExcluded);
+  const projectScanDirs = settingsAgentScanDirs(readConfiguredAgentScanDirs(projectSettingsPath), isExcluded);
   const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
-  const userLoaded = [...extraUserAgentDirs(), userDirOld, userDirNew].map((dir, discoveryPriority) => {
-    const inspection = inspectAgentDefinitionDirectory(dir);
+  const userLoaded = [...extraUserAgentDirs(), ...userScanDirs.dirs, userDirOld, userDirNew].filter((dir) => !isExcluded(dir)).map((dir, discoveryPriority) => {
+    const inspection = inspectAgentDefinitionDirectory(dir, undefined, isExcluded);
     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 projectInspections = new Map(projectCandidateDirs.filter((dir) => !isExcluded(dir)).map((dir) => [dir, inspectAgentDefinitionDirectory(dir, undefined, isExcluded)]));
+  const projectLoaded = [...projectScanDirs.dirs, ...projectAgentDirs].filter((dir) => !isExcluded(dir)).map((dir, discoveryPriority) => {
+    const inspection = projectInspections.get(dir) ?? inspectAgentDefinitionDirectory(dir, undefined, isExcluded);
+    return { dir, inspection, loaded: loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : discoveryPriority, undefined, inspection) };
   });
-  const packageLoaded = packageSubagentPaths.agents.map((entry, index) => {
-    const inspection = inspectAgentDefinitionDirectory(entry.dir);
+  const packageLoaded = packageSubagentPaths.agents.filter((entry) => !isExcluded(entry.dir)).map((entry, index) => {
+    const inspection = inspectAgentDefinitionDirectory(entry.dir, undefined, isExcluded);
     return { dir: entry.dir, inspection, packageEntry: entry, loaded: loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry, inspection) };
   });
   const watchPaths = new Set([
@@ -2018,6 +2164,8 @@ function buildAgentDiscoverySources(cwd, preferredModelProvider) {
     ...projectSettingsPath ? [projectSettingsPath] : [],
     ...projectDiscoveryWatchPaths(effectiveCwd),
     ...findProjectRootCandidates(effectiveCwd).map((root) => path.join(getProjectConfigDir(root), "settings.json")),
+    ...userScanDirs.watchPaths,
+    ...projectScanDirs.watchPaths,
     ...packageSubagentPaths.watchPaths
   ]);
   for (const directory of userLoaded)
@@ -2026,6 +2174,8 @@ function buildAgentDiscoverySources(cwd, preferredModelProvider) {
     const inspection = projectInspections.get(dir);
     addDirectoryWatchPaths(watchPaths, dir, inspection?.files ?? [], inspection ? inspectedAgentDefinitionDirectories(inspection, dir) : []);
   }
+  for (const directory of projectLoaded)
+    addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
   for (const directory of packageLoaded)
     addDirectoryWatchPaths(watchPaths, directory.dir, directory.inspection.files, inspectedAgentDefinitionDirectories(directory.inspection, directory.dir));
   const userDir = process.env.DM_CODING_AGENT_DIR ? userDirOld : fs.existsSync(userDirNew) ? userDirNew : userDirOld;
@@ -2037,7 +2187,7 @@ function buildAgentDiscoverySources(cwd, preferredModelProvider) {
     userDirNew,
     userChainDir,
     projectAgentDirs,
-    projectCandidateDirs,
+    projectCandidateDirs: projectCandidateDirs.filter((dir) => !isExcluded(dir)),
     projectAgentsDir,
     projectChainDirs,
     projectChainDir,
@@ -2049,7 +2199,18 @@ function buildAgentDiscoverySources(cwd, preferredModelProvider) {
     projectLoaded,
     projectInspections,
     packageLoaded,
-    watchPaths: [...watchPaths]
+    isExcluded,
+    exclusionRoots,
+    identityWatchPaths: [...new Set([
+      ...userScanDirs.watchPaths,
+      ...projectScanDirs.watchPaths,
+      ...extraUserAgentDirs(),
+      userDirOld,
+      userDirNew,
+      ...projectCandidateDirs,
+      ...packageSubagentPaths.agents.map((entry) => entry.dir)
+    ])].filter((dir) => !exclusionRoots.some((root) => isPathWithin(root.resolved, dir)) && isExcluded(dir)),
+    watchPaths: [...watchPaths].filter((filePath) => !isExcluded(filePath) || filePath === userSettingsPath || filePath === projectSettingsPath)
   };
 }
 function ensureDiscoveryChains(sources) {
@@ -2058,30 +2219,31 @@ function ensureDiscoveryChains(sources) {
   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);
+  const watchPaths = new Set(sources.packageSubagentPaths.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];
+  sources.chainWatchPaths = watchPaths;
+  sources.watchPaths = [...new Set([...sources.watchPaths, ...watchPaths])];
 }
-function getAgentDiscoverySources(cwd, preferredModelProvider, includeChains = false) {
-  const key = discoveryCacheKey(cwd, preferredModelProvider);
+function getAgentDiscoverySources(cwd, preferredModelProvider, includeChains = false, globalNpmRoot) {
+  const key = discoveryCacheKey(cwd, preferredModelProvider, globalNpmRoot);
   const cached = agentDiscoveryCache.get(key);
-  if (cached && cached.fingerprint === discoveryFingerprint(cached.sources.watchPaths)) {
+  if (cached && cached.fingerprint === discoveryFingerprint(cached.sources)) {
     if (includeChains) {
       ensureDiscoveryChains(cached.sources);
-      cached.fingerprint = discoveryFingerprint(cached.sources.watchPaths);
+      cached.fingerprint = discoveryFingerprint(cached.sources);
     }
     return cached.sources;
   }
-  const sources = buildAgentDiscoverySources(cwd, preferredModelProvider);
-  const entry = { sources, fingerprint: discoveryFingerprint(sources.watchPaths) };
+  const sources = buildAgentDiscoverySources(cwd, preferredModelProvider, globalNpmRoot);
+  const entry = { sources, fingerprint: discoveryFingerprint(sources) };
   agentDiscoveryCache.set(key, entry);
   if (includeChains) {
     ensureDiscoveryChains(sources);
-    entry.fingerprint = discoveryFingerprint(sources.watchPaths);
+    entry.fingerprint = discoveryFingerprint(sources);
   }
   return sources;
 }
@@ -2114,7 +2276,8 @@ function configuredAgentsForScope(sources, scope, settingsScope = scope) {
   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 defaultSubagentOnlyExtensions = resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, sources.projectSettingsPath);
+  const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions);
   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;
@@ -2148,9 +2311,17 @@ function discoveryDirectories(sources, scope) {
   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)
+  if (scope !== "user") {
+    const reported = new Set;
+    for (const dir of sources.projectCandidateDirs) {
+      reported.add(path.resolve(dir));
       directories.push(reportAgentDefinitionDirectory("project", dir, sources.projectInspections.get(dir)));
+    }
+    for (const directory of sources.projectLoaded) {
+      if (!reported.has(path.resolve(directory.dir)))
+        directories.push(reportAgentDefinitionDirectory("project", directory.dir, directory.inspection));
+    }
+  }
   for (const directory of sources.packageLoaded) {
     if (directory.packageEntry && packageEntryIncluded(scope, directory.packageEntry.scope))
       directories.push(reportAgentDefinitionDirectory("package", directory.dir, directory.inspection));
@@ -2216,6 +2387,7 @@ function buildAllDiscovery(sources, includeChains, settingsScope) {
     ],
     chains,
     chainDiagnostics: [...packageChainDiagnostics, ...sources.userChains?.diagnostics ?? [], ...projectChainDiagnostics],
+    cwd: sources.cwd,
     userDir: sources.userDir,
     projectDir: sources.projectAgentsDir,
     userChainDir: sources.userChainDir,
@@ -2227,10 +2399,10 @@ function buildAllDiscovery(sources, includeChains, settingsScope) {
 }
 export function discoverAgentSnapshot(cwd, scope, preferredModelProvider, options = {}) {
   const includeChains = options.includeChains !== false;
-  const sources = getAgentDiscoverySources(cwd, preferredModelProvider, includeChains);
+  const sources = getAgentDiscoverySources(cwd, preferredModelProvider, includeChains, options.globalNpmRoot);
   return { effective: buildEffectiveDiscovery(sources, scope), all: buildAllDiscovery(sources, includeChains, scope) };
 }
-function discoverAgentsUncached(cwd, scope, preferredModelProvider) {
+function discoverAgentsUncached(cwd, scope, preferredModelProvider, options = {}) {
   const effectiveCwd = path.resolve(cwd);
   const userDirOld = path.join(getAgentDir(), "agents");
   const userDirNew = path.join(os.homedir(), ".agents");
@@ -2244,25 +2416,35 @@ function discoverAgentsUncached(cwd, scope, preferredModelProvider) {
   const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
   const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
   const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
+  const defaultSubagentOnlyExtensions = resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, projectSettingsPath);
   const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
-  const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: scope !== "project", includeProject: scope !== "user" });
+  const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: scope !== "project", includeProject: scope !== "user", globalNpmRoot: options.globalNpmRoot });
+  const isExcluded = agentExclusions(agentExclusionRoots(userSettingsPath, projectSettingsPath));
   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);
+  const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions);
+  const builtinAgents = applyBuiltinOverrides(applyDefaults(builtinLoaded.agents), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+  const userScanDirs = settingsAgentScanDirs(userSettings.agentScanDirs ?? [], isExcluded);
+  const projectScanDirs = settingsAgentScanDirs(projectSettings.agentScanDirs ?? [], isExcluded);
+  const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), ...userScanDirs.dirs, userDirOld, userDirNew].filter((dir) => !isExcluded(dir)).map((dir, discoveryPriority) => {
+    const inspection = inspectAgentDefinitionDirectory(dir, undefined, isExcluded);
     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)]));
+  const userAgents = applyCustomAgentOverrides(applyDefaults(userLoaded.flatMap((loaded) => loaded.agents)), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+  const projectInspections = scope === "user" ? new Map : new Map(projectCandidateDirs.filter((dir) => !isExcluded(dir)).map((dir) => [dir, inspectAgentDefinitionDirectory(dir, undefined, isExcluded)]));
   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);
+    for (const [dir, inspection] of projectInspections)
+      directories.push(reportAgentDefinitionDirectory("project", dir, inspection));
+  const projectLoaded = scope === "user" ? [] : [...projectScanDirs.dirs, ...projectAgentDirs].filter((dir) => !isExcluded(dir)).map((dir, discoveryPriority) => {
+    const inspection = projectInspections.get(dir) ?? inspectAgentDefinitionDirectory(dir, undefined, isExcluded);
+    if (!projectInspections.has(dir))
+      directories.push(reportAgentDefinitionDirectory("project", dir, inspection));
+    return loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : discoveryPriority, undefined, inspection);
+  });
+  const projectAgents = applyCustomAgentOverrides(applyDefaults(projectLoaded.flatMap((loaded) => loaded.agents)), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
+  const packageLoaded = packageSubagentPaths.agents.filter((entry) => !isExcluded(entry.dir)).map((entry, index) => {
+    const inspection = inspectAgentDefinitionDirectory(entry.dir, undefined, isExcluded);
     directories.push(reportAgentDefinitionDirectory("package", entry.dir, inspection));
     return loadAgentsFromDir(entry.dir, "package", packageSubagentPaths.agents.length - index, entry, inspection);
   });
@@ -2271,17 +2453,17 @@ function discoverAgentsUncached(cwd, scope, preferredModelProvider) {
     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 packageAgents = applyCustomAgentOverrides(applyDefaults(Array.from(packageMap.values())), 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) {
+export function discoverAgents(cwd, scope, preferredModelProvider, options = {}) {
   if (scope !== "both")
-    return discoverAgentsUncached(cwd, scope, preferredModelProvider);
-  const sources = getAgentDiscoverySources(cwd, preferredModelProvider);
+    return discoverAgentsUncached(cwd, scope, preferredModelProvider, options);
+  const sources = getAgentDiscoverySources(cwd, preferredModelProvider, false, options.globalNpmRoot);
   return buildEffectiveDiscovery(sources, scope);
 }
-export function discoverAgentsAll(cwd, preferredModelProvider) {
-  return discoverAgentSnapshot(cwd, "both", preferredModelProvider).all;
+export function discoverAgentsAll(cwd, preferredModelProvider, options = {}) {
+  return discoverAgentSnapshot(cwd, "both", preferredModelProvider, options).all;
 }