@xzzpig/pi-subagents 0.14.0 → 0.15.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 (198) hide show
  1. package/CHANGELOG.md +233 -0
  2. package/README.md +6 -5
  3. package/agents/evidence-auditor.md +34 -0
  4. package/agents/researcher.md +23 -13
  5. package/agents/reviewer.md +3 -2
  6. package/docs/agents.md +56 -15
  7. package/docs/configuration.md +92 -14
  8. package/docs/extension-api.md +132 -19
  9. package/docs/missions.md +10 -2
  10. package/docs/models.md +11 -22
  11. package/docs/observability.md +63 -11
  12. package/docs/standalone-background.md +59 -0
  13. package/docs/tool-reference.md +42 -23
  14. package/docs/watchdog.md +39 -10
  15. package/docs/workflows.md +58 -19
  16. package/index.ts +5 -2
  17. package/inspector-runner.mjs +2 -2
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
  19. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
  21. package/package.json +9 -4
  22. package/prompts/parallel-review.md +1 -1
  23. package/runner-peer-loader.mjs +24 -0
  24. package/runner-peer-preload.mjs +36 -0
  25. package/skills/pi-subagents/SKILL.md +34 -22
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
  27. package/skills/pi-subagents/references/execution-controls.md +27 -8
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
  31. package/skills/pi-subagents/references/review-and-validation.md +3 -3
  32. package/src/agents/advertised-agent-prompt.ts +94 -0
  33. package/src/agents/agent-management.ts +71 -59
  34. package/src/agents/agent-serializer.ts +6 -3
  35. package/src/agents/agents.ts +198 -72
  36. package/src/agents/builtin-names.ts +1 -0
  37. package/src/agents/chain-serializer.ts +5 -0
  38. package/src/agents/runtime-agent-registry.ts +7 -6
  39. package/src/api/delegation.ts +4 -0
  40. package/src/api/preflight.ts +110 -71
  41. package/src/api/required-child-extensions.ts +6 -0
  42. package/src/api/shared-types.ts +3 -1
  43. package/src/api/workflow-resources.ts +6 -0
  44. package/src/extension/config.ts +14 -37
  45. package/src/extension/fanout-child.ts +68 -5
  46. package/src/extension/herdr-pi-bridge.ts +164 -0
  47. package/src/extension/index.ts +141 -51
  48. package/src/extension/public-execution.ts +7 -6
  49. package/src/extension/rpc.ts +8 -21
  50. package/src/extension/schemas.ts +86 -84
  51. package/src/extension/tool-description.ts +32 -79
  52. package/src/inspectors/actions.ts +148 -0
  53. package/src/inspectors/ghostty/actions.ts +74 -0
  54. package/src/inspectors/ghostty/plugin.ts +17 -0
  55. package/src/inspectors/herdr/actions.ts +99 -179
  56. package/src/inspectors/herdr/plugin.ts +20 -0
  57. package/src/inspectors/herdr/project-panes.ts +4 -1
  58. package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
  59. package/src/inspectors/plugins.ts +8 -0
  60. package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
  61. package/src/inspectors/types.ts +51 -0
  62. package/src/integrations/pi-web-session-liveness.ts +73 -0
  63. package/src/intercom/intercom-bridge.ts +50 -8
  64. package/src/intercom/native-supervisor-channel.ts +142 -115
  65. package/src/intercom/supervisor-ui.ts +3 -2
  66. package/src/missions/workflow-state.ts +37 -16
  67. package/src/policy/authority.ts +4 -0
  68. package/src/profiles/profiles.ts +12 -6
  69. package/src/runs/background/active-async-capacity.ts +22 -18
  70. package/src/runs/background/active-run-index.ts +17 -1
  71. package/src/runs/background/async-execution.ts +359 -176
  72. package/src/runs/background/async-job-tracker.ts +41 -7
  73. package/src/runs/background/async-resume.ts +19 -12
  74. package/src/runs/background/async-retention.ts +20 -0
  75. package/src/runs/background/async-status-snapshot.ts +10 -12
  76. package/src/runs/background/async-status.ts +32 -13
  77. package/src/runs/background/auto-drain.ts +59 -35
  78. package/src/runs/background/binary-bootstrap.ts +38 -0
  79. package/src/runs/background/chain-append.ts +1 -1
  80. package/src/runs/background/chain-root-attachment.ts +22 -33
  81. package/src/runs/background/control-channel.ts +78 -44
  82. package/src/runs/background/fleet-view.ts +30 -2
  83. package/src/runs/background/notify.ts +193 -19
  84. package/src/runs/background/owned-process-tree.ts +35 -8
  85. package/src/runs/background/process-terminal.ts +23 -23
  86. package/src/runs/background/result-files.ts +8 -4
  87. package/src/runs/background/result-watcher.ts +19 -2
  88. package/src/runs/background/retained-nested-route-tracker.ts +96 -0
  89. package/src/runs/background/run-child-session.ts +118 -41
  90. package/src/runs/background/run-status.ts +78 -5
  91. package/src/runs/background/runner-aliases.ts +22 -5
  92. package/src/runs/background/runner-child-launch.ts +93 -0
  93. package/src/runs/background/runner-child-sessions.ts +5 -4
  94. package/src/runs/background/runner-http-dispatcher.ts +119 -0
  95. package/src/runs/background/scheduled-runs.ts +51 -18
  96. package/src/runs/background/stale-run-reconciler.ts +38 -12
  97. package/src/runs/background/steering.ts +20 -2
  98. package/src/runs/background/subagent-runner.ts +766 -432
  99. package/src/runs/background/subagent-wait.ts +179 -28
  100. package/src/runs/background/wait-completions.ts +79 -27
  101. package/src/runs/background/wait-subscriptions.ts +9 -3
  102. package/src/runs/background/wait-tool.ts +5 -3
  103. package/src/runs/foreground/async-steering-action.ts +37 -7
  104. package/src/runs/foreground/async-stop-action.ts +93 -3
  105. package/src/runs/foreground/execution.ts +174 -194
  106. package/src/runs/foreground/foreground-history.ts +5 -2
  107. package/src/runs/foreground/prompt-audit.ts +12 -6
  108. package/src/runs/foreground/subagent-executor.ts +896 -397
  109. package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
  110. package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
  111. package/src/runs/shared/acceptance.ts +54 -14
  112. package/src/runs/shared/agent-contract.ts +1 -1
  113. package/src/runs/shared/async-status-projection.ts +172 -78
  114. package/src/runs/shared/capability-ceiling.ts +2 -0
  115. package/src/runs/shared/child-hooks.ts +167 -3
  116. package/src/runs/shared/child-launch-plan.ts +15 -3
  117. package/src/runs/shared/child-launch.ts +44 -16
  118. package/src/runs/shared/child-lifecycle.ts +6 -3
  119. package/src/runs/shared/child-runtime-config.ts +8 -1
  120. package/src/runs/shared/child-session.ts +130 -24
  121. package/src/runs/shared/child-tool-plan.ts +145 -14
  122. package/src/runs/shared/completion-evidence.ts +2 -2
  123. package/src/runs/shared/completion-guard.ts +6 -3
  124. package/src/runs/shared/dynamic-fanout.ts +2 -2
  125. package/src/runs/shared/effective-system-prompt.ts +33 -0
  126. package/src/runs/shared/external-cli-contract.ts +11 -1
  127. package/src/runs/shared/external-cli-preflight.ts +6 -2
  128. package/src/runs/shared/external-cli-runner.ts +9 -7
  129. package/src/runs/shared/herdr-connection.ts +134 -0
  130. package/src/runs/shared/herdr-external-adapters.ts +169 -0
  131. package/src/runs/shared/herdr-machine.ts +279 -0
  132. package/src/runs/shared/herdr-pi-protocol.ts +59 -0
  133. package/src/runs/shared/herdr-placed-run.ts +263 -0
  134. package/src/runs/shared/host-step-status.ts +11 -11
  135. package/src/runs/shared/llm-intent-arbiter.ts +40 -21
  136. package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
  137. package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
  138. package/src/runs/shared/model-scope.ts +1 -1
  139. package/src/runs/shared/nested-events.ts +19 -10
  140. package/src/runs/shared/orca-progress-tabs.ts +7 -1
  141. package/src/runs/shared/parallel-handoff.ts +57 -12
  142. package/src/runs/shared/parallel-utils.ts +10 -4
  143. package/src/runs/shared/pi-spawn.ts +10 -0
  144. package/src/runs/shared/readonly-drain-observation.ts +42 -0
  145. package/src/runs/shared/run-fanout-budget.ts +8 -8
  146. package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
  147. package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
  148. package/src/runs/shared/task-intent.ts +46 -13
  149. package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
  150. package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
  151. package/src/runs/shared/worktree-setup-command.ts +213 -0
  152. package/src/runs/shared/worktree.ts +437 -214
  153. package/src/shared/child-cache-retention.ts +43 -0
  154. package/src/shared/fork-context.ts +15 -72
  155. package/src/shared/launch-contract.ts +70 -8
  156. package/src/shared/model-response-aliases.ts +13 -0
  157. package/src/shared/opencode-session-headers.ts +30 -0
  158. package/src/shared/pruned-fork.ts +1 -1
  159. package/src/shared/required-child-extensions.ts +81 -0
  160. package/src/shared/settings.ts +5 -2
  161. package/src/shared/shortcuts.ts +0 -4
  162. package/src/shared/types.ts +163 -90
  163. package/src/shared/utils.ts +10 -2
  164. package/src/shared/watch-strategy.ts +2 -0
  165. package/src/shared/workflow-child-permit.ts +18 -13
  166. package/src/slash/delegation-adapters.ts +3 -1
  167. package/src/slash/delegation-request.ts +14 -0
  168. package/src/slash/slash-commands.ts +2 -7
  169. package/src/slash/subagents-admin.ts +31 -14
  170. package/src/tui/fleet-status.ts +165 -20
  171. package/src/tui/fleet.ts +30 -19
  172. package/src/tui/render.ts +210 -50
  173. package/src/watchdog/child-status.ts +28 -28
  174. package/src/watchdog/lsp-diagnostics.ts +1 -1
  175. package/src/watchdog/model-selection.ts +21 -1
  176. package/src/watchdog/permission-arbiter.ts +5 -2
  177. package/src/watchdog/register-child.ts +10 -2
  178. package/src/watchdog/register-main.ts +39 -35
  179. package/src/watchdog/render.ts +1 -1
  180. package/src/watchdog/review.ts +122 -74
  181. package/src/watchdog/rules.ts +1 -1
  182. package/src/watchdog/runtime.ts +100 -27
  183. package/src/watchdog/scope.ts +1 -1
  184. package/src/watchdog/settings.ts +3 -0
  185. package/src/watchdog/tool-actions.ts +13 -12
  186. package/src/watchdog/turn-delta.ts +23 -0
  187. package/src/watchdog/types.ts +5 -3
  188. package/src/watchdog/warning-format.ts +1 -1
  189. package/src/workflows/chat-progress.ts +3 -3
  190. package/src/workflows/scripted-workflow.ts +349 -26
  191. package/src/workflows/workflow-checklist.ts +17 -20
  192. package/src/workflows/workflow-child-summary.ts +57 -8
  193. package/src/workflows/workflow-preflight.ts +19 -19
  194. package/src/workflows/workflow-receipt.ts +24 -6
  195. package/src/workflows/workflow-resources.ts +108 -22
  196. package/src/workflows/workflow-settlement.ts +3 -0
  197. package/src/runs/shared/model-exclusions.ts +0 -373
  198. /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
