@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
package/docs/agents.md
CHANGED
|
@@ -28,6 +28,7 @@ Discovery notes:
|
|
|
28
28
|
- Project discovery also reads legacy `.agents/**/*.md` files. If both `.agents/` and the project config agents directory define the same parsed runtime agent name, the project config directory wins.
|
|
29
29
|
- Nested subdirectories are discovered recursively. `.chain.md` files do not define agents.
|
|
30
30
|
- User and project settings can add extra recursive scan roots with `subagents.agentScanDirs`; fixed user/project agent directories keep higher priority than same-name agents from scan roots.
|
|
31
|
+
- Use `subagents.agentExcludeDirs` to prune literal directory subtrees without disabling legacy agents. See [configuration.md](configuration.md#excluded-agent-directories-settings) for path resolution, scope, and exemptions.
|
|
31
32
|
- Installed Pi packages can expose agent directories from either `{"pi-subagents":{"agents":["./agents"]}}` or `{"pi":{"subagents":{"agents":["./agents"]}}}` in their package manifest. Package agents load above builtins and below user/project agents.
|
|
32
33
|
- Use `agentScope: "user" | "project" | "both"` to control discovery. `both` is the default, and project definitions win runtime-name collisions.
|
|
33
34
|
|
|
@@ -39,12 +40,13 @@ Builtins load at the lowest priority, so a user or project agent with the same n
|
|
|
39
40
|
|-------|--------------------------|
|
|
40
41
|
| `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks, and where another agent should start. |
|
|
41
42
|
| `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
|
|
43
|
+
| `evidence-auditor` | Independent evidence review of important claims in an existing research brief. |
|
|
42
44
|
| `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
|
|
43
45
|
| `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
|
|
44
46
|
| `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
|
|
45
47
|
| `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
|
|
46
48
|
|
|
47
|
-
Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
|
|
49
|
+
Rule of thumb: `scout` before you understand the code, `researcher` before you trust external facts, `evidence-auditor` before you rely on important research, `worker` to implement, `reviewer` to check, and `oracle` when the decision itself feels risky.
|
|
48
50
|
|
|
49
51
|
`oracle` is an advisory reviewer that critiques direction and proposes an execution prompt without editing files. `advisor` is the same bundled role under the Claude Code-compatible name.
|
|
50
52
|
|
|
@@ -58,7 +60,7 @@ The Pi async run remains the source of truth for status, artifacts, wake/wait, m
|
|
|
58
60
|
|
|
59
61
|
### Advisory runner data boundary
|
|
60
62
|
|
|
61
|
-
External CLI agents use their own runner contract. Do not pass 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 adapter explicitly implements them.
|
|
63
|
+
External CLI agents use their own runner contract. They are deliberate execution modes, not implicit recovery paths for a failed native `subagent` workflow. For backlog lanes and other subagent-governed workflows, switching to an external, foreground, or CLI runner requires explicit owner approval after the exact failure/run/worktree state is recorded and the worktree is verified clean or its partial diff is captured. Do not pass 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 adapter explicitly implements them.
|
|
62
64
|
|
|
63
65
|
The built-in `codex-exec` and `codex-exec-writer` profiles are the supported Codex one-shot modes. Both require an installed and authenticated Codex CLI. The adapters own `codex exec --json` argv with ignored user config and rules, ephemeral sessions, approval policy `never`, and a final-message artifact.
|
|
64
66
|
|
|
@@ -184,12 +186,16 @@ Native `oracle` runs inside Pi and can use its configured read tools. The Claude
|
|
|
184
186
|
| `external-job-requests/` and `external-job-responses/` | Host-mediated provider bridge | pending request, terminal response | Host process writes a matching response and removes the request | Bridge timeout or malformed request response | Requests are operation-scoped. Recovery sends `reattach`/`result`, not `start` or `follow-up`, when job metadata exists. `start` and `follow-up` use durable dispatch claims | Provider not registered, host bridge not loaded, malformed request, provider exception, ambiguous dispatch without a provider job id |
|
|
185
187
|
| Provider artifact path | External provider | provider-defined terminal artifact | Provider returns `artifactPath`, or Pi writes returned text to `external-job-<index>.result.md` | Provider reports failure or no result | Existing artifact path is retained in `status.json` | Missing artifact with no text output returns a terminal message instead of inventing content |
|
|
186
188
|
|
|
187
|
-
|
|
189
|
+
### Web research prerequisites
|
|
190
|
+
|
|
191
|
+
The `researcher` and `evidence-auditor` builtins use `web_search`, `fetch_content`, `get_search_content`, and selective `source_check` validation. Those require [pi-web-access](https://github.com/nicobailon/pi-web-access):
|
|
188
192
|
|
|
189
193
|
```bash
|
|
190
194
|
pi install npm:pi-web-access
|
|
191
195
|
```
|
|
192
196
|
|
|
197
|
+
The provider must be loaded in the child and register all four tools, including `source_check`, before launch; a missing required tool prevents a successful run. Foreground children do not load ambient parent extensions: configure `extensions` or `subagentOnlyExtensions` explicitly, or use background extension discovery as described in [Tool and extension selection](#tool-and-extension-selection). For `researcher`, fetched-source inspection is a fallback for a registered `source_check` call failing, not for missing registration.
|
|
198
|
+
|
|
193
199
|
## Overriding builtins and custom agents
|
|
194
200
|
|
|
195
201
|
You can override selected agent fields without copying the whole agent. Overrides live in settings:
|
|
@@ -210,10 +216,10 @@ You can override selected agent fields without copying the whole agent. Override
|
|
|
210
216
|
}
|
|
211
217
|
```
|
|
212
218
|
|
|
213
|
-
Supported override fields: `description`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `
|
|
219
|
+
Supported override fields: `description`, `machine`, `output`, `outputMode`, `defaultReads`, `model`, `defaultProvider`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritGlobalContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, `sandbox`, and `systemPrompt`.
|
|
214
220
|
|
|
215
221
|
- `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
|
|
216
|
-
- Use `output: false`, `defaultReads: false`, `defaultContext: false`, or `
|
|
222
|
+
- Use `output: false`, `defaultReads: false`, `defaultContext: false`, `acceptanceRole: false`, or `machine: false` to clear an inherited value.
|
|
217
223
|
- Use `tools: "inherit"` when that one role should omit its bundled or frontmatter tool allowlist and receive Pi's normal builtins (plus ambient extensions when it runs as a background child).
|
|
218
224
|
- Project overrides beat user overrides.
|
|
219
225
|
- Matching package, user, and project agents also receive override fields, which replace the same fields declared in their frontmatter. This lets a shared agent keep its persona while local settings choose the effective model, context, tools, or other supported options.
|
|
@@ -228,6 +234,37 @@ Disable and restore:
|
|
|
228
234
|
|
|
229
235
|
`eject`, `disable`, `enable`, and `reset` accept `agentScope: "user" | "project"` and operate in one scope at a time. Project overrides still win over user ones, so a project-scope disable survives a user-scope `enable` until you target the project scope.
|
|
230
236
|
|
|
237
|
+
## Running external CLI agents on a Herdr saved machine
|
|
238
|
+
|
|
239
|
+
Native Pi and the six code-owned Claude Code, Codex, and Cursor profiles can run on a Herdr machine (`herdr machine add <target> --label <name>`). Herdr owns each visible agent process in a fresh no-focus pane; SSH is used only as bounded transport for Herdr RPC and ownership checks. Herdr's catalog is the host allowlist; raw ssh targets are rejected.
|
|
240
|
+
|
|
241
|
+
`machine` is a top-level frontmatter key, a settings override (`subagents.agentOverrides.<agent>.machine`, project beats user, `false` clears a pin), and a launch option on the `subagent` tool, workflow `runs.run`, chain, parallel, and dynamic-fanout steps. The launch option wins. Placement survives `subagent({ action: "disable" })`, `reset`, and model profile switches.
|
|
242
|
+
|
|
243
|
+
`cwd` means the directory on that machine when a machine is set. An absolute path or `~/...` is used as given; a relative path joins the repo's configured machine root; with no cwd the root is used; with no root the launch fails closed naming the setting:
|
|
244
|
+
|
|
245
|
+
```json
|
|
246
|
+
{
|
|
247
|
+
"subagents": {
|
|
248
|
+
"agentOverrides": { "claude-code": { "machine": "workmac" } },
|
|
249
|
+
"machines": { "workmac": { "cwd": "/home/nico/proj" } }
|
|
250
|
+
}
|
|
251
|
+
}
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
`machines.<label-or-id>.env` is rejected. No local API key, vendor environment, expanded prompt resource, extension path, or callback is copied. Remote runs use the machine's own credentials and managed model registry. Bounded probes and ownership checks use a fixed machine-owned PATH without sourcing shell profiles.
|
|
255
|
+
|
|
256
|
+
Placed external profiles are one-shot and stop-only: they cannot steer, resume, or claim a Pi supervisor. Their result is always `partial` and begins `[best-effort/unverified]`, because only bounded sanitized terminal snapshots are exposed; no vendor-private transcript, database, JSONL, or blob is used as authoritative settlement evidence. Reconnect observes the same pane and process without redispatching the prompt.
|
|
257
|
+
|
|
258
|
+
pi-subagents never clones, pulls, or checks out on the machine. Generic `external-cli` commands and managed worktrees are rejected before launch; saved-machine placement accepts native Pi and only the six code-owned external profiles.
|
|
259
|
+
|
|
260
|
+
## Parent prompt discovery
|
|
261
|
+
|
|
262
|
+
Set `advertise: true` in a specialist's agent file frontmatter for parent-prompt discovery. When the `subagent` tool is active, pi-subagents adds an agent-owned catalog of names and descriptions to the parent system prompt. Disabled agents and agents excluded by the current capability ceiling are omitted. Advertisement is not supported through settings overrides or runtime registration.
|
|
263
|
+
|
|
264
|
+
Advertisement is opt-in discovery, not automatic routing. The catalog is sorted by name and limited to 16 agents and 12,288 total rendered UTF-8 bytes, including XML escaping, instructions, and omission counts. Descriptions are capped at 512 UTF-8 bytes before escaping. Entries that cannot fit are omitted; canonical agent names are never truncated. The parent still calls `subagent({ action: "list", capabilities: true })` before execution to confirm that the selected agent is executable (including `runner.available === true` for external CLI agents).
|
|
265
|
+
|
|
266
|
+
The file catalog snapshot refreshes at session start/reload and after extension-owned agent-management mutations. External file or settings edits require `/reload`; ordinary turns do not poll the filesystem. Tool availability and capability-ceiling filtering are checked in memory on every prompt. A failed management-triggered refresh withdraws the catalog until a successful refresh, without changing the persisted mutation's result.
|
|
267
|
+
|
|
231
268
|
## Prompt assembly
|
|
232
269
|
|
|
233
270
|
Subagents are narrow by default. Custom agents start with a clean system prompt and only the context you intentionally give them. They do not automatically inherit Pi's whole base prompt, project instruction files, or discovered skills catalog.
|
|
@@ -254,6 +291,7 @@ name: scout
|
|
|
254
291
|
# Optional: registers this as code-analysis.scout while preserving name: scout
|
|
255
292
|
package: code-analysis
|
|
256
293
|
description: Fast codebase recon
|
|
294
|
+
advertise: true
|
|
257
295
|
aliases: explorer, code-scout
|
|
258
296
|
tools: read, grep, find, ls, bash, mcp:chrome-devtools
|
|
259
297
|
excludeTools: bash
|
|
@@ -262,7 +300,6 @@ subagentOnlyExtensions: ./tools/child-only-search.ts
|
|
|
262
300
|
sandbox: reviewer-strict
|
|
263
301
|
permission-profile: reviewer
|
|
264
302
|
model: claude-haiku-4-5
|
|
265
|
-
fallbackModels: openai-codex/gpt-5.6-luna:low, anthropic/claude-sonnet-4
|
|
266
303
|
thinking: high
|
|
267
304
|
systemPromptMode: replace
|
|
268
305
|
inheritProjectContext: false
|
|
@@ -288,15 +325,12 @@ injectToContext: true
|
|
|
288
325
|
Your system prompt goes here.
|
|
289
326
|
```
|
|
290
327
|
|
|
291
|
-
Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `defaultReads`, `skill`/`skills`, `skillPath`, `
|
|
328
|
+
Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `excludeTools`, `defaultReads`, `skill`/`skills`, `skillPath`, `extensions`, and `subagentOnlyExtensions`:
|
|
292
329
|
|
|
293
330
|
```yaml
|
|
294
331
|
tools:
|
|
295
332
|
- read
|
|
296
333
|
- mcp:github/search_repositories
|
|
297
|
-
fallbackModels:
|
|
298
|
-
- openai-codex/gpt-5.6-luna:low
|
|
299
|
-
- anthropic/claude-sonnet-4
|
|
300
334
|
```
|
|
301
335
|
|
|
302
336
|
Field notes:
|
|
@@ -304,6 +338,7 @@ Field notes:
|
|
|
304
338
|
| Field | Notes |
|
|
305
339
|
|-------|-------|
|
|
306
340
|
| `package` | Optional package identifier. A file with `name: scout` and `package: code-analysis` registers as `code-analysis.scout`; serialization keeps `name` and `package` separate. |
|
|
341
|
+
| `advertise` | Set `true` to include this agent's name and description in the parent system prompt when the `subagent` tool is active. Defaults to `false`. |
|
|
307
342
|
| `aliases` | Optional comma-separated or block-list names that resolve to this agent for selection and explicit `agent` and task inputs. Runtime status, persistence, and config still use the canonical `name`. Exact canonical names take precedence over aliases, and alias collisions between distinct canonical agents fail as ambiguous. |
|
|
308
343
|
| `tools` | Strict child tool allowlist. Named extension tools must also have their provider loaded. `mcp:` entries select direct MCP tools when `pi-mcp-adapter` is installed. |
|
|
309
344
|
| `excludeTools` | Optional child tool deny-list applied after normal tool resolution. With an explicit `tools` allowlist, matching names are removed; when `tools` is omitted, the names are excluded from the child session's default tool set. Unknown names are ignored by Pi without making the agent definition invalid. |
|
|
@@ -311,9 +346,8 @@ Field notes:
|
|
|
311
346
|
| `extensions` | Omitted means a background child loads the parent's ambient extensions; empty means no ambient extensions; list values load exactly those extensions. Foreground children never load ambient extensions, so for them only listed values apply. |
|
|
312
347
|
| `subagentOnlyExtensions` | Extension paths loaded only in this agent's child sessions. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
|
|
313
348
|
| `sandbox` | Optional named `pi-sandbox` profile for a native Pi child. It must be a non-empty safe name defined in the user's global `<agentDir>/sandbox.json`; it is a selector only, never an inline network or filesystem policy. |
|
|
314
|
-
| `permission-profile` | Optional named permission profile for a native Pi child. The name must be a non-empty safe identifier defined in the global `pi-permission-system` config's `profiles` registry; only the validated name is passed to the child. See
|
|
349
|
+
| `permission-profile` | Optional named permission profile for a native Pi child. The name must be a non-empty safe identifier defined in the global `pi-permission-system` config's `profiles` registry; only the validated name is passed to the child. See [Permission profiles](fork-extensions.md#permission-profiles). |
|
|
315
350
|
| `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
|
|
316
|
-
| `fallbackModels` | Ordered backup models for provider/model failures such as quota, auth, provider-reported timeout, or unavailable model. Expiration of the run-level `timeoutMs` / `maxRuntimeMs` deadline is terminal and does not trigger fallback. Ordinary task failures do not trigger fallback. |
|
|
317
351
|
| `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. |
|
|
318
352
|
| `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
|
|
319
353
|
| `inheritProjectContext` | Keeps or strips inherited repository instruction blocks. |
|
|
@@ -334,131 +368,16 @@ Field notes:
|
|
|
334
368
|
| `completionGuard` | Set `false` only for non-implementation agents that may mention implementation words while using mutation-capable tools such as `bash`. |
|
|
335
369
|
| `interactive` | Parsed for compatibility but not currently enforced. |
|
|
336
370
|
| `maxSubagentDepth` | Tightens nested delegation for this agent's children. |
|
|
337
|
-
| `injectToContext` | Advertise this agent in the parent system prompt at session start so the main agent can select it without calling `{ action: "list" }` first. See [Context injection](#context-injection). |
|
|
371
|
+
| `injectToContext` | Advertise this agent in the parent system prompt at session start so the main agent can select it without calling `{ action: "list" }` first. See [Context injection](fork-extensions.md#context-injection). |
|
|
338
372
|
| `memory` | Opt-in role-specific persistent memory. See below. |
|
|
339
373
|
|
|
340
|
-
###
|
|
341
|
-
|
|
342
|
-
Use `sandbox: <profile-name>` only for a native Pi child. The profile is resolved
|
|
343
|
-
from the global `pi-sandbox` configuration, never from an agent file or a project
|
|
344
|
-
profile registry:
|
|
374
|
+
### Required host extensions
|
|
345
375
|
|
|
346
|
-
|
|
347
|
-
---
|
|
348
|
-
name: security-reviewer
|
|
349
|
-
description: Review changes with a constrained filesystem and no network
|
|
350
|
-
sandbox: reviewer-strict
|
|
351
|
-
extensions: ./review-tools.ts
|
|
352
|
-
---
|
|
353
|
-
|
|
354
|
-
Review the requested change.
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
`pi-subagents` validates the scalar name and passes only that name to the child.
|
|
358
|
-
It automatically resolves and injects the installed `pi-sandbox` extension and a
|
|
359
|
-
startup guard even when `extensions` is an explicit allowlist; an explicit empty
|
|
360
|
-
allowlist does not remove these required runtime extensions. The guard requires
|
|
361
|
-
`pi-sandbox` to acknowledge successful profile initialization before the child
|
|
362
|
-
can enter its first model turn. The launch fails before the model's first turn when the package or manifest is missing, a capability ceiling denies child
|
|
363
|
-
extensions, the profile cannot be loaded, or sandbox initialization fails. A
|
|
364
|
-
blocked child publishes that reason through its startup diagnostics, so the
|
|
365
|
-
caller sees the profile error (and the available profile names) instead of a
|
|
366
|
-
generic empty-output message; a startup block is never recorded as a model
|
|
367
|
-
failure and never excludes the model from later runs.
|
|
368
|
-
|
|
369
|
-
The field is rejected for `external-cli` and `external-job` runners because they
|
|
370
|
-
do not host a Pi child extension. It also cannot be an object, `false`, an empty
|
|
371
|
-
value, or an inline allow/deny policy. Define the actual network and filesystem
|
|
372
|
-
rules in global `pi-sandbox` `profiles` instead.
|
|
373
|
-
|
|
374
|
-
A profile chosen by a project-scoped agent or project override is used only when
|
|
375
|
-
the host marks that project trusted. Otherwise the launch reports an actionable
|
|
376
|
-
trust error. In a headless child, accesses outside the profile's preconfigured
|
|
377
|
-
network/read/write rules are blocked; pi-sandbox does not use Permission System
|
|
378
|
-
or supervisor forwarding to ask the parent for an approval. See
|
|
379
|
-
[`pi-sandbox`'s README](https://github.com/xzzpig/pi-extensions/tree/main/packages/pi-sandbox#named-profiles-for-subagents)
|
|
380
|
-
for profile inheritance and merge rules.
|
|
381
|
-
|
|
382
|
-
### Permission profiles
|
|
383
|
-
|
|
384
|
-
Use `permission-profile: <name>` to select a named policy profile from the
|
|
385
|
-
**global-only** `profiles` registry in `pi-permission-system`'s config
|
|
386
|
-
(`<agentDir>/extensions/pi-permission-system/config.json`). It is a selector
|
|
387
|
-
only — the actual rules (tool scalars, `bash`/`mcp`/`skill`/`external_directory`
|
|
388
|
-
pattern maps, `'*'` fallback) live in that registry and always resolve from the
|
|
389
|
-
child's own global config:
|
|
390
|
-
|
|
391
|
-
```yaml
|
|
392
|
-
---
|
|
393
|
-
name: reviewer
|
|
394
|
-
description: Review changes without write access
|
|
395
|
-
permission-profile: reviewer
|
|
396
|
-
---
|
|
397
|
-
Review the requested change and report findings.
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
`pi-subagents` validates the scalar name (same grammar as sandbox profiles),
|
|
401
|
-
passes only that name to the child via the transient
|
|
402
|
-
`PI_SUBAGENT_PERMISSION_PROFILE` environment variable, and injects the
|
|
403
|
-
installed `pi-permission-system` extension into the child launch even when
|
|
404
|
-
`extensions` is an explicit allowlist, so the child's permission system applies
|
|
405
|
-
the selected profile. The env channel carries a bare validated name — raw
|
|
406
|
-
policy is never transmitted — and the rules are always read from the child's
|
|
407
|
-
own global config, so the profile means the same policy regardless of which
|
|
408
|
-
host launches the agent. Selection precedence inside the permission system is
|
|
409
|
-
env > project agent file > global agent file.
|
|
410
|
-
|
|
411
|
-
The launch fails closed when a profile is declared but `pi-permission-system`
|
|
412
|
-
is not installed, when a capability ceiling denies child extensions, or when
|
|
413
|
-
the runner is not a native Pi child (the field is rejected for `external-cli`
|
|
414
|
-
and `external-job` runners). At runtime, selecting an unknown profile or an
|
|
415
|
-
empty ruleset clamps that agent's `allow` rules to `ask` with an explicit
|
|
416
|
-
`Permission profile '<name>' could not be resolved` diagnostic — it never
|
|
417
|
-
silently degrades to the unselected baseline. An agent without the field keeps
|
|
418
|
-
its pre-change behavior exactly.
|
|
419
|
-
|
|
420
|
-
The profile merges between the project config and the agent's own `permission:`
|
|
421
|
-
block: patterns the profile does not mention keep the lower scopes' rules
|
|
422
|
-
(global denies survive), and `permission:` overrides the profile per pattern.
|
|
423
|
-
A profile selected by a **project** agent file participates only when the host
|
|
424
|
-
marks that project trusted.
|
|
425
|
-
|
|
426
|
-
## Context injection
|
|
427
|
-
|
|
428
|
-
By default the parent agent learns which agents exist only by calling `subagent({ action: "list" })`. Context injection pre-declares selected agents in the parent system prompt through a compact `<available_subagents>` block, so routing decisions can happen without a discovery round trip.
|
|
429
|
-
|
|
430
|
-
Two sources contribute, and the union is advertised:
|
|
431
|
-
|
|
432
|
-
1. Agent files that opt in with `injectToContext: true` in their frontmatter.
|
|
433
|
-
2. The `subagents.injectAgents` setting, which lists agent names (canonical names or aliases; builtins allowed):
|
|
434
|
-
|
|
435
|
-
```json
|
|
436
|
-
{
|
|
437
|
-
"subagents": {
|
|
438
|
-
"injectAgents": ["worker", "reviewer", "security-reviewer"]
|
|
439
|
-
}
|
|
440
|
-
}
|
|
441
|
-
```
|
|
442
|
-
|
|
443
|
-
Rendered block shape:
|
|
444
|
-
|
|
445
|
-
```text
|
|
446
|
-
<available_subagents>
|
|
447
|
-
The following pre-declared subagents are available.
|
|
448
|
-
Launch them with the subagent tool when a task matches their description.
|
|
449
|
-
|
|
450
|
-
- security-reviewer: Security review specialist
|
|
451
|
-
- worker: Implementation work, including approved oracle handoffs.
|
|
452
|
-
</available_subagents>
|
|
453
|
-
```
|
|
376
|
+
Hosts can import `registerRequiredChildExtensions` from `pi-subagents/required-child-extensions` and register `{ sessionId, extensions: [{ id, path }] }`. Paths resolve to existing files and are canonicalized into an immutable launch snapshot; bounded safe IDs appear in evidence instead of paths. One registration is allowed per parent session until its idempotent `dispose()` runs, normally on `session_shutdown`.
|
|
454
377
|
|
|
455
|
-
|
|
378
|
+
Required paths follow ordinary extension resolution and survive agent defaults and `extensions: []` across native foreground, detached, nested, and recovery launches. A `capabilityCeiling.denyExtensions` conflict or required load/provider-registration failure rejects before model resolution. External runners are excluded, and status/watch paths do not query the registry.
|
|
456
379
|
|
|
457
|
-
|
|
458
|
-
- **Only executable agents are advertised.** Disabled agents and agents restricted by the session capability ceiling are never injected.
|
|
459
|
-
- **Children never see it.** Spawned child sessions do not load the parent injection; fanout children can still call `{ action: "list" }`.
|
|
460
|
-
- **Unknown setting names are ignored** and reported by `/subagents-doctor` instead of failing startup.
|
|
461
|
-
- The block is appended only when it is not already present, so forked or resumed sessions never duplicate it.
|
|
380
|
+
When the completion guard would flag missing edits, a model intent arbiter can rescue only a confident read-only task. Foreground uses the parent model; native background uses the child attempt's existing model services after child shutdown. Ordinary completions do not invoke classification or resolve arbiter auth. Disabled arbitration (`PI_SUBAGENTS_LLM_INTENT_ARBITER=0`), unavailable model/auth, errors, ambiguous intent, and tasks over 8,000 characters keep the guard result. The classification prompt has a 10-second timeout; preceding auth and module loading are outside that bound. This does not change capability limits or the v1 contract's default-off guard and explicit missing-effect semantics.
|
|
462
381
|
|
|
463
382
|
## Per-agent persistent memory
|
|
464
383
|
|
|
@@ -521,7 +440,7 @@ How `tools` behaves:
|
|
|
521
440
|
|
|
522
441
|
An allowlisted name does not load the extension that registers it. Load that provider through `extensions`, `subagentOnlyExtensions`, a path-like `tools` entry, or (background children only) normal Pi extension discovery.
|
|
523
442
|
|
|
524
|
-
Ambient extensions depend on where the child runs.
|
|
443
|
+
Ambient extensions depend on where the child runs. Local foreground children are sessions inside the parent Pi process and never load the parent's ambient extensions; otherwise the parent would start a second copy of each ambient extension, including this one. Background children are sessions inside the detached runner process and load the ambient extensions unless the agent sets `extensions` or the capability ceiling denies extensions. Local foreground children do inherit the providers the parent's extensions registered (`pi.registerProvider`), so their models resolve without loading those extensions again. Pane-native remote foreground children instead use the remote machine's provider discovery and configuration. Agents that need MCP tools (`mcpDirectTools`, or MCP tools from an ambient adapter such as pi-mcp-adapter) must therefore run as background children (`async: true`). A foreground launch of such an agent fails with a diagnostic that says exactly that.
|
|
525
444
|
|
|
526
445
|
More rules:
|
|
527
446
|
|
|
@@ -610,15 +529,15 @@ Agent-local `skillPath` candidates never enter Pi's parent/global skills catalog
|
|
|
610
529
|
|
|
611
530
|
## The bundled pi-subagents skill
|
|
612
531
|
|
|
613
|
-
The package bundles a `pi-subagents` skill that is automatically available to the parent agent when the extension is installed. It is for the orchestrating parent only: child subagents never receive it, and their context is explicitly filtered to strip parent-only orchestration instructions.
|
|
532
|
+
The package bundles a `pi-subagents` skill that is automatically available to the parent agent when the extension is installed. Availability is not automatic routing or permission to delegate: the parent works directly unless the operator requests delegation in the current request or through applicable user/project instructions. Once authorized, use the smallest bounded child or workflow whose evidence, independent review, specialization, parallelism, or isolation benefit earns its overhead. It is for the orchestrating parent only: child subagents never receive it, and their context is explicitly filtered to strip parent-only orchestration instructions.
|
|
614
533
|
|
|
615
534
|
What it covers:
|
|
616
535
|
|
|
617
|
-
- **Delegation patterns**:
|
|
536
|
+
- **Delegation patterns**: how to select a bounded agent and single, parallel, scripted, or async shape after delegation is authorized, including fresh or forked context.
|
|
618
537
|
- **Prompt workflow recipes**: how to apply the packaged techniques directly with `subagent(...)` when the user describes the workflow in natural language instead of invoking a slash command. This includes parallel review, review-loop, parallel research, parallel context-build, parallel handoff-plan, gather-context-and-clarify, and parallel cleanup.
|
|
619
538
|
- **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers.
|
|
620
539
|
- **Safety boundaries**: child agents must not run subagents unless their resolved builtin tools explicitly include `subagent`, must not invent intercom targets, and must escalate unapproved decisions.
|
|
621
540
|
- **Intercom conventions**: when to ask vs send, and how parent-side supervisor/result delivery works through the native channel.
|
|
622
541
|
- **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action.
|
|
623
542
|
|
|
624
|
-
If you are writing an agent that
|
|
543
|
+
If you are writing an agent that has been asked to orchestrate subagents, the bundled skill helps it behave correctly without guessing the patterns. If you are a human user, you do not need to read it; the README and prompt shortcuts encode the same workflows in user-facing form.
|
package/docs/configuration.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
|
|
3
3
|
`pi-subagents` reads optional JSON config from `~/.pi/agent/extensions/subagent/config.json`. This page lists every key, plus the environment variables and the settings-file keys that affect config resolution.
|
|
4
4
|
|
|
5
|
-
Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `agentScanDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, `injectAgents`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, and `allow: ["inherit"]` permits the current parent model. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
|
|
5
|
+
Settings-level keys (`subagents.defaultModel`, `defaultProvider`, `defaultThinking`, `defaultExtensions`, `agentOverrides`, `machines`, `agentScanDirs`, `agentExcludeDirs`, `modelScope`, `disableThinking`, `disableBuiltins`, `injectAgents`, watchdog settings) live in Pi settings files, not this config file. `modelScope.agents.<name>` adds per-agent restrictions, and `allow: ["inherit"]` permits the current parent model. See [models.md](models.md), [agents.md](agents.md), and [watchdog.md](watchdog.md).
|
|
6
6
|
|
|
7
7
|
## Project root resolution (settings)
|
|
8
8
|
|
|
9
|
-
By default, project settings resolve from the nearest parent directory that contains `.pi` or `.agents`, preserving existing nested-project behavior. In monorepos or git worktrees where an incidental nested `.pi` directory should not shadow the repository-level config, set this in the repository root `.pi/settings.json`:
|
|
9
|
+
By default, project settings resolve from the nearest parent directory that contains `.pi` or `.agents`, preserving existing nested-project behavior. Discovery stops at the user home directory, including when the home is reached through a filesystem alias such as a symlink or Windows junction, so home-level `.pi` and `.agents` remain user configuration rather than project configuration. In monorepos or git worktrees where an incidental nested `.pi` directory should not shadow the repository-level config, set this in the repository root `.pi/settings.json`:
|
|
10
10
|
|
|
11
11
|
```json
|
|
12
12
|
{
|
|
@@ -32,17 +32,49 @@ Add recursive user or project agent roots with `subagents.agentScanDirs` in Pi s
|
|
|
32
32
|
|
|
33
33
|
Entries support `~` expansion. A single `*` path segment expands one directory level, so package-like folders can each expose an `agents/` directory. Missing directories are ignored. Fixed user/project agent directories still win over same-name agents from scan roots.
|
|
34
34
|
|
|
35
|
-
##
|
|
35
|
+
## Excluded agent directories (settings)
|
|
36
|
+
|
|
37
|
+
Prune directory subtrees from recursive agent-definition discovery with `subagents.agentExcludeDirs`:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"subagents": {
|
|
42
|
+
"agentExcludeDirs": ["~/.agents/plugins", "../.agents/plugins"]
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Entries are literal directory paths (no globs), supporting `~` and absolute paths. Relative paths resolve from the directory containing their settings file: the user agent config directory for user settings, or the project config directory (normally `.pi/`) for project settings. Thus `../.agents/plugins` in project `.pi/settings.json` excludes the project's legacy plugin subtree without excluding ordinary `.agents/*.md` agents.
|
|
48
|
+
|
|
49
|
+
User and nearest-project exclusions are combined for every discovery scope, including all-source diagnostics. They apply before traversal and definition reads; explicit scan roots, environment roots, and installed packages cannot re-include an excluded tree. Normalized and real-path containment also excludes symlink aliases without matching sibling directory prefixes. Settings changes invalidate cached discovery. Excluded agent trees are not fingerprinted; chain discovery keeps its own unchanged watches when it shares a directory. Skills, chains, and the extension's bundled builtin snapshot are outside this setting's scope.
|
|
50
|
+
|
|
51
|
+
## `modelResponseAliases`
|
|
52
|
+
|
|
53
|
+
In `~/.pi/agent/extensions/subagent/config.json` (top-level, not under `subagents`):
|
|
36
54
|
|
|
37
55
|
```json
|
|
38
56
|
{
|
|
39
|
-
"
|
|
40
|
-
"
|
|
57
|
+
"modelResponseAliases": {
|
|
58
|
+
"databricks-bedrock/ias-claude-opus-5": ["claude-opus-5"]
|
|
41
59
|
}
|
|
42
60
|
}
|
|
43
61
|
```
|
|
44
62
|
|
|
45
|
-
|
|
63
|
+
Optionally accept exact response model IDs for an exact provider-qualified launch. Keys use the resolved `provider/model` ID without its thinking suffix; values are arrays of non-empty response ID strings. Alias matching is exact and case-sensitive, with no fuzzy or suffix matching. Empty arrays add no accepted IDs; malformed declarations fail config loading.
|
|
64
|
+
|
|
65
|
+
This is your explicit assertion that the declared response IDs identify the requested model, not proof from model output. It does not rewrite the outgoing model or provider route, or bypass verification for other routes. Foreground and background runs capture this declaration for launch and retain it on revival, including when no aliases were declared. Changing config affects new independent runs, not the retained declaration. Without a matching declaration, existing strict verification remains unchanged.
|
|
66
|
+
|
|
67
|
+
For a native Pi `model_verification_failed` where your proxy accepts `claude-haiku-4-5` but reports `anthropic.claude-haiku-4-5-20251001-v1:0`, independently confirm your proxy's mapping, then configure:
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
{
|
|
71
|
+
"modelResponseAliases": {
|
|
72
|
+
"YOUR_PROVIDER/claude-haiku-4-5": ["anthropic.claude-haiku-4-5-20251001-v1:0"]
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Replace `YOUR_PROVIDER` with the resolved Pi provider ID. Keep the outgoing model alias unchanged. This native remedy already exists in v0.65.1; it does not infer equivalence from provider prefixes or dates. The built-in external `claude-code` adapter does not invoke this verifier or use this setting. If an external run shows this diagnostic, identify the installed version, resolved runner kind/adapter, and error location before applying a native remedy. Thanks to [sixtus](https://github.com/sixtus) for the concrete request-ID/response-ID example in [#1922](https://github.com/nicobailon/pi-subagents/issues/1922).
|
|
46
78
|
|
|
47
79
|
## `toolDescriptionMode`
|
|
48
80
|
|
|
@@ -50,7 +82,7 @@ Controls the duration, in milliseconds, for model exclusions. The default is `86
|
|
|
50
82
|
{ "toolDescriptionMode": "compact" }
|
|
51
83
|
```
|
|
52
84
|
|
|
53
|
-
Controls the parent-facing `subagent` tool description registered at startup. The default registers
|
|
85
|
+
Controls the parent-facing `subagent` tool description registered at startup. The default registers the compact execution/safety description plus separate `promptSnippet` and `promptGuidelines`. That metadata explains use after operator-authorized delegation; it does not route ordinary work to children or independently authorize delegation. Explicit `"compact"` uses the same description without that extra metadata; `"full"` adds workflow and management detail, also without split metadata. All modes retain the same flat parameter schema. Extended examples and recipes are available on demand through `action:"guide"` and the bundled pi-subagents skill; full mode is not an exhaustive manual. Count the separate default metadata as well as the tool definition when comparing prompt footprints.
|
|
54
86
|
|
|
55
87
|
`custom` reads `subagent-tool-description.md` from the project config directory, then from `~/.pi/agent/subagent-tool-description.md`. Missing, empty, unreadable, or oversized custom files fall back to the full description. Custom templates may use `{{fullDescription}}`, `{{compactDescription}}`, `{{safetyGuidance}}`, `{{agentDir}}`, and `{{projectConfigDir}}`; the safety guidance is always present so custom prose cannot remove the runtime guardrails. Restart Pi after changing the mode or custom file.
|
|
56
88
|
|
|
@@ -62,6 +94,8 @@ Controls the parent-facing `subagent` tool description registered at startup. Th
|
|
|
62
94
|
|
|
63
95
|
Controls the `subagent` tool result shown inline in chat. The default, `"rich"`, shows live child activity and expands to detailed output. `"summary"` keeps the inline result at one stable row for running, completed, failed, stopped, and paused runs; it does not animate, show elapsed time, preview child output, or change when Pi's expand key is pressed. FleetView remains available for live progress and detailed inspection.
|
|
64
96
|
|
|
97
|
+
This is one result row **per tool call**, not one panel per run; the call heading remains. Separate `status` calls for the same run remain separate historical transcript entries. Summary mode neither merges those calls nor changes cross-extension ordering. For a compact chat plus one live editor surface, see [Reducing status display noise](observability.md#reducing-status-display-noise).
|
|
98
|
+
|
|
65
99
|
## `mainWindowRenderer`
|
|
66
100
|
|
|
67
101
|
```json
|
|
@@ -150,7 +184,7 @@ Controls how resolved fork launches prepare the inherited session. The default `
|
|
|
150
184
|
|
|
151
185
|
Child-visible spilled items contain only the model summary and a stable `{ batchId, itemId }` recovery ref. Raw bodies and their digests, source entry ids, labels, sizes, and tool metadata go to a private `0600` sidecar next to the child session. This release does not add a recovery command or expose that payload to the child model.
|
|
152
186
|
|
|
153
|
-
Pruned forks keep the normal `parentSession` link, child cwd alignment, and fork thinking-block sanitization. Missing model or auth, invalid or incomplete summary JSON, budget overflow, recovery validation failure, and raw overflow leakage all stop the launch before child spawn. The extension never falls back to a full fork or refs-only context after a prune failure.
|
|
187
|
+
Pruned forks keep the normal `parentSession` link, child cwd alignment, and fork thinking-block sanitization (signed Anthropic thinking blocks are stripped; the child keeps its requested thinking level). Missing model or auth, invalid or incomplete summary JSON, budget overflow, recovery validation failure, and raw overflow leakage all stop the launch before child spawn. The extension never falls back to a full fork or refs-only context after a prune failure.
|
|
154
188
|
|
|
155
189
|
## `fleetView`
|
|
156
190
|
|
|
@@ -231,7 +265,9 @@ Forces depth-0 internal single, parallel, and chain runs into background mode an
|
|
|
231
265
|
{ "timeoutMs": 3600000 }
|
|
232
266
|
```
|
|
233
267
|
|
|
234
|
-
Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and workflowScript) and plain single-agent async runs whenever no call-level `timeoutMs`/`maxRuntimeMs` applies. For single-agent launches, selected agent frontmatter `timeoutMs` still wins. This only moves the *default*. Expiring this run-level deadline is terminal
|
|
268
|
+
Global default runtime deadline, in milliseconds, for subagent runs. It replaces the built-in 30-minute backstop for foreground launches (single, parallel, chain, and workflowScript) and plain single-agent async runs whenever no call-level `timeoutMs`/`maxRuntimeMs` applies. For single-agent launches, selected agent frontmatter `timeoutMs` still wins. This only moves the *default*. Expiring this run-level deadline is terminal.
|
|
269
|
+
|
|
270
|
+
This deadline bounds the whole run. The wait for a single model response is bounded separately by Pi's `httpIdleTimeoutMs` setting (default 300000; `0` disables it), which Pi applies both as the SDK request timeout and as the undici header/body idle timeout. Detached async runners read the same setting from `~/.pi/agent/settings.json` and the project `.pi/settings.json` for their own HTTP dispatcher, so a local model that queues or prefills for longer than five minutes needs `httpIdleTimeoutMs` raised or disabled in Pi settings, plus a `timeoutMs` long enough for the run.
|
|
235
271
|
|
|
236
272
|
Use it when foreground orchestration or plain async single-agent runs need a longer default than 30 minutes. It does not set async composite top-level deadlines, and it does not replace async fan-out child deadlines.
|
|
237
273
|
|
|
@@ -249,6 +285,16 @@ Without a configured value, Pi still applies a five-minute hard timeout to known
|
|
|
249
285
|
|
|
250
286
|
The tool timer tracks each active `toolCallId` separately and never extends the run-level deadline: when the remaining run budget is shorter, the ordinary run-level timeout wins. `contact_supervisor`, `intercom`, and `bg_wait` are exempt because their legitimate purpose can be to wait for a human, supervisor, or background run. Use hard tool timeouts only for wedge protection; an elapsed timeout is not a mutation-safe boundary. Configured values must be positive integers no greater than `2147483647`; invalid or out-of-range values are rejected with a visible error rather than silently ignored.
|
|
251
287
|
|
|
288
|
+
## `checkpointBeforeDeadlineMs`
|
|
289
|
+
|
|
290
|
+
```json
|
|
291
|
+
{ "checkpointBeforeDeadlineMs": 300000 }
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
Global default for the async single-agent `checkpointBeforeDeadlineMs` launch option. When an async single-agent run has a run-level deadline, the runner issues a best-effort "checkpoint and stop" steer to the child this many milliseconds before that deadline: finish the current tool call, report changed files, build/test state, remaining work, and commit/PR state, and start no new work. The steer uses the normal steering lifecycle at the child's next tool boundary, so its receipt (requested, routed, delivered) is visible in run status and events, and the ordinary `timeoutMs` kill still applies if the child does not stop.
|
|
295
|
+
|
|
296
|
+
An explicit `subagent` call value wins over this default. Choose a value at least as long as the child's longest expected tool call; a steer cannot land inside one. When the deadline leaves less than one second of run time before the checkpoint, the checkpoint is disarmed and the run behaves as if the option were absent. The global config value must be a positive integer no greater than `2147483647`; invalid values fail config loading rather than silently disabling the checkpoint.
|
|
297
|
+
|
|
252
298
|
## `globalConcurrencyLimit`
|
|
253
299
|
|
|
254
300
|
```json
|
|
@@ -279,7 +325,7 @@ Caps cumulative logical child admissions in one top-level run tree. The default
|
|
|
279
325
|
|
|
280
326
|
Inline or file-backed top-level workflow calls may set a positive safe-integer `maxSubagentSpawnsPerRun`; it overrides the environment and config for that workflow. Inherited nested budgets remain authoritative, and the override is not forwarded to child calls.
|
|
281
327
|
|
|
282
|
-
The budget counts single launches, expanded `tasks`/`count`, static chain steps and parallel groups, actual dynamic `expand` items, appended chain steps, workflow children, and nested child calls. Static and materialized dynamic groups are admitted atomically.
|
|
328
|
+
The budget counts single launches, expanded `tasks`/`count`, static chain steps and parallel groups, actual dynamic `expand` items, appended chain steps, workflow children, and nested child calls. Static and materialized dynamic groups are admitted atomically. Retained-child resume reuses the original logical child claim. Claims are never released or refunded. This cap is independent from the session-wide cumulative spawn budget and `globalConcurrencyLimit`.
|
|
283
329
|
|
|
284
330
|
## `maxActiveAsyncRunsPerSession`
|
|
285
331
|
|
|
@@ -362,7 +408,17 @@ Controls nested delegation when no stricter limit is inherited from the launchin
|
|
|
362
408
|
export PI_SUBAGENT_PI_BINARY=/path/to/pi-or-wrapper
|
|
363
409
|
```
|
|
364
410
|
|
|
365
|
-
Overrides the `pi` command pi-subagents spawns for
|
|
411
|
+
Overrides the `pi` command pi-subagents spawns for project panes and the profile model probe. On a supported Bun-compiled Pi host it also selects the detached background host executable. That executable must accept Pi's bootstrap arguments and supply its compatible embedded SDK and adjacent release resources; bare Bun is not a substitute. Empty or whitespace-only values are ignored. Failed launches are not retried with another runtime.
|
|
412
|
+
|
|
413
|
+
Foreground children remain sessions inside the parent. Npm background children retain their Node runner and host-package peer aliases; this variable does not turn npm Pi into a binary-backed runner. See [Standalone background execution](standalone-background.md) for the official tested target.
|
|
414
|
+
|
|
415
|
+
## `PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT`
|
|
416
|
+
|
|
417
|
+
```bash
|
|
418
|
+
export PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT=/path/to/pi-coding-agent-package
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Overrides host-package discovery for spawned children. Foreground CLI resolution uses this root to locate the `pi` CLI script, and the detached background runner uses it for jiti host resolution and peer-package aliases, so both child kinds agree on one host. It is consulted when argv-based automatic discovery cannot identify the host, such as a wrapper install or a non-standard layout. The value must be the root of a canonical `@earendil-works/pi-coding-agent` installation (the directory containing its `package.json`, with that package name); both child kinds still validate the package name and its peer packages from that install tree, so a package whose manifest carries a different name is rejected even with the override set. Empty or whitespace-only values are ignored.
|
|
366
422
|
|
|
367
423
|
## `intercomBridge`
|
|
368
424
|
|
|
@@ -381,7 +437,7 @@ Controls whether subagents receive runtime coordination instructions and whether
|
|
|
381
437
|
Fields:
|
|
382
438
|
|
|
383
439
|
- `mode`: default `always`; use `fork-only` to inject only for forked runs, or `off` to disable the bridge.
|
|
384
|
-
- `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated. Relative paths resolve from `~/.pi/agent/extensions/subagent/`.
|
|
440
|
+
- `instructionFile`: optional Markdown template replacing the default bridge instructions. `{orchestratorTarget}` is interpolated with the parent session target. Relative paths resolve from `~/.pi/agent/extensions/subagent/`. The default template does not name the session, because `contact_supervisor` resolves it from the child runtime config; a template that does name it ties `launchContractDigest` to the parent session, and launch-contract preflight then needs `orchestratorTarget` to match.
|
|
385
441
|
- `resultDelivery`: default `false`; set `true` only when an external listener consumes `subagent:result-intercom` and acknowledges the grouped completion payload. This is optional external result delivery, not native supervisor messaging. Enabled delivery waits for acknowledgement and reports acknowledgement failures. It does not change supervisor asks or progress updates.
|
|
386
442
|
|
|
387
443
|
Bridge activation requires a targetable current parent session id, which `pi-subagents` passes to children automatically. Native supervisor messaging does not require an external `pi-intercom` installation or per-agent extension allowlists: children use `contact_supervisor`, and parents use `subagent_supervisor` to inspect or reply. Agents can still use an external `intercom` tool when they explicitly request a provider that supplies it.
|
|
@@ -404,7 +460,7 @@ Each native worktree leaf is `{dedicatedRoot}/{projectName}/pi-worktree-{runId}-
|
|
|
404
460
|
{ "worktreeProvider": "auto", "worktreeBranchPrefix": "pi-subagents/" }
|
|
405
461
|
```
|
|
406
462
|
|
|
407
|
-
Selects the managed worktree allocator: `auto` (the default) uses Worktrunk when its machine-readable interface is available and otherwise falls back to Pi's native Git worktrees; `native` always uses Pi's Git implementation; and `worktrunk` fails closed when Worktrunk is unavailable or incompatible. A configured `worktreeBaseDir` (or `PI_SUBAGENTS_WORKTREE_DIR`) selects native allocation and cannot be combined with explicit `worktrunk`.
|
|
463
|
+
Selects the managed worktree allocator: `auto` (the default) uses Worktrunk when its machine-readable interface is available and otherwise falls back to Pi's native Git worktrees; `native` always uses Pi's Git implementation; and `worktrunk` fails closed when Worktrunk is unavailable or incompatible. On Windows, pi-subagents invokes Worktrunk through `git wt` to avoid Windows Terminal's conflicting `wt.exe` alias. A configured `worktreeBaseDir` (or `PI_SUBAGENTS_WORKTREE_DIR`) selects native allocation and cannot be combined with explicit `worktrunk`.
|
|
408
464
|
|
|
409
465
|
`worktreeBranchPrefix` is normalized as a Git ref namespace and defaults to `pi-subagents/`. Branch names include readable task/lane identity plus run and fan-out indexes. Pi continues to own setup hooks, launch, handoff/diff evidence, resume, and cleanup; Worktrunk is used only to allocate and report the worktree path.
|
|
410
466
|
|
|
@@ -421,6 +477,10 @@ Set `worktree` to `true` to make managed worktree isolation the default for laun
|
|
|
421
477
|
|
|
422
478
|
The hook runs once per created worktree. Paths must be absolute, `~/...`, or repo-relative; bare command names are rejected.
|
|
423
479
|
|
|
480
|
+
Setup command waits are nonblocking and cancellable through existing run controls. Existing run deadlines and the hook timeout still apply; there is no new setup timeout or configuration.
|
|
481
|
+
|
|
482
|
+
Setup commands, including Git hooks, must be finite and await all descendants before reporting success; do not start background services. Exit zero, natural pipe closure, complete bounded output, and valid JSON/path metadata are trusted completion for launch and cleanup—not observed process-tree proof. Violations are unsupported: protection against deleting a worktree with an undisclosed live descendant is not guaranteed. No additional Windows containment guarantee is provided.
|
|
483
|
+
|
|
424
484
|
stdin is a JSON object with `repoRoot`, `worktreePath`, `agentCwd`, `branch`, `index`, `runId`, and `baseCommit`. stdout must be one JSON object, for example:
|
|
425
485
|
|
|
426
486
|
```json
|
|
@@ -458,13 +518,17 @@ Automatic missions are enabled by default for ordinary launches with a task. Use
|
|
|
458
518
|
"spawnBudgetGrant": "confirm",
|
|
459
519
|
"scheduleCreate": "auto",
|
|
460
520
|
"stopRun": "auto",
|
|
461
|
-
"steerRun": "auto"
|
|
521
|
+
"steerRun": "auto",
|
|
522
|
+
"inspectorOpen": "auto",
|
|
523
|
+
"projectOpen": "confirm"
|
|
462
524
|
}
|
|
463
525
|
}
|
|
464
526
|
```
|
|
465
527
|
|
|
466
528
|
Each fixed action resolves to `"auto"`, `"confirm"`, or `"forbid"`. This is intentionally a small action map, not a generic policy language. Confirm-required control actions fail closed without an interactive UI.
|
|
467
529
|
|
|
530
|
+
`inspectorOpen` and `projectOpen` cover the `inspector.open` and `project.open` tool actions, which launch an external inspector host or a Herdr project pane. `inspector.open` only reaches a plugin that reports itself available, so it defaults to `"auto"`; `project.open` runs `herdr` (or `HERDR_BIN`) with no such check and opens a pane that hosts its own Pi session, so it defaults to `"confirm"`. Set `"projectOpen": "auto"` to restore the previous unprompted behavior. The policy applies to the tool actions; opening an inspector from the fleet TUI is already an explicit operator keypress and is unaffected.
|
|
531
|
+
|
|
468
532
|
## `artifactDir`
|
|
469
533
|
|
|
470
534
|
```json
|
|
@@ -509,6 +573,20 @@ Controls smart batching of async-completion notifications. When several backgrou
|
|
|
509
573
|
|
|
510
574
|
Native child tool permission rules. See [watchdog.md](watchdog.md#native-child-tool-permissions).
|
|
511
575
|
|
|
576
|
+
## `PI_SUBAGENT_CACHE_RETENTION`
|
|
577
|
+
|
|
578
|
+
Sets the prompt-cache retention tier for child sessions, overriding `PI_CACHE_RETENTION` for children only. Environment-only; there is no config key. Accepts the same values Pi accepts, normally `short` or `long`.
|
|
579
|
+
|
|
580
|
+
Anthropic prices a cache write by the retention it is asked for: the 1h tier costs more per write than the 5m one. A parent that keeps a long-lived conversation earns that back by surviving idle gaps, but children are short-lived and rarely idle long enough to claim the longer window, so on a wide fanout the higher write price is paid without the benefit:
|
|
581
|
+
|
|
582
|
+
```text
|
|
583
|
+
PI_CACHE_RETENTION=long PI_SUBAGENT_CACHE_RETENTION=short
|
|
584
|
+
```
|
|
585
|
+
|
|
586
|
+
Unset by default, so children inherit the parent's retention and behaviour is unchanged unless you opt in. Both spawned children (through the launch environment) and in-process children (through the session's own stream function) honour it; the in-process path scopes the value per session rather than mutating `process.env`, so a child cannot change retention for a parent turn streaming at the same time.
|
|
587
|
+
|
|
588
|
+
Provider-reported `cacheWrite1h` usage confirms which tier a request used: it matches `cacheWrite` on the 1h tier and is `0` on the short one.
|
|
589
|
+
|
|
512
590
|
## `PI_SUBAGENT_FS_RETRY_MAX_TOTAL_MS`
|
|
513
591
|
|
|
514
592
|
Caps the total time a single retried filesystem operation may sleep, in milliseconds. Environment-only; there is no config key.
|