@howarewoo/pi-subagents 0.1.1 → 0.2.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 +50 -0
- package/README.md +268 -97
- package/docs/advanced-policies.md +4 -2
- package/docs/delegation-contract.md +57 -28
- package/docs/images/subagent-hub.svg +1 -1
- package/docs/images/subagent-profiles.svg +1 -1
- package/docs/images/subagent-widget.svg +1 -1
- package/docs/releases.md +111 -23
- package/docs/verification.md +1 -1
- package/package.json +4 -4
- package/src/child-execution.ts +459 -0
- package/src/coordinator.ts +608 -664
- package/src/delegation-types.ts +111 -0
- package/src/hub.ts +80 -300
- package/src/pi-extended-subagents.ts +83 -189
- package/src/profile-viewer.ts +109 -38
- package/src/scheduling.ts +1 -1
- package/src/subagent-widget.ts +150 -0
- package/src/supported-host.ts +26 -0
- package/src/task-input.ts +3 -2
- package/src/task-presentation.ts +196 -0
- package/src/tool-schemas.ts +165 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,55 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [Unreleased]
|
|
4
|
+
|
|
5
|
+
## [0.2.1]
|
|
6
|
+
|
|
7
|
+
Requires Node 22.19+ and stable Pi 1.5.2 or newer. Tested host remains Pi 1.5.2;
|
|
8
|
+
newer stable hosts are allowed, not guaranteed compatible. No configuration migration is
|
|
9
|
+
required. Let active tasks finish before updating, then restart Pi; reload and shutdown
|
|
10
|
+
abort and drain active children rather than migrating them. Permissions, scheduling limits
|
|
11
|
+
and lifecycle behavior are unchanged.
|
|
12
|
+
|
|
13
|
+
- Keep Hub tree lanes, unselected agent names and status text in the normal foreground color. Highlight the selected name and selection marker with the accent color, while profile words and status circles retain lifecycle coloring, including compact views.
|
|
14
|
+
|
|
15
|
+
- Replace the widget activity preview with a summary below the visible child when its parent has additional hidden running children. Show “2 more nested subagents running” for the capacity illustration while keeping the total hidden-fleet overflow count unchanged.
|
|
16
|
+
|
|
17
|
+
- Add lifecycle-colored status circles to the Hub roster and compact selected-agent header. Use a tee for widget activity when a visible child follows, preserving the last child's elbow connector.
|
|
18
|
+
|
|
19
|
+
- Render connected subagent trees with three-column widget lanes and four-column Hub lanes, last-sibling elbow branches and continuing ancestor pipes, including aligned activity/profile rows. Group descendants by parent generation. The widget closes its last visible nested sibling before the overflow summary; Hub connectors reflect the full roster across viewport clipping. Remove blank separator rows between Hub agents and refresh the README illustrations. Indentation remains capped at three displayed levels and width/row bounds are unchanged.
|
|
20
|
+
|
|
21
|
+
- Refresh README Hub and widget illustrations to show the default capacity of 16 running tasks and 32 queued, with depth-two scout/review nesting and bounded widget overflow. Move the widget to the README introduction and the Hub image into its own section. Generate fixtures from the scheduling defaults and retain explicit synthetic-data disclosures; runtime limits are unchanged.
|
|
22
|
+
|
|
23
|
+
- Simplify README installation and update guidance now that the repository rename is complete. Keep current npm/Git sources, duplicate-loading precautions and a link to the historical package migration instructions.
|
|
24
|
+
|
|
25
|
+
## [0.2.0]
|
|
26
|
+
|
|
27
|
+
Requires Node 22.19+ and stable Pi 1.5.2 or newer. Tested host: Pi 1.5.2; newer stable
|
|
28
|
+
hosts are allowed, not guaranteed compatible. The npm package remains `@howarewoo/pi-subagents`.
|
|
29
|
+
|
|
30
|
+
- Prepare the GitHub repository rename from `howarewoo/pi-extended-subagents` to `howarewoo/pi-subagents`: update canonical links, Git installation examples, package metadata and the release repository guard. The npm package remains `@howarewoo/pi-subagents`; the production entrypoint and runtime behavior are unchanged. The repository owner must coordinate the GitHub rename and verify npm trusted publishing before the next release; these external settings are not changed here.
|
|
31
|
+
|
|
32
|
+
- Simplify the README: put delegation examples before comparisons and architectural rationale, shorten repeated explanations, and make native controls and execution limits easier to scan. Preserve examples, section anchors and safety boundaries.
|
|
33
|
+
- Replace the README's unknown tintinweb messaging comparison with source-verified limited support: parent-to-child steering and result return, without built-in child-initiated or sibling messaging.
|
|
34
|
+
- Clarify in the README and advanced policy documentation that worktree lifecycle management is intentionally caller-owned, not a deferred extension feature; distinguish it from deferred filesystem isolation. Existing `cwd` support, parent permission hooks and global writer serialization are unchanged; workspace selection is not filesystem containment.
|
|
35
|
+
- Compact collapsed Delegate results to task headlines and statuses, keeping error and pause reasons visible. Use Pi’s global tool-output toggle (`Ctrl+O` by default, or the configured binding) to reveal detailed cards; model-facing results, saved artifacts and Subagent Hub behavior are unchanged.
|
|
36
|
+
- Enable child-local codemode for every subagent profile, including nested agents, when codemode is enabled in the parent. Scripts expose only child-authorized tools, with the `models` API disabled; existing permission hooks, workspace mapping, tool budgets and cancellation remain enforced. Failed or permission-blocked edits and writes do not trigger the prewalk model handoff.
|
|
37
|
+
- Remove persistent writer warnings from the pinned Subagents widget and Subagent Hub footer, freeing space for task activity. Keep the coordination caveat in Hub Details and the README; writer serialization is unchanged.
|
|
38
|
+
- Remove unused provider-secret bindings and credential examples from the Pullfrog workflow while retaining its OIDC App token integration.
|
|
39
|
+
- Create new task/generation, agent and transcript directories with private POSIX mode `0700`, preserving exclusive creation and `0600` outcome artifacts. Existing records and parent/global storage permissions are unchanged; Windows access control remains dependent on filesystem ACLs.
|
|
40
|
+
- Enforce live initiator/ancestor grant revocation for nested task-file reads, spawning and coordination before protected effects; malformed policy fails closed. Already in-flight work and accepted mailbox effects are not rolled back.
|
|
41
|
+
|
|
42
|
+
### Release isolation
|
|
43
|
+
|
|
44
|
+
- Separate release validation, human-protected npm publication and GitHub release creation into jobs with distinct credentials. Publish only the exact smoke-tested tarball after mandatory SHA-512 and release-identity verification; suppress npm lifecycle scripts.
|
|
45
|
+
- Repository owners must configure the `npm` environment approval and release-tag protections, and verify npm trusted publishing before a live release. These account settings are not configured by the workflow.
|
|
46
|
+
|
|
47
|
+
### Breaking — minimum supported Pi version
|
|
48
|
+
|
|
49
|
+
- Require stable Pi 1.5.2 or newer for delegated execution, including native and compatibility launches, resume, followup, revive and direct coordinator execution. Below-minimum, prerelease, malformed and unknown versions reject before task-file reads, child allocation, task-directory setup or child model requests, with an error naming the detected version and minimum stable version. Newer stable patch, minor and major versions are allowed; standard build metadata has equal precedence. Tested host remains Pi 1.5.2, not a compatibility guarantee for future allowed stable versions.
|
|
50
|
+
- Keep required wildcard host peers and pinned SDK development packages unchanged. Wildcard peers are a Pi packaging requirement, not a promise of support for every host. Root status, stop/cleanup and diagnostics remain usable where the host can load the extension; arbitrary ancient SDK module-load compatibility is not promised.
|
|
51
|
+
- Migration from 0.1.x: let active tasks drain, install stable Pi 1.5.2 or newer, update the extension to `@howarewoo/pi-subagents@0.2.0` and restart Pi. Shutdown or reload aborts and drains active children rather than migrating them.
|
|
52
|
+
|
|
3
53
|
## [0.1.1]
|
|
4
54
|
|
|
5
55
|
### Scoped npm package
|
package/README.md
CHANGED
|
@@ -1,105 +1,44 @@
|
|
|
1
1
|
# @howarewoo/pi-subagents
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@howarewoo/pi-subagents)
|
|
4
|
+
[](https://www.npmjs.com/package/@howarewoo/pi-subagents)
|
|
5
|
+
|
|
3
6
|
Delegate work to subagents in Pi, follow their progress, and steer or stop them from Subagent Hub. Subagents use your selected model by default, with their own assignments and explicit tool grants.
|
|
4
7
|
|
|
5
|
-
|
|
6
9
|
|
|
7
|
-
|
|
10
|
+
_Pinned Subagents widget at default capacity: 16 running tasks and 32 queued. Counts and nested-agent progress stay visible above the editor. Synthetic demo data, not a live load test._
|
|
8
11
|
|
|
9
12
|
## Installation
|
|
10
13
|
|
|
11
|
-
Requires Node 22.19
|
|
14
|
+
Requires **Node 22.19+** and **stable Pi 1.5.2 or newer**. Tested host: Pi 1.5.2;
|
|
15
|
+
newer stable versions are allowed, not guaranteed compatible. Prerelease, older, malformed
|
|
16
|
+
and unknown host versions are rejected before task reads, allocation or model requests.
|
|
17
|
+
Wildcard host peer dependencies follow Pi's package format, not a compatibility promise.
|
|
18
|
+
See [host support](docs/delegation-contract.md#supported-host) for version rules.
|
|
12
19
|
|
|
13
|
-
|
|
20
|
+
If the host is unsupported, let active tasks drain, update Pi and restart. Status,
|
|
21
|
+
stop/cleanup and diagnostics remain available where the extension can load; arbitrary
|
|
22
|
+
older SDKs may fail at module load. The minimum-host restriction is a breaking change
|
|
23
|
+
in 0.2.0. When upgrading from 0.1.x, drain active tasks, install stable Pi 1.5.2 or newer,
|
|
24
|
+
update the extension and restart Pi.
|
|
14
25
|
|
|
15
|
-
|
|
16
|
-
pi install npm:@howarewoo/pi-subagents
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
### Migrate from the old package
|
|
20
|
-
|
|
21
|
-
If you installed `pi-extended-subagents`, remove it before installing the scoped package
|
|
22
|
-
so Pi does not load the extension twice:
|
|
26
|
+
Install from npm:
|
|
23
27
|
|
|
24
28
|
```sh
|
|
25
|
-
pi remove npm:pi-extended-subagents
|
|
26
29
|
pi install npm:@howarewoo/pi-subagents
|
|
27
30
|
```
|
|
28
31
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
+
Alternatively, install from Git with `pi install git:github.com/howarewoo/pi-subagents`.
|
|
33
|
+
Use only one source: when switching between npm, Git or a local checkout, remove the
|
|
34
|
+
previously registered source first so Pi does not load the extension twice.
|
|
32
35
|
|
|
33
|
-
Restart Pi and run `/subagent-profiles` to check the installation.
|
|
36
|
+
Restart Pi and run `/subagent-profiles` to check the installation.
|
|
34
37
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
Let active subagents finish before updating, then restart Pi. Shutdown or `/reload` aborts
|
|
38
|
-
and drains children; active tasks are not migrated to the new version. There is no extension-owned
|
|
39
|
-
auto-updater.
|
|
40
|
-
|
|
41
|
-
```sh
|
|
42
|
-
# Update an unpinned npm installation
|
|
43
|
-
pi update npm:@howarewoo/pi-subagents
|
|
44
|
-
|
|
45
|
-
# Or update all installed extension packages
|
|
46
|
-
pi update --extensions
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
Plain `pi update` updates Pi itself, not installed extension packages. For a Git installation,
|
|
50
|
-
use `pi update git:github.com/howarewoo/pi-extended-subagents`; an unpinned Git source tracks
|
|
51
|
-
the repository's default branch, including unreleased commits.
|
|
52
|
-
|
|
53
|
-
For a reproducible npm installation or rollback, select an exact published version:
|
|
54
|
-
|
|
55
|
-
```sh
|
|
56
|
-
pi install npm:@howarewoo/pi-subagents@0.1.1
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
For Git, select a published tag, for example
|
|
60
|
-
`pi install git:github.com/howarewoo/pi-extended-subagents@v0.1.1`.
|
|
61
|
-
Exact npm versions and Git tags stay pinned; updating does not advance them to the next release.
|
|
62
|
-
Install a different version explicitly to change the pin.
|
|
63
|
-
|
|
64
|
-
[CHANGELOG.md](CHANGELOG.md) lists user-facing changes and migrations. Pi shows new package
|
|
65
|
-
changelog entries on the next fresh launch after a version increase. See the
|
|
66
|
-
[maintainer release guide](docs/releases.md) for publishing and recovery.
|
|
67
|
-
|
|
68
|
-
## Feature comparison
|
|
69
|
-
|
|
70
|
-
Compared with two community alternatives using their documentation, checked on 2026-11-11. This is a feature comparison, not a performance or reliability benchmark. UI cells name documented surfaces; they do not imply other features are absent.
|
|
71
|
-
|
|
72
|
-
| Feature | @howarewoo/pi-subagents | [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) | [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents) |
|
|
73
|
-
| ------------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
|
|
74
|
-
| Background tasks | Until parent exit or reload | ✓ Supported | ✓ Supported |
|
|
75
|
-
| Nested delegation | Opt-in; foreground only | Opt-in | Opt-in |
|
|
76
|
-
| Task list / conversation | Subagent Hub: split panes; full-width thread on narrow terminals | Fleet inspector: roster and output pane | FleetView opens a separate conversation viewer |
|
|
77
|
-
| Message / tool rendering | Native Pi message and tool components | Structured Markdown/tool transcripts | Markdown + session-registered tool renderers |
|
|
78
|
-
| Live follow / scrollback | ✓ Scroll up to pause; End to follow | ✓ Scroll away to pause; bottom resumes | ✓ Scroll up to pause; End to follow |
|
|
79
|
-
| In-UI task controls | Hub: steer, inbox, stop, wait, park | Inspector: steer/follow-up and stop async runs | Viewer: steer, stop, foreground-to-background handoff |
|
|
80
|
-
| Tool / usage inspection | Tools: sanitized arguments/results; Details: direct usage | Expandable tool details + token counts | Expandable tool output + tokens; optional cost |
|
|
81
|
-
| Schema-validated results | ✓ Supported | ✓ Supported | Workflow agents only |
|
|
82
|
-
| Managed Git worktrees | — Not supported | ✓ Supported | ✓ Supported |
|
|
83
|
-
| Workflow scripts | — Not supported | ✓ Supported | ✓ Supported |
|
|
84
|
-
| Scheduled runs | — Not supported | ✓ Supported | Session-scoped agents only |
|
|
85
|
-
|
|
86
|
-
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).
|
|
87
|
-
|
|
88
|
-
## Native orchestration
|
|
89
|
-
|
|
90
|
-
Pi discovers the native `subagent` tool at startup through its tool description and coding-worker guidance; no enable call is needed. For replacement use, load only one extension providing `subagent`: Pi uses the first registration, not an automatic provider preference. Switching providers does not migrate or remove old runs.
|
|
91
|
-
|
|
92
|
-
```json
|
|
93
|
-
{
|
|
94
|
-
"agent": "worker",
|
|
95
|
-
"task": "Implement the approved change; follow the supplied repository guidelines and task references",
|
|
96
|
-
"cwd": "/absolute/path/to/task-worktree"
|
|
97
|
-
}
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
`worker` uses the configured `implementation` profile. `scout`, `review` and `general` are also available. Calls are async by default and wake the parent after drain; set `async:false` to wait. Batches use `tasks:[{agent,task,cwd?}]`. Use the returned `id` with `action:"status"`, `"steer"`, `"stop"` or `"resume"`; steer/resume also need `message`.
|
|
38
|
+
### Migrate from the old package
|
|
101
39
|
|
|
102
|
-
|
|
40
|
+
If you installed the former unscoped package, follow the
|
|
41
|
+
[0.1.1 migration instructions](CHANGELOG.md#011) before installing the current package.
|
|
103
42
|
|
|
104
43
|
## Use delegation
|
|
105
44
|
|
|
@@ -135,9 +74,9 @@ The default is 16 concurrent tasks, a 32-item queue and up to 16 tasks per batch
|
|
|
135
74
|
|
|
136
75
|
`scout` and `review` allow up to `read`, `grep`, `find` and `ls`. `general` and `implementation` also allow `write`, `edit` and `bash`. Each role receives only the builtins already callable in the parent. With Pi's default tools, scouts get `read` only. Tool calls retain the parent's permission hooks; incompatible tool overrides are rejected.
|
|
137
76
|
|
|
138
|
-
`general`
|
|
77
|
+
`general` inherits available parent skills, not parent instructions or history. Its role prompt and assignment remain intact. Operator/trusted-project `tools` and `skills` settings can narrow inheritance; `[]` removes grants. General can write when its effective tool set allows it.
|
|
139
78
|
|
|
140
|
-
|
|
79
|
+
**Extension/MCP tools require operator review.** Set `general.leafTools` to exact names only for trusted tools that never call other Pi tools or change the tool/model/session loadout. Descriptions and annotations do not grant trust. Orchestrating/reaching tools, codemode, tool search, owned controls, hidden/model-only tools and builtin replacements cannot be forwarded. Leaf tools require the global writer lease and the root workspace; only builtins support cwd adaptation. See [restricted inheritance](docs/delegation-contract.md#restricted-general-inheritance).
|
|
141
80
|
|
|
142
81
|
Foreground calls return the final results. Set `background:true` to return immediately and receive one ordered completion message after the batch drains. Use the returned task ID and generation for controls:
|
|
143
82
|
|
|
@@ -150,6 +89,25 @@ Foreground calls return the final results. Set `background:true` to return immed
|
|
|
150
89
|
/subagent-hub
|
|
151
90
|
```
|
|
152
91
|
|
|
92
|
+
## Native orchestration
|
|
93
|
+
|
|
94
|
+
Pi discovers the native `subagent` tool at startup through its tool description and coding-worker guidance; no enable call is needed. For replacement use, load only one extension providing `subagent`: Pi uses the first registration, not an automatic provider preference. Switching providers does not migrate or remove old runs.
|
|
95
|
+
|
|
96
|
+
```json
|
|
97
|
+
{
|
|
98
|
+
"agent": "worker",
|
|
99
|
+
"task": "Implement the approved change; follow the supplied repository guidelines and task references",
|
|
100
|
+
"cwd": "/absolute/path/to/task-worktree"
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
- `worker` maps to the configured `implementation` profile; `scout`, `review` and `general` are also available.
|
|
105
|
+
- Calls are async by default and wake the parent after drain. Set `async:false` to wait; use `tasks:[{agent,task,cwd?}]` for a batch.
|
|
106
|
+
- Control a task with its returned `id` and `action:"status"`, `"steer"`, `"stop"` or `"resume"`. Steer/resume also require `message`.
|
|
107
|
+
- Resume keeps a paused conversation in the same generation. Completed idle/parked work gets a fresh generation, so include needed prior conclusions.
|
|
108
|
+
|
|
109
|
+
The coordinator supplies an existing workspace and the complete handoff, including accessible skill/reference paths. The extension does not create or manage worktrees. This is the [supported orchestration interface](docs/delegation-contract.md#native-orchestration-compatibility), not compatibility with every competing workflow script or custom agent definition.
|
|
110
|
+
|
|
153
111
|
## Subagent Profiles
|
|
154
112
|
|
|
155
113
|
Run `/subagent-profiles` to inspect the resolved profiles for the current workspace: bundled definitions, operator `delegation.json`, then trusted-project narrowing. It opens a read-only list/details overlay, not an editor. Reopen it after configuration changes to refresh the snapshot.
|
|
@@ -164,15 +122,15 @@ _Synthetic native-component output; not a terminal screenshot or live-provider v
|
|
|
164
122
|
|
|
165
123
|
## Subagent Hub
|
|
166
124
|
|
|
167
|
-
Subagent Hub shows the
|
|
125
|
+
Subagent Hub shows the task list beside the selected conversation using Pi's native renderers. On narrow terminals, the conversation takes the full width. Details shows results, artifacts, grants and usage; Tools shows full sanitized arguments and result text.
|
|
168
126
|
|
|
169
127
|
The thread follows new output until you scroll up. Press End to follow again. The pinned Subagents widget appears after the first task starts. Closing Subagent Hub does not stop the work.
|
|
170
128
|
|
|
171
|
-
|
|
129
|
+
The Hub and widget illustrations use native renderer output with a synthetic fleet filling the default 16 concurrent slots and 32-item queue. Four read-only audit leads each have three foreground descendants, reaching the default nesting depth of two. The queue represents two further 16-task root batches, not one oversized batch. These are illustrations, not terminal screenshots or live-provider stress-test evidence. Regenerate them with `node scripts/render-hub-hero.ts` and `node scripts/render-hub-hero.ts --widget`.
|
|
172
130
|
|
|
173
|
-
|
|
174
132
|
|
|
175
|
-
|
|
133
|
+
_Subagent Hub at default capacity: tasks and conversations side by side, with nested scouts/reviewers at depth two. The roster scrolls through all 48 tasks._
|
|
176
134
|
|
|
177
135
|
| Key | Action |
|
|
178
136
|
| --------------------- | ------------------------------------------------- |
|
|
@@ -236,25 +194,238 @@ No configuration is needed for the bundled roles. To change prompts or narrow to
|
|
|
236
194
|
|
|
237
195
|
All bundled profiles may delegate to `scout` and `review` by default, within a total depth of two (root 0, child 1, grandchild 2). Other nested targets and child messaging need explicit operator grants. Set `spawn: []` to revoke nesting. General inherits available parent skills; other roles need explicit skill grants. Trusted project configuration in `.pi/delegation.json` can narrow grants, never expand them. Children do not load ambient extension/MCP runtimes or context files; general can forward only the reviewed leaf tools described above.
|
|
238
196
|
|
|
239
|
-
|
|
197
|
+
Default task limits are **30 minutes**, **100 model requests** and **100 tool calls**:
|
|
198
|
+
|
|
199
|
+
- A deadline pauses the active subtree after tool/provider drain, releasing capacity and writer leases but retaining sessions and conversations.
|
|
200
|
+
- Use `subagent` resume or root-only `delegate_coordinate` `{action:"resume",target:{id,generation},assignment:"Continue…"}` to continue the same identity and conversation. Only the deadline resets; request/tool/spawn counters remain cumulative.
|
|
201
|
+
- Resume the parent first, then explicitly selected children. Descendants never resume automatically.
|
|
202
|
+
- Stop, shutdown and hard request/tool limits cancel and dispose. Unresponsive code must drain before pause or cancellation can release resources.
|
|
203
|
+
|
|
204
|
+
See [limits and nesting](docs/delegation-contract.md#capacity-and-bounded-execution), [profile grants](docs/delegation-contract.md#subagent-profiles-and-explicit-spawn-grants), and [model selection and prewalk](docs/advanced-policies.md).
|
|
240
205
|
|
|
241
206
|
## Shared checkout and lifetime
|
|
242
207
|
|
|
243
|
-
Subagents use your checkout
|
|
208
|
+
Subagents use your checkout unless you supply an existing directory as `cwd`. Parent permission hooks still apply and may deny access. **Writers serialize even across worktrees**, and workspace selection is not a sandbox. Manual commands, external editors and other sessions are uncoordinated: avoid conflicting edits. See [workspace safety](#why-workspaces-are-caller-managed-and-writers-serialize).
|
|
244
209
|
|
|
245
|
-
|
|
210
|
+
Keep the parent runtime alive until work finishes. Shutdown or reload aborts and drains children; there is no restart recovery or cross-parent revival. Saved transcripts and results may contain sensitive task, tool and model output; protect them like your main Pi transcripts.
|
|
246
211
|
|
|
247
212
|
### Why worktrees are managed externally
|
|
248
213
|
|
|
249
|
-
|
|
214
|
+
Create or select a workspace externally, then pass `cwd` as in the
|
|
215
|
+
[native orchestration example](#native-orchestration). The caller owns it throughout the
|
|
216
|
+
assignment, including inspection, integration and removal. Automatic worktree creation,
|
|
217
|
+
commits, apply and cleanup are intentionally outside scope, not planned features.
|
|
250
218
|
|
|
251
|
-
|
|
219
|
+
Separate worktrees neither bypass writer serialization nor provide a sandbox.
|
|
220
|
+
See [workspace ownership and writer coordination](#why-workspaces-are-caller-managed-and-writers-serialize).
|
|
252
221
|
|
|
253
222
|
### Why workflows and scheduling stay external
|
|
254
223
|
|
|
255
|
-
|
|
224
|
+
Separate packages can compose the public delegation tools and own when and how to run
|
|
225
|
+
assignments within the parent runtime. This does not grant automatic tool/context
|
|
226
|
+
inheritance or promise compatibility with existing third-party workflow packages.
|
|
227
|
+
See [orchestration boundaries](#why-orchestration-stays-with-the-caller).
|
|
228
|
+
|
|
229
|
+
## Updates and rollback
|
|
230
|
+
|
|
231
|
+
Let active subagents finish before updating, then restart Pi. Shutdown or `/reload` aborts
|
|
232
|
+
and drains children; active tasks are not migrated to the new version. There is no extension-owned
|
|
233
|
+
auto-updater.
|
|
234
|
+
|
|
235
|
+
```sh
|
|
236
|
+
# Update an unpinned npm installation
|
|
237
|
+
pi update npm:@howarewoo/pi-subagents
|
|
238
|
+
|
|
239
|
+
# Or update all installed extension packages
|
|
240
|
+
pi update --extensions
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Plain `pi update` updates Pi itself, not installed extension packages. For a Git installation,
|
|
244
|
+
use `pi update git:github.com/howarewoo/pi-subagents`, matching the source you registered.
|
|
245
|
+
An unpinned Git source tracks the repository's default branch, including unreleased commits.
|
|
246
|
+
|
|
247
|
+
For a reproducible npm installation or rollback, select an exact published version:
|
|
248
|
+
|
|
249
|
+
```sh
|
|
250
|
+
pi install npm:@howarewoo/pi-subagents@0.2.0
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
For Git, select a published tag, for example
|
|
254
|
+
`pi install git:github.com/howarewoo/pi-subagents@v0.2.0`.
|
|
255
|
+
Exact npm versions and Git tags stay pinned; updating does not advance them to the next release.
|
|
256
|
+
Install a different version explicitly to change the pin.
|
|
257
|
+
|
|
258
|
+
[CHANGELOG.md](CHANGELOG.md) lists user-facing changes and migrations. Pi shows new package
|
|
259
|
+
changelog entries on the next fresh launch after a version increase. See the
|
|
260
|
+
[maintainer release guide](docs/releases.md) for publishing and recovery.
|
|
261
|
+
|
|
262
|
+
## Feature comparison
|
|
263
|
+
|
|
264
|
+
Compared with two community alternatives using their documentation, checked on 2026-11-11. Tintinweb's messaging scope was additionally checked against source at revision `b72b414` (2026-11-12). This is a feature comparison, not a performance or reliability benchmark. UI cells name documented surfaces; they do not imply other features are absent.
|
|
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.
|
|
282
|
+
|
|
283
|
+
🚫 marks a deliberate product boundary, not a missing implementation within the current
|
|
284
|
+
contract. Linked explanations describe the trade-offs behind this repo's choices.
|
|
285
|
+
|
|
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).
|
|
287
|
+
|
|
288
|
+
## Architectural decisions
|
|
289
|
+
|
|
290
|
+
These choices define the current execution contract and its trade-offs. They are not
|
|
291
|
+
claims that other designs are unsafe or impossible. Deferred capabilities are identified
|
|
292
|
+
separately; an unsupported feature is not automatically a permanent exclusion.
|
|
293
|
+
|
|
294
|
+
### Why background tasks are parent-bound
|
|
295
|
+
|
|
296
|
+
Background tasks belong to the live parent Pi runtime. Shutdown or `/reload` cancels
|
|
297
|
+
children and drains their tools and descendants before releasing capacity and writer
|
|
298
|
+
leases. Closing Subagent Hub does not stop work. This prevents replacement writers
|
|
299
|
+
from overlapping tools that are still stopping.
|
|
300
|
+
|
|
301
|
+
Keep Pi running until tasks finish: there is no detached runner or restart recovery.
|
|
302
|
+
Unresponsive provider, permission or tool code can delay drain; abrupt process death
|
|
303
|
+
cannot guarantee cleanup. Saved transcripts are inspection records, not restart state.
|
|
304
|
+
|
|
305
|
+
In the cited versions, nicobailon uses detached background processes. Tintinweb stops
|
|
306
|
+
agents on shutdown but supports persisted conversation resume and foreground-to-background
|
|
307
|
+
handoff. Persisted conversations do not keep jobs running after exit.
|
|
308
|
+
See [the delegation contract](docs/delegation-contract.md) for continuation semantics.
|
|
309
|
+
|
|
310
|
+
### Why nested delegation is foreground-only
|
|
311
|
+
|
|
312
|
+
Nested calls require explicit profile grants and wait for their children while retaining
|
|
313
|
+
their execution slot. Work that cannot start immediately is rejected rather than queued
|
|
314
|
+
behind waiting ancestors or given extra capacity. A writing child cannot spawn another
|
|
315
|
+
writer beneath itself.
|
|
316
|
+
|
|
317
|
+
This keeps capacity and ownership predictable but limits fan-out. Parent completion or
|
|
318
|
+
stop drains descendants; there are no detached grandchildren.
|
|
319
|
+
See [lifecycle and scheduling](ARCHITECTURE.md#lifecycle-and-scheduling).
|
|
320
|
+
|
|
321
|
+
### Why permissions and resources are explicit
|
|
322
|
+
|
|
323
|
+
Profiles cap tools at what the parent can call. Builtin calls retain the parent's
|
|
324
|
+
permission hooks; operator grants set authority, and trusted-project configuration and
|
|
325
|
+
task requests can only narrow it. Selecting another workspace does not load its trust policy.
|
|
326
|
+
|
|
327
|
+
Children receive their assignment, role prompt and granted skills, not parent
|
|
328
|
+
instructions, history or ambient context. General also inherits available skills and
|
|
329
|
+
may use exact operator-reviewed leaf tools. Full extension/MCP runtime inheritance and
|
|
330
|
+
tool-to-tool forwarding are unsupported, so provide a complete handoff.
|
|
331
|
+
Tool grants and cwd adaptation are not an OS sandbox.
|
|
332
|
+
See [permission and resource boundaries](ARCHITECTURE.md#permission-and-resource-boundaries).
|
|
333
|
+
|
|
334
|
+
### Why model routing is exact
|
|
335
|
+
|
|
336
|
+
Children use the parent's selected model and effort by default. Overrides require exact
|
|
337
|
+
operator-approved provider/model/effort grants. Unavailable selections and unsupported
|
|
338
|
+
effort fail visibly; there is no automatic cheaper-model or provider fallback.
|
|
339
|
+
Authentication stays with the parent's registry, not child task directories.
|
|
340
|
+
|
|
341
|
+
A configured role prewalk can make one approved model switch after an edit/write call;
|
|
342
|
+
it adds no hidden planning inference.
|
|
343
|
+
See [models and authentication](ARCHITECTURE.md#models-and-authentication).
|
|
344
|
+
|
|
345
|
+
### Why workspaces are caller-managed and writers serialize
|
|
346
|
+
|
|
347
|
+
Pass an existing directory as `cwd`, including a caller-created worktree. The extension
|
|
348
|
+
adapts builtin paths and shell cwd through parent permission hooks. Worktree creation,
|
|
349
|
+
branch/base selection, integration and cleanup stay with the caller or separate tooling,
|
|
350
|
+
keeping this extension focused on subagent execution, coordination and UI.
|
|
351
|
+
|
|
352
|
+
Workspace selection is not containment: paths and shell commands can reach outside the
|
|
353
|
+
directory when parent permissions allow. Effective writing tasks share one global lease,
|
|
354
|
+
even across worktrees; coordinated parent model-tool mutations cannot overlap a child
|
|
355
|
+
writer. The lease lasts through actual drain, sacrificing parallel writing throughput
|
|
356
|
+
rather than assuming different directories isolate every write.
|
|
357
|
+
|
|
358
|
+
Manual `!`/`!!` commands, external editors, other sessions and arbitrary extension
|
|
359
|
+
JavaScript are not coordinated. Avoid conflicting edits while a subagent writes.
|
|
360
|
+
See [tool execution and workspaces](ARCHITECTURE.md#tool-execution-and-workspaces)
|
|
361
|
+
and [explicit working directory](docs/delegation-contract.md#explicit-working-directory).
|
|
362
|
+
|
|
363
|
+
### Why structured results require explicit submission
|
|
364
|
+
|
|
365
|
+
Schema-required children must call `submit_result` with a value matching the supported
|
|
366
|
+
bounded JSON Schema subset. Final prose is not parsed. Submission is provisional until
|
|
367
|
+
execution and descendants drain: it cannot override cancellation or failure, and a
|
|
368
|
+
missing required submission fails the task.
|
|
369
|
+
|
|
370
|
+
Whole batches pass preflight before admission. Results keep input order, and a failed
|
|
371
|
+
child does not cancel unrelated siblings. Background batches send one outcome after
|
|
372
|
+
drain, so fast results may wait for slower siblings.
|
|
373
|
+
See [results and persistence](ARCHITECTURE.md#results-and-persistence).
|
|
374
|
+
|
|
375
|
+
### Why the UI observes one native registry
|
|
376
|
+
|
|
377
|
+
Hub, the widget and result cards observe the same coordinator; viewers do not start
|
|
378
|
+
another executor. Pi's native components render sanitized conversations, using split
|
|
379
|
+
panes or a full-width thread on narrow terminals.
|
|
380
|
+
|
|
381
|
+
Usage is reported directly per generation, without recursive parent totals or estimates
|
|
382
|
+
for missing provider usage. Display sanitization does not redact saved files.
|
|
383
|
+
See [observation and terminal UI](ARCHITECTURE.md#observation-and-terminal-ui).
|
|
384
|
+
|
|
385
|
+
### Why controls are identity-pinned
|
|
256
386
|
|
|
257
|
-
|
|
387
|
+
Controls target a UUID and generation, so stale selections cannot change newer
|
|
388
|
+
assignments. Paused continuation keeps its conversation; follow-up or revival of completed
|
|
389
|
+
work starts a fresh generation under current, narrowed authority. Supply needed prior
|
|
390
|
+
conclusions: old transcripts are not replayed.
|
|
391
|
+
|
|
392
|
+
Hub uses the same registry authority as the tools, but cannot start new generations:
|
|
393
|
+
its command context lacks Pi's permission-preserving tool dispatcher. Use model-issued
|
|
394
|
+
tool calls for those actions.
|
|
395
|
+
See [coordination, presence and generations](ARCHITECTURE.md#coordination-presence-and-generations).
|
|
396
|
+
|
|
397
|
+
### Why agent messaging is family-scoped
|
|
398
|
+
|
|
399
|
+
Explicit grants allow parent/child messages in both directions and sibling messages
|
|
400
|
+
within the same exact parent generation. Senders must know the recipient's UUID and
|
|
401
|
+
generation. Children cannot enumerate the registry, address arbitrary sessions or read
|
|
402
|
+
peer transcripts.
|
|
403
|
+
|
|
404
|
+
`delegate_coordinate` supports inbox, steering/follow-up delivery and bounded event-driven
|
|
405
|
+
waits. Recipients must be running; inbox delivery does not trigger parent inference.
|
|
406
|
+
Receipts distinguish acceptance, queuing and visibility, not model acknowledgment.
|
|
407
|
+
Mailboxes and waits are finite, waits retain capacity, and cycles are rejected. Callers
|
|
408
|
+
must arrange identities and replies; this is not a durable broker or blocking supervisor
|
|
409
|
+
interview.
|
|
410
|
+
|
|
411
|
+
Nicobailon documents child `contact_supervisor` requests and parent `subagent_supervisor`
|
|
412
|
+
replies, including nested supervision. Tintinweb implements steering and result return.
|
|
413
|
+
At `b72b414`, its [nested steering tool](https://github.com/tintinweb/pi-subagents/blob/b72b414581d8aa9bbfb1d44c832aed0d0b0b9053/src/nested-tools.ts#L400-L430)
|
|
414
|
+
targets only owned children; its [completion outbox](https://github.com/tintinweb/pi-subagents/blob/b72b414581d8aa9bbfb1d44c832aed0d0b0b9053/src/index.ts#L466-L497)
|
|
415
|
+
returns results, not child-initiated dialogue. No built-in upstream or sibling messaging
|
|
416
|
+
was found in that source inspection.
|
|
417
|
+
See the [coordination contract](docs/delegation-contract.md#live-parent-messaging-waits-and-presence).
|
|
418
|
+
|
|
419
|
+
### Why orchestration stays with the caller
|
|
420
|
+
|
|
421
|
+
The caller owns the larger plan and workspace preparation. This extension provides
|
|
422
|
+
bounded assignments, batches and live coordination, not a workflow-script runtime or
|
|
423
|
+
scheduling service. Scripts and recurring jobs need separate tooling and must respect
|
|
424
|
+
the live-parent lifetime.
|
|
425
|
+
|
|
426
|
+
The native `subagent` interface uses the same executor; it does not interpret competitors'
|
|
427
|
+
workflow scripts or custom agent definitions.
|
|
428
|
+
See [entry points and runtime ownership](ARCHITECTURE.md#entry-points-and-runtime-ownership).
|
|
258
429
|
|
|
259
430
|
## Documentation
|
|
260
431
|
|
|
@@ -54,7 +54,9 @@ A boundary-only one-shot review changes the product meaning and already overlaps
|
|
|
54
54
|
|
|
55
55
|
## Production isolation — deferred and unimplemented
|
|
56
56
|
|
|
57
|
-
Filesystem isolation
|
|
57
|
+
Filesystem isolation remains deferred and unimplemented. Worktree lifecycle management is intentionally caller-owned: automatic worktree creation, commits, copying/apply and cleanup are outside scope, not planned extension features. See [why worktrees are managed externally](../README.md#why-worktrees-are-managed-externally).
|
|
58
|
+
|
|
59
|
+
Existing caller-supplied workspaces are supported through explicitly approved file-path and shell-cwd adaptation, preserving the original parent dispatcher and its hooks. Hooks see the actual transformed arguments, not a transparently rebound cwd. The public dispatcher still has no per-call cwd. This execution adapter and the global model-tool writer lease are not filesystem containment or an OS sandbox; see [the workspace contract](delegation-contract.md#explicit-working-directory).
|
|
58
60
|
|
|
59
61
|
## Bounded investigations — not enabled
|
|
60
62
|
|
|
@@ -73,4 +75,4 @@ The exact extension-path and busy-prompt counterexamples are in `test/advanced-c
|
|
|
73
75
|
|
|
74
76
|
## Joined fleet consumer
|
|
75
77
|
|
|
76
|
-
The one registry still owns queued/setup/running/draining/terminal state, limits, identity/generation/history, artifacts and direct telemetry. The joined native fleet widget/cards/Hub display those alongside actual model/effort and prewalk armed/handed-off/suppressed-exact/no-op, immutable selected-generation history and separate presence. No inferred role fallback, subtree double billing, new provider call or advisor observer is added. Hub input/stop/message targets stay pinned to original UUID+generation. Native followup/revive remains model-issued only because Hub command context has no permission-preserving dispatcher. See the [supported surface table](delegation-contract.md#storage-and-fleet-observation). Explicit workspace path/shell adaptation is supported; production filesystem isolation
|
|
78
|
+
The one registry still owns queued/setup/running/draining/terminal state, limits, identity/generation/history, artifacts and direct telemetry. The joined native fleet widget/cards/Hub display those alongside actual model/effort and prewalk armed/handed-off/suppressed-exact/no-op, immutable selected-generation history and separate presence. No inferred role fallback, subtree double billing, new provider call or advisor observer is added. Hub input/stop/message targets stay pinned to original UUID+generation. Native followup/revive remains model-issued only because Hub command context has no permission-preserving dispatcher. See the [supported surface table](delegation-contract.md#storage-and-fleet-observation). Explicit workspace path/shell adaptation is supported; production filesystem isolation remains deferred, worktree lifecycle management remains caller-owned and retained advisor is excluded from current product scope. Neither excluded advisor nor deferred filesystem isolation is a current release gate. Other unsupported/parked capabilities above remain explicit gaps, not implied support.
|