@xzzpig/pi-subagents 0.8.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 (218) hide show
  1. package/CHANGELOG.md +443 -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 +151 -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 +5 -4
  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 +370 -114
  33. package/src/agents/agent-refinements.ts +4 -4
  34. package/src/agents/agent-serializer.ts +12 -2
  35. package/src/agents/agents.ts +919 -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 +31 -20
  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 +48 -18
  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 +57 -21
  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 +2 -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 +366 -128
  65. package/src/runs/background/async-job-tracker.ts +95 -15
  66. package/src/runs/background/async-resume.ts +45 -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 +189 -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 +676 -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 +468 -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 +1172 -400
  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 +314 -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 +342 -0
  115. package/src/runs/shared/child-tool-plan.ts +540 -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 +142 -14
  135. package/src/runs/shared/mutation-evidence.ts +57 -3
  136. package/src/runs/shared/nested-events.ts +38 -48
  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 +15 -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/single-output.ts +89 -22
  149. package/src/runs/shared/structured-output.ts +49 -9
  150. package/src/runs/shared/subagent-control.ts +6 -2
  151. package/src/runs/shared/subagent-prompt-runtime.ts +188 -365
  152. package/src/runs/shared/task-intent.ts +21 -7
  153. package/src/runs/shared/tool-availability.ts +18 -62
  154. package/src/runs/shared/tool-budget.ts +0 -14
  155. package/src/runs/shared/tool-timeout.ts +1 -1
  156. package/src/runs/shared/workflow-graph.ts +16 -0
  157. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  158. package/src/runs/shared/worktree.ts +571 -62
  159. package/src/shared/atomic-json.ts +3 -1
  160. package/src/shared/child-session-name.ts +46 -0
  161. package/src/shared/extension-context.ts +24 -0
  162. package/src/shared/fork-context.ts +21 -12
  163. package/src/shared/fork-session-cwd.ts +27 -0
  164. package/src/shared/formatters.ts +18 -3
  165. package/src/shared/jsonl-writer.ts +11 -0
  166. package/src/shared/launch-contract.ts +8 -1
  167. package/src/shared/pruned-fork.ts +450 -0
  168. package/src/shared/session-file-trust.ts +19 -0
  169. package/src/shared/session-tokens.ts +14 -3
  170. package/src/shared/settings.ts +19 -105
  171. package/src/shared/shortcuts.ts +17 -0
  172. package/src/shared/thinking-ceiling.ts +0 -6
  173. package/src/shared/types.ts +524 -70
  174. package/src/shared/utils.ts +60 -93
  175. package/src/shared/workflow-child-permit.ts +207 -0
  176. package/src/slash/delegation-adapters.ts +1 -9
  177. package/src/slash/delegation-request.ts +0 -4
  178. package/src/slash/prompt-template-bridge.ts +37 -1
  179. package/src/slash/slash-bridge.ts +1 -2
  180. package/src/slash/slash-commands.ts +383 -116
  181. package/src/slash/slash-live-state.ts +22 -11
  182. package/src/slash/subagents-admin.ts +29 -12
  183. package/src/tui/fleet-native-transcript.ts +4 -0
  184. package/src/tui/fleet-status.ts +217 -82
  185. package/src/tui/fleet-transcript.ts +11 -5
  186. package/src/tui/fleet.ts +54 -28
  187. package/src/tui/render-helpers.ts +31 -0
  188. package/src/tui/render.ts +1429 -163
  189. package/src/watchdog/change-signature.ts +40 -1
  190. package/src/watchdog/child-status.ts +54 -34
  191. package/src/watchdog/diff-tool.ts +77 -0
  192. package/src/watchdog/emission-guard.ts +5 -3
  193. package/src/watchdog/guidance.ts +20 -0
  194. package/src/watchdog/register-child.ts +28 -25
  195. package/src/watchdog/register-main.ts +10 -9
  196. package/src/watchdog/render.ts +4 -5
  197. package/src/watchdog/review.ts +15 -4
  198. package/src/watchdog/rules.ts +70 -0
  199. package/src/watchdog/runtime.ts +75 -92
  200. package/src/watchdog/scope.ts +0 -11
  201. package/src/watchdog/settings.ts +48 -104
  202. package/src/watchdog/turn-delta.ts +1 -1
  203. package/src/watchdog/types.ts +18 -32
  204. package/src/watchdog/warning-format.ts +0 -1
  205. package/src/workflows/chat-progress.ts +7 -3
  206. package/src/workflows/host-command.ts +235 -0
  207. package/src/workflows/scripted-workflow.ts +988 -59
  208. package/src/workflows/workflow-checklist.ts +439 -0
  209. package/src/workflows/workflow-child-summary.ts +121 -0
  210. package/src/workflows/workflow-preflight.ts +297 -0
  211. package/src/workflows/workflow-receipt.ts +232 -6
  212. package/src/workflows/workflow-resources.ts +150 -0
  213. package/src/workflows/workflow-settlement.ts +246 -0
  214. package/src/runs/shared/child-protocol.ts +0 -401
  215. package/src/runs/shared/pi-args.ts +0 -935
  216. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  217. package/src/runs/shared/turn-budget.ts +0 -98
  218. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -14,6 +14,8 @@ import type { AuthorityPolicyConfig } from "../policy/authority.ts";
14
14
  import type { ThinkingLevel } from "./model-info.ts";
15
15
  import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
16
16
  import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
17
+ import type { WorkflowChildPermitContext } from "./workflow-child-permit.ts";
18
+ import type { WatchdogWarningDetails } from "../watchdog/types.ts";
17
19
 
18
20
  // ============================================================================
19
21
  // Basic Types
