@xzzpig/pi-subagents 0.20.0 → 0.22.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.
- package/CHANGELOG.md +164 -0
- package/README.md +1 -1
- package/agents/oracle.md +8 -19
- package/agents/researcher.md +0 -3
- package/agents/reviewer.md +17 -61
- package/agents/scout.md +1 -4
- package/agents/worker.md +8 -25
- package/docs/agents.md +72 -7
- package/docs/configuration.md +58 -7
- package/docs/extension-api.md +36 -11
- package/docs/fork-extensions.md +1 -0
- package/docs/fork-supervisor-routing.md +77 -0
- package/docs/missions.md +34 -17
- package/docs/models.md +1 -1
- package/docs/observability.md +10 -5
- package/docs/tool-reference.md +117 -84
- package/docs/watchdog.md +8 -6
- package/docs/workflows.md +16 -7
- package/index.ts +5 -0
- package/package.json +6 -3
- package/prompts/council.md +1 -1
- package/skills/pi-subagents/SKILL.md +1 -1
- package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
- package/skills/pi-subagents/references/execution-controls.md +16 -16
- package/skills/pi-subagents/references/management-authoring-rpc.md +16 -12
- package/skills/pi-subagents/references/prompting-and-roles.md +3 -3
- package/src/agents/advertised-agent-prompt.ts +9 -1
- package/src/agents/agent-management.ts +4 -0
- package/src/agents/agent-memory.ts +3 -3
- package/src/agents/agent-scope.ts +4 -0
- package/src/agents/agent-serializer.ts +8 -1
- package/src/agents/agents.ts +191 -145
- package/src/api/preflight.ts +8 -4
- package/src/api/supervisor-routing.ts +196 -0
- package/src/extension/config.ts +21 -2
- package/src/extension/context-injection.ts +6 -1
- package/src/extension/control-notices.ts +1 -9
- package/src/extension/declaration-pinning.ts +164 -0
- package/src/extension/doctor.ts +7 -10
- package/src/extension/fanout-child.ts +7 -8
- package/src/extension/index.ts +143 -134
- package/src/extension/reply-workflow-script.ts +20 -11
- package/src/extension/rpc.ts +11 -6
- package/src/extension/schemas.ts +34 -30
- package/src/extension/subagent-guide.ts +86 -6
- package/src/extension/subagent-options.ts +47 -0
- package/src/extension/tool-activation.ts +3 -2
- package/src/extension/tool-description.ts +51 -68
- package/src/inspectors/actions.ts +37 -11
- package/src/inspectors/plugins.ts +3 -2
- package/src/inspectors/tmux/actions.ts +204 -0
- package/src/inspectors/tmux/client.ts +85 -0
- package/src/inspectors/tmux/plugin.ts +21 -0
- package/src/integrations/herdr-status.ts +18 -49
- package/src/integrations/program-status.ts +215 -0
- package/src/intercom/fork-supervisor-routing.ts +533 -0
- package/src/intercom/native-supervisor-channel.ts +152 -13
- package/src/intercom/result-intercom.ts +3 -2
- package/src/intercom/supervisor-ui.ts +2 -174
- package/src/missions/store.ts +25 -5
- package/src/profiles/profiles.ts +24 -21
- package/src/runs/background/active-async-capacity.ts +58 -8
- package/src/runs/background/async-execution.ts +143 -38
- package/src/runs/background/async-job-tracker.ts +11 -4
- package/src/runs/background/async-resume.ts +5 -2
- package/src/runs/background/await-async-run.ts +14 -9
- package/src/runs/background/binary-bootstrap.ts +2 -1
- package/src/runs/background/calendar-schedule.ts +90 -0
- package/src/runs/background/chain-root-attachment.ts +9 -5
- package/src/runs/background/fleet-view.ts +5 -5
- package/src/runs/background/notify.ts +185 -12
- package/src/runs/background/result-files.ts +116 -5
- package/src/runs/background/result-watcher.ts +99 -66
- package/src/runs/background/resume-guidance.ts +2 -2
- package/src/runs/background/run-child-session.ts +16 -2
- package/src/runs/background/run-id-resolver.ts +8 -5
- package/src/runs/background/run-status.ts +21 -16
- package/src/runs/background/runner-child-launch.ts +1 -0
- package/src/runs/background/runner-http-dispatcher.ts +3 -0
- package/src/runs/background/scheduled-runs.ts +256 -61
- package/src/runs/background/subagent-runner-bootstrap.ts +4 -1
- package/src/runs/background/subagent-runner.ts +32 -12
- package/src/runs/background/subagent-wait.ts +38 -19
- package/src/runs/background/terminal-run-index.ts +46 -1
- package/src/runs/background/wait-completions.ts +1 -0
- package/src/runs/background/wait-tool.ts +33 -23
- package/src/runs/background/workflow-terminal-proof.ts +39 -22
- package/src/runs/foreground/async-stop-action.ts +48 -22
- package/src/runs/foreground/execution.ts +94 -52
- package/src/runs/foreground/foreground-history.ts +1 -0
- package/src/runs/foreground/subagent-executor.ts +232 -77
- package/src/runs/shared/child-commands.ts +2 -1
- package/src/runs/shared/child-hooks.ts +4 -3
- package/src/runs/shared/child-launch.ts +3 -0
- package/src/runs/shared/child-session.ts +41 -24
- package/src/runs/shared/child-tool-plan.ts +13 -26
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/fork-command-result.ts +10 -0
- package/src/runs/shared/herdr-placed-run.ts +5 -4
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +5 -3
- package/src/runs/shared/model-resolution-diagnostic.ts +25 -0
- package/src/runs/shared/model-resolution.ts +30 -1
- package/src/runs/shared/nested-events.ts +5 -0
- package/src/runs/shared/parallel-handoff.ts +56 -8
- package/src/runs/shared/parallel-utils.ts +2 -0
- package/src/runs/shared/partial-output.ts +48 -0
- package/src/runs/shared/runner-launcher.ts +25 -0
- package/src/runs/shared/single-output.ts +53 -0
- package/src/runs/shared/structured-output.ts +14 -7
- package/src/runs/shared/subagent-control.ts +3 -3
- package/src/runs/shared/subagent-prompt-runtime.ts +47 -24
- package/src/runs/shared/workflow-async-child-guidance.ts +1 -1
- package/src/runs/shared/worktree-cleanup-apply.ts +160 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +41 -19
- package/src/runs/shared/worktree-lock.ts +29 -0
- package/src/runs/shared/worktree.ts +12 -1
- package/src/shared/atomic-json.ts +4 -2
- package/src/shared/edit-distance.ts +33 -0
- package/src/shared/file-lease.ts +74 -0
- package/src/shared/formatters.ts +1 -5
- package/src/shared/model-info.ts +22 -0
- package/src/shared/package-version.ts +17 -0
- package/src/shared/parent-wake.ts +79 -0
- package/src/shared/pruned-fork.ts +7 -1
- package/src/shared/runtime-module-path.ts +19 -0
- package/src/shared/settings-file-lease.ts +36 -0
- package/src/shared/types.ts +36 -2
- package/src/shared/utils.ts +8 -6
- package/src/slash/prompt-template-bridge.ts +21 -20
- package/src/slash/slash-commands.ts +3 -3
- package/src/slash/subagents-admin.ts +2 -1
- package/src/tui/fleet-native-transcript.ts +2 -0
- package/src/tui/fleet-transcript.ts +12 -3
- package/src/tui/fleet.ts +11 -8
- package/src/tui/render.ts +27 -19
- package/src/tui/subagent-messages.ts +305 -0
- package/src/watchdog/diff-tool.ts +2 -2
- package/src/watchdog/register-main.ts +2 -22
- package/src/watchdog/render.ts +2 -24
- package/src/watchdog/runtime.ts +6 -4
- package/src/watchdog/settings.ts +18 -13
- package/src/watchdog/tool-actions.ts +2 -2
- package/src/workflows/scripted-workflow.ts +20 -6
- package/src/workflows/workflow-resources.ts +11 -0
package/docs/missions.md
CHANGED
|
@@ -28,13 +28,15 @@ An explicit `mission` object must have exactly one non-empty `title` or `summary
|
|
|
28
28
|
```ts
|
|
29
29
|
const created = subagent({
|
|
30
30
|
action: "mission.create",
|
|
31
|
-
|
|
31
|
+
options: {
|
|
32
|
+
mission: { title: "Ship auth refresh", objective: "Implement and validate token refresh" }
|
|
33
|
+
}
|
|
32
34
|
})
|
|
33
35
|
// After a ```js workflow block that runs the approved auth refresh plan:
|
|
34
|
-
subagent({ workflow: true, missionId: "<mission-id>" })
|
|
36
|
+
subagent({ workflow: true, options: { missionId: "<mission-id>" } })
|
|
35
37
|
|
|
36
38
|
// Or create and attach in one launch
|
|
37
|
-
subagent({ workflow: true, mission: { title: "Ship auth refresh" } })
|
|
39
|
+
subagent({ workflow: true, options: { mission: { title: "Ship auth refresh" } } })
|
|
38
40
|
```
|
|
39
41
|
|
|
40
42
|
### Goal missions
|
|
@@ -44,11 +46,13 @@ Set `goal: true` with a token budget to make an open mission an active continuat
|
|
|
44
46
|
```ts
|
|
45
47
|
subagent({
|
|
46
48
|
action: "mission.create",
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
49
|
+
options: {
|
|
50
|
+
mission: {
|
|
51
|
+
title: "Ship auth refresh",
|
|
52
|
+
objective: "Implement and validate token refresh",
|
|
53
|
+
goal: true,
|
|
54
|
+
budget: { tokens: 400000 }
|
|
55
|
+
}
|
|
52
56
|
}
|
|
53
57
|
})
|
|
54
58
|
```
|
|
@@ -92,10 +96,12 @@ return runs.run("main", { agent: "reviewer", task: "Review the current diff." })
|
|
|
92
96
|
subagent({
|
|
93
97
|
action: "schedule.create",
|
|
94
98
|
id: "evening-review",
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
+
workflow: true,
|
|
100
|
+
options: {
|
|
101
|
+
name: "Evening review",
|
|
102
|
+
at: "+30m",
|
|
103
|
+
baseRef: "refs/heads/release"
|
|
104
|
+
}
|
|
99
105
|
})
|
|
100
106
|
```
|
|
101
107
|
|
|
@@ -103,15 +109,24 @@ Create a fixed recurring workflow from a script file:
|
|
|
103
109
|
|
|
104
110
|
```ts
|
|
105
111
|
// .pi/workflows/backlog.js: return runs.run('main', { agent: 'worker', task: args.task })
|
|
106
|
-
subagent({ action: "schedule.create", id: "backlog",
|
|
112
|
+
subagent({ action: "schedule.create", id: "backlog", workflow: "./.pi/workflows/backlog.js", args: { task: "Maintain core" }, options: { every: "6h", catchUp: "latest" } })
|
|
107
113
|
```
|
|
108
114
|
|
|
115
|
+
Create a daily or weekly local-time schedule:
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
subagent({ action: "schedule.create", workflow: "./.pi/workflows/review.js", options: { every: "day", at: "09:00", timezone: "Asia/Taipei" } })
|
|
119
|
+
subagent({ action: "schedule.create", workflow: "./.pi/workflows/review.js", options: { every: "week", on: ["mon", "tue", "wed", "thu", "fri"], at: "09:00", timezone: "America/New_York" } })
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Calendar schedules require `HH:mm` and an explicit IANA `timezone` or `UTC`. Weekly `on` is a non-empty weekday array; duplicates are removed and weekdays sorted. Daily schedules do not accept `on`. Missing local times and skipped dates are skipped; a repeated time fires at its first instant only. The pending local date is persisted with a UTC cache that is refreshed on restoration using the host's current timezone data. Use a calendar-capable version in every session sharing these definitions; older schedulers reject the unknown trigger kind.
|
|
123
|
+
|
|
109
124
|
Fixed intervals support `m`, `h`, `d`, and `w` units and advance from the planned time without completion drift. The schedule stores the script text read at creation, so later edits to the file do not change it. Schedule arguments are normalized and persisted for exact replay after reload; do not put secrets in them.
|
|
110
125
|
|
|
111
126
|
Create a quiet recurring workflow whose successful completions stay visible but do not wake the parent session:
|
|
112
127
|
|
|
113
128
|
```ts
|
|
114
|
-
subagent({ action: "schedule.create", id: "nightly-sweep", every: "24h", quiet: true
|
|
129
|
+
subagent({ action: "schedule.create", id: "nightly-sweep", workflow: true, options: { every: "24h", quiet: true } })
|
|
115
130
|
```
|
|
116
131
|
|
|
117
132
|
Manage schedules with `schedule.list`, `schedule.show`, `schedule.history`, `schedule.pause`, `schedule.resume`, `schedule.run`, `schedule.run-due`, and `schedule.delete`.
|
|
@@ -119,7 +134,7 @@ Manage schedules with `schedule.list`, `schedule.show`, `schedule.history`, `sch
|
|
|
119
134
|
Attach an existing mission to give each scheduled workflow access to the same durable `state.get/set`:
|
|
120
135
|
|
|
121
136
|
```ts
|
|
122
|
-
subagent({ action: "schedule.create", id: "backlog",
|
|
137
|
+
subagent({ action: "schedule.create", id: "backlog", workflow: "./.pi/workflows/backlog.js", options: { every: "6h", missionId: "<mission-id>" } })
|
|
123
138
|
```
|
|
124
139
|
|
|
125
140
|
The mission must be readable in the store resolved from the schedule's target `cwd` and current mission configuration. Creation checks it without changing its status. Every fire uses the normal explicit mission launch path, including after session restoration; missing or invalid records fail before workflow execution. Schedules accept only an existing `missionId`, not mission creation or updates. The script's fixed `args` and its mutable mission state remain separate.
|
|
@@ -133,13 +148,15 @@ Mission-bound definitions use schedule schema version 2 so older versions reject
|
|
|
133
148
|
Behavior:
|
|
134
149
|
|
|
135
150
|
- Runs always launch async with fresh context. Without `missionId`, they disable mission creation and have no `state` global.
|
|
151
|
+
- Project-wide schedules (the default) fire in whichever Pi session in that project claims the fire first, and that session receives the run's notifications. Pass `sessionOnly: true` to bind restoration and every fire to the creating session; other sessions in the project never arm it.
|
|
136
152
|
- An optional top-level `baseRef` selects the safe Git ref used by managed worktrees (default `HEAD`); it is persisted with the schedule and forwarded on every fire. The source checkout must still be clean.
|
|
137
153
|
- Definitions, bounded history, append-only events, and per-run receipts are stored with mode `0600`.
|
|
138
154
|
- `overlap` is currently fixed to `skip`; `catchUp` supports `latest` (default) and `none`.
|
|
139
|
-
- A successful `schedule.run` satisfies the next natural fire; a failed manual launch does not skip it.
|
|
155
|
+
- A successful `schedule.run` satisfies the next natural fire; a failed manual launch does not skip it. For calendars, a manual launch before today's pending fire consumes today; if today has already fired, it consumes the next pending date. When overdue, it consumes the latest pending occurrence. The next fire is after both that occurrence and the current time.
|
|
156
|
+
- If a natural calendar fire overlaps a manual launch that later fails, the pending fire remains due. Pausing the schedule while that launch is pending still prevents automatic execution after the failure.
|
|
140
157
|
- `quiet` persists only on recurring (`every`) schedules. Successful automatic fires stay visible without a parent turn; failed, stopped, or paused outcomes still wake the session. One-shot `at` schedules and `schedule.run` stay noisy unless that launch passes `quiet: true`.
|
|
141
158
|
- `schedule.run-due` lets an external launcher start due project work without making `pi-subagents` a daemon.
|
|
142
|
-
-
|
|
159
|
+
- Month/year recurrence, cron, queue/replace overlap, and the schedule TUI inspector are intentionally deferred to the next slice.
|
|
143
160
|
- The old `schedule`, `schedule-list`, `schedule-status`, and `schedule-cancel` actions were removed in a hard cutover.
|
|
144
161
|
|
|
145
162
|
Disable or bound schedules with the `scheduledRuns` config key in [configuration.md](configuration.md#scheduledruns).
|
package/docs/models.md
CHANGED
|
@@ -220,7 +220,7 @@ Model scope is policy only. It rejects or warns; it does not select a cheaper mo
|
|
|
220
220
|
|
|
221
221
|
`inherit` and `scoped` expand in the parent process at each launch. They are never sent to the child as model ids. A nested child therefore inherits its immediate parent's current model, not the original top-level model. `scoped` uses the scoped-model set at launch, so a mid-session `/scoped-models` change applies to the next child; background runs keep the set captured when the run started. Pi reports an empty set when the session is unscoped, either because nothing is configured or because no configured pattern matches an available model, and then lets the parent use every model. In that case `scoped` behaves exactly as `inherit`, which is narrower. If no parent model is available, an enforced `inherit` or `scoped` entry does not match and fails closed.
|
|
222
222
|
|
|
223
|
-
Project `modelScope` settings replace the complete user `modelScope`, as with the existing project-over-user settings precedence.
|
|
223
|
+
Project `modelScope` settings replace the complete user `modelScope`, as with the existing project-over-user settings precedence. This applies only when the session trusts the project: when project trust is declined, project subagent settings are ignored and the user `modelScope` applies.
|
|
224
224
|
|
|
225
225
|
## Profiles and provider model catalogs
|
|
226
226
|
|
package/docs/observability.md
CHANGED
|
@@ -29,6 +29,8 @@ subagent({ action: "status", id: "..." }) // one run
|
|
|
29
29
|
|
|
30
30
|
Or ask naturally: "Show me the current async runs."
|
|
31
31
|
|
|
32
|
+
In a terminal that supports [OSC 7501](https://www.superlogical.com/rex/docs/build/program-status), each background run is also reported to the terminal as working, waiting on you, finished, or failed. See [`programStatus`](configuration.md#programstatus).
|
|
33
|
+
|
|
32
34
|
### Usage and cost accounting
|
|
33
35
|
|
|
34
36
|
Run `/subagent-cost` for the parent session's combined parent and child token usage and cost. It includes completed async workflow children when their persisted receipts and metadata remain available. Missing child metadata is reported as unavailable when the receipt identifies that child. If the workflow receipt itself is missing, unreadable, invalid, or non-terminal, affected children can be omitted from the total without an unavailable count, so treat the result as a lower bound when run artifacts are unavailable.
|
|
@@ -46,7 +48,7 @@ async subagent worker · background
|
|
|
46
48
|
Press configured-expand-key for live detail
|
|
47
49
|
```
|
|
48
50
|
|
|
49
|
-
To inspect one background child in text, use `subagent({ action: "status", id: "...", view: "transcript" })`; add `index` for a specific child in a parallel or chain run.
|
|
51
|
+
To inspect one background child in text, use `subagent({ action: "status", id: "...", options: { view: "transcript" } })`; add `index` for a specific child in a parallel or chain run.
|
|
50
52
|
|
|
51
53
|
In Pi fullscreen mode with mouse dispatch, left-click
|
|
52
54
|
anywhere on the async widget's header row to fold it into a live one-line status
|
|
@@ -79,6 +81,7 @@ For compact chat results with FleetView as the only live editor surface, merge t
|
|
|
79
81
|
- `fleetView: true` retains live progress. Open `/subagents-fleet` for details instead of repeatedly requesting status just to watch progress. Pi's expand key does not expand summary results; keep `"rich"` if you want expandable inline output.
|
|
80
82
|
- `asyncWidget: false` hides only the additional under-editor async widget, leaving FleetView available. This configuration reduces visible surfaces; it does not guarantee ordering relative to other extensions.
|
|
81
83
|
- `asyncWidgetCollapsed: true` starts each newly mounted async widget as a one-line live status summary; click its header to expand it.
|
|
84
|
+
- `asyncWidgetLayout: "rows"` shows each run in the async widget as one line under a header instead of a block of detail rows; Pi's expand key still shows the details.
|
|
82
85
|
|
|
83
86
|
Thanks to [DraconDev](https://github.com/DraconDev) for reporting the display noise and suggesting summary mode in [#1931](https://github.com/nicobailon/pi-subagents/issues/1931).
|
|
84
87
|
|
|
@@ -129,11 +132,11 @@ In the structured view every replayed assistant message keeps its own thinking b
|
|
|
129
132
|
|
|
130
133
|
`Ctrl+Alt+F` opens the same inspector even while a foreground turn is active and slash input is queued.
|
|
131
134
|
|
|
132
|
-
Enter and `H` use the available Inspect plugin. On macOS with Ghostty 1.3+ (TERM_PROGRAM=ghostty), this includes the other bundled open-only plugin using Ghostty's preview AppleScript API; status and close are unavailable because no binding is written. In a child-specific inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls. The bundled Herdr plugin uses Herdr 0.7.5+.
|
|
135
|
+
Enter and `H` use the available Inspect plugin. Inside tmux, this includes the bundled tmux plugin: it splits the focused window, runs the inspector pane there, and records a binding, so `status` and `close` are available and ordinary tmux keys such as the prefix keep working in the pane. On macOS with Ghostty 1.3+ (TERM_PROGRAM=ghostty), this includes the other bundled open-only plugin using Ghostty's preview AppleScript API; status and close are unavailable because no binding is written. In a child-specific inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls. The bundled Herdr plugin uses Herdr 0.7.5+.
|
|
133
136
|
|
|
134
|
-
Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "status", view: "fleet" })` fallback, and mutations use explicit commands: run `/subagents-stop` and pick from the selector, or use `/subagents-stop <run-id>` / `subagent({ action: "stop", id: "..." })` when you already know the id.
|
|
137
|
+
Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "status", options: { view: "fleet" } })` fallback, and mutations use explicit commands: run `/subagents-stop` and pick from the selector, or use `/subagents-stop <run-id>` / `subagent({ action: "stop", id: "..." })` when you already know the id.
|
|
135
138
|
|
|
136
|
-
Use `/subagents-detach [run-id]` only for an active foreground single-subagent run you want to leave running without terminating; the eventual result remains available through status/wait.
|
|
139
|
+
Use `/subagents-detach [run-id]` only for an active foreground single-subagent run you want to leave running without terminating; the eventual result remains available through status/wait. A detached foreground child runs inside the current pi-subagents runtime. When `/reload`, a session resume, or a session switch replaces that runtime, the child is stopped, and `status` then shows it as stopped with the reason. `resume` continues it from its session.
|
|
137
140
|
|
|
138
141
|
Set `foregroundDetachShortcut` in `~/.pi/agent/extensions/subagent/config.json` to bind the same action to a shortcut. The running foreground card shows the configured shortcut beside its live-detail hint:
|
|
139
142
|
|
|
@@ -301,7 +304,7 @@ Debug artifacts live under `{sessionDir}/subagent-artifacts/`, `.pi/subagents/ar
|
|
|
301
304
|
- `{runId}_{agent}.jsonl`
|
|
302
305
|
- `{runId}_{agent}_meta.json`
|
|
303
306
|
|
|
304
|
-
Metadata records timing, usage, exit code, the resolved model, and the resolved acceptance ledger with its parsed child report. A strictly guarded retained-session recovery after a verified compaction abort may continue once on that same model; it never selects another model.
|
|
307
|
+
Metadata records the parent session id, timing, usage, exit code, the resolved model, and the resolved acceptance ledger with its parsed child report. A strictly guarded retained-session recovery after a verified compaction abort may continue once on that same model; it never selects another model.
|
|
305
308
|
|
|
306
309
|
For npm package projects, project-scoped artifacts need a `.npmignore` rule (or `.gitignore` when no `.npmignore` exists) or a `files` allowlist that does not include `.pi/subagents/`. pi-subagents warns at launch when these package settings can include the artifacts. Use `artifactDir: "session"` or `"temp"` to keep them outside the package worktree.
|
|
307
310
|
|
|
@@ -309,6 +312,8 @@ For npm package projects, project-scoped artifacts need a `.npmignore` rule (or
|
|
|
309
312
|
|
|
310
313
|
Session files are stored under a per-run session directory. With `context: "fork"`, each child starts from a branched session file produced from the parent's current leaf (foreground children open it in-process; background children receive it as `--session`). That is a real session fork, not an injected summary. An omitted launch `context` that resolves through `defaultContext: fork` uses the same branch when the parent session file and current leaf exist, and otherwise starts fresh.
|
|
311
314
|
|
|
315
|
+
A child session's header records the launching session's file as `parentSession`, the field Pi uses for its own forks, so a reader can find the parent session without parsing the directory layout. A nested child points at the session of the child that launched it. Run metadata (`{runId}_{agent}_meta.json`) also records `parentSessionId`, the launching session's id.
|
|
316
|
+
|
|
312
317
|
## Completion notifications
|
|
313
318
|
|
|
314
319
|
Async completions belong only to the originating session. The result watcher emits `subagent:async-complete` for detached runs. Awaited workflow children emit it when they settle, with `awaitedByWorkflow: true`, `parentWorkflowRunId`, and `triggerTurn: false`. They do not send a separate child notification or turn.
|
package/docs/tool-reference.md
CHANGED
|
@@ -4,7 +4,7 @@ Parameters and actions for the `subagent` tool. These are what the LLM passes wh
|
|
|
4
4
|
|
|
5
5
|
In a fresh parent session, `subagents_enable({})` makes the full `subagent` tool available on the immediately following model request without launching work. Pi may call it when delegation is authorized by the current request or applicable instructions, or to manage existing runs. Direct execution remains the default; task complexity does not grant delegation authority. The public `subagent` name and parameters are unchanged after activation.
|
|
6
6
|
|
|
7
|
-
Call `{ action: "guide", topic: "tool-reference" }` for this reference or `topic: "workflows"` for [workflow recipes](workflows.md). Use `topic: "agents"` for authoring, `topic: "missions"` for missions/schedules, and `topic: "watchdog"` for watchdog controls
|
|
7
|
+
Call `{ action: "guide", options: { topic: "tool-reference" } }` for this reference or `options: { topic: "workflows" }` for [workflow recipes](workflows.md). Use `topic: "agents"` for authoring, `topic: "missions"` for missions/schedules, and `topic: "watchdog"` for watchdog controls, always inside `options`. Guide reads do not change the schema or grant authority.
|
|
8
8
|
|
|
9
9
|
## Execution examples
|
|
10
10
|
|
|
@@ -30,7 +30,7 @@ The host resolves the script and authority internally and records bounded proven
|
|
|
30
30
|
```js
|
|
31
31
|
{ workflow: "./workflows/review.js", args: { target: "src/workflows" }, cwd: "/path/to/project" }
|
|
32
32
|
{ action: "validate", workflow: "./workflows/review.js", args: { target: "src/workflows" } }
|
|
33
|
-
{ action: "schedule.create",
|
|
33
|
+
{ action: "schedule.create", workflow: "./workflows/review.js", args: { target: "src/workflows" }, options: { every: "6h" } }
|
|
34
34
|
```
|
|
35
35
|
|
|
36
36
|
Each script below is the ```` ```js workflow ```` block of a reply that then calls `subagent({ workflow: true })`:
|
|
@@ -67,49 +67,59 @@ The complete plain-JSON inventory is validated before the first launch (maximum
|
|
|
67
67
|
|
|
68
68
|
## Parameter reference
|
|
69
69
|
|
|
70
|
+
The `subagent` tool schema lists `agent`, `task`, `workflow`, `args`, `async`, `model`, `cwd`, `worktree`, `output`, `action`, `id` and `message` at the top level and every other field inside `options`, for example `subagent({ action: "status", id: "<run-id>", options: { view: "transcript" } })`. Management fields and the `runId`, `maxRuntimeMs` and `isolation` aliases also keep working at the top level, as in RPC payloads, slash commands, schedules and workflow `runs.run`/`runs.all` items; a field given in both places with different values is rejected.
|
|
71
|
+
|
|
72
|
+
### Target and management parameters
|
|
73
|
+
|
|
70
74
|
| Param | Type | Default | Description |
|
|
71
75
|
|-------|------|---------|-------------|
|
|
76
|
+
| `options` | object | - | Management and control fields; the rows named `options.<name>` below go here. Unknown keys are rejected with the closest valid option. The same fields are also accepted at the top level. |
|
|
72
77
|
| `agent` | string | - | One direct child or agent-management target. Workflow child agents are set inside `runs.run` or `runs.all`. |
|
|
73
78
|
| `task` | string | agent default | Direct child's task; requires `agent`, excludes `action` and workflow inputs. `agent` may also select a management target. |
|
|
74
|
-
| `action` | string | - | Offline workflow `validate`, agent management (including `guide`, `children.list`, and `refine`/`refine.show`/`refine.rollback`), lane evidence (`lane.status`, `lane.recordMerge`, `lane.recordSupersession`), mission (`mission.create/list/show/update/resolve-decision/attach-run/close`), Inspect actions (`inspector.command/open/status/close`), Herdr project pane (`project.open/status/close`), status/control,
|
|
75
|
-
| `topic` | `overview \| workflows \| agents \| missions \| observability \| tool-reference \| configuration \| models \| watchdog \| extension-api \| council
|
|
76
|
-
| `config` | object/string | - | Agent config for management create/update. |
|
|
77
|
-
| `context` | `fresh \| fork \| profile` | global or per-agent default, else `fresh` | Explicit `fresh` or `fork` overrides every workflow child. `profile` requires the selected agent's declared `defaultContext` and ignores config `defaultSubagentContext`; missing agent defaults fail. When omitted, [`defaultSubagentContext`](configuration.md#defaultsubagentcontext) wins over each agent's `defaultContext`; implicit fork falls back to fresh without a persisted parent session and leaf. Explicit fork is strict. Packaged `worker` defaults to `fresh`; packaged `oracle` and `advisor` default to `fork`. |
|
|
78
|
-
| `model` | string | agent default |
|
|
79
|
-
| `missionId` | string | - | Attach a workflow, including each fire of `schedule.create`, to an existing project mission. Scheduled attachment uses ordinary lifecycle and retention rules. |
|
|
80
|
-
| `mission` | object/false | auto-create | Override the default enclosing mission with `{ title \| summary, objective?, goal?, budget?, labels? }`. Set exactly one non-empty `title` or `summary`; `objective` and `labels` are optional. `goal` may only be `true`, requires `budget.tokens`, and enables continuation notices. Pass `false` for an intentionally ephemeral workflow with no mission for it or its children and no `state` global. Explicit mission persistence failures are strict. |
|
|
81
|
-
| `handoffPath` | string | - | Aggregate handoff manifest for `action: "worktree.discard"` or lane evidence actions, or optional explicit metadata for `action: "worktree.cleanup"`. |
|
|
82
|
-
| `repo` | string | runtime cwd | Repository path for `action: "worktree.cleanup"`;
|
|
83
|
-
| `planId` | string | - |
|
|
84
|
-
| `mode` | `steer \| follow_up \| auto \| plan \| apply` | - | Delivery mode for `action: "steer"`; `worktree.cleanup`
|
|
85
|
-
| `laneId` | string | - | Exact `runId` stored in the handoff manifest for `lane.status`, `lane.recordMerge`, or `lane.recordSupersession`. |
|
|
86
|
-
| `merge` | object | - | Attested merge evidence for `lane.recordMerge`; requires a positive PR number, full reviewed/merge SHAs, tree-equivalence and post-merge-check statuses, attestor, and timestamp. |
|
|
87
|
-
| `supersession` | object | - | Attested replacement-lane evidence for `lane.recordSupersession`; requires a different replacement lane id, attestor, and timestamp. |
|
|
88
|
-
| `focus` | boolean | false | Focus the newly split host inspector pane for `action: "inspector.open"` or the new Herdr project pane for `action: "project.open"`; not a standalone action. `inspector.command` is read-only and does not contact Herdr or write a binding. Panes open in the background unless you set `focus: true`. Existing saved project panes can be focused through the public project-pane API when Herdr reports a tab or workspace id. |
|
|
89
|
-
| `view` | `fleet \| transcript` | - | Optional `status` view for the active fleet surface or transcript tail inspection. |
|
|
90
|
-
| `lines` | number | `80` | Maximum transcript lines for `action: "status"
|
|
91
|
-
| `agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
|
|
92
|
-
| `capabilities` | boolean | `false` | With `action: "list"`, return compact prompt-free rows and `details.agentCapabilities` machine-readable records for each agent's declared/default routing capabilities. External CLI rows also include their command and passive local availability. |
|
|
79
|
+
| `action` | string | - | Offline workflow `validate`, agent management (including `guide`, `children.list`, and `refine`/`refine.show`/`refine.rollback`), lane evidence (`lane.status`, `lane.recordMerge`, `lane.recordSupersession`), mission (`mission.create/list/show/update/resolve-decision/attach-run/close`), Inspect actions (`inspector.command/open/status/close`), Herdr project pane (`project.open/status/close`), status/control, reviewed `worktree.cleanup`, schedule, watchdog, or doctor action. |
|
|
80
|
+
| `options.topic` | `overview \| workflows \| agents \| missions \| observability \| tool-reference \| configuration \| models \| watchdog \| extension-api \| council`, or `<topic>/<section>` | `overview` | Packaged guide topic for `action: "guide"`. A docs topic returns its table of contents; `<topic>/<section>` returns one section. |
|
|
81
|
+
| `options.config` | object/string | - | Agent config for management create/update. |
|
|
82
|
+
| `options.context` | `fresh \| fork \| profile` | global or per-agent default, else `fresh` | Explicit `fresh` or `fork` overrides every workflow child. `profile` requires the selected agent's declared `defaultContext` and ignores config `defaultSubagentContext`; missing agent defaults fail. When omitted, [`defaultSubagentContext`](configuration.md#defaultsubagentcontext) wins over each agent's `defaultContext`; implicit fork falls back to fresh without a persisted parent session and leaf. Explicit fork is strict. Packaged `worker` defaults to `fresh`; packaged `oracle` and `advisor` default to `fork`. |
|
|
83
|
+
| `model` | string | agent default | An exact `provider/id`; bare ids resolve only if unique, and agent names are not model ids. An unknown or ambiguous model fails with up to 5 closest registry ids to copy; `{action:"models"}` lists them all. A suffix such as `provider/id:high` (`off/minimal/low/medium/high/xhigh/max`) overrides agent thinking. The `thinking` field is only for `watchdog.configure`, ignored on dispatch. On the `claude-code` and `claude-code-writer` adapters the model is Claude Code's own alias or id, and the same suffix becomes its `--effort`, bounded by `subagents.maxThinking` and by an enforced `subagents.modelScope`. |
|
|
84
|
+
| `options.missionId` | string | - | Attach a workflow, including each fire of `schedule.create`, to an existing project mission. Scheduled attachment uses ordinary lifecycle and retention rules. |
|
|
85
|
+
| `options.mission` | object/false | auto-create | Override the default enclosing mission with `{ title \| summary, objective?, goal?, budget?, labels? }`. Set exactly one non-empty `title` or `summary`; `objective` and `labels` are optional. `goal` may only be `true`, requires `budget.tokens`, and enables continuation notices. Pass `false` for an intentionally ephemeral workflow with no mission for it or its children and no `state` global. Explicit mission persistence failures are strict. |
|
|
86
|
+
| `options.handoffPath` | string | - | Aggregate handoff manifest for `action: "worktree.discard"` or lane evidence actions, or optional explicit metadata for `action: "worktree.cleanup"`. |
|
|
87
|
+
| `options.repo` | string | runtime cwd | Repository path for `action: "worktree.cleanup"`; required explicitly for apply. The configured worktree base filters candidates by their per-project folder under it but never discovers them. |
|
|
88
|
+
| `options.planId` | string | - | Saved, reviewed cleanup plan ID; required for apply, rejected in plan mode. |
|
|
89
|
+
| `options.mode` | `steer \| follow_up \| auto \| plan \| apply` | - | Delivery mode for `action: "steer"`; `worktree.cleanup` accepts `plan` or `apply`; apply requires an explicit repository and saved plan ID. |
|
|
90
|
+
| `options.laneId` | string | - | Exact `runId` stored in the handoff manifest for `lane.status`, `lane.recordMerge`, or `lane.recordSupersession`. |
|
|
91
|
+
| `options.merge` | object | - | Attested merge evidence for `lane.recordMerge`; requires a positive PR number, full reviewed/merge SHAs, tree-equivalence and post-merge-check statuses, attestor, and timestamp. |
|
|
92
|
+
| `options.supersession` | object | - | Attested replacement-lane evidence for `lane.recordSupersession`; requires a different replacement lane id, attestor, and timestamp. |
|
|
93
|
+
| `options.focus` | boolean | false | Focus the newly split host inspector pane for `action: "inspector.open"` or the new Herdr project pane for `action: "project.open"`; not a standalone action. `inspector.command` is read-only and does not contact Herdr or write a binding. Panes open in the background unless you set `focus: true`. Existing saved project panes can be focused through the public project-pane API when Herdr reports a tab or workspace id. |
|
|
94
|
+
| `options.view` | `fleet \| transcript` | - | Optional `status` view for the active fleet surface or transcript tail inspection. |
|
|
95
|
+
| `options.lines` | number | `80` | Maximum transcript lines for `action: "status"` with `options.view: "transcript"`; capped at 500. |
|
|
96
|
+
| `options.agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
|
|
97
|
+
| `options.capabilities` | boolean | `false` | With `action: "list"`, return compact prompt-free rows and `details.agentCapabilities` machine-readable records for each agent's declared/default routing capabilities. External CLI rows also include their command and passive local availability. |
|
|
98
|
+
|
|
99
|
+
### Execution parameters
|
|
100
|
+
|
|
101
|
+
| Param | Type | Default | Description |
|
|
102
|
+
|-------|------|---------|-------------|
|
|
93
103
|
| `async` | boolean | default-on | Background execution. Workflows default to background. `async:false` blocks the parent until completion. A local foreground child runs inside the parent Pi process and never loads the parent's ambient extensions, but it does inherit the providers those extensions registered. A pane-native remote foreground child instead uses the remote machine's provider discovery and configuration. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) must run as background children, which load them inside the detached runner process. |
|
|
94
|
-
| `chatProgress` | `auto \| off \| live-card` | `auto` | Workflow chat projection. `auto` renders a live in-chat card only for watched foreground workflows in the same Git repository, including managed worktrees; it is off otherwise. Explicit `live-card` requires `async:false` and the same Git repository. Async workflows have no inline live card, so omit `chatProgress` or use `auto`/`off`; use `async:false` only when the parent must block. |
|
|
95
|
-
| `isolation` | `none \| worktree` | - | Workflow child isolation. `none` runs in the shared cwd and does not need Git. `worktree` requires a managed Git worktree. Do not combine it with a contradictory `worktree` value. |
|
|
96
|
-
| `baseRef` | string | `HEAD` | `HEAD` or a supported named ref such as `refs/heads/release`, `refs/tags/v1`, or `origin/main`. Full 40/64-character commit IDs and revision expressions such as `HEAD~1` are unsupported. The ref must resolve to a commit at worktree allocation; omitted values default to `HEAD` resolved at that time. Source-checkout cleanliness is still checked. For a workflow script, set it on the outer request as a default or on an individual `runs.run`/`runs.all` child to override it. |
|
|
97
|
-
| `timeoutMs`
|
|
98
|
-
| `toolTimeoutMs` | number | fast-tool default | Optional positive hard per-tool-call deadline in milliseconds. Precedence: call value → agent frontmatter → config → `PI_SUBAGENT_TOOL_TIMEOUT_MS`. The timer starts on `tool_execution_start`, clears on the matching `tool_execution_end`, and terminates the run with `timedOut: true` if the tool remains open. When omitted, known-fast built-in tools get a five-minute default; long-running tools get attention notices but no hard default. It never extends the run deadline; `contact_supervisor`, `intercom`, and `bg_wait` are exempt. |
|
|
99
|
-
| `checkpointBeforeDeadlineMs` | number | none | Async single-agent runs only. The runner requests that the child "checkpoint and stop" this many milliseconds before the run deadline (finish the current tool call, report changed files, build/test state, remaining work, commit/PR state; start no new work). This best-effort steer uses the normal steering lifecycle at the next tool boundary, so the receipt is visible in status and events; the ordinary deadline kill still applies. Precedence: call value → config `checkpointBeforeDeadlineMs`. Disarmed when the deadline leaves under one second before the checkpoint. |
|
|
100
|
-
| `toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`: `hard` is a positive integer and `soft`, if set, is a positive integer no greater than `hard`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, and accepts either a nonempty array of tool names or `"*"` for every tool call. Final assistant text is never blocked. |
|
|
101
|
-
| `usageBudget` | object | none | Optional root-only reported-usage budget `{ tokens?: { soft?, hard }, costUsd?: { soft?, hard } }`. Include at least one metric; each `hard` must be positive and each optional `soft` positive and no greater than its `hard`. Soft limits are status-only. Hard limits prevent later child launches after reported usage is reconciled; already-running children are not stopped and no reservations are made. |
|
|
102
|
-
| `extensionBindings` | object | none | Child-only plain JSON keyed by namespaces like `package.name/1` (positive version): at most 16 namespaces, nesting depth 16, 256 total object properties, and 16 KiB of canonical UTF-8 JSON. Native Pi launches only; external runners and retained resumes reject it. |
|
|
103
|
-
| `preflight` | object | none | Advisory lane hints for raw scripts (`workflow: true` or a script path) only; not accepted with named workflows or direct children. See [bounded workflows](workflows.md#opt-in-bounded-workflows). |
|
|
104
|
+
| `options.chatProgress` | `auto \| off \| live-card` | `auto` | Workflow chat projection. `auto` renders a live in-chat card only for watched foreground workflows in the same Git repository, including managed worktrees; it is off otherwise. Explicit `live-card` requires `async:false` and the same Git repository. Async workflows have no inline live card, so omit `chatProgress` or use `auto`/`off`; use `async:false` only when the parent must block. |
|
|
105
|
+
| `isolation` | `none \| worktree` | - | Alias kept at the top level; prefer `worktree`. Workflow child isolation. `none` runs in the shared cwd and does not need Git. `worktree` requires a managed Git worktree. Do not combine it with a contradictory `worktree` value. |
|
|
106
|
+
| `options.baseRef` | string | `HEAD` | `HEAD` or a supported named ref such as `refs/heads/release`, `refs/tags/v1`, or `origin/main`. Full 40/64-character commit IDs and revision expressions such as `HEAD~1` are unsupported. The ref must resolve to a commit at worktree allocation; omitted values default to `HEAD` resolved at that time. Source-checkout cleanliness is still checked. For a workflow script, set it on the outer request as a default or on an individual `runs.run`/`runs.all` child to override it. |
|
|
107
|
+
| `options.timeoutMs` | number | config `timeoutMs`, else 30 min foreground / single-agent async | Optional run-level max runtime in milliseconds. The top-level alias `maxRuntimeMs` is also accepted; both must agree. When omitted, the global [`timeoutMs`](configuration.md#timeoutms) config provides the default; absent that, foreground and plain single-agent async runs fall back to 30 minutes, while composite async runs (chains, parallel tasks, workflows) stay unbounded at the top level. Expiration of this run-level deadline is terminal. |
|
|
108
|
+
| `options.toolTimeoutMs` | number | fast-tool default | Optional positive hard per-tool-call deadline in milliseconds. Precedence: call value → agent frontmatter → config → `PI_SUBAGENT_TOOL_TIMEOUT_MS`. The timer starts on `tool_execution_start`, clears on the matching `tool_execution_end`, and terminates the run with `timedOut: true` if the tool remains open. When omitted, known-fast built-in tools get a five-minute default; long-running tools get attention notices but no hard default. It never extends the run deadline; `contact_supervisor`, `intercom`, and `bg_wait` are exempt. |
|
|
109
|
+
| `options.checkpointBeforeDeadlineMs` | number | none | Async single-agent runs only. The runner requests that the child "checkpoint and stop" this many milliseconds before the run deadline (finish the current tool call, report changed files, build/test state, remaining work, commit/PR state; start no new work). This best-effort steer uses the normal steering lifecycle at the next tool boundary, so the receipt is visible in status and events; the ordinary deadline kill still applies. Precedence: call value → config `checkpointBeforeDeadlineMs`. Disarmed when the deadline leaves under one second before the checkpoint. |
|
|
110
|
+
| `options.toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`: `hard` is a positive integer and `soft`, if set, is a positive integer no greater than `hard`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, and accepts either a nonempty array of tool names or `"*"` for every tool call. Final assistant text is never blocked. |
|
|
111
|
+
| `options.usageBudget` | object | none | Optional root-only reported-usage budget `{ tokens?: { soft?, hard }, costUsd?: { soft?, hard } }`. Include at least one metric; each `hard` must be positive and each optional `soft` positive and no greater than its `hard`. Soft limits are status-only. Hard limits prevent later child launches after reported usage is reconciled; already-running children are not stopped and no reservations are made. |
|
|
112
|
+
| `options.extensionBindings` | object | none | Child-only plain JSON keyed by namespaces like `package.name/1` (positive version): at most 16 namespaces, nesting depth 16, 256 total object properties, and 16 KiB of canonical UTF-8 JSON. Native Pi launches only; external runners and retained resumes reject it. |
|
|
113
|
+
| `options.preflight` | object | none | Advisory lane hints for raw scripts (`workflow: true` or a script path) only; not accepted with named workflows or direct children. See [bounded workflows](workflows.md#opt-in-bounded-workflows). |
|
|
104
114
|
| `cwd` | string | runtime cwd | Override working directory. With `machine`, the directory on that machine. |
|
|
105
|
-
| `machine` | string | - | Herdr saved machine (label or profile id) for external-cli agents; see [agents.md](agents.md#running-external-cli-agents-on-a-herdr-saved-machine). |
|
|
106
|
-
| `maxOutput` | object | none | Final output truncation limits `{ bytes?, lines? }`. For child runs it is only applied when set; there is no default cap on the inline path, so use `outputMode: "file-only"` for large outputs. For workflow script results, the Return, Emitted, and Console sections are always capped, at 200 KB / 5000 lines unless `maxOutput` sets other limits. |
|
|
107
|
-
| `artifacts` | boolean | true | Write debug artifacts. |
|
|
108
|
-
| `includeProgress` | boolean | false | Include full progress in result. |
|
|
109
|
-
| `share` | boolean | false | Upload session export to GitHub Gist. |
|
|
110
|
-
| `sessionDir` | string | derived | Override session log directory. |
|
|
111
|
-
| `acceptance` | string/object/false | inferred | Configure evidence gates. See [Acceptance gates](#acceptance-gates). |
|
|
112
|
-
| `gate` | string \| object | - | One host-run verification command, shorthand for `acceptance: { level: "verified", verify: [{ id: "gate", command }] }`. The object form `{ command, output?: "json", schema?, timeoutMs? }` adds a [typed gate](#typed-gates): with `output: "json"`, a passing command's stdout becomes the child's `structuredOutput`. Also valid on individual `runs.run`/`runs.all` items. Rejects `acceptance` except `false` (treated as omitted), rejects retained `resume`, and `output: "json"` rejects `outputSchema`. |
|
|
115
|
+
| `options.machine` | string | - | Herdr saved machine (label or profile id) for external-cli agents; see [agents.md](agents.md#running-external-cli-agents-on-a-herdr-saved-machine). |
|
|
116
|
+
| `options.maxOutput` | object | none | Final output truncation limits `{ bytes?, lines? }`. For child runs it is only applied when set; there is no default cap on the inline path, so use `outputMode: "file-only"` for large outputs. For workflow script results, the Return, Emitted, and Console sections are always capped, at 200 KB / 5000 lines unless `maxOutput` sets other limits. |
|
|
117
|
+
| `options.artifacts` | boolean | true | Write debug artifacts. |
|
|
118
|
+
| `options.includeProgress` | boolean | false | Include full progress in result. |
|
|
119
|
+
| `options.share` | boolean | false | Upload session export to GitHub Gist. |
|
|
120
|
+
| `options.sessionDir` | string | derived | Override session log directory. |
|
|
121
|
+
| `options.acceptance` | string/object/false | inferred | Configure evidence gates. See [Acceptance gates](#acceptance-gates). |
|
|
122
|
+
| `options.gate` | string \| object | - | One host-run verification command, shorthand for `acceptance: { level: "verified", verify: [{ id: "gate", command }] }`. The object form `{ command, output?: "json", schema?, timeoutMs? }` adds a [typed gate](#typed-gates): with `output: "json"`, a passing command's stdout becomes the child's `structuredOutput`. Also valid on individual `runs.run`/`runs.all` items. Rejects `acceptance` except `false` (treated as omitted), rejects retained `resume`, and `output: "json"` rejects `outputSchema`. |
|
|
113
123
|
|
|
114
124
|
### Budget guidance for writers
|
|
115
125
|
|
|
@@ -150,7 +160,7 @@ return { first: first.key, rest: rest.map((child) => child.key), receipt };
|
|
|
150
160
|
|
|
151
161
|
Use `outputMode: "file-only"` when a saved output may be large and the parent only needs a pointer. The returned text is a compact reference like `Output saved to: /abs/report.md (48.2 KB, 2847 lines). Read this file if needed.` Failed runs and save errors still return normal inline output for debugging.
|
|
152
162
|
|
|
153
|
-
In a workflow script, give each child an explicit output path when later script steps need a durable file reference. A child with only read-only tools does not need direct filesystem access for `output`: it returns the complete artifact in its final response and the runtime persists it. Children with mutation-capable tools retain the direct-write instruction.
|
|
163
|
+
In a workflow script, give each child an explicit output path when later script steps need a durable file reference. A child with only read-only tools does not need direct filesystem access for `output`: it returns the complete artifact in its final response and the runtime persists it. Children with mutation-capable tools retain the direct-write instruction. With `outputSchema`, the runtime persists the structured result as indented JSON instead of the final prose, unless the child wrote the file itself.
|
|
154
164
|
|
|
155
165
|
The `output` field is the API binding; a filename mentioned in task text (for example, `Write your findings to exactly this path: report.md`) is only instruction and does not override runtime routing. When a later workflow step or parent needs a durable file, set `output` on `runs.run`/`runs.all` and return the child’s `outputReference`, `outputPathMapping`, or `artifactPaths`; arbitrary literal strings returned by workflow JavaScript are not rewritten. Omitted child output may use a managed aggregate-derived sibling path.
|
|
156
166
|
|
|
@@ -181,20 +191,20 @@ For a simple implementation challenge outside a workflow script, send the challe
|
|
|
181
191
|
|
|
182
192
|
### Guide
|
|
183
193
|
|
|
184
|
-
`{ action: "guide" }` reads the packaged `README.md` from the installed version. Pass
|
|
194
|
+
`{ action: "guide" }` reads the packaged `README.md` from the installed version. Pass a docs topic to get the intro of its packaged `docs/<topic>.md` and a table of section addresses, then pass `topic: "<topic>/<section>"` (for example `"tool-reference/acceptance-gates"`) to read one section. A section runs from its heading to the next heading at the same or a higher level, and no response is longer than 8,000 characters: a larger section returns its intro and its subsection addresses. The `council` topic returns the packaged `skills/council-mode/SKILL.md` with the references it asks for, so `/council` works when Pi runs with `--no-skills`. Unknown topics list the valid values, unknown sections list the topic's table of contents, and neither changes files. Use `/subagents-guide [topic]` for the slash equivalent.
|
|
185
195
|
|
|
186
196
|
Agent definitions are not loaded into context by default. Management actions let the LLM discover, inspect, create, update, and delete agents at runtime. An unknown action returns safe next steps (`status` and `list`) and may suggest a close non-destructive action. Destructive actions are only named for a near-complete one-character typo, and suggestions never execute an action.
|
|
187
197
|
|
|
188
198
|
```ts
|
|
189
199
|
{ action: "list" }
|
|
190
|
-
{ action: "list", agentScope: "project" }
|
|
191
|
-
{ action: "list", capabilities: true }
|
|
200
|
+
{ action: "list", options: { agentScope: "project" } }
|
|
201
|
+
{ action: "list", options: { capabilities: true } }
|
|
192
202
|
{ action: "get", agent: "scout" }
|
|
193
203
|
{ action: "models" }
|
|
194
204
|
{ action: "models", agent: "reviewer" }
|
|
195
205
|
{ action: "get", agent: "code-analysis.scout" }
|
|
196
206
|
|
|
197
|
-
{ action: "create", config: {
|
|
207
|
+
{ action: "create", options: { config: {
|
|
198
208
|
name: "Code Scout",
|
|
199
209
|
package: "code-analysis",
|
|
200
210
|
description: "Scans codebases for patterns and issues",
|
|
@@ -214,24 +224,24 @@ Agent definitions are not loaded into context by default. Management actions let
|
|
|
214
224
|
output: "context.md",
|
|
215
225
|
reads: "shared-context.md",
|
|
216
226
|
progress: true
|
|
217
|
-
}}
|
|
227
|
+
}}}
|
|
218
228
|
|
|
219
229
|
|
|
220
|
-
{ action: "update", agent: "code-analysis.scout", config: { model: "openai/gpt-4o" } }
|
|
221
|
-
{ action: "update", agent: "code-analysis.scout", config: { acceptance: "" } } // clear the frontmatter default
|
|
222
|
-
{ action: "update", agent: "code-analysis.scout", config: { acceptanceRole: false } } // restore default lightweight attestation
|
|
230
|
+
{ action: "update", agent: "code-analysis.scout", options: { config: { model: "openai/gpt-4o" } } }
|
|
231
|
+
{ action: "update", agent: "code-analysis.scout", options: { config: { acceptance: "" } } } // clear the frontmatter default
|
|
232
|
+
{ action: "update", agent: "code-analysis.scout", options: { config: { acceptanceRole: false } } } // restore default lightweight attestation
|
|
223
233
|
{ action: "delete", agent: "scout" }
|
|
224
234
|
|
|
225
235
|
{ action: "eject", agent: "reviewer" }
|
|
226
|
-
{ action: "eject", agent: "reviewer", agentScope: "project" }
|
|
236
|
+
{ action: "eject", agent: "reviewer", options: { agentScope: "project" } }
|
|
227
237
|
{ action: "disable", agent: "reviewer" }
|
|
228
|
-
{ action: "enable", agent: "reviewer", agentScope: "project" }
|
|
238
|
+
{ action: "enable", agent: "reviewer", options: { agentScope: "project" } }
|
|
229
239
|
{ action: "reset", agent: "reviewer" }
|
|
230
240
|
```
|
|
231
241
|
|
|
232
242
|
Rules:
|
|
233
243
|
|
|
234
|
-
- `capabilities: true` changes `action: "list"` to compact one-line rows and adds `details.agentCapabilities: { agents, restrictedCount, capabilityCeilingSources? }`. Each agent row includes source, aliases, runner type/capabilities, tools, MCP direct tools, mutation tools, model/thinking, default async/timeout, declared acceptance policy/role, output path/mode, skills/extensions, and whether the current capability ceiling allows execution. External CLI rows include `runner.command`, `runner.available`, and a bounded `runner.unavailableReason` when passive PATH/PATHEXT/X_OK lookup cannot find the command. It never includes an agent's system prompt. Rows show declared/default capabilities and command discoverability, not authentication, version compatibility, or successful launch; launch preflight remains authoritative.
|
|
244
|
+
- `options.capabilities: true` changes `action: "list"` to compact one-line rows and adds `details.agentCapabilities: { agents, restrictedCount, capabilityCeilingSources? }`. Each agent row includes source, aliases, runner type/capabilities, tools, MCP direct tools, mutation tools, model/thinking, default async/timeout, declared acceptance policy/role, output path/mode, skills/extensions, and whether the current capability ceiling allows execution. External CLI rows include `runner.command`, `runner.available`, and a bounded `runner.unavailableReason` when passive PATH/PATHEXT/X_OK lookup cannot find the command. It never includes an agent's system prompt. Rows show declared/default capabilities and command discoverability, not authentication, version compatibility, or successful launch; launch preflight remains authoritative.
|
|
235
245
|
- `create` uses `config.scope`, not `agentScope`.
|
|
236
246
|
- `config.name` is the local frontmatter name; optional `config.package` registers the runtime name as `{package}.{name}` and is saved as separate `name` and `package` frontmatter.
|
|
237
247
|
- `config.aliases` accepts a comma-separated string, string array, or `false` to clear aliases. Aliases resolve to the canonical agent name for execution and are shown by `list`/`get`.
|
|
@@ -246,7 +256,7 @@ Rules:
|
|
|
246
256
|
|
|
247
257
|
### Schedule controls
|
|
248
258
|
|
|
249
|
-
Use `schedule.create` with `workflow: true` or a script path, not a direct child. `at` accepts a delay like `+10m` or an ISO timestamp with timezone; `every` accepts fixed intervals. `sessionOnly:true` binds restoration/execution to the creating session file; omitted/false is project-wide. Recurring `quiet:true` keeps successful automatic fires visible without a parent turn; failed, stopped or paused runs still wake the parent. One-shot `at` and manual `schedule.run` stay noisy unless that launch passes `quiet:true`. An optional `missionId` attaches an existing mission on every fire and exposes its workflow state, using ordinary mission lifecycle and retention rules; `mission.close` does not pause the schedule. See [missions and schedules](missions.md#schedules) for examples and list/show/history/pause/resume/run/run-due/delete.
|
|
259
|
+
Use `schedule.create` with `workflow: true` or a script path, not a direct child. `at` accepts a delay like `+10m` or an ISO timestamp with timezone; `every` accepts fixed intervals or `day`/`week` with `at:"HH:mm"` and an explicit IANA `timezone` (or `UTC`). Weekly `on` is a non-empty array of `mon`–`sun`; daily schedules omit it. Missing local times are skipped; repeated times fire once at their first instant. `sessionOnly:true` binds restoration/execution to the creating session file; omitted/false is project-wide. Recurring `quiet:true` keeps successful automatic fires visible without a parent turn; failed, stopped or paused runs still wake the parent. One-shot `at` and manual `schedule.run` stay noisy unless that launch passes `quiet:true`. An optional `missionId` attaches an existing mission on every fire and exposes its workflow state, using ordinary mission lifecycle and retention rules; `mission.close` does not pause the schedule. See [missions and schedules](missions.md#schedules) for examples and list/show/history/pause/resume/run/run-due/delete. `baseRef` resolves only at worktree allocation and still requires a clean source checkout.
|
|
250
260
|
|
|
251
261
|
## Lane merge evidence and cleanup eligibility
|
|
252
262
|
|
|
@@ -255,29 +265,33 @@ Lane evidence actions update an existing parallel handoff manifest at an explici
|
|
|
255
265
|
```ts
|
|
256
266
|
subagent({
|
|
257
267
|
action: "lane.recordMerge",
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
+
options: {
|
|
269
|
+
laneId: "<manifest-run-id>",
|
|
270
|
+
handoffPath: "/path/to/handoff.json",
|
|
271
|
+
merge: {
|
|
272
|
+
prNumber: 123,
|
|
273
|
+
reviewedHead: "<40-character-sha>",
|
|
274
|
+
mergeCommit: "<40-character-sha>",
|
|
275
|
+
treeEquivalent: true,
|
|
276
|
+
postMergeChecks: "recorded",
|
|
277
|
+
attestedBy: "operator",
|
|
278
|
+
attestedAt: "2026-08-27T16:23:00.000Z"
|
|
279
|
+
}
|
|
268
280
|
}
|
|
269
281
|
})
|
|
270
282
|
subagent({
|
|
271
283
|
action: "lane.recordSupersession",
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
284
|
+
options: {
|
|
285
|
+
laneId: "<manifest-run-id>",
|
|
286
|
+
handoffPath: "/path/to/handoff.json",
|
|
287
|
+
supersession: {
|
|
288
|
+
supersededBy: "<replacement-lane-id>",
|
|
289
|
+
attestedBy: "operator",
|
|
290
|
+
attestedAt: "2026-08-27T16:23:00.000Z"
|
|
291
|
+
}
|
|
278
292
|
}
|
|
279
293
|
})
|
|
280
|
-
subagent({ action: "lane.status", laneId: "<manifest-run-id>", handoffPath: "/path/to/handoff.json" })
|
|
294
|
+
subagent({ action: "lane.status", options: { laneId: "<manifest-run-id>", handoffPath: "/path/to/handoff.json" } })
|
|
281
295
|
```
|
|
282
296
|
|
|
283
297
|
The manifest stores one of these fail-closed eligibility states: `active` (an owning child is still running), `terminal-eligible` (complete merge evidence and recorded post-merge checks), `terminal-blocked` with a reason, `superseded-eligible` (an explicit replacement attestation), or `unknown` (missing or malformed evidence/manifest). Each attestation stores a digest of the manifest facts it covered; later group, worktree, or patch changes downgrade that evidence to `terminal-blocked` until it is recorded again. A terminal update recomputes a previously stored `active` state from the current child statuses and evidence. Conflicting reviewed heads and mismatched lane ids are rejected as stale. Existing workflow receipts remain immutable.
|
|
@@ -294,19 +308,19 @@ For backlog lanes and other subagent-governed workflows, external/foreground/CLI
|
|
|
294
308
|
|
|
295
309
|
```ts
|
|
296
310
|
subagent({ action: "status" })
|
|
297
|
-
subagent({ action: "status", view: "fleet" })
|
|
311
|
+
subagent({ action: "status", options: { view: "fleet" } })
|
|
298
312
|
subagent({ action: "status", id: "<run-id>" })
|
|
299
|
-
subagent({ action: "status", id: "<run-id>", view: "transcript", index: 0, lines: 80 })
|
|
313
|
+
subagent({ action: "status", id: "<run-id>", options: { view: "transcript", index: 0, lines: 80 } })
|
|
300
314
|
subagent({ action: "status", id: "<nested-run-id>" })
|
|
301
315
|
subagent({ action: "interrupt", id: "<run-id>" })
|
|
302
316
|
subagent({ action: "interrupt", id: "<nested-run-id>" })
|
|
303
317
|
subagent({ action: "stop", id: "<run-id>" })
|
|
304
318
|
subagent({ action: "resume", id: "<run-id>", message: "follow-up question after it pauses or finishes" })
|
|
305
|
-
subagent({ action: "resume", id: "<run-id>",
|
|
319
|
+
subagent({ action: "resume", id: "<run-id>", message: "follow-up for child 2", options: { index: 1 } })
|
|
306
320
|
subagent({ action: "resume", id: "<nested-run-id>", message: "follow-up for a nested child" })
|
|
307
321
|
subagent({ action: "steer", id: "<run-id>", message: "guidance for the running child" })
|
|
308
|
-
subagent({ action: "steer", id: "<run-id>",
|
|
309
|
-
subagent({ action: "steer", id: "<run-id>",
|
|
322
|
+
subagent({ action: "steer", id: "<run-id>", message: "check this after the current turn", options: { mode: "follow_up" } })
|
|
323
|
+
subagent({ action: "steer", id: "<run-id>", message: "guidance for child 2", options: { index: 1, mode: "auto" } })
|
|
310
324
|
subagent({ action: "doctor" })
|
|
311
325
|
```
|
|
312
326
|
|
|
@@ -325,10 +339,10 @@ subagent({ action: "doctor" })
|
|
|
325
339
|
Command controls target direct local native Pi children that explicitly select both `bash` and `subagent_command`, in foreground or async runs. They require the owning parent session, a run `id`, an explicit `index` for multi-child runs, and the exact `toolCallId` for mutations. Nested, external, and custom shell backends do not expose this controller. Custom bash extensions keep their own registered `subagent_command` tool. If a custom bash backend does not provide that tool, an explicitly required `subagent_command` remains available and reports an unsupported-backend error. Native supervisor command controls are unavailable for custom backends.
|
|
326
340
|
|
|
327
341
|
```ts
|
|
328
|
-
subagent({ action: "command.status", id: "<run-id>", index: 0 })
|
|
329
|
-
subagent({ action: "command.yield", id: "<run-id>", index: 0, toolCallId: "<call-id>" })
|
|
330
|
-
subagent({ action: "command.cancel", id: "<run-id>", index: 0, toolCallId: "<call-id>" })
|
|
331
|
-
subagent({ action: "command.status", id: "<run-id>", index: 0, toolCallId: "<call-id>" })
|
|
342
|
+
subagent({ action: "command.status", id: "<run-id>", options: { index: 0 } })
|
|
343
|
+
subagent({ action: "command.yield", id: "<run-id>", options: { index: 0, toolCallId: "<call-id>" } })
|
|
344
|
+
subagent({ action: "command.cancel", id: "<run-id>", options: { index: 0, toolCallId: "<call-id>" } })
|
|
345
|
+
subagent({ action: "command.status", id: "<run-id>", options: { index: 0, toolCallId: "<call-id>" } })
|
|
332
346
|
```
|
|
333
347
|
|
|
334
348
|
`command.yield` releases the selected blocking tool call without restarting the process. `command.cancel` aborts only that command through Pi's native bash cancellation; the child receives a tool error and can continue. `cancel_requested` acknowledges the request, while `cancelled` confirms the backend settled. A stale id never targets a later command. Run-scoped `interrupt` remains separate.
|
|
@@ -391,15 +405,19 @@ Prefer an inline JSON object. JSON-encoded object strings are tolerated only dur
|
|
|
391
405
|
{
|
|
392
406
|
agent: "worker",
|
|
393
407
|
task: "Implement the fix",
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
408
|
+
options: {
|
|
409
|
+
acceptance: {
|
|
410
|
+
level: "verified",
|
|
411
|
+
criteria: ["Patch the bug without widening scope"],
|
|
412
|
+
evidence: ["changed-files", "tests-added", "commands-run", "residual-risks", "no-staged-files"],
|
|
413
|
+
verify: [{ id: "focused", command: "npm test", timeoutMs: 120000 }]
|
|
414
|
+
}
|
|
399
415
|
}
|
|
400
416
|
}
|
|
401
417
|
```
|
|
402
418
|
|
|
419
|
+
A direct tool call passes `acceptance` inside `options`; a workflow `runs.run` item passes it as a plain field.
|
|
420
|
+
|
|
403
421
|
### One-command gates
|
|
404
422
|
|
|
405
423
|
When one host-run command is the entire verification contract, use the `gate` shorthand instead of a full `acceptance` object:
|
|
@@ -519,7 +537,22 @@ return runs.run("main", { agent: "scout", task: "..." });
|
|
|
519
537
|
```
|
|
520
538
|
|
|
521
539
|
```js
|
|
522
|
-
subagent({ workflow: true, share: true });
|
|
540
|
+
subagent({ workflow: true, options: { share: true } });
|
|
523
541
|
```
|
|
524
542
|
|
|
525
543
|
This is disabled by default. Session data may contain source code, paths, environment variables, credentials, or other sensitive output. You need `gh` installed and authenticated.
|
|
544
|
+
|
|
545
|
+
### Reviewed worktree cleanup
|
|
546
|
+
|
|
547
|
+
`worktree.cleanup` first saves a plan without removing anything:
|
|
548
|
+
|
|
549
|
+
```ts
|
|
550
|
+
subagent({ action: "worktree.cleanup", options: { repo: "/path/to/repo", mode: "plan" } })
|
|
551
|
+
subagent({ action: "worktree.cleanup", options: { repo: "/path/to/repo", mode: "apply", planId: "<reviewed-plan-id>" } })
|
|
552
|
+
```
|
|
553
|
+
|
|
554
|
+
Apply uses the existing `authorityPolicy.discardWorktree` (`confirm` by default). It checks the saved plan's repository, hash and 30-minute expiry, then rechecks only reviewed candidates under a repository lock shared with retained resume admission. Only a clean, contained, provably owned terminal worktree with durable evidence can be removed. Dirty or untracked files, ignored files, Git locks, active ownership, recorded native session dependencies, retained resume admission, changed heads and missing artifacts keep the tree. Every local branch is retained; apply never forces removal or prunes unrelated Git metadata.
|
|
555
|
+
|
|
556
|
+
Cleanup also requires the canonical base directory recorded when the worktree was created. Older handoffs without that proof remain kept; planning never infers it from the current location. A path redirected outside its creation directory or an invalid handoff manifest prevents removal. Apply validates the full manifest under its write lock before recording a removal attempt or invoking Git.
|
|
557
|
+
|
|
558
|
+
The plan is claimed once before deletion and records progress in a durable receipt. Repeating a claimed plan displays its receipt without attempting more removals. It can repair a journaled removal's handoff fact only when that directory and Git registration are both gone; a recreated path is retained. After an interruption, inspect the receipt and create a fresh plan for additional work. Cleanup failures leave child outcomes and artifacts intact. `worktree.discard` remains the separate explicitly authorized destructive discard operation.
|
package/docs/watchdog.md
CHANGED
|
@@ -46,13 +46,15 @@ you ─▶ agent turn ─▶ edits repo ─▶ agent_end ─▶ watchdog review
|
|
|
46
46
|
└─ warning: low/medium user entry, or high steered message
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
A warning shows as one `[subagent] watchdog concern` or `[subagent] watchdog blocker` line, like every other message pi-subagents shows in the chat. Pi's expand key, or a click on the line, opens it to the summary, evidence, recommended action, importance, category, and source:
|
|
50
50
|
|
|
51
51
|
```
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
52
|
+
[subagent] watchdog blocker
|
|
53
|
+
|
|
54
|
+
Subagent watchdog Blocker (displayed): Claims tests passed without running them
|
|
55
|
+
Evidence: The transcript claims npm test passed but no test command appears in the tool log.
|
|
56
|
+
Recommended action: Run the focused test before finishing.
|
|
57
|
+
Importance: High · Category: Test Gap · Source: main
|
|
56
58
|
```
|
|
57
59
|
|
|
58
60
|
When consecutive boundary reviews raise the same warning, the agent is not making progress. After `stalemateRepeats` identical warnings in a row (default 3), the warning is shown as `stalemate`, no continuation is triggered, and the turn ends. Your next prompt resets the count.
|
|
@@ -110,7 +112,7 @@ Omit `main.model` to inherit the session model and thinking level. A `main.model
|
|
|
110
112
|
|
|
111
113
|
The watchdog resolves one reviewer model and makes one review call. Unavailable models fail visibly; rate limits, quota, authentication, provider timeouts, findings, clarification, cancellation, and the overall watchdog deadline never switch models automatically. An inherited model keeps the current session model and thinking level.
|
|
112
114
|
|
|
113
|
-
Agents can call `subagent({ action: "watchdog.recommend-model" })` and `subagent({ action: "watchdog.configure", model: "recommended", scope: "session" | "user" | "project" })`. They should use `scope: "session"` unless you ask for a lasting default.
|
|
115
|
+
Agents can call `subagent({ action: "watchdog.recommend-model" })` and `subagent({ action: "watchdog.configure", model: "recommended", options: { scope: "session" | "user" | "project" } })`. They should use `options: { scope: "session" }` unless you ask for a lasting default.
|
|
114
116
|
|
|
115
117
|
## Optional main-session clarification
|
|
116
118
|
|