@xzzpig/pi-subagents 0.16.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/CHANGELOG.md +233 -1
  2. package/README.md +5 -3
  3. package/agents/claude-code-writer.md +1 -0
  4. package/agents/codex-exec-writer.md +1 -0
  5. package/agents/cursor-agent-writer.md +1 -0
  6. package/agents/reviewer.md +3 -2
  7. package/agents/worker.md +3 -2
  8. package/docs/agents.md +34 -21
  9. package/docs/configuration.md +82 -7
  10. package/docs/extension-api.md +75 -8
  11. package/docs/missions.md +13 -13
  12. package/docs/models.md +7 -5
  13. package/docs/observability.md +23 -13
  14. package/docs/standalone-background.md +5 -5
  15. package/docs/tool-reference.md +98 -100
  16. package/docs/watchdog.md +2 -0
  17. package/docs/workflows.md +214 -162
  18. package/inspector-runner.mjs +1 -1
  19. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  20. package/package.json +15 -9
  21. package/prompts/council.md +6 -3
  22. package/prompts/review-loop.md +1 -1
  23. package/runner-peer-loader.mjs +4 -7
  24. package/runner-peer-preload.mjs +5 -7
  25. package/skills/council-mode/SKILL.md +1 -1
  26. package/skills/pi-subagents/SKILL.md +13 -5
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
  28. package/skills/pi-subagents/references/execution-controls.md +72 -69
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
  32. package/src/agents/advertised-agent-prompt.ts +21 -41
  33. package/src/agents/agent-eject.ts +3 -3
  34. package/src/agents/agent-management.ts +63 -54
  35. package/src/agents/agent-memory.ts +90 -3
  36. package/src/agents/agent-serializer.ts +4 -4
  37. package/src/agents/agents.ts +132 -51
  38. package/src/agents/global-npm-root.ts +58 -0
  39. package/src/agents/proactive-skills.ts +4 -1
  40. package/src/agents/runtime-agent-registry.ts +14 -11
  41. package/src/agents/skills.ts +42 -9
  42. package/src/api/delegation.ts +15 -0
  43. package/src/api/inspectors.ts +27 -0
  44. package/src/api/preflight.ts +7 -2
  45. package/src/extension/config.ts +12 -4
  46. package/src/extension/control-notices.ts +3 -0
  47. package/src/extension/doctor.ts +10 -4
  48. package/src/extension/fanout-child.ts +20 -3
  49. package/src/extension/herdr-pi-bridge.ts +2 -0
  50. package/src/extension/index.ts +168 -206
  51. package/src/extension/public-execution.ts +69 -35
  52. package/src/extension/reply-workflow-script.ts +58 -0
  53. package/src/extension/rpc.ts +39 -11
  54. package/src/extension/schemas.ts +47 -138
  55. package/src/extension/subagent-guide.ts +12 -4
  56. package/src/extension/tool-activation.ts +146 -0
  57. package/src/extension/tool-description.ts +62 -27
  58. package/src/extension/upgrade-notice.ts +40 -0
  59. package/src/inspectors/ghostty/plugin.ts +13 -1
  60. package/src/inspectors/plugins.ts +70 -3
  61. package/src/integrations/herdr-status.ts +19 -3
  62. package/src/intercom/intercom-bridge.ts +2 -0
  63. package/src/intercom/native-supervisor-channel.ts +26 -16
  64. package/src/intercom/result-intercom.ts +4 -0
  65. package/src/runs/background/active-async-capacity.ts +3 -25
  66. package/src/runs/background/async-execution.ts +60 -95
  67. package/src/runs/background/async-job-tracker.ts +91 -56
  68. package/src/runs/background/async-resume.ts +16 -8
  69. package/src/runs/background/async-retention.ts +46 -16
  70. package/src/runs/background/async-status.ts +2 -0
  71. package/src/runs/background/await-async-run.ts +76 -0
  72. package/src/runs/background/binary-bootstrap.ts +34 -6
  73. package/src/runs/background/chain-root-attachment.ts +4 -4
  74. package/src/runs/background/control-channel.ts +18 -2
  75. package/src/runs/background/fleet-view.ts +51 -7
  76. package/src/runs/background/notify.ts +98 -7
  77. package/src/runs/background/pid-namespace.ts +18 -0
  78. package/src/runs/background/process-terminal-candidate.ts +98 -0
  79. package/src/runs/background/process-terminal.ts +17 -96
  80. package/src/runs/background/result-watcher.ts +1 -1
  81. package/src/runs/background/retained-children.ts +3 -2
  82. package/src/runs/background/run-child-session.ts +20 -6
  83. package/src/runs/background/run-id-resolver.ts +10 -5
  84. package/src/runs/background/run-status.ts +16 -4
  85. package/src/runs/background/runner-aliases.ts +54 -16
  86. package/src/runs/background/runner-child-launch.ts +4 -2
  87. package/src/runs/background/runner-startup-failure.ts +56 -0
  88. package/src/runs/background/scheduled-runs.ts +5 -5
  89. package/src/runs/background/stale-run-reconciler.ts +19 -3
  90. package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
  91. package/src/runs/background/subagent-runner.ts +111 -288
  92. package/src/runs/background/wait-tool.ts +2 -0
  93. package/src/runs/background/workflow-terminal-proof.ts +68 -0
  94. package/src/runs/foreground/async-stop-action.ts +17 -3
  95. package/src/runs/foreground/execution.ts +111 -139
  96. package/src/runs/foreground/prompt-audit.ts +3 -9
  97. package/src/runs/foreground/subagent-executor.ts +715 -258
  98. package/src/runs/shared/acceptance.ts +167 -68
  99. package/src/runs/shared/async-status-projection.ts +5 -0
  100. package/src/runs/shared/capability-ceiling.ts +4 -1
  101. package/src/runs/shared/child-hooks.ts +1 -16
  102. package/src/runs/shared/child-launch.ts +37 -16
  103. package/src/runs/shared/child-runtime-config.ts +3 -0
  104. package/src/runs/shared/child-session.ts +144 -8
  105. package/src/runs/shared/child-tool-plan.ts +38 -116
  106. package/src/runs/shared/dynamic-fanout.ts +1 -1
  107. package/src/runs/shared/external-cli-runner.ts +3 -1
  108. package/src/runs/shared/external-job-bridge.ts +54 -0
  109. package/src/runs/shared/git-environment.ts +29 -0
  110. package/src/runs/shared/mcp-config-sources.ts +5 -1
  111. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
  112. package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
  113. package/src/runs/shared/model-resolution.ts +35 -10
  114. package/src/runs/shared/model-scope.ts +28 -9
  115. package/src/runs/shared/nested-events.ts +12 -0
  116. package/src/runs/shared/orca-progress-tabs.ts +3 -2
  117. package/src/runs/shared/parallel-utils.ts +4 -1
  118. package/src/runs/shared/pi-spawn.ts +1 -3
  119. package/src/runs/shared/single-output.ts +11 -2
  120. package/src/runs/shared/structured-output.ts +227 -7
  121. package/src/runs/shared/subagent-control.ts +2 -16
  122. package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
  123. package/src/runs/shared/tool-availability.ts +2 -2
  124. package/src/runs/shared/tool-budget.ts +21 -0
  125. package/src/runs/shared/usage-reconciliation.ts +73 -0
  126. package/src/runs/shared/worktree.ts +36 -9
  127. package/src/shared/child-session-name.ts +4 -2
  128. package/src/shared/disabled-features.ts +123 -0
  129. package/src/shared/extension-context.ts +13 -0
  130. package/src/shared/fork-context.ts +11 -4
  131. package/src/shared/launch-contract.ts +1 -1
  132. package/src/shared/model-info.ts +9 -0
  133. package/src/shared/pruned-fork.ts +69 -56
  134. package/src/shared/settings.ts +1 -1
  135. package/src/shared/types.ts +73 -16
  136. package/src/slash/delegation-adapters.ts +25 -1
  137. package/src/slash/prompt-template-bridge.ts +18 -3
  138. package/src/slash/prompt-workflows.ts +12 -1
  139. package/src/slash/slash-commands.ts +17 -246
  140. package/src/slash/subagent-cost.ts +313 -0
  141. package/src/slash/subagents-admin.ts +4 -5
  142. package/src/tui/fleet-status.ts +38 -8
  143. package/src/tui/fleet.ts +21 -6
  144. package/src/tui/render.ts +166 -71
  145. package/src/tui/running-tone.ts +28 -0
  146. package/src/watchdog/diff-tool.ts +47 -12
  147. package/src/watchdog/permission-arbiter.ts +13 -15
  148. package/src/watchdog/register-child.ts +13 -5
  149. package/src/watchdog/register-main.ts +3 -3
  150. package/src/watchdog/review.ts +16 -16
  151. package/src/watchdog/runtime.ts +2 -1
  152. package/src/watchdog/turn-delta.ts +12 -6
  153. package/src/workflows/chat-progress.ts +2 -2
  154. package/src/workflows/scripted-workflow.ts +225 -59
  155. package/src/workflows/structured-workflow-scripts.ts +177 -0
  156. package/src/workflows/workflow-checklist.ts +6 -0
  157. package/src/workflows/workflow-child-summary.ts +4 -2
  158. package/src/workflows/workflow-receipt.ts +8 -2
  159. package/src/workflows/workflow-resources.ts +37 -12
  160. package/src/workflows/workflow-reuse.ts +120 -0
  161. package/src/workflows/workflow-revival.ts +123 -0
  162. package/src/workflows/workflow-settlement.ts +4 -1
  163. package/src/runs/shared/completion-evidence.ts +0 -89
  164. package/src/runs/shared/completion-guard.ts +0 -255
  165. package/src/runs/shared/llm-intent-arbiter.ts +0 -321
  166. package/src/runs/shared/task-intent.ts +0 -244