@@ -39,11 +41,43 @@ export interface ChainOutputMapEntry {
39
41
 
40
42
  export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
41
43
 
42
- export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "paused" | "stopped" | "detached" | "rejected";
44
+ export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed" | "partial" | "paused" | "stopped" | "detached" | "rejected";
45
+
46
+ export type HostStepMonitorKind = "command" | "ci" | "gate";
47
+ export type HostStepState = "pending" | "running" | "done" | "cancelled" | "error";
48
+ export type HostStepVerdict = "pass" | "fail" | "inconclusive";
49
+
50
+ export interface HostStepFreshnessV1 {
51
+ expectedRef: string;
52
+ observedRef?: string;
53
+ stale?: boolean;
54
+ }
55
+
56
+ /** Bounded, provider-agnostic status for a host-owned workflow monitor. */
57
+ export interface HostStepNodeV1 {
58
+ version: 1;
59
+ kind: "host-step";
60
+ /** Explicit monitor category; never inferred from labels or commands. */
61
+ monitorKind: HostStepMonitorKind;
62
+ id: string;
63
+ label: string;
64
+ role?: string;
65
+ provider?: string;
66
+ state: HostStepState;
67
+ verdict?: HostStepVerdict;
68
+ reasonCode?: string;
69
+ detail?: string;
70
+ target?: string;
71
+ freshness?: HostStepFreshnessV1;
72
+ reportPath?: string;
73
+ exitCode?: number | null;
74
+ updatedAt: number;
75
+ deadlineAt?: number;
76
+ }
43
77
 
44
78
  export interface WorkflowGraphNode {
45
79
  id: string;
46
- kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
80
+ kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent" | "host-step";
47
81
  agent?: string;
48
82
  phase?: string;
49
83
  label: string;
@@ -63,6 +97,7 @@ export interface WorkflowGraphNode {
63
97
  structured?: boolean;
64
98
  acceptanceStatus?: AcceptanceLedgerStatus;
65
99
  error?: string;
100
+ hostStep?: HostStepNodeV1;
66
101
  }
67
102
 
68
103
  export interface WorkflowGraphSnapshot {
@@ -73,18 +108,104 @@ export interface WorkflowGraphSnapshot {
73
108
  currentNodeId?: string;
74
109
  }
75
110
 
111
+ export type WorkflowPreflightCoverage = "complete" | "partial";
112
+ export type WorkflowPreflightMode = "mutation" | "review" | "scout" | "gate";
113
+
114
+ /** Bounded, display-only lane hints supplied alongside a workflowScript launch. */
115
+ export interface WorkflowPreflightLaneV1 {
116
+ key: string;
117
+ mode?: WorkflowPreflightMode;
118
+ decision?: string;
119
+ claims?: string[];
120
+ expectedOutput?: string;
121
+ independence?: string;
122
+ }
123
+
124
+ /** Versioned, display-only workflow launch plan; it never grants launch authority. */
125
+ export interface WorkflowPreflightV1 {
126
+ version: 1;
127
+ coverage: WorkflowPreflightCoverage;
128
+ lanes: WorkflowPreflightLaneV1[];
129
+ }
130
+
76
131
  export type WorkflowReceiptState = "complete" | "failed" | "paused" | "stopped";
77
132
 
133
+ export type WorkflowTerminalResolution = "settled-awaiting-resume" | "failed-child" | "interrupted-child";
134
+
135
+ export interface WorkflowTerminalOutcome {
136
+ state: "partial";
137
+ reason: "budget_exhausted" | "timeout";
138
+ }
139
+
140
+ export interface WorkflowRecoveryAction {
141
+ key: string;
142
+ call: "runs.run";
143
+ resume: { workflowRunId: string; key: string; latest: true };
144
+ taskRequired: true;
145
+ }
146
+
147
+ /**
148
+ * Bounded, host-generated identity for a resolved pi-subagents workflow resource.
149
+ * Permission/policy extensions can use it to distinguish resolved content from
150
+ * raw workflow scripts. This audit projection never grants execution authority.
151
+ */
152
+ export interface WorkflowResourceProvenanceV1 {
153
+ kind: "workflow";
154
+ name: string;
155
+ version: number;
156
+ invocation: "named";
157
+ expansion: "resolved";
158
+ id: string;
159
+ }
160
+
161
+ /**
162
+ * Bounded, launch-declared workflow lane metadata. This is display and
163
+ * triage information only; capability ceilings, authorization, and cleanup
164
+ * safety remain owned by their existing enforcement and handoff paths.
165
+ */
166
+ export type WorkflowLaneMode = "mutation" | "review" | "scout" | "gate";
167
+
168
+ export interface WorkflowLaneMetadata {
169
+ version: 1;
170
+ key: string;
171
+ mode?: WorkflowLaneMode;
172
+ sourceRef?: string;
173
+ claims?: string[];
174
+ outputPaths?: string[];
175
+ }
176
+
177
+ export interface WorkflowChildSummaryV1 {
178
+ version: 1;
179
+ parentToolCallId: string;
180
+ workflowRunId: string;
181
+ inventoryComplete: boolean;
182
+ workflowState: "queued" | "running" | "completed" | "failed" | "paused" | "stopped";
183
+ children: Array<{
184
+ childId: string;
185
+ runId?: string;
186
+ agent?: string;
187
+ /** Human-readable display name for the child session, when derived at launch. */
188
+ sessionName?: string;
189
+ model?: string;
190
+ thinking?: string;
191
+ state: "pending" | "running" | "completed" | "failed" | "paused" | "stopped" | "rejected" | "detached";
192
+ }>;
193
+ }
194
+
78
195
  type WorkflowReceiptEntryResumability =
79
196
  | { latestRunId: string; resumability: { state: "resumable" } }
80
197
  | { latestRunId?: string; resumability: { state: "not-resumable"; reason: string } };
81
198
 
82
199
  export type WorkflowReceiptEntry = WorkflowReceiptEntryResumability & {
83
200
  key: string;
201
+ lane?: WorkflowLaneMetadata;
202
+ terminalOutcome?: WorkflowTerminalOutcome;
84
203
  agent?: string;
85
204
  requestedContext?: "fresh" | "fork";
86
205
  resolvedContext?: "fresh" | "fork" | "mixed";
87
206
  outputReference?: string;
207
+ acceptanceRecovery?: AcceptanceRecoveryMetadata;
208
+ externalAdapter?: ExternalCliReceiptMetadata;
88
209
  continuation: { runIds: string[] };
89
210
  };
90
211
 
@@ -94,6 +215,12 @@ export interface WorkflowReceipt {
94
215
  state: WorkflowReceiptState;
95
216
  createdAt: number;
96
217
  entries: Record<string, WorkflowReceiptEntry>;
218
+ resource?: WorkflowResourceProvenanceV1;
219
+ hostSteps?: HostStepNodeV1[];
220
+ workflowChildren?: WorkflowChildSummaryV1;
221
+ workflowResolution?: WorkflowTerminalResolution;
222
+ terminalOutcome?: WorkflowTerminalOutcome;
223
+ recovery?: WorkflowRecoveryAction[];
97
224
  }
98
225
 
99
226
  export interface SavedOutputReference {
@@ -120,16 +247,6 @@ export interface Usage {
120
247
  turns: number;
121
248
  }
122
249
 
123
- export interface TurnBudgetConfig {
124
- maxTurns: number;
125
- graceTurns?: number;
126
- }
127
-
128
- export interface ResolvedTurnBudget {
129
- maxTurns: number;
130
- graceTurns: number;
131
- }
132
-
133
250
  export interface ToolBudgetConfig {
134
251
  soft?: number;
135
252
  hard: number;
@@ -152,9 +269,19 @@ export interface ToolBudgetState extends ResolvedToolBudget {
152
269
  blockedTool?: string;
153
270
  }
154
271
 
272
+ /**
273
+ * @deprecated Turn budgets are no longer accepted as launch configuration or
274
+ * enforced. Retained only to decode historical persisted status and result data.
275
+ */
155
276
  export type TurnBudgetOutcome = "within-budget" | "wrap-up-requested" | "termination-deferred" | "exceeded";
156
277
 
157
- export interface TurnBudgetState extends ResolvedTurnBudget {
278
+ /**
279
+ * @deprecated Historical persisted turn-budget state. New runs do not produce
280
+ * this field, but status readers retain it for backwards compatibility.
281
+ */
282
+ export interface TurnBudgetState {
283
+ maxTurns: number;
284
+ graceTurns: number;
158
285
  outcome: TurnBudgetOutcome;
159
286
  turnCount: number;
160
287
  wrapUpRequestedAtTurn?: number;
@@ -166,6 +293,10 @@ export interface TokenUsage {
166
293
  input: number;
167
294
  output: number;
168
295
  total: number;
296
+ /** Input plus cache-read tokens for the latest assistant turn. */
297
+ window?: number;
298
+ /** Largest window observed in this usage scope. */
299
+ windowPeak?: number;
169
300
  }
170
301
 
171
302
  export type ActivityState = "active_long_running" | "needs_attention";
@@ -216,6 +347,8 @@ export interface CompletionBatchConfig {
216
347
 
217
348
  export interface WaitToolConfigObject {
218
349
  enabled?: boolean;
350
+ /** Default blocking window for bg_wait calls that omit timeoutMs. */
351
+ defaultTimeoutMs?: number;
219
352
  }
220
353
 
221
354
  export type WaitToolConfig = boolean | WaitToolConfigObject;
@@ -236,6 +369,7 @@ export interface ControlEvent {
236
369
  tokens?: number;
237
370
  toolCount?: number;
238
371
  currentTool?: string;
372
+ toolCallId?: string;
239
373
  currentToolDurationMs?: number;
240
374
  currentPath?: string;
241
375
  elapsedMs?: number;
@@ -250,6 +384,17 @@ export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped"
250
384
  export type SubagentOutputState = "present" | "absent" | "unknown";
251
385
  export type SubagentRunMode = "single" | "parallel" | "chain" | "workflow";
252
386
  export type SubagentResultMode = SubagentRunMode;
387
+ export type WorktreeProvider = "auto" | "native" | "worktrunk";
388
+ export type ManagedWorktreeProvider = Exclude<WorktreeProvider, "auto">;
389
+
390
+ export interface WorktreeNaming {
391
+ requestedBranch: string;
392
+ branchPrefix: string;
393
+ label: string;
394
+ sanitizedPathComponent: string;
395
+ collision?: "branch" | "path" | "both";
396
+ collisionSuffix?: string;
397
+ }
253
398
 
254
399
  export interface ParallelHandoffPatch {
255
400
  path: string;
@@ -266,6 +411,11 @@ export interface ParallelHandoffChild {
266
411
  index: number;
267
412
  taskIndex: number;
268
413
  agent: string;
414
+ /** Stable workflow identity used to join status/receipt metadata. */
415
+ workflowKey?: string;
416
+ /** Child run id when the worktree belongs to a workflow child. */
417
+ runId?: string;
418
+ lane?: WorkflowLaneMetadata;
269
419
  status: SubagentResultStatus;
270
420
  summary: string;
271
421
  outputPath?: string;
@@ -275,10 +425,23 @@ export interface ParallelHandoffChild {
275
425
  patch: ParallelHandoffPatch;
276
426
  }
277
427
 
428
+ /** Launch-time identity retained while a handoff group has no terminal child rows yet. */
429
+ export interface ParallelHandoffLaneBinding {
430
+ index: number;
431
+ taskIndex: number;
432
+ workflowKey?: string;
433
+ runId?: string;
434
+ lane?: WorkflowLaneMetadata;
435
+ }
436
+
278
437
  export interface ParallelHandoffCleanupTask {
279
438
  index: number;
280
439
  path: string;
281
440
  branch: string;
441
+ /** Provider that allocated this worktree; omitted in old manifests. */
442
+ provider?: ManagedWorktreeProvider;
443
+ /** Branch/path naming evidence retained with the cleanup authority. */
444
+ naming?: WorktreeNaming;
282
445
  worktreeRemoved: boolean;
283
446
  branchRemoved: boolean;
284
447
  preserved?: boolean;
@@ -286,11 +449,38 @@ export interface ParallelHandoffCleanupTask {
286
449
  errors?: string[];
287
450
  }
288
451
 
452
+ export type CleanupEligibility =
453
+ | { state: "active" }
454
+ | { state: "terminal-eligible" }
455
+ | { state: "terminal-blocked"; reason: string }
456
+ | { state: "superseded-eligible" }
457
+ | { state: "unknown" };
458
+
459
+ export interface ParallelHandoffMergeEvidence {
460
+ prNumber: number;
461
+ reviewedHead: string;
462
+ mergeCommit: string;
463
+ treeEquivalent: boolean | "unknown";
464
+ postMergeChecks: "recorded" | "unknown";
465
+ attestedBy: string;
466
+ attestedAt: string;
467
+ manifestDigest?: string;
468
+ }
469
+
470
+ export interface ParallelHandoffSupersessionEvidence {
471
+ supersededBy: string;
472
+ attestedBy: string;
473
+ attestedAt: string;
474
+ manifestDigest?: string;
475
+ }
476
+
289
477
  export interface ParallelHandoffGroup {
290
478
  stepIndex: number;
291
479
  baseCommit: string;
292
480
  repoRoot: string;
293
481
  children: ParallelHandoffChild[];
482
+ /** Optional launch identities for pending groups before child results settle. */
483
+ laneBindings?: ParallelHandoffLaneBinding[];
294
484
  cleanup: {
295
485
  state: "complete" | "partial";
296
486
  tasks: ParallelHandoffCleanupTask[];
@@ -308,6 +498,9 @@ export interface ParallelHandoffManifest {
308
498
  createdAt: number;
309
499
  updatedAt: number;
310
500
  groups: ParallelHandoffGroup[];
501
+ merge?: ParallelHandoffMergeEvidence;
502
+ supersession?: ParallelHandoffSupersessionEvidence;
503
+ cleanupEligibility?: CleanupEligibility;
311
504
  }
312
505
 
313
506
  export interface ParallelHandoffReference {
@@ -317,6 +510,7 @@ export interface ParallelHandoffReference {
317
510
  childCount: number;
318
511
  changedPatches: number;
319
512
  cleanupState: "complete" | "partial";
513
+ cleanupEligibility?: CleanupEligibility;
320
514
  }
321
515
 
322
516
  export interface AgentContract {
@@ -325,7 +519,7 @@ export interface AgentContract {
325
519
 
326
520
  export type ChainGateLayer = "execution" | "acceptance";
327
521
 
328
- export type ExecutionProjectionStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
522
+ export type ExecutionProjectionStatus = "completed" | "failed" | "partial" | "paused" | "stopped" | "detached";
329
523
 
330
524
  export interface ExecutionProjection {
331
525
  status: ExecutionProjectionStatus;
@@ -352,8 +546,24 @@ export interface FileMutationEffect {
352
546
  evidence?: TrackedMutationEvidence;
353
547
  }
354
548
 
549
+ export interface SettlementDiagnostic {
550
+ finalTextPresent: boolean;
551
+ mutation: {
552
+ expected: boolean;
553
+ attempted: boolean;
554
+ observed: boolean;
555
+ };
556
+ requiredOutput?: {
557
+ kind: "file-only" | "structured";
558
+ path: string;
559
+ missing: boolean;
560
+ };
561
+ afterCompactionSettlement?: boolean;
562
+ }
563
+
355
564
  export interface EffectsProjection {
356
565
  fileMutation?: FileMutationEffect;
566
+ settlementDiagnostic?: SettlementDiagnostic;
357
567
  }
358
568
 
359
569
  export interface TrackedMutationSnapshot {
@@ -382,6 +592,10 @@ export interface TimeoutRecoverySummary {
382
592
  termination: "timed-out" | "stopped";
383
593
  changedFiles: string[];
384
594
  truncated?: boolean;
595
+ /** True only when a timed-out child left tracked changes without its requested report. */
596
+ recoveryNeeded?: boolean;
597
+ reason?: "timed-out-with-dirty-worktree";
598
+ reportStatus?: "missing" | "written" | "not-requested" | "unknown";
385
599
  currentTool?: string;
386
600
  currentToolArgs?: string;
387
601
  currentPath?: string;
@@ -392,6 +606,9 @@ export interface TimeoutRecoverySummary {
392
606
  message: string;
393
607
  }
394
608
 
609
+ /** Safe parent-facing subset of a timeout recovery summary. */
610
+ export type TimeoutRecoveryProjection = Pick<TimeoutRecoverySummary, "termination" | "changedFiles" | "truncated" | "recoveryNeeded" | "reason" | "reportStatus">;
611
+
395
612
  export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
396
613
  export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
397
614
 
@@ -570,21 +787,28 @@ export interface SteeringRecoveryDescriptor {
570
787
  agentContract?: AgentContract;
571
788
  agent: string;
572
789
  sessionFile?: string;
790
+ /** Git ref used to allocate managed worktrees for this run. */
791
+ baseRef?: string;
573
792
  cwd: string;
574
793
  model?: string;
575
794
  modelProvider?: string;
576
795
  modelOverrideFromParent?: boolean;
796
+ modelOrigin?: "explicit" | "inherited" | "configured";
577
797
  fallbackModels?: string[];
578
798
  fast?: boolean;
579
799
  thinking?: string;
580
800
  thinkingCeiling?: ThinkingLevel;
581
801
  tools?: string[];
802
+ excludeTools?: string[];
803
+ allowNestedSubagents?: boolean;
582
804
  extensions?: string[];
583
805
  subagentOnlyExtensions?: string[];
584
806
  mcpDirectTools?: string[];
807
+ mutationTools?: string[];
585
808
  systemPrompt?: string;
586
809
  systemPromptMode: "append" | "replace";
587
810
  inheritProjectContext: boolean;
811
+ inheritGlobalContext: boolean;
588
812
  inheritSkills: boolean;
589
813
  skills?: string[];
590
814
  skillPath?: string[];
@@ -600,8 +824,8 @@ export interface SteeringRecoveryDescriptor {
600
824
  context?: "fresh" | "fork";
601
825
  /** Raw per-run bridge override. Omitted descriptors continue to use global config. */
602
826
  intercomBridge?: IntercomBridgeConfig;
827
+ lane?: WorkflowLaneMetadata;
603
828
  absoluteDeadlineAt?: number;
604
- initialTurnBudget?: ResolvedTurnBudget;
605
829
  initialToolBudget?: ResolvedToolBudget;
606
830
  maxSubagentDepth: number;
607
831
  maxOutput?: MaxOutputConfig;
@@ -615,7 +839,7 @@ export interface SteeringRecoveryDescriptor {
615
839
 
616
840
  export type PublicNestedStepSummary = Pick<
617
841
  NestedStepSummary,
618
- "agent" | "status" | "model" | "thinking" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut" | "stopped"
842
+ "agent" | "sessionName" | "status" | "model" | "thinking" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut" | "stopped"
619
843
  > & {
620
844
  children?: PublicNestedRunSummary[];
621
845
  };
@@ -628,7 +852,7 @@ export type CostSummary = {
628
852
 
629
853
  export type PublicNestedRunSummary = Pick<
630
854
  NestedRunSummary,
631
- "id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "agents" | "model" | "thinking" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut" | "stopped" | "turnBudget" | "turnBudgetExceeded" | "wrapUpRequested"
855
+ "id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "sessionName" | "agents" | "model" | "thinking" | "currentStep" | "chainStepCount" | "parallelGroups" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "totalTokens" | "totalCost" | "startedAt" | "endedAt" | "lastUpdate" | "error" | "timeoutMs" | "deadlineAt" | "timedOut" | "stopped" | "turnBudget" | "turnBudgetExceeded" | "wrapUpRequested"
632
856
  > & {
633
857
  steps?: PublicNestedStepSummary[];
634
858
  children?: PublicNestedRunSummary[];
@@ -636,6 +860,8 @@ export type PublicNestedRunSummary = Pick<
636
860
 
637
861
  export interface SubagentResultIntercomChild {
638
862
  agent: string;
863
+ /** Human-readable display name for the child session, when derived at launch. */
864
+ sessionName?: string;
639
865
  /** Process/lifecycle status. It does not establish semantic task completion. */
640
866
  status: SubagentResultStatus;
641
867
  /** Whether the child produced substantive output before its process ended. */
@@ -672,18 +898,26 @@ export interface SubagentResultIntercomPayload {
672
898
  // Progress Tracking
673
899
  // ============================================================================
674
900
 
901
+ export interface ChildWatchdogWarningSummary extends Pick<WatchdogWarningDetails, "severity" | "category" | "summary" | "evidence" | "recommendedAction" | "displayedAt"> {
902
+ /** True when a later assistant turn in the child followed the warning. */
903
+ addressed: boolean;
904
+ stalemate: boolean;
905
+ }
906
+
675
907
  export interface ChildWatchdogProgress {
676
- phase: "idle" | "reviewing" | "autofollow" | "settling" | "stale" | "failed";
908
+ phase: "idle" | "reviewing" | "stale" | "failed";
677
909
  seq: number;
678
910
  lastUpdate: number;
679
- followUpPending: boolean;
680
911
  reason?: string;
681
912
  timedOut?: boolean;
913
+ warnings?: ChildWatchdogWarningSummary[];
682
914
  }
683
915
 
684
916
  export interface AgentProgress {
685
917
  index: number;
686
918
  agent: string;
919
+ /** Human-readable display name for the child's session, when derived at launch. */
920
+ sessionName?: string;
687
921
  status: "pending" | "running" | "completed" | "failed" | "detached";
688
922
  activityState?: ActivityState;
689
923
  task: string;
@@ -703,6 +937,8 @@ export interface AgentProgress {
703
937
  thinking?: string;
704
938
  inputTokens?: number;
705
939
  outputTokens?: number;
940
+ window?: number;
941
+ windowPeak?: number;
706
942
  durationMs: number;
707
943
  error?: string;
708
944
  failedTool?: string;
@@ -717,6 +953,8 @@ export interface ToolCallSummary {
717
953
  interface ProgressSummary {
718
954
  index?: number;
719
955
  agent?: string;
956
+ /** Human-readable display name for the child's session, when derived at launch. */
957
+ sessionName?: string;
720
958
  status?: AgentProgress["status"];
721
959
  activityState?: ActivityState;
722
960
  skills?: string[];
@@ -782,6 +1020,7 @@ export interface AcceptanceReviewGate {
782
1020
 
783
1021
  export interface AcceptanceConfig {
784
1022
  level?: AcceptanceLevel;
1023
+ report?: "on" | "off";
785
1024
  criteria?: Array<string | AcceptanceGate>;
786
1025
  evidence?: AcceptanceEvidenceKind[];
787
1026
  verify?: AcceptanceVerifyCommand[];
@@ -891,6 +1130,18 @@ export type AcceptanceLedgerStatus =
891
1130
  | "reviewed"
892
1131
  | "accepted";
893
1132
 
1133
+ /**
1134
+ * Durable child evidence that can be handed to a read-only review after the
1135
+ * acceptance envelope itself was rejected. This never upgrades acceptance;
1136
+ * the enclosing ledger remains rejected and the child remains unsuccessful.
1137
+ */
1138
+ export interface AcceptanceRecoveryMetadata {
1139
+ status: "available-for-review";
1140
+ reason: "acceptance-metadata-rejected";
1141
+ reportPath: string;
1142
+ reportHash: string;
1143
+ }
1144
+
894
1145
  export interface AcceptanceLedger {
895
1146
  status: AcceptanceLedgerStatus;
896
1147
  evidenceStatus: AcceptanceEvidenceStatus;
@@ -900,6 +1151,7 @@ export interface AcceptanceLedger {
900
1151
  criteria: ResolvedAcceptanceGate[];
901
1152
  childReport?: AcceptanceReport;
902
1153
  childReportParseError?: string;
1154
+ recovery?: AcceptanceRecoveryMetadata;
903
1155
  runtimeChecks: AcceptanceRuntimeCheck[];
904
1156
  verifyRuns: AcceptanceVerifyResult[];
905
1157
  reviewResult?: AcceptanceReviewResult;
@@ -910,15 +1162,6 @@ export interface AcceptanceLedger {
910
1162
  };
911
1163
  }
912
1164
 
913
- export interface ProtocolOutputLimit {
914
- code: "protocol_output_limit";
915
- stream: "stdout" | "stderr";
916
- limitBytes: number;
917
- observedBytes: number;
918
- diagnosticPrefix: string;
919
- diagnosticTail: string;
920
- }
921
-
922
1165
  export interface LaunchResolvedChildExtensionsV1 {
923
1166
  version: 1;
924
1167
  /** This is parent-resolved launch intent, not child-runtime acknowledgement that extensions loaded. */
@@ -975,8 +1218,13 @@ export interface SingleResult {
975
1218
  * result row's array position.
976
1219
  */
977
1220
  index: number;
1221
+ /** Workflow child key that owns this result when returned from workflow details. */
1222
+ workflowKey?: string;
978
1223
  agent: string;
979
1224
  task: string;
1225
+ /** Human-readable display name for the child's own session (agent + task
1226
+ * excerpt), when the launcher derived one. Display metadata only. */
1227
+ sessionName?: string;
980
1228
  /** Resolved launch context for this child. */
981
1229
  context?: "fresh" | "fork";
982
1230
  exitCode: number;
@@ -1008,7 +1256,6 @@ export interface SingleResult {
1008
1256
  * a signal to reduce input size or re-decompose the task.
1009
1257
  */
1010
1258
  contextOverflow?: boolean;
1011
- protocolError?: ProtocolOutputLimit;
1012
1259
  sessionFile?: string;
1013
1260
  skills?: string[];
1014
1261
  skillsWarning?: string;
@@ -1044,6 +1291,8 @@ export interface SingleResult {
1044
1291
  watchdog?: ChildWatchdogProgress;
1045
1292
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1046
1293
  capabilityAudit?: SubagentCapabilityAudit;
1294
+ runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1295
+ externalProcess?: ExternalProcessStatus;
1047
1296
  }
1048
1297
 
1049
1298
  export interface SpawnBudgetGrant {
@@ -1069,16 +1318,23 @@ export interface WaitCompletionChild {
1069
1318
  agent?: string;
1070
1319
  /** Child run identity where the producer records one (workflow children); artifact files are keyed by it. */
1071
1320
  runId?: string;
1321
+ /** Bounded accounting projection used by /subagent-cost after async completion. */
1322
+ usage?: Usage;
1323
+ /** Persisted Pi child session when available. */
1324
+ sessionFile?: string;
1072
1325
  success?: boolean;
1073
1326
  outputState?: SubagentOutputState;
1327
+ structuredOutput?: unknown;
1328
+ structuredOutputPath?: string;
1074
1329
  error?: string;
1075
1330
  model?: string;
1076
1331
  contextOverflow?: boolean;
1077
1332
  artifactPaths?: Partial<ArtifactPaths>;
1333
+ timeoutRecovery?: TimeoutRecoveryProjection;
1078
1334
  }
1079
1335
 
1080
1336
  /**
1081
- * Terminal completion observed for a run a subagent_wait call covered. Carries run
1337
+ * Terminal completion observed for a run a bg_wait call covered. Carries run
1082
1338
  * identity and the artifact trail; output text stays in the tool result content.
1083
1339
  */
1084
1340
  export interface WaitCompletion {
@@ -1090,6 +1346,28 @@ export interface WaitCompletion {
1090
1346
  /** Versioned bounded output archive retained with the durable completion replay. */
1091
1347
  archivePath?: string;
1092
1348
  results?: WaitCompletionChild[];
1349
+ workflowChildren?: WorkflowChildSummaryV1;
1350
+ }
1351
+
1352
+ export interface AgentCapabilitiesSnapshot {
1353
+ agents: AgentCapabilityRow[];
1354
+ restrictedCount: number;
1355
+ capabilityCeilingSources?: string[];
1356
+ }
1357
+
1358
+ export interface AgentCapabilityRow {
1359
+ name: string;
1360
+ description: string;
1361
+ source: "builtin" | "package" | "user" | "project" | "runtime";
1362
+ executable: boolean;
1363
+ restrictionSources?: string[];
1364
+ aliases?: string[];
1365
+ runner: { type: "pi" } | { type: "external-cli"; adapter?: string; command: string; available: boolean; unavailableReason?: string; capabilities: ExternalCliCapabilities } | { type: "external-job"; provider: string; available?: boolean; capabilities: ExternalJobRunnerStatus["capabilities"] };
1366
+ tools: { ambient: boolean; names: string[]; excludeTools?: string[]; mcpDirectTools: string[]; mutationTools?: string[] };
1367
+ model?: { value?: string; fallbackModels?: string[]; thinking?: string | false };
1368
+ execution?: { defaultAsync?: boolean; timeoutMs?: number };
1369
+ output?: { path?: string; mode?: OutputMode };
1370
+ extensions?: { names?: string[]; subagentOnly?: string[]; skills?: string[] };
1093
1371
  }
1094
1372
 
1095
1373
  export interface Details {
@@ -1100,13 +1378,20 @@ export interface Details {
1100
1378
  /** Run-level context summary. "mixed" when children resolved to different modes. */
1101
1379
  context?: "fresh" | "fork" | "mixed";
1102
1380
  results: SingleResult[];
1381
+ workflowChildren?: WorkflowChildSummaryV1;
1103
1382
  /**
1104
- * Terminal completion payloads for runs this subagent_wait call observed
1383
+ * Terminal completion payloads for runs this bg_wait call observed
1105
1384
  * finishing. Async completions travel as result files that are consumed and
1106
1385
  * deleted after text delivery, so without this field their run and artifact
1107
1386
  * identity never reaches tool_result details.
1108
1387
  */
1109
1388
  completions?: WaitCompletion[];
1389
+ wait?: {
1390
+ reason: "window_elapsed";
1391
+ timedOut: true;
1392
+ activeRunIds: string[];
1393
+ activeProviderItems: Array<{ provider: string; id: string }>;
1394
+ };
1110
1395
  controlEvents?: ControlEvent[];
1111
1396
  steering?: SteerActionResult;
1112
1397
  asyncId?: string;
@@ -1116,7 +1401,6 @@ export interface Details {
1116
1401
  deadlineAt?: number;
1117
1402
  timedOut?: boolean;
1118
1403
  stopped?: boolean;
1119
- turnBudget?: ResolvedTurnBudget;
1120
1404
  toolBudget?: ResolvedToolBudget;
1121
1405
  usageBudget?: UsageBudgetState;
1122
1406
  progress?: AgentProgress[];
@@ -1136,6 +1420,9 @@ export interface Details {
1136
1420
  totalSteps?: number; // Total steps in chain
1137
1421
  currentStepIndex?: number; // 0-indexed current step (for running chains)
1138
1422
  workflowGraph?: WorkflowGraphSnapshot;
1423
+ /** Validated, display-only fanout plan supplied with a workflow launch. */
1424
+ preflight?: WorkflowPreflightV1;
1425
+ preflightWarnings?: string[];
1139
1426
  outputs?: ChainOutputMap;
1140
1427
  // Aggregated child usage across all agents in the run
1141
1428
  totalChildUsage?: Usage;
@@ -1145,6 +1432,7 @@ export interface Details {
1145
1432
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1146
1433
  runFanoutRejection?: RunFanoutRejection;
1147
1434
  activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
1435
+ agentCapabilities?: AgentCapabilitiesSnapshot;
1148
1436
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1149
1437
  capabilityAudit?: SubagentCapabilityAudit;
1150
1438
  parallelHandoff?: ParallelHandoffReference;
@@ -1164,8 +1452,10 @@ export interface Details {
1164
1452
  mission?: MissionRecord;
1165
1453
  workflow?: {
1166
1454
  value?: unknown;
1455
+ resource?: WorkflowResourceProvenanceV1;
1456
+ preflightWarnings?: string[];
1167
1457
  trace: Array<{
1168
- operation: "run" | "status" | "steer";
1458
+ operation: "run" | "status" | "steer" | "host";
1169
1459
  key: string;
1170
1460
  state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
1171
1461
  agent?: string;
@@ -1173,6 +1463,9 @@ export interface Details {
1173
1463
  phase?: string;
1174
1464
  label?: string;
1175
1465
  durationMs?: number;
1466
+ /** Internal provenance for a generated runs.lanes child key. */
1467
+ generatedLaneKey?: string;
1468
+ warning?: string;
1176
1469
  error?: string;
1177
1470
  }>;
1178
1471
  emits: unknown[];
@@ -1232,7 +1525,7 @@ export interface AsyncParallelGroupStatus {
1232
1525
  stepIndex: number;
1233
1526
  }
1234
1527
 
1235
- export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1528
+ export type NestedRunState = "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1236
1529
  export type NestedOwnerState = "live" | "gone" | "unknown";
1237
1530
 
1238
1531
  export interface NestedRunAddress {
@@ -1246,7 +1539,9 @@ export interface NestedRunAddress {
1246
1539
 
1247
1540
  export interface NestedStepSummary {
1248
1541
  agent: string;
1249
- status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1542
+ /** Human-readable display name for the child session, when derived at launch. */
1543
+ sessionName?: string;
1544
+ status: "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1250
1545
  model?: string;
1251
1546
  thinking?: string;
1252
1547
  sessionFile?: string;
@@ -1297,6 +1592,8 @@ export interface NestedRunSummary extends NestedRunAddress {
1297
1592
  capabilityAudit?: SubagentCapabilityAudit;
1298
1593
  state: NestedRunState;
1299
1594
  agent?: string;
1595
+ /** Human-readable display name for the child session, when derived at launch. */
1596
+ sessionName?: string;
1300
1597
  agents?: string[];
1301
1598
  model?: string;
1302
1599
  thinking?: string;
@@ -1358,6 +1655,7 @@ export interface AsyncStartedEvent {
1358
1655
  chainStepCount?: number;
1359
1656
  parallelGroups?: AsyncParallelGroupStatus[];
1360
1657
  workflowGraph?: WorkflowGraphSnapshot;
1658
+ preflight?: WorkflowPreflightV1;
1361
1659
  launchContractDigest?: string;
1362
1660
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1363
1661
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1375,9 +1673,11 @@ export type AgentRunnerConfig =
1375
1673
  | { type: "pi" }
1376
1674
  | {
1377
1675
  type: "external-cli";
1676
+ adapter?: "codex-exec" | "codex-exec-writer" | "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer";
1378
1677
  command: string;
1379
1678
  args?: string[];
1380
1679
  promptDelivery?: "stdin";
1680
+ capabilities?: ExternalCliCapabilityNarrowing;
1381
1681
  }
1382
1682
  | {
1383
1683
  type: "external-job";
@@ -1385,18 +1685,46 @@ export type AgentRunnerConfig =
1385
1685
  options?: Record<string, unknown>;
1386
1686
  };
1387
1687
 
1688
+ export type ExternalCliCapabilityNarrowing = Partial<Record<"steer" | "resume" | "structuredOutput" | "toolEvents" | "supervisor" | "forkContext" | "extensionBindings", false>>;
1689
+
1690
+ export interface ExternalCliCapabilities {
1691
+ stop: true;
1692
+ steer: false;
1693
+ resume: false;
1694
+ structuredOutput: false;
1695
+ toolEvents: false;
1696
+ supervisor: "unsupported";
1697
+ forkContext: false;
1698
+ extensionBindings: false;
1699
+ }
1700
+
1701
+ export interface ExternalCliReceiptMetadata {
1702
+ adapter: { id: "external-cli" | "codex-exec" | "codex-exec-writer" | "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer" | "grok-build"; version: 1; executionMode: "one-shot-stdin" | "one-shot-prompt-file" };
1703
+ capabilities: ExternalCliCapabilities;
1704
+ safety?:
1705
+ | { sandbox: "read-only"; approvalPolicy: "never"; ephemeral: true }
1706
+ | { access: "workspace-write"; sandbox: "workspace-write"; approvalPolicy: "never"; ephemeral: true }
1707
+ | { permissionMode: "plan"; tools: "none"; mcp: "empty-strict"; settingSources: "none"; sessionPersistence: false }
1708
+ | { access: "read-only"; authentication: "existing-cli-required"; permissionMode: "plan"; tools: "none"; mcp: "empty-strict"; settingSources: "user"; userSettingsTrust: "required"; sessionPersistence: false }
1709
+ | { access: "workspace-write"; authentication: "existing-cli-required"; permissionMode: "acceptEdits"; tools: "Read,Write,Edit,Glob,Grep"; mcp: "empty-strict"; settingSources: "user"; userSettingsTrust: "required"; sessionPersistence: false }
1710
+ | { access: "read-only"; authentication: "cursor-api-key-or-existing-login"; mode: "ask"; sandbox: "enabled"; workspaceTrust: "existing-required"; sessionReuse: false }
1711
+ | { access: "workspace-write"; authentication: "cursor-api-key-or-existing-login"; mode: "print"; sandbox: "enabled"; workspaceTrust: "existing-required"; sessionReuse: false };
1712
+ outputArtifacts?: { stdoutPath?: string; stderrPath?: string; finalOutputPath?: string };
1713
+ handoff: { mode: "fresh" };
1714
+ supervisor: { mode: "unsupported"; reason: string };
1715
+ nonResumableReason: string;
1716
+ }
1717
+
1388
1718
  export interface ExternalCliRunnerStatus {
1389
1719
  type: "external-cli";
1390
1720
  command: string;
1391
1721
  args: string[];
1392
- promptDelivery: "stdin";
1393
- capabilities: {
1394
- stop: true;
1395
- steer: false;
1396
- resume: false;
1397
- structuredOutput: false;
1398
- toolEvents: false;
1399
- };
1722
+ promptDelivery: "stdin" | "prompt-file";
1723
+ adapter: ExternalCliReceiptMetadata["adapter"];
1724
+ safety?: ExternalCliReceiptMetadata["safety"];
1725
+ capabilities: ExternalCliCapabilities;
1726
+ unsupportedReasons: Record<Exclude<keyof ExternalCliCapabilities, "stop">, string>;
1727
+ nonResumableReason: string;
1400
1728
  }
1401
1729
 
1402
1730
  export interface ExternalJobRunnerStatus {
@@ -1443,6 +1771,11 @@ export interface ExternalProcessStatus {
1443
1771
  processSignal?: string | null;
1444
1772
  stdoutPath: string;
1445
1773
  stderrPath: string;
1774
+ finalOutputPath?: string;
1775
+ stdoutBytes?: number;
1776
+ stderrBytes?: number;
1777
+ stdoutTruncated?: boolean;
1778
+ stderrTruncated?: boolean;
1446
1779
  }
1447
1780
 
1448
1781
  export interface AsyncStatus {
@@ -1456,7 +1789,7 @@ export interface AsyncStatus {
1456
1789
  mode: SubagentRunMode;
1457
1790
  context?: "fresh" | "fork" | "mixed";
1458
1791
  isNested?: boolean;
1459
- state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1792
+ state: "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1460
1793
  /** Display-only dismissal marker for a reload-orphaned workflow. */
1461
1794
  displayDismissedAt?: number;
1462
1795
  error?: string;
@@ -1490,6 +1823,7 @@ export interface AsyncStatus {
1490
1823
  pendingAppends?: number;
1491
1824
  parallelGroups?: AsyncParallelGroupStatus[];
1492
1825
  workflowGraph?: WorkflowGraphSnapshot;
1826
+ preflight?: WorkflowPreflightV1;
1493
1827
  processTerminal?: ProcessTerminalV1;
1494
1828
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1495
1829
  runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
@@ -1499,14 +1833,18 @@ export interface AsyncStatus {
1499
1833
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1500
1834
  capabilityAudit?: SubagentCapabilityAudit;
1501
1835
  workflow?: Details["workflow"];
1836
+ workflowChildren?: WorkflowChildSummaryV1;
1502
1837
  parentWorkflowRunId?: string;
1503
1838
  workflowKey?: string;
1839
+ lane?: WorkflowLaneMetadata;
1504
1840
  /** Set when a durable schedule launched this run, so completions can name their origin. */
1505
1841
  scheduleOrigin?: ScheduleOrigin;
1506
1842
  steps?: Array<{
1507
1843
  /** Stable caller-facing child identity for inspect/status/stop. */
1508
1844
  childId?: string;
1509
1845
  agent: string;
1846
+ /** Human-readable display name for the child session, when derived at launch. */
1847
+ sessionName?: string;
1510
1848
  runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1511
1849
  externalProcess?: ExternalProcessStatus;
1512
1850
  externalJob?: ExternalJobStatus;
@@ -1517,6 +1855,15 @@ export interface AsyncStatus {
1517
1855
  phase?: string;
1518
1856
  label?: string;
1519
1857
  workflowKey?: string;
1858
+ lane?: WorkflowLaneMetadata;
1859
+ /** Display-only worktree path copied at launch; handoff remains authoritative. */
1860
+ worktreePath?: string;
1861
+ /** Display-only branch copied at launch; handoff remains authoritative. */
1862
+ branch?: string;
1863
+ /** Display-only provisioning provider copied at launch; handoff remains authoritative. */
1864
+ provider?: ManagedWorktreeProvider;
1865
+ /** Display-only naming evidence copied at launch; handoff remains authoritative. */
1866
+ naming?: WorktreeNaming;
1520
1867
  /** Child run identity for workflow capacity reconciliation. */
1521
1868
  runId?: string;
1522
1869
  /** True only when this workflow child owns a detached async runner. */
@@ -1524,7 +1871,7 @@ export interface AsyncStatus {
1524
1871
  parentWorkflowRunId?: string;
1525
1872
  outputName?: string;
1526
1873
  structured?: boolean;
1527
- status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1874
+ status: "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1528
1875
  stopRequested?: boolean;
1529
1876
  stopRequestedAt?: number;
1530
1877
  children?: NestedRunSummary[];
@@ -1557,6 +1904,7 @@ export interface AsyncStatus {
1557
1904
  skills?: string[];
1558
1905
  model?: string;
1559
1906
  thinking?: string;
1907
+ contextLimit?: number;
1560
1908
  thinkingCeiling?: ThinkingLevel;
1561
1909
  attemptedModels?: string[];
1562
1910
  modelAttempts?: ModelAttempt[];
@@ -1590,9 +1938,10 @@ export interface AsyncStatus {
1590
1938
  parallelHandoff?: ParallelHandoffReference;
1591
1939
  }
1592
1940
 
1593
- export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
1941
+ export type AsyncJobStep = Omit<NonNullable<AsyncStatus["steps"]>[number], "timeoutRecovery"> & {
1594
1942
  index?: number;
1595
1943
  description?: string;
1944
+ timeoutRecovery?: TimeoutRecoveryProjection;
1596
1945
  };
1597
1946
 
1598
1947
  export interface AsyncJobState {
@@ -1604,7 +1953,7 @@ export interface AsyncJobState {
1604
1953
  cwd?: string;
1605
1954
  /** Parent-resolved child session root retained for trusted live transcript lookup. */
1606
1955
  sessionRoot?: string;
1607
- status: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1956
+ status: "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1608
1957
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1609
1958
  description?: string;
1610
1959
  pid?: number;
@@ -1625,7 +1974,12 @@ export interface AsyncJobState {
1625
1974
  currentStep?: number;
1626
1975
  chainStepCount?: number;
1627
1976
  parallelGroups?: AsyncParallelGroupStatus[];
1977
+ /** Bounded host-owned CI/gate nodes loaded from the workflow status graph. */
1978
+ hostSteps?: HostStepNodeV1[];
1979
+ /** Full bounded workflow plan, including not-yet-materialized stages. */
1980
+ workflowGraph?: WorkflowGraphSnapshot;
1628
1981
  steps?: AsyncJobStep[];
1982
+ preflight?: WorkflowPreflightV1;
1629
1983
  stepsTotal?: number;
1630
1984
  runningSteps?: number;
1631
1985
  completedSteps?: number;
@@ -1654,10 +2008,14 @@ export interface AsyncJobState {
1654
2008
  parentWorkflowRunId?: string;
1655
2009
  workflowKey?: string;
1656
2010
  workflow?: Details["workflow"];
2011
+ workflowChildren?: WorkflowChildSummaryV1;
2012
+ lane?: WorkflowLaneMetadata;
1657
2013
  }
1658
2014
 
1659
2015
  export interface ForegroundResumeChild {
1660
2016
  agent: string;
2017
+ /** Human-readable display name for the child session, when derived at launch. */
2018
+ sessionName?: string;
1661
2019
  index: number;
1662
2020
  context?: "fresh" | "fork";
1663
2021
  sessionFile?: string;
@@ -1671,6 +2029,8 @@ export interface ForegroundResumeChild {
1671
2029
  currentPath?: string;
1672
2030
  turnCount?: number;
1673
2031
  tokens?: number;
2032
+ window?: number;
2033
+ windowPeak?: number;
1674
2034
  toolCount?: number;
1675
2035
  exitCode?: number;
1676
2036
  error?: string;
@@ -1685,6 +2045,14 @@ export interface ForegroundResumeChild {
1685
2045
  detachedReason?: string;
1686
2046
  acceptance?: AcceptanceLedger;
1687
2047
  agentContract?: AgentContract;
2048
+ /** Private bounded launch fields needed to preserve the child contract on resume. */
2049
+ resumeContract?: {
2050
+ outputSchema?: JsonSchemaObject;
2051
+ agentContract?: AgentContract;
2052
+ acceptance?: AcceptanceInput;
2053
+ output?: string | boolean;
2054
+ outputMode?: OutputMode;
2055
+ };
1688
2056
  launchContractDigest?: string;
1689
2057
  /** Private retained launch authority. Never project into status or result output. */
1690
2058
  extensionBindings?: ExtensionBindings;
@@ -1711,6 +2079,8 @@ export interface ForegroundResumeRun {
1711
2079
  export interface ForegroundChildControl {
1712
2080
  index: number;
1713
2081
  agent: string;
2082
+ /** Human-readable display name for the child's session, when derived at launch. */
2083
+ sessionName?: string;
1714
2084
  description?: string;
1715
2085
  startedAt: number;
1716
2086
  updatedAt: number;
@@ -1723,11 +2093,25 @@ export interface ForegroundChildControl {
1723
2093
  tokens?: number;
1724
2094
  inputTokens?: number;
1725
2095
  outputTokens?: number;
2096
+ window?: number;
2097
+ windowPeak?: number;
1726
2098
  model?: string;
1727
2099
  thinking?: string;
1728
2100
  toolCount?: number;
1729
2101
  interrupt?: () => boolean;
1730
2102
  detach?: () => boolean;
2103
+ /** Steer the live in-process child session; undefined until the session exists. */
2104
+ steer?: (input: ForegroundSteerInput) => Promise<ForegroundSteerOutcome>;
2105
+ }
2106
+
2107
+ export interface ForegroundSteerInput {
2108
+ message: string;
2109
+ mode?: "steer" | "follow_up" | "auto";
2110
+ }
2111
+
2112
+ export interface ForegroundSteerOutcome {
2113
+ state: "delivered" | "queued" | "failed";
2114
+ reason?: string;
1731
2115
  }
1732
2116
 
1733
2117
  export interface ForegroundRunControl {
@@ -1736,8 +2120,6 @@ export interface ForegroundRunControl {
1736
2120
  parentWorkflowRunId?: string;
1737
2121
  /** Stable workflow lane key for this live foreground child. */
1738
2122
  workflowKey?: string;
1739
- /** Private control root used to steer a live workflow-owned child. */
1740
- workflowSteeringDir?: string;
1741
2123
  /** Originating parent session; required for public fleet projection. */
1742
2124
  sessionId?: string;
1743
2125
  mode: SubagentRunMode;
@@ -1746,6 +2128,8 @@ export interface ForegroundRunControl {
1746
2128
  /** Effective working directory used to resolve live transcript artifacts. */
1747
2129
  cwd?: string;
1748
2130
  currentAgent?: string;
2131
+ /** Human-readable display name for the current child session, when derived at launch. */
2132
+ sessionName?: string;
1749
2133
  currentIndex?: number;
1750
2134
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1751
2135
  description?: string;
@@ -1758,6 +2142,8 @@ export interface ForegroundRunControl {
1758
2142
  tokens?: number;
1759
2143
  inputTokens?: number;
1760
2144
  outputTokens?: number;
2145
+ window?: number;
2146
+ windowPeak?: number;
1761
2147
  model?: string;
1762
2148
  thinking?: string;
1763
2149
  toolCount?: number;
@@ -1775,6 +2161,7 @@ export interface ForegroundRunControl {
1775
2161
  nestedChildren?: NestedRunSummary[];
1776
2162
  interrupt?: () => boolean;
1777
2163
  detach?: () => boolean;
2164
+ steer?: ForegroundChildControl["steer"];
1778
2165
  }
1779
2166
 
1780
2167
  export interface WaitSubscriptionRecord {
@@ -1797,6 +2184,8 @@ export interface ActiveAsyncCapacitySnapshot {
1797
2184
  export interface SubagentState {
1798
2185
  baseCwd: string;
1799
2186
  currentSessionId: string | null;
2187
+ /** Session for which active status projections were restored successfully. */
2188
+ statusProjectionSessionId?: string | null;
1800
2189
  /** Reload-stable identity for this parent Pi process/window. */
1801
2190
  completionOwnerId?: string;
1802
2191
  /** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
@@ -1808,6 +2197,8 @@ export interface SubagentState {
1808
2197
  parentSessionFile?: string | null;
1809
2198
  /** Extension-owned roots trusted for child session transcript reads. */
1810
2199
  trustedSessionRoots?: string[];
2200
+ /** Pi sessions base that caps exact runtime-recorded session file trust. */
2201
+ trustedSessionFileRoot?: string;
1811
2202
  /** Live async session roots created by this parent executor, keyed by run id. */
1812
2203
  liveAsyncSessionRoots?: Map<string, string>;
1813
2204
  /** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
@@ -1935,18 +2326,30 @@ export interface SubagentChildStatusEvent {
1935
2326
  // Execution Options
1936
2327
  // ============================================================================
1937
2328
 
2329
+ /** Live controls for one in-process foreground child session. */
2330
+ export interface ForegroundChildSessionControls {
2331
+ steer: (text: string) => Promise<void>;
2332
+ followUp: (text: string) => Promise<void>;
2333
+ }
2334
+
1938
2335
  export interface RunSyncOptions {
2336
+ /** Exact discovery provenance for an unknown-agent error; omission uses defensive fallback discovery. */
2337
+ unknownAgentDiagnosticContext?: import("../agents/agents.ts").UnknownAgentDiagnosticContext;
2338
+ /** Session factory for the in-process child; defaults to the process-wide factory. */
2339
+ childSessionFactory?: import("../runs/shared/child-session.ts").ChildSessionFactory;
2340
+ /** The launching executor's own child runtime when it is itself an in-process child. */
2341
+ childRuntime?: import("../runs/shared/child-runtime-config.ts").ChildRuntimeConfig;
2342
+ /** Fires once the child session exists and can be steered. */
2343
+ onChildSession?: (controls: ForegroundChildSessionControls) => void;
1939
2344
  /** Opt-in global permission rules; missing tools remain allowed. */
1940
2345
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
1941
2346
  /** Session id of the direct parent session for permission-system ask forwarding. */
1942
2347
  parentSessionId?: string;
1943
- /** Private prompt-runtime steering transport for workflow-owned foreground children. */
1944
- steerInboxDir?: string;
1945
- steerCapabilityPath?: string;
1946
- steerAckDir?: string;
1947
2348
  /** Resolved launch context for this child. */
1948
2349
  context?: "fresh" | "fork";
1949
2350
  cwd?: string;
2351
+ /** Original cwd input retained for launch diagnostics. */
2352
+ requestedCwd?: string;
1950
2353
  signal?: AbortSignal;
1951
2354
  interruptSignal?: AbortSignal;
1952
2355
  timeoutMs?: number;
@@ -1955,15 +2358,14 @@ export interface RunSyncOptions {
1955
2358
  toolTimeoutMs?: number;
1956
2359
  /** Raw global config.toolTimeoutMs, used by the per-child resolver. */
1957
2360
  configToolTimeoutMs?: number;
1958
- turnBudget?: ResolvedTurnBudget;
1959
2361
  usageBudget?: UsageBudgetConfig;
1960
- /** Enforce maxTurns + graceTurns as a hard model-turn boundary. */
1961
- enforceHardTurnLimit?: boolean;
1962
2362
  toolBudget?: ResolvedToolBudget;
1963
2363
  allowZeroToolBudget?: boolean;
1964
2364
  allowIntercomDetach?: boolean;
1965
2365
  intercomEvents?: IntercomEventBus;
1966
2366
  onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
2367
+ /** Internal structured-delegation transport optimization: skip unchanged live snapshots. */
2368
+ suppressUnchangedDelegationUpdates?: boolean;
1967
2369
  onControlEvent?: (event: ControlEvent) => void;
1968
2370
  /** Exposes a non-terminating detach callback while the child is active. */
1969
2371
  onDetachReady?: (detach: (reason?: string) => boolean) => void;
@@ -1983,10 +2385,13 @@ export interface RunSyncOptions {
1983
2385
  sessionFile?: string;
1984
2386
  share?: boolean;
1985
2387
  outputPath?: string;
2388
+ outputClaimPath?: string;
1986
2389
  outputMode?: OutputMode;
1987
2390
  maxSubagentDepth?: number;
1988
2391
  /** Effective parent wait-tool setting propagated to the child runtime. */
1989
2392
  waitToolEnabled?: boolean;
2393
+ /** Effective parent default wait window propagated to the child runtime. */
2394
+ waitToolDefaultTimeoutMs?: number;
1990
2395
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1991
2396
  runFanoutBudget?: RunFanoutBudgetDescriptor;
1992
2397
  nestedRoute?: NestedRouteInfo;
@@ -1996,16 +2401,22 @@ export interface RunSyncOptions {
1996
2401
  fast?: boolean;
1997
2402
  /** The override came from the running parent session, not configuration. */
1998
2403
  modelOverrideFromParent?: boolean;
2404
+ /** How the launch model was selected: explicit per-call, configured agent primary, or inherited parent. */
2405
+ modelOrigin?: "explicit" | "inherited" | "configured";
1999
2406
  /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
2000
2407
  llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
2001
2408
  /** Override the agent's default thinking level for this run */
2002
2409
  thinkingOverride?: AgentConfig["thinking"];
2003
2410
  thinkingCeiling?: ThinkingLevel;
2004
2411
  extensionBindings?: ExtensionBindings;
2412
+ /** Package-internal one-use authorization for one foreground workflow child. */
2413
+ workflowChildPermitLaunch?: WorkflowChildPermitContext;
2005
2414
  /** Registry models available for heuristic bare-model resolution */
2006
- availableModels?: Array<{ provider: string; id: string; fullId: string }>;
2415
+ availableModels?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
2007
2416
  /** Current parent-session provider to prefer for ambiguous bare model ids */
2008
2417
  preferredModelProvider?: string;
2418
+ /** Parent Pi event host used to snapshot runtime-registered MCP servers before child launch. */
2419
+ runtimeSnapshotHost?: import("../runs/shared/mcp-direct-tool-allowlist.ts").McpRuntimeSnapshotHost;
2009
2420
  /** Optional subagent model-scope enforcement for fallback candidates */
2010
2421
  modelScope?: ModelScopeRule | ModelScopeRule[];
2011
2422
  /** Skills to make available (overrides agent default if provided) */
@@ -2015,6 +2426,7 @@ export interface RunSyncOptions {
2015
2426
  schemaPath: string;
2016
2427
  outputPath: string;
2017
2428
  acceptanceReportPath?: string;
2429
+ acceptanceReportRequired?: boolean;
2018
2430
  };
2019
2431
  agentContract?: AgentContract;
2020
2432
  acceptance?: AcceptanceInput;
@@ -2067,6 +2479,11 @@ export interface ScheduledRunsConfig {
2067
2479
  storeRoot?: string;
2068
2480
  }
2069
2481
 
2482
+ export interface ModelExclusionsConfig {
2483
+ /** Default duration in milliseconds. A lower configured value also shortens active cached exclusions. */
2484
+ defaultTtlMs?: number;
2485
+ }
2486
+
2070
2487
  export type FleetViewPlacement = "aboveEditor" | "belowEditor";
2071
2488
 
2072
2489
  export const FLEET_KEYBINDING_ACTIONS = [
@@ -2102,10 +2519,24 @@ export interface MainWindowRendererConfig {
2102
2519
  compactResultMaxLines?: number;
2103
2520
  }
2104
2521
 
2522
+ export interface ForkContextConfig {
2523
+ /** Keep the complete fork by default, or summarize large text-only tool results before launch. */
2524
+ mode?: "full" | "pruned";
2525
+ /** Required pruning model when mode is "pruned". */
2526
+ model?: string;
2527
+ }
2528
+
2529
+ export interface ActiveAsyncCapacityConfig {
2530
+ /** Reclaim failed runner slots after this age when process proof is unknown; false keeps strict retention. */
2531
+ abandonedSlotReleaseAfterMs?: number | false;
2532
+ }
2533
+
2105
2534
  export interface ExtensionConfig {
2106
2535
  asyncByDefault?: boolean;
2107
2536
  /** Set the context for launches that omit an explicit context. */
2108
2537
  defaultSubagentContext?: "fresh" | "fork";
2538
+ /** Configure how every resolved fork session is prepared before child spawn. */
2539
+ forkContext?: ForkContextConfig;
2109
2540
  /** Optional shortcut that detaches the active foreground single-subagent run. */
2110
2541
  foregroundDetachShortcut?: string;
2111
2542
  /** Show the Claude Code-style navigable fleet. Defaults to true. */
@@ -2116,6 +2547,8 @@ export interface ExtensionConfig {
2116
2547
  fleetKeybindings?: FleetKeybindingsConfig;
2117
2548
  /** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
2118
2549
  asyncWidget?: boolean;
2550
+ /** Configure the process-wide TTL policy for persisted model exclusions. */
2551
+ modelExclusions?: ModelExclusionsConfig;
2119
2552
  /** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
2120
2553
  toolDescriptionMode?: ToolDescriptionMode;
2121
2554
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
@@ -2135,6 +2568,8 @@ export interface ExtensionConfig {
2135
2568
  maxSubagentSpawnsPerRun?: number;
2136
2569
  /** Optional active top-level async run cap per parent session. Unset or 0 means unlimited. */
2137
2570
  maxActiveAsyncRunsPerSession?: number;
2571
+ /** Active-capacity cleanup policy. */
2572
+ capacity?: ActiveAsyncCapacityConfig;
2138
2573
  /** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
2139
2574
  globalConcurrencyLimit?: number;
2140
2575
  /**
@@ -2158,7 +2593,6 @@ export interface ExtensionConfig {
2158
2593
  toolTimeoutMs?: number;
2159
2594
  control?: ControlConfig;
2160
2595
  completionBatch?: CompletionBatchConfig;
2161
- turnBudget?: TurnBudgetConfig;
2162
2596
  toolBudget?: ToolBudgetConfig;
2163
2597
  /** Opt-in native tool permissions. Bash remains outside this policy. */
2164
2598
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
@@ -2168,6 +2602,12 @@ export interface ExtensionConfig {
2168
2602
  worktreeSetupHook?: string;
2169
2603
  worktreeSetupHookTimeoutMs?: number;
2170
2604
  worktreeBaseDir?: string;
2605
+ /** Enable managed worktrees when a launch does not provide an explicit value. */
2606
+ worktree?: boolean;
2607
+ /** Worktree allocator selection. Defaults to auto. */
2608
+ worktreeProvider?: WorktreeProvider;
2609
+ /** Namespace used by managed worktree branches. Defaults to pi-subagents/. */
2610
+ worktreeBranchPrefix?: string;
2171
2611
  /** Where to store subagent artifact files. Defaults to "session" (the pi session directory, or OS temp when unavailable). Set to "project" for cwd/.pi/subagents. */
2172
2612
  artifactDir?: ArtifactDirPreference;
2173
2613
  /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
@@ -2290,7 +2730,7 @@ export const POLL_INTERVAL_MS = 250;
2290
2730
  export const WIDGET_ANIMATION_INTERVAL_MS = 1000;
2291
2731
  export const MAX_WIDGET_JOBS = 4;
2292
2732
  export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
2293
- export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
2733
+ export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "validate", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "worktree.cleanup", "lane.status", "lane.recordMerge", "lane.recordSupersession", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;
2294
2734
 
2295
2735
  export const DEFAULT_FORK_PREAMBLE =
2296
2736
  "You are a delegated subagent running from a fork of the parent session. " +
@@ -2343,8 +2783,17 @@ export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
2343
2783
  return normalizeNonNegativeInteger(value);
2344
2784
  }
2345
2785
 
2346
- export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
2347
- return normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH)
2786
+ /** Depth context of the executor's own child runtime, when it runs as an in-process child. */
2787
+ export interface SubagentDepthContext {
2788
+ depth: number;
2789
+ maxDepth?: number;
2790
+ }
2791
+
2792
+ /** Operator override for the top-level parent; children inherit their limit through their runtime config. */
2793
+ export const SUBAGENT_MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
2794
+
2795
+ export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number, runtime?: SubagentDepthContext): number {
2796
+ return normalizeMaxSubagentDepth(runtime ? runtime.maxDepth : process.env[SUBAGENT_MAX_DEPTH_ENV])
2348
2797
  ?? normalizeMaxSubagentDepth(configMaxDepth)
2349
2798
  ?? DEFAULT_SUBAGENT_MAX_DEPTH;
2350
2799
  }
@@ -2355,19 +2804,24 @@ export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDep
2355
2804
  return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
2356
2805
  }
2357
2806
 
2358
- export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
2359
- const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
2360
- const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
2361
- const blocked = Number.isFinite(depth) && depth >= maxDepth;
2807
+ /** Depth of the executor itself: 0 for a top-level parent, its own child depth otherwise. */
2808
+ export function resolveCurrentSubagentDepth(runtime?: SubagentDepthContext): number {
2809
+ const depth = runtime ? runtime.depth : 0;
2810
+ return Number.isFinite(depth) ? depth : 0;
2811
+ }
2812
+
2813
+ export function checkSubagentDepth(configMaxDepth?: number, runtime?: SubagentDepthContext): { blocked: boolean; depth: number; maxDepth: number } {
2814
+ const depth = resolveCurrentSubagentDepth(runtime);
2815
+ const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth, runtime);
2816
+ const blocked = depth >= maxDepth;
2362
2817
  return { blocked, depth, maxDepth };
2363
2818
  }
2364
2819
 
2365
- export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
2366
- const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
2367
- const nextDepth = Number.isFinite(parentDepth) ? parentDepth + 1 : 1;
2820
+ /** Depth context handed to a child launched by an executor at `runtime` (undefined for a top-level parent). */
2821
+ export function resolveChildDepth(maxDepth?: number, runtime?: SubagentDepthContext): Required<SubagentDepthContext> {
2368
2822
  return {
2369
- PI_SUBAGENT_DEPTH: String(nextDepth),
2370
- PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
2823
+ depth: resolveCurrentSubagentDepth(runtime) + 1,
2824
+ maxDepth: normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth(undefined, runtime),
2371
2825
  };
2372
2826
  }
2373
2827