@xzzpig/pi-subagents 0.7.0 → 0.9.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 +456 -4
- package/README.md +3 -3
- package/agents/claude-code-writer.md +15 -0
- package/agents/claude-code.md +15 -0
- package/agents/codex-exec-writer.md +15 -0
- package/agents/codex-exec.md +15 -0
- package/agents/cursor-agent-writer.md +14 -0
- package/agents/cursor-agent.md +14 -0
- package/agents/reviewer.md +13 -3
- package/agents/scout.md +1 -1
- package/docs/agents.md +154 -42
- package/docs/configuration.md +85 -26
- package/docs/extension-api.md +81 -16
- package/docs/missions.md +2 -0
- package/docs/models.md +75 -11
- package/docs/observability.md +34 -21
- package/docs/tool-reference.md +142 -18
- package/docs/watchdog.md +92 -114
- package/docs/workflows.md +148 -4
- package/index.ts +10 -1
- package/install.mjs +1 -1
- package/package.json +7 -6
- package/prompts/council.md +19 -7
- package/prompts/parallel-review.md +5 -1
- package/prompts/review-loop.md +11 -7
- package/skills/council-mode/SKILL.md +44 -215
- package/skills/council-mode/references/pass-contracts.md +150 -0
- package/skills/pi-subagents/SKILL.md +90 -32
- package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
- package/skills/pi-subagents/references/execution-controls.md +104 -19
- package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
- package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
- package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
- package/skills/pi-subagents/references/review-and-validation.md +73 -0
- package/src/agents/agent-management.ts +471 -114
- package/src/agents/agent-refinements.ts +4 -4
- package/src/agents/agent-serializer.ts +16 -4
- package/src/agents/agents.ts +1076 -351
- package/src/agents/builtin-names.ts +6 -0
- package/src/agents/runtime-agent-events.ts +70 -0
- package/src/agents/runtime-agent-registry.ts +31 -20
- package/src/api/agents.ts +10 -5
- package/src/api/background-work.ts +12 -3
- package/src/api/capability-ceiling.ts +0 -1
- package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
- package/src/api/delegation.ts +0 -7
- package/src/api/external-job-provider.ts +10 -1
- package/src/api/external-runs.ts +67 -4
- package/src/api/preflight.ts +97 -34
- package/src/api/project-panes.ts +2 -0
- package/src/api/shared-types.ts +6 -0
- package/src/extension/config.ts +90 -0
- package/src/extension/doctor.ts +15 -13
- package/src/extension/fanout-child.ts +17 -16
- package/src/extension/index.ts +139 -41
- package/src/extension/public-execution.ts +113 -22
- package/src/extension/rpc.ts +182 -13
- package/src/extension/schemas.ts +63 -21
- package/src/extension/tool-description.ts +48 -23
- package/src/extension/tool-result.ts +19 -0
- package/src/inspectors/herdr/actions.ts +2 -1
- package/src/inspectors/herdr/client.ts +3 -3
- package/src/inspectors/herdr/focus.ts +55 -0
- package/src/inspectors/herdr/inspector-runner.ts +21 -23
- package/src/inspectors/herdr/project-panes.ts +228 -44
- package/src/inspectors/herdr/session-roots-codec.ts +42 -0
- package/src/integrations/herdr-status.ts +75 -5
- package/src/intercom/native-supervisor-channel.ts +138 -60
- package/src/intercom/result-intercom.ts +2 -0
- package/src/intercom/supervisor-ui.ts +243 -0
- package/src/profiles/profiles.ts +5 -6
- package/src/runs/background/active-async-capacity.ts +103 -18
- package/src/runs/background/async-execution.ts +492 -125
- package/src/runs/background/async-job-tracker.ts +127 -28
- package/src/runs/background/async-resume.ts +67 -29
- package/src/runs/background/async-retention.ts +21 -4
- package/src/runs/background/async-status-snapshot.ts +23 -261
- package/src/runs/background/async-status.ts +199 -14
- package/src/runs/background/auto-drain.ts +1 -1
- package/src/runs/background/chain-append.ts +8 -3
- package/src/runs/background/chain-root-attachment.ts +79 -8
- package/src/runs/background/control-channel.ts +101 -214
- package/src/runs/background/fleet-view.ts +38 -22
- package/src/runs/background/inspect-rpc.ts +8 -8
- package/src/runs/background/notify.ts +295 -8
- package/src/runs/background/process-terminal.ts +16 -0
- package/src/runs/background/result-delivery-ownership.ts +45 -0
- package/src/runs/background/result-files.ts +28 -14
- package/src/runs/background/result-watcher.ts +43 -19
- package/src/runs/background/resume-guidance.ts +2 -2
- package/src/runs/background/retained-children.ts +1 -1
- package/src/runs/background/run-child-session.ts +613 -0
- package/src/runs/background/run-status.ts +99 -18
- package/src/runs/background/runner-aliases.ts +125 -0
- package/src/runs/background/runner-child-sessions.ts +31 -0
- package/src/runs/background/scheduled-runs.ts +174 -18
- package/src/runs/background/stale-run-reconciler.ts +13 -4
- package/src/runs/background/steering.ts +8 -15
- package/src/runs/background/subagent-runner.ts +959 -1159
- package/src/runs/background/subagent-wait.ts +86 -31
- package/src/runs/background/terminal-run-index.ts +1 -1
- package/src/runs/background/wait-completions.ts +45 -2
- package/src/runs/background/wait-config.ts +23 -9
- package/src/runs/background/wait-tool.ts +27 -19
- package/src/runs/foreground/async-steering-action.ts +3 -19
- package/src/runs/foreground/async-stop-action.ts +23 -2
- package/src/runs/foreground/execution.ts +585 -481
- package/src/runs/foreground/foreground-control.ts +13 -0
- package/src/runs/foreground/foreground-history.ts +26 -3
- package/src/runs/foreground/subagent-executor.ts +1549 -410
- package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
- package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
- package/src/runs/shared/abort-recovery.ts +119 -0
- package/src/runs/shared/acceptance.ts +147 -39
- package/src/runs/shared/agent-contract.ts +1 -1
- package/src/runs/shared/async-status-projection.ts +565 -0
- package/src/runs/shared/background-process-options.ts +9 -0
- package/src/runs/shared/capability-ceiling.ts +2 -2
- package/src/runs/shared/child-hooks.ts +25 -0
- package/src/runs/shared/child-identity.ts +62 -0
- package/src/runs/shared/child-launch-plan.ts +151 -0
- package/src/runs/shared/child-launch.ts +314 -0
- package/src/runs/shared/child-lifecycle.ts +25 -0
- package/src/runs/shared/child-runtime-config.ts +126 -0
- package/src/runs/shared/child-session.ts +342 -0
- package/src/runs/shared/child-tool-plan.ts +540 -0
- package/src/runs/shared/claude-code-adapter.ts +133 -0
- package/src/runs/shared/codex-exec-adapter.ts +129 -0
- package/src/runs/shared/completion-evidence.ts +89 -0
- package/src/runs/shared/completion-guard.ts +57 -6
- package/src/runs/shared/cursor-agent-adapter.ts +114 -0
- package/src/runs/shared/dynamic-fanout.ts +4 -4
- package/src/runs/shared/extension-bindings.ts +78 -0
- package/src/runs/shared/external-cli-contract.ts +167 -0
- package/src/runs/shared/external-cli-preflight.ts +138 -0
- package/src/runs/shared/external-cli-runner.ts +349 -54
- package/src/runs/shared/external-job-bridge.ts +53 -37
- package/src/runs/shared/external-job-runner.ts +126 -23
- package/src/runs/shared/fast-mode-extension.ts +10 -0
- package/src/runs/shared/host-step-status.ts +231 -0
- package/src/runs/shared/lane-metadata.ts +126 -0
- package/src/runs/shared/launch-cwd.ts +16 -0
- package/src/runs/shared/long-running-guard.ts +2 -1
- package/src/runs/shared/mcp-config-sources.ts +422 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
- package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
- package/src/runs/shared/model-exclusions.ts +141 -10
- package/src/runs/shared/model-fallback.ts +187 -33
- package/src/runs/shared/model-scope.ts +106 -39
- package/src/runs/shared/mutation-evidence.ts +199 -0
- package/src/runs/shared/nested-events.ts +38 -48
- package/src/runs/shared/nested-path.ts +0 -14
- package/src/runs/shared/nested-render.ts +9 -5
- package/src/runs/shared/orca-progress-tabs.ts +83 -16
- package/src/runs/shared/parallel-handoff.ts +423 -7
- package/src/runs/shared/parallel-utils.ts +28 -5
- package/src/runs/shared/permissions.ts +1 -14
- package/src/runs/shared/pi-spawn.ts +69 -35
- package/src/runs/shared/process-signal.ts +16 -0
- package/src/runs/shared/run-fanout-budget.ts +0 -13
- package/src/runs/shared/run-history.ts +21 -1
- package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
- package/src/runs/shared/single-output.ts +89 -22
- package/src/runs/shared/structured-output.ts +61 -7
- package/src/runs/shared/subagent-control.ts +6 -2
- package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
- package/src/runs/shared/task-intent.ts +21 -7
- package/src/runs/shared/tool-availability.ts +18 -64
- package/src/runs/shared/tool-budget.ts +0 -14
- package/src/runs/shared/tool-timeout.ts +1 -1
- package/src/runs/shared/workflow-graph.ts +16 -0
- package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
- package/src/runs/shared/worktree.ts +571 -62
- package/src/shared/atomic-json.ts +3 -1
- package/src/shared/child-session-name.ts +46 -0
- package/src/shared/extension-context.ts +24 -0
- package/src/shared/fork-context.ts +21 -12
- package/src/shared/fork-session-cwd.ts +27 -0
- package/src/shared/formatters.ts +18 -3
- package/src/shared/jsonl-writer.ts +11 -0
- package/src/shared/launch-contract.ts +20 -6
- package/src/shared/pruned-fork.ts +450 -0
- package/src/shared/session-file-trust.ts +19 -0
- package/src/shared/session-tokens.ts +14 -3
- package/src/shared/settings.ts +21 -102
- package/src/shared/shortcuts.ts +17 -0
- package/src/shared/thinking-ceiling.ts +46 -0
- package/src/shared/types.ts +644 -75
- package/src/shared/utils.ts +60 -93
- package/src/shared/workflow-child-permit.ts +207 -0
- package/src/slash/delegation-adapters.ts +1 -9
- package/src/slash/delegation-request.ts +0 -4
- package/src/slash/prompt-template-bridge.ts +37 -1
- package/src/slash/slash-bridge.ts +1 -2
- package/src/slash/slash-commands.ts +383 -116
- package/src/slash/slash-live-state.ts +22 -11
- package/src/slash/subagents-admin.ts +29 -12
- package/src/tui/fleet-native-transcript.ts +4 -0
- package/src/tui/fleet-status.ts +278 -90
- package/src/tui/fleet-transcript.ts +11 -5
- package/src/tui/fleet.ts +54 -28
- package/src/tui/render-helpers.ts +31 -0
- package/src/tui/render.ts +1433 -166
- package/src/watchdog/change-signature.ts +40 -1
- package/src/watchdog/child-status.ts +54 -34
- package/src/watchdog/diff-tool.ts +77 -0
- package/src/watchdog/emission-guard.ts +5 -3
- package/src/watchdog/guidance.ts +20 -0
- package/src/watchdog/permission-arbiter.ts +59 -52
- package/src/watchdog/register-child.ts +28 -25
- package/src/watchdog/register-main.ts +10 -9
- package/src/watchdog/render.ts +4 -5
- package/src/watchdog/review.ts +15 -4
- package/src/watchdog/rules.ts +70 -0
- package/src/watchdog/runtime.ts +75 -92
- package/src/watchdog/scope.ts +0 -11
- package/src/watchdog/settings.ts +48 -104
- package/src/watchdog/turn-delta.ts +1 -1
- package/src/watchdog/types.ts +18 -32
- package/src/watchdog/warning-format.ts +0 -1
- package/src/workflows/chat-progress.ts +7 -3
- package/src/workflows/host-command.ts +235 -0
- package/src/workflows/scripted-workflow.ts +1142 -69
- package/src/workflows/workflow-checklist.ts +439 -0
- package/src/workflows/workflow-child-summary.ts +121 -0
- package/src/workflows/workflow-preflight.ts +297 -0
- package/src/workflows/workflow-receipt.ts +232 -6
- package/src/workflows/workflow-resources.ts +150 -0
- package/src/workflows/workflow-settlement.ts +246 -0
- package/src/runs/shared/child-protocol.ts +0 -401
- package/src/runs/shared/pi-args.ts +0 -858
- package/src/runs/shared/subagent-startup-retry.ts +0 -116
- package/src/runs/shared/turn-budget.ts +0 -98
- package/src/shared/post-exit-stdio-guard.ts +0 -85
package/docs/models.md
CHANGED
|
@@ -5,10 +5,15 @@ How subagents pick models, and how to change that.
|
|
|
5
5
|
Builtin agents inherit your current Pi default model. This keeps new installs from depending on a provider you may not have configured. From there you can layer defaults and overrides:
|
|
6
6
|
|
|
7
7
|
- `subagents.defaultModel` — a default for every subagent that does not set its own model.
|
|
8
|
+
- `subagents.defaultProvider` — a provider preference for bare model ids, such as `llama-3`, when multiple providers expose the same id.
|
|
8
9
|
- `subagents.agentOverrides.<name>.model` — pin one role.
|
|
10
|
+
- `subagents.agentOverrides.<name>.defaultProvider` — choose or clear the provider preference for one role.
|
|
11
|
+
- `subagents.agentOverridesByProvider.<provider>.<name>` — layer role fields for the active parent provider.
|
|
9
12
|
- Per-run overrides — for one launch only.
|
|
10
13
|
|
|
11
|
-
Precedence, strongest first: per-run override →
|
|
14
|
+
Precedence, strongest first: per-run override → provider-scoped role override → `agentOverrides.<name>.model` → agent frontmatter `model` → `subagents.defaultModel` → the parent session model. A provider preference does not replace this order; it only resolves bare model ids when the active registry has more than one match. Fully qualified `provider/model` strings still win exactly.
|
|
15
|
+
|
|
16
|
+
Use `model: "inherit"` in agent frontmatter or `agentOverrides.<name>.model` to select the current parent session model explicitly.
|
|
12
17
|
|
|
13
18
|
## Setting defaults and overrides
|
|
14
19
|
|
|
@@ -19,15 +24,41 @@ In `~/.pi/agent/settings.json` (user) or the project config settings file (`.pi/
|
|
|
19
24
|
"defaultModel": "deepseek-v4-pro",
|
|
20
25
|
"subagents": {
|
|
21
26
|
"defaultModel": "deepseek-v4-flash",
|
|
27
|
+
"defaultProvider": "gpu-a",
|
|
22
28
|
"agentOverrides": {
|
|
23
29
|
"oracle": {
|
|
24
30
|
"model": "deepseek-v4-pro"
|
|
31
|
+
},
|
|
32
|
+
"worker": {
|
|
33
|
+
"defaultProvider": "gpu-b"
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
To keep one role definition but configure it differently for work and personal providers, add the unambiguous provider map beside `agentOverrides`:
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"subagents": {
|
|
45
|
+
"agentOverrides": {
|
|
46
|
+
"worker": { "thinking": "medium" }
|
|
47
|
+
},
|
|
48
|
+
"agentOverridesByProvider": {
|
|
49
|
+
"github-copilot": {
|
|
50
|
+
"worker": { "model": "github-copilot/gpt-5-mini" }
|
|
51
|
+
},
|
|
52
|
+
"openrouter": {
|
|
53
|
+
"worker": { "model": "openrouter/openai/gpt-5-mini" }
|
|
25
54
|
}
|
|
26
55
|
}
|
|
27
56
|
}
|
|
28
57
|
}
|
|
29
58
|
```
|
|
30
59
|
|
|
60
|
+
The provider key comes from the active parent session model (or an explicit host `preferredProvider`) before fallback selection. Provider-scoped fields layer over the ordinary override in the same settings file; project settings still win over user settings. A fallback attempt does not switch the selected provider configuration.
|
|
61
|
+
|
|
31
62
|
For one run, put the override in the command:
|
|
32
63
|
|
|
33
64
|
```text
|
|
@@ -43,27 +74,33 @@ For a persistent role override with a backup model for provider failures:
|
|
|
43
74
|
"reviewer": {
|
|
44
75
|
"model": "anthropic/claude-sonnet-4",
|
|
45
76
|
"thinking": "high",
|
|
46
|
-
"fallbackModels": ["openai/gpt-5-
|
|
77
|
+
"fallbackModels": ["openai-codex/gpt-5.6-luna:low"]
|
|
47
78
|
}
|
|
48
79
|
}
|
|
49
80
|
}
|
|
50
81
|
}
|
|
51
82
|
```
|
|
52
83
|
|
|
53
|
-
`subagents.defaultModel`
|
|
84
|
+
`subagents.defaultModel` and `subagents.defaultProvider` apply to builtin, package, user, and project agents. `defaultModel` fills only agents that do not set `model` in frontmatter. `defaultProvider` is also applied to frontmatter and override models so bare ids resolve against the intended provider. Per-run model overrides and `agentOverrides.<name>.model` win over frontmatter and the global default. The same `agentOverrides` block can change `tools`, `skills`, inherited context, prompt text, or disable an agent (see [agents.md](agents.md)); matching custom-agent frontmatter is replaced for any field set by the override.
|
|
85
|
+
|
|
86
|
+
## Fast mode
|
|
87
|
+
|
|
88
|
+
Set `fast: true` on a run, in agent frontmatter, or in `subagents.agentOverrides.<name>.fast` to request the OpenAI priority service tier for supported native OpenAI-Codex children. This can use a higher quota tier or cost more. It is off by default.
|
|
89
|
+
|
|
90
|
+
Fast mode fails before launch unless every resolved model candidate is on the allowlist. The current allowlist is `openai-codex/gpt-5.6-luna` and `openai-codex/gpt-5.6-sol`. External runners, Anthropic models, and other providers do not use fast mode.
|
|
54
91
|
|
|
55
92
|
## Recommended model tiering (optional)
|
|
56
93
|
|
|
57
94
|
A setup that works well in practice: route agents by task shape instead of running everything on one model. Four tiers:
|
|
58
95
|
|
|
59
96
|
1. **Fast workhorse** — the cheapest capable model at low thinking, for recon, lookups, and mechanical edits. Example: `openai-codex/gpt-5.6-luna:low` on `scout`.
|
|
60
|
-
2. **Standard well-scoped** — a mid-tier model at medium thinking, for most delegations: routine multi-file edits, focused reviews, straightforward implementation. Example: `openai-codex/gpt-5.6-
|
|
97
|
+
2. **Standard well-scoped** — a mid-tier model at medium thinking, for most delegations: routine multi-file edits, focused reviews, straightforward implementation. Example: `openai-codex/gpt-5.6-luna:max` on `worker`, `reviewer`, and a lightweight `delegate` agent.
|
|
61
98
|
3. **Deep but bounded** — a top reasoning model at high thinking, only for hard tasks that arrive with explicit goals and completion criteria. These models tend to loop on vague goals, so keep them off open-ended work. Example: `openai-codex/gpt-5.6-sol:high` on oracle-style agents.
|
|
62
99
|
4. **Taste and intent** — a model that reads human intent well and makes judgment calls without looping, for ambiguous work: UX and design decisions, product tradeoffs, planning from vague requirements, writing quality. Example: `anthropic/claude-fable-5` at `low` for lighter passes and `medium` for harder ones.
|
|
63
100
|
|
|
64
101
|
The routing rule: use the capability tiers (1–3) when the task is well-scoped, and the intent tier (4) when scoping or judging is the task itself.
|
|
65
102
|
|
|
66
|
-
Give tier-4 agents cross-provider `fallbackModels` so subscription usage limits degrade gracefully instead of failing the run. Fallback triggers on rate-limit and
|
|
103
|
+
Give tier-4 agents cross-provider `fallbackModels` so subscription usage limits degrade gracefully instead of failing the run. Fallback triggers on retryable provider/model failures such as rate-limit, overload, unavailable-model, and provider-reported timeout errors. The outer run-level `timeoutMs` / `maxRuntimeMs` deadline is terminal and does not start another fallback attempt:
|
|
67
104
|
|
|
68
105
|
```yaml
|
|
69
106
|
---
|
|
@@ -79,7 +116,7 @@ One interaction worth knowing for tier 4: forked context over an Anthropic paren
|
|
|
79
116
|
|
|
80
117
|
## Thinking level defaults
|
|
81
118
|
|
|
82
|
-
Set `subagents.defaultThinking` to give builtin, package, user, and project agents without a `thinking` value a shared thinking level, independent of the parent session's default. Project settings win over user settings.
|
|
119
|
+
Set `subagents.defaultThinking` to give builtin, package, user, and project agents without a `thinking` value a shared thinking level, independent of the parent session's default. Project settings win over user settings. Matching `agentOverrides.<name>.thinking` and per-run thinking overrides replace frontmatter; otherwise explicit frontmatter remains in effect. `thinking: false` remains an explicit opt-out:
|
|
83
120
|
|
|
84
121
|
```json
|
|
85
122
|
{
|
|
@@ -92,7 +129,22 @@ Set `subagents.defaultThinking` to give builtin, package, user, and project agen
|
|
|
92
129
|
}
|
|
93
130
|
```
|
|
94
131
|
|
|
95
|
-
If your provider rejects model IDs with thinking suffixes, set `subagents.disableThinking: true` in user or project settings. That clears bundled builtin thinking defaults in one place. An explicit higher-precedence `agentOverrides.<name>.thinking` value can opt a role back in
|
|
132
|
+
If your provider rejects model IDs with thinking suffixes, set `subagents.disableThinking: true` in user or project settings. That clears bundled builtin thinking defaults in one place. An explicit higher-precedence `agentOverrides.<name>.thinking` value can opt a role back in or replace custom-agent frontmatter thinking.
|
|
133
|
+
|
|
134
|
+
### Thinking ceiling
|
|
135
|
+
|
|
136
|
+
Set `subagents.maxThinking` to enforce a hard maximum for every native Pi child. The supported levels, from least to most thinking, are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`:
|
|
137
|
+
|
|
138
|
+
```json
|
|
139
|
+
{
|
|
140
|
+
"subagents": {
|
|
141
|
+
"defaultThinking": "medium",
|
|
142
|
+
"maxThinking": "xhigh"
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
Requests above the ceiling fail before child startup; the setting covers frontmatter, `agentOverrides`, per-run overrides, fallback models, parallel/chain children, nested launches, and resumed children. Project settings take precedence over user settings. External runners retain their existing behavior.
|
|
96
148
|
|
|
97
149
|
## Extension defaults
|
|
98
150
|
|
|
@@ -102,7 +154,7 @@ Set `subagents.defaultExtensions` to give builtin, package, user, and project ag
|
|
|
102
154
|
- Empty array: sets `extensions: []` for agents that do not explicitly define it, disabling ambient extension loading.
|
|
103
155
|
- Non-empty array: supplies that allowlist to agents that do not explicitly define one.
|
|
104
156
|
|
|
105
|
-
Project settings win over user settings. Use `agentOverrides.<name>.extensions` for per-agent settings;
|
|
157
|
+
Project settings win over user settings. Use `agentOverrides.<name>.extensions` for per-agent settings; a matching override replaces custom-agent frontmatter for that field.
|
|
106
158
|
|
|
107
159
|
```json
|
|
108
160
|
{
|
|
@@ -153,17 +205,29 @@ To keep subagents inside a budget or compliance profile, enforce a model scope.
|
|
|
153
205
|
"modelScope": {
|
|
154
206
|
"enforce": true,
|
|
155
207
|
"strict": true,
|
|
156
|
-
"allow": ["
|
|
208
|
+
"allow": ["inherit", "openai/gpt-5-*", "openai-codex/gpt-5.6-*"],
|
|
209
|
+
"agents": {
|
|
210
|
+
"worker": { "allow": ["openai-codex/gpt-5.6-luna"] },
|
|
211
|
+
"reviewer": { "allow": ["inherit"] }
|
|
212
|
+
}
|
|
157
213
|
}
|
|
158
214
|
}
|
|
159
215
|
}
|
|
160
216
|
```
|
|
161
217
|
|
|
162
|
-
- `allow` is a list of glob patterns matched against the resolved `provider/id` (only `*` is special, case-insensitive).
|
|
218
|
+
- `allow` is a list of glob patterns matched against the resolved `provider/id` (only `*` is special, case-insensitive). The literal `inherit` means the current parent session model.
|
|
219
|
+
- `agents.<name>` adds a second allow-list for that agent. The model must pass both the global list and the matching agent list, so an agent rule cannot weaken the global rule. Agent rules inherit `enforce` and `strict` when those fields are absent.
|
|
220
|
+
- A top-level `enforce: true` with only agent allow-lists restricts only those named agents. Unknown names are allowed so settings can be shared across projects and machines.
|
|
163
221
|
- Models you pass explicitly — the tool-call `model`, `--model`, or a clarify pick — error and abort the run.
|
|
164
222
|
- By default, models from agent frontmatter, `subagents.defaultModel`, the inherited parent session model, or fallback chains only warn and remain available, so existing configurations keep working while you tighten the scope.
|
|
165
223
|
- Set `strict: true` with `enforce: true` to reject every resolved out-of-scope model. This includes inherited models and fallback candidates. An invalid fallback fails the run instead of being removed from the candidate chain.
|
|
166
|
-
- `enforce: true` requires
|
|
224
|
+
- `enforce: true` requires at least one non-empty global or agent `allow` list; otherwise the config is rejected at load time.
|
|
225
|
+
|
|
226
|
+
Model scope is policy only. It rejects or warns; it does not select a cheaper model. Set `agentOverrides.worker.model` to choose a worker model and use `modelScope.agents.worker` to prevent a per-run override or fallback from escaping that restriction.
|
|
227
|
+
|
|
228
|
+
`inherit` expands in the parent process at each launch. It is never sent to the child as a model id. A nested child therefore inherits its immediate parent's current model, not the original top-level model. If no parent model is available, an enforced `inherit` entry does not match and fails closed.
|
|
229
|
+
|
|
230
|
+
Project `modelScope` settings replace the complete user `modelScope`, as with the existing project-over-user settings precedence. Project settings are trusted and can therefore replace user restrictions.
|
|
167
231
|
|
|
168
232
|
## Profiles and provider model catalogs
|
|
169
233
|
|
package/docs/observability.md
CHANGED
|
@@ -6,9 +6,13 @@ Where running subagents show up, how to inspect them, and the files and events t
|
|
|
6
6
|
|
|
7
7
|
Foreground runs stream progress in the conversation while they run. They default to a generous 30-minute wall-clock timeout when neither the call nor the selected agent provides a timeout; a global [`timeoutMs`](configuration.md#timeoutms) config replaces that default, and explicit `timeoutMs`/`maxRuntimeMs` and agent defaults win.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
A foreground child is a pi session created inside the parent Pi process, not a second `pi` process. A run timeout, tool timeout, interrupt, or stop aborts the child session and disposes it. Detach keeps the session running inside the parent and publishes the same receipt and completion notification as before.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
A background child is a pi session created inside the detached runner process. The runner mirrors session events into `events.jsonl`, `output-<index>.log`, and the transcript. Interrupt and stop abort the child session; steer requests are delivered with the session's `steer` or `followUp`.
|
|
12
|
+
|
|
13
|
+
Live progress shows compact detail for single, chain, and parallel modes: a bounded one-line task, current tool, recent output, token counts, aggregate cost, duration, activity freshness, current-tool duration, and chain graph metadata when available. Workflow `label` metadata wins over raw task text in compact multi-child cards.
|
|
14
|
+
|
|
15
|
+
Press Pi's configured expand key (`Ctrl+O` by default) to expand the full streaming view with complete output per step. Running-card hints also advertise `Ctrl+Alt+F` for the Fleet inspector.
|
|
12
16
|
|
|
13
17
|
Sequential chains show a flow line like `done scout → running worker`. Chains with parallel steps show per-step cards instead. Chain status uses `label` and `phase` metadata when present, while falling back to agent names for older chains.
|
|
14
18
|
|
|
@@ -29,8 +33,9 @@ The under-editor async widget gives a short view while work runs. Its expand key
|
|
|
29
33
|
async subagent worker · background
|
|
30
34
|
● worker
|
|
31
35
|
● Step 1/1: worker · running
|
|
36
|
+
task: Review authentication boundaries
|
|
32
37
|
⎿ read: src/auth.ts | 2.0s
|
|
33
|
-
Press configured-expand-key for live detail
|
|
38
|
+
Press configured-expand-key for live detail · Ctrl+Alt+F Fleet
|
|
34
39
|
```
|
|
35
40
|
|
|
36
41
|
To inspect one background child in text, use `subagent({ action: "status", id: "...", view: "transcript" })`; add `index` for a specific child in a parallel or chain run.
|
|
@@ -40,7 +45,7 @@ To inspect one background child in text, use `subagent({ action: "status", id: "
|
|
|
40
45
|
In the TUI, a persistent FleetView below the editor keeps active work visible as a compact summary. Set `fleetViewPlacement` to `"aboveEditor"` to move it above the editor.
|
|
41
46
|
|
|
42
47
|
```text
|
|
43
|
-
2 active agents · ↓ 4.2k
|
|
48
|
+
2 active agents · 1 pane · ↓ 3.1k window · 4.2k spent · ↓/← to inspect
|
|
44
49
|
```
|
|
45
50
|
|
|
46
51
|
After you expand it:
|
|
@@ -49,13 +54,13 @@ After you expand it:
|
|
|
49
54
|
↑↓/jk select · enter inspect · esc back
|
|
50
55
|
|
|
51
56
|
> main
|
|
52
|
-
scout · running
|
|
53
|
-
reviewer · running
|
|
57
|
+
scout · running 1m 12s · ↓ 2.0k window · 2.8k spent
|
|
58
|
+
reviewer · running 38s · ↓ 1.1k window · 1.4k spent
|
|
54
59
|
```
|
|
55
60
|
|
|
56
|
-
When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with agent name, state, elapsed time, and token
|
|
61
|
+
When the focused editor is empty, press `↓` or `←` to expand the summary into `main` plus active children with agent name, state, elapsed time, and token usage. When providers report usage, `window` is the latest assistant turn's input plus cache-read tokens, while `spent` keeps the cumulative input-plus-output total. Old run artifacts without window data keep the existing token-total label. The compact line counts active current-session work and Herdr project panes. Then use `↑`/`↓` or `j`/`k` to select a child and `Enter` to open the Fleet lobby; press `Enter` or `H` there to open its child-specific Herdr inspector. Printable navigation keys are never intercepted before activation.
|
|
57
62
|
|
|
58
|
-
FleetView replaces the legacy above-editor async widget by default. Successful background completions stay quiet so inactive Pi tabs are not marked unread, while failed or paused completions still notify the originating session. Parallel runs show every active child independently. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones. When a child is explicitly allowed to fan out with `tools: subagent`, its nested runs appear under that parent child in the main status tree instead of being hidden inside the child
|
|
63
|
+
FleetView replaces the legacy above-editor async widget by default. Successful background completions stay quiet so inactive Pi tabs are not marked unread, while failed or paused completions still notify the originating session. Parallel runs show every active child independently. Chains with parallel groups keep their grouped shape in progress and results, so failed or paused agents stay visible next to completed ones. When a child is explicitly allowed to fan out with `tools: subagent` or `allowNestedSubagents: true`, its nested runs appear under that parent child in the main status tree instead of being hidden inside the child session.
|
|
59
64
|
|
|
60
65
|
## The fleet inspector
|
|
61
66
|
|
|
@@ -69,6 +74,7 @@ Default keys:
|
|
|
69
74
|
- `x`/`Ctrl+O` — toggle tool details
|
|
70
75
|
- `r` — refresh
|
|
71
76
|
- `Esc` — close
|
|
77
|
+
- `Enter` — open the selected inspectable async child in its child-specific Herdr inspector
|
|
72
78
|
- `s` — compose an acknowledged message to a selected live async child; Tab cycles `steer`, `follow_up`, and `auto`
|
|
73
79
|
- `D` — stop a selected child's top-level async run after confirmation
|
|
74
80
|
- `H` — open the selected active async child in a Herdr inspector pane (Herdr 0.7.5+)
|
|
@@ -77,6 +83,8 @@ Set `fleetKeybindings` in the extension config to replace inspector-level keys w
|
|
|
77
83
|
|
|
78
84
|
`Ctrl+Alt+F` opens the same inspector even while a foreground turn is active and slash input is queued.
|
|
79
85
|
|
|
86
|
+
Enter and `H` use the existing Herdr pane path. In a child-specific Herdr inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls.
|
|
87
|
+
|
|
80
88
|
Without a TUI, `/subagents-fleet` retains the textual `subagent({ action: "status", view: "fleet" })` fallback, and mutations use explicit commands: run `/subagents-stop` and pick from the selector, or use `/subagents-stop <run-id>` / `subagent({ action: "stop", id: "..." })` when you already know the id.
|
|
81
89
|
|
|
82
90
|
Use `/subagents-detach [run-id]` only for an active foreground single-subagent run you want to leave running without terminating; the eventual result remains available through status/wait.
|
|
@@ -156,7 +164,7 @@ For a top-level async run, `details.asyncDir` points at that directory; the fina
|
|
|
156
164
|
|
|
157
165
|
The result file is consumed and deleted once its completion notice is delivered. Before deletion, the watcher writes a versioned replay record under `<resultsDir>/completion-replay/<runId>.json` and a bounded output archive under `<resultsDir>/output-archives/<runId>.json`. Replay records expire with the completion deduplication window and are best-effort temporary state, not a permanent run ledger.
|
|
158
166
|
|
|
159
|
-
`
|
|
167
|
+
`bg_wait` surfaces a slim projection of each terminal payload it covered in its own tool-result `details.completions` — run identity, per-child agent/`runId`/success, artifact paths, and the bounded `archivePath`, without duplicating output text. It reads the replay when watcher delivery or a watcher restart has removed the one-shot result file and in-memory completion state is unavailable. Durable non-blocking wait subscriptions use the same replay in their delivered details. Workflow result files record each child's `runId` explicitly, since a workflow child's `artifactPaths` entry points at its saved output rather than the artifact files keyed by the id. Extensions observing `tool_result` events can read run and artifact identity from there instead of parsing the text summary.
|
|
160
168
|
|
|
161
169
|
Output archives reference an existing child output artifact or session file when one is available. For children without either file, the archive stores a per-child `result-tail` entry with `resultIndex`, bounded to 64 KiB per child, and records whether it was truncated. Replay and archive JSON use `version: 1`; consumers must ignore unknown fields.
|
|
162
170
|
|
|
@@ -164,6 +172,17 @@ Nested fanout status is stored as compact sidecar event/registry metadata and me
|
|
|
164
172
|
|
|
165
173
|
Consumers should read these JSON files instead of scraping terminal output. Unknown fields and event types should be ignored for forward compatibility.
|
|
166
174
|
|
|
175
|
+
RPC hosts that need low-latency child-stop UI hints can subscribe to the
|
|
176
|
+
`subagent:child-status` event advertised by RPC `ping` as `events.childStatus`.
|
|
177
|
+
The payload uses `type: "subagent.child-status"`, `version: 1`, `runId`,
|
|
178
|
+
`childId`, `status` (`"stopping"` or `"stopped"`), `ts`, and optional child
|
|
179
|
+
metadata such as `stepIndex`, `agent`, `childRunId`, `workflowKey`, `phase`, and
|
|
180
|
+
`label`. These events are observer hints only. They can duplicate across RPC and
|
|
181
|
+
async replay paths, and they are not replayed after a host restart. Status
|
|
182
|
+
snapshots remain authoritative for recovery and final state. Child stop control
|
|
183
|
+
still uses the normal `stop` request with `childId`; there is no separate child
|
|
184
|
+
stop API.
|
|
185
|
+
|
|
167
186
|
### Status and result fields
|
|
168
187
|
|
|
169
188
|
The status/result fields are: `lifecycleArtifactVersion`, `runId`/`id`, `sessionId`, `mode`, `state`, `startedAt`, `lastUpdate`, `endedAt`, `durationMs`, `cwd`, `asyncDir`, `sessionFile`, `outputFile`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `model`/`attemptedModels`/`modelAttempts`, `toolCount`, `turnCount`, optional `launchResolvedExtensions`, optional `runtimeAcknowledgedExtensions`, and nested `children` when a child is allowed to launch subagents.
|
|
@@ -172,7 +191,7 @@ The status/result fields are: `lifecycleArtifactVersion`, `runId`/`id`, `session
|
|
|
172
191
|
|
|
173
192
|
### Runtime extension acknowledgement
|
|
174
193
|
|
|
175
|
-
Cooperating child extensions can acknowledge child-runtime registration by emitting `subagent:acknowledge-extension` on the child
|
|
194
|
+
Cooperating child extensions can acknowledge child-runtime registration by emitting `subagent:acknowledge-extension` on the child session's `pi.events` bus with payload `{ id: string }`. The process that hosts the child session (the parent for foreground children, the runner for background children) captures the acknowledgement in memory.
|
|
176
195
|
|
|
177
196
|
Acknowledgement ids are self-declared opaque strings. They must be non-empty, at most 128 characters, contain only `A-Z`, `a-z`, `0-9`, `.`, `_`, `:`, `@`, `+`, or `-`, and must not contain `/`, `\`, or `..`.
|
|
178
197
|
|
|
@@ -186,19 +205,13 @@ The reported `runtimeAcknowledgedExtensions` projection is `{ version: 1, source
|
|
|
186
205
|
|
|
187
206
|
Lifecycle artifact v3 adds `process-terminal-candidate.json` (private runner evidence) and `process-terminal.json` (the public proof projection).
|
|
188
207
|
|
|
189
|
-
A proof is `observed` only after the live parent observes the exact detached runner's `close` event
|
|
208
|
+
A proof is `observed` only after the live parent observes the exact detached runner's `close` event and any tracked canonical-session lease is free. Children run inside the runner process, so the candidate records no separate writer processes. If the observer is unavailable, the proof is `unknown`; do not infer process exit from `endedAt`, result-file existence, PID disappearance, or lease-directory absence.
|
|
190
209
|
|
|
191
210
|
The `subagent:process-terminal` event and RPC `ping.capabilities.processTerminalProof` expose this status. Process proof is point-in-time evidence and remains separate from execution success or stopped/non-resumable state.
|
|
192
211
|
|
|
193
|
-
### Child
|
|
194
|
-
|
|
195
|
-
Foreground and async runners share bounded child-protocol handling:
|
|
212
|
+
### Child session events
|
|
196
213
|
|
|
197
|
-
|
|
198
|
-
- Stderr retains only its latest 128 KiB.
|
|
199
|
-
- Split UTF-8 and final unterminated JSON events remain valid.
|
|
200
|
-
- `agent_end.willRetry` defers completion until the child settles.
|
|
201
|
-
- Current Pi builds use `agent_settled` as the terminal watermark; older builds retain the bounded terminal-message fallback.
|
|
214
|
+
Both launch paths subscribe to the child session's event stream directly; there is no stdout protocol. The `events.jsonl` artifact mirrors those events with `message_update` dropped, and the transcript records them with `message_update` projected the same way pi's JSON mode prints it. `agent_end.willRetry` defers completion until the child settles, and `agent_settled` is the terminal watermark; a child whose run does not settle shortly after its terminal event is aborted and finished without it.
|
|
202
215
|
|
|
203
216
|
## Workflow and debug artifacts
|
|
204
217
|
|
|
@@ -210,7 +223,7 @@ Each scripted workflow stores runtime artifacts under a workflow artifact direct
|
|
|
210
223
|
|
|
211
224
|
A run directory may contain files such as `context.md`, `plan.md`, `progress.md`, and `parallel-{stepIndex}/.../output.md`. User-scoped temp workflow artifact directories older than 24 hours are cleaned up on extension startup; project-local and explicit persistent roots are not age-scanned.
|
|
212
225
|
|
|
213
|
-
Debug artifacts live under `{sessionDir}/subagent-artifacts/`, `.pi/subagents/artifacts/` for project-scoped runs, or a user-scoped temp artifact directory. Single-run relative `output` files are saved under `{artifactsDir}/outputs/{runId}/` unless `singleRunOutputBaseDir` is configured. Per task you may see:
|
|
226
|
+
Debug artifacts live under `{sessionDir}/subagent-artifacts/`, `.pi/subagents/artifacts/` for project-scoped runs, or a user-scoped temp artifact directory. Single-run relative `output` files are saved under `{artifactsDir}/outputs/{runId}/` unless `singleRunOutputBaseDir` is configured. For lane, review, council, and gate reports, prefer these managed artifacts or the aggregate workflow result instead of repo-root `reports/` files. Copy only final durable evidence to session memory, a mission artifact, a PR/comment, or an approved docs path. Per task you may see:
|
|
214
227
|
|
|
215
228
|
- `{runId}_{agent}_input.md`
|
|
216
229
|
- `{runId}_{agent}_output.md`
|
|
@@ -223,7 +236,7 @@ For npm package projects, project-scoped artifacts need a `.npmignore` rule (or
|
|
|
223
236
|
|
|
224
237
|
## Sessions
|
|
225
238
|
|
|
226
|
-
Session files are stored under a per-run session directory. With `context: "fork"`, each child starts
|
|
239
|
+
Session files are stored under a per-run session directory. With `context: "fork"`, each child starts from a branched session file produced from the parent's current leaf (foreground children open it in-process; background children receive it as `--session`). That is a real session fork, not an injected summary. An omitted launch `context` that resolves through `defaultContext: fork` uses the same branch when the parent session file and current leaf exist, and otherwise starts fresh.
|
|
227
240
|
|
|
228
241
|
## Completion notifications
|
|
229
242
|
|