@ferris1225/pi-subagents 4.1.13 → 4.1.16
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/README.md +333 -291
- package/agents/cleaner.md +24 -30
- package/agents/documenter.md +23 -20
- package/agents/explorer.md +7 -2
- package/agents/reviewer.md +82 -77
- package/agents/worker.md +45 -37
- package/package.json +1 -1
- package/src/announcements.ts +59 -54
- package/src/background.ts +26 -10
- package/src/completion.ts +7 -1
- package/src/config.ts +1 -1
- package/src/dispatch.ts +133 -133
- package/src/durable.ts +85 -19
- package/src/format.ts +179 -167
- package/src/monitor.ts +4 -2
- package/src/prompt.ts +14 -27
- package/src/runtime.ts +18 -14
- package/src/setup.ts +3 -3
- package/src/spawn.ts +650 -642
- package/src/temp-hygiene.ts +0 -28
- package/src/thread-lifecycle.ts +85 -99
- package/src/tools.ts +712 -708
- package/src/widget.ts +9 -0
- package/src/workflow.ts +199 -248
- package/src/worktree.ts +64 -37
package/README.md
CHANGED
|
@@ -1,291 +1,333 @@
|
|
|
1
|
-
# pi-subagents
|
|
2
|
-
|
|
3
|
-
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
-
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
-
[](./LICENSE)
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
A managed engineering team for [pi](https://github.com/earendil-works/pi): five
|
|
10
|
-
specialized sub-agents, durable threads, automatic quality gates, and Git
|
|
11
|
-
worktree isolation — installed once, then your main agent delegates on its own.
|
|
12
|
-
|
|
13
|
-
## Why pi-subagents
|
|
14
|
-
|
|
15
|
-
Delegation should **remove** coordination work, not create more of it. Most
|
|
16
|
-
sub-agent launchers stop at "spawn a child with a prompt"; the coordination
|
|
17
|
-
burden — when to delegate, how wide to fan out, who reviews, what happens when a
|
|
18
|
-
model dies, how results come back — stays with you. pi-subagents owns that
|
|
19
|
-
burden:
|
|
20
|
-
|
|
21
|
-
- **The main model actually delegates.** A lean delegation directive is injected
|
|
22
|
-
into its system prompt:
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
its
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
##
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
1
|
+
# pi-subagents
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
4
|
+
[](https://www.npmjs.com/package/@ferris1225/pi-subagents)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
A managed engineering team for [pi](https://github.com/earendil-works/pi): five
|
|
10
|
+
specialized sub-agents, durable threads, automatic quality gates, and Git
|
|
11
|
+
worktree isolation — installed once, then your main agent delegates on its own.
|
|
12
|
+
|
|
13
|
+
## Why pi-subagents
|
|
14
|
+
|
|
15
|
+
Delegation should **remove** coordination work, not create more of it. Most
|
|
16
|
+
sub-agent launchers stop at "spawn a child with a prompt"; the coordination
|
|
17
|
+
burden — when to delegate, how wide to fan out, who reviews, what happens when a
|
|
18
|
+
model dies, how results come back — stays with you. pi-subagents owns that
|
|
19
|
+
burden:
|
|
20
|
+
|
|
21
|
+
- **The main model actually delegates.** A lean delegation directive is injected
|
|
22
|
+
into its system prompt: child contexts are cheap and yours is scarce —
|
|
23
|
+
non-trivial implementation defaults to `worker`, trivial work stays inline,
|
|
24
|
+
and dispatching never blocks or ends the main turn, so it can fire several
|
|
25
|
+
dispatches and keep working while they run.
|
|
26
|
+
- **Fan-out is the model's call, not a cap.** One parallel dispatch carries as
|
|
27
|
+
many tasks as the work genuinely decomposes into. The runtime paces execution
|
|
28
|
+
at a process-slot pool that scales with the machine (cores/2, bounded 4–16);
|
|
29
|
+
extra tasks simply queue and start automatically as slots free, so wide
|
|
30
|
+
batches never fail, never flood your context (results deliver compact, with
|
|
31
|
+
the full text on disk), and queueing is always visible pacing — never a
|
|
32
|
+
hidden dispatch limit.
|
|
33
|
+
- **Quality gates are built in and converge by themselves.** Successful
|
|
34
|
+
worker/cleaner runs continue through one independent reviewer gate. A failing
|
|
35
|
+
gate is fixed by the reviewer itself — the same retained session gets write
|
|
36
|
+
access and applies its own fix instructions, then a converging re-review
|
|
37
|
+
verifies the fixes — bounded rounds; a still-failing gate returns to the main
|
|
38
|
+
agent with every finding and fix instruction. No guessing what satisfies the
|
|
39
|
+
reviewer.
|
|
40
|
+
- **Documentation stops drifting.** Writers sync the docs they directly affect;
|
|
41
|
+
documentation drift is an ordinary gate finding, and dispatching the
|
|
42
|
+
documenter for real remaining drift stays the main agent's decision.
|
|
43
|
+
- **Parallel edits are safe.** Parallel workers default to isolated Git
|
|
44
|
+
worktrees and integrate back without touching your index; shared-checkout
|
|
45
|
+
writers serialize through one repository lane.
|
|
46
|
+
- **Work survives everything.** Threads keep retained sessions across resume,
|
|
47
|
+
stop, and pi reloads or crashes; a model failure hands the same session to
|
|
48
|
+
the current main model instead of losing progress.
|
|
49
|
+
- **Failures are visible.** Crashes, partial starts, and integration failures
|
|
50
|
+
come back as results with recovery records — never as silent hangs.
|
|
51
|
+
|
|
52
|
+
## How it works
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
You
|
|
56
|
+
└─ pi main agent
|
|
57
|
+
├─ explorer ─── retrieval index only (never an automatic gate)
|
|
58
|
+
├─ worker ───── implements ─┬─▶ reviewer ─ PASS → deliver
|
|
59
|
+
├─ cleaner ──── cleans up ──┘ └─ FAIL → reviewer fixes itself
|
|
60
|
+
├─ documenter ─ explicit docs/comments task → deliver │
|
|
61
|
+
└─ reviewer ─── advisory report (no VERDICT), or managed gate ◀──────┘
|
|
62
|
+
└─ direct REVIEW_FAIL → findings + fix instructions → main agent fixes
|
|
63
|
+
|
|
64
|
+
Worker and cleaner update existing docs/comments they directly affect. The stable
|
|
65
|
+
parent returns one final result when its complete managed workflow settles.
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Every child is an isolated leaf Pi process with its own context window and no
|
|
69
|
+
memory of your conversation — the brief is its only input. Completions resume
|
|
70
|
+
the main agent automatically; there is no polling loop.
|
|
71
|
+
|
|
72
|
+
## Quick start
|
|
73
|
+
|
|
74
|
+
Requires **pi >= 0.83.0** and **Node.js >= 22.19.0**.
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
pi install npm:@ferris1225/pi-subagents
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Open pi and run `/subagents-setup` to pick agents, models, and thinking
|
|
81
|
+
strengths. Fresh installs enable all five built-in agents on the current main
|
|
82
|
+
model, and until a config file exists each session start points you at
|
|
83
|
+
`/subagents-setup`. Then just ask:
|
|
84
|
+
|
|
85
|
+
```text
|
|
86
|
+
Map how authentication works, fix the refresh race, run the tests, and review the diff.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The main agent decides when delegation pays off; you can also call the tools
|
|
90
|
+
directly for exact control.
|
|
91
|
+
|
|
92
|
+
## The team
|
|
93
|
+
|
|
94
|
+
| Agent | Access | Best for |
|
|
95
|
+
| ------------ | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
96
|
+
| `explorer` | Read-only | Broad search, unfamiliar-area mapping, symbol/dependency tracing. Fast model, returns a retrieval index — never proof. |
|
|
97
|
+
| `worker` | Full | The default route for any non-trivial, self-contained implementation, fix, refactor, or test task carried through verification. |
|
|
98
|
+
| `cleaner` | Full | Explicitly authorized cleanup, removal, simplification, deduplication. Every safe proven cut applies without item-by-item approval. |
|
|
99
|
+
| `documenter` | Docs/comments | Standalone docs/comments work, including syncing real drift a change left behind. May make zero edits; never changes runtime behavior. |
|
|
100
|
+
| `reviewer` | Read-only (review) / full (fix stage) | Audits, code-health checks, plans, PR/issue validation, and independent gates; a failing managed gate continues into the reviewer's own write-enabled fix stage. |
|
|
101
|
+
|
|
102
|
+
A good brief carries the goal, exact paths, constraints, and expected output —
|
|
103
|
+
the injected delegation guidance does this automatically when the main agent
|
|
104
|
+
dispatches for you.
|
|
105
|
+
|
|
106
|
+
## Dispatch and fan-out
|
|
107
|
+
|
|
108
|
+
```ts
|
|
109
|
+
// One task
|
|
110
|
+
subagent({
|
|
111
|
+
agent: "worker",
|
|
112
|
+
task: "Fix the cache invalidation bug in src/cache, add regression tests, run the checks.",
|
|
113
|
+
});
|
|
114
|
+
|
|
115
|
+
// Parallel: as many genuinely independent units as the work has
|
|
116
|
+
subagent({
|
|
117
|
+
tasks: [
|
|
118
|
+
{
|
|
119
|
+
agent: "explorer",
|
|
120
|
+
task: "Trace model fallback from dispatch to completion.",
|
|
121
|
+
},
|
|
122
|
+
{ agent: "worker", task: "Add edge-case tests for config migration." },
|
|
123
|
+
],
|
|
124
|
+
});
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
The main agent owns the breadth — there is no per-call task cap. The runtime
|
|
128
|
+
runs a machine-scaled pool of child processes at once and queues the rest;
|
|
129
|
+
dispatch confirmations and `subagent_status` state the live running/queued
|
|
130
|
+
counts and the slot capacity, so pacing is never mistaken for a limit. A
|
|
131
|
+
generation that moves on to its managed stages (gate review, fix rounds) or
|
|
132
|
+
waits on the shared-checkout writer lane releases its slot, so neither managed
|
|
133
|
+
work nor serialized writers starve new dispatches. Parallel write-capable
|
|
134
|
+
agents default to isolated worktrees and integrate via a three-way merge, so
|
|
135
|
+
disjoint edits from parallel workers land without conflicts. One child owns one
|
|
136
|
+
coherent deliverable and its files; dependent work starts only after its
|
|
137
|
+
prerequisite delivers.
|
|
138
|
+
|
|
139
|
+
## Review gates and fixes
|
|
140
|
+
|
|
141
|
+
```ts
|
|
142
|
+
subagent({
|
|
143
|
+
agent: "reviewer",
|
|
144
|
+
task: "Gate the current diff for correctness, regressions, and missing tests.",
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
A gate ends with exactly one verdict line: `VERDICT: REVIEW_PASS` or
|
|
149
|
+
`REVIEW_FAIL`. Every gate finding carries a concrete fix instruction, and the
|
|
150
|
+
reviewer must surface the complete finding set in one pass — never rationing
|
|
151
|
+
findings across later rounds.
|
|
152
|
+
|
|
153
|
+
A failing **managed** gate (after a top-level worker/cleaner) converges inside
|
|
154
|
+
the workflow: the same retained reviewer session continues with write access
|
|
155
|
+
and applies its own fix instructions, then a fresh gate verifies the fixes and
|
|
156
|
+
hunts regressions they introduced (re-reviews converge on the fixes instead of
|
|
157
|
+
re-scanning the whole surface). The loop is bounded to two fix rounds, after
|
|
158
|
+
which the still-failing gate returns to the main agent with every finding.
|
|
159
|
+
|
|
160
|
+
A failing gate **you dispatched directly** returns the full findings to the
|
|
161
|
+
main agent, which resolves them itself (inline or via a worker it briefs)
|
|
162
|
+
without waiting for you; only a genuinely destructive or scope-changing fix is
|
|
163
|
+
worth asking about. It re-verifies once, then reports remaining findings and
|
|
164
|
+
moves on — gate dispatches never loop. Generic audits and read-only reviews
|
|
165
|
+
are advisory by default: no `VERDICT`, no edits.
|
|
166
|
+
|
|
167
|
+
`cleaner` is dispatch-authorized cleanup: asking for an audit never silently
|
|
168
|
+
authorizes code changes, and asking for cleanup never rewards speculative
|
|
169
|
+
deletion. A top-level `documenter` is an explicit docs-writing task that
|
|
170
|
+
delivers without another gate.
|
|
171
|
+
|
|
172
|
+
## Safe parallel editing
|
|
173
|
+
|
|
174
|
+
- Single tasks default to the shared checkout; every parallel write-capable
|
|
175
|
+
agent (`worker`, `cleaner`, `documenter`, custom writers) defaults to a
|
|
176
|
+
detached Git worktree (requires a committed `HEAD`; read-only agents reject
|
|
177
|
+
worktree mode), so parallel writers run concurrently.
|
|
178
|
+
- An isolated workflow's reviewer and documenter run inside the same worktree;
|
|
179
|
+
tracked, deleted, untracked, and binary changes integrate back exactly once
|
|
180
|
+
after the workflow settles — nothing is staged and your index is untouched.
|
|
181
|
+
- Integration is a three-way merge: parallel workers that touched disjoint
|
|
182
|
+
files or regions land cleanly even when earlier patches drifted the checkout.
|
|
183
|
+
A genuine overlap keeps conflict markers in the checkout plus the retained
|
|
184
|
+
worktree and patch for you to resolve.
|
|
185
|
+
- Shared-checkout writers (and reviewers snapshotting their diff) serialize
|
|
186
|
+
through one repository lane, so two shared writers never race.
|
|
187
|
+
- Setup or integration failures keep the useful patch/worktree and record
|
|
188
|
+
recovery info in `~/.pi/agent/pi-subagents-recovery.json`; a parked isolated
|
|
189
|
+
thread keeps its worktree and resumes there.
|
|
190
|
+
|
|
191
|
+
## Follow, redirect, or stop
|
|
192
|
+
|
|
193
|
+
Every dispatch returns a stable `#id` — the handle for all control tools:
|
|
194
|
+
|
|
195
|
+
| Tool | What it does |
|
|
196
|
+
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
197
|
+
| `subagent_control` | `resume` a parked/settled thread with its full retained context, optionally with a new `objective` appended. Only interrupted (parked) threads survive a reload. |
|
|
198
|
+
| `subagent_status` | List active and recent runs, or return one run's full result and failed-tool diagnostics. |
|
|
199
|
+
| `subagent_wait` | Non-blocking in-turn lookup; `timeoutMs` only when you must wait. |
|
|
200
|
+
| `subagent_stop` | Destructively cancel, deliver the partial output, retire the thread. |
|
|
201
|
+
|
|
202
|
+
```ts
|
|
203
|
+
subagent_control({ action: "resume", id: 7, objective: "Finish the tests." });
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Threads are durable while work is unfinished: parked sessions, worktree
|
|
207
|
+
checkpoints, and result excerpts live under
|
|
208
|
+
`~/.pi/agent/ferris-pi-subagents/<project>/` (grouped per project; not the OS
|
|
209
|
+
temp directory) and are restored when pi reloads or restarts — a reload
|
|
210
|
+
interrupts a live run into a restorable checkpoint instead of losing it. A
|
|
211
|
+
thread that completes or fails cleanly drops its durable record, so the
|
|
212
|
+
threads manifest exists only
|
|
213
|
+
while interrupted work needs it; parked work stays resumable for 30 days, and
|
|
214
|
+
a project directory idle for three days is deleted wholesale on the next load
|
|
215
|
+
(parked threads' references always win), so per-project storage never grows
|
|
216
|
+
forever. All control operations are bounded; they never hang on a generation
|
|
217
|
+
that is still settling.
|
|
218
|
+
|
|
219
|
+
## Results and live status
|
|
220
|
+
|
|
221
|
+
The TUI widget projects each managed workflow as a timeline plus its current
|
|
222
|
+
child:
|
|
223
|
+
|
|
224
|
+
```text
|
|
225
|
+
◆ #12 worker workflow · src/cache.ts · wt:a91f3c · 42s
|
|
226
|
+
✓ implement ─ ● review ─ ○ docs
|
|
227
|
+
└ ● #15 reviewer · final review · claude-sonnet-4-5/high · 10s
|
|
228
|
+
○ #23 worker · queued · redirect to ripgrep crates · 5m02s
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
The widget is capped at ten lines: when many runs are live at once, extra rows
|
|
232
|
+
collapse into a `… +N more (subagent_status)` marker so the editor area keeps
|
|
233
|
+
its space; `subagent_status` always shows the full picture.
|
|
234
|
+
|
|
235
|
+
Completions resume the main agent automatically with a compact block (40 lines
|
|
236
|
+
by default; longer output lands unchanged in a temporary Markdown artifact
|
|
237
|
+
reachable via `subagent_status`). Roles author result-only handoffs — outcome,
|
|
238
|
+
paths, verification, unresolved blockers — and the main agent is told to add
|
|
239
|
+
its conclusion, not restate what you already saw.
|
|
240
|
+
|
|
241
|
+
## Models, thinking, and vision
|
|
242
|
+
|
|
243
|
+
Each agent runs on the current main model or one picked in `/subagents-setup`
|
|
244
|
+
(vision/text-only labels included). If a selected model is missing, rate-limited,
|
|
245
|
+
or fails at the provider level, the **same retained session** continues on the
|
|
246
|
+
main model — finished searches, reads, and edits are preserved; ordinary task
|
|
247
|
+
failures do not trigger a handoff. Thinking defaults to **Auto**: the role's
|
|
248
|
+
preference, clamped to what the effective model supports. `/subagents-setup` →
|
|
249
|
+
_Configure an agent_ also offers a manual strength per agent, listing only the
|
|
250
|
+
levels that model supports. There is no separate
|
|
251
|
+
vision mode: assign a multimodal model and name the image paths in the task.
|
|
252
|
+
|
|
253
|
+
Every dispatch, managed stage, resume, retry, and fallback snapshots the
|
|
254
|
+
parent's currently active tools: roles without an explicit list inherit the
|
|
255
|
+
full set; explicit lists keep their Pi built-in boundary while their shell slot
|
|
256
|
+
(`bash`/`powershell`) follows the parent and active extension tools are
|
|
257
|
+
appended. Read-only roles never gain `edit`/`write`; all `subagent*` tools are
|
|
258
|
+
stripped so children stay leaves. An empty snapshot starts the child with
|
|
259
|
+
`--no-tools`.
|
|
260
|
+
|
|
261
|
+
## Configuration
|
|
262
|
+
|
|
263
|
+
`/subagents-setup` stays one level deep: enabled agents, per-agent models and
|
|
264
|
+
thinking strengths, and the delegation-injection toggle. Everything else is
|
|
265
|
+
config-file only, stored at
|
|
266
|
+
`~/.pi/agent/pi-subagents.json` (follows `PI_CODING_AGENT_DIR`):
|
|
267
|
+
|
|
268
|
+
```json
|
|
269
|
+
{
|
|
270
|
+
"enabledAgents": ["explorer", "worker", "cleaner", "documenter", "reviewer"],
|
|
271
|
+
"agentModels": { "explorer": "anthropic/claude-haiku-4-5" },
|
|
272
|
+
"agentThinkingLevels": { "reviewer": "high" },
|
|
273
|
+
"notifyOnReviewPass": false,
|
|
274
|
+
"maxResultLines": 40,
|
|
275
|
+
"proactiveInjection": true,
|
|
276
|
+
"agentScope": "user",
|
|
277
|
+
"idleTimeoutSec": 90
|
|
278
|
+
}
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
| Field | Meaning |
|
|
282
|
+
| --------------------- | --------------------------------------------------------------------------------- |
|
|
283
|
+
| `enabledAgents` | Agents available for discovery and delegation. `[]` disables all. |
|
|
284
|
+
| `agentModels` | Optional `provider/model-id` per agent; missing = current main model. |
|
|
285
|
+
| `agentThinkingLevels` | Optional manual level per agent; missing = Auto. |
|
|
286
|
+
| `notifyOnReviewPass` | Deliver a standalone passing gate without waking the main agent. Default `false`. |
|
|
287
|
+
| `maxResultLines` | Lines kept in a completion message before the artifact takes over. Default `40`. |
|
|
288
|
+
| `proactiveInjection` | Inject the delegation directive into the main system prompt. Default `true`. |
|
|
289
|
+
| `agentScope` | Discover `user`, `project`, or `both` agent directories. Default `user`. |
|
|
290
|
+
| `idleTimeoutSec` | Seconds without child RPC output before termination; `0` disables. Default `90`. |
|
|
291
|
+
|
|
292
|
+
Invalid values fall back safely; stale keys (including the former
|
|
293
|
+
`maxConcurrency`/`maxFixRounds` knobs) are dropped automatically. At session
|
|
294
|
+
start, model overrides Pi no longer reports are removed with a one-time notice.
|
|
295
|
+
|
|
296
|
+
## Custom agents
|
|
297
|
+
|
|
298
|
+
Built-ins ship in the package; add or replace them with Markdown files:
|
|
299
|
+
|
|
300
|
+
- User agents: `~/.pi/agent/agents/`
|
|
301
|
+
- Project agents: nearest `.pi/agents/` in a trusted project
|
|
302
|
+
- Precedence: project > user > built-in (same `name` wins)
|
|
303
|
+
|
|
304
|
+
```yaml
|
|
305
|
+
---
|
|
306
|
+
name: explorer
|
|
307
|
+
description: Fast read-only codebase reconnaissance
|
|
308
|
+
model: anthropic/claude-haiku-4-5
|
|
309
|
+
thinking: low
|
|
310
|
+
tools: read, bash
|
|
311
|
+
---
|
|
312
|
+
…additional system prompt…
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Wizard choices override frontmatter defaults; an explicit `tools` list stays the
|
|
316
|
+
capability boundary (shell slot follows the parent, active extension tools are
|
|
317
|
+
appended), and omitting it inherits the parent's complete active set.
|
|
318
|
+
|
|
319
|
+
## Development
|
|
320
|
+
|
|
321
|
+
```bash
|
|
322
|
+
npm install
|
|
323
|
+
npm run check
|
|
324
|
+
npm test
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
No bundled runtime dependencies — pi and TypeBox are peers. Source is split by
|
|
328
|
+
responsibility: dispatch/workflow policy, thread lifecycle, RPC transport,
|
|
329
|
+
worktree integration, completion delivery, tools, and TUI status.
|
|
330
|
+
|
|
331
|
+
## License
|
|
332
|
+
|
|
333
|
+
MIT
|