@xzzpig/pi-subagents 0.8.0 → 0.10.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 (221) hide show
  1. package/CHANGELOG.md +477 -0
  2. package/README.md +2 -2
  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 +1 -1
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +195 -39
  12. package/docs/configuration.md +81 -22
  13. package/docs/extension-api.md +69 -14
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +32 -9
  16. package/docs/observability.md +22 -20
  17. package/docs/tool-reference.md +123 -14
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +142 -4
  20. package/install.mjs +1 -1
  21. package/package.json +7 -6
  22. package/prompts/review-loop.md +2 -2
  23. package/skills/council-mode/SKILL.md +48 -243
  24. package/skills/council-mode/references/pass-contracts.md +150 -0
  25. package/skills/pi-subagents/SKILL.md +89 -35
  26. package/skills/pi-subagents/references/constraints-and-recipes.md +30 -234
  27. package/skills/pi-subagents/references/execution-controls.md +91 -15
  28. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +13 -1
  30. package/skills/pi-subagents/references/prompting-and-roles.md +59 -31
  31. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  32. package/src/agents/agent-management.ts +384 -115
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +14 -2
  35. package/src/agents/agents.ts +935 -372
  36. package/src/agents/builtin-names.ts +6 -0
  37. package/src/agents/runtime-agent-events.ts +70 -0
  38. package/src/agents/runtime-agent-registry.ts +42 -21
  39. package/src/api/agents.ts +10 -5
  40. package/src/api/background-work.ts +12 -3
  41. package/src/api/capability-ceiling.ts +0 -1
  42. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  43. package/src/api/delegation.ts +0 -7
  44. package/src/api/external-runs.ts +67 -4
  45. package/src/api/preflight.ts +77 -21
  46. package/src/api/shared-types.ts +6 -0
  47. package/src/extension/config.ts +90 -0
  48. package/src/extension/doctor.ts +5 -13
  49. package/src/extension/fanout-child.ts +14 -14
  50. package/src/extension/index.ts +115 -37
  51. package/src/extension/public-execution.ts +103 -15
  52. package/src/extension/rpc.ts +120 -25
  53. package/src/extension/schemas.ts +65 -29
  54. package/src/extension/tool-description.ts +48 -26
  55. package/src/inspectors/herdr/actions.ts +2 -1
  56. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  57. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  58. package/src/integrations/herdr-status.ts +51 -3
  59. package/src/intercom/native-supervisor-channel.ts +138 -60
  60. package/src/intercom/result-intercom.ts +7 -0
  61. package/src/intercom/supervisor-ui.ts +243 -0
  62. package/src/profiles/profiles.ts +5 -6
  63. package/src/runs/background/active-async-capacity.ts +103 -18
  64. package/src/runs/background/async-execution.ts +417 -133
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +60 -28
  67. package/src/runs/background/async-retention.ts +20 -3
  68. package/src/runs/background/async-status-snapshot.ts +23 -261
  69. package/src/runs/background/async-status.ts +204 -14
  70. package/src/runs/background/auto-drain.ts +1 -1
  71. package/src/runs/background/chain-append.ts +8 -3
  72. package/src/runs/background/chain-root-attachment.ts +74 -8
  73. package/src/runs/background/control-channel.ts +4 -205
  74. package/src/runs/background/fleet-view.ts +38 -22
  75. package/src/runs/background/inspect-rpc.ts +8 -8
  76. package/src/runs/background/notify.ts +238 -12
  77. package/src/runs/background/process-terminal.ts +16 -0
  78. package/src/runs/background/result-delivery-ownership.ts +45 -0
  79. package/src/runs/background/result-files.ts +28 -14
  80. package/src/runs/background/result-watcher.ts +39 -16
  81. package/src/runs/background/resume-guidance.ts +2 -2
  82. package/src/runs/background/retained-children.ts +1 -1
  83. package/src/runs/background/run-child-session.ts +613 -0
  84. package/src/runs/background/run-status.ts +84 -17
  85. package/src/runs/background/runner-aliases.ts +125 -0
  86. package/src/runs/background/runner-child-sessions.ts +31 -0
  87. package/src/runs/background/scheduled-runs.ts +174 -18
  88. package/src/runs/background/stale-run-reconciler.ts +10 -4
  89. package/src/runs/background/steering.ts +8 -15
  90. package/src/runs/background/subagent-runner.ts +718 -1161
  91. package/src/runs/background/subagent-wait.ts +86 -31
  92. package/src/runs/background/terminal-run-index.ts +1 -1
  93. package/src/runs/background/wait-completions.ts +43 -2
  94. package/src/runs/background/wait-config.ts +23 -9
  95. package/src/runs/background/wait-tool.ts +26 -19
  96. package/src/runs/foreground/async-steering-action.ts +3 -19
  97. package/src/runs/foreground/execution.ts +489 -499
  98. package/src/runs/foreground/foreground-control.ts +13 -0
  99. package/src/runs/foreground/foreground-history.ts +23 -1
  100. package/src/runs/foreground/subagent-executor.ts +1223 -402
  101. package/src/runs/foreground/workflow-detach-reconcile.ts +140 -115
  102. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  103. package/src/runs/shared/abort-recovery.ts +119 -0
  104. package/src/runs/shared/acceptance.ts +138 -36
  105. package/src/runs/shared/async-status-projection.ts +565 -0
  106. package/src/runs/shared/background-process-options.ts +9 -0
  107. package/src/runs/shared/capability-ceiling.ts +2 -2
  108. package/src/runs/shared/child-hooks.ts +25 -0
  109. package/src/runs/shared/child-identity.ts +32 -6
  110. package/src/runs/shared/child-launch-plan.ts +151 -0
  111. package/src/runs/shared/child-launch.ts +364 -0
  112. package/src/runs/shared/child-lifecycle.ts +25 -0
  113. package/src/runs/shared/child-runtime-config.ts +126 -0
  114. package/src/runs/shared/child-session.ts +366 -0
  115. package/src/runs/shared/child-tool-plan.ts +632 -0
  116. package/src/runs/shared/claude-code-adapter.ts +133 -0
  117. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  118. package/src/runs/shared/completion-evidence.ts +89 -0
  119. package/src/runs/shared/completion-guard.ts +6 -5
  120. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  121. package/src/runs/shared/dynamic-fanout.ts +3 -3
  122. package/src/runs/shared/external-cli-contract.ts +167 -0
  123. package/src/runs/shared/external-cli-preflight.ts +138 -0
  124. package/src/runs/shared/external-cli-runner.ts +348 -55
  125. package/src/runs/shared/fast-mode-extension.ts +5 -5
  126. package/src/runs/shared/host-step-status.ts +231 -0
  127. package/src/runs/shared/lane-metadata.ts +126 -0
  128. package/src/runs/shared/launch-cwd.ts +16 -0
  129. package/src/runs/shared/long-running-guard.ts +2 -1
  130. package/src/runs/shared/mcp-config-sources.ts +422 -0
  131. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  132. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  133. package/src/runs/shared/model-exclusions.ts +139 -9
  134. package/src/runs/shared/model-fallback.ts +146 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +99 -77
  137. package/src/runs/shared/nested-path.ts +0 -14
  138. package/src/runs/shared/nested-render.ts +9 -5
  139. package/src/runs/shared/orca-progress-tabs.ts +12 -7
  140. package/src/runs/shared/parallel-handoff.ts +423 -7
  141. package/src/runs/shared/parallel-utils.ts +20 -7
  142. package/src/runs/shared/permissions.ts +1 -14
  143. package/src/runs/shared/pi-spawn.ts +69 -35
  144. package/src/runs/shared/process-signal.ts +16 -0
  145. package/src/runs/shared/run-fanout-budget.ts +0 -13
  146. package/src/runs/shared/run-history.ts +21 -1
  147. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  148. package/src/runs/shared/sandbox-profile-guard.ts +85 -0
  149. package/src/runs/shared/sandbox-startup-diagnostics.ts +54 -0
  150. package/src/runs/shared/single-output.ts +89 -22
  151. package/src/runs/shared/structured-output.ts +49 -9
  152. package/src/runs/shared/subagent-control.ts +6 -2
  153. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  154. package/src/runs/shared/task-intent.ts +21 -7
  155. package/src/runs/shared/tool-availability.ts +18 -62
  156. package/src/runs/shared/tool-budget.ts +0 -14
  157. package/src/runs/shared/tool-timeout.ts +1 -1
  158. package/src/runs/shared/workflow-graph.ts +16 -0
  159. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  160. package/src/runs/shared/worktree.ts +571 -62
  161. package/src/shared/atomic-json.ts +3 -1
  162. package/src/shared/child-session-name.ts +46 -0
  163. package/src/shared/extension-context.ts +24 -0
  164. package/src/shared/fork-context.ts +21 -12
  165. package/src/shared/fork-session-cwd.ts +27 -0
  166. package/src/shared/formatters.ts +18 -3
  167. package/src/shared/jsonl-writer.ts +11 -0
  168. package/src/shared/launch-contract.ts +11 -1
  169. package/src/shared/pruned-fork.ts +450 -0
  170. package/src/shared/sandbox-profile.ts +23 -0
  171. package/src/shared/session-file-trust.ts +19 -0
  172. package/src/shared/session-tokens.ts +14 -3
  173. package/src/shared/settings.ts +19 -105
  174. package/src/shared/shortcuts.ts +17 -0
  175. package/src/shared/thinking-ceiling.ts +0 -6
  176. package/src/shared/types.ts +545 -70
  177. package/src/shared/utils.ts +60 -93
  178. package/src/shared/workflow-child-permit.ts +207 -0
  179. package/src/slash/delegation-adapters.ts +1 -9
  180. package/src/slash/delegation-request.ts +0 -4
  181. package/src/slash/prompt-template-bridge.ts +37 -1
  182. package/src/slash/slash-bridge.ts +1 -2
  183. package/src/slash/slash-commands.ts +383 -116
  184. package/src/slash/slash-live-state.ts +22 -11
  185. package/src/slash/subagents-admin.ts +29 -12
  186. package/src/tui/fleet-native-transcript.ts +4 -0
  187. package/src/tui/fleet-status.ts +217 -82
  188. package/src/tui/fleet-transcript.ts +11 -5
  189. package/src/tui/fleet.ts +54 -28
  190. package/src/tui/render-helpers.ts +31 -0
  191. package/src/tui/render.ts +1429 -163
  192. package/src/watchdog/change-signature.ts +40 -1
  193. package/src/watchdog/child-status.ts +54 -34
  194. package/src/watchdog/diff-tool.ts +77 -0
  195. package/src/watchdog/emission-guard.ts +5 -3
  196. package/src/watchdog/guidance.ts +20 -0
  197. package/src/watchdog/register-child.ts +28 -25
  198. package/src/watchdog/register-main.ts +10 -9
  199. package/src/watchdog/render.ts +4 -5
  200. package/src/watchdog/review.ts +15 -4
  201. package/src/watchdog/rules.ts +70 -0
  202. package/src/watchdog/runtime.ts +75 -92
  203. package/src/watchdog/scope.ts +0 -11
  204. package/src/watchdog/settings.ts +48 -104
  205. package/src/watchdog/turn-delta.ts +1 -1
  206. package/src/watchdog/types.ts +18 -32
  207. package/src/watchdog/warning-format.ts +0 -1
  208. package/src/workflows/chat-progress.ts +7 -3
  209. package/src/workflows/host-command.ts +235 -0
  210. package/src/workflows/scripted-workflow.ts +988 -59
  211. package/src/workflows/workflow-checklist.ts +439 -0
  212. package/src/workflows/workflow-child-summary.ts +121 -0
  213. package/src/workflows/workflow-preflight.ts +297 -0
  214. package/src/workflows/workflow-receipt.ts +232 -6
  215. package/src/workflows/workflow-resources.ts +150 -0
  216. package/src/workflows/workflow-settlement.ts +246 -0
  217. package/src/runs/shared/child-protocol.ts +0 -401
  218. package/src/runs/shared/pi-args.ts +0 -935
  219. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  220. package/src/runs/shared/turn-budget.ts +0 -98
  221. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -1,22 +1,20 @@
