@xzzpig/pi-subagents 0.14.0 → 0.15.1
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 +239 -0
- package/README.md +7 -6
- package/agents/evidence-auditor.md +34 -0
- package/agents/researcher.md +23 -13
- package/agents/reviewer.md +3 -2
- package/docs/agents.md +55 -136
- package/docs/configuration.md +92 -14
- package/docs/extension-api.md +132 -74
- package/docs/fork-extensions.md +184 -0
- package/docs/missions.md +10 -2
- package/docs/models.md +11 -22
- package/docs/observability.md +63 -11
- package/docs/standalone-background.md +59 -0
- package/docs/tool-reference.md +42 -23
- package/docs/watchdog.md +39 -10
- package/docs/workflows.md +58 -19
- package/index.ts +5 -2
- package/inspector-runner.mjs +2 -2
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +13 -3
- package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +18 -6
- package/node_modules/@xzzpig/pi-components/src/transcript.ts +26 -6
- package/package.json +9 -4
- package/prompts/parallel-review.md +1 -1
- package/runner-peer-loader.mjs +24 -0
- package/runner-peer-preload.mjs +36 -0
- package/skills/pi-subagents/SKILL.md +34 -22
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
- package/skills/pi-subagents/references/execution-controls.md +27 -8
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +17 -13
- package/skills/pi-subagents/references/review-and-validation.md +3 -3
- package/src/agents/advertised-agent-prompt.ts +94 -0
- package/src/agents/agent-eject.ts +339 -0
- package/src/agents/agent-management.ts +79 -387
- package/src/agents/agent-serializer.ts +6 -3
- package/src/agents/agents.ts +198 -72
- package/src/agents/builtin-names.ts +1 -0
- package/src/agents/chain-serializer.ts +5 -0
- package/src/agents/runtime-agent-registry.ts +7 -6
- package/src/api/agent-management.ts +2 -2
- package/src/api/delegation.ts +4 -0
- package/src/api/preflight.ts +131 -86
- package/src/api/required-child-extensions.ts +6 -0
- package/src/api/shared-types.ts +3 -1
- package/src/api/workflow-resources.ts +6 -0
- package/src/extension/config.ts +14 -37
- package/src/extension/fanout-child.ts +68 -5
- package/src/extension/herdr-pi-bridge.ts +164 -0
- package/src/extension/index.ts +141 -51
- package/src/extension/public-execution.ts +7 -6
- package/src/extension/rpc.ts +8 -21
- package/src/extension/schemas.ts +86 -84
- package/src/extension/tool-description.ts +32 -79
- package/src/inspectors/actions.ts +148 -0
- package/src/inspectors/ghostty/actions.ts +74 -0
- package/src/inspectors/ghostty/plugin.ts +17 -0
- package/src/inspectors/herdr/actions.ts +99 -179
- package/src/inspectors/herdr/plugin.ts +20 -0
- package/src/inspectors/herdr/project-panes.ts +4 -1
- package/src/inspectors/{herdr/inspector-runner.ts → inspector-runner.ts} +12 -12
- package/src/inspectors/plugins.ts +8 -0
- package/src/inspectors/{herdr/session-roots-codec.ts → session-roots-codec.ts} +3 -14
- package/src/inspectors/types.ts +51 -0
- package/src/integrations/pi-web-session-liveness.ts +73 -0
- package/src/intercom/intercom-bridge.ts +50 -8
- package/src/intercom/native-supervisor-channel.ts +142 -115
- package/src/intercom/supervisor-ui.ts +3 -2
- package/src/missions/workflow-state.ts +37 -16
- package/src/policy/authority.ts +4 -0
- package/src/profiles/profiles.ts +12 -6
- package/src/runs/background/active-async-capacity.ts +22 -18
- package/src/runs/background/active-run-index.ts +17 -1
- package/src/runs/background/async-execution.ts +359 -176
- package/src/runs/background/async-job-tracker.ts +41 -7
- package/src/runs/background/async-resume.ts +19 -12
- package/src/runs/background/async-retention.ts +20 -0
- package/src/runs/background/async-status-snapshot.ts +10 -12
- package/src/runs/background/async-status.ts +38 -35
- package/src/runs/background/auto-drain.ts +59 -35
- package/src/runs/background/binary-bootstrap.ts +38 -0
- package/src/runs/background/chain-append.ts +1 -1
- package/src/runs/background/chain-root-attachment.ts +22 -33
- package/src/runs/background/control-channel.ts +78 -44
- package/src/runs/background/fleet-view.ts +30 -2
- package/src/runs/background/notify.ts +193 -19
- package/src/runs/background/owned-process-tree.ts +35 -8
- package/src/runs/background/process-terminal.ts +23 -23
- package/src/runs/background/result-files.ts +8 -4
- package/src/runs/background/result-watcher.ts +19 -2
- package/src/runs/background/retained-nested-route-tracker.ts +96 -0
- package/src/runs/background/run-child-session.ts +118 -41
- package/src/runs/background/run-status.ts +78 -5
- package/src/runs/background/runner-aliases.ts +22 -5
- package/src/runs/background/runner-child-launch.ts +93 -0
- package/src/runs/background/runner-child-sessions.ts +5 -4
- package/src/runs/background/runner-http-dispatcher.ts +119 -0
- package/src/runs/background/scheduled-runs.ts +51 -18
- package/src/runs/background/stale-run-reconciler.ts +38 -12
- package/src/runs/background/steering.ts +20 -2
- package/src/runs/background/subagent-runner.ts +770 -444
- package/src/runs/background/subagent-wait.ts +179 -28
- package/src/runs/background/wait-completions.ts +79 -27
- package/src/runs/background/wait-subscriptions.ts +9 -3
- package/src/runs/background/wait-tool.ts +5 -3
- package/src/runs/foreground/async-steering-action.ts +37 -7
- package/src/runs/foreground/async-stop-action.ts +93 -3
- package/src/runs/foreground/execution.ts +174 -194
- package/src/runs/foreground/foreground-history.ts +5 -2
- package/src/runs/foreground/prompt-audit.ts +12 -6
- package/src/runs/foreground/subagent-executor.ts +915 -411
- package/src/runs/foreground/workflow-detach-reconcile.ts +10 -5
- package/src/runs/foreground/workflow-foreground-steering.ts +57 -2
- package/src/runs/shared/acceptance.ts +54 -14
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/async-status-projection.ts +172 -78
- package/src/runs/shared/capability-ceiling.ts +2 -0
- package/src/runs/shared/child-hooks.ts +167 -3
- package/src/runs/shared/child-launch-plan.ts +15 -3
- package/src/runs/shared/child-launch.ts +49 -85
- package/src/runs/shared/child-lifecycle.ts +6 -3
- package/src/runs/shared/child-runtime-config.ts +8 -1
- package/src/runs/shared/child-session.ts +130 -24
- package/src/runs/shared/child-tool-plan.ts +149 -112
- package/src/runs/shared/completion-evidence.ts +2 -2
- package/src/runs/shared/completion-guard.ts +6 -3
- package/src/runs/shared/dynamic-fanout.ts +2 -2
- package/src/runs/shared/effective-system-prompt.ts +33 -0
- package/src/runs/shared/external-cli-contract.ts +11 -1
- package/src/runs/shared/external-cli-preflight.ts +6 -2
- package/src/runs/shared/external-cli-runner.ts +9 -7
- package/src/runs/shared/herdr-connection.ts +134 -0
- package/src/runs/shared/herdr-external-adapters.ts +169 -0
- package/src/runs/shared/herdr-machine.ts +279 -0
- package/src/runs/shared/herdr-pi-protocol.ts +59 -0
- package/src/runs/shared/herdr-placed-run.ts +263 -0
- package/src/runs/shared/host-step-status.ts +11 -11
- package/src/runs/shared/llm-intent-arbiter.ts +40 -21
- package/src/runs/shared/model-resolution-diagnostic.ts +76 -0
- package/src/runs/shared/{model-fallback.ts → model-resolution.ts} +34 -218
- package/src/runs/shared/model-scope.ts +1 -1
- package/src/runs/shared/nested-events.ts +27 -34
- package/src/runs/shared/orca-progress-tabs.ts +7 -1
- package/src/runs/shared/parallel-handoff.ts +57 -12
- package/src/runs/shared/parallel-utils.ts +10 -4
- package/src/runs/shared/pi-spawn.ts +10 -0
- package/src/runs/shared/profile-extensions.ts +134 -0
- package/src/runs/shared/profile-launch-env.ts +113 -0
- package/src/runs/shared/readonly-drain-observation.ts +42 -0
- package/src/runs/shared/run-fanout-budget.ts +8 -8
- package/src/runs/shared/runtime-acknowledged-extensions.ts +3 -3
- package/src/runs/shared/sandbox-profile-guard.ts +34 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +23 -5
- package/src/runs/shared/task-intent.ts +46 -13
- package/src/runs/shared/workflow-async-child-guidance.ts +18 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +6 -3
- package/src/runs/shared/worktree-setup-command.ts +213 -0
- package/src/runs/shared/worktree.ts +437 -214
- package/src/shared/child-cache-retention.ts +43 -0
- package/src/shared/fork-context.ts +15 -72
- package/src/shared/launch-contract.ts +70 -8
- package/src/shared/model-response-aliases.ts +13 -0
- package/src/shared/opencode-session-headers.ts +30 -0
- package/src/shared/permission-profile.ts +14 -0
- package/src/shared/pruned-fork.ts +1 -1
- package/src/shared/required-child-extensions.ts +81 -0
- package/src/shared/sandbox-profile.ts +14 -0
- package/src/shared/settings.ts +5 -2
- package/src/shared/shortcuts.ts +0 -4
- package/src/shared/types.ts +163 -90
- package/src/shared/utils.ts +10 -2
- package/src/shared/watch-strategy.ts +2 -0
- package/src/shared/workflow-child-permit.ts +18 -13
- package/src/slash/delegation-adapters.ts +3 -1
- package/src/slash/delegation-request.ts +14 -0
- package/src/slash/slash-commands.ts +2 -7
- package/src/slash/subagents-admin.ts +31 -14
- package/src/tui/fleet-status.ts +165 -20
- package/src/tui/fleet.ts +30 -19
- package/src/tui/render.ts +210 -50
- package/src/watchdog/child-status.ts +28 -28
- package/src/watchdog/lsp-diagnostics.ts +1 -1
- package/src/watchdog/model-selection.ts +21 -1
- package/src/watchdog/permission-arbiter.ts +5 -2
- package/src/watchdog/register-child.ts +10 -2
- package/src/watchdog/register-main.ts +39 -35
- package/src/watchdog/render.ts +1 -1
- package/src/watchdog/review.ts +122 -74
- package/src/watchdog/rules.ts +1 -1
- package/src/watchdog/runtime.ts +100 -27
- package/src/watchdog/scope.ts +1 -1
- package/src/watchdog/settings.ts +3 -0
- package/src/watchdog/tool-actions.ts +13 -12
- package/src/watchdog/turn-delta.ts +23 -0
- package/src/watchdog/types.ts +5 -3
- package/src/watchdog/warning-format.ts +1 -1
- package/src/workflows/chat-progress.ts +3 -3
- package/src/workflows/scripted-workflow.ts +349 -26
- package/src/workflows/workflow-checklist.ts +17 -20
- package/src/workflows/workflow-child-summary.ts +57 -8
- package/src/workflows/workflow-preflight.ts +19 -19
- package/src/workflows/workflow-receipt.ts +24 -6
- package/src/workflows/workflow-resources.ts +108 -22
- package/src/workflows/workflow-settlement.ts +3 -0
- package/src/runs/shared/model-exclusions.ts +0 -373
- /package/src/inspectors/{herdr/shell-command.ts → shell-command.ts} +0 -0
|
@@ -24,7 +24,7 @@ Project settings resolve from the nearest parent directory containing `.pi` or `
|
|
|
24
24
|
|
|
25
25
|
An agent may set `runner.type: external-cli` with a non-empty `command`, optional string `args`, and `promptDelivery: stdin` (the default). The command runs with `shell: false`, inherits the resolved cwd and environment, and receives the combined agent instructions and task through stdin. It must already be installed; pi-subagents adds no CLI dependency.
|
|
26
26
|
|
|
27
|
-
External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents,
|
|
27
|
+
External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents, and sessions are also unsupported.
|
|
28
28
|
|
|
29
29
|
### External job profiles
|
|
30
30
|
|
|
@@ -32,7 +32,7 @@ An agent may set `runner.type: external-job` with a non-empty `provider` and opt
|
|
|
32
32
|
|
|
33
33
|
External job profiles are async-only. The provider owns the remote job and Pi owns the async run record. Status persists provider name, provider job id, prompt digest, provider options, handle/conversation URLs when supplied, result artifact path, last known state, and provider failure code/message. Recovery uses existing provider job metadata to call `reattach` and `result`; it refuses to redispatch a prompt when the persisted provider job does not match the prompt digest.
|
|
34
34
|
|
|
35
|
-
External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions,
|
|
35
|
+
External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, or Pi child sessions. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
|
|
36
36
|
|
|
37
37
|
### Single agent
|
|
38
38
|
|
|
@@ -83,10 +83,10 @@ lanes, or a fanout that the parent will consume together.
|
|
|
83
83
|
```js
|
|
84
84
|
subagent({
|
|
85
85
|
workflowScript: `
|
|
86
|
-
const scan = await runs.run("scan", { agent: "scout", task: "Map the target" });
|
|
86
|
+
const scan = await runs.run("scan", { label: "Map target behavior", agent: "scout", task: "Map the target" });
|
|
87
87
|
const reviews = await runs.all([
|
|
88
|
-
{ key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
89
|
-
{ key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
88
|
+
{ key: "correctness", label: "Review target correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
89
|
+
{ key: "tests", label: "Review target test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
90
90
|
]);
|
|
91
91
|
return reviews.map(result => result.output);
|
|
92
92
|
`
|
|
@@ -109,6 +109,7 @@ Terminal async workflows also persist `workflow-receipt.json` beside `status.jso
|
|
|
109
109
|
|
|
110
110
|
```js
|
|
111
111
|
return runs.run("cross-oracle", {
|
|
112
|
+
label: "Challenge proposed direction",
|
|
112
113
|
resume: { workflowRunId: "<pass-1-workflow-id>", key: "advisor-oracle", latest: true },
|
|
113
114
|
task: "Review the focused challenge packet."
|
|
114
115
|
});
|
|
@@ -120,7 +121,8 @@ Keyed resume reads that one exact receipt and revalidates the retained run at la
|
|
|
120
121
|
|
|
121
122
|
For a broad plan with a known set of narrow, visible stages per lane, use
|
|
122
123
|
`runs.lanes(...)` inside a `workflowScript`; it is a nested helper, not a
|
|
123
|
-
top-level `subagent` mode. Give each lane and stage a stable key
|
|
124
|
+
top-level `subagent` mode. Give each lane and stage a stable key; give stage
|
|
125
|
+
items a short verb + behavior `label`, preserving explicit user labels. The first
|
|
124
126
|
stage from every lane is launched together, then later stages sequence per lane.
|
|
125
127
|
`resume: "previous"` requires the retained predecessor, and a failed or blocked
|
|
126
128
|
stage blocks only that lane. The returned board exposes lane/stage results for
|
|
@@ -246,15 +248,19 @@ Use diagnostics when setup or child startup looks wrong:
|
|
|
246
248
|
subagent({ action: "doctor" })
|
|
247
249
|
```
|
|
248
250
|
|
|
251
|
+
### Failed lane recovery and execution-mode changes
|
|
252
|
+
|
|
253
|
+
A failure in the subagent workflow, child launch, prompt runtime, extension loading, or child tooling setup is a lane infrastructure blocker, not permission to silently change execution mode. Stop and report the exact failure, run/status, and repo/cwd/worktree/branch/ref state. Retry or fix the `subagent` path only through a clear same-protocol retry; before retrying or asking the owner, verify the worktree is clean or capture the partial diff. For backlog lanes and other subagent-governed workflows, switching to `interactive_shell`, `pi -ne`, Codex/Claude/Cursor CLI, a foreground agent, or another external mode requires explicit owner approval. Pi core may print a generic `pi -ne` extension-load hint; that hint is outside this package and is not protocol-approved. A verified compaction abort may continue the retained child session once on the same resolved model; provider failures never select another model automatically.
|
|
254
|
+
|
|
249
255
|
### External terminal work
|
|
250
256
|
|
|
251
|
-
Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts,
|
|
257
|
+
Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts, or recovery only when the user explicitly requests that mode or the task is outside the governed subagent protocol; it is not an implicit replacement for a failed `subagent` lane.
|
|
252
258
|
|
|
253
259
|
A cooperating terminal runtime can register read-only external records through `@xzzpig/pi-subagents/external-runs`. Records include the source, session, state, optional report path, and completion reason. They are observations only: pi-subagents does not start, stop, steer, or otherwise own the foreign process. Run unattended raw terminal agents in an explicit isolated cwd or worktree; do not use a live project checkout as disposable review space.
|
|
254
260
|
|
|
255
261
|
### Scheduled subagent runs
|
|
256
262
|
|
|
257
|
-
Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
|
|
263
|
+
Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for. To keep schedules outside the project repository, set `{ "scheduledRuns": { "storeRoot": "~/.pi/subagent-schedules" } }` in the same config: `storeRoot` accepts an absolute path or a `~/`-prefixed path, and records land under `<storeRoot>/<sha256(path.resolve(cwd)) first 20 hex>/<scheduleId>/`.
|
|
258
264
|
|
|
259
265
|
```typescript
|
|
260
266
|
// One-shot reviewer
|
|
@@ -323,6 +329,19 @@ subagent({ action: "steer", id: "abc123", message: "Focus on the failing test."
|
|
|
323
329
|
|
|
324
330
|
The action waits up to three seconds for the child Pi session to accept the correlated user input and returns a request id with `delivered`, `scheduled`, `pending`, `partial`, `recovered`, or `failed` plus per-child states. Indexed pending children return `scheduled` immediately. Only a top-level single-child run may automatically interrupt after a missed acknowledgment and recover after confirmed pause within a further 15 seconds. Recovery preserves the original child contract and only its remaining deadline, turn, and tool budgets. If the session is missing, a budget is exhausted, the pause cannot be confirmed, or replacement launch fails, the source remains paused when pausing succeeded and the action returns the exact failure. Chain, parallel, and nested runs never auto-interrupt; inspect their per-child outcomes and handle failures explicitly. A late acknowledgment is recorded and cannot cancel committed recovery.
|
|
325
331
|
|
|
332
|
+
Steering supports three delivery modes via the `mode` parameter (`steer` is the default):
|
|
333
|
+
|
|
334
|
+
- `mode: "steer"` — interrupt the child at the next safe point of its current turn and deliver the message.
|
|
335
|
+
- `mode: "follow_up"` — do not interrupt; queue input through Pi's native follow-up path for the next turn boundary. Eligible completed retained workflow children (single-step runs in state `complete` with a stored session file) receive the message as a revival brief (`queueRevivalBrief`) when they are revived; paused children reject follow-up steering outright. The 20-message queue limit applies to retained revival briefs, not live follow-up input.
|
|
336
|
+
- `mode: "auto"` — same next-safe-point delivery path as `steer`, but without the automatic pause-and-revive recovery after a missed acknowledgment.
|
|
337
|
+
|
|
338
|
+
```typescript
|
|
339
|
+
subagent({ action: "steer", id: "abc123", mode: "follow_up", message: "After this step, also validate the config file." })
|
|
340
|
+
subagent({ action: "steer", id: "abc123", mode: "auto", message: "Switch to the failing test now." })
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
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.
|
|
344
|
+
|
|
326
345
|
## Watchdog
|
|
327
346
|
|
|
328
347
|
The subagent watchdog is an **opt-in** adversarial change reviewer. It is not the
|
|
@@ -96,6 +96,7 @@ A minimal agent file looks like this:
|
|
|
96
96
|
name: my-agent
|
|
97
97
|
package: code-analysis
|
|
98
98
|
description: What this agent does
|
|
99
|
+
advertise: true
|
|
99
100
|
aliases: developer, coder
|
|
100
101
|
model: provider/model-id
|
|
101
102
|
thinking: high
|
|
@@ -111,12 +112,11 @@ skillPath: ./skills, ../shared-skills
|
|
|
111
112
|
Your system prompt here.
|
|
112
113
|
```
|
|
113
114
|
|
|
114
|
-
That is only a starting point. Omit `package` for the traditional unqualified runtime name. Common optional fields include:
|
|
115
|
+
That is only a starting point. Omit `package` for the traditional unqualified runtime name. Set `advertise: true` only when the parent should receive this agent's name and description before deciding whether to delegate; advertisement is off by default. Common optional fields include:
|
|
115
116
|
- `defaultProgress`
|
|
116
117
|
- `defaultReads`
|
|
117
118
|
- `output`
|
|
118
119
|
- `aliases`
|
|
119
|
-
- `fallbackModels`
|
|
120
120
|
- `subagentOnlyExtensions`
|
|
121
121
|
- `skills`
|
|
122
122
|
- `skillPath`
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
|
|
4
4
|
|
|
5
|
-
Create lanes only
|
|
5
|
+
Create lanes only after delegation is operator-authorized and each lane materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. Do not manufacture parallelism: keep dependent work serial, and only split work when each lane has a distinct decision and useful output.
|
|
6
6
|
|
|
7
7
|
## Lane board and authority
|
|
8
8
|
|
|
@@ -46,6 +46,8 @@ After a writer produces a candidate, run the required fresh-context, read-only r
|
|
|
46
46
|
|
|
47
47
|
Use stable lane-qualified artifact paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths. Copy only the final evidence to memory, a mission record, or a PR/comment, then remove scratch files from the active worktree before closing the lane.
|
|
48
48
|
|
|
49
|
+
For backlog lanes and other subagent-governed workflows, a setup/runtime/tooling failure remains an infrastructure blocker. Preserve the exact failure, run/status, and repository/cwd/worktree/branch/ref state; verify a clean worktree or capture any partial diff before a same-protocol retry or asking the owner. Do not start another writer or switch to an external, foreground, or CLI execution mode without explicit owner approval.
|
|
50
|
+
|
|
49
51
|
Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
|
|
50
52
|
|
|
51
53
|
Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.
|
|
@@ -8,12 +8,17 @@ Parent extensions may register a session-scoped, out-of-band ceiling through `@x
|
|
|
8
8
|
|
|
9
9
|
## When to Use
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
All launch guidance below assumes delegation was requested by the operator in
|
|
12
|
+
the current request or applicable user/project instructions. Complexity,
|
|
13
|
+
workflow fit, and potential quality gains help choose a shape after that gate;
|
|
14
|
+
they do not authorize a launch.
|
|
15
|
+
|
|
16
|
+
- **Complex work orchestration**: after delegation is authorized, keep the parent on its ordinary strong default model and launch only when a bounded child materially improves evidence, independent review, specialization, useful parallelism, or isolated execution. For hard orchestration or root-cause questions, use a top-reasoning model only as a bounded read-only critic/oracle escalation, never as an autonomous root. Lightweight one-off delegation can stay lightweight.
|
|
12
17
|
- **Advisory review**: use fresh-context `reviewer` agents for adversarial code review; fork to `oracle` only for rare escalation where inherited decisions, drift, model routing, root cause, or hard tradeoffs matter
|
|
13
18
|
- **Implementation handoff**: have `oracle` advise, then `worker` implement only after an approved direction
|
|
14
19
|
- **Recon and planning**: use `scout`, then write a plan when needed
|
|
15
20
|
- **Parallel exploration**: run multiple non-conflicting tasks concurrently
|
|
16
|
-
- **Regular skill specialists**: when
|
|
21
|
+
- **Regular skill specialists**: when authorized delegation names or benefits from a relevant specialization, discovery suggestions may help select a small fresh-context fanout
|
|
17
22
|
- **Long-running work**: launch async/background runs and inspect them later. For mutation-capable work, bound the delivery slice and elapsed runtime, then request checkpoints after active tool work returns. Reserve hard tool-call caps for explicitly read-only children.
|
|
18
23
|
- **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
|
|
19
24
|
- **Agent authoring**: create, update, or override project agents. Treat saved chain records as legacy inspection or migration inputs, not as a current authoring target.
|
|
@@ -29,7 +34,7 @@ Agents use the `subagent(...)` tool for execution, management, status, and contr
|
|
|
29
34
|
- `/subagents-detach [run-id]` — detach an active foreground single-subagent run without terminating its child
|
|
30
35
|
- `/subagents-steer <run-id> [--child <child-id>] <message>` — steer a live async run (or one child of it) from non-TUI sessions and RPC hosts
|
|
31
36
|
- `/subagent-cost` — show parent plus child token usage and cost for the session
|
|
32
|
-
- `/subagents-fleet` — open the live fleet inspector with per-child controls;
|
|
37
|
+
- `/subagents-fleet` — open the live fleet inspector with per-child controls; `↑↓`/`jk` selects children, `PgUp`/`PgDn` scrolls transcript detail, `s` steers the selected live async child, and `D` stops its top-level async run after confirmation
|
|
33
38
|
- `/subagents-watchdog` — inspect or configure the opt-in adversarial change watchdog (model, on/off, recommend-model, check)
|
|
34
39
|
- `/subagents-doctor` — diagnose setup, discovery, async paths, and intercom bridge state
|
|
35
40
|
- `/subagents-models [agent]` — show the live runtime-loaded builtin model mapping
|
|
@@ -39,7 +44,7 @@ Agents use the `subagent(...)` tool for execution, management, status, and contr
|
|
|
39
44
|
Prefer the tool when you are writing agent logic. Prefer the slash commands when
|
|
40
45
|
you are guiding a human through an interactive flow.
|
|
41
46
|
|
|
42
|
-
Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes,
|
|
47
|
+
Packaged prompt shortcuts are also available for repeatable workflows. Treat them as reusable orchestration recipes, not just human slash commands. When the user asks for one of these shapes, apply the same pattern directly with `subagent(...)` and other tools:
|
|
43
48
|
- `/parallel-review` — fresh-context reviewers with distinct review angles, then synthesis
|
|
44
49
|
- `/review-loop` — parent-orchestrated worker, fresh-reviewer, and fix-worker cycles until clean or capped
|
|
45
50
|
- `/parallel-research` — combine `researcher` and `scout` for external evidence plus local code context
|
|
@@ -53,7 +58,7 @@ The prompt templates in `prompts/` encode workflows the parent agent can run on
|
|
|
53
58
|
|
|
54
59
|
### Commission-risk and cold-start packets
|
|
55
60
|
|
|
56
|
-
|
|
61
|
+
After the operator-authority gate above, delegate only when the child materially improves evidence, independent review, specialization, useful parallelism, or isolated execution; do not manufacture parallelism. Every child packet must be cold-start complete: state the goal, exact target/cwd/ref, authority and edit boundary, relevant context/evidence, success criteria, validation, output, and stop/escalation rules. For an orchestration audit by the critic tier, make the child read-only and request at most three omissions, each cited to a file, line, or decision; high thinking is an explicit escalation, not a default.
|
|
57
62
|
|
|
58
63
|
### Council Mode technique
|
|
59
64
|
|
|
@@ -63,11 +68,11 @@ Council advisors are read-only. User or project `council-*` profiles choose allo
|
|
|
63
68
|
|
|
64
69
|
### Parallel review technique
|
|
65
70
|
|
|
66
|
-
Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. Filter on evidence, not severity: report
|
|
71
|
+
Use this when the user wants adversarial review of a diff, plan, issue, file, or implemented work. Launch fresh-context `reviewer` agents with distinct angles generated from the actual target. Common angles are correctness/regressions, tests/validation, and simplicity/maintainability; adapt for TypeScript, UI, security, docs, or large structural changes. Reviewers should inspect files and diffs directly, return concise evidence-backed findings with file/line references, and avoid edits unless the user explicitly asks for a writer pass. Filter on evidence, not severity: report concrete current issues within the named review target, with source proof, a test or repro, or a contract contradiction. For a diff review, require that the issue is caused or made reachable by that diff. Label findings P0/P1/P2 and end with `Merge verdict: BLOCK`, `Merge verdict: OK`, or `Merge verdict: OK with notes`. Use `blockers only` only for final pre-merge re-checks after P1/P2 findings are already captured, or for explicit emergency hotfix lanes where non-blocking findings are intentionally deferred. For targeted follow-up, ask only whether the named finding was resolved, whether the fix introduced a new defect in the fix blast radius, and whether prior P1/P2 notes still stand. For bot or PR-comment triage, classify each comment as VALID, STALE, INVALID, or OUT-OF-POLICY against current HEAD, then assign P0/P1/P2 only to VALID comments. The parent synthesizes fixes worth doing now, optional improvements, and feedback to ignore/defer before applying anything.
|
|
67
72
|
|
|
68
73
|
### Proactive skill-specialist technique
|
|
69
74
|
|
|
70
|
-
Use this when `{ action: "list" }` reports
|
|
75
|
+
Use this only within operator-authorized delegation when `{ action: "list" }` reports skill subagent suggestions relevant to the requested handoff. Availability is a selection hint, not authority or a command to fan out.
|
|
71
76
|
|
|
72
77
|
Default guardrails:
|
|
73
78
|
- Keep the fanout small: usually one or two skill-specialist children, never more than the listed recommendations or configured cap.
|
|
@@ -105,11 +110,11 @@ Use this when the question needs both external evidence and local implications.
|
|
|
105
110
|
|
|
106
111
|
### Gather-context-and-clarify technique
|
|
107
112
|
|
|
108
|
-
Use this
|
|
113
|
+
Use this when the operator requests delegated context gathering. Launch `scout` for local context and `researcher` only when external docs, recent sources, ecosystem context, or primary evidence would materially improve understanding. Ask children for concise findings plus remaining clarification questions. Then synthesize what is known and use `interview` to ask the unresolved questions needed for shared understanding before planning or implementing.
|
|
109
114
|
|
|
110
115
|
### Parallel cleanup technique
|
|
111
116
|
|
|
112
|
-
Use this after implementation when the user
|
|
117
|
+
Use this after implementation when the user or applicable instructions request delegated cleanup review. Launch two fresh-context `reviewer` tasks with `output: false` and `progress: false`: one deslop pass and one verbosity pass. If the `deslop` or `verbosity-cleaner` skills are available, pass the relevant skill to that reviewer; otherwise inline the criteria. Both reviewers are review-only and should flag concrete issues with severity, file/line references, and smallest safe fixes. Phrase the constraint as “Do not modify project/source files; returning findings through the configured output artifact is allowed” when you use `output` or `outputMode: "file-only"`. The parent decides what to apply and asks before making changes unless cleanup was already authorized.
|
|
113
118
|
|
|
114
119
|
### Staged fix orchestration technique
|
|
115
120
|
|
|
@@ -203,7 +208,7 @@ For one run, use inline config:
|
|
|
203
208
|
|
|
204
209
|
For persistent tweaks, edit `subagents.agentOverrides` in user or project settings. User overrides apply everywhere. Project overrides apply only in that repo and win over user overrides. Use `/subagents-models` or `subagent({ action: "models" })` to inspect the live mapping after settings and overrides load.
|
|
205
210
|
|
|
206
|
-
Provider-scoped entries can layer on top of the default override for the active parent session provider. The provider is selected once from the parent model
|
|
211
|
+
Provider-scoped entries can layer on top of the default override for the active parent session provider. The provider is selected once from the parent model. Within each settings file, the provider entry wins per field; project settings still win over user settings.
|
|
207
212
|
|
|
208
213
|
```json
|
|
209
214
|
{
|
|
@@ -261,7 +266,6 @@ Direct settings example:
|
|
|
261
266
|
"reviewer": {
|
|
262
267
|
"model": "provider/strong-review-model",
|
|
263
268
|
"thinking": "high",
|
|
264
|
-
"fallbackModels": ["backup-provider/strong-review-model"],
|
|
265
269
|
"acceptanceRole": "read-only"
|
|
266
270
|
}
|
|
267
271
|
}
|
|
@@ -269,7 +273,7 @@ Direct settings example:
|
|
|
269
273
|
}
|
|
270
274
|
```
|
|
271
275
|
|
|
272
|
-
Useful override fields: `description`, `model`, `
|
|
276
|
+
Useful override fields: `description`, `model`, `thinking`,
|
|
273
277
|
`systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`,
|
|
274
278
|
`acceptanceRole`, `disabled`, `skills`, `tools`, `extensions`, and `systemPrompt`.
|
|
275
279
|
`description` replaces the discovered description for builtin and custom agents
|
|
@@ -283,7 +287,7 @@ Keep the parent/orchestrator on the ordinary strong default model because omissi
|
|
|
283
287
|
|
|
284
288
|
Examples are illustrative, not requirements. Map these tiers to concrete models in user/project settings or a profile. A non-OpenAI setup should choose comparable available models by capability.
|
|
285
289
|
|
|
286
|
-
|
|
290
|
+
Each child launch uses one resolved model exactly once. If quota or availability fails, surface that failure and let the parent or operator explicitly launch a later attempt with another model. Forked children keep their requested thinking level even when provider-specific reasoning blocks are stripped from the inherited transcript.
|
|
287
291
|
|
|
288
292
|
If a provider rejects model IDs with thinking suffixes, use
|
|
289
293
|
`subagents.disableThinking: true` in user or project settings to clear bundled
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Pi Subagents: Review And Validation
|
|
2
2
|
|
|
3
|
-
Generic review and delivery guidance for delegated work. This file does not encode private backlog, merge, or release policy.
|
|
3
|
+
Generic review and delivery guidance for operator-authorized delegated work. This file does not encode private backlog, merge, or release policy.
|
|
4
4
|
|
|
5
5
|
## Delivery loop
|
|
6
6
|
|
|
@@ -9,7 +9,7 @@ Use the smallest loop that proves the change:
|
|
|
9
9
|
1. Inspect the source, diff, issue, or plan directly.
|
|
10
10
|
2. Keep one writer for each cwd or worktree.
|
|
11
11
|
3. Run focused validation that can fail for the changed behavior.
|
|
12
|
-
4.
|
|
12
|
+
4. When the operator/project delegation contract calls for independent review, use a fresh-context read-only reviewer; otherwise parent inspection is valid.
|
|
13
13
|
5. Apply only accepted findings inside the same writer boundary.
|
|
14
14
|
6. Re-run affected validation and review only the changed blast radius.
|
|
15
15
|
7. Inspect the final diff and evidence before parent acceptance.
|
|
@@ -61,7 +61,7 @@ Before reporting delegated work as done, verify the relevant subset:
|
|
|
61
61
|
|
|
62
62
|
- final diff contains only intended files
|
|
63
63
|
- focused validation covers changed behavior
|
|
64
|
-
-
|
|
64
|
+
- required independent review has fresh-review evidence
|
|
65
65
|
- accepted findings are fixed and revalidated
|
|
66
66
|
- publication authority exists before push, comment, close, merge, deploy, or release
|
|
67
67
|
- external checks are exact-head when used as evidence
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { Buffer } from "node:buffer";
|
|
2
|
+
import type { ResolvedSubagentCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
|
|
3
|
+
import { isAgentAllowedByCapabilityCeiling } from "../runs/shared/capability-ceiling.ts";
|
|
4
|
+
import type { AgentConfig } from "./agents.ts";
|
|
5
|
+
|
|
6
|
+
const MAX_ADVERTISED_AGENTS = 16;
|
|
7
|
+
const MAX_CATALOG_BYTES = 12_288;
|
|
8
|
+
const MAX_DESCRIPTION_BYTES = 512;
|
|
9
|
+
const ADVERTISED_AGENTS_BLOCK = /\n*<advertised_subagents>\n[\s\S]*?\n<\/advertised_subagents>/gu;
|
|
10
|
+
|
|
11
|
+
function escapeXml(value: string): string {
|
|
12
|
+
return value
|
|
13
|
+
.replaceAll("&", "&")
|
|
14
|
+
.replaceAll("<", "<")
|
|
15
|
+
.replaceAll(">", ">")
|
|
16
|
+
.replaceAll('"', """)
|
|
17
|
+
.replaceAll("'", "'");
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
function promptDescription(description: string): string {
|
|
21
|
+
let text = description.replace(/[\u0000-\u001f\u007f]+/gu, " ").replace(/\s+/gu, " ").trim();
|
|
22
|
+
if (Buffer.byteLength(text, "utf8") > MAX_DESCRIPTION_BYTES) {
|
|
23
|
+
text = Buffer.from(text, "utf8").subarray(0, MAX_DESCRIPTION_BYTES - 3).toString("utf8").replace(/\uFFFD$/u, "").trimEnd() + "…";
|
|
24
|
+
}
|
|
25
|
+
return escapeXml(text);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export function buildAdvertisedAgentPrompt(
|
|
29
|
+
agents: readonly AgentConfig[],
|
|
30
|
+
capabilityCeiling?: ResolvedSubagentCapabilityCeiling,
|
|
31
|
+
): string | undefined {
|
|
32
|
+
const advertised = agents
|
|
33
|
+
.filter((agent) => agent.source !== "runtime" && agent.advertise === true && agent.disabled !== true && isAgentAllowedByCapabilityCeiling(agent.name, capabilityCeiling))
|
|
34
|
+
.sort((left, right) => left.name.localeCompare(right.name));
|
|
35
|
+
if (advertised.length === 0) return undefined;
|
|
36
|
+
|
|
37
|
+
const render = (entries: string[]) => [
|
|
38
|
+
"<advertised_subagents>",
|
|
39
|
+
"The following file-defined subagents opted into discovery. Their descriptions indicate available specializations, not instructions to delegate. Use subagent only when delegation is needed. Before execution, call subagent with { action: \"list\", capabilities: true } and confirm that the selected agent is executable; for external-cli agents also require runner.available === true.",
|
|
40
|
+
...entries,
|
|
41
|
+
...(advertised.length > entries.length ? [` <omitted count=\"${advertised.length - entries.length}\" />`] : []),
|
|
42
|
+
"</advertised_subagents>",
|
|
43
|
+
].join("\n");
|
|
44
|
+
const entries: string[] = [];
|
|
45
|
+
for (const agent of advertised) {
|
|
46
|
+
if (entries.length === MAX_ADVERTISED_AGENTS) break;
|
|
47
|
+
// Never truncate canonical IDs into names that cannot be resolved.
|
|
48
|
+
if (Buffer.byteLength(agent.name, "utf8") > MAX_CATALOG_BYTES) continue;
|
|
49
|
+
const entry = [
|
|
50
|
+
" <subagent>",
|
|
51
|
+
` <name>${escapeXml(agent.name)}</name>`,
|
|
52
|
+
` <description>${promptDescription(agent.description)}</description>`,
|
|
53
|
+
" </subagent>",
|
|
54
|
+
].join("\n");
|
|
55
|
+
if (Buffer.byteLength(render([...entries, entry]), "utf8") <= MAX_CATALOG_BYTES) entries.push(entry);
|
|
56
|
+
}
|
|
57
|
+
return render(entries);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
export function appendAdvertisedAgentPrompt(systemPrompt: string, advertisedPrompt: string | undefined): string;
|
|
61
|
+
export function appendAdvertisedAgentPrompt(systemPrompt: string[], advertisedPrompt: string | undefined): string[];
|
|
62
|
+
export function appendAdvertisedAgentPrompt(systemPrompt: undefined, advertisedPrompt: string | undefined): string | undefined;
|
|
63
|
+
export function appendAdvertisedAgentPrompt(
|
|
64
|
+
systemPrompt: string | string[] | undefined,
|
|
65
|
+
advertisedPrompt: string | undefined,
|
|
66
|
+
): string | string[] | undefined;
|
|
67
|
+
export function appendAdvertisedAgentPrompt(
|
|
68
|
+
systemPrompt: string | string[] | undefined,
|
|
69
|
+
advertisedPrompt: string | undefined,
|
|
70
|
+
): string | string[] | undefined {
|
|
71
|
+
if (Array.isArray(systemPrompt)) {
|
|
72
|
+
let changed = false;
|
|
73
|
+
const cleaned = systemPrompt
|
|
74
|
+
.map((part) => {
|
|
75
|
+
if (typeof part !== "string") return part;
|
|
76
|
+
const stripped = part.replace(ADVERTISED_AGENTS_BLOCK, "");
|
|
77
|
+
if (stripped !== part) changed = true;
|
|
78
|
+
return stripped;
|
|
79
|
+
})
|
|
80
|
+
.filter((b) => typeof b === "string" && b.length > 0);
|
|
81
|
+
|
|
82
|
+
if (advertisedPrompt) {
|
|
83
|
+
return [...cleaned, advertisedPrompt];
|
|
84
|
+
}
|
|
85
|
+
return changed ? cleaned : systemPrompt;
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
if (typeof systemPrompt === "string") {
|
|
89
|
+
const base = systemPrompt.replace(ADVERTISED_AGENTS_BLOCK, "");
|
|
90
|
+
return advertisedPrompt ? (base.trim() ? `${base.trimEnd()}\n\n${advertisedPrompt}` : advertisedPrompt) : base;
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
return advertisedPrompt;
|
|
94
|
+
}
|