@xzzpig/pi-subagents 0.16.0 → 0.19.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 (166) hide show
  1. package/CHANGELOG.md +233 -1
  2. package/README.md +5 -3
  3. package/agents/claude-code-writer.md +1 -0
  4. package/agents/codex-exec-writer.md +1 -0
  5. package/agents/cursor-agent-writer.md +1 -0
  6. package/agents/reviewer.md +3 -2
  7. package/agents/worker.md +3 -2
  8. package/docs/agents.md +34 -21
  9. package/docs/configuration.md +82 -7
  10. package/docs/extension-api.md +75 -8
  11. package/docs/missions.md +13 -13
  12. package/docs/models.md +7 -5
  13. package/docs/observability.md +23 -13
  14. package/docs/standalone-background.md +5 -5
  15. package/docs/tool-reference.md +98 -100
  16. package/docs/watchdog.md +2 -0
  17. package/docs/workflows.md +214 -162
  18. package/inspector-runner.mjs +1 -1
  19. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  20. package/package.json +15 -9
  21. package/prompts/council.md +6 -3
  22. package/prompts/review-loop.md +1 -1
  23. package/runner-peer-loader.mjs +4 -7
  24. package/runner-peer-preload.mjs +5 -7
  25. package/skills/council-mode/SKILL.md +1 -1
  26. package/skills/pi-subagents/SKILL.md +13 -5
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
  28. package/skills/pi-subagents/references/execution-controls.md +72 -69
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
  32. package/src/agents/advertised-agent-prompt.ts +21 -41
  33. package/src/agents/agent-eject.ts +3 -3
  34. package/src/agents/agent-management.ts +63 -54
  35. package/src/agents/agent-memory.ts +90 -3
  36. package/src/agents/agent-serializer.ts +4 -4
  37. package/src/agents/agents.ts +132 -51
  38. package/src/agents/global-npm-root.ts +58 -0
  39. package/src/agents/proactive-skills.ts +4 -1
  40. package/src/agents/runtime-agent-registry.ts +14 -11
  41. package/src/agents/skills.ts +42 -9
  42. package/src/api/delegation.ts +15 -0
  43. package/src/api/inspectors.ts +27 -0
  44. package/src/api/preflight.ts +7 -2
  45. package/src/extension/config.ts +12 -4
  46. package/src/extension/control-notices.ts +3 -0
  47. package/src/extension/doctor.ts +10 -4
  48. package/src/extension/fanout-child.ts +20 -3
  49. package/src/extension/herdr-pi-bridge.ts +2 -0
  50. package/src/extension/index.ts +168 -206
  51. package/src/extension/public-execution.ts +69 -35
  52. package/src/extension/reply-workflow-script.ts +58 -0
  53. package/src/extension/rpc.ts +39 -11
  54. package/src/extension/schemas.ts +47 -138
  55. package/src/extension/subagent-guide.ts +12 -4
  56. package/src/extension/tool-activation.ts +146 -0
  57. package/src/extension/tool-description.ts +62 -27
  58. package/src/extension/upgrade-notice.ts +40 -0
  59. package/src/inspectors/ghostty/plugin.ts +13 -1
  60. package/src/inspectors/plugins.ts +70 -3
  61. package/src/integrations/herdr-status.ts +19 -3
  62. package/src/intercom/intercom-bridge.ts +2 -0
  63. package/src/intercom/native-supervisor-channel.ts +26 -16
  64. package/src/intercom/result-intercom.ts +4 -0
  65. package/src/runs/background/active-async-capacity.ts +3 -25
  66. package/src/runs/background/async-execution.ts +60 -95
  67. package/src/runs/background/async-job-tracker.ts +91 -56
  68. package/src/runs/background/async-resume.ts +16 -8
  69. package/src/runs/background/async-retention.ts +46 -16
  70. package/src/runs/background/async-status.ts +2 -0
  71. package/src/runs/background/await-async-run.ts +76 -0
  72. package/src/runs/background/binary-bootstrap.ts +34 -6
  73. package/src/runs/background/chain-root-attachment.ts +4 -4
  74. package/src/runs/background/control-channel.ts +18 -2
  75. package/src/runs/background/fleet-view.ts +51 -7
  76. package/src/runs/background/notify.ts +98 -7
  77. package/src/runs/background/pid-namespace.ts +18 -0
  78. package/src/runs/background/process-terminal-candidate.ts +98 -0
  79. package/src/runs/background/process-terminal.ts +17 -96
  80. package/src/runs/background/result-watcher.ts +1 -1
  81. package/src/runs/background/retained-children.ts +3 -2
  82. package/src/runs/background/run-child-session.ts +20 -6
  83. package/src/runs/background/run-id-resolver.ts +10 -5
  84. package/src/runs/background/run-status.ts +16 -4
  85. package/src/runs/background/runner-aliases.ts +54 -16
  86. package/src/runs/background/runner-child-launch.ts +4 -2
  87. package/src/runs/background/runner-startup-failure.ts +56 -0
  88. package/src/runs/background/scheduled-runs.ts +5 -5
  89. package/src/runs/background/stale-run-reconciler.ts +19 -3
  90. package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
  91. package/src/runs/background/subagent-runner.ts +111 -288
  92. package/src/runs/background/wait-tool.ts +2 -0
  93. package/src/runs/background/workflow-terminal-proof.ts +68 -0
  94. package/src/runs/foreground/async-stop-action.ts +17 -3
  95. package/src/runs/foreground/execution.ts +111 -139
  96. package/src/runs/foreground/prompt-audit.ts +3 -9
  97. package/src/runs/foreground/subagent-executor.ts +715 -258
  98. package/src/runs/shared/acceptance.ts +167 -68
  99. package/src/runs/shared/async-status-projection.ts +5 -0
  100. package/src/runs/shared/capability-ceiling.ts +4 -1
  101. package/src/runs/shared/child-hooks.ts +1 -16
  102. package/src/runs/shared/child-launch.ts +37 -16
  103. package/src/runs/shared/child-runtime-config.ts +3 -0
  104. package/src/runs/shared/child-session.ts +144 -8
  105. package/src/runs/shared/child-tool-plan.ts +38 -116
  106. package/src/runs/shared/dynamic-fanout.ts +1 -1
  107. package/src/runs/shared/external-cli-runner.ts +3 -1
  108. package/src/runs/shared/external-job-bridge.ts +54 -0
  109. package/src/runs/shared/git-environment.ts +29 -0
  110. package/src/runs/shared/mcp-config-sources.ts +5 -1
  111. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
  112. package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
  113. package/src/runs/shared/model-resolution.ts +35 -10
  114. package/src/runs/shared/model-scope.ts +28 -9
  115. package/src/runs/shared/nested-events.ts +12 -0
  116. package/src/runs/shared/orca-progress-tabs.ts +3 -2
  117. package/src/runs/shared/parallel-utils.ts +4 -1
  118. package/src/runs/shared/pi-spawn.ts +1 -3
  119. package/src/runs/shared/single-output.ts +11 -2
  120. package/src/runs/shared/structured-output.ts +227 -7
  121. package/src/runs/shared/subagent-control.ts +2 -16
  122. package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
  123. package/src/runs/shared/tool-availability.ts +2 -2
  124. package/src/runs/shared/tool-budget.ts +21 -0
  125. package/src/runs/shared/usage-reconciliation.ts +73 -0
  126. package/src/runs/shared/worktree.ts +36 -9
  127. package/src/shared/child-session-name.ts +4 -2
  128. package/src/shared/disabled-features.ts +123 -0
  129. package/src/shared/extension-context.ts +13 -0
  130. package/src/shared/fork-context.ts +11 -4
  131. package/src/shared/launch-contract.ts +1 -1
  132. package/src/shared/model-info.ts +9 -0
  133. package/src/shared/pruned-fork.ts +69 -56
  134. package/src/shared/settings.ts +1 -1
  135. package/src/shared/types.ts +73 -16
  136. package/src/slash/delegation-adapters.ts +25 -1
  137. package/src/slash/prompt-template-bridge.ts +18 -3
  138. package/src/slash/prompt-workflows.ts +12 -1
  139. package/src/slash/slash-commands.ts +17 -246
  140. package/src/slash/subagent-cost.ts +313 -0
  141. package/src/slash/subagents-admin.ts +4 -5
  142. package/src/tui/fleet-status.ts +38 -8
  143. package/src/tui/fleet.ts +21 -6
  144. package/src/tui/render.ts +166 -71
  145. package/src/tui/running-tone.ts +28 -0
  146. package/src/watchdog/diff-tool.ts +47 -12
  147. package/src/watchdog/permission-arbiter.ts +13 -15
  148. package/src/watchdog/register-child.ts +13 -5
  149. package/src/watchdog/register-main.ts +3 -3
  150. package/src/watchdog/review.ts +16 -16
  151. package/src/watchdog/runtime.ts +2 -1
  152. package/src/watchdog/turn-delta.ts +12 -6
  153. package/src/workflows/chat-progress.ts +2 -2
  154. package/src/workflows/scripted-workflow.ts +225 -59
  155. package/src/workflows/structured-workflow-scripts.ts +177 -0
  156. package/src/workflows/workflow-checklist.ts +6 -0
  157. package/src/workflows/workflow-child-summary.ts +4 -2
  158. package/src/workflows/workflow-receipt.ts +8 -2
  159. package/src/workflows/workflow-resources.ts +37 -12
  160. package/src/workflows/workflow-reuse.ts +120 -0
  161. package/src/workflows/workflow-revival.ts +123 -0
  162. package/src/workflows/workflow-settlement.ts +4 -1
  163. package/src/runs/shared/completion-evidence.ts +0 -89
  164. package/src/runs/shared/completion-guard.ts +0 -255
  165. package/src/runs/shared/llm-intent-arbiter.ts +0 -321
  166. package/src/runs/shared/task-intent.ts +0 -244
