@xzzpig/pi-subagents 0.18.0 → 0.20.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 (108) hide show
  1. package/CHANGELOG.md +129 -0
  2. package/README.md +1 -1
  3. package/docs/agents.md +32 -16
  4. package/docs/configuration.md +76 -9
  5. package/docs/extension-api.md +6 -5
  6. package/docs/missions.md +28 -14
  7. package/docs/models.md +8 -4
  8. package/docs/observability.md +10 -5
  9. package/docs/standalone-background.md +1 -1
  10. package/docs/tool-reference.md +90 -88
  11. package/docs/workflows.md +171 -173
  12. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  13. package/package.json +6 -6
  14. package/prompts/review-loop.md +1 -1
  15. package/skills/council-mode/SKILL.md +1 -1
  16. package/skills/pi-subagents/SKILL.md +12 -5
  17. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -3
  18. package/skills/pi-subagents/references/execution-controls.md +68 -67
  19. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  20. package/skills/pi-subagents/references/multi-lane-orchestration.md +1 -1
  21. package/skills/pi-subagents/references/prompting-and-roles.md +45 -48
  22. package/src/agents/advertised-agent-prompt.ts +21 -41
  23. package/src/agents/agent-management.ts +2 -2
  24. package/src/agents/agents.ts +66 -3
  25. package/src/api/preflight.ts +109 -63
  26. package/src/extension/config.ts +15 -4
  27. package/src/extension/control-notices.ts +3 -0
  28. package/src/extension/doctor.ts +1 -0
  29. package/src/extension/fanout-child.ts +12 -3
  30. package/src/extension/herdr-pi-bridge.ts +2 -0
  31. package/src/extension/index.ts +90 -174
  32. package/src/extension/public-execution.ts +72 -35
  33. package/src/extension/reply-workflow-script.ts +58 -0
  34. package/src/extension/rpc.ts +29 -10
  35. package/src/extension/schemas.ts +40 -135
  36. package/src/extension/tool-activation.ts +57 -108
  37. package/src/extension/tool-description.ts +62 -27
  38. package/src/extension/upgrade-notice.ts +40 -0
  39. package/src/integrations/herdr-status.ts +19 -3
  40. package/src/intercom/native-supervisor-channel.ts +4 -1
  41. package/src/missions/goal-driver.ts +44 -31
  42. package/src/missions/store.ts +10 -1
  43. package/src/profiles/profiles.ts +5 -2
  44. package/src/runs/background/async-execution.ts +146 -59
  45. package/src/runs/background/async-job-tracker.ts +66 -24
  46. package/src/runs/background/async-retention.ts +46 -16
  47. package/src/runs/background/await-async-run.ts +78 -0
  48. package/src/runs/background/chain-root-attachment.ts +4 -4
  49. package/src/runs/background/control-channel.ts +61 -2
  50. package/src/runs/background/notify.ts +5 -0
  51. package/src/runs/background/run-child-session.ts +17 -7
  52. package/src/runs/background/run-status.ts +6 -0
  53. package/src/runs/background/runner-aliases.ts +37 -6
  54. package/src/runs/background/runner-child-launch.ts +3 -0
  55. package/src/runs/background/scheduled-runs.ts +33 -18
  56. package/src/runs/background/stale-run-reconciler.ts +13 -2
  57. package/src/runs/background/subagent-runner.ts +58 -5
  58. package/src/runs/foreground/async-stop-action.ts +17 -3
  59. package/src/runs/foreground/command-action.ts +41 -0
  60. package/src/runs/foreground/execution.ts +145 -131
  61. package/src/runs/foreground/subagent-executor.ts +546 -296
  62. package/src/runs/shared/async-status-projection.ts +5 -0
  63. package/src/runs/shared/child-commands.ts +228 -0
  64. package/src/runs/shared/child-launch.ts +15 -2
  65. package/src/runs/shared/child-session.ts +184 -24
  66. package/src/runs/shared/child-tool-plan.ts +16 -4
  67. package/src/runs/shared/claude-code-adapter.ts +157 -2
  68. package/src/runs/shared/dynamic-fanout.ts +2 -2
  69. package/src/runs/shared/external-cli-preflight.ts +54 -6
  70. package/src/runs/shared/external-cli-runner.ts +5 -1
  71. package/src/runs/shared/mcp-config-sources.ts +2 -1
  72. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -11
  73. package/src/runs/shared/model-resolution.ts +38 -10
  74. package/src/runs/shared/model-scope.ts +28 -9
  75. package/src/runs/shared/nested-events.ts +55 -55
  76. package/src/runs/shared/parallel-utils.ts +4 -0
  77. package/src/runs/shared/pi-spawn.ts +7 -95
  78. package/src/runs/shared/run-history.ts +87 -0
  79. package/src/runs/shared/subagent-control.ts +32 -17
  80. package/src/runs/shared/subagent-prompt-runtime.ts +14 -6
  81. package/src/runs/shared/worktree.ts +1 -1
  82. package/src/shared/disabled-features.ts +123 -0
  83. package/src/shared/extension-context.ts +13 -0
  84. package/src/shared/model-info.ts +9 -0
  85. package/src/shared/required-child-extensions.ts +39 -5
  86. package/src/shared/settings.ts +1 -1
  87. package/src/shared/types.ts +27 -1
  88. package/src/slash/prompt-template-bridge.ts +2 -2
  89. package/src/slash/slash-commands.ts +10 -5
  90. package/src/slash/subagent-cost.ts +9 -5
  91. package/src/slash/subagents-admin.ts +24 -24
  92. package/src/tui/fleet-status.ts +14 -6
  93. package/src/tui/fleet.ts +14 -2
  94. package/src/tui/render.ts +117 -56
  95. package/src/tui/running-tone.ts +28 -0
  96. package/src/watchdog/diff-tool.ts +23 -9
  97. package/src/watchdog/register-child.ts +3 -3
  98. package/src/watchdog/register-main.ts +3 -3
  99. package/src/watchdog/review.ts +2 -2
  100. package/src/watchdog/turn-delta.ts +1 -1
  101. package/src/workflows/chat-progress.ts +2 -2
  102. package/src/workflows/scripted-workflow.ts +117 -37
  103. package/src/workflows/structured-workflow-scripts.ts +177 -0
  104. package/src/workflows/workflow-checklist.ts +6 -0
  105. package/src/workflows/workflow-receipt.ts +10 -4
  106. package/src/workflows/workflow-resources.ts +44 -16
  107. package/src/workflows/workflow-reuse.ts +120 -0
  108. package/src/workflows/workflow-revival.ts +123 -0
