@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -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 +195 -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 +7 -6
  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 +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -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 +42 -21
  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 +77 -21
  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 +65 -29
  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 +7 -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 +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -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 +204 -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 +718 -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 +489 -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 +1223 -402
  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 +364 -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 +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -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 +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  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 +20 -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/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. 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,17 +28,20 @@ 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";
44
+ import { validateSandboxProfileName } from "../shared/sandbox-profile.ts";
43
45
 
44
46
  export const AGENT_MANAGEMENT_API_VERSION = 1 as const;
45
47
 
@@ -97,17 +99,27 @@ export type EjectAgentDefinitionResult =
97
99
 
98
100
  type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete" | "eject" | "disable" | "enable" | "reset";
99
101
  type ManagementScope = "user" | "project";
100
- type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { model?: ExtensionContext["model"]; config?: ExtensionConfig; currentSessionId?: string; runtimeAgentOwner?: RuntimeAgentOwner };
102
+ type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { isProjectTrusted?: ExtensionContext["isProjectTrusted"]; model?: ExtensionContext["model"]; config?: ExtensionConfig; currentSessionId?: string; runtimeAgentOwner?: RuntimeAgentOwner };
101
103
 
102
104
  interface ManagementParams {
103
105
  action?: string;
104
106
  agent?: string;
105
107
  agentScope?: unknown;
108
+ capabilities?: unknown;
106
109
  config?: unknown;
107
110
  }
108
111
 
109
- function result(text: string, isError = false): AgentToolResult<Details> {
110
- return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [] } };
112
+ function result(text: string, isError = false, details?: Partial<Details>): AgentToolResult<Details> {
113
+ return { content: [{ type: "text", text }], isError, details: { mode: "management", results: [], ...details } };
114
+ }
115
+
116
+ function jsonDetails<T>(value: T): T {
117
+ return JSON.parse(JSON.stringify(value)) as T;
118
+ }
119
+
120
+ function presentDetails<T extends Record<string, unknown>>(value: T): T | undefined {
121
+ const cleaned = jsonDetails(value);
122
+ return Object.keys(cleaned).length > 0 ? cleaned : undefined;
111
123
  }
112
124
 
113
125
  function parseCsv(value: string): string[] {
@@ -174,18 +186,39 @@ function allAgents(d: { builtin: AgentConfig[]; package: AgentConfig[]; user: Ag
174
186
  return [...d.builtin, ...d.package, ...d.user, ...d.project];
175
187
  }
176
188
 
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));
189
+ function effectiveAgentsForScope(
190
+ scope: AgentScope,
191
+ d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
192
+ runtimeAgentOwner?: RuntimeAgentOwner,
193
+ ): AgentConfig[] {
194
+ let agents = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
195
+ if (runtimeAgentOwner) {
196
+ agents = mergeRuntimeAgents(runtimeAgentOwner, { agents }, allAgents(d)).agents;
197
+ }
198
+ return agents;
199
+ }
200
+
201
+ function availableAgentNamesFromDiscovery(
202
+ d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
203
+ runtimeAgentOwner?: RuntimeAgentOwner,
204
+ ): string[] {
205
+ const agents = runtimeAgentOwner ? effectiveAgentsForScope("both", d, runtimeAgentOwner) : allAgents(d);
206
+ return [...new Set(agents.map((agent) => agent.name))].sort((a, b) => a.localeCompare(b));
179
207
  }
180
208
 
181
209
  function availableAgentNames(cwd: string): string[] {
182
210
  return availableAgentNamesFromDiscovery(discoverAgentsAll(cwd));
183
211
  }
184
212
 
