@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
@@ -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
 
@@ -569,22 +786,30 @@ export interface SteeringRecoveryDescriptor {
569
786
  sourceRunId: string;
570
787
  agentContract?: AgentContract;
571
788
  agent: string;
789
+ sandbox?: string;
572
790
  sessionFile?: string;
791
+ /** Git ref used to allocate managed worktrees for this run. */
792
+ baseRef?: string;
573
793
  cwd: string;
574
794
  model?: string;
575
795
  modelProvider?: string;
576
796
  modelOverrideFromParent?: boolean;
797
+ modelOrigin?: "explicit" | "inherited" | "configured";
577
798
  fallbackModels?: string[];
578
799
  fast?: boolean;
579
800
  thinking?: string;
580
801
  thinkingCeiling?: ThinkingLevel;
581
802
  tools?: string[];
803
+ excludeTools?: string[];
804
+ allowNestedSubagents?: boolean;
582
805
  extensions?: string[];
583
806
  subagentOnlyExtensions?: string[];
584
807
  mcpDirectTools?: string[];
808
+ mutationTools?: string[];
585
809
  systemPrompt?: string;
586
810
  systemPromptMode: "append" | "replace";
587
811
  inheritProjectContext: boolean;
812
+ inheritGlobalContext: boolean;
588
813
  inheritSkills: boolean;
589
814
  skills?: string[];
590
815
  skillPath?: string[];
@@ -600,8 +825,8 @@ export interface SteeringRecoveryDescriptor {
600
825
  context?: "fresh" | "fork";
601
826
  /** Raw per-run bridge override. Omitted descriptors continue to use global config. */
602
827
  intercomBridge?: IntercomBridgeConfig;
828
+ lane?: WorkflowLaneMetadata;
603
829
  absoluteDeadlineAt?: number;
604
- initialTurnBudget?: ResolvedTurnBudget;
605
830
  initialToolBudget?: ResolvedToolBudget;
606
831
  maxSubagentDepth: number;
607
832
  maxOutput?: MaxOutputConfig;
@@ -615,7 +840,7 @@ export interface SteeringRecoveryDescriptor {
615
840
 
616
841
  export type PublicNestedStepSummary = Pick<
617
842
  NestedStepSummary,
618
- "agent" | "status" | "model" | "thinking" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut" | "stopped"
843
+ "agent" | "sessionName" | "status" | "model" | "thinking" | "sandbox" | "sessionFile" | "transcriptPath" | "transcriptError" | "activityState" | "lastActivityAt" | "currentTool" | "currentToolStartedAt" | "currentPath" | "turnCount" | "toolCount" | "toolBudget" | "toolBudgetBlocked" | "startedAt" | "endedAt" | "error" | "timedOut" | "stopped"
619
844
  > & {
620
845
  children?: PublicNestedRunSummary[];
621
846
  };
@@ -628,7 +853,7 @@ export type CostSummary = {
628
853
 
629
854
  export type PublicNestedRunSummary = Pick<
630
855
  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"
856
+ "id" | "parentRunId" | "parentStepIndex" | "parentAgent" | "depth" | "path" | "asyncDir" | "sessionId" | "sessionFile" | "intercomTarget" | "ownerIntercomTarget" | "leafIntercomTarget" | "ownerState" | "mode" | "state" | "agent" | "sessionName" | "agents" | "model" | "thinking" | "sandbox" | "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
857
  > & {
633
858
  steps?: PublicNestedStepSummary[];
634
859
  children?: PublicNestedRunSummary[];
@@ -636,6 +861,8 @@ export type PublicNestedRunSummary = Pick<
636
861
 
637
862
  export interface SubagentResultIntercomChild {
638
863
  agent: string;
864
+ /** Human-readable display name for the child session, when derived at launch. */
865
+ sessionName?: string;
639
866
  /** Process/lifecycle status. It does not establish semantic task completion. */
640
867
  status: SubagentResultStatus;
641
868
  /** Whether the child produced substantive output before its process ended. */
@@ -672,18 +899,26 @@ export interface SubagentResultIntercomPayload {
672
899
  // Progress Tracking
673
900
  // ============================================================================
674
901
 
902
+ export interface ChildWatchdogWarningSummary extends Pick<WatchdogWarningDetails, "severity" | "category" | "summary" | "evidence" | "recommendedAction" | "displayedAt"> {
903
+ /** True when a later assistant turn in the child followed the warning. */
904
+ addressed: boolean;
905
+ stalemate: boolean;
906
+ }
907
+
675
908
  export interface ChildWatchdogProgress {
676
- phase: "idle" | "reviewing" | "autofollow" | "settling" | "stale" | "failed";
909
+ phase: "idle" | "reviewing" | "stale" | "failed";
677
910
  seq: number;
678
911
  lastUpdate: number;
679
- followUpPending: boolean;
680
912
  reason?: string;
681
913
  timedOut?: boolean;
914
+ warnings?: ChildWatchdogWarningSummary[];
682
915
  }
683
916
 
684
917
  export interface AgentProgress {
685
918
  index: number;
686
919
  agent: string;
920
+ /** Human-readable display name for the child's session, when derived at launch. */
921
+ sessionName?: string;
687
922
  status: "pending" | "running" | "completed" | "failed" | "detached";
688
923
  activityState?: ActivityState;
689
924
  task: string;
@@ -703,6 +938,8 @@ export interface AgentProgress {
703
938
  thinking?: string;
704
939
  inputTokens?: number;
705
940
  outputTokens?: number;
941
+ window?: number;
942
+ windowPeak?: number;
706
943
  durationMs: number;
707
944
  error?: string;
708
945
  failedTool?: string;
@@ -717,6 +954,8 @@ export interface ToolCallSummary {
717
954
  interface ProgressSummary {
718
955
  index?: number;
719
956
  agent?: string;
957
+ /** Human-readable display name for the child's session, when derived at launch. */
958
+ sessionName?: string;
720
959
  status?: AgentProgress["status"];
721
960
  activityState?: ActivityState;
722
961
  skills?: string[];
@@ -782,6 +1021,7 @@ export interface AcceptanceReviewGate {
782
1021
 
783
1022
  export interface AcceptanceConfig {
784
1023
  level?: AcceptanceLevel;
1024
+ report?: "on" | "off";
785
1025
  criteria?: Array<string | AcceptanceGate>;
786
1026
  evidence?: AcceptanceEvidenceKind[];
787
1027
  verify?: AcceptanceVerifyCommand[];
@@ -891,6 +1131,18 @@ export type AcceptanceLedgerStatus =
891
1131
  | "reviewed"
892
1132
  | "accepted";
893
1133
 
1134
+ /**
1135
+ * Durable child evidence that can be handed to a read-only review after the
1136
+ * acceptance envelope itself was rejected. This never upgrades acceptance;
1137
+ * the enclosing ledger remains rejected and the child remains unsuccessful.
1138
+ */
1139
+ export interface AcceptanceRecoveryMetadata {
1140
+ status: "available-for-review";
1141
+ reason: "acceptance-metadata-rejected";
1142
+ reportPath: string;
1143
+ reportHash: string;
1144
+ }
1145
+
894
1146
  export interface AcceptanceLedger {
895
1147
  status: AcceptanceLedgerStatus;
896
1148
  evidenceStatus: AcceptanceEvidenceStatus;
@@ -900,6 +1152,7 @@ export interface AcceptanceLedger {
900
1152
  criteria: ResolvedAcceptanceGate[];
901
1153
  childReport?: AcceptanceReport;
902
1154
  childReportParseError?: string;
1155
+ recovery?: AcceptanceRecoveryMetadata;
903
1156
  runtimeChecks: AcceptanceRuntimeCheck[];
904
1157
  verifyRuns: AcceptanceVerifyResult[];
905
1158
  reviewResult?: AcceptanceReviewResult;
@@ -910,15 +1163,6 @@ export interface AcceptanceLedger {
910
1163
  };
911
1164
  }
912
1165
 
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
1166
  export interface LaunchResolvedChildExtensionsV1 {
923
1167
  version: 1;
924
1168
  /** This is parent-resolved launch intent, not child-runtime acknowledgement that extensions loaded. */
@@ -975,8 +1219,13 @@ export interface SingleResult {
975
1219
  * result row's array position.
976
1220
  */
977
1221
  index: number;
1222
+ /** Workflow child key that owns this result when returned from workflow details. */
1223
+ workflowKey?: string;
978
1224
  agent: string;
979
1225
  task: string;
1226
+ /** Human-readable display name for the child's own session (agent + task
1227
+ * excerpt), when the launcher derived one. Display metadata only. */
1228
+ sessionName?: string;
980
1229
  /** Resolved launch context for this child. */
981
1230
  context?: "fresh" | "fork";
982
1231
  exitCode: number;
@@ -992,6 +1241,7 @@ export interface SingleResult {
992
1241
  wrapUpRequested?: boolean;
993
1242
  toolBudget?: ToolBudgetState;
994
1243
  toolBudgetBlocked?: boolean;
1244
+ sandbox?: string;
995
1245
  messages?: Message[];
996
1246
  usage: Usage;
997
1247
  model?: string;
@@ -1008,7 +1258,13 @@ export interface SingleResult {
1008
1258
  * a signal to reduce input size or re-decompose the task.
1009
1259
  */
1010
1260
  contextOverflow?: boolean;
1011
- protocolError?: ProtocolOutputLimit;
1261
+ /**
1262
+ * True when the child never reached its first model turn because a startup
1263
+ * guard blocked it (for example a required sandbox profile that failed to
1264
+ * initialize). Retrying another model cannot succeed, and the failure must
1265
+ * not be recorded as a model exclusion.
1266
+ */
1267
+ startupBlocked?: boolean;
1012
1268
  sessionFile?: string;
1013
1269
  skills?: string[];
1014
1270
  skillsWarning?: string;
@@ -1044,6 +1300,8 @@ export interface SingleResult {
1044
1300
  watchdog?: ChildWatchdogProgress;
1045
1301
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1046
1302
  capabilityAudit?: SubagentCapabilityAudit;
1303
+ runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1304
+ externalProcess?: ExternalProcessStatus;
1047
1305
  }
1048
1306
 
1049
1307
  export interface SpawnBudgetGrant {
@@ -1069,16 +1327,23 @@ export interface WaitCompletionChild {
1069
1327
  agent?: string;
1070
1328
  /** Child run identity where the producer records one (workflow children); artifact files are keyed by it. */
1071
1329
  runId?: string;
1330
+ /** Bounded accounting projection used by /subagent-cost after async completion. */
1331
+ usage?: Usage;
1332
+ /** Persisted Pi child session when available. */
1333
+ sessionFile?: string;
1072
1334
  success?: boolean;
1073
1335
  outputState?: SubagentOutputState;
1336
+ structuredOutput?: unknown;
1337
+ structuredOutputPath?: string;
1074
1338
  error?: string;
1075
1339
  model?: string;
1076
1340
  contextOverflow?: boolean;
1077
1341
  artifactPaths?: Partial<ArtifactPaths>;
1342
+ timeoutRecovery?: TimeoutRecoveryProjection;
1078
1343
  }
1079
1344
 
1080
1345
  /**
1081
- * Terminal completion observed for a run a subagent_wait call covered. Carries run
1346
+ * Terminal completion observed for a run a bg_wait call covered. Carries run
1082
1347
  * identity and the artifact trail; output text stays in the tool result content.
1083
1348
  */
1084
1349
  export interface WaitCompletion {
@@ -1090,6 +1355,28 @@ export interface WaitCompletion {
1090
1355
  /** Versioned bounded output archive retained with the durable completion replay. */
1091
1356
  archivePath?: string;
1092
1357
  results?: WaitCompletionChild[];
1358
+ workflowChildren?: WorkflowChildSummaryV1;
1359
+ }
1360
+
1361
+ export interface AgentCapabilitiesSnapshot {
1362
+ agents: AgentCapabilityRow[];
1363
+ restrictedCount: number;
1364
+ capabilityCeilingSources?: string[];
1365
+ }
1366
+
1367
+ export interface AgentCapabilityRow {
1368
+ name: string;
1369
+ description: string;
1370
+ source: "builtin" | "package" | "user" | "project" | "runtime";
1371
+ executable: boolean;
1372
+ restrictionSources?: string[];
1373
+ aliases?: string[];
1374
+ 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"] };
1375
+ tools: { ambient: boolean; names: string[]; excludeTools?: string[]; mcpDirectTools: string[]; mutationTools?: string[] };
1376
+ model?: { value?: string; fallbackModels?: string[]; thinking?: string | false };
1377
+ execution?: { defaultAsync?: boolean; timeoutMs?: number };
1378
+ output?: { path?: string; mode?: OutputMode };
1379
+ extensions?: { names?: string[]; subagentOnly?: string[]; skills?: string[] };
1093
1380
  }
1094
1381
 
1095
1382
  export interface Details {
@@ -1100,13 +1387,20 @@ export interface Details {
1100
1387
  /** Run-level context summary. "mixed" when children resolved to different modes. */
1101
1388
  context?: "fresh" | "fork" | "mixed";
1102
1389
  results: SingleResult[];
1390
+ workflowChildren?: WorkflowChildSummaryV1;
1103
1391
  /**
1104
- * Terminal completion payloads for runs this subagent_wait call observed
1392
+ * Terminal completion payloads for runs this bg_wait call observed
1105
1393
  * finishing. Async completions travel as result files that are consumed and
1106
1394
  * deleted after text delivery, so without this field their run and artifact
1107
1395
  * identity never reaches tool_result details.
1108
1396
  */
1109
1397
  completions?: WaitCompletion[];
1398
+ wait?: {
1399
+ reason: "window_elapsed";
1400
+ timedOut: true;
1401
+ activeRunIds: string[];
1402
+ activeProviderItems: Array<{ provider: string; id: string }>;
1403
+ };
1110
1404
  controlEvents?: ControlEvent[];
1111
1405
  steering?: SteerActionResult;
1112
1406
  asyncId?: string;
@@ -1116,7 +1410,6 @@ export interface Details {
1116
1410
  deadlineAt?: number;
1117
1411
  timedOut?: boolean;
1118
1412
  stopped?: boolean;
1119
- turnBudget?: ResolvedTurnBudget;
1120
1413
  toolBudget?: ResolvedToolBudget;
1121
1414
  usageBudget?: UsageBudgetState;
1122
1415
  progress?: AgentProgress[];
@@ -1136,6 +1429,9 @@ export interface Details {
1136
1429
  totalSteps?: number; // Total steps in chain
1137
1430
  currentStepIndex?: number; // 0-indexed current step (for running chains)
1138
1431
  workflowGraph?: WorkflowGraphSnapshot;
1432
+ /** Validated, display-only fanout plan supplied with a workflow launch. */
1433
+ preflight?: WorkflowPreflightV1;
1434
+ preflightWarnings?: string[];
1139
1435
  outputs?: ChainOutputMap;
1140
1436
  // Aggregated child usage across all agents in the run
1141
1437
  totalChildUsage?: Usage;
@@ -1145,6 +1441,7 @@ export interface Details {
1145
1441
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1146
1442
  runFanoutRejection?: RunFanoutRejection;
1147
1443
  activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
1444
+ agentCapabilities?: AgentCapabilitiesSnapshot;
1148
1445
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1149
1446
  capabilityAudit?: SubagentCapabilityAudit;
1150
1447
  parallelHandoff?: ParallelHandoffReference;
@@ -1164,8 +1461,10 @@ export interface Details {
1164
1461
  mission?: MissionRecord;
1165
1462
  workflow?: {
1166
1463
  value?: unknown;
1464
+ resource?: WorkflowResourceProvenanceV1;
1465
+ preflightWarnings?: string[];
1167
1466
  trace: Array<{
1168
- operation: "run" | "status" | "steer";
1467
+ operation: "run" | "status" | "steer" | "host";
1169
1468
  key: string;
1170
1469
  state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
1171
1470
  agent?: string;
@@ -1173,6 +1472,9 @@ export interface Details {
1173
1472
  phase?: string;
1174
1473
  label?: string;
1175
1474
  durationMs?: number;
1475
+ /** Internal provenance for a generated runs.lanes child key. */
1476
+ generatedLaneKey?: string;
1477
+ warning?: string;
1176
1478
  error?: string;
1177
1479
  }>;
1178
1480
  emits: unknown[];
@@ -1232,7 +1534,7 @@ export interface AsyncParallelGroupStatus {
1232
1534
  stepIndex: number;
1233
1535
  }
1234
1536
 
1235
- export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1537
+ export type NestedRunState = "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1236
1538
  export type NestedOwnerState = "live" | "gone" | "unknown";
1237
1539
 
1238
1540
  export interface NestedRunAddress {
@@ -1246,7 +1548,9 @@ export interface NestedRunAddress {
1246
1548
 
1247
1549
  export interface NestedStepSummary {
1248
1550
  agent: string;
1249
- status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1551
+ /** Human-readable display name for the child session, when derived at launch. */
1552
+ sessionName?: string;
1553
+ status: "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1250
1554
  model?: string;
1251
1555
  thinking?: string;
1252
1556
  sessionFile?: string;
@@ -1270,6 +1574,7 @@ export interface NestedStepSummary {
1270
1574
  wrapUpRequested?: boolean;
1271
1575
  toolBudget?: ToolBudgetState;
1272
1576
  toolBudgetBlocked?: boolean;
1577
+ sandbox?: string;
1273
1578
  processTerminal?: ProcessTerminalV1;
1274
1579
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1275
1580
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1297,6 +1602,9 @@ export interface NestedRunSummary extends NestedRunAddress {
1297
1602
  capabilityAudit?: SubagentCapabilityAudit;
1298
1603
  state: NestedRunState;
1299
1604
  agent?: string;
1605
+ /** Human-readable display name for the child session, when derived at launch. */
1606
+ sessionName?: string;
1607
+ sandbox?: string;
1300
1608
  agents?: string[];
1301
1609
  model?: string;
1302
1610
  thinking?: string;
@@ -1358,7 +1666,9 @@ export interface AsyncStartedEvent {
1358
1666
  chainStepCount?: number;
1359
1667
  parallelGroups?: AsyncParallelGroupStatus[];
1360
1668
  workflowGraph?: WorkflowGraphSnapshot;
1669
+ preflight?: WorkflowPreflightV1;
1361
1670
  launchContractDigest?: string;
1671
+ sandbox?: string;
1362
1672
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1363
1673
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
1364
1674
  usageBudget?: UsageBudgetState;
@@ -1375,9 +1685,11 @@ export type AgentRunnerConfig =
1375
1685
  | { type: "pi" }
1376
1686
  | {
1377
1687
  type: "external-cli";
1688
+ adapter?: "codex-exec" | "codex-exec-writer" | "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer";
1378
1689
  command: string;
1379
1690
  args?: string[];
1380
1691
  promptDelivery?: "stdin";
1692
+ capabilities?: ExternalCliCapabilityNarrowing;
1381
1693
  }
1382
1694
  | {
1383
1695
  type: "external-job";
@@ -1385,18 +1697,46 @@ export type AgentRunnerConfig =
1385
1697
  options?: Record<string, unknown>;
1386
1698
  };
1387
1699
 
1700
+ export type ExternalCliCapabilityNarrowing = Partial<Record<"steer" | "resume" | "structuredOutput" | "toolEvents" | "supervisor" | "forkContext" | "extensionBindings", false>>;
1701
+
1702
+ export interface ExternalCliCapabilities {
1703
+ stop: true;
1704
+ steer: false;
1705
+ resume: false;
1706
+ structuredOutput: false;
1707
+ toolEvents: false;
1708
+ supervisor: "unsupported";
1709
+ forkContext: false;
1710
+ extensionBindings: false;
1711
+ }
1712
+
1713
+ export interface ExternalCliReceiptMetadata {
1714
+ 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" };
1715
+ capabilities: ExternalCliCapabilities;
1716
+ safety?:
1717
+ | { sandbox: "read-only"; approvalPolicy: "never"; ephemeral: true }
1718
+ | { access: "workspace-write"; sandbox: "workspace-write"; approvalPolicy: "never"; ephemeral: true }
1719
+ | { permissionMode: "plan"; tools: "none"; mcp: "empty-strict"; settingSources: "none"; sessionPersistence: false }
1720
+ | { access: "read-only"; authentication: "existing-cli-required"; permissionMode: "plan"; tools: "none"; mcp: "empty-strict"; settingSources: "user"; userSettingsTrust: "required"; sessionPersistence: false }
1721
+ | { access: "workspace-write"; authentication: "existing-cli-required"; permissionMode: "acceptEdits"; tools: "Read,Write,Edit,Glob,Grep"; mcp: "empty-strict"; settingSources: "user"; userSettingsTrust: "required"; sessionPersistence: false }
1722
+ | { access: "read-only"; authentication: "cursor-api-key-or-existing-login"; mode: "ask"; sandbox: "enabled"; workspaceTrust: "existing-required"; sessionReuse: false }
1723
+ | { access: "workspace-write"; authentication: "cursor-api-key-or-existing-login"; mode: "print"; sandbox: "enabled"; workspaceTrust: "existing-required"; sessionReuse: false };
1724
+ outputArtifacts?: { stdoutPath?: string; stderrPath?: string; finalOutputPath?: string };
1725
+ handoff: { mode: "fresh" };
1726
+ supervisor: { mode: "unsupported"; reason: string };
1727
+ nonResumableReason: string;
1728
+ }
1729
+
1388
1730
  export interface ExternalCliRunnerStatus {
1389
1731
  type: "external-cli";
1390
1732
  command: string;
1391
1733
  args: string[];
1392
- promptDelivery: "stdin";
1393
- capabilities: {
1394
- stop: true;
1395
- steer: false;
1396
- resume: false;
1397
- structuredOutput: false;
1398
- toolEvents: false;
1399
- };
1734
+ promptDelivery: "stdin" | "prompt-file";
1735
+ adapter: ExternalCliReceiptMetadata["adapter"];
1736
+ safety?: ExternalCliReceiptMetadata["safety"];
1737
+ capabilities: ExternalCliCapabilities;
1738
+ unsupportedReasons: Record<Exclude<keyof ExternalCliCapabilities, "stop">, string>;
1739
+ nonResumableReason: string;
1400
1740
  }
1401
1741
 
1402
1742
  export interface ExternalJobRunnerStatus {
@@ -1443,6 +1783,11 @@ export interface ExternalProcessStatus {
1443
1783
  processSignal?: string | null;
1444
1784
  stdoutPath: string;
1445
1785
  stderrPath: string;
1786
+ finalOutputPath?: string;
1787
+ stdoutBytes?: number;
1788
+ stderrBytes?: number;
1789
+ stdoutTruncated?: boolean;
1790
+ stderrTruncated?: boolean;
1446
1791
  }
1447
1792
 
1448
1793
  export interface AsyncStatus {
@@ -1456,7 +1801,7 @@ export interface AsyncStatus {
1456
1801
  mode: SubagentRunMode;
1457
1802
  context?: "fresh" | "fork" | "mixed";
1458
1803
  isNested?: boolean;
1459
- state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1804
+ state: "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1460
1805
  /** Display-only dismissal marker for a reload-orphaned workflow. */
1461
1806
  displayDismissedAt?: number;
1462
1807
  error?: string;
@@ -1490,23 +1835,29 @@ export interface AsyncStatus {
1490
1835
  pendingAppends?: number;
1491
1836
  parallelGroups?: AsyncParallelGroupStatus[];
1492
1837
  workflowGraph?: WorkflowGraphSnapshot;
1838
+ preflight?: WorkflowPreflightV1;
1493
1839
  processTerminal?: ProcessTerminalV1;
1494
1840
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1495
1841
  runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
1496
1842
  launchContractDigest?: string;
1843
+ sandbox?: string;
1497
1844
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1498
1845
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
1499
1846
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1500
1847
  capabilityAudit?: SubagentCapabilityAudit;
1501
1848
  workflow?: Details["workflow"];
1849
+ workflowChildren?: WorkflowChildSummaryV1;
1502
1850
  parentWorkflowRunId?: string;
1503
1851
  workflowKey?: string;
1852
+ lane?: WorkflowLaneMetadata;
1504
1853
  /** Set when a durable schedule launched this run, so completions can name their origin. */
1505
1854
  scheduleOrigin?: ScheduleOrigin;
1506
1855
  steps?: Array<{
1507
1856
  /** Stable caller-facing child identity for inspect/status/stop. */
1508
1857
  childId?: string;
1509
1858
  agent: string;
1859
+ /** Human-readable display name for the child session, when derived at launch. */
1860
+ sessionName?: string;
1510
1861
  runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1511
1862
  externalProcess?: ExternalProcessStatus;
1512
1863
  externalJob?: ExternalJobStatus;
@@ -1517,6 +1868,15 @@ export interface AsyncStatus {
1517
1868
  phase?: string;
1518
1869
  label?: string;
1519
1870
  workflowKey?: string;
1871
+ lane?: WorkflowLaneMetadata;
1872
+ /** Display-only worktree path copied at launch; handoff remains authoritative. */
1873
+ worktreePath?: string;
1874
+ /** Display-only branch copied at launch; handoff remains authoritative. */
1875
+ branch?: string;
1876
+ /** Display-only provisioning provider copied at launch; handoff remains authoritative. */
1877
+ provider?: ManagedWorktreeProvider;
1878
+ /** Display-only naming evidence copied at launch; handoff remains authoritative. */
1879
+ naming?: WorktreeNaming;
1520
1880
  /** Child run identity for workflow capacity reconciliation. */
1521
1881
  runId?: string;
1522
1882
  /** True only when this workflow child owns a detached async runner. */
@@ -1524,7 +1884,7 @@ export interface AsyncStatus {
1524
1884
  parentWorkflowRunId?: string;
1525
1885
  outputName?: string;
1526
1886
  structured?: boolean;
1527
- status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1887
+ status: "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1528
1888
  stopRequested?: boolean;
1529
1889
  stopRequestedAt?: number;
1530
1890
  children?: NestedRunSummary[];
@@ -1557,6 +1917,7 @@ export interface AsyncStatus {
1557
1917
  skills?: string[];
1558
1918
  model?: string;
1559
1919
  thinking?: string;
1920
+ contextLimit?: number;
1560
1921
  thinkingCeiling?: ThinkingLevel;
1561
1922
  attemptedModels?: string[];
1562
1923
  modelAttempts?: ModelAttempt[];
@@ -1571,6 +1932,7 @@ export interface AsyncStatus {
1571
1932
  acceptance?: AcceptanceLedger;
1572
1933
  agentContract?: AgentContract;
1573
1934
  launchContractDigest?: string;
1935
+ sandbox?: string;
1574
1936
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1575
1937
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
1576
1938
  execution?: ExecutionProjection;
@@ -1590,9 +1952,10 @@ export interface AsyncStatus {
1590
1952
  parallelHandoff?: ParallelHandoffReference;
1591
1953
  }
1592
1954
 
1593
- export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
1955
+ export type AsyncJobStep = Omit<NonNullable<AsyncStatus["steps"]>[number], "timeoutRecovery"> & {
1594
1956
  index?: number;
1595
1957
  description?: string;
1958
+ timeoutRecovery?: TimeoutRecoveryProjection;
1596
1959
  };
1597
1960
 
1598
1961
  export interface AsyncJobState {
@@ -1604,7 +1967,7 @@ export interface AsyncJobState {
1604
1967
  cwd?: string;
1605
1968
  /** Parent-resolved child session root retained for trusted live transcript lookup. */
1606
1969
  sessionRoot?: string;
1607
- status: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1970
+ status: "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1608
1971
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1609
1972
  description?: string;
1610
1973
  pid?: number;
@@ -1625,7 +1988,12 @@ export interface AsyncJobState {
1625
1988
  currentStep?: number;
1626
1989
  chainStepCount?: number;
1627
1990
  parallelGroups?: AsyncParallelGroupStatus[];
1991
+ /** Bounded host-owned CI/gate nodes loaded from the workflow status graph. */
1992
+ hostSteps?: HostStepNodeV1[];
1993
+ /** Full bounded workflow plan, including not-yet-materialized stages. */
1994
+ workflowGraph?: WorkflowGraphSnapshot;
1628
1995
  steps?: AsyncJobStep[];
1996
+ preflight?: WorkflowPreflightV1;
1629
1997
  stepsTotal?: number;
1630
1998
  runningSteps?: number;
1631
1999
  completedSteps?: number;
@@ -1654,10 +2022,14 @@ export interface AsyncJobState {
1654
2022
  parentWorkflowRunId?: string;
1655
2023
  workflowKey?: string;
1656
2024
  workflow?: Details["workflow"];
2025
+ workflowChildren?: WorkflowChildSummaryV1;
2026
+ lane?: WorkflowLaneMetadata;
1657
2027
  }
1658
2028
 
1659
2029
  export interface ForegroundResumeChild {
1660
2030
  agent: string;
2031
+ /** Human-readable display name for the child session, when derived at launch. */
2032
+ sessionName?: string;
1661
2033
  index: number;
1662
2034
  context?: "fresh" | "fork";
1663
2035
  sessionFile?: string;
@@ -1671,6 +2043,8 @@ export interface ForegroundResumeChild {
1671
2043
  currentPath?: string;
1672
2044
  turnCount?: number;
1673
2045
  tokens?: number;
2046
+ window?: number;
2047
+ windowPeak?: number;
1674
2048
  toolCount?: number;
1675
2049
  exitCode?: number;
1676
2050
  error?: string;
@@ -1685,7 +2059,16 @@ export interface ForegroundResumeChild {
1685
2059
  detachedReason?: string;
1686
2060
  acceptance?: AcceptanceLedger;
1687
2061
  agentContract?: AgentContract;
2062
+ /** Private bounded launch fields needed to preserve the child contract on resume. */
2063
+ resumeContract?: {
2064
+ outputSchema?: JsonSchemaObject;
2065
+ agentContract?: AgentContract;
2066
+ acceptance?: AcceptanceInput;
2067
+ output?: string | boolean;
2068
+ outputMode?: OutputMode;
2069
+ };
1688
2070
  launchContractDigest?: string;
2071
+ sandbox?: string;
1689
2072
  /** Private retained launch authority. Never project into status or result output. */
1690
2073
  extensionBindings?: ExtensionBindings;
1691
2074
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
@@ -1711,6 +2094,8 @@ export interface ForegroundResumeRun {
1711
2094
  export interface ForegroundChildControl {
1712
2095
  index: number;
1713
2096
  agent: string;
2097
+ /** Human-readable display name for the child's session, when derived at launch. */
2098
+ sessionName?: string;
1714
2099
  description?: string;
1715
2100
  startedAt: number;
1716
2101
  updatedAt: number;
@@ -1723,11 +2108,25 @@ export interface ForegroundChildControl {
1723
2108
  tokens?: number;
1724
2109
  inputTokens?: number;
1725
2110
  outputTokens?: number;
2111
+ window?: number;
2112
+ windowPeak?: number;
1726
2113
  model?: string;
1727
2114
  thinking?: string;
1728
2115
  toolCount?: number;
1729
2116
  interrupt?: () => boolean;
1730
2117
  detach?: () => boolean;
2118
+ /** Steer the live in-process child session; undefined until the session exists. */
2119
+ steer?: (input: ForegroundSteerInput) => Promise<ForegroundSteerOutcome>;
2120
+ }
2121
+
2122
+ export interface ForegroundSteerInput {
2123
+ message: string;
2124
+ mode?: "steer" | "follow_up" | "auto";
2125
+ }
2126
+
2127
+ export interface ForegroundSteerOutcome {
2128
+ state: "delivered" | "queued" | "failed";
2129
+ reason?: string;
1731
2130
  }
1732
2131
 
1733
2132
  export interface ForegroundRunControl {
@@ -1736,8 +2135,6 @@ export interface ForegroundRunControl {
1736
2135
  parentWorkflowRunId?: string;
1737
2136
  /** Stable workflow lane key for this live foreground child. */
1738
2137
  workflowKey?: string;
1739
- /** Private control root used to steer a live workflow-owned child. */
1740
- workflowSteeringDir?: string;
1741
2138
  /** Originating parent session; required for public fleet projection. */
1742
2139
  sessionId?: string;
1743
2140
  mode: SubagentRunMode;
@@ -1746,6 +2143,8 @@ export interface ForegroundRunControl {
1746
2143
  /** Effective working directory used to resolve live transcript artifacts. */
1747
2144
  cwd?: string;
1748
2145
  currentAgent?: string;
2146
+ /** Human-readable display name for the current child session, when derived at launch. */
2147
+ sessionName?: string;
1749
2148
  currentIndex?: number;
1750
2149
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1751
2150
  description?: string;
@@ -1758,6 +2157,8 @@ export interface ForegroundRunControl {
1758
2157
  tokens?: number;
1759
2158
  inputTokens?: number;
1760
2159
  outputTokens?: number;
2160
+ window?: number;
2161
+ windowPeak?: number;
1761
2162
  model?: string;
1762
2163
  thinking?: string;
1763
2164
  toolCount?: number;
@@ -1775,6 +2176,7 @@ export interface ForegroundRunControl {
1775
2176
  nestedChildren?: NestedRunSummary[];
1776
2177
  interrupt?: () => boolean;
1777
2178
  detach?: () => boolean;
2179
+ steer?: ForegroundChildControl["steer"];
1778
2180
  }
1779
2181
 
1780
2182
  export interface WaitSubscriptionRecord {
@@ -1797,6 +2199,8 @@ export interface ActiveAsyncCapacitySnapshot {
1797
2199
  export interface SubagentState {
1798
2200
  baseCwd: string;
1799
2201
  currentSessionId: string | null;
2202
+ /** Session for which active status projections were restored successfully. */
2203
+ statusProjectionSessionId?: string | null;
1800
2204
  /** Reload-stable identity for this parent Pi process/window. */
1801
2205
  completionOwnerId?: string;
1802
2206
  /** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
@@ -1808,6 +2212,8 @@ export interface SubagentState {
1808
2212
  parentSessionFile?: string | null;
1809
2213
  /** Extension-owned roots trusted for child session transcript reads. */
1810
2214
  trustedSessionRoots?: string[];
2215
+ /** Pi sessions base that caps exact runtime-recorded session file trust. */
2216
+ trustedSessionFileRoot?: string;
1811
2217
  /** Live async session roots created by this parent executor, keyed by run id. */
1812
2218
  liveAsyncSessionRoots?: Map<string, string>;
1813
2219
  /** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
@@ -1935,18 +2341,30 @@ export interface SubagentChildStatusEvent {
1935
2341
  // Execution Options
1936
2342
  // ============================================================================
1937
2343
 
2344
+ /** Live controls for one in-process foreground child session. */
2345
+ export interface ForegroundChildSessionControls {
2346
+ steer: (text: string) => Promise<void>;
2347
+ followUp: (text: string) => Promise<void>;
2348
+ }
2349
+
1938
2350
  export interface RunSyncOptions {
2351
+ /** Exact discovery provenance for an unknown-agent error; omission uses defensive fallback discovery. */
2352
+ unknownAgentDiagnosticContext?: import("../agents/agents.ts").UnknownAgentDiagnosticContext;
2353
+ /** Session factory for the in-process child; defaults to the process-wide factory. */
2354
+ childSessionFactory?: import("../runs/shared/child-session.ts").ChildSessionFactory;
2355
+ /** The launching executor's own child runtime when it is itself an in-process child. */
2356
+ childRuntime?: import("../runs/shared/child-runtime-config.ts").ChildRuntimeConfig;
2357
+ /** Fires once the child session exists and can be steered. */
2358
+ onChildSession?: (controls: ForegroundChildSessionControls) => void;
1939
2359
  /** Opt-in global permission rules; missing tools remain allowed. */
1940
2360
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
1941
2361
  /** Session id of the direct parent session for permission-system ask forwarding. */
1942
2362
  parentSessionId?: string;
1943
- /** Private prompt-runtime steering transport for workflow-owned foreground children. */
1944
- steerInboxDir?: string;
1945
- steerCapabilityPath?: string;
1946
- steerAckDir?: string;
1947
2363
  /** Resolved launch context for this child. */
1948
2364
  context?: "fresh" | "fork";
1949
2365
  cwd?: string;
2366
+ /** Original cwd input retained for launch diagnostics. */
2367
+ requestedCwd?: string;
1950
2368
  signal?: AbortSignal;
1951
2369
  interruptSignal?: AbortSignal;
1952
2370
  timeoutMs?: number;
@@ -1955,15 +2373,16 @@ export interface RunSyncOptions {
1955
2373
  toolTimeoutMs?: number;
1956
2374
  /** Raw global config.toolTimeoutMs, used by the per-child resolver. */
1957
2375
  configToolTimeoutMs?: number;
1958
- turnBudget?: ResolvedTurnBudget;
1959
2376
  usageBudget?: UsageBudgetConfig;
1960
- /** Enforce maxTurns + graceTurns as a hard model-turn boundary. */
1961
- enforceHardTurnLimit?: boolean;
1962
2377
  toolBudget?: ResolvedToolBudget;
2378
+ /** Selected global sandbox profile, when this child requested one. */
2379
+ sandbox?: string;
1963
2380
  allowZeroToolBudget?: boolean;
1964
2381
  allowIntercomDetach?: boolean;
1965
2382
  intercomEvents?: IntercomEventBus;
1966
2383
  onUpdate?: (r: import("@earendil-works/pi-agent-core").AgentToolResult<Details>) => void;
2384
+ /** Internal structured-delegation transport optimization: skip unchanged live snapshots. */
2385
+ suppressUnchangedDelegationUpdates?: boolean;
1967
2386
  onControlEvent?: (event: ControlEvent) => void;
1968
2387
  /** Exposes a non-terminating detach callback while the child is active. */
1969
2388
  onDetachReady?: (detach: (reason?: string) => boolean) => void;
@@ -1983,11 +2402,18 @@ export interface RunSyncOptions {
1983
2402
  sessionFile?: string;
1984
2403
  share?: boolean;
1985
2404
  outputPath?: string;
2405
+ outputClaimPath?: string;
1986
2406
  outputMode?: OutputMode;
1987
2407
  maxSubagentDepth?: number;
1988
2408
  /** Effective parent wait-tool setting propagated to the child runtime. */
1989
2409
  waitToolEnabled?: boolean;
2410
+ /** Effective parent default wait window propagated to the child runtime. */
2411
+ waitToolDefaultTimeoutMs?: number;
1990
2412
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
2413
+ /** Whether project-scoped agent/config inputs were trusted by the host. */
2414
+ projectTrusted?: boolean;
2415
+ /** Exact trusted parent cwd; project config applies only when it matches this child cwd. */
2416
+ trustedProjectCwd?: string;
1991
2417
  runFanoutBudget?: RunFanoutBudgetDescriptor;
1992
2418
  nestedRoute?: NestedRouteInfo;
1993
2419
  /** Override the agent's default model (format: "provider/id" or just "id") */
@@ -1996,16 +2422,22 @@ export interface RunSyncOptions {
1996
2422
  fast?: boolean;
1997
2423
  /** The override came from the running parent session, not configuration. */
1998
2424
  modelOverrideFromParent?: boolean;
2425
+ /** How the launch model was selected: explicit per-call, configured agent primary, or inherited parent. */
2426
+ modelOrigin?: "explicit" | "inherited" | "configured";
1999
2427
  /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
2000
2428
  llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
2001
2429
  /** Override the agent's default thinking level for this run */
2002
2430
  thinkingOverride?: AgentConfig["thinking"];
2003
2431
  thinkingCeiling?: ThinkingLevel;
2004
2432
  extensionBindings?: ExtensionBindings;
2433
+ /** Package-internal one-use authorization for one foreground workflow child. */
2434
+ workflowChildPermitLaunch?: WorkflowChildPermitContext;
2005
2435
  /** Registry models available for heuristic bare-model resolution */
2006
- availableModels?: Array<{ provider: string; id: string; fullId: string }>;
2436
+ availableModels?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
2007
2437
  /** Current parent-session provider to prefer for ambiguous bare model ids */
2008
2438
  preferredModelProvider?: string;
2439
+ /** Parent Pi event host used to snapshot runtime-registered MCP servers before child launch. */
2440
+ runtimeSnapshotHost?: import("../runs/shared/mcp-direct-tool-allowlist.ts").McpRuntimeSnapshotHost;
2009
2441
  /** Optional subagent model-scope enforcement for fallback candidates */
2010
2442
  modelScope?: ModelScopeRule | ModelScopeRule[];
2011
2443
  /** Skills to make available (overrides agent default if provided) */
@@ -2015,6 +2447,7 @@ export interface RunSyncOptions {
2015
2447
  schemaPath: string;
2016
2448
  outputPath: string;
2017
2449
  acceptanceReportPath?: string;
2450
+ acceptanceReportRequired?: boolean;
2018
2451
  };
2019
2452
  agentContract?: AgentContract;
2020
2453
  acceptance?: AcceptanceInput;
@@ -2067,6 +2500,11 @@ export interface ScheduledRunsConfig {
2067
2500
  storeRoot?: string;
2068
2501
  }
2069
2502
 
2503
+ export interface ModelExclusionsConfig {
2504
+ /** Default duration in milliseconds. A lower configured value also shortens active cached exclusions. */
2505
+ defaultTtlMs?: number;
2506
+ }
2507
+
2070
2508
  export type FleetViewPlacement = "aboveEditor" | "belowEditor";
2071
2509
 
2072
2510
  export const FLEET_KEYBINDING_ACTIONS = [
@@ -2102,10 +2540,24 @@ export interface MainWindowRendererConfig {
2102
2540
  compactResultMaxLines?: number;
2103
2541
  }
2104
2542
 
2543
+ export interface ForkContextConfig {
2544
+ /** Keep the complete fork by default, or summarize large text-only tool results before launch. */
2545
+ mode?: "full" | "pruned";
2546
+ /** Required pruning model when mode is "pruned". */
2547
+ model?: string;
2548
+ }
2549
+
2550
+ export interface ActiveAsyncCapacityConfig {
2551
+ /** Reclaim failed runner slots after this age when process proof is unknown; false keeps strict retention. */
2552
+ abandonedSlotReleaseAfterMs?: number | false;
2553
+ }
2554
+
2105
2555
  export interface ExtensionConfig {
2106
2556
  asyncByDefault?: boolean;
2107
2557
  /** Set the context for launches that omit an explicit context. */
2108
2558
  defaultSubagentContext?: "fresh" | "fork";
2559
+ /** Configure how every resolved fork session is prepared before child spawn. */
2560
+ forkContext?: ForkContextConfig;
2109
2561
  /** Optional shortcut that detaches the active foreground single-subagent run. */
2110
2562
  foregroundDetachShortcut?: string;
2111
2563
  /** Show the Claude Code-style navigable fleet. Defaults to true. */
@@ -2116,6 +2568,8 @@ export interface ExtensionConfig {
2116
2568
  fleetKeybindings?: FleetKeybindingsConfig;
2117
2569
  /** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
2118
2570
  asyncWidget?: boolean;
2571
+ /** Configure the process-wide TTL policy for persisted model exclusions. */
2572
+ modelExclusions?: ModelExclusionsConfig;
2119
2573
  /** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
2120
2574
  toolDescriptionMode?: ToolDescriptionMode;
2121
2575
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
@@ -2135,6 +2589,8 @@ export interface ExtensionConfig {
2135
2589
  maxSubagentSpawnsPerRun?: number;
2136
2590
  /** Optional active top-level async run cap per parent session. Unset or 0 means unlimited. */
2137
2591
  maxActiveAsyncRunsPerSession?: number;
2592
+ /** Active-capacity cleanup policy. */
2593
+ capacity?: ActiveAsyncCapacityConfig;
2138
2594
  /** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
2139
2595
  globalConcurrencyLimit?: number;
2140
2596
  /**
@@ -2158,7 +2614,6 @@ export interface ExtensionConfig {
2158
2614
  toolTimeoutMs?: number;
2159
2615
  control?: ControlConfig;
2160
2616
  completionBatch?: CompletionBatchConfig;
2161
- turnBudget?: TurnBudgetConfig;
2162
2617
  toolBudget?: ToolBudgetConfig;
2163
2618
  /** Opt-in native tool permissions. Bash remains outside this policy. */
2164
2619
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
@@ -2168,6 +2623,12 @@ export interface ExtensionConfig {
2168
2623
  worktreeSetupHook?: string;
2169
2624
  worktreeSetupHookTimeoutMs?: number;
2170
2625
  worktreeBaseDir?: string;
2626
+ /** Enable managed worktrees when a launch does not provide an explicit value. */
2627
+ worktree?: boolean;
2628
+ /** Worktree allocator selection. Defaults to auto. */
2629
+ worktreeProvider?: WorktreeProvider;
2630
+ /** Namespace used by managed worktree branches. Defaults to pi-subagents/. */
2631
+ worktreeBranchPrefix?: string;
2171
2632
  /** 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
2633
  artifactDir?: ArtifactDirPreference;
2173
2634
  /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
@@ -2290,7 +2751,7 @@ export const POLL_INTERVAL_MS = 250;
2290
2751
  export const WIDGET_ANIMATION_INTERVAL_MS = 1000;
2291
2752
  export const MAX_WIDGET_JOBS = 4;
2292
2753
  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;
2754
+ 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
2755
 
2295
2756
  export const DEFAULT_FORK_PREAMBLE =
2296
2757
  "You are a delegated subagent running from a fork of the parent session. " +
@@ -2343,8 +2804,17 @@ export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
2343
2804
  return normalizeNonNegativeInteger(value);
2344
2805
  }
2345
2806
 
2346
- export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
2347
- return normalizeMaxSubagentDepth(process.env.PI_SUBAGENT_MAX_DEPTH)
2807
+ /** Depth context of the executor's own child runtime, when it runs as an in-process child. */
2808
+ export interface SubagentDepthContext {
2809
+ depth: number;
2810
+ maxDepth?: number;
2811
+ }
2812
+
2813
+ /** Operator override for the top-level parent; children inherit their limit through their runtime config. */
2814
+ export const SUBAGENT_MAX_DEPTH_ENV = "PI_SUBAGENT_MAX_DEPTH";
2815
+
2816
+ export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number, runtime?: SubagentDepthContext): number {
2817
+ return normalizeMaxSubagentDepth(runtime ? runtime.maxDepth : process.env[SUBAGENT_MAX_DEPTH_ENV])
2348
2818
  ?? normalizeMaxSubagentDepth(configMaxDepth)
2349
2819
  ?? DEFAULT_SUBAGENT_MAX_DEPTH;
2350
2820
  }
@@ -2355,19 +2825,24 @@ export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDep
2355
2825
  return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
2356
2826
  }
2357
2827
 
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;
2828
+ /** Depth of the executor itself: 0 for a top-level parent, its own child depth otherwise. */
2829
+ export function resolveCurrentSubagentDepth(runtime?: SubagentDepthContext): number {
2830
+ const depth = runtime ? runtime.depth : 0;
2831
+ return Number.isFinite(depth) ? depth : 0;
2832
+ }
2833
+
2834
+ export function checkSubagentDepth(configMaxDepth?: number, runtime?: SubagentDepthContext): { blocked: boolean; depth: number; maxDepth: number } {
2835
+ const depth = resolveCurrentSubagentDepth(runtime);
2836
+ const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth, runtime);
2837
+ const blocked = depth >= maxDepth;
2362
2838
  return { blocked, depth, maxDepth };
2363
2839
  }
2364
2840
 
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;
2841
+ /** Depth context handed to a child launched by an executor at `runtime` (undefined for a top-level parent). */
2842
+ export function resolveChildDepth(maxDepth?: number, runtime?: SubagentDepthContext): Required<SubagentDepthContext> {
2368
2843
  return {
2369
- PI_SUBAGENT_DEPTH: String(nextDepth),
2370
- PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
2844
+ depth: resolveCurrentSubagentDepth(runtime) + 1,
2845
+ maxDepth: normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth(undefined, runtime),
2371
2846
  };
2372
2847
  }
2373
2848