@@ -8,12 +8,17 @@ Parent extensions may register a session-scoped, out-of-band ceiling through `@x
8
8
 
9
9
  ## When to Use
10
10
 
11
- - **Complex work orchestration**: keep the parent on its ordinary strong default model. Delegate only when another child materially improves evidence, independent review, or isolated execution; omission failures are cheaper than unnecessary commissions. For hard orchestration or root-cause questions, use a top-reasoning model only as a bounded read-only critic/oracle escalation, never as an autonomous root. Complex means the task has multiple moving parts, unclear acceptance, cross-cutting code, meaningful user-visible impact, expensive or irreversible validation, broad review surface, or the user asks for orchestration. Lightweight one-off delegation can stay lightweight.
11
+ All launch guidance below assumes delegation was requested by the operator in
12
+ the current request or applicable user/project instructions. Complexity,
13
+ workflow fit, and potential quality gains help choose a shape after that gate;
14
+ they do not authorize a launch.
15
+
16
+ - **Complex work orchestration**: after delegation is authorized, keep the parent on its ordinary strong default model and launch only when a bounded child materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. For hard orchestration or root-cause questions, use a top-reasoning model only as a bounded read-only critic/oracle escalation, never as an autonomous root. Lightweight one-off delegation can stay lightweight.
12
17
  - **Advisory review**: use fresh-context `reviewer` agents for adversarial code review; fork to `oracle` only for rare escalation where inherited decisions, drift, model routing, root cause, or hard tradeoffs matter
13
18
  - **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
14
19
  - **Recon and planning**: use `scout`, then write a plan when needed
15
20
  - **Parallel exploration**: run multiple non-conflicting tasks concurrently
16
- - **Regular skill specialists**: when discovery shows proactive skill subagent suggestions and the current work is broad enough, launch a small fresh-context fanout that asks one subagent per relevant regularly used skill to apply that skill's perspective to the task
21
+ - **Regular skill specialists**: when authorized delegation names or benefits from a relevant specialization, discovery suggestions may help select a small fresh-context fanout
17
22
  - **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard tool-call caps for explicitly read-only children.
18
23
  - **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
19
24
  - **Agent authoring**: create, update, or override project agents. Treat saved chain records as legacy inspection or migration inputs, not as a current authoring target.
@@ -29,7 +34,7 @@ Agents use the `subagent(...)` tool for execution, management, status, and contr
29
34
  - `/subagents-detach [run-id]` — detach an active foreground single-subagent run without terminating its child
30
35
  - `/subagents-steer <run-id> [--child <child-id>] <message>` — steer a live async run (or one child of it) from non-TUI sessions and RPC hosts
31
36
  - `/subagent-cost` — show parent plus child token usage and cost for the session
32
- - `/subagents-fleet` — open the live fleet inspector with per-child controls; `Ctrl+Alt+F` opens it during an active foreground turn, `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
37
+ - `/subagents-fleet` — open the live fleet inspector with per-child controls; `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
33
38
  - `/subagents-watchdog` — inspect or configure the opt-in adversarial change watchdog (model, on/off, recommend-model, check)
34
39
  - `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