185
- function findAgentsInDiscovery(name: string, d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] }, scope: AgentScope = "both"): AgentConfig[] {
213
+ function findAgentsInDiscovery(
214
+ name: string,
215
+ d: { builtin: AgentConfig[]; package: AgentConfig[]; user: AgentConfig[]; project: AgentConfig[] },
216
+ scope: AgentScope = "both",
217
+ runtimeAgentOwner?: RuntimeAgentOwner,
218
+ ): AgentConfig[] {
186
219
  const raw = name.trim();
187
220
  const sanitized = sanitizeName(raw);
188
- const scoped = mergeAgentsForScope(scope, d.user, d.project, d.builtin, d.package);
221
+ const scoped = effectiveAgentsForScope(scope, d, runtimeAgentOwner);
189
222
  let resolved = resolveAgentName(raw, scoped);
190
223
  if (!resolved.agent && !resolved.error && sanitized !== raw) resolved = resolveAgentName(sanitized, scoped);
191
224
  if (resolved.agent) return scoped.filter((agent) => agent.name === resolved.agent!.name).sort((a, b) => a.source.localeCompare(b.source));
@@ -275,16 +308,29 @@ function withDeclaredExtensionPaths(config: AgentConfig, filePath: string): Agen
275
308
  export function editableAgentConfig(agent: AgentConfig): AgentConfig {
276
309
  const { extensions: _extensions, ...withoutExtensions } = agent;
277
310
  const base = agent.override?.base;
311
+ const description = base?.description ?? agent.description;
312
+ const frontmatterFields = agent.source === "builtin" || agent.source === "runtime" ? undefined : readAgentFrontmatterFields(agent.filePath);
313
+ const hasDeclaredField = (...fields: string[]) => frontmatterFields === undefined || fields.some((field) => frontmatterFields.has(field));
314
+ const withoutSettingsDefaults = (config: AgentConfig): AgentConfig => {
315
+ if (!frontmatterFields) return config;
316
+ const next = { ...config };
317
+ if (!hasDeclaredField("model")) delete next.model;
318
+ if (!hasDeclaredField("thinking")) delete next.thinking;
319
+ return next;
320
+ };
278
321
  const {
279
322
  override: _override,
323
+ description: _description,
280
324
  output: _output,
281
325
  outputMode: _outputMode,
282
326
  defaultReads: _defaultReads,
283
327
  model: _model,
284
328
  fallbackModels: _fallbackModels,
329
+ fast: _fast,
285
330
  thinking: _thinking,
286
331
  systemPromptMode: _systemPromptMode,
287
332
  inheritProjectContext: _inheritProjectContext,
333
+ inheritGlobalContext: _inheritGlobalContext,
288
334
  inheritSkills: _inheritSkills,
289
335
  defaultContext: _defaultContext,
290
336
  acceptanceRole: _acceptanceRole,
@@ -293,28 +339,35 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
293
339
  skills: _skills,
294
340
  skillPath: _skillPath,
295
341
  tools: _tools,
342
+ excludeTools: _excludeTools,
296
343
  mcpDirectTools: _mcpDirectTools,
344
+ allowNestedSubagents: _allowNestedSubagents,
297
345
  subagentOnlyExtensions: _subagentOnlyExtensions,
346
+ mutationTools: _mutationTools,
298
347
  completionGuard: _completionGuard,
348
+ toolBudget: _toolBudget,
299
349
  ...editable
300
350
  } = withoutExtensions;
301
351
  if (!base) {
302
- return withDeclaredExtensionPaths({
352
+ return withDeclaredExtensionPaths(withoutSettingsDefaults({
303
353
  ...withoutExtensions,
304
354
  ...(agent.extensionsFromDefault ? {} : agent.extensions !== undefined ? { extensions: [...agent.extensions] } : {}),
305
- }, agent.filePath);
355
+ }), agent.filePath);
306
356
  }
307
357
 
308
358
  return withDeclaredExtensionPaths({
309
359
  ...editable,
360
+ description,
310
361
  ...(base.output !== undefined ? { output: base.output } : {}),
311
362
  ...(base.outputMode !== undefined ? { outputMode: base.outputMode } : {}),
312
363
  ...(base.defaultReads !== undefined ? { defaultReads: [...base.defaultReads] } : {}),
313
- ...(base.model !== undefined ? { model: base.model } : {}),
364
+ ...(base.model !== undefined && hasDeclaredField("model") ? { model: base.model } : {}),
314
365
  ...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
315
- ...(base.thinking !== undefined ? { thinking: base.thinking } : {}),
366
+ ...(base.fast !== undefined ? { fast: base.fast } : {}),
367
+ ...(base.thinking !== undefined && hasDeclaredField("thinking") ? { thinking: base.thinking } : {}),
316
368
  systemPromptMode: base.systemPromptMode,
317
369
  inheritProjectContext: base.inheritProjectContext,
370
+ inheritGlobalContext: base.inheritGlobalContext,
318
371
  inheritSkills: base.inheritSkills,
319
372
  ...(base.defaultContext !== undefined ? { defaultContext: base.defaultContext } : {}),
320
373
  ...(base.acceptanceRole !== undefined ? { acceptanceRole: base.acceptanceRole } : {}),
@@ -323,10 +376,14 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
323
376
  ...(base.skills !== undefined ? { skills: [...base.skills] } : {}),
324
377
  ...(base.skillPath !== undefined ? { skillPath: [...base.skillPath] } : {}),
325
378
  ...(base.tools !== undefined ? { tools: [...base.tools] } : {}),
379
+ ...(base.excludeTools !== undefined ? { excludeTools: [...base.excludeTools] } : {}),
326
380
  ...(base.mcpDirectTools !== undefined ? { mcpDirectTools: [...base.mcpDirectTools] } : {}),
381
+ ...(base.allowNestedSubagents !== undefined ? { allowNestedSubagents: base.allowNestedSubagents } : {}),
327
382
  ...(base.extensions !== undefined ? { extensions: [...base.extensions] } : {}),
328
383
  ...(base.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: [...base.subagentOnlyExtensions] } : {}),
384
+ ...(base.mutationTools !== undefined ? { mutationTools: [...base.mutationTools] } : {}),
329
385
  ...(base.completionGuard !== undefined ? { completionGuard: base.completionGuard } : {}),
386
+ ...(base.toolBudget !== undefined ? { toolBudget: base.toolBudget } : {}),
330
387
  }, agent.filePath);
331
388
  }
332
389
 
@@ -354,10 +411,12 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
354
411
  if (hasKey(cfg, "model")) changed("model");
355
412
  if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
356
413
  if (hasKey(cfg, "tools")) changed("tools");
414
+ if (hasKey(cfg, "excludeTools")) changed("excludeTools");
357
415
  if (hasKey(cfg, "skills")) changed("skill", "skills");
358
416
  if (hasKey(cfg, "skillPath")) changed("skillPath");
359
417
  if (hasKey(cfg, "extensions")) changed("extensions");
360
418
  if (hasKey(cfg, "subagentOnlyExtensions")) changed("subagentOnlyExtensions");
419
+ if (hasKey(cfg, "mutationTools")) changed("mutationTools");
361
420
  if (hasKey(cfg, "thinking")) {
362
421
  changed("thinking");
363
422
  if (cfg.thinking === "off") fields.add("thinking");
@@ -370,6 +429,10 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
370
429
  changed("inheritProjectContext");
371
430
  fields.add("inheritProjectContext");
372
431
  }
432
+ if (hasKey(cfg, "inheritGlobalContext")) {
433
+ changed("inheritGlobalContext");
434
+ fields.add("inheritGlobalContext");
435
+ }
373
436
  if (hasKey(cfg, "inheritSkills")) {
374
437
  changed("inheritSkills");
375
438
  fields.add("inheritSkills");
@@ -377,7 +440,6 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
377
440
  if (hasKey(cfg, "defaultContext")) changed("defaultContext");
378
441
  if (hasKey(cfg, "async")) changed("async");
379
442
  if (hasKey(cfg, "timeoutMs")) changed("timeoutMs");
380
- if (hasKey(cfg, "turnBudget")) changed("turnBudget");
381
443
  if (hasKey(cfg, "acceptance")) changed("acceptance");
382
444
  if (hasKey(cfg, "acceptanceRole")) changed("acceptanceRole");
383
445
  if (hasKey(cfg, "output")) changed("output");
@@ -390,6 +452,7 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
390
452
  if (cfg.completionGuard === true) fields.add("completionGuard");
391
453
  }
392
454
  if (hasKey(cfg, "toolBudget")) changed("toolBudget");
455
+ if (hasKey(cfg, "sandbox")) changed("sandbox");
393
456
 
394
457
  return fields;
395
458
  }
