@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.
Files changed (234) hide show
  1. package/CHANGELOG.md +456 -4
  2. package/README.md +3 -3
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +13 -3
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +154 -42
  12. package/docs/configuration.md +85 -26
  13. package/docs/extension-api.md +81 -16
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +75 -11
  16. package/docs/observability.md +34 -21
  17. package/docs/tool-reference.md +142 -18
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +148 -4
  20. package/index.ts +10 -1
  21. package/install.mjs +1 -1
  22. package/package.json +7 -6
  23. package/prompts/council.md +19 -7
  24. package/prompts/parallel-review.md +5 -1
  25. package/prompts/review-loop.md +11 -7
  26. package/skills/council-mode/SKILL.md +44 -215
  27. package/skills/council-mode/references/pass-contracts.md +150 -0
  28. package/skills/pi-subagents/SKILL.md +90 -32
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
  30. package/skills/pi-subagents/references/execution-controls.md +104 -19
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
  33. package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
  34. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  35. package/src/agents/agent-management.ts +471 -114
  36. package/src/agents/agent-refinements.ts +4 -4
  37. package/src/agents/agent-serializer.ts +16 -4
  38. package/src/agents/agents.ts +1076 -351
  39. package/src/agents/builtin-names.ts +6 -0
  40. package/src/agents/runtime-agent-events.ts +70 -0
  41. package/src/agents/runtime-agent-registry.ts +31 -20
  42. package/src/api/agents.ts +10 -5
  43. package/src/api/background-work.ts +12 -3
  44. package/src/api/capability-ceiling.ts +0 -1
  45. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  46. package/src/api/delegation.ts +0 -7
  47. package/src/api/external-job-provider.ts +10 -1
  48. package/src/api/external-runs.ts +67 -4
  49. package/src/api/preflight.ts +97 -34
  50. package/src/api/project-panes.ts +2 -0
  51. package/src/api/shared-types.ts +6 -0
  52. package/src/extension/config.ts +90 -0
  53. package/src/extension/doctor.ts +15 -13
  54. package/src/extension/fanout-child.ts +17 -16
  55. package/src/extension/index.ts +139 -41
  56. package/src/extension/public-execution.ts +113 -22
  57. package/src/extension/rpc.ts +182 -13
  58. package/src/extension/schemas.ts +63 -21
  59. package/src/extension/tool-description.ts +48 -23
  60. package/src/extension/tool-result.ts +19 -0
  61. package/src/inspectors/herdr/actions.ts +2 -1
  62. package/src/inspectors/herdr/client.ts +3 -3
  63. package/src/inspectors/herdr/focus.ts +55 -0
  64. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  65. package/src/inspectors/herdr/project-panes.ts +228 -44
  66. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  67. package/src/integrations/herdr-status.ts +75 -5
  68. package/src/intercom/native-supervisor-channel.ts +138 -60
  69. package/src/intercom/result-intercom.ts +2 -0
  70. package/src/intercom/supervisor-ui.ts +243 -0
  71. package/src/profiles/profiles.ts +5 -6
  72. package/src/runs/background/active-async-capacity.ts +103 -18
  73. package/src/runs/background/async-execution.ts +492 -125
  74. package/src/runs/background/async-job-tracker.ts +127 -28
  75. package/src/runs/background/async-resume.ts +67 -29
  76. package/src/runs/background/async-retention.ts +21 -4
  77. package/src/runs/background/async-status-snapshot.ts +23 -261
  78. package/src/runs/background/async-status.ts +199 -14
  79. package/src/runs/background/auto-drain.ts +1 -1
  80. package/src/runs/background/chain-append.ts +8 -3
  81. package/src/runs/background/chain-root-attachment.ts +79 -8
  82. package/src/runs/background/control-channel.ts +101 -214
  83. package/src/runs/background/fleet-view.ts +38 -22
  84. package/src/runs/background/inspect-rpc.ts +8 -8
  85. package/src/runs/background/notify.ts +295 -8
  86. package/src/runs/background/process-terminal.ts +16 -0
  87. package/src/runs/background/result-delivery-ownership.ts +45 -0
  88. package/src/runs/background/result-files.ts +28 -14
  89. package/src/runs/background/result-watcher.ts +43 -19
  90. package/src/runs/background/resume-guidance.ts +2 -2
  91. package/src/runs/background/retained-children.ts +1 -1
  92. package/src/runs/background/run-child-session.ts +613 -0
  93. package/src/runs/background/run-status.ts +99 -18
  94. package/src/runs/background/runner-aliases.ts +125 -0
  95. package/src/runs/background/runner-child-sessions.ts +31 -0
  96. package/src/runs/background/scheduled-runs.ts +174 -18
  97. package/src/runs/background/stale-run-reconciler.ts +13 -4
  98. package/src/runs/background/steering.ts +8 -15
  99. package/src/runs/background/subagent-runner.ts +959 -1159
  100. package/src/runs/background/subagent-wait.ts +86 -31
  101. package/src/runs/background/terminal-run-index.ts +1 -1
  102. package/src/runs/background/wait-completions.ts +45 -2
  103. package/src/runs/background/wait-config.ts +23 -9
  104. package/src/runs/background/wait-tool.ts +27 -19
  105. package/src/runs/foreground/async-steering-action.ts +3 -19
  106. package/src/runs/foreground/async-stop-action.ts +23 -2
  107. package/src/runs/foreground/execution.ts +585 -481
  108. package/src/runs/foreground/foreground-control.ts +13 -0
  109. package/src/runs/foreground/foreground-history.ts +26 -3
  110. package/src/runs/foreground/subagent-executor.ts +1549 -410
  111. package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
  112. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  113. package/src/runs/shared/abort-recovery.ts +119 -0
  114. package/src/runs/shared/acceptance.ts +147 -39
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +565 -0
  117. package/src/runs/shared/background-process-options.ts +9 -0
  118. package/src/runs/shared/capability-ceiling.ts +2 -2
  119. package/src/runs/shared/child-hooks.ts +25 -0
  120. package/src/runs/shared/child-identity.ts +62 -0
  121. package/src/runs/shared/child-launch-plan.ts +151 -0
  122. package/src/runs/shared/child-launch.ts +314 -0
  123. package/src/runs/shared/child-lifecycle.ts +25 -0
  124. package/src/runs/shared/child-runtime-config.ts +126 -0
  125. package/src/runs/shared/child-session.ts +342 -0
  126. package/src/runs/shared/child-tool-plan.ts +540 -0
  127. package/src/runs/shared/claude-code-adapter.ts +133 -0
  128. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  129. package/src/runs/shared/completion-evidence.ts +89 -0
  130. package/src/runs/shared/completion-guard.ts +57 -6
  131. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  132. package/src/runs/shared/dynamic-fanout.ts +4 -4
  133. package/src/runs/shared/extension-bindings.ts +78 -0
  134. package/src/runs/shared/external-cli-contract.ts +167 -0
  135. package/src/runs/shared/external-cli-preflight.ts +138 -0
  136. package/src/runs/shared/external-cli-runner.ts +349 -54
  137. package/src/runs/shared/external-job-bridge.ts +53 -37
  138. package/src/runs/shared/external-job-runner.ts +126 -23
  139. package/src/runs/shared/fast-mode-extension.ts +10 -0
  140. package/src/runs/shared/host-step-status.ts +231 -0
  141. package/src/runs/shared/lane-metadata.ts +126 -0
  142. package/src/runs/shared/launch-cwd.ts +16 -0
  143. package/src/runs/shared/long-running-guard.ts +2 -1
  144. package/src/runs/shared/mcp-config-sources.ts +422 -0
  145. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  146. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  147. package/src/runs/shared/model-exclusions.ts +141 -10
  148. package/src/runs/shared/model-fallback.ts +187 -33
  149. package/src/runs/shared/model-scope.ts +106 -39
  150. package/src/runs/shared/mutation-evidence.ts +199 -0
  151. package/src/runs/shared/nested-events.ts +38 -48
  152. package/src/runs/shared/nested-path.ts +0 -14
  153. package/src/runs/shared/nested-render.ts +9 -5
  154. package/src/runs/shared/orca-progress-tabs.ts +83 -16
  155. package/src/runs/shared/parallel-handoff.ts +423 -7
  156. package/src/runs/shared/parallel-utils.ts +28 -5
  157. package/src/runs/shared/permissions.ts +1 -14
  158. package/src/runs/shared/pi-spawn.ts +69 -35
  159. package/src/runs/shared/process-signal.ts +16 -0
  160. package/src/runs/shared/run-fanout-budget.ts +0 -13
  161. package/src/runs/shared/run-history.ts +21 -1
  162. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  163. package/src/runs/shared/single-output.ts +89 -22
  164. package/src/runs/shared/structured-output.ts +61 -7
  165. package/src/runs/shared/subagent-control.ts +6 -2
  166. package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
  167. package/src/runs/shared/task-intent.ts +21 -7
  168. package/src/runs/shared/tool-availability.ts +18 -64
  169. package/src/runs/shared/tool-budget.ts +0 -14
  170. package/src/runs/shared/tool-timeout.ts +1 -1
  171. package/src/runs/shared/workflow-graph.ts +16 -0
  172. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  173. package/src/runs/shared/worktree.ts +571 -62
  174. package/src/shared/atomic-json.ts +3 -1
  175. package/src/shared/child-session-name.ts +46 -0
  176. package/src/shared/extension-context.ts +24 -0
  177. package/src/shared/fork-context.ts +21 -12
  178. package/src/shared/fork-session-cwd.ts +27 -0
  179. package/src/shared/formatters.ts +18 -3
  180. package/src/shared/jsonl-writer.ts +11 -0
  181. package/src/shared/launch-contract.ts +20 -6
  182. package/src/shared/pruned-fork.ts +450 -0
  183. package/src/shared/session-file-trust.ts +19 -0
  184. package/src/shared/session-tokens.ts +14 -3
  185. package/src/shared/settings.ts +21 -102
  186. package/src/shared/shortcuts.ts +17 -0
  187. package/src/shared/thinking-ceiling.ts +46 -0
  188. package/src/shared/types.ts +644 -75
  189. package/src/shared/utils.ts +60 -93
  190. package/src/shared/workflow-child-permit.ts +207 -0
  191. package/src/slash/delegation-adapters.ts +1 -9
  192. package/src/slash/delegation-request.ts +0 -4
  193. package/src/slash/prompt-template-bridge.ts +37 -1
  194. package/src/slash/slash-bridge.ts +1 -2
  195. package/src/slash/slash-commands.ts +383 -116
  196. package/src/slash/slash-live-state.ts +22 -11
  197. package/src/slash/subagents-admin.ts +29 -12
  198. package/src/tui/fleet-native-transcript.ts +4 -0
  199. package/src/tui/fleet-status.ts +278 -90
  200. package/src/tui/fleet-transcript.ts +11 -5
  201. package/src/tui/fleet.ts +54 -28
  202. package/src/tui/render-helpers.ts +31 -0
  203. package/src/tui/render.ts +1433 -166
  204. package/src/watchdog/change-signature.ts +40 -1
  205. package/src/watchdog/child-status.ts +54 -34
  206. package/src/watchdog/diff-tool.ts +77 -0
  207. package/src/watchdog/emission-guard.ts +5 -3
  208. package/src/watchdog/guidance.ts +20 -0
  209. package/src/watchdog/permission-arbiter.ts +59 -52
  210. package/src/watchdog/register-child.ts +28 -25
  211. package/src/watchdog/register-main.ts +10 -9
  212. package/src/watchdog/render.ts +4 -5
  213. package/src/watchdog/review.ts +15 -4
  214. package/src/watchdog/rules.ts +70 -0
  215. package/src/watchdog/runtime.ts +75 -92
  216. package/src/watchdog/scope.ts +0 -11
  217. package/src/watchdog/settings.ts +48 -104
  218. package/src/watchdog/turn-delta.ts +1 -1
  219. package/src/watchdog/types.ts +18 -32
  220. package/src/watchdog/warning-format.ts +0 -1
  221. package/src/workflows/chat-progress.ts +7 -3
  222. package/src/workflows/host-command.ts +235 -0
  223. package/src/workflows/scripted-workflow.ts +1142 -69
  224. package/src/workflows/workflow-checklist.ts +439 -0
  225. package/src/workflows/workflow-child-summary.ts +121 -0
  226. package/src/workflows/workflow-preflight.ts +297 -0
  227. package/src/workflows/workflow-receipt.ts +232 -6
  228. package/src/workflows/workflow-resources.ts +150 -0
  229. package/src/workflows/workflow-settlement.ts +246 -0
  230. package/src/runs/shared/child-protocol.ts +0 -401
  231. package/src/runs/shared/pi-args.ts +0 -858
  232. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  233. package/src/runs/shared/turn-budget.ts +0 -98
  234. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -1,29 +1,30 @@
