@xzzpig/pi-subagents 0.4.2 → 0.5.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 +168 -0
- package/README.md +4 -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 +40 -2
- package/docs/configuration.md +41 -13
- 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 +2 -0
- package/src/agents/agents.ts +186 -44
- package/src/agents/builtin-names.ts +9 -0
- package/src/agents/runtime-agent-registry.ts +418 -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/doctor.ts +4 -6
- package/src/extension/fanout-child.ts +2 -2
- package/src/extension/index.ts +183 -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 +106 -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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.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
|
|
|
@@ -26,6 +26,14 @@ An agent may set `runner.type: external-cli` with a non-empty `command`, optiona
|
|
|
26
26
|
|
|
27
27
|
External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support foreground/clarify, steer/resume/interrupt-as-pause, Pi models/tools/extensions/skills, tool or turn budgets, structured output, nested subagents, fallbacks, or sessions.
|
|
28
28
|
|
|
29
|
+
### External job profiles
|
|
30
|
+
|
|
31
|
+
An agent may set `runner.type: external-job` with a non-empty `provider` and optional JSON `options`. When `surf-cli` is installed and loaded, Surf can optionally expose a `gpt-pro` package agent through provider `surf-oracle`. Surf maps `model: pro` to ChatGPT GPT-5.6 Sol Pro web mode. pi-subagents does not own that package agent or model mapping. Remove any old `agentOverrides.gpt-pro.disabled` workaround before using Surf's package agent. The provider must be registered in the host Pi process through `pi-subagents/external-job-provider`; the async runner talks to that parent-owned registry through a local operation bridge.
|
|
32
|
+
|
|
33
|
+
External job profiles are async-only. The provider owns the remote job and Pi owns the async run record. Status persists provider name, provider job id, prompt digest, provider options, handle/conversation URLs when supplied, result artifact path, last known state, and provider failure code/message. Recovery uses existing provider job metadata to call `reattach` and `result`; it refuses to redispatch a prompt when the persisted provider job does not match the prompt digest.
|
|
34
|
+
|
|
35
|
+
External job profiles do not support foreground/clarify, steer/resume, Pi models/tools/extensions/skills, tool or turn budgets, structured output, native child permissions, fallbacks, or Pi child sessions. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
|
|
36
|
+
|
|
29
37
|
### Single agent
|
|
30
38
|
|
|
31
39
|
```typescript
|
|
@@ -53,7 +61,7 @@ its resolved launch context as `[fresh]` or `[fork]`. Aggregate headers show
|
|
|
53
61
|
|
|
54
62
|
### Scripted workflows
|
|
55
63
|
|
|
56
|
-
`workflowScript` is the sole public execution surface. Use `runs.run(key, { agent, task, ... })` for one child, `runs.all([...])` for parallel children, and ordinary JavaScript for sequence, branching, filtering, retries, and aggregation. Scripts are ordinary JavaScript statement bodies, so use an explicit return such as `workflowScript: "return runs.run('main', { agent: 'worker', task: '...' })"` for a useful one-child result. Prefer a single scripted workflow whenever the parent is starting a coordinated wave, such as multiple reviews, review plus gate monitor, worker then monitor setup, cross-repo prep lanes, or a fanout that the parent will consume together.
|
|
64
|
+
`workflowScript` is the sole public execution surface. Use `runs.run(key, { agent, task, ... })` for one child, `runs.all([...])` for parallel children, and ordinary JavaScript for sequence, branching, filtering, retries, and aggregation. Scripts are ordinary JavaScript statement bodies, so use an explicit return such as `workflowScript: "return runs.run('main', { agent: 'worker', task: '...' })"` for a useful one-child result. Use top-level `await`, plain helper functions, or explicit Promise chains; nested `async function` helpers, async arrows, and async methods are rejected. Prefer a single scripted workflow whenever the parent is starting a coordinated wave, such as multiple reviews, review plus gate monitor, worker then monitor setup, cross-repo prep lanes, or a fanout that the parent will consume together.
|
|
57
65
|
|
|
58
66
|
```js
|
|
59
67
|
subagent({
|
|
@@ -68,21 +76,34 @@ subagent({
|
|
|
68
76
|
})
|
|
69
77
|
```
|
|
70
78
|
|
|
71
|
-
Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `
|
|
79
|
+
Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `emit`, captured `console`, and standard JavaScript. Pass explicit task text to `runs.run`. Mission-attached workflows also get `await state.get(key)` and `await state.set(key, value)` for durable JSON state shared across workflows on the same mission; `mission: false` workflows have no `state` global. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports.
|
|
72
80
|
|
|
73
81
|
For one host-run verification command, pass `gate: "npm test"` on a `runs.run`/`runs.all` item (or at the top level as a workflow default). It is shorthand for verified acceptance with that single command: the runtime executes it on the host, records the result as evidence, and memoizes it per tracked workspace state and effective environment. `gate` cannot be combined with `acceptance`; use explicit `acceptance.verify` for multiple commands or custom criteria.
|
|
74
82
|
|
|
75
|
-
Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. Resume only rows reported `resumable`. For a retained-child challenge, use `resume` instead of `steer` when the child is complete. If no retained child is resumable, launch a same-role fallback challenge and label it as fallback. A later workflow continues a resumable child with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached.
|
|
83
|
+
Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. Resume only rows reported `resumable`. For a retained-child challenge, use `resume` instead of `steer` when the child is complete. If no retained child is resumable, launch a same-role fallback challenge and label it as fallback. A later workflow continues a resumable child with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside `workflowScript`, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. Pass explicit follow-up task text. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
|
|
84
|
+
|
|
85
|
+
Terminal async workflows also persist `workflow-receipt.json` beside `status.json`. It maps each stable child key to its agent, requested and resolved context when known, latest run id, resumability, output reference, and continuation lineage. A later workflow can resume the latest retained child without copying its run id:
|
|
86
|
+
|
|
87
|
+
```js
|
|
88
|
+
return runs.run("cross-oracle", {
|
|
89
|
+
resume: { workflowRunId: "<pass-1-workflow-id>", key: "advisor-oracle", latest: true },
|
|
90
|
+
task: "Review the focused challenge packet."
|
|
91
|
+
});
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
Keyed resume reads that one exact receipt and revalidates the retained run at launch. It fails when the workflow or key is missing, the receipt is stale, `latest` is not `true`, or the recorded child is no longer resumable. Foreground workflow results expose the same receipt in `details.workflow.receipt`, but cross-workflow keyed lookup requires the durable receipt from an async workflow.
|
|
76
95
|
|
|
77
96
|
### Async/background
|
|
78
97
|
|
|
79
|
-
Prefer async mode for every subagent launch. Set `async: true` no matter the task unless
|
|
98
|
+
Prefer async mode for every subagent launch. Set `async: true` no matter the task unless the parent must block until completion. This applies to scouts, researchers, workers, reviewers, validators, oracle checks, one-off delegates, final review gates, backlog gates, and scripted workflows. Keep the write path single-threaded even when the run is async.
|
|
99
|
+
|
|
100
|
+
Use `async:false` only when the parent must block until completion. Async mode still shows progress. Do not use `async:false` because a task is short, because it is the last gate, because no other work is ready, because the user asked to finish the overall job, or because blocking is convenient.
|
|
80
101
|
|
|
81
102
|
Async does not mean parallel writes. Do not edit the same active worktree while an async worker is changing it. Parent-side overlap should be reading, validation prep, synthesis, command planning, or review of unaffected context unless the writer is isolated in a separate worktree.
|
|
82
103
|
|
|
83
|
-
Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed.
|
|
104
|
+
Do not end your turn immediately after launching an async child if you promised to keep working. Continue the local inspection, synthesis, or validation prep, then check the async run when its result is needed. If no safe independent work remains, return control and let Pi wake the session; do not convert the child to foreground.
|
|
84
105
|
|
|
85
|
-
In an interactive chat, normally return control when ready to yield and let Pi wake the session on completion; do not call `subagent_wait()` merely to wait.
|
|
106
|
+
In an interactive chat, normally return control when ready to yield and let Pi wake the session on completion; do not call `subagent_wait()` merely to wait. A run-to-completion user request is not by itself a reason to use foreground children. Override the normal yield-and-wake flow only when this exact turn cannot safely end without the result, such as a headless provider flow or a skill contract that must produce a same-turn artifact. Use `subagent_wait()`, not `async:false`, for that current-turn dependency. Never substitute sleep or status-polling loops.
|
|
86
107
|
|
|
87
108
|
`subagent_wait()` returns when the next initially active async run or registered provider item finishes or a subagent needs attention. Use `subagent_wait({ all: true })` for all work active at call time, `subagent_wait({ id: "..." })` for one async or remembered detached foreground run, and `subagent_wait({ timeoutMs })` to cap the block. In a long-lived interactive parent session, use `subagent_wait({ id: "...", nonBlocking: true })` to resolve the prefix to one exact run, persist an armed subscription, return immediately, and wake later on completion, failure, attention, reconciliation failure, or timeout. Ordinary status lists armed subscriptions separately from active children. This differs from disabling `waitTool`, which returns immediately without arming a future wake. If a foreground child detaches for supervisor coordination, reply first, then wait on its id; do not resume or launch a replacement while it remains detached. Headless sessions also auto-drain exact current-session work at `agent_end` as a final safeguard.
|
|
88
109
|
|
|
@@ -110,17 +131,10 @@ While children run, the persistent FleetView and the collapsed foreground tool-r
|
|
|
110
131
|
|
|
111
132
|
Inspect async runs with `subagent({ action: "status", id: "..." })` or `subagent({ action: "status" })` for active runs. Use `subagent({ action: "status", view: "fleet" })` when supervising several active foreground/background runs and `subagent({ action: "status", id: "...", view: "transcript", index: 0 })` when you need the latest child output without digging through artifacts. If a delegated fanout child launches nested runs, the parent status view shows them as a tree and you can target a nested run directly with its nested id.
|
|
112
133
|
|
|
113
|
-
Stop a current-session top-level async run with `stop` (or `/subagents-stop`). Stopped runs finish as `stopped`/cancelled and are not resumable. For an active foreground single-subagent run, `/subagents-detach [run-id]` leaves the child running without terminating it and returns the eventual result through status/wait.
|
|
134
|
+
Stop a current-session top-level async run with `stop` (or `/subagents-stop`). Stopped runs finish as `stopped`/cancelled and are not resumable. For an active foreground single-subagent run, `/subagents-detach [run-id]` leaves the child running without terminating it and returns the eventual result through status/wait.
|
|
114
135
|
|
|
115
136
|
```typescript
|
|
116
137
|
subagent({ action: "stop", id: "run-id" })
|
|
117
|
-
subagent({
|
|
118
|
-
action: "append-step",
|
|
119
|
-
id: "run-id",
|
|
120
|
-
step: { checkpoint: "review", message: "Approve the next implementation step?" }
|
|
121
|
-
})
|
|
122
|
-
subagent({ action: "approve-checkpoint", id: "run-id" })
|
|
123
|
-
subagent({ action: "reject-checkpoint", id: "run-id" })
|
|
124
138
|
```
|
|
125
139
|
|
|
126
140
|
Use `steer` for top-level live async guidance and `resume` after a delegated run pauses or finishes. Routed nested runs retain their existing non-destructive live follow-up path:
|
|
@@ -183,7 +197,7 @@ Humans can use `/subagents-doctor` for the same read-only report. It checks runt
|
|
|
183
197
|
|
|
184
198
|
### Subagent control
|
|
185
199
|
|
|
186
|
-
Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, `stopped`, `failed`, or `rejected`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck. Manual top-level async cancellation uses `stop` / `/subagents-stop
|
|
200
|
+
Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, `stopped`, `failed`, or `rejected`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck. Manual top-level async cancellation uses `stop` / `/subagents-stop`.
|
|
187
201
|
|
|
188
202
|
Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs can push this as a `subagent:control-event` event, and async runs persist it to `events.jsonl` so the parent tracker can surface it without constant manual polling. Notification-worthy control events are also inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state.
|
|
189
203
|
|
|
@@ -351,6 +365,17 @@ worktree, first confirm dependencies were linked, installed, or provisioned by
|
|
|
351
365
|
|
|
352
366
|
## The Oracle Workflow
|
|
353
367
|
|
|
368
|
+
### Oracle consultation loop
|
|
369
|
+
|
|
370
|
+
For plan, design, or architecture advice that asks to ask, consult, discuss with, or come to agreement with `oracle`, start with one forked oracle run. Read its result. If it challenges the direction or leaves a material tradeoff, resume that same completed child once with a focused follow-up, then synthesize the parent decision. `resume` returns a new run id, but continues the same oracle session and inherited context. Do not force a second round for an explicit one-shot request, a trivial question, or a fully settled first answer.
|
|
371
|
+
|
|
372
|
+
```typescript
|
|
373
|
+
const first = await runs.run("oracle-consult", { agent: "oracle", task: "Review this plan and identify the strongest unresolved tradeoff." });
|
|
374
|
+
const final = await runs.run("oracle-consult-follow-up", { resume: first.runId, task: "Address this focused question, then state the best recommendation: ..." });
|
|
375
|
+
```
|
|
376
|
+
|
|
377
|
+
The parent remains the final decision-maker. Oracle advice does not approve a direction or start implementation.
|
|
378
|
+
|
|
354
379
|
The intended oracle loop is:
|
|
355
380
|
1. the main agent forks to `oracle`
|
|
356
381
|
2. `oracle` reviews direction, drift, assumptions, and risks
|
|
@@ -6,7 +6,7 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
|
|
|
6
6
|
|
|
7
7
|
The `subagent(...)` tool also supports management actions.
|
|
8
8
|
|
|
9
|
-
### List available agents and
|
|
9
|
+
### List available agents and legacy chain records
|
|
10
10
|
|
|
11
11
|
```typescript
|
|
12
12
|
subagent({ action: "list" })
|
|
@@ -85,7 +85,7 @@ subagent({ action: "reset", agent: "reviewer" })
|
|
|
85
85
|
Use management actions when the system needs to create or edit subagents on
|
|
86
86
|
demand without dropping into raw file editing.
|
|
87
87
|
|
|
88
|
-
Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and
|
|
88
|
+
Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and scripted workflow steps. For small builtin changes such as a model swap, prefer `subagents.agentOverrides` in settings. Durable `.chain.md` definitions are legacy records, not a current authoring target; use `workflowScript` or `/prompt-workflow` for repeatable orchestration.
|
|
89
89
|
|
|
90
90
|
## Creating and Editing Agents by File
|
|
91
91
|
|
|
@@ -129,7 +129,7 @@ That is only a starting point. Omit `package` for the traditional unqualified ru
|
|
|
129
129
|
|
|
130
130
|
`aliases` is an optional comma-separated or block-list set of alternate names for selecting an agent. Aliases resolve to the canonical `name` for execution, status, persistence, and config. Exact canonical names take precedence over aliases, and alias collisions between distinct canonical agents fail as ambiguous. Management create/update accepts a comma-separated string, string array, or `false`/empty string to clear aliases.
|
|
131
131
|
|
|
132
|
-
`acceptance` is a single-agent launch default. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. An explicit tool-call value wins;
|
|
132
|
+
`acceptance` is a single-agent launch default. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. An explicit tool-call value wins; scripted workflow child acceptance remains configured on the `runs.run` or `runs.all` item. Management create/update accepts the same policy object, and `acceptance: ""` clears the frontmatter default (`false` remains the deprecated disabled-policy shorthand).
|
|
133
133
|
|
|
134
134
|
`acceptanceRole` is `read-only` or `writer` and controls automatic acceptance inference only. Explicit task mutation or no-edit intent wins; otherwise the role replaces agent-name guessing. Omission preserves the current name heuristics. The field does not grant or revoke tools. Management accepts `false` or an empty string to clear it.
|
|
135
135
|
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Multi-Lane Orchestration
|
|
2
|
+
|
|
3
|
+
Use this reference when several independent tasks need coordinated workers, worktrees, or repositories. It defines lane ownership; use the other pi-subagents references for run controls, prompts, and mission details. The parent remains the final decision-maker.
|
|
4
|
+
|
|
5
|
+
## Lane board and authority
|
|
6
|
+
|
|
7
|
+
Before multiple mutation-capable lanes start, record this board in the parent context:
|
|
8
|
+
|
|
9
|
+
`Lane | repo/cwd | exact decision | claimed files or contract | isolation path | authority | next gate | handoff | why independent`
|
|
10
|
+
|
|
11
|
+
Record the isolation path before the first mutation. Do not split one source seam or decision into duplicate lanes. Make overlapping work one lane with one source of truth.
|
|
12
|
+
|
|
13
|
+
For every lane, record the delivery target, allowed actions, required validation, and review rigor. For cross-repository work, name the shared contract and which repository changes first. A blocked decision is a lane state: record the owner, options, recommended default, and evidence needed to continue.
|
|
14
|
+
|
|
15
|
+
## Partitioned runs
|
|
16
|
+
|
|
17
|
+
Use one writer per repo/cwd or worktree. Mutation lanes need distinct isolation paths and explicit `cwd` values. Set `worktree: true` when a run needs managed worktree isolation within one repository. Read-only runs can share a checkout only when they cannot change state or create generated files.
|
|
18
|
+
|
|
19
|
+
For Pi extension repositories, keep lane worktrees outside auto-discovered extension directories such as `~/.pi/agent/extensions`. A stale extension worktree there can auto-load duplicate tools and shortcuts. Remove or move it only after its handoff is durable, the worktree is clean, and no run owns it.
|
|
20
|
+
|
|
21
|
+
Partition fanout by repository, source seam, decision, or review angle. Each run needs a stable key, lane-specific task, and durable output path. Do not launch prompts that differ only by item name or broad file glob.
|
|
22
|
+
|
|
23
|
+
Use one async `workflowScript` for a coordinated wave. Use `runs.all` for independent lanes and `runs.run` for dependent lane stages. Give cross-repository runs explicit `cwd` values and lane-qualified outputs. Use `outputMode: "file-only"` when a report must survive the run or feed a later stage.
|
|
24
|
+
|
|
25
|
+
## Keep independent work moving
|
|
26
|
+
|
|
27
|
+
While one lane waits, run safe independent preparation, validation, or fresh read-only review lanes. Do not block the parent just because a run is active. If no safe lane remains, record the blocker and the event that will reopen work.
|
|
28
|
+
|
|
29
|
+
An ordinary coordinated workflow has one mission. Use its durable state, artifacts, run records, and receipts for recovery. Treat a receipt as evidence, not as authority or acceptance.
|
|
30
|
+
|
|
31
|
+
After a writer produces a candidate, run the required fresh-context, read-only reviewer. The reviewer inspects the exact worktree and returns evidence-backed findings. The parent decides which findings are in scope and whether the lane is ready. Send accepted fixes to that lane's sole writer, then rerun only the affected gate.
|
|
32
|
+
|
|
33
|
+
## Handoff, cleanup, and recovery
|
|
34
|
+
|
|
35
|
+
Use stable lane-qualified paths for reports and review output. A handoff states the lane status, repository and worktree, changed files, validation, open decisions, next action, and artifact or receipt paths.
|
|
36
|
+
|
|
37
|
+
Keep a worktree until its handoff is durable, no run owns it, and no later gate needs it. Clean up only inside the recorded authority boundary. If a run stops or needs attention, preserve its worktree and artifacts, record the last known state and recovery owner, then resume that run or create one replacement lane from the handoff. Do not start another writer while worktree ownership is uncertain.
|
|
38
|
+
|
|
39
|
+
Before completion, inspect the board. Every lane must be terminal or blocked with a named next action. Confirm one writer per repo/cwd or worktree, required validation, required fresh read-only review, and a durable handoff. The parent reports outcomes, evidence, residual risks, and the next decision.
|