@@ -434,15 +497,17 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
434
497
  if (runner.type === "pi" && Object.keys(runner).every((key) => key === "type")) target.runner = { type: "pi" };
435
498
  else if (runner.type === "external-cli" && typeof runner.command === "string" && runner.command.trim()
436
499
  && (runner.args === undefined || (Array.isArray(runner.args) && runner.args.every((arg) => typeof arg === "string")))
500
+ && (runner.adapter === undefined || isCodeOwnedExternalCliAdapterId(runner.adapter))
501
+ && (runner.adapter === undefined || runner.args === undefined || runner.args.length === 0)
437
502
  && (runner.promptDelivery === undefined || runner.promptDelivery === "stdin")
438
- && Object.keys(runner).every((key) => ["type", "command", "args", "promptDelivery"].includes(key))) {
503
+ && Object.keys(runner).every((key) => ["type", "adapter", "command", "args", "promptDelivery"].includes(key))) {
439
504
  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" } : {}) };
505
+ target.runner = { type: "external-cli", ...(isCodeOwnedExternalCliAdapterId(runner.adapter) ? { adapter: runner.adapter } : {}), command: runner.command.trim(), ...(runnerArgs?.length ? { args: runnerArgs } : {}), ...(runner.promptDelivery ? { promptDelivery: "stdin" } : {}) };
441
506
  } else if (runner.type === "external-job" && typeof runner.provider === "string" && runner.provider.trim() === runner.provider && runner.provider
442
507
  && (runner.options === undefined || (runner.options && typeof runner.options === "object" && !Array.isArray(runner.options) && isJsonSerializable(runner.options)))
443
508
  && Object.keys(runner).every((key) => ["type", "provider", "options"].includes(key))) {
444
509
  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 }.";
510
+ } 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
511
  } else return "config.runner must be an object, false, or empty string when provided.";
447
512
  }
448
513
  if (hasKey(cfg, "model")) {
@@ -478,6 +543,18 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
478
543
  else delete target.mcpDirectTools;
479
544
  } else return "config.tools must be a comma-separated string or false when provided.";
480
545
  }
