@xzzpig/pi-subagents 0.20.0 → 0.21.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 (140) hide show
  1. package/CHANGELOG.md +154 -0
  2. package/README.md +1 -1
  3. package/agents/oracle.md +8 -19
  4. package/agents/researcher.md +0 -3
  5. package/agents/reviewer.md +17 -61
  6. package/agents/scout.md +1 -4
  7. package/agents/worker.md +8 -25
  8. package/docs/agents.md +72 -7
  9. package/docs/configuration.md +58 -7
  10. package/docs/extension-api.md +36 -11
  11. package/docs/fork-extensions.md +1 -0
  12. package/docs/missions.md +34 -17
  13. package/docs/models.md +1 -1
  14. package/docs/observability.md +10 -5
  15. package/docs/tool-reference.md +117 -84
  16. package/docs/watchdog.md +8 -6
  17. package/docs/workflows.md +16 -7
  18. package/index.ts +5 -0
  19. package/package.json +5 -3
  20. package/prompts/council.md +1 -1
  21. package/skills/pi-subagents/SKILL.md +1 -1
  22. package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
  23. package/skills/pi-subagents/references/execution-controls.md +16 -16
  24. package/skills/pi-subagents/references/management-authoring-rpc.md +16 -12
  25. package/skills/pi-subagents/references/prompting-and-roles.md +3 -3
  26. package/src/agents/advertised-agent-prompt.ts +9 -1
  27. package/src/agents/agent-management.ts +4 -0
  28. package/src/agents/agent-memory.ts +3 -3
  29. package/src/agents/agent-scope.ts +4 -0
  30. package/src/agents/agent-serializer.ts +8 -1
  31. package/src/agents/agents.ts +191 -145
  32. package/src/api/preflight.ts +8 -4
  33. package/src/extension/config.ts +21 -2
  34. package/src/extension/context-injection.ts +6 -1
  35. package/src/extension/control-notices.ts +1 -9
  36. package/src/extension/declaration-pinning.ts +164 -0
  37. package/src/extension/doctor.ts +7 -10
  38. package/src/extension/fanout-child.ts +7 -8
  39. package/src/extension/index.ts +114 -132
  40. package/src/extension/reply-workflow-script.ts +20 -11
  41. package/src/extension/rpc.ts +11 -6
  42. package/src/extension/schemas.ts +34 -30
  43. package/src/extension/subagent-guide.ts +86 -6
  44. package/src/extension/subagent-options.ts +47 -0
  45. package/src/extension/tool-activation.ts +3 -2
  46. package/src/extension/tool-description.ts +51 -68
  47. package/src/inspectors/actions.ts +37 -11
  48. package/src/inspectors/plugins.ts +3 -2
  49. package/src/inspectors/tmux/actions.ts +204 -0
  50. package/src/inspectors/tmux/client.ts +85 -0
  51. package/src/inspectors/tmux/plugin.ts +21 -0
  52. package/src/integrations/herdr-status.ts +18 -49
  53. package/src/integrations/program-status.ts +215 -0
  54. package/src/intercom/native-supervisor-channel.ts +77 -4
  55. package/src/intercom/result-intercom.ts +3 -2
  56. package/src/intercom/supervisor-ui.ts +2 -174
  57. package/src/missions/store.ts +25 -5
  58. package/src/profiles/profiles.ts +24 -21
  59. package/src/runs/background/active-async-capacity.ts +58 -8
  60. package/src/runs/background/async-execution.ts +143 -38
  61. package/src/runs/background/async-job-tracker.ts +11 -4
  62. package/src/runs/background/async-resume.ts +5 -2
  63. package/src/runs/background/await-async-run.ts +14 -9
  64. package/src/runs/background/binary-bootstrap.ts +2 -1
  65. package/src/runs/background/calendar-schedule.ts +90 -0
  66. package/src/runs/background/chain-root-attachment.ts +9 -5
  67. package/src/runs/background/fleet-view.ts +5 -5
  68. package/src/runs/background/notify.ts +185 -12
  69. package/src/runs/background/result-files.ts +116 -5
  70. package/src/runs/background/result-watcher.ts +99 -66
  71. package/src/runs/background/resume-guidance.ts +2 -2
  72. package/src/runs/background/run-child-session.ts +16 -2
  73. package/src/runs/background/run-id-resolver.ts +8 -5
  74. package/src/runs/background/run-status.ts +21 -16
  75. package/src/runs/background/runner-child-launch.ts +1 -0
  76. package/src/runs/background/runner-http-dispatcher.ts +3 -0
  77. package/src/runs/background/scheduled-runs.ts +256 -61
  78. package/src/runs/background/subagent-runner-bootstrap.ts +4 -1
  79. package/src/runs/background/subagent-runner.ts +32 -12
  80. package/src/runs/background/subagent-wait.ts +38 -19
  81. package/src/runs/background/terminal-run-index.ts +46 -1
  82. package/src/runs/background/wait-completions.ts +1 -0
  83. package/src/runs/background/wait-tool.ts +33 -23
  84. package/src/runs/background/workflow-terminal-proof.ts +39 -22
  85. package/src/runs/foreground/async-stop-action.ts +48 -22
  86. package/src/runs/foreground/execution.ts +94 -52
  87. package/src/runs/foreground/foreground-history.ts +1 -0
  88. package/src/runs/foreground/subagent-executor.ts +207 -77
  89. package/src/runs/shared/child-commands.ts +2 -1
  90. package/src/runs/shared/child-hooks.ts +4 -3
  91. package/src/runs/shared/child-launch.ts +3 -0
  92. package/src/runs/shared/child-session.ts +41 -24
  93. package/src/runs/shared/child-tool-plan.ts +13 -26
  94. package/src/runs/shared/dynamic-fanout.ts +1 -1
  95. package/src/runs/shared/fork-command-result.ts +10 -0
  96. package/src/runs/shared/herdr-placed-run.ts +5 -4
  97. package/src/runs/shared/mcp-direct-tool-allowlist.ts +5 -3
  98. package/src/runs/shared/model-resolution-diagnostic.ts +25 -0
  99. package/src/runs/shared/model-resolution.ts +30 -1
  100. package/src/runs/shared/nested-events.ts +5 -0
  101. package/src/runs/shared/parallel-handoff.ts +56 -8
  102. package/src/runs/shared/parallel-utils.ts +2 -0
  103. package/src/runs/shared/partial-output.ts +48 -0
  104. package/src/runs/shared/runner-launcher.ts +25 -0
  105. package/src/runs/shared/single-output.ts +53 -0
  106. package/src/runs/shared/structured-output.ts +14 -7
  107. package/src/runs/shared/subagent-control.ts +3 -3
  108. package/src/runs/shared/subagent-prompt-runtime.ts +47 -24
  109. package/src/runs/shared/workflow-async-child-guidance.ts +1 -1
  110. package/src/runs/shared/worktree-cleanup-apply.ts +160 -0
  111. package/src/runs/shared/worktree-cleanup-plan.ts +41 -19
  112. package/src/runs/shared/worktree-lock.ts +29 -0
  113. package/src/runs/shared/worktree.ts +12 -1
  114. package/src/shared/atomic-json.ts +4 -2
  115. package/src/shared/edit-distance.ts +33 -0
  116. package/src/shared/file-lease.ts +74 -0
  117. package/src/shared/formatters.ts +1 -5
  118. package/src/shared/model-info.ts +22 -0
  119. package/src/shared/package-version.ts +17 -0
  120. package/src/shared/parent-wake.ts +79 -0
  121. package/src/shared/pruned-fork.ts +7 -1
  122. package/src/shared/runtime-module-path.ts +19 -0
  123. package/src/shared/settings-file-lease.ts +36 -0
  124. package/src/shared/types.ts +36 -2
  125. package/src/shared/utils.ts +8 -6
  126. package/src/slash/slash-commands.ts +3 -3
  127. package/src/slash/subagents-admin.ts +2 -1
  128. package/src/tui/fleet-native-transcript.ts +2 -0
  129. package/src/tui/fleet-transcript.ts +12 -3
  130. package/src/tui/fleet.ts +11 -8
  131. package/src/tui/render.ts +27 -19
  132. package/src/tui/subagent-messages.ts +305 -0
  133. package/src/watchdog/diff-tool.ts +2 -2
  134. package/src/watchdog/register-main.ts +2 -22
  135. package/src/watchdog/render.ts +2 -24
  136. package/src/watchdog/runtime.ts +6 -4
  137. package/src/watchdog/settings.ts +18 -13
  138. package/src/watchdog/tool-actions.ts +2 -2
  139. package/src/workflows/scripted-workflow.ts +20 -6
  140. package/src/workflows/workflow-resources.ts +11 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xzzpig/pi-subagents",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