1
1
  import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
3
  import { fileURLToPath } from "node:url";
4
- 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";
5
5
  import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
6
6
  import { buildSkillInjection, normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
7
7
  import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
8
- import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-fallback.ts";
8
+ import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, resolveModelOrigin, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-fallback.ts";
9
9
  import { resolveModelScopesForAgent } from "../runs/shared/model-scope.ts";
10
- import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } from "../runs/shared/pi-args.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, decodeThinkingCeiling, intersectThinkingCeilings, SUBAGENT_THINKING_CEILING_ENV, type ThinkingLevel } from "../shared/thinking-ceiling.ts";
14
+ import { assertThinkingWithinCeiling, intersectThinkingCeilings, type ThinkingLevel } from "../shared/thinking-ceiling.ts";
15
15
  import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
16
16
  import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
17
- import { appendTurnBudgetSystemPrompt } from "../runs/shared/turn-budget.ts";
18
17
  import { resolvePermissionRules } from "../runs/shared/permissions.ts";
19
- import type { ResolvedTurnBudget } from "../shared/types.ts";
20
18
  import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
21
19
  import { resolveStepBehavior } from "../shared/settings.ts";
22
20
  import { canPreferForkFromSnapshot, resolveSubagentLaunchContext } from "../shared/fork-context.ts";