546
+ if (hasKey(cfg, "excludeTools")) {
547
+ if (cfg.excludeTools === false || cfg.excludeTools === "") delete target.excludeTools;
548
+ else if (typeof cfg.excludeTools === "string") {
549
+ const excludeTools = parseCsv(cfg.excludeTools);
550
+ if (excludeTools.length) target.excludeTools = [...new Set(excludeTools)];
551
+ else delete target.excludeTools;
552
+ } else if (Array.isArray(cfg.excludeTools) && cfg.excludeTools.every((entry) => typeof entry === "string")) {
553
+ const excludeTools = [...new Set(cfg.excludeTools.map((entry) => entry.trim()).filter(Boolean))];
554
+ if (excludeTools.length) target.excludeTools = excludeTools;
555
+ else delete target.excludeTools;
556
+ } else return "config.excludeTools must be a comma-separated string, string array, or false when provided.";
557
+ }
481
558
  if (hasKey(cfg, "skills")) {
482
559
  if (cfg.skills === false || cfg.skills === "") delete target.skills;
483
560
  else if (typeof cfg.skills === "string") {
@@ -510,6 +587,12 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
510
587
  else if (typeof cfg.subagentOnlyExtensions === "string") target.subagentOnlyExtensions = parseCsv(cfg.subagentOnlyExtensions);
511
588
  else return "config.subagentOnlyExtensions must be a comma-separated string, empty string, or false when provided.";
512
589
  }
590
+ if (hasKey(cfg, "mutationTools")) {
591
+ if (cfg.mutationTools === false) delete target.mutationTools;
592
+ else if (cfg.mutationTools === "") target.mutationTools = [];
593
+ else if (typeof cfg.mutationTools === "string") target.mutationTools = parseCsv(cfg.mutationTools);
594
+ else return "config.mutationTools must be a comma-separated string, empty string, or false when provided.";
595
+ }
513
596
  if (hasKey(cfg, "thinking")) {
514
597
  if (cfg.thinking === false || cfg.thinking === "") delete target.thinking;
515
598
  else if (typeof cfg.thinking === "string") {
@@ -526,6 +609,10 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
526
609
  if (typeof cfg.inheritProjectContext !== "boolean") return "config.inheritProjectContext must be a boolean when provided.";
527
610
  target.inheritProjectContext = cfg.inheritProjectContext;
528
611
  }
612
+ if (hasKey(cfg, "inheritGlobalContext")) {
613
+ if (typeof cfg.inheritGlobalContext !== "boolean") return "config.inheritGlobalContext must be a boolean when provided.";
614
+ target.inheritGlobalContext = cfg.inheritGlobalContext;
615
+ }
529
616
  if (hasKey(cfg, "inheritSkills")) {
530
617
  if (typeof cfg.inheritSkills !== "boolean") return "config.inheritSkills must be a boolean when provided.";
531
618
  target.inheritSkills = cfg.inheritSkills;
@@ -545,15 +632,6 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
545
632
  else if (typeof cfg.timeoutMs === "number" && Number.isInteger(cfg.timeoutMs) && cfg.timeoutMs > 0) target.defaultTimeoutMs = cfg.timeoutMs;
546
633
  else return "config.timeoutMs must be a positive integer or false when provided.";
547
634
  }
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
635
  if (hasKey(cfg, "acceptance")) {
558
636
  if (cfg.acceptance === "") delete target.defaultAcceptance;
559
637
  else {
@@ -606,18 +684,29 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
606
684
  target.toolBudget = cfg.toolBudget as ToolBudgetConfig;
607
685
  }
608
686
  }
687
+ if (hasKey(cfg, "sandbox")) {
688
+ if (typeof cfg.sandbox !== "string") return "config.sandbox must be a non-empty sandbox profile name when provided.";
689
+ try {
690
+ target.sandbox = validateSandboxProfileName(cfg.sandbox, "config.sandbox");
691
+ } catch (error) {
692
+ return error instanceof Error ? error.message : String(error);
693
+ }
694
+ }
609
695
  if (target.runner?.type === "external-cli" || target.runner?.type === "external-job") {
610
696
  const unsupported = [
611
697
  target.tools?.length || target.mcpDirectTools?.length ? "tools" : undefined,
698
+ target.excludeTools?.length ? "excludeTools" : undefined,
612
699
  target.model ? "model" : undefined,
613
700
  target.fallbackModels?.length ? "fallbackModels" : undefined,
614
701
  target.thinking ? "thinking" : undefined,
615
702
  target.extensions?.length ? "extensions" : undefined,
616
703
  target.subagentOnlyExtensions?.length ? "subagentOnlyExtensions" : undefined,
704
+ target.mutationTools?.length ? "mutationTools" : undefined,
617
705
  target.skills?.length || target.skillPath?.length ? "skills" : undefined,
618
706
  target.maxSubagentDepth !== undefined ? "maxSubagentDepth" : undefined,
619
707
  target.completionGuard !== undefined ? "completionGuard" : undefined,
620
708
  target.toolBudget ? "toolBudget" : undefined,
709
+ target.sandbox ? "sandbox" : undefined,
621
710
  ].filter((field): field is string => Boolean(field));
622
711
  if (unsupported.length > 0) return `config.runner type '${target.runner.type}' does not support Pi-only fields: ${unsupported.join(", ")}.`;
623
712
  }
@@ -683,24 +772,170 @@ function externalJobProviderSuffix(provider: string, names: Set<string> | undefi
683
772
  return names.has(provider) ? "✓" : "missing";
684
773
  }
685
774
 
686
- function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefined): string | undefined {
775
+ type ExternalCliAvailabilityByCommand = ReadonlyMap<string, ExternalCliBinaryAvailability>;
776
+
777
+ function externalCliAvailabilityForAgents(agents: readonly AgentConfig[]): ExternalCliAvailabilityByCommand {
778
+ const availability = new Map<string, ExternalCliBinaryAvailability>();
779
+ for (const agent of agents) {
780
+ const runner = agent.runner;
781
+ if (runner?.type === "external-cli" && !availability.has(runner.command)) {
782
+ availability.set(runner.command, resolveExternalCliBinaryAvailability(runner.command, process.env));
783
+ }
784
+ }
785
+ return availability;
786
+ }
787
+
788
+ function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string | undefined {
687
789
  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";
790
+ if (agent.runner?.type === "external-cli") {
791
+ const availability = externalCliAvailability?.get(agent.runner.command);
792
+ if (!availability) return "external-cli";
793
+ return `external-cli:${agent.runner.command} ${availability.available ? "✓" : "missing"}`;
794
+ }
689
795
  return undefined;
690
796
  }
691
797
 
692
- function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
798
+ function agentListMetadata(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string {
693
799
  const source = agent.source === "package" ? packageSourceLabel(agent) : agent.source;
694
- const parts = [
800
+ return [
695
801
  source,
696
- runnerListBadge(agent, providerNames),
802
+ runnerListBadge(agent, providerNames, externalCliAvailability),
697
803
  agent.defaultContext ? `context: ${agent.defaultContext}` : undefined,
698
804
  agent.aliases?.length ? `aliases: ${agent.aliases.join(", ")}` : undefined,
699
- ].filter((part): part is string => Boolean(part));
700
- return `- ${agent.name} (${parts.join(", ")}): ${agent.description}`;
805
+ ].filter((part): part is string => Boolean(part)).join(", ");
806
+ }
807
+
808
+ function formatAgentListLine(agent: AgentConfig, providerNames: Set<string> | undefined): string {
809
+ return `- ${agent.name} (${agentListMetadata(agent, providerNames)}): ${agent.description}`;
810
+ }
811
+
812
+ function formatAgentCapabilitiesLine(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string {
813
+ const declaredTools = [
814
+ ...(agent.tools ?? []),
815
+ ...(agent.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
816
+ ];
817
+ let tools = "none";
818
+ if (agent.tools === undefined && agent.mcpDirectTools === undefined) {
819
+ tools = "default/ambient";
820
+ } else if (declaredTools.length > 0) {
821
+ tools = declaredTools.join(", ");
822
+ }
823
+ if (agent.excludeTools?.length) tools = `${tools}; excludes: ${agent.excludeTools.join(", ")}`;
824
+ let model = "inherits current session";
825
+ if (agent.model !== undefined) {
826
+ model = agent.model;
827
+ if (agent.modelProvider && !agent.model.includes("/")) model = `${agent.modelProvider}/${agent.model}`;
828
+ }
829
+ const thinking = agent.thinking === false ? "off" : agent.thinking ?? "default";
830
+ return `- ${agent.name} (${agentListMetadata(agent, providerNames, externalCliAvailability)}): Description: ${previewDisplayText(agent.description, 240)}; Tools: ${tools}; Model: ${model}; Thinking: ${thinking}`;
701
831
  }
702
832
 
703
- function formatAgentListSections(agents: AgentConfig[], providerNames: Set<string> | undefined): string[] {
833
+ const EXTERNAL_JOB_CAPABILITIES = { stop: false, steer: false, resume: false, structuredOutput: false, toolEvents: false } as const;
834
+ const PI_AGENT_RUNNER = { type: "pi" } as const;
835
+
836
+ function listOrEmpty<T>(values: T[] | undefined): T[] {
837
+ return values ?? [];
838
+ }
839
+
840
+ function agentCapabilityRunner(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability: ExternalCliAvailabilityByCommand): AgentCapabilityRow["runner"] {
841
+ const runner = agent.runner;
842
+ if (!runner || runner.type === "pi") return PI_AGENT_RUNNER;
843
+ if (runner.type === "external-cli") {
844
+ const availability = externalCliAvailability.get(runner.command)!;
845
+ return {
846
+ type: "external-cli",
847
+ adapter: runner.adapter,
848
+ command: runner.command,
849
+ ...availability,
850
+ capabilities: resolveExternalCliRunnerStatus(runner).capabilities,
851
+ };
852
+ }
853
+ return { type: "external-job", provider: runner.provider, available: providerNames?.has(runner.provider), capabilities: EXTERNAL_JOB_CAPABILITIES };
854
+ }
855
+
856
+ function agentCapabilityTools(agent: AgentConfig): AgentCapabilityRow["tools"] {
857
+ return {
858
+ ambient: agent.tools === undefined && agent.mcpDirectTools === undefined,
859
+ names: listOrEmpty(agent.tools),
860
+ ...(agent.excludeTools !== undefined ? { excludeTools: [...agent.excludeTools] } : {}),
861
+ mcpDirectTools: listOrEmpty(agent.mcpDirectTools),
862
+ mutationTools: agent.mutationTools,
863
+ };
864
+ }
865
+
866
+ function agentCapabilityRow(agent: AgentConfig, options: { executable: boolean; providerNames?: Set<string>; externalCliAvailability: ExternalCliAvailabilityByCommand; restrictionSources?: string[] }): AgentCapabilityRow {
867
+ return {
868
+ name: agent.name,
869
+ description: previewDisplayText(agent.description, 1000),
870
+ source: agent.source,
871
+ executable: options.executable,
872
+ restrictionSources: options.executable ? undefined : options.restrictionSources ?? [],
873
+ aliases: agent.aliases ? [...agent.aliases] : undefined,
874
+ runner: agentCapabilityRunner(agent, options.providerNames, options.externalCliAvailability),
875
+ tools: agentCapabilityTools(agent),
876
+ model: presentDetails({ value: agent.model, fallbackModels: agent.fallbackModels, thinking: agent.thinking }),
877
+ execution: presentDetails({ defaultAsync: agent.defaultAsync, timeoutMs: agent.defaultTimeoutMs }),
878
+ output: presentDetails({ path: agent.output, mode: agent.outputMode }),
879
+ extensions: presentDetails({ names: agent.extensions, subagentOnly: agent.subagentOnlyExtensions, skills: agent.skills }),
880
+ };
881
+ }
882
+
883
+ function agentCapabilitiesSnapshot(input: { agents: AgentConfig[]; restrictedAgents: AgentConfig[]; providerNames?: Set<string>; externalCliAvailability: ExternalCliAvailabilityByCommand; restrictedSources?: string[] }): AgentCapabilitiesSnapshot {
884
+ return {
885
+ agents: [
886
+ ...input.agents.map((agent) => agentCapabilityRow(agent, { executable: true, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability })),
887
+ ...input.restrictedAgents.map((agent) => agentCapabilityRow(agent, { executable: false, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability, restrictionSources: input.restrictedSources })),
888
+ ],
889
+ restrictedCount: input.restrictedAgents.length,
890
+ ...(input.restrictedSources?.length ? { capabilityCeilingSources: [...input.restrictedSources] } : {}),
891
+ };
892
+ }
893
+
894
+ function providerNames(status: ExternalJobProviderStatus): Set<string> | undefined {
895
+ return status.ok ? status.names : undefined;
896
+ }
897
+
898
+ function appendRestrictedAgentLines(input: { lines: string[]; agents: AgentConfig[]; sources?: string[]; providerNames?: Set<string>; formatLine: (agent: AgentConfig, providerNames: Set<string> | undefined) => string }): void {
899
+ if (input.agents.length === 0) return;
900
+ input.lines.push(
901
+ "",
902
+ `Restricted agents (not executable in this session${input.sources?.length ? `; capability ceiling: ${input.sources.join(", ")}` : ""}):`,
903
+ ...input.agents.map((agent) => input.formatLine(agent, input.providerNames)),
904
+ );
905
+ }
906
+
907
+ function appendExternalJobRegistryLine(lines: string[], agents: AgentConfig[], status: ExternalJobProviderStatus): void {
908
+ if (status.ok || !agents.some((agent) => agent.runner?.type === "external-job")) return;
909
+ lines.push("", `External-job provider registry unavailable: ${status.error}`);
910
+ }
911
+
912
+ function appendAgentDiagnosticLines(lines: string[], diagnostics: AgentDiscoveryDiagnostic[] | undefined): void {
913
+ if (!diagnostics?.length) return;
914
+ lines.push(
915
+ "",
916
+ "Invalid agent definitions:",
917
+ ...diagnostics.map((diagnostic) => `- ${diagnostic.name ?? diagnostic.filePath} (${diagnostic.source}): ${diagnostic.error}`),
918
+ );
919
+ }
920
+
921
+ function agentCapabilityDetails(input: { capabilityMode: boolean; agents: AgentConfig[]; restrictedAgents: AgentConfig[]; providerNames?: Set<string>; externalCliAvailability: ExternalCliAvailabilityByCommand; restrictedSources?: string[] }): Partial<Details> | undefined {
922
+ if (!input.capabilityMode) return undefined;
923
+ return {
924
+ agentCapabilities: jsonDetails(agentCapabilitiesSnapshot({
925
+ agents: input.agents,
926
+ restrictedAgents: input.restrictedAgents,
927
+ providerNames: input.providerNames,
928
+ externalCliAvailability: input.externalCliAvailability,
929
+ restrictedSources: input.restrictedSources,
930
+ })),
931
+ };
932
+ }
933
+
934
+ function formatAgentListSections(
935
+ agents: AgentConfig[],
936
+ providerNames: Set<string> | undefined,
937
+ formatLine: (agent: AgentConfig, providerNames: Set<string> | undefined) => string = formatAgentListLine,
938
+ ): string[] {
704
939
  if (agents.length === 0) return ["- (none)"];
705
940
  const sections: Array<[AgentSource, string]> = [
706
941
  ["package", "Package agents"],
@@ -714,7 +949,7 @@ function formatAgentListSections(agents: AgentConfig[], providerNames: Set<strin
714
949
  const matches = agents.filter((agent) => agent.source === source);
715
950
  if (matches.length === 0) continue;
716
951
  if (lines.length > 0) lines.push("");
717
- lines.push(label, ...matches.map((agent) => formatAgentListLine(agent, providerNames)));
952
+ lines.push(label, ...matches.map((agent) => formatLine(agent, providerNames)));
718
953
  }
719
954
  return lines;
720
955
  }
@@ -742,6 +977,7 @@ function formatAgentDetail(agent: AgentConfig): string {
742
977
  if (agent.model) lines.push(`Model: ${agent.model}`);
743
978
  if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
744
979
  if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
980
+ if (agent.excludeTools?.length) lines.push(`Excluded tools: ${agent.excludeTools.join(", ")}`);
745
981
  if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
746
982
  if (agent.skillPath?.length) lines.push(`Skill paths: ${agent.skillPath.join(", ")}`);
747
983
  lines.push(`System prompt mode: ${agent.systemPromptMode}`);
@@ -752,16 +988,17 @@ function formatAgentDetail(agent: AgentConfig): string {
752
988
  if (agent.runner?.type === "external-job" && agent.runner.options) lines.push(`Runner options: ${JSON.stringify(agent.runner.options)}`);
753
989
  }
754
990
  lines.push(`Inherit project context: ${agent.inheritProjectContext ? "true" : "false"}`);
991
+ lines.push(`Inherit global context: ${agent.inheritGlobalContext ? "true" : "false"}`);
755
992
  lines.push(`Inherit skills: ${agent.inheritSkills ? "true" : "false"}`);
756
993
  if (agent.defaultContext) lines.push(`Default context: ${agent.defaultContext}`);
757
994
  if (agent.defaultAsync !== undefined) lines.push(`Async: ${agent.defaultAsync ? "true" : "false"}`);
758
995
  if (agent.defaultTimeoutMs !== undefined) lines.push(`Timeout: ${agent.defaultTimeoutMs}ms`);
759
- if (agent.defaultTurnBudget) lines.push(`Turn budget: ${JSON.stringify(agent.defaultTurnBudget)}`);
760
996
  if (agent.defaultAcceptance !== undefined) lines.push(`Acceptance: ${typeof agent.defaultAcceptance === "object" ? JSON.stringify(agent.defaultAcceptance) : String(agent.defaultAcceptance)}`);
761
997
  if (agent.acceptanceRole) lines.push(`Acceptance role: ${agent.acceptanceRole}`);
762
998
  if (agent.source === "builtin") lines.push(`Disabled: ${agent.disabled ? "true" : "false"}`);
763
999
  if (agent.extensions !== undefined) lines.push(`Extensions: ${agent.extensions.length ? agent.extensions.join(", ") : "(none)"}`);
764
1000
  if (agent.subagentOnlyExtensions !== undefined) lines.push(`Subagent-only extensions: ${agent.subagentOnlyExtensions.length ? agent.subagentOnlyExtensions.join(", ") : "(none)"}`);
1001
+ if (agent.mutationTools !== undefined) lines.push(`Mutation tools: ${agent.mutationTools.length ? agent.mutationTools.join(", ") : "(none)"}`);
765
1002
  if (agent.thinking) lines.push(`Thinking: ${agent.thinking}`);
766
1003
  if (agent.output) lines.push(`Output: ${agent.output}`);
767
1004
  if (agent.outputMode) lines.push(`Output mode: ${agent.outputMode}`);
@@ -770,6 +1007,7 @@ function formatAgentDetail(agent: AgentConfig): string {
770
1007
  if (agent.maxSubagentDepth !== undefined) lines.push(`Max subagent depth: ${agent.maxSubagentDepth}`);
771
1008
  if (agent.completionGuard === false) lines.push("Completion guard: false");
772
1009
  if (agent.toolBudget) lines.push(`Tool budget: ${JSON.stringify(agent.toolBudget)}`);
1010
+ if (agent.sandbox) lines.push(`Sandbox profile: ${agent.sandbox}`);
773
1011
  if (agent.memory) lines.push(`Memory: ${agent.memory.scope} scope, path: ${agent.memory.path}`);
774
1012
  if (agent.systemPrompt.trim()) lines.push("", "System Prompt:", agent.systemPrompt);
775
1013
  return lines.join("\n");
@@ -777,17 +1015,8 @@ function formatAgentDetail(agent: AgentConfig): string {
777
1015
 
778
1016
  export function handleList(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
779
1017
  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
- }
1018
+ const d = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
1019
+ let scopedAgents = effectiveAgentsForScope(scope, d, ctx.runtimeAgentOwner);
791
1020
  scopedAgents = scopedAgents
792
1021
  .sort((a, b) => a.name.localeCompare(b.name));
793
1022
  const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
@@ -801,23 +1030,28 @@ export function handleList(params: ManagementParams, ctx: ManagementContext): Ag
801
1030
  discoverAvailableSkills: () => discoverAvailableSkills(ctx.cwd),
802
1031
  });
803
1032
  const providerStatus = registeredExternalJobProviderStatus();
1033
+ const providerNameSet = providerNames(providerStatus);
1034
+ const capabilityMode = params.capabilities === true;
1035
+ const externalCliAvailability = capabilityMode ? externalCliAvailabilityForAgents([...agents, ...restrictedAgents]) : undefined;
1036
+ const formatLine = capabilityMode
1037
+ ? (agent: AgentConfig, names: Set<string> | undefined) => formatAgentCapabilitiesLine(agent, names, externalCliAvailability)
1038
+ : formatAgentListLine;
804
1039
  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] : []),
1040
+ capabilityMode ? "Executable agents (capabilities):" : "Executable agents:",
1041
+ ...formatAgentListSections(agents, providerNameSet, formatLine),
819
1042
  ];
820
- return result(lines.join("\n"));
1043
+ appendRestrictedAgentLines({ lines, agents: restrictedAgents, sources: restrictedSources, providerNames: providerNameSet, formatLine });
1044
+ appendExternalJobRegistryLine(lines, [...agents, ...restrictedAgents], providerStatus);
1045
+ appendAgentDiagnosticLines(lines, d.agentDiagnostics);
1046
+ if (proactiveSuggestions.length) lines.push("", ...proactiveSuggestions);
1047
+ return result(lines.join("\n"), false, agentCapabilityDetails({
1048
+ capabilityMode,
1049
+ agents,
1050
+ restrictedAgents,
1051
+ providerNames: providerNameSet,
1052
+ externalCliAvailability: externalCliAvailability ?? new Map(),
1053
+ restrictedSources,
1054
+ }));
821
1055
  }
822
1056
 
823
1057
  function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undefined): string {
@@ -827,79 +1061,108 @@ function formatModelSource(agent: AgentConfig, currentModel: ParentModel | undef
827
1061
  if (agent.modelSource?.type === "subagents.defaultModel" && agent.model === agent.modelSource.model) {
828
1062
  return `${agent.modelSource.scope} defaultModel`;
829
1063
  }
830
- if (agent.model) return "builtin agent config";
1064
+ if (agent.model) return `${agent.source} agent config`;
831
1065
  if (currentModel) return "inherits current session model";
832
1066
  return "inherit requested, but no current session model is available";
833
1067
  }
834
1068
 
835
1069
  function handleModels(params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
836
1070
  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
- }
1071
+ const scope = normalizeListScope(params.agentScope);
1072
+ if (!scope) return result("agentScope must be 'user', 'project', or 'both' for models.", true);
840
1073
 
841
- const discovered = discoverAgentsAll(ctx.cwd);
842
- const builtinByName = new Map(discovered.builtin.map((agent) => [agent.name, agent]));
1074
+ const discovered = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
1075
+ const effectiveAgents = effectiveAgentsForScope(scope, discovered, ctx.runtimeAgentOwner)
1076
+ .sort((a, b) => a.name.localeCompare(b.name));
843
1077
  const availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
844
1078
  const currentModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
845
1079
  const preferredProvider = ctx.model?.provider;
846
- const names = requestedAgent ? [requestedAgent] : [...BUILTIN_AGENT_NAMES];
1080
+ const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId);
847
1081
 
1082
+ let selectedAgents = effectiveAgents;
848
1083
  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}`);
863
- }
864
- if (agent.model && resolvedModel && agent.model !== resolvedModel) {
865
- lines.push("Requested model setting:");
866
- lines.push(` ${agent.model}`);
1084
+ const matches = findAgentsInDiscovery(requestedAgent, discovered, scope, ctx.runtimeAgentOwner);
1085
+ const diagnostics = diagnosticsForScope(discovered.agentDiagnostics, scope);
1086
+ const normalizedName = sanitizeName(requestedAgent);
1087
+ const diagnostic = findBlockingAgentDiagnostic(requestedAgent, matches, diagnostics)
1088
+ ?? (normalizedName !== requestedAgent ? findBlockingAgentDiagnostic(normalizedName, matches, diagnostics) : undefined);
1089
+ if (diagnostic) return result(`Agent '${params.agent}' has invalid configuration: ${diagnostic.error}`, true);
1090
+ const distinctNames = [...new Set(matches.map((agent) => agent.name))];
1091
+ if (distinctNames.length > 1) return result(`Ambiguous agent alias or name '${params.agent}': ${distinctNames.sort((a, b) => a.localeCompare(b)).join(", ")}`, true);
1092
+ if (!matches.length) {
1093
+ return result(`Agent '${params.agent}' not found. Available: ${availableAgentNamesFromDiscovery(discovered, ctx.runtimeAgentOwner).join(", ") || "none"}.`, true);
867
1094
  }
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"));
1095
+ selectedAgents = [matches[0]!];
872
1096
  }
873
1097
 
874
1098
  const lines = [
875
- "Builtin subagent models",
876
- "",
877
- "Current session model:",
878
- ` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
1099
+ requestedAgent ? "Subagent model" : "Subagent models",
879
1100
  "",
1101
+ ...(requestedAgent ? [] : [
1102
+ "Current session model:",
1103
+ ` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`,
1104
+ "",
1105
+ ]),
880
1106
  ];
881
1107
 
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;
1108
+ const modelEntries = selectedAgents.flatMap((agent) => requestedAgent
1109
+ ? [{ agent, name: requestedAgent }]
1110
+ : [{ agent, name: agent.name }, ...(agent.aliases ?? []).map((name) => ({ agent, name }))]);
1111
+ for (const { agent, name } of modelEntries) {
1112
+ const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, agent.modelProvider ?? preferredProvider);
1113
+ const effectiveThinking = resolveEffectiveThinking(resolvedModel, agent.thinking)
1114
+ ?? (agent.thinking === false ? "off" : undefined);
1115
+ const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}${isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling) ? "" : "; restricted"}`;
1116
+ if (requestedAgent) {
1117
+ lines.push(`Agent: ${requestedAgent}`);
1118
+ lines.push("Effective model:");
1119
+ lines.push(` ${resolvedModel ?? "(unresolved)"}`);
1120
+ lines.push(`Source: ${source}`);
1121
+ lines.push(`Thinking: ${effectiveThinking ?? "default"}`);
1122
+ if (agent.fallbackModels?.length) {
1123
+ lines.push("Fallback models:");
1124
+ for (const fallback of agent.fallbackModels) {
1125
+ lines.push(` ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
1126
+ }
1127
+ }
1128
+ if (agent.override) {
1129
+ lines.push("Override file:");
1130
+ lines.push(` ${agent.override.path}`);
1131
+ }
1132
+ if (agent.model && resolvedModel && agent.model !== resolvedModel) {
1133
+ lines.push("Requested model setting:");
1134
+ lines.push(` ${agent.model}`);
1135
+ }
1136
+ if (agent.disabled) lines.push("Disabled: true");
1137
+ if (!isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling)) lines.push("Restricted: true");
1138
+ lines.push("Current session model:");
1139
+ lines.push(` ${currentModel ? `${currentModel.provider}/${currentModel.id}` : "(unavailable)"}`);
1140
+ break;
891
1141
  }