35
40
  - `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
@@ -39,7 +44,7 @@ Agents use the `subagent(...)` tool for execution, management, status, and contr
39
44
  Prefer the tool when you are writing agent logic. Prefer the slash commands when
40
45
  you are guiding a human through an interactive flow.
41
46
 
42
- Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, or when the workflow clearly fits, apply the same pattern directly with `subagent(...)` and other tools:
47
+ Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, apply the same pattern directly with `subagent(...)` and other tools:
43
48
  - `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
44
49
  - `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped
45
50
  - `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
@@ -53,7 +58,7 @@ The prompt templates in `prompts/` encode workflows the parent agent can run on
53
58
 
54
59
  ### Commission-risk and cold-start packets
55
60
 
56
- Delegate only when the child materially improves evidence, independent review, or isolated execution; do not manufacture parallelism. Every child packet must be cold-start complete: state the goal, exact target/cwd/ref, authority and edit boundary, relevant context/evidence, success criteria, validation, output, and stop/escalation rules. For an orchestration audit by the critic tier, make the child read-only and request at most three omissions, each cited to a file, line, or decision; high thinking is an explicit escalation, not a default.
61
+ After the operator-authority gate above, delegate only when the child materially improves evidence, independent review, specialization, useful parallelism, or isolated execution; do not manufacture parallelism. Every child packet must be cold-start complete: state the goal, exact target/cwd/ref, authority and edit boundary, relevant context/evidence, success criteria, validation, output, and stop/escalation rules. For an orchestration audit by the critic tier, make the child read-only and request at most three omissions, each cited to a file, line, or decision; high thinking is an explicit escalation, not a default.
57
62
 
58
63
  ### Council Mode technique
59
64
 
@@ -63,11 +68,11 @@ Council advisors are read-only. User or project `council-*` profiles choose allo
63
68
 
64
69
  ### Parallel review technique
65
70
 
66
- Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. Filter on evidence, not severity: report only concrete current issues caused or made reachable by the target diff, with source proof, a test or repro, or a contract contradiction. Label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred. For targeted follow-up, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
71
+ Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. Filter on evidence, not severity: report concrete current issues within the named review target, with source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred. For targeted follow-up, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
67
72
 
68
73
  ### Proactive skill-specialist technique
69
74
 
70
- Use this when `{ action: "list" }` reports proactive skill subagent suggestions and the user's task would benefit from perspectives the parent regularly uses. These suggestions are conservative: a skill is recommended only when it is available and referenced repeatedly by configured agents or saved chains. Treat the list as an opt-in hint for the current task, not a command to always fan out.
75
+ Use this only within operator-authorized delegation when `{ action: "list" }` reports skill subagent suggestions relevant to the requested handoff. Availability is a selection hint, not authority or a command to fan out.
71
76
 
72
77
  Default guardrails:
73
78
  - Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap.
@@ -105,11 +110,11 @@ Use this when the question needs both external evidence and local implications.
105
110
 
106
111
  ### Gather-context-and-clarify technique
107
112
 
108
- Use this at the start of non-trivial work. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
113
+ Use this when the operator requests delegated context gathering. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
109
114
 
110
115
  ### Parallel cleanup technique
111
116
 
112
- Use this after implementation when the user wants cleanup review or when a final pass would reduce AI-slop. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
117
+ Use this after implementation when the user or applicable instructions request delegated cleanup review. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
113
118
 
114
119
  ### Staged fix orchestration technique
115
120
 
@@ -203,7 +208,7 @@ For one run, use inline config:
203
208
 
204
209
  For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Use `/subagents-models` or `subagent({ action: "models" })` to inspect the live mapping after settings and overrides load.
205
210
 
206
- Provider-scoped entries can layer on top of the default override for the active parent session provider. The provider is selected once from the parent model before child model fallback starts, so fallback attempts cannot switch configuration. Within each settings file, the provider entry wins per field; project settings still win over user settings.
211
+ Provider-scoped entries can layer on top of the default override for the active parent session provider. The provider is selected once from the parent model. Within each settings file, the provider entry wins per field; project settings still win over user settings.
207
212
 
208
213
  ```json
209
214
  {
@@ -261,7 +266,6 @@ Direct settings example:
261
266
  "reviewer": {
262
267
  "model": "provider/strong-review-model",
263
268
  "thinking": "high",
264
- "fallbackModels": ["backup-provider/strong-review-model"],
265
269
  "acceptanceRole": "read-only"
266
270
  }
267
271
  }
@@ -269,7 +273,7 @@ Direct settings example:
269
273
  }
270
274
  ```
271
275
 
272
- Useful override fields: `description`, `model`, `fallbackModels`, `thinking`,
276
+ Useful override fields: `description`, `model`, `thinking`,
273
277
  `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`,
274
278
  `acceptanceRole`, `disabled`, `skills`, `tools`, `extensions`, and `systemPrompt`.
275
279
  `description` replaces the discovered description for builtin and custom agents
@@ -283,7 +287,7 @@ Keep the parent/orchestrator on the ordinary strong default model because omissi
283
287
 
284
288
  Examples are illustrative, not requirements. Map these tiers to concrete models in user/project settings or a profile. A non-OpenAI setup should choose comparable available models by capability.
285
289
 
286
- Use `fallbackModels` when a tier has provider quota or availability risk. Prefer fresh context for cross-provider children when inherited provider-specific reasoning blocks would force thinking off.
290
+ Each child launch uses one resolved model exactly once. If quota or availability fails, surface that failure and let the parent or operator explicitly launch a later attempt with another model. Forked children keep their requested thinking level even when provider-specific reasoning blocks are stripped from the inherited transcript.
287
291
 
288
292
  If a provider rejects model IDs with thinking suffixes, use
289
293
  `subagents.disableThinking: true` in user or project settings to clear bundled
