@xzzpig/pi-subagents 0.1.0 → 0.3.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 +135 -0
- package/README.md +4 -0
- package/agents/reviewer.md +3 -4
- package/docs/agents.md +343 -0
- package/docs/configuration.md +395 -0
- package/docs/extension-api.md +308 -0
- package/docs/missions.md +121 -0
- package/docs/models.md +192 -0
- package/docs/observability.md +198 -0
- package/docs/tool-reference.md +343 -0
- package/docs/watchdog.md +176 -0
- package/docs/workflows.md +163 -0
- package/package.json +13 -11
- package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
- package/skills/pi-subagents/references/execution-controls.md +7 -7
- package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
- package/src/agents/agents.ts +53 -23
- package/src/agents/frontmatter.ts +7 -3
- package/src/agents/skills.ts +2 -9
- package/src/api/preflight.ts +1 -1
- package/src/api/project-panes.ts +30 -0
- package/src/extension/config.ts +54 -1
- package/src/extension/doctor.ts +40 -0
- package/src/extension/fanout-child.ts +5 -4
- package/src/extension/index.ts +114 -38
- package/src/extension/public-execution.ts +35 -4
- package/src/extension/rpc.ts +10 -15
- package/src/extension/schemas.ts +33 -11
- package/src/extension/subagent-guide.ts +39 -0
- package/src/extension/tool-description.ts +38 -18
- package/src/inspectors/herdr/actions.ts +11 -2
- package/src/inspectors/herdr/inspector-runner.ts +16 -3
- package/src/inspectors/herdr/project-panes.ts +459 -63
- package/src/intercom/intercom-bridge.ts +7 -2
- package/src/intercom/native-supervisor-channel.ts +102 -4
- package/src/missions/actions.ts +25 -2
- package/src/missions/lifecycle.ts +25 -9
- package/src/missions/store.ts +89 -7
- package/src/missions/types.ts +33 -0
- package/src/missions/workflow-state.ts +25 -15
- package/src/runs/background/active-async-capacity.ts +431 -0
- package/src/runs/background/active-run-index.ts +46 -0
- package/src/runs/background/async-execution.ts +158 -71
- package/src/runs/background/async-job-tracker.ts +297 -133
- package/src/runs/background/async-resume.ts +37 -5
- package/src/runs/background/async-status.ts +39 -5
- package/src/runs/background/chain-append.ts +33 -15
- package/src/runs/background/completion-replay.ts +267 -0
- package/src/runs/background/control-channel.ts +95 -54
- package/src/runs/background/fleet-view.ts +18 -5
- package/src/runs/background/owned-process-tree.ts +104 -0
- package/src/runs/background/process-terminal.ts +17 -3
- package/src/runs/background/result-watcher.ts +113 -10
- package/src/runs/background/resume-guidance.ts +53 -0
- package/src/runs/background/retained-children.ts +14 -6
- package/src/runs/background/run-status.ts +119 -5
- package/src/runs/background/scheduled-runs.ts +25 -1
- package/src/runs/background/stale-run-reconciler.ts +12 -24
- package/src/runs/background/subagent-runner.ts +127 -41
- package/src/runs/background/subagent-wait.ts +5 -2
- package/src/runs/background/wait-completions.ts +39 -5
- package/src/runs/background/wait-subscriptions.ts +21 -5
- package/src/runs/foreground/async-dismiss-action.ts +85 -0
- package/src/runs/foreground/async-steering-action.ts +7 -8
- package/src/runs/foreground/chain-execution.ts +40 -2
- package/src/runs/foreground/execution.ts +97 -19
- package/src/runs/foreground/foreground-control.ts +12 -0
- package/src/runs/foreground/foreground-history.ts +137 -0
- package/src/runs/foreground/prompt-audit.ts +172 -0
- package/src/runs/foreground/subagent-executor.ts +1274 -243
- package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
- package/src/runs/shared/acceptance.ts +13 -4
- package/src/runs/shared/completion-guard.ts +17 -1
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/llm-intent-arbiter.ts +302 -0
- package/src/runs/shared/model-fallback.ts +8 -4
- package/src/runs/shared/model-scope.ts +12 -2
- package/src/runs/shared/parallel-utils.ts +3 -0
- package/src/runs/shared/pi-args.ts +44 -1
- package/src/runs/shared/run-fanout-budget.ts +280 -0
- package/src/runs/shared/single-output.ts +4 -2
- package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
- package/src/runs/shared/task-intent.ts +19 -3
- package/src/runs/shared/worktree.ts +20 -7
- package/src/shared/agent-stream-options.ts +5 -0
- package/src/shared/artifacts.ts +17 -21
- package/src/shared/display-text.ts +150 -0
- package/src/shared/file-coalescer.ts +9 -0
- package/src/shared/fork-context.ts +13 -0
- package/src/shared/formatters.ts +4 -6
- package/src/shared/node-executable.ts +21 -0
- package/src/shared/prompt-resources.ts +51 -0
- package/src/shared/settings.ts +15 -2
- package/src/shared/types.ts +158 -4
- package/src/shared/utf8.ts +11 -0
- package/src/shared/utils.ts +46 -34
- package/src/slash/prompt-workflows.ts +2 -15
- package/src/slash/slash-commands.ts +22 -2
- package/src/tui/fleet-status.ts +29 -17
- package/src/tui/fleet-transcript.ts +1 -48
- package/src/tui/fleet.ts +362 -37
- package/src/tui/render.ts +235 -71
- package/src/watchdog/change-signature.ts +4 -3
- package/src/watchdog/permission-arbiter.ts +2 -1
- package/src/watchdog/review.ts +4 -3
- package/src/workflows/chat-progress.ts +8 -2
- package/src/workflows/scripted-workflow.ts +273 -20
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,141 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.3.0] - 2026-08-14
|
|
6
|
+
|
|
7
|
+
### Changed
|
|
8
|
+
- Synced the fork with upstream pi-subagents v0.49.0 while preserving local compatibility fixes.
|
|
9
|
+
|
|
10
|
+
## [0.49.0] - 2026-08-13
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
- Run a single child with `{ agent, task? }` when a full workflow script is not needed (#1059).
|
|
14
|
+
- Adjust FleetView spacing and collapsed result height from the main window. Thanks to @pierre-mgmt for #1048.
|
|
15
|
+
- Inspect async run state with `debug.run`, without exposing prompts, secrets, or transcripts (#1037).
|
|
16
|
+
- Let builtin role overrides keep Pi's normal tools and extensions with `tools: "inherit"`. Thanks to @estanexanavsem for #1047 and @davidarny for #1049.
|
|
17
|
+
- Add simple terminal examples for FleetView, the async widget, and inline tool display. Thanks to @czottmann for #1050.
|
|
18
|
+
|
|
19
|
+
### Changed
|
|
20
|
+
- Clean up active-run limits and artifact packaging code without changing behavior.
|
|
21
|
+
|
|
22
|
+
### Fixed
|
|
23
|
+
- Trust live Herdr session roots only when the parent executor registered them for that async run.
|
|
24
|
+
- Let a workflow child disable the intercom bridge for one run with `intercomBridge: { mode: "off" }`, while normal async completion still works. Thanks to @jaudiger for #1072.
|
|
25
|
+
- Recover sibling children after a detached workflow fails (#1066).
|
|
26
|
+
- Show child session transcripts in standalone Herdr inspectors when the transcript is in a trusted session folder (#1069).
|
|
27
|
+
- Keep watchdog reviews, permission checks, Prompt Audit rewriting, and completion intent checks on the authenticated provider stream across the Pi 0.81 and 0.84 APIs. Thanks to @nuzayets for #1067.
|
|
28
|
+
- Mark children stopped by a parent workflow as stopped, not failed, and keep the stop reason (#1060).
|
|
29
|
+
- Keep subagent artifacts and automatic mission records out of project worktrees by default, so read-only workflows leave the tree clean (#1062).
|
|
30
|
+
- Make parents wait at dependency barriers after async launches, so child results are available before dependent work continues. Thanks to @exuanbo for #1045.
|
|
31
|
+
- Keep wait callers alive for intercom replies instead of reviving a detached wrapper. Thanks to @yayamaz for #1053.
|
|
32
|
+
- Keep workflow summary reports separate from child reports, and reject report path collisions before launch (#1038).
|
|
33
|
+
- Accept no-edit implementation challenge passes when the writer says the current solution is already best (#1054).
|
|
34
|
+
- Make the mutation guard safer for LLM intent checks, long tasks, and provider authentication. Thanks to @MarcusNeufeldt for #1044.
|
|
35
|
+
- Launch Herdr inspector panes with Node when Pi runs as a standalone executable. Thanks to @kevinpita for #1051.
|
|
36
|
+
- Sanitize async, nested, and result transcript output before showing it in terminal views. Thanks to @riesbri for #1046.
|
|
37
|
+
|
|
38
|
+
## [0.48.0] - 2026-08-13
|
|
39
|
+
|
|
40
|
+
### Added
|
|
41
|
+
- Limit each run to 64 child launches by default, so accidental fan-out loops stop before they create too many children. Thanks to @asjer for #1031.
|
|
42
|
+
- Add an optional limit for how many top-level async runs one session can have active at the same time. Fleet, status, RPC, and doctor now show the limit and current usage. Thanks to @asjer for #1029.
|
|
43
|
+
- Add a live Prompt Audit drawer to Fleet for foreground children owned by the current session. It shows the prompt on screen without saving it to status files, history, transcripts, metadata, results, progress, or run artifacts (#1021).
|
|
44
|
+
- Add a global `timeoutMs` setting for default run deadlines on foreground launches and plain single-agent async runs. It applies when a launch or agent does not set its own timeout, and it prevents long foreground fan-outs from falling back to the built-in 30-minute limit. Composite async runs stay unbounded at the top level. Thanks to @shaharmor for #1018.
|
|
45
|
+
- Add `PI_SUBAGENT_TASK_DELIVERY=auto|file` for hosts that block child processes when the task text appears in the command line. File mode writes the task to a temporary `task.md` and passes that path instead. Thanks to @yanqianglu for #1028.
|
|
46
|
+
- Retry with file-based task delivery after a child exits with no activity, which helps recover from endpoint protection tools that block long command lines. Thanks to @yanqianglu for #1028.
|
|
47
|
+
|
|
48
|
+
### Fixed
|
|
49
|
+
- Open Fleet Prompt Audit with the original task visible by default, and show a short task summary in the normal Fleet detail pane (#1021).
|
|
50
|
+
- Use the full task text when caching LLM intent decisions, so similar tasks with the same prefix cannot share the wrong answer.
|
|
51
|
+
- Stop async Pi writer processes as full process groups, and only mark process cleanup as proven after the process tree has actually exited. Thanks to @asjer for #1030.
|
|
52
|
+
- Explain when a mission belongs to another worktree, including both the current project root and the mission directory (#1024).
|
|
53
|
+
- Keep the configured output reference when explicit acceptance rejects a foreground child, so useful reports remain available (#1023).
|
|
54
|
+
- Reject worktree base directories inside the agent extensions directory, including symlinked paths (#1014).
|
|
55
|
+
- Make unnamed intercom fallback targets match pi-intercom's registered name length, so subagents without a custom session name can still reach their parent. Thanks to @mystery4f for #1017.
|
|
56
|
+
- Stop treating phrases like "must-fix items" or "should-fix tests" as instructions to edit files during read-only review tasks. Thanks to @MarcusNeufeldt for #1020.
|
|
57
|
+
- Add an optional LLM check before the mutation guard fails a foreground single, parallel, or chain child that made no edits. If the task was actually read-only, the run now completes instead of failing. Thanks to @MarcusNeufeldt for #1020.
|
|
58
|
+
- Accept empty strings inside acceptance-report string arrays instead of rejecting the full report. Thanks to @hjiang for #1015.
|
|
59
|
+
- Let single external-CLI workflow children start without inheriting a Pi model, so model-less external runners do not fail preflight. Thanks to @twosunnus for #1016.
|
|
60
|
+
|
|
61
|
+
## [0.47.1] - 2026-08-12
|
|
62
|
+
|
|
63
|
+
### Fixed
|
|
64
|
+
- Honor configured artifact cleanup retention days and let `0` disable artifact cleanup. Thanks to @elecnix for #1012.
|
|
65
|
+
- Add a display-only dismiss action for reload-recovered running workflows without claiming or attempting to stop their work (#1010).
|
|
66
|
+
- Stop the bundled reviewer from inheriting chain-only plan/progress reads in ad-hoc review runs. Thanks to @Ostii for #1000.
|
|
67
|
+
- Remove mutation-capable tools from the bundled reviewer so read-only review lanes have a hard launch-time tool boundary (#1007).
|
|
68
|
+
- Show the requested child agent in workflow started trace entries. Thanks to @albertgwo for #1001.
|
|
69
|
+
|
|
70
|
+
## [0.47.0] - 2026-08-11
|
|
71
|
+
|
|
72
|
+
### Changed
|
|
73
|
+
- Avoid fully parsing stale cross-session result files during watcher recovery and reduce healthy watcher safety scans.
|
|
74
|
+
- Index active async runs so status restoration no longer scans all historical run directories.
|
|
75
|
+
- Refresh active async job state from filesystem events while reserving polling for slow liveness repair.
|
|
76
|
+
- Add optional strict model-scope enforcement that rejects inherited and fallback models outside the configured allowlist. Thanks to @antonioc-cl for #995.
|
|
77
|
+
- Trim legacy chain-control schema fields and guidance by default, saving 1,319 `o200k_base` tokens from the serialized default tool schema plus description versus `legacyChainControls: true`. Thanks to @tajquitgenius for #977.
|
|
78
|
+
- Move project-scoped pi-subagents storage from `.pi-subagents/` to `.pi/subagents/` for cleaner project roots. Thanks to @yceachan for #971.
|
|
79
|
+
- Clarify the accepted mission launch object contract for tool callers.
|
|
80
|
+
- Reduce repeated async status parsing, workflow trace projection, and constrained widget rendering work.
|
|
81
|
+
- Coalesce rapid running-status writes while keeping terminal and attention status changes durable immediately.
|
|
82
|
+
- Keep parsed async statuses cached beyond 50 runs while preserving per-read freshness checks. Thanks to @bcanvural for #982.
|
|
83
|
+
- Prefer native control inbox watchers over per-process 250 ms polling, with polling retained as a fallback.
|
|
84
|
+
|
|
85
|
+
### Fixed
|
|
86
|
+
- Omit missing configured read files from child task instructions.
|
|
87
|
+
- Stabilize steering recovery budget coverage around the confirmed paused handoff.
|
|
88
|
+
- Keep timeout-sensitive async acceptance verification coverage off Windows CI where signal delivery is intermittent.
|
|
89
|
+
- Retry transient Windows mission state lock creation failures and stabilize no-session steering recovery coverage.
|
|
90
|
+
- Keep async widget running glyphs moving while children are quiet but active. Thanks to @bcanvural for #983.
|
|
91
|
+
- Let active-session workflows live-steer their workflow-owned foreground children by child or unique workflow identity. Thanks to @youlikemodernart for #988.
|
|
92
|
+
- Accept persisted async recovery descriptors that include internal turn-budget state fields (#985).
|
|
93
|
+
- Add a 30-minute default wall-clock timeout to async children while keeping async composite parents unbounded by default. Thanks to @forrestbthomas for #978 and #979.
|
|
94
|
+
- Keep tool argument previews on one physical terminal line so live widget updates do not leave stacked terminal frames. Thanks to @xz-dev for #972.
|
|
95
|
+
- Recover durable async completions when a healthy native result watcher misses a filesystem event. Thanks to @xz-dev for #973.
|
|
96
|
+
|
|
97
|
+
## [0.46.0] - 2026-08-11
|
|
98
|
+
|
|
99
|
+
### Added
|
|
100
|
+
- Add `prompts.render(ref, vars?)` to `workflowScript` for explicitly scoped package, user, and project prompt fragments with simple `{{name}}` interpolation (#960).
|
|
101
|
+
- Expose a versioned `pi-subagents/project-panes` TypeScript API so other Pi extensions can deterministically open, inspect, and close project-owned Herdr panes without invoking the model-facing `subagent` tool. The structured status includes bounded pane runtime state and an opt-in idle-only close guard; Pi project trust remains an explicit human verification step. Thanks to @wiizard-chen for #949.
|
|
102
|
+
- Preserve short-lived completion replay records and bounded output archives so waits can recover consumed async result details after watcher delivery or restart.
|
|
103
|
+
- Add `subagent({ action: "guide" })` and `/subagents-guide [topic]` to read current-version packaged guides.
|
|
104
|
+
- Persist workflow child attempts, status heartbeats, session paths, and artifacts in their enclosing mission, and add explicit mission decision resolution.
|
|
105
|
+
|
|
106
|
+
### Fixed
|
|
107
|
+
- Suspend subagent status widgets during automatic compaction to prevent duplicate terminal frames.
|
|
108
|
+
- Make live foreground workflow children visible as workflow-owned Fleet rows, route Herdr inspection to their workflow parent, and report their active and needs-attention state to Herdr. Thanks to @lukechen526 for #965.
|
|
109
|
+
- Wait for retained-child resumes inside `workflowScript` to finish and return completed output before the script continues (#961).
|
|
110
|
+
- Keep fork-context workflow children inside their managed worktree by aligning the persisted child session cwd before launch. Thanks to @flopsi for #953.
|
|
111
|
+
- Show the resolved child agent in async workflow status while keeping the workflow key as its stable label. Thanks to @albertgwo for #955.
|
|
112
|
+
- Reject workflow scripts that finish with unawaited child launches and name every launch that was aborted. Thanks to @zig-zag-zig for #957.
|
|
113
|
+
- Reject mismatched completion replay archive paths so stale replay cleanup cannot delete another run's saved output archive.
|
|
114
|
+
- Keep `git-root` project agent and package discovery stable when incidental `.pi` state appears in a nested linked worktree. Thanks to @klajdo-f for #950.
|
|
115
|
+
- Read skill descriptions from YAML block scalars instead of exposing their markers. Thanks to @ashlineldridge for #945.
|
|
116
|
+
- Collapse repeated subagent status snapshots in live widgets so status polling does not overflow the chat.
|
|
117
|
+
- Give invalid `subagent` actions safe next steps and typo suggestions without suggesting destructive actions for ambiguous input.
|
|
118
|
+
- Let the Fleet inspector use extension-local keybindings for terminals that intercept navigation keys. Thanks to @epheien for #940.
|
|
119
|
+
- Restore completed foreground children from a compact Fleet history index after session resume. Thanks to @epheien for #946.
|
|
120
|
+
- Compact noisy repeated subagent live-output lines and bound workflow live-card rows so progress stays readable in the TUI (#947).
|
|
121
|
+
|
|
122
|
+
## [0.45.2] - 2026-08-10
|
|
123
|
+
|
|
124
|
+
### Fixed
|
|
125
|
+
- Tell parents to revive resumable failed async runs before reporting failure or launching a replacement. Thanks to @Livan-pro for #938.
|
|
126
|
+
- Persist the actual agent and session file for workflow children when they start so their sessions can resume after a parent restart. Thanks to @Livan-pro for #932.
|
|
127
|
+
- Retry steering requests that remain pending after manual compaction and fail unresolved requests at shutdown. Thanks to @jtac for #933.
|
|
128
|
+
- Omit undefined object fields from `workflowScript` return values so completed `runs.all` results are not discarded when callers include unsupported fields such as `status` (#930).
|
|
129
|
+
- Keep child steering inbox `auto` requests queued between `agent_end` and `agent_settled` so settlement-time guidance is not sent as an idle prompt too early. Thanks to @jtac for #928.
|
|
130
|
+
|
|
131
|
+
## [0.45.1] - 2026-08-09
|
|
132
|
+
|
|
133
|
+
### Changed
|
|
134
|
+
- Simplified async workflow activity projection and its regression test to reuse canonical status types.
|
|
135
|
+
|
|
136
|
+
### Fixed
|
|
137
|
+
- Add actionable guidance when Markdown fence backticks make a `workflowScript` invalid JavaScript.
|
|
138
|
+
- Prevent async interrupt requests from signaling unverified runner PIDs, including the shared host PID stored by workflows. Thanks to @kdasme for #925.
|
|
139
|
+
|
|
5
140
|
## [0.45.0] - 2026-08-09
|
|
6
141
|
|
|
7
142
|
### Added
|
package/README.md
CHANGED
|
@@ -93,6 +93,8 @@ In the TUI, a persistent FleetView below the editor keeps active work visible. `
|
|
|
93
93
|
|
|
94
94
|
Details, keybindings, and the machine-readable run artifacts are in [Observability](https://github.com/nicobailon/pi-subagents/blob/main/docs/observability.md).
|
|
95
95
|
|
|
96
|
+
For bounded orchestration, `maxSubagentSpawnsPerRun` limits cumulative logical children in one run tree. It defaults to 64 and stays separate from active concurrency and the session-wide cumulative spawn budget. See [Configuration](https://github.com/nicobailon/pi-subagents/blob/main/docs/configuration.md#maxsubagentspawnsperrun).
|
|
97
|
+
|
|
96
98
|
## If something feels off
|
|
97
99
|
|
|
98
100
|
```text
|
|
@@ -101,6 +103,8 @@ Details, keybindings, and the machine-readable run artifacts are in [Observabili
|
|
|
101
103
|
|
|
102
104
|
or ask: "Check whether subagents and intercom are set up correctly."
|
|
103
105
|
|
|
106
|
+
For installed-version help, use `/subagents-guide [topic]` or `subagent({ action: "guide", topic: "workflows" })`. The default topic is `overview`; available topics are `overview`, `workflows`, `agents`, `missions`, `observability`, `tool-reference`, `configuration`, `models`, `watchdog`, and `extension-api`.
|
|
107
|
+
|
|
104
108
|
## Documentation
|
|
105
109
|
|
|
106
110
|
The full reference lives in `docs/`:
|
package/agents/reviewer.md
CHANGED
|
@@ -1,12 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: reviewer
|
|
3
3
|
description: Versatile review specialist for code diffs, plans, proposed solutions, codebase health, and PR/issue validation
|
|
4
|
-
tools: read, grep, find, ls,
|
|
4
|
+
tools: read, grep, find, ls, intercom
|
|
5
5
|
thinking: high
|
|
6
6
|
systemPromptMode: replace
|
|
7
7
|
inheritProjectContext: true
|
|
8
8
|
inheritSkills: false
|
|
9
|
-
defaultReads: plan.md, progress.md
|
|
10
9
|
---
|
|
11
10
|
|
|
12
11
|
You are a disciplined review subagent. Your job is to inspect, evaluate, and report findings with evidence. You do not guess; you verify from the code, tests, docs, or requirements.
|
|
@@ -51,9 +50,9 @@ Review a PR or issue by understanding the context, then verifying:
|
|
|
51
50
|
- Tests and docs are updated as needed.
|
|
52
51
|
|
|
53
52
|
## Working rules
|
|
54
|
-
- Read the plan
|
|
53
|
+
- Read the relevant files first. Read plan and progress when the task supplies them.
|
|
55
54
|
- Repo-local `progress.md` files are allowed scratch/memory files. Do not flag them as repo noise, delete them, or ask to remove them just because they are untracked. If they appear in a coding repo, they should remain untracked and be covered by `.gitignore`.
|
|
56
|
-
-
|
|
55
|
+
- Do not use shell commands or write files. Report any test or Git command that a supervisor must run.
|
|
57
56
|
- Do not invent issues. Only report problems you can justify from evidence.
|
|
58
57
|
- Prefer small corrective edits over broad rewrites.
|
|
59
58
|
- If everything looks good, say so plainly.
|
package/docs/agents.md
ADDED
|
@@ -0,0 +1,343 @@
|
|
|
1
|
+
# Agents
|
|
2
|
+
|
|
3
|
+
An agent is a markdown file: YAML frontmatter on top, a system prompt below. The frontmatter defines the specialist that runs in the child Pi process.
|
|
4
|
+
|
|
5
|
+
```yaml
|
|
6
|
+
---
|
|
7
|
+
name: scout
|
|
8
|
+
description: Fast codebase recon
|
|
9
|
+
tools: read, grep, find, ls
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
Your system prompt goes here.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Where agents live
|
|
16
|
+
|
|
17
|
+
Lowest to highest priority:
|
|
18
|
+
|
|
19
|
+
| Scope | Path |
|
|
20
|
+
|-------|------|
|
|
21
|
+
| Builtin | `~/.pi/agent/extensions/subagent/agents/` |
|
|
22
|
+
| Installed package | `package.json` `pi-subagents.agents` or `pi.subagents.agents` |
|
|
23
|
+
| User | `~/.pi/agent/agents/**/*.md` |
|
|
24
|
+
| Project | Project config `agents/**/*.md` (`.pi/agents/**/*.md` in standard Pi) |
|
|
25
|
+
|
|
26
|
+
Discovery notes:
|
|
27
|
+
|
|
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
|
+
- Nested subdirectories are discovered recursively. `.chain.md` files do not define agents.
|
|
30
|
+
- 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.
|
|
31
|
+
- Use `agentScope: "user" | "project" | "both"` to control discovery. `both` is the default, and project definitions win runtime-name collisions.
|
|
32
|
+
|
|
33
|
+
## Builtin agents
|
|
34
|
+
|
|
35
|
+
Builtins load at the lowest priority, so a user or project agent with the same name overrides them. They do not pin a provider model; they inherit your current Pi default model unless you set `subagents.defaultModel` or `subagents.agentOverrides.<name>.model` (see [models.md](models.md)).
|
|
36
|
+
|
|
37
|
+
| Agent | Use it when you want... |
|
|
38
|
+
|-------|--------------------------|
|
|
39
|
+
| `scout` | Fast local codebase recon: relevant files, entry points, data flow, risks, and where another agent should start. |
|
|
40
|
+
| `researcher` | Web/docs research with sources: official docs, specs, benchmarks, recent changes, and a concise research brief. |
|
|
41
|
+
| `worker` | Implementation work, including approved oracle handoffs. It edits files, validates, and escalates unapproved decisions instead of guessing. |
|
|
42
|
+
| `reviewer` | Code review and small fixes. It checks the implementation against the task/plan, tests, edge cases, and simplicity. |
|
|
43
|
+
| `oracle` | A second opinion before acting. It challenges assumptions, catches drift, and recommends the safest next move without editing. |
|
|
44
|
+
| `delegate` | A lightweight general delegate when you want a child agent that behaves close to the parent session. |
|
|
45
|
+
|
|
46
|
+
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.
|
|
47
|
+
|
|
48
|
+
`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.
|
|
49
|
+
|
|
50
|
+
The `researcher` builtin uses `web_search`, `fetch_content`, and `get_search_content`. Those require [pi-web-access](https://github.com/nicobailon/pi-web-access):
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
pi install npm:pi-web-access
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
## Overriding builtins
|
|
57
|
+
|
|
58
|
+
You can override selected builtin fields without copying the whole agent. Overrides live in settings:
|
|
59
|
+
|
|
60
|
+
- User: `~/.pi/agent/settings.json`
|
|
61
|
+
- Project: project config settings file (`.pi/settings.json` in standard Pi)
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"subagents": {
|
|
66
|
+
"agentOverrides": {
|
|
67
|
+
"reviewer": {
|
|
68
|
+
"description": "Independent review tier",
|
|
69
|
+
"inheritProjectContext": false
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Supported override fields: `description`, `model`, `fallbackModels`, `thinking`, `systemPromptMode`, `inheritProjectContext`, `inheritSkills`, `defaultContext`, `acceptanceRole`, `disabled`, `skills`, `tools`, and `systemPrompt`.
|
|
77
|
+
|
|
78
|
+
- `description` replaces the discovered description for builtin and custom agents, which lets list output show deployment-specific routing or model metadata.
|
|
79
|
+
- Use `defaultContext: false` or `acceptanceRole: false` to clear an inherited override.
|
|
80
|
+
- Use `tools: "inherit"` on a builtin when that one role should omit its bundled tool allowlist and receive Pi's normal builtins and ambient extensions. This keeps strict tools as the default for other builtins.
|
|
81
|
+
- Project overrides beat user overrides.
|
|
82
|
+
- Matching user and project agents also receive override fields that their frontmatter leaves unset, so a shared project config agent can keep the persona while local settings choose the model.
|
|
83
|
+
|
|
84
|
+
Disable and restore:
|
|
85
|
+
|
|
86
|
+
- `disabled: true` hides a builtin from runtime discovery and agent-facing `subagent({ action: "list" })` output.
|
|
87
|
+
- `subagents.disableBuiltins: true` disables all builtins at once.
|
|
88
|
+
- `subagent({ action: "disable", agent: "reviewer" })` writes the override without editing settings by hand; `subagent({ action: "enable", agent: "reviewer" })` removes it.
|
|
89
|
+
- `subagent({ action: "eject", agent: "reviewer" })` copies a bundled builtin or package agent verbatim into the user or project agent dir (default `user`) as an editable custom file that shadows the original.
|
|
90
|
+
- `subagent({ action: "reset", agent: "reviewer" })` deletes the scope's custom agent file and/or settings override entry, restoring the bundled default. It refuses if no bundled default exists (use `delete` for purely custom agents).
|
|
91
|
+
|
|
92
|
+
`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.
|
|
93
|
+
|
|
94
|
+
## Prompt assembly
|
|
95
|
+
|
|
96
|
+
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.
|
|
97
|
+
|
|
98
|
+
Use these fields when an agent should see more:
|
|
99
|
+
|
|
100
|
+
| Field | Effect |
|
|
101
|
+
|-------|--------|
|
|
102
|
+
| `systemPromptMode: append` | Append the agent prompt to Pi's normal base prompt. |
|
|
103
|
+
| `inheritProjectContext: true` | Keep inherited project instructions from files like `AGENTS.md` and `CLAUDE.md`. |
|
|
104
|
+
| `inheritSkills: true` | Let the child see Pi's discovered skills catalog. |
|
|
105
|
+
| `defaultContext: fork` | Use forked session context when a launch omits `context`; explicit `context: "fresh"` still wins. |
|
|
106
|
+
|
|
107
|
+
Builtin agents opt into project instruction inheritance by default so they follow repo-specific rules out of the box. `delegate` also uses append mode because its job is orchestration inside the parent workflow.
|
|
108
|
+
|
|
109
|
+
## Frontmatter reference
|
|
110
|
+
|
|
111
|
+
A full example:
|
|
112
|
+
|
|
113
|
+
```yaml
|
|
114
|
+
---
|
|
115
|
+
name: scout
|
|
116
|
+
# Optional: registers this as code-analysis.scout while preserving name: scout
|
|
117
|
+
package: code-analysis
|
|
118
|
+
description: Fast codebase recon
|
|
119
|
+
aliases: explorer, code-scout
|
|
120
|
+
tools: read, grep, find, ls, bash, mcp:chrome-devtools
|
|
121
|
+
extensions:
|
|
122
|
+
subagentOnlyExtensions: ./tools/child-only-search.ts
|
|
123
|
+
model: claude-haiku-4-5
|
|
124
|
+
fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
|
|
125
|
+
thinking: high
|
|
126
|
+
systemPromptMode: replace
|
|
127
|
+
inheritProjectContext: false
|
|
128
|
+
inheritSkills: false
|
|
129
|
+
skills: safe-bash, review-checklist
|
|
130
|
+
skillPath: ./skills, ../shared-skills
|
|
131
|
+
output: context.md
|
|
132
|
+
defaultReads: context.md
|
|
133
|
+
defaultProgress: true
|
|
134
|
+
async: true
|
|
135
|
+
timeoutMs: 900000
|
|
136
|
+
turnBudget: {"maxTurns":20,"graceTurns":2}
|
|
137
|
+
acceptance: {"level":"none","reason":"lightweight lookup"}
|
|
138
|
+
acceptanceRole: read-only
|
|
139
|
+
completionGuard: false
|
|
140
|
+
interactive: true
|
|
141
|
+
maxSubagentDepth: 1
|
|
142
|
+
---
|
|
143
|
+
|
|
144
|
+
Your system prompt goes here.
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Simple-scalar list fields accept either a comma-separated form or a newline block list with one `- item` per line. This applies to `tools`, `defaultReads`, `skill`/`skills`, `skillPath`, `fallbackModels`, `extensions`, and `subagentOnlyExtensions`:
|
|
148
|
+
|
|
149
|
+
```yaml
|
|
150
|
+
tools:
|
|
151
|
+
- read
|
|
152
|
+
- mcp:github/search_repositories
|
|
153
|
+
fallbackModels:
|
|
154
|
+
- openai/gpt-5-mini
|
|
155
|
+
- anthropic/claude-sonnet-4
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Field notes:
|
|
159
|
+
|
|
160
|
+
| Field | Notes |
|
|
161
|
+
|-------|-------|
|
|
162
|
+
| `package` | Optional package identifier. A file with `name: scout` and `package: code-analysis` registers as `code-analysis.scout`; serialization keeps `name` and `package` separate. |
|
|
163
|
+
| `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. |
|
|
164
|
+
| `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. |
|
|
165
|
+
| `extensions` | Omitted means normal extensions; empty means no extensions; list values allowlist specific extensions. |
|
|
166
|
+
| `subagentOnlyExtensions` | Extension paths loaded only in spawned child sessions for this agent. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
|
|
167
|
+
| `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
|
|
168
|
+
| `fallbackModels` | Ordered backup models for provider/model failures such as quota, auth, timeout, or unavailable model. Ordinary task failures do not trigger fallback. |
|
|
169
|
+
| `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. |
|
|
170
|
+
| `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
|
|
171
|
+
| `inheritProjectContext` | Keeps or strips inherited project instruction blocks. |
|
|
172
|
+
| `inheritSkills` | Keeps or strips Pi's discovered skills catalog. |
|
|
173
|
+
| `defaultContext` | Optional `fresh` or `fork` launch context default for this agent. |
|
|
174
|
+
| `skills` | Selects specific skills for the child, regardless of `inheritSkills`. |
|
|
175
|
+
| `skillPath` | Invocation-private skill files or discovery directories. Relative paths resolve from the agent definition file. Local matches take precedence, while unresolved or unreadable matches fall back to normal skill discovery. This field discovers candidates only; `skills` still selects what the child receives. |
|
|
176
|
+
| `output` | Default single-agent output file. |
|
|
177
|
+
| `defaultReads` | Files to read before running the agent. |
|
|
178
|
+
| `defaultProgress` | Maintain `progress.md`. |
|
|
179
|
+
| `async` | Default a single-agent launch to background (`true`) or foreground (`false`) when the call omits `async`. Explicit call values and `forceTopLevelAsync` win. |
|
|
180
|
+
| `timeoutMs` | Positive integer default runtime deadline in milliseconds for single-agent launches. Foreground launches use 30 minutes when neither the call nor agent provides a timeout; explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win. |
|
|
181
|
+
| `turnBudget` | JSON object default such as `{"maxTurns":20,"graceTurns":2}` for single-agent launches. An explicit call value wins, followed by this agent default, then global `turnBudget` config. |
|
|
182
|
+
| `acceptance` | Acceptance default for single-agent launches. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. Explicit call values win; chain and parallel acceptance remains task/step configuration. |
|
|
183
|
+
| `acceptanceRole` | Optional `read-only` or `writer` role for automatic acceptance inference. Explicit task mutation or no-edit intent wins; otherwise the declared role replaces agent-name guessing. This does not grant or revoke tools. |
|
|
184
|
+
| `completionGuard` | Set `false` only for non-implementation agents that may mention implementation words while using mutation-capable tools such as `bash`. |
|
|
185
|
+
| `interactive` | Parsed for compatibility but not currently enforced. |
|
|
186
|
+
| `maxSubagentDepth` | Tightens nested delegation for this agent's children. |
|
|
187
|
+
| `memory` | Opt-in role-specific persistent memory. See below. |
|
|
188
|
+
|
|
189
|
+
## Per-agent persistent memory
|
|
190
|
+
|
|
191
|
+
A recurring custom agent can opt into a durable, role-specific memory scope with the `memory` frontmatter field:
|
|
192
|
+
|
|
193
|
+
```yaml
|
|
194
|
+
memory:
|
|
195
|
+
scope: project
|
|
196
|
+
path: security-reviewer
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
This is independent of Pi's own parent/session/project memory system and writes nothing to it. Memory lives under a dedicated `agent-memory/` namespace so the two never collide.
|
|
200
|
+
|
|
201
|
+
How it works:
|
|
202
|
+
|
|
203
|
+
- On each run, the first 200 lines of `MEMORY.md` in the resolved memory directory are injected into the child system prompt, so the agent can recall accumulated role notes such as threat-model entries, release gotchas, or verified commands.
|
|
204
|
+
- Agents with write tools (`edit`, `write`, or `bash`, or no `tools` allowlist at all) are told they may append concise dated entries to the file.
|
|
205
|
+
- Agents without write tools receive a read-only memory block and are not instructed to edit it. A read-only reviewer can recall prior notes without gaining write capability.
|
|
206
|
+
- The memory directory is never created eagerly. The agent's own `write` tool creates it (and `MEMORY.md`) on the first persist.
|
|
207
|
+
- Memory paths are validated against `.`/`..` traversal and symlink escape. An unsafe or unresolvable scope is silently skipped rather than breaking the run.
|
|
208
|
+
|
|
209
|
+
Scopes:
|
|
210
|
+
|
|
211
|
+
- Project: resolves under `<project>/.pi/agent-memory/<path>` and travels with the repo.
|
|
212
|
+
- User: resolves under `~/.pi/agent/agent-memory/<path>` and is shared across projects for that agent.
|
|
213
|
+
|
|
214
|
+
## Refinement overlays
|
|
215
|
+
|
|
216
|
+
A refinement overlay is bounded, project-local guidance layered on top of one agent's system prompt without editing the agent file. Use it when an agent repeatedly stumbles on the same project-specific issue and recent run evidence shows what to correct.
|
|
217
|
+
|
|
218
|
+
```text
|
|
219
|
+
/subagents-refine reviewer
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
```ts
|
|
223
|
+
subagent({ action: "refine", agent: "reviewer" })
|
|
224
|
+
subagent({ action: "refine.show", agent: "reviewer" })
|
|
225
|
+
subagent({ action: "refine.rollback", agent: "reviewer" })
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
How it works:
|
|
229
|
+
|
|
230
|
+
- `refine` collects bounded evidence from that agent's recent runs in the project (statuses, errors, review findings, residual risks, output tails), then launches a fresh read-only proposal child to draft small guidance edits from that evidence.
|
|
231
|
+
- Proposed guidance is validated before it is written. Edits that try to override safety, policy, tool, output, acceptance, developer, or system instructions are rejected, as are edits that target all agents or base agent files.
|
|
232
|
+
- The accepted overlay is stored at `.pi/subagents/refinements/<agent>.md` with revision metadata and snapshots. Each `refine` or `refine.rollback` adds a snapshot, and `refine.rollback` restores the previous revision.
|
|
233
|
+
- At launch, the current overlay is injected into that agent's child system prompt as a `<pi-subagents-refinement>` block scoped to this project. The base agent definition is never modified.
|
|
234
|
+
|
|
235
|
+
`refine.show` prints the current overlay and revision history. Delete the overlay file to remove the refinement entirely.
|
|
236
|
+
|
|
237
|
+
## Tool and extension selection
|
|
238
|
+
|
|
239
|
+
How `tools` behaves:
|
|
240
|
+
|
|
241
|
+
- `tools` omitted: `pi-subagents` does not pass `--tools`, so the child gets Pi's normal builtin tools.
|
|
242
|
+
- `tools` present: regular tool names become an explicit allowlist.
|
|
243
|
+
- `tools:` empty: emits `--no-tools`.
|
|
244
|
+
|
|
245
|
+
An allowlisted name does not load the extension that registers it. Load that provider through normal Pi extension discovery, `extensions`, `subagentOnlyExtensions`, or a path-like `tools` entry.
|
|
246
|
+
|
|
247
|
+
More rules:
|
|
248
|
+
|
|
249
|
+
- `mcp:` entries are split out and forwarded as direct MCP selections without granting normal builtins unless those builtins are also listed.
|
|
250
|
+
- Path-like `tools` entries, such as extension paths or `.ts`/`.js` files, are treated as tool-extension paths rather than tool names.
|
|
251
|
+
- Internal runtime tools such as `structured_output` are added to an explicit allowlist only when their contract is active.
|
|
252
|
+
- Agents that declare only known read-only builtin tools skip the implementation completion guard. `bash`, unknown tools, and MCP tools stay mutation-capable. Use `completionGuard: false` for bash-enabled validators or advisors that should never be judged as implementation agents.
|
|
253
|
+
|
|
254
|
+
Examples:
|
|
255
|
+
|
|
256
|
+
- `tools` omitted and `extensions` omitted: normal builtins and normal extensions.
|
|
257
|
+
- `tools: mcp:chrome-devtools`: only the resolved direct Chrome DevTools MCP tools.
|
|
258
|
+
- `tools: read, bash, mcp:chrome-devtools`: only `read` and `bash` as builtins, plus direct Chrome DevTools MCP tools.
|
|
259
|
+
- `tools: subagent, read`: a child-safe `subagent` tool is available inside that child so it can run explicitly assigned nested fanout.
|
|
260
|
+
- `tools: read, fixture_search` plus `subagentOnlyExtensions: ./tools/fixture-search.ts`: the provider loads only in this agent's child process, and the registered `fixture_search` name survives the strict allowlist.
|
|
261
|
+
|
|
262
|
+
Direct MCP tools require [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter). Subagents only receive direct MCP tools when `mcp:` entries are listed in their frontmatter; global `directTools: true` in `mcp.json` is not enough by itself. The generic `mcp` proxy tool can still be used for discovery when available. The adapter caches tool metadata at startup, so after connecting a new MCP server for the first time, restart Pi before relying on direct tools. An `mcp:` entry named `subagent` does not authorize nested fanout; only the builtin `subagent` tool name does. If a resolved direct MCP name is missing from the child registry, pi-subagents keeps the launch failed under the strict allowlist and identifies the condition as a host/pi-mcp-adapter registration problem; verify that the adapter registers the selected tools before child startup.
|
|
263
|
+
|
|
264
|
+
`extensions` controls child extension loading:
|
|
265
|
+
|
|
266
|
+
```yaml
|
|
267
|
+
# Omitted: all normal extensions load
|
|
268
|
+
|
|
269
|
+
# Empty: no extensions
|
|
270
|
+
extensions:
|
|
271
|
+
|
|
272
|
+
# Allowlist
|
|
273
|
+
extensions: /abs/path/to/ext-a.ts, /abs/path/to/ext-b.ts
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
When `extensions` is present, normal discovered extensions are disabled. The listed extensions, path-like `tools` entries, required pi-subagents runtime extensions, and `subagentOnlyExtensions` still load.
|
|
277
|
+
|
|
278
|
+
Use `subagentOnlyExtensions` when a custom extension tool should exist only inside child sessions. It is scoped by agent config: every run of that agent receives those extension paths, while other agents do not unless they declare the same field. The current model does not have a separate named-subagent audience inside one agent definition.
|
|
279
|
+
|
|
280
|
+
To apply the same `extensions` allowlist to every agent that does not declare its own, set `subagents.defaultExtensions` in user or project settings (see [configuration.md](configuration.md)).
|
|
281
|
+
|
|
282
|
+
Before the first model turn, the child runtime compares every explicit tool name with Pi's final filtered registry. A missing provider fails the run with the unavailable names and concrete `subagentOnlyExtensions`/`extensions` guidance, instead of letting a direct or chained child silently continue without its requested tools.
|
|
283
|
+
|
|
284
|
+
## Skills
|
|
285
|
+
|
|
286
|
+
Skills are `SKILL.md` files made available to an agent. The prompt includes skill metadata and the file location; the agent reads the full skill file only when the task matches.
|
|
287
|
+
|
|
288
|
+
Discovery uses project-first precedence:
|
|
289
|
+
|
|
290
|
+
1. Project config `skills/{name}/SKILL.md` (`.pi/skills/{name}/SKILL.md` in standard Pi)
|
|
291
|
+
2. Project packages and project settings packages via `package.json -> pi.skills`
|
|
292
|
+
3. Current task cwd package via `package.json -> pi.skills`
|
|
293
|
+
4. Project config `settings.json -> skills`
|
|
294
|
+
5. `~/.pi/agent/skills/{name}/SKILL.md`
|
|
295
|
+
6. User packages and user settings packages via `package.json -> pi.skills`
|
|
296
|
+
7. `~/.pi/agent/settings.json -> skills`
|
|
297
|
+
|
|
298
|
+
Use agent defaults, override them at runtime, or disable them:
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
{ workflowScript: `return runs.run("main", { agent: "scout", task: "..." })` }
|
|
302
|
+
{ workflowScript: `return runs.run("main", { agent: "scout", task: "...", skill: "tmux, safe-bash" })` }
|
|
303
|
+
{ workflowScript: `return runs.run("main", { agent: "scout", task: "...", skill: false })` }
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
For chains, `skill` at the top level is additive. A step-level `skill` overrides that step; `false` disables skills for that step.
|
|
307
|
+
|
|
308
|
+
Available skills use this shape in the child prompt:
|
|
309
|
+
|
|
310
|
+
```xml
|
|
311
|
+
The following configured skills are available to this subagent.
|
|
312
|
+
Use the read tool to load a skill's file when the task matches its description.
|
|
313
|
+
When a skill file references a relative path, resolve it against the skill directory (parent of SKILL.md / dirname of the path) and use that absolute path in tool commands.
|
|
314
|
+
|
|
315
|
+
<available_skills>
|
|
316
|
+
<skill>
|
|
317
|
+
<name>safe-bash</name>
|
|
318
|
+
<description>Run shell commands safely.</description>
|
|
319
|
+
<location>/absolute/path/to/safe-bash/SKILL.md</location>
|
|
320
|
+
</skill>
|
|
321
|
+
</available_skills>
|
|
322
|
+
```
|
|
323
|
+
|
|
324
|
+
If an agent has an explicit `tools` allowlist and resolved skills, `read` is added for that child run so the listed skill files can be loaded on demand.
|
|
325
|
+
|
|
326
|
+
Missing skills do not fail execution. The result summary shows a warning.
|
|
327
|
+
|
|
328
|
+
Agent-local `skillPath` candidates never enter Pi's parent/global skills catalog. Pair `inheritSkills: false` with explicit `skills` and `skillPath` when a child should receive only its selected private skills.
|
|
329
|
+
|
|
330
|
+
## The bundled pi-subagents skill
|
|
331
|
+
|
|
332
|
+
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.
|
|
333
|
+
|
|
334
|
+
What it covers:
|
|
335
|
+
|
|
336
|
+
- **Delegation patterns**: when to launch which agent, whether to use single, parallel, chain, or async mode, and whether to use fresh or forked context.
|
|
337
|
+
- **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.
|
|
338
|
+
- **Role-agent prompting guidance**: compact contract prompts instead of long scripts, what to include in role-specific meta prompts, and retrieval budgets for researchers.
|
|
339
|
+
- **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.
|
|
340
|
+
- **Intercom conventions**: when to ask vs send, and how parent-side supervisor/result delivery works through the native channel.
|
|
341
|
+
- **Control and diagnostics**: attention signals, soft interrupts, status, and the `doctor` action.
|
|
342
|
+
|
|
343
|
+
If you are writing an agent that orchestrates 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.
|