@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 +6 -0
- package/README.md +1 -1
- package/docs/agents.md +2 -124
- package/docs/extension-api.md +0 -55
- package/docs/fork-extensions.md +184 -0
- package/package.json +1 -1
- package/src/agents/agent-eject.ts +339 -0
- package/src/agents/agent-management.ts +8 -328
- package/src/api/agent-management.ts +2 -2
- package/src/api/preflight.ts +21 -15
- package/src/runs/background/async-status.ts +6 -22
- package/src/runs/background/subagent-runner.ts +4 -12
- package/src/runs/foreground/subagent-executor.ts +19 -14
- package/src/runs/shared/child-launch.ts +5 -69
- package/src/runs/shared/child-tool-plan.ts +7 -101
- package/src/runs/shared/nested-events.ts +8 -24
- package/src/runs/shared/profile-extensions.ts +134 -0
- package/src/runs/shared/profile-launch-env.ts +113 -0
- package/src/runs/shared/sandbox-profile-guard.ts +34 -0
- package/src/shared/permission-profile.ts +14 -0
- package/src/shared/sandbox-profile.ts +14 -0
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/
|
|
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
|
|
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`.
|
package/docs/extension-api.md
CHANGED
|
@@ -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.
|