@howarewoo/pi-subagents 0.3.0 → 0.3.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 +14 -0
- package/README.md +99 -26
- package/package.json +9 -3
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [0.3.1]
|
|
6
|
+
|
|
7
|
+
Requires Node 22.19+ and stable Pi 1.5.2 or newer, unchanged from 0.3.0. Tested host
|
|
8
|
+
remains Pi 1.5.2; newer stable hosts are allowed, not guaranteed compatible. No
|
|
9
|
+
configuration migration is required. Runtime behavior, permissions and lifecycle are
|
|
10
|
+
unchanged. Let active tasks finish before updating, then restart Pi; reload and shutdown
|
|
11
|
+
abort and drain active children rather than migrating them.
|
|
12
|
+
|
|
13
|
+
- Clarify the package description, add Pi/subagent discovery keywords, and lead the README with the supervised workflow, execution trade-offs, comparison links and a bounded read-only quick start.
|
|
14
|
+
|
|
15
|
+
- Shorten README selection guidance while preserving the comparison sources, feature coverage and execution boundaries.
|
|
16
|
+
|
|
17
|
+
- Add `pi-better-subagents` 0.32.4 to the README feature comparison with versioned sources and explicit unassessed entries. Explain when to choose this repo's permission hooks, exact model routing, validated batch results, Hub supervision and writer coordination, including sandbox, persistence and automation trade-offs. Add competitor-specific selection guidance for nicobailon, tintinweb and pi-better-subagents, identifying overlapping features and cases where each alternative is a better fit.
|
|
18
|
+
|
|
5
19
|
## [0.3.0]
|
|
6
20
|
|
|
7
21
|
Requires Node 22.19+ and stable Pi 1.5.2 or newer, unchanged from 0.2.x. Tested host
|
package/README.md
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
|
-
# @howarewoo/pi-subagents
|
|
1
|
+
# @howarewoo/pi-subagents — Pi subagent extension
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@howarewoo/pi-subagents)
|
|
4
4
|
[](https://www.npmjs.com/package/@howarewoo/pi-subagents)
|
|
5
5
|
|
|
6
|
-
Delegate
|
|
6
|
+
Delegate code exploration, reviews and implementation tasks in the [Pi coding agent](https://pi.dev). Follow each subagent's conversation and tool use, then steer or stop tasks from [Subagent Hub](#subagent-hub). Subagents use your selected model by default, with their own assignments and explicit tool grants.
|
|
7
|
+
|
|
8
|
+
Use this extension to supervise delegated work inside a running Pi session. Keep the parent running until tasks finish; writers serialize, and you manage any worktrees. See [why choose this repo](#why-choose-this-repo) and the [feature comparison](#feature-comparison) for the full trade-offs.
|
|
9
|
+
|
|
10
|
+
[Install](#installation) · [Quick start](#quick-start) · [Subagent Hub](#subagent-hub) · [Compare extensions](#feature-comparison) · [Documentation](#documentation)
|
|
7
11
|
|
|
8
12
|
|
|
9
13
|
|
|
@@ -40,25 +44,29 @@ Restart Pi and run `/subagent-profiles` to check the installation.
|
|
|
40
44
|
If you installed the former unscoped package, follow the
|
|
41
45
|
[0.1.1 migration instructions](CHANGELOG.md#011) before installing the current package.
|
|
42
46
|
|
|
43
|
-
##
|
|
47
|
+
## Quick start
|
|
44
48
|
|
|
45
|
-
Choose a model through Pi's `/login` and `/model` setup. Delegation uses that provider and may incur charges; it does not automatically switch to a cheaper model.
|
|
49
|
+
Start Pi in a project containing a `README.md` file. Choose a model through Pi's `/login` and `/model` setup. Delegation uses that provider and may incur charges; it does not automatically switch to a cheaper model.
|
|
46
50
|
|
|
47
51
|
Ask Pi:
|
|
48
52
|
|
|
49
|
-
> Use delegate_task with profile scout to
|
|
53
|
+
> Use delegate_task with profile scout to read README.md and summarize this project's purpose in three bullets. Run it in the foreground.
|
|
50
54
|
|
|
51
55
|
The corresponding tool call is:
|
|
52
56
|
|
|
53
57
|
```json
|
|
54
58
|
{
|
|
55
|
-
"assignment": "
|
|
59
|
+
"assignment": "Read README.md and summarize this project's purpose in three bullets",
|
|
56
60
|
"profile": "scout",
|
|
57
61
|
"background": false
|
|
58
62
|
}
|
|
59
63
|
```
|
|
60
64
|
|
|
61
|
-
|
|
65
|
+
The foreground call returns the scout's summary to the parent. Open `/subagent-hub` to inspect its conversation and tool calls. This example needs only the `read` tool; it does not require enabling `grep`, `find`, `ls` or `bash`.
|
|
66
|
+
|
|
67
|
+
## Use delegation
|
|
68
|
+
|
|
69
|
+
Submit a batch for parallel read-only work:
|
|
62
70
|
|
|
63
71
|
```json
|
|
64
72
|
{
|
|
@@ -261,29 +269,94 @@ changelog entries on the next fresh launch after a version increase. See the
|
|
|
261
269
|
|
|
262
270
|
## Feature comparison
|
|
263
271
|
|
|
264
|
-
Compared with
|
|
265
|
-
|
|
266
|
-
| Feature | @howarewoo/pi-subagents | [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) | [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) |
|
|
267
|
-
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
268
|
-
| Background tasks | ✅ [Parent-bound by design; until exit or reload](#why-background-tasks-are-parent-bound) | ✅ Supported | ✅ Supported |
|
|
269
|
-
| Nested delegation | ✅ [Supported](#why-nested-delegation-is-foreground-only) | ✅ Supported | ✅ Supported |
|
|
270
|
-
| Task list / conversation | ✅ [Subagent Hub: split panes; full-width thread on narrow terminals](#why-the-ui-observes-one-native-registry) | ✅ Fleet inspector: roster and output pane | ✅ FleetView opens a separate conversation viewer |
|
|
271
|
-
| Message / tool rendering | ✅ [Native Pi message and tool components](#why-the-ui-observes-one-native-registry) | ✅ Structured Markdown/tool transcripts | ✅ Markdown + session-registered tool renderers |
|
|
272
|
-
| Bi-directional agent messaging | ✅ [Supported; parent/child and siblings](#why-agent-messaging-is-family-scoped) | ⚠️ [Child/supervisor requests and replies](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/workflows.md#supervisor-coordination-child-asks-parent) | ⚠️ [Parent-to-child steering + result return; no built-in child-initiated or sibling messaging](https://github.com/tintinweb/pi-subagents/blob/b72b414581d8aa9bbfb1d44c832aed0d0b0b9053/src/nested-tools.ts#L400-L430) |
|
|
273
|
-
| Live follow / scrollback | ✅ Scroll up to pause; End to follow | ✅ Scroll away to pause; bottom resumes | ✅ Scroll up to pause; End to follow |
|
|
274
|
-
| In-UI task controls | ✅ [Hub: steer, inbox, stop, wait, park](#why-controls-are-identity-pinned) | ✅ Inspector: steer/follow-up and stop async runs | ✅ Viewer: steer, stop, foreground-to-background handoff |
|
|
275
|
-
| Tool / usage inspection | ✅ [Tools: sanitized arguments/results; Details: direct usage](#why-the-ui-observes-one-native-registry) | ✅ Expandable tool details + token counts | ✅ Expandable tool output + tokens; optional cost |
|
|
276
|
-
| Schema-validated results | ✅ [Supported](#why-structured-results-require-explicit-submission) | ✅ Supported | ⚠️ Workflow agents only |
|
|
277
|
-
| Managed Git worktrees | 🚫 [By design; caller-managed worktrees supported](#why-workspaces-are-caller-managed-and-writers-serialize) | ✅ Supported | ✅ Supported |
|
|
278
|
-
| Workflow scripts | 🚫 [By design; caller-owned](#why-orchestration-stays-with-the-caller) | ✅ Supported | ✅ Supported |
|
|
279
|
-
| Scheduled runs | 🚫 [By design; no scheduler](#why-orchestration-stays-with-the-caller) | ✅ Supported | ⚠️ Session-scoped agents only |
|
|
280
|
-
|
|
281
|
-
Legend: ✅ Supported (stated design boundaries apply) · ⚠️ Supported with scope restrictions · 🚫 By design.
|
|
272
|
+
Compared with three community alternatives using their documentation. Nicobailon and tintinweb were checked on 2026-11-11; tintinweb's messaging scope was additionally checked against source at revision `b72b414` (2026-11-12). `pi-better-subagents` was checked against its published 0.32.4 documentation on 2026-11-13. This is a feature comparison, not a performance or reliability benchmark. UI cells name documented surfaces; they do not imply other features are absent.
|
|
273
|
+
|
|
274
|
+
| Feature | @howarewoo/pi-subagents | [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) | [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) | [pi-better-subagents](https://pi.dev/packages/pi-better-subagents) |
|
|
275
|
+
| ------------------------------ | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
276
|
+
| Background tasks | ✅ [Parent-bound by design; until exit or reload](#why-background-tasks-are-parent-bound) | ✅ Supported | ✅ Supported | ✅ Non-blocking `pi -p` child processes; completion callbacks |
|
|
277
|
+
| Nested delegation | ✅ [Supported](#why-nested-delegation-is-foreground-only) | ✅ Supported | ✅ Supported | ⚠️ Opt-in for unconfined children; disabled in sandbox |
|
|
278
|
+
| Task list / conversation | ✅ [Subagent Hub: split panes; full-width thread on narrow terminals](#why-the-ui-observes-one-native-registry) | ✅ Fleet inspector: roster and output pane | ✅ FleetView opens a separate conversation viewer | ✅ Background-work navigator; output/result tools |
|
|
279
|
+
| Message / tool rendering | ✅ [Native Pi message and tool components](#why-the-ui-observes-one-native-registry) | ✅ Structured Markdown/tool transcripts | ✅ Markdown + session-registered tool renderers | — Not assessed |
|
|
280
|
+
| Bi-directional agent messaging | ✅ [Supported; parent/child and siblings](#why-agent-messaging-is-family-scoped) | ⚠️ [Child/supervisor requests and replies](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/workflows.md#supervisor-coordination-child-asks-parent) | ⚠️ [Parent-to-child steering + result return; no built-in child-initiated or sibling messaging](https://github.com/tintinweb/pi-subagents/blob/b72b414581d8aa9bbfb1d44c832aed0d0b0b9053/src/nested-tools.ts#L400-L430) | ⚠️ Parent-to-child communication + result return; no blocking child-to-parent requests |
|
|
281
|
+
| Live follow / scrollback | ✅ Scroll up to pause; End to follow | ✅ Scroll away to pause; bottom resumes | ✅ Scroll up to pause; End to follow | — Not assessed |
|
|
282
|
+
| In-UI task controls | ✅ [Hub: steer, inbox, stop, wait, park](#why-controls-are-identity-pinned) | ✅ Inspector: steer/follow-up and stop async runs | ✅ Viewer: steer, stop, foreground-to-background handoff | ✅ Navigator stop controls |
|
|
283
|
+
| Tool / usage inspection | ✅ [Tools: sanitized arguments/results; Details: direct usage](#why-the-ui-observes-one-native-registry) | ✅ Expandable tool details + token counts | ✅ Expandable tool output + tokens; optional cost | ✅ Output/result tools expose optional cost and tool counts |
|
|
284
|
+
| Schema-validated results | ✅ [Supported](#why-structured-results-require-explicit-submission) | ✅ Supported | ⚠️ Workflow agents only | — No equivalent caller-supplied result schema documented |
|
|
285
|
+
| Managed Git worktrees | 🚫 [By design; caller-managed worktrees supported](#why-workspaces-are-caller-managed-and-writers-serialize) | ✅ Supported | ✅ Supported | ⚠️ Optional self-contained Git clone; not managed linked worktrees |
|
|
286
|
+
| Workflow scripts | 🚫 [By design; caller-owned](#why-orchestration-stays-with-the-caller) | ✅ Supported | ✅ Supported | — Not assessed |
|
|
287
|
+
| Scheduled runs | 🚫 [By design; no scheduler](#why-orchestration-stays-with-the-caller) | ✅ Supported | ⚠️ Session-scoped agents only | — Not assessed |
|
|
288
|
+
|
|
289
|
+
Legend: ✅ Supported (stated design boundaries apply) · ⚠️ Supported with scope restrictions · 🚫 By design · — Not established by the cited documentation or not assessed.
|
|
282
290
|
|
|
283
291
|
🚫 marks a deliberate product boundary, not a missing implementation within the current
|
|
284
292
|
contract. Linked explanations describe the trade-offs behind this repo's choices.
|
|
285
293
|
|
|
286
|
-
Sources: [our contract](docs/delegation-contract.md); nicobailon's [README](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/README.md), [agents](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/agents.md), [workflows](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/workflows.md) and [observability](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/observability.md); tintinweb's [README](https://github.com/tintinweb/pi-subagents/blob/8df7fa7d8e8130151a8fbfa991a1d3fa6b443739/README.md) and [workflows](https://github.com/tintinweb/pi-subagents/blob/8df7fa7d8e8130151a8fbfa991a1d3fa6b443739/docs/workflows.md).
|
|
294
|
+
Sources: [our contract](docs/delegation-contract.md); nicobailon's [README](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/README.md), [agents](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/agents.md), [workflows](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/workflows.md) and [observability](https://github.com/nicobailon/pi-subagents/blob/c99503aed6d6b20d2397a1767f7d60730efe3963/docs/observability.md); tintinweb's [README](https://github.com/tintinweb/pi-subagents/blob/8df7fa7d8e8130151a8fbfa991a1d3fa6b443739/README.md) and [workflows](https://github.com/tintinweb/pi-subagents/blob/8df7fa7d8e8130151a8fbfa991a1d3fa6b443739/docs/workflows.md); pi-better-subagents' [usage guide (0.32.4)](https://cdn.jsdelivr.net/npm/pi-better-subagents@0.32.4/docs/usage.md) and [agent catalog (0.32.4)](https://cdn.jsdelivr.net/npm/pi-better-subagents@0.32.4/docs/agent-catalog.md).
|
|
295
|
+
|
|
296
|
+
### Why choose this repo?
|
|
297
|
+
|
|
298
|
+
Choose this repo for a supervised workflow in an existing checkout:
|
|
299
|
+
|
|
300
|
+
- Child tools retain parent permission hooks. Profiles cap authority; trusted-project
|
|
301
|
+
settings and tasks can only narrow operator grants. Ambient extension/MCP runtimes
|
|
302
|
+
are not loaded, and extra leaf tools require operator review.
|
|
303
|
+
See [permissions and resources](#why-permissions-and-resources-are-explicit).
|
|
304
|
+
- Children use the parent's model and effort unless an exact operator-approved override
|
|
305
|
+
applies. Unavailable selections fail without fallback.
|
|
306
|
+
See [model routing](#why-model-routing-is-exact).
|
|
307
|
+
- `resultSchema` requires explicit, validated submission. Batches pass preflight before
|
|
308
|
+
any child starts, retain input order and report background outcomes after all siblings
|
|
309
|
+
drain. See [structured results](#why-structured-results-require-explicit-submission).
|
|
310
|
+
- Hub combines native Pi conversations, tool arguments/results, usage and identity-pinned
|
|
311
|
+
controls. Granted parent/child and sibling messaging stays bounded within the live
|
|
312
|
+
parent runtime. See [Hub](#subagent-hub) and [messaging](#why-agent-messaging-is-family-scoped).
|
|
313
|
+
- Writers serialize across worktrees, and coordinated parent model-tool mutations cannot
|
|
314
|
+
overlap a child writer. This reduces in-runtime conflicts at the cost of parallel
|
|
315
|
+
writing throughput. External editors and manual commands remain uncoordinated.
|
|
316
|
+
See [workspace ownership](#why-workspaces-are-caller-managed-and-writers-serialize).
|
|
317
|
+
|
|
318
|
+
#### Compared with nicobailon/pi-subagents
|
|
319
|
+
|
|
320
|
+
This repo keeps background assignments under one live parent responsible for grants,
|
|
321
|
+
admission, descendant drain and writer serialization. Nicobailon also runs foreground
|
|
322
|
+
children in-process, but uses a detached background runner. Both have fleet inspection
|
|
323
|
+
and schema-validated results.
|
|
324
|
+
|
|
325
|
+
Choose nicobailon for packaged review loops, council patterns, custom agents with
|
|
326
|
+
per-agent memory, managed worktrees, durable missions or scheduled runs. This repo
|
|
327
|
+
leaves workflows and workspace lifecycle to the caller, with no scheduler or restart
|
|
328
|
+
recovery.
|
|
329
|
+
|
|
330
|
+
#### Compared with tintinweb/pi-subagents
|
|
331
|
+
|
|
332
|
+
This repo supports granted parent/child and sibling messaging, plus schema-validated
|
|
333
|
+
results on ordinary assignments. Tintinweb's cited implementation has parent-to-child
|
|
334
|
+
steering and result return; its schema-validated results are documented for workflow
|
|
335
|
+
agents. This repo's Hub keeps the roster beside the conversation on wide terminals;
|
|
336
|
+
tintinweb's FleetView opens a separate viewer.
|
|
337
|
+
|
|
338
|
+
Choose tintinweb for Claude Code-style tool conventions, compatible JavaScript workflows,
|
|
339
|
+
persistent agent memory, session-scoped scheduling or managed worktrees that preserve
|
|
340
|
+
changes on a branch. Both support conversation continuation, but this repo retains it
|
|
341
|
+
only within the owning parent runtime; tintinweb documents persisted resume. Its worktree
|
|
342
|
+
isolation is not an OS sandbox.
|
|
343
|
+
|
|
344
|
+
#### Compared with pi-better-subagents
|
|
345
|
+
|
|
346
|
+
This repo supports foreground results or background completion, live family messaging
|
|
347
|
+
and explicitly submitted schema-validated results. `pi-better-subagents` uses independent,
|
|
348
|
+
non-blocking child processes with completion callbacks and no mid-task blocking
|
|
349
|
+
child-to-parent requests.
|
|
350
|
+
|
|
351
|
+
Choose `pi-better-subagents` for opt-in macOS/Linux sandboxing (off by default), saved
|
|
352
|
+
conversations another foreground session can continue, or optional sandbox-oriented Git
|
|
353
|
+
clones. This repo has no OS sandbox; changing `cwd` does not provide containment.
|
|
354
|
+
The other package also has an editable role/named-agent catalog and, with Background
|
|
355
|
+
Tasks loaded and its documented prerequisites met, workers that release slots while
|
|
356
|
+
waiting for long operations.
|
|
357
|
+
|
|
358
|
+
Recommendations apply to the cited versions, without a performance or reliability ranking.
|
|
359
|
+
Unassessed controls may exist in the alternatives.
|
|
287
360
|
|
|
288
361
|
## Architectural decisions
|
|
289
362
|
|
package/package.json
CHANGED
|
@@ -1,9 +1,15 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@howarewoo/pi-subagents",
|
|
3
|
-
"version": "0.3.
|
|
4
|
-
"description": "Pi
|
|
3
|
+
"version": "0.3.1",
|
|
4
|
+
"description": "Pi subagent extension for supervised coding tasks with live monitoring, steering, and explicit tool permissions.",
|
|
5
5
|
"keywords": [
|
|
6
|
-
"
|
|
6
|
+
"agent-delegation",
|
|
7
|
+
"multi-agent",
|
|
8
|
+
"pi-coding-agent",
|
|
9
|
+
"pi-extension",
|
|
10
|
+
"pi-package",
|
|
11
|
+
"subagent",
|
|
12
|
+
"subagents"
|
|
7
13
|
],
|
|
8
14
|
"homepage": "https://github.com/howarewoo/pi-subagents#readme",
|
|
9
15
|
"bugs": {
|