@xzzpig/pi-subagents 0.7.0 → 0.9.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 +456 -4
- package/README.md +3 -3
- package/agents/claude-code-writer.md +15 -0
- package/agents/claude-code.md +15 -0
- package/agents/codex-exec-writer.md +15 -0
- package/agents/codex-exec.md +15 -0
- package/agents/cursor-agent-writer.md +14 -0
- package/agents/cursor-agent.md +14 -0
- package/agents/reviewer.md +13 -3
- package/agents/scout.md +1 -1
- package/docs/agents.md +154 -42
- package/docs/configuration.md +85 -26
- package/docs/extension-api.md +81 -16
- package/docs/missions.md +2 -0
- package/docs/models.md +75 -11
- package/docs/observability.md +34 -21
- package/docs/tool-reference.md +142 -18
- package/docs/watchdog.md +92 -114
- package/docs/workflows.md +148 -4
- package/index.ts +10 -1
- package/install.mjs +1 -1
- package/package.json +7 -6
- package/prompts/council.md +19 -7
- package/prompts/parallel-review.md +5 -1
- package/prompts/review-loop.md +11 -7
- package/skills/council-mode/SKILL.md +44 -215
- package/skills/council-mode/references/pass-contracts.md +150 -0
- package/skills/pi-subagents/SKILL.md +90 -32
- package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
- package/skills/pi-subagents/references/execution-controls.md +104 -19
- package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
- package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
- package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
- package/skills/pi-subagents/references/review-and-validation.md +73 -0
- package/src/agents/agent-management.ts +471 -114
- package/src/agents/agent-refinements.ts +4 -4
- package/src/agents/agent-serializer.ts +16 -4
- package/src/agents/agents.ts +1076 -351
- package/src/agents/builtin-names.ts +6 -0
- package/src/agents/runtime-agent-events.ts +70 -0
- package/src/agents/runtime-agent-registry.ts +31 -20
- package/src/api/agents.ts +10 -5
- package/src/api/background-work.ts +12 -3
- package/src/api/capability-ceiling.ts +0 -1
- package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
- package/src/api/delegation.ts +0 -7
- package/src/api/external-job-provider.ts +10 -1
- package/src/api/external-runs.ts +67 -4
- package/src/api/preflight.ts +97 -34
- package/src/api/project-panes.ts +2 -0
- package/src/api/shared-types.ts +6 -0
- package/src/extension/config.ts +90 -0
- package/src/extension/doctor.ts +15 -13
- package/src/extension/fanout-child.ts +17 -16
- package/src/extension/index.ts +139 -41
- package/src/extension/public-execution.ts +113 -22
- package/src/extension/rpc.ts +182 -13
- package/src/extension/schemas.ts +63 -21
- package/src/extension/tool-description.ts +48 -23
- package/src/extension/tool-result.ts +19 -0
- package/src/inspectors/herdr/actions.ts +2 -1
- package/src/inspectors/herdr/client.ts +3 -3
- package/src/inspectors/herdr/focus.ts +55 -0
- package/src/inspectors/herdr/inspector-runner.ts +21 -23
- package/src/inspectors/herdr/project-panes.ts +228 -44
- package/src/inspectors/herdr/session-roots-codec.ts +42 -0
- package/src/integrations/herdr-status.ts +75 -5
- package/src/intercom/native-supervisor-channel.ts +138 -60
- package/src/intercom/result-intercom.ts +2 -0
- package/src/intercom/supervisor-ui.ts +243 -0
- package/src/profiles/profiles.ts +5 -6
- package/src/runs/background/active-async-capacity.ts +103 -18
- package/src/runs/background/async-execution.ts +492 -125
- package/src/runs/background/async-job-tracker.ts +127 -28
- package/src/runs/background/async-resume.ts +67 -29
- package/src/runs/background/async-retention.ts +21 -4
- package/src/runs/background/async-status-snapshot.ts +23 -261
- package/src/runs/background/async-status.ts +199 -14
- package/src/runs/background/auto-drain.ts +1 -1
- package/src/runs/background/chain-append.ts +8 -3
- package/src/runs/background/chain-root-attachment.ts +79 -8
- package/src/runs/background/control-channel.ts +101 -214
- package/src/runs/background/fleet-view.ts +38 -22
- package/src/runs/background/inspect-rpc.ts +8 -8
- package/src/runs/background/notify.ts +295 -8
- package/src/runs/background/process-terminal.ts +16 -0
- package/src/runs/background/result-delivery-ownership.ts +45 -0
- package/src/runs/background/result-files.ts +28 -14
- package/src/runs/background/result-watcher.ts +43 -19
- package/src/runs/background/resume-guidance.ts +2 -2
- package/src/runs/background/retained-children.ts +1 -1
- package/src/runs/background/run-child-session.ts +613 -0
- package/src/runs/background/run-status.ts +99 -18
- package/src/runs/background/runner-aliases.ts +125 -0
- package/src/runs/background/runner-child-sessions.ts +31 -0
- package/src/runs/background/scheduled-runs.ts +174 -18
- package/src/runs/background/stale-run-reconciler.ts +13 -4
- package/src/runs/background/steering.ts +8 -15
- package/src/runs/background/subagent-runner.ts +959 -1159
- package/src/runs/background/subagent-wait.ts +86 -31
- package/src/runs/background/terminal-run-index.ts +1 -1
- package/src/runs/background/wait-completions.ts +45 -2
- package/src/runs/background/wait-config.ts +23 -9
- package/src/runs/background/wait-tool.ts +27 -19
- package/src/runs/foreground/async-steering-action.ts +3 -19
- package/src/runs/foreground/async-stop-action.ts +23 -2
- package/src/runs/foreground/execution.ts +585 -481
- package/src/runs/foreground/foreground-control.ts +13 -0
- package/src/runs/foreground/foreground-history.ts +26 -3
- package/src/runs/foreground/subagent-executor.ts +1549 -410
- package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
- package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
- package/src/runs/shared/abort-recovery.ts +119 -0
- package/src/runs/shared/acceptance.ts +147 -39
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/async-status-projection.ts +565 -0
- package/src/runs/shared/background-process-options.ts +9 -0
- package/src/runs/shared/capability-ceiling.ts +2 -2
- package/src/runs/shared/child-hooks.ts +25 -0
- package/src/runs/shared/child-identity.ts +62 -0
- package/src/runs/shared/child-launch-plan.ts +151 -0
- package/src/runs/shared/child-launch.ts +314 -0
- package/src/runs/shared/child-lifecycle.ts +25 -0
- package/src/runs/shared/child-runtime-config.ts +126 -0
- package/src/runs/shared/child-session.ts +342 -0
- package/src/runs/shared/child-tool-plan.ts +540 -0
- package/src/runs/shared/claude-code-adapter.ts +133 -0
- package/src/runs/shared/codex-exec-adapter.ts +129 -0
- package/src/runs/shared/completion-evidence.ts +89 -0
- package/src/runs/shared/completion-guard.ts +57 -6
- package/src/runs/shared/cursor-agent-adapter.ts +114 -0
- package/src/runs/shared/dynamic-fanout.ts +4 -4
- package/src/runs/shared/extension-bindings.ts +78 -0
- package/src/runs/shared/external-cli-contract.ts +167 -0
- package/src/runs/shared/external-cli-preflight.ts +138 -0
- package/src/runs/shared/external-cli-runner.ts +349 -54
- package/src/runs/shared/external-job-bridge.ts +53 -37
- package/src/runs/shared/external-job-runner.ts +126 -23
- package/src/runs/shared/fast-mode-extension.ts +10 -0
- package/src/runs/shared/host-step-status.ts +231 -0
- package/src/runs/shared/lane-metadata.ts +126 -0
- package/src/runs/shared/launch-cwd.ts +16 -0
- package/src/runs/shared/long-running-guard.ts +2 -1
- package/src/runs/shared/mcp-config-sources.ts +422 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
- package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
- package/src/runs/shared/model-exclusions.ts +141 -10
- package/src/runs/shared/model-fallback.ts +187 -33
- package/src/runs/shared/model-scope.ts +106 -39
- package/src/runs/shared/mutation-evidence.ts +199 -0
- package/src/runs/shared/nested-events.ts +38 -48
- package/src/runs/shared/nested-path.ts +0 -14
- package/src/runs/shared/nested-render.ts +9 -5
- package/src/runs/shared/orca-progress-tabs.ts +83 -16
- package/src/runs/shared/parallel-handoff.ts +423 -7
- package/src/runs/shared/parallel-utils.ts +28 -5
- package/src/runs/shared/permissions.ts +1 -14
- package/src/runs/shared/pi-spawn.ts +69 -35
- package/src/runs/shared/process-signal.ts +16 -0
- package/src/runs/shared/run-fanout-budget.ts +0 -13
- package/src/runs/shared/run-history.ts +21 -1
- package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
- package/src/runs/shared/single-output.ts +89 -22
- package/src/runs/shared/structured-output.ts +61 -7
- package/src/runs/shared/subagent-control.ts +6 -2
- package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
- package/src/runs/shared/task-intent.ts +21 -7
- package/src/runs/shared/tool-availability.ts +18 -64
- package/src/runs/shared/tool-budget.ts +0 -14
- package/src/runs/shared/tool-timeout.ts +1 -1
- package/src/runs/shared/workflow-graph.ts +16 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
- package/src/runs/shared/worktree.ts +571 -62
- package/src/shared/atomic-json.ts +3 -1
- package/src/shared/child-session-name.ts +46 -0
- package/src/shared/extension-context.ts +24 -0
- package/src/shared/fork-context.ts +21 -12
- package/src/shared/fork-session-cwd.ts +27 -0
- package/src/shared/formatters.ts +18 -3
- package/src/shared/jsonl-writer.ts +11 -0
- package/src/shared/launch-contract.ts +20 -6
- package/src/shared/pruned-fork.ts +450 -0
- package/src/shared/session-file-trust.ts +19 -0
- package/src/shared/session-tokens.ts +14 -3
- package/src/shared/settings.ts +21 -102
- package/src/shared/shortcuts.ts +17 -0
- package/src/shared/thinking-ceiling.ts +46 -0
- package/src/shared/types.ts +644 -75
- package/src/shared/utils.ts +60 -93
- package/src/shared/workflow-child-permit.ts +207 -0
- package/src/slash/delegation-adapters.ts +1 -9
- package/src/slash/delegation-request.ts +0 -4
- package/src/slash/prompt-template-bridge.ts +37 -1
- package/src/slash/slash-bridge.ts +1 -2
- package/src/slash/slash-commands.ts +383 -116
- package/src/slash/slash-live-state.ts +22 -11
- package/src/slash/subagents-admin.ts +29 -12
- package/src/tui/fleet-native-transcript.ts +4 -0
- package/src/tui/fleet-status.ts +278 -90
- package/src/tui/fleet-transcript.ts +11 -5
- package/src/tui/fleet.ts +54 -28
- package/src/tui/render-helpers.ts +31 -0
- package/src/tui/render.ts +1433 -166
- package/src/watchdog/change-signature.ts +40 -1
- package/src/watchdog/child-status.ts +54 -34
- package/src/watchdog/diff-tool.ts +77 -0
- package/src/watchdog/emission-guard.ts +5 -3
- package/src/watchdog/guidance.ts +20 -0
- package/src/watchdog/permission-arbiter.ts +59 -52
- package/src/watchdog/register-child.ts +28 -25
- package/src/watchdog/register-main.ts +10 -9
- package/src/watchdog/render.ts +4 -5
- package/src/watchdog/review.ts +15 -4
- package/src/watchdog/rules.ts +70 -0
- package/src/watchdog/runtime.ts +75 -92
- package/src/watchdog/scope.ts +0 -11
- package/src/watchdog/settings.ts +48 -104
- package/src/watchdog/turn-delta.ts +1 -1
- package/src/watchdog/types.ts +18 -32
- package/src/watchdog/warning-format.ts +0 -1
- package/src/workflows/chat-progress.ts +7 -3
- package/src/workflows/host-command.ts +235 -0
- package/src/workflows/scripted-workflow.ts +1142 -69
- package/src/workflows/workflow-checklist.ts +439 -0
- package/src/workflows/workflow-child-summary.ts +121 -0
- package/src/workflows/workflow-preflight.ts +297 -0
- package/src/workflows/workflow-receipt.ts +232 -6
- package/src/workflows/workflow-resources.ts +150 -0
- package/src/workflows/workflow-settlement.ts +246 -0
- package/src/runs/shared/child-protocol.ts +0 -401
- package/src/runs/shared/pi-args.ts +0 -858
- package/src/runs/shared/subagent-startup-retry.ts +0 -116
- package/src/runs/shared/turn-budget.ts +0 -98
- package/src/shared/post-exit-stdio-guard.ts +0 -85
package/docs/tool-reference.md
CHANGED
|
@@ -4,7 +4,26 @@ Parameters and actions for the `subagent` tool. These are what the LLM passes wh
|
|
|
4
4
|
|
|
5
5
|
## Execution examples
|
|
6
6
|
|
|
7
|
-
Chaining is code-driven through `workflowScript`. Use `await runs.run(...)` for sequential steps and `await runs.all([{ key, agent, task }, ...])` for ordinary parallel fanout. Do not read `.output` from an unawaited `runs.run` launch. Stored `runs.run` promises are only for the advanced rolling fanout pattern under [Workflow steering](#workflow-steering), where every promise is later observed with direct `await`, `Promise.race`, or `Promise.all`. Legacy top-level `chain`, `tasks`, and `parallel` inputs are not supported. Helper functions must be plain functions or explicit Promise chains. Nested `async function` helpers, async arrows, and async methods are rejected so child-launch tracking stays portable across Node and Bun.
|
|
7
|
+
Chaining is code-driven through `workflowScript`. Use `await runs.run(...)` for sequential steps and `await runs.all([{ key, agent, task }, ...])` for ordinary parallel fanout. `runs.all` resolves to an ordered array, not a key map, so use indexes, destructuring, or `.map(...)`, not `results.<key>`. Do not read `.output` from an unawaited `runs.run` launch. Stored `runs.run` promises are only for the advanced rolling fanout pattern under [Workflow steering](#workflow-steering), where every promise is later observed with direct `await`, `Promise.race`, or `Promise.all`. Legacy top-level `chain`, `tasks`, and `parallel` inputs are not supported. Helper functions must be plain functions or explicit Promise chains. Nested `async function` helpers, async arrows, and async methods are rejected so child-launch tracking stays portable across Node and Bun. For permission-sensitive host calls, use an extension-owned named resource such as `{ workflow: "run-ci", args: { command: "npm test" } }`; raw public `workflowScript`/`workflowScriptPath` inputs have unknown resource provenance and cannot call `runs.host`. A resolved resource may internally use `runs.host(key, { kind: "command", command, timeoutMs, output?, role?, provider? })` within its authority ceiling; there is no per-step `cwd`, and commands and relative output paths use the workflow `cwd`. Set `cwd` on the outer `subagent({...})` request instead, or put a trusted directory change in the command (for example, `cd /path/to/worktree && npm test`).
|
|
8
|
+
|
|
9
|
+
Use `{ action: "validate", workflowScript }` to check statically decidable syntax and structure without launching children. It returns `{ ok, errors }` and fails the tool call when `ok` is false. Dynamic keys and values remain valid because runtime-only cases are not guessed.
|
|
10
|
+
|
|
11
|
+
Use `workflowScriptPath` instead of `workflowScript` to load the same JavaScript statement body from a file. The two fields are mutually exclusive. Relative paths resolve against the request `cwd`, and absolute paths pass through. The host reads the file before validation, scheduling, or sandbox execution. The workflow sandbox still has no filesystem access. Missing, unreadable, and empty files fail as file input errors.
|
|
12
|
+
|
|
13
|
+
For permission-extension interoperability, use one of the package-owned named resources with bounded `args` instead of caller-supplied workflow text:
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
{ workflow: "review", args: { task: "Review the auth flow" } }
|
|
17
|
+
{ workflow: "run-ci", args: { command: "npm test" } }
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The host resolves the script and authority internally and records bounded provenance in workflow details and receipts. Named resources cannot be combined with `agent`, `task`, `workflowScript`, or `workflowScriptPath`; user/project resource registries are not part of this first slice.
|
|
21
|
+
|
|
22
|
+
```js
|
|
23
|
+
{ workflowScriptPath: "workflows/review.js", cwd: "/path/to/project" }
|
|
24
|
+
{ action: "validate", workflowScriptPath: "workflows/review.js" }
|
|
25
|
+
{ action: "schedule.create", every: "6h", workflowScriptPath: "workflows/review.js" }
|
|
26
|
+
```
|
|
8
27
|
|
|
9
28
|
```js
|
|
10
29
|
// One child; return the child promise explicitly
|
|
@@ -26,28 +45,72 @@ Chaining is code-driven through `workflowScript`. Use `await runs.run(...)` for
|
|
|
26
45
|
` }
|
|
27
46
|
```
|
|
28
47
|
|
|
48
|
+
### Parallel sequential lanes
|
|
49
|
+
|
|
50
|
+
Use `runs.lanes(lanes)` inside a `workflowScript` when several independent lanes each have ordered stages. This helper composes the existing workflow child runner; it does not add a top-level `lanes` parameter or a second persistence/cleanup system.
|
|
51
|
+
|
|
52
|
+
```js
|
|
53
|
+
{ workflowScript: `
|
|
54
|
+
const board = await runs.lanes([
|
|
55
|
+
{ key: "api", stages: [
|
|
56
|
+
{ key: "writer", agent: "worker", task: "Implement the API change" },
|
|
57
|
+
{ key: "challenge", resume: "previous", task: "Challenge the implementation" },
|
|
58
|
+
{ key: "review", agent: "reviewer", task: "Review the API lane" }
|
|
59
|
+
] },
|
|
60
|
+
{ key: "ui", stages: [
|
|
61
|
+
{ key: "writer", agent: "worker", task: "Implement the UI change" },
|
|
62
|
+
{ key: "review", agent: "reviewer", task: "Review the UI lane" }
|
|
63
|
+
] }
|
|
64
|
+
]);
|
|
65
|
+
return board.map((lane) => ({
|
|
66
|
+
key: lane.key,
|
|
67
|
+
state: lane.state,
|
|
68
|
+
failedStage: lane.failedStage,
|
|
69
|
+
stages: lane.stages.map((stage) => ({
|
|
70
|
+
key: stage.key,
|
|
71
|
+
state: stage.state,
|
|
72
|
+
ok: stage.ok,
|
|
73
|
+
runId: stage.runId,
|
|
74
|
+
outputReference: stage.outputReference,
|
|
75
|
+
verdict: stage.verdict
|
|
76
|
+
}))
|
|
77
|
+
}));
|
|
78
|
+
` }
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The first stage of each lane is launched by one existing `runs.all(...)` batch. Later stages run in lane order. Set `resume: "previous"` on a later stage to continue the preceding retained child; the helper requires that child’s returned `runId` and delegates to the existing resume checks. Stage keys are local to the lane, and generated child keys are `<lane>.<stage>`.
|
|
82
|
+
|
|
83
|
+
The complete plain-JSON inventory is validated before the first launch (maximum 32 lanes, 16 stages per lane, 64 total stages, and 64 KiB canonical JSON). A failed, stopped, or detached stage blocks only its lane and marks later stages `skipped`; an explicit `structuredOutput.verdict === "blocked"` has the same effect. Reviewer prose is not parsed. The bounded board returns lane/stage keys, state, `ok`, run ids, explicit output references, bounded errors, and optional verdicts, not transcripts. Use raw `runs.run(...)`/`runs.all(...)` for conditional or rolling workflows.
|
|
84
|
+
|
|
29
85
|
## Parameter reference
|
|
30
86
|
|
|
31
87
|
| Param | Type | Default | Description |
|
|
32
88
|
|-------|------|---------|-------------|
|
|
33
89
|
| `agent` | string | - | Agent target for management actions. Workflow child agents are set inside `runs.run` or `runs.all`. |
|
|
34
|
-
| `action` | string | - |
|
|
90
|
+
| `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`), Herdr inspector (`inspector.open/status/close`), Herdr project pane (`project.open/status/close`), status/control, plan-only `worktree.cleanup`, schedule, watchdog, or doctor action. |
|
|
35
91
|
| `topic` | `overview \| workflows \| agents \| missions \| observability \| tool-reference \| configuration \| models \| watchdog \| extension-api` | `overview` | Packaged guide topic for `action: "guide"`. |
|
|
36
92
|
| `config` | object/string | - | Agent config for management create/update. |
|
|
37
93
|
| `context` | `fresh \| fork` | global or per-agent default, else `fresh` | Explicit `fresh` or `fork` overrides every workflow child. When omitted, [`defaultSubagentContext`](configuration.md#defaultsubagentcontext) wins over each agent's `defaultContext`; `"fork"` creates a real branched session when the parent session file and current leaf exist, otherwise it falls back to `fresh`. Packaged `worker`, `oracle`, and `advisor` default to `fork`. |
|
|
38
94
|
| `missionId` | string | - | Attach a workflow to an existing project mission instead of creating its default enclosing mission. |
|
|
39
95
|
| `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. |
|
|
40
|
-
| `handoffPath` | string | - | Aggregate handoff manifest
|
|
41
|
-
| `
|
|
96
|
+
| `handoffPath` | string | - | Aggregate handoff manifest for `action: "worktree.discard"` or lane evidence actions, or optional explicit metadata for `action: "worktree.cleanup"`. |
|
|
97
|
+
| `repo` | string | runtime cwd | Repository path for `action: "worktree.cleanup"`; plan mode only. The configured worktree base filters candidates by their per-project folder under it but never discovers them. |
|
|
98
|
+
| `planId` | string | - | Reserved for a future `worktree.cleanup` apply action; rejected by the current plan-only action. |
|
|
99
|
+
| `mode` | `steer \| follow_up \| auto \| plan \| apply` | - | Delivery mode for `action: "steer"`; `worktree.cleanup` currently accepts `plan` only. Apply/removal is reserved for a later change. |
|
|
100
|
+
| `laneId` | string | - | Exact `runId` stored in the handoff manifest for `lane.status`, `lane.recordMerge`, or `lane.recordSupersession`. |
|
|
101
|
+
| `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. |
|
|
102
|
+
| `supersession` | object | - | Attested replacement-lane evidence for `lane.recordSupersession`; requires a different replacement lane id, attestor, and timestamp. |
|
|
103
|
+
| `focus` | boolean | false | Focus the newly split pane for `action: "inspector.open"` or `action: "project.open"`; not a standalone action. 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. |
|
|
42
104
|
| `view` | `fleet \| transcript` | - | Optional `status` view for the active fleet surface or transcript tail inspection. |
|
|
43
105
|
| `lines` | number | `80` | Maximum transcript lines for `action: "status", view: "transcript"`; capped at 500. |
|
|
44
106
|
| `agentScope` | `user \| project \| both` | `both` | Agent discovery scope. Project wins on collisions. |
|
|
45
|
-
| `
|
|
107
|
+
| `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. |
|
|
108
|
+
| `async` | boolean | default-on | Background execution. Workflows default to background. `async:false` blocks the parent until completion and runs the child as a session inside the parent Pi process; such foreground children never load the parent's ambient extensions, so agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) or models from a provider extension must run as background children, which load them inside the detached runner process. |
|
|
46
109
|
| `chatProgress` | `auto \| off \| live-card` | `auto` | WorkflowScript 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. |
|
|
47
110
|
| `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. |
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
111
|
+
| `baseRef` | string | `HEAD` | Git ref used as the base commit for managed worktrees. It must be a safe Git ref that resolves to a commit; source-checkout cleanliness is still checked before allocation. For workflowScript, set it on the outer request as a default or on an individual `runs.run`/`runs.all` child to override it. |
|
|
112
|
+
| `timeoutMs` / `maxRuntimeMs` | number | config `timeoutMs`, else 30 min foreground / single-agent async | Optional run-level max runtime in milliseconds. 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 and does not trigger `fallbackModels`. |
|
|
113
|
+
| `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. |
|
|
51
114
|
| `toolBudget` | object | none | Optional child tool-call budget `{ soft?, hard, block? }`. At `soft` the child is nudged to finalize. After `hard`, configured tools are blocked; `block` defaults to `read`, `grep`, `find`, and `ls`, while `"*"` blocks every tool call. Final assistant text is never blocked. |
|
|
52
115
|
| `usageBudget` | object | none | Optional root-only reported-usage budget `{ tokens?: { soft?, hard }, costUsd?: { soft?, 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. |
|
|
53
116
|
| `cwd` | string | runtime cwd | Override working directory. |
|
|
@@ -61,7 +124,7 @@ Chaining is code-driven through `workflowScript`. Use `await runs.run(...)` for
|
|
|
61
124
|
|
|
62
125
|
### Budget guidance for writers
|
|
63
126
|
|
|
64
|
-
As a conservative orchestration policy, do not set
|
|
127
|
+
As a conservative orchestration policy, do not set a hard `toolBudget` or tight `usageBudget` on implementation workers, fix workers, reviewers with edit authority, or other mutation-capable children. A default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model, so neither tool-call counts nor token/cost totals measure whether a delivery slice is buildable or safe to hand off. Hard caps remain appropriate for explicitly read-only scouts, reviewers, and validators.
|
|
65
128
|
|
|
66
129
|
Bound writer work with a narrow task and an outer `timeoutMs` or `maxRuntimeMs` that leaves enough margin for the slice. An elapsed timeout is not a mutation-safe boundary and may still signal a child during tool work. Before the deadline, use `steer` or an attention notice to request a checkpoint after the current tool returns, including changed files, build/test state, remaining work, and commit or PR state.
|
|
67
130
|
|
|
@@ -77,7 +140,7 @@ In workflow runs that omit `context`, each `runs.run` child follows the global `
|
|
|
77
140
|
|
|
78
141
|
`runs.steer(key, message, options?)` targets a stable key already launched by `runs.run` or `runs.all`. It does not accept a raw run id. Options are `mode?: "steer" | "follow_up" | "auto"`, `index?: number`, and `ackTimeoutMs?: number`. The promise returns `{ key, state, requestId?, deliveryStatus?, targets?, error? }`, where `state` is `queued`, `delivered`, `missed`, or `failed`.
|
|
79
142
|
|
|
80
|
-
The workflow trace records the attempt and receipt. Always await, return, or include the promise in an awaited standard Promise combinator. Unawaited steering calls reject workflow completion after the side effect settles. `Promise.race` remains the rolling primitive.
|
|
143
|
+
The workflow trace records the attempt and receipt. Always await, return, or include the promise in an awaited standard Promise combinator. Unawaited steering calls reject workflow completion after the side effect settles. `Promise.race` remains the rolling primitive. Foreground children are steered through their in-process session (`steer` and `auto` interrupt at the next safe point and report `delivered`; `follow_up` queues until the run settles and reports `queued`). Async children use the file control inbox. Steering recovery is disabled in both cases.
|
|
81
144
|
|
|
82
145
|
For advanced rolling fanout, keep the launched `runs.run` promises in ordinary JavaScript data only when every promise is later observed with direct `await`, `Promise.race`, or `Promise.all`. `Promise.race` gives the next completed child, `runs.steer` can challenge a still-running keyed sibling, and `Promise.all` collects the rest. No separate `runs.start`, `runs.next`, or `runs.collect` API is exposed.
|
|
83
146
|
|
|
@@ -102,6 +165,8 @@ Use `outputMode: "file-only"` when a saved output may be large and the parent on
|
|
|
102
165
|
|
|
103
166
|
In workflowScript, 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.
|
|
104
167
|
|
|
168
|
+
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.
|
|
169
|
+
|
|
105
170
|
Workflows get `await state.get(key)` and `await state.set(key, value)` through their default or explicit mission. Use them to share durable JSON values across later workflows attached with the same `missionId`. Each `set` takes the state-file lock and merges its key with the latest on-disk state. Missing keys return `undefined`, and the complete state file has a strict 256 KiB limit. `mission:false` workflows have no `state` global.
|
|
106
171
|
|
|
107
172
|
### Retained children
|
|
@@ -119,6 +184,8 @@ Completed workflow children from the current parent session stay addressable as
|
|
|
119
184
|
` }
|
|
120
185
|
```
|
|
121
186
|
|
|
187
|
+
Each workflow key identifies one result lane. Use a new stable workflow key for every distinct retained resume pass; same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected.
|
|
188
|
+
|
|
122
189
|
Inside `workflowScript`, `await runs.run(key, { resume, task })` waits for the revived child to finish and returns its completed output and new `runId`. Each resume can return a new retained run id, so loops must continue from the latest returned `runId`. Top-level `{ action: "resume" }` remains detached and returns a background-run receipt.
|
|
123
190
|
|
|
124
191
|
For a simple implementation challenge outside a workflow script, send the challenge through `subagent({ action: "resume", id: "<retained-writer-run>", message: "Reconsider the implementation and make any better current-scope change." })` only when `children.list` reports that retained writer as `resumable`. If no retained writer is resumable, start a same-role fallback challenge and record why it is a fallback. Use workflow `runs.run({ resume })` only when the script must await the revived writer output before the next step. Do not use `steer` as the sole challenge action for a completed retained child; `steer` with `mode: "follow_up"` only queues text for the next `resume`.
|
|
@@ -136,6 +203,7 @@ Agent definitions are not loaded into context by default. Management actions let
|
|
|
136
203
|
```ts
|
|
137
204
|
{ action: "list" }
|
|
138
205
|
{ action: "list", agentScope: "project" }
|
|
206
|
+
{ action: "list", capabilities: true }
|
|
139
207
|
{ action: "get", agent: "scout" }
|
|
140
208
|
{ action: "models" }
|
|
141
209
|
{ action: "models", agent: "reviewer" }
|
|
@@ -149,9 +217,10 @@ Agent definitions are not loaded into context by default. Management actions let
|
|
|
149
217
|
systemPrompt: "You are a code scout...",
|
|
150
218
|
systemPromptMode: "replace",
|
|
151
219
|
inheritProjectContext: false,
|
|
220
|
+
inheritGlobalContext: false,
|
|
152
221
|
inheritSkills: false,
|
|
153
222
|
model: "anthropic/claude-sonnet-4",
|
|
154
|
-
fallbackModels: ["openai/gpt-5-
|
|
223
|
+
fallbackModels: ["openai-codex/gpt-5.6-luna:low", "anthropic/claude-haiku-4-5"],
|
|
155
224
|
tools: "read, bash, mcp:github/search_repositories",
|
|
156
225
|
extensions: "",
|
|
157
226
|
skills: "parallel-scout",
|
|
@@ -178,6 +247,7 @@ Agent definitions are not loaded into context by default. Management actions let
|
|
|
178
247
|
|
|
179
248
|
Rules:
|
|
180
249
|
|
|
250
|
+
- `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/fallbacks, default async/timeout, 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.
|
|
181
251
|
- `create` uses `config.scope`, not `agentScope`.
|
|
182
252
|
- `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.
|
|
183
253
|
- `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`.
|
|
@@ -190,6 +260,42 @@ Rules:
|
|
|
190
260
|
|
|
191
261
|
`refine`, `refine.show`, and `refine.rollback` manage project-local refinement overlays for one agent. `/subagents-refine <agent>` is the slash equivalent of `refine`. See [agents.md](agents.md#refinement-overlays) for behavior and storage.
|
|
192
262
|
|
|
263
|
+
## Lane merge evidence and cleanup eligibility
|
|
264
|
+
|
|
265
|
+
Lane evidence actions update an existing parallel handoff manifest at an explicit update boundary. They do not verify GitHub state, run Git commands, or remove worktrees. Pass the manifest path and its exact `runId` as `laneId`:
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
subagent({
|
|
269
|
+
action: "lane.recordMerge",
|
|
270
|
+
laneId: "<manifest-run-id>",
|
|
271
|
+
handoffPath: "/path/to/handoff.json",
|
|
272
|
+
merge: {
|
|
273
|
+
prNumber: 123,
|
|
274
|
+
reviewedHead: "<40-character-sha>",
|
|
275
|
+
mergeCommit: "<40-character-sha>",
|
|
276
|
+
treeEquivalent: true,
|
|
277
|
+
postMergeChecks: "recorded",
|
|
278
|
+
attestedBy: "operator",
|
|
279
|
+
attestedAt: "2026-08-27T16:23:00.000Z"
|
|
280
|
+
}
|
|
281
|
+
})
|
|
282
|
+
subagent({
|
|
283
|
+
action: "lane.recordSupersession",
|
|
284
|
+
laneId: "<manifest-run-id>",
|
|
285
|
+
handoffPath: "/path/to/handoff.json",
|
|
286
|
+
supersession: {
|
|
287
|
+
supersededBy: "<replacement-lane-id>",
|
|
288
|
+
attestedBy: "operator",
|
|
289
|
+
attestedAt: "2026-08-27T16:23:00.000Z"
|
|
290
|
+
}
|
|
291
|
+
})
|
|
292
|
+
subagent({ action: "lane.status", laneId: "<manifest-run-id>", handoffPath: "/path/to/handoff.json" })
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
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.
|
|
296
|
+
|
|
297
|
+
`lane.status` renders the stored state and a copy-pasteable `worktree.cleanup` plan invocation. It never runs that invocation. All cleanup planning/apply and apply-time Git/ownership revalidation belong to `worktree.cleanup` from #1622; remote branch deletion and extension-side GitHub verification remain out of scope.
|
|
298
|
+
|
|
193
299
|
## Status and control actions
|
|
194
300
|
|
|
195
301
|
```ts
|
|
@@ -226,7 +332,8 @@ subagent({ action: "doctor" })
|
|
|
226
332
|
|
|
227
333
|
- Multi-child async runs and remembered foreground single, parallel, or chain runs can be revived by passing `index` to choose the child.
|
|
228
334
|
- Nested runs can be resumed by nested id when their live route or persisted nested session metadata is available.
|
|
229
|
-
-
|
|
335
|
+
- Completed external-job runs can use the same `resume` action as a provider follow-up when the registered provider exposes `followUp(input)`. Running external-job parents fail closed with guidance to wait for completion. Unsupported providers fail with an update/reload message.
|
|
336
|
+
- Revive starts a new child session from the old session context; it does not resume the live session, and it requires the chosen child to have a persisted `.jsonl` session file.
|
|
230
337
|
- Direct revival takes an exclusive cross-process lease on the canonical session file until the new child finishes. A concurrent attempt fails before Pi is spawned and identifies the owning revived run; dead-owner leases are reclaimed only when staleness can be proved.
|
|
231
338
|
|
|
232
339
|
### stop
|
|
@@ -238,6 +345,7 @@ subagent({ action: "doctor" })
|
|
|
238
345
|
- Direct id calls execute immediately.
|
|
239
346
|
- `/subagents-stop` without an id opens a selector with confirmation when a TUI is available. Use `↑`/`↓` or `j`/`k` to move through the selector.
|
|
240
347
|
- In non-TUI contexts the slash command prints exact `subagent({ action: "stop", id })` and `/subagents-stop <id>` commands.
|
|
348
|
+
- Pass a child id to stop one child of a multi-child async run or workflow while the rest continue: `/subagents-stop <run-id> <child-id>` (equivalent to `subagent({ action: "stop", id, childId })`). Child ids come from status output, the async status snapshot, or `/subagents-inspect-rpc` replies. Only pending or running children are stoppable; the request is rejected for anything else instead of widening to a run-level stop.
|
|
241
349
|
- Inactive schedules can appear in the selector, but they are labeled as schedules and route through `schedule.pause`, not `stop`.
|
|
242
350
|
|
|
243
351
|
### steer
|
|
@@ -250,6 +358,8 @@ Only a top-level single run may interrupt after the acknowledgment deadline and
|
|
|
250
358
|
|
|
251
359
|
The persisted `steering` ledger retains 20 requests and replaces the old `steerCount`/`lastSteerAt` fields.
|
|
252
360
|
|
|
361
|
+
The `/subagents-steer <run-id> [--child <child-id>] <message>` slash command is the host bridge for non-TUI sessions and RPC hosts. `--child` accepts the stable child identity shown in status output and inspect replies (workflow key, child run id, or `step:<index>`) and resolves it to the child index before steering; unknown or ambiguous child ids fail closed. Flags are parsed only between the run id and the message tail — once the message starts, `--` tokens are message text. The bridge always disables pause-and-revive recovery (`steeringRecovery: false`), matching the extension RPC `nonRecoveringSteer` guarantee so the caller keeps authority over the exact child it addressed.
|
|
362
|
+
|
|
253
363
|
## Acceptance gates
|
|
254
364
|
|
|
255
365
|
Every run resolves an effective acceptance policy. Callers may omit `acceptance` for the inferred default, or set it on single runs, top-level parallel task items, chain steps, static parallel tasks, and dynamic fanout templates.
|
|
@@ -284,7 +394,7 @@ Acceptance evidence levels are `auto`, `none`, `attested`, `checked`, and `verif
|
|
|
284
394
|
Review is a separate gate configured with `acceptance.review`:
|
|
285
395
|
|
|
286
396
|
- Async, risky, and dynamic writer contexts infer checked evidence plus `review: { agent: "reviewer", required: true }`.
|
|
287
|
-
-
|
|
397
|
+
- Reviewer/read-only calls infer no acceptance by default; explicit acceptance requests still apply.
|
|
288
398
|
- Normal writer tasks infer checked evidence without review.
|
|
289
399
|
|
|
290
400
|
Agent frontmatter or `subagents.agentOverrides` may set `acceptanceRole: "read-only" | "writer"` for ambiguous tasks. Explicit task mutation or no-edit intent wins over that role, while omitted metadata preserves the existing reviewer/scout/worker name heuristics. The role affects acceptance inference only and does not change tool access.
|
|
@@ -311,12 +421,26 @@ Acceptance provenance is stored separately from child prose. `evidenceStatus` pr
|
|
|
311
421
|
|
|
312
422
|
### The acceptance report
|
|
313
423
|
|
|
314
|
-
For `attested` or stricter levels, the child prompt includes a standardized acceptance section and asks for a fenced `acceptance-report` JSON block.
|
|
424
|
+
For `attested` or stricter levels, the child prompt includes a standardized acceptance section and asks for a fenced `acceptance-report` JSON block. Reviewer/read-only inference resolves to `none`, so it does not add this section; explicit acceptance still does. With `outputSchema`, set `acceptance.report: "on"` to require the same report in the final `structured_output` call, or `"off"` to keep the fenced-report path. Omitting `report` preserves the default behavior. Runs without `outputSchema` never gain a standalone structured-output tool from this option.
|
|
315
425
|
|
|
316
426
|
The parser canonicalizes known enum synonyms, snake_case report keys and wrappers, underscore fence tags, unambiguous scalar arrays, string booleans, and criterion-id separators. Unknown or ambiguous keys and enum values fail with field-level diagnostics. Explicit empty `changedFiles` and `testsAddedOrUpdated` arrays are recorded as not applicable; missing fields and empty required command or validation evidence still fail.
|
|
317
427
|
|
|
318
428
|
Acceptance fences are removed from normal output artifacts, while the raw child transcript remains intact and per-child metadata stores the complete acceptance ledger and parsed report. Explicit failed gates fail the run. Inferred gates remain observable without failing the run.
|
|
319
429
|
|
|
430
|
+
## Herdr project panes
|
|
431
|
+
|
|
432
|
+
Herdr project panes are peer Pi sessions opened by this Pi session:
|
|
433
|
+
|
|
434
|
+
```ts
|
|
435
|
+
subagent({ action: "project.open", cwd: "/path/to/repo", message: "Start in this project." })
|
|
436
|
+
subagent({ action: "project.status", cwd: "/path/to/repo" })
|
|
437
|
+
subagent({ action: "project.close", cwd: "/path/to/repo" })
|
|
438
|
+
```
|
|
439
|
+
|
|
440
|
+
The saved pane binding is pane-level only. The parent can refresh status, focus the saved pane when Herdr reports a tab or workspace id, or close it after Herdr verifies ownership and `agent_status: "idle"`. It cannot inspect, steer, or stop subagents inside that peer session. Stale or opaque Herdr metadata stays unknown and fails closed.
|
|
441
|
+
|
|
442
|
+
Inline status counts active current-session work and Herdr project panes. Use Herdr itself or the project-pane API to focus or close project panes.
|
|
443
|
+
|
|
320
444
|
## Orca progress tabs (experimental observer)
|
|
321
445
|
|
|
322
446
|
Orca progress tabs are a global, opt-in observer, not an agent runner. Enable them in the extension config:
|
|
@@ -325,11 +449,11 @@ Orca progress tabs are a global, opt-in observer, not an agent runner. Enable th
|
|
|
325
449
|
{ "orcaProgressTabs": { "enabled": true } }
|
|
326
450
|
```
|
|
327
451
|
|
|
328
|
-
|
|
452
|
+
Foreground and background children keep running through their normal native Pi or `external-cli` path. For each top-level subagent call, the observer asks Orca to create one background terminal tab in the owning worktree and mirrors progress into it. Parallel and chain children share that tab and are separated by child headers. Titles receive a persistent worktree-local sequence number, including across separate workflow calls. Creates for the same worktree are serialized in that sequence so tabs appear to the right in order (`1`, then `2`, then `3`) instead of racing. Model/startup retries reuse the same observer. Attaching an already-running async root does not create a duplicate child tab. Terminal control sequences are removed at the viewer sink across read boundaries. Each mirror is capped at 1 MiB and truncates when the cap or stream backpressure is reached. After the run finishes, its viewer returns to the terminal shell instead of ending the terminal session, so the tab and scrollback remain until the user closes them. Successful native Pi runs with a known session append a safely quoted removal command for the exact verified session path; unsuccessful and sessionless runs append only their terminal status.
|
|
329
453
|
|
|
330
|
-
The observer supports macOS and Linux and is disabled on Windows. It requires executable `orca` on `PATH` (or `PI_SUBAGENT_ORCA_BINARY`) and a running Orca runtime that recognizes the
|
|
454
|
+
The observer supports macOS and Linux and is disabled on Windows. It requires executable `orca` on `PATH` (or `PI_SUBAGENT_ORCA_BINARY`) and a running Orca runtime that recognizes the cwd. Availability and tab creation are best-effort: failures never fail, stop, or delay the subagent. When possible, the observer writes a passive manifest under `<worktree>/.pi/subagents/views/orca/`; the manifest is display metadata only, not a lifecycle or control source. Set `orcaProgressTabs.enabled` to `false` to guarantee that no Orca command or tab is created.
|
|
331
455
|
|
|
332
|
-
Agent profile `runner.type` supports native Pi (the default), `external-cli`, and `external-job`. Orca is intentionally not a profile runner and does not own subagent execution, completion, cancellation, artifacts, or result delivery.
|
|
456
|
+
Agent profile `runner.type` supports native Pi (the default), `external-cli`, and `external-job`. Orca is intentionally not a profile runner and does not own subagent execution, completion, cancellation, artifacts, or result delivery. External-job providers can optionally expose `followUp(input)` so a completed provider job can continue its parent conversation through `subagent({ action: "resume", id: "<run>", message: "..." })`.
|
|
333
457
|
|
|
334
458
|
## External CLI agent profiles
|
|
335
459
|
|
|
@@ -346,7 +470,7 @@ async: true
|
|
|
346
470
|
|
|
347
471
|
Supported: status artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are written to log files, while the in-memory final stdout response and stderr error are limited to their last 64 KiB.
|
|
348
472
|
|
|
349
|
-
Intentionally unsupported:
|
|
473
|
+
Intentionally unsupported: 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 fallback models are also unsupported.
|
|
350
474
|
|
|
351
475
|
## Session sharing
|
|
352
476
|
|
package/docs/watchdog.md
CHANGED
|
@@ -1,145 +1,142 @@
|
|
|
1
1
|
# Watchdog and child permissions
|
|
2
2
|
|
|
3
|
-
The watchdog is an opt-in
|
|
3
|
+
The watchdog is an opt-in second model that reviews what the agent just did and pushes findings back into the transcript. It looks for missed constraints, correctness risks, test gaps, unsafe changes, loop risks, and scope drift, and says nothing when the turn is clean. It is not the `reviewer` subagent; `subagents.defaultModel` and `agentOverrides.reviewer` do not configure it.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## When it runs
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
| Timing | Trigger | Gate | Delivery |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| Boundary review | `agent_end` of every main or child turn | Repo changed | Steered into the transcript; the agent gets one continuation, then that turn is reviewed again |
|
|
10
|
+
| Cadence review | Every `cadence.everyNTools` tool results, minimum 5 | Opt-in | Steered after the current tool, before the next step |
|
|
11
|
+
| LSP pre-pass | Before boundary review | Changed TypeScript/JavaScript files | Diagnostics become watchdog findings without a model call |
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
Boundary reviews coalesce a turn's edits into one final-state review. Unchanged or reverted diffs are skipped, as are `.pi/subagents/` and `tmp/` artifacts. In orchestrated runs, each writing child reviews its own worktree and the parent reviews the aggregate diff after child changes land. There is no timer or "every turn regardless of edits" mode; the closest is a low cadence such as `everyNTools: 5`. Cadence monitoring is inspired by [Scopey](https://github.com/ArchAstro/scopey).
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
- Multiple edits in one turn are coalesced into one review of the final changed state.
|
|
13
|
-
- Unchanged/reverted diffs are skipped.
|
|
14
|
-
- Generated `.pi/subagents/` or `tmp/` artifacts do not trigger review.
|
|
15
|
-
- In orchestrated runs, each writing child can review its own edited worktree, and the parent can still review the aggregate repo diff after child changes are applied.
|
|
15
|
+
Children get the same boundary, cadence, and LSP behavior. Child cadence resolves from `children.overrides.<agent>.cadence`, then `children.cadence`, then top-level `cadence`:
|
|
16
16
|
|
|
17
|
-
|
|
17
|
+
```json
|
|
18
|
+
{
|
|
19
|
+
"subagents": {
|
|
20
|
+
"watchdog": {
|
|
21
|
+
"enabled": true,
|
|
22
|
+
"cadence": { "everyNTools": 10 },
|
|
23
|
+
"children": {
|
|
24
|
+
"enabled": true,
|
|
25
|
+
"cadence": { "everyNTools": 20 },
|
|
26
|
+
"overrides": {
|
|
27
|
+
"worker": { "cadence": { "everyNTools": 5 } },
|
|
28
|
+
"reviewer": { "enabled": false }
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
18
35
|
|
|
19
|
-
|
|
36
|
+
That means: main every 10 tools, worker every 5, other children every 20, reviewer never.
|
|
20
37
|
|
|
21
|
-
|
|
38
|
+
## What you see
|
|
22
39
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
40
|
+
Every finding is an ordinary transcript message: expandable, scrollable, and persisted in session JSONL. A clean review shows nothing.
|
|
41
|
+
|
|
42
|
+
```
|
|
43
|
+
you ─▶ agent turn ─▶ edits repo ─▶ agent_end ─▶ watchdog review
|
|
44
|
+
├─ clean: turn ends
|
|
45
|
+
└─ warning: steered in; agent continues once
|
|
27
46
|
```
|
|
28
47
|
|
|
29
|
-
|
|
48
|
+
Collapsed warnings show the title and evidence line. Expanded warnings show evidence, recommended action, category, and source:
|
|
30
49
|
|
|
31
|
-
|
|
32
|
-
|
|
50
|
+
```
|
|
51
|
+
● Subagent watchdog Blocker (displayed): Claims tests passed without running them
|
|
52
|
+
Evidence: The transcript claims `npm test` passed but no test command appears in the tool log.
|
|
53
|
+
Recommended action: Run the focused test before finishing.
|
|
54
|
+
Category: Test Gap · Source: main
|
|
55
|
+
```
|
|
33
56
|
|
|
34
|
-
|
|
57
|
+
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.
|
|
35
58
|
|
|
36
|
-
|
|
37
|
-
/subagents-watchdog model anthropic/claude-opus-4-8:high
|
|
38
|
-
/subagents-watchdog model openai-codex/gpt-5.5:high
|
|
39
|
-
/subagents-watchdog model inherit
|
|
40
|
-
/subagents-watchdog check
|
|
41
|
-
```
|
|
59
|
+
Child watchdog findings are lifted into the parent in three ways:
|
|
42
60
|
|
|
43
|
-
|
|
61
|
+
- The result envelope contains `watchdog.warnings` with severity, category, summary, evidence, recommended action, `addressed`, and `stalemate`, bounded to the last 20.
|
|
62
|
+
- The acceptance runtime check `watchdog-blocker` fails on blockers that are unaddressed or stalemate.
|
|
63
|
+
- Completion notices include `Watchdog blockers:` lines, and Fleet/status views show `wd:<n>` plus `resolve watchdog blockers`.
|
|
44
64
|
|
|
45
|
-
-
|
|
46
|
-
- If `main.model` is set without a thinking suffix or `main.thinking`, it runs with thinking off. Prefer `:high` or `"thinking": "high"` for the strong-watchdog pairing.
|
|
65
|
+
`/subagents-watchdog status` shows setting sources, enabled state, runtime state, review trigger, scope, cadence, LSP status, selected model/thinking, child overrides, timeout, stalemate count, launch-rule count, review backend, last warning, changed paths, and config errors when present.
|
|
47
66
|
|
|
48
|
-
|
|
67
|
+
## What the reviewer is given
|
|
49
68
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
"main": {
|
|
56
|
-
"model": "anthropic/claude-opus-4-8",
|
|
57
|
-
"thinking": "high"
|
|
58
|
-
}
|
|
59
|
-
}
|
|
60
|
-
}
|
|
61
|
-
}
|
|
62
|
-
```
|
|
69
|
+
- **Turn delta** with changed repo paths. Over-long input keeps the first 6,000 characters and the tail.
|
|
70
|
+
- **Current scope** (`scope.enabled`, default on): bounded real user prompts, with newer prompts superseding older ones.
|
|
71
|
+
- **`watchdog_diff`** when inside git: diff since the session-start commit, including later commits, plus untracked paths to inspect with `read`; accepts `path` and `stat:true`.
|
|
72
|
+
- **`WATCHDOG.md`** standing instructions, read fresh on every review: `<project>/.pi/WATCHDOG.md` first, then `~/.pi/agent/WATCHDOG.md`, capped at 8,000 characters. Set `guidance.watchdogMd: false` to ignore them.
|
|
73
|
+
- **LSP diagnostics** from `typescript-language-server`, auto-detected in `node_modules/.bin` or `PATH`; it is never installed and never run over the whole workspace. Errors become blockers, warnings concerns, and info/hints stay in status.
|
|
63
74
|
|
|
64
|
-
##
|
|
75
|
+
## Choosing a model
|
|
65
76
|
|
|
66
|
-
|
|
77
|
+
One model setting serves both boundary and cadence reviews per endpoint. Use a strong complementary model for rare adversarial boundary reviews, or a cheap one for frequent cadence monitoring.
|
|
67
78
|
|
|
68
|
-
|
|
79
|
+
```text
|
|
80
|
+
/subagents-watchdog recommend-model
|
|
81
|
+
/subagents-watchdog session model recommended
|
|
82
|
+
/subagents-watchdog model recommended
|
|
83
|
+
/subagents-watchdog model anthropic/claude-opus-4-8:high
|
|
84
|
+
/subagents-watchdog model openai-codex/gpt-5.5:high
|
|
85
|
+
/subagents-watchdog model inherit
|
|
86
|
+
/subagents-watchdog check
|
|
87
|
+
/subagents-watchdog on
|
|
88
|
+
```
|
|
69
89
|
|
|
70
|
-
|
|
90
|
+
The recommendation is Opus 4.8 or GPT 5.5 at thinking high, whichever your main session is not using and is authenticated. Saving a model does not enable the watchdog; use `on` separately.
|
|
71
91
|
|
|
72
92
|
```json
|
|
73
93
|
{
|
|
74
94
|
"subagents": {
|
|
75
95
|
"watchdog": {
|
|
76
96
|
"enabled": true,
|
|
77
|
-
"main": {
|
|
78
|
-
"model": "anthropic/claude-haiku-4-5",
|
|
79
|
-
"thinking": "medium"
|
|
80
|
-
},
|
|
97
|
+
"main": { "model": "anthropic/claude-opus-4-8", "thinking": "high" },
|
|
81
98
|
"scope": { "enabled": true },
|
|
82
99
|
"cadence": { "everyNTools": 10 },
|
|
83
|
-
"
|
|
84
|
-
"blockers": true,
|
|
85
|
-
"maxAttempts": 3,
|
|
86
|
-
"stalemateRepeats": 3
|
|
87
|
-
}
|
|
100
|
+
"stalemateRepeats": 3
|
|
88
101
|
}
|
|
89
102
|
}
|
|
90
103
|
}
|
|
91
104
|
```
|
|
92
105
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
When the watchdog displays a blocker at `agent_end`, the `subagents.watchdog.autoFollow` policy can queue a visible follow-up user message asking the agent to address it. Auto-follow only runs while the watchdog is enabled, respects `maxAttempts`, and stops on repeated identical blockers using `stalemateRepeats`.
|
|
96
|
-
|
|
97
|
-
## LSP diagnostics
|
|
98
|
-
|
|
99
|
-
When the watchdog is enabled, it also checks changed TypeScript and JavaScript files for fresh language-server diagnostics before the model review.
|
|
106
|
+
Omit `main.model` to inherit the session model and thinking level. A `main.model` without a thinking suffix or `main.thinking` runs with thinking off, so prefer `:high` for the strong pairing.
|
|
100
107
|
|
|
101
|
-
|
|
102
|
-
- LSP errors surface as watchdog blockers, warnings as concerns, and info/hints stay in status details.
|
|
103
|
-
- Slow or missing servers are reported in `/subagents-watchdog status` without blocking the turn or emitting late mid-turn warnings.
|
|
104
|
-
- Configure the bounds with `subagents.watchdog.lsp.enabled`, `timeoutMs`, `maxFiles`, and `maxDiagnostics`.
|
|
108
|
+
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.
|
|
105
109
|
|
|
106
110
|
## Child watchdogs
|
|
107
111
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
Child watchdogs are opt-in and follow the same edit-gated rule: read-only children do not trigger watchdog reviews, while writer children are reviewed at their own `agent_end` if their worktree changed.
|
|
111
|
-
|
|
112
|
-
## Agent-driven configuration
|
|
113
|
-
|
|
114
|
-
Agents can configure the same values through the tool when you ask them to set up the watchdog:
|
|
115
|
-
|
|
116
|
-
```ts
|
|
117
|
-
subagent({ action: "watchdog.recommend-model" })
|
|
118
|
-
subagent({ action: "watchdog.configure", model: "recommended", scope: "session" })
|
|
119
|
-
subagent({ action: "watchdog.configure", model: "recommended", scope: "project" })
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
Persistent scopes (`user` or `project`) should only be used when you ask for a lasting default. Otherwise the agent should use `scope: "session"`.
|
|
112
|
+
Opt in under `subagents.watchdog.children`. `model` and `thinking` set the default child watchdog; `overrides.<agent>` can set `model`, `thinking`, `enabled`, or `cadence` per role.
|
|
123
113
|
|
|
124
|
-
##
|
|
114
|
+
## Launch rules
|
|
125
115
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
Configure explicit non-bash rules globally in `~/.pi/agent/extensions/subagent/config.json`:
|
|
116
|
+
`subagents.watchdog.rules` pins which models each role may run on. It runs before a child starts, needs no model call, and applies even when model review is off.
|
|
129
117
|
|
|
130
118
|
```json
|
|
131
119
|
{
|
|
132
|
-
"
|
|
133
|
-
"
|
|
134
|
-
"
|
|
135
|
-
|
|
136
|
-
|
|
120
|
+
"subagents": {
|
|
121
|
+
"watchdog": {
|
|
122
|
+
"rules": {
|
|
123
|
+
"action": "warn",
|
|
124
|
+
"roleModels": {
|
|
125
|
+
"scout": { "allow": ["openai-codex/gpt-5.6-luna:max"] },
|
|
126
|
+
"oracle": { "deny": ["*"], "note": "oracle is for hard questions only; ask before launching" },
|
|
127
|
+
"worker": { "deny": ["openai-codex/gpt-5.6-sol:high"] }
|
|
128
|
+
}
|
|
129
|
+
}
|
|
137
130
|
}
|
|
138
131
|
}
|
|
139
132
|
}
|
|
140
133
|
```
|
|
141
134
|
|
|
142
|
-
|
|
135
|
+
`action: "warn"` steers a concern into the orchestrator transcript and lets the launch proceed. `action: "block"` returns a tool error and starts nothing. `allow` and `deny` are anchored, case-sensitive globs (`*`, `?`) matched against `provider/id[:thinking]` and bare `provider/id`; `deny` wins. Rules apply to direct launches, workflow children, and chain/parallel steps using settings visible at the launch cwd.
|
|
136
|
+
|
|
137
|
+
## Native child tool permissions
|
|
138
|
+
|
|
139
|
+
Opt-in, Pi child runtimes only. With no rules, every tool call passes through. Global non-bash rules live in `~/.pi/agent/extensions/subagent/config.json`; agents override matching rules in `permission:` or `permissions:` frontmatter:
|
|
143
140
|
|
|
144
141
|
```yaml
|
|
145
142
|
---
|
|
@@ -150,27 +147,8 @@ permission:
|
|
|
150
147
|
---
|
|
151
148
|
```
|
|
152
149
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
- Agent rules override matching global rules.
|
|
156
|
-
- Omitted and unknown tools default to `allow`.
|
|
157
|
-
- Explicit `allow` removes an inherited restriction.
|
|
158
|
-
- The gate is not registered when the resolved policy has no `ask` or `deny` rules.
|
|
159
|
-
|
|
160
|
-
### How `ask` works
|
|
161
|
-
|
|
162
|
-
An explicit `ask` pauses that exact tool call and sends a bounded, redacted preview to a one-call permission arbiter owned by the built-in child watchdog. The arbiter uses the configured child-watchdog model and returns only `approve` or `deny`; it does not notify the parent agent.
|
|
163
|
-
|
|
164
|
-
Enable and configure `subagents.watchdog.children` before using `ask` rules. A disabled watchdog, missing model/auth, timeout, malformed response, or runtime error denies the call with a clear error.
|
|
165
|
-
|
|
166
|
-
Asked requests and decisions are written to bounded audit JSONL, including `decisionSource: "watchdog"` and bounded failure reasons. Ordinary direction and clarification through `contact_supervisor` or the optional `pi-intercom` extension remain separate and are never permission-gated.
|
|
167
|
-
|
|
168
|
-
### Bash is out of scope
|
|
169
|
-
|
|
170
|
-
`bash` is always passed through by pi-subagents. Bash rules are rejected rather than parsed, gated, denied, or audited. Install and configure `pi-guard` when command-level bash policy is needed.
|
|
171
|
-
|
|
172
|
-
A pi-subagents child is headless, so a pi-guard rule that resolves to `ask` cannot request approval from the parent Pi UI. Native permissions do not forward pi-guard decisions; they only apply to the separate non-bash child permission gate. For child-specific policy, use `PI_GUARD` through a `PI_SUBAGENT_PI_BINARY` wrapper or an equivalent launch wrapper, and configure explicit `allow` or `deny` rules. An `allow` rule grants execution; it is not approval forwarding, so retain explicit denies for commands the child must not run.
|
|
150
|
+
Values are `allow`, `ask`, and `deny`. Agent rules override global ones, omitted and unknown tools default to `allow`, an explicit `allow` removes an inherited restriction, and the gate is not registered when the resolved policy has no `ask` or `deny`.
|
|
173
151
|
|
|
174
|
-
|
|
152
|
+
`ask` pauses that exact tool call and sends a bounded, redacted preview to a one-call arbiter owned by the child watchdog, using the configured child-watchdog model. The arbiter returns only `approve` or `deny` and does not notify the parent. A disabled watchdog, missing model/auth, timeout, malformed response, or runtime error denies the call with a clear error. Requests and decisions are written to bounded audit JSONL. `contact_supervisor` and the optional `pi-intercom` extension are never permission-gated.
|
|
175
153
|
|
|
176
|
-
External CLI profiles are opaque processes, so native permissions cannot intercept their tools
|
|
154
|
+
Bash is always passed through; bash rules are rejected. Use `pi-guard` for command-level policy. Children are pi sessions inside the parent process (foreground) or the detached runner process (background), not separate `pi` binaries, so there is no per-child command wrapper; load `pi-guard` into a child through the agent's `extensions` or `subagentOnlyExtensions`, and background children also pick it up as an ambient extension. External CLI profiles are opaque processes, so native permissions cannot intercept their tools; launches with effective `ask` or `deny` rules are rejected for external CLI agents.
|