@@ -3,7 +3,6 @@ import { createHash } from "node:crypto";
3
3
  import * as fs from "node:fs";
4
4
  import * as path from "node:path";
5
5
  import type { TextContent } from "@earendil-works/pi-ai";
6
- import { completeSimple } from "@earendil-works/pi-ai/compat";
7
6
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
8
7
  import { resolveModelCandidate } from "../runs/shared/model-resolution.ts";
9
8
  import { splitKnownThinkingSuffix, toModelInfo } from "./model-info.ts";
@@ -30,6 +29,8 @@ type SessionEntry = Record<string, unknown> & {
30
29
  id?: string;
31
30
  parentId?: string | null;
32
31
  timestamp?: string;
32
+ targetId?: string;
33
+ replacement?: { content?: unknown } | null;
33
34
  message?: Record<string, unknown>;
34
35
  };
35
36
 
@@ -115,27 +116,36 @@ function stringsInValue(value: unknown): string[] {
115
116
  return [];
116
117
  }
117
118
 
119
+ function pushContentStrings(strings: string[], role: unknown, content: unknown): void {
120
+ if (role === "toolResult") strings.push(...textBlocks(content).map(({ block }) => block.text as string));
121
+ if (role === "assistant" && Array.isArray(content)) {
122
+ for (const blockValue of content) {
123
+ if (!blockValue || typeof blockValue !== "object" || Array.isArray(blockValue)) continue;
124
+ const block = blockValue as Record<string, unknown>;
125
+ if (block.type === "text" && typeof block.text === "string") strings.push(block.text);
126
+ else if (block.type === "thinking" && typeof block.thinking === "string") strings.push(block.thinking);
127
+ else if (block.type === "toolCall") strings.push(stableJson(block.arguments ?? {}), ...stringsInValue(block.arguments));
128
+ }
129
+ }
130
+ if (role === "user") {
131
+ if (typeof content === "string") strings.push(content);
132
+ else strings.push(...textBlocks(content).map(({ block }) => block.text as string));
133
+ }
134
+ }
135
+
118
136
  function modelFacingStrings(entries: SessionEntry[]): string[] {
119
137
  const strings: string[] = [];
138
+ const entriesById = new Map(entries.flatMap((entry) => entry.id ? [[entry.id, entry] as const] : []));
120
139
  for (const entry of entries) {
121
140
  const message = entry.type === "message" && entry.message && typeof entry.message === "object" ? entry.message : undefined;
122
- if (message?.role === "toolResult") strings.push(...textBlocks(message.content).map(({ block }) => block.text as string));
123
- if (message?.role === "assistant" && Array.isArray(message.content)) {
124
- for (const blockValue of message.content) {
125
- if (!blockValue || typeof blockValue !== "object" || Array.isArray(blockValue)) continue;
126
- const block = blockValue as Record<string, unknown>;
127
- if (block.type === "text" && typeof block.text === "string") strings.push(block.text);
128
- else if (block.type === "thinking" && typeof block.thinking === "string") strings.push(block.thinking);
129
- else if (block.type === "toolCall") strings.push(stableJson(block.arguments ?? {}), ...stringsInValue(block.arguments));
130
- }
131
- }
132
- if (message?.role === "user") {
133
- if (typeof message.content === "string") strings.push(message.content);
134
- else strings.push(...textBlocks(message.content).map(({ block }) => block.text as string));
141
+ if (message) pushContentStrings(strings, message.role, message.content);
142
+ if (entry.type === "context_edit" && entry.replacement && entry.targetId) {
143
+ const target = entriesById.get(entry.targetId);
144
+ const role = target?.type === "custom_message" ? "user" : target?.message?.role;
145
+ pushContentStrings(strings, role, entry.replacement.content);
135
146
  }
136
147
  if (entry.type === "custom_message") {
137
- if (typeof entry.content === "string") strings.push(entry.content);
138
- else strings.push(...textBlocks(entry.content).map(({ block }) => block.text as string));
148
+ pushContentStrings(strings, "user", entry.content);
139
149
  }
140
150
  if ((entry.type === "compaction" || entry.type === "branch_summary") && typeof entry.summary === "string") strings.push(entry.summary);
141
151
  }
@@ -186,23 +196,25 @@ function collectOverflowItems(entries: SessionEntry[]): OverflowItem[] {
186
196
  apply,
187
197
  });
188
198
  };