892
- const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, preferredProvider);
893
- const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}`;
894
1142
  lines.push(name);
895
1143
  lines.push(" model:");
896
1144
  lines.push(` ${resolvedModel ?? "(unresolved)"}`);
897
1145
  lines.push(` source: ${source}`);
1146
+ lines.push(` thinking: ${effectiveThinking ?? "default"}`);
1147
+ if (agent.fallbackModels?.length) {
1148
+ lines.push(" fallback models:");
1149
+ for (const fallback of agent.fallbackModels) {
1150
+ lines.push(` ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
1151
+ }
1152
+ }
1153
+ if (agent.override) {
1154
+ lines.push(" override file:");
1155
+ lines.push(` ${agent.override.path}`);
1156
+ }
1157
+ if (agent.model && resolvedModel && agent.model !== resolvedModel) {
1158
+ lines.push(" requested model setting:");
1159
+ lines.push(` ${agent.model}`);
1160
+ }
898
1161
  lines.push("");
899
1162
  }
900
1163
 
901
1164
  const availableFullIds = availableModels.map((m) => m.fullId).sort();
902
- if (availableFullIds.length > 0) {
1165
+ if (!requestedAgent && availableFullIds.length > 0) {
903
1166
  lines.push("Available models in this session's registry (copy an exact provider/id when passing model):");
904
1167
  lines.push("");
905
1168
  const shown = availableFullIds.slice(0, 80);
@@ -908,7 +1171,7 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
908
1171
  lines.push("");
909
1172
  lines.push("Use an exact provider/id from this list when you pass model; bare ids resolve only when unique in the registry.");
910
1173
  }
911
-
1174
+ if (!requestedAgent) appendAgentDiagnosticLines(lines, diagnosticsForScope(discovered.agentDiagnostics, scope));
912
1175
  return result(lines.join("\n"));
913
1176
  }
