@xzzpig/pi-subagents 0.15.0 → 0.15.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 CHANGED
@@ -1,5 +1,11 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.15.1] - 2026-09-19
4
+
5
+ ### Changed
6
+
7
+ - **Conflict-surface refactor, no behavior change.** The agent-eject implementation moved to fork-only `src/agents/agent-eject.ts`; the sandbox/permission-profile resolution and launch-env construction moved to fork-only `src/runs/shared/profile-extensions.ts` and `profile-launch-env.ts` (all error messages byte-identical); profile-name validation and project-trust error copies were deduplicated into the fork-only shared modules; fork test blocks moved out of five upstream test files (now byte-identical to upstream) into `test/unit/fork-*.test.ts`; fork documentation chapters moved to `docs/fork-extensions.md`.
8
+
3
9
  ## [0.15.0] - 2026-09-17
4
10
 
5
11
  ### Changed
package/README.md CHANGED
@@ -52,7 +52,7 @@ When you finish implementing, run a reviewer subagent before summarizing.
52
52
 
53
53
  ### Pre-declaring agents in context (context injection)
54
54
 
55
- By default Pi discovers agents by calling `subagent({ action: "list" })`. You can pre-declare selected agents in the parent system prompt so routing happens without that round trip: set `injectToContext: true` in an agent's frontmatter, or list names under `subagents.injectAgents` in settings. The union is injected once per session as a compact block — byte-stable across turns, so prompt caching stays effective. Disabled and capability-restricted agents are never advertised; unknown setting names are ignored and reported by `/subagents-doctor`. See [docs/agents.md](docs/agents.md#context-injection).
55
+ By default Pi discovers agents by calling `subagent({ action: "list" })`. You can pre-declare selected agents in the parent system prompt so routing happens without that round trip: set `injectToContext: true` in an agent's frontmatter, or list names under `subagents.injectAgents` in settings. The union is injected once per session as a compact block — byte-stable across turns, so prompt caching stays effective. Disabled and capability-restricted agents are never advertised; unknown setting names are ignored and reported by `/subagents-doctor`. See [docs/fork-extensions.md](docs/fork-extensions.md#context-injection).
56
56
 
57
57
  ## Builtin agents
58
58
 
package/docs/agents.md CHANGED
@@ -346,7 +346,7 @@ Field notes:
346
346
  | `extensions` | Omitted means a background child loads the parent's ambient extensions; empty means no ambient extensions; list values load exactly those extensions. Foreground children never load ambient extensions, so for them only listed values apply. |
347
347
  | `subagentOnlyExtensions` | Extension paths loaded only in this agent's child sessions. Tools registered there are unavailable to the main agent unless also installed through normal Pi extension configuration. |
348
348
  | `sandbox` | Optional named `pi-sandbox` profile for a native Pi child. It must be a non-empty safe name defined in the user's global `<agentDir>/sandbox.json`; it is a selector only, never an inline network or filesystem policy. |
349
- | `permission-profile` | Optional named permission profile for a native Pi child. The name must be a non-empty safe identifier defined in the global `pi-permission-system` config's `profiles` registry; only the validated name is passed to the child. See below. |
349
+ | `permission-profile` | Optional named permission profile for a native Pi child. The name must be a non-empty safe identifier defined in the global `pi-permission-system` config's `profiles` registry; only the validated name is passed to the child. See [Permission profiles](fork-extensions.md#permission-profiles). |
350
350
  | `model` | Default model. Bare ids prefer the current provider when possible, then unique registry matches. |
351
351
  | `thinking` | Appended as a `:level` suffix at runtime unless a suffix is already present. |
352
352
  | `systemPromptMode` | `replace` by default; `append` keeps Pi's base prompt. |
@@ -368,131 +368,9 @@ Field notes:
368
368
  | `completionGuard` | Set `false` only for non-implementation agents that may mention implementation words while using mutation-capable tools such as `bash`. |
369
369
  | `interactive` | Parsed for compatibility but not currently enforced. |
370
370
  | `maxSubagentDepth` | Tightens nested delegation for this agent's children. |