@@ -5,7 +5,7 @@
5
5
  * - Sync (default): Streams output, renders markdown, tracks usage
6
6
  * - Async: Background execution, emits events when done
7
7
  *
8
- * Public execution mode: workflow (workflowScript)
8
+ * Public execution mode: workflow (workflow: true reply block, script path, or named resource)
9
9
  * Toggle: async parameter (default: true; set asyncByDefault:false in config.json to opt out)
10
10
  *
11
11
  * Config file: ~/.pi/agent/extensions/subagent/config.json
@@ -21,7 +21,7 @@ import { keyText, type ExtensionAPI, type ExtensionContext, type ToolDefinition
21
21
  import { Box, Container, Spacer, Text, truncateToWidth, visibleWidth, wrapTextWithAnsi, type Component } from "@earendil-works/pi-tui";
22
22
  import { clearAgentDiscoveryCache, discoverAgentSnapshot, discoverAgents, discoverAgentsAll, type AgentConfig, type AgentScope } from "../agents/agents.ts";
23
23
  import { resolveGlobalNpmRoot } from "../agents/global-npm-root.ts";
24
- import { appendAdvertisedAgentPrompt, buildAdvertisedAgentPrompt } from "../agents/advertised-agent-prompt.ts";
24
+ import { buildAdvertisedAgentCatalog, buildAdvertisedAgentPrompt } from "../agents/advertised-agent-prompt.ts";
25
25
  import { mergeAgentsForScope } from "../agents/agent-selection.ts";
26
26
  import { clearRuntimeAgentsForPi, listRuntimeAgentConfigs, mergeRuntimeAgents } from "../agents/runtime-agent-registry.ts";
27
27
  import { discoverAgentsWithRuntime } from "../agents/runtime-discovery.ts";
@@ -30,13 +30,15 @@ import { ensureAccessibleDir } from "../shared/accessible-dir.ts";
30
30
  import { cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir } from "../shared/artifacts.ts";
31
31
  import { resolveCurrentSessionId } from "../shared/session-identity.ts";
32
32
  import { getAgentDir } from "../shared/utils.ts";
33
- import { isStaleExtensionContextError, withCachedUiContext } from "../shared/extension-context.ts";
33
+ import { isStaleExtensionContextError, MODEL_ONLY_TOOL, withCachedUiContext } from "../shared/extension-context.ts";
34
34
  import { currentCompletionOwnerId } from "../shared/completion-owner.ts";
35
35
  import { cleanupOldChainDirs } from "../shared/settings.ts";
36
36
  import { clearLegacyResultAnimationTimer, renderSubagentResult, renderSubagentSummary, setInlineWorkflowCoverage } from "../tui/render.ts";
37
37
  import { getInspectorPlugins, registerInspectorEventListener } from "../inspectors/plugins.ts";
38
38
  import { SubagentFleetStatus, resolveFleetViewPlacement } from "../tui/fleet-status.ts";
39
+ import { readMainThinkingLevel, setMainThinkingLevelSource } from "../tui/running-tone.ts";
39
40
  import { createSubagentParamsSchema } from "./schemas.ts";
41
+ import { resolveDisabledFeatureSurface } from "../shared/disabled-features.ts";
40
42
  import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts";
41
43
  import { createAsyncJobTracker } from "../runs/background/async-job-tracker.ts";
42
44
  import { getActiveAsyncCapacitySnapshot, resolveAbandonedSlotReleaseAfterMs, resolveMaxActiveAsyncRunsPerSession } from "../runs/background/active-async-capacity.ts";
@@ -78,7 +80,9 @@ import { loadConfig, resolveAsyncByDefault, resolveScheduledStoreRoot } from "./
78
80
  import { applyInjectionBlock, renderInjectionBlock, resolveInjectableAgents } from "./context-injection.ts";
79
81
  import { buildSubagentToolDescription, buildSubagentToolPromptMetadata } from "./tool-description.ts";
80
82
  import { formatWorkflowPreflightSummary, normalizeWorkflowPreflight } from "../workflows/workflow-preflight.ts";
83
+ import { runtimeReplacedAbortReason } from "../workflows/workflow-reuse.ts";
81
84
  import { finalizeToolResult } from "./tool-result.ts";
85
+ import { removedModelWorkflowFieldError } from "./public-execution.ts";
82
86
  import { collectGoalContinuationNotices } from "../missions/goal-driver.ts";
83
87
  import { restoreForegroundRunHistory } from "../runs/foreground/foreground-history.ts";
84
88
  import { resolveMissionStoreLocation } from "../missions/store.ts";
@@ -105,10 +109,13 @@ import {
105
109
  SUBAGENT_CONTROL_MESSAGE_TYPE,
106
110
  type SubagentControlMessageDetails,
107
111
  } from "./control-notices.ts";
112
+ import { showUpgradeNotice } from "./upgrade-notice.ts";
108
113
 
109
114
  export { loadConfig, resolveAsyncByDefault } from "./config.ts";
110
115
 
111
116
  const SLOW_RELOAD_PHASE_MS = 250;
117
+ // Long enough for Pi to finish starting; loading the executor blocks the event loop for tens of ms.
118
+ const MODULE_PRELOAD_DELAY_MS = 1_000;
112
119
  const RUNTIME_REGISTRY_STORE_KEY = "__piSubagentRuntimeRegistry";
113
120
 
114
121
  type SubagentExecutorModule = typeof import("../runs/foreground/subagent-executor.ts");
@@ -150,128 +157,6 @@ function logSlowPhase(label: string, startedAt: number): void {
150
157
  if (elapsed >= SLOW_RELOAD_PHASE_MS) console.error(`Subagent reload phase '${label}' took ${elapsed}ms.`);
151
158
  }
152
159
 
153
- function workflowLaneKeys(script: string): string[] {
154
- const keys: string[] = [];
155
- const seen = new Set<string>();
156
- const add = (key: string): void => {
157
- if (!seen.has(key)) {
158
- seen.add(key);
159
- keys.push(key);
160
- }
161
- };
162
- const isIdentifier = (char: string | undefined): boolean => char !== undefined && /[\w$]/.test(char);
163
- const skipTrivia = (start: number): number => {
164
- let index = start;
165
- while (index < script.length) {
166
- if (/\s/.test(script[index]!)) index += 1;
167
- else if (script.startsWith("//", index)) {
168
- const end = script.indexOf("\n", index + 2);
169
- index = end === -1 ? script.length : end + 1;
170
- } else if (script.startsWith("/*", index)) {
171
- const end = script.indexOf("*/", index + 2);
172
- index = end === -1 ? script.length : end + 2;
173
- } else break;
174
- }
175
- return index;
176
- };
177
- const readLiteral = (start: number): { key?: string; end: number } | undefined => {
178
- const quote = script[start];
179
- if (quote !== "'" && quote !== '"' && quote !== "`") return undefined;
180
- let index = start + 1;
181
- let dynamicTemplate = false;
182
- while (index < script.length) {
183
- if (script[index] === "\\") {
184
- index += 2;
185
- continue;
186
- }
187
- if (quote === "`" && script.startsWith("${", index)) dynamicTemplate = true;
188
- if (script[index] === quote) return { key: dynamicTemplate ? undefined : script.slice(start + 1, index), end: index + 1 };
189
- if (quote !== "`" && /[\r\n]/.test(script[index]!)) return { end: index + 1 };
190
- index += 1;
191
- }
192
- return { end: script.length };
193
- };
194
-
195
- const collectRunsAllKeys = (start: number): number => {
196
- let index = skipTrivia(start);
197
- if (script[index] !== "(") return start;
198
- index = skipTrivia(index + 1);
199
- if (script[index] !== "[") return start;
200
- let arrayDepth = 1;
201
- let objectDepth = 0;
202
- let directChildObject = false;
203
- let expectingElement = true;
204
- for (index += 1; index < script.length; index += 1) {
205
- index = skipTrivia(index);
206
- const literal = readLiteral(index);
207
- if (literal) {
208
- index = literal.end - 1;
209
- continue;
210
- }
211
- if (script[index] === "[") {
212
- arrayDepth += 1;
213
- expectingElement = false;
214
- continue;
215
- }
216
- if (script[index] === "]") {
217
- arrayDepth -= 1;
218
- if (arrayDepth === 0) return index + 1;
219
- continue;
220
- }
221
- if (script[index] === "{") {
222
- objectDepth += 1;
223
- if (objectDepth === 1) directChildObject = arrayDepth === 1 && expectingElement;
224
- expectingElement = false;
225
- continue;
226
- }
227
- if (script[index] === "}") {
228
- objectDepth -= 1;
229
- if (objectDepth === 0) directChildObject = false;
230
- continue;
231
- }
232
- if (script[index] === "," && arrayDepth === 1 && objectDepth === 0) {
233
- expectingElement = true;
234
- continue;
235
- }
236
- if (directChildObject && objectDepth === 1 && !isIdentifier(script[index - 1]) && script.startsWith("key", index) && !isIdentifier(script[index + 3])) {
237
- const colon = skipTrivia(index + 3);
238
- const key = script[colon] === ":" ? readLiteral(skipTrivia(colon + 1)) : undefined;
239
- if (key) {
240
- const next = skipTrivia(key.end);
241
- if (key.key !== undefined && (script[next] === "," || script[next] === "}")) add(key.key);
242
- index = key.end - 1;
243
- }
244
- }
245
- }
246
- return index;
247
- };
248
-
249
- for (let index = 0; index < script.length;) {
250
- index = skipTrivia(index);
251
- const literal = readLiteral(index);
252
- if (literal) {
253
- index = literal.end;
254
- continue;
255
- }
256
- if (!isIdentifier(script[index - 1]) && script.startsWith("runs.run", index) && !isIdentifier(script[index + 8])) {
257
- const open = skipTrivia(index + 8);
258
- const key = script[open] === "(" ? readLiteral(skipTrivia(open + 1)) : undefined;
259
- if (key) {
260
- const next = skipTrivia(key.end);
261
- if (key.key !== undefined && (script[next] === "," || script[next] === ")")) add(key.key);
262
- index = key.end;
263
- continue;
264
- }
265
- }
266
- if (!isIdentifier(script[index - 1]) && script.startsWith("runs.all", index) && !isIdentifier(script[index + 8])) {
267
- index = collectRunsAllKeys(index + 8);
268
- continue;
269
- }
270
- index += 1;
271
- }
272
- return keys;
273
- }
274
-
275
160
  function formatWorkflowPreflightCall(input: unknown): string {
276
161
  if (input === undefined) return "";
277
162
  try {
@@ -281,18 +166,6 @@ function formatWorkflowPreflightCall(input: unknown): string {
281
166
  }
282
167
  }
283
168
 
284
- function formatWorkflowManifest(script: string, async: unknown, clarify: unknown, preflightInput?: unknown): string {
285
- if (clarify === true) return "workflow script · rejected: clarify UI unsupported";
286
- const keys = workflowLaneKeys(script);
287
- // The workflow executor starts background work unless callers pass async:false.
288
- const mode = async === false ? "foreground" : "background";
289
- const preflight = formatWorkflowPreflightCall(preflightInput);
290
- if (keys.length === 0) return `workflow script · ${mode}${preflight ? ` · ${preflight}` : ""}`;
291
- const visibleKeys = keys.slice(0, 4).join(", ");
292
- const remainder = keys.length > 4 ? `, +${keys.length - 4}` : "";
293
- return `workflow · ${mode} · ${keys.length} lane${keys.length === 1 ? "" : "s"}: ${visibleKeys}${remainder}${preflight ? ` · ${preflight}` : ""}`;
294
- }
295
-
296
169
  /**
297
170
  * Derive subagent session base directory from parent session file.
298
171
  * If parent session is ~/.pi/agent/sessions/abc123.jsonl,
@@ -412,18 +285,31 @@ export function projectActiveHerdrRuns(state: SubagentState): HerdrStatusRun[] {
412
285
  existing.push(...children);
413
286
  foregroundChildrenByWorkflow.set(control.parentWorkflowRunId, existing);
414
287
  }
288
+
289
+ // Keep each async child under its own ID: completion and attention events
290
+ // address that ID directly. The workflow row accounts only for foreground
291
+ // children; its own coordinator and step summaries are not leaf agents.
415
292
  return [...state.asyncJobs.values()]
416
293
  .filter((job) => active(job.status))
417
294
  .map((job) => {
418
- const children = job.mode === "workflow" ? foregroundChildrenByWorkflow.get(job.asyncId) : undefined;
419
295
  const currentStep = job.steps?.find((step) => step.status === "running")
420
296
  ?? (job.currentStep !== undefined ? job.steps?.[job.currentStep] : undefined)
421
297
  ?? job.steps?.find((step) => step.status === "pending");
298
+ if (job.mode === "workflow") {
299
+ const children = foregroundChildrenByWorkflow.get(job.asyncId) ?? [];
300
+ return {
301
+ id: job.asyncId,
302
+ coordinator: true as const,
303
+ agents: children.map((child) => child.agent),
304
+ ...(currentStep?.label ? { taskLabel: currentStep.label } : {}),
305
+ needsAttention: job.activityState === "needs_attention" || children.some((child) => child.needsAttention),
306
+ };
307
+ }
422
308
  return {
423
309
  id: job.asyncId,
424
- agents: children?.length ? children.map((child) => child.agent) : job.agents,
310
+ agents: job.agents,
425
311
  ...(currentStep?.label ? { taskLabel: currentStep.label } : {}),
426
- needsAttention: job.activityState === "needs_attention" || children?.some((child) => child.needsAttention),
312
+ needsAttention: job.activityState === "needs_attention",
427
313
  };
428
314
  });
429
315
  }
@@ -433,6 +319,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
433
319
  return;
434
320
  }
435
321
  const runtimeRegistry = getRuntimeRegistry();
322
+ setMainThinkingLevelSource(() => readMainThinkingLevel(() => pi.getThinkingLevel()));
436
323
 
437
324
  DIRS.results = ensureAccessibleDir(DIRS.results);
438
325
  DIRS.async = ensureAccessibleDir(DIRS.async);
@@ -444,6 +331,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
444
331
  const fleetViewEnabled = config.fleetView !== false;
445
332
  const fleetViewPlacement = resolveFleetViewPlacement(config.fleetViewPlacement);
446
333
  const asyncWidgetEnabled = config.asyncWidget !== false;
334
+ const asyncWidgetCollapsed = config.asyncWidgetCollapsed === true;
447
335
  const summaryInlineToolDisplay = config.inlineToolDisplay === "summary";
448
336
  const tempArtifactsDir = getArtifactsDir(null);
449
337
  const artifactCleanupDays = config.artifactConfig?.cleanupDays ?? DEFAULT_ARTIFACT_CONFIG.cleanupDays;
@@ -598,6 +486,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
598
486
  };
599
487
  const { ensurePoller, refreshWidget, handleStarted, handleComplete, resetJobs, restoreActiveJobs, dispose: disposeAsyncJobTracker } = createAsyncJobTracker(pi, state, DIRS.async, {
600
488
  widgetEnabled: asyncWidgetEnabled,
489
+ widgetCollapsed: asyncWidgetCollapsed,
601
490
  onJobTerminal: () => refreshResultDelivery(),
602
491
  supervisorRequestState: supervisorChannel.getSupervisorRequestState,
603
492
  });
@@ -682,13 +571,29 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
682
571
  };
683
572
  let executor: SubagentExecutor | undefined;
684
573
  let executorPromise: Promise<SubagentExecutor> | undefined;
574
+ let executorModulePromise: Promise<SubagentExecutorModule> | undefined;
575
+ const loadExecutorModule = () => executorModulePromise ??= import("../runs/foreground/subagent-executor.ts");
685
576
  const getExecutor = (): Promise<SubagentExecutor> => {
686
- executorPromise ??= import("../runs/foreground/subagent-executor.ts").then(({ createSubagentExecutor }) => {
577
+ executorPromise ??= loadExecutorModule().then(({ createSubagentExecutor }) => {
687
578
  executor = createSubagentExecutor(executorDeps);
688
579
  return executor;
689
580
  });
690
581
  return executorPromise;
691
582
  };
583
+ // Loading these on first use could happen days after startup, when pi-subagents may have
584
+ // changed on disk and the new files would import stale cached copies of modules loaded at
585
+ // startup. Load them shortly after a session starts instead, off Pi's startup path; child
586
+ // runtimes return before registration and never schedule this.
587
+ let modulePreloadTimer: ReturnType<typeof setTimeout> | undefined;
588
+ const scheduleModulePreload = () => {
589
+ if (executorModulePromise || modulePreloadTimer) return;
590
+ modulePreloadTimer = setTimeout(() => {
591
+ // Errors surface from the first call that needs the module.
592
+ loadExecutorModule().catch(() => {});
593
+ if (fleetViewEnabled) import("../tui/fleet.ts").catch(() => {});
594
+ }, MODULE_PRELOAD_DELAY_MS);
595
+ modulePreloadTimer.unref?.();
596
+ };
692
597
 
693
598
  pi.registerMessageRenderer<SupervisorRequestMessageDetails>(SUPERVISOR_REQUEST_MESSAGE_TYPE, renderSupervisorRequest);
694
599
  // SAFETY: `registerEntryRenderer` is not part of the typed ExtensionAPI in the
@@ -805,23 +710,28 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
805
710
  },
806
711
  });
807
712
 
713
+ const disabledFeatures = resolveDisabledFeatureSurface(config);
808
714
  const rpcBridge = registerSubagentRpcBridge({
809
715
  events: pi.events,
810
716
  getContext: () => state.lastUiContext,
811
717
  execute: executeSubagentReady,
812
718
  state,
719
+ disabledFeatures,
813
720
  });
814
721
 
815
722
 
816
- const parameters = createSubagentParamsSchema();
723
+ const parameters = createSubagentParamsSchema(disabledFeatures);
817
724
  const tool: ToolDefinition<typeof parameters, Details> = {
818
725
  name: "subagent",
726
+ ...MODEL_ONLY_TOOL,
819
727
  label: "Subagent",
820
- description: buildSubagentToolDescription(config),
821
- ...buildSubagentToolPromptMetadata(config),
728
+ description: buildSubagentToolDescription(config, { disabledFeatures }),
729
+ ...buildSubagentToolPromptMetadata(config, disabledFeatures),
822
730
  parameters,
823
731
 
824
732
  async execute(id, params, signal, onUpdate, ctx) {
733
+ const removedField = removedModelWorkflowFieldError(params);
734
+ if (removedField) throw new Error(removedField);
825
735
  return finalizeToolResult(await executeSubagentCollapsed(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx));
826
736
  },
827
737
 
@@ -835,15 +745,9 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
835
745
  0, 0,
836
746
  );
837
747
  }
838
- if (args.workflowScript)
839
- return new Text(
840
- `${title}${gap}${formatWorkflowManifest(args.workflowScript, args.async, false, args.preflight)}`,
841
- 0,
842
- 0,
843
- );
844
- if (args.workflowScriptPath)
748
+ if (args.workflow !== undefined)
845
749
  return new Text(
846
- `${title}${gap}${theme.fg("accent", args.workflowScriptPath)}${args.async === true ? `${gap}${theme.fg("warning", "[async]")}` : ""}${args.preflight !== undefined ? `${gap}${theme.fg("dim", formatWorkflowPreflightCall(args.preflight))}` : ""}`,
750
+ `${title}${gap}${theme.fg("accent", args.workflow === true || args.workflow === "true" ? "workflow (reply block)" : `workflow ${String(args.workflow)}`)}${args.async === true ? `${gap}${theme.fg("warning", "[async]")}` : ""}${args.preflight !== undefined ? `${gap}${theme.fg("dim", formatWorkflowPreflightCall(args.preflight))}` : ""}`,
847
751
  0,
848
752
  0,
849
753
  );
@@ -878,41 +782,47 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
878
782
 
879
783
  pi.on("before_agent_start", async (event, ctx) => {
880
784
  await waitForAdvertisement();
881
- const selectedTools = event.systemPromptOptions?.selectedTools ?? (typeof pi.getActiveTools === "function" ? pi.getActiveTools() : []);
785
+ if (!event.systemPromptOptions.selectedTools.includes("subagent")) return;
882
786
  const sessionId = state.currentSessionId ?? resolveCurrentSessionId(ctx.sessionManager);
883
- const advertisedPrompt = Array.isArray(selectedTools) && selectedTools.includes("subagent")
884
- ? buildAdvertisedAgentPrompt(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(sessionId))
885
- : undefined;
886
- const systemPrompt = appendAdvertisedAgentPrompt(event.systemPrompt, advertisedPrompt);
887
- if (systemPrompt !== event.systemPrompt) return { systemPrompt };
787
+ // Structured sections let Pi append a transcript delta instead of replacing the
788
+ // cached system prompt. Set the section on every turn it applies: Pi rebuilds the
789
+ // options each turn, and an unset turn records a removal.
790
+ const catalog = buildAdvertisedAgentCatalog(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(sessionId));
791
+ if (catalog) event.systemPromptOptions.sections.advertised_subagents = catalog;
888
792
  });
889
793
 
890
794
  registerWaitTool(pi, state, waitToolConfig.enabled, waitSubscriptionManager, waitToolConfig.defaultTimeoutMs, undefined, supervisorChannel.hasPendingRequests);
891
795
 
892
796
  pi.on("agent_end", async (_event, ctx) => {
893
- if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events, hasPendingSupervisorRequest: supervisorChannel.hasPendingRequests });
894
- const ownerSessionId = state.currentSessionId;
895
- if (!ownerSessionId) return;
896
- goalTurnId += 1;
897
797
  try {
898
- const location = resolveMissionStoreLocation({ projectRoot: state.baseCwd, ...(config.missions ? { config: config.missions } : {}) });
899
- const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionId);
900
- for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
901
- handleSubagentControlNotice({
902
- pi,
903
- state,
904
- visibleControlNotices: new Set(),
905
- details: { source: "goal", event: notice.event, noticeText: notice.message },
906
- });
798
+ if (!ctx.hasUI) await drainOutstandingWork({ state, events: pi.events, hasPendingSupervisorRequest: supervisorChannel.hasPendingRequests });
799
+ } finally {
800
+ // Deliver notices after a failed drain without suppressing its rejection.
801
+ const ownerSessionId = state.currentSessionId;
802
+ if (ownerSessionId) {
803
+ goalTurnId += 1;
804
+ try {
805
+ const location = resolveMissionStoreLocation({ projectRoot: state.baseCwd, ...(config.missions ? { config: config.missions } : {}) });
806
+ const retainedChildren = listRetainedChildren(DIRS.async, ownerSessionId);
807
+ for (const notice of collectGoalContinuationNotices({ location, ownerSessionId, retainedChildren, turnId: goalTurnId })) {
808
+ handleSubagentControlNotice({
809
+ pi,
810
+ state,
811
+ visibleControlNotices: new Set(),
812
+ details: { source: "goal", event: notice.event, noticeText: notice.message },
813
+ });
814
+ }
815
+ } catch (error) {
816
+ console.error("Failed to evaluate goal missions:", error);
817
+ }
907
818
  }
908
- } catch (error) {
909
- console.error("Failed to evaluate goal missions:", error);
910
819
  }
911
820
  });
912
821
 
913
822
  const disposeSlashCommands = registerSlashCommands(pi, state, {
914
823
  fleetKeybindings: config.fleetKeybindings,
915
824
  foregroundDetachShortcut: config.foregroundDetachShortcut,
825
+ workflowScriptsDisabled: disabledFeatures.features.has("workflow-scripts"),
916
826
  });
917
827
 
918
828
  let visibleControlNotices = new Set<string>();
@@ -1124,7 +1034,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1124
1034
  // Workflow continuations retain their launch context; abort them before
1125
1035
  // teardown so a reload cannot launch through a stale context.
1126
1036
  for (const controller of state.workflowControllers?.values() ?? []) {
1127
- if (!controller.signal.aborted) controller.abort(new Error("Workflow stopped because the extension session was replaced or reloaded."));
1037
+ if (!controller.signal.aborted) controller.abort(runtimeReplacedAbortReason());
1128
1038
  }
1129
1039
  state.workflowControllers?.clear();
1130
1040
  state.workflowChildStops?.clear();
@@ -1133,6 +1043,8 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1133
1043
  resultIndexCleanupTimer = undefined;
1134
1044
  if (asyncRetentionTimer) clearTimeout(asyncRetentionTimer);
1135
1045
  asyncRetentionTimer = undefined;
1046
+ if (modulePreloadTimer) clearTimeout(modulePreloadTimer);
1047
+ modulePreloadTimer = undefined;
1136
1048
  asyncRetentionAbort.abort();
1137
1049
  stopResultWatcher();
1138
1050
  resultDeliveryOwnership.clear();
@@ -1239,6 +1151,7 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1239
1151
  pi.on("session_start", (event, ctx) => {
1240
1152
  installRuntime(ctx);
1241
1153
  startSessionMaintenance();
1154
+ scheduleModulePreload();
1242
1155
  const recovering = event.reason === "startup" || event.reason === "reload" || event.reason === "resume";
1243
1156
  resetSessionState(ctx, recovering, event.previousSessionFile);
1244
1157
  refreshContextInjectionSnapshot(ctx);
@@ -1276,9 +1189,12 @@ export default function registerSubagentExtension(pi: ExtensionAPI): void {
1276
1189
  await herdrStatusBridge.flush();
1277
1190
  });
1278
1191
 
1192
+ // Child processes and Herdr panes never load this module; in-process children have no UI.
1193
+ pi.on("session_start", (_event, ctx) => void showUpgradeNotice(ctx).catch((error) => console.error("Failed to show the pi-subagents upgrade notice:", error)));
1279
1194
  pi.on("session_start", (_event, ctx) => beginAdvertisement(ctx));
1280
1195
 
1281
1196
  registerSubagentToolActivation(pi, {
1197
+ mode: config.toolActivation,
1282
1198
  advertisedPrompt: async () => {
1283
1199
  await waitForAdvertisement();
1284
1200
  return buildAdvertisedAgentPrompt(advertisedAgents, resolveCurrentSubagentCapabilityCeiling(state.currentSessionId ?? undefined));