@@ -1,6 +1,6 @@
1
1
  # Pi Subagents: Review And Validation
2
2
 
3
- Generic review and delivery guidance for delegated work. This file does not encode private backlog, merge, or release policy.
3
+ Generic review and delivery guidance for operator-authorized delegated work. This file does not encode private backlog, merge, or release policy.
4
4
 
5
5
  ## Delivery loop
6
6
 
@@ -9,7 +9,7 @@ Use the smallest loop that proves the change:
9
9
  1. Inspect the source, diff, issue, or plan directly.
10
10
  2. Keep one writer for each cwd or worktree.
11
11
  3. Run focused validation that can fail for the changed behavior.
12
- 4. Use fresh-context read-only review for substantial, risky, public, or hard-to-see changes.
12
+ 4. When the operator/project delegation contract calls for independent review, use a fresh-context read-only reviewer; otherwise parent inspection is valid.
13
13
  5. Apply only accepted findings inside the same writer boundary.
14
14
  6. Re-run affected validation and review only the changed blast radius.
15
15
  7. Inspect the final diff and evidence before parent acceptance.
@@ -61,7 +61,7 @@ Before reporting delegated work as done, verify the relevant subset:
61
61
 
62
62
  - final diff contains only intended files
63
63
  - focused validation covers changed behavior
64
- - substantial or risky changes have fresh-review evidence
64
+ - required independent review has fresh-review evidence
65
65
  - accepted findings are fixed and revalidated
66
66
  - publication authority exists before push, comment, close, merge, deploy, or release
67
67
  - external checks are exact-head when used as evidence
