@xzzpig/pi-subagents 0.1.0 → 0.3.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 +135 -0
- package/README.md +4 -0
- package/agents/reviewer.md +3 -4
- package/docs/agents.md +343 -0
- package/docs/configuration.md +395 -0
- package/docs/extension-api.md +308 -0
- package/docs/missions.md +121 -0
- package/docs/models.md +192 -0
- package/docs/observability.md +198 -0
- package/docs/tool-reference.md +343 -0
- package/docs/watchdog.md +176 -0
- package/docs/workflows.md +163 -0
- package/package.json +13 -11
- package/skills/pi-subagents/references/constraints-and-recipes.md +1 -1
- package/skills/pi-subagents/references/execution-controls.md +7 -7
- package/skills/pi-subagents/references/management-authoring-rpc.md +1 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +1 -1
- package/src/agents/agents.ts +53 -23
- package/src/agents/frontmatter.ts +7 -3
- package/src/agents/skills.ts +2 -9
- package/src/api/preflight.ts +1 -1
- package/src/api/project-panes.ts +30 -0
- package/src/extension/config.ts +54 -1
- package/src/extension/doctor.ts +40 -0
- package/src/extension/fanout-child.ts +5 -4
- package/src/extension/index.ts +114 -38
- package/src/extension/public-execution.ts +35 -4
- package/src/extension/rpc.ts +10 -15
- package/src/extension/schemas.ts +33 -11
- package/src/extension/subagent-guide.ts +39 -0
- package/src/extension/tool-description.ts +38 -18
- package/src/inspectors/herdr/actions.ts +11 -2
- package/src/inspectors/herdr/inspector-runner.ts +16 -3
- package/src/inspectors/herdr/project-panes.ts +459 -63
- package/src/intercom/intercom-bridge.ts +7 -2
- package/src/intercom/native-supervisor-channel.ts +102 -4
- package/src/missions/actions.ts +25 -2
- package/src/missions/lifecycle.ts +25 -9
- package/src/missions/store.ts +89 -7
- package/src/missions/types.ts +33 -0
- package/src/missions/workflow-state.ts +25 -15
- package/src/runs/background/active-async-capacity.ts +431 -0
- package/src/runs/background/active-run-index.ts +46 -0
- package/src/runs/background/async-execution.ts +158 -71
- package/src/runs/background/async-job-tracker.ts +297 -133
- package/src/runs/background/async-resume.ts +37 -5
- package/src/runs/background/async-status.ts +39 -5
- package/src/runs/background/chain-append.ts +33 -15
- package/src/runs/background/completion-replay.ts +267 -0
- package/src/runs/background/control-channel.ts +95 -54
- package/src/runs/background/fleet-view.ts +18 -5
- package/src/runs/background/owned-process-tree.ts +104 -0
- package/src/runs/background/process-terminal.ts +17 -3
- package/src/runs/background/result-watcher.ts +113 -10
- package/src/runs/background/resume-guidance.ts +53 -0
- package/src/runs/background/retained-children.ts +14 -6
- package/src/runs/background/run-status.ts +119 -5
- package/src/runs/background/scheduled-runs.ts +25 -1
- package/src/runs/background/stale-run-reconciler.ts +12 -24
- package/src/runs/background/subagent-runner.ts +127 -41
- package/src/runs/background/subagent-wait.ts +5 -2
- package/src/runs/background/wait-completions.ts +39 -5
- package/src/runs/background/wait-subscriptions.ts +21 -5
- package/src/runs/foreground/async-dismiss-action.ts +85 -0
- package/src/runs/foreground/async-steering-action.ts +7 -8
- package/src/runs/foreground/chain-execution.ts +40 -2
- package/src/runs/foreground/execution.ts +97 -19
- package/src/runs/foreground/foreground-control.ts +12 -0
- package/src/runs/foreground/foreground-history.ts +137 -0
- package/src/runs/foreground/prompt-audit.ts +172 -0
- package/src/runs/foreground/subagent-executor.ts +1274 -243
- package/src/runs/foreground/workflow-foreground-steering.ts +187 -0
- package/src/runs/shared/acceptance.ts +13 -4
- package/src/runs/shared/completion-guard.ts +17 -1
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/llm-intent-arbiter.ts +302 -0
- package/src/runs/shared/model-fallback.ts +8 -4
- package/src/runs/shared/model-scope.ts +12 -2
- package/src/runs/shared/parallel-utils.ts +3 -0
- package/src/runs/shared/pi-args.ts +44 -1
- package/src/runs/shared/run-fanout-budget.ts +280 -0
- package/src/runs/shared/single-output.ts +4 -2
- package/src/runs/shared/subagent-prompt-runtime.ts +94 -9
- package/src/runs/shared/task-intent.ts +19 -3
- package/src/runs/shared/worktree.ts +20 -7
- package/src/shared/agent-stream-options.ts +5 -0
- package/src/shared/artifacts.ts +17 -21
- package/src/shared/display-text.ts +150 -0
- package/src/shared/file-coalescer.ts +9 -0
- package/src/shared/fork-context.ts +13 -0
- package/src/shared/formatters.ts +4 -6
- package/src/shared/node-executable.ts +21 -0
- package/src/shared/prompt-resources.ts +51 -0
- package/src/shared/settings.ts +15 -2
- package/src/shared/types.ts +158 -4
- package/src/shared/utf8.ts +11 -0
- package/src/shared/utils.ts +46 -34
- package/src/slash/prompt-workflows.ts +2 -15
- package/src/slash/slash-commands.ts +22 -2
- package/src/tui/fleet-status.ts +29 -17
- package/src/tui/fleet-transcript.ts +1 -48
- package/src/tui/fleet.ts +362 -37
- package/src/tui/render.ts +235 -71
- package/src/watchdog/change-signature.ts +4 -3
- package/src/watchdog/permission-arbiter.ts +2 -1
- package/src/watchdog/review.ts +4 -3
- package/src/workflows/chat-progress.ts +8 -2
- package/src/workflows/scripted-workflow.ts +273 -20
package/docs/watchdog.md
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
# Watchdog and child permissions
|
|
2
|
+
|
|
3
|
+
The watchdog is an opt-in adversarial reviewer for repo edits. This page covers what it reviews, how to pick its model, scope monitoring, LSP diagnostics, and the native child tool permission gate that uses the child watchdog as its arbiter.
|
|
4
|
+
|
|
5
|
+
## What the watchdog reviews
|
|
6
|
+
|
|
7
|
+
The watchdog is not the `reviewer` subagent. `subagents.defaultModel` and `subagents.agentOverrides.reviewer` do not configure it.
|
|
8
|
+
|
|
9
|
+
It reviews repo edits, not ordinary conversation:
|
|
10
|
+
|
|
11
|
+
- It runs at the safe `agent_end` boundary, only when the current agent or child writer changed the final repo state since the start of that turn.
|
|
12
|
+
- Multiple edits in one turn are coalesced into one review of the final changed state.
|
|
13
|
+
- Unchanged/reverted diffs are skipped.
|
|
14
|
+
- Generated `.pi/subagents/` or `tmp/` artifacts do not trigger review.
|
|
15
|
+
- In orchestrated runs, each writing child can review its own edited worktree, and the parent can still review the aggregate repo diff after child changes are applied.
|
|
16
|
+
|
|
17
|
+
## Choosing a model
|
|
18
|
+
|
|
19
|
+
Because the watchdog is an adversarial change reviewer, it should usually use a strong complementary model rather than a cheap/light one.
|
|
20
|
+
|
|
21
|
+
Ask pi-subagents for the current strong pairing:
|
|
22
|
+
|
|
23
|
+
```text
|
|
24
|
+
/subagents-watchdog recommend-model
|
|
25
|
+
/subagents-watchdog session model recommended
|
|
26
|
+
/subagents-watchdog model recommended
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
The current recommendation policy is Opus 4.8 with thinking high or GPT 5.5 with thinking high. If your main session is using one, the watchdog should use the other when that model is authenticated.
|
|
30
|
+
|
|
31
|
+
- `session model recommended` changes only the current Pi session.
|
|
32
|
+
- `model recommended` saves the recommendation to `~/.pi/agent/settings.json`. It does not turn the watchdog on; enable it separately with `/subagents-watchdog on`.
|
|
33
|
+
|
|
34
|
+
Or set the model explicitly:
|
|
35
|
+
|
|
36
|
+
```text
|
|
37
|
+
/subagents-watchdog model anthropic/claude-opus-4-8:high
|
|
38
|
+
/subagents-watchdog model openai-codex/gpt-5.5:high
|
|
39
|
+
/subagents-watchdog model inherit
|
|
40
|
+
/subagents-watchdog check
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
In settings files, use `subagents.watchdog.main.model` and `subagents.watchdog.main.thinking` for the main watchdog:
|
|
44
|
+
|
|
45
|
+
- If `main.model` is omitted, the main watchdog uses the current session model and thinking level.
|
|
46
|
+
- If `main.model` is set without a thinking suffix or `main.thinking`, it runs with thinking off. Prefer `:high` or `"thinking": "high"` for the strong-watchdog pairing.
|
|
47
|
+
|
|
48
|
+
Default strong-reviewer profile:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"subagents": {
|
|
53
|
+
"watchdog": {
|
|
54
|
+
"enabled": true,
|
|
55
|
+
"main": {
|
|
56
|
+
"model": "anthropic/claude-opus-4-8",
|
|
57
|
+
"thinking": "high"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Scope monitoring
|
|
65
|
+
|
|
66
|
+
When enabled, the watchdog keeps a bounded in-memory current-scope artifact from real user prompts and prepends it to review input by default (`subagents.watchdog.scope.enabled`). Newer prompts supersede and mutate older prompts, so the reviewer can flag work that no longer serves the current scope as `scope-drift`. Watchdog auto-follow prompts are not recorded as scope.
|
|
67
|
+
|
|
68
|
+
You can opt into Scopey-style scope monitoring, inspired by [Scopey](https://github.com/ArchAstro/scopey), by setting `subagents.watchdog.cadence.everyNTools` to run additional non-blocking reviews every N tool results. Cadence warnings are transcript-visible and delivered with Pi's `steer` mode after the current tool boundary; they are never hidden. The same configured watchdog model is used for all checks, so choose a cheap model for frequent monitoring or a strong model for rarer adversarial review.
|
|
69
|
+
|
|
70
|
+
Scopey-style profile:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"subagents": {
|
|
75
|
+
"watchdog": {
|
|
76
|
+
"enabled": true,
|
|
77
|
+
"main": {
|
|
78
|
+
"model": "anthropic/claude-haiku-4-5",
|
|
79
|
+
"thinking": "medium"
|
|
80
|
+
},
|
|
81
|
+
"scope": { "enabled": true },
|
|
82
|
+
"cadence": { "everyNTools": 10 },
|
|
83
|
+
"autoFollow": {
|
|
84
|
+
"blockers": true,
|
|
85
|
+
"maxAttempts": 3,
|
|
86
|
+
"stalemateRepeats": 3
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Auto-follow
|
|
94
|
+
|
|
95
|
+
When the watchdog displays a blocker at `agent_end`, the `subagents.watchdog.autoFollow` policy can queue a visible follow-up user message asking the agent to address it. Auto-follow only runs while the watchdog is enabled, respects `maxAttempts`, and stops on repeated identical blockers using `stalemateRepeats`.
|
|
96
|
+
|
|
97
|
+
## LSP diagnostics
|
|
98
|
+
|
|
99
|
+
When the watchdog is enabled, it also checks changed TypeScript and JavaScript files for fresh language-server diagnostics before the model review.
|
|
100
|
+
|
|
101
|
+
- It auto-detects `typescript-language-server` from the project `node_modules/.bin` or `PATH`. It never installs tools or scans the whole workspace.
|
|
102
|
+
- LSP errors surface as watchdog blockers, warnings as concerns, and info/hints stay in status details.
|
|
103
|
+
- Slow or missing servers are reported in `/subagents-watchdog status` without blocking the turn or emitting late mid-turn warnings.
|
|
104
|
+
- Configure the bounds with `subagents.watchdog.lsp.enabled`, `timeoutMs`, `maxFiles`, and `maxDiagnostics`.
|
|
105
|
+
|
|
106
|
+
## Child watchdogs
|
|
107
|
+
|
|
108
|
+
For child subagent watchdogs, use `subagents.watchdog.children.model` as the default child watchdog model, or `subagents.watchdog.children.overrides.<agent>.model` for a specific child role.
|
|
109
|
+
|
|
110
|
+
Child watchdogs are opt-in and follow the same edit-gated rule: read-only children do not trigger watchdog reviews, while writer children are reviewed at their own `agent_end` if their worktree changed.
|
|
111
|
+
|
|
112
|
+
## Agent-driven configuration
|
|
113
|
+
|
|
114
|
+
Agents can configure the same values through the tool when you ask them to set up the watchdog:
|
|
115
|
+
|
|
116
|
+
```ts
|
|
117
|
+
subagent({ action: "watchdog.recommend-model" })
|
|
118
|
+
subagent({ action: "watchdog.configure", model: "recommended", scope: "session" })
|
|
119
|
+
subagent({ action: "watchdog.configure", model: "recommended", scope: "project" })
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Persistent scopes (`user` or `project`) should only be used when you ask for a lasting default. Otherwise the agent should use `scope: "session"`.
|
|
123
|
+
|
|
124
|
+
## Native child tool permissions
|
|
125
|
+
|
|
126
|
+
Native permissions are opt-in and apply only to Pi child runtimes. With no rules configured, every tool call passes through unchanged.
|
|
127
|
+
|
|
128
|
+
Configure explicit non-bash rules globally in `~/.pi/agent/extensions/subagent/config.json`:
|
|
129
|
+
|
|
130
|
+
```json
|
|
131
|
+
{
|
|
132
|
+
"permissions": {
|
|
133
|
+
"rules": {
|
|
134
|
+
"read": "allow",
|
|
135
|
+
"write": "ask",
|
|
136
|
+
"edit": "deny"
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Custom agents can override matching global rules with a `permission:` or `permissions:` frontmatter block:
|
|
143
|
+
|
|
144
|
+
```yaml
|
|
145
|
+
---
|
|
146
|
+
name: worker
|
|
147
|
+
permission:
|
|
148
|
+
write: allow
|
|
149
|
+
edit: ask
|
|
150
|
+
---
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Rules support `allow`, `ask`, and `deny`:
|
|
154
|
+
|
|
155
|
+
- Agent rules override matching global rules.
|
|
156
|
+
- Omitted and unknown tools default to `allow`.
|
|
157
|
+
- Explicit `allow` removes an inherited restriction.
|
|
158
|
+
- The gate is not registered when the resolved policy has no `ask` or `deny` rules.
|
|
159
|
+
|
|
160
|
+
### How `ask` works
|
|
161
|
+
|
|
162
|
+
An explicit `ask` pauses that exact tool call and sends a bounded, redacted preview to a one-call permission arbiter owned by the built-in child watchdog. The arbiter uses the configured child-watchdog model and returns only `approve` or `deny`; it does not notify the parent agent.
|
|
163
|
+
|
|
164
|
+
Enable and configure `subagents.watchdog.children` before using `ask` rules. A disabled watchdog, missing model/auth, timeout, malformed response, or runtime error denies the call with a clear error.
|
|
165
|
+
|
|
166
|
+
Asked requests and decisions are written to bounded audit JSONL, including `decisionSource: "watchdog"` and bounded failure reasons. Ordinary direction and clarification through `contact_supervisor` or the optional `pi-intercom` extension remain separate and are never permission-gated.
|
|
167
|
+
|
|
168
|
+
### Bash is out of scope
|
|
169
|
+
|
|
170
|
+
`bash` is always passed through by pi-subagents. Bash rules are rejected rather than parsed, gated, denied, or audited. Install and configure `pi-guard` when command-level bash policy is needed.
|
|
171
|
+
|
|
172
|
+
A pi-subagents child is headless, so a pi-guard rule that resolves to `ask` cannot request approval from the parent Pi UI. Native permissions do not forward pi-guard decisions; they only apply to the separate non-bash child permission gate. For child-specific policy, use `PI_GUARD` through a `PI_SUBAGENT_PI_BINARY` wrapper or an equivalent launch wrapper, and configure explicit `allow` or `deny` rules. An `allow` rule grants execution; it is not approval forwarding, so retain explicit denies for commands the child must not run.
|
|
173
|
+
|
|
174
|
+
### External CLI profiles
|
|
175
|
+
|
|
176
|
+
External CLI profiles are opaque processes, so native permissions cannot intercept their tools. A launch with effective `ask` or `deny` rules is rejected for an external CLI agent instead of claiming enforcement.
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# Workflows and orchestration
|
|
2
|
+
|
|
3
|
+
How to compose subagents: the recommended pattern, packaged prompt shortcuts, scripted workflows, direct commands, worktree isolation, and child-to-parent coordination.
|
|
4
|
+
|
|
5
|
+
## Recommended orchestration pattern
|
|
6
|
+
|
|
7
|
+
Use orchestration as parent-agent guidance, not as a runtime workflow mode. For implementation work, the recommended loop is:
|
|
8
|
+
|
|
9
|
+
```text
|
|
10
|
+
clarify → scout → worker → fresh reviewers → worker
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Packaged `worker`, `oracle`, and `advisor` default to forked context when a launch omits `context`; pass `context: "fresh"` when you intentionally want a fresh child run.
|
|
14
|
+
|
|
15
|
+
Child-safety boundaries are enforced at runtime:
|
|
16
|
+
|
|
17
|
+
- Spawned child sessions do not receive the bundled `pi-subagents` skill.
|
|
18
|
+
- Forked child context filtering removes parent-only subagent artifacts (including old hidden orchestration-instruction messages, slash/status/control messages, and prior parent `subagent` tool-call/tool-result history) while preserving ordinary prose and unrelated tool calls/results.
|
|
19
|
+
- By default, children do not register the `subagent` tool and receive boundary instructions that they are not the parent orchestrator and must not propose or run subagents.
|
|
20
|
+
- The explicit exception is an agent whose resolved builtin `tools` includes `subagent`; that child gets a child-safe `subagent` tool for the fanout work the parent assigned, still bounded by `maxSubagentDepth`.
|
|
21
|
+
|
|
22
|
+
## Prompt shortcuts
|
|
23
|
+
|
|
24
|
+
The package includes reusable prompt templates for common workflows. You do not need them, but they are handy when you want the same shape every time:
|
|
25
|
+
|
|
26
|
+
| Prompt | Use it for |
|
|
27
|
+
|--------|------------|
|
|
28
|
+
| `/parallel-review` | Launch fresh-context reviewers with distinct angles, then synthesize what to fix. |
|
|
29
|
+
| `/review-loop` | Run parent-controlled worker, reviewer, and fix-worker cycles until clean or capped. |
|
|
30
|
+
| `/parallel-research` | Combine `researcher` and `scout` for external evidence, local code context, and practical tradeoffs. |
|
|
31
|
+
| `/gather-context-and-clarify` | Scout/research first, then ask the user the clarification questions that matter. |
|
|
32
|
+
| `/parallel-cleanup` | Run review-only cleanup passes after implementation. |
|
|
33
|
+
|
|
34
|
+
Add `autofix` to `/parallel-review` or `/parallel-cleanup` to apply only the synthesized fixes worth doing now after reviewers return.
|
|
35
|
+
|
|
36
|
+
## Scripted workflows (workflowScript)
|
|
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:
|
|
39
|
+
|
|
40
|
+
```js
|
|
41
|
+
subagent({ workflowScript: `
|
|
42
|
+
const scan = await runs.run("scan", { agent: "scout", task: "Scan the codebase" });
|
|
43
|
+
const reviews = await runs.all([
|
|
44
|
+
{ key: "correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
45
|
+
{ key: "tests", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
46
|
+
]);
|
|
47
|
+
return reviews.map(result => result.output);
|
|
48
|
+
` });
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
For long task text with Markdown fences or shell blocks, use quoted lines instead of a raw template literal:
|
|
52
|
+
|
|
53
|
+
````js
|
|
54
|
+
const task = [
|
|
55
|
+
"Run this command:",
|
|
56
|
+
"```bash",
|
|
57
|
+
"npm test",
|
|
58
|
+
"```"
|
|
59
|
+
].join("\n");
|
|
60
|
+
return runs.run("test", { agent: "worker", task });
|
|
61
|
+
````
|
|
62
|
+
|
|
63
|
+
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
|
+
|
|
65
|
+
For watched same-repo workflows, pass `async:false` to show the live in-chat workflow card. `chatProgress` can force `off` or `live-card` when the automatic policy is not what you want. Foreground 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
|
+
|
|
67
|
+
The legacy `/chain`, `/parallel`, and `/run-chain` commands are not registered.
|
|
68
|
+
|
|
69
|
+
## Direct commands
|
|
70
|
+
|
|
71
|
+
Use `/run <agent> [task] [--bg] [--fork]` for one child.
|
|
72
|
+
|
|
73
|
+
## Worktree isolation
|
|
74
|
+
|
|
75
|
+
Scripted workflows can give each writing child a separate managed git worktree by setting `worktree: true` on each `runs.run` / `runs.all` item:
|
|
76
|
+
|
|
77
|
+
```javascript
|
|
78
|
+
const [api, ui] = await runs.all([
|
|
79
|
+
{ key: "api", agent: "worker", task: "Implement the API", worktree: true },
|
|
80
|
+
{ key: "ui", agent: "worker", task: "Implement the UI", worktree: true }
|
|
81
|
+
]);
|
|
82
|
+
return { api: api.artifactPaths, ui: ui.artifactPaths };
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Each child uses the existing worktree lifecycle: it branches from clean HEAD, journals ownership before launch, captures a patch and handoff manifest, then removes cleanly captured temporary worktrees and branches. The handoff manifest path remains available in the child's `artifactPaths`; return or emit it when the orchestrator needs to apply or inspect the patches. `runs.ref` stays concise and intentionally omits full paths.
|
|
86
|
+
|
|
87
|
+
A top-level `{ workflowScript, worktree: true }` makes isolation the default for every workflow child. An individual child can override that default with `worktree: false`. Keep one writer when parallel writes are not intentionally isolated.
|
|
88
|
+
|
|
89
|
+
Configure the worktree base directory and setup hook in [configuration.md](configuration.md).
|
|
90
|
+
|
|
91
|
+
## Supervisor coordination (child asks parent)
|
|
92
|
+
|
|
93
|
+
Child agents can talk back to the parent Pi session without installing `pi-intercom`. `pi-subagents` provides the child-facing `contact_supervisor` tool and the parent-facing `subagent_supervisor({ action: "reply" })` path natively. If no external `pi-intercom` tool owns the `intercom` name, the native channel also exposes `intercom` as a compatibility fallback.
|
|
94
|
+
|
|
95
|
+
Use it for work where the child might need a decision instead of guessing:
|
|
96
|
+
|
|
97
|
+
```text
|
|
98
|
+
Run this implementation in the background. If the worker gets blocked or needs a product decision, have it ask me through intercom.
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
Ask oracle to review this plan. If it sees a decision I need to make, have it ask me instead of assuming.
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
The child uses one dedicated coordination tool, `contact_supervisor`, with a `reason`:
|
|
106
|
+
|
|
107
|
+
- `need_decision` — blocking decisions or clarification
|
|
108
|
+
- `interview_request` — structured input
|
|
109
|
+
- `progress_update` — short non-blocking updates when a discovery changes the plan
|
|
110
|
+
|
|
111
|
+
Children should not ask for clarification when the only conflict is review-only/no-edit versus progress-writing or artifact-writing instructions; no-edit wins.
|
|
112
|
+
|
|
113
|
+
The parent replies with `subagent_supervisor({ action: "reply", replyTo, message })` or checks pending requests with `subagent_supervisor({ action: "pending" })`. Supervisor messages are scoped to the exact Pi session id that spawned the child. A second Pi session in the same repository does not receive those requests.
|
|
114
|
+
|
|
115
|
+
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
|
+
|
|
117
|
+
If messages do not show up, run `/subagents-doctor`. Advanced users can tune the bridge with `intercomBridge` in [configuration.md](configuration.md).
|
|
118
|
+
|
|
119
|
+
## Recursion guard
|
|
120
|
+
|
|
121
|
+
Subagents can call `subagent` only when their resolved builtin tools explicitly include `subagent`. That is meant for delegated fanout agents, not ordinary worker/reviewer children. A depth guard prevents unbounded nesting.
|
|
122
|
+
|
|
123
|
+
By default, nesting is limited to two levels: main session → subagent → sub-subagent. Deeper calls are blocked with guidance to complete the current task directly. Nested runs appear in the parent status widget and `status` output as a tree, and `status`, `interrupt`, and `resume` can target a nested run by its id.
|
|
124
|
+
|
|
125
|
+
Configure the limit with:
|
|
126
|
+
|
|
127
|
+
1. `PI_SUBAGENT_MAX_DEPTH` before starting Pi
|
|
128
|
+
2. `config.maxSubagentDepth`
|
|
129
|
+
3. `maxSubagentDepth` in agent frontmatter, which can only tighten the inherited limit
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
export PI_SUBAGENT_MAX_DEPTH=3
|
|
133
|
+
export PI_SUBAGENT_MAX_DEPTH=1
|
|
134
|
+
export PI_SUBAGENT_MAX_DEPTH=0
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
`PI_SUBAGENT_DEPTH` is internal and propagated automatically. Do not set it manually.
|
|
138
|
+
|
|
139
|
+
## Prompt-template integration
|
|
140
|
+
|
|
141
|
+
`pi-subagents` includes a native prompt-workflow adapter for reusable subagent prompt templates, so you do not need `pi-prompt-template-model` for the common subagent workflow path.
|
|
142
|
+
|
|
143
|
+
Create a prompt in `.pi/prompts/` or `~/.pi/agent/prompts/`:
|
|
144
|
+
|
|
145
|
+
```md
|
|
146
|
+
---
|
|
147
|
+
description: Take a screenshot
|
|
148
|
+
model: claude-sonnet-4-20250514
|
|
149
|
+
subagent: browser-screenshoter
|
|
150
|
+
cwd: /tmp/screenshots
|
|
151
|
+
---
|
|
152
|
+
Use url in the prompt to take screenshot: $@
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Then run it through the native adapter:
|
|
156
|
+
|
|
157
|
+
```text
|
|
158
|
+
/prompt-workflow take-screenshot https://example.com
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
The adapter delegates to the named subagent, applies `model`, `skill`, `cwd`, and fork/fresh context metadata, and supports runtime overrides such as `--subagent reviewer`, `--fork`, `--fresh`, and `--bg`.
|
|
162
|
+
|
|
163
|
+
Prompt templates with `chain:` frontmatter are translated into `workflowScript` and launched through `/prompt-workflow`; `/chain-prompts` is no longer registered.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -15,7 +15,8 @@
|
|
|
15
15
|
"./control-channel": "./src/api/control-channel.ts",
|
|
16
16
|
"./intercom-bridge": "./src/api/intercom-bridge.ts",
|
|
17
17
|
"./pi-args": "./src/api/pi-args.ts",
|
|
18
|
-
"./shared-types": "./src/api/shared-types.ts"
|
|
18
|
+
"./shared-types": "./src/api/shared-types.ts",
|
|
19
|
+
"./project-panes": "./src/api/project-panes.ts"
|
|
19
20
|
},
|
|
20
21
|
"repository": {
|
|
21
22
|
"type": "git",
|
|
@@ -44,9 +45,18 @@
|
|
|
44
45
|
"agents/",
|
|
45
46
|
"skills/**/*",
|
|
46
47
|
"prompts/**/*",
|
|
48
|
+
"docs/**/*",
|
|
47
49
|
"README.md",
|
|
48
50
|
"CHANGELOG.md"
|
|
49
51
|
],
|
|
52
|
+
"scripts": {
|
|
53
|
+
"typecheck": "tsc --noEmit",
|
|
54
|
+
"test": "npm run test:unit",
|
|
55
|
+
"test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
|
|
56
|
+
"test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
|
|
57
|
+
"test:e2e": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/e2e/*.test.ts",
|
|
58
|
+
"test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
|
|
59
|
+
},
|
|
50
60
|
"pi": {
|
|
51
61
|
"extensions": [
|
|
52
62
|
"./index.ts"
|
|
@@ -93,13 +103,5 @@
|
|
|
93
103
|
},
|
|
94
104
|
"publishConfig": {
|
|
95
105
|
"access": "public"
|
|
96
|
-
},
|
|
97
|
-
"scripts": {
|
|
98
|
-
"typecheck": "tsc --noEmit",
|
|
99
|
-
"test": "npm run test:unit",
|
|
100
|
-
"test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
|
|
101
|
-
"test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
|
|
102
|
-
"test:e2e": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/e2e/*.test.ts",
|
|
103
|
-
"test:all": "npm run test:unit && npm run test:integration && npm run test:e2e"
|
|
104
106
|
}
|
|
105
|
-
}
|
|
107
|
+
}
|
|
@@ -36,7 +36,7 @@ In an interactive chat, do not call `subagent_wait()` merely to wait after launc
|
|
|
36
36
|
- `subagent_wait({ id: "..." })` — block on one async or remembered detached foreground run (id or prefix). Provider items are not selected through this parameter.
|
|
37
37
|
- `subagent_wait({ timeoutMs })` — cap the block; active work keeps running if it elapses.
|
|
38
38
|
|
|
39
|
-
Providers are discovered through the
|
|
39
|
+
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`.
|
|
40
40
|
|
|
41
41
|
For non-interactive fleet orchestration, `subagent_wait()` can keep N workers in flight: launch N, wait for the next completion, react to the result, launch a replacement if needed, then wait again. Use `subagent_wait({ all: true })` only when you intentionally want to drain the fleet to zero. If the turn ends first, headless `agent_end` auto-drain still waits for exact current-session work. In an interactive session, return to the user instead of holding the turn open just to await completion.
|
|
42
42
|
|
|
@@ -68,11 +68,11 @@ subagent({
|
|
|
68
68
|
})
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
-
Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `emit`, captured `console`, and standard JavaScript. 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.
|
|
71
|
+
Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `prompts.render`, `emit`, captured `console`, and standard JavaScript. `await prompts.render("package:<name>" | "user:<name>" | "project:<name>", vars?)` reads a named Markdown fragment through the host resolver, applies simple scalar `{{name}}` interpolation, and returns plain task text. It does not give the script filesystem access. Pass the rendered text explicitly as `task` 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
72
|
|
|
73
73
|
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
74
|
|
|
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 a later workflow continues one with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
|
|
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 a later workflow continues one 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. A follow-up loop can render each task with `await prompts.render(...)`. 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.
|
|
76
76
|
|
|
77
77
|
### Async/background
|
|
78
78
|
|
|
@@ -154,11 +154,11 @@ subagent({ action: "doctor" })
|
|
|
154
154
|
|
|
155
155
|
Use native `subagent` runs for unattended implementation, review, and gate work that needs managed isolation, durable artifacts, and process controls. Use `interactive_shell` for visible terminal work, alternate CLIs, trust prompts, and recovery.
|
|
156
156
|
|
|
157
|
-
A cooperating terminal runtime can register read-only external records through
|
|
157
|
+
A cooperating terminal runtime can register read-only external records through `@xzzpig/pi-subagents/external-runs`. Records include the source, session, state, optional report path, and completion reason. They are observations only: pi-subagents does not start, stop, steer, or otherwise own the foreign process. Run unattended raw terminal agents in an explicit isolated cwd or worktree; do not use a live project checkout as disposable review space.
|
|
158
158
|
|
|
159
159
|
### Scheduled subagent runs
|
|
160
160
|
|
|
161
|
-
Schedules are durable project records under `.pi
|
|
161
|
+
Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for.
|
|
162
162
|
|
|
163
163
|
```typescript
|
|
164
164
|
// One-shot reviewer
|
|
@@ -235,7 +235,7 @@ The subagent watchdog is an **opt-in** adversarial change reviewer. It is not th
|
|
|
235
235
|
|
|
236
236
|
When enabled, it reviews actual repo edits at safe `agent_end` boundaries only if
|
|
237
237
|
the final worktree state changed during that turn. Unchanged or reverted diffs and
|
|
238
|
-
generated `.pi
|
|
238
|
+
generated `.pi/subagents/` / temp artifacts do not trigger review. Writing children
|
|
239
239
|
can review their own worktree; the parent can still review the aggregate diff after
|
|
240
240
|
child changes land. Enabled watchdogs also run changed-file TypeScript/JavaScript
|
|
241
241
|
LSP diagnostics before the model pass when `typescript-language-server` is available.
|
|
@@ -298,7 +298,7 @@ Routing rule:
|
|
|
298
298
|
- Several projects with independent work: one async `workflowScript` whose child keys include repo slugs and whose child calls set explicit `cwd`; keep publication and merge decisions serial per repo.
|
|
299
299
|
- Different project, substantial or long-running work: open a project-owned Herdr pane rooted there when a separate visible project session is useful, then give that project Pi session a narrow mission/result contract. Do not model it as ordinary child nesting, and do not expect existing headless runs to move into the pane.
|
|
300
300
|
|
|
301
|
-
Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi
|
|
301
|
+
Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi/subagents/project-panes/herdr.json`. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
|
|
302
302
|
|
|
303
303
|
```typescript
|
|
304
304
|
subagent({ action: "mission.create", mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } })
|
|
@@ -340,7 +340,7 @@ single-writer pattern instead.
|
|
|
340
340
|
|
|
341
341
|
Git worktrees start from tracked files, so ignored or untracked build state
|
|
342
342
|
such as `node_modules` may be absent. The clean-check ignores pi-subagents'
|
|
343
|
-
own `.pi
|
|
343
|
+
own `.pi/subagents/` runtime state, including default mission records, but still
|
|
344
344
|
rejects ordinary source/config changes. `pi-subagents` attempts to symlink the
|
|
345
345
|
root checkout's `node_modules` into each managed worktree when it exists, but
|
|
346
346
|
agents should still treat dependency setup as an explicit bootstrap step before
|
|
@@ -28,7 +28,7 @@ subagent({ action: "refine.show", agent: "reviewer" })
|
|
|
28
28
|
subagent({ action: "refine.rollback", agent: "reviewer" })
|
|
29
29
|
```
|
|
30
30
|
|
|
31
|
-
`refine` builds a bounded project-local guidance overlay for one agent from recent run evidence, using a fresh read-only proposal child; validated guidance is stored under `.pi
|
|
31
|
+
`refine` builds a bounded project-local guidance overlay for one agent from recent run evidence, using a fresh read-only proposal child; validated guidance is stored under `.pi/subagents/refinements/<agent>.md` with revision snapshots and is injected into that agent's child system prompt for this project. `refine.show` prints the current overlay and history; `refine.rollback` restores the previous revision. Guidance that tries to override safety, policy, tool, output, acceptance, developer, or system instructions is rejected. `/subagents-refine <agent>` is the slash equivalent.
|
|
32
32
|
|
|
33
33
|
### Create an agent
|
|
34
34
|
|
|
@@ -4,7 +4,7 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
|
|
|
4
4
|
|
|
5
5
|
## Capability ceilings
|
|
6
6
|
|
|
7
|
-
Parent extensions may register a session-scoped, out-of-band ceiling through
|
|
7
|
+
Parent extensions may register a session-scoped, out-of-band ceiling through `@xzzpig/pi-subagents/capability-ceiling`. Child tools and eligible canonical agent names are intersected with every active registration and inherited snapshot; `denyExtensions` removes ambient/provider extension loading while retaining package protocol runtime. `{ action: "list" }` marks non-allowlisted agents as restricted, and launch rejects them before spawn. Do not add a model-visible ceiling field or rely on unrestricted role selection for enforcement. Restricted schedules are rejected until their ceiling can be persisted safely.
|
|
8
8
|
|
|
9
9
|
## When to Use
|
|
10
10
|
|
package/src/agents/agents.ts
CHANGED
|
@@ -92,7 +92,7 @@ interface BuiltinAgentOverrideConfig {
|
|
|
92
92
|
disabled?: boolean;
|
|
93
93
|
systemPrompt?: string;
|
|
94
94
|
skills?: string[] | false;
|
|
95
|
-
tools?: string[] | false;
|
|
95
|
+
tools?: string[] | false | "inherit";
|
|
96
96
|
extensions?: string[] | false;
|
|
97
97
|
subagentOnlyExtensions?: string[] | false;
|
|
98
98
|
completionGuard?: boolean;
|
|
@@ -602,7 +602,7 @@ function cloneOverrideValue(override: BuiltinAgentOverrideConfig): BuiltinAgentO
|
|
|
602
602
|
...(override.disabled !== undefined ? { disabled: override.disabled } : {}),
|
|
603
603
|
...(override.systemPrompt !== undefined ? { systemPrompt: override.systemPrompt } : {}),
|
|
604
604
|
...(override.skills !== undefined ? { skills: override.skills === false ? false : [...override.skills] } : {}),
|
|
605
|
-
...(override.tools !== undefined ? { tools: override.tools
|
|
605
|
+
...(override.tools !== undefined ? { tools: Array.isArray(override.tools) ? [...override.tools] : override.tools } : {}),
|
|
606
606
|
...(override.extensions !== undefined ? { extensions: override.extensions === false ? false : [...override.extensions] } : {}),
|
|
607
607
|
...(override.subagentOnlyExtensions !== undefined ? { subagentOnlyExtensions: override.subagentOnlyExtensions === false ? false : [...override.subagentOnlyExtensions] } : {}),
|
|
608
608
|
...(override.completionGuard !== undefined ? { completionGuard: override.completionGuard } : {}),
|
|
@@ -659,16 +659,25 @@ function findConfiguredProjectRoot(cwd: string): string | null {
|
|
|
659
659
|
const nearestRoot = candidates[0];
|
|
660
660
|
if (!nearestRoot) return null;
|
|
661
661
|
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
662
|
+
let policyRoot: string | undefined;
|
|
663
|
+
let policyRootIndex = -1;
|
|
664
|
+
for (const [index, candidate] of candidates.entries()) {
|
|
665
|
+
const mode = readProjectRootResolution(candidate);
|
|
666
|
+
if (mode === "nearest") return nearestRoot;
|
|
667
|
+
if (mode === "git-root") {
|
|
668
|
+
policyRoot = candidate;
|
|
669
|
+
policyRootIndex = index;
|
|
670
|
+
break;
|
|
671
|
+
}
|
|
669
672
|
}
|
|
673
|
+
if (!policyRoot) return nearestRoot;
|
|
670
674
|
|
|
671
|
-
|
|
675
|
+
const gitRoot = findNearestGitRoot(cwd);
|
|
676
|
+
const gitProjectRoot = gitRoot
|
|
677
|
+
? candidates.slice(policyRootIndex).find((candidate) => path.resolve(candidate) === path.resolve(gitRoot))
|
|
678
|
+
: undefined;
|
|
679
|
+
const configuredGitRoot = fs.existsSync(path.join(policyRoot, ".git")) ? policyRoot : undefined;
|
|
680
|
+
return gitProjectRoot ?? configuredGitRoot ?? nearestRoot;
|
|
672
681
|
}
|
|
673
682
|
|
|
674
683
|
function getUserAgentSettingsPath(): string {
|
|
@@ -729,6 +738,17 @@ function parseOverrideStringArrayOrFalse(
|
|
|
729
738
|
return items;
|
|
730
739
|
}
|
|
731
740
|
|
|
741
|
+
function parseToolsOverride(
|
|
742
|
+
value: unknown,
|
|
743
|
+
meta: { filePath: string; name: string },
|
|
744
|
+
): BuiltinAgentOverrideConfig["tools"] | undefined {
|
|
745
|
+
if (typeof value === "string" && value.trim() === "inherit") return "inherit";
|
|
746
|
+
if (value === undefined || value === false || Array.isArray(value)) {
|
|
747
|
+
return parseOverrideStringArrayOrFalse(value, { ...meta, field: "tools" });
|
|
748
|
+
}
|
|
749
|
+
throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid 'tools'; expected an array of strings, "inherit", or false.`);
|
|
750
|
+
}
|
|
751
|
+
|
|
732
752
|
function parseBuiltinOverrideEntry(
|
|
733
753
|
name: string,
|
|
734
754
|
value: unknown,
|
|
@@ -836,7 +856,7 @@ function parseBuiltinOverrideEntry(
|
|
|
836
856
|
const skills = parseOverrideStringArrayOrFalse(input.skills, { filePath, name, field: "skills" });
|
|
837
857
|
if (skills !== undefined) override.skills = skills;
|
|
838
858
|
|
|
839
|
-
const tools =
|
|
859
|
+
const tools = parseToolsOverride(input.tools, { filePath, name });
|
|
840
860
|
if (tools !== undefined) override.tools = tools;
|
|
841
861
|
|
|
842
862
|
const extensions = parseOverrideStringArrayOrFalse(input.extensions, { filePath, name, field: "extensions" });
|
|
@@ -995,6 +1015,17 @@ function applySubagentDefaults(
|
|
|
995
1015
|
);
|
|
996
1016
|
}
|
|
997
1017
|
|
|
1018
|
+
function applyToolsOverride(target: AgentConfig, toolsOverride: string[] | false | "inherit"): void {
|
|
1019
|
+
if (toolsOverride === "inherit") {
|
|
1020
|
+
delete target.tools;
|
|
1021
|
+
delete target.mcpDirectTools;
|
|
1022
|
+
return;
|
|
1023
|
+
}
|
|
1024
|
+
const { tools, mcpDirectTools } = splitToolList(toolsOverride === false ? [] : toolsOverride);
|
|
1025
|
+
if (tools === undefined) delete target.tools; else target.tools = tools;
|
|
1026
|
+
if (mcpDirectTools === undefined) delete target.mcpDirectTools; else target.mcpDirectTools = mcpDirectTools;
|
|
1027
|
+
}
|
|
1028
|
+
|
|
998
1029
|
function applyBuiltinOverride(
|
|
999
1030
|
agent: AgentConfig,
|
|
1000
1031
|
override: BuiltinAgentOverrideConfig,
|
|
@@ -1006,7 +1037,10 @@ function applyBuiltinOverride(
|
|
|
1006
1037
|
};
|
|
1007
1038
|
|
|
1008
1039
|
if (override.description !== undefined) next.description = override.description;
|
|
1009
|
-
if (override.model !== undefined) {
|
|
1040
|
+
if (override.model !== undefined) {
|
|
1041
|
+
if (override.model === false) delete next.model; else next.model = override.model;
|
|
1042
|
+
delete next.modelSource;
|
|
1043
|
+
}
|
|
1010
1044
|
if (override.fallbackModels !== undefined) { if (override.fallbackModels === false) delete next.fallbackModels; else next.fallbackModels = [...override.fallbackModels]; }
|
|
1011
1045
|
if (override.thinking !== undefined) { if (override.thinking === false) delete next.thinking; else next.thinking = override.thinking; }
|
|
1012
1046
|
if (override.systemPromptMode !== undefined) next.systemPromptMode = override.systemPromptMode;
|
|
@@ -1017,11 +1051,7 @@ function applyBuiltinOverride(
|
|
|
1017
1051
|
if (override.disabled !== undefined) next.disabled = override.disabled;
|
|
1018
1052
|
if (override.systemPrompt !== undefined) next.systemPrompt = override.systemPrompt;
|
|
1019
1053
|
if (override.skills !== undefined) { if (override.skills === false) delete next.skills; else next.skills = [...override.skills]; }
|
|
1020
|
-
if (override.tools !== undefined)
|
|
1021
|
-
const { tools, mcpDirectTools } = splitToolList(override.tools === false ? [] : override.tools);
|
|
1022
|
-
if (tools === undefined) delete next.tools; else next.tools = tools;
|
|
1023
|
-
if (mcpDirectTools === undefined) delete next.mcpDirectTools; else next.mcpDirectTools = mcpDirectTools;
|
|
1024
|
-
}
|
|
1054
|
+
if (override.tools !== undefined) applyToolsOverride(next, override.tools);
|
|
1025
1055
|
if (override.extensions !== undefined) { if (override.extensions === false) delete next.extensions; else next.extensions = [...override.extensions]; }
|
|
1026
1056
|
if (override.subagentOnlyExtensions !== undefined) { if (override.subagentOnlyExtensions === false) delete next.subagentOnlyExtensions; else next.subagentOnlyExtensions = [...override.subagentOnlyExtensions]; }
|
|
1027
1057
|
if (override.completionGuard !== undefined) next.completionGuard = override.completionGuard;
|
|
@@ -1124,8 +1154,11 @@ function applyCustomAgentOverride(
|
|
|
1124
1154
|
mutable().description = override.description;
|
|
1125
1155
|
anyFilled = true;
|
|
1126
1156
|
}
|
|
1127
|
-
if (override.model !== undefined) {
|
|
1128
|
-
|
|
1157
|
+
if (override.model !== undefined && !agentHasFrontmatterField(agent, "model")) {
|
|
1158
|
+
const target = mutable();
|
|
1159
|
+
if (override.model === false) delete target.model; else target.model = override.model;
|
|
1160
|
+
delete target.modelSource;
|
|
1161
|
+
anyFilled = true;
|
|
1129
1162
|
}
|
|
1130
1163
|
if (override.fallbackModels !== undefined) {
|
|
1131
1164
|
fill(
|
|
@@ -1160,10 +1193,7 @@ function applyCustomAgentOverride(
|
|
|
1160
1193
|
fill("skills", ["skill", "skills"], override.skills === false ? undefined : [...override.skills]);
|
|
1161
1194
|
}
|
|
1162
1195
|
if (override.tools !== undefined && !agentHasFrontmatterField(agent, "tools")) {
|
|
1163
|
-
|
|
1164
|
-
const target = mutable();
|
|
1165
|
-
if (tools === undefined) delete target.tools; else target.tools = tools;
|
|
1166
|
-
if (mcpDirectTools === undefined) delete target.mcpDirectTools; else target.mcpDirectTools = mcpDirectTools;
|
|
1196
|
+
applyToolsOverride(mutable(), override.tools);
|
|
1167
1197
|
anyFilled = true;
|
|
1168
1198
|
}
|
|
1169
1199
|
if (override.extensions !== undefined) {
|