1
- import { createHash } from "node:crypto";
2
1
  import * as fs from "node:fs";
3
2
  import * as path from "node:path";
4
3
  import { fileURLToPath } from "node:url";
5
- import { discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, resolveAgentName, type AgentConfig, type AgentScope, type AgentSource } from "../agents/agents.ts";
4
+ import { discoverAgentSnapshot, findBlockingAgentDiagnostic, formatUnknownAgentError, resolveAgentName, unknownAgentDiagnosticContext, type AgentConfig, type AgentDiscoveryAllResult, type AgentScope, type AgentSource } from "../agents/agents.ts";
6
5
  import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
7
6
  import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
8
7
  import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
9
- import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-fallback.ts";
10
- import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } from "../runs/shared/pi-args.ts";
8
+ import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, resolveModelOrigin, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-fallback.ts";
9
+ import { resolveModelScopesForAgent } from "../runs/shared/model-scope.ts";
10
+ import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } from "../runs/shared/child-tool-plan.ts";
11
11
  import { injectOutputPathSystemPrompt, normalizeSingleOutputOverride, resolveSingleOutputPath } from "../runs/shared/single-output.ts";
12
12
  import { getArtifactPaths, getArtifactsDir } from "../shared/artifacts.ts";
13
13
  import { resolveEffectiveThinking } from "../shared/model-info.ts";