@@ -27,6 +27,7 @@ import { parseThinkingLevel, type ThinkingLevel } from "../shared/thinking-ceili
27
27
  import { validateSandboxProfileName } from "../shared/sandbox-profile.ts";
28
28
  import { validatePermissionProfileName } from "../shared/permission-profile.ts";
29
29
  import { assertJsonSchemaObject } from "../runs/shared/structured-output.ts";
30
+ import { normalizeCapabilityCeilingAllowedAgents } from "../runs/shared/capability-ceiling.ts";
30
31
 
31
32
  export type AgentScope = "user" | "project" | "both";
32
33
 
@@ -76,11 +77,11 @@ export interface BuiltinAgentOverrideBase {
76
77
  tools?: string[];
77
78
  excludeTools?: string[];
78
79
  allowNestedSubagents?: boolean;
80
+ allowedAgents?: string[];
79
81
  mcpDirectTools?: string[];
80
82
  extensions?: string[];
81
83
  subagentOnlyExtensions?: string[];
82
84
  mutationTools?: string[];
83
- completionGuard?: boolean;
84
85
  toolBudget?: ToolBudgetConfig;
85
86
  sandbox?: string;
86
87
  permissionProfile?: string;
@@ -88,6 +89,7 @@ export interface BuiltinAgentOverrideBase {
88
89
 
89
90
  interface BuiltinAgentOverrideConfig {
90
91
  description?: string;
92
+ advertise?: boolean;
91
93
  machine?: string | false;
92
94
  output?: string | false;
93
95
  outputMode?: OutputMode;
@@ -108,10 +110,10 @@ interface BuiltinAgentOverrideConfig {
108
110
  tools?: string[] | false | "inherit";
109
111
  excludeTools?: string[] | false;
110
112
  allowNestedSubagents?: boolean;
113
+ allowedAgents?: string[] | false;
111
114
  extensions?: string[] | false;
112
115
  subagentOnlyExtensions?: string[] | false;
113
116
  mutationTools?: string[] | false;
114
- completionGuard?: boolean;
115
117
  toolBudget?: ToolBudgetConfig | false;
116
118
  sandbox?: string;
117
119
  permissionProfile?: string;
@@ -147,6 +149,7 @@ export interface AgentConfig {
147
149
  tools?: string[];
148
150
  excludeTools?: string[];
149
151
  allowNestedSubagents?: boolean;
152
+ allowedAgents?: string[];
150
153
  mcpDirectTools?: string[];
151
154
  model?: string;
152
155
  modelProvider?: string;
@@ -180,7 +183,6 @@ export interface AgentConfig {
180
183
  injectToContext?: boolean;
181
184
  interactive?: boolean;
182
185
  maxSubagentDepth?: number;
183
- completionGuard?: boolean;
184
186
  toolBudget?: ToolBudgetConfig;
185
187
  sandbox?: string;
186
188
  permissionProfile?: string;
@@ -212,6 +214,7 @@ interface SubagentSettings {
212
214
  defaultThinking?: string;
213
215
  maxThinking?: ThinkingLevel;
214
216
  defaultExtensions?: string[];
217
+ defaultSubagentOnlyExtensions?: string[];
215
218
  disableBuiltins?: boolean;
216
219
  disableThinking?: boolean;
217
220
  modelScope?: ModelScopeConfig;
@@ -516,7 +519,7 @@ function getGlobalNpmRoot(): string | null {
516
519
  }
517
520
 
518
521
  try {
519
- cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true }).trim());
522
+ cachedGlobalNpmRoot = fs.realpathSync(execSync("npm root -g", { encoding: "utf-8", timeout: 5000, windowsHide: true, stdio: ["ignore", "pipe", "ignore"] }).trim());
520
523
  return cachedGlobalNpmRoot;
521
524
  } catch {
522
525
  cachedGlobalNpmRoot = "";
@@ -626,7 +629,7 @@ function collectSettingsPackageRoots(settingsFile: string, baseDir: string): str
626
629
  return roots;
627
630
  }
628
631
 
629
- function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolean; includeProject: boolean } = { includeUser: true, includeProject: true }): PackageSubagentPaths {
632
+ function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolean; includeProject: boolean; globalNpmRoot?: string | null } = { includeUser: true, includeProject: true }): PackageSubagentPaths {
630
633
  const agentDir = getAgentDir();
631
634
  const projectRoot = findConfiguredProjectRoot(cwd) ?? cwd;
632
635
  const packageRoots: Array<{ root: string; scope: PackageScope }> = [
@@ -661,7 +664,7 @@ function collectPackageSubagentPaths(cwd: string, options: { includeUser: boolea
661
664
  }
662
665
 
663
666
  if (options.includeUser) {
664
- const globalRoot = getGlobalNpmRoot();
667
+ const globalRoot = options.globalNpmRoot === undefined ? getGlobalNpmRoot() : options.globalNpmRoot;
665
668
  if (globalRoot) {
666
669
  packageRoots.push(...collectPackageRootsFromNodeModules(globalRoot, watchPaths).map((root) => ({ root, scope: "user" as const })));
667
670
  }
@@ -809,11 +812,11 @@ function cloneOverrideBase(agent: AgentConfig): BuiltinAgentOverrideBase {
809
812
  ...(agent.tools ? { tools: [...agent.tools] } : {}),
810
813
  ...(agent.excludeTools ? { excludeTools: [...agent.excludeTools] } : {}),
811
814
  ...(agent.allowNestedSubagents !== undefined ? { allowNestedSubagents: agent.allowNestedSubagents } : {}),
815
+ ...(agent.allowedAgents !== undefined ? { allowedAgents: [...agent.allowedAgents] } : {}),
812
816
  ...(agent.mcpDirectTools ? { mcpDirectTools: [...agent.mcpDirectTools] } : {}),
813
817
  ...(!agent.extensionsFromDefault && agent.extensions ? { extensions: [...agent.extensions] } : {}),
814
818
  ...(agent.subagentOnlyExtensions ? { subagentOnlyExtensions: [...agent.subagentOnlyExtensions] } : {}),
815
819
  ...(agent.mutationTools ? { mutationTools: [...agent.mutationTools] } : {}),
816
- ...(agent.completionGuard !== undefined ? { completionGuard: agent.completionGuard } : {}),
817
820
  ...(agent.toolBudget !== undefined ? { toolBudget: agent.toolBudget } : {}),
818
821
  ...(agent.sandbox !== undefined ? { sandbox: agent.sandbox } : {}),
819
822
  ...(agent.permissionProfile !== undefined ? { permissionProfile: agent.permissionProfile } : {}),
@@ -843,10 +846,10 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
843
846
  ...(override.tools !== undefined ? { tools: Array.isArray(override.tools) ? [...override.tools] : override.tools } : {}),
844
847
  ...(override.excludeTools !== undefined ? { excludeTools: override.excludeTools === false ? false : [...override.excludeTools] } : {}),
845
848
  ...(override.allowNestedSubagents !== undefined ? { allowNestedSubagents: override.allowNestedSubagents } : {}),
849
+ ...(override.allowedAgents !== undefined ? { allowedAgents: override.allowedAgents === false ? false : [...override.allowedAgents] } : {}),
846
850
  ...(override.extensions !== undefined ? { extensions: override.extensions === false ? false : [...override.extensions] } : {}),
847
851
  ...(override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {}),
848
852
  ...(override.mutationTools !== undefined ? { mutationTools: override.mutationTools === false ? false : [...override.mutationTools] } : {}),
849
- ...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
850
853
  ...(override.toolBudget !== undefined ? { toolBudget: override.toolBudget === false ? false : { ...override.toolBudget, ...(Array.isArray(override.toolBudget.block) ? { block: [...override.toolBudget.block] } : {}) } } : {}),
851
854
  ...(override.sandbox !== undefined ? { sandbox: override.sandbox } : {}),
852
855
  ...(override.permissionProfile !== undefined ? { permissionProfile: override.permissionProfile } : {}),
@@ -878,7 +881,7 @@ function findProjectRootCandidates(cwd: string): string[] {
878
881
  }
879
882
  }
880
883
 
881
- function findNearestGitRoot(cwd: string): string | null {
884
+ export function findNearestGitRoot(cwd: string): string | null {
882
885
  let currentDir = cwd;
883
886
  while (true) {
884
887
  if (fs.existsSync(path.join(currentDir, ".git"))) return currentDir;
@@ -1033,6 +1036,11 @@ function parseBuiltinOverrideEntry(
1033
1036
  }
1034
1037
  }
1035
1038
 
1039
+ if ("advertise" in input) {
1040
+ if (typeof input.advertise === "boolean") override.advertise = input.advertise;
1041
+ else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'advertise'; expected a boolean.`);
1042
+ }
1043
+
1036
1044
  if ("output" in input) {
1037
1045
  if ((typeof input.output === "string" && input.output.trim()) || input.output === false) override.output = input.output;
1038
1046
  else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'output'; expected a non-empty string or false.`);
@@ -1117,13 +1125,6 @@ function parseBuiltinOverrideEntry(
1117
1125
  }
1118
1126
  }
1119
1127
 
1120
- if ("completionGuard" in input) {
1121
- if (typeof input.completionGuard === "boolean") {
1122
- override.completionGuard = input.completionGuard;
1123
- } else {
1124
- throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'completionGuard'; expected a boolean.`);
1125
- }
1126
- }
1127
1128
 
1128
1129
  if ("toolBudget" in input) {
1129
1130
  if (input.toolBudget === false) {
@@ -1175,6 +1176,8 @@ function parseBuiltinOverrideEntry(
1175
1176
  if (typeof input.allowNestedSubagents === "boolean") override.allowNestedSubagents = input.allowNestedSubagents;
1176
1177
  else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'allowNestedSubagents'; expected a boolean.`);
1177
1178
  }
1179
+ const allowedAgents = parseOverrideStringArrayOrFalse(input.allowedAgents, { filePath, name, field: "allowedAgents" });
1180
+ if (allowedAgents !== undefined) override.allowedAgents = allowedAgents === false ? false : normalizeCapabilityCeilingAllowedAgents(allowedAgents);
1178
1181
 
1179
1182
  const extensions = parseOverrideStringArrayOrFalse(input.extensions, { filePath, name, field: "extensions" });
1180
1183
  if (extensions !== undefined) override.extensions = extensions;
@@ -1259,6 +1262,14 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
1259
1262
  }
1260
1263
  injectAgents = subagentsObject.injectAgents.map((item) => item.trim());
1261
1264
  }
1265
+ let defaultSubagentOnlyExtensions: string[] | undefined;
1266
+ if ("defaultSubagentOnlyExtensions" in subagentsObject) {
1267
+ if (!Array.isArray(subagentsObject.defaultSubagentOnlyExtensions)
1268
+ || subagentsObject.defaultSubagentOnlyExtensions.some((item) => typeof item !== "string" || !item.trim())) {
1269
+ throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultSubagentOnlyExtensions'; expected an array of non-empty strings.`);
1270
+ }
1271
+ defaultSubagentOnlyExtensions = subagentsObject.defaultSubagentOnlyExtensions.map((item) => item.trim());
1272
+ }
1262
1273
  let agentScanDirs: string[] | undefined;
1263
1274
  if ("agentScanDirs" in subagentsObject) {
1264
1275
  if (!Array.isArray(subagentsObject.agentScanDirs)
@@ -1289,6 +1300,7 @@ function readSubagentSettings(filePath: string | null): SubagentSettings {
1289
1300
  ...(defaultThinking !== undefined ? { defaultThinking } : {}),
1290
1301
  ...(maxThinking !== undefined ? { maxThinking } : {}),
1291
1302
  ...(defaultExtensions !== undefined ? { defaultExtensions } : {}),
1303
+ ...(defaultSubagentOnlyExtensions !== undefined ? { defaultSubagentOnlyExtensions } : {}),
1292
1304
  ...(agentScanDirs !== undefined ? { agentScanDirs } : {}),
1293
1305
  ...(agentExcludeDirs !== undefined ? { agentExcludeDirs } : {}),
1294
1306
  ...(disableBuiltins !== undefined ? { disableBuiltins } : {}),
@@ -1425,16 +1437,40 @@ function applySubagentDefaultExtensions(agents: AgentConfig[], defaultExtensions
1425
1437
  });
1426
1438
  }
1427
1439
 
1440
+ function resolveSubagentDefaultSubagentOnlyExtensions(
1441
+ userSettings: SubagentSettings,
1442
+ projectSettings: SubagentSettings,
1443
+ projectSettingsPath: string | null,
1444
+ ): string[] | undefined {
1445
+ if (projectSettingsPath && projectSettings.defaultSubagentOnlyExtensions !== undefined) return projectSettings.defaultSubagentOnlyExtensions;
1446
+ return userSettings.defaultSubagentOnlyExtensions;
1447
+ }
1448
+
1449
+ function applySubagentDefaultSubagentOnlyExtensions(agents: AgentConfig[], defaultSubagentOnlyExtensions: string[] | undefined): AgentConfig[] {
1450
+ if (defaultSubagentOnlyExtensions === undefined) return agents;
1451
+ return agents.map((agent) => {
1452
+ if (agent.subagentOnlyExtensions !== undefined) return agent;
1453
+ const next = { ...agent, subagentOnlyExtensions: [...defaultSubagentOnlyExtensions] };
1454
+ const frontmatterFields = agentFrontmatterFields.get(agent);
1455
+ if (frontmatterFields) agentFrontmatterFields.set(next, frontmatterFields);
1456
+ return next;
1457
+ });
1458
+ }
1459
+
1428
1460
  function applySubagentDefaults(
1429
1461
  agents: AgentConfig[],
1430
1462
  defaultModel: AgentModelSourceInfo | undefined,
1431
1463
  defaultProvider: string | undefined,
1432
1464
  defaultThinking: string | undefined,
1433
1465
  defaultExtensions: string[] | undefined,
1466
+ defaultSubagentOnlyExtensions: string[] | undefined,
1434
1467
  ): AgentConfig[] {
1435
- return applySubagentDefaultExtensions(
1436
- applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking),
1437
- defaultExtensions,
1468
+ return applySubagentDefaultSubagentOnlyExtensions(
1469
+ applySubagentDefaultExtensions(
1470
+ applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking),
1471
+ defaultExtensions,
1472
+ ),
1473
+ defaultSubagentOnlyExtensions,
1438
1474
  );
1439
1475
  }
1440
1476
 
@@ -1470,6 +1506,7 @@ function applyBuiltinOverride(
1470
1506
  };
1471
1507
 
1472
1508
  if (override.description !== undefined) next.description = override.description;
1509
+ if (override.advertise !== undefined) next.advertise = override.advertise;
1473
1510
  if (override.machine !== undefined) { if (override.machine === false) delete next.machine; else next.machine = override.machine; }
1474
1511
  if (override.output !== undefined) { if (override.output === false) delete next.output; else next.output = override.output; }
1475
1512
  if (override.outputMode !== undefined) next.outputMode = override.outputMode;
@@ -1496,10 +1533,10 @@ function applyBuiltinOverride(
1496
1533
  if (override.tools !== undefined) applyToolsOverride(next, override.tools);
1497
1534
  if (override.excludeTools !== undefined) { if (override.excludeTools === false) delete next.excludeTools; else next.excludeTools = [...override.excludeTools]; }
1498
1535
  if (override.allowNestedSubagents !== undefined) next.allowNestedSubagents = override.allowNestedSubagents;
1536
+ if (override.allowedAgents !== undefined) { if (override.allowedAgents === false) delete next.allowedAgents; else next.allowedAgents = [...override.allowedAgents]; }
1499
1537
  if (override.extensions !== undefined) { if (override.extensions === false) delete next.extensions; else next.extensions = [...override.extensions]; }
1500
1538
  if (override.subagentOnlyExtensions !== undefined) { if (override.subagentOnlyExtensions === false) delete next.subagentOnlyExtensions; else next.subagentOnlyExtensions = [...override.subagentOnlyExtensions]; }
1501
1539
  if (override.mutationTools !== undefined) { if (override.mutationTools === false) delete next.mutationTools; else next.mutationTools = [...override.mutationTools]; }
1502
- if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
1503
1540
  if (override.toolBudget !== undefined) { if (override.toolBudget === false) delete next.toolBudget; else next.toolBudget = override.toolBudget; }
1504
1541
  if (override.sandbox !== undefined) next.sandbox = override.sandbox;
1505
1542
  if (override.permissionProfile !== undefined) next.permissionProfile = override.permissionProfile;
@@ -1602,9 +1639,48 @@ function applyCustomAgentOverrides(
1602
1639
  });
1603
1640
  }
1604
1641
 
1642
+ export interface RuntimeAgentSettingsContext {
1643
+ cwd: string;
1644
+ scope: AgentScope;
1645
+ preferredModelProvider?: string;
1646
+ }
1647
+
1648
+ function runtimeAgentOverrides(settings: SubagentSettings): SubagentSettings {
1649
+ const overrides: Record<string, BuiltinAgentOverrideConfig> = {};
1650
+ for (const [name, override] of Object.entries(settings.overrides)) {
1651
+ const narrowed: BuiltinAgentOverrideConfig = {};
1652
+ if (override.model !== undefined) narrowed.model = override.model;
1653
+ if (override.defaultProvider !== undefined) narrowed.defaultProvider = override.defaultProvider;
1654
+ if (override.fast !== undefined) narrowed.fast = override.fast;
1655
+ if (override.thinking !== undefined) narrowed.thinking = override.thinking;
1656
+ if (Object.keys(narrowed).length > 0) overrides[name] = narrowed;
1657
+ }
1658
+ return { ...settings, overrides };
1659
+ }
1660
+
1661
+ /**
1662
+ * Runtime-registered agents keep their extension-owned definition (prompt,
1663
+ * tools, context, budgets, and every other launch field) but follow the same
1664
+ * model-tier settings as every other agent: `subagents.defaultModel`,
1665
+ * `defaultProvider`, `defaultThinking`, and the `model`, `defaultProvider`,
1666
+ * `fast`, and `thinking` fields of `agentOverrides.<name>`, user then project,
1667
+ * provider-scoped overrides included. Other override fields are ignored for
1668
+ * runtime agents. A definition `model` still wins over `defaultModel`.
1669
+ */
1670
+ export function applyRuntimeAgentSettings(agents: AgentConfig[], context: RuntimeAgentSettingsContext): AgentConfig[] {
1671
+ if (agents.length === 0) return agents;
1672
+ const sources = getAgentDiscoverySources(context.cwd, context.preferredModelProvider);
1673
+ const { user, project } = settingsForScope(sources, context.scope);
1674
+ const defaultProvider = resolveSubagentDefaultProvider(user, project, sources.projectSettingsPath);
1675
+ const defaultModel = resolveSubagentDefaultModel(user, project, sources.userSettingsPath, sources.projectSettingsPath, defaultProvider);
1676
+ const defaultThinking = resolveSubagentDefaultThinking(user, project, sources.projectSettingsPath);
1677
+ const withDefaults = applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking);
1678
+ return applyCustomAgentOverrides(withDefaults, runtimeAgentOverrides(user), runtimeAgentOverrides(project), sources.userSettingsPath, sources.projectSettingsPath);
1679
+ }
1680
+
1605
1681
  export function buildBuiltinOverrideConfig(
1606
1682
  base: BuiltinAgentOverrideBase,
1607
- draft: Pick<AgentConfig, "model" | "modelProvider" | "fast" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritGlobalContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "allowNestedSubagents" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "mutationTools" | "completionGuard" | "toolBudget" | "sandbox" | "permissionProfile"> & Partial<Pick<AgentConfig, "description" | "machine" | "output" | "outputMode" | "defaultReads" | "excludeTools">>,
1683
+ draft: Pick<AgentConfig, "model" | "modelProvider" | "fast" | "thinking" | "systemPromptMode" | "inheritProjectContext" | "inheritGlobalContext" | "inheritSkills" | "defaultContext" | "acceptanceRole" | "disabled" | "systemPrompt" | "skills" | "tools" | "allowNestedSubagents" | "mcpDirectTools" | "extensions" | "subagentOnlyExtensions" | "mutationTools" | "toolBudget" | "sandbox" | "permissionProfile"> & Partial<Pick<AgentConfig, "description" | "machine" | "output" | "outputMode" | "defaultReads" | "excludeTools">>,
1608
1684
  ): BuiltinAgentOverrideConfig | undefined {
1609
1685
  const override: BuiltinAgentOverrideConfig = {};
1610
1686
  if (draft.machine !== base.machine) override.machine = draft.machine ?? false;
@@ -1640,9 +1716,6 @@ export function buildBuiltinOverrideConfig(
1640
1716
  override.subagentOnlyExtensions = draft.subagentOnlyExtensions ? [...draft.subagentOnlyExtensions] : false;
1641
1717
  }
1642
1718
  if (!arraysEqual(draft.mutationTools, base.mutationTools)) override.mutationTools = draft.mutationTools ? [...draft.mutationTools] : false;
1643
- if ((draft.completionGuard !== false) !== (base.completionGuard !== false)) {
1644
- override.completionGuard = draft.completionGuard !== false;
1645
- }
1646
1719
  if (JSON.stringify(draft.toolBudget) !== JSON.stringify(base.toolBudget)) override.toolBudget = draft.toolBudget ?? false;
1647
1720
  if (draft.sandbox !== undefined && draft.sandbox !== base.sandbox) override.sandbox = draft.sandbox;
1648
1721
  if (draft.permissionProfile !== undefined && draft.permissionProfile !== base.permissionProfile) override.permissionProfile = draft.permissionProfile;
@@ -2006,7 +2079,7 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
2006
2079
 
2007
2080
  function validateExternalRunnerProfile(frontmatter: Record<string, string>, agentName: string, runner: AgentRunnerConfig | undefined): void {
2008
2081
  if (runner?.type !== "external-cli" && runner?.type !== "external-job") return;
2009
- const unsupported = ["tools", "excludeTools", "allowNestedSubagents", "model", "thinking", "extensions", "subagentOnlyExtensions", "mutationTools", "maxSubagentDepth", "completionGuard", "skills", "skill", "skillPath", "toolBudget", "sandbox", "permission-profile", "permission", "permissions"]
2082
+ const unsupported = ["tools", "excludeTools", "allowNestedSubagents", "allowedAgents", "model", "thinking", "extensions", "subagentOnlyExtensions", "mutationTools", "maxSubagentDepth", "skills", "skill", "skillPath", "toolBudget", "sandbox", "permission-profile", "permission", "permissions"]
2010
2083
  .filter((field) => frontmatter[field] !== undefined);
2011
2084
  if (unsupported.length > 0) {
2012
2085
  throw new Error(`Agent '${agentName}' uses runner.type='${runner.type}' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
@@ -2095,6 +2168,8 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
2095
2168
  const tools = parsedTools.tools ?? [];
2096
2169
  const mcpDirectTools = parsedTools.mcpDirectTools ?? [];
2097
2170
  const excludeTools = parseFrontmatterList(frontmatter.excludeTools);
2171
+ const parsedAllowedAgents = parseFrontmatterList(frontmatter.allowedAgents);
2172
+ const allowedAgents = parsedAllowedAgents === undefined ? undefined : normalizeCapabilityCeilingAllowedAgents(parsedAllowedAgents);
2098
2173
  const defaultReads = parseFrontmatterList(frontmatter.defaultReads);
2099
2174
  const aliases = normalizeAgentAliases(parseFrontmatterList(frontmatter.aliases ?? frontmatter.alias), runtimeName);
2100
2175
  const profileError = validateCodeOwnedProfileRunner({ name: runtimeName, localName, aliases, runner });
@@ -2207,11 +2282,6 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
2207
2282
  assertJsonSchemaObject(parsed, `Agent '${localName}' outputSchema`);
2208
2283
  outputSchema = parsed;
2209
2284
  }
2210
- const completionGuard = frontmatter.completionGuard === "false"
2211
- ? false
2212
- : frontmatter.completionGuard === "true"
2213
- ? true
2214
- : undefined;
2215
2285
 
2216
2286
  const maxSubagentDepth = Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0
2217
2287
  ? parsedMaxSubagentDepth
@@ -2232,6 +2302,7 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
2232
2302
  ...(rawTools !== undefined ? { tools } : {}),
2233
2303
  ...(excludeTools !== undefined ? { excludeTools } : {}),
2234
2304
  ...(allowNestedSubagents !== undefined ? { allowNestedSubagents } : {}),
2305
+ ...(allowedAgents !== undefined ? { allowedAgents } : {}),
2235
2306
  ...(mcpDirectTools.length > 0 ? { mcpDirectTools } : {}),
2236
2307
  ...(frontmatter.model !== undefined ? { model: frontmatter.model } : {}),
2237
2308
  ...(fast !== undefined ? { fast } : {}),
@@ -2264,7 +2335,6 @@ function loadAgentsFromDefinitionFiles(files: AgentDefinitionFile[], source: Age
2264
2335
  injectToContext: frontmatter.injectToContext === "true",
2265
2336
  interactive: frontmatter.interactive === "true",
2266
2337
  ...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
2267
- ...(completionGuard !== undefined ? { completionGuard } : {}),
2268
2338
  ...(toolBudget !== undefined ? { toolBudget } : {}),
2269
2339
  ...(sandbox !== undefined ? { sandbox } : {}),
2270
2340
  ...(permissionProfile !== undefined ? { permissionProfile } : {}),
@@ -2465,6 +2535,7 @@ export interface AgentDiscoveryAllResult {
2465
2535
  package: AgentConfig[];
2466
2536
  user: AgentConfig[];
2467
2537
  project: AgentConfig[];
2538
+ cwd: string;
2468
2539
  agentDiagnostics?: AgentDiscoveryDiagnostic[];
2469
2540
  injectAgents?: string[];
2470
2541
  chains: ChainConfig[];
@@ -2489,6 +2560,11 @@ export interface AgentDiscoverySnapshot {
2489
2560
  all: AgentDiscoveryAllResult;
2490
2561
  }
2491
2562
 
2563
+ /** Undefined uses synchronous npm lookup; null skips global npm discovery. */
2564
+ export interface AgentDiscoveryOptions {
2565
+ globalNpmRoot?: string | null;
2566
+ }
2567
+
2492
2568
  interface LoadedAgentDirectory {
2493
2569
  dir: string;
2494
2570
  inspection: AgentDefinitionInspection;
@@ -2591,10 +2667,11 @@ function discoveryFingerprint(sources: AgentDiscoverySources): string {
2591
2667
  .join("\n");
2592
2668
  }
2593
2669
 
2594
- function discoveryCacheKey(cwd: string, preferredModelProvider: string | undefined): string {
2670
+ function discoveryCacheKey(cwd: string, preferredModelProvider: string | undefined, globalNpmRoot?: string | null): string {
2595
2671
  return JSON.stringify([
2596
2672
  path.resolve(cwd),
2597
2673
  preferredModelProvider ?? null,
2674
+ globalNpmRoot === undefined ? ["default"] : ["override", globalNpmRoot],
2598
2675
  getProjectConfigDir(path.resolve(cwd)),
2599
2676
  getAgentDir(),
2600
2677
  os.homedir(),
@@ -2623,7 +2700,7 @@ function packageEntryIncluded(scope: AgentScope, packageScopes: PackageSubagentP
2623
2700
  return packageScopes.has(scope);
2624
2701
  }
2625
2702
 
2626
- function buildAgentDiscoverySources(cwd: string, preferredModelProvider?: string): AgentDiscoverySources {
2703
+ function buildAgentDiscoverySources(cwd: string, preferredModelProvider?: string, globalNpmRoot?: string | null): AgentDiscoverySources {
2627
2704
  const effectiveCwd = path.resolve(cwd);
2628
2705
  const userDirOld = path.join(getAgentDir(), "agents");
2629
2706
  const userDirNew = path.join(os.homedir(), ".agents");
@@ -2632,7 +2709,7 @@ function buildAgentDiscoverySources(cwd: string, preferredModelProvider?: string
2632
2709
  const { readDirs: projectChainDirs, preferredDir: projectChainDir } = resolveNearestProjectChainDirs(effectiveCwd);
2633
2710
  const userSettingsPath = getUserAgentSettingsPath();
2634
2711
  const projectSettingsPath = getProjectAgentSettingsPath(effectiveCwd);
2635
- const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd);
2712
+ const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: true, includeProject: true, globalNpmRoot });
2636
2713
  const exclusionRoots = agentExclusionRoots(userSettingsPath, projectSettingsPath);
2637
2714
  const isExcluded = agentExclusions(exclusionRoots);
2638
2715
  const userScanDirs = settingsAgentScanDirs(readConfiguredAgentScanDirs(userSettingsPath), isExcluded);
@@ -2718,8 +2795,8 @@ function ensureDiscoveryChains(sources: AgentDiscoverySources): void {
2718
2795
  sources.watchPaths = [...new Set([...sources.watchPaths, ...watchPaths])];
2719
2796
  }
2720
2797
 
2721
- function getAgentDiscoverySources(cwd: string, preferredModelProvider?: string, includeChains = false): AgentDiscoverySources {
2722
- const key = discoveryCacheKey(cwd, preferredModelProvider);
2798
+ function getAgentDiscoverySources(cwd: string, preferredModelProvider?: string, includeChains = false, globalNpmRoot?: string | null): AgentDiscoverySources {
2799
+ const key = discoveryCacheKey(cwd, preferredModelProvider, globalNpmRoot);
2723
2800
  const cached = agentDiscoveryCache.get(key);
2724
2801
  if (cached && cached.fingerprint === discoveryFingerprint(cached.sources)) {
2725
2802
  if (includeChains) {
@@ -2728,7 +2805,7 @@ function getAgentDiscoverySources(cwd: string, preferredModelProvider?: string,
2728
2805
  }
2729
2806
  return cached.sources;
2730
2807
  }
2731
- const sources = buildAgentDiscoverySources(cwd, preferredModelProvider);
2808
+ const sources = buildAgentDiscoverySources(cwd, preferredModelProvider, globalNpmRoot);
2732
2809
  const entry = { sources, fingerprint: discoveryFingerprint(sources) };
2733
2810
  agentDiscoveryCache.set(key, entry);
2734
2811
  if (includeChains) {
@@ -2781,7 +2858,8 @@ function configuredAgentsForScope(sources: AgentDiscoverySources, scope: AgentSc
2781
2858
  const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, sources.projectSettingsPath);
2782
2859
  const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, sources.projectSettingsPath);
2783
2860
  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, sources.projectSettingsPath);
2784
- const applyDefaults = (agents: AgentConfig[]): AgentConfig[] => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions);
2861
+ const defaultSubagentOnlyExtensions = resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, sources.projectSettingsPath);
2862
+ const applyDefaults = (agents: AgentConfig[]): AgentConfig[] => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions);
2785
2863
  const builtin = applyBuiltinOverrides(applyDefaults(sources.builtinLoaded.agents), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
2786
2864
  const user = applyCustomAgentOverrides(
2787
2865
  applyDefaults(scope === "project" ? [] : sources.userLoaded.flatMap((loaded) => loaded.loaded.agents)),
@@ -2901,6 +2979,7 @@ function buildAllDiscovery(sources: AgentDiscoverySources, includeChains: boolea
2901
2979
  ],
2902
2980
  chains,
2903
2981
  chainDiagnostics: [...packageChainDiagnostics, ...(sources.userChains?.diagnostics ?? []), ...projectChainDiagnostics],
2982
+ cwd: sources.cwd,
2904
2983
  userDir: sources.userDir,
2905
2984
  projectDir: sources.projectAgentsDir,
2906
2985
  userChainDir: sources.userChainDir,
@@ -2916,14 +2995,14 @@ export function discoverAgentSnapshot(
2916
2995
  cwd: string,
2917
2996
  scope: AgentScope,
2918
2997
  preferredModelProvider?: string,
2919
- options: { includeChains?: boolean } = {},
2998
+ options: AgentDiscoveryOptions & { includeChains?: boolean } = {},
2920
2999
  ): AgentDiscoverySnapshot {
2921
3000
  const includeChains = options.includeChains !== false;
2922
- const sources = getAgentDiscoverySources(cwd, preferredModelProvider, includeChains);
3001
+ const sources = getAgentDiscoverySources(cwd, preferredModelProvider, includeChains, options.globalNpmRoot);
2923
3002
  return { effective: buildEffectiveDiscovery(sources, scope), all: buildAllDiscovery(sources, includeChains, scope) };
2924
3003
  }
2925
3004
 
2926
- function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelProvider?: string): AgentDiscoveryResult {
3005
+ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelProvider?: string, options: AgentDiscoveryOptions = {}): AgentDiscoveryResult {
2927
3006
  const effectiveCwd = path.resolve(cwd);
2928
3007
  const userDirOld = path.join(getAgentDir(), "agents");
2929
3008
  const userDirNew = path.join(os.homedir(), ".agents");
@@ -2937,15 +3016,17 @@ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelPr
2937
3016
  const defaultThinking = resolveSubagentDefaultThinking(userSettings, projectSettings, projectSettingsPath);
2938
3017
  const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
2939
3018
  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
3019
+ const defaultSubagentOnlyExtensions = resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, projectSettingsPath);
2940
3020
  const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
2941
3021
  const injectAgents = projectSettings.injectAgents !== undefined
2942
3022
  ? projectSettings.injectAgents
2943
3023
  : userSettings.injectAgents;
2944
- const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: scope !== "project", includeProject: scope !== "user" });
3024
+ const packageSubagentPaths = collectPackageSubagentPaths(effectiveCwd, { includeUser: scope !== "project", includeProject: scope !== "user", globalNpmRoot: options.globalNpmRoot });
2945
3025
  const isExcluded = agentExclusions(agentExclusionRoots(userSettingsPath, projectSettingsPath));
2946
3026
  const directories: AgentDefinitionDirectoryReport[] = [reportAgentDefinitionDirectory("builtin", BUILTIN_AGENTS_DIR, BUILTIN_AGENT_DEFINITION_INSPECTION)];
2947
3027
  const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
2948
- const builtinAgents = applyBuiltinOverrides(applySubagentDefaults(builtinLoaded.agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
3028
+ const applyDefaults = (agents: AgentConfig[]): AgentConfig[] => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions);
3029
+ const builtinAgents = applyBuiltinOverrides(applyDefaults(builtinLoaded.agents), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
2949
3030
  const userScanDirs = settingsAgentScanDirs(userSettings.agentScanDirs ?? [], isExcluded);
2950
3031
  const projectScanDirs = settingsAgentScanDirs(projectSettings.agentScanDirs ?? [], isExcluded);
2951
3032
  const userLoaded = scope === "project" ? [] : [...extraUserAgentDirs(), ...userScanDirs.dirs, userDirOld, userDirNew].filter((dir) => !isExcluded(dir)).map((dir, discoveryPriority) => {
@@ -2953,7 +3034,7 @@ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelPr
2953
3034
  directories.push(reportAgentDefinitionDirectory("user", dir, inspection));
2954
3035
  return loadAgentsFromDir(dir, "user", discoveryPriority, undefined, inspection);
2955
3036
  });
2956
- const userAgents = applyCustomAgentOverrides(applySubagentDefaults(userLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
3037
+ const userAgents = applyCustomAgentOverrides(applyDefaults(userLoaded.flatMap((loaded) => loaded.agents)), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
2957
3038
  const projectInspections = scope === "user" ? new Map<string, AgentDefinitionInspection>() : new Map(projectCandidateDirs.filter((dir) => !isExcluded(dir)).map((dir) => [dir, inspectAgentDefinitionDirectory(dir, undefined, isExcluded)]));
2958
3039
  if (scope !== "user") for (const [dir, inspection] of projectInspections) directories.push(reportAgentDefinitionDirectory("project", dir, inspection));
2959
3040
  const projectLoaded = scope === "user" ? [] : [...projectScanDirs.dirs, ...projectAgentDirs].filter((dir) => !isExcluded(dir)).map((dir, discoveryPriority) => {
@@ -2961,7 +3042,7 @@ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelPr
2961
3042
  if (!projectInspections.has(dir)) directories.push(reportAgentDefinitionDirectory("project", dir, inspection));
2962
3043
  return loadAgentsFromDir(dir, "project", dir === projectAgentsDir ? 1 : discoveryPriority, undefined, inspection);
2963
3044
  });
2964
- const projectAgents = applyCustomAgentOverrides(applySubagentDefaults(projectLoaded.flatMap((loaded) => loaded.agents), defaultModel, defaultProvider, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
3045
+ const projectAgents = applyCustomAgentOverrides(applyDefaults(projectLoaded.flatMap((loaded) => loaded.agents)), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
2965
3046
  const packageLoaded = packageSubagentPaths.agents.filter((entry) => !isExcluded(entry.dir)).map((entry, index) => {
2966
3047
  const inspection = inspectAgentDefinitionDirectory(entry.dir, undefined, isExcluded);
2967
3048
  directories.push(reportAgentDefinitionDirectory("package", entry.dir, inspection));
@@ -2969,18 +3050,18 @@ function discoverAgentsUncached(cwd: string, scope: AgentScope, preferredModelPr
2969
3050
  });
2970
3051
  const packageMap = new Map<string, AgentConfig>();
2971
3052
  for (const loaded of packageLoaded) for (const agent of loaded.agents) if (!packageMap.has(agent.name)) packageMap.set(agent.name, agent);
2972
- const packageAgents = applyCustomAgentOverrides(applySubagentDefaults(Array.from(packageMap.values()), defaultModel, defaultProvider, defaultThinking, defaultExtensions), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
3053
+ const packageAgents = applyCustomAgentOverrides(applyDefaults(Array.from(packageMap.values())), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
2973
3054
  const agents = applySubagentMaxThinking(mergeAgentsForScope(scope, userAgents, projectAgents, builtinAgents, packageAgents).filter((agent) => agent.disabled !== true), maxThinking);
2974
3055
  const agentDiagnostics = [...builtinLoaded.diagnostics, ...userLoaded.flatMap((loaded) => loaded.diagnostics), ...projectLoaded.flatMap((loaded) => loaded.diagnostics), ...packageLoaded.flatMap((loaded) => loaded.diagnostics)];
2975
3056
  return { agents, agentDiagnostics, projectAgentsDir, cwd: effectiveCwd, scope, directories, ...(modelScope !== undefined ? { modelScope } : {}), ...(injectAgents?.length ? { injectAgents } : {}), ...(maxThinking !== undefined ? { maxThinking } : {}) };
2976
3057
  }
2977
3058
 
2978
- export function discoverAgents(cwd: string, scope: AgentScope, preferredModelProvider?: string): AgentDiscoveryResult {
2979
- if (scope !== "both") return discoverAgentsUncached(cwd, scope, preferredModelProvider);
2980
- const sources = getAgentDiscoverySources(cwd, preferredModelProvider);
3059
+ export function discoverAgents(cwd: string, scope: AgentScope, preferredModelProvider?: string, options: AgentDiscoveryOptions = {}): AgentDiscoveryResult {
3060
+ if (scope !== "both") return discoverAgentsUncached(cwd, scope, preferredModelProvider, options);
3061
+ const sources = getAgentDiscoverySources(cwd, preferredModelProvider, false, options.globalNpmRoot);
2981
3062
  return buildEffectiveDiscovery(sources, scope);
2982
3063
  }
2983
3064
 
2984
- export function discoverAgentsAll(cwd: string, preferredModelProvider?: string): AgentDiscoveryAllResult {
2985
- return discoverAgentSnapshot(cwd, "both", preferredModelProvider).all;
3065
+ export function discoverAgentsAll(cwd: string, preferredModelProvider?: string, options: AgentDiscoveryOptions = {}): AgentDiscoveryAllResult {
3066
+ return discoverAgentSnapshot(cwd, "both", preferredModelProvider, options).all;
2986
3067
  }
@@ -0,0 +1,58 @@
1
+ import { exec, execFile } from "node:child_process";
2
+ import { promises as fs } from "node:fs";
3
+ import path from "node:path";
4
+
5
+ /** Optional global package discovery; a failure never prevents local discovery. */
6
+ export async function resolveGlobalNpmRoot(options: {
7
+ env?: NodeJS.ProcessEnv;
8
+ platform?: NodeJS.Platform;
9
+ timeoutMs?: number;
10
+ } = {}): Promise<string | null> {
11
+ const env = options.env ?? process.env;
12
+ const offline = env.PI_OFFLINE?.toLowerCase();
13
+ if (offline === "1" || offline === "true" || offline === "yes") return null;
14
+
15
+ if ((options.platform ?? process.platform) === "win32" && env.APPDATA) {
16
+ const appDataRoot = path.join(env.APPDATA, "npm", "node_modules");
17
+ try {
18
+ if ((await fs.stat(appDataRoot)).isDirectory()) return await fs.realpath(appDataRoot);
19
+ } catch {
20
+ // Invalid APPDATA roots fall back to npm (including disappearing directories).
21
+ }
22
+ }
23
+
24
+ const timeoutMs = options.timeoutMs ?? 5000;
25
+ const output = await new Promise<string | null>((resolve) => {
26
+ let settled = false;
27
+ const finish = (value: string | null) => {
28
+ if (settled) return;
29
+ settled = true;
30
+ clearTimeout(timer);
31
+ resolve(value);
32
+ };
33
+ const commandOptions = {
34
+ encoding: "utf8",
35
+ timeout: timeoutMs,
36
+ windowsHide: true,
37
+ env,
38
+ maxBuffer: 64 * 1024,
39
+ } as const;
40
+ // POSIX npm is executable directly: killing a shell would leave npm running.
41
+ // Windows npm.cmd requires a shell, matching the existing command behavior.
42
+ const callback = (error: Error | null, stdout: string) => finish(error ? null : stdout.trim());
43
+ const child = (options.platform ?? process.platform) === "win32"
44
+ ? exec("npm root -g", commandOptions, callback)
45
+ : execFile("npm", ["root", "-g"], commandOptions, callback);
46
+ // Resolve at the deadline even if inherited pipes hold the callback open.
47
+ const timer = setTimeout(() => {
48
+ child.kill();
49
+ finish(null);
50
+ }, timeoutMs);
51
+ });
52
+ if (!output) return null;
53
+ try {
54
+ return await fs.realpath(output);
55
+ } catch {
56
+ return null;
57
+ }
58
+ }
@@ -27,6 +27,7 @@ export interface ProactiveSkillSubagentRecommendation {
27
27
  export interface AvailableSkill {
28
28
  name: string;
29
29
  description?: string;
30
+ disableModelInvocation?: boolean;
30
31
  }
31
32
 
32
33
  function positiveInteger(value: unknown): number | undefined {
@@ -140,7 +141,9 @@ export function recommendProactiveSkillSubagents(input: {
140
141
  }
141
142
 
142
143
  return [...counts.entries()]
143
- .filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)))
144
+ // Hidden skills (disable-model-invocation: true) are user-only and must
145
+ // never surface in model-facing proactive recommendations.
146
+ .filter(([skill, sources]) => sources.size >= config.minReferences && (!availableByName || availableByName.has(skill)) && availableByName?.get(skill)?.disableModelInvocation !== true)
144
147
  .map(([skill, sources]) => {
145
148
  const description = availableByName?.get(skill)?.description;
146
149
  return {