@xzzpig/pi-subagents 0.24.2 → 0.25.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 (258) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/bundle/agent-management.js +4 -4
  3. package/bundle/agents.js +3 -3
  4. package/bundle/child-tool-plan.js +2 -2
  5. package/bundle/chunk-34TUUBRN.js +1107 -0
  6. package/bundle/{chunk-SW2VMNIU.js → chunk-5OD3OWTE.js} +2 -2
  7. package/bundle/{chunk-XWWUDWUW.js → chunk-5YEOWNSD.js} +371 -135
  8. package/bundle/{chunk-EUPJB4S7.js → chunk-5Z7JAORM.js} +196 -1219
  9. package/bundle/{chunk-LCDJWBVM.js → chunk-66JNFRFS.js} +1 -1
  10. package/bundle/{chunk-4UH4WS4G.js → chunk-6MNRKUHY.js} +23 -12
  11. package/bundle/{chunk-ED55MIC2.js → chunk-CGFF4WA3.js} +42 -19
  12. package/bundle/{chunk-TMHVDPYW.js → chunk-DLVPMML3.js} +263 -154
  13. package/bundle/chunk-HXRB42AF.js +108 -0
  14. package/bundle/{chunk-355ECEP2.js → chunk-IH7LQVEE.js} +29 -14
  15. package/bundle/{chunk-CYY5UMJU.js → chunk-IJWITCC6.js} +411 -249
  16. package/bundle/{chunk-RU522D5W.js → chunk-IKFKH5EL.js} +369 -50
  17. package/bundle/{chunk-Z6TFJ6BR.js → chunk-INWSUNI6.js} +1 -1
  18. package/bundle/{chunk-JEA2ZKUA.js → chunk-IUDEI6FJ.js} +35 -200
  19. package/bundle/{chunk-WW76JRIX.js → chunk-JAXVBXGF.js} +1 -1
  20. package/bundle/{chunk-ICNYIALB.js → chunk-JH5H4CYJ.js} +784 -474
  21. package/bundle/{chunk-35GII5EF.js → chunk-JWFLPSTP.js} +41 -117
  22. package/bundle/{chunk-224WMDIV.js → chunk-KCJFGKVK.js} +350 -123
  23. package/bundle/{chunk-RB4GELQA.js → chunk-LPJEKHOY.js} +1 -1
  24. package/bundle/chunk-LYKG4FKH.js +523 -0
  25. package/bundle/{chunk-X6LOM3Z4.js → chunk-LZ3HBDTR.js} +161 -78
  26. package/bundle/{chunk-FG6SQJAR.js → chunk-OGPOCGWX.js} +24 -6
  27. package/bundle/{chunk-BQ2OAB4Q.js → chunk-OSVXFWPG.js} +67 -30
  28. package/bundle/{chunk-FJWI64H7.js → chunk-RMSABUN3.js} +27 -13
  29. package/bundle/{chunk-H36HBZB2.js → chunk-SJPABBZG.js} +2 -2
  30. package/bundle/{chunk-3U633XDZ.js → chunk-U3ZDUUTM.js} +11 -3
  31. package/bundle/{chunk-LVWU2HOO.js → chunk-ULGMXABL.js} +16 -7
  32. package/bundle/{chunk-WPW4V6HM.js → chunk-W7ZA6TYD.js} +2 -2
  33. package/bundle/{chunk-V2KFIGFH.js → chunk-XAC2XNAP.js} +503 -304
  34. package/bundle/{chunk-O4D5PBVI.js → chunk-YWXILP5N.js} +3 -2
  35. package/bundle/control-channel.js +2 -2
  36. package/bundle/index.js +1 -1
  37. package/bundle/intercom-bridge.js +2 -2
  38. package/bundle/preflight.js +12 -10
  39. package/bundle/project-panes.js +3 -3
  40. package/bundle/workflow-resources.js +1 -1
  41. package/docs/agents.md +27 -6
  42. package/docs/configuration.md +20 -8
  43. package/docs/extension-api.md +18 -1
  44. package/docs/models.md +6 -2
  45. package/docs/observability.md +2 -0
  46. package/docs/tool-reference.md +7 -1
  47. package/docs/workflows.md +30 -2
  48. package/package.json +2 -2
  49. package/skills/pi-subagents/SKILL.md +15 -6
  50. package/skills/pi-subagents/references/prompting-and-roles.md +1 -0
  51. package/src/agents/agent-management.d.ts +1 -0
  52. package/src/agents/agent-management.js +46 -18
  53. package/src/agents/agent-memory.d.ts +1 -4
  54. package/src/agents/agent-memory.js +1 -4
  55. package/src/agents/agent-serializer.d.ts +2 -0
  56. package/src/agents/agent-serializer.js +1 -1
  57. package/src/agents/agents.d.ts +2 -3
  58. package/src/agents/agents.js +46 -20
  59. package/src/agents/frontmatter.js +1 -8
  60. package/src/agents/global-npm-root.d.ts +1 -0
  61. package/src/agents/global-npm-root.js +11 -3
  62. package/src/agents/skills.d.ts +0 -3
  63. package/src/agents/skills.js +0 -3
  64. package/src/api/preflight.d.ts +3 -1
  65. package/src/api/preflight.js +2 -0
  66. package/src/extension/config.d.ts +1 -0
  67. package/src/extension/config.js +13 -1
  68. package/src/extension/herdr-pi-bridge.js +10 -2
  69. package/src/extension/index.d.ts +0 -13
  70. package/src/extension/index.js +51 -37
  71. package/src/extension/public-execution.d.ts +1 -0
  72. package/src/extension/public-execution.js +4 -0
  73. package/src/extension/reply-workflow-script.js +24 -4
  74. package/src/extension/schemas.d.ts +12 -3
  75. package/src/extension/schemas.js +7 -3
  76. package/src/extension/session-switch.d.ts +25 -0
  77. package/src/extension/session-switch.js +138 -0
  78. package/src/extension/subagent-guide.d.ts +1 -1
  79. package/src/extension/subagent-guide.js +1 -1
  80. package/src/extension/subagent-launch-tool.d.ts +25 -0
  81. package/src/extension/subagent-launch-tool.js +48 -0
  82. package/src/extension/tool-activation.js +55 -15
  83. package/src/extension/tool-description.d.ts +1 -1
  84. package/src/extension/tool-description.js +14 -8
  85. package/src/inspectors/herdr/actions.d.ts +0 -1
  86. package/src/inspectors/herdr/actions.js +0 -1
  87. package/src/inspectors/session-roots-codec.d.ts +0 -1
  88. package/src/inspectors/session-roots-codec.js +0 -1
  89. package/src/inspectors/tmux/actions.d.ts +0 -1
  90. package/src/inspectors/tmux/actions.js +0 -1
  91. package/src/integrations/herdr-status.js +3 -8
  92. package/src/intercom/native-supervisor-channel.js +65 -9
  93. package/src/runs/background/async-execution.d.ts +7 -10
  94. package/src/runs/background/async-execution.js +66 -29
  95. package/src/runs/background/async-job-tracker.js +12 -0
  96. package/src/runs/background/async-resume.d.ts +2 -1
  97. package/src/runs/background/async-resume.js +114 -40
  98. package/src/runs/background/async-retention.d.ts +0 -2
  99. package/src/runs/background/async-retention.js +17 -6
  100. package/src/runs/background/async-status.d.ts +2 -0
  101. package/src/runs/background/async-status.js +4 -0
  102. package/src/runs/background/auto-drain.js +2 -1
  103. package/src/runs/background/boot-id.d.ts +1 -3
  104. package/src/runs/background/boot-id.js +1 -3
  105. package/src/runs/background/completion-batcher.d.ts +3 -4
  106. package/src/runs/background/completion-batcher.js +2 -3
  107. package/src/runs/background/control-channel.d.ts +0 -6
  108. package/src/runs/background/control-channel.js +0 -6
  109. package/src/runs/background/fleet-view.js +2 -3
  110. package/src/runs/background/notify.d.ts +0 -2
  111. package/src/runs/background/notify.js +0 -2
  112. package/src/runs/background/result-watcher.d.ts +1 -0
  113. package/src/runs/background/result-watcher.js +59 -29
  114. package/src/runs/background/resume-guidance.js +4 -2
  115. package/src/runs/background/retained-children.js +2 -1
  116. package/src/runs/background/run-child-session.d.ts +2 -3
  117. package/src/runs/background/run-child-session.js +5 -8
  118. package/src/runs/background/run-status.js +9 -7
  119. package/src/runs/background/runner-aliases.js +15 -0
  120. package/src/runs/background/scheduled-runs.d.ts +3 -1
  121. package/src/runs/background/scheduled-runs.js +13 -16
  122. package/src/runs/background/steering.d.ts +2 -11
  123. package/src/runs/background/steering.js +11 -6
  124. package/src/runs/background/subagent-runner.d.ts +2 -6
  125. package/src/runs/background/subagent-runner.js +88 -70
  126. package/src/runs/background/subagent-wait.js +12 -15
  127. package/src/runs/background/wait-config.d.ts +2 -0
  128. package/src/runs/background/wait-config.js +17 -3
  129. package/src/runs/background/wait-subscriptions.js +124 -12
  130. package/src/runs/background/wait-tool.js +4 -2
  131. package/src/runs/background/workflow-terminal-proof.d.ts +0 -1
  132. package/src/runs/background/workflow-terminal-proof.js +0 -1
  133. package/src/runs/foreground/async-steering-action.js +24 -9
  134. package/src/runs/foreground/async-stop-action.d.ts +1 -1
  135. package/src/runs/foreground/async-stop-action.js +9 -1
  136. package/src/runs/foreground/execution.d.ts +0 -3
  137. package/src/runs/foreground/execution.js +56 -24
  138. package/src/runs/foreground/prompt-audit.js +1 -0
  139. package/src/runs/foreground/subagent-executor.d.ts +5 -10
  140. package/src/runs/foreground/subagent-executor.js +164 -49
  141. package/src/runs/shared/acceptance.js +69 -26
  142. package/src/runs/shared/async-status-projection.d.ts +2 -0
  143. package/src/runs/shared/async-status-projection.js +10 -0
  144. package/src/runs/shared/child-commands.js +15 -2
  145. package/src/runs/shared/child-hooks.d.ts +1 -7
  146. package/src/runs/shared/child-hooks.js +13 -5
  147. package/src/runs/shared/child-launch.js +6 -2
  148. package/src/runs/shared/child-runtime-config.d.ts +0 -1
  149. package/src/runs/shared/child-session.d.ts +6 -5
  150. package/src/runs/shared/child-session.js +85 -38
  151. package/src/runs/shared/child-tool-plan.d.ts +0 -1
  152. package/src/runs/shared/child-tool-plan.js +0 -1
  153. package/src/runs/shared/claude-code-adapter.js +11 -0
  154. package/src/runs/shared/external-cli-contract.d.ts +49 -0
  155. package/src/runs/shared/external-cli-contract.js +18 -13
  156. package/src/runs/shared/external-cli-runner.js +26 -6
  157. package/src/runs/shared/herdr-connection.js +2 -1
  158. package/src/runs/shared/herdr-pane-host.d.ts +2 -2
  159. package/src/runs/shared/herdr-pane-host.js +17 -1
  160. package/src/runs/shared/herdr-placed-run.js +51 -24
  161. package/src/runs/shared/lane-metadata.d.ts +0 -1
  162. package/src/runs/shared/lane-metadata.js +0 -1
  163. package/src/runs/shared/mcp-config-sources.d.ts +4 -1
  164. package/src/runs/shared/mcp-config-sources.js +1 -1
  165. package/src/runs/shared/mcp-direct-tool-allowlist.d.ts +0 -3
  166. package/src/runs/shared/mcp-direct-tool-allowlist.js +26 -17
  167. package/src/runs/shared/mcp-direct-tool-grant.js +8 -1
  168. package/src/runs/shared/model-resolution-diagnostic.d.ts +0 -1
  169. package/src/runs/shared/model-resolution.d.ts +20 -5
  170. package/src/runs/shared/model-resolution.js +55 -50
  171. package/src/runs/shared/model-scope.d.ts +1 -5
  172. package/src/runs/shared/model-scope.js +1 -5
  173. package/src/runs/shared/mutation-evidence.d.ts +1 -1
  174. package/src/runs/shared/mutation-evidence.js +52 -7
  175. package/src/runs/shared/nested-events.d.ts +1 -0
  176. package/src/runs/shared/nested-events.js +1 -1
  177. package/src/runs/shared/parallel-utils.d.ts +0 -1
  178. package/src/runs/shared/permissions.js +5 -3
  179. package/src/runs/shared/placement-host.d.ts +5 -1
  180. package/src/runs/shared/rex-pane-host.d.ts +0 -1
  181. package/src/runs/shared/rex-pane-host.js +0 -2
  182. package/src/runs/shared/run-launch-folder.d.ts +12 -0
  183. package/src/runs/shared/run-launch-folder.js +21 -0
  184. package/src/runs/shared/runner-launcher.d.ts +12 -1
  185. package/src/runs/shared/runner-launcher.js +16 -0
  186. package/src/runs/shared/single-output.d.ts +3 -3
  187. package/src/runs/shared/single-output.js +5 -3
  188. package/src/runs/shared/structured-output.d.ts +8 -0
  189. package/src/runs/shared/structured-output.js +40 -5
  190. package/src/runs/shared/subagent-prompt-runtime.d.ts +0 -1
  191. package/src/runs/shared/subagent-prompt-runtime.js +18 -4
  192. package/src/runs/shared/supervisor-wait-timer.d.ts +16 -0
  193. package/src/runs/shared/supervisor-wait-timer.js +61 -0
  194. package/src/runs/shared/tool-timeout.js +2 -1
  195. package/src/runs/shared/worktree-cleanup-plan.d.ts +0 -1
  196. package/src/runs/shared/worktree-cleanup-plan.js +0 -1
  197. package/src/runs/shared/worktree.d.ts +3 -0
  198. package/src/runs/shared/worktree.js +20 -0
  199. package/src/shared/artifacts.d.ts +1 -0
  200. package/src/shared/artifacts.js +132 -22
  201. package/src/shared/capacity-resilient-json.d.ts +1 -1
  202. package/src/shared/child-cache-retention.d.ts +1 -2
  203. package/src/shared/child-cache-retention.js +1 -2
  204. package/src/shared/fleet-transcript-reader.d.ts +51 -0
  205. package/src/shared/fleet-transcript-reader.js +333 -0
  206. package/src/shared/formatters.d.ts +0 -18
  207. package/src/shared/formatters.js +0 -18
  208. package/src/shared/pruned-fork.js +2 -2
  209. package/src/shared/reported-progress.d.ts +1 -0
  210. package/src/shared/reported-progress.js +12 -0
  211. package/src/shared/session-succession.d.ts +16 -1
  212. package/src/shared/session-succession.js +41 -2
  213. package/src/shared/session-warnings.d.ts +7 -0
  214. package/src/shared/session-warnings.js +26 -0
  215. package/src/shared/settings.d.ts +0 -23
  216. package/src/shared/settings.js +3 -35
  217. package/src/shared/status-format.d.ts +1 -0
  218. package/src/shared/status-format.js +1 -1
  219. package/src/shared/types.d.ts +108 -59
  220. package/src/shared/types.js +0 -12
  221. package/src/shared/utils.d.ts +3 -15
  222. package/src/shared/utils.js +4 -22
  223. package/src/shared/wait-tool-name.d.ts +8 -0
  224. package/src/shared/wait-tool-name.js +13 -0
  225. package/src/slash/slash-commands.js +2 -1
  226. package/src/slash/subagent-cost.d.ts +3 -2
  227. package/src/slash/subagent-cost.js +22 -3
  228. package/src/slash/subagents-admin.js +0 -1
  229. package/src/tui/fleet-status.d.ts +0 -5
  230. package/src/tui/fleet-status.js +4 -24
  231. package/src/tui/fleet.js +6 -4
  232. package/src/tui/render.d.ts +0 -9
  233. package/src/tui/render.js +194 -68
  234. package/src/tui/subagent-messages.js +3 -2
  235. package/src/watchdog/model-selection.js +2 -2
  236. package/src/watchdog/permission-arbiter.js +1 -0
  237. package/src/watchdog/register-child.d.ts +2 -3
  238. package/src/watchdog/register-child.js +2 -3
  239. package/src/watchdog/review.d.ts +0 -5
  240. package/src/watchdog/review.js +4 -3
  241. package/src/watchdog/turn-delta.js +2 -1
  242. package/src/workflows/scripted-workflow.d.ts +2 -0
  243. package/src/workflows/scripted-workflow.js +344 -59
  244. package/src/workflows/structured-workflow-scripts.d.ts +4 -3
  245. package/src/workflows/structured-workflow-scripts.js +32 -11
  246. package/src/workflows/workflow-launch-record.d.ts +15 -6
  247. package/src/workflows/workflow-launch-record.js +30 -12
  248. package/src/workflows/workflow-receipt.js +36 -53
  249. package/src/workflows/workflow-resources.js +4 -4
  250. package/src/workflows/workflow-resume-claim.d.ts +2 -0
  251. package/src/workflows/workflow-resume-claim.js +3 -3
  252. package/src/workflows/workflow-resume.d.ts +1 -1
  253. package/src/workflows/workflow-resume.js +13 -8
  254. package/src/workflows/workflow-script-worker.d.ts +13 -0
  255. package/src/workflows/workflow-script-worker.js +81 -0
  256. package/workflow-script-process.cjs +36 -0
  257. package/workflow-script-worker.cjs +4 -1
  258. package/bundle/chunk-U4ODUYAG.js +0 -235