14
+ import { assertThinkingWithinCeiling, intersectThinkingCeilings, type ThinkingLevel } from "../shared/thinking-ceiling.ts";
14
15
  import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
15
16
  import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
16
- import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
17
- import type { ResolvedTurnBudget } from "../shared/types.ts";
17
+ import { resolvePermissionRules } from "../runs/shared/permissions.ts";
18
18
  import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
19
19
  import { resolveStepBehavior } from "../shared/settings.ts";
20
20
  import { canPreferForkFromSnapshot, resolveSubagentLaunchContext } from "../shared/fork-context.ts";
21
21
  import { loadConfig } from "../extension/config.ts";
22
- import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest } from "../shared/launch-contract.ts";
22
+ import { agentDefinitionDigest, AGENT_DEFINITION_PROJECTION_VERSION, launchBindingDigest, stableJsonDigest } from "../shared/launch-contract.ts";
23
23
  import { DIRS, TEMP_ROOT_DIR } from "../shared/types.ts";
24
24
  import { processTerminalCandidatePath, processTerminalPath } from "../runs/background/process-terminal.ts";
25
25
  import { resultFilePath } from "../runs/background/result-files.ts";
26
26
  import { nestedResultsPath } from "../runs/shared/nested-events.ts";
27
+ import { normalizeExtensionBindings, type ExtensionBindings } from "../runs/shared/extension-bindings.ts";
27
28
 
28
29
  export const SUBAGENT_LAUNCH_CONTRACT_VERSION = 2 as const;
29
30
 
@@ -35,10 +36,14 @@ export type SubagentLaunchContractReasonCode =
35
36
  | "invalid_artifact_dir"
36
37
  | "invalid_cwd"
37
38
  | "unsupported_mode"
38
- | "restricted_agent";
39
+ | "restricted_agent"
40
+ | "thinking_ceiling"
41
+ | "invalid_extension_bindings";
42
+
43
+ export type SubagentLaunchContractDiagnosticCode = SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning" | "workspace_scope_authority";
39
44
 
40
45
  export interface SubagentLaunchContractDiagnostic {
41
- code: SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning";
46
+ code: SubagentLaunchContractDiagnosticCode;
42
47
  severity: "error" | "warning" | "host-required";
43
48
  message: string;
44
49
  }
