@xzzpig/pi-subagents 0.4.2 → 0.6.0
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 +172 -1
- package/README.md +8 -0
- package/agents/oracle.md +3 -1
- package/agents/reviewer.md +1 -0
- package/agents/scout.md +2 -2
- package/agents/worker.md +2 -1
- package/async-retention-discovery-worker.mjs +180 -0
- package/docs/agents.md +79 -2
- package/docs/configuration.md +42 -14
- package/docs/extension-api.md +45 -2
- package/docs/models.md +2 -0
- package/docs/observability.md +41 -5
- package/docs/tool-reference.md +38 -39
- package/docs/workflows.md +173 -3
- package/package.json +13 -10
- package/prompts/council.md +48 -0
- package/skills/council-mode/SKILL.md +230 -0
- package/skills/pi-subagents/SKILL.md +8 -4
- package/skills/pi-subagents/references/constraints-and-recipes.md +13 -6
- package/skills/pi-subagents/references/execution-controls.md +40 -15
- package/skills/pi-subagents/references/management-authoring-rpc.md +3 -3
- package/skills/pi-subagents/references/multi-lane-orchestration.md +39 -0
- package/skills/pi-subagents/references/prompting-and-roles.md +4 -2
- package/src/agents/agent-management.ts +158 -357
- package/src/agents/agent-serializer.ts +4 -0
- package/src/agents/agents.ts +227 -53
- package/src/agents/builtin-names.ts +9 -0
- package/src/agents/runtime-agent-registry.ts +422 -0
- package/src/agents/skills.ts +1 -1
- package/src/api/agents.ts +7 -0
- package/src/api/external-job-provider.ts +186 -0
- package/src/api/preflight.ts +37 -9
- package/src/api/shared-types.ts +2 -0
- package/src/extension/config.ts +6 -3
- package/src/extension/context-injection.ts +118 -0
- package/src/extension/doctor.ts +15 -6
- package/src/extension/fanout-child.ts +2 -2
- package/src/extension/index.ts +224 -90
- package/src/extension/public-execution.ts +31 -2
- package/src/extension/rpc.ts +41 -1
- package/src/extension/schemas.ts +17 -37
- package/src/extension/tool-description.ts +35 -24
- package/src/inspectors/herdr/actions.ts +2 -2
- package/src/inspectors/herdr/inspector-runner.ts +2 -1
- package/src/inspectors/herdr/project-panes.ts +2 -2
- package/src/intercom/native-supervisor-channel.ts +32 -10
- package/src/missions/lifecycle.ts +6 -1
- package/src/missions/store.ts +4 -9
- package/src/missions/workflow-state.ts +2 -2
- package/src/profiles/profiles.ts +3 -1
- package/src/runs/background/active-run-index.ts +31 -8
- package/src/runs/background/async-execution.ts +70 -41
- package/src/runs/background/async-job-tracker.ts +24 -7
- package/src/runs/background/async-resume.ts +49 -16
- package/src/runs/background/async-retention.ts +886 -0
- package/src/runs/background/async-status-snapshot.ts +14 -5
- package/src/runs/background/async-status.ts +39 -53
- package/src/runs/background/auto-drain.ts +1 -0
- package/src/runs/background/chain-append.ts +3 -33
- package/src/runs/background/completion-dedupe.ts +5 -1
- package/src/runs/background/completion-replay.ts +22 -12
- package/src/runs/background/control-channel.ts +14 -68
- package/src/runs/background/fleet-view.ts +68 -19
- package/src/runs/background/index-segment.ts +59 -0
- package/src/runs/background/inspect-rpc.ts +443 -0
- package/src/runs/background/notify.ts +31 -5
- package/src/runs/background/result-files.ts +158 -90
- package/src/runs/background/result-watcher.ts +124 -20
- package/src/runs/background/resume-guidance.ts +8 -5
- package/src/runs/background/retained-children.ts +13 -3
- package/src/runs/background/run-id-query.ts +7 -0
- package/src/runs/background/run-id-resolver.ts +11 -9
- package/src/runs/background/run-status.ts +27 -18
- package/src/runs/background/scheduled-runs.ts +24 -4
- package/src/runs/background/stale-run-reconciler.ts +6 -3
- package/src/runs/background/steering.ts +11 -1
- package/src/runs/background/subagent-runner.ts +260 -144
- package/src/runs/background/subagent-wait.ts +17 -13
- package/src/runs/background/terminal-run-index.ts +138 -0
- package/src/runs/background/wait-completions.ts +21 -4
- package/src/runs/background/wait-subscriptions.ts +81 -2
- package/src/runs/background/wait-tool.ts +1 -0
- package/src/runs/foreground/async-steering-action.ts +21 -14
- package/src/runs/foreground/execution.ts +8 -2
- package/src/runs/foreground/subagent-executor.ts +816 -1593
- package/src/runs/foreground/workflow-detach-reconcile.ts +262 -0
- package/src/runs/foreground/workflow-foreground-steering.ts +6 -5
- package/src/runs/shared/acceptance.ts +48 -5
- package/src/runs/shared/chain-outputs.ts +1 -3
- package/src/runs/shared/external-job-bridge.ts +444 -0
- package/src/runs/shared/external-job-runner.ts +286 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +14 -0
- package/src/runs/shared/model-exclusions.ts +242 -0
- package/src/runs/shared/model-fallback.ts +153 -40
- package/src/runs/shared/orca-progress-tabs.ts +84 -22
- package/src/runs/shared/parallel-handoff.ts +46 -4
- package/src/runs/shared/parallel-utils.ts +4 -15
- package/src/runs/shared/permissions.ts +5 -1
- package/src/runs/shared/pi-args.ts +8 -1
- package/src/runs/shared/session-lease.ts +0 -6
- package/src/runs/shared/subagent-control.ts +51 -7
- package/src/runs/shared/subagent-prompt-runtime.ts +12 -6
- package/src/runs/shared/workflow-graph.ts +1 -23
- package/src/runs/shared/worktree.ts +14 -2
- package/src/shared/atomic-json.ts +22 -2
- package/src/shared/capacity-resilient-json.ts +102 -0
- package/src/shared/completion-owner.ts +14 -0
- package/src/shared/file-system-retry.ts +49 -1
- package/src/shared/fork-context.ts +59 -1
- package/src/shared/model-info.ts +20 -0
- package/src/shared/prompt-resources.ts +0 -40
- package/src/shared/settings.ts +5 -29
- package/src/shared/types.ts +110 -26
- package/src/shared/utils.ts +8 -0
- package/src/shared/watch-strategy.ts +10 -0
- package/src/slash/slash-bridge.ts +2 -1
- package/src/slash/slash-commands.ts +47 -7
- package/src/slash/slash-live-state.ts +3 -3
- package/src/tui/fleet-status.ts +86 -1
- package/src/tui/fleet.ts +117 -16
- package/src/tui/render.ts +73 -3
- package/src/watchdog/change-signature.ts +1 -1
- package/src/watchdog/lsp-diagnostics.ts +1 -0
- package/src/workflows/chat-progress.ts +2 -2
- package/src/workflows/scripted-workflow.ts +320 -79
- package/src/workflows/workflow-receipt.ts +140 -0
- package/src/runs/foreground/chain-clarify.ts +0 -1354
- package/src/runs/foreground/chain-execution.ts +0 -1581
package/docs/workflows.md
CHANGED
|
@@ -10,7 +10,7 @@ Use orchestration as parent-agent guidance, not as a runtime workflow mode. For
|
|
|
10
10
|
clarify → scout → worker → fresh reviewers → worker
|
|
11
11
|
```
|
|
12
12
|
|
|
13
|
-
Packaged `worker`, `oracle`, and `advisor` default to forked context when a launch omits `context
|
|
13
|
+
Packaged `worker`, `oracle`, and `advisor` default to forked context when a launch omits `context`. If the parent has no persisted session file or current leaf yet, that implicit default falls back to `fresh`. Pass `context: "fresh"` when you intentionally want a fresh child run, or `context: "fork"` when fork must remain strict.
|
|
14
14
|
|
|
15
15
|
Child-safety boundaries are enforced at runtime:
|
|
16
16
|
|
|
@@ -35,7 +35,9 @@ Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the syn
|
|
|
35
35
|
|
|
36
36
|
## Scripted workflows (workflowScript)
|
|
37
37
|
|
|
38
|
-
All model-facing subagent execution is expressed through `workflowScript` in the `subagent` tool. Use stable keys and ordinary JavaScript for one child, sequence, and parallelism. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
|
|
38
|
+
All model-facing subagent execution is expressed through `workflowScript` in the `subagent` tool. Use stable keys and ordinary JavaScript for one child, sequence, and parallelism. For ordinary parallel fanout, use `await runs.all([{ key, agent, task }, ...])`; do not read `.output` from unawaited `runs.run` launches. Store a `runs.run` promise only when the script later observes it with `await`, `Promise.race`, or `Promise.all`, such as steering a live child before awaiting its result. Scripts are ordinary JavaScript statement bodies. Use an explicit `return` for a useful result:
|
|
39
|
+
|
|
40
|
+
Child results cross into the script as plain JSON data. Non-JSON host metadata is omitted, so use returned fields such as `runId`, `ok`, `output`, and `structuredOutput` for workflow control.
|
|
39
41
|
|
|
40
42
|
```js
|
|
41
43
|
subagent({ workflowScript: `
|
|
@@ -48,6 +50,153 @@ subagent({ workflowScript: `
|
|
|
48
50
|
` });
|
|
49
51
|
```
|
|
50
52
|
|
|
53
|
+
Keep helper functions portable across Node and Bun. Use top-level `await`, plain helper functions that return `runs.run(...)`, or explicit Promise chains. Do not define nested `async function` helpers, async arrows, or async methods inside `workflowScript`; native async helpers hide child-launch observation in Bun and are rejected.
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
subagent({ workflowScript: `
|
|
57
|
+
function scan() {
|
|
58
|
+
return runs.run("scan", { agent: "scout", task: "Scan the codebase" });
|
|
59
|
+
}
|
|
60
|
+
const result = await scan();
|
|
61
|
+
return result.output;
|
|
62
|
+
` });
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Chaining is still supported. The supported form is scripted chaining: await one `runs.run(...)` result, then pass its output into the next step. Parallel fanout uses `runs.all(...)` inside the same script.
|
|
66
|
+
|
|
67
|
+
```js
|
|
68
|
+
subagent({ workflowScript: `
|
|
69
|
+
const plan = await runs.run("plan", { agent: "scout", task: "Plan the migration" });
|
|
70
|
+
const patch = await runs.run("patch", { agent: "worker", task: "Implement this plan:\n" + plan.output });
|
|
71
|
+
return patch.output;
|
|
72
|
+
` });
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Steering a workflow child
|
|
76
|
+
|
|
77
|
+
Use `await runs.steer(key, message, options?)` after `runs.run` or `runs.all` has launched that stable key. Scripts do not target raw run ids. The optional fields are `mode: "steer" | "follow_up" | "auto"`, a non-negative child `index`, and a positive `ackTimeoutMs`.
|
|
78
|
+
|
|
79
|
+
```js
|
|
80
|
+
subagent({ workflowScript: `
|
|
81
|
+
const writer = runs.run("writer", { agent: "worker", task: "Implement the change" });
|
|
82
|
+
const evidence = await runs.run("evidence", { agent: "scout", task: "Find the exact contract" });
|
|
83
|
+
const receipt = await runs.steer("writer", "Also check: " + evidence.output, { mode: "follow_up" });
|
|
84
|
+
return { writer: await writer, receipt };
|
|
85
|
+
` });
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The receipt state is `queued`, `delivered`, `missed`, or `failed`. `delivered` means the child Pi session accepted the input. It does not mean the model followed it. `missed` means the keyed child became terminal or had no live route before delivery. This first slice uses the existing foreground and async steering transports but does not start steering recovery. Workflow traces include one steering attempt entry and one receipt entry.
|
|
89
|
+
|
|
90
|
+
Always await or return a `runs.steer` promise. The workflow waits for an observed steering side effect to settle before it exits and rejects fire-and-forget calls. Use ordinary `Promise.race` when the first child or steering receipt should advance the script. There is no callback API or child inbox access.
|
|
91
|
+
|
|
92
|
+
### Advanced rolling child runs
|
|
93
|
+
|
|
94
|
+
`runs.run` starts a keyed child when you call it. You do not need separate `runs.start`, `runs.next`, or `runs.collect` helpers for rolling councils or staged reviews. This is the advanced exception to ordinary `runs.all` fanout: keep launched promises only when the script later observes each one with direct `await`, `Promise.race`, or `Promise.all`. Use `Promise.race` to wait for the next completed child, steer a still-running sibling by its stable key, and use `Promise.all` to collect the remaining children.
|
|
95
|
+
|
|
96
|
+
```js
|
|
97
|
+
subagent({ workflowScript: `
|
|
98
|
+
let pending = [
|
|
99
|
+
{ key: "analysis-a", promise: runs.run("analysis-a", { agent: "reviewer", task: "Analyze option A" }).then((result) => ({ key: "analysis-a", result })) },
|
|
100
|
+
{ key: "analysis-b", promise: runs.run("analysis-b", { agent: "reviewer", task: "Analyze option B" }).then((result) => ({ key: "analysis-b", result })) },
|
|
101
|
+
{ key: "critic", promise: runs.run("critic", { agent: "reviewer", task: "Find the strongest objection" }).then((result) => ({ key: "critic", result })) }
|
|
102
|
+
];
|
|
103
|
+
|
|
104
|
+
const first = await Promise.race(pending.map((child) => child.promise));
|
|
105
|
+
pending = pending.filter((child) => child.key !== first.key);
|
|
106
|
+
|
|
107
|
+
const target = pending.find((child) => child.key === "critic") ?? pending[0];
|
|
108
|
+
const receipt = await runs.steer(target.key, "Challenge this early result:\n" + first.result.output, { mode: "auto" });
|
|
109
|
+
const rest = await Promise.all(pending.map((child) => child.promise));
|
|
110
|
+
|
|
111
|
+
return { first: first.result.output, rest: rest.map((child) => child.result.output), receipt };
|
|
112
|
+
` });
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
The workflow trace records the run completions and steering receipt. Scripts still never see raw async directories, inbox paths, or session files. If the keyed child is terminal, stale, or has no live route when `runs.steer` runs, the receipt reports `missed` or `failed` and the script can decide whether to continue.
|
|
116
|
+
|
|
117
|
+
Use named outputs when later workflow steps need structured data or durable references:
|
|
118
|
+
|
|
119
|
+
```js
|
|
120
|
+
subagent({ workflowScript: `
|
|
121
|
+
const inventory = await runs.run("inventory", {
|
|
122
|
+
agent: "scout",
|
|
123
|
+
task: "List the files that need review.",
|
|
124
|
+
outputSchema: {
|
|
125
|
+
type: "object",
|
|
126
|
+
properties: { files: { type: "array", items: { type: "string" } } },
|
|
127
|
+
required: ["files"],
|
|
128
|
+
additionalProperties: false
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
return runs.run("review", {
|
|
132
|
+
agent: "reviewer",
|
|
133
|
+
task: "Review these files: " + inventory.structuredOutput.files.join(", ")
|
|
134
|
+
});
|
|
135
|
+
` });
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
For dynamic fanout, have one step return a structured list, check it in JavaScript, then map the bounded entries into `runs.all(...)`:
|
|
139
|
+
|
|
140
|
+
```js
|
|
141
|
+
subagent({ workflowScript: `
|
|
142
|
+
const targets = await runs.run("targets", {
|
|
143
|
+
agent: "scout",
|
|
144
|
+
task: "Return up to five source files that need review.",
|
|
145
|
+
outputSchema: {
|
|
146
|
+
type: "object",
|
|
147
|
+
properties: { files: { type: "array", items: { type: "string" }, maxItems: 5 } },
|
|
148
|
+
required: ["files"],
|
|
149
|
+
additionalProperties: false
|
|
150
|
+
}
|
|
151
|
+
});
|
|
152
|
+
const files = targets.structuredOutput.files.slice(0, 5);
|
|
153
|
+
return runs.all(files.map((file, index) => ({
|
|
154
|
+
key: "review-" + index,
|
|
155
|
+
agent: "reviewer",
|
|
156
|
+
task: "Review " + file
|
|
157
|
+
})));
|
|
158
|
+
` });
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
For intermediate data that only later steps need, prefer the prior child's returned output or `structuredOutput` instead of writing shared files:
|
|
162
|
+
|
|
163
|
+
```js
|
|
164
|
+
subagent({ workflowScript: `
|
|
165
|
+
const scan = await runs.run("scan", { agent: "scout", task: "Find the files that need fixes." });
|
|
166
|
+
return runs.run("fix", { agent: "worker", task: "Implement these findings:\n" + scan.output });
|
|
167
|
+
` });
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
`{chain_dir}` remains available inside scripted workflow step templates for legacy-compatible path templates. It expands to the workflow cwd, not to private temporary storage.
|
|
171
|
+
|
|
172
|
+
### Migrating old chain shapes
|
|
173
|
+
|
|
174
|
+
Legacy top-level `chain`, `tasks`, `parallel`, `chainDir`, `/chain`, `/parallel`, `/run-chain`, and durable `.chain.md` execution are no longer the public workflow API. Rewrite them as JavaScript:
|
|
175
|
+
|
|
176
|
+
```js
|
|
177
|
+
// Old shape, no longer supported:
|
|
178
|
+
// { chain: [{ agent: "scout", task: "Scan" }, { agent: "worker", task: "Fix from {previous}" }] }
|
|
179
|
+
|
|
180
|
+
// Current shape:
|
|
181
|
+
{ workflowScript: `
|
|
182
|
+
const scan = await runs.run("scan", { agent: "scout", task: "Scan" });
|
|
183
|
+
return runs.run("fix", { agent: "worker", task: "Fix from: " + scan.output });
|
|
184
|
+
` }
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
```js
|
|
188
|
+
// Old shape, no longer supported:
|
|
189
|
+
// { tasks: [{ agent: "reviewer", task: "Review API" }, { agent: "reviewer", task: "Review UI" }] }
|
|
190
|
+
|
|
191
|
+
// Current shape:
|
|
192
|
+
{ workflowScript: `
|
|
193
|
+
return runs.all([
|
|
194
|
+
{ key: "api", agent: "reviewer", task: "Review API" },
|
|
195
|
+
{ key: "ui", agent: "reviewer", task: "Review UI" }
|
|
196
|
+
]);
|
|
197
|
+
` }
|
|
198
|
+
```
|
|
199
|
+
|
|
51
200
|
For long task text with Markdown fences or shell blocks, use quoted lines instead of a raw template literal:
|
|
52
201
|
|
|
53
202
|
````js
|
|
@@ -62,7 +211,26 @@ return runs.run("test", { agent: "worker", task });
|
|
|
62
211
|
|
|
63
212
|
A plain workflow creates one enclosing mission by default. Its children do not create separate missions. The result exposes the id as `details.missionId`, and human-readable output ends with `Mission: <id> (<status>)`. Pass `mission:false` for an ephemeral workflow with no mission or durable `state` global.
|
|
64
213
|
|
|
65
|
-
|
|
214
|
+
### Repeatable workflows
|
|
215
|
+
|
|
216
|
+
Use stable child keys and keep process logic in ordinary JavaScript. `runs.run` launches one child, `runs.all` launches independent children together, and later steps can use each completed child's `output`. Put long task text in arrays joined with `"\n"` so Markdown fences do not conflict with the script string.
|
|
217
|
+
|
|
218
|
+
For a process you run often, save the task as a prompt template under `.pi/prompts/` or `~/.pi/agent/prompts/` and launch it with `/prompt-workflow`. The adapter compiles prompt steps into `workflowScript`, so templates describe the work instead of embedding raw `subagent` tool-call JSON. You can ask the parent agent to create or update these prompt files from a process described in natural language.
|
|
219
|
+
|
|
220
|
+
```md
|
|
221
|
+
---
|
|
222
|
+
description: Review a release candidate
|
|
223
|
+
subagent: reviewer
|
|
224
|
+
fresh: true
|
|
225
|
+
---
|
|
226
|
+
Review $@. Return concrete findings with source proof, or state that no issue was found.
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
```text
|
|
230
|
+
/prompt-workflow review-release-candidate v0.51.0
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
For watched same-repo workflows, pass `async:false` only when the parent must block until completion. That blocking mode also shows the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Blocking workflows default to a 30-minute timeout; async workflows have no default timeout. See the [tool reference](tool-reference.md) for the full parameter list.
|
|
66
234
|
|
|
67
235
|
The legacy `/chain`, `/parallel`, and `/run-chain` commands are not registered.
|
|
68
236
|
|
|
@@ -114,6 +282,8 @@ The parent replies with `subagent_supervisor({ action: "reply", replyTo, message
|
|
|
114
282
|
|
|
115
283
|
Child-side routine completion handoffs are not expected. If a child appears stalled, needs-attention notices show up in the parent session with useful next actions, such as checking `subagent({ action: "status" })`, interrupting the run, or nudging the child.
|
|
116
284
|
|
|
285
|
+
If a `workflowScript` child detaches through `contact_supervisor`, the enclosing async workflow stays `paused` until that child exits. Then the extension reconciles it to `complete` or `failed`. Wait on the child until that happens.
|
|
286
|
+
|
|
117
287
|
If messages do not show up, run `/subagents-doctor`. Advanced users can tune the bridge with `intercomBridge` in [configuration.md](configuration.md).
|
|
118
288
|
|
|
119
289
|
## Recursion guard
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.6.0",
|
|
4
4
|
"description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -8,7 +8,9 @@
|
|
|
8
8
|
"exports": {
|
|
9
9
|
".": "./index.ts",
|
|
10
10
|
"./background-work": "./src/api/background-work.ts",
|
|
11
|
+
"./external-job-provider": "./src/api/external-job-provider.ts",
|
|
11
12
|
"./external-runs": "./src/api/external-runs.ts",
|
|
13
|
+
"./agents": "./src/api/agents.ts",
|
|
12
14
|
"./delegation": "./src/api/delegation.ts",
|
|
13
15
|
"./capability-ceiling": "./src/api/capability-ceiling.ts",
|
|
14
16
|
"./preflight": "./src/api/preflight.ts",
|
|
@@ -50,14 +52,6 @@
|
|
|
50
52
|
"README.md",
|
|
51
53
|
"CHANGELOG.md"
|
|
52
54
|
],
|
|
53
|
-
"scripts": {
|
|
54
|
-
"typecheck": "tsc --noEmit",
|
|
55
|
-
"test": "npm run test:unit",
|
|
56
|
-
"test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
|
|
57
|
-
"test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
|
|
58
|
-
"test:e2e": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/e2e/*.test.ts",
|
|
59
|
-
"test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
|
|
60
|
-
},
|
|
61
55
|
"pi": {
|
|
62
56
|
"extensions": [
|
|
63
57
|
"./index.ts"
|
|
@@ -90,6 +84,7 @@
|
|
|
90
84
|
}
|
|
91
85
|
},
|
|
92
86
|
"dependencies": {
|
|
87
|
+
"acorn": "8.18.0",
|
|
93
88
|
"jiti": "2.7.0",
|
|
94
89
|
"typebox": "1.1.38",
|
|
95
90
|
"yaml": "2.8.3"
|
|
@@ -104,5 +99,13 @@
|
|
|
104
99
|
},
|
|
105
100
|
"publishConfig": {
|
|
106
101
|
"access": "public"
|
|
102
|
+
},
|
|
103
|
+
"scripts": {
|
|
104
|
+
"typecheck": "tsc --noEmit",
|
|
105
|
+
"test": "npm run test:unit",
|
|
106
|
+
"test:unit": "node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
|
|
107
|
+
"test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
|
|
108
|
+
"test:e2e": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/e2e/*.test.ts",
|
|
109
|
+
"test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
|
|
107
110
|
}
|
|
108
|
-
}
|
|
111
|
+
}
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Run a bounded supervisor-mediated council of advisors and write a decision memo
|
|
3
|
+
argument-hint: "<question> [--advisors name:role,name:role] [--max-passes 2|3] [--scope ...] [--non-goals ...]"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Run a bounded, supervisor-mediated council on this question. You, the parent
|
|
7
|
+
session, are the supervisor. You select the roster, curate cross-advisor packets,
|
|
8
|
+
decide which feedback is valid, and write the final memo. Advisors do not talk
|
|
9
|
+
directly or see peer transcripts by default. This is not free-form agent chat.
|
|
10
|
+
|
|
11
|
+
Before you orchestrate, read `skills/council-mode/SKILL.md` and
|
|
12
|
+
`skills/pi-subagents/references/execution-controls.md`.
|
|
13
|
+
|
|
14
|
+
Parse the invocation yourself. The flags below are conventions, not runtime
|
|
15
|
+
options. Record a brief with the question, scope, non-goals, evidence targets,
|
|
16
|
+
roster, roles, and pass cap. Default `--max-passes` to 2. Clamp it to 2 or 3. If
|
|
17
|
+
the question is trivial or settled, answer directly instead of convening a council.
|
|
18
|
+
|
|
19
|
+
## Roster
|
|
20
|
+
|
|
21
|
+
- If `--advisors` is given, use exactly those `name:role` pairs. Fail clearly on an
|
|
22
|
+
unknown agent.
|
|
23
|
+
- Otherwise list agents with `subagent({ action: "list" })`, then prefer 2–3
|
|
24
|
+
executable names that start with `council-`.
|
|
25
|
+
- If fewer than two profiles are available, fill the roster with `oracle`, then
|
|
26
|
+
`reviewer`, until it has two advisors. Launch fallback `oracle` with
|
|
27
|
+
`context: "fork"` so global defaults cannot remove its parent-chat context.
|
|
28
|
+
Let `reviewer` use its normal profile context. Note the fallback and known
|
|
29
|
+
context modes in the memo.
|
|
30
|
+
- Use the normal single-oracle loop only when a requested roster or unavailable
|
|
31
|
+
builtins leaves fewer than two advisors. Label the memo as degraded mode.
|
|
32
|
+
|
|
33
|
+
Roles belong to this request, not to the profiles. Keep the roster at 2–3 and never
|
|
34
|
+
exceed 4.
|
|
35
|
+
|
|
36
|
+
## Run the protocol
|
|
37
|
+
|
|
38
|
+
Use the canonical workflow, structured advisor contracts, aggregate pass receipts,
|
|
39
|
+
and memo requirements in `skills/council-mode/SKILL.md`. Keep the parent as the
|
|
40
|
+
only synthesizer and decision maker. Do not introduce a chair advisor, peer chat,
|
|
41
|
+
or transcript sharing.
|
|
42
|
+
|
|
43
|
+
Use its required boundary checkpoints, yield for each async workflow without
|
|
44
|
+
polling, and write its required final memo.
|
|
45
|
+
|
|
46
|
+
Question and options from the slash command invocation:
|
|
47
|
+
|
|
48
|
+
$@
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: council-mode
|
|
3
|
+
description: Run a bounded supervisor-mediated advisor council. Use when the user asks to convene advisors, debate a decision, cross-examine recommendations, or run /council.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Council Mode
|
|
7
|
+
|
|
8
|
+
This skill is for the parent supervisor only. Do not inject it into advisors. The
|
|
9
|
+
parent selects the roster, curates all cross-advisor communication, decides which
|
|
10
|
+
feedback is valid, and writes the decision memo. Advisors do not talk directly or
|
|
11
|
+
see peer transcripts by default. This is not free-form agent chat.
|
|
12
|
+
|
|
13
|
+
Use council mode for a material decision with real tradeoffs. Do not use it for a
|
|
14
|
+
trivial or settled question, or for implementation work. Read
|
|
15
|
+
`skills/pi-subagents/references/execution-controls.md` before you launch advisors.
|
|
16
|
+
|
|
17
|
+
## Roster and limits
|
|
18
|
+
|
|
19
|
+
Roles such as architect, skeptic, operator, and performance reviewer belong to the
|
|
20
|
+
`/council` request. A `council-*` profile defines only model, tools, context, and
|
|
21
|
+
output defaults. Its profile configuration or explicit invocation owns its context
|
|
22
|
+
choice.
|
|
23
|
+
|
|
24
|
+
Create model-based profiles in your user or project agent directory. Do not add
|
|
25
|
+
them to this package. This is a valid example; roles still come from `/council`:
|
|
26
|
+
|
|
27
|
+
```markdown
|
|
28
|
+
---
|
|
29
|
+
name: council-sol
|
|
30
|
+
description: Read-only fresh-context advisor for bounded council decisions
|
|
31
|
+
tools: read, grep, find, ls
|
|
32
|
+
model: openai-codex/gpt-5.6-sol
|
|
33
|
+
thinking: high
|
|
34
|
+
systemPromptMode: replace
|
|
35
|
+
inheritProjectContext: true
|
|
36
|
+
inheritSkills: false
|
|
37
|
+
defaultContext: fresh
|
|
38
|
+
acceptanceRole: read-only
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
Analyze only the assigned council role. Inspect evidence directly. Do not edit,
|
|
42
|
+
run mutating commands, commit, push, contact peers, or spawn subagents. Return
|
|
43
|
+
concise, cited advice using the report contract in the council task.
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
After `subagent({ action: "list" })`, prefer 2–3 executable names that start with
|
|
47
|
+
`council-`. The prefix is a naming convention, not runtime selection. If fewer
|
|
48
|
+
than two profiles are available, fill the roster with `oracle`, then `reviewer`,
|
|
49
|
+
until it has two advisors. Launch fallback `oracle` with `context: "fork"` so
|
|
50
|
+
global defaults cannot remove its parent-chat context. Let fallback `reviewer`
|
|
51
|
+
use its normal profile context. Note the fallback and known context modes in the
|
|
52
|
+
memo. Use the normal single-oracle consultation loop only when a requested roster
|
|
53
|
+
or unavailable builtins leaves fewer than two advisors.
|
|
54
|
+
Label that result as degraded mode. Never use more than four advisors.
|
|
55
|
+
|
|
56
|
+
Pass 1 is independent reports. Pass 2 is one cross-exam. The default pass cap is
|
|
57
|
+
2. Run pass 3 only when `--max-passes 3` was requested and a material dispute can
|
|
58
|
+
be settled by evidence an advisor can produce. Never run an unbounded loop.
|
|
59
|
+
|
|
60
|
+
## Protocol
|
|
61
|
+
|
|
62
|
+
1. The parent writes a brief with the question, scope, non-goals, evidence targets,
|
|
63
|
+
roster, roles, and pass cap.
|
|
64
|
+
2. Before Pass 1, tell the user the roster, roles, requested or known context
|
|
65
|
+
modes, and pass cap. Use a stable key, `phase`, and concise `label` for every
|
|
66
|
+
workflow child. For example, use `advisor-oracle`, `phase: "Council pass 1"`,
|
|
67
|
+
and `label: "Oracle — intent and consistency"`.
|
|
68
|
+
3. Launch one async `workflowScript` with `runs.all` for independent advisor
|
|
69
|
+
reports. Set `context` when the selected advisor has a known profile context or
|
|
70
|
+
a fallback rule requests one, because a global default can otherwise override
|
|
71
|
+
that profile. Set `context: "fork"` for fallback `oracle`. If no advisor context
|
|
72
|
+
is known, omit `context` and disclose the unknown runtime default in the memo.
|
|
73
|
+
Each advisor is read-only and must not spawn children, edit files, run mutating
|
|
74
|
+
commands, commit, or push. Set `output: false` unless separate advisor artifacts
|
|
75
|
+
are explicitly requested or useful for the decision.
|
|
76
|
+
4. Return one aggregate Pass 1 receipt. After it completes, tell the user the
|
|
77
|
+
completion count, agreement count, dispute count, and whether Pass 2 is needed.
|
|
78
|
+
5. The parent synthesizes a claim matrix in session. It contains agreements,
|
|
79
|
+
disputed claims, missing proof, owner decisions, and a relay set of at most five
|
|
80
|
+
high-impact claims per advisor. Do not delegate this synthesis.
|
|
81
|
+
6. Before Pass 2, tell the user how many claims are relayed and why each is
|
|
82
|
+
material. Launch a second async `workflowScript` with `runs.all` resume calls.
|
|
83
|
+
Each task is a curated challenge packet, not a peer transcript. A resume requires
|
|
84
|
+
a retained run id and a non-empty task. It excludes `agent` and rejects `gate`.
|
|
85
|
+
Record the new run id from every resume. Pass 3 resumes those latest ids. Return
|
|
86
|
+
one aggregate Pass 2 receipt.
|
|
87
|
+
7. After Pass 2, tell the user whether the council converged or which owner
|
|
88
|
+
decisions remain. The parent writes the final memo. Do not delegate it.
|
|
89
|
+
|
|
90
|
+
If an advisor is not resumable, run the same profile in fresh context with its own
|
|
91
|
+
pass-1 report and the challenge packet. Label that response as a fresh-context
|
|
92
|
+
fallback, not a true cross-exam.
|
|
93
|
+
|
|
94
|
+
Do not set `clarify`, `worktree`, `gate`, turn budgets, tool budgets, or tight usage
|
|
95
|
+
budgets on advisors. Bound work through the roster, pass cap, and report length.
|
|
96
|
+
|
|
97
|
+
## Advisor contracts and pass receipts
|
|
98
|
+
|
|
99
|
+
Pass-1 reports are at most about 600 words. Give each advisor the same
|
|
100
|
+
`outputSchema`, so reports are comparable without heading cleanup. The following
|
|
101
|
+
shape is a contract template. Use the runtime schema syntax supported by the
|
|
102
|
+
workflow and keep narrative fields as strings:
|
|
103
|
+
|
|
104
|
+
```js
|
|
105
|
+
const pass1OutputSchema = {
|
|
106
|
+
type: "object",
|
|
107
|
+
required: [
|
|
108
|
+
"recommendation", "evidence", "assumptions", "risks", "confidence",
|
|
109
|
+
"challengeClaims", "ownerDecisions", "changeMyMind"
|
|
110
|
+
],
|
|
111
|
+
properties: {
|
|
112
|
+
recommendation: { type: "string" },
|
|
113
|
+
evidence: {
|
|
114
|
+
type: "array",
|
|
115
|
+
items: {
|
|
116
|
+
type: "object",
|
|
117
|
+
required: ["claim", "sources"],
|
|
118
|
+
properties: {
|
|
119
|
+
claim: { type: "string" },
|
|
120
|
+
sources: { type: "array", items: { type: "string" } }
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
},
|
|
124
|
+
assumptions: {
|
|
125
|
+
type: "array",
|
|
126
|
+
items: {
|
|
127
|
+
type: "object",
|
|
128
|
+
required: ["assumption", "status"],
|
|
129
|
+
properties: {
|
|
130
|
+
assumption: { type: "string" },
|
|
131
|
+
status: { enum: ["verified", "unverified"] }
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
},
|
|
135
|
+
risks: { type: "array", items: { type: "string" } },
|
|
136
|
+
confidence: {
|
|
137
|
+
type: "object",
|
|
138
|
+
required: ["level", "reason"],
|
|
139
|
+
properties: {
|
|
140
|
+
level: { enum: ["high", "medium", "low"] },
|
|
141
|
+
reason: { type: "string" }
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
challengeClaims: { type: "array", items: { type: "string" }, maxItems: 3 },
|
|
145
|
+
ownerDecisions: { type: "array", items: { type: "string" } },
|
|
146
|
+
changeMyMind: { type: "array", items: { type: "string" } }
|
|
147
|
+
}
|
|
148
|
+
};
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
Include this contract in each Pass 1 task: inspect supplied evidence directly; do
|
|
152
|
+
not see or ask about other advisors; stay read-only; do not spawn children; return
|
|
153
|
+
only the structured report.
|
|
154
|
+
|
|
155
|
+
After `runs.all`, return one aggregate receipt rather than making the parent find
|
|
156
|
+
separate artifacts. Preserve the result order or map it by stable key so each row
|
|
157
|
+
contains the advisor identity and report:
|
|
158
|
+
|
|
159
|
+
```js
|
|
160
|
+
return {
|
|
161
|
+
pass: 1,
|
|
162
|
+
advisors: results.map((result, index) => ({
|
|
163
|
+
key: result.key,
|
|
164
|
+
agent: result.agent,
|
|
165
|
+
role: roster[index].role,
|
|
166
|
+
requestedContext: roster[index].context ?? "runtime-default-unknown",
|
|
167
|
+
runId: result.runId,
|
|
168
|
+
report: result.structuredOutput
|
|
169
|
+
}))
|
|
170
|
+
};
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Do not replace `runtime-default-unknown` with a guessed context. It records that
|
|
174
|
+
the launch intentionally omitted context.
|
|
175
|
+
|
|
176
|
+
A challenge packet contains only disputed claims, strong conflicting evidence,
|
|
177
|
+
missing proof, owner decisions, and high-impact risks. Attribute peer content as
|
|
178
|
+
"another advisor". Do not include full peer reports. Use a common Pass 2 contract:
|
|
179
|
+
|
|
180
|
+
```js
|
|
181
|
+
const pass2OutputSchema = {
|
|
182
|
+
type: "object",
|
|
183
|
+
required: ["responses", "recommendationChanged", "outOfScopeFindings"],
|
|
184
|
+
properties: {
|
|
185
|
+
responses: {
|
|
186
|
+
type: "array",
|
|
187
|
+
items: {
|
|
188
|
+
type: "object",
|
|
189
|
+
required: ["claimId", "disposition", "reason", "sources"],
|
|
190
|
+
properties: {
|
|
191
|
+
claimId: { type: "string" },
|
|
192
|
+
disposition: {
|
|
193
|
+
enum: ["accept", "reject", "refine", "owner-decision"]
|
|
194
|
+
},
|
|
195
|
+
reason: { type: "string" },
|
|
196
|
+
sources: { type: "array", items: { type: "string" } }
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
},
|
|
200
|
+
recommendationChanged: {
|
|
201
|
+
type: "object",
|
|
202
|
+
required: ["changed", "reason"],
|
|
203
|
+
properties: { changed: { type: "boolean" }, reason: { type: "string" } }
|
|
204
|
+
},
|
|
205
|
+
outOfScopeFindings: { type: "array", items: { type: "string" } }
|
|
206
|
+
}
|
|
207
|
+
};
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
Use stable resume keys such as `cross-oracle`, `phase: "Council pass 2"`, concise
|
|
211
|
+
labels, and `output: false` unless separate artifacts are requested or useful. The
|
|
212
|
+
aggregate Pass 2 receipt uses the same row shape as Pass 1, with the new `runId`
|
|
213
|
+
and `structuredOutput`.
|
|
214
|
+
|
|
215
|
+
## Stop and memo
|
|
216
|
+
|
|
217
|
+
Converged means no disputed claim remains that both materially affects the
|
|
218
|
+
recommendation and can plausibly be settled by evidence. Stop at convergence, the
|
|
219
|
+
pass cap, failed fallback, or user interruption. Put unresolved disputes in owner
|
|
220
|
+
decisions. Never add a round for polish or symmetry.
|
|
221
|
+
|
|
222
|
+
The parent memo states the question and scope, recommendation, rationale, accepted
|
|
223
|
+
and rejected feedback with reasons, owner decisions, evidence and run ids,
|
|
224
|
+
confidence, what would change the decision, and the roster, roles, passes,
|
|
225
|
+
fallbacks, and known advisor context modes. State that fallback `oracle` is
|
|
226
|
+
context-aware and forked.
|
|
227
|
+
|
|
228
|
+
Council mode is not agent-to-agent chat, a transcript dump, mutation authority,
|
|
229
|
+
auto-escalation to writer lanes, or a council UI. Escalate to a writer only after
|
|
230
|
+
the parent memo and only when the user explicitly requests it.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
name: pi-subagents
|
|
3
3
|
description: |
|
|
4
4
|
Delegate work to builtin or custom subagents with single-agent, parallel,
|
|
5
|
-
scripted
|
|
5
|
+
scripted-chaining, async, forked-context, and coordinated workflows. Use
|
|
6
6
|
for advisory review, implementation handoffs, and multi-step tasks where a
|
|
7
7
|
single agent should stay in control while other agents contribute context,
|
|
8
8
|
planning, or execution.
|
|
@@ -12,7 +12,7 @@ description: |
|
|
|
12
12
|
|
|
13
13
|
This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
|
|
14
14
|
|
|
15
|
-
Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `workflowScript` for all execution, including one isolated child.
|
|
15
|
+
Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `workflowScript` for all execution, including one isolated child. Chaining is still supported, but it is code-driven: use `await runs.run(...)` for sequential steps, `runs.all([...])` for parallel fanout, and ordinary JavaScript for branching, retries, gate monitors, and aggregation. Keep workflow helpers portable: use plain helper functions or explicit Promise chains, not nested `async function` helpers, async arrows, or async methods. Do not use legacy top-level `chain` / `tasks` inputs or durable `.chain.md` execution. Scripted workflows normally start asynchronously unless config sets `asyncByDefault:false`; set `async:true` explicitly when async behavior matters. Pass `async:false` only when the parent must block until completion. Async mode still shows progress. Do not use `async:false` for final reviews, backlog gates, run-to-completion convenience, or because no other work is available.
|
|
16
16
|
|
|
17
17
|
## How to use this router
|
|
18
18
|
|
|
@@ -22,7 +22,8 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
|
|
|
22
22
|
| --- | --- |
|
|
23
23
|
| Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
|
|
24
24
|
| Run one-child, scripted, async, scheduled, mission-backed, forked, watchdog, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
|
|
25
|
-
|
|
|
25
|
+
| Coordinate several independent tasks, worktrees, repositories, or writer lanes | `references/multi-lane-orchestration.md` |
|
|
26
|
+
| List/create/update/delete/eject/disable agents, inspect legacy chain records, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
|
|
26
27
|
| Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
|
|
27
28
|
|
|
28
29
|
For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
|
|
@@ -30,11 +31,14 @@ For broad or uncertain requests, read more than one reference. For complex work,
|
|
|
30
31
|
## Always-on constraints
|
|
31
32
|
|
|
32
33
|
- Keep the parent as orchestrator and final decision-maker.
|
|
34
|
+
- Before multiple mutation-capable lanes, record a lane board and each lane's isolation path.
|
|
35
|
+
- For plan, design, or architecture advice that asks to consult, discuss with, or come to agreement with `oracle`, use a short same-session consultation loop: read the first result, resume once with a targeted challenge when material tradeoffs remain, then synthesize the parent decision. Keep explicit one-shot, trivial, and fully settled consultations one-shot.
|
|
33
36
|
- Use one writer per cwd/worktree unless isolated worktrees are intentional.
|
|
34
37
|
- For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.
|
|
35
38
|
- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` with stable keys and aggregate output unless there is truly only one child.
|
|
36
39
|
- Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
|
|
37
|
-
- Use async/background by default when
|
|
40
|
+
- Use async/background by default. Final reviews, gate checks, oracle checks, and backlog lanes stay async. Use `async:false` only when the parent must block until completion. Do not poll just to wait. For adaptive gates, branch in `workflowScript`.
|
|
41
|
+
- For Pi extension repos whose canonical checkout is under `~/.pi/agent/extensions`, never create lane worktrees as sibling directories there. Pi auto-loads `~/.pi/agent/extensions/*/index.ts`, so sibling worktrees can register duplicate tools. Put lanes under `~/.pi/agent/worktrees`, another worktree base outside auto-discovery, or a temporary clone. If a lane must run the modified extension itself, use an isolated Pi config home with `PI_CODING_AGENT_DIR=<lane-config> pi --no-extensions -e <lane>/index.ts`. Use full containers only when path and config isolation are insufficient.
|
|
38
42
|
- Preserve capability ceilings, including child tool restrictions and session-scoped allowed-agent restrictions.
|
|
39
43
|
- Escalate unresolved product, architecture, authority, release, merge, or safety decisions upward instead of letting a child decide silently.
|
|
40
44
|
- Treat receipts, CI, review bots, and external-run records as evidence, not authority to merge, close, comment, publish, or release.
|
|
@@ -4,10 +4,12 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
|
|
|
4
4
|
|
|
5
5
|
## Important Constraints
|
|
6
6
|
|
|
7
|
-
- **
|
|
8
|
-
have a persisted session file
|
|
9
|
-
|
|
10
|
-
when
|
|
7
|
+
- **Explicit forking requires a persisted parent session.** If the current session
|
|
8
|
+
does not have a persisted session file or current leaf, explicit `context: "fork"`
|
|
9
|
+
fails. An agent-level `defaultContext: fork` is a preference: packaged `worker`,
|
|
10
|
+
`oracle`, and `advisor` fall back to `fresh` when those fork preconditions are not
|
|
11
|
+
met yet. Use `context: "fresh"` when you do not want a fork even after the parent
|
|
12
|
+
session exists.
|
|
11
13
|
- **Forked runs inherit parent history.** They are branched threads, not fresh
|
|
12
14
|
filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
|
|
13
15
|
- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
|
|
@@ -34,6 +36,7 @@ In an interactive chat, do not call `subagent_wait()` merely to wait after launc
|
|
|
34
36
|
- `subagent_wait()` — return when the next initially active async run or registered provider item finishes, or a subagent needs attention.
|
|
35
37
|
- `subagent_wait({ all: true })` — block until every async run and provider item active at call time finishes, or a subagent needs attention.
|
|
36
38
|
- `subagent_wait({ id: "..." })` — block on one async or remembered detached foreground run (id or prefix). Provider items are not selected through this parameter.
|
|
39
|
+
- `subagent_wait({ stopOnAttention: false })` — for blocking waits only, keep waiting through idle or long-thinking attention; supervisor/contact requests still stop the wait.
|
|
37
40
|
- `subagent_wait({ timeoutMs })` — cap the block; active work keeps running if it elapses.
|
|
38
41
|
|
|
39
42
|
Providers are discovered through the `@xzzpig/pi-subagents/background-work` registry and must return stable item IDs with exact owning session IDs. Child agents receive no provider automatically: keep `subagent_wait` in the child `tools` allowlist and load provider extensions through `extensions` or `subagentOnlyExtensions`.
|
|
@@ -63,6 +66,10 @@ Give subagents specific tasks rather than vague mandates.
|
|
|
63
66
|
|
|
64
67
|
If a subagent encounters an unapproved product, architecture, scope, merge, release, credential, or authority choice, it should use `contact_supervisor` and wait for the reply instead of deciding alone. Generic `intercom` is external or provider-supplied only. Use it only when external bridge instructions provide an explicit safe target. External checks, receipts, and review bots provide evidence only; they do not grant authority.
|
|
65
68
|
|
|
69
|
+
### Use a short oracle consultation for material advice
|
|
70
|
+
|
|
71
|
+
When a user asks to ask, consult, discuss with, or come to agreement with `oracle` about a plan, design, or architecture decision, do not treat the first advisory report as final when it raises a material challenge or tradeoff. Read it, resume the same oracle session once with a targeted question, then make the parent decision. An explicit one-shot request, a trivial question, or a fully settled first answer does not need a follow-up.
|
|
72
|
+
|
|
66
73
|
### Intervene only on clear control signals
|
|
67
74
|
|
|
68
75
|
Use subagent control proactively when a delegated run emits `needs_attention`, or when a human asks you to regain control. Do not interrupt just because a child has briefly produced no output. Silence can be normal during long tool calls, test runs, or model reasoning.
|
|
@@ -77,8 +84,8 @@ Use `/name` so intercom targeting stays stable.
|
|
|
77
84
|
|
|
78
85
|
```js
|
|
79
86
|
subagent({ workflowScript: `
|
|
80
|
-
const context = await runs.run("recon", { agent: "scout", task: "
|
|
81
|
-
return (await runs.run("implement", { agent: "worker", task: "Implement from: " + context.output })).output;
|
|
87
|
+
const context = await runs.run("recon", { agent: "scout", task: "Start from the named source roots, paths, and symbols. Identify the implementation seam before broad search." });
|
|
88
|
+
return (await runs.run("implement", { agent: "worker", task: "Read the scout output, plan paths, and named files/seams first. Implement from: " + context.output })).output;
|
|
82
89
|
` })
|
|
83
90
|
```
|
|
84
91
|
|