914
1177
 
@@ -916,7 +1179,7 @@ function handleGet(params: ManagementParams, ctx: ManagementContext): AgentToolR
916
1179
  if (!params.agent) return result("Specify 'agent' for get.", true);
917
1180
  const scope = normalizeListScope(params.agentScope);
918
1181
  if (!scope) return result("agentScope must be 'user', 'project', or 'both' for get.", true);
919
- const discovered = discoverAgentsAll(ctx.cwd);
1182
+ const discovered = discoverAgentsAll(ctx.cwd, ctx.model?.provider);
920
1183
  const matches = findAgentsInDiscovery(params.agent, discovered, scope);
921
1184
  const diagnostics = diagnosticsForScope(discovered.agentDiagnostics, scope);
922
1185
  const rawName = params.agent.trim();
@@ -946,7 +1209,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
946
1209
  const runtimeName = buildRuntimeName(name, parsedPackage.packageName);
947
1210
  const scopeRaw = cfg.scope ?? "user";
948
1211
  if (scopeRaw !== "user" && scopeRaw !== "project") return result("config.scope must be 'user' or 'project'.", true);
949
- const scope = scopeRaw as ManagementScope;
1212
+ const scope = scopeRaw;
950
1213
  if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
951
1214
  const d = discoverAgentsAll(ctx.cwd);