@@ -0,0 +1,94 @@
1
+ import { Buffer } from "node:buffer";
2
+ import type { ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
3
+ import { isAgentAllowedByCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
4
+ import type { AgentConfig } from "./agents.ts";
5
+
6
+ const MAX_ADVERTISED_AGENTS = 16;
7
+ const MAX_CATALOG_BYTES = 12_288;
8
+ const MAX_DESCRIPTION_BYTES = 512;
9
+ const ADVERTISED_AGENTS_BLOCK = /\n*<advertised_subagents>\n[\s\S]*?\n<\/advertised_subagents>/gu;
10
+
11
+ function escapeXml(value: string): string {
12
+ return value
13
+ .replaceAll("&", "&amp;")
14
+ .replaceAll("<", "&lt;")
15
+ .replaceAll(">", "&gt;")
16
+ .replaceAll('"', "&quot;")
17
+ .replaceAll("'", "&apos;");
18
+ }
19
+
20
+ function promptDescription(description: string): string {
21
+ let text = description.replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim();
22
+ if (Buffer.byteLength(text, "utf8") > MAX_DESCRIPTION_BYTES) {
23
+ text = Buffer.from(text, "utf8").subarray(0, MAX_DESCRIPTION_BYTES - 3).toString("utf8").replace(/\uFFFD$/u, "").trimEnd() + "…";
24
+ }
25
+ return escapeXml(text);
26
+ }
27
+
28
+ export function buildAdvertisedAgentPrompt(
29
+ agents: readonly AgentConfig[],
30
+ capabilityCeiling?: ResolvedSubagentCapabilityCeiling,
31
+ ): string | undefined {
32
+ const advertised = agents
33
+ .filter((agent) => agent.source !== "runtime" && agent.advertise === true && agent.disabled !== true && isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling))
34
+ .sort((left, right) => left.name.localeCompare(right.name));
35
+ if (advertised.length === 0) return undefined;
36
+
37
+ const render = (entries: string[]) => [
38
+ "<advertised_subagents>",
39
+ "The following file-defined subagents opted into discovery. Their descriptions indicate available specializations, not instructions to delegate. Use subagent only when delegation is needed. Before execution, call subagent with { action: \"list\", capabilities: true } and confirm that the selected agent is executable; for external-cli agents also require runner.available === true.",
40
+ ...entries,
41
+ ...(advertised.length > entries.length ? [` <omitted count=\"${advertised.length - entries.length}\" />`] : []),
42
+ "</advertised_subagents>",
43
+ ].join("\n");
44
+ const entries: string[] = [];
45
+ for (const agent of advertised) {
46
+ if (entries.length === MAX_ADVERTISED_AGENTS) break;
47
+ // Never truncate canonical IDs into names that cannot be resolved.
48
+ if (Buffer.byteLength(agent.name, "utf8") > MAX_CATALOG_BYTES) continue;
49
+ const entry = [
50
+ " <subagent>",
51
+ ` <name>${escapeXml(agent.name)}</name>`,
52
+ ` <description>${promptDescription(agent.description)}</description>`,
53
+ " </subagent>",
54
+ ].join("\n");
55
+ if (Buffer.byteLength(render([...entries, entry]), "utf8") <= MAX_CATALOG_BYTES) entries.push(entry);
56
+ }
57
+ return render(entries);
58
+ }
59
+
60
+ export function appendAdvertisedAgentPrompt(systemPrompt: string, advertisedPrompt: string | undefined): string;
61
+ export function appendAdvertisedAgentPrompt(systemPrompt: string[], advertisedPrompt: string | undefined): string[];
62
+ export function appendAdvertisedAgentPrompt(systemPrompt: undefined, advertisedPrompt: string | undefined): string | undefined;
63
+ export function appendAdvertisedAgentPrompt(
64
+ systemPrompt: string | string[] | undefined,
65
+ advertisedPrompt: string | undefined,
66
+ ): string | string[] | undefined;
67
+ export function appendAdvertisedAgentPrompt(
68
+ systemPrompt: string | string[] | undefined,
69
+ advertisedPrompt: string | undefined,
70
+ ): string | string[] | undefined {
71
+ if (Array.isArray(systemPrompt)) {
72
+ let changed = false;
73
+ const cleaned = systemPrompt
74
+ .map((part) => {
75
+ if (typeof part !== "string") return part;
76
+ const stripped = part.replace(ADVERTISED_AGENTS_BLOCK, "");
77
+ if (stripped !== part) changed = true;
78
+ return stripped;
79
+ })
80
+ .filter((b) => typeof b === "string" && b.length > 0);
81
+
82
+ if (advertisedPrompt) {
83
+ return [...cleaned, advertisedPrompt];
84
+ }
85
+ return changed ? cleaned : systemPrompt;
86
+ }
87
+
88
+ if (typeof systemPrompt === "string") {
89
+ const base = systemPrompt.replace(ADVERTISED_AGENTS_BLOCK, "");
90
+ return advertisedPrompt ? (base.trim() ? `${base.trimEnd()}\n\n${advertisedPrompt}` : advertisedPrompt) : base;
91
+ }
92
+
93
+ return advertisedPrompt;
94
+ }
@@ -30,9 +30,9 @@ import {
30
30
  import { parseFrontmatter, parseFrontmatterList } from "./frontmatter.ts";
31
31
  import { resolvePiLaunchToolPlan } from "../runs/shared/child-tool-plan.ts";
32
32
  import { resolveEffectiveThinking, toModelInfo } from "../shared/model-info.ts";
33
- import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-fallback.ts";
33
+ import { resolveSubagentModelOverride, type ParentModel } from "../runs/shared/model-resolution.ts";
34
34
  import { validateToolBudgetConfig } from "../runs/shared/tool-budget.ts";
35
- import { validateAcceptanceInput } from "../runs/shared/acceptance.ts";
35
+ import { formatReviewGateLabel, validateAcceptanceInput } from "../runs/shared/acceptance.ts";
36
36
  import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, resolveExternalCliRunnerStatus, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
37
37
  import { resolveExternalCliBinaryAvailability, type ExternalCliBinaryAvailability } from "../runs/shared/external-cli-preflight.ts";
38
38
  import type { AcceptanceInput, AgentCapabilitiesSnapshot, AgentCapabilityRow, Details, ExtensionConfig, ToolBudgetConfig } from "../shared/types.ts";
@@ -100,7 +100,7 @@ export type EjectAgentDefinitionResult =
100
100
 
101
101
  type ManagementAction = "list" | "get" | "models" | "create" | "update" | "delete" | "eject" | "disable" | "enable" | "reset";
102
102
  type ManagementScope = "user" | "project";
103
- type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { isProjectTrusted?: ExtensionContext["isProjectTrusted"]; model?: ExtensionContext["model"]; config?: ExtensionConfig; currentSessionId?: string; runtimeAgentOwner?: RuntimeAgentOwner };
103
+ type ManagementContext = Pick<ExtensionContext, "cwd" | "modelRegistry"> & { isProjectTrusted?: ExtensionContext["isProjectTrusted"]; model?: ExtensionContext["model"]; config?: ExtensionConfig; currentSessionId?: string; runtimeAgentOwner?: RuntimeAgentOwner; onAgentsChanged?: () => void };
104
104
 
105
105
  interface ManagementParams {
106
106
  action?: string;
@@ -280,13 +280,6 @@ function modelWarning(ctx: ManagementContext, model: string | undefined): string
280
280
  return `Warning: model '${model}' is not in the current model registry. Run subagent({ action: "models" }) to list valid provider/id selectors, then use the exact provider/id form (bare ids resolve only when unique).`;
281
281
  }
282
282
 
283
- function fallbackModelsWarning(ctx: ManagementContext, fallbackModels: string[] | undefined): string | undefined {
284
- if (!fallbackModels || fallbackModels.length === 0) return undefined;
285
- const available = new Set(ctx.modelRegistry.getAvailable().flatMap((m) => [`${m.provider}/${m.id}`, m.id]));
286
- const missing = fallbackModels.filter((model) => !available.has(model));
287
- return missing.length ? `Warning: fallback models not in the current model registry: ${missing.join(", ")}.` : undefined;
288
- }
289
-
290
283
  function skillsWarning(cwd: string, agent: Pick<AgentConfig, "skills" | "skillPath" | "filePath">): string | undefined {
291
284
  if (!agent.skills?.length) return undefined;
292
285
  const { missing } = resolveSkills(
@@ -330,7 +323,6 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
330
323
  outputMode: _outputMode,
331
324
  defaultReads: _defaultReads,
332
325
  model: _model,
333
- fallbackModels: _fallbackModels,
334
326
  fast: _fast,
335
327
  thinking: _thinking,
336
328
  systemPromptMode: _systemPromptMode,
@@ -367,7 +359,6 @@ export function editableAgentConfig(agent: AgentConfig): AgentConfig {
367
359
  ...(base.outputMode !== undefined ? { outputMode: base.outputMode } : {}),
368
360
  ...(base.defaultReads !== undefined ? { defaultReads: [...base.defaultReads] } : {}),
369
361
  ...(base.model !== undefined && hasDeclaredField("model") ? { model: base.model } : {}),
370
- ...(base.fallbackModels !== undefined ? { fallbackModels: [...base.fallbackModels] } : {}),
371
362
  ...(base.fast !== undefined ? { fast: base.fast } : {}),
372
363
  ...(base.thinking !== undefined && hasDeclaredField("thinking") ? { thinking: base.thinking } : {}),
373
364
  systemPromptMode: base.systemPromptMode,
@@ -410,11 +401,11 @@ export function preservedAgentFrontmatterFields(agent: AgentConfig, cfg: Record<
410
401
  if (hasKey(cfg, "name")) changed("name");
411
402
  if (hasKey(cfg, "package")) changed("package");
412
403
  if (hasKey(cfg, "description")) changed("description");
404
+ if (hasKey(cfg, "advertise")) changed("advertise");
413
405
  if (hasKey(cfg, "aliases")) changed("alias", "aliases");
414
406
  if (hasKey(cfg, "systemPrompt")) changed("systemPrompt");
415
407
  if (hasKey(cfg, "runner")) changed("runner");
416
408
  if (hasKey(cfg, "model")) changed("model");
417
- if (hasKey(cfg, "fallbackModels")) changed("fallbackModels");
418
409
  if (hasKey(cfg, "tools")) changed("tools");
419
410
  if (hasKey(cfg, "excludeTools")) changed("excludeTools");
420
411
  if (hasKey(cfg, "skills")) changed("skill", "skills");
@@ -479,6 +470,11 @@ function parseTools(raw: string): { tools?: string[]; mcpDirectTools?: string[]
479
470
  }
480
471
 
481
472
  function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): string | undefined {
473
+ if (hasKey(cfg, "advertise")) {
474
+ if (cfg.advertise === "") delete target.advertise;
475
+ else if (typeof cfg.advertise === "boolean") target.advertise = cfg.advertise;
476
+ else return "config.advertise must be a boolean or empty string when provided.";
477
+ }
482
478
  if (hasKey(cfg, "aliases")) {
483
479
  if (cfg.aliases === false || cfg.aliases === "") delete target.aliases;
484
480
  else if (typeof cfg.aliases === "string") {
@@ -524,21 +520,7 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
524
520
  else delete target.model;
525
521
  } else return "config.model must be a string or false when provided.";
526
522
  }
527
- if (hasKey(cfg, "fallbackModels")) {
528
- if (cfg.fallbackModels === false || cfg.fallbackModels === "") delete target.fallbackModels;
529
- else if (typeof cfg.fallbackModels === "string") {
530
- const models = parseCsv(cfg.fallbackModels);
531
- if (models.length) target.fallbackModels = models;
532
- else delete target.fallbackModels;
533
- } else if (Array.isArray(cfg.fallbackModels)) {
534
- const models = cfg.fallbackModels
535
- .filter((value): value is string => typeof value === "string")
536
- .map((value) => value.trim())
537
- .filter(Boolean);
538
- if (models.length) target.fallbackModels = [...new Set(models)];
539
- else delete target.fallbackModels;
540
- } else return "config.fallbackModels must be a comma-separated string, string array, or false when provided.";
541
- }
523
+ if (hasKey(cfg, "fallbackModels")) return "config.fallbackModels was removed; configure one model instead.";
542
524
  if (hasKey(cfg, "tools")) {
543
525
  if (cfg.tools === false || cfg.tools === "") { delete target.tools; delete target.mcpDirectTools; }
544
526
  else if (typeof cfg.tools === "string") {
@@ -711,7 +693,6 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
711
693
  target.tools?.length || target.mcpDirectTools?.length ? "tools" : undefined,
712
694
  target.excludeTools?.length ? "excludeTools" : undefined,
713
695
  target.model ? "model" : undefined,
714
- target.fallbackModels?.length ? "fallbackModels" : undefined,
715
696
  target.thinking ? "thinking" : undefined,
716
697
  target.extensions?.length ? "extensions" : undefined,
717
698
  target.subagentOnlyExtensions?.length ? "subagentOnlyExtensions" : undefined,
@@ -789,13 +770,19 @@ function externalJobProviderSuffix(provider: string, names: Set<string> | undefi
789
770
 
790
771
  type ExternalCliAvailabilityByCommand = ReadonlyMap<string, ExternalCliBinaryAvailability>;
791
772
 
773
+ /** A placed agent checks only local ssh; machine catalog and remote CLI validation happen at launch. */
774
+ function externalCliAvailabilityKey(command: string, machine: string | undefined): string {
775
+ return machine ? `ssh@${machine}` : command;
776
+ }
777
+
792
778
  function externalCliAvailabilityForAgents(agents: readonly AgentConfig[]): ExternalCliAvailabilityByCommand {
793
779
  const availability = new Map<string, ExternalCliBinaryAvailability>();
794
780
  for (const agent of agents) {
795
781
  const runner = agent.runner;
796
- if (runner?.type === "external-cli" && !availability.has(runner.command)) {
797
- availability.set(runner.command, resolveExternalCliBinaryAvailability(runner.command, process.env));
798
- }
782
+ if (runner?.type !== "external-cli") continue;
783
+ const key = externalCliAvailabilityKey(runner.command, agent.machine);
784
+ if (availability.has(key)) continue;
785
+ availability.set(key, resolveExternalCliBinaryAvailability(agent.machine ? "ssh" : runner.command, process.env));
799
786
  }
800
787
  return availability;
801
788
  }
@@ -803,10 +790,13 @@ function externalCliAvailabilityForAgents(agents: readonly AgentConfig[]): Exter
803
790
  function runnerListBadge(agent: AgentConfig, providerNames: Set<string> | undefined, externalCliAvailability?: ExternalCliAvailabilityByCommand): string | undefined {
804
791
  if (agent.runner?.type === "external-job") return `external-job:${agent.runner.provider} ${externalJobProviderSuffix(agent.runner.provider, providerNames)}`;
805
792
  if (agent.runner?.type === "external-cli") {
806
- const availability = externalCliAvailability?.get(agent.runner.command);
807
- if (!availability) return "external-cli";
808
- return `external-cli:${agent.runner.command} ${availability.available ? "✓" : "missing"}`;
793
+ const placed = agent.machine ? `${agent.runner.command} @ ${agent.machine}` : agent.runner.command;
794
+ const availability = externalCliAvailability?.get(externalCliAvailabilityKey(agent.runner.command, agent.machine));
795
+ if (!availability) return `external-cli:${placed}`;
796
+ if (agent.machine) return `external-cli:${placed} saved Herdr placement; transport ${availability.available ? "✓" : "missing"}; machine not preflighted`;
797
+ return `external-cli:${placed} ${availability.available ? "✓" : "missing"}`;
809
798
  }
799
+ if (agent.machine) return `machine: ${agent.machine} (saved Herdr placement)`;
810
800
  return undefined;
811
801
  }
812
802
 
@@ -842,7 +832,39 @@ function formatAgentCapabilitiesLine(agent: AgentConfig, providerNames: Set<stri
842
832
  if (agent.modelProvider && !agent.model.includes("/")) model = `${agent.modelProvider}/${agent.model}`;
843
833
  }
844
834
  const thinking = agent.thinking === false ? "off" : agent.thinking ?? "default";
845
- return `- ${agent.name} (${agentListMetadata(agent, providerNames, externalCliAvailability)}): Description: ${previewDisplayText(agent.description, 240)}; Tools: ${tools}; Model: ${model}; Thinking: ${thinking}`;
835
+ const machine = agent.machine ? `; Machine: ${agent.machine} (saved Herdr placement)` : "";
836
+ const acceptance = formatAcceptanceSummary(agent);
837
+ return `- ${agent.name} (${agentListMetadata(agent, providerNames, externalCliAvailability)}): Description: ${previewDisplayText(agent.description, 240)}; Tools: ${tools}; Model: ${model}; Thinking: ${thinking}${machine}${acceptance ? `; ${acceptance}` : ""}`;
838
+ }
839
+
840
+ function formatAcceptanceSummary(agent: AgentConfig): string | undefined {
841
+ const policy = agent.defaultAcceptance;
842
+ const summary: string[] = [];
843
+ if (policy === false) summary.push("Acceptance: disabled");
844
+ else if (typeof policy === "string") summary.push(`Acceptance: ${policy}`);
845
+ else if (policy) {
846
+ const modifiers = [
847
+ ...(policy.evidence ?? []),
848
+ ...(policy.verify ?? []).map((command) => `verify: ${formatAcceptanceDisplayLabel(command.id)}`),
849
+ ...(policy.criteria?.length ? [`criteria: ${policy.criteria.length}`] : []),
850
+ ...(policy.stopRules?.length ? [`stopRules: ${policy.stopRules.length}`] : []),
851
+ ];
852
+ if (policy.review === false) modifiers.push("review: off");
853
+ else if (policy.review) {
854
+ const displayReview = policy.review.agent
855
+ ? { ...policy.review, agent: formatAcceptanceDisplayLabel(policy.review.agent) }
856
+ : policy.review;
857
+ modifiers.push(`review: ${formatReviewGateLabel(displayReview)}`);
858
+ }
859
+ if (policy.report) modifiers.push(`report: ${policy.report}`);
860
+ summary.push(`Acceptance: ${policy.level ?? "auto"}${modifiers.length > 0 ? ` (${modifiers.join(", ")})` : ""}`);
861
+ }
862
+ if (agent.acceptanceRole) summary.push(`Acceptance role: ${agent.acceptanceRole}`);
863
+ return summary.length > 0 ? summary.join("; ") : undefined;
864
+ }
865
+
866
+ function formatAcceptanceDisplayLabel(value: string): string {
867
+ return JSON.stringify(previewDisplayText(value, 80));
846
868
  }
847
869
 
848
870
  const EXTERNAL_JOB_CAPABILITIES = { stop: false, steer: false, resume: false, structuredOutput: false, toolEvents: false } as const;
@@ -856,11 +878,12 @@ function agentCapabilityRunner(agent: AgentConfig, providerNames: Set<string> |
856
878
  const runner = agent.runner;
857
879
  if (!runner || runner.type === "pi") return PI_AGENT_RUNNER;
858
880
  if (runner.type === "external-cli") {
859
- const availability = externalCliAvailability.get(runner.command)!;
881
+ const availability = externalCliAvailability.get(externalCliAvailabilityKey(runner.command, agent.machine))!;
860
882
  return {
861
883
  type: "external-cli",
862
884
  adapter: runner.adapter,
863
885
  command: runner.command,
886
+ ...(agent.machine ? { machine: agent.machine } : {}),
864
887
  ...availability,
865
888
  capabilities: resolveExternalCliRunnerStatus(runner).capabilities,
866
889
  };
@@ -888,8 +911,9 @@ function agentCapabilityRow(agent: AgentConfig, options: { executable: boolean;
888
911
  aliases: agent.aliases ? [...agent.aliases] : undefined,
889
912
  runner: agentCapabilityRunner(agent, options.providerNames, options.externalCliAvailability),
890
913
  tools: agentCapabilityTools(agent),
891
- model: presentDetails({ value: agent.model, fallbackModels: agent.fallbackModels, thinking: agent.thinking }),
914
+ model: presentDetails({ value: agent.model, thinking: agent.thinking }),
892
915
  execution: presentDetails({ defaultAsync: agent.defaultAsync, timeoutMs: agent.defaultTimeoutMs }),
916
+ acceptance: presentDetails({ policy: agent.defaultAcceptance, role: agent.acceptanceRole }),
893
917
  output: presentDetails({ path: agent.output, mode: agent.outputMode }),
894
918
  extensions: presentDetails({ names: agent.extensions, subagentOnly: agent.subagentOnlyExtensions, skills: agent.skills }),
895
919
  };
@@ -990,7 +1014,6 @@ function formatAgentDetail(agent: AgentConfig): string {
990
1014
  }
991
1015
  if (agent.aliases?.length) lines.push(`Aliases: ${agent.aliases.join(", ")}`);
992
1016
  if (agent.model) lines.push(`Model: ${agent.model}`);
993
- if (agent.fallbackModels?.length) lines.push(`Fallback models: ${agent.fallbackModels.join(", ")}`);
994
1017
  if (tools.length) lines.push(`Tools: ${tools.join(", ")}`);
995
1018
  if (agent.excludeTools?.length) lines.push(`Excluded tools: ${agent.excludeTools.join(", ")}`);
996
1019
  if (agent.skills?.length) lines.push(`Skills: ${agent.skills.join(", ")}`);
@@ -1135,12 +1158,6 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
1135
1158
  lines.push(` ${resolvedModel ?? "(unresolved)"}`);
1136
1159
  lines.push(`Source: ${source}`);
1137
1160
  lines.push(`Thinking: ${effectiveThinking ?? "default"}`);
1138
- if (agent.fallbackModels?.length) {
1139
- lines.push("Fallback models:");
1140
- for (const fallback of agent.fallbackModels) {
1141
- lines.push(` ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
1142
- }
1143
- }
1144
1161
  if (agent.override) {
1145
1162
  lines.push("Override file:");
1146
1163
  lines.push(` ${agent.override.path}`);
@@ -1160,12 +1177,6 @@ function handleModels(params: ManagementParams, ctx: ManagementContext): AgentTo
1160
1177
  lines.push(` ${resolvedModel ?? "(unresolved)"}`);
1161
1178
  lines.push(` source: ${source}`);
1162
1179
  lines.push(` thinking: ${effectiveThinking ?? "default"}`);
1163
- if (agent.fallbackModels?.length) {
1164
- lines.push(" fallback models:");
1165
- for (const fallback of agent.fallbackModels) {
1166
- lines.push(` ${resolveSubagentModelOverride(fallback, currentModel, availableModels, agent.modelProvider ?? preferredProvider) ?? fallback}`);
1167
- }
1168
- }
1169
1180
  if (agent.override) {
1170
1181
  lines.push(" override file:");
1171
1182
  lines.push(` ${agent.override.path}`);
@@ -1255,11 +1266,10 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
1255
1266
  if (profileError) return result(profileError, true);
1256
1267
  const mw = modelWarning(ctx, agent.model);
1257
1268
  if (mw) warnings.push(mw);
1258
- const fmw = fallbackModelsWarning(ctx, agent.fallbackModels);
1259
- if (fmw) warnings.push(fmw);
1260
1269
  const sw = skillsWarning(ctx.cwd, agent);
1261
1270
  if (sw) warnings.push(sw);
1262
1271
  fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
1272
+ ctx.onAgentsChanged?.();
1263
1273
  return result([`Created agent '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
1264
1274
  }
1265
1275
 
@@ -1311,10 +1321,6 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
1311
1321
  const mw = modelWarning(ctx, updated.model);
1312
1322
  if (mw) warnings.push(mw);
1313
1323
  }
1314
- if (hasKey(cfg, "fallbackModels")) {
1315
- const fmw = fallbackModelsWarning(ctx, updated.fallbackModels);
1316
- if (fmw) warnings.push(fmw);
1317
- }
1318
1324
  if (hasKey(cfg, "skills") || hasKey(cfg, "skillPath")) {
1319
1325
  const sw = skillsWarning(ctx.cwd, updated);
1320
1326
  if (sw) warnings.push(sw);
@@ -1325,6 +1331,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
1325
1331
  updated.filePath = renamed.filePath!;
1326
1332
  }
1327
1333
  fs.writeFileSync(updated.filePath, serializeAgent(updated, { preserveFrontmatterFields }), "utf-8");
1334
+ ctx.onAgentsChanged?.();
1328
1335
  const headline = updated.name === oldName
1329
1336
  ? `Updated agent '${updated.name}' at ${updated.filePath}.`
1330
1337
  : `Updated agent '${oldName}' to '${updated.name}' at ${updated.filePath}.`;
@@ -1338,6 +1345,7 @@ function handleDelete(params: ManagementParams, ctx: ManagementContext): AgentTo
1338
1345
  if ("content" in targetOrError) return targetOrError;
1339
1346
  const target = targetOrError;
1340
1347
  fs.unlinkSync(target.filePath);
1348
+ ctx.onAgentsChanged?.();
1341
1349
  return result(`Deleted agent '${target.name}' at ${target.filePath}.`);
1342
1350
  }
1343
1351
 
@@ -1624,6 +1632,7 @@ function handleEject(params: ManagementParams, ctx: ManagementContext): AgentToo
1624
1632
  // must supply affirmative project trust themselves.
1625
1633
  ...(scope === "project" ? { projectTrusted: true } : {}),
1626
1634
  });
1635
+ if (ejected.ok) ctx.onAgentsChanged?.();
1627
1636
  return result(ejected.message, !ejected.ok);
1628
1637
  }
1629
1638
 
@@ -1646,6 +1655,7 @@ function handleDisable(params: ManagementParams, ctx: ManagementContext): AgentT
1646
1655
  const settingsPath = mergeBuiltinAgentOverride(ctx.cwd, runtimeName, scope, { disabled: true });
1647
1656
  const after = resolveEffectiveAgent(discoverAgentsAll(ctx.cwd), raw).agent;
1648
1657
  if (after?.disabled === true) {
1658
+ ctx.onAgentsChanged?.();
1649
1659
  return result(`Disabled agent '${runtimeName}' via ${scope} settings override at ${settingsPath}. It is now hidden from runtime discovery and { action: "list" }.`);
1650
1660
  }
1651
1661
  return result(`Wrote a disabled override for '${runtimeName}' at ${settingsPath}, but the agent is still enabled. A higher-precedence ${after?.override?.scope ?? "project"} override is likely winning. Try agentScope: '${after?.override?.scope ?? "project"}'.`, true);
@@ -1670,6 +1680,7 @@ function handleEnable(params: ManagementParams, ctx: ManagementContext): AgentTo
1670
1680
  const { path: settingsPath, removed } = removeBuiltinAgentOverrideFields(ctx.cwd, runtimeName, scope, ["disabled"]);
1671
1681
  const after = resolveEffectiveAgent(discoverAgentsAll(ctx.cwd), raw).agent;
1672
1682
  if (after && after.disabled !== true) {
1683
+ if (removed) ctx.onAgentsChanged?.();
1673
1684
  if (removed) return result(`Enabled agent '${runtimeName}' (removed disabled override at ${settingsPath}).`);
1674
1685
  return result(`Agent '${runtimeName}' is already enabled.`);
1675
1686
  }
@@ -1705,8 +1716,8 @@ function handleReset(params: ManagementParams, ctx: ManagementContext): AgentToo
1705
1716
  fs.unlinkSync(custom.filePath);
1706
1717
  lines.push(`Deleted custom ${scope} agent file at ${custom.filePath}.`);
1707
1718
  }
1708
- const overrideRemoval = removeBuiltinAgentOverride(ctx.cwd, runtimeName, scope);
1709
- if (overrideRemoval.removed) lines.push(`Removed ${scope} settings override at ${overrideRemoval.path}.`);
1719
+ const overrideRemoval = removeBuiltinAgentOverride(ctx.cwd, runtimeName, scope, { preserveMachine: true });
1720
+ if (overrideRemoval.removed) lines.push(`${overrideRemoval.machinePreserved ? "Cleared customization in" : "Removed"} ${scope} settings override at ${overrideRemoval.path}.${overrideRemoval.machinePreserved ? " Retained machine placement." : ""}`);
1710
1721
  if (lines.length === 0) {
1711
1722
  const otherScope = scope === "user" ? "project" : "user";
1712
1723
  const otherCustom = (otherScope === "user" ? d.user : d.project).find((a) => a.name === raw || a.name === sanitized);
@@ -1717,6 +1728,7 @@ function handleReset(params: ManagementParams, ctx: ManagementContext): AgentToo
1717
1728
  return result(`Agent '${runtimeName}' has no ${scope} customization to reset.${note} It is at its bundled ${bundled.source} default.`);
1718
1729
  }
1719
1730
  lines.push(`Reset agent '${runtimeName}' to its bundled ${bundled.source} default.`);
1731
+ ctx.onAgentsChanged?.();
1720
1732
  return result(lines.join("\n"));
1721
1733
  }
1722
1734
 
@@ -6,13 +6,13 @@ export const KNOWN_FIELDS = new Set([
6
6
  "name",
7
7
  "package",
8
8
  "description",
9
+ "advertise",
9
10
  "alias",
10
11
  "aliases",
11
12
  "tools",
12
13
  "excludeTools",
13
14
  "allowNestedSubagents",
14
15
  "model",
15
- "fallbackModels",
16
16
  "fast",
17
17
  "thinking",
18
18
  "systemPromptMode",
@@ -31,8 +31,10 @@ export const KNOWN_FIELDS = new Set([
31
31
  "extensions",
32
32
  "subagentOnlyExtensions",
33
33
  "mutationTools",
34
+ "machine",
34
35
  "output",
35
36
  "outputMode",
37
+ "outputSchema",
36
38
  "defaultReads",
37
39
  "defaultProgress",
38
40
  "injectToContext",
@@ -65,6 +67,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
65
67
  lines.push(`name: ${frontmatterNameForConfig(config)}`);
66
68
  if (config.packageName) lines.push(`package: ${config.packageName}`);
67
69
  lines.push(`description: ${config.description}`);
70
+ if (config.advertise === true || preserve("advertise")) lines.push(`advertise: ${config.advertise === true ? "true" : "false"}`);
68
71
  const aliasesValue = joinComma(config.aliases);
69
72
  if (aliasesValue || preserve("alias", "aliases")) lines.push(`aliases: ${aliasesValue ?? ""}`);
70
73
 
@@ -81,8 +84,6 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
81
84
  }
82
85
 
83
86
  if (config.model || preserve("model")) lines.push(`model: ${config.model ?? ""}`);
84
- const fallbackModelsValue = joinComma(config.fallbackModels);
85
- if (fallbackModelsValue || preserve("fallbackModels")) lines.push(`fallbackModels: ${fallbackModelsValue ?? ""}`);
86
87
  if (config.fast === true || preserve("fast")) lines.push(`fast: ${config.fast === undefined ? "" : config.fast ? "true" : "false"}`);
87
88
  if ((config.thinking && (config.thinking !== "off" || preserve("thinking"))) || (!config.thinking && preserve("thinking"))) {
88
89
  lines.push(`thinking: ${config.thinking ?? ""}`);
@@ -128,8 +129,10 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
128
129
  const mutationToolsValue = joinComma(config.mutationTools);
129
130
  if (mutationToolsValue || preserve("mutationTools")) lines.push(`mutationTools: ${mutationToolsValue ?? ""}`);
130
131
 
132
+ if (config.machine || preserve("machine")) lines.push(`machine: ${config.machine ?? ""}`);
131
133
  if (config.output || preserve("output")) lines.push(`output: ${config.output ?? ""}`);
132
134
  if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);
135
+ if (config.outputSchema || preserve("outputSchema")) lines.push(`outputSchema: ${config.outputSchema ? JSON.stringify(config.outputSchema) : ""}`);
133
136
 
134
137
  const readsValue = joinComma(config.defaultReads);
135
138
  if (readsValue || preserve("defaultReads")) lines.push(`defaultReads: ${readsValue ?? ""}`);