5
5
  "author": "Nico Bailon",
6
6
  "license": "MIT",
@@ -36,6 +36,7 @@
36
36
  "pi-package",
37
37
  "pi",
38
38
  "pi-coding-agent",
39
+ "extension",
39
40
  "subagents",
40
41
  "ai",
41
42
  "agents",
@@ -92,6 +93,7 @@
92
93
  },
93
94
  "dependencies": {
94
95
  "@xzzpig/pi-components": "0.4.0",
96
+ "@js-temporal/polyfill": "0.5.1",
95
97
  "acorn": "8.18.0",
96
98
  "jiti": "2.7.0",
97
99
  "undici": "8.10.2",
@@ -119,8 +121,8 @@
119
121
  "pack:pkg": "npm run build:pkg && npm pack ./dist-pkg",
120
122
  "typecheck": "tsc --noEmit",
121
123
  "test": "npm run test:unit",
122
- "test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
123
- "test:integration": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
124
+ "test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --import ./test/support/fork-test-environment.mjs --test test/unit/*.test.ts",
125
+ "test:integration": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/register-loader.mjs --import ./test/support/fork-test-environment.mjs --test test/integration/*.test.ts",
124
126
  "test:smoke:tool-activation": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --test test/smoke/tool-activation.test.ts",
125
127
  "test:all": "npm run test:unit && npm run test:integration"
126
128
  }
@@ -9,7 +9,7 @@ decide which feedback is valid, and write the final memo. Advisors do not talk
9
9
  directly or see peer transcripts by default. This is not free-form agent chat.
10
10
 
11
11
  Before you orchestrate, load the council protocol with
12
- `subagent({ action: "guide", topic: "council" })`. If only `subagents_enable`
12
+ `subagent({ action: "guide", options: { topic: "council" } })`. If only `subagents_enable`
13
13
  is available, call it first; `subagent` is available on the next request. The
14
14
  guide returns the packaged council-mode skill and the references it asks you to
15
15
  read, so it also works when Pi runs with `--no-skills`.
@@ -87,7 +87,7 @@ that runner explicitly supports the option.
87
87
 
88
88
  ## Read the reference for the branch
89
89
 
90
- For exact API fields and worked examples, call `subagent({action:"guide",topic:"tool-reference"})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
90
+ For exact API fields and worked examples, call `subagent({action:"guide",options:{topic:"tool-reference"}})` or `topic:"workflows"`. The compact tool definition is not the recipe catalog; use `topic:"missions"` for mission updates and schedules.
91
91
 
92
92
  | Branch | Read |
93
93
  | --- | --- |
@@ -64,7 +64,7 @@ its overhead. Recipes select a shape; they do not authorize delegation:
64
64
 
65
65
  ## Error Handling
66
66
 
67
- - **Unknown agent:** run `subagent({ action: "list" })`; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
67
+ - **Unknown agent:** the error lists the available agents and the directories searched; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
68
68
  - **Setup, discovery, or intercom confusion:** run `subagent({ action: "doctor" })`.
69
69
  - **Max subagent depth exceeded:** flatten the workflow or raise `maxSubagentDepth` in config.
70
70
  - **Missing session file for a fork:** persist the parent session before using `context: "fork"`.
@@ -211,19 +211,19 @@ return runs.run("correctness", { agent: "reviewer", task: "Review the current di
211
211
  ```
212
212
 
213
213
  ```typescript
214
- const run = subagent({ workflow: true, async: true, context: "fresh" })
214
+ const run = subagent({ workflow: true, async: true, options: { context: "fresh" } })
215
215
  // Continue local inspection, then later call status with the returned id.
216
216
  ```
217
217
 
218
218
  While children run, the persistent FleetView and the collapsed foreground tool-result card show live per-child detail: resolved model and thinking level, `[fresh]`/`[fork]` context, tool/token/elapsed counters, and current activity. The collapsed running card also prints the configured expand-key hint ("Press … for live detail"); expanding it shows nested children, recent tools, and recent output. Model badges appear once the child's model resolves at first attempt start. `/subagents-fleet` opens the live fleet inspector, which also has per-child controls (`s` steer, `D` stop with confirmation). When optional Herdr 0.7.5+ is available, `H` opens a raw inspector dashboard for the selected active async child; this mirrors artifacts rather than attaching to the headless child. When optional Orca progress tabs are enabled, Pi creates one passive Orca observer tab for the top-level subagent call. Parallel and chain children share that tab and write child section headers into the mirrored log instead of opening one tab per child. Pi remains authoritative for lifecycle, status, control, artifacts, and results; the Orca tab is display-only. Pi also writes passive display metadata under `.pi/subagents/views/orca/` when possible, so other surfaces can discover the observer without treating it as an owned child run. Use visual panes for confusing or long-running active async work when the human wants a dedicated surface or FleetView is insufficient, not for routine headless runs.
219
219
 
220
- Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", view: "fleet" })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", view: "transcript", index: 0 })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
220
+ Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", options: { view: "fleet" } })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", options: { view: "transcript", index: 0 } })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
221
221
 
222
222
  Stop a current-session top-level async run with `stop` (or `/subagents-stop`). Stopped runs finish as `stopped`/cancelled and are not resumable. For an active foreground single-subagent run, `/subagents-detach [run-id]` leaves the child running without terminating it and returns the eventual result through status/wait.
223
223
 
224
224
  ```typescript
225
225
  subagent({ action: "stop", id: "run-id" })
226
- subagent({ action: "stop", id: "run-id", childId: "child-id" })
226
+ subagent({ action: "stop", id: "run-id", options: { childId: "child-id" } })
227
227
  ```
228
228
 
229
229
  Use `childId` only for active async/workflow runs whose status snapshot shows a
@@ -237,7 +237,7 @@ Use `steer` for top-level live async guidance and `resume` after a delegated run
237
237
  ```typescript
238
238
  subagent({ action: "steer", id: "run-id", message: "Focus on the failing test." })
239
239
  subagent({ action: "resume", id: "run-id", message: "Follow up on this point." })
240
- subagent({ action: "resume", id: "run-id", index: 1, message: "Continue reviewer 2." })
240
+ subagent({ action: "resume", id: "run-id", message: "Continue reviewer 2.", options: { index: 1 } })
241
241
  subagent({ action: "resume", id: "nested-run-id", message: "Continue this nested reviewer." })
242
242
  ```
243
243
 
@@ -275,10 +275,10 @@ Schedules are durable project records under `.pi/subagents/schedules/`. They are
275
275
 
276
276
  ```typescript
277
277
  // One-shot reviewer, after a ```js workflow block with the script
278
- subagent({ action: "schedule.create", id: "evening-review", name: "Evening review", at: "+30m", workflow: true })
278
+ subagent({ action: "schedule.create", id: "evening-review", workflow: true, options: { name: "Evening review", at: "+30m" } })
279
279
 
280
280
  // Fixed recurring workflow from a script file
281
- subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflow: "./.pi/workflows/backlog.js" })
281
+ subagent({ action: "schedule.create", id: "backlog", workflow: "./.pi/workflows/backlog.js", options: { every: "6h", catchUp: "latest" } })
282
282
 
283
283
  subagent({ action: "schedule.list" })
284
284
  subagent({ action: "schedule.show", id: "backlog" })
@@ -345,8 +345,8 @@ Steering supports three delivery modes via the `mode` parameter (`steer` is the
345
345
  - `mode: "auto"` — same next-safe-point delivery path as `steer`, but without the automatic pause-and-revive recovery after a missed acknowledgment.
346
346
 
347
347
  ```typescript
348
- subagent({ action: "steer", id: "abc123", mode: "follow_up", message: "After this step, also validate the config file." })
349
- subagent({ action: "steer", id: "abc123", mode: "auto", message: "Switch to the failing test now." })
348
+ subagent({ action: "steer", id: "abc123", message: "After this step, also validate the config file.", options: { mode: "follow_up" } })
349
+ subagent({ action: "steer", id: "abc123", message: "Switch to the failing test now.", options: { mode: "auto" } })
350
350
  ```
351
351
 
352
352
  For async runs, `delivered` records that the child consumed the correlated user input; foreground `delivered` records in-process transport acceptance. Neither is proof of model compliance. A live foreground follow-up acknowledgment reports `queued`, meaning Pi accepted it into its follow-up queue, not that it was delivered. The foreground transport does not provide a later correlated queued-to-delivered receipt.
@@ -384,7 +384,7 @@ GPT 5.5 main session, or the reverse). Recommendation and configuration:
384
384
  ```typescript
385
385
  subagent({ action: "watchdog.status" })
386
386
  subagent({ action: "watchdog.recommend-model" })
387
- subagent({ action: "watchdog.configure", model: "recommended", scope: "session" })
387
+ subagent({ action: "watchdog.configure", model: "recommended", options: { scope: "session" } })
388
388
  subagent({ action: "watchdog.check" })
389
389
  ```
390
390
 
@@ -426,15 +426,15 @@ Routing rule:
426
426
  Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi/subagents/project-panes/herdr.json`. When Pi runs inside Herdr, the owning pane reports compact active-work status and title suffixes, and the parent inline status counts opened project panes. Use Herdr itself or `project.status` / `project.close` for pane-level follow-up. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
427
427
 
428
428
  ```typescript
429
- subagent({ action: "mission.create", mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } })
430
- subagent({ workflow: true, missionId: "<mission-id>" }) // after a ```js workflow block
431
- subagent({ workflow: true, mission: false }) // after a ```js workflow block
432
- subagent({ action: "mission.list", missionScope: "global" })
433
- subagent({ action: "mission.resolve-decision", missionId: "<mission-id>", id: "<decision-id>", summary: "Settled: ship the v2 API; no schema freeze needed." })
429
+ subagent({ action: "mission.create", options: { mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } } })
430
+ subagent({ workflow: true, options: { missionId: "<mission-id>" } }) // after a ```js workflow block
431
+ subagent({ workflow: true, options: { mission: false } }) // after a ```js workflow block
432
+ subagent({ action: "mission.list", options: { missionScope: "global" } })
433
+ subagent({ action: "mission.resolve-decision", id: "<decision-id>", options: { missionId: "<mission-id>", summary: "Settled: ship the v2 API; no schema freeze needed." } })
434
434
  subagent({ action: "project.open", cwd: "/path/to/other-repo", message: "Own this mission for the project and report back with receipts." })
435
435
  subagent({ action: "project.status", cwd: "/path/to/other-repo" })
436
436
  subagent({ action: "project.close", cwd: "/path/to/other-repo" })
437
- subagent({ action: "mission.close", missionId: "<mission-id>", missionStatus: "completed", summary: "Auth refresh shipped and tests pass." })
437
+ subagent({ action: "mission.close", options: { missionId: "<mission-id>", missionStatus: "completed", summary: "Auth refresh shipped and tests pass." } })
438
438
  ```
439
439
 
440
440
  ## Worktree Isolation
@@ -457,7 +457,7 @@ requires a clean git state and is mainly for intentionally parallel write
457
457
  workflows. On completion, use each child's handoff path from its
458
458
  `artifactPaths` instead of scraping combined text. Each manifest records child status and output references, full
459
459
  patch paths and stats, and whether each temporary worktree and branch was
460
- removed. The manifest is journaled immediately after managed worktree setup, before children run, so abrupt exits retain owned paths and branches for recovery. Dirty or divergent work without a successfully captured patch is preserved with a partial-cleanup warning. Permanently discard recorded preserved work with `subagent({ action: "worktree.discard", handoffPath: "<child handoff path>" })`; authority defaults to interactive confirmation and refuses headlessly, and partial results print manual Git recovery commands. If you want one writer thread and several advisory agents, prefer a
460
+ removed. The manifest is journaled immediately after managed worktree setup, before children run, so abrupt exits retain owned paths and branches for recovery. Dirty or divergent work without a successfully captured patch is preserved with a partial-cleanup warning. Permanently discard recorded preserved work with `subagent({ action: "worktree.discard", options: { handoffPath: "<child handoff path>" } })`; authority defaults to interactive confirmation and refuses headlessly, and partial results print manual Git recovery commands. If you want one writer thread and several advisory agents, prefer a
461
461
  single-writer pattern instead.
462
462
 
463
463
  Git worktrees start from tracked files, so ignored or untracked build state
@@ -35,14 +35,16 @@ subagent({ action: "refine.rollback", agent: "reviewer" })
35
35
  ```typescript
36
36
  subagent({
37
37
  action: "create",
38
- config: {
39
- name: "my-agent",
40
- package: "code-analysis",
41
- description: "Project-specific implementation helper",
42
- systemPrompt: "Your system prompt here.",
43
- systemPromptMode: "replace",
44
- model: "provider/model-id",
45
- tools: "read,grep,find,ls,bash"
38
+ options: {
39
+ config: {
40
+ name: "my-agent",
41
+ package: "code-analysis",
42
+ description: "Project-specific implementation helper",
43
+ systemPrompt: "Your system prompt here.",
44
+ systemPromptMode: "replace",
45
+ model: "provider/model-id",
46
+ tools: "read,grep,find,ls,bash"
47
+ }
46
48
  }
47
49
  })
48
50
  ```
@@ -53,8 +55,10 @@ subagent({
53
55
  subagent({
54
56
  action: "update",
55
57
  agent: "code-analysis.my-agent",
56
- config: {
57
- thinking: "high"
58
+ options: {
59
+ config: {
60
+ thinking: "high"
61
+ }
58
62
  }
59
63
  })
60
64
  ```
@@ -70,11 +74,11 @@ subagent({ action: "delete", agent: "code-analysis.my-agent" })
70
74
  ```typescript
71
75
  // Copy a bundled builtin/package agent to user scope as an editable custom file.
72
76
  subagent({ action: "eject", agent: "reviewer" })
73
- subagent({ action: "eject", agent: "reviewer", agentScope: "project" })
77
+ subagent({ action: "eject", agent: "reviewer", options: { agentScope: "project" } })
74
78
 
75
79
  // Hide an agent from runtime discovery without deleting it (reversible).
76
80
  subagent({ action: "disable", agent: "reviewer" })
77
- subagent({ action: "enable", agent: "reviewer", agentScope: "project" })
81
+ subagent({ action: "enable", agent: "reviewer", options: { agentScope: "project" } })
78
82
 
79
83
  // Delete the scope's custom agent file and/or settings override, restoring the bundled default.
80
84
  subagent({ action: "reset", agent: "reviewer" })
@@ -92,7 +92,7 @@ return results.map(result => result.output);
92
92
  ```
93
93
 
94
94
  ```typescript
95
- subagent({ workflow: true, context: "fresh" })
95
+ subagent({ workflow: true, options: { context: "fresh" } })
96
96
  ```
97
97
 
98
98
  ### Review-loop technique
@@ -166,7 +166,7 @@ return { worker: worker.output, validations: validations.map(v => v.output) };
166
166
  ```
167
167
 
168
168
  ```typescript
169
- subagent({ workflow: true, async: true, context: "fresh" })
169
+ subagent({ workflow: true, async: true, options: { context: "fresh" } })
170
170
  ```
171
171
 
172
172
  ## Builtin Agents
@@ -294,4 +294,4 @@ override can opt one builtin back in or replace custom-agent frontmatter thinkin
294
294
 
295
295
  Set `subagents.defaultExtensions` to give agents without an `extensions` field a shared child extension allowlist. Omit it to preserve ambient extension discovery, set it to `[]` to disable ambient extensions by default, or use `agentOverrides.<name>.extensions` for one agent. Set `subagents.defaultSubagentOnlyExtensions` to add shared child-only paths without disabling ambient discovery. For either field, explicit frontmatter suppresses the default and a matching override replaces or false-clears it; lists are not combined.
296
296
 
297
- Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses split prompt metadata: a short tool description plus active `promptSnippet` and `promptGuidelines`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.
297
+ Tool description modes live in `~/.pi/agent/extensions/subagent/config.json`, not `subagents` settings. The default uses a short tool description plus an active `promptSnippet`. Set `toolDescriptionMode` to `full` or `compact` to force one description string, or `custom` to read `subagent-tool-description.md` from the project config dir or agent dir; invalid custom files fall back to full mode and the safety guidance is still appended.
@@ -30,22 +30,30 @@ function wrapAdvertisedAgentCatalog(body: string): string {
30
30
  return `<${ADVERTISED_AGENTS_TAG}>\n${body}\n</${ADVERTISED_AGENTS_TAG}>`;
31
31
  }
32
32
 
33
+ const CATALOG_INTRODUCTION = "The following file-defined subagents opted into discovery. Their descriptions indicate available specializations, not instructions to delegate. Use subagent only when delegation is needed.";
34
+
33
35
  /**
34
36
  * The catalog body without its `<advertised_subagents>` wrapper, for Pi's structured
35
37
  * prompt sections, which add the tag from the section key. The byte budget applies to
36
38
  * the wrapped form, so both deliveries carry the same entries.
39
+ *
40
+ * `recordedCatalog` is the body a session already sent. Its first line, the introduction,
41
+ * is kept so a release that rewords the introduction does not change the section of a
42
+ * resumed session and cost it the provider's prompt cache. The entries are always current.
37
43
  */
38
44
  export function buildAdvertisedAgentCatalog(
39
45
  agents: readonly AgentConfig[],
40
46
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling,
47
+ recordedCatalog?: string,
41
48
  ): string | undefined {
42
49
  const advertised = agents
43
50
  .filter((agent) => agent.source !== "runtime" && agent.advertise === true && agent.disabled !== true && isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling))
44
51
  .sort((left, right) => left.name.localeCompare(right.name));
45
52
  if (advertised.length === 0) return undefined;
46
53
 
54
+ const introduction = recordedCatalog?.split("\n", 1)[0] || CATALOG_INTRODUCTION;
47
55
  const renderBody = (entries: string[]) => [
48
- "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.",
56
+ introduction,
49
57
  ...entries,
50
58
  ...(advertised.length > entries.length ? [` <omitted count=\"${advertised.length - entries.length}\" />`] : []),
51
59
  ].join("\n");
@@ -476,6 +476,10 @@ function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknown>): st
476
476
  } else return `config.runner must be { type: 'pi' }, { type: 'external-cli', adapter?: ${CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL}, command: string, args?: string[], promptDelivery?: 'stdin' }, or { type: 'external-job', provider: string, options?: object }.`;