@@ -40,10 +38,14 @@ export type SubagentLaunchContractReasonCode =
40
38
  | "unsupported_mode"
41
39
  | "restricted_agent"
42
40
  | "thinking_ceiling"
43
- | "invalid_extension_bindings";
41
+ | "invalid_extension_bindings"
42
+ | "untrusted_project"
43
+ | "sandbox_unavailable";
44
+
45
+ export type SubagentLaunchContractDiagnosticCode = SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning" | "workspace_scope_authority";
44
46
 
45
47
  export interface SubagentLaunchContractDiagnostic {
46
- code: SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning";
48
+ code: SubagentLaunchContractDiagnosticCode;
47
49
  severity: "error" | "warning" | "host-required";
48
50
  message: string;
49
51
  }
@@ -67,7 +69,6 @@ export interface SubagentLaunchContractInput {
67
69
  outputMode?: OutputMode;
68
70
  outputSchema?: JsonSchemaObject;
69
71
  extensionBindings?: ExtensionBindings;
70
- turnBudget?: ResolvedTurnBudget;
71
72
  artifacts?: boolean;
72
73
  artifactDir?: ArtifactDirPreference;
73
74
  parentSessionFile?: string | null;
@@ -80,6 +81,10 @@ export interface SubagentLaunchContractInput {
80
81
  nestedRootRunId?: string;
81
82
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
82
83
  inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
84
+ /** Host-affirmed trust state for a project-scoped profile selection. */
85
+ projectTrusted?: boolean;
86
+ /** Exact trusted project cwd. When omitted, an affirmative trust assertion applies only to `cwd`. */
87
+ trustedProjectCwd?: string;
83
88
  }
84
89
 
85
90
  export interface SubagentLaunchContractAgentCandidate {
@@ -112,6 +117,7 @@ export interface SubagentLaunchContractSkills {
112
117
  export interface SubagentLaunchContractTools {
113
118
  requestedBuiltin: string[];
114
119
  declaredBuiltin: string[];
120
+ excludeTools?: string[];
115
121
  effectiveAllowlist: string[];
116
122
  explicitAllowlist: boolean;
117
123
  requiredChildTools: string[];
@@ -155,8 +161,10 @@ export interface SubagentLaunchContract {
155
161
  modelCandidates: string[];
156
162
  thinking?: string;
157
163
  thinkingCeiling?: ThinkingLevel;
164
+ sandbox?: string;
158
165
  systemPromptMode: AgentConfig["systemPromptMode"];
159
166
  inheritProjectContext: boolean;
167
+ inheritGlobalContext: boolean;
160
168
  inheritSkills: boolean;
161
169
  skills: SubagentLaunchContractSkills;
162
170
  tools: SubagentLaunchContractTools;
@@ -208,8 +216,25 @@ function resolveLaunchContractContext(input: SubagentLaunchContractInput, agent:
208
216
  });
209
217
  }
210
218
 
211
- function candidateList(inputAgent: string, selected: AgentConfig | undefined, cwd: string): SubagentLaunchContractAgentCandidate[] {
212
- const all = discoverAgentsAll(cwd);
219
+ function taskWorkspaceScopeAuthorityDiagnostic(task: string | undefined): SubagentLaunchContractDiagnostic | undefined {
220
+ if (!task) return undefined;
221
+ const text = task.replace(/\s+/g, " ").trim();
222
+ if (!text) return undefined;
223
+ const createsWorkspacePackage = /\b(?:add|create|introduce|make|set up)\b.{0,80}\b(?:new\s+)?(?:workspace\s+)?package\b/i.test(text)
224
+ || /\b(?:new\s+)?package\b.{0,80}\b(?:workspace|monorepo)\b/i.test(text);
225
+ if (!createsWorkspacePackage) return undefined;
226
+ 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)
227
+ || /\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)
228
+ || /\bwithout\b.{0,40}\b(?:root|workspace|lockfile|metadata)\b.{0,40}\b(?:edit|change|modification|write)s?\b/i.test(text);
229
+ if (!packageOnlyAuthority) return undefined;
230
+ return {
231
+ code: "workspace_scope_authority",
232
+ severity: "warning",
233
+ 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.",
234
+ };
235
+ }
236
+
237
+ function candidateList(inputAgent: string, selected: AgentConfig | undefined, all: AgentDiscoveryAllResult): SubagentLaunchContractAgentCandidate[] {
213
238
  return [...all.builtin, ...all.package, ...all.user, ...all.project]
214
239
  .filter((agent) => Boolean(resolveAgentName(inputAgent, [agent]).agent))
215
240
  .map((agent) => ({
@@ -225,6 +250,8 @@ function candidateList(inputAgent: string, selected: AgentConfig | undefined, cw
225
250
 
226
251
  export async function resolveSubagentLaunchContract(input: SubagentLaunchContractInput): Promise<SubagentLaunchContractResult> {
227
252
  const diagnostics: SubagentLaunchContractDiagnostic[] = [];
253
+ const authorityDiagnostic = taskWorkspaceScopeAuthorityDiagnostic(input.task);
254
+ if (authorityDiagnostic) diagnostics.push(authorityDiagnostic);
228
255
  const effectiveCwd = path.resolve(input.cwd);
229
256
  try {
230
257
  if (!fs.statSync(effectiveCwd).isDirectory()) {
@@ -241,7 +268,9 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
241
268
  return { ok: false, code: "invalid_artifact_dir", message: `Unsupported artifactDir '${String(input.artifactDir)}'; expected 'project', 'session', or 'temp'.`, diagnostics };
242
269
  }
243
270
  const scope = resolveExecutionAgentScope(input.agentScope);
244
- const discovered = discoverAgents(effectiveCwd, scope);
271
+ const parentProvider = input.preferredProvider ?? input.parentModel?.provider;
272
+ const discovery = discoverAgentSnapshot(effectiveCwd, scope, parentProvider, { includeChains: false });
273
+ const discovered = discovery.effective;
245
274
  const resolvedAgent = resolveAgentName(input.agent, discovered.agents);
246
275
  const ambiguousCandidates = resolvedAgent.error
247
276
  ? discovered.agents.filter((agent) => resolveAgentName(input.agent, [agent]).agent)
@@ -255,9 +284,24 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
255
284
  return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
256
285
  }
257
286
  if (!resolvedAgent.agent) {
258
- return { ok: false, code: "missing_agent", message: `Unknown agent: ${input.agent}`, diagnostics };
287
+ return { ok: false, code: "missing_agent", message: formatUnknownAgentError(input.agent, unknownAgentDiagnosticContext(discovered)), diagnostics };
259
288
  }
260
289
  const agent = resolvedAgent.agent;
290
+ const trustedProjectCwd = input.projectTrusted === true
291
+ ? path.resolve(input.trustedProjectCwd ?? effectiveCwd)
292
+ : undefined;
293
+ if (agent.sandbox && (agent.source === "project" || agent.override?.scope === "project") && input.projectTrusted !== true) {
294
+ const message = `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but the project is not trusted. Trust the project and retry.`;
295
+ return { ok: false, code: "untrusted_project", message, diagnostics: [{ code: "untrusted_project", severity: "error", message }] };
296
+ }
297
+ if (agent.sandbox && (agent.source === "project" || agent.override?.scope === "project") && trustedProjectCwd !== effectiveCwd) {
298
+ const message = `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but cwd '${effectiveCwd}' does not match trusted project cwd '${trustedProjectCwd}'. Launch from the trusted project cwd and retry.`;
299
+ return { ok: false, code: "untrusted_project", message, diagnostics: [{ code: "untrusted_project", severity: "error", message }] };
300
+ }
301
+ if (agent.sandbox && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
302
+ const message = `Agent '${agent.name}' requests sandbox profile '${agent.sandbox}', but runner.type='${agent.runner.type}' cannot load the native pi-sandbox extension.`;
303
+ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
304
+ }
261
305
  let extensionBindings: ExtensionBindings | undefined;
262
306
  try {
263
307
  extensionBindings = normalizeExtensionBindings(input.extensionBindings)?.value;
@@ -300,22 +344,26 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
300
344
  const availableModels = normalizeAvailableModels(input.availableModels);
301
345
  const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
302
346
  const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel);
347
+ const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
303
348
  const primaryModel = externalRunner
304
349
  ? undefined
305
- : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, { scope: modelScopes });
350
+ : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, {
351
+ scope: modelScopes,
352
+ source: modelOrigin === "explicit" ? "explicit" : "inherited",
353
+ });
306
354
  const effectiveThinkingConfig = input.thinking !== undefined ? input.thinking : agent.thinking;
307
355
  const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
308
356
  discovered.maxThinking,
309
357
  input.thinkingCeiling,
310
358
  input.inheritedThinkingCeiling,
311
- decodeThinkingCeiling(process.env[SUBAGENT_THINKING_CEILING_ENV]),
312
359
  );
313
360
  const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinkingConfig, input.thinking !== undefined);
314
361
  const modelCandidates = externalRunner
315
362
  ? []
316
363
  : buildModelCandidates(primaryModel, agent.fallbackModels, availableModels, preferredProvider, {
317
364
  scope: modelScopes,
318
- primaryModelFromParent: inheritsParentModel(input.model, agent.model, input.parentModel),
365
+ primaryModelFromParent: modelOrigin === "inherited" || inheritsParentModel(input.model, agent.model, input.parentModel),
366
+ origin: modelOrigin,
319
367
  })
320
368
  .map((candidate) => applyThinkingSuffix(candidate, effectiveThinkingConfig, input.thinking !== undefined) ?? candidate);
321
369
  if (!externalRunner) {
@@ -334,6 +382,8 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
334
382
  try {
335
383
  toolPlan = resolvePiLaunchToolPlan({
336
384
  tools: agent.tools,
385
+ excludeTools: agent.excludeTools,
386
+ allowNestedSubagents: agent.allowNestedSubagents,
337
387
  extensions: agent.extensions,
338
388
  subagentOnlyExtensions: agent.subagentOnlyExtensions,
339
389
  mcpDirectTools: agent.mcpDirectTools,
@@ -346,11 +396,13 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
346
396
  capabilityCeiling: effectiveCapabilityCeiling,
347
397
  agentName: agent.name,
348
398
  permissionRules,
399
+ sandbox: agent.sandbox,
349
400
  });
350
401
  } catch (error) {
351
402
  const message = error instanceof Error ? error.message : String(error);
352
- diagnostics.push({ code: "denied_required_tool", severity: "error", message });
353
- return { ok: false, code: "denied_required_tool", message, diagnostics };
403
+ const code: SubagentLaunchContractReasonCode = agent.sandbox ? "sandbox_unavailable" : "denied_required_tool";
404
+ diagnostics.push({ code, severity: "error", message });
405
+ return { ok: false, code, message, diagnostics };
354
406
  }
355
407
  const artifactsEnabled = input.artifacts !== false;
356
408
  const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir) : undefined;
@@ -379,9 +431,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
379
431
  const memoryInjection = buildAgentMemoryInjection(agent, effectiveCwd);
380
432
  if (memoryInjection) effectiveSystemPrompt = effectiveSystemPrompt ? `${effectiveSystemPrompt}\n\n${memoryInjection}` : memoryInjection;
381
433
  effectiveSystemPrompt = injectOutputPathSystemPrompt(effectiveSystemPrompt, outputPath, agent);
382
- const turnBudget = input.turnBudget ?? agent.defaultTurnBudget;
383
- effectiveSystemPrompt = appendTurnBudgetSystemPrompt(effectiveSystemPrompt, turnBudget);
384
- const candidates = candidateList(input.agent, agent, effectiveCwd);
434
+ const candidates = candidateList(input.agent, agent, discovery.all);
385
435
  const shadowedCandidates = candidates.filter((candidate) => !candidate.selected);
386
436
  const definitionDigest = agentDefinitionDigest(agent);
387
437
  const contractBase: Omit<SubagentLaunchContract, "digest"> = {
@@ -402,8 +452,10 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
402
452
  modelCandidates,
403
453
  ...(resolveEffectiveThinking(model, effectiveThinkingConfig) ? { thinking: resolveEffectiveThinking(model, effectiveThinkingConfig) } : {}),
404
454
  ...(thinkingCeiling ? { thinkingCeiling } : {}),
455
+ ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
405
456
  systemPromptMode: agent.systemPromptMode,
406
457
  inheritProjectContext: agent.inheritProjectContext,
458
+ inheritGlobalContext: agent.inheritGlobalContext,
407
459
  inheritSkills: agent.inheritSkills,
408
460
  skills: {
409
461
  requested: requestedSkills,
@@ -413,6 +465,7 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
413
465
  tools: {
414
466
  requestedBuiltin: toolPlan.requestedBuiltinTools,
415
467
  declaredBuiltin: toolPlan.declaredBuiltinTools,
468
+ ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
416
469
  effectiveAllowlist: toolPlan.effectiveToolAllowlist,
417
470
  explicitAllowlist: toolPlan.explicitToolAllowlist,
418
471
  requiredChildTools: toolPlan.requiredChildTools,
@@ -459,9 +512,12 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
459
512
  systemPrompt: effectiveSystemPrompt,
460
513
  systemPromptMode: agent.systemPromptMode,
461
514
  inheritProjectContext: agent.inheritProjectContext,
515
+ inheritGlobalContext: agent.inheritGlobalContext,
462
516
  inheritSkills: agent.inheritSkills,
517
+ sandbox: agent.sandbox,
463
518
  skills: requestedSkills,
464
519
  tools: toolPlan.effectiveToolAllowlist,
520
+ ...(toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {}),
465
521
  extensions: toolPlan.extensionArgs,
466
522
  mcpDirectTools: toolPlan.effectiveMcpTools,
467
523
  ...(outputPath ? { outputPath } : {}),
@@ -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"}`);
@@ -6,8 +6,8 @@ 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";
@@ -51,12 +51,8 @@ function createChildSafeState(): SubagentState {
51
51
  };
52
52
  }
53
53
 
54
- function resolveNestedControlRoute(): NestedRoute | undefined {
55
- try {
56
- return resolveNestedRouteFromEnv();
57
- } catch {
58
- return undefined;
59
- }
54
+ function resolveNestedControlRoute(config: ChildRuntimeConfig): NestedRoute | undefined {
55
+ return config.nestedRoute ? resolveInheritedNestedRoute(config.nestedRoute) : undefined;
60
56
  }
61
57
 
62
58
  function nestedControlRouteKey(route: NestedRoute): string {
@@ -145,8 +141,9 @@ function startNestedControlInboxListener(pi: ExtensionAPI, state: SubagentState,
145
141
  return () => clearInterval(timer);
146
142
  }
147
143
 
148
- export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI): void {
149
- 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;
150
147
 
151
148
  const globalStore = globalThis as Record<string, unknown>;
152
149
  const registeredKey = "__piSubagentFanoutChildRegisteredApis";
@@ -158,18 +155,21 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
158
155
  registeredApis.add(pi);
159
156
 
160
157
  const config = loadConfig();
158
+ const waitToolConfig = resolveWaitToolConfig(config.waitTool);
161
159
  const state = createChildSafeState();
162
160
  const executor = createSubagentExecutor({
163
161
  pi,
164
162
  state,
165
163
  config,
166
164
  asyncByDefault: resolveAsyncByDefault(config),
167
- waitToolEnabled: resolveWaitToolConfig(config.waitTool).enabled,
165
+ waitToolEnabled: waitToolConfig.enabled,
166
+ waitToolDefaultTimeoutMs: waitToolConfig.defaultTimeoutMs,
168
167
  tempArtifactsDir: getArtifactsDir(null),
169
168
  getSubagentSessionRoot,
170
169
  expandTilde,
171
170
  discoverAgents,
172
171
  allowMutatingManagementActions: false,
172
+ childRuntime: childConfig,
173
173
  });
174
174
 
175
175
  const params = createSubagentParamsSchema();
@@ -178,8 +178,8 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
178
178
  label: "Subagent",
179
179
  description: [
180
180
  "Delegate to subagents from child-safe fanout mode.",
181
- "Allowed management/control actions: list, get, status, interrupt, resume, steer, doctor.",
182
- "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.",
183
183
  ].join("\n"),
184
184
  parameters: params,
185
185
  async execute(id, params, signal, onUpdate, ctx) {
@@ -188,7 +188,7 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI):
188
188
  };
189
189
 
190
190
  pi.registerTool(tool);
191
- const route = resolveNestedControlRoute();
191
+ const route = resolveNestedControlRoute(childConfig);
192
192
  if (!route) return;
193
193
  const listenerCleanupKey = "__piSubagentFanoutChildNestedControlInboxCleanups";
194
194
  const listenerCleanups = globalStore[listenerCleanupKey] instanceof Map