@@ -50,7 +55,10 @@ export interface SubagentLaunchContractInput {
50
55
  agentScope?: AgentScope;
51
56
  context?: "fresh" | "fork";
52
57
  model?: string;
58
+ fast?: boolean;
53
59
  thinking?: string | false;
60
+ thinkingCeiling?: ThinkingLevel;
61
+ inheritedThinkingCeiling?: ThinkingLevel;
54
62
  parentModel?: ParentModel;
55
63
  availableModels?: ReadonlyArray<AvailableModelInfo | { provider: string; id: string; fullId?: string; reasoning?: boolean }>;
56
64
  preferredProvider?: string;
@@ -58,7 +66,7 @@ export interface SubagentLaunchContractInput {
58
66
  output?: string | boolean;
59
67
  outputMode?: OutputMode;
60
68
  outputSchema?: JsonSchemaObject;
61
- turnBudget?: ResolvedTurnBudget;
69
+ extensionBindings?: ExtensionBindings;
62
70
  artifacts?: boolean;
63
71
  artifactDir?: ArtifactDirPreference;
64
72
  parentSessionFile?: string | null;
@@ -103,6 +111,7 @@ export interface SubagentLaunchContractSkills {
103
111
  export interface SubagentLaunchContractTools {
104
112
  requestedBuiltin: string[];
105
113
  declaredBuiltin: string[];
114
+ excludeTools?: string[];
106
115
  effectiveAllowlist: string[];
107
116
  explicitAllowlist: boolean;
108
117
  requiredChildTools: string[];
@@ -145,8 +154,10 @@ export interface SubagentLaunchContract {
145
154
  model?: string;
146
155
  modelCandidates: string[];
147
156
  thinking?: string;
157
+ thinkingCeiling?: ThinkingLevel;
148
158
  systemPromptMode: AgentConfig["systemPromptMode"];
149
159
  inheritProjectContext: boolean;
160
+ inheritGlobalContext: boolean;
150
161
  inheritSkills: boolean;
151
162
  skills: SubagentLaunchContractSkills;
152
163
  tools: SubagentLaunchContractTools;
@@ -178,20 +189,8 @@ function packageVersion(): string {
178
189
  }
179
190
  }
180
191
 
181
- function stableJson(value: unknown): string {
182
- if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
183
- if (value && typeof value === "object") {
184
- return `{${Object.entries(value as Record<string, unknown>)
185
- .filter(([, entry]) => entry !== undefined)
186
- .sort(([a], [b]) => a.localeCompare(b))
187
- .map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`)
188
- .join(",")}}`;
189
- }
190
- return JSON.stringify(value);
191
- }
192
-
193
192
  function digestContract(contract: Omit<SubagentLaunchContract, "digest">): string {
194
- return createHash("sha256").update(stableJson(contract)).digest("hex");
193
+ return stableJsonDigest(contract);
195
194
  }
196
195
 
197
196
  function normalizeAvailableModels(models: SubagentLaunchContractInput["availableModels"]): AvailableModelInfo[] {
@@ -210,8 +209,25 @@ function resolveLaunchContractContext(input: SubagentLaunchContractInput, agent:
210
209
  });
211
210
  }
212
211
 
213
- function candidateList(inputAgent: string, selected: AgentConfig | undefined, cwd: string): SubagentLaunchContractAgentCandidate[] {
214
- const all = discoverAgentsAll(cwd);
212
+ function taskWorkspaceScopeAuthorityDiagnostic(task: string | undefined): SubagentLaunchContractDiagnostic | undefined {
213
+ if (!task) return undefined;
214
+ const text = task.replace(/\s+/g, " ").trim();
215
+ if (!text) return undefined;
216
+ const createsWorkspacePackage = /\b(?:add|create|introduce|make|set up)\b.{0,80}\b(?:new\s+)?(?:workspace\s+)?package\b/i.test(text)
217
+ || /\b(?:new\s+)?package\b.{0,80}\b(?:workspace|monorepo)\b/i.test(text);
218
+ if (!createsWorkspacePackage) return undefined;
219
+ const packageOnlyAuthority = /\b(?:only|solely)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:package(?:\s+directory)?|packages\/[\w.-]+)\b/i.test(text)
220
+ || /\b(?:do not|don't|must not)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:root|workspace|lockfile|metadata)\b/i.test(text)
221
+ || /\bwithout\b.{0,40}\b(?:root|workspace|lockfile|metadata)\b.{0,40}\b(?:edit|change|modification|write)s?\b/i.test(text);
222
+ if (!packageOnlyAuthority) return undefined;
223
+ return {
224
+ code: "workspace_scope_authority",
225
+ severity: "warning",
226
+ message: "Task asks for a workspace package change while limiting authority to package-scope edits. New workspace packages often need root workspace metadata or lockfile changes, so confirm that authority before launch.",
227
+ };
228
+ }
229
+
230
+ function candidateList(inputAgent: string, selected: AgentConfig | undefined, all: AgentDiscoveryAllResult): SubagentLaunchContractAgentCandidate[] {
215
231
  return [...all.builtin, ...all.package, ...all.user, ...all.project]
216
232
  .filter((agent) => Boolean(resolveAgentName(inputAgent, [agent]).agent))
217
233
  .map((agent) => ({
@@ -227,6 +243,8 @@ function candidateList(inputAgent: string, selected: AgentConfig | undefined, cw
227
243
 
228
244
  export async function resolveSubagentLaunchContract(input: SubagentLaunchContractInput): Promise<SubagentLaunchContractResult> {
229
245
  const diagnostics: SubagentLaunchContractDiagnostic[] = [];
246
+ const authorityDiagnostic = taskWorkspaceScopeAuthorityDiagnostic(input.task);
247
+ if (authorityDiagnostic) diagnostics.push(authorityDiagnostic);
230
248
  const effectiveCwd = path.resolve(input.cwd);
231
249
  try {
232
250
  if (!fs.statSync(effectiveCwd).isDirectory()) {
@@ -243,7 +261,9 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
243
261
  return { ok: false, code: "invalid_artifact_dir", message: `Unsupported artifactDir '${String(input.artifactDir)}'; expected 'project', 'session', or 'temp'.`, diagnostics };
244
262
  }
245
263
  const scope = resolveExecutionAgentScope(input.agentScope);
246
- const discovered = discoverAgents(effectiveCwd, scope);
264
+ const parentProvider = input.preferredProvider ?? input.parentModel?.provider;
265
+ const discovery = discoverAgentSnapshot(effectiveCwd, scope, parentProvider, { includeChains: false });
266
+ const discovered = discovery.effective;
247
267
  const resolvedAgent = resolveAgentName(input.agent, discovered.agents);
248
268
  const ambiguousCandidates = resolvedAgent.error
249
269
  ? discovered.agents.filter((agent) => resolveAgentName(input.agent, [agent]).agent)
@@ -257,9 +277,18 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
257
277
  return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
258
278
  }
259
279
  if (!resolvedAgent.agent) {
260
- return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
280
+ return { ok: false, code: "missing_agent", message: formatUnknownAgentError(input.agent, unknownAgentDiagnosticContext(discovered)), diagnostics };
261
281
  }
262
282
  const agent = resolvedAgent.agent;
283
+ let extensionBindings: ExtensionBindings | undefined;
284
+ try {
285
+ extensionBindings = normalizeExtensionBindings(input.extensionBindings)?.value;
286
+ } catch (error) {
287
+ return { ok: false, code: "invalid_extension_bindings", message: error instanceof Error ? error.message : String(error), diagnostics };
288
+ }
289
+ if (extensionBindings !== undefined && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
290
+ return { ok: false, code: "unsupported_mode", message: `extensionBindings is not supported for runner.type='${agent.runner.type}'.`, diagnostics };
291
+ }
263
292
  const context = resolveLaunchContractContext(input, agent);
264
293
  if (context === "fork") {
265
294
  diagnostics.push({ code: "host_required", severity: "host-required", message: "Exact fork session branching and fork-thinking downgrade checks require Pi host session and model-registry snapshots." });
@@ -291,31 +320,60 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
291
320
 
292
321
  const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
293
322
  const availableModels = normalizeAvailableModels(input.availableModels);
294
- const preferredProvider = input.preferredProvider ?? input.parentModel?.provider;
323
+ const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
324
+ const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel);
325
+ const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
295
326
  const primaryModel = externalRunner
296
327
  ? undefined
297
- : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: discovered.modelScope });
328
+ : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, {
329
+ scope: modelScopes,
330
+ source: modelOrigin === "explicit" ? "explicit" : "inherited",
331
+ });
298
332
  const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
333
+ const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
334
+ discovered.maxThinking,
335
+ input.thinkingCeiling,
336
+ input.inheritedThinkingCeiling,
337
+ );
299
338
  const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
300
339
  const modelCandidates = externalRunner
301
340
  ? []
302
341
  : buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, {
303
- scope: discovered.modelScope,
304
- primaryModelFromParent: inheritsParentModel(input.model, agent.model, input.parentModel),
342
+ scope: modelScopes,
343
+ primaryModelFromParent: modelOrigin === "inherited" || inheritsParentModel(input.model, agent.model, input.parentModel),
344
+ origin: modelOrigin,
305
345
  })
306
346
  .map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
347
+ if (!externalRunner) {
348
+ try {
349
+ assertThinkingWithinCeiling({ model, configThinking: effectiveThinkingConfig, ceiling: thinkingCeiling, agent: agent.name, runId });
350
+ for (const candidate of modelCandidates) assertThinkingWithinCeiling({ model: candidate, configThinking: effectiveThinkingConfig, ceiling: thinkingCeiling, agent: agent.name, runId });
351
+ } catch (error) {
352
+ const message = error instanceof Error ? error.message : String(error);
353
+ diagnostics.push({ code: "thinking_ceiling", severity: "error", message });
354
+ return { ok: false, code: "thinking_ceiling", message, diagnostics };
355
+ }
356
+ }
307
357
  let toolPlan: PiLaunchToolPlan;
358
+ const permissionRules = resolvePermissionRules(loadConfig().permissions, agent.permissions);
359
+ const fast = input.fast ?? agent.fast;
308
360
  try {
309
361
  toolPlan = resolvePiLaunchToolPlan({
310
362
  tools: agent.tools,
363
+ excludeTools: agent.excludeTools,
364
+ allowNestedSubagents: agent.allowNestedSubagents,
311
365
  extensions: agent.extensions,
312
366
  subagentOnlyExtensions: agent.subagentOnlyExtensions,
313
367
  mcpDirectTools: agent.mcpDirectTools,
314
368
  cwd: effectiveCwd,
315
369
  requireReadTool: resolvedSkills.resolved.length > 0,
316
370
  structuredOutput: Boolean(input.outputSchema),
371
+ fast,
372
+ model,
373
+ modelCandidates,
317
374
  capabilityCeiling: effectiveCapabilityCeiling,
318
375
  agentName: agent.name,
376
+ permissionRules,
319
377
  });
320
378
  } catch (error) {
321
379
  const message = error instanceof Error ? error.message : String(error);
@@ -349,9 +407,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
349
407
  const memoryInjection = buildAgentMemoryInjection(agent, effectiveCwd);
350
408
  if (memoryInjection) effectiveSystemPrompt = effectiveSystemPrompt ? `${effectiveSystemPrompt}\n\n${memoryInjection}` : memoryInjection;
351
409
  effectiveSystemPrompt = injectOutputPathSystemPrompt(effectiveSystemPrompt, outputPath, agent);
352
- const turnBudget = input.turnBudget ?? agent.defaultTurnBudget;
353
- effectiveSystemPrompt = appendTurnBudgetSystemPrompt(effectiveSystemPrompt, turnBudget);
354
- const candidates = candidateList(input.agent, agent, effectiveCwd);
410
+ const candidates = candidateList(input.agent, agent, discovery.all);
355
411
  const shadowedCandidates = candidates.filter((candidate) => !candidate.selected);
356
412
  const definitionDigest = agentDefinitionDigest(agent);
357
413
  const contractBase: Omit<SubagentLaunchContract, "digest"> = {
@@ -371,8 +427,10 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
371
427
  ...(model ? { model } : {}),
372
428
  modelCandidates,
373
429
  ...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),
430
+ ...(thinkingCeiling ? { thinkingCeiling } : {}),
374
431
  systemPromptMode: agent.systemPromptMode,
375
432
  inheritProjectContext: agent.inheritProjectContext,
433
+ inheritGlobalContext: agent.inheritGlobalContext,
376
434
  inheritSkills: agent.inheritSkills,
377
435
  skills: {
378
436
  requested: requestedSkills,
@@ -382,6 +440,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
382
440
  tools: {
383
441
  requestedBuiltin: toolPlan.requestedBuiltinTools,
384
442
  declaredBuiltin: toolPlan.declaredBuiltinTools,
443
+ ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
385
444
  effectiveAllowlist: toolPlan.effectiveToolAllowlist,
386
445
  explicitAllowlist: toolPlan.explicitToolAllowlist,
387
446
  requiredChildTools: toolPlan.requiredChildTools,
@@ -423,18 +482,22 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
423
482
  definitionDigest,
424
483
  ...(model ? { model } : {}),
425
484
  modelCandidates,
485
+ ...(fast !== undefined ? { fast } : {}),
426
486
  ...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),
427
487
  systemPrompt: effectiveSystemPrompt,
428
488
  systemPromptMode: agent.systemPromptMode,
429
489
  inheritProjectContext: agent.inheritProjectContext,
490
+ inheritGlobalContext: agent.inheritGlobalContext,
430
491
  inheritSkills: agent.inheritSkills,
431
492
  skills: requestedSkills,
432
493
  tools: toolPlan.effectiveToolAllowlist,
494
+ ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
433
495
  extensions: toolPlan.extensionArgs,
434
496
  mcpDirectTools: toolPlan.effectiveMcpTools,
435
497
  ...(outputPath ? { outputPath } : {}),
436
498
  outputMode: behavior.outputMode,
437
499
  ...(input.outputSchema ? { structuredOutputSchema: input.outputSchema } : {}),
500
+ ...(extensionBindings ? { extensionBindings } : {}),
438
501
  }),
439
502
  };
440
503
  return { ok: true, contract: { ...contractBase, digest: digestContract(contractBase) } };
@@ -10,6 +10,7 @@ export {
10
10
  createProjectPaneManager,
11
11
  openProjectPane,
12
12
  getProjectPaneStatus,
13
+ focusProjectPane,
13
14
  closeProjectPane,
14
15
  readProjectPaneBinding,
15
16
  projectPaneBindingPath,
@@ -21,6 +22,7 @@ export {
21
22
  type CloseProjectPaneOptions,
22
23
  type OpenProjectPaneData,
23
24
  type ProjectPaneStatusData,
25
+ type FocusProjectPaneData,
24
26
  type CloseProjectPaneData,
25
27
  type ProjectPaneRuntime,
26
28
  type ProjectPaneError,
@@ -5,6 +5,8 @@ export {
5
5
  type AcceptanceInput,
6
6
  type AcceptanceLedger,
7
7
  type AcceptanceLevel,
8
+ type AgentCapabilitiesSnapshot,
9
+ type AgentCapabilityRow,
8
10
  type AsyncStartedEvent,
9
11
  type ControlEvent,
10
12
  type Details,
@@ -18,4 +20,8 @@ export {
18
20
  type SubagentResultStatus,
19
21
  type SubagentRunMode,
20
22
  type Usage,
23
+ type ManagedWorktreeProvider,
24
+ type WorktreeNaming,
25
+ type WorktreeProvider,
26
+ type WorkflowResourceProvenanceV1,
21
27
  } from "../shared/types.ts";
@@ -6,7 +6,10 @@ import { FLEET_KEYBINDING_ACTIONS, type ArtifactDirPreference, type ExtensionCon
6
6
  import { validateMissionStoreConfig } from "../missions/store.ts";
7
7
  import { validateAuthorityPolicy } from "../policy/authority.ts";
8
8
  import { getAgentDir } from "../shared/utils.ts";
9
+ import { DEFAULT_MODEL_EXCLUSION_TTL_MS, MAX_MODEL_EXCLUSION_TTL_MS, setDefaultTTL } from "../runs/shared/model-exclusions.ts";
9
10
  import { validatePermissionConfig } from "../runs/shared/permissions.ts";
11
+ import { MAX_ABANDONED_SLOT_RELEASE_AFTER_MS, MIN_ABANDONED_SLOT_RELEASE_AFTER_MS } from "../runs/background/active-async-capacity.ts";
12
+ import { normalizeWorktreeBranchPrefix } from "../runs/shared/worktree.ts";
10
13
 
11
14
  const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
12
15
  const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
@@ -16,6 +19,23 @@ const BASE_KEY_IDS = new Set([
16
19
  ...Object.values(Key).flatMap((value) => typeof value === "string" ? [value.toLowerCase()] : []),
17
20
  ]);
18
21
 
22
+ class PrunedForkConfigError extends Error {}
23
+
24
+ function validateForkContextConfig(value: unknown): void {
25
+ if (value === undefined) return;
26
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.forkContext must be a JSON object");
27
+ const config = value as Record<string, unknown>;
28
+ if (config.mode !== undefined && config.mode !== "full" && config.mode !== "pruned") {
29
+ throw new Error('config.forkContext.mode must be "full" or "pruned"');
30
+ }
31
+ if (config.model !== undefined && (typeof config.model !== "string" || !config.model.trim())) {
32
+ throw new PrunedForkConfigError("config.forkContext.model must be a non-empty string");
33
+ }
34
+ if (config.mode === "pruned" && config.model === undefined) {
35
+ throw new PrunedForkConfigError('config.forkContext.model is required when config.forkContext.mode is "pruned"');
36
+ }
37
+ }
38
+
19
39
  function isValidKeyId(value: string): boolean {
20
40
  if (value !== value.trim()) return false;
21
41
  const parts = value.toLowerCase().split("+");
@@ -62,6 +82,31 @@ function validateArtifactConfig(value: unknown): void {
62
82
  }
63
83
  }
64
84
 
85
+ function validateCapacityConfig(value: unknown): void {
86
+ if (value === undefined) return;
87
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.capacity must be a JSON object");
88
+ const abandonedSlotReleaseAfterMs = (value as Record<string, unknown>).abandonedSlotReleaseAfterMs;
89
+ if (abandonedSlotReleaseAfterMs !== undefined
90
+ && abandonedSlotReleaseAfterMs !== false
91
+ && (typeof abandonedSlotReleaseAfterMs !== "number"
92
+ || !Number.isInteger(abandonedSlotReleaseAfterMs)
93
+ || abandonedSlotReleaseAfterMs < MIN_ABANDONED_SLOT_RELEASE_AFTER_MS
94
+ || abandonedSlotReleaseAfterMs > MAX_ABANDONED_SLOT_RELEASE_AFTER_MS)) {
95
+ throw new Error(`config.capacity.abandonedSlotReleaseAfterMs must be false or an integer from ${MIN_ABANDONED_SLOT_RELEASE_AFTER_MS} to ${MAX_ABANDONED_SLOT_RELEASE_AFTER_MS}`);
96
+ }
97
+ }
98
+
99
+ /** Validate the user-controlled TTL policy before it reaches the exclusion store. */
100
+ // TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
101
+ function validateModelExclusionsConfig(value: unknown): void {
102
+ if (value === undefined) return;
103
+ if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.modelExclusions must be a JSON object");
104
+ const defaultTtlMs = (value as Record<string, unknown>).defaultTtlMs;
105
+ if (defaultTtlMs !== undefined && (typeof defaultTtlMs !== "number" || !Number.isFinite(defaultTtlMs) || defaultTtlMs <= 0 || defaultTtlMs > MAX_MODEL_EXCLUSION_TTL_MS)) {
106
+ throw new Error(`config.modelExclusions.defaultTtlMs must be a finite positive number no greater than ${MAX_MODEL_EXCLUSION_TTL_MS}`);
107
+ }
108
+ }
109
+
65
110
  function validateOrcaProgressTabsConfig(value: unknown): void {
66
111
  if (value === undefined) return;
67
112
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.orcaProgressTabs must be a JSON object");
@@ -94,9 +139,20 @@ function validateMainWindowRendererConfig(value: unknown): void {
94
139
  }
95
140
 
96
141
  function validateConfig(config: Record<string, unknown>): void {
142
+ if (config.worktree !== undefined && typeof config.worktree !== "boolean") {
143
+ throw new Error("config.worktree must be a boolean");
144
+ }
145
+ if (config.worktreeProvider !== undefined && config.worktreeProvider !== "auto" && config.worktreeProvider !== "native" && config.worktreeProvider !== "worktrunk") {
146
+ throw new Error('config.worktreeProvider must be "auto", "native", or "worktrunk"');
147
+ }
148
+ if (config.worktreeBranchPrefix !== undefined) {
149
+ if (typeof config.worktreeBranchPrefix !== "string") throw new Error("config.worktreeBranchPrefix must be a string");
150
+ normalizeWorktreeBranchPrefix(config.worktreeBranchPrefix);
151
+ }
97
152
  if (config.defaultSubagentContext !== undefined && config.defaultSubagentContext !== "fresh" && config.defaultSubagentContext !== "fork") {
98
153
  throw new Error('config.defaultSubagentContext must be "fresh" or "fork"');
99
154
  }
155
+ validateForkContextConfig(config.forkContext);
100
156
  if (config.foregroundDetachShortcut !== undefined
101
157
  && (typeof config.foregroundDetachShortcut !== "string" || !isValidKeyId(config.foregroundDetachShortcut))) {
102
158
  throw new Error("config.foregroundDetachShortcut must be a valid keybinding string such as \"ctrl+b\"");
@@ -119,6 +175,8 @@ function validateConfig(config: Record<string, unknown>): void {
119
175
  validateScheduledRunsConfig(config.scheduledRuns);
120
176
  validateFleetKeybindingsConfig(config.fleetKeybindings);
121
177
  validateArtifactConfig(config.artifactConfig);
178
+ validateCapacityConfig(config.capacity);
179
+ validateModelExclusionsConfig(config.modelExclusions);
122
180
  validateMainWindowRendererConfig(config.mainWindowRenderer);
123
181
  validateOrcaProgressTabsConfig(config.orcaProgressTabs);
124
182
  }
@@ -150,6 +208,28 @@ export function updateConfig(updater: (config: ExtensionConfig) => ExtensionConf
150
208
  return next;
151
209
  }
152
210
 
211
+ /**
212
+ * Resolve the default TTL that the process-wide exclusion store should use.
213
+ *
214
+ * @param config Extension configuration after validation.
215
+ * @returns The configured TTL in milliseconds, or the built-in 24-hour default.
216
+ */
217
+ // TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
218
+ export function resolveModelExclusionTTL(config: Pick<ExtensionConfig, "modelExclusions">): number {
219
+ return config.modelExclusions?.defaultTtlMs ?? DEFAULT_MODEL_EXCLUSION_TTL_MS;
220
+ }
221
+
222
+ /**
223
+ * Apply the configured exclusion policy to the process-wide model store.
224
+ *
225
+ * @param config Extension configuration after validation.
226
+ * @returns Nothing.
227
+ */
228
+ // TEST:test/unit/pi-coding-agent-dir.test.ts[loads and applies model exclusion TTL config]
229
+ export function applyModelExclusionsConfig(config: Pick<ExtensionConfig, "modelExclusions">): void {
230
+ setDefaultTTL(resolveModelExclusionTTL(config), { shortenExisting: config.modelExclusions?.defaultTtlMs !== undefined });
231
+ }
232
+
153
233
  export function resolveAsyncByDefault(config: Pick<ExtensionConfig, "asyncByDefault">): boolean {
154
234
  return config.asyncByDefault !== false;
155
235
  }
@@ -159,6 +239,16 @@ export function loadConfig(): ExtensionConfig {
159
239
  try {
160
240
  return readConfigForUpdate(configPath);
161
241
  } catch (error) {
242
+ if (error instanceof PrunedForkConfigError) throw error;
243
+ // An explicitly requested worktree provider/prefix must not be silently
244
+ // discarded and replaced by the built-in defaults after validation fails.
245
+ try {
246
+ const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
247
+ if (raw && typeof raw === "object" && !Array.isArray(raw)
248
+ && (Object.hasOwn(raw, "worktreeProvider") || Object.hasOwn(raw, "worktreeBranchPrefix"))) throw error;
249
+ } catch (readError) {
250
+ if (readError === error) throw error;
251
+ }
162
252
  console.error(`Failed to load subagent config from '${configPath}':`, error);
163
253
  }
164
254
  return {};
@@ -5,8 +5,8 @@ import { mergeAgentsForScope } from "../agents/agent-selection.ts";
5
5
  import { resolveInjectableAgents } from "./context-injection.ts";
6
6
  import { isAsyncAvailable } from "../runs/background/async-execution.ts";
7
7
  import { formatSpawnBudgetSummary, getSpawnBudgetSnapshot } from "../runs/shared/spawn-budget.ts";
8
- import { getActiveAsyncCapacitySnapshot, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
9
- import { decodeRunFanoutBudgetDescriptor, formatRunFanoutBudget, getRunFanoutBudgetSnapshot, RUN_FANOUT_BUDGET_ENV } from "../runs/shared/run-fanout-budget.ts";
8
+ import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
9
+
10
10
  import { diagnoseIntercomBridge, type IntercomBridgeDiagnostic } from "../intercom/intercom-bridge.ts";
11
11
  import { discoverAvailableSkills, type SkillSource } from "../agents/skills.ts";
12
12
  import {
@@ -189,14 +189,6 @@ function formatSpawnBudgetSection(input: DoctorReportInput): string[] {
189
189
  }
190
190
 
191
191
  function formatRunFanoutSection(input: DoctorReportInput): string[] {
192
- try {
193
- const inherited = decodeRunFanoutBudgetDescriptor(process.env[RUN_FANOUT_BUDGET_ENV]);
194
- if (inherited) {
195
- return [`- usage: ${formatRunFanoutBudget(getRunFanoutBudgetSnapshot(inherited)).replace(/^Run fan-out: /, "")}`, `- root run: ${inherited.rootRunId}`, "- reset boundary: cumulative claims are never released; a new top-level run creates a new budget"];
196
- }
197
- } catch (error) {
198
- return [`- inherited budget: invalid — ${errorText(error)}`];
199
- }
200
192
  const configured = resolveMaxSubagentSpawnsPerRun(input.config.maxSubagentSpawnsPerRun);
201
193
  const source = normalizeMaxSubagentSpawnsPerRun(process.env.PI_SUBAGENT_MAX_SPAWNS_PER_RUN) !== undefined
202
194
  ? "environment"
@@ -208,13 +200,13 @@ function formatActiveAsyncCapacitySection(input: DoctorReportInput): string[] {
208
200
  const limit = resolveMaxActiveAsyncRunsPerSession(input.config.maxActiveAsyncRunsPerSession);
209
201
  const sessionId = input.currentSessionId ?? input.state.currentSessionId;
210
202
  const snapshot = sessionId
211
- ? getActiveAsyncCapacitySnapshot(sessionId, limit, { liveWorkflowRunIds: new Set(input.state.workflowControllers?.keys() ?? []) })
203
+ ? getActiveAsyncCapacitySnapshot(sessionId, limit, { liveWorkflowRunIds: new Set(input.state.workflowControllers?.keys() ?? []), abandonedSlotReleaseAfterMs: resolveAbandonedSlotReleaseAfterMs(input.config.capacity?.abandonedSlotReleaseAfterMs) })
212
204
  : { used: 0, limit: limit ?? 0 };
213
205
  input.state.activeAsyncCapacity = snapshot;
214
206
  return [
215
207
  `- usage: ${snapshot.used}/${snapshot.limit || "unlimited"} used`,
216
208
  "- scope: top-level async runs in the current parent session; foreground and nested workflow children are not charged again",
217
- "- release: terminal logical state plus verified process exit; missing or unknown cleanup proof retains capacity",
209
+ "- release: terminal state plus matching observed process-terminal proof, or abandoned-timeout for failed runs with a dead runner PID and stale activity when enabled; false keeps unknown-proof slots",
218
210
  ];
219
211
  }
220
212
 
@@ -225,7 +217,7 @@ function formatPermissionSystemSection(): string[] {
225
217
  if (trimmed) {
226
218
  lines.push(`- parent session: set (${trimmed})`);
227
219
  } else {
228
- lines.push("- parent session: not set — ask forwarding from subprocess children will not reach a parent UI");
220
+ lines.push("- parent session: not set — ask forwarding from background children will not reach a parent UI");
229
221
  }
230
222
  const isChild = process.env["PI_SUBAGENT_CHILD"] === "1";
231
223
  lines.push(`- subagent process: ${isChild ? "yes (PI_SUBAGENT_CHILD=1)" : "no"}`);
@@ -235,6 +227,13 @@ function formatPermissionSystemSection(): string[] {
235
227
  return lines;
236
228
  }
237
229
 
230
+ function formatWorkflowScriptSection(): string[] {
231
+ return [
232
+ "- helpers: runs.run, runs.all, runs.steer, runs.status, runs.ref/refs, emit, console",
233
+ "- recovery: if runs.all is missing, reload or update pi-subagents; await Promise.all([runs.run(...)]) is also supported",
234
+ ];
235
+ }
236
+
238
237
  export function buildDoctorReport(input: DoctorReportInput): string {
239
238
  const paths = input.paths ?? defaultPaths();
240
239
  const deps = { ...DEFAULT_DEPS, ...input.deps };
@@ -264,6 +263,9 @@ export function buildDoctorReport(input: DoctorReportInput): string {
264
263
  "Active async capacity",
265
264
  ...formatActiveAsyncCapacitySection(input),
266
265
  "",
266
+ "Workflow script",
267
+ ...formatWorkflowScriptSection(),
268
+ "",
267
269
  "Permission system",
268
270
  ...formatPermissionSystemSection(),
269
271
  "",
@@ -6,11 +6,12 @@ import { discoverAgents } from "../agents/agents.ts";
6
6
  import { getArtifactsDir } from "../shared/artifacts.ts";
7
7
  import { createSubagentExecutor, type SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
8
8
  import { resolveWaitToolConfig } from "../runs/background/wait-config.ts";
9
- import { SUBAGENT_CHILD_ENV, SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
10
- import { readNestedControlRequests, resolveNestedRouteFromEnv, type NestedRoute, writeNestedControlResult } from "../runs/shared/nested-events.ts";
9
+ import type { ChildRuntimeConfig } from "../runs/shared/child-runtime-config.ts";
10
+ import { readNestedControlRequests, resolveInheritedNestedRoute, type NestedRoute, writeNestedControlResult } from "../runs/shared/nested-events.ts";
11
11
  import { deliverSubagentIntercomMessageEvent } from "../intercom/result-intercom.ts";
12
12
  import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
13
13
  import { createSubagentParamsSchema } from "./schemas.ts";
14
+ import { finalizeToolResult } from "./tool-result.ts";
14
15
  import { loadConfig, resolveAsyncByDefault } from "./config.ts";
15
16
  import { type Details, type SubagentState } from "../shared/types.ts";
16
17
 
@@ -50,12 +51,8 @@ function createChildSafeState(): SubagentState {
50
51
  };
51
52
  }
52
53
 
53
- function resolveNestedControlRoute(): NestedRoute | undefined {
54
- try {
55
- return resolveNestedRouteFromEnv();
56
- } catch {
57
- return undefined;
58
- }
54
+ function resolveNestedControlRoute(config: ChildRuntimeConfig): NestedRoute | undefined {
55
+ return config.nestedRoute ? resolveInheritedNestedRoute(config.nestedRoute) : undefined;
59
56
  }
60
57
 
61
58
  function nestedControlRouteKey(route: NestedRoute): string {
@@ -144,8 +141,9 @@ function startNestedControlInboxListener(pi: ExtensionAPI, state: SubagentState,
144
141
  return () => clearInterval(timer);
145
142
  }
146
143
 
147
- export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI): void {
148
- if (process.env[SUBAGENT_CHILD_ENV] !== "1" || process.env[SUBAGENT_FANOUT_CHILD_ENV] !== "1") return;
144
+ /** Register the child-side `subagent` tool for fanout-authorized children. */
145
+ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI, childConfig: ChildRuntimeConfig): void {
146
+ if (!childConfig.fanoutChild) return;
149
147
 
150
148
  const globalStore = globalThis as Record<string, unknown>;
151
149
  const registeredKey = "__piSubagentFanoutChildRegisteredApis";
@@ -157,18 +155,21 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
157
155
  registeredApis.add(pi);
158
156
 
159
157
  const config = loadConfig();
158
+ const waitToolConfig = resolveWaitToolConfig(config.waitTool);
160
159
  const state = createChildSafeState();
161
160
  const executor = createSubagentExecutor({
162
161
  pi,
163
162
  state,
164
163
  config,
165
164
  asyncByDefault: resolveAsyncByDefault(config),
166
- waitToolEnabled: resolveWaitToolConfig(config.waitTool).enabled,
165
+ waitToolEnabled: waitToolConfig.enabled,
166
+ waitToolDefaultTimeoutMs: waitToolConfig.defaultTimeoutMs,
167
167
  tempArtifactsDir: getArtifactsDir(null),
168
168
  getSubagentSessionRoot,
169
169
  expandTilde,
170
170
  discoverAgents,
171
171
  allowMutatingManagementActions: false,
172
+ childRuntime: childConfig,
172
173
  });
173
174
 
174
175
  const params = createSubagentParamsSchema();
@@ -177,17 +178,17 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
177
178
  label: "Subagent",
178
179
  description: [
179
180
  "Delegate to subagents from child-safe fanout mode.",
180
- "Allowed management/control actions: list, get, status, interrupt, resume, steer, doctor.",
181
- "Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget) are blocked in this mode.",
181
+ "Allowed management/control actions: list, get, status, lane.status, interrupt, resume, steer, doctor.",
182
+ "Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget, lane.recordMerge, lane.recordSupersession) are blocked in this mode.",
182
183
  ].join("\n"),
183
184
  parameters: params,
184
- execute(id, params, signal, onUpdate, ctx) {
185
- return executor.executePublic(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx);
185
+ async execute(id, params, signal, onUpdate, ctx) {
186
+ return finalizeToolResult(await executor.executePublic(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx));
186
187
  },
187
188
  };
188
189
 
189
190
  pi.registerTool(tool);
190
- const route = resolveNestedControlRoute();
191
+ const route = resolveNestedControlRoute(childConfig);
191
192
  if (!route) return;
192
193
  const listenerCleanupKey = "__piSubagentFanoutChildNestedControlInboxCleanups";
193
194
  const listenerCleanups = globalStore[listenerCleanupKey] instanceof Map