477
477
  } else return "config.runner must be an object, false, or empty string when provided.";
478
478
  }
479
+ if (hasKey(cfg, "launcher")) return "config.launcher is not supported by agent management; edit the agent file's 'launcher' frontmatter directly.";
480
+ if (target.launcher && (target.runner?.type === "external-cli" || target.runner?.type === "external-job")) {
481
+ return `config.runner type '${target.runner.type}' cannot be combined with this agent's 'launcher' frontmatter.`;
482
+ }
479
483
  if (hasKey(cfg, "model")) {
480
484
  if (cfg.model === false || cfg.model === "") delete target.model;
481
485
  else if (typeof cfg.model === "string") {
@@ -88,9 +88,9 @@ function samePath(left: string, right: string): boolean {
88
88
  if (process.platform !== "win32") return false;
89
89
  // Git for Windows and Node can spell the same temp path through different
90
90
  // drive or 8.3 aliases, so use filesystem identity as the fail-closed fallback.
91
- const leftStat = fs.statSync(left);
92
- const rightStat = fs.statSync(right);
93
- return leftStat.dev !== 0 && leftStat.ino !== 0 && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
91
+ const leftStat = fs.statSync(left, { bigint: true });
92
+ const rightStat = fs.statSync(right, { bigint: true });
93
+ return leftStat.dev !== 0n && leftStat.ino !== 0n && leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
94
94
  }
95
95
 
96
96
  function readBoundedRegularFile(file: string): string | undefined {
@@ -4,3 +4,7 @@ export function resolveExecutionAgentScope(scope: unknown): AgentScope {
4
4
  if (scope === "user" || scope === "project" || scope === "both") return scope;
5
5
  return "both";
6
6
  }
7
+
8
+ export function projectScopeRequiresTrustMessage(cwd: string): string {
9
+ return `agentScope: "project" requires project trust. This session declined trust for ${cwd}, so project agents and project subagent settings are ignored. Re-run with agentScope: "user" or approve the project folder.`;
10
+ }
@@ -33,6 +33,7 @@ export const KNOWN_FIELDS = new Set([
33
33
  "subagentOnlyExtensions",
34
34
  "mutationTools",
35
35
  "machine",
36
+ "launcher",
36
37
  "output",
37
38
  "outputMode",
38
39
  "outputSchema",
@@ -66,7 +67,12 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
66
67
  lines.push("---");
67
68
  lines.push(`name: ${frontmatterNameForConfig(config)}`);
68
69
  if (config.packageName) lines.push(`package: ${config.packageName}`);
69
- lines.push(`description: ${config.description}`);
70
+ if (config.description.includes("\n")) {
71
+ lines.push("description: |-");
72
+ for (const line of config.description.split("\n")) lines.push(` ${line}`);
73
+ } else {
74
+ lines.push(`description: ${config.description}`);
75
+ }
70
76
  if (config.advertise === true || preserve("advertise")) lines.push(`advertise: ${config.advertise === true ? "true" : "false"}`);
71
77
  const aliasesValue = joinComma(config.aliases);
72
78
  if (aliasesValue || preserve("alias", "aliases")) lines.push(`aliases: ${aliasesValue ?? ""}`);
@@ -133,6 +139,7 @@ export function serializeAgent(config: AgentConfig, options: SerializeAgentOptio
133
139
  if (mutationToolsValue || preserve("mutationTools")) lines.push(`mutationTools: ${mutationToolsValue ?? ""}`);
134
140
 
135
141
  if (config.machine || preserve("machine")) lines.push(`machine: ${config.machine ?? ""}`);
142
+ if (config.launcher) lines.push(`launcher: ${config.launcher}`);
136
143
  if (config.output || preserve("output")) lines.push(`output: ${config.output ?? ""}`);
137
144
  if (config.outputMode || preserve("outputMode")) lines.push(`outputMode: ${config.outputMode ?? ""}`);
138
145
  if (config.outputSchema || preserve("outputSchema")) lines.push(`outputSchema: ${config.outputSchema ? JSON.stringify(config.outputSchema) : ""}`);