@xzzpig/pi-subagents 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (234) hide show
  1. package/CHANGELOG.md +456 -4
  2. package/README.md +3 -3
  3. package/agents/claude-code-writer.md +15 -0
  4. package/agents/claude-code.md +15 -0
  5. package/agents/codex-exec-writer.md +15 -0
  6. package/agents/codex-exec.md +15 -0
  7. package/agents/cursor-agent-writer.md +14 -0
  8. package/agents/cursor-agent.md +14 -0
  9. package/agents/reviewer.md +13 -3
  10. package/agents/scout.md +1 -1
  11. package/docs/agents.md +154 -42
  12. package/docs/configuration.md +85 -26
  13. package/docs/extension-api.md +81 -16
  14. package/docs/missions.md +2 -0
  15. package/docs/models.md +75 -11
  16. package/docs/observability.md +34 -21
  17. package/docs/tool-reference.md +142 -18
  18. package/docs/watchdog.md +92 -114
  19. package/docs/workflows.md +148 -4
  20. package/index.ts +10 -1
  21. package/install.mjs +1 -1
  22. package/package.json +7 -6
  23. package/prompts/council.md +19 -7
  24. package/prompts/parallel-review.md +5 -1
  25. package/prompts/review-loop.md +11 -7
  26. package/skills/council-mode/SKILL.md +44 -215
  27. package/skills/council-mode/references/pass-contracts.md +150 -0
  28. package/skills/pi-subagents/SKILL.md +90 -32
  29. package/skills/pi-subagents/references/constraints-and-recipes.md +34 -223
  30. package/skills/pi-subagents/references/execution-controls.md +104 -19
  31. package/skills/pi-subagents/references/management-authoring-rpc.md +5 -5
  32. package/skills/pi-subagents/references/multi-lane-orchestration.md +16 -4
  33. package/skills/pi-subagents/references/prompting-and-roles.md +71 -36
  34. package/skills/pi-subagents/references/review-and-validation.md +73 -0
  35. package/src/agents/agent-management.ts +471 -114
  36. package/src/agents/agent-refinements.ts +4 -4
  37. package/src/agents/agent-serializer.ts +16 -4
  38. package/src/agents/agents.ts +1076 -351
  39. package/src/agents/builtin-names.ts +6 -0
  40. package/src/agents/runtime-agent-events.ts +70 -0
  41. package/src/agents/runtime-agent-registry.ts +31 -20
  42. package/src/api/agents.ts +10 -5
  43. package/src/api/background-work.ts +12 -3
  44. package/src/api/capability-ceiling.ts +0 -1
  45. package/src/api/{pi-args.ts → child-tool-plan.ts} +1 -1
  46. package/src/api/delegation.ts +0 -7
  47. package/src/api/external-job-provider.ts +10 -1
  48. package/src/api/external-runs.ts +67 -4
  49. package/src/api/preflight.ts +97 -34
  50. package/src/api/project-panes.ts +2 -0
  51. package/src/api/shared-types.ts +6 -0
  52. package/src/extension/config.ts +90 -0
  53. package/src/extension/doctor.ts +15 -13
  54. package/src/extension/fanout-child.ts +17 -16
  55. package/src/extension/index.ts +139 -41
  56. package/src/extension/public-execution.ts +113 -22
  57. package/src/extension/rpc.ts +182 -13
  58. package/src/extension/schemas.ts +63 -21
  59. package/src/extension/tool-description.ts +48 -23
  60. package/src/extension/tool-result.ts +19 -0
  61. package/src/inspectors/herdr/actions.ts +2 -1
  62. package/src/inspectors/herdr/client.ts +3 -3
  63. package/src/inspectors/herdr/focus.ts +55 -0
  64. package/src/inspectors/herdr/inspector-runner.ts +21 -23
  65. package/src/inspectors/herdr/project-panes.ts +228 -44
  66. package/src/inspectors/herdr/session-roots-codec.ts +42 -0
  67. package/src/integrations/herdr-status.ts +75 -5
  68. package/src/intercom/native-supervisor-channel.ts +138 -60
  69. package/src/intercom/result-intercom.ts +2 -0
  70. package/src/intercom/supervisor-ui.ts +243 -0
  71. package/src/profiles/profiles.ts +5 -6
  72. package/src/runs/background/active-async-capacity.ts +103 -18
  73. package/src/runs/background/async-execution.ts +492 -125
  74. package/src/runs/background/async-job-tracker.ts +127 -28
  75. package/src/runs/background/async-resume.ts +67 -29
  76. package/src/runs/background/async-retention.ts +21 -4
  77. package/src/runs/background/async-status-snapshot.ts +23 -261
  78. package/src/runs/background/async-status.ts +199 -14
  79. package/src/runs/background/auto-drain.ts +1 -1
  80. package/src/runs/background/chain-append.ts +8 -3
  81. package/src/runs/background/chain-root-attachment.ts +79 -8
  82. package/src/runs/background/control-channel.ts +101 -214
  83. package/src/runs/background/fleet-view.ts +38 -22
  84. package/src/runs/background/inspect-rpc.ts +8 -8
  85. package/src/runs/background/notify.ts +295 -8
  86. package/src/runs/background/process-terminal.ts +16 -0
  87. package/src/runs/background/result-delivery-ownership.ts +45 -0
  88. package/src/runs/background/result-files.ts +28 -14
  89. package/src/runs/background/result-watcher.ts +43 -19
  90. package/src/runs/background/resume-guidance.ts +2 -2
  91. package/src/runs/background/retained-children.ts +1 -1
  92. package/src/runs/background/run-child-session.ts +613 -0
  93. package/src/runs/background/run-status.ts +99 -18
  94. package/src/runs/background/runner-aliases.ts +125 -0
  95. package/src/runs/background/runner-child-sessions.ts +31 -0
  96. package/src/runs/background/scheduled-runs.ts +174 -18
  97. package/src/runs/background/stale-run-reconciler.ts +13 -4
  98. package/src/runs/background/steering.ts +8 -15
  99. package/src/runs/background/subagent-runner.ts +959 -1159
  100. package/src/runs/background/subagent-wait.ts +86 -31
  101. package/src/runs/background/terminal-run-index.ts +1 -1
  102. package/src/runs/background/wait-completions.ts +45 -2
  103. package/src/runs/background/wait-config.ts +23 -9
  104. package/src/runs/background/wait-tool.ts +27 -19
  105. package/src/runs/foreground/async-steering-action.ts +3 -19
  106. package/src/runs/foreground/async-stop-action.ts +23 -2
  107. package/src/runs/foreground/execution.ts +585 -481
  108. package/src/runs/foreground/foreground-control.ts +13 -0
  109. package/src/runs/foreground/foreground-history.ts +26 -3
  110. package/src/runs/foreground/subagent-executor.ts +1549 -410
  111. package/src/runs/foreground/workflow-detach-reconcile.ts +141 -104
  112. package/src/runs/foreground/workflow-foreground-steering.ts +24 -98
  113. package/src/runs/shared/abort-recovery.ts +119 -0
  114. package/src/runs/shared/acceptance.ts +147 -39
  115. package/src/runs/shared/agent-contract.ts +1 -1
  116. package/src/runs/shared/async-status-projection.ts +565 -0
  117. package/src/runs/shared/background-process-options.ts +9 -0
  118. package/src/runs/shared/capability-ceiling.ts +2 -2
  119. package/src/runs/shared/child-hooks.ts +25 -0
  120. package/src/runs/shared/child-identity.ts +62 -0
  121. package/src/runs/shared/child-launch-plan.ts +151 -0
  122. package/src/runs/shared/child-launch.ts +314 -0
  123. package/src/runs/shared/child-lifecycle.ts +25 -0
  124. package/src/runs/shared/child-runtime-config.ts +126 -0
  125. package/src/runs/shared/child-session.ts +342 -0
  126. package/src/runs/shared/child-tool-plan.ts +540 -0
  127. package/src/runs/shared/claude-code-adapter.ts +133 -0
  128. package/src/runs/shared/codex-exec-adapter.ts +129 -0
  129. package/src/runs/shared/completion-evidence.ts +89 -0
  130. package/src/runs/shared/completion-guard.ts +57 -6
  131. package/src/runs/shared/cursor-agent-adapter.ts +114 -0
  132. package/src/runs/shared/dynamic-fanout.ts +4 -4
  133. package/src/runs/shared/extension-bindings.ts +78 -0
  134. package/src/runs/shared/external-cli-contract.ts +167 -0
  135. package/src/runs/shared/external-cli-preflight.ts +138 -0
  136. package/src/runs/shared/external-cli-runner.ts +349 -54
  137. package/src/runs/shared/external-job-bridge.ts +53 -37
  138. package/src/runs/shared/external-job-runner.ts +126 -23
  139. package/src/runs/shared/fast-mode-extension.ts +10 -0
  140. package/src/runs/shared/host-step-status.ts +231 -0
  141. package/src/runs/shared/lane-metadata.ts +126 -0
  142. package/src/runs/shared/launch-cwd.ts +16 -0
  143. package/src/runs/shared/long-running-guard.ts +2 -1
  144. package/src/runs/shared/mcp-config-sources.ts +422 -0
  145. package/src/runs/shared/mcp-direct-tool-allowlist.ts +222 -158
  146. package/src/runs/shared/mcp-direct-tool-grant.ts +194 -0
  147. package/src/runs/shared/model-exclusions.ts +141 -10
  148. package/src/runs/shared/model-fallback.ts +187 -33
  149. package/src/runs/shared/model-scope.ts +106 -39
  150. package/src/runs/shared/mutation-evidence.ts +199 -0
  151. package/src/runs/shared/nested-events.ts +38 -48
  152. package/src/runs/shared/nested-path.ts +0 -14
  153. package/src/runs/shared/nested-render.ts +9 -5
  154. package/src/runs/shared/orca-progress-tabs.ts +83 -16
  155. package/src/runs/shared/parallel-handoff.ts +423 -7
  156. package/src/runs/shared/parallel-utils.ts +28 -5
  157. package/src/runs/shared/permissions.ts +1 -14
  158. package/src/runs/shared/pi-spawn.ts +69 -35
  159. package/src/runs/shared/process-signal.ts +16 -0
  160. package/src/runs/shared/run-fanout-budget.ts +0 -13
  161. package/src/runs/shared/run-history.ts +21 -1
  162. package/src/runs/shared/runtime-acknowledged-extensions.ts +0 -27
  163. package/src/runs/shared/single-output.ts +89 -22
  164. package/src/runs/shared/structured-output.ts +61 -7
  165. package/src/runs/shared/subagent-control.ts +6 -2
  166. package/src/runs/shared/subagent-prompt-runtime.ts +216 -360
  167. package/src/runs/shared/task-intent.ts +21 -7
  168. package/src/runs/shared/tool-availability.ts +18 -64
  169. package/src/runs/shared/tool-budget.ts +0 -14
  170. package/src/runs/shared/tool-timeout.ts +1 -1
  171. package/src/runs/shared/workflow-graph.ts +16 -0
  172. package/src/runs/shared/worktree-cleanup-plan.ts +866 -0
  173. package/src/runs/shared/worktree.ts +571 -62
  174. package/src/shared/atomic-json.ts +3 -1
  175. package/src/shared/child-session-name.ts +46 -0
  176. package/src/shared/extension-context.ts +24 -0
  177. package/src/shared/fork-context.ts +21 -12
  178. package/src/shared/fork-session-cwd.ts +27 -0
  179. package/src/shared/formatters.ts +18 -3
  180. package/src/shared/jsonl-writer.ts +11 -0
  181. package/src/shared/launch-contract.ts +20 -6
  182. package/src/shared/pruned-fork.ts +450 -0
  183. package/src/shared/session-file-trust.ts +19 -0
  184. package/src/shared/session-tokens.ts +14 -3
  185. package/src/shared/settings.ts +21 -102
  186. package/src/shared/shortcuts.ts +17 -0
  187. package/src/shared/thinking-ceiling.ts +46 -0
  188. package/src/shared/types.ts +644 -75
  189. package/src/shared/utils.ts +60 -93
  190. package/src/shared/workflow-child-permit.ts +207 -0
  191. package/src/slash/delegation-adapters.ts +1 -9
  192. package/src/slash/delegation-request.ts +0 -4
  193. package/src/slash/prompt-template-bridge.ts +37 -1
  194. package/src/slash/slash-bridge.ts +1 -2
  195. package/src/slash/slash-commands.ts +383 -116
  196. package/src/slash/slash-live-state.ts +22 -11
  197. package/src/slash/subagents-admin.ts +29 -12
  198. package/src/tui/fleet-native-transcript.ts +4 -0
  199. package/src/tui/fleet-status.ts +278 -90
  200. package/src/tui/fleet-transcript.ts +11 -5
  201. package/src/tui/fleet.ts +54 -28
  202. package/src/tui/render-helpers.ts +31 -0
  203. package/src/tui/render.ts +1433 -166
  204. package/src/watchdog/change-signature.ts +40 -1
  205. package/src/watchdog/child-status.ts +54 -34
  206. package/src/watchdog/diff-tool.ts +77 -0
  207. package/src/watchdog/emission-guard.ts +5 -3
  208. package/src/watchdog/guidance.ts +20 -0
  209. package/src/watchdog/permission-arbiter.ts +59 -52
  210. package/src/watchdog/register-child.ts +28 -25
  211. package/src/watchdog/register-main.ts +10 -9
  212. package/src/watchdog/render.ts +4 -5
  213. package/src/watchdog/review.ts +15 -4
  214. package/src/watchdog/rules.ts +70 -0
  215. package/src/watchdog/runtime.ts +75 -92
  216. package/src/watchdog/scope.ts +0 -11
  217. package/src/watchdog/settings.ts +48 -104
  218. package/src/watchdog/turn-delta.ts +1 -1
  219. package/src/watchdog/types.ts +18 -32
  220. package/src/watchdog/warning-format.ts +0 -1
  221. package/src/workflows/chat-progress.ts +7 -3
  222. package/src/workflows/host-command.ts +235 -0
  223. package/src/workflows/scripted-workflow.ts +1142 -69
  224. package/src/workflows/workflow-checklist.ts +439 -0
  225. package/src/workflows/workflow-child-summary.ts +121 -0
  226. package/src/workflows/workflow-preflight.ts +297 -0
  227. package/src/workflows/workflow-receipt.ts +232 -6
  228. package/src/workflows/workflow-resources.ts +150 -0
  229. package/src/workflows/workflow-settlement.ts +246 -0
  230. package/src/runs/shared/child-protocol.ts +0 -401
  231. package/src/runs/shared/pi-args.ts +0 -858
  232. package/src/runs/shared/subagent-startup-retry.ts +0 -116
  233. package/src/runs/shared/turn-budget.ts +0 -98
  234. package/src/shared/post-exit-stdio-guard.ts +0 -85
