@narumitw/pi-subagents 2.0.3 → 2.0.4
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 +250 -157
- package/dist/chunks/{chunk-F5YWVHQX.ts → chunk-2OUVSORM.ts} +2 -2
- package/dist/chunks/{config-ui-3IBMHTQB.ts → config-ui-7IMI3I4B.ts} +2 -2
- package/dist/chunks/{create-stateful-transport-4WKZHRSI.ts → create-stateful-transport-F5OG2LEY.ts} +2 -2
- package/dist/chunks/{rpc-transport-Y6LA5BOP.ts → rpc-transport-ZNNBRUSY.ts} +94 -24
- package/dist/chunks/rpc-transport-ZNNBRUSY.ts.map +7 -0
- package/dist/index.ts +2 -2
- package/package.json +2 -2
- package/src/rpc-transport.ts +20 -6
- package/src/rpc-turn-capture.ts +98 -23
- package/dist/chunks/rpc-transport-Y6LA5BOP.ts.map +0 -7
- /package/dist/chunks/{chunk-F5YWVHQX.ts.map → chunk-2OUVSORM.ts.map} +0 -0
- /package/dist/chunks/{config-ui-3IBMHTQB.ts.map → config-ui-7IMI3I4B.ts.map} +0 -0
- /package/dist/chunks/{create-stateful-transport-4WKZHRSI.ts.map → create-stateful-transport-F5OG2LEY.ts.map} +0 -0
package/README.md
CHANGED
|
@@ -1,46 +1,25 @@
|
|
|
1
|
-
# 🧑🤝🧑 pi-subagents —
|
|
1
|
+
# 🧑🤝🧑 pi-subagents — Delegate Work to Specialized Agents
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-subagents) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
By default, it exposes seven capability-specific tools: blocking batches, four detached lifecycle tools, side-effect-free inspection, and synchronous read-only consultation.
|
|
7
|
-
The compatibility default remains **All delegation methods**, while **Async only** is the recommended smaller surface for normal async-first use.
|
|
5
|
+
Delegate bounded research or implementation work to isolated specialist agents while the main Pi agent retains planning, integration, verification, and the final answer.
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
7
|
+
Use the built-in `explorer` for read-only evidence and `worker` for a clearly owned implementation slice.
|
|
8
|
+
|
|
9
|
+
The compatibility default exposes every delegation method, while **Async only** is the recommended smaller surface for normal parallel work.
|
|
12
10
|
|
|
13
11
|
## ✨ Features
|
|
14
12
|
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
-
|
|
25
|
-
- Supports built-in `explorer` and `worker` agents.
|
|
26
|
-
- Loads custom user agents from `~/.pi/agent/agents/*.md`.
|
|
27
|
-
- Optionally loads project agents from `.pi/agents/*.md` with confirmation.
|
|
28
|
-
- Provides a current-session-first `/subagents` manager, direct `settings|status|help` routes, and compatibility aliases for agent tools and retained agents.
|
|
29
|
-
- Supports trust-aware per-task `cwd` policies, task-selected work, workflow, idle, turn, and tool-call budgets, deterministic timeout checkpoints, bounded abort-then-summary recovery, progress telemetry, and per-agent execution defaults.
|
|
30
|
-
- Uses Pi-native tool rows throughout; blocking and consultation calls add bounded custom live activity.
|
|
31
|
-
- Bounds JSON lines, captured messages, stderr, final output, chain substitution, and fan-in context.
|
|
32
|
-
- Enforces a recursion-depth guard and deterministic process-group termination.
|
|
33
|
-
- Gives every retained agent both an opaque durable `agentId` and a session-scoped canonical `taskPath`, while preserving ID compatibility across lifecycle and inspection tools.
|
|
34
|
-
- Gives retained children authenticated `subagent_peer_send` and `subagent_peer_list` tools for bounded queue-only communication with `/root` or any retained peer in the same session.
|
|
35
|
-
- Routes nested completions to the direct retained parent first, while top-level completions continue through the root completion broker.
|
|
36
|
-
- Provides addressable stateful agents with follow-up, consolidated mailbox/management actions, idempotent spawn retries, context selection and preview, versioned structured outcomes, and persistence.
|
|
37
|
-
- Publishes built-in and custom agent capability manifests, then records the executor-owned `ExecutionPlan` that resolves requested authority to effective tools, model, thinking, timeout, transport, trust, and workspace controls.
|
|
38
|
-
- Runs explicit dependency workflows through a persistent `WorkItem` ledger, dependency-aware scheduler, declared scope-conflict checks, artifact provenance, stale-result invalidation, and bounded overall deadlines.
|
|
39
|
-
- Runs first-class blocking panels with two or more independent reviewers, incremental bounded evidence artifacts, preserved blockers and dissent, a minimum-valid-review barrier, reserved synthesis and cleanup budgets, and one evidence-preserving synthesis.
|
|
40
|
-
- Supports bounded retries only for explicitly idempotent work and hedged execution only for explicitly read-only work.
|
|
41
|
-
- Detects retained-agent semantic skew across agent definitions, role prompts, tools, model resolution, transport, trust, repository generation, artifacts, and scheduler policy before follow-up work starts.
|
|
42
|
-
- Publishes transient runtime status through Pi's generic extension status API while subagents are running.
|
|
43
|
-
- Returns complete bounded worker output in tool details and a concise result for the main agent.
|
|
13
|
+
- Provides blocking batches, detached reusable agents, read-only consultation, metadata inspection, and queue-only mailboxes.
|
|
14
|
+
- Includes `explorer` and `worker` definitions and loads optional user or confirmed project agents.
|
|
15
|
+
- Keeps detached agents addressable by durable IDs and task paths across follow-ups and recovery.
|
|
16
|
+
- Supports subprocess, in-process, RPC, and deterministic automatic transport choices for different trust and tool needs.
|
|
17
|
+
- Applies trust-aware cwd policy, capability contracts, dependency workflows, context bounds, deadlines, turn limits, tool limits, and deterministic termination.
|
|
18
|
+
- Persists accepted lifecycle and workflow state, preserves evidence and dissent, and rejects stale work after semantic or session changes.
|
|
19
|
+
- Routes nested completion and peer communication through authenticated session-scoped channels.
|
|
20
|
+
- Provides `/subagents` settings, status, help, tool-surface selection, and recovery diagnostics.
|
|
21
|
+
- Returns concise model-visible results with complete bounded details and sanitized terminal rendering.
|
|
22
|
+
- Loads a generated split runtime while preserving lazy execution, UI, inspection, and transport chunks.
|
|
44
23
|
|
|
45
24
|
## 📦 Install
|
|
46
25
|
|
|
@@ -77,9 +56,23 @@ Keep **All delegation methods** when an explicit blocking workflow or synchronou
|
|
|
77
56
|
|
|
78
57
|
Async-first delegation still requires useful parallel main-agent work, clear worker ownership, and a supported completion path.
|
|
79
58
|
|
|
80
|
-
##
|
|
59
|
+
## 💬 Commands
|
|
60
|
+
|
|
61
|
+
- `/subagents` opens the current-session manager in TUI mode and reports bounded status in RPC mode.
|
|
62
|
+
- `/subagents settings` configures target locations, trusted resources, and async completion delivery.
|
|
63
|
+
- `/subagents status` shows current-session and configured values with their sources.
|
|
64
|
+
- `/subagents help` summarizes the command surface and isolation limits.
|
|
65
|
+
|
|
66
|
+
## ⚙️ Settings
|
|
67
|
+
|
|
68
|
+
Use `/subagents settings` for target location, trust, consultation resource, and detached-completion preferences.
|
|
69
|
+
Use `/subagents` → **Advanced settings** for delegation workflow, agent tool permissions, and runtime limits.
|
|
70
|
+
Settings are stored in `~/.pi/agent/pi-subagents.json`; the detailed sections below document precedence, reload requirements, and safety behavior.
|
|
81
71
|
|
|
82
|
-
|
|
72
|
+
## 🛠️ Tools
|
|
73
|
+
|
|
74
|
+
`pi-subagents` registers seven tools by default.
|
|
75
|
+
Run `/subagents`, choose **Change delegation**, review the concrete tool changes, then select **Save and reload** to apply one of these workflows:
|
|
83
76
|
|
|
84
77
|
| Workflow | Registered tools |
|
|
85
78
|
| --- | --- |
|
|
@@ -92,35 +85,44 @@ Async-first delegation still requires useful parallel main-agent work, clear wor
|
|
|
92
85
|
The four async lifecycle tools stay separate because starting work, sending follow-ups, managing lifecycle, and queueing mailbox messages have different contracts.
|
|
93
86
|
Any default change, tool removal, or lifecycle consolidation requires a separately approved compatibility migration.
|
|
94
87
|
|
|
95
|
-
The preview compares the selection with the tools registered in the current session, even when a manual settings edit is pending, and remains read-only until confirmation.
|
|
88
|
+
The preview compares the selection with the tools registered in the current session, even when a manual settings edit is pending, and remains read-only until confirmation.
|
|
89
|
+
Escape or **Cancel** leaves settings unchanged.
|
|
90
|
+
Tool removal requires an extension reload because Pi does not expose extension tool unregistration.
|
|
91
|
+
To avoid aborting work or removing isolated worktrees during `session_shutdown`, workflow changes are blocked while detached agents are retained; finish or clear them through **Current agents** first.
|
|
92
|
+
Pi owns reload-error reporting and does not return a success result to extensions, so the save notification also tells users to run `/reload` if the tool surface does not refresh.
|
|
96
93
|
|
|
97
94
|
The available tools are:
|
|
98
95
|
|
|
99
|
-
- `subagent` — delegate blocking single, parallel, fan-in, chained, panel-review, or explicit dependency-workflow tasks.
|
|
96
|
+
- `subagent` — delegate blocking single, parallel, fan-in, chained, panel-review, or explicit dependency-workflow tasks.
|
|
97
|
+
The main agent cannot process queued steering until the call returns.
|
|
100
98
|
- `subagent_spawn` and related lifecycle tools — when enabled, start reusable detached work, return immediately, and receive bounded completion messages automatically.
|
|
101
99
|
- `subagent_inspect` — inspect agent/model/run/runtime metadata without launching work or changing state.
|
|
102
100
|
- `subagent_consult` — run one ephemeral read-only consultation and wait for its answer.
|
|
103
101
|
|
|
104
102
|
### Interactive tool rows
|
|
105
103
|
|
|
106
|
-
In Pi's interactive TUI, every registered tool uses Pi's native tool shell and theme.
|
|
104
|
+
In Pi's interactive TUI, every registered tool uses Pi's native tool shell and theme.
|
|
105
|
+
Call rows identify the action, agent or retained id, scope, and a bounded task/message preview.
|
|
106
|
+
Result rows use explicit `Starting`, `Running`, `Completed`, `Failed`, `Cancelled`, `Interrupted`, or `Closed` text in addition to icons and color.
|
|
107
107
|
|
|
108
|
-
Collapsed rows stay scan-friendly: consultation and blocking calls show recent activity while running, completed answers show up to three lines, and list actions show up to five items.
|
|
108
|
+
Collapsed rows stay scan-friendly: consultation and blocking calls show recent activity while running, completed answers show up to three lines, and list actions show up to five items.
|
|
109
|
+
Use Pi's configured `app.tools.expand` keybinding (Ctrl+O by default) for the additional bounded task, policy, activity, answer, usage, inspection, or mailbox details available to that tool.
|
|
110
|
+
The hint follows the user's keybinding rather than assuming Ctrl+O.
|
|
109
111
|
|
|
110
|
-
`subagent_consult` emits an initial starting update before launching its child and then reports the actual provider/model, thinking request, usage, and a safe projection of recent `read`, `grep`, `find`, and `ls` activity.
|
|
112
|
+
`subagent_consult` emits an initial starting update before launching its child and then reports the actual provider/model, thinking request, usage, and a safe projection of recent `read`, `grep`, `find`, and `ls` activity.
|
|
113
|
+
Progress never includes full child messages, prompts, credentials, headers, or environment values.
|
|
114
|
+
Tool-row previews remove terminal controls and redact private text.
|
|
111
115
|
|
|
112
|
-
`subagent_spawn` remains deliberately detached and non-polling: its tool row ends after returning the new `agentId` and initial retained state.
|
|
116
|
+
`subagent_spawn` remains deliberately detached and non-polling: its tool row ends after returning the new `agentId` and initial retained state.
|
|
117
|
+
It does not pretend to stream the background child after the tool call has completed; the existing completion message and configured delivery policy report eventual completion.
|
|
113
118
|
|
|
114
|
-
Custom transcript rendering is TUI presentation only.
|
|
119
|
+
Custom transcript rendering is TUI presentation only.
|
|
120
|
+
Tool names, parameter schemas, model-facing final content/details, errors, completion delivery, and print/JSON/RPC final output remain unchanged; JSON/RPC observers may see additive bounded consultation partial-progress details.
|
|
115
121
|
|
|
116
|
-
After each session starts, the descriptions of the registered `subagent`, `subagent_spawn`, and
|
|
117
|
-
`
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
formats; the `agent` parameters remain unconstrained strings for cwd and scope flexibility. The
|
|
121
|
-
catalog also warns that enforced path, network, and secret guarantees are unsupported. It is rebuilt on
|
|
122
|
-
`/reload` or the next session start, and omitted entries are reported explicitly when the catalog
|
|
123
|
-
exceeds its metadata bounds.
|
|
122
|
+
After each session starts, the descriptions of the registered `subagent`, `subagent_spawn`, and `subagent_consult` tools include the same bounded parent-facing catalog of the agents available in that session.
|
|
123
|
+
Entries show the source (`built-in`, `user`, or `project`), required `agentScope`, declared capability identifiers, configured tools, filesystem authority, and supported result formats; the `agent` parameters remain unconstrained strings for cwd and scope flexibility.
|
|
124
|
+
The catalog also warns that enforced path, network, and secret guarantees are unsupported.
|
|
125
|
+
It is rebuilt on `/reload` or the next session start, and omitted entries are reported explicitly when the catalog exceeds its metadata bounds.
|
|
124
126
|
|
|
125
127
|
Choose the API by lifecycle:
|
|
126
128
|
|
|
@@ -158,11 +160,15 @@ Common controls:
|
|
|
158
160
|
- `resultFormat` — keep bounded text by default, request legacy `structured-v1`, or request `structured-v2` with explicit outcome status, reason code, claims, artifacts, verification, limitations, and unresolved dependencies.
|
|
159
161
|
- `totalTimeoutMs` — bound a whole explicit blocking workflow; no new task starts after the budget is exhausted.
|
|
160
162
|
|
|
161
|
-
For `subagent_spawn`, the root agent selects the lowest thinking level and shortest realistic work deadline sufficient for the delegated task.
|
|
163
|
+
For `subagent_spawn`, the root agent selects the lowest thinking level and shortest realistic work deadline sufficient for the delegated task.
|
|
164
|
+
These are tool-argument decisions made from the task already in context; `pi-subagents` does not run a string heuristic or an extra classifier model call.
|
|
162
165
|
|
|
163
166
|
## 🔐 Working-directory trust policy
|
|
164
167
|
|
|
165
|
-
Pi records saved project trust in `~/.pi/agent/trust.json`.
|
|
168
|
+
Pi records saved project trust in `~/.pi/agent/trust.json`.
|
|
169
|
+
The closest saved decision for the canonical target or one of its parents wins, so trusting a worktree parent covers worktrees below it while a nearer `false` overrides a trusted parent.
|
|
170
|
+
`pi-subagents` reads this through Pi's public `ProjectTrustStore`; it never parses, writes, or migrates the file.
|
|
171
|
+
Open Pi in a folder and use `/trust` to manage trust, then restart Pi before expecting retained-runtime behavior to change.
|
|
166
172
|
|
|
167
173
|
The default target policies are:
|
|
168
174
|
|
|
@@ -171,32 +177,35 @@ The default target policies are:
|
|
|
171
177
|
| `cwdPolicy.consultation` | `"anywhere"`, `"current-workspace"` | `"anywhere"`: consultation may start in any existing directory, but a target without effective trust is forced to `resources: "none"` |
|
|
172
178
|
| `cwdPolicy.delegation` | `"trusted-targets"`, `"current-workspace"`, `"anywhere"` | `"trusted-targets"`: blocking and detached delegation may target the current workspace or an external folder covered by a saved `true` decision |
|
|
173
179
|
|
|
174
|
-
All paths are resolved relative to the current session workspace and canonicalized before containment and trust checks.
|
|
180
|
+
All paths are resolved relative to the current session workspace and canonicalized before containment and trust checks.
|
|
181
|
+
Missing paths, non-directories, sibling paths, and symlink escapes cannot bypass the policy.
|
|
182
|
+
Blocking parallel, chain, panel, and fan-in calls preflight every target before any child starts.
|
|
183
|
+
A generated `workspaceMode: "worktree"` inherits the resolved trust of its approved base cwd.
|
|
175
184
|
|
|
176
|
-
`"anywhere"` for general delegation restores the previous external-target flexibility.
|
|
185
|
+
`"anywhere"` for general delegation restores the previous external-target flexibility.
|
|
186
|
+
An external target without effective trust starts with `projectTrusted: false`, so Pi-protected project settings, packages, extensions, skills, prompts, and system resources stay disabled.
|
|
187
|
+
General agents still have their configured tools and ordinary Pi/OS permissions, and Pi may still load `AGENTS.md` or `CLAUDE.md` because those context files are not protected by project trust.
|
|
188
|
+
Resource-free consultation is stricter: it also passes `--no-context-files`, `--no-skills`, `--no-prompt-templates`, `--no-approve`, and `--no-extensions`.
|
|
177
189
|
|
|
178
|
-
These controls govern child starting directories and automatically loaded resources.
|
|
190
|
+
These controls govern child starting directories and automatically loaded resources.
|
|
191
|
+
They do **not** restrict absolute paths, shell commands, custom tools, network access, extension code, or filesystem access available to the Pi process.
|
|
192
|
+
For real isolation, run Pi in a container, VM, micro-VM, or OS sandbox with only the required paths and credentials mounted.
|
|
179
193
|
|
|
180
194
|
## 🧭 Proactive use
|
|
181
195
|
|
|
182
|
-
When registered, the blocking `subagent` tool advertises only blocking guidance.
|
|
183
|
-
are registered, `subagent_spawn` adds detached guidance for the active completion-delivery policy.
|
|
196
|
+
When registered, the blocking `subagent` tool advertises only blocking guidance.
|
|
197
|
+
When stateful lifecycle tools are registered, `subagent_spawn` adds detached guidance for the active completion-delivery policy.
|
|
184
198
|
Changing the policy through `/subagents settings` refreshes that guidance immediately.
|
|
185
199
|
|
|
186
|
-
The `subagent`, `subagent_spawn`, and `subagent_consult` descriptions advertise the current agent
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
`agentScope: "project"
|
|
193
|
-
metadata
|
|
194
|
-
|
|
195
|
-
version is used only for `"project"`/`"both"`. A user override of a built-in also shows the
|
|
196
|
-
built-in fallback available with `agentScope: "project"`; `"both"` keeps the user definition. The
|
|
197
|
-
catalog is bounded and reports its omission count; metadata discovery also caps files and bytes read
|
|
198
|
-
per scope. Refreshed metadata replaces the previous session's catalog rather than accumulating stale
|
|
199
|
-
entries.
|
|
200
|
+
The `subagent`, `subagent_spawn`, and `subagent_consult` descriptions advertise the current agent catalog automatically; no preliminary list call is needed.
|
|
201
|
+
Each entry exposes the exact declared capability and tool identifiers needed by an enforced contract, plus filesystem authority and result formats.
|
|
202
|
+
Agents without a valid capability manifest are labeled `undeclared` instead of implying support.
|
|
203
|
+
Built-ins and user agents appear under the default `agentScope: "user"`.
|
|
204
|
+
Trusted project agents appear separately and explicitly require `agentScope: "project"` or `"both"`; project-authored names and descriptions are not read into metadata for untrusted projects.
|
|
205
|
+
If a project definition shares a name with a user or built-in definition, the user version is the default and the project version is used only for `"project"`/`"both"`.
|
|
206
|
+
A user override of a built-in also shows the built-in fallback available with `agentScope: "project"`; `"both"` keeps the user definition.
|
|
207
|
+
The catalog is bounded and reports its omission count; metadata discovery also caps files and bytes read per scope.
|
|
208
|
+
Refreshed metadata replaces the previous session's catalog rather than accumulating stale entries.
|
|
200
209
|
|
|
201
210
|
Delegation guidance:
|
|
202
211
|
|
|
@@ -261,7 +270,8 @@ A blocking fan-out is reserved for output that must be synthesized before the ma
|
|
|
261
270
|
|
|
262
271
|
## 🔎 Read-only inspection
|
|
263
272
|
|
|
264
|
-
`subagent_inspect` is registered in every workflow, including disabled delegation.
|
|
273
|
+
`subagent_inspect` is registered in every workflow, including disabled delegation.
|
|
274
|
+
It never starts a child, sends or acknowledges mailbox messages, interrupts or closes a run, changes settings, refreshes providers, resolves credentials, or modifies files.
|
|
265
275
|
|
|
266
276
|
| Action | Parameters | Result |
|
|
267
277
|
| --- | --- | --- |
|
|
@@ -276,9 +286,14 @@ A blocking fan-out is reserved for output that must be synthesized before the ma
|
|
|
276
286
|
| `status` | No additional fields | Effective workflow, runtime counts/transport, detached limit values, completion delivery, consultation resources, and configured/runtime settings with per-field sources |
|
|
277
287
|
| `diagnose` | No additional fields | Structured `pass`, `warning`, and `fail` checks; failed checks are report data rather than a tool error |
|
|
278
288
|
|
|
279
|
-
The schema rejects fields that do not belong to the selected action.
|
|
289
|
+
The schema rejects fields that do not belong to the selected action.
|
|
290
|
+
Explicit `project` or `both` scope fails before project-agent discovery unless Pi already trusts the project.
|
|
291
|
+
Run inspection never returns history output, stored context, or mailbox content; unread counts come from a metadata-only snapshot and do not acknowledge messages.
|
|
292
|
+
Workflow inspection reads validated, redacted snapshots without quarantining or rewriting invalid files.
|
|
293
|
+
Paths beneath the Pi agent directory use `~`, project paths are workspace-relative, model objects are projected through an allow-list, and model-facing text is bounded to 50 KiB or 2,000 lines.
|
|
280
294
|
|
|
281
|
-
`subagent_manage` no longer accepts its former compatibility `list` action.
|
|
295
|
+
`subagent_manage` no longer accepts its former compatibility `list` action.
|
|
296
|
+
Use `subagent_inspect({ "action": "list_runs", "includeClosed": true })` for metadata-only discovery and `get_run` for detail.
|
|
282
297
|
|
|
283
298
|
## 📖 Read-only consultation
|
|
284
299
|
|
|
@@ -297,15 +312,12 @@ The executor policy remains authoritative even when the task or agent prompt ask
|
|
|
297
312
|
}
|
|
298
313
|
```
|
|
299
314
|
|
|
300
|
-
The actionless schema requires `agent` and `task` and accepts optional `agentScope`,
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
default; non-interactive calls fail closed unless they explicitly send
|
|
307
|
-
`confirmProjectAgents: false`. Declining an interactive confirmation returns a normal cancelled result
|
|
308
|
-
without launching or charging a child.
|
|
315
|
+
The actionless schema requires `agent` and `task` and accepts optional `agentScope`, `confirmProjectAgents`, `cwd`, `timeoutMs`, and `thinkingLevel`.
|
|
316
|
+
Any agent resolved from that scope may be selected; consultation always intersects its configured tools with the enforced read-only allow-list rather than defining a separate read-only agent category.
|
|
317
|
+
An unknown name fails before launch with a bounded name/source list for the requested scope.
|
|
318
|
+
Project scope is rejected before discovery when the project is untrusted.
|
|
319
|
+
A trusted project agent still asks for confirmation by default; non-interactive calls fail closed unless they explicitly send `confirmProjectAgents: false`.
|
|
320
|
+
Declining an interactive confirmation returns a normal cancelled result without launching or charging a child.
|
|
309
321
|
|
|
310
322
|
`consult.resources` controls automatically inherited instruction resources:
|
|
311
323
|
|
|
@@ -315,17 +327,30 @@ without launching or charging a child.
|
|
|
315
327
|
| `"none"` | Use only the package consultation base, selected agent prompt, and enforced read-only instruction |
|
|
316
328
|
| `"all"` | Keep ordinarily discoverable trusted context/system/append-system files, skills, and prompt templates |
|
|
317
329
|
|
|
318
|
-
Extensions remain disabled for all three values.
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
330
|
+
Extensions remain disabled for all three values.
|
|
331
|
+
Pi core owns system-prompt source precedence: a trusted project prompt wins over the global prompt, with the global prompt used as fallback.
|
|
332
|
+
A selected Pi prompt source must be a readable regular file; directories, FIFOs, devices, sockets, and unreadable sources fail before child launch.
|
|
333
|
+
A current target uses the session's effective project trust, including session-only or CLI overrides.
|
|
334
|
+
An external target uses the nearest saved trust decision.
|
|
335
|
+
For an untrusted, explicitly denied, unsaved, or trust-error target, consultation remains available when `cwdPolicy.consultation` permits it but automatically downgrades to `resources: "none"`.
|
|
336
|
+
This also disables context files because Pi does not protect `AGENTS.md` and `CLAUDE.md` with project trust alone.
|
|
337
|
+
A saved-trusted external target uses the configured resource policy and discovers `SYSTEM.md`, `APPEND_SYSTEM.md`, and ordinary child context from that target rather than the parent workspace.
|
|
338
|
+
|
|
339
|
+
Both settings are user-owned in `~/.pi/agent/pi-subagents.json`; projects cannot override them.
|
|
340
|
+
`cwdPolicy.consultation: "current-workspace"` rejects every canonical external target before agent discovery or launch even when that target is saved-trusted.
|
|
341
|
+
This is not a path sandbox: read-only tools can still read an explicitly requested accessible absolute path.
|
|
342
|
+
|
|
343
|
+
Result details report the canonical safe cwd, current/external boundary, bounded target-trust decision/source/warning, requested and effective tools/resources, downgrade reason, agent/model/thinking/timeout metadata, and the facts that extensions, session persistence, and retained-agent state are disabled.
|
|
344
|
+
They never dump prompt contents or the full trust store.
|
|
345
|
+
Nested model usage is returned through Pi's usage field, so footer, `/session`, and RPC totals include consultation cost.
|
|
346
|
+
Validation, disallowed targets, and launch failures throw.
|
|
347
|
+
Failures after model launch preserve bounded partial evidence and usage while the finalized Pi tool result is marked as an error.
|
|
348
|
+
Explicit abort, session replacement, and shutdown use the existing process-tree termination and temporary-file cleanup path; a work timeout additionally makes one separately bounded, tool-less summary attempt after abort.
|
|
323
349
|
|
|
324
350
|
## 🚀 Blocking batch examples
|
|
325
351
|
|
|
326
|
-
Every example in this section calls `subagent` and keeps the main agent unavailable until the batch
|
|
327
|
-
|
|
328
|
-
completion policy supports when synthesis is needed.
|
|
352
|
+
Every example in this section calls `subagent` and keeps the main agent unavailable until the batch finishes.
|
|
353
|
+
Use `subagent_spawn` instead when the work can complete asynchronously and its configured completion policy supports when synthesis is needed.
|
|
329
354
|
|
|
330
355
|
Run one read-only reconnaissance agent:
|
|
331
356
|
|
|
@@ -359,9 +384,8 @@ Run multiple agents in parallel with a shared thinking level and one per-task ov
|
|
|
359
384
|
}
|
|
360
385
|
```
|
|
361
386
|
|
|
362
|
-
Omit `aggregator` entirely when parallel worker outputs should return directly.
|
|
363
|
-
empty strings, or an empty object for an unused optional field; for compatibility, an aggregator with
|
|
364
|
-
an empty or whitespace-only `agent` or `task` is treated as absent.
|
|
387
|
+
Omit `aggregator` entirely when parallel worker outputs should return directly.
|
|
388
|
+
Do not send `null`, empty strings, or an empty object for an unused optional field; for compatibility, an aggregator with an empty or whitespace-only `agent` or `task` is treated as absent.
|
|
365
389
|
|
|
366
390
|
Run parallel workers, then aggregate their results:
|
|
367
391
|
|
|
@@ -574,7 +598,10 @@ Legacy v1 and v2 records without acceptance fields retain their prior completed
|
|
|
574
598
|
|
|
575
599
|
## 🔁 Stateful agents
|
|
576
600
|
|
|
577
|
-
Stateful lifecycle tools are available by default.
|
|
601
|
+
Stateful lifecycle tools are available by default.
|
|
602
|
+
`subagent_spawn` is detached: it schedules work, returns immediately with an opaque `agentId` plus canonical `taskPath`, and later delivers a bounded completion to its intended parent.
|
|
603
|
+
Every turn receives an executor-owned `runId`, monotonically increasing agent-local generation, and unique `completionId`.
|
|
604
|
+
The terminal completion and recipient are persisted before delivery, simultaneous root completions are batched, and the root broker allows at most one in-flight wake until that parent turn starts.
|
|
578
605
|
In TUI mode, completion messages show a compact task and payload summary while collapsed; use the configured tool-output expansion action (`Ctrl+O` by default) to show or hide the complete message globally.
|
|
579
606
|
|
|
580
607
|
Detached work follows a non-polling policy.
|
|
@@ -591,10 +618,20 @@ Simple and immediate critical-path work should stay in the main agent.
|
|
|
591
618
|
|
|
592
619
|
`stateful.completionDelivery` controls settled completion delivery:
|
|
593
620
|
|
|
594
|
-
- `"next-turn"` (default) sends `deliverAs: "steer"` without a turn trigger.
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
621
|
+
- `"next-turn"` (default) sends `deliverAs: "steer"` without a turn trigger.
|
|
622
|
+
Pi queues it into an active root's context, while an idle root records it without waking.
|
|
623
|
+
- `"auto-resume"` holds completion while the root is active, then requests one synthesis turn after the parent settles when no user or extension messages are already pending.
|
|
624
|
+
Simultaneous completions share that turn, active work is not interrupted, and pending input suppresses the automatic wake.
|
|
625
|
+
|
|
626
|
+
The bounded persisted completion outbox provides ordered at-least-once delivery across process restart without replaying the child turn.
|
|
627
|
+
A top-level completion targets `/root`; a nested completion enters the direct retained parent's mailbox and is not duplicated into the root transcript.
|
|
628
|
+
If the direct parent cannot own delivery, routing walks toward the nearest live retained ancestor and uses `/root` only as the final fallback.
|
|
629
|
+
An idle parent remains asleep, and inspection exposes its unread and pending-completion counts until a later turn consumes the envelope.
|
|
630
|
+
When state must be reduced to its storage bound, persistence drops roots without pending completions first and trims old history rather than discarding an outbox-owned root.
|
|
631
|
+
A completion is acknowledged only after the intended recipient context observes its exact `completionId`; an injection that returns synchronously but never reaches context remains pending for retry.
|
|
632
|
+
If the process exits after context assembly but before acknowledgement is persisted, the same ID can be delivered again and consumers must deduplicate it.
|
|
633
|
+
Auto-resume applies only to `/root`; nested delivery never silently starts the parent.
|
|
634
|
+
Transient terminal-persistence failures retry with bounded exponential backoff and keep the run pending; shutdown cancels retry waits and reports a final persistence failure instead of silently resolving unsaved work.
|
|
598
635
|
|
|
599
636
|
The default `subprocess` transport preserves compatibility: each turn starts a fresh isolated `pi --mode json -p --no-session` child and receives sanitized, bounded history.
|
|
600
637
|
Pi loads one generated split TypeScript runtime and registers every Subagents tool and command during startup, but loads blocking execution, manager UI, inspection work, and the selected detached transport implementation only on first use.
|
|
@@ -617,7 +654,10 @@ Detached-limit saves are durable immediately but apply to the runtime after `/re
|
|
|
617
654
|
Escape returns from a nested screen to a newly refreshed manager, while Ctrl+C closes the full flow.
|
|
618
655
|
Exact workflow/reload and project-agent safety confirmations remain extension-owned because they guard live agent and trust-boundary policy rather than ordinary navigation.
|
|
619
656
|
|
|
620
|
-
The direct routes remain predictable: `/subagents settings` changes both target policies, consultation resources, and completion delivery and applies them immediately, including refreshing model-facing tool guidance; `/subagents status` reports current-session runtime values separately from configured values, per-field sources, and path; `/subagents help` summarizes the single-command interface and the non-sandbox limitation.
|
|
657
|
+
The direct routes remain predictable: `/subagents settings` changes both target policies, consultation resources, and completion delivery and applies them immediately, including refreshing model-facing tool guidance; `/subagents status` reports current-session runtime values separately from configured values, per-field sources, and path; `/subagents help` summarizes the single-command interface and the non-sandbox limitation.
|
|
658
|
+
In RPC mode, bare `/subagents` emits the same bounded status through Pi's notification protocol instead of opening a custom TUI.
|
|
659
|
+
JSON and print modes do not emit ad hoc command output.
|
|
660
|
+
Manual edits use `~/.pi/agent/pi-subagents.json` and take effect after reloading Pi:
|
|
621
661
|
|
|
622
662
|
```json
|
|
623
663
|
{
|
|
@@ -678,7 +718,8 @@ This avoids lifecycle-driven tool-schema churn and preserves a stable provider p
|
|
|
678
718
|
| `subagent_manage` | Use `"interrupt"` to retain an agent after aborting active work or `"close"` to release it; both actions accept optional `subtree`. Use `subagent_inspect` for all list and detail operations. |
|
|
679
719
|
| `subagent_mailbox` | Use `action: "send"` for queue-only messages that do not start a turn, or `"read"` to read and optionally acknowledge unread messages. |
|
|
680
720
|
|
|
681
|
-
The action schemas are flat for provider compatibility and reject parameters that belong to another action.
|
|
721
|
+
The action schemas are flat for provider compatibility and reject parameters that belong to another action.
|
|
722
|
+
For example:
|
|
682
723
|
|
|
683
724
|
```json
|
|
684
725
|
{
|
|
@@ -734,7 +775,8 @@ Older records require no manual migration because missing paths and recipients a
|
|
|
734
775
|
|
|
735
776
|
### Migrating from the previous seven-tool lifecycle surface
|
|
736
777
|
|
|
737
|
-
The five replaced names are intentionally not registered as aliases.
|
|
778
|
+
The five replaced names are intentionally not registered as aliases.
|
|
779
|
+
Update explicit prompts and integrations as follows:
|
|
738
780
|
|
|
739
781
|
| Previous call | Fixed-surface call |
|
|
740
782
|
| --- | --- |
|
|
@@ -745,7 +787,10 @@ The five replaced names are intentionally not registered as aliases. Update expl
|
|
|
745
787
|
| `subagent_message({ agentId, message, ... })` | `subagent_mailbox({ action: "send", agentId, message, ... })` |
|
|
746
788
|
| `subagent_messages({ agentId, acknowledge, limit })` | `subagent_mailbox({ action: "read", agentId, acknowledge, limit })` |
|
|
747
789
|
|
|
748
|
-
Persisted agent and mailbox records require no manual migration; older records load with an empty completion outbox and generation zero.
|
|
790
|
+
Persisted agent and mailbox records require no manual migration; older records load with an empty completion outbox and generation zero.
|
|
791
|
+
If an explicit prompt in a resumed conversation keeps requesting an old name, update it with the mapping above or start a fresh conversation.
|
|
792
|
+
To roll back after an upgrade, pin the package version used before the upgrade; for this migration, use `pi install npm:@narumitw/pi-subagents@0.26.0`.
|
|
793
|
+
The previous release can read the same state directory.
|
|
749
794
|
|
|
750
795
|
A spawn can request a thinking level explicitly:
|
|
751
796
|
|
|
@@ -758,7 +803,9 @@ A spawn can request a thinking level explicitly:
|
|
|
758
803
|
}
|
|
759
804
|
```
|
|
760
805
|
|
|
761
|
-
The requested level and spawn `timeoutMs`, `idleTimeoutMs`, `maxTurns`, and `maxToolCalls` are stored with the stateful agent and remain in effect for all follow-ups and after persisted restore.
|
|
806
|
+
The requested level and spawn `timeoutMs`, `idleTimeoutMs`, `maxTurns`, and `maxToolCalls` are stored with the stateful agent and remain in effect for all follow-ups and after persisted restore.
|
|
807
|
+
The same fields on `subagent_send` override only that follow-up turn.
|
|
808
|
+
`subagent_send` does not provide a per-turn thinking override; create a new agent when a later task needs a different level.
|
|
762
809
|
|
|
763
810
|
An exact retry can use a bounded session-owned idempotency key:
|
|
764
811
|
|
|
@@ -794,21 +841,37 @@ Stable source IDs are retained so repeated follow-ups do not need to duplicate p
|
|
|
794
841
|
Use `subagent_inspect` with `action: "preview_context"` to inspect selected turns, source count, UTF-8 bytes, and truncation before spawning without returning the context text.
|
|
795
842
|
The byte count is not a provider token estimate.
|
|
796
843
|
|
|
797
|
-
Reasoning, tool results, custom transport messages, and non-text parts are excluded.
|
|
844
|
+
Reasoning, tool results, custom transport messages, and non-text parts are excluded.
|
|
845
|
+
Text inside `<private>...</private>` and lines containing `[subagent-private]` are omitted before context, mailbox content, or history is persisted.
|
|
798
846
|
|
|
799
847
|
Stateful execution uses a transport boundary:
|
|
800
848
|
|
|
801
849
|
- `subprocess` is the default compatibility and rollback path and starts a fresh child for every turn.
|
|
802
|
-
- `in-process` uses only public Pi SDK APIs: `createAgentSessionServices()`, `createAgentSessionFromServices()`, `SessionManager.inMemory()`, and normal session lifecycle methods.
|
|
803
|
-
|
|
804
|
-
- `
|
|
805
|
-
|
|
806
|
-
-
|
|
850
|
+
- `in-process` uses only public Pi SDK APIs: `createAgentSessionServices()`, `createAgentSessionFromServices()`, `SessionManager.inMemory()`, and normal session lifecycle methods.
|
|
851
|
+
It isolates conversation/tool selection, not memory or crashes; child failures share the parent Node.js process.
|
|
852
|
+
- `rpc` uses strict bounded JSONL over one lazy child process per active retained agent.
|
|
853
|
+
A `get_state` response proves readiness, prompt response means accepted only, and `agent_settled` is the completion boundary after retry or compaction.
|
|
854
|
+
- `auto` selects one transport before launch and retains the choice for that agent's runtime lifetime.
|
|
855
|
+
It never retries through another transport after startup or accepted work.
|
|
856
|
+
- In-process and RPC child resource loading disables user and project extensions to prevent recursive `pi-subagents` loading and duplicate extension side effects while retaining trust-eligible context/skill resources and the selected agent prompt.
|
|
857
|
+
All transports add only the package-owned peer bridge and its two communication tools; the bridge does not add filesystem, shell, model, network-destination, or user-extension authority.
|
|
858
|
+
The compatibility subprocess path retains its recursion-depth guard and configured execution tools.
|
|
859
|
+
Transports receive the same resolved target-trust boolean through their public SDK or explicit CLI trust controls.
|
|
860
|
+
- Agent model strings use Pi core's CLI resolver, including provider/model patterns, fuzzy matching, custom provider model IDs, and `:<thinking>` suffixes.
|
|
861
|
+
Thinking level and built-in tool allow-list overrides are applied when the child is created.
|
|
862
|
+
Parent model/thinking changes are snapshotted for subsequently created children; an existing child keeps its own session configuration.
|
|
807
863
|
- Extension/custom tool names are rejected by in-process and RPC v1 before child creation; automatic mode selects `subprocess` for them, and permissions are never silently widened.
|
|
808
|
-
- Timeout, parent abort, close, expiry, and session shutdown abort
|
|
809
|
-
|
|
864
|
+
- Timeout, parent abort, close, expiry, and session shutdown abort or dispose owned child sessions or process groups.
|
|
865
|
+
A child that does not settle after abort grace is discarded rather than reused.
|
|
866
|
+
- RPC progress uses `pi-subagents:v1` metadata and reports only bounded phase, queue, timing, effective model/thinking, and validated usage fields.
|
|
867
|
+
Successive Pi 0.84.2 `message_update.usage` values replace one cumulative in-flight snapshot, while a valid final `message_end.message.usage` remains authoritative.
|
|
868
|
+
Missing or invalid final usage falls back to the latest valid streaming snapshot, and an interrupted attempt is committed before retry or timeout-summary usage is added.
|
|
869
|
+
Usage progress and terminal outcomes therefore retain partial token and total-cost evidence without double counting cumulative updates.
|
|
870
|
+
The `turns` field still counts finalized assistant messages only, not interrupted attempts or tool-result messages.
|
|
871
|
+
Telemetry never exposes raw prompts, assistant content, reasoning, credentials, headers, environment values, or full RPC events.
|
|
810
872
|
- A successful RPC prompt response is never treated as completion, and accepted or ambiguously accepted work is never replayed automatically.
|
|
811
|
-
- In-process startup failures do not silently retry through subprocesses, preventing duplicate side effects.
|
|
873
|
+
- In-process startup failures do not silently retry through subprocesses, preventing duplicate side effects.
|
|
874
|
+
If the loaded Pi core lacks public `createAgentSessionServices()`, `createAgentSessionFromServices()`, or `resolveCliModel()` support, startup fails with an actionable instruction to select `stateful.transport: "subprocess"`.
|
|
812
875
|
|
|
813
876
|
No private Pi imports, runtime casts, or `ExtensionAPI` monkey-patching are used.
|
|
814
877
|
The package uses public Pi root RPC types but owns exact CLI resolution, bounded framing, readiness, stderr, cancellation, and process-group cleanup because the stock client does not provide those package-specific guarantees.
|
|
@@ -821,7 +884,11 @@ Use isolated worktrees when repository-write isolation is required.
|
|
|
821
884
|
The deprecated `allowConcurrentWrites` field remains accepted for compatibility but no longer changes admission behavior.
|
|
822
885
|
Use the blocking batch only when synchronous outputs justify making the main agent unavailable.
|
|
823
886
|
|
|
824
|
-
Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree; this requires a clean repository and the worktree is removed on close or session shutdown.
|
|
887
|
+
Set `workspaceMode: "worktree"` to opt into a disposable detached Git worktree; this requires a clean repository and the worktree is removed on close or session shutdown.
|
|
888
|
+
The generated path inherits the approved base cwd's trust snapshot.
|
|
889
|
+
Retained records mark disposable worktrees explicitly, so they are never restored even if cleanup could not remove the generated directory.
|
|
890
|
+
Shared-workspace retained records store an additive bounded target-trust snapshot for transport and inspection parity; session restore canonicalizes the retained cwd and re-resolves current/saved trust rather than blindly trusting the persisted value.
|
|
891
|
+
Older records without either field remain readable.
|
|
825
892
|
|
|
826
893
|
## 📜 Compatibility and failure contract
|
|
827
894
|
|
|
@@ -843,10 +910,15 @@ The intentional compatibility change is that an external target without saved tr
|
|
|
843
910
|
| Workflow | Deterministic dependency-ready and critical-path order, with results returned in declared task order. | Invalid graphs fail before launch; blocked or failed dependencies prevent downstream start; bounded retry and hedging require explicit side-effect contracts. |
|
|
844
911
|
| Panel | Reviewer declaration order, then at most one synthesizer. | Invalid or failed reviews remain visible; synthesis requires `minValidReviews`; insufficient panels preserve partial evidence without a consensus claim; synthesis contract failure marks the tool result as an error. |
|
|
845
912
|
|
|
846
|
-
An aggregator whose `agent` or `task` is empty or whitespace-only is treated as absent, so successful
|
|
847
|
-
parallel outputs remain available instead of being replaced by a malformed fan-in failure.
|
|
913
|
+
An aggregator whose `agent` or `task` is empty or whitespace-only is treated as absent, so successful parallel outputs remain available instead of being replaced by a malformed fan-in failure.
|
|
848
914
|
|
|
849
|
-
Blocking work-timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms, then `totalTimeoutMs` caps the effective remaining time.
|
|
915
|
+
Blocking work-timeout precedence remains: task/step/aggregator → call → agent setting → `PI_SUBAGENT_TIMEOUT_MS` → 600000 ms, then `totalTimeoutMs` caps the effective remaining time.
|
|
916
|
+
Blocking idle, turn, and tool-call precedence is task/step/aggregator → call → omitted.
|
|
917
|
+
Stateful budget precedence is the explicit `subagent_send` field for one follow-up → retained `subagent_spawn` field → timeout-only agent/environment fallback where applicable.
|
|
918
|
+
Blocking thinking precedence remains: task/step/aggregator → call → agent setting → child default.
|
|
919
|
+
Stateful spawn thinking precedence is: `subagent_spawn.thinkingLevel` → agent setting → transport fallback.
|
|
920
|
+
Project-agent resolution and confirmation behavior is unchanged after target preflight.
|
|
921
|
+
Blocking and retained result/inspection details add bounded target, budget, termination, and effective trust metadata.
|
|
850
922
|
|
|
851
923
|
## 🤖 Built-in agents
|
|
852
924
|
|
|
@@ -867,25 +939,24 @@ Users who need shell-assisted read-mostly work can define a custom agent, but `b
|
|
|
867
939
|
|
|
868
940
|
## ⚙️ Configure agent tools
|
|
869
941
|
|
|
870
|
-
Open `/subagents`, choose **Advanced settings**, then **Agent tool permissions** in an interactive
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
tool names and availability metadata; Save and Discard remain pinned below the matches. These are user
|
|
876
|
-
settings stored in `~/.pi/agent/pi-subagents.json` and affect future sessions.
|
|
942
|
+
Open `/subagents`, choose **Advanced settings**, then **Agent tool permissions** in an interactive Pi session to edit the tools each subagent may use.
|
|
943
|
+
Choose **Performance and execution** → **Agent execution defaults** to edit provider-neutral inherited model patterns, thinking levels, and timeouts without changing tools.
|
|
944
|
+
The standard bounded multi-select keeps a one-save draft: toggles do not write until **Save changes**, Escape leaves the draft without writing, and unavailable configured tool names remain visible and preserved.
|
|
945
|
+
In TUI mode, type to fuzzy-search tool names and availability metadata; Save and Discard remain pinned below the matches.
|
|
946
|
+
These are user settings stored in `~/.pi/agent/pi-subagents.json` and affect future sessions.
|
|
877
947
|
|
|
878
|
-
Compatibility: a valid legacy `pi-subagents-config.json` remains readable with a warning and is never modified automatically; rename it to `pi-subagents.json`.
|
|
948
|
+
Compatibility: a valid legacy `pi-subagents-config.json` remains readable with a warning and is never modified automatically; rename it to `pi-subagents.json`.
|
|
949
|
+
The first subsequent settings save writes the canonical file.
|
|
950
|
+
If both files exist, the new filename takes precedence.
|
|
879
951
|
A saved `agents.scout` override from earlier releases applies to the renamed built-in `explorer` only when no explicit `agents.explorer` override exists and no custom `scout` agent is available.
|
|
880
952
|
|
|
881
953
|
- Select an agent, then press Enter or Space to toggle tools.
|
|
882
|
-
- Choose **Save changes** to write the draft, choose **Discard draft** to abandon it, or press Esc to
|
|
883
|
-
return to agent selection without writing.
|
|
954
|
+
- Choose **Save changes** to write the draft, choose **Discard draft** to abandon it, or press Esc to return to agent selection without writing.
|
|
884
955
|
- Save the default selection to remove a custom override and use the agent defaults again.
|
|
885
|
-
- Deselect every tool and save to run that agent with no tools.
|
|
956
|
+
- Deselect every tool and save to run that agent with no tools.
|
|
957
|
+
An explicit empty list remains distinct from an absent list; blank `tools:` or `tools: []` in agent frontmatter also means no tools.
|
|
886
958
|
|
|
887
|
-
Configured tool names that are not currently registered are preserved, so settings for tools from
|
|
888
|
-
other extension sessions are not silently dropped.
|
|
959
|
+
Configured tool names that are not currently registered are preserved, so settings for tools from other extension sessions are not silently dropped.
|
|
889
960
|
|
|
890
961
|
## 🧩 Custom agents
|
|
891
962
|
|
|
@@ -920,7 +991,8 @@ You are an API review subagent. Do not edit files. Check compatibility,
|
|
|
920
991
|
test coverage, and migration risks. Report PASS/FAIL/PARTIAL with evidence.
|
|
921
992
|
```
|
|
922
993
|
|
|
923
|
-
`tools` accepts either the comma-separated form above or a YAML string array such as `tools: [read, grep]`.
|
|
994
|
+
`tools` accepts either the comma-separated form above or a YAML string array such as `tools: [read, grep]`.
|
|
995
|
+
An omitted field keeps the agent's default tools; blank, `null`, or `[]` explicitly selects no tools.
|
|
924
996
|
|
|
925
997
|
`capabilityManifest` is optional for legacy custom agents and never grants authority by itself.
|
|
926
998
|
Explicit workflow routing can match declared capabilities, configured tools, filesystem authority, verification roles, and low/medium/high cost or latency hints.
|
|
@@ -928,11 +1000,11 @@ A missing or malformed manifest remains unknown and cannot satisfy a capability-
|
|
|
928
1000
|
The parent-facing catalog exposes contract-relevant declarations before the first delegation decision.
|
|
929
1001
|
Use those identifiers exactly; enforced `readPaths`, `writePaths`, network, and secret guarantees are currently unsupported and require an external enforcement boundary.
|
|
930
1002
|
|
|
931
|
-
`agentScope` is a top-level tool argument supplied per invocation.
|
|
932
|
-
`~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter.
|
|
933
|
-
metadata discovers these definitions after session start and labels their source and required scope.
|
|
934
|
-
Edit agent files and run `/reload` (or start a new session) to refresh the catalog; there is no live
|
|
935
|
-
|
|
1003
|
+
`agentScope` is a top-level tool argument supplied per invocation.
|
|
1004
|
+
It is not a setting in `~/.pi/agent/pi-subagents.json` and does not belong in agent frontmatter.
|
|
1005
|
+
The parent-facing tool metadata discovers these definitions after session start and labels their source and required scope.
|
|
1006
|
+
Edit agent files and run `/reload` (or start a new session) to refresh the catalog; there is no live filesystem watcher.
|
|
1007
|
+
The scope selects which custom agent directories are loaded; built-in agents remain available in every scope:
|
|
936
1008
|
|
|
937
1009
|
| `agentScope` | Custom agents loaded |
|
|
938
1010
|
| --- | --- |
|
|
@@ -960,13 +1032,12 @@ Or select the scope when creating a stateful agent with `subagent_spawn`:
|
|
|
960
1032
|
}
|
|
961
1033
|
```
|
|
962
1034
|
|
|
963
|
-
A stateful agent retains the scope selected by `subagent_spawn` for its follow-ups.
|
|
964
|
-
blocking `subagent` invocation or `subagent_spawn` call that needs project agents must supply
|
|
965
|
-
`agentScope: "project"` or `"both"` again.
|
|
1035
|
+
A stateful agent retains the scope selected by `subagent_spawn` for its follow-ups.
|
|
1036
|
+
Every new blocking `subagent` invocation or `subagent_spawn` call that needs project agents must supply `agentScope: "project"` or `"both"` again.
|
|
966
1037
|
|
|
967
|
-
Project-local agents require a trusted Pi project.
|
|
968
|
-
before using them by default.
|
|
969
|
-
argument skips that confirmation dialog, but it does not bypass the project trust requirement.
|
|
1038
|
+
Project-local agents require a trusted Pi project.
|
|
1039
|
+
Interactive sessions also ask for confirmation before using them by default.
|
|
1040
|
+
Passing `confirmProjectAgents: false` as another top-level tool argument skips that confirmation dialog, but it does not bypass the project trust requirement.
|
|
970
1041
|
|
|
971
1042
|
## ⏱️ Runtime limits and thinking levels
|
|
972
1043
|
|
|
@@ -976,7 +1047,8 @@ Every turn can combine main-agent-selected wall-clock, idle, assistant-turn, and
|
|
|
976
1047
|
- The worker-count limit defaults to 8 and does not change the fixed four-at-a-time execution concurrency.
|
|
977
1048
|
- Set `timeoutMs` on the top-level blocking call to apply a work deadline to all jobs.
|
|
978
1049
|
- Set `timeoutMs` on a task, chain step, or aggregator to override it locally.
|
|
979
|
-
- Set top-level blocking `totalTimeoutMs` to cap model work across the whole call; each child receives at most the remaining budget, queued work is not started after expiry, fan-in receives only remaining time, and an orchestration-expired child skips model finalization.
|
|
1050
|
+
- Set top-level blocking `totalTimeoutMs` to cap model work across the whole call; each child receives at most the remaining budget, queued work is not started after expiry, fan-in receives only remaining time, and an orchestration-expired child skips model finalization.
|
|
1051
|
+
Bounded process-cleanup grace may follow the deadline.
|
|
980
1052
|
- Set `idleTimeoutMs` to stop a turn that has produced no completed assistant turn or tool result within that interval.
|
|
981
1053
|
- Set `maxTurns` or `maxToolCalls` to stop unfinished repeated work; a terminal answer at the exact turn limit remains successful.
|
|
982
1054
|
- Set spawn budgets as retained defaults, or the same fields on `subagent_send` to override one follow-up turn.
|
|
@@ -986,7 +1058,8 @@ Every turn can combine main-agent-selected wall-clock, idle, assistant-turn, and
|
|
|
986
1058
|
- `maxTurns` and `maxToolCalls` accept integers from 1 through 1,000,000.
|
|
987
1059
|
- If `timeoutMs` is omitted, the default is the retained or agent setting, then `PI_SUBAGENT_TIMEOUT_MS`, or `600000` milliseconds (10 minutes) when unset; the other new budgets remain opt-in.
|
|
988
1060
|
|
|
989
|
-
Set `thinkingLevel` to request one of Pi's supported levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
|
|
1061
|
+
Set `thinkingLevel` to request one of Pi's supported levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
|
|
1062
|
+
Blocking subprocess calls pass the resolved value through `--thinking <level>`.
|
|
990
1063
|
|
|
991
1064
|
For `subagent_spawn`, the root agent should choose the lowest sufficient level:
|
|
992
1065
|
|
|
@@ -1007,19 +1080,32 @@ In-process delegates configured model parsing to loaded Pi core and then uses th
|
|
|
1007
1080
|
RPC passes the selected CLI model and thinking controls before its readiness handshake and reports the effective state returned by Pi.
|
|
1008
1081
|
An explicit spawn value is retained for the agent lifecycle and wins over every fallback.
|
|
1009
1082
|
|
|
1010
|
-
Omit `thinkingLevel` to preserve existing behavior.
|
|
1083
|
+
Omit `thinkingLevel` to preserve existing behavior.
|
|
1084
|
+
Reported stateful details show the requested level, not a guarantee of the provider's effective value.
|
|
1085
|
+
Pi still owns model capability clamping; `pi-subagents` does not duplicate capability detection.
|
|
1011
1086
|
|
|
1012
|
-
When any execution budget expires, the extension aborts the active run first and creates a versioned, bounded, redacted checkpoint containing partial assistant notes, completed tool evidence, changed-file hints, and whether side effects may already have occurred.
|
|
1087
|
+
When any execution budget expires, the extension aborts the active run first and creates a versioned, bounded, redacted checkpoint containing partial assistant notes, completed tool evidence, changed-file hints, and whether side effects may already have occurred.
|
|
1088
|
+
After authoritative settlement it may make one concise summary attempt over that checkpoint without replaying the stopped task.
|
|
1089
|
+
The summary attempt has its own extension-owned model-work deadline of at most 45 seconds, followed only by bounded abort and process-cleanup grace.
|
|
1090
|
+
Fresh subprocess summaries run with no tools or project resources.
|
|
1091
|
+
Retained RPC and in-process summaries reuse their child context and are explicitly instructed not to call tools; the current child APIs do not support replacing an existing session's tool set for one turn, so their separate deadline and abort path remain the enforcement boundary.
|
|
1092
|
+
Before a retained RPC summary starts, validated in-flight usage from the interrupted work attempt is committed so the summary adds to it exactly once.
|
|
1093
|
+
The deterministic checkpoint remains available when finalization or the provider fails, and results retain exit `124` plus a structured termination reason and finalization status.
|
|
1094
|
+
Explicit parent or user abort stops immediately, never starts finalization, and is not mislabeled as a budget stop.
|
|
1013
1095
|
|
|
1014
|
-
This release does not claim a cooperative soft-wrap-up phase because print-mode subprocess children cannot receive steering while they are running.
|
|
1096
|
+
This release does not claim a cooperative soft-wrap-up phase because print-mode subprocess children cannot receive steering while they are running.
|
|
1097
|
+
It also does not retry budget-stopped work automatically because file or external side effects may already have occurred.
|
|
1015
1098
|
|
|
1016
|
-
The child event protocol limits each JSON line to 256 KiB.
|
|
1099
|
+
The child event protocol limits each JSON line to 256 KiB.
|
|
1100
|
+
Captured output uses these defaults:
|
|
1017
1101
|
|
|
1018
1102
|
- final output and fan-in/chain context: 50 KiB;
|
|
1019
1103
|
- stderr: 16 KiB;
|
|
1020
1104
|
- captured messages: 200.
|
|
1021
1105
|
|
|
1022
|
-
Truncated text includes a `truncated by pi-subagents` marker and details expose `truncated: true`.
|
|
1106
|
+
Truncated text includes a `truncated by pi-subagents` marker and details expose `truncated: true`.
|
|
1107
|
+
Inspection and consultation model-facing content also stops at 2,000 lines, whichever limit is reached first.
|
|
1108
|
+
`PI_SUBAGENT_MAX_DEPTH` controls nested delegation depth and defaults to 1; child processes receive `PI_SUBAGENT_DEPTH` automatically.
|
|
1023
1109
|
|
|
1024
1110
|
## 📡 Runtime status
|
|
1025
1111
|
|
|
@@ -1035,11 +1121,16 @@ Subprocess and in-process timing fields use the nearest public lifecycle boundar
|
|
|
1035
1121
|
Timing and progress are current-session diagnostics and are not persisted.
|
|
1036
1122
|
The benchmark measures transport overhead rather than model latency or output quality.
|
|
1037
1123
|
|
|
1038
|
-
While the `subagent` tool is running, `pi-subagents` publishes compact activity status with `ctx.ui.setStatus("subagents", "...")`.
|
|
1124
|
+
While the `subagent` tool is running, `pi-subagents` publishes compact activity status with `ctx.ui.setStatus("subagents", "...")`.
|
|
1125
|
+
Any statusline extension that reads Pi's generic extension status API can display it; no package-to-package dependency is required.
|
|
1039
1126
|
|
|
1040
|
-
## 🔒
|
|
1127
|
+
## 🔒 Security and privacy
|
|
1041
1128
|
|
|
1042
|
-
Subagents have separate processes and context windows, but they are **not security sandboxes**.
|
|
1129
|
+
Subagents have separate processes and context windows, but they are **not security sandboxes**.
|
|
1130
|
+
They run as the same OS user, share the host filesystem and network access, and may conflict if they edit the same files.
|
|
1131
|
+
Tool allow-lists reduce available Pi tools but do not reduce operating-system permissions.
|
|
1132
|
+
`subagent_consult` prevents writes through its Pi tool surface and disables extensions, but it can read accessible paths, call the configured model over the network, and incur cost; its instruction-resource policy is not a filesystem or confidentiality boundary.
|
|
1133
|
+
Panel write-capable reviewers use separate disposable Git worktrees, but those worktrees provide repository-write isolation only.
|
|
1043
1134
|
|
|
1044
1135
|
Every contracted execution records a hashed immutable `ExecutionPlan` and an executor-owned capability grant bound to its task generation, effective tools, issuance time, and expiry.
|
|
1045
1136
|
Interrupt, close, shutdown, replacement, persistence, and restore revoke active grants before signalling work or accepting another generation, and late old-plan results become `stale` diagnostic evidence.
|
|
@@ -1050,7 +1141,8 @@ The runner explicitly reports policy continuity in result details:
|
|
|
1050
1141
|
- overridden when selected: cwd, model, thinking level, and tool list;
|
|
1051
1142
|
- unsupported guarantees: parent approval policy, sandbox profile, and provider headers.
|
|
1052
1143
|
|
|
1053
|
-
Treat project-local agent prompts like executable project configuration: only enable them in trusted repositories.
|
|
1144
|
+
Treat project-local agent prompts like executable project configuration: only enable them in trusted repositories.
|
|
1145
|
+
Stateful project agents require Pi's project trust; interactive use also keeps confirmation enabled by default.
|
|
1054
1146
|
|
|
1055
1147
|
Stateful records are stored as versioned mode-0600 JSON under `~/.pi/agent/pi-subagents-state/` (or the configured Pi agent directory).
|
|
1056
1148
|
Explicit blocking-workflow snapshots use separate mode-0600 files under `~/.pi/agent/pi-subagents-workflows/`, retain at most 64 workflows per session for 30 days, and are available only through current-session workflow inspection.
|
|
@@ -1165,4 +1257,5 @@ Pi extension, Pi coding agent, subagents, agent delegation, parallel agents, rev
|
|
|
1165
1257
|
|
|
1166
1258
|
## 📄 License
|
|
1167
1259
|
|
|
1168
|
-
MIT.
|
|
1260
|
+
MIT.
|
|
1261
|
+
See [`LICENSE`](./LICENSE).
|