package/docs/workflows.md CHANGED
@@ -37,7 +37,7 @@ When the Pi process that ran an async workflow exits before the workflow finishe
37
37
 
38
38
  A stopped run is continued by one relaunch only. While that relaunch exists, another relaunch of the same stopped run, by the same script or by `options.reuseFrom`, is refused with `workflow run '<id>' was resumed as <new id>; wait on it or stop it.` If that relaunch stops the same way, relaunch it instead: it carries the children of every run before it. If the Pi process that started the relaunch exits before the relaunch begins, the stopped run can be relaunched again.
39
39
 
40
- To continue a stopped run without sending its script again, resume it by id from the session that owns it: `subagent({ action: "resume", id: "<stopped run id>" })` with no `message`. Every async top-level workflow saves its launch (the script or named resource, its `args` and options) when it starts, and the resume relaunches that launch with `options.reuseFrom` set to the stopped run, in the stopped run's cwd, with no more authority than it had. A named resource is resolved again and must still have the same script. The new run records `workflow.resumeOrigin: { sourceRunId, attempt }`, where `attempt` counts the resumes that followed a Pi exit. Another session cannot resume the run by id; reopen the session that started it, or relaunch the same script with `options.reuseFrom`. When the run cannot be resumed this way (it started before launches were saved, was launched from `tasks` or `chain`, or its resource changed), the refusal says so; relaunch the same script by hand with `options: { reuseFrom: "<stopped run id>" }`.
40
+ To continue a stopped run without sending its script again, resume it by id from the session that owns it: `subagent({ action: "resume", id: "<stopped run id>" })` with no `message`. Every async top-level workflow saves its launch (the script or named resource, its `args` and options) when it starts, outside its run directory, and the resume relaunches that launch with `options.reuseFrom` set to the stopped run, in the stopped run's cwd, with no more authority than it had. A named resource is resolved again and must still have the same script. The new run records `workflow.resumeOrigin: { sourceRunId, attempt }`, where `attempt` counts the resumes that followed a Pi exit. Another session cannot resume the run by id; reopen the session that started it, or relaunch the same script with `options.reuseFrom`. When the run cannot be resumed this way (it started before launches were saved outside run directories, was launched from `tasks` or `chain`, or its resource changed), the refusal says so; relaunch the same script by hand with `options: { reuseFrom: "<stopped run id>" }`.
41
41
 
