@xzzpig/pi-subagents 0.8.0 → 0.9.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 (218) hide show
  1. package/CHANGELOG.md +443 -0
  2. package/README.md +2 -2
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +151 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +5 -4
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +370 -114
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +12 -2
  35. package/src/agents/agents.ts +919 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +31 -20
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +48 -18
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +57 -21
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +2 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +366 -128
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +45 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +189 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +676 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +468 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1172 -400
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +314 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +342 -0
  115. package/src/runs/shared/child-tool-plan.ts +540 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +142 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +38 -48
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +15 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/single-output.ts +89 -22
  149. package/src/runs/shared/structured-output.ts +49 -9
  150. package/src/runs/shared/subagent-control.ts +6 -2
  151. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  152. package/src/runs/shared/task-intent.ts +21 -7
  153. package/src/runs/shared/tool-availability.ts +18 -62
  154. package/src/runs/shared/tool-budget.ts +0 -14
  155. package/src/runs/shared/tool-timeout.ts +1 -1
  156. package/src/runs/shared/workflow-graph.ts +16 -0
  157. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  158. package/src/runs/shared/worktree.ts +571 -62
  159. package/src/shared/atomic-json.ts +3 -1
  160. package/src/shared/child-session-name.ts +46 -0
  161. package/src/shared/extension-context.ts +24 -0
  162. package/src/shared/fork-context.ts +21 -12
  163. package/src/shared/fork-session-cwd.ts +27 -0
  164. package/src/shared/formatters.ts +18 -3
  165. package/src/shared/jsonl-writer.ts +11 -0
  166. package/src/shared/launch-contract.ts +8 -1
  167. package/src/shared/pruned-fork.ts +450 -0
  168. package/src/shared/session-file-trust.ts +19 -0
  169. package/src/shared/session-tokens.ts +14 -3
  170. package/src/shared/settings.ts +19 -105
  171. package/src/shared/shortcuts.ts +17 -0
  172. package/src/shared/thinking-ceiling.ts +0 -6
  173. package/src/shared/types.ts +524 -70
  174. package/src/shared/utils.ts +60 -93
  175. package/src/shared/workflow-child-permit.ts +207 -0
  176. package/src/slash/delegation-adapters.ts +1 -9
  177. package/src/slash/delegation-request.ts +0 -4
  178. package/src/slash/prompt-template-bridge.ts +37 -1
  179. package/src/slash/slash-bridge.ts +1 -2
  180. package/src/slash/slash-commands.ts +383 -116
  181. package/src/slash/slash-live-state.ts +22 -11
  182. package/src/slash/subagents-admin.ts +29 -12
  183. package/src/tui/fleet-native-transcript.ts +4 -0
  184. package/src/tui/fleet-status.ts +217 -82
  185. package/src/tui/fleet-transcript.ts +11 -5
  186. package/src/tui/fleet.ts +54 -28
  187. package/src/tui/render-helpers.ts +31 -0
  188. package/src/tui/render.ts +1429 -163
  189. package/src/watchdog/change-signature.ts +40 -1
  190. package/src/watchdog/child-status.ts +54 -34
  191. package/src/watchdog/diff-tool.ts +77 -0
  192. package/src/watchdog/emission-guard.ts +5 -3
  193. package/src/watchdog/guidance.ts +20 -0
  194. package/src/watchdog/register-child.ts +28 -25
  195. package/src/watchdog/register-main.ts +10 -9
  196. package/src/watchdog/render.ts +4 -5
  197. package/src/watchdog/review.ts +15 -4
  198. package/src/watchdog/rules.ts +70 -0
  199. package/src/watchdog/runtime.ts +75 -92
  200. package/src/watchdog/scope.ts +0 -11
  201. package/src/watchdog/settings.ts +48 -104
  202. package/src/watchdog/turn-delta.ts +1 -1
  203. package/src/watchdog/types.ts +18 -32
  204. package/src/watchdog/warning-format.ts +0 -1
  205. package/src/workflows/chat-progress.ts +7 -3
  206. package/src/workflows/host-command.ts +235 -0
  207. package/src/workflows/scripted-workflow.ts +988 -59
  208. package/src/workflows/workflow-checklist.ts +439 -0
  209. package/src/workflows/workflow-child-summary.ts +121 -0
  210. package/src/workflows/workflow-preflight.ts +297 -0
  211. package/src/workflows/workflow-receipt.ts +232 -6
  212. package/src/workflows/workflow-resources.ts +150 -0
  213. package/src/workflows/workflow-settlement.ts +246 -0
  214. package/src/runs/shared/child-protocol.ts +0 -401
  215. package/src/runs/shared/pi-args.ts +0 -935
  216. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  217. package/src/runs/shared/turn-budget.ts +0 -98
  218. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -7,7 +7,6 @@ import {
7
7
  type AgentDiscoveryDiagnostic,
8
8
  type AgentScope,
9
9
  type AgentSource,
10
- BUILTIN_AGENT_NAMES,
11
10
  defaultInheritProjectContext,
12
11
  defaultInheritSkills,
13
12
  defaultSystemPromptMode,
@@ -29,16 +28,18 @@ import {
29
28
  buildProactiveSkillSubagentRecommendationLines,
30
29
  } from "./proactive-skills.ts";
31
30
  import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.ts";
32
- import { resolvePiLaunchToolPlan } from "../runs/shared/pi-args.ts";
33
- import { toModelInfo } from "../shared/model-info.ts";
31
+ import { resolvePiLaunchToolPlan } from "../runs/shared/child-tool-plan.ts";
32
+ import { resolveEffectiveThinking, toModelInfo } from "../shared/model-info.ts";
34
33
  import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
35
34
  import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
36
- import { resolveTurnBudgetConfig } from "../runs/shared/turn-budget.ts";
37
35
  import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
38
- import type { AcceptanceInput, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
36
+ import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, resolveExternalCliRunnerStatus, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
37
+ import { resolveExternalCliBinaryAvailability, type ExternalCliBinaryAvailability } from "../runs/shared/external-cli-preflight.ts";
38
+ import type { AcceptanceInput, AgentCapabilitiesSnapshot, AgentCapabilityRow, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
39
39
  import { getProjectConfigDir } from "../shared/utils.ts";
40
+ import { previewDisplayText } from "../shared/display-text.ts";
40
41
  import { capabilityCeilingAgentRestrictionSources, isAgentAllowedByCapabilityCeiling, resolveCurrentSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
41
- import { listRuntimeAgentConfigs, mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
42
+ import { mergeRuntimeAgents, type RuntimeAgentOwner } from "./runtime-agent-registry.ts";
42
43
  import { listExternalJobProviders } from "../api/external-job-provider.ts";
43
44
 
44
45
  export const AGENT_MANAGEMENT_API_VERSION = 1 as const;
@@ -103,11 +104,21 @@ interface ManagementParams {
103
104
  action?: string;
104
105
  agent?: string;
105
106
  agentScope?: unknown;
107
+ capabilities?: unknown;
106
108
  config?: unknown;
107
109
  }
108
110
 
109
- function result(text: string, isError = false): AgentToolResult<Details> {
110
- return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
111
+ function result(text: string, isError = false, details?: Partial<Details>): AgentToolResult<Details> {
112
+ return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [], ...details } };
113
+ }
114
+
115
+ function jsonDetails<T>(value: T): T {
116
+ return JSON.parse(JSON.stringify(value)) as T;
117
+ }
118
+
119
+ function presentDetails<T extends Record<string, unknown>>(value: T): T | undefined {
120
+ const cleaned = jsonDetails(value);
121
+ return Object.keys(cleaned).length > 0 ? cleaned : undefined;
111
122
  }
112
123
 
113
124
  function parseCsv(value: string): string[] {
@@ -174,18 +185,39 @@ function allAgents(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: Ag
174
185
  return [...d.builtin, ...d.package, ...d.user, ...d.project];
175
186
  }
176
187
 
177
- function availableAgentNamesFromDiscovery(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }): string[] {
178
- return [...new Set(allAgents(d).map((agent) => agent.name))].sort((a, b) => a.localeCompare(b));
188
+ function effectiveAgentsForScope(
189
+ scope: AgentScope,
190
+ d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
191
+ runtimeAgentOwner?: RuntimeAgentOwner,
192
+ ): AgentConfig[] {
193
+ let agents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
194
+ if (runtimeAgentOwner) {
195
+ agents = mergeRuntimeAgents(runtimeAgentOwner, { agents }, allAgents(d)).agents;
196
+ }
197
+ return agents;
198
+ }
199
+
200
+ function availableAgentNamesFromDiscovery(
201
+ d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
202
+ runtimeAgentOwner?: RuntimeAgentOwner,
203
+ ): string[] {
204
+ const agents = runtimeAgentOwner ? effectiveAgentsForScope("both", d, runtimeAgentOwner) : allAgents(d);
205
+ return [...new Set(agents.map((agent) => agent.name))].sort((a, b) => a.localeCompare(b));
179
206
  }
180
207
 
181
208
  function availableAgentNames(cwd: string): string[] {
182
209
  return availableAgentNamesFromDiscovery(discoverAgentsAll(cwd));
183
210
  }
184
211
 
185
- function findAgentsInDiscovery(name: string, d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }, scope: AgentScope = "both"): AgentConfig[] {
212
+ function findAgentsInDiscovery(
213
+ name: string,
214
+ d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
215
+ scope: AgentScope = "both",
216
+ runtimeAgentOwner?: RuntimeAgentOwner,
217
+ ): AgentConfig[] {
186
218
  const raw = name.trim();
187
219
  const sanitized = sanitizeName(raw);
188
- const scoped = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
220
+ const scoped = effectiveAgentsForScope(scope, d, runtimeAgentOwner);
189
221
  let resolved = resolveAgentName(raw, scoped);
190
222
  if (!resolved.agent && !resolved.error && sanitized !== raw) resolved = resolveAgentName(sanitized, scoped);
191
223
  if (resolved.agent) return scoped.filter((agent) => agent.name === resolved.agent!.name).sort((a, b) => a.source.localeCompare(b.source));
@@ -275,16 +307,29 @@ function withDeclaredExtensionPaths(config: AgentConfig, filePath: string): Agen
275
307
  export function editableAgentConfig(agent: AgentConfig): AgentConfig {
276
308
  const { extensions: _extensions, ...withoutExtensions } = agent;
277
309
  const base = agent.override?.base;
310
+ const description = base?.description ?? agent.description;
311
+ const frontmatterFields = agent.source === "builtin" || agent.source === "runtime" ? undefined : readAgentFrontmatterFields(agent.filePath);
312
+ const hasDeclaredField = (...fields: string[]) => frontmatterFields === undefined || fields.some((field) => frontmatterFields.has(field));
313
+ const withoutSettingsDefaults = (config: AgentConfig): AgentConfig => {
314
+ if (!frontmatterFields) return config;
315
+ const next = { ...config };
316
+ if (!hasDeclaredField("model")) delete next.model;
317
+ if (!hasDeclaredField("thinking")) delete next.thinking;
318
+ return next;
319
+ };
278
320
  const {
279
321
  override: _override,
322
+ description: _description,
280
323
  output: _output,
281
324
  outputMode: _outputMode,
282
325
  defaultReads: _defaultReads,
283
326
  model: _model,
284
327
  fallbackModels: _fallbackModels,
328
+ fast: _fast,
285
329
  thinking: _thinking,
286
330
  systemPromptMode: _systemPromptMode,
287
331
  inheritProjectContext: _inheritProjectContext,
332
+ inheritGlobalContext: _inheritGlobalContext,
288
333
  inheritSkills: _inheritSkills,
289
334
  defaultContext: _defaultContext,
290
335
  acceptanceRole: _acceptanceRole,
@@ -293,28 +338,35 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
293
338
  skills: _skills,
294
339
  skillPath: _skillPath,
295
340
  tools: _tools,
341
+ excludeTools: _excludeTools,
296
342
  mcpDirectTools: _mcpDirectTools,
343
+ allowNestedSubagents: _allowNestedSubagents,
297
344
  subagentOnlyExtensions: _subagentOnlyExtensions,
345
+ mutationTools: _mutationTools,
298
346
  completionGuard: _completionGuard,
347
+ toolBudget: _toolBudget,
299
348
  ...editable
300
349
  } = withoutExtensions;
301
350
  if (!base) {
302
- return withDeclaredExtensionPaths({
351
+ return withDeclaredExtensionPaths(withoutSettingsDefaults({
303
352
  ...withoutExtensions,
304
353
  ...(agent.extensionsFromDefault ? {} : agent.extensions !== undefined ? { extensions: [...agent.extensions] } : {}),
305
- }, agent.filePath);
354
+ }), agent.filePath);
306
355
  }
307
356
 
308
357
  return withDeclaredExtensionPaths({
309
358
  ...editable,
359
+ description,
310
360
  ...(base.output !== undefined ? { output: base.output } : {}),
311
361
  ...(base.outputMode !== undefined ? { outputMode: base.outputMode } : {}),
312
362
  ...(base.defaultReads !== undefined ? { defaultReads: [...base.defaultReads] } : {}),
313
- ...(base.model !== undefined ? { model: base.model } : {}),
363
+ ...(base.model !== undefined && hasDeclaredField("model") ? { model: base.model } : {}),
314
364
  ...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
315
- ...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
365
+ ...(base.fast !== undefined ? { fast: base.fast } : {}),
366
+ ...(base.thinking !== undefined && hasDeclaredField("thinking") ? { thinking: base.thinking } : {}),
316
367
  systemPromptMode: base.systemPromptMode,
317
368
  inheritProjectContext: base.inheritProjectContext,
369
+ inheritGlobalContext: base.inheritGlobalContext,
318
370
  inheritSkills: base.inheritSkills,
319
371
  ...(base.defaultContext !== undefined ? { defaultContext: base.defaultContext } : {}),
320
372
  ...(base.acceptanceRole !== undefined ? { acceptanceRole: base.acceptanceRole } : {}),
@@ -323,10 +375,14 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
323
375
  ...(base.skills !== undefined ? { skills: [...base.skills] } : {}),
324
376
  ...(base.skillPath !== undefined ? { skillPath: [...base.skillPath] } : {}),
325
377
  ...(base.tools !== undefined ? { tools: [...base.tools] } : {}),
378
+ ...(base.excludeTools !== undefined ? { excludeTools: [...base.excludeTools] } : {}),
326
379
  ...(base.mcpDirectTools !== undefined ? { mcpDirectTools: [...base.mcpDirectTools] } : {}),
380
+ ...(base.allowNestedSubagents !== undefined ? { allowNestedSubagents: base.allowNestedSubagents } : {}),
327
381
  ...(base.extensions !== undefined ? { extensions: [...base.extensions] } : {}),
328
382
  ...(base.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...base.subagentOnlyExtensions] } : {}),
383
+ ...(base.mutationTools !== undefined ? { mutationTools: [...base.mutationTools] } : {}),
329
384
  ...(base.completionGuard !== undefined ? { completionGuard: base.completionGuard } : {}),
385
+ ...(base.toolBudget !== undefined ? { toolBudget: base.toolBudget } : {}),
330
386
  }, agent.filePath);
331
387
  }
332
388
 
@@ -354,10 +410,12 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
354
410
  if (hasKey(cfg, "model")) changed("model");
355
411
  if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
356
412
  if (hasKey(cfg, "tools")) changed("tools");
413
+ if (hasKey(cfg, "excludeTools")) changed("excludeTools");
357
414
  if (hasKey(cfg, "skills")) changed("skill", "skills");
358
415
  if (hasKey(cfg, "skillPath")) changed("skillPath");
359
416
  if (hasKey(cfg, "extensions")) changed("extensions");
360
417
  if (hasKey(cfg, "subagentOnlyExtensions")) changed("subagentOnlyExtensions");
418
+ if (hasKey(cfg, "mutationTools")) changed("mutationTools");
361
419
  if (hasKey(cfg, "thinking")) {
362
420
  changed("thinking");
363
421
  if (cfg.thinking === "off") fields.add("thinking");
@@ -370,6 +428,10 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
370
428
  changed("inheritProjectContext");
371
429
  fields.add("inheritProjectContext");
372
430
  }
431
+ if (hasKey(cfg, "inheritGlobalContext")) {
432
+ changed("inheritGlobalContext");
433
+ fields.add("inheritGlobalContext");
434
+ }
373
435
  if (hasKey(cfg, "inheritSkills")) {
374
436
  changed("inheritSkills");
375
437
  fields.add("inheritSkills");
@@ -377,7 +439,6 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
377
439
  if (hasKey(cfg, "defaultContext")) changed("defaultContext");
378
440
  if (hasKey(cfg, "async")) changed("async");
379
441
  if (hasKey(cfg, "timeoutMs")) changed("timeoutMs");
380
- if (hasKey(cfg, "turnBudget")) changed("turnBudget");
381
442
  if (hasKey(cfg, "acceptance")) changed("acceptance");
382
443
  if (hasKey(cfg, "acceptanceRole")) changed("acceptanceRole");
383
444
  if (hasKey(cfg, "output")) changed("output");
@@ -434,15 +495,17 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
434
495
  if (runner.type === "pi" && Object.keys(runner).every((key) => key === "type")) target.runner = { type: "pi" };
435
496
  else if (runner.type === "external-cli" && typeof runner.command === "string" && runner.command.trim()
436
497
  && (runner.args === undefined || (Array.isArray(runner.args) && runner.args.every((arg) => typeof arg === "string")))
498
+ && (runner.adapter === undefined || isCodeOwnedExternalCliAdapterId(runner.adapter))
499
+ && (runner.adapter === undefined || runner.args === undefined || runner.args.length === 0)
437
500
  && (runner.promptDelivery === undefined || runner.promptDelivery === "stdin")
438
- && Object.keys(runner).every((key) => ["type", "command", "args", "promptDelivery"].includes(key))) {
501
+ && Object.keys(runner).every((key) => ["type", "adapter", "command", "args", "promptDelivery"].includes(key))) {
439
502
  const runnerArgs = Array.isArray(runner.args) ? runner.args.filter((arg): arg is string => typeof arg === "string") : undefined;
440
- target.runner = { type: "external-cli", command: runner.command.trim(), ...(runnerArgs?.length ? { args: runnerArgs } : {}), ...(runner.promptDelivery ? { promptDelivery: "stdin" } : {}) };
503
+ target.runner = { type: "external-cli", ...(isCodeOwnedExternalCliAdapterId(runner.adapter) ? { adapter: runner.adapter } : {}), command: runner.command.trim(), ...(runnerArgs?.length ? { args: runnerArgs } : {}), ...(runner.promptDelivery ? { promptDelivery: "stdin" } : {}) };
441
504
  } else if (runner.type === "external-job" && typeof runner.provider === "string" && runner.provider.trim() === runner.provider && runner.provider
442
505
  && (runner.options === undefined || (runner.options && typeof runner.options === "object" && !Array.isArray(runner.options) && isJsonSerializable(runner.options)))
443
506
  && Object.keys(runner).every((key) => ["type", "provider", "options"].includes(key))) {
444
507
  target.runner = { type: "external-job", provider: runner.provider, ...(runner.options ? { options: runner.options as Record<string, unknown> } : {}) };
445
- } else return "config.runner must be { type: 'pi' }, { type: 'external-cli', command: string, args?: string[], promptDelivery?: 'stdin' }, or { type: 'external-job', provider: string, options?: object }.";
508
+ } else return `config.runner must be { type: 'pi' }, { type: 'external-cli', adapter?: ${CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL}, command: string, args?: string[], promptDelivery?: 'stdin' }, or { type: 'external-job', provider: string, options?: object }.`;
446
509
  } else return "config.runner must be an object, false, or empty string when provided.";
447
510
  }
448
511
  if (hasKey(cfg, "model")) {
@@ -478,6 +541,18 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
478
541
  else delete target.mcpDirectTools;
479
542
  } else return "config.tools must be a comma-separated string or false when provided.";
480
543
  }
544
+ if (hasKey(cfg, "excludeTools")) {
545
+ if (cfg.excludeTools === false || cfg.excludeTools === "") delete target.excludeTools;
546
+ else if (typeof cfg.excludeTools === "string") {
547
+ const excludeTools = parseCsv(cfg.excludeTools);
548
+ if (excludeTools.length) target.excludeTools = [...new Set(excludeTools)];
549
+ else delete target.excludeTools;
550
+ } else if (Array.isArray(cfg.excludeTools) && cfg.excludeTools.every((entry) => typeof entry === "string")) {
551
+ const excludeTools = [...new Set(cfg.excludeTools.map((entry) => entry.trim()).filter(Boolean))];
552
+ if (excludeTools.length) target.excludeTools = excludeTools;
553
+ else delete target.excludeTools;
554
+ } else return "config.excludeTools must be a comma-separated string, string array, or false when provided.";
555
+ }
481
556
  if (hasKey(cfg, "skills")) {
482
557
  if (cfg.skills === false || cfg.skills === "") delete target.skills;
483
558
  else if (typeof cfg.skills === "string") {
@@ -510,6 +585,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
510
585
  else if (typeof cfg.subagentOnlyExtensions === "string") target.subagentOnlyExtensions = parseCsv(cfg.subagentOnlyExtensions);
511
586
  else return "config.subagentOnlyExtensions must be a comma-separated string, empty string, or false when provided.";
512
587
  }
588
+ if (hasKey(cfg, "mutationTools")) {
589
+ if (cfg.mutationTools === false) delete target.mutationTools;
590
+ else if (cfg.mutationTools === "") target.mutationTools = [];
591
+ else if (typeof cfg.mutationTools === "string") target.mutationTools = parseCsv(cfg.mutationTools);
592
+ else return "config.mutationTools must be a comma-separated string, empty string, or false when provided.";
593
+ }
513
594
  if (hasKey(cfg, "thinking")) {
514
595
  if (cfg.thinking === false || cfg.thinking === "") delete target.thinking;
515
596
  else if (typeof cfg.thinking === "string") {
@@ -526,6 +607,10 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
526
607
  if (typeof cfg.inheritProjectContext !== "boolean") return "config.inheritProjectContext must be a boolean when provided.";
527
608
  target.inheritProjectContext = cfg.inheritProjectContext;
528
609
  }
610
+ if (hasKey(cfg, "inheritGlobalContext")) {
611
+ if (typeof cfg.inheritGlobalContext !== "boolean") return "config.inheritGlobalContext must be a boolean when provided.";
612
+ target.inheritGlobalContext = cfg.inheritGlobalContext;
613
+ }
529
614
  if (hasKey(cfg, "inheritSkills")) {
530
615
  if (typeof cfg.inheritSkills !== "boolean") return "config.inheritSkills must be a boolean when provided.";
531
616
  target.inheritSkills = cfg.inheritSkills;
@@ -545,15 +630,6 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
545
630
  else if (typeof cfg.timeoutMs === "number" && Number.isInteger(cfg.timeoutMs) && cfg.timeoutMs > 0) target.defaultTimeoutMs = cfg.timeoutMs;
546
631
  else return "config.timeoutMs must be a positive integer or false when provided.";
547
632
  }
548
- if (hasKey(cfg, "turnBudget")) {
549
- if (cfg.turnBudget === false || cfg.turnBudget === "") delete target.defaultTurnBudget;
550
- else {
551
- const resolved = resolveTurnBudgetConfig(cfg.turnBudget, "config.turnBudget");
552
- if (resolved.error) return resolved.error;
553
- if (resolved.turnBudget !== undefined) target.defaultTurnBudget = resolved.turnBudget;
554
- else delete target.defaultTurnBudget;
555
- }
556
- }
557
633
  if (hasKey(cfg, "acceptance")) {
558
634
  if (cfg.acceptance === "") delete target.defaultAcceptance;
559
635
  else {
@@ -609,11 +685,13 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
609
685
  if (target.runner?.type === "external-cli" || target.runner?.type === "external-job") {
610
686
  const unsupported = [
611
687
  target.tools?.length || target.mcpDirectTools?.length ? "tools" : undefined,
688
+ target.excludeTools?.length ? "excludeTools" : undefined,
612
689
  target.model ? "model" : undefined,
613
690
  target.fallbackModels?.length ? "fallbackModels" : undefined,
614
691
  target.thinking ? "thinking" : undefined,
615
692
  target.extensions?.length ? "extensions" : undefined,
616
693
  target.subagentOnlyExtensions?.length ? "subagentOnlyExtensions" : undefined,
694
+ target.mutationTools?.length ? "mutationTools" : undefined,
617
695
  target.skills?.length || target.skillPath?.length ? "skills" : undefined,
618
696
  target.maxSubagentDepth !== undefined ? "maxSubagentDepth" : undefined,
619
697
  target.completionGuard !== undefined ? "completionGuard" : undefined,
@@ -683,24 +761,170 @@ function externalJobProviderSuffix(provider: string, names: Set<string> | undefi
683
761
  return names.has(provider) ? "✓" : "missing";
684
762
  }
685
763
 
686
- function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefined): string | undefined {
764
+ type ExternalCliAvailabilityByCommand = ReadonlyMap<string, ExternalCliBinaryAvailability>;
765
+
766
+ function externalCliAvailabilityForAgents(agents: readonly AgentConfig[]): ExternalCliAvailabilityByCommand {
767
+ const availability = new Map<string, ExternalCliBinaryAvailability>();
768
+ for (const agent of agents) {
769
+ const runner = agent.runner;
770
+ if (runner?.type === "external-cli" && !availability.has(runner.command)) {
771
+ availability.set(runner.command, resolveExternalCliBinaryAvailability(runner.command, process.env));
772
+ }
773
+ }
774
+ return availability;
775
+ }
776
+
777
+ function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string | undefined {
687
778
  if (agent.runner?.type === "external-job") return `external-job:${agent.runner.provider} ${externalJobProviderSuffix(agent.runner.provider, providerNames)}`;
688
- if (agent.runner?.type === "external-cli") return "external-cli";
779
+ if (agent.runner?.type === "external-cli") {
780
+ const availability = externalCliAvailability?.get(agent.runner.command);
781
+ if (!availability) return "external-cli";
782
+ return `external-cli:${agent.runner.command} ${availability.available ? "✓" : "missing"}`;
783
+ }
689
784
  return undefined;
690
785
  }
691
786
 
692
- function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
787
+ function agentListMetadata(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string {
693
788
  const source = agent.source === "package" ? packageSourceLabel(agent) : agent.source;
694
- const parts = [
789
+ return [
695
790
  source,
696
- runnerListBadge(agent, providerNames),
791
+ runnerListBadge(agent, providerNames, externalCliAvailability),
697
792
  agent.defaultContext ? `context: ${agent.defaultContext}` : undefined,
698
793
  agent.aliases?.length ? `aliases: ${agent.aliases.join(", ")}` : undefined,
699
- ].filter((part): part is string => Boolean(part));
700
- return `- ${agent.name} (${parts.join(", ")}): ${agent.description}`;
794
+ ].filter((part): part is string => Boolean(part)).join(", ");
795
+ }
796
+
797
+ function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
798
+ return `- ${agent.name} (${agentListMetadata(agent, providerNames)}): ${agent.description}`;
799
+ }
800
+
801
+ function formatAgentCapabilitiesLine(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string {
802
+ const declaredTools = [
803
+ ...(agent.tools ?? []),
804
+ ...(agent.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
805
+ ];
806
+ let tools = "none";
807
+ if (agent.tools === undefined && agent.mcpDirectTools === undefined) {
808
+ tools = "default/ambient";
809
+ } else if (declaredTools.length > 0) {
810
+ tools = declaredTools.join(", ");
811
+ }
812
+ if (agent.excludeTools?.length) tools = `${tools}; excludes: ${agent.excludeTools.join(", ")}`;
813
+ let model = "inherits current session";
814
+ if (agent.model !== undefined) {
815
+ model = agent.model;
816
+ if (agent.modelProvider && !agent.model.includes("/")) model = `${agent.modelProvider}/${agent.model}`;
817
+ }
818
+ const thinking = agent.thinking === false ? "off" : agent.thinking ?? "default";
819
+ return `- ${agent.name} (${agentListMetadata(agent, providerNames, externalCliAvailability)}): Description: ${previewDisplayText(agent.description, 240)}; Tools: ${tools}; Model: ${model}; Thinking: ${thinking}`;
820
+ }
821
+
822
+ const EXTERNAL_JOB_CAPABILITIES = { stop: false, steer: false, resume: false, structuredOutput: false, toolEvents: false } as const;
823
+ const PI_AGENT_RUNNER = { type: "pi" } as const;
824
+
825
+ function listOrEmpty<T>(values: T[] | undefined): T[] {
826
+ return values ?? [];
827
+ }
828
+
829
+ function agentCapabilityRunner(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability: ExternalCliAvailabilityByCommand): AgentCapabilityRow["runner"] {
830
+ const runner = agent.runner;
831
+ if (!runner || runner.type === "pi") return PI_AGENT_RUNNER;
832
+ if (runner.type === "external-cli") {
833
+ const availability = externalCliAvailability.get(runner.command)!;
834
+ return {
835
+ type: "external-cli",
836
+ adapter: runner.adapter,
837
+ command: runner.command,
838
+ ...availability,
839
+ capabilities: resolveExternalCliRunnerStatus(runner).capabilities,
840
+ };
841
+ }
842
+ return { type: "external-job", provider: runner.provider, available: providerNames?.has(runner.provider), capabilities: EXTERNAL_JOB_CAPABILITIES };
701
843
  }
702
844
 
703
- function formatAgentListSections(agents: AgentConfig[], providerNames: Set<string> | undefined): string[] {
845
+ function agentCapabilityTools(agent: AgentConfig): AgentCapabilityRow["tools"] {
846
+ return {
847
+ ambient: agent.tools === undefined && agent.mcpDirectTools === undefined,
848
+ names: listOrEmpty(agent.tools),
849
+ ...(agent.excludeTools !== undefined ? { excludeTools: [...agent.excludeTools] } : {}),
850
+ mcpDirectTools: listOrEmpty(agent.mcpDirectTools),
851
+ mutationTools: agent.mutationTools,
852
+ };
853
+ }
854
+
855
+ function agentCapabilityRow(agent: AgentConfig, options: { executable: boolean; providerNames?: Set<string>; externalCliAvailability: ExternalCliAvailabilityByCommand; restrictionSources?: string[] }): AgentCapabilityRow {
856
+ return {
857
+ name: agent.name,
858
+ description: previewDisplayText(agent.description, 1000),
859
+ source: agent.source,
860
+ executable: options.executable,
861
+ restrictionSources: options.executable ? undefined : options.restrictionSources ?? [],
862
+ aliases: agent.aliases ? [...agent.aliases] : undefined,
863
+ runner: agentCapabilityRunner(agent, options.providerNames, options.externalCliAvailability),
864
+ tools: agentCapabilityTools(agent),
865
+ model: presentDetails({ value: agent.model, fallbackModels: agent.fallbackModels, thinking: agent.thinking }),
866
+ execution: presentDetails({ defaultAsync: agent.defaultAsync, timeoutMs: agent.defaultTimeoutMs }),
867
+ output: presentDetails({ path: agent.output, mode: agent.outputMode }),
868
+ extensions: presentDetails({ names: agent.extensions, subagentOnly: agent.subagentOnlyExtensions, skills: agent.skills }),
869
+ };
870
+ }
871
+
872
+ function agentCapabilitiesSnapshot(input: { agents: AgentConfig[]; restrictedAgents: AgentConfig[]; providerNames?: Set<string>; externalCliAvailability: ExternalCliAvailabilityByCommand; restrictedSources?: string[] }): AgentCapabilitiesSnapshot {
873
+ return {
874
+ agents: [
875
+ ...input.agents.map((agent) => agentCapabilityRow(agent, { executable: true, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability })),
876
+ ...input.restrictedAgents.map((agent) => agentCapabilityRow(agent, { executable: false, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability, restrictionSources: input.restrictedSources })),
877
+ ],
878
+ restrictedCount: input.restrictedAgents.length,
879
+ ...(input.restrictedSources?.length ? { capabilityCeilingSources: [...input.restrictedSources] } : {}),
880
+ };
881
+ }
882
+
883
+ function providerNames(status: ExternalJobProviderStatus): Set<string> | undefined {
884
+ return status.ok ? status.names : undefined;
885
+ }
886
+
887
+ function appendRestrictedAgentLines(input: { lines: string[]; agents: AgentConfig[]; sources?: string[]; providerNames?: Set<string>; formatLine: (agent: AgentConfig, providerNames: Set<string> | undefined) => string }): void {
888
+ if (input.agents.length === 0) return;
889
+ input.lines.push(
890
+ "",
891
+ `Restricted agents (not executable in this session${input.sources?.length ? `; capability ceiling: ${input.sources.join(", ")}` : ""}):`,
892
+ ...input.agents.map((agent) => input.formatLine(agent, input.providerNames)),
893
+ );
894
+ }
895
+
896
+ function appendExternalJobRegistryLine(lines: string[], agents: AgentConfig[], status: ExternalJobProviderStatus): void {
897
+ if (status.ok || !agents.some((agent) => agent.runner?.type === "external-job")) return;
898
+ lines.push("", `External-job provider registry unavailable: ${status.error}`);
899
+ }
900
+
901
+ function appendAgentDiagnosticLines(lines: string[], diagnostics: AgentDiscoveryDiagnostic[] | undefined): void {
902
+ if (!diagnostics?.length) return;
903
+ lines.push(
904
+ "",
905
+ "Invalid agent definitions:",
906
+ ...diagnostics.map((diagnostic) => `- ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
907
+ );
908
+ }
909
+
910
+ function agentCapabilityDetails(input: { capabilityMode: boolean; agents: AgentConfig[]; restrictedAgents: AgentConfig[]; providerNames?: Set<string>; externalCliAvailability: ExternalCliAvailabilityByCommand; restrictedSources?: string[] }): Partial<Details> | undefined {
911
+ if (!input.capabilityMode) return undefined;
912
+ return {
913
+ agentCapabilities: jsonDetails(agentCapabilitiesSnapshot({
914
+ agents: input.agents,
915
+ restrictedAgents: input.restrictedAgents,
916
+ providerNames: input.providerNames,
917
+ externalCliAvailability: input.externalCliAvailability,
918
+ restrictedSources: input.restrictedSources,
919
+ })),
920
+ };
921
+ }
922
+
923
+ function formatAgentListSections(
924
+ agents: AgentConfig[],
925
+ providerNames: Set<string> | undefined,
926
+ formatLine: (agent: AgentConfig, providerNames: Set<string> | undefined) => string = formatAgentListLine,
927
+ ): string[] {
704
928
  if (agents.length === 0) return ["- (none)"];
705
929
  const sections: Array<[AgentSource, string]> = [
706
930
  ["package", "Package agents"],
@@ -714,7 +938,7 @@ function formatAgentListSections(agents: AgentConfig[], providerNames: Set<strin
714
938
  const matches = agents.filter((agent) => agent.source === source);
715
939
  if (matches.length === 0) continue;
716
940
  if (lines.length > 0) lines.push("");
717
- lines.push(label, ...matches.map((agent) => formatAgentListLine(agent, providerNames)));
941
+ lines.push(label, ...matches.map((agent) => formatLine(agent, providerNames)));
718
942
  }
719
943
  return lines;
720
944
  }
@@ -742,6 +966,7 @@ function formatAgentDetail(agent: AgentConfig): string {
742
966
  if (agent.model) lines.push(`Model: ${agent.model}`);
743
967
  if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
744
968
  if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
969
+ if (agent.excludeTools?.length) lines.push(`Excluded tools: ${agent.excludeTools.join(", ")}`);
745
970
  if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
746
971
  if (agent.skillPath?.length) lines.push(`Skill paths: ${agent.skillPath.join(", ")}`);
747
972
  lines.push(`System prompt mode: ${agent.systemPromptMode}`);
@@ -752,16 +977,17 @@ function formatAgentDetail(agent: AgentConfig): string {
752
977
  if (agent.runner?.type === "external-job" && agent.runner.options) lines.push(`Runner options: ${JSON.stringify(agent.runner.options)}`);
753
978
  }
754
979
  lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
980
+ lines.push(`Inherit global context: ${agent.inheritGlobalContext ? "true" : "false"}`);
755
981
  lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
756
982
  if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
757
983
  if (agent.defaultAsync !== undefined) lines.push(`Async: ${agent.defaultAsync ? "true" : "false"}`);
758
984
  if (agent.defaultTimeoutMs !== undefined) lines.push(`Timeout: ${agent.defaultTimeoutMs}ms`);
759
- if (agent.defaultTurnBudget) lines.push(`Turn budget: ${JSON.stringify(agent.defaultTurnBudget)}`);
760
985
  if (agent.defaultAcceptance !== undefined) lines.push(`Acceptance: ${typeof agent.defaultAcceptance === "object" ? JSON.stringify(agent.defaultAcceptance) : String(agent.defaultAcceptance)}`);
761
986
  if (agent.acceptanceRole) lines.push(`Acceptance role: ${agent.acceptanceRole}`);
762
987
  if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
763
988
  if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
764
989
  if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
990
+ if (agent.mutationTools !== undefined) lines.push(`Mutation tools: ${agent.mutationTools.length ? agent.mutationTools.join(", ") : "(none)"}`);
765
991
  if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
766
992
  if (agent.output) lines.push(`Output: ${agent.output}`);
767
993
  if (agent.outputMode) lines.push(`Output mode: ${agent.outputMode}`);
@@ -777,17 +1003,8 @@ function formatAgentDetail(agent: AgentConfig): string {
777
1003
 
778
1004
  export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
779
1005
  const scope = normalizeListScope(params.agentScope) ?? "both";
780
- const d = discoverAgentsAll(ctx.cwd);
781
- let scopedAgents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
782
- if (ctx.runtimeAgentOwner && listRuntimeAgentConfigs(ctx.runtimeAgentOwner).length > 0) {
783
- const configuredAgents: AgentConfig[] = [
784
- ...d.builtin,
785
- ...d.package,
786
- ...d.user,
787
- ...d.project,
788
- ];
789
- scopedAgents = mergeRuntimeAgents(ctx.runtimeAgentOwner, { agents: scopedAgents }, configuredAgents).agents;
790
- }
1006
+ const d = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
1007
+ let scopedAgents = effectiveAgentsForScope(scope, d, ctx.runtimeAgentOwner);
791
1008
  scopedAgents = scopedAgents
792
1009
  .sort((a, b) => a.name.localeCompare(b.name));
793
1010
  const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
@@ -801,23 +1018,28 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
801
1018
  discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
802
1019
  });
803
1020
  const providerStatus = registeredExternalJobProviderStatus();
1021
+ const providerNameSet = providerNames(providerStatus);
1022
+ const capabilityMode = params.capabilities === true;
1023
+ const externalCliAvailability = capabilityMode ? externalCliAvailabilityForAgents([...agents, ...restrictedAgents]) : undefined;
1024
+ const formatLine = capabilityMode
1025
+ ? (agent: AgentConfig, names: Set<string> | undefined) => formatAgentCapabilitiesLine(agent, names, externalCliAvailability)
1026
+ : formatAgentListLine;
804
1027
  const lines = [
805
- "Executable agents:",
806
- ...formatAgentListSections(agents, providerStatus.ok ? providerStatus.names : undefined),
807
- ...(restrictedAgents.length ? [
808
- "",
809
- `Restricted agents (not executable in this session${restrictedSources?.length ? `; capability ceiling: ${restrictedSources.join(", ")}` : ""}):`,
810
- ...restrictedAgents.map((a) => formatAgentListLine(a, providerStatus.ok ? providerStatus.names : undefined)),
811
- ] : []),
812
- ...(!providerStatus.ok && [...agents, ...restrictedAgents].some((agent) => agent.runner?.type === "external-job") ? ["", `External-job provider registry unavailable: ${providerStatus.error}`] : []),
813
- ...(d.agentDiagnostics?.length ? [
814
- "",
815
- "Invalid agent definitions:",
816
- ...d.agentDiagnostics.map((diagnostic) => `- ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
817
- ] : []),
818
- ...(proactiveSuggestions.length ? ["", ...proactiveSuggestions] : []),
1028
+ capabilityMode ? "Executable agents (capabilities):" : "Executable agents:",
1029
+ ...formatAgentListSections(agents, providerNameSet, formatLine),
819
1030
  ];
820
- return result(lines.join("\n"));
1031
+ appendRestrictedAgentLines({ lines, agents: restrictedAgents, sources: restrictedSources, providerNames: providerNameSet, formatLine });
1032
+ appendExternalJobRegistryLine(lines, [...agents, ...restrictedAgents], providerStatus);
1033
+ appendAgentDiagnosticLines(lines, d.agentDiagnostics);
1034
+ if (proactiveSuggestions.length) lines.push("", ...proactiveSuggestions);
1035
+ return result(lines.join("\n"), false, agentCapabilityDetails({
1036
+ capabilityMode,
1037
+ agents,
1038
+ restrictedAgents,
1039
+ providerNames: providerNameSet,
1040
+ externalCliAvailability: externalCliAvailability ?? new Map(),
1041
+ restrictedSources,
1042
+ }));
821
1043
  }
822
1044
 
823
1045
  function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {
@@ -827,79 +1049,108 @@ function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undef
827
1049
  if (agent.modelSource?.type === "subagents.defaultModel" && agent.model === agent.modelSource.model) {
828
1050
  return `${agent.modelSource.scope} defaultModel`;
829
1051
  }
830
- if (agent.model) return "builtin agent config";
1052
+ if (agent.model) return `${agent.source} agent config`;
831
1053
  if (currentModel) return "inherits current session model";
832
1054
  return "inherit requested, but no current session model is available";
833
1055
  }
834
1056
 
835
1057
  function handleModels(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
836
1058
  const requestedAgent = params.agent?.trim();
837
- if (requestedAgent && !(BUILTIN_AGENT_NAMES as readonly string[]).includes(requestedAgent)) {
838
- return result(`Builtin agent '${requestedAgent}' not found. Available: ${BUILTIN_AGENT_NAMES.join(", ")}.`, true);
839
- }
1059
+ const scope = normalizeListScope(params.agentScope);
1060
+ if (!scope) return result("agentScope must be 'user', 'project', or 'both' for models.", true);
840
1061
 
841
- const discovered = discoverAgentsAll(ctx.cwd);
842
- const builtinByName = new Map(discovered.builtin.map((agent) => [agent.name, agent]));
1062
+ const discovered = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
1063
+ const effectiveAgents = effectiveAgentsForScope(scope, discovered, ctx.runtimeAgentOwner)
1064
+ .sort((a, b) => a.name.localeCompare(b.name));
843
1065
  const availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
844
1066
  const currentModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
845
1067
  const preferredProvider = ctx.model?.provider;
846
- const names = requestedAgent ? [requestedAgent] : [...BUILTIN_AGENT_NAMES];
1068
+ const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
847
1069
 
1070
+ let selectedAgents = effectiveAgents;
848
1071
  if (requestedAgent) {
849
- const agent = builtinByName.get(requestedAgent);
850
- if (!agent) return result(`Builtin agent '${requestedAgent}' not found.`, true);
851
- const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
852
- const lines = [
853
- "Builtin subagent model",
854
- "",
855
- `Agent: ${requestedAgent}`,
856
- "Effective model:",
857
- ` ${resolvedModel ?? "(unresolved)"}`,
858
- `Source: ${formatModelSource(agent, currentModel)}`,
859
- ];
860
- if (agent.override) {
861
- lines.push("Override file:");
862
- lines.push(` ${agent.override.path}`);
1072
+ const matches = findAgentsInDiscovery(requestedAgent, discovered, scope, ctx.runtimeAgentOwner);
1073
+ const diagnostics = diagnosticsForScope(discovered.agentDiagnostics, scope);
1074
+ const normalizedName = sanitizeName(requestedAgent);
1075
+ const diagnostic = findBlockingAgentDiagnostic(requestedAgent, matches, diagnostics)
1076
+ ?? (normalizedName !== requestedAgent ? findBlockingAgentDiagnostic(normalizedName, matches, diagnostics) : undefined);
1077
+ if (diagnostic) return result(`Agent '${params.agent}' has invalid configuration: ${diagnostic.error}`, true);
1078
+ const distinctNames = [...new Set(matches.map((agent) => agent.name))];
1079
+ if (distinctNames.length > 1) return result(`Ambiguous agent alias or name '${params.agent}': ${distinctNames.sort((a, b) => a.localeCompare(b)).join(", ")}`, true);
1080
+ if (!matches.length) {
1081
+ return result(`Agent '${params.agent}' not found. Available: ${availableAgentNamesFromDiscovery(discovered, ctx.runtimeAgentOwner).join(", ") || "none"}.`, true);
863
1082
  }
864
- if (agent.model && resolvedModel && agent.model !== resolvedModel) {
865
- lines.push("Requested model setting:");
866
- lines.push(` ${agent.model}`);
867
- }
868
- if (agent.disabled) lines.push("Disabled: true");
869
- lines.push("Current session model:");
870
- lines.push(` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`);
871
- return result(lines.join("\n"));
1083
+ selectedAgents = [matches[0]!];
872
1084
  }
873
1085
 
874
1086
  const lines = [
875
- "Builtin subagent models",
876
- "",
877
- "Current session model:",
878
- ` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
1087
+ requestedAgent ? "Subagent model" : "Subagent models",
879
1088
  "",
1089
+ ...(requestedAgent ? [] : [
1090
+ "Current session model:",
1091
+ ` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
1092
+ "",
1093
+ ]),
880
1094
  ];
881
1095
 
882
- for (const name of names) {
883
- const agent = builtinByName.get(name);
884
- if (!agent) {
885
- lines.push(name);
886
- lines.push(" model:");
887
- lines.push(" (builtin definition not found)");
888
- lines.push(" source: missing");
889
- lines.push("");
890
- continue;
1096
+ const modelEntries = selectedAgents.flatMap((agent) => requestedAgent
1097
+ ? [{ agent, name: requestedAgent }]
1098
+ : [{ agent, name: agent.name }, ...(agent.aliases ?? []).map((name) => ({ agent, name }))]);
1099
+ for (const { agent, name } of modelEntries) {
1100
+ const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, agent.modelProvider ?? preferredProvider);
1101
+ const effectiveThinking = resolveEffectiveThinking(resolvedModel, agent.thinking)
1102
+ ?? (agent.thinking === false ? "off" : undefined);
1103
+ const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}${isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling) ? "" : "; restricted"}`;
1104
+ if (requestedAgent) {
1105
+ lines.push(`Agent: ${requestedAgent}`);
1106
+ lines.push("Effective model:");
1107
+ lines.push(` ${resolvedModel ?? "(unresolved)"}`);
1108
+ lines.push(`Source: ${source}`);
1109
+ lines.push(`Thinking: ${effectiveThinking ?? "default"}`);
1110
+ if (agent.fallbackModels?.length) {
1111
+ lines.push("Fallback models:");
1112
+ for (const fallback of agent.fallbackModels) {
1113
+ lines.push(` ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
1114
+ }
1115
+ }
1116
+ if (agent.override) {
1117
+ lines.push("Override file:");
1118
+ lines.push(` ${agent.override.path}`);
1119
+ }
1120
+ if (agent.model && resolvedModel && agent.model !== resolvedModel) {
1121
+ lines.push("Requested model setting:");
1122
+ lines.push(` ${agent.model}`);
1123
+ }
1124
+ if (agent.disabled) lines.push("Disabled: true");
1125
+ if (!isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling)) lines.push("Restricted: true");
1126
+ lines.push("Current session model:");
1127
+ lines.push(` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`);
1128
+ break;
891
1129
  }
892
- const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
893
- const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}`;
894
1130
  lines.push(name);
895
1131
  lines.push(" model:");
896
1132
  lines.push(` ${resolvedModel ?? "(unresolved)"}`);
897
1133
  lines.push(` source: ${source}`);
1134
+ lines.push(` thinking: ${effectiveThinking ?? "default"}`);
1135
+ if (agent.fallbackModels?.length) {
1136
+ lines.push(" fallback models:");
1137
+ for (const fallback of agent.fallbackModels) {
1138
+ lines.push(` ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
1139
+ }
1140
+ }
1141
+ if (agent.override) {
1142
+ lines.push(" override file:");
1143
+ lines.push(` ${agent.override.path}`);
1144
+ }
1145
+ if (agent.model && resolvedModel && agent.model !== resolvedModel) {
1146
+ lines.push(" requested model setting:");
1147
+ lines.push(` ${agent.model}`);
1148
+ }
898
1149
  lines.push("");
899
1150
  }
900
1151
 
901
1152
  const availableFullIds = availableModels.map((m) => m.fullId).sort();
902
- if (availableFullIds.length > 0) {
1153
+ if (!requestedAgent && availableFullIds.length > 0) {
903
1154
  lines.push("Available models in this session's registry (copy an exact provider/id when passing model):");
904
1155
  lines.push("");
905
1156
  const shown = availableFullIds.slice(0, 80);
@@ -908,7 +1159,7 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
908
1159
  lines.push("");
909
1160
  lines.push("Use an exact provider/id from this list when you pass model; bare ids resolve only when unique in the registry.");
910
1161
  }
911
-
1162
+ if (!requestedAgent) appendAgentDiagnosticLines(lines, diagnosticsForScope(discovered.agentDiagnostics, scope));
912
1163
  return result(lines.join("\n"));
913
1164
  }
914
1165
 
@@ -916,7 +1167,7 @@ function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolR
916
1167
  if (!params.agent) return result("Specify 'agent' for get.", true);
917
1168
  const scope = normalizeListScope(params.agentScope);
918
1169
  if (!scope) return result("agentScope must be 'user', 'project', or 'both' for get.", true);
919
- const discovered = discoverAgentsAll(ctx.cwd);
1170
+ const discovered = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
920
1171
  const matches = findAgentsInDiscovery(params.agent, discovered, scope);
921
1172
  const diagnostics = diagnosticsForScope(discovered.agentDiagnostics, scope);
922
1173
  const rawName = params.agent.trim();
@@ -946,7 +1197,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
946
1197
  const runtimeName = buildRuntimeName(name, parsedPackage.packageName);
947
1198
  const scopeRaw = cfg.scope ?? "user";
948
1199
  if (scopeRaw !== "user" && scopeRaw !== "project") return result("config.scope must be 'user' or 'project'.", true);
949
- const scope = scopeRaw as ManagementScope;
1200
+ const scope = scopeRaw;
950
1201
  if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
951
1202
  const d = discoverAgentsAll(ctx.cwd);
952
1203
  const projectConfigDir = getProjectConfigDir(ctx.cwd);
@@ -967,10 +1218,13 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
967
1218
  systemPrompt: "",
968
1219
  systemPromptMode: defaultSystemPromptMode(name),
969
1220
  inheritProjectContext: defaultInheritProjectContext(name),
1221
+ inheritGlobalContext: false,
970
1222
  inheritSkills: defaultInheritSkills(),
971
1223
  };