371
- | `injectToContext` | Advertise this agent in the parent system prompt at session start so the main agent can select it without calling `{ action: "list" }` first. See [Context injection](#context-injection). |
371
+ | `injectToContext` | Advertise this agent in the parent system prompt at session start so the main agent can select it without calling `{ action: "list" }` first. See [Context injection](fork-extensions.md#context-injection). |
372
372
  | `memory` | Opt-in role-specific persistent memory. See below. |
373
373
 
374
- ### Sandbox profiles
375
-
376
- Use `sandbox: <profile-name>` only for a native Pi child. The profile is resolved
377
- from the global `pi-sandbox` configuration, never from an agent file or a project
378
- profile registry:
379
-
380
- ```yaml
381
- ---
382
- name: security-reviewer
383
- description: Review changes with a constrained filesystem and no network
384
- sandbox: reviewer-strict
385
- extensions: ./review-tools.ts
386
- ---
387
-
388
- Review the requested change.
389
- ```
390
-
391
- `pi-subagents` validates the scalar name and passes only that name to the child.
392
- It automatically resolves and injects the installed `pi-sandbox` extension and a
393
- startup guard even when `extensions` is an explicit allowlist; an explicit empty
394
- allowlist does not remove these required runtime extensions. The guard requires
395
- `pi-sandbox` to acknowledge successful profile initialization before the child
396
- can enter its first model turn. The launch fails before the model's first turn when the package or manifest is missing, a capability ceiling denies child
397
- extensions, the profile cannot be loaded, or sandbox initialization fails. A
398
- blocked child publishes that reason through its startup diagnostics, so the
399
- caller sees the profile error (and the available profile names) instead of a
400
- generic empty-output message; a startup block is never recorded as a model
401
- failure and never excludes the model from later runs.
402
-
403
- The field is rejected for `external-cli` and `external-job` runners because they
404
- do not host a Pi child extension. It also cannot be an object, `false`, an empty
405
- value, or an inline allow/deny policy. Define the actual network and filesystem
406
- rules in global `pi-sandbox` `profiles` instead.
407
-
408
- A profile chosen by a project-scoped agent or project override is used only when
409
- the host marks that project trusted. Otherwise the launch reports an actionable
410
- trust error. In a headless child, accesses outside the profile's preconfigured
411
- network/read/write rules are blocked; pi-sandbox does not use Permission System
412
- or supervisor forwarding to ask the parent for an approval. See
413
- [`pi-sandbox`'s README](https://github.com/xzzpig/pi-extensions/tree/main/packages/pi-sandbox#named-profiles-for-subagents)
414
- for profile inheritance and merge rules.
415
-
416
- ### Permission profiles
417
-
418
- Use `permission-profile: <name>` to select a named policy profile from the
419
- **global-only** `profiles` registry in `pi-permission-system`'s config
420
- (`<agentDir>/extensions/pi-permission-system/config.json`). It is a selector
421
- only — the actual rules (tool scalars, `bash`/`mcp`/`skill`/`external_directory`
422
- pattern maps, `'*'` fallback) live in that registry and always resolve from the
423
- child's own global config:
424
-
425
- ```yaml
426
- ---
427
- name: reviewer
428
- description: Review changes without write access
429
- permission-profile: reviewer
430
- ---
431
- Review the requested change and report findings.
432
- ```
433
-
434
- `pi-subagents` validates the scalar name (same grammar as sandbox profiles),
435
- passes only that name to the child via the transient
436
- `PI_SUBAGENT_PERMISSION_PROFILE` environment variable, and injects the
437
- installed `pi-permission-system` extension into the child launch even when
438
- `extensions` is an explicit allowlist, so the child's permission system applies
439
- the selected profile. The env channel carries a bare validated name — raw
440
- policy is never transmitted — and the rules are always read from the child's
441
- own global config, so the profile means the same policy regardless of which
442
- host launches the agent. Selection precedence inside the permission system is
443
- env > project agent file > global agent file.
444
-
445
- The launch fails closed when a profile is declared but `pi-permission-system`
446
- is not installed, when a capability ceiling denies child extensions, or when
447
- the runner is not a native Pi child (the field is rejected for `external-cli`
448
- and `external-job` runners). At runtime, selecting an unknown profile or an
449
- empty ruleset clamps that agent's `allow` rules to `ask` with an explicit
450
- `Permission profile '<name>' could not be resolved` diagnostic — it never
451
- silently degrades to the unselected baseline. An agent without the field keeps
452
- its pre-change behavior exactly.
453
-
454
- The profile merges between the project config and the agent's own `permission:`
455
- block: patterns the profile does not mention keep the lower scopes' rules
456
- (global denies survive), and `permission:` overrides the profile per pattern.
457
- A profile selected by a **project** agent file participates only when the host
458
- marks that project trusted.
459
-
460
- ## Context injection
461
-
462
- By default the parent agent learns which agents exist only by calling `subagent({ action: "list" })`. Context injection pre-declares selected agents in the parent system prompt through a compact `<available_subagents>` block, so routing decisions can happen without a discovery round trip.
463
-
464
- Two sources contribute, and the union is advertised:
465
-
466
- 1. Agent files that opt in with `injectToContext: true` in their frontmatter.
467
- 2. The `subagents.injectAgents` setting, which lists agent names (canonical names or aliases; builtins allowed):
468
-
469
- ```json
470
- {
471
- "subagents": {
472
- "injectAgents": ["worker", "reviewer", "security-reviewer"]
473
- }
474
- }
475
- ```
476
-
477
- Rendered block shape:
478
-
479
- ```text
480
- <available_subagents>
481
- The following pre-declared subagents are available.
482
- Launch them with the subagent tool when a task matches their description.
483
-
484
- - security-reviewer: Security review specialist
485
- - worker: Implementation work, including approved oracle handoffs.
486
- </available_subagents>
487
- ```
488
-
489
- Semantics and guarantees:
490
-
491
- - **Snapshot per session.** The list resolves once at session start (and on reload) and stays byte-identical for every turn, so provider prompt caching is never invalidated mid-session. Edits to agent files or settings take effect in a new session, not the current one; `{ action: "list" }` remains the runtime source of truth.
492
- - **Only executable agents are advertised.** Disabled agents and agents restricted by the session capability ceiling are never injected.
493
- - **Children never see it.** Spawned child sessions do not load the parent injection; fanout children can still call `{ action: "list" }`.
494
- - **Unknown setting names are ignored** and reported by `/subagents-doctor` instead of failing startup.
495
- - The block is appended only when it is not already present, so forked or resumed sessions never duplicate it.
496
374
  ### Required host extensions
497
375
 
498
376
  Hosts can import `registerRequiredChildExtensions` from `pi-subagents/required-child-extensions` and register `{ sessionId, extensions: [{ id, path }] }`. Paths resolve to existing files and are canonicalized into an immutable launch snapshot; bounded safe IDs appear in evidence instead of paths. One registration is allowed per parent session until its idempotent `dispose()` runs, normally on `session_shutdown`.
@@ -192,41 +192,6 @@ The installed owner applies the existing runtime-agent validation, collision che
192
192
 
193
193
  This contract is process-local. It does not register agents in child sessions or other Pi processes, and it does not change package discovery or package resolution.
194
194
 
195
- ## Agent discovery from independent extensions
196
-
197
- An extension that wants to offer the same agent list the subagent launcher uses
198
- — a session role picker, for example — can call the exported discovery helper
199
- instead of re-implementing agent loading:
200
-
201
- ```typescript
202
- import { discoverAgentsWithRuntime } from "pi-subagents/agents";
203
-
204
- const result = discoverAgentsWithRuntime(pi, cwd, "both");
205
- for (const agent of result.agents) {
206
- // agent.name, agent.description, agent.aliases, agent.source,
207
- // agent.sandbox, agent.permissionProfile, agent.override?.scope, agent.disabled
208
- }
209
- result.agentDiagnostics; // loader problems, per source
210
- result.projectAgentsDir; // where project agents came from
211
- ```
212
-
213
- The result is the merged view: builtin, package, user, and project agent files
214
- plus anything registered at runtime through the contract above. With nothing
215
- registered, it is exactly `discoverAgents(cwd, scope)`.
216
-
217
- `scope` is `"user" | "project" | "both"`. Pass the caller's `cwd` so project
218
- layering resolves against the right tree, and pass the caller's `ExtensionAPI`
219
- because the runtime registry is keyed on it.
220
-
221
- Two notes for consumers of an optional dependency:
222
-
223
- - Treat the module as optional. A package that is not installed cannot be
224
- imported, so load it dynamically and report the failure rather than failing
225
- extension load.
226
- - `agent.source === "project"` (or `agent.override?.scope === "project"`) means
227
- the definition comes from the current project. Gate such an agent behind the
228
- host's project-trust decision before adopting it for anything.
229
-
230
195
  ## External jobs in FleetView
231
196
 
232
197
  Use `pi-subagents/external-runs` to publish display-only current-session jobs owned by another extension:
@@ -312,26 +277,6 @@ Boundaries:
312
277
  - Some host-owned facts, such as exact fork snapshots, nested async roots, and live model registries, can only be proven by the Pi host; those appear as `host_required` diagnostics instead of silently pretending to be exact.
313
278
  - Preflight reads the extension config, so `defaultSubagentContext: "fresh"` or `"fork"` affects omitted context in the same way as execution. Explicit `context` still wins.
314
279
 
315
- ## Agent ejection API
316
-
317
- Use `@xzzpig/pi-subagents/agent-management` when an extension needs to make a bundled agent editable without parsing model-facing management output:
318
-
319
- ```ts
320
- import { ejectAgentDefinition } from "@xzzpig/pi-subagents/agent-management";
321
-
322
- const result = ejectAgentDefinition({
323
- cwd: ctx.cwd,
324
- agent: "reviewer",
325
- scope: "project",
326
- projectTrusted: ctx.isProjectTrusted(),
327
- });
328
-
329
- if (!result.ok) throw new Error(result.message);
330
- console.log(result.targetPath, result.verification.launchPreflighted);
331
- ```
332
-
333
- The operation never overwrites an existing agent, chain, or conflicting file. Package-relative tool, extension, and skill paths are normalized before writing. After rediscovery, it validates copied skills and the static child launch tool plan; if that check fails, it removes only the new file created by that call and returns `preflight_failed`. Host-dependent checks such as the live model registry and actual child process startup remain the responsibility of the caller's normal launch preflight/execution path.
334
-
335
280
  ## Structured delegation API
336
281
 
337
282
  Other Pi extensions can ask `pi-subagents` to run one configured foreground leaf agent through the structured delegation API. It uses the established `prompt-template:subagent:*` event family and the same executor as the `subagent` tool; it does not add another launcher.
@@ -0,0 +1,184 @@
1
+ # Fork extensions
2
+
3
+ Documentation for `@xzzpig/pi-subagents`-specific extensions that are not part
4
+ of upstream `pi-subagents`. These chapters were moved out of
5
+ [`agents.md`](agents.md) and [`extension-api.md`](extension-api.md) so those
6
+ files stay byte-identical to upstream.
7
+
8
+ ## Sandbox profiles
9
+
10
+ Use `sandbox: <profile-name>` only for a native Pi child. The profile is resolved
11
+ from the global `pi-sandbox` configuration, never from an agent file or a project
12
+ profile registry:
13
+
14
+ ```yaml
15
+ ---
16
+ name: security-reviewer
17
+ description: Review changes with a constrained filesystem and no network
18
+ sandbox: reviewer-strict
19
+ extensions: ./review-tools.ts
20
+ ---
21
+
22
+ Review the requested change.
23
+ ```
24
+
25
+ `pi-subagents` validates the scalar name and passes only that name to the child.
26
+ It automatically resolves and injects the installed `pi-sandbox` extension and a
27
+ startup guard even when `extensions` is an explicit allowlist; an explicit empty
28
+ allowlist does not remove these required runtime extensions. The guard requires
29
+ `pi-sandbox` to acknowledge successful profile initialization before the child
30
+ can enter its first model turn. The launch fails before the model's first turn when the package or manifest is missing, a capability ceiling denies child
31
+ extensions, the profile cannot be loaded, or sandbox initialization fails. A
32
+ blocked child publishes that reason through its startup diagnostics, so the
33
+ caller sees the profile error (and the available profile names) instead of a
34
+ generic empty-output message; a startup block is never recorded as a model
35
+ failure and never excludes the model from later runs.
36
+
37
+ The field is rejected for `external-cli` and `external-job` runners because they
38
+ do not host a Pi child extension. It also cannot be an object, `false`, an empty
39
+ value, or an inline allow/deny policy. Define the actual network and filesystem
40
+ rules in global `pi-sandbox` `profiles` instead.
41
+
42
+ A profile chosen by a project-scoped agent or project override is used only when
43
+ the host marks that project trusted. Otherwise the launch reports an actionable
44
+ trust error. In a headless child, accesses outside the profile's preconfigured
45
+ network/read/write rules are blocked; pi-sandbox does not use Permission System
46
+ or supervisor forwarding to ask the parent for an approval. See
47
+ [`pi-sandbox`'s README](https://github.com/xzzpig/pi-extensions/tree/main/packages/pi-sandbox#named-profiles-for-subagents)
48
+ for profile inheritance and merge rules.
49
+
50
+ ## Permission profiles
51
+
52
+ Use `permission-profile: <name>` to select a named policy profile from the
53
+ **global-only** `profiles` registry in `pi-permission-system`'s config
54
+ (`<agentDir>/extensions/pi-permission-system/config.json`). It is a selector
55
+ only — the actual rules (tool scalars, `bash`/`mcp`/`skill`/`external_directory`
56
+ pattern maps, `'*'` fallback) live in that registry and always resolve from the
57
+ child's own global config:
58
+
59
+ ```yaml
60
+ ---
61
+ name: reviewer
62
+ description: Review changes without write access
63
+ permission-profile: reviewer
64
+ ---
65
+ Review the requested change and report findings.
66
+ ```
67
+
68
+ `pi-subagents` validates the scalar name (same grammar as sandbox profiles),
69
+ passes only that name to the child via the transient
70
+ `PI_SUBAGENT_PERMISSION_PROFILE` environment variable, and injects the
71
+ installed `pi-permission-system` extension into the child launch even when
72
+ `extensions` is an explicit allowlist, so the child's permission system applies
73
+ the selected profile. The env channel carries a bare validated name — raw
74
+ policy is never transmitted — and the rules are always read from the child's
75
+ own global config, so the profile means the same policy regardless of which
76
+ host launches the agent. Selection precedence inside the permission system is
77
+ env > project agent file > global agent file.
78
+
79
+ The launch fails closed when a profile is declared but `pi-permission-system`
80
+ is not installed, when a capability ceiling denies child extensions, or when
81
+ the runner is not a native Pi child (the field is rejected for `external-cli`
82
+ and `external-job` runners). At runtime, selecting an unknown profile or an
83
+ empty ruleset clamps that agent's `allow` rules to `ask` with an explicit
84
+ `Permission profile '<name>' could not be resolved` diagnostic — it never
85
+ silently degrades to the unselected baseline. An agent without the field keeps
86
+ its pre-change behavior exactly.
87
+
88
+ The profile merges between the project config and the agent's own `permission:`
89
+ block: patterns the profile does not mention keep the lower scopes' rules
90
+ (global denies survive), and `permission:` overrides the profile per pattern.
91
+ A profile selected by a **project** agent file participates only when the host
92
+ marks that project trusted.
93
+
94
+ ## Context injection
95
+
96
+ By default the parent agent learns which agents exist only by calling `subagent({ action: "list" })`. Context injection pre-declares selected agents in the parent system prompt through a compact `<available_subagents>` block, so routing decisions can happen without a discovery round trip.
97
+
98
+ Two sources contribute, and the union is advertised:
99
+
100
+ 1. Agent files that opt in with `injectToContext: true` in their frontmatter.
101
+ 2. The `subagents.injectAgents` setting, which lists agent names (canonical names or aliases; builtins allowed):
102
+
103
+ ```json
104
+ {
105
+ "subagents": {
106
+ "injectAgents": ["worker", "reviewer", "security-reviewer"]
107
+ }
108
+ }
109
+ ```
110
+
111
+ Rendered block shape:
112
+
113
+ ```text
114
+ <available_subagents>
115
+ The following pre-declared subagents are available.
116
+ Launch them with the subagent tool when a task matches their description.
117
+
118
+ - security-reviewer: Security review specialist
119
+ - worker: Implementation work, including approved oracle handoffs.
120
+ </available_subagents>
121
+ ```
122
+
123
+ Semantics and guarantees:
124
+
125
+ - **Snapshot per session.** The list resolves once at session start (and on reload) and stays byte-identical for every turn, so provider prompt caching is never invalidated mid-session. Edits to agent files or settings take effect in a new session, not the current one; `{ action: "list" }` remains the runtime source of truth.
126
+ - **Only executable agents are advertised.** Disabled agents and agents restricted by the session capability ceiling are never injected.
127
+ - **Children never see it.** Spawned child sessions do not load the parent injection; fanout children can still call `{ action: "list" }`.
128
+ - **Unknown setting names are ignored** and reported by `/subagents-doctor` instead of failing startup.
129
+ - The block is appended only when it is not already present, so forked or resumed sessions never duplicate it.
130
+
131
+ ## Agent discovery from independent extensions
132
+
133
+ An extension that wants to offer the same agent list the subagent launcher uses
134
+ — a session role picker, for example — can call the exported discovery helper
135
+ instead of re-implementing agent loading:
136
+
137
+ ```typescript
138
+ import { discoverAgentsWithRuntime } from "pi-subagents/agents";
139
+
140
+ const result = discoverAgentsWithRuntime(pi, cwd, "both");
141
+ for (const agent of result.agents) {
142
+ // agent.name, agent.description, agent.aliases, agent.source,
143
+ // agent.sandbox, agent.permissionProfile, agent.override?.scope, agent.disabled
144
+ }
145
+ result.agentDiagnostics; // loader problems, per source
146
+ result.projectAgentsDir; // where project agents came from
147
+ ```
148
+
149
+ The result is the merged view: builtin, package, user, and project agent files
150
+ plus anything registered at runtime through the contract above. With nothing
151
+ registered, it is exactly `discoverAgents(cwd, scope)`.
152
+
153
+ `scope` is `"user" | "project" | "both"`. Pass the caller's `cwd` so project
154
+ layering resolves against the right tree, and pass the caller's `ExtensionAPI`
155
+ because the runtime registry is keyed on it.
156
+
157
+ Two notes for consumers of an optional dependency:
158
+
159
+ - Treat the module as optional. A package that is not installed cannot be
160
+ imported, so load it dynamically and report the failure rather than failing
161
+ extension load.
162
+ - `agent.source === "project"` (or `agent.override?.scope === "project"`) means
163
+ the definition comes from the current project. Gate such an agent behind the
164
+ host's project-trust decision before adopting it for anything.
165
+
166
+ ## Agent ejection API
167
+
168
+ Use `@xzzpig/pi-subagents/agent-management` when an extension needs to make a bundled agent editable without parsing model-facing management output:
169
+
170
+ ```ts
171
+ import { ejectAgentDefinition } from "@xzzpig/pi-subagents/agent-management";
172
+
173
+ const result = ejectAgentDefinition({
174
+ cwd: ctx.cwd,
175
+ agent: "reviewer",
176
+ scope: "project",
177
+ projectTrusted: ctx.isProjectTrusted(),
178
+ });
179
+
180
+ if (!result.ok) throw new Error(result.message);
181
+ console.log(result.targetPath, result.verification.launchPreflighted);
182
+ ```
183
+
184
+ The operation never overwrites an existing agent, chain, or conflicting file. Package-relative tool, extension, and skill paths are normalized before writing. After rediscovery, it validates copied skills and the static child launch tool plan; if that check fails, it removes only the new file created by that call and returns `preflight_failed`. Host-dependent checks such as the live model registry and actual child process startup remain the responsibility of the caller's normal launch preflight/execution path.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xzzpig/pi-subagents",
3
- "version": "0.15.0",
3
+ "version": "0.15.1",
4
4
  "description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
5
5
  "author": "Nico Bailon",
6
6
  "license": "MIT",