952
1215
  const projectConfigDir = getProjectConfigDir(ctx.cwd);
@@ -967,10 +1230,13 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
967
1230
  systemPrompt: "",
968
1231
  systemPromptMode: defaultSystemPromptMode(name),
969
1232
  inheritProjectContext: defaultInheritProjectContext(name),
1233
+ inheritGlobalContext: false,
970
1234
  inheritSkills: defaultInheritSkills(),
971
1235
  };
972
1236
  const applyError = applyAgentConfig(agent, cfg);
973
1237
  if (applyError) return result(applyError, true);
1238
+ const profileError = validateCodeOwnedProfileRunner(agent);
1239
+ if (profileError) return result(profileError, true);
974
1240
  const mw = modelWarning(ctx, agent.model);
975
1241
  if (mw) warnings.push(mw);
976
1242
  const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
@@ -1022,6 +1288,8 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
1022
1288
  if (newPackageName !== undefined) updated.packageName = newPackageName;
1023
1289
  else delete updated.packageName;
1024
1290
  updated.name = buildRuntimeName(newLocalName, newPackageName);
1291
+ const profileError = validateCodeOwnedProfileRunner(updated);
1292
+ if (profileError) return result(profileError, true);
1025
1293
  if (hasKey(cfg, "description")) updated.description = (cfg.description as string).trim();
1026
1294
  if (hasKey(cfg, "model")) {
1027
1295
  const mw = modelWarning(ctx, updated.model);
@@ -1167,6 +1435,7 @@ function validateEjectedAgentLaunchPreflight(agent: AgentConfig, cwd: string): s
1167
1435
  cwd,
1168
1436
  requireReadTool: resolvedSkills.resolved.length > 0,
1169
1437
  agentName: agent.name,
1438
+ sandbox: agent.sandbox,
1170
1439
  });
1171
1440
  } catch (error) {
1172
1441
  return error instanceof Error ? error.message : String(error);
@@ -1435,7 +1704,7 @@ function handleReset(params: ManagementParams, ctx: ManagementContext): AgentToo
1435
1704
  }
1436
1705
 
1437
1706
  export function handleManagementAction(action: string, params: ManagementParams, ctx: ManagementContext): AgentToolResult<Details> {
1438
- switch (action as ManagementAction) {
1707
+ switch (action) {
1439
1708
  case "list": return handleList(params, ctx);
1440
1709
  case "get": return handleGet(params, ctx);
1441
1710
  case "models": return handleModels(params, ctx);