189
-
190
- for (const entry of entries) {
191
- const message = entry.type === "message" && entry.message && typeof entry.message === "object" ? entry.message : undefined;
192
- const role = message?.role;
193
- if (role === "toolResult" && message) {
194
- const toolCallId = typeof message.toolCallId === "string" ? message.toolCallId : undefined;
195
- const toolName = typeof message.toolName === "string" ? message.toolName : undefined;
196
- for (const { block } of textBlocks(message.content)) {
199
+ const collectContent = (
200
+ entry: SessionEntry,
201
+ source: Record<string, unknown>,
202
+ owner: Record<string, unknown>,
203
+ userLabel = "User:",
204
+ ): boolean => {
205
+ if (source.role === "toolResult") {
206
+ const toolCallId = typeof source.toolCallId === "string" ? source.toolCallId : undefined;
207
+ const toolName = typeof source.toolName === "string" ? source.toolName : undefined;
208
+ for (const { block } of textBlocks(owner.content)) {
197
209
  const body = block.text as string;
198
- add(entry, "tool-result", `Tool result: ${toolName ?? "unknown"}${toolCallId ? ` ${toolCallId}` : ""}${message.isError === true ? " (error)" : ""}`, body, (summary, ref) => {
210
+ add(entry, "tool-result", `Tool result: ${toolName ?? "unknown"}${toolCallId ? ` ${toolCallId}` : ""}${source.isError === true ? " (error)" : ""}`, body, (summary, ref) => {
199
211
  block.text = `${summary}\nRecovery ref: ${ref}`;
200
- }, { toolCallId, toolName, isError: message.isError === true });
212
+ }, { toolCallId, toolName, isError: source.isError === true });
201
213
  }
202
- continue;
214
+ return true;
203
215
  }
204
- if (role === "assistant" && message && Array.isArray(message.content)) {
205
- for (const blockValue of message.content) {
216
+ if (source.role === "assistant" && Array.isArray(owner.content)) {
217
+ for (const blockValue of owner.content) {
206
218
  if (!blockValue || typeof blockValue !== "object" || Array.isArray(blockValue)) continue;
207
219
  const block = blockValue as Record<string, unknown>;
208
220
  if (block.type === "text" && typeof block.text === "string") {
@@ -218,30 +230,36 @@ function collectOverflowItems(entries: SessionEntry[]): OverflowItem[] {
218
230
  }, { toolCallId: block.id, toolName: block.name });
219
231
  }
220
232
  }
221
- continue;
233
+ return true;
222
234
  }
223
- if (role === "user" && message) {
224
- if (typeof message.content === "string") {
225
- const body = message.content;
226
- add(entry, "user-text", "User:", body, (summary, ref) => { message.content = `${summary}\nRecovery ref: ${ref}`; });
227
- } else {
228
- for (const { block } of textBlocks(message.content)) {
229
- const body = block.text as string;
230
- add(entry, "user-text", "User:", body, (summary, ref) => { block.text = `${summary}\nRecovery ref: ${ref}`; });
231
- }
235
+ if (source.role !== "user") return false;
236
+ if (typeof owner.content === "string") {
237
+ const body = owner.content;
238
+ add(entry, "user-text", userLabel, body, (summary, ref) => { owner.content = `${summary}\nRecovery ref: ${ref}`; });
239
+ } else {
240
+ for (const { block } of textBlocks(owner.content)) {
241
+ const body = block.text as string;
242
+ add(entry, "user-text", userLabel, body, (summary, ref) => { block.text = `${summary}\nRecovery ref: ${ref}`; });
243
+ }
244
+ }
245
+ return true;
246
+ };
247
+ const entriesById = new Map(entries.flatMap((entry) => entry.id ? [[entry.id, entry] as const] : []));
248
+
249
+ for (const entry of entries) {
250
+ const message = entry.type === "message" && entry.message && typeof entry.message === "object" ? entry.message : undefined;
251
+ if (message && collectContent(entry, message, message)) continue;
252
+ if (entry.type === "context_edit" && entry.replacement && entry.targetId) {
253
+ const target = entriesById.get(entry.targetId);
254
+ if (target?.type === "custom_message") {
255
+ collectContent(entry, { role: "user" }, entry.replacement, `Extension message: ${String(target.customType ?? "unknown")}`);
256
+ } else if (target?.message) {
257
+ collectContent(entry, target.message, entry.replacement);
232
258
  }
233
259
  continue;
234
260
  }
235
261
  if (entry.type === "custom_message") {
236
- if (typeof entry.content === "string") {
237
- const body = entry.content;
238
- add(entry, "user-text", `Extension message: ${String(entry.customType ?? "unknown")}`, body, (summary, ref) => { entry.content = `${summary}\nRecovery ref: ${ref}`; });
239
- } else {
240
- for (const { block } of textBlocks(entry.content)) {
241
- const body = block.text as string;
242
- add(entry, "user-text", `Extension message: ${String(entry.customType ?? "unknown")}`, body, (summary, ref) => { block.text = `${summary}\nRecovery ref: ${ref}`; });
243
- }
244
- }
262
+ collectContent(entry, { role: "user" }, entry, `Extension message: ${String(entry.customType ?? "unknown")}`);
245
263
  continue;
246
264
  }
247
265
  if ((entry.type === "compaction" || entry.type === "branch_summary") && typeof entry.summary === "string") {
@@ -403,7 +421,7 @@ function splitProviderModel(value: string): { provider: string; id: string } | u
403
421
  }
404
422
 
405
423
  export async function createPrunedForkSessionWriter(
406
- ctx: ExtensionContext,
424
+ ctx: Pick<ExtensionContext, "modelRegistry" | "model">,
407
425
  config: ForkContextConfig | undefined,
408
426
  signal?: AbortSignal,
409
427
  ): Promise<(sessionFile: string) => Promise<void>> {
@@ -417,22 +435,17 @@ export async function createPrunedForkSessionWriter(
417
435
  if (!named) throw new Error(`Pruned fork model '${config.model}' must resolve to provider/model.`);
418
436
  const model = ctx.modelRegistry.find(named.provider, named.id);
419
437
  if (!model) throw new Error(`Pruned fork model '${config.model}' was not found as '${baseModel}'.`);
420
- const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
421
- if (auth.ok === false) throw new Error(`Pruned fork model auth failed for ${baseModel}: ${auth.error}`);
422
438
 
423
439
  let sharedSummary: Promise<string> | undefined;
424
440
  const summarize: SummaryFunction = async (payload) => {
425
441
  sharedSummary ??= (async () => {
426
- const response = await completeSimple(model, {
442
+ const response = await ctx.modelRegistry.streamSimple(model, {
427
443
  systemPrompt: SYSTEM_PROMPT,
428
444
  messages: [{ role: "user", content: [{ type: "text", text: payload }], timestamp: Date.now() }],
429
445
  }, {
430
- apiKey: auth.apiKey,
431
- headers: auth.headers,
432
- env: auth.env,
433
446
  maxTokens: Math.min(MAX_SUMMARY_TOKENS, typeof model.maxTokens === "number" && model.maxTokens > 0 ? model.maxTokens : MAX_SUMMARY_TOKENS),
434
447
  signal,
435
- });
448
+ }).result();
436
449
  if (response.stopReason === "error" || response.stopReason === "aborted") {
437
450
  throw new Error(`Pruned fork summarization stopped with ${response.stopReason}${response.errorMessage ? `: ${response.errorMessage}` : ""}`);
438
451
  }
@@ -46,7 +46,7 @@ export interface SequentialStep {
46
46
  acceptance?: AcceptanceInput;
47
47
  agentContract?: AgentContract;
48
48
  gateOn?: ChainGateLayer;
49
- /** Internal workflow child isolation; public workflowScript supplies this on runs.run. */
49
+ /** Internal workflow child isolation; public workflow scripts supply this on runs.run. */
50
50
  worktree?: boolean;
51
51
  }
52
52
 
@@ -12,6 +12,7 @@ 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
14
  import type { ThinkingLevel } from "./model-info.ts";
15
+ import type { SubagentFeature } from "./disabled-features.ts";
15
16
  import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
16
17
  import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
17
18
  import type { WorkflowChildPermitContext } from "./workflow-child-permit.ts";
@@ -131,6 +132,8 @@ export interface WorkflowPreflight {
131
132
 
132
133
  export type WorkflowReceiptState = "complete" | "failed" | "paused" | "stopped";
133
134
 
135
+ export type WorkflowScriptFailureKind = "validation" | "script" | "child" | "return-serialization" | "timeout" | "detached-child" | "runtime";
136
+
134
137
  export type WorkflowTerminalResolution = "settled-awaiting-resume" | "failed-child" | "interrupted-child";
135
138
 
136
139
  export interface WorkflowTerminalOutcome {
@@ -381,7 +384,7 @@ export interface ControlEvent {
381
384
  nestedRunId?: string;
382
385
  nestingPath?: NestedRunAddress["path"];
383
386
  message: string;
384
- reason?: "idle" | "completion_guard" | "active_long_running" | "tool_failures" | "supervisor_request" | "time_threshold" | "turn_threshold" | "token_threshold" | "tool_open_threshold";
387
+ reason?: "idle" | "active_long_running" | "tool_failures" | "supervisor_request" | "time_threshold" | "turn_threshold" | "token_threshold" | "tool_open_threshold";
385
388
  turns?: number;
386
389
  tokens?: number;
387
390
  toolCount?: number;
@@ -397,7 +400,7 @@ export interface ControlEvent {
397
400
  taskPreview?: string;
398
401
  }
399
402
 
400
- export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
403
+ export type SubagentResultStatus = "running" | "completed" | "failed" | "paused" | "stopped" | "detached";
401
404
  export type SubagentOutputState = "present" | "absent" | "unknown";
402
405
  export type SubagentRunMode = "single" | "parallel" | "chain" | "workflow";
403
406
  export type SubagentResultMode = SubagentRunMode;
@@ -555,18 +558,14 @@ export interface ReviewProjection {
555
558
  }
556
559
 
557
560
  export interface FileMutationEffect {
558
- status: "not-requested" | "not-applicable" | "observed" | "missing" | "blocked";
559
- expected: boolean;
560
- attempted: boolean;
561
- message?: string;
562
- resolvedBy?: "llm-intent-arbiter";
561
+ status: "observed";
562
+ attempted: true;
563
563
  evidence?: TrackedMutationEvidence;
564
564
  }
565
565
 
566
566
  export interface SettlementDiagnostic {
567
567
  finalTextPresent: boolean;
568
568
  mutation: {
569
- expected: boolean;
570
569
  attempted: boolean;
571
570
  observed: boolean;
572
571
  };
@@ -710,8 +709,29 @@ export type ProcessTerminal =
710
709
  state: "unknown";
711
710
  reason: ProcessTerminalReason;
712
711
  diagnostic?: string;
712
+ /** The runner's own exit, when observed even though the process tree could not be verified. */
713
+ instances?: RunnerProcessInstanceExit[];
713
714
  });
714
715
 
716
+ export type WorkflowTerminalProof =
717
+ | {
718
+ version: 1;
719
+ kind: "workflow";
720
+ runId: string;
721
+ state: "observed";
722
+ dispatchClosed: true;
723
+ observedAt: number;
724
+ children: ProcessTerminal[];
725
+ }
726
+ | {
727
+ version: 1;
728
+ kind: "workflow";
729
+ runId: string;
730
+ state: "pending" | "unknown";
731
+ dispatchClosed: boolean;
732
+ reason: string;
733
+ };
734
+
715
735
  /** Identifies the durable schedule that launched a run, so its completion is attributable. */
716
736
  export interface ScheduleOrigin {
717
737
  id: string;
@@ -829,6 +849,7 @@ export interface SteeringRecoveryDescriptor {
829
849
  tools?: string[];
830
850
  excludeTools?: string[];
831
851
  allowNestedSubagents?: boolean;
852
+ allowedAgents?: string[];
832
853
  extensions?: string[];
833
854
  subagentOnlyExtensions?: string[];
834
855
  mcpDirectTools?: string[];
@@ -841,7 +862,6 @@ export interface SteeringRecoveryDescriptor {
841
862
  skills?: string[];
842
863
  skillPath?: string[];
843
864
  agentFilePath?: string;
844
- completionGuard?: boolean;
845
865
  memory?: { scope: "project" | "user"; path: string };
846
866
  outputPath?: string;
847
867
  outputMode: "inline" | "file-only";
@@ -965,6 +985,9 @@ export interface AgentProgress {
965
985
  thinking?: string;
966
986
  inputTokens?: number;
967
987
  outputTokens?: number;
988
+ /** Cumulative cache-read/cache-write tokens for the current attempt, alongside inputTokens/outputTokens. */
989
+ cacheRead?: number;
990
+ cacheWrite?: number;
968
991
  window?: number;
969
992
  windowPeak?: number;
970
993
  durationMs: number;
@@ -1030,6 +1053,10 @@ export interface AcceptanceVerifyCommand {
1030
1053
  cwd?: string;
1031
1054
  env?: Record<string, string>;
1032
1055
  allowFailure?: boolean;
1056
+ /** When "json", a passing command's stdout is parsed and becomes the run's structured output. */
1057
+ output?: "json";
1058
+ /** Optional JSON Schema the parsed stdout must satisfy; only meaningful with `output: "json"`. */
1059
+ schema?: JsonSchemaObject;
1033
1060
  }
1034
1061
 
1035
1062
  export interface AcceptanceReviewGate {
@@ -1041,6 +1068,8 @@ export interface AcceptanceReviewGate {
1041
1068
  export interface AcceptanceConfig {
1042
1069
  level?: AcceptanceLevel;
1043
1070
  report?: "on" | "off";
1071
+ /** Preserve an intentional launch-time staged index, while rejecting any terminal index change. */
1072
+ preserveStagedIndex?: true;
1044
1073
  criteria?: Array<string | AcceptanceGate>;
1045
1074
  evidence?: AcceptanceEvidenceKind[];
1046
1075
  verify?: AcceptanceVerifyCommand[];
@@ -1065,6 +1094,7 @@ export interface ResolvedAcceptanceConfig {
1065
1094
  inferredReason: string[];
1066
1095
  criteria: ResolvedAcceptanceGate[];
1067
1096
  evidence: AcceptanceEvidenceKind[];
1097
+ preserveStagedIndex?: true;
1068
1098
  verify: AcceptanceVerifyCommand[];
1069
1099
  review?: AcceptanceReviewGate | false;
1070
1100
  stopRules: string[];
@@ -1123,6 +1153,10 @@ export interface AcceptanceVerifyResult {
1123
1153
  diffHash: string;
1124
1154
  };
1125
1155
  artifactError?: string;
1156
+ /** Parsed stdout of a passing `output: "json"` command. */
1157
+ structuredOutput?: unknown;
1158
+ /** Why a passing `output: "json"` command still failed: invalid JSON, truncated stdout, or schema mismatch. */
1159
+ structuredOutputError?: string;
1126
1160
  }
1127
1161
 
1128
1162
  export interface AcceptanceReviewResult {
@@ -1414,6 +1448,7 @@ export interface Details {
1414
1448
  context?: "fresh" | "fork" | "mixed";
1415
1449
  results: SingleResult[];
1416
1450
  workflowChildren?: WorkflowChildSummary;
1451
+ workflowTerminalProof?: WorkflowTerminalProof;
1417
1452
  /**
1418
1453
  * Terminal completion payloads for runs this bg_wait call observed
1419
1454
  * finishing. Async completions travel as result files that are consumed and
@@ -1493,8 +1528,15 @@ export interface Details {
1493
1528
  mission?: MissionRecord;
1494
1529
  workflow?: {
1495
1530
  value?: unknown;
1531
+ failureKind?: WorkflowScriptFailureKind;
1496
1532
  args?: Record<string, unknown>;
1497
1533
  argsDigest?: string;
1534
+ /** SHA-256 of the workflow script source (async workflows). */
1535
+ scriptDigest?: string;
1536
+ /** Structured stop cause; set only when the owning extension runtime was replaced. */
1537
+ stopCause?: "runtime-replaced";
1538
+ /** Runtime-replaced workflow run whose finished children this run reused. */
1539
+ reusedFrom?: string;
1498
1540
  resource?: WorkflowResourceProvenance;
1499
1541
  preflightWarnings?: string[];
1500
1542
  trace: Array<{
@@ -1510,6 +1552,8 @@ export interface Details {
1510
1552
  generatedLaneKey?: string;
1511
1553
  warning?: string;
1512
1554
  error?: string;
1555
+ /** Came from a previous runtime-replaced run of the same script and args; this run launched nothing. */
1556
+ reused?: boolean;
1513
1557
  }>;
1514
1558
  emits: unknown[];
1515
1559
  console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
@@ -1694,9 +1738,9 @@ export interface AsyncStartedEvent {
1694
1738
  mode?: SubagentRunMode;
1695
1739
  agent?: string;
1696
1740
  agents?: string[];
1697
- /** Truncated first child task retained for backwards compatibility. */
1741
+ /** Redacted prompt marker for the first child task; workflow roots may omit this field. */
1698
1742
  task?: string;
1699
- /** Workflow-level caller task, falling back to the first child task. */
1743
+ /** Redacted prompt marker for the workflow-level caller task or first-child fallback. */
1700
1744
  goal?: string;
1701
1745
  chain?: string[];
1702
1746
  chainStepCount?: number;
@@ -1889,6 +1933,8 @@ export interface AsyncStatus {
1889
1933
  toolBudgetBlocked?: boolean;
1890
1934
  usageBudget?: UsageBudgetState;
1891
1935
  pid?: number;
1936
+ /** Linux PID namespace identity used to scope liveness probes. */
1937
+ pidNamespaceScope?: string;
1892
1938
  cwd?: string;
1893
1939
  /** Parent-resolved child session root retained for trusted restored transcript lookup. */
1894
1940
  sessionRoot?: string;
@@ -1907,6 +1953,8 @@ export interface AsyncStatus {
1907
1953
  launchResolvedExtensions?: LaunchResolvedChildExtensions;
1908
1954
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensions;
1909
1955
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1956
+ /** Parent admission authority before the selected workflow child's descendant restrictions. */
1957
+ admissionCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
1910
1958
  capabilityAudit?: SubagentCapabilityAudit;
1911
1959
  workflow?: Details["workflow"];
1912
1960
  workflowChildren?: WorkflowChildSummary;
@@ -1948,6 +1996,8 @@ export interface AsyncStatus {
1948
1996
  outputName?: string;
1949
1997
  structured?: boolean;
1950
1998
  status: "pending" | "running" | "complete" | "completed" | "failed" | "partial" | "paused" | "stopped" | "rejected";
1999
+ /** Workflow child result reused from a previous runtime-replaced run; the child was not re-run. */
2000
+ reused?: boolean;
1951
2001
  stopRequested?: boolean;
1952
2002
  stopRequestedAt?: number;
1953
2003
  children?: NestedRunSummary[];
@@ -2286,6 +2336,8 @@ export interface SubagentState {
2286
2336
  liveAsyncSessionRoots?: Map<string, string>;
2287
2337
  /** Foreground nested routes retained after their direct parent settles, keyed by root run id. */
2288
2338
  retainedForegroundNestedRoutes?: Map<string, NestedRouteInfo>;
2339
+ /** Lookup authority outlives live controls, but never crosses the owning session. */
2340
+ retainedNestedLookupRoutes?: { sessionId: string; routes: Map<string, NestedRouteInfo> };
2289
2341
  /** Last valid parent session model observed for this session; used when continuation contexts omit ctx.model. */
2290
2342
  lastParentModel?: { provider: string; id: string };
2291
2343
  subagentInProgress?: boolean;
@@ -2378,6 +2430,8 @@ export interface IntercomEventBus {
2378
2430
 
2379
2431
  export const INTERCOM_DETACH_REQUEST_EVENT = "pi-intercom:detach-request";
2380
2432
  export const INTERCOM_DETACH_RESPONSE_EVENT = "pi-intercom:detach-response";
2433
+ /** pi-intercom asks each session for a fixed intercom ID at session start; `claim(id)` answers synchronously. */
2434
+ export const INTERCOM_SESSION_IDENTITY_EVENT = "intercom:session-identity";
2381
2435
  export const SUBAGENT_ASYNC_STARTED_EVENT = "subagent:async-started";
2382
2436
  export const SUBAGENT_ASYNC_COMPLETE_EVENT = "subagent:async-complete";
2383
2437
  export const SUBAGENT_PROCESS_TERMINAL_EVENT = "subagent:process-terminal";
@@ -2394,7 +2448,7 @@ export interface SubagentChildStatusEvent {
2394
2448
  version: 1;
2395
2449
  runId: string;
2396
2450
  childId: string;
2397
- status: "stopping" | "stopped";
2451
+ status: "started" | "stopping" | "stopped";
2398
2452
  ts: number;
2399
2453
  reason?: string;
2400
2454
  source?: "rpc" | "async";
@@ -2442,6 +2496,8 @@ export interface RunSyncOptions {
2442
2496
  /** Original cwd input retained for launch diagnostics. */
2443
2497
  requestedCwd?: string;
2444
2498
  signal?: AbortSignal;
2499
+ /** Report a child ended by `signal` as stopped; set for workflow children, whose signal is the workflow's. */
2500
+ abortedAsStopped?: boolean;
2445
2501
  interruptSignal?: AbortSignal;
2446
2502
  timeoutMs?: number;
2447
2503
  deadlineAt?: number;
@@ -2502,8 +2558,6 @@ export interface RunSyncOptions {
2502
2558
  modelOverrideFromParent?: boolean;
2503
2559
  /** How the launch model was selected: explicit per-call, configured agent primary, or inherited parent. */
2504
2560
  modelOrigin?: "explicit" | "inherited" | "configured";
2505
- /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
2506
- llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
2507
2561
  /** Override the agent's default thinking level for this run */
2508
2562
  thinkingOverride?: AgentConfig["thinking"];
2509
2563
  thinkingCeiling?: ThinkingLevel;
@@ -2518,8 +2572,6 @@ export interface RunSyncOptions {
2518
2572
  preferredModelProvider?: string;
2519
2573
  /** Parent Pi event host used to snapshot runtime-registered MCP servers before child launch. */
2520
2574
  runtimeSnapshotHost?: import("../runs/shared/mcp-direct-tool-allowlist.ts").McpRuntimeSnapshotHost;
2521
- /** Builtin tool names the host runtime provides; used to intersect agent-declared tools. */
2522
- hostAvailableBuiltins?: readonly string[];
2523
2575
  /** Optional subagent model-scope enforcement. */
2524
2576
  modelScope?: ModelScopeRule | ModelScopeRule[];
2525
2577
  /** Skills to make available (overrides agent default if provided) */
@@ -2573,6 +2625,7 @@ export interface ProactiveSkillSubagentsConfig {
2573
2625
  }
2574
2626
 
2575
2627
  export type ToolDescriptionMode = "full" | "compact" | "custom";
2628
+ export type ToolActivationMode = "auto" | "dynamic" | "eager";
2576
2629
  export type InlineToolDisplay = "rich" | "summary";
2577
2630
 
2578
2631
  export interface ScheduledRunsConfig {
@@ -2650,6 +2703,10 @@ export interface ExtensionConfig {
2650
2703
  modelResponseAliases?: Record<string, string[]>;
2651
2704
  /** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
2652
2705
  toolDescriptionMode?: ToolDescriptionMode;
2706
+ /** How a new parent session offers the subagent tool. Defaults to auto. */
2707
+ toolActivation?: ToolActivationMode;
2708
+ /** Opt-in feature groups removed from the subagent tool schema and rejected at every execution boundary. */
2709
+ disabledFeatures?: SubagentFeature[];
2653
2710
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
2654
2711
  inlineToolDisplay?: InlineToolDisplay;
2655
2712
  /** Density controls for the main chat subagent call/result renderer. */
@@ -4,9 +4,10 @@ import {
4
4
  type SubagentDelegationStatus,
5
5
  type SubagentDelegationThinking,
6
6
  type SubagentDelegationUpdate,
7
+ type SubagentDelegationUpdateUsage,
7
8
  type SubagentDelegationValue,
8
9
  } from "../api/delegation.ts";
9
- import type { AcceptanceInput, AgentContract, EffectsProjection, ExecutionProjection, IntercomBridgeConfig, JsonSchemaObject, ReviewProjection, ToolBudgetConfig, Usage } from "../shared/types.ts";
10
+ import type { AcceptanceInput, AgentContract, AgentProgress, EffectsProjection, ExecutionProjection, IntercomBridgeConfig, JsonSchemaObject, ReviewProjection, ToolBudgetConfig, Usage } from "../shared/types.ts";
10
11
  import { cloneJsonWithinByteLimit } from "./delegation-json.ts";
11
12
 
12
13
  export interface PromptTemplateDelegationRequest {
@@ -52,6 +53,7 @@ export interface PromptTemplateDelegationUpdate {
52
53
  toolCount?: number;
53
54
  durationMs?: number;
54
55
  tokens?: number;
56
+ usage?: SubagentDelegationUpdateUsage;
55
57
  taskProgress?: PromptTemplateDelegationTaskProgress[];
56
58
  }
57
59
 
@@ -108,6 +110,11 @@ export interface PromptTemplateBridgeResult {
108
110
  toolCount?: number;
109
111
  durationMs?: number;
110
112
  tokens?: number;
113
+ inputTokens?: number;
114
+ outputTokens?: number;
115
+ cacheRead?: number;
116
+ cacheWrite?: number;
117
+ turnCount?: number;
111
118
  }>;
112
119
  };
113
120
  }
@@ -238,6 +245,21 @@ function buildDelegationMessages(
238
245
  return [{ role: "assistant", content }];
239
246
  }
240
247
 
248
+ function isFiniteNonNegative(value: unknown): value is number {
249
+ return typeof value === "number" && Number.isFinite(value) && value >= 0;
250
+ }
251
+
252
+ function buildDelegationUpdateUsage(entry: Pick<AgentProgress, "inputTokens" | "outputTokens" | "cacheRead" | "cacheWrite" | "turnCount"> | undefined): SubagentDelegationUpdateUsage | undefined {
253
+ if (!entry) return undefined;
254
+ const { inputTokens, outputTokens, cacheRead, cacheWrite, turnCount } = entry;
255
+ if (!isFiniteNonNegative(inputTokens)
256
+ || !isFiniteNonNegative(outputTokens)
257
+ || !isFiniteNonNegative(cacheRead)
258
+ || !isFiniteNonNegative(cacheWrite)
259
+ || !isFiniteNonNegative(turnCount)) return undefined;
260
+ return { input: inputTokens, output: outputTokens, cacheRead, cacheWrite, turns: turnCount };
261
+ }
262
+
241
263
  export function toDelegationUpdate(requestId: string, update: PromptTemplateBridgeResult): PromptTemplateDelegationUpdate | undefined {
242
264
  const progress = update.details?.progress?.[0];
243
265
  const taskProgress = update.details?.progress?.map((entry) => {
@@ -277,6 +299,7 @@ export function toDelegationUpdate(requestId: string, update: PromptTemplateBrid
277
299
  recentTools: sanitizeRecentTools(progress?.recentTools),
278
300
  model: progress ? resolveProgressModel(update, progress) : undefined,
279
301
  toolCount: progress?.toolCount,
302
+ usage: buildDelegationUpdateUsage(progress),
280
303
  durationMs: progress?.durationMs,
281
304
  tokens: progress?.tokens,
282
305
  taskProgress,
@@ -325,6 +348,7 @@ export function toSubagentDelegationUpdate(
325
348
  ...(typeof legacy.toolCount === "number" ? { toolCount: legacy.toolCount } : {}),
326
349
  ...(typeof legacy.durationMs === "number" ? { durationMs: legacy.durationMs } : {}),
327
350
  ...(typeof legacy.tokens === "number" ? { tokens: legacy.tokens } : {}),
351
+ ...(legacy.usage ? { usage: legacy.usage } : {}),
328
352
  };
329
353
  }
330
354
 
@@ -82,6 +82,20 @@ function sameRecentTools(
82
82
  return left.every((tool, index) => tool.tool === right[index]?.tool && tool.args === right[index]?.args);
83
83
  }
84
84
 
85
+ /** A cache-only or turn-only change with unchanged tokens/tool progress must still count as a change, not a heartbeat. */
86
+ function sameUpdateUsage(
87
+ left: SubagentDelegationUpdate["usage"],
88
+ right: SubagentDelegationUpdate["usage"],
89
+ ): boolean {
90
+ if (left === right) return true;
91
+ if (!left || !right) return false;
92
+ return left.input === right.input
93
+ && left.output === right.output
94
+ && left.cacheRead === right.cacheRead
95
+ && left.cacheWrite === right.cacheWrite
96
+ && left.turns === right.turns;
97
+ }
98
+
85
99
  /** Duration is a heartbeat clock, not delegation-visible progress; terminal usage remains authoritative. */
86
100
  function sameStructuredDelegationUpdateProgress(left: SubagentDelegationUpdate, right: SubagentDelegationUpdate): boolean {
87
101
  return left.requestId === right.requestId
@@ -95,7 +109,8 @@ function sameStructuredDelegationUpdateProgress(left: SubagentDelegationUpdate,
95
109
  && sameRecentTools(left.recentTools, right.recentTools)
96
110
  && left.model === right.model
97
111
  && left.toolCount === right.toolCount
98
- && left.tokens === right.tokens;
112
+ && left.tokens === right.tokens
113
+ && sameUpdateUsage(left.usage, right.usage);
99
114
  }
100
115
 
101
116
  export function registerPromptTemplateDelegationBridge<Ctx extends { cwd?: string }>(
@@ -219,7 +234,7 @@ export function registerPromptTemplateDelegationBridge<Ctx extends { cwd?: strin
219
234
  requestId: legacy.requestId,
220
235
  messages: [],
221
236
  isError: true,
222
- errorText: "Legacy prompt-template tasks/worktree orchestration was removed; use workflowScript.",
237
+ errorText: "Legacy prompt-template tasks/worktree orchestration was removed; use a workflow script.",
223
238
  });
224
239
  return;
225
240
  }
@@ -230,7 +245,7 @@ export function registerPromptTemplateDelegationBridge<Ctx extends { cwd?: strin
230
245
  ...legacyRequest,
231
246
  messages: [],
232
247
  isError: true,
233
- errorText: "Legacy prompt-template direct delegation was removed; use workflowScript through the subagent tool or structured delegation.",
248
+ errorText: "Legacy prompt-template direct delegation was removed; use a workflow script through the subagent tool or structured delegation.",
234
249
  } satisfies PromptTemplateDelegationResponse);
235
250
  return;
236
251
  }
@@ -41,7 +41,18 @@ function readPromptFiles(cwd: string): string[] {
41
41
  continue;
42
42
  }
43
43
  for (const entry of entries) {
44
- if (entry.isFile() && entry.name.endsWith(".md")) files.push(path.join(dir, entry.name));
44
+ if (!entry.name.endsWith(".md")) continue;
45
+ const filePath = path.join(dir, entry.name);
46
+ let isFile = entry.isFile();
47
+ if (entry.isSymbolicLink()) {
48
+ try {
49
+ isFile = fs.statSync(filePath).isFile();
50
+ } catch (error) {
51
+ if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
52
+ isFile = false;
53
+ }
54
+ }
55
+ if (isFile) files.push(filePath);
45
56
  }
46
57
  }
47
58
  return files;