42
42
  When the session that owns such a run is reopened or reloaded, the run is resumed this way automatically, once, if it was interrupted in the last 24 hours: for a Pi exit, measured from the last time the dead Pi process updated the run. Session start does not wait for the relaunch. A run that cannot be relaunched is named in its notice (`Not auto-resumed: …`, with how to continue by hand); a launch that fails after session start also posts one `Workflow <id> was not auto-resumed: <reason>.` message. Either way the run is not tried again. `/new` and forks do not resume the runs of the session they replaced. The `autoResume` setting turns this off; see [Configuration](configuration.md#autoresume).
43
43
 
@@ -45,12 +45,22 @@ Starting Pi in a folder where another session's subagent runs were cut off by it
45
45
 
46
46
  The completion notice of a workflow stopped by a Pi exit or a runtime replacement has one line right after `Workflow run: <id>` that says what happens next: `Auto-resumed as <new id>.`, `Resumed as <new id>.` (resumed by id), `Relaunched as <new id>.` (relaunched with the same script or `options.reuseFrom`), `Not auto-resumed: <reason>.` followed by the way to continue by hand, or, when nothing continues it, `Resume by hand: subagent({ action: "resume", id: "<id>" })` (or the `options.reuseFrom` form when its launch cannot be resumed by id).
47
47
 
48
- After `/new`, `/resume`, or a fork in the same Pi process, the new session owns the async runs of the session it replaced, and of the sessions that one replaced. It can list, `bg_wait` on, steer, stop, and resume them, receives their completion notices, and answers their children's pending supervisor requests. Over RPC, a host can steer, interrupt, stop, resume, and inspect them, and sees them in the fleet and `subagent-async` snapshots. Startup and other Pi processes inherit nothing; `/reload` adds nothing new but keeps what the session already inherited. To relaunch a stopped workflow instead of controlling its children one by one, use `options.reuseFrom`.
48
+ After `/new`, `/resume`, or a fork in the same Pi process, the new session owns the async runs of the session it replaced, and of the sessions that one replaced. It can list, `bg_wait` on, steer, stop, and resume them, receives their completion notices, and answers their children's pending supervisor requests. Over RPC, a host can steer, interrupt, stop, resume, and inspect them, and sees them in the fleet and `subagent-async` snapshots. Startup and other Pi processes inherit nothing; `/reload` adds nothing new but keeps what the session already inherited. A replaced session that starts again (pi-web reopening it) takes its runs back. To relaunch a stopped workflow instead of controlling its children one by one, use `options.reuseFrom`.
49
49
 
50
50
  Once the Pi process that started a background single, parallel, or chain run has exited, the run is reported once to a Pi window that has its session open, whether it finished while Pi was closed or finishes later. A workflow's children are reported through their workflow.
51
51
 
52
52
  Pi core may print a generic `pi -ne` extension-load hint; that out-of-repo hint is not protocol-approved fallback. A verified compaction abort may continue the retained child once on its already resolved model; it does not authorize an execution-mode or model switch.
53
53
 
54
+ ### Switching sessions with background work
55
+
56
+ When a session with a UI has queued or running async work, live nested children, undelivered results, or supervisor questions, `/new`, `/resume`, `/fork`, and `/clone` first ask **pi-subagents: switch sessions?**:
57
+
58
+ - **Stay here** (default, also Escape): cancel the switch. The work keeps running.
59
+ - **Switch and take the work**: the new session takes the work over, as after any switch without the prompt.
60
+ - **Switch and leave the work here**: the new session inherits nothing from this one. Async single, parallel, and chain runs keep running under this session; reopen it to get their results. Async workflows and detached foreground runs stop on any switch; a stopped workflow resumes automatically only if you reopen this session within 24 hours. A child's question can be answered only until it times out (10 minutes by default).
61
+
62
+ Without outstanding work, or without a UI (`pi -p`, SDK sessions), there is no prompt and the new session takes the work over. Over RPC the prompt is a select dialog that counts as **Stay here** if the host does not answer within one minute. The prompt never enters model history.
63
+
54
64
  ## Prompt shortcuts
55
65
 
56
66
  The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
@@ -85,6 +95,10 @@ Workflow-level child controls default onto each `runs.run`/`runs.all` launch; ex
85
95
 
86
96
  Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
87
97
 
98
+ On Node, each script runs in a new permission-restricted process that can read only its supervisor, worker and Acorn parser; Node denies file writes, other reads, child processes and nested workers. The process inherits no host startup flags, preloads or environment variables (except `SystemRoot` on Windows) and starts in Acorn's directory, because Node lets worker threads read their working directory. A small supervisor keeps IPC responsive, so a busy script is still killed when the parent disconnects. The process ends when the workflow settles.
99
+
100
+ This is a permission layer around the VM, not an OS sandbox: network access stays open on Node 22 and 24, and child launches and `runs.host` commands still run in Pi under their own contracts. Bun has no permission model, so it keeps the in-process worker. If the Node process fails to start, the workflow fails; it never retries in an unrestricted worker.
101
+
88
102
  Omitting a child's `async` preserves awaited final-result semantics, even if the child runs in the background. Explicit child `async: true` intentionally returns after launch: its receipt has `state: "running"`, `ok: false`, an empty `output`, and no completion error or final `outputReference`. `ok` confirms successful child completion, not successful dispatch. It does not confirm that the task's intent was carried out: a child that declines or cannot do the work can still end normally. When later steps depend on the work having happened, give the child an `outputSchema` with an explicit status field (and check `structuredOutput` in the script) or a host-run `gate`, and treat only that verdict as success. Use `runId` and `asyncDir` to inspect the running child; `artifactPaths` may include runtime directories and is not a list of final reports. Reusing the same workflow key returns the same receipt, not a refreshed result.
89
103
 
90
104
  A workflow can finish dispatch while these children remain running. Its summary and child rows identify that distinction, and launch receipts do not generate child-completion notices. Consume the later child result before treating its work or report as complete.
@@ -133,6 +147,20 @@ The host resolves the name and validates bounded plain-JSON `args` before starti
133
147
 
134
148
  `parallel` runs independent children together without writing a script: `args.tasks` is a list of `{ agent, task, cwd?, model? }` items, the children run in one `runs.all` batch, and the result lists each child's output in order. `cwd` and `model` are optional per child and apply to that child only, as they do on a `runs.all` item, so one call can fan out across several repositories or mix models. A failed child fails the workflow. Use a workflow script when steps depend on each other.
135
149
 
150
+ ### Approving workflow children in permission extensions
151
+
152
+ Before a workflow starts a child, pi-subagents makes a nested `subagent_launch` tool call, so permission extensions see it in their `tool_call` handler like any other tool call. This covers reply-block, file and named workflows, and `chain` and `tasks`. The call's input is `{ workflowRunId, key, agent?, task?, cwd?, model?, async?, worktree?, resume?, commands?, output? }`. `cwd` is the absolute directory the child starts in. It is left out for a resumed child, which keeps its earlier directory, and for a child placed on another machine. `commands` lists, in run order, the shell commands the child's `gate`, `acceptance.verify` or agent `acceptance` will run on this machine after the child finishes, each `{ command, cwd?, env? }`. A command's `cwd` is absolute and is left out when the child's is; for a `worktree: true` child it names the source directory, because the worktree does not exist yet. `env` lists only the variables the command sets on top of the parent's environment. `output` is the absolute path of the file the child's `output` writes. The other optional fields appear when the child request sets them. A blocked or failed call stops that child, so its commands never run and its output file is never written; it fails with `Workflow child '<key>' was not started: …` and the block reason. Allowed calls do nothing else. The tool is not declared to the model.
153
+
154
+ Extensions that ask about tools they have no rule for ask once per workflow child until you allow `subagent_launch`. Ones that deny unknown tools without a UI, as in `pi -p`, refuse every workflow child until you allow it.
155
+
156
+ Limits:
157
+ - Children reused from an interrupted run's journal are not offered again; nothing new starts.
158
+ - Starts with no tool call behind them are not offered: schedule ticks, auto-resume on session reopen, `/prompt-workflow` and prompt-template delegation, and RPC or SDK launches. Block `schedule.create`, set `authorityPolicy.scheduleCreate` to `"forbid"`, or set [`autoResume`](configuration.md#autoresume) to `false` to control those.
159
+ - Workflows started inside child agents are not offered: children do not register `subagent_launch`. Neither are workflows in a session whose tool allowlist (`pi --tools …`) leaves it out.
160
+ - Commands are offered at launch, not when they run. An extension's `bash` rules don't apply to them on their own; it has to check `commands`.
161
+ - A resumed child's retained `acceptance.verify` commands are not listed again; only commands the resume request adds are.
162
+ - `runs.host` is only available to built-in workflows (`run-ci` runs only `npm test` or `npm run typecheck`) and is not offered.
163
+
136
164
  ### Opt-in bounded workflows
137
165
 
138
166
  Composite workflows have no default parent deadline. Add bounds only when the workflow contract calls for them:
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "type": "module",
3
3
  "name": "@xzzpig/pi-subagents",
4
- "version": "0.24.2",
4
+ "version": "0.25.0",
5
5
  "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
6
6
  "author": "Nico Bailon",
7
7
  "license": "MIT",
@@ -21,7 +21,7 @@
21
21
  "@js-temporal/polyfill": "0.5.1",
22
22
  "acorn": "8.18.0",
23
23
  "jiti": "2.7.0",
24
- "undici": "8.12.3",
24
+ "undici": "8.12.4",
25
25
  "yaml": "2.8.3"
26
26
  },
27
27
  "bundledDependencies": [
@@ -68,9 +68,11 @@ return reviews.map((review) => review.output);
68
68
  and plain helpers. Nested async functions, arrows, and methods are rejected.
69
69
  - Every `runs.run` / `runs.all` item needs a stable `key`. Add a short
70
70
  verb + behavior `label` unless the user gave one.
71
- - Bind files with `output: "plans/x.md"` (relative paths land in run
72
- artifacts) and return `outputReference` or `artifactPaths`. A filename in
73
- task text does not route output. Never send reports to the repo root.
71
+ - Bind files with `output: "plans/x.md"` and return `outputReference` or
72
+ `artifactPaths`; a filename in task text does not route output. Relative
73
+ paths land in run artifacts. Never send reports to the repo root. When the
74
+ task ends, delete scratch briefs, scripts and reports you wrote anywhere
75
+ else; keep final deliverables.
74
76
  - `runs.lanes([{ key, stages: [...] }])` runs a predeclared plan: first stages
75
77
  together, later stages in order per lane.
76
78
 
@@ -102,7 +104,13 @@ number.
102
104
  `.pi/subagents/` does not). For Pi extension repos, put lane worktrees
103
105
  outside `~/.pi/agent/extensions`, for example `~/.pi/agent/worktrees`.
104
106
  - Reviewers use fresh context. Use `context: "fork"` only when the child needs
105
- the parent's history; it requires a persisted parent session.
107
+ the parent's history; it requires a persisted parent session. Each fork
108
+ copies the parent's session file to
109
+ `<parent session file without .jsonl>/forks/<run id>/`:
110
+ before forking from a session file of hundreds of MB, run `df -h` on that
111
+ file's folder. Once a forked child is accepted or dropped and won't be
112
+ resumed, delete its `forks/<run id>/` folder; never one whose run is still
113
+ active.
106
114
  - Children do not spawn subagents unless the parent delegated fanout and their
107
115
  resolved `tools` include `subagent`.
108
116
  - A failed workflow, launch, prompt runtime, extension load, or child tool
@@ -110,10 +118,11 @@ number.
110
118
  verify a clean worktree or capture the partial diff, then retry the same way
111
119
  once. Switching to `interactive_shell`, `pi -ne`, or another CLI needs owner
112
120
  approval.
113
- - As a conservative orchestration policy, do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
121
+ - Do not pass a hard `toolBudget` or tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools. If interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
114
122
  - Route workers and scouts to a fast capable tier, serious reviews to a strong
115
123
  tier, and top reasoning only to bounded read-only critique. Exact model names
116
- belong in user or project settings, not here.
124
+ belong in user or project settings, not here. When neither the user nor
125
+ settings name a model, omit `model` so the child inherits the parent's.
117
126
  - `subagent`, `subagents_enable`, `subagent_supervisor`, `contact_supervisor`, and `structured_output` are model-only: call them as ordinary model tool calls. Codemode scripts cannot reach them through `tools.*`, `ALL_TOOLS`, or `searchTools`.
118
127
  - Receipts, CI, and review bots are evidence, not authority. Backlog, release,
119
128
  and merge policy belong to the user's or project's own skill.
@@ -100,3 +100,4 @@ top-reasoning model is only a bounded read-only critic after ordinary evidence
100
100
  falls short, never an autonomous root. Map tiers to real models in user or
101
101
  project settings or a profile (guide `models/setting-defaults-and-overrides`,
102
102
  `models/profiles-and-provider-model-catalogs`). Explicit user policy wins.
103
+ Never pick a model from memory.
@@ -20,6 +20,7 @@ interface ManagementParams {
20
20
  agentScope?: unknown;
21
21
  capabilities?: unknown;
22
22
  config?: unknown;
23
+ search?: unknown;
23
24
  }
24
25
  export declare function sanitizeName(name: string): string;
25
26
  export declare function availableAgentNamesForCwd(cwd: string): string[];
@@ -1,13 +1,13 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
- import { defaultInheritProjectContext, defaultInheritSkills, defaultSystemPromptMode, discoverAgentsAll, buildRuntimeName, findBlockingAgentDiagnostic, frontmatterNameForConfig, parsePackageName, mergeBuiltinAgentOverride, removeBuiltinAgentOverride, removeBuiltinAgentOverrideFields, resolveAgentName, } from "./agents.js";
3
+ import { defaultInheritProjectContext, defaultInheritSkills, defaultSystemPromptMode, discoverAgentsAll, buildRuntimeName, findBlockingAgentDiagnostic, frontmatterNameForConfig, MAX_LISTED_AGENTS, parsePackageName, mergeBuiltinAgentOverride, removeBuiltinAgentOverride, removeBuiltinAgentOverrideFields, resolveAgentName, } from "./agents.js";
4
4
  import { serializeAgent } from "./agent-serializer.js";
5
5
  import { mergeAgentsForScope } from "./agent-selection.js";
6
6
  import { discoverAvailableSkills, resolveSkills } from "./skills.js";
7
7
  import { buildProactiveSkillSubagentRecommendationLines, } from "./proactive-skills.js";
8
8
  import { parseFrontmatter, parseUnquotedList } from "./frontmatter.js";
9
9
  import { resolveEffectiveThinking, THINKING_LEVELS, toModelInfo } from "../shared/model-info.js";
10
- import { resolveSubagentModelOverride } from "../runs/shared/model-resolution.js";
10
+ import { isUnavailableSubagentModel, knownModelProviders, resolveSubagentModelOverride } from "../runs/shared/model-resolution.js";
11
11
  import { validateToolBudgetConfig } from "../runs/shared/tool-budget.js";
12
12
  import { formatReviewGateLabel, validateAcceptanceInput } from "../runs/shared/acceptance.js";
13
13
  import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, resolveExternalCliRunnerStatus, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.js";
@@ -213,6 +213,8 @@ export function editableAgentConfig(agent) {
213
213
  delete next.model;
214
214
  if (!hasDeclaredField("thinking"))
215
215
  delete next.thinking;
216
+ if (!hasDeclaredField("inheritGlobalContext"))
217
+ next.inheritGlobalContext = false;
216
218
  return next;
217
219
  };
218
220
  const { override: _override, description: _description, output: _output, outputMode: _outputMode, defaultReads: _defaultReads, model: _model, fast: _fast, thinking: _thinking, systemPromptMode: _systemPromptMode, inheritProjectContext: _inheritProjectContext, inheritGlobalContext: _inheritGlobalContext, inheritSkills: _inheritSkills, defaultContext: _defaultContext, acceptanceRole: _acceptanceRole, disabled: _disabled, systemPrompt: _systemPrompt, skills: _skills, skillPath: _skillPath, tools: _tools, excludeTools: _excludeTools, mcpDirectTools: _mcpDirectTools, allowNestedSubagents: _allowNestedSubagents, allowedAgents: _allowedAgents, subagentOnlyExtensions: _subagentOnlyExtensions, mutationTools: _mutationTools, toolBudget: _toolBudget, ...editable } = withoutExtensions;
@@ -233,7 +235,7 @@ export function editableAgentConfig(agent) {
233
235
  ...(base.thinking !== undefined && hasDeclaredField("thinking") ? { thinking: base.thinking } : {}),
234
236
  systemPromptMode: base.systemPromptMode,
235
237
  inheritProjectContext: base.inheritProjectContext,
236
- inheritGlobalContext: base.inheritGlobalContext,
238
+ inheritGlobalContext: hasDeclaredField("inheritGlobalContext") && base.inheritGlobalContext,
237
239
  inheritSkills: base.inheritSkills,
238
240
  ...(base.defaultContext !== undefined ? { defaultContext: base.defaultContext } : {}),
239
241
  ...(base.acceptanceRole !== undefined ? { acceptanceRole: base.acceptanceRole } : {}),
@@ -809,7 +811,8 @@ function agentListMetadata(agent, providerNames, externalCliAvailability) {
809
811
  function formatAgentListLine(agent, providerNames) {
810
812
  return `- ${agent.name} (${agentListMetadata(agent, providerNames)}): ${agent.description}`;
811
813
  }
812
- function formatAgentCapabilitiesLine(agent, providerNames, externalCliAvailability) {
814
+ const UNAVAILABLE_MODEL_MARKER = "(unavailable in the active model registry)";
815
+ function formatAgentCapabilitiesLine(agent, providerNames, externalCliAvailability, unavailableModels) {
813
816
  const declaredTools = [
814
817
  ...(agent.tools ?? []),
815
818
  ...(agent.mcpDirectTools ?? []).map((tool) => `mcp:${tool}`),
@@ -828,6 +831,8 @@ function formatAgentCapabilitiesLine(agent, providerNames, externalCliAvailabili
828
831
  model = agent.model;
829
832
  if (agent.modelProvider && !agent.model.includes("/"))
830
833
  model = `${agent.modelProvider}/${agent.model}`;
834
+ if (unavailableModels.has(agent))
835
+ model = `${model} ${UNAVAILABLE_MODEL_MARKER}`;
831
836
  }
832
837
  const thinking = agent.thinking === false ? "off" : agent.thinking ?? "default";
833
838
  const machine = agent.machine ? `; Machine: ${agent.machine} (saved Herdr placement)` : "";
@@ -908,7 +913,7 @@ function agentCapabilityRow(agent, options) {
908
913
  aliases: agent.aliases ? [...agent.aliases] : undefined,
909
914
  runner: agentCapabilityRunner(agent, options.providerNames, options.externalCliAvailability),
910
915
  tools: agentCapabilityTools(agent),
911
- model: presentDetails({ value: agent.model, thinking: agent.thinking }),
916
+ model: presentDetails({ value: agent.model, thinking: agent.thinking, unavailable: options.unavailableModels.has(agent) || undefined }),
912
917
  execution: presentDetails({ defaultAsync: agent.defaultAsync, timeoutMs: agent.defaultTimeoutMs }),
913
918
  acceptance: presentDetails({ policy: agent.defaultAcceptance, role: agent.acceptanceRole }),
914
919
  output: presentDetails({ path: agent.output, mode: agent.outputMode }),
@@ -918,8 +923,8 @@ function agentCapabilityRow(agent, options) {
918
923
  function agentCapabilitiesSnapshot(input) {
919
924
  return {
920
925
  agents: [
921
- ...input.agents.map((agent) => agentCapabilityRow(agent, { executable: true, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability })),
922
- ...input.restrictedAgents.map((agent) => agentCapabilityRow(agent, { executable: false, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability, restrictionSources: input.restrictedSources })),
926
+ ...input.agents.map((agent) => agentCapabilityRow(agent, { executable: true, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability, unavailableModels: input.unavailableModels })),
927
+ ...input.restrictedAgents.map((agent) => agentCapabilityRow(agent, { executable: false, providerNames: input.providerNames, externalCliAvailability: input.externalCliAvailability, unavailableModels: input.unavailableModels, restrictionSources: input.restrictedSources })),
923
928
  ],
924
929
  restrictedCount: input.restrictedAgents.length,
925
930
  ...(input.restrictedSources?.length ? { capabilityCeilingSources: [...input.restrictedSources] } : {}),
@@ -952,6 +957,7 @@ function agentCapabilityDetails(input) {
952
957
  restrictedAgents: input.restrictedAgents,
953
958
  providerNames: input.providerNames,
954
959
  externalCliAvailability: input.externalCliAvailability,
960
+ unavailableModels: input.unavailableModels,
955
961
  restrictedSources: input.restrictedSources,
956
962
  })),
957
963
  };
@@ -1072,7 +1078,9 @@ export function handleList(params, ctx) {
1072
1078
  scopedAgents = scopedAgents
1073
1079
  .sort((a, b) => a.name.localeCompare(b.name));
1074
1080
  const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.piSessionId);
1075
- const visibleAgents = scopedAgents.filter((a) => !a.disabled);
1081
+ const search = typeof params.search === "string" ? params.search.trim().toLowerCase() : "";
1082
+ const visibleAgents = scopedAgents.filter((a) => !a.disabled
1083
+ && (!search || [a.name, a.description, ...(a.aliases ?? [])].some((text) => text.toLowerCase().includes(search))));
1076
1084
  const agents = visibleAgents.filter((a) => isAgentAllowedByCapabilityCeiling(a.name, capabilityCeiling));
1077
1085
  const restrictedAgents = visibleAgents.filter((a) => !isAgentAllowedByCapabilityCeiling(a.name, capabilityCeiling));
1078
1086
  const restrictedSources = capabilityCeilingAgentRestrictionSources(capabilityCeiling);
@@ -1085,14 +1093,24 @@ export function handleList(params, ctx) {
1085
1093
  const providerNameSet = providerNames(providerStatus);
1086
1094
  const capabilityMode = params.capabilities === true;
1087
1095
  const externalCliAvailability = capabilityMode ? externalCliAvailabilityForAgents([...agents, ...restrictedAgents]) : undefined;
1096
+ const availableModels = capabilityMode ? ctx.modelRegistry.getAvailable().map(toModelInfo) : [];
1097
+ const knownProviders = knownModelProviders(ctx.modelRegistry);
1098
+ const unavailableModels = new Set([...agents, ...restrictedAgents].filter((agent) => (agent.runner?.type ?? "pi") === "pi"
1099
+ && isUnavailableSubagentModel(agent.model, availableModels, agent.modelProvider ?? ctx.model?.provider, knownProviders)));
1088
1100
  const formatLine = capabilityMode
1089
- ? (agent, names) => formatAgentCapabilitiesLine(agent, names, externalCliAvailability)
1101
+ ? (agent, names) => formatAgentCapabilitiesLine(agent, names, externalCliAvailability, unavailableModels)
1090
1102
  : formatAgentListLine;
1103
+ // A large catalog would otherwise put every agent's description into the model's context at once.
1104
+ const shownAgents = agents.slice(0, MAX_LISTED_AGENTS);
1105
+ const shownRestrictedAgents = restrictedAgents.slice(0, MAX_LISTED_AGENTS - shownAgents.length);
1106
+ const omittedCount = Math.max(0, agents.length + restrictedAgents.length - MAX_LISTED_AGENTS);
1091
1107
  const lines = [
1092
1108
  capabilityMode ? "Executable agents (capabilities):" : "Executable agents:",
1093
- ...formatAgentListSections(agents, providerNameSet, formatLine),
1109
+ ...formatAgentListSections(shownAgents, providerNameSet, formatLine),
1094
1110
  ];
1095
- appendRestrictedAgentLines({ lines, agents: restrictedAgents, sources: restrictedSources, providerNames: providerNameSet, formatLine });
1111
+ appendRestrictedAgentLines({ lines, agents: shownRestrictedAgents, sources: restrictedSources, providerNames: providerNameSet, formatLine });
1112
+ if (omittedCount > 0)
1113
+ lines.push("", `+${omittedCount} more; narrow with {action:"list", options:{search:"<term>"}}`);
1096
1114
  appendExternalJobRegistryLine(lines, [...agents, ...restrictedAgents], providerStatus);
1097
1115
  appendAgentDiagnosticLines(lines, d.agentDiagnostics);
1098
1116
  if (proactiveSuggestions.length)
@@ -1103,12 +1121,19 @@ export function handleList(params, ctx) {
1103
1121
  restrictedAgents,
1104
1122
  providerNames: providerNameSet,
1105
1123
  externalCliAvailability: externalCliAvailability ?? new Map(),
1124
+ unavailableModels,
1106
1125
  restrictedSources,
1107
1126
  }));
1108
1127
  }
1128
+ // User then project overrides are layered, so the override's top-level scope can name a file that did not set `model`.
1129
+ function modelOverrideFile(override) {
1130
+ const scopes = override.fieldScopes?.model;
1131
+ const scope = scopes?.includes("project") ? "project" : scopes?.includes("user") ? "user" : override.scope;
1132
+ return { scope, path: override.paths?.[scope] ?? override.path };
1133
+ }
1109
1134
  function formatModelSource(agent, currentModel) {
1110
1135
  if (agent.override && agent.model !== agent.override.base.model) {
1111
- return `${agent.override.scope} override`;
1136
+ return `${modelOverrideFile(agent.override).scope} override`;
1112
1137
  }
1113
1138
  if (agent.modelSource?.type === "subagents.defaultModel" && agent.model === agent.modelSource.model) {
1114
1139
  return `${agent.modelSource.scope} defaultModel`;
@@ -1128,6 +1153,7 @@ function handleModels(params, ctx) {
1128
1153
  const effectiveAgents = effectiveAgentsForScope(scope, discovered, ctx.runtimeAgentOwner, ctx.model?.provider)
1129
1154
  .sort((a, b) => a.name.localeCompare(b.name));
1130
1155
  const availableModels = ctx.modelRegistry.getAvailable().map(toModelInfo);
1156
+ const knownProviders = knownModelProviders(ctx.modelRegistry);
1131
1157
  const currentModel = ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined;
1132
1158
  const preferredProvider = ctx.model?.provider;
1133
1159
  const capabilityCeiling = resolveCurrentSubagentCapabilityCeiling(ctx.piSessionId);
@@ -1161,19 +1187,21 @@ function handleModels(params, ctx) {
1161
1187
  ? [{ agent, name: requestedAgent }]
1162
1188
  : [{ agent, name: agent.name }, ...(agent.aliases ?? []).map((name) => ({ agent, name }))]);
1163
1189
  for (const { agent, name } of modelEntries) {
1164
- const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, agent.modelProvider ?? preferredProvider);
1190
+ const resolvedModel = resolveSubagentModelOverride(agent.model, currentModel, availableModels, agent.modelProvider ?? preferredProvider, { knownProviders });
1191
+ const shownModel = resolvedModel === undefined ? "(unresolved)"
1192
+ : (agent.runner?.type ?? "pi") === "pi" && isUnavailableSubagentModel(agent.model, availableModels, agent.modelProvider ?? preferredProvider, knownProviders) ? `${resolvedModel} ${UNAVAILABLE_MODEL_MARKER}` : resolvedModel;
1165
1193
  const effectiveThinking = resolveEffectiveThinking(resolvedModel, agent.thinking)
1166
1194
  ?? (agent.thinking === false ? "off" : undefined);
1167
1195
  const source = `${formatModelSource(agent, currentModel)}${agent.disabled ? "; disabled" : ""}${isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling) ? "" : "; restricted"}`;
1168
1196
  if (requestedAgent) {
1169
1197
  lines.push(`Agent: ${requestedAgent}`);
1170
1198
  lines.push("Effective model:");
1171
- lines.push(` ${resolvedModel ?? "(unresolved)"}`);
1199
+ lines.push(` ${shownModel}`);
1172
1200
  lines.push(`Source: ${source}`);
1173
1201
  lines.push(`Thinking: ${effectiveThinking ?? "default"}`);
1174
1202
  if (agent.override) {
1175
1203
  lines.push("Override file:");
1176
- lines.push(` ${agent.override.path}`);
1204
+ lines.push(` ${modelOverrideFile(agent.override).path}`);
1177
1205
  }
1178
1206
  if (agent.model && resolvedModel && agent.model !== resolvedModel) {
1179
1207
  lines.push("Requested model setting:");
@@ -1189,12 +1217,12 @@ function handleModels(params, ctx) {
1189
1217
  }
1190
1218
  lines.push(name);
1191
1219
  lines.push(" model:");
1192
- lines.push(` ${resolvedModel ?? "(unresolved)"}`);
1220
+ lines.push(` ${shownModel}`);
1193
1221
  lines.push(` source: ${source}`);
1194
1222
  lines.push(` thinking: ${effectiveThinking ?? "default"}`);
1195
1223
  if (agent.override) {
1196
1224
  lines.push(" override file:");
1197
- lines.push(` ${agent.override.path}`);
1225
+ lines.push(` ${modelOverrideFile(agent.override).path}`);
1198
1226
  }
1199
1227
  if (agent.model && resolvedModel && agent.model !== resolvedModel) {
1200
1228
  lines.push(" requested model setting:");
@@ -1302,7 +1330,7 @@ export function handleCreate(params, ctx) {
1302
1330
  const sw = skillsWarning(ctx.cwd, agent);
1303
1331
  if (sw)
1304
1332
  warnings.push(sw);
1305
- fs.writeFileSync(targetPath, serializeAgent(agent), "utf-8");
1333
+ fs.writeFileSync(targetPath, serializeAgent(agent, { explicitInheritGlobalContext: hasKey(cfg, "inheritGlobalContext") }), "utf-8");
1306
1334
  ctx.onAgentsChanged?.();
1307
1335
  return result([`Created agent '${runtimeName}' at ${targetPath}.`, ...warnings].join("\n"));
1308
1336
  }
@@ -15,13 +15,10 @@ import { type AgentConfig, type AgentMemoryConfig } from "./agents.ts";
15
15
  export declare const AGENT_MEMORY_DIR_NAME = "agent-memory";
16
16
  export declare const AGENT_MEMORY_FILE = "MEMORY.md";
17
17
  export declare const MAX_MEMORY_LINES = 200;
18
- /** Parse a `memory` frontmatter block string into a typed config, or undefined if invalid. */
19
18
  export declare function parseMemoryFrontmatter(raw: string | undefined): AgentMemoryConfig | undefined;
20
- /** Whether an agent can write files this run (inherits default builtins when `tools` is unset). */
19
+ /** Inherits default builtins when `tools` is unset. */
21
20
  export declare function agentHasWriteTools(agent: Pick<AgentConfig, "tools">): boolean;
22
21
  /**
23
- * Resolve a memory directory under `rootDir` for the given scoped path.
24
- *
25
22
  * Rejects empty paths, `.`/`..` segments, paths that escape the root, and
26
23
  * existing directories whose real path (via symlink) lands outside the root.
27
24
  */
@@ -29,7 +29,6 @@ function unquoteFrontmatterValue(value) {
29
29
  }
30
30
  return trimmed;
31
31
  }
32
- /** Parse a `memory` frontmatter block string into a typed config, or undefined if invalid. */
33
32
  export function parseMemoryFrontmatter(raw) {
34
33
  if (!raw)
35
34
  return undefined;
@@ -60,7 +59,7 @@ export function parseMemoryFrontmatter(raw) {
60
59
  return undefined;
61
60
  return { scope, path: scopedPath };
62
61
  }
63
- /** Whether an agent can write files this run (inherits default builtins when `tools` is unset). */
62
+ /** Inherits default builtins when `tools` is unset. */
64
63
  export function agentHasWriteTools(agent) {
65
64
  const tools = agent.tools;
66
65
  if (!tools)
@@ -168,8 +167,6 @@ function resolveProjectMemoryRoot(projectRoot) {
168
167
  }
169
168
  }
170
169
  /**
171
- * Resolve a memory directory under `rootDir` for the given scoped path.
172
- *
173
170
  * Rejects empty paths, `.`/`..` segments, paths that escape the root, and
174
171
  * existing directories whose real path (via symlink) lands outside the root.
175
172
  */
@@ -2,6 +2,8 @@ import type { AgentConfig } from "./agents.ts";
2
2
  export declare const KNOWN_FIELDS: Set<string>;
3
3
  interface SerializeAgentOptions {
4
4
  preserveFrontmatterFields?: ReadonlySet<string>;
5
+ /** The caller set inheritGlobalContext on create; write it even when false, because an absent field takes settings defaults. */
6
+ explicitInheritGlobalContext?: boolean;
5
7
  }
6
8
  export declare function serializeAgent(config: AgentConfig, options?: SerializeAgentOptions): string;
7
9
  export {};
@@ -100,7 +100,7 @@ export function serializeAgent(config, options = {}) {
100
100
  lines.push(`systemPromptMode: ${config.systemPromptMode}`);
101
101
  if (!preservingExistingFrontmatter || preserve("inheritProjectContext"))
102
102
  lines.push(`inheritProjectContext: ${config.inheritProjectContext ? "true" : "false"}`);
103
- if (config.inheritGlobalContext || preserve("inheritGlobalContext"))
103
+ if (config.inheritGlobalContext || preserve("inheritGlobalContext") || options.explicitInheritGlobalContext)
104
104
  lines.push(`inheritGlobalContext: ${config.inheritGlobalContext ? "true" : "false"}`);
105
105
  if (!preservingExistingFrontmatter || preserve("inheritSkills"))
106
106
  lines.push(`inheritSkills: ${config.inheritSkills ? "true" : "false"}`);
@@ -1,6 +1,3 @@
1
- /**
2
- * Agent discovery and configuration
3
- */
4
1
  import * as fs from "node:fs";
5
2
  import { type AcceptanceInput, type AcceptanceRole, type AgentRunnerConfig, type JsonSchemaObject, type OutputMode, type ToolBudgetConfig } from "../shared/types.ts";
6
3
  import { type ModelScopeConfig } from "../runs/shared/model-scope.ts";
@@ -89,6 +86,7 @@ interface BuiltinAgentOverrideInfo {
89
86
  base: BuiltinAgentOverrideBase;
90
87
  fields?: string[];
91
88
  fieldScopes?: Record<string, Array<"user" | "project">>;
89
+ paths?: Partial<Record<"user" | "project", string>>;
92
90
  }
93
91
  export interface AgentModelSourceInfo {
94
92
  type: "subagents.defaultModel";
@@ -245,6 +243,7 @@ export interface AgentDiscoveryResult {
245
243
  }
246
244
  /** Create formatter input from the exact discovery operation used for resolution. */
247
245
  export declare function unknownAgentDiagnosticContext(discovered: Pick<AgentDiscoveryResult, "cwd" | "scope" | "directories" | "agents" | "disabledAgents">): UnknownAgentDiagnosticContext;
246
+ export declare const MAX_LISTED_AGENTS = 30;
248
247
  /** One line per agent the caller can launch instead, so a wrong name needs no separate list call. */
249
248
  export declare function formatAvailableAgentLines(agents: readonly AgentConfig[]): string[];
250
249
  /** The closest agent name or alias when `name` looks like a typo of one. */
@@ -1,6 +1,3 @@
1
- /**
2
- * Agent discovery and configuration
3
- */
4
1
  import { execSync } from "node:child_process";
5
2
  import * as fs from "node:fs";
6
3
  import { parse as parseYaml } from "yaml";
@@ -89,7 +86,7 @@ export function unknownAgentDiagnosticContext(discovered) {
89
86
  ...(discovered.disabledAgents?.length ? { disabledAgents: discovered.disabledAgents } : {}),
90
87
  };
91
88
  }
92
- const MAX_LISTED_AGENTS = 30;
89
+ export const MAX_LISTED_AGENTS = 30;
93
90
  const MAX_LISTED_DESCRIPTION_CHARS = 80;
94
91
  /** One line per agent the caller can launch instead, so a wrong name needs no separate list call. */
95
92
  export function formatAvailableAgentLines(agents) {
@@ -100,7 +97,7 @@ export function formatAvailableAgentLines(agents) {
100
97
  return `- ${agent.name} (${agent.source})${short ? ` — ${short}` : ""}`;
101
98
  });
102
99
  if (sorted.length > MAX_LISTED_AGENTS)
103
- lines.push(`+${sorted.length - MAX_LISTED_AGENTS} more; {action:"list"}`);
100
+ lines.push(`+${sorted.length - MAX_LISTED_AGENTS} more; {action:"list", options:{search:"<term>"}}`);
104
101
  return lines.length ? lines : ["- (none)"];
105
102
  }
106
103
  /** The closest agent name or alias when `name` looks like a typo of one. */
@@ -972,21 +969,24 @@ function readSubagentSettings(filePath) {
972
969
  const subagentsObject = subagents;
973
970
  let disableBuiltins;
974
971
  if ("disableBuiltins" in subagentsObject) {
975
- if (typeof subagentsObject.disableBuiltins === "boolean") {
972
+ if (typeof subagentsObject.disableBuiltins === "boolean")
976
973
  disableBuiltins = subagentsObject.disableBuiltins;
977
- }
978
- else {
974
+ else
979
975
  throw new Error(`Subagent settings in '${filePath}' have invalid 'disableBuiltins'; expected a boolean.`);
980
- }
981
976
  }
982
977
  let disableThinking;
983
978
  if ("disableThinking" in subagentsObject) {
984
- if (typeof subagentsObject.disableThinking === "boolean") {
979
+ if (typeof subagentsObject.disableThinking === "boolean")
985
980
  disableThinking = subagentsObject.disableThinking;
986
- }
987
- else {
981
+ else
988
982
  throw new Error(`Subagent settings in '${filePath}' have invalid 'disableThinking'; expected a boolean.`);
989
- }
983
+ }
984
+ let defaultInheritGlobalContext;
985
+ if ("defaultInheritGlobalContext" in subagentsObject) {
986
+ if (typeof subagentsObject.defaultInheritGlobalContext === "boolean")
987
+ defaultInheritGlobalContext = subagentsObject.defaultInheritGlobalContext;
988
+ else
989
+ throw new Error(`Subagent settings in '${filePath}' have invalid 'defaultInheritGlobalContext'; expected a boolean.`);
990
990
  }
991
991
  let defaultModel;
992
992
  if ("defaultModel" in subagentsObject) {
@@ -1078,6 +1078,7 @@ function readSubagentSettings(filePath) {
1078
1078
  ...(maxThinking !== undefined ? { maxThinking } : {}),
1079
1079
  ...(defaultExtensions !== undefined ? { defaultExtensions } : {}),
1080
1080
  ...(defaultSubagentOnlyExtensions !== undefined ? { defaultSubagentOnlyExtensions } : {}),
1081
+ ...(defaultInheritGlobalContext !== undefined ? { defaultInheritGlobalContext } : {}),
1081
1082
  ...(agentScanDirs !== undefined ? { agentScanDirs } : {}),
1082
1083
  ...(agentExcludeDirs !== undefined ? { agentExcludeDirs } : {}),
1083
1084
  ...(disableBuiltins !== undefined ? { disableBuiltins } : {}),
@@ -1217,8 +1218,27 @@ function applySubagentDefaultSubagentOnlyExtensions(agents, defaultSubagentOnlyE
1217
1218
  return next;
1218
1219
  });
1219
1220
  }
1220
- function applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions) {
1221
- return applySubagentDefaultSubagentOnlyExtensions(applySubagentDefaultExtensions(applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking), defaultExtensions), defaultSubagentOnlyExtensions);
1221
+ function resolveSubagentDefaultInheritGlobalContext(userSettings, projectSettings, projectSettingsPath) {
1222
+ if (projectSettingsPath && projectSettings.defaultInheritGlobalContext !== undefined)
1223
+ return projectSettings.defaultInheritGlobalContext;
1224
+ return userSettings.defaultInheritGlobalContext;
1225
+ }
1226
+ // The parsed field is a plain boolean, so only the frontmatter key tells an explicit `false` from an unset field.
1227
+ function applySubagentDefaultInheritGlobalContext(agents, defaultInheritGlobalContext) {
1228
+ if (!defaultInheritGlobalContext)
1229
+ return agents;
1230
+ return agents.map((agent) => {
1231
+ const frontmatterFields = agentFrontmatterFields.get(agent);
1232
+ if (agent.inheritGlobalContext || frontmatterFields?.has("inheritGlobalContext"))
1233
+ return agent;
1234
+ const next = { ...agent, inheritGlobalContext: true };
1235
+ if (frontmatterFields)
1236
+ agentFrontmatterFields.set(next, frontmatterFields);
1237
+ return next;
1238
+ });
1239
+ }
1240
+ function applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions, defaultInheritGlobalContext) {
1241
+ return applySubagentDefaultInheritGlobalContext(applySubagentDefaultSubagentOnlyExtensions(applySubagentDefaultExtensions(applySubagentDefaultThinking(applySubagentDefaultModel(agents, defaultModel, defaultProvider), defaultThinking), defaultExtensions), defaultSubagentOnlyExtensions), defaultInheritGlobalContext);
1222
1242
  }
1223
1243
  function applyToolsOverride(target, toolsOverride) {
1224
1244
  if (toolsOverride === "inherit") {
@@ -1242,6 +1262,7 @@ function applyBuiltinOverride(agent, override, meta) {
1242
1262
  base: agent.override?.base ?? cloneOverrideBase(agent),
1243
1263
  fields: [...new Set([...(agent.override?.fields ?? []), ...Object.keys(override)])].sort(),
1244
1264
  fieldScopes: Object.fromEntries(Object.entries({ ...(agent.override?.fieldScopes ?? {}) }).map(([field, scopes]) => [field, [...scopes]])),
1265
+ paths: { ...agent.override?.paths, [meta.scope]: meta.path },
1245
1266
  };
1246
1267
  for (const field of Object.keys(override)) {
1247
1268
  const scopes = overrideInfo.fieldScopes[field] ?? [];
@@ -1393,13 +1414,16 @@ function applyBuiltinOverrides(builtinAgents, userSettings, projectSettings, use
1393
1414
  };
1394
1415
  return builtinAgents.map((agent) => {
1395
1416
  const projectOverride = projectSettings.overrides[agent.name];
1417
+ const userOverride = userSettings.overrides[agent.name];
1396
1418
  if (projectOverride && projectSettingsPath) {
1397
- return applyGlobalThinking(applyBuiltinOverride(agent, projectOverride, { scope: "project", path: projectSettingsPath }), projectOverride.thinking !== undefined);
1419
+ const withUserOverride = userOverride
1420
+ ? applyBuiltinOverride(agent, userOverride, { scope: "user", path: userSettingsPath })
1421
+ : agent;
1422
+ return applyGlobalThinking(applyBuiltinOverride(withUserOverride, projectOverride, { scope: "project", path: projectSettingsPath }), projectOverride.thinking !== undefined || (!projectThinkingConfigured && userOverride?.thinking !== undefined));
1398
1423
  }
1399
1424
  if (projectBulkDisabled && projectSettingsPath) {
1400
1425
  return applyGlobalThinking(applyBuiltinOverride(agent, { disabled: true }, { scope: "project", path: projectSettingsPath }), false);
1401
1426
  }
1402
- const userOverride = userSettings.overrides[agent.name];
1403
1427
  if (userOverride) {
1404
1428
  return applyGlobalThinking(applyBuiltinOverride(agent, userOverride, { scope: "user", path: userSettingsPath }), !projectThinkingConfigured && userOverride.thinking !== undefined);
1405
1429
  }
@@ -2542,7 +2566,7 @@ function getAgentDiscoverySources(cwd, preferredModelProvider, includeChains = f
2542
2566
  const key = discoveryCacheKey(cwd, preferredModelProvider, globalNpmRoot, projectTrusted);
2543
2567
  const cached = agentDiscoveryCache.get(key);
2544
2568
  if (cached && cached.fingerprint === discoveryFingerprint(cached.sources)) {
2545
- if (includeChains) {
2569
+ if (includeChains && !cached.sources.userChains) {
2546
2570
  ensureDiscoveryChains(cached.sources);
2547
2571
  cached.fingerprint = discoveryFingerprint(cached.sources);
2548
2572
  }
@@ -2591,7 +2615,8 @@ function configuredAgentsForScope(sources, scope, settingsScope = scope) {
2591
2615
  const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, sources.projectSettingsPath);
2592
2616
  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, sources.projectSettingsPath);
2593
2617
  const defaultSubagentOnlyExtensions = resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, sources.projectSettingsPath);
2594
- const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions);
2618
+ const defaultInheritGlobalContext = resolveSubagentDefaultInheritGlobalContext(userSettings, projectSettings, sources.projectSettingsPath);
2619
+ const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions, defaultInheritGlobalContext);
2595
2620
  const builtin = applyBuiltinOverrides(applyDefaults(sources.builtinLoaded.agents), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
2596
2621
  const user = applyCustomAgentOverrides(applyDefaults(scope === "project" ? [] : sources.userLoaded.flatMap((loaded) => loaded.loaded.agents)), userSettings, projectSettings, sources.userSettingsPath, sources.projectSettingsPath);
2597
2622
  const projectMap = new Map();
@@ -2757,6 +2782,7 @@ function discoverAgentsUncached(cwd, scope, preferredModelProvider, options = {}
2757
2782
  const maxThinking = resolveSubagentMaxThinking(userSettings, projectSettings, projectSettingsPath);
2758
2783
  const defaultExtensions = resolveSubagentDefaultExtensions(userSettings, projectSettings, projectSettingsPath);
2759
2784
  const defaultSubagentOnlyExtensions = resolveSubagentDefaultSubagentOnlyExtensions(userSettings, projectSettings, projectSettingsPath);
2785
+ const defaultInheritGlobalContext = resolveSubagentDefaultInheritGlobalContext(userSettings, projectSettings, projectSettingsPath);
2760
2786
  const modelScope = projectSettings.modelScope ?? userSettings.modelScope;
2761
2787
  const injectAgents = projectSettings.injectAgents !== undefined
2762
2788
  ? projectSettings.injectAgents
@@ -2765,7 +2791,7 @@ function discoverAgentsUncached(cwd, scope, preferredModelProvider, options = {}
2765
2791
  const isExcluded = agentExclusions(agentExclusionRoots(userSettingsPath, projectSettingsPath));
2766
2792
  const directories = [reportAgentDefinitionDirectory("builtin", BUILTIN_AGENTS_DIR, BUILTIN_AGENT_DEFINITION_INSPECTION)];
2767
2793
  const builtinLoaded = loadAgentsFromDefinitionFiles(BUILTIN_AGENT_DEFINITION_FILES, "builtin");
2768
- const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions);
2794
+ const applyDefaults = (agents) => applySubagentDefaults(agents, defaultModel, defaultProvider, defaultThinking, defaultExtensions, defaultSubagentOnlyExtensions, defaultInheritGlobalContext);
2769
2795
  const builtinAgents = applyBuiltinOverrides(applyDefaults(builtinLoaded.agents), userSettings, projectSettings, userSettingsPath, projectSettingsPath);
2770
2796
  const userScanDirs = settingsAgentScanDirs(userSettings.agentScanDirs ?? [], isExcluded);
2771
2797
  const projectScanDirs = settingsAgentScanDirs(projectSettings.agentScanDirs ?? [], isExcluded);