972
1224
  const applyError = applyAgentConfig(agent, cfg);
973
1225
  if (applyError) return result(applyError, true);
1226
+ const profileError = validateCodeOwnedProfileRunner(agent);
1227
+ if (profileError) return result(profileError, true);
974
1228
  const mw = modelWarning(ctx, agent.model);
975
1229
  if (mw) warnings.push(mw);
976
1230
  const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
@@ -1022,6 +1276,8 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
1022
1276
  if (newPackageName !== undefined) updated.packageName = newPackageName;
1023
1277
  else delete updated.packageName;
1024
1278
  updated.name = buildRuntimeName(newLocalName, newPackageName);
1279
+ const profileError = validateCodeOwnedProfileRunner(updated);
1280
+ if (profileError) return result(profileError, true);
1025
1281
  if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
1026
1282
  if (hasKey(cfg, "model")) {
1027
1283
  const mw = modelWarning(ctx, updated.model);
@@ -1435,7 +1691,7 @@ function handleReset(params: ManagementParams, ctx: ManagementContext): AgentToo
1435
1691
  }
1436
1692
 
1437
1693
  export function handleManagementAction(action: string, params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
1438
- switch (action as ManagementAction) {
1694
+ switch (action) {
1439
1695
  case "list": return handleList(params, ctx);
1440
1696
  case "get": return handleGet(params, ctx);
1441
1697
  case "models": return handleModels(params, ctx);