@@ -8,10 +8,14 @@ import type { Message } from "@earendil-works/pi-ai";
8
8
  import type { AgentConfig } from "../agents/agents.ts";
9
9
  import type { FSWatcher } from "node:fs";
10
10
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
11
- import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
11
+ import type { ModelScopeRule } from "../runs/shared/model-scope.ts";
12
12
  import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
13
13
  import type { AuthorityPolicyConfig } from "../policy/authority.ts";
14
+ import type { ThinkingLevel } from "./model-info.ts";
14
15
  import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
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";
15
19
 
16
20
  // ============================================================================
17
21
  // Basic Types
@@ -37,11 +41,43 @@ export interface ChainOutputMapEntry {
37
41
 
38
42
  export type ChainOutputMap = Record<string, ChainOutputMapEntry>;
39
43
 
40
- 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
+ }
41
77
 
42
78
  export interface WorkflowGraphNode {
43
79
  id: string;
44
- kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
80
+ kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent" | "host-step";
45
81
  agent?: string;
46
82
  phase?: string;
47
83
  label: string;
@@ -61,6 +97,7 @@ export interface WorkflowGraphNode {
61
97
  structured?: boolean;
62
98
  acceptanceStatus?: AcceptanceLedgerStatus;
63
99
  error?: string;
100
+ hostStep?: HostStepNodeV1;
64
101
  }
65
102
 
66
103
  export interface WorkflowGraphSnapshot {
@@ -71,18 +108,104 @@ export interface WorkflowGraphSnapshot {
71
108
  currentNodeId?: string;
72
109
  }
73
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
+
74
131
  export type WorkflowReceiptState = "complete" | "failed" | "paused" | "stopped";
75
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
+
76
195
  type WorkflowReceiptEntryResumability =
77
196
  | { latestRunId: string; resumability: { state: "resumable" } }
78
197
  | { latestRunId?: string; resumability: { state: "not-resumable"; reason: string } };
79
198
 
80
199
  export type WorkflowReceiptEntry = WorkflowReceiptEntryResumability & {
81
200
  key: string;
201
+ lane?: WorkflowLaneMetadata;
202
+ terminalOutcome?: WorkflowTerminalOutcome;
82
203
  agent?: string;
83
204
  requestedContext?: "fresh" | "fork";
84
205
  resolvedContext?: "fresh" | "fork" | "mixed";
85
206
  outputReference?: string;
207
+ acceptanceRecovery?: AcceptanceRecoveryMetadata;
208
+ externalAdapter?: ExternalCliReceiptMetadata;
86
209
  continuation: { runIds: string[] };
87
210
  };
88
211
 
@@ -92,6 +215,12 @@ export interface WorkflowReceipt {
92
215
  state: WorkflowReceiptState;
93
216
  createdAt: number;
94
217
  entries: Record<string, WorkflowReceiptEntry>;
218
+ resource?: WorkflowResourceProvenanceV1;
219
+ hostSteps?: HostStepNodeV1[];
220
+ workflowChildren?: WorkflowChildSummaryV1;
221
+ workflowResolution?: WorkflowTerminalResolution;
222
+ terminalOutcome?: WorkflowTerminalOutcome;
223
+ recovery?: WorkflowRecoveryAction[];
95
224
  }
96
225
 
97
226
  export interface SavedOutputReference {
@@ -118,16 +247,6 @@ export interface Usage {
118
247
  turns: number;
119
248
  }
120
249
 
121
- export interface TurnBudgetConfig {
122
- maxTurns: number;
123
- graceTurns?: number;
124
- }
125
-
126
- export interface ResolvedTurnBudget {
127
- maxTurns: number;
128
- graceTurns: number;
129
- }
130
-
131
250
  export interface ToolBudgetConfig {
132
251
  soft?: number;
133
252
  hard: number;
@@ -150,9 +269,19 @@ export interface ToolBudgetState extends ResolvedToolBudget {
150
269
  blockedTool?: string;
151
270
  }
152
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
+ */
153
276
  export type TurnBudgetOutcome = "within-budget" | "wrap-up-requested" | "termination-deferred" | "exceeded";
154
277
 
155
- 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;
156
285
  outcome: TurnBudgetOutcome;
157
286
  turnCount: number;
158
287
  wrapUpRequestedAtTurn?: number;
@@ -164,6 +293,10 @@ export interface TokenUsage {
164
293
  input: number;
165
294
  output: number;
166
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;
167
300
  }
168
301
 
169
302
  export type ActivityState = "active_long_running" | "needs_attention";
@@ -214,6 +347,8 @@ export interface CompletionBatchConfig {
214
347
 
215
348
  export interface WaitToolConfigObject {
216
349
  enabled?: boolean;
350
+ /** Default blocking window for bg_wait calls that omit timeoutMs. */
351
+ defaultTimeoutMs?: number;
217
352
  }
218
353
 
219
354
  export type WaitToolConfig = boolean | WaitToolConfigObject;
@@ -234,6 +369,7 @@ export interface ControlEvent {
234
369
  tokens?: number;
235
370
  toolCount?: number;
236
371
  currentTool?: string;
372
+ toolCallId?: string;
237
373
  currentToolDurationMs?: number;
238
374
  currentPath?: string;
239
375
  elapsedMs?: number;
@@ -248,6 +384,17 @@ export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped"
248
384
  export type SubagentOutputState = "present" | "absent" | "unknown";
249
385
  export type SubagentRunMode = "single" | "parallel" | "chain" | "workflow";
250
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
+ }
251
398
 
252
399
  export interface ParallelHandoffPatch {
253
400
  path: string;
@@ -264,6 +411,11 @@ export interface ParallelHandoffChild {
264
411
  index: number;
265
412
  taskIndex: number;
266
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;
267
419
  status: SubagentResultStatus;
268
420
  summary: string;
269
421
  outputPath?: string;
@@ -273,10 +425,23 @@ export interface ParallelHandoffChild {
273
425
  patch: ParallelHandoffPatch;
274
426
  }
275
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
+
276
437
  export interface ParallelHandoffCleanupTask {
277
438
  index: number;
278
439
  path: string;
279
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;
280
445
  worktreeRemoved: boolean;
281
446
  branchRemoved: boolean;
282
447
  preserved?: boolean;
@@ -284,11 +449,38 @@ export interface ParallelHandoffCleanupTask {
284
449
  errors?: string[];
285
450
  }
286
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
+
287
477
  export interface ParallelHandoffGroup {
288
478
  stepIndex: number;
289
479
  baseCommit: string;
290
480
  repoRoot: string;
291
481
  children: ParallelHandoffChild[];
482
+ /** Optional launch identities for pending groups before child results settle. */
483
+ laneBindings?: ParallelHandoffLaneBinding[];
292
484
  cleanup: {
293
485
  state: "complete" | "partial";
294
486
  tasks: ParallelHandoffCleanupTask[];
@@ -306,6 +498,9 @@ export interface ParallelHandoffManifest {
306
498
  createdAt: number;
307
499
  updatedAt: number;
308
500
  groups: ParallelHandoffGroup[];
501
+ merge?: ParallelHandoffMergeEvidence;
502
+ supersession?: ParallelHandoffSupersessionEvidence;
503
+ cleanupEligibility?: CleanupEligibility;
309
504
  }
310
505
 
311
506
  export interface ParallelHandoffReference {
@@ -315,6 +510,7 @@ export interface ParallelHandoffReference {
315
510
  childCount: number;
316
511
  changedPatches: number;
317
512
  cleanupState: "complete" | "partial";
513
+ cleanupEligibility?: CleanupEligibility;
318
514
  }
319
515
 
320
516
  export interface AgentContract {
@@ -323,7 +519,7 @@ export interface AgentContract {
323
519
 
324
520
  export type ChainGateLayer = "execution" | "acceptance";
325
521
 
326
- export type ExecutionProjectionStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
522
+ export type ExecutionProjectionStatus = "completed" | "failed" | "partial" | "paused" | "stopped" | "detached";
327
523
 
328
524
  export interface ExecutionProjection {
329
525
  status: ExecutionProjectionStatus;
@@ -342,17 +538,77 @@ export interface ReviewProjection {
342
538
  }
343
539
 
344
540
  export interface FileMutationEffect {
345
- status: "not-requested" | "not-applicable" | "observed" | "missing";
541
+ status: "not-requested" | "not-applicable" | "observed" | "missing" | "blocked";
346
542
  expected: boolean;
347
543
  attempted: boolean;
348
544
  message?: string;
349
545
  resolvedBy?: "llm-intent-arbiter";
546
+ evidence?: TrackedMutationEvidence;
547
+ }
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;
350
562
  }
351
563
 
352
564
  export interface EffectsProjection {
353
565
  fileMutation?: FileMutationEffect;
566
+ settlementDiagnostic?: SettlementDiagnostic;
354
567
  }
355
568
 
569
+ export interface TrackedMutationSnapshot {
570
+ source: "tracked-files";
571
+ trackedOnly: true;
572
+ cwd: string;
573
+ gitRoot?: string;
574
+ dirtyFiles: string[];
575
+ fingerprints: Record<string, TrackedMutationFingerprint>;
576
+ truncated?: boolean;
577
+ unavailable?: string;
578
+ }
579
+
580
+ export type TrackedMutationFingerprint = { kind: "diff"; digest: string };
581
+
582
+ export interface TrackedMutationEvidence {
583
+ source: "tracked-files";
584
+ trackedOnly: true;
585
+ changedFiles: string[];
586
+ attemptedMutation: boolean;
587
+ truncated?: boolean;
588
+ unavailable?: string;
589
+ }
590
+
591
+ export interface TimeoutRecoverySummary {
592
+ termination: "timed-out" | "stopped";
593
+ changedFiles: string[];
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";
599
+ currentTool?: string;
600
+ currentToolArgs?: string;
601
+ currentPath?: string;
602
+ sessionFile?: string;
603
+ transcriptPath?: string;
604
+ artifactPaths?: ArtifactPaths;
605
+ warning: string;
606
+ message: string;
607
+ }
608
+
609
+ /** Safe parent-facing subset of a timeout recovery summary. */
610
+ export type TimeoutRecoveryProjection = Pick<TimeoutRecoverySummary, "termination" | "changedFiles" | "truncated" | "recoveryNeeded" | "reason" | "reportStatus">;
611
+
356
612
  export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
357
613
  export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
358
614
 
@@ -525,23 +781,34 @@ export interface RunFanoutRejection extends RunFanoutBudgetSnapshot {
525
781
  export interface SteeringRecoveryDescriptor {
526
782
  version: 1;
527
783
  launchContractDigest?: string;
784
+ extensionBindings?: ExtensionBindings;
528
785
  runFanoutBudget: RunFanoutBudgetDescriptor;
529
786
  sourceRunId: string;
530
787
  agentContract?: AgentContract;
531
788
  agent: string;
532
789
  sessionFile?: string;
790
+ /** Git ref used to allocate managed worktrees for this run. */
791
+ baseRef?: string;
533
792
  cwd: string;
534
793
  model?: string;
794
+ modelProvider?: string;
535
795
  modelOverrideFromParent?: boolean;
796
+ modelOrigin?: "explicit" | "inherited" | "configured";
536
797
  fallbackModels?: string[];
798
+ fast?: boolean;
537
799
  thinking?: string;
800
+ thinkingCeiling?: ThinkingLevel;
538
801
  tools?: string[];
802
+ excludeTools?: string[];
803
+ allowNestedSubagents?: boolean;
539
804
  extensions?: string[];
540
805
  subagentOnlyExtensions?: string[];
541
806
  mcpDirectTools?: string[];
807
+ mutationTools?: string[];
542
808
  systemPrompt?: string;
543
809
  systemPromptMode: "append" | "replace";
544
810
  inheritProjectContext: boolean;
811
+ inheritGlobalContext: boolean;
545
812
  inheritSkills: boolean;
546
813
  skills?: string[];
547
814
  skillPath?: string[];
@@ -557,8 +824,8 @@ export interface SteeringRecoveryDescriptor {
557
824
  context?: "fresh" | "fork";
558
825
  /** Raw per-run bridge override. Omitted descriptors continue to use global config. */
559
826
  intercomBridge?: IntercomBridgeConfig;
827
+ lane?: WorkflowLaneMetadata;
560
828
  absoluteDeadlineAt?: number;
561
- initialTurnBudget?: ResolvedTurnBudget;
562
829
  initialToolBudget?: ResolvedToolBudget;
563
830
  maxSubagentDepth: number;
564
831
  maxOutput?: MaxOutputConfig;
@@ -572,7 +839,7 @@ export interface SteeringRecoveryDescriptor {
572
839
 
573
840
  export type PublicNestedStepSummary = Pick<
574
841
  NestedStepSummary,
575
- "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"
576
843
  > & {
577
844
  children?: PublicNestedRunSummary[];
578
845
  };
@@ -585,7 +852,7 @@ export type CostSummary = {
585
852
 
586
853
  export type PublicNestedRunSummary = Pick<
587
854
  NestedRunSummary,
588
- "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"
589
856
  > & {
590
857
  steps?: PublicNestedStepSummary[];
591
858
  children?: PublicNestedRunSummary[];
@@ -593,6 +860,8 @@ export type PublicNestedRunSummary = Pick<
593
860
 
594
861
  export interface SubagentResultIntercomChild {
595
862
  agent: string;
863
+ /** Human-readable display name for the child session, when derived at launch. */
864
+ sessionName?: string;
596
865
  /** Process/lifecycle status. It does not establish semantic task completion. */
597
866
  status: SubagentResultStatus;
598
867
  /** Whether the child produced substantive output before its process ended. */
@@ -629,18 +898,26 @@ export interface SubagentResultIntercomPayload {
629
898
  // Progress Tracking
630
899
  // ============================================================================
631
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
+
632
907
  export interface ChildWatchdogProgress {
633
- phase: "idle" | "reviewing" | "autofollow" | "settling" | "stale" | "failed";
908
+ phase: "idle" | "reviewing" | "stale" | "failed";
634
909
  seq: number;
635
910
  lastUpdate: number;
636
- followUpPending: boolean;
637
911
  reason?: string;
638
912
  timedOut?: boolean;
913
+ warnings?: ChildWatchdogWarningSummary[];
639
914
  }
640
915
 
641
916
  export interface AgentProgress {
642
917
  index: number;
643
918
  agent: string;
919
+ /** Human-readable display name for the child's session, when derived at launch. */
920
+ sessionName?: string;
644
921
  status: "pending" | "running" | "completed" | "failed" | "detached";
645
922
  activityState?: ActivityState;
646
923
  task: string;
@@ -660,6 +937,8 @@ export interface AgentProgress {
660
937
  thinking?: string;
661
938
  inputTokens?: number;
662
939
  outputTokens?: number;
940
+ window?: number;
941
+ windowPeak?: number;
663
942
  durationMs: number;
664
943
  error?: string;
665
944
  failedTool?: string;
@@ -674,6 +953,8 @@ export interface ToolCallSummary {
674
953
  interface ProgressSummary {
675
954
  index?: number;
676
955
  agent?: string;
956
+ /** Human-readable display name for the child's session, when derived at launch. */
957
+ sessionName?: string;
677
958
  status?: AgentProgress["status"];
678
959
  activityState?: ActivityState;
679
960
  skills?: string[];
@@ -739,6 +1020,7 @@ export interface AcceptanceReviewGate {
739
1020
 
740
1021
  export interface AcceptanceConfig {
741
1022
  level?: AcceptanceLevel;
1023
+ report?: "on" | "off";
742
1024
  criteria?: Array<string | AcceptanceGate>;
743
1025
  evidence?: AcceptanceEvidenceKind[];
744
1026
  verify?: AcceptanceVerifyCommand[];
@@ -848,6 +1130,18 @@ export type AcceptanceLedgerStatus =
848
1130
  | "reviewed"
849
1131
  | "accepted";
850
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
+
851
1145
  export interface AcceptanceLedger {
852
1146
  status: AcceptanceLedgerStatus;
853
1147
  evidenceStatus: AcceptanceEvidenceStatus;
@@ -857,6 +1151,7 @@ export interface AcceptanceLedger {
857
1151
  criteria: ResolvedAcceptanceGate[];
858
1152
  childReport?: AcceptanceReport;
859
1153
  childReportParseError?: string;
1154
+ recovery?: AcceptanceRecoveryMetadata;
860
1155
  runtimeChecks: AcceptanceRuntimeCheck[];
861
1156
  verifyRuns: AcceptanceVerifyResult[];
862
1157
  reviewResult?: AcceptanceReviewResult;
@@ -867,15 +1162,6 @@ export interface AcceptanceLedger {
867
1162
  };
868
1163
  }
869
1164
 
870
- export interface ProtocolOutputLimit {
871
- code: "protocol_output_limit";
872
- stream: "stdout" | "stderr";
873
- limitBytes: number;
874
- observedBytes: number;
875
- diagnosticPrefix: string;
876
- diagnosticTail: string;
877
- }
878
-
879
1165
  export interface LaunchResolvedChildExtensionsV1 {
880
1166
  version: 1;
881
1167
  /** This is parent-resolved launch intent, not child-runtime acknowledgement that extensions loaded. */
@@ -932,12 +1218,18 @@ export interface SingleResult {
932
1218
  * result row's array position.
933
1219
  */
934
1220
  index: number;
1221
+ /** Workflow child key that owns this result when returned from workflow details. */
1222
+ workflowKey?: string;
935
1223
  agent: string;
936
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;
937
1228
  /** Resolved launch context for this child. */
938
1229
  context?: "fresh" | "fork";
939
1230
  exitCode: number;
940
1231
  processSignal?: string | null;
1232
+ timeoutRecovery?: TimeoutRecoverySummary;
941
1233
  detached?: boolean;
942
1234
  detachedReason?: string;
943
1235
  interrupted?: boolean;
@@ -957,7 +1249,13 @@ export interface SingleResult {
957
1249
  modelAttempts?: ModelAttempt[];
958
1250
  controlEvents?: ControlEvent[];
959
1251
  error?: string;
960
- protocolError?: ProtocolOutputLimit;
1252
+ /**
1253
+ * True when the dispatch failed because the input exceeded the model's
1254
+ * context window. The model fallback loop stops immediately (retrying the
1255
+ * same input on another model cannot succeed). Callers should treat this as
1256
+ * a signal to reduce input size or re-decompose the task.
1257
+ */
1258
+ contextOverflow?: boolean;
961
1259
  sessionFile?: string;
962
1260
  skills?: string[];
963
1261
  skillsWarning?: string;
@@ -993,6 +1291,8 @@ export interface SingleResult {
993
1291
  watchdog?: ChildWatchdogProgress;
994
1292
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
995
1293
  capabilityAudit?: SubagentCapabilityAudit;
1294
+ runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1295
+ externalProcess?: ExternalProcessStatus;
996
1296
  }
997
1297
 
998
1298
  export interface SpawnBudgetGrant {
@@ -1018,15 +1318,23 @@ export interface WaitCompletionChild {
1018
1318
  agent?: string;
1019
1319
  /** Child run identity where the producer records one (workflow children); artifact files are keyed by it. */
1020
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;
1021
1325
  success?: boolean;
1022
1326
  outputState?: SubagentOutputState;
1327
+ structuredOutput?: unknown;
1328
+ structuredOutputPath?: string;
1023
1329
  error?: string;
1024
1330
  model?: string;
1331
+ contextOverflow?: boolean;
1025
1332
  artifactPaths?: Partial<ArtifactPaths>;
1333
+ timeoutRecovery?: TimeoutRecoveryProjection;
1026
1334
  }
1027
1335
 
1028
1336
  /**
1029
- * 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
1030
1338
  * identity and the artifact trail; output text stays in the tool result content.
1031
1339
  */
1032
1340
  export interface WaitCompletion {
@@ -1038,6 +1346,28 @@ export interface WaitCompletion {
1038
1346
  /** Versioned bounded output archive retained with the durable completion replay. */
1039
1347
  archivePath?: string;
1040
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[] };
1041
1371
  }
1042
1372
 
1043
1373
  export interface Details {
@@ -1048,13 +1378,20 @@ export interface Details {
1048
1378
  /** Run-level context summary. "mixed" when children resolved to different modes. */
1049
1379
  context?: "fresh" | "fork" | "mixed";
1050
1380
  results: SingleResult[];
1381
+ workflowChildren?: WorkflowChildSummaryV1;
1051
1382
  /**
1052
- * Terminal completion payloads for runs this subagent_wait call observed
1383
+ * Terminal completion payloads for runs this bg_wait call observed
1053
1384
  * finishing. Async completions travel as result files that are consumed and
1054
1385
  * deleted after text delivery, so without this field their run and artifact
1055
1386
  * identity never reaches tool_result details.
1056
1387
  */
1057
1388
  completions?: WaitCompletion[];
1389
+ wait?: {
1390
+ reason: "window_elapsed";
1391
+ timedOut: true;
1392
+ activeRunIds: string[];
1393
+ activeProviderItems: Array<{ provider: string; id: string }>;
1394
+ };
1058
1395
  controlEvents?: ControlEvent[];
1059
1396
  steering?: SteerActionResult;
1060
1397
  asyncId?: string;
@@ -1064,7 +1401,6 @@ export interface Details {
1064
1401
  deadlineAt?: number;
1065
1402
  timedOut?: boolean;
1066
1403
  stopped?: boolean;
1067
- turnBudget?: ResolvedTurnBudget;
1068
1404
  toolBudget?: ResolvedToolBudget;
1069
1405
  usageBudget?: UsageBudgetState;
1070
1406
  progress?: AgentProgress[];
@@ -1084,6 +1420,9 @@ export interface Details {
1084
1420
  totalSteps?: number; // Total steps in chain
1085
1421
  currentStepIndex?: number; // 0-indexed current step (for running chains)
1086
1422
  workflowGraph?: WorkflowGraphSnapshot;
1423
+ /** Validated, display-only fanout plan supplied with a workflow launch. */
1424
+ preflight?: WorkflowPreflightV1;
1425
+ preflightWarnings?: string[];
1087
1426
  outputs?: ChainOutputMap;
1088
1427
  // Aggregated child usage across all agents in the run
1089
1428
  totalChildUsage?: Usage;
@@ -1093,6 +1432,7 @@ export interface Details {
1093
1432
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1094
1433
  runFanoutRejection?: RunFanoutRejection;
1095
1434
  activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
1435
+ agentCapabilities?: AgentCapabilitiesSnapshot;
1096
1436
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1097
1437
  capabilityAudit?: SubagentCapabilityAudit;
1098
1438
  parallelHandoff?: ParallelHandoffReference;
@@ -1112,8 +1452,10 @@ export interface Details {
1112
1452
  mission?: MissionRecord;
1113
1453
  workflow?: {
1114
1454
  value?: unknown;
1455
+ resource?: WorkflowResourceProvenanceV1;
1456
+ preflightWarnings?: string[];
1115
1457
  trace: Array<{
1116
- operation: "run" | "status" | "steer";
1458
+ operation: "run" | "status" | "steer" | "host";
1117
1459
  key: string;
1118
1460
  state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
1119
1461
  agent?: string;
@@ -1121,6 +1463,9 @@ export interface Details {
1121
1463
  phase?: string;
1122
1464
  label?: string;
1123
1465
  durationMs?: number;
1466
+ /** Internal provenance for a generated runs.lanes child key. */
1467
+ generatedLaneKey?: string;
1468
+ warning?: string;
1124
1469
  error?: string;
1125
1470
  }>;
1126
1471
  emits: unknown[];
@@ -1180,7 +1525,7 @@ export interface AsyncParallelGroupStatus {
1180
1525
  stepIndex: number;
1181
1526
  }
1182
1527
 
1183
- export type NestedRunState = "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1528
+ export type NestedRunState = "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1184
1529
  export type NestedOwnerState = "live" | "gone" | "unknown";
1185
1530
 
1186
1531
  export interface NestedRunAddress {
@@ -1194,7 +1539,9 @@ export interface NestedRunAddress {
1194
1539
 
1195
1540
  export interface NestedStepSummary {
1196
1541
  agent: string;
1197
- 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";
1198
1545
  model?: string;
1199
1546
  thinking?: string;
1200
1547
  sessionFile?: string;
@@ -1245,6 +1592,8 @@ export interface NestedRunSummary extends NestedRunAddress {
1245
1592
  capabilityAudit?: SubagentCapabilityAudit;
1246
1593
  state: NestedRunState;
1247
1594
  agent?: string;
1595
+ /** Human-readable display name for the child session, when derived at launch. */
1596
+ sessionName?: string;
1248
1597
  agents?: string[];
1249
1598
  model?: string;
1250
1599
  thinking?: string;
@@ -1306,6 +1655,7 @@ export interface AsyncStartedEvent {
1306
1655
  chainStepCount?: number;
1307
1656
  parallelGroups?: AsyncParallelGroupStatus[];
1308
1657
  workflowGraph?: WorkflowGraphSnapshot;
1658
+ preflight?: WorkflowPreflightV1;
1309
1659
  launchContractDigest?: string;
1310
1660
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1311
1661
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1323,9 +1673,11 @@ export type AgentRunnerConfig =
1323
1673
  | { type: "pi" }
1324
1674
  | {
1325
1675
  type: "external-cli";
1676
+ adapter?: "codex-exec" | "codex-exec-writer" | "claude-code" | "claude-code-writer" | "cursor-agent" | "cursor-agent-writer";
1326
1677
  command: string;
1327
1678
  args?: string[];
1328
1679
  promptDelivery?: "stdin";
1680
+ capabilities?: ExternalCliCapabilityNarrowing;
1329
1681
  }
1330
1682
  | {
1331
1683
  type: "external-job";
@@ -1333,18 +1685,46 @@ export type AgentRunnerConfig =
1333
1685
  options?: Record<string, unknown>;
1334
1686
  };
1335
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
+
1336
1718
  export interface ExternalCliRunnerStatus {
1337
1719
  type: "external-cli";
1338
1720
  command: string;
1339
1721
  args: string[];
1340
- promptDelivery: "stdin";
1341
- capabilities: {
1342
- stop: true;
1343
- steer: false;
1344
- resume: false;
1345
- structuredOutput: false;
1346
- toolEvents: false;
1347
- };
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;
1348
1728
  }
1349
1729
 
1350
1730
  export interface ExternalJobRunnerStatus {
@@ -1364,6 +1744,12 @@ export interface ExternalJobStatus {
1364
1744
  provider: string;
1365
1745
  providerJobId?: string;
1366
1746
  promptDigest: string;
1747
+ operation?: "start" | "follow-up";
1748
+ sourceRunId?: string;
1749
+ sourceStepIndex?: number;
1750
+ parentProviderJobId?: string;
1751
+ requestId?: string;
1752
+ requestDigest?: string;
1367
1753
  options: Record<string, unknown>;
1368
1754
  handleUrl?: string;
1369
1755
  conversationUrl?: string;
@@ -1385,6 +1771,11 @@ export interface ExternalProcessStatus {
1385
1771
  processSignal?: string | null;
1386
1772
  stdoutPath: string;
1387
1773
  stderrPath: string;
1774
+ finalOutputPath?: string;
1775
+ stdoutBytes?: number;
1776
+ stderrBytes?: number;
1777
+ stdoutTruncated?: boolean;
1778
+ stderrTruncated?: boolean;
1388
1779
  }
1389
1780
 
1390
1781
  export interface AsyncStatus {
@@ -1398,7 +1789,7 @@ export interface AsyncStatus {
1398
1789
  mode: SubagentRunMode;
1399
1790
  context?: "fresh" | "fork" | "mixed";
1400
1791
  isNested?: boolean;
1401
- state: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1792
+ state: "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1402
1793
  /** Display-only dismissal marker for a reload-orphaned workflow. */
1403
1794
  displayDismissedAt?: number;
1404
1795
  error?: string;
@@ -1432,6 +1823,7 @@ export interface AsyncStatus {
1432
1823
  pendingAppends?: number;
1433
1824
  parallelGroups?: AsyncParallelGroupStatus[];
1434
1825
  workflowGraph?: WorkflowGraphSnapshot;
1826
+ preflight?: WorkflowPreflightV1;
1435
1827
  processTerminal?: ProcessTerminalV1;
1436
1828
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1437
1829
  runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
@@ -1441,12 +1833,18 @@ export interface AsyncStatus {
1441
1833
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1442
1834
  capabilityAudit?: SubagentCapabilityAudit;
1443
1835
  workflow?: Details["workflow"];
1836
+ workflowChildren?: WorkflowChildSummaryV1;
1444
1837
  parentWorkflowRunId?: string;
1445
1838
  workflowKey?: string;
1839
+ lane?: WorkflowLaneMetadata;
1446
1840
  /** Set when a durable schedule launched this run, so completions can name their origin. */
1447
1841
  scheduleOrigin?: ScheduleOrigin;
1448
1842
  steps?: Array<{
1843
+ /** Stable caller-facing child identity for inspect/status/stop. */
1844
+ childId?: string;
1449
1845
  agent: string;
1846
+ /** Human-readable display name for the child session, when derived at launch. */
1847
+ sessionName?: string;
1450
1848
  runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1451
1849
  externalProcess?: ExternalProcessStatus;
1452
1850
  externalJob?: ExternalJobStatus;
@@ -1457,6 +1855,15 @@ export interface AsyncStatus {
1457
1855
  phase?: string;
1458
1856
  label?: string;
1459
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;
1460
1867
  /** Child run identity for workflow capacity reconciliation. */
1461
1868
  runId?: string;
1462
1869
  /** True only when this workflow child owns a detached async runner. */
@@ -1464,7 +1871,9 @@ export interface AsyncStatus {
1464
1871
  parentWorkflowRunId?: string;
1465
1872
  outputName?: string;
1466
1873
  structured?: boolean;
1467
- status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1874
+ status: "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1875
+ stopRequested?: boolean;
1876
+ stopRequestedAt?: number;
1468
1877
  children?: NestedRunSummary[];
1469
1878
  sessionFile?: string;
1470
1879
  transcriptPath?: string;
@@ -1484,6 +1893,7 @@ export interface AsyncStatus {
1484
1893
  durationMs?: number;
1485
1894
  exitCode?: number | null;
1486
1895
  timedOut?: boolean;
1896
+ timeoutRecovery?: TimeoutRecoverySummary;
1487
1897
  stopped?: boolean;
1488
1898
  turnBudget?: TurnBudgetState;
1489
1899
  turnBudgetExceeded?: boolean;
@@ -1494,8 +1904,12 @@ export interface AsyncStatus {
1494
1904
  skills?: string[];
1495
1905
  model?: string;
1496
1906
  thinking?: string;
1907
+ contextLimit?: number;
1908
+ thinkingCeiling?: ThinkingLevel;
1497
1909
  attemptedModels?: string[];
1498
1910
  modelAttempts?: ModelAttempt[];
1911
+ /** True when the child input exceeded the model context window. */
1912
+ contextOverflow?: boolean;
1499
1913
  totalCost?: CostSummary;
1500
1914
  steering?: SteeringStatus;
1501
1915
  error?: string;
@@ -1524,9 +1938,10 @@ export interface AsyncStatus {
1524
1938
  parallelHandoff?: ParallelHandoffReference;
1525
1939
  }
1526
1940
 
1527
- export type AsyncJobStep = NonNullable<AsyncStatus["steps"]>[number] & {
1941
+ export type AsyncJobStep = Omit<NonNullable<AsyncStatus["steps"]>[number], "timeoutRecovery"> & {
1528
1942
  index?: number;
1529
1943
  description?: string;
1944
+ timeoutRecovery?: TimeoutRecoveryProjection;
1530
1945
  };
1531
1946
 
1532
1947
  export interface AsyncJobState {
@@ -1538,7 +1953,7 @@ export interface AsyncJobState {
1538
1953
  cwd?: string;
1539
1954
  /** Parent-resolved child session root retained for trusted live transcript lookup. */
1540
1955
  sessionRoot?: string;
1541
- status: "queued" | "running" | "complete" | "failed" | "paused" | "stopped" | "rejected";
1956
+ status: "queued" | "running" | "complete" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1542
1957
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1543
1958
  description?: string;
1544
1959
  pid?: number;
@@ -1559,7 +1974,12 @@ export interface AsyncJobState {
1559
1974
  currentStep?: number;
1560
1975
  chainStepCount?: number;
1561
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;
1562
1981
  steps?: AsyncJobStep[];
1982
+ preflight?: WorkflowPreflightV1;
1563
1983
  stepsTotal?: number;
1564
1984
  runningSteps?: number;
1565
1985
  completedSteps?: number;
@@ -1588,10 +2008,14 @@ export interface AsyncJobState {
1588
2008
  parentWorkflowRunId?: string;
1589
2009
  workflowKey?: string;
1590
2010
  workflow?: Details["workflow"];
2011
+ workflowChildren?: WorkflowChildSummaryV1;
2012
+ lane?: WorkflowLaneMetadata;
1591
2013
  }
1592
2014
 
1593
2015
  export interface ForegroundResumeChild {
1594
2016
  agent: string;
2017
+ /** Human-readable display name for the child session, when derived at launch. */
2018
+ sessionName?: string;
1595
2019
  index: number;
1596
2020
  context?: "fresh" | "fork";
1597
2021
  sessionFile?: string;
@@ -1605,6 +2029,8 @@ export interface ForegroundResumeChild {
1605
2029
  currentPath?: string;
1606
2030
  turnCount?: number;
1607
2031
  tokens?: number;
2032
+ window?: number;
2033
+ windowPeak?: number;
1608
2034
  toolCount?: number;
1609
2035
  exitCode?: number;
1610
2036
  error?: string;
@@ -1619,7 +2045,17 @@ export interface ForegroundResumeChild {
1619
2045
  detachedReason?: string;
1620
2046
  acceptance?: AcceptanceLedger;
1621
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
+ };
1622
2056
  launchContractDigest?: string;
2057
+ /** Private retained launch authority. Never project into status or result output. */
2058
+ extensionBindings?: ExtensionBindings;
1623
2059
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1624
2060
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
1625
2061
  execution?: ExecutionProjection;
@@ -1643,6 +2079,8 @@ export interface ForegroundResumeRun {
1643
2079
  export interface ForegroundChildControl {
1644
2080
  index: number;
1645
2081
  agent: string;
2082
+ /** Human-readable display name for the child's session, when derived at launch. */
2083
+ sessionName?: string;
1646
2084
  description?: string;
1647
2085
  startedAt: number;
1648
2086
  updatedAt: number;
@@ -1655,11 +2093,25 @@ export interface ForegroundChildControl {
1655
2093
  tokens?: number;
1656
2094
  inputTokens?: number;
1657
2095
  outputTokens?: number;
2096
+ window?: number;
2097
+ windowPeak?: number;
1658
2098
  model?: string;
1659
2099
  thinking?: string;
1660
2100
  toolCount?: number;
1661
2101
  interrupt?: () => boolean;
1662
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;
1663
2115
  }
1664
2116
 
1665
2117
  export interface ForegroundRunControl {
@@ -1668,8 +2120,6 @@ export interface ForegroundRunControl {
1668
2120
  parentWorkflowRunId?: string;
1669
2121
  /** Stable workflow lane key for this live foreground child. */
1670
2122
  workflowKey?: string;
1671
- /** Private control root used to steer a live workflow-owned child. */
1672
- workflowSteeringDir?: string;
1673
2123
  /** Originating parent session; required for public fleet projection. */
1674
2124
  sessionId?: string;
1675
2125
  mode: SubagentRunMode;
@@ -1678,6 +2128,8 @@ export interface ForegroundRunControl {
1678
2128
  /** Effective working directory used to resolve live transcript artifacts. */
1679
2129
  cwd?: string;
1680
2130
  currentAgent?: string;
2131
+ /** Human-readable display name for the current child session, when derived at launch. */
2132
+ sessionName?: string;
1681
2133
  currentIndex?: number;
1682
2134
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
1683
2135
  description?: string;
@@ -1690,6 +2142,8 @@ export interface ForegroundRunControl {
1690
2142
  tokens?: number;
1691
2143
  inputTokens?: number;
1692
2144
  outputTokens?: number;
2145
+ window?: number;
2146
+ windowPeak?: number;
1693
2147
  model?: string;
1694
2148
  thinking?: string;
1695
2149
  toolCount?: number;
@@ -1707,6 +2161,7 @@ export interface ForegroundRunControl {
1707
2161
  nestedChildren?: NestedRunSummary[];
1708
2162
  interrupt?: () => boolean;
1709
2163
  detach?: () => boolean;
2164
+ steer?: ForegroundChildControl["steer"];
1710
2165
  }
1711
2166
 
1712
2167
  export interface WaitSubscriptionRecord {
@@ -1729,6 +2184,8 @@ export interface ActiveAsyncCapacitySnapshot {
1729
2184
  export interface SubagentState {
1730
2185
  baseCwd: string;
1731
2186
  currentSessionId: string | null;
2187
+ /** Session for which active status projections were restored successfully. */
2188
+ statusProjectionSessionId?: string | null;
1732
2189
  /** Reload-stable identity for this parent Pi process/window. */
1733
2190
  completionOwnerId?: string;
1734
2191
  /** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
@@ -1740,6 +2197,8 @@ export interface SubagentState {
1740
2197
  parentSessionFile?: string | null;
1741
2198
  /** Extension-owned roots trusted for child session transcript reads. */
1742
2199
  trustedSessionRoots?: string[];
2200
+ /** Pi sessions base that caps exact runtime-recorded session file trust. */
2201
+ trustedSessionFileRoot?: string;
1743
2202
  /** Live async session roots created by this parent executor, keyed by run id. */
1744
2203
  liveAsyncSessionRoots?: Map<string, string>;
1745
2204
  /** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
@@ -1754,6 +2213,8 @@ export interface SubagentState {
1754
2213
  };
1755
2214
  /** Current-session top-level async capacity projection. */
1756
2215
  activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
2216
+ /** Herdr project panes opened by this Pi session, keyed by project root. */
2217
+ herdrProjectPanes?: Map<string, HerdrProjectPaneSnapshot>;
1757
2218
  asyncJobs: Map<string, AsyncJobState>;
1758
2219
  /** Current-session active and recent async runs for the native fleet inspector. */
1759
2220
  fleetJobs?: Map<string, AsyncJobState>;
@@ -1780,12 +2241,32 @@ export interface SubagentState {
1780
2241
  waitSubscriptions?: Map<string, WaitSubscriptionRecord>;
1781
2242
  /** Live in-process workflow controllers. Durable status remains on disk after settlement. */
1782
2243
  workflowControllers?: Map<string, AbortController>;
2244
+ /** Live in-process workflow child stoppers keyed by parent workflow run id. */
2245
+ workflowChildStops?: Map<string, (childId: string, message?: string) => boolean>;
1783
2246
  /** Session-snapshot `<available_subagents>` block appended to the parent system prompt; empty when nothing is advertised. */
1784
2247
  contextInjectionBlock?: string;
1785
2248
  /** `subagents.injectAgents` entries that matched no discovered agent at snapshot time. */
1786
2249
  contextInjectionUnknownNames?: string[];
1787
2250
  }
1788
2251
 
2252
+ export interface HerdrProjectPaneSnapshot {
2253
+ projectRoot: string;
2254
+ bindingPath: string;
2255
+ paneId: string;
2256
+ openedAt: string;
2257
+ lastFocusedAt?: string;
2258
+ state: "open" | "stale";
2259
+ agentStatus: string;
2260
+ ownership: "verified" | "unknown" | "mismatch";
2261
+ safeToClose: boolean;
2262
+ refreshedAt: number;
2263
+ summary?: string;
2264
+ tabId?: string;
2265
+ workspaceId?: string;
2266
+ terminalTitle?: string;
2267
+ staleReason?: string;
2268
+ }
2269
+
1789
2270
  // ============================================================================
1790
2271
  // Display
1791
2272
  // ============================================================================
@@ -1819,25 +2300,56 @@ export const SUBAGENT_FOREGROUND_COMPLETE_EVENT = "subagent:foreground-complete"
1819
2300
  export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
1820
2301
  export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
1821
2302
  export const SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
2303
+ export const SUBAGENT_CHILD_STATUS_EVENT = "subagent:child-status";
1822
2304
  export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
1823
2305
  export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
1824
2306
 
2307
+ export interface SubagentChildStatusEvent {
2308
+ type: "subagent.child-status";
2309
+ version: 1;
2310
+ runId: string;
2311
+ childId: string;
2312
+ status: "stopping" | "stopped";
2313
+ ts: number;
2314
+ reason?: string;
2315
+ source?: "rpc" | "async";
2316
+ asyncDir?: string;
2317
+ stepIndex?: number;
2318
+ agent?: string;
2319
+ childRunId?: string;
2320
+ workflowKey?: string;
2321
+ phase?: string;
2322
+ label?: string;
2323
+ }
2324
+
1825
2325
  // ============================================================================
1826
2326
  // Execution Options
1827
2327
  // ============================================================================
1828
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
+
1829
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;
1830
2344
  /** Opt-in global permission rules; missing tools remain allowed. */
1831
2345
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
1832
2346
  /** Session id of the direct parent session for permission-system ask forwarding. */
1833
2347
  parentSessionId?: string;
1834
- /** Private prompt-runtime steering transport for workflow-owned foreground children. */
1835
- steerInboxDir?: string;
1836
- steerCapabilityPath?: string;
1837
- steerAckDir?: string;
1838
2348
  /** Resolved launch context for this child. */
1839
2349
  context?: "fresh" | "fork";
1840
2350
  cwd?: string;
2351
+ /** Original cwd input retained for launch diagnostics. */
2352
+ requestedCwd?: string;
1841
2353
  signal?: AbortSignal;
1842
2354
  interruptSignal?: AbortSignal;
1843
2355
  timeoutMs?: number;
@@ -1846,15 +2358,14 @@ export interface RunSyncOptions {
1846
2358
  toolTimeoutMs?: number;
1847
2359
  /** Raw global config.toolTimeoutMs, used by the per-child resolver. */
1848
2360
  configToolTimeoutMs?: number;
1849
- turnBudget?: ResolvedTurnBudget;
1850
2361
  usageBudget?: UsageBudgetConfig;
1851
- /** Enforce maxTurns + graceTurns as a hard model-turn boundary. */
1852
- enforceHardTurnLimit?: boolean;
1853
2362
  toolBudget?: ResolvedToolBudget;
1854
2363
  allowZeroToolBudget?: boolean;
1855
2364
  allowIntercomDetach?: boolean;
1856
2365
  intercomEvents?: IntercomEventBus;
1857
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;
1858
2369
  onControlEvent?: (event: ControlEvent) => void;
1859
2370
  /** Exposes a non-terminating detach callback while the child is active. */
1860
2371
  onDetachReady?: (detach: (reason?: string) => boolean) => void;
@@ -1874,33 +2385,48 @@ export interface RunSyncOptions {
1874
2385
  sessionFile?: string;
1875
2386
  share?: boolean;
1876
2387
  outputPath?: string;
2388
+ outputClaimPath?: string;
1877
2389
  outputMode?: OutputMode;
1878
2390
  maxSubagentDepth?: number;
1879
2391
  /** Effective parent wait-tool setting propagated to the child runtime. */
1880
2392
  waitToolEnabled?: boolean;
2393
+ /** Effective parent default wait window propagated to the child runtime. */
2394
+ waitToolDefaultTimeoutMs?: number;
1881
2395
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1882
2396
  runFanoutBudget?: RunFanoutBudgetDescriptor;
1883
2397
  nestedRoute?: NestedRouteInfo;
1884
2398
  /** Override the agent's default model (format: "provider/id" or just "id") */
1885
2399
  modelOverride?: string;
2400
+ /** Opt into priority service tier for supported native OpenAI-Codex launches. */
2401
+ fast?: boolean;
1886
2402
  /** The override came from the running parent session, not configuration. */
1887
2403
  modelOverrideFromParent?: boolean;
2404
+ /** How the launch model was selected: explicit per-call, configured agent primary, or inherited parent. */
2405
+ modelOrigin?: "explicit" | "inherited" | "configured";
1888
2406
  /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
1889
2407
  llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
1890
2408
  /** Override the agent's default thinking level for this run */
1891
2409
  thinkingOverride?: AgentConfig["thinking"];
2410
+ thinkingCeiling?: ThinkingLevel;
2411
+ extensionBindings?: ExtensionBindings;
2412
+ /** Package-internal one-use authorization for one foreground workflow child. */
2413
+ workflowChildPermitLaunch?: WorkflowChildPermitContext;
1892
2414
  /** Registry models available for heuristic bare-model resolution */
1893
- availableModels?: Array<{ provider: string; id: string; fullId: string }>;
2415
+ availableModels?: Array<{ provider: string; id: string; fullId: string; contextWindow?: number }>;
1894
2416
  /** Current parent-session provider to prefer for ambiguous bare model ids */
1895
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;
1896
2420
  /** Optional subagent model-scope enforcement for fallback candidates */
1897
- modelScope?: ModelScopeConfig;
2421
+ modelScope?: ModelScopeRule | ModelScopeRule[];
1898
2422
  /** Skills to make available (overrides agent default if provided) */
1899
2423
  skills?: string[];
1900
2424
  structuredOutput?: {
1901
2425
  schema: JsonSchemaObject;
1902
2426
  schemaPath: string;
1903
2427
  outputPath: string;
2428
+ acceptanceReportPath?: string;
2429
+ acceptanceReportRequired?: boolean;
1904
2430
  };
1905
2431
  agentContract?: AgentContract;
1906
2432
  acceptance?: AcceptanceInput;
@@ -1953,6 +2479,11 @@ export interface ScheduledRunsConfig {
1953
2479
  storeRoot?: string;
1954
2480
  }
1955
2481
 
2482
+ export interface ModelExclusionsConfig {
2483
+ /** Default duration in milliseconds. A lower configured value also shortens active cached exclusions. */
2484
+ defaultTtlMs?: number;
2485
+ }
2486
+
1956
2487
  export type FleetViewPlacement = "aboveEditor" | "belowEditor";
1957
2488
 
1958
2489
  export const FLEET_KEYBINDING_ACTIONS = [
@@ -1977,7 +2508,7 @@ export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
1977
2508
  export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
1978
2509
 
1979
2510
  export interface OrcaProgressTabsConfig {
1980
- /** Create one Orca terminal tab per running subagent. Experimental and opt-in. */
2511
+ /** Create one Orca observer tab per top-level subagent call. Experimental and opt-in. */
1981
2512
  enabled?: boolean;
1982
2513
  }
1983
2514
 
@@ -1988,10 +2519,24 @@ export interface MainWindowRendererConfig {
1988
2519
  compactResultMaxLines?: number;
1989
2520
  }
1990
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
+
1991
2534
  export interface ExtensionConfig {
1992
2535
  asyncByDefault?: boolean;
1993
2536
  /** Set the context for launches that omit an explicit context. */
1994
2537
  defaultSubagentContext?: "fresh" | "fork";
2538
+ /** Configure how every resolved fork session is prepared before child spawn. */
2539
+ forkContext?: ForkContextConfig;
1995
2540
  /** Optional shortcut that detaches the active foreground single-subagent run. */
1996
2541
  foregroundDetachShortcut?: string;
1997
2542
  /** Show the Claude Code-style navigable fleet. Defaults to true. */
@@ -2002,6 +2547,8 @@ export interface ExtensionConfig {
2002
2547
  fleetKeybindings?: FleetKeybindingsConfig;
2003
2548
  /** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
2004
2549
  asyncWidget?: boolean;
2550
+ /** Configure the process-wide TTL policy for persisted model exclusions. */
2551
+ modelExclusions?: ModelExclusionsConfig;
2005
2552
  /** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
2006
2553
  toolDescriptionMode?: ToolDescriptionMode;
2007
2554
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
@@ -2021,6 +2568,8 @@ export interface ExtensionConfig {
2021
2568
  maxSubagentSpawnsPerRun?: number;
2022
2569
  /** Optional active top-level async run cap per parent session. Unset or 0 means unlimited. */
2023
2570
  maxActiveAsyncRunsPerSession?: number;
2571
+ /** Active-capacity cleanup policy. */
2572
+ capacity?: ActiveAsyncCapacityConfig;
2024
2573
  /** Global cap on simultaneously-running subagent tasks within a single run. Defaults to 20. */
2025
2574
  globalConcurrencyLimit?: number;
2026
2575
  /**
@@ -2044,7 +2593,6 @@ export interface ExtensionConfig {
2044
2593
  toolTimeoutMs?: number;
2045
2594
  control?: ControlConfig;
2046
2595
  completionBatch?: CompletionBatchConfig;
2047
- turnBudget?: TurnBudgetConfig;
2048
2596
  toolBudget?: ToolBudgetConfig;
2049
2597
  /** Opt-in native tool permissions. Bash remains outside this policy. */
2050
2598
  permissions?: import("../runs/shared/permissions.ts").PermissionConfig;
@@ -2054,12 +2602,18 @@ export interface ExtensionConfig {
2054
2602
  worktreeSetupHook?: string;
2055
2603
  worktreeSetupHookTimeoutMs?: number;
2056
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;
2057
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. */
2058
2612
  artifactDir?: ArtifactDirPreference;
2059
2613
  /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
2060
2614
  artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
2061
2615
  intercomBridge?: IntercomBridgeConfig;
2062
- /** Control how slow result-index scans are logged. Defaults to \"all\".
2616
+ /** Control how slow result-index scans are logged. Defaults to \"activity\".
2063
2617
  * - \"all\": log every slow scan, including scans that find nothing.
2064
2618
  * - \"activity\": log only slow scans that found or scheduled work. Silences
2065
2619
  * the periodic healthy rescan that inspects zero files while no async runs
@@ -2173,9 +2727,10 @@ export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
2173
2727
  export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
2174
2728
  export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
2175
2729
  export const POLL_INTERVAL_MS = 250;
2730
+ export const WIDGET_ANIMATION_INTERVAL_MS = 1000;
2176
2731
  export const MAX_WIDGET_JOBS = 4;
2177
2732
  export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
2178
- 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;
2179
2734
 
2180
2735
  export const DEFAULT_FORK_PREAMBLE =
2181
2736
  "You are a delegated subagent running from a fork of the parent session. " +
@@ -2228,8 +2783,17 @@ export function normalizeMaxSubagentDepth(value: unknown): number | undefined {
2228
2783
  return normalizeNonNegativeInteger(value);
2229
2784
  }
2230
2785
 
2231
- export function resolveCurrentMaxSubagentDepth(configMaxDepth?: number): number {
2232
- 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])
2233
2797
  ?? normalizeMaxSubagentDepth(configMaxDepth)
2234
2798
  ?? DEFAULT_SUBAGENT_MAX_DEPTH;
2235
2799
  }
@@ -2240,19 +2804,24 @@ export function resolveChildMaxSubagentDepth(parentMaxDepth: number, agentMaxDep
2240
2804
  return normalizedAgent === undefined ? normalizedParent : Math.min(normalizedParent, normalizedAgent);
2241
2805
  }
2242
2806
 
2243
- export function checkSubagentDepth(configMaxDepth?: number): { blocked: boolean; depth: number; maxDepth: number } {
2244
- const depth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
2245
- const maxDepth = resolveCurrentMaxSubagentDepth(configMaxDepth);
2246
- 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;
2247
2817
  return { blocked, depth, maxDepth };
2248
2818
  }
2249
2819
 
2250
- export function getSubagentDepthEnv(maxDepth?: number): Record<string, string> {
2251
- const parentDepth = Number(process.env.PI_SUBAGENT_DEPTH ?? "0");
2252
- 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> {
2253
2822
  return {
2254
- PI_SUBAGENT_DEPTH: String(nextDepth),
2255
- PI_SUBAGENT_MAX_DEPTH: String(normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth()),
2823
+ depth: resolveCurrentSubagentDepth(runtime) + 1,
2824
+ maxDepth: normalizeMaxSubagentDepth(maxDepth) ?? resolveCurrentMaxSubagentDepth(undefined, runtime),
2256
2825
  };
2257
2826
  }
2258
2827