@xzzpig/pi-subagents 0.4.2 → 0.5.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 (127) hide show
  1. package/CHANGELOG.md +168 -0
  2. package/README.md +4 -0
  3. package/agents/oracle.md +3 -1
  4. package/agents/reviewer.md +1 -0
  5. package/agents/scout.md +2 -2
  6. package/agents/worker.md +2 -1
  7. package/async-retention-discovery-worker.mjs +180 -0
  8. package/docs/agents.md +40 -2
  9. package/docs/configuration.md +41 -13
  10. package/docs/extension-api.md +45 -2
  11. package/docs/models.md +2 -0
  12. package/docs/observability.md +41 -5
  13. package/docs/tool-reference.md +38 -39
  14. package/docs/workflows.md +173 -3
  15. package/package.json +13 -10
  16. package/prompts/council.md +48 -0
  17. package/skills/council-mode/SKILL.md +230 -0
  18. package/skills/pi-subagents/SKILL.md +8 -4
  19. package/skills/pi-subagents/references/constraints-and-recipes.md +13 -6
  20. package/skills/pi-subagents/references/execution-controls.md +40 -15
  21. package/skills/pi-subagents/references/management-authoring-rpc.md +3 -3
  22. package/skills/pi-subagents/references/multi-lane-orchestration.md +39 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +4 -2
  24. package/src/agents/agent-management.ts +158 -357
  25. package/src/agents/agent-serializer.ts +2 -0
  26. package/src/agents/agents.ts +186 -44
  27. package/src/agents/builtin-names.ts +9 -0
  28. package/src/agents/runtime-agent-registry.ts +418 -0
  29. package/src/agents/skills.ts +1 -1
  30. package/src/api/agents.ts +7 -0
  31. package/src/api/external-job-provider.ts +186 -0
  32. package/src/api/preflight.ts +37 -9
  33. package/src/api/shared-types.ts +2 -0
  34. package/src/extension/config.ts +6 -3
  35. package/src/extension/doctor.ts +4 -6
  36. package/src/extension/fanout-child.ts +2 -2
  37. package/src/extension/index.ts +183 -90
  38. package/src/extension/public-execution.ts +31 -2
  39. package/src/extension/rpc.ts +41 -1
  40. package/src/extension/schemas.ts +17 -37
  41. package/src/extension/tool-description.ts +35 -24
  42. package/src/inspectors/herdr/actions.ts +2 -2
  43. package/src/inspectors/herdr/inspector-runner.ts +2 -1
  44. package/src/inspectors/herdr/project-panes.ts +2 -2
  45. package/src/intercom/native-supervisor-channel.ts +32 -10
  46. package/src/missions/lifecycle.ts +6 -1
  47. package/src/missions/store.ts +4 -9
  48. package/src/missions/workflow-state.ts +2 -2
  49. package/src/profiles/profiles.ts +3 -1
  50. package/src/runs/background/active-run-index.ts +31 -8
  51. package/src/runs/background/async-execution.ts +70 -41
  52. package/src/runs/background/async-job-tracker.ts +24 -7
  53. package/src/runs/background/async-resume.ts +49 -16
  54. package/src/runs/background/async-retention.ts +886 -0
  55. package/src/runs/background/async-status-snapshot.ts +14 -5
  56. package/src/runs/background/async-status.ts +39 -53
  57. package/src/runs/background/auto-drain.ts +1 -0
  58. package/src/runs/background/chain-append.ts +3 -33
  59. package/src/runs/background/completion-dedupe.ts +5 -1
  60. package/src/runs/background/completion-replay.ts +22 -12
  61. package/src/runs/background/control-channel.ts +14 -68
  62. package/src/runs/background/fleet-view.ts +68 -19
  63. package/src/runs/background/index-segment.ts +59 -0
  64. package/src/runs/background/inspect-rpc.ts +443 -0
  65. package/src/runs/background/notify.ts +31 -5
  66. package/src/runs/background/result-files.ts +158 -90
  67. package/src/runs/background/result-watcher.ts +124 -20
  68. package/src/runs/background/resume-guidance.ts +8 -5
  69. package/src/runs/background/retained-children.ts +13 -3
  70. package/src/runs/background/run-id-query.ts +7 -0
  71. package/src/runs/background/run-id-resolver.ts +11 -9
  72. package/src/runs/background/run-status.ts +27 -18
  73. package/src/runs/background/scheduled-runs.ts +24 -4
  74. package/src/runs/background/stale-run-reconciler.ts +6 -3
  75. package/src/runs/background/steering.ts +11 -1
  76. package/src/runs/background/subagent-runner.ts +260 -144
  77. package/src/runs/background/subagent-wait.ts +17 -13
  78. package/src/runs/background/terminal-run-index.ts +138 -0
  79. package/src/runs/background/wait-completions.ts +21 -4
  80. package/src/runs/background/wait-subscriptions.ts +81 -2
  81. package/src/runs/background/wait-tool.ts +1 -0
  82. package/src/runs/foreground/async-steering-action.ts +21 -14
  83. package/src/runs/foreground/execution.ts +8 -2
  84. package/src/runs/foreground/subagent-executor.ts +816 -1593
  85. package/src/runs/foreground/workflow-detach-reconcile.ts +262 -0
  86. package/src/runs/foreground/workflow-foreground-steering.ts +6 -5
  87. package/src/runs/shared/acceptance.ts +48 -5
  88. package/src/runs/shared/chain-outputs.ts +1 -3
  89. package/src/runs/shared/external-job-bridge.ts +444 -0
  90. package/src/runs/shared/external-job-runner.ts +286 -0
  91. package/src/runs/shared/mcp-direct-tool-allowlist.ts +14 -0
  92. package/src/runs/shared/model-exclusions.ts +242 -0
  93. package/src/runs/shared/model-fallback.ts +153 -40
  94. package/src/runs/shared/orca-progress-tabs.ts +84 -22
  95. package/src/runs/shared/parallel-handoff.ts +46 -4
  96. package/src/runs/shared/parallel-utils.ts +4 -15
  97. package/src/runs/shared/permissions.ts +5 -1
  98. package/src/runs/shared/pi-args.ts +8 -1
  99. package/src/runs/shared/session-lease.ts +0 -6
  100. package/src/runs/shared/subagent-control.ts +51 -7
  101. package/src/runs/shared/subagent-prompt-runtime.ts +12 -6
  102. package/src/runs/shared/workflow-graph.ts +1 -23
  103. package/src/runs/shared/worktree.ts +14 -2
  104. package/src/shared/atomic-json.ts +22 -2
  105. package/src/shared/capacity-resilient-json.ts +102 -0
  106. package/src/shared/completion-owner.ts +14 -0
  107. package/src/shared/file-system-retry.ts +49 -1
  108. package/src/shared/fork-context.ts +59 -1
  109. package/src/shared/model-info.ts +20 -0
  110. package/src/shared/prompt-resources.ts +0 -40
  111. package/src/shared/settings.ts +5 -29
  112. package/src/shared/types.ts +106 -26
  113. package/src/shared/utils.ts +8 -0
  114. package/src/shared/watch-strategy.ts +10 -0
  115. package/src/slash/slash-bridge.ts +2 -1
  116. package/src/slash/slash-commands.ts +47 -7
  117. package/src/slash/slash-live-state.ts +3 -3
  118. package/src/tui/fleet-status.ts +86 -1
  119. package/src/tui/fleet.ts +117 -16
  120. package/src/tui/render.ts +73 -3
  121. package/src/watchdog/change-signature.ts +1 -1
  122. package/src/watchdog/lsp-diagnostics.ts +1 -0
  123. package/src/workflows/chat-progress.ts +2 -2
  124. package/src/workflows/scripted-workflow.ts +320 -79
  125. package/src/workflows/workflow-receipt.ts +140 -0
  126. package/src/runs/foreground/chain-clarify.ts +0 -1354
  127. package/src/runs/foreground/chain-execution.ts +0 -1581
@@ -64,6 +64,8 @@ export interface SequentialStep {
64
64
  acceptance?: AcceptanceInput;
65
65
  agentContract?: AgentContract;
66
66
  gateOn?: ChainGateLayer;
67
+ /** Internal workflow child isolation; public workflowScript supplies this on runs.run. */
68
+ worktree?: boolean;
67
69
  }
68
70
 
69
71
  /** Parallel task item within a parallel step */
@@ -119,24 +121,6 @@ export interface DynamicParallelStep {
119
121
  gateOn?: ChainGateLayer;
120
122
  }
121
123
 
122
- /** Approval checkpoint: pause before later chain steps until parent approval. */
123
- export interface CheckpointStep {
124
- checkpoint: string;
125
- message?: string;
126
- phase?: string;
127
- label?: string;
128
- agent?: string;
129
- task?: string;
130
- as?: string;
131
- output?: OutputOverrideInput;
132
- outputMode?: OutputMode;
133
- reads?: string[] | false;
134
- progress?: boolean;
135
- skill?: string | string[] | false;
136
- skills?: string[] | false;
137
- model?: string;
138
- }
139
-
140
124
  /** Parallel step: multiple agents running concurrently */
141
125
  export interface ParallelStep {
142
126
  parallel: ParallelTaskItem[];
@@ -149,16 +133,12 @@ export interface ParallelStep {
149
133
  }
150
134
 
151
135
  /** Union type for chain steps */
152
- export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep | CheckpointStep;
136
+ export type ChainStep = SequentialStep | ParallelStep | DynamicParallelStep;
153
137
 
154
138
  // =============================================================================
155
139
  // Type Guards
156
140
  // =============================================================================
157
141
 
158
- export function isCheckpointStep(step: ChainStep): step is CheckpointStep {
159
- return "checkpoint" in step;
160
- }
161
-
162
142
  export function isParallelStep(step: ChainStep): step is ParallelStep {
163
143
  return "parallel" in step && Array.isArray((step as ParallelStep).parallel);
164
144
  }
@@ -169,9 +149,6 @@ export function isDynamicParallelStep(step: ChainStep): step is DynamicParallelS
169
149
 
170
150
  /** Get all agent names in a step (single for sequential, multiple for parallel) */
171
151
  export function getStepAgents(step: ChainStep): string[] {
172
- if (isCheckpointStep(step)) {
173
- return [];
174
- }
175
152
  if (isParallelStep(step)) {
176
153
  return step.parallel.map((t) => t.agent);
177
154
  }
@@ -239,7 +216,6 @@ export function resolveChainTemplates(
239
216
  steps: ChainStep[],
240
217
  ): ResolvedTemplates {
241
218
  return steps.map((step, i) => {
242
- if (isCheckpointStep(step)) return "";
243
219
  if (isParallelStep(step)) {
244
220
  // Parallel step: resolve each task's template
245
221
  return step.parallel.map((task) => {
@@ -306,7 +282,7 @@ export function resolveStepBehavior(
306
282
  }
307
283
  }
308
284
 
309
- const outputMode = stepOverrides.outputMode ?? "inline";
285
+ const outputMode = stepOverrides.outputMode ?? agentConfig.outputMode ?? "inline";
310
286
  const model = stepOverrides.model ?? agentConfig.model;
311
287
  return { output, outputMode, reads, progress, skills, model };
312
288
  }
@@ -489,7 +465,7 @@ export function resolveParallelBehaviors(
489
465
  }
490
466
  }
491
467
 
492
- const outputMode = task.outputMode ?? "inline";
468
+ const outputMode = task.outputMode ?? config.outputMode ?? "inline";
493
469
  const model = task.model ?? config.model;
494
470
  return { output, outputMode, reads, progress, skills, model };
495
471
  });
@@ -41,7 +41,7 @@ export type WorkflowNodeStatus = "pending" | "running" | "completed" | "failed"
41
41
 
42
42
  export interface WorkflowGraphNode {
43
43
  id: string;
44
- kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent" | "checkpoint";
44
+ kind: "step" | "parallel-group" | "dynamic-parallel-group" | "agent";
45
45
  agent?: string;
46
46
  phase?: string;
47
47
  label: string;
@@ -61,16 +61,6 @@ export interface WorkflowGraphNode {
61
61
  structured?: boolean;
62
62
  acceptanceStatus?: AcceptanceLedgerStatus;
63
63
  error?: string;
64
- checkpoint?: ChainCheckpointState;
65
- }
66
-
67
- export interface ChainCheckpointState {
68
- name: string;
69
- message?: string;
70
- status: "pending" | "approved" | "rejected";
71
- stepIndex: number;
72
- approvedAt?: number;
73
- rejectedAt?: number;
74
64
  }
75
65
 
76
66
  export interface WorkflowGraphSnapshot {
@@ -81,6 +71,29 @@ export interface WorkflowGraphSnapshot {
81
71
  currentNodeId?: string;
82
72
  }
83
73
 
74
+ export type WorkflowReceiptState = "complete" | "failed" | "paused" | "stopped";
75
+
76
+ type WorkflowReceiptEntryResumability =
77
+ | { latestRunId: string; resumability: { state: "resumable" } }
78
+ | { latestRunId?: string; resumability: { state: "not-resumable"; reason: string } };
79
+
80
+ export type WorkflowReceiptEntry = WorkflowReceiptEntryResumability & {
81
+ key: string;
82
+ agent?: string;
83
+ requestedContext?: "fresh" | "fork";
84
+ resolvedContext?: "fresh" | "fork" | "mixed";
85
+ outputReference?: string;
86
+ continuation: { runIds: string[] };
87
+ };
88
+
89
+ export interface WorkflowReceipt {
90
+ version: 1;
91
+ workflowRunId: string;
92
+ state: WorkflowReceiptState;
93
+ createdAt: number;
94
+ entries: Record<string, WorkflowReceiptEntry>;
95
+ }
96
+
84
97
  export interface SavedOutputReference {
85
98
  path: string;
86
99
  bytes: number;
@@ -171,6 +184,7 @@ export interface ControlConfig {
171
184
  export interface ResolvedControlConfig {
172
185
  enabled: boolean;
173
186
  needsAttentionAfterMs: number;
187
+ needsAttentionAfterMsIsExplicit?: boolean;
174
188
  activeNoticeAfterMs: number;
175
189
  activeNoticeAfterTurns?: number;
176
190
  activeNoticeAfterTokens?: number;
@@ -224,6 +238,10 @@ export interface ControlEvent {
224
238
  currentPath?: string;
225
239
  elapsedMs?: number;
226
240
  recentFailureSummary?: string;
241
+ workflowKey?: string;
242
+ phase?: string;
243
+ label?: string;
244
+ taskPreview?: string;
227
245
  }
228
246
 
229
247
  export type SubagentResultStatus = "completed" | "failed" | "paused" | "stopped" | "detached";
@@ -282,7 +300,7 @@ export interface ParallelHandoffGroup {
282
300
  export interface ParallelHandoffManifest {
283
301
  version: 1;
284
302
  runId: string;
285
- mode: "parallel" | "chain";
303
+ mode: "single" | "parallel" | "chain";
286
304
  source: "foreground" | "async";
287
305
  cwd: string;
288
306
  createdAt: number;
@@ -415,6 +433,12 @@ export type ProcessTerminalV1 =
415
433
  diagnostic?: string;
416
434
  });
417
435
 
436
+ /** Identifies the durable schedule that launched a run, so its completion is attributable. */
437
+ export interface ScheduleOrigin {
438
+ id: string;
439
+ name?: string;
440
+ }
441
+
418
442
  export type SteeringActionState = "delivered" | "scheduled" | "pending" | "partial" | "recovered" | "failed";
419
443
  export type SteeringTargetState = "scheduled" | "pending" | "routed" | "queued" | "delivered" | "late" | "failed" | "recovered";
420
444
 
@@ -508,6 +532,7 @@ export interface SteeringRecoveryDescriptor {
508
532
  sessionFile?: string;
509
533
  cwd: string;
510
534
  model?: string;
535
+ modelOverrideFromParent?: boolean;
511
536
  fallbackModels?: string[];
512
537
  thinking?: string;
513
538
  tools?: string[];
@@ -528,6 +553,8 @@ export interface SteeringRecoveryDescriptor {
528
553
  structuredOutputSchema?: JsonSchemaObject;
529
554
  acceptance?: AcceptanceInput;
530
555
  controlConfig?: ResolvedControlConfig;
556
+ /** Resolved launch context for this async child. */
557
+ context?: "fresh" | "fork";
531
558
  /** Raw per-run bridge override. Omitted descriptors continue to use global config. */
532
559
  intercomBridge?: IntercomBridgeConfig;
533
560
  absoluteDeadlineAt?: number;
@@ -1057,7 +1084,6 @@ export interface Details {
1057
1084
  totalSteps?: number; // Total steps in chain
1058
1085
  currentStepIndex?: number; // 0-indexed current step (for running chains)
1059
1086
  workflowGraph?: WorkflowGraphSnapshot;
1060
- checkpoint?: ChainCheckpointState;
1061
1087
  outputs?: ChainOutputMap;
1062
1088
  // Aggregated child usage across all agents in the run
1063
1089
  totalChildUsage?: Usage;
@@ -1087,9 +1113,9 @@ export interface Details {
1087
1113
  workflow?: {
1088
1114
  value?: unknown;
1089
1115
  trace: Array<{
1090
- operation: "run" | "status";
1116
+ operation: "run" | "status" | "steer";
1091
1117
  key: string;
1092
- state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused";
1118
+ state: "started" | "completed" | "failed" | "detached" | "stopped" | "reused" | "queued" | "delivered" | "missed";
1093
1119
  agent?: string;
1094
1120
  runId?: string;
1095
1121
  phase?: string;
@@ -1099,6 +1125,8 @@ export interface Details {
1099
1125
  }>;
1100
1126
  emits: unknown[];
1101
1127
  console: Array<{ level: "log" | "info" | "warn" | "error"; text: string }>;
1128
+ /** Terminal keyed child receipt. Async workflows also persist it beside status.json. */
1129
+ receipt?: WorkflowReceipt;
1102
1130
  };
1103
1131
  chatProgress?: {
1104
1132
  mode: "off" | "live-card";
@@ -1266,6 +1294,7 @@ export interface AsyncStartedEvent {
1266
1294
  sessionRoot?: string;
1267
1295
  pid?: number;
1268
1296
  sessionId?: string;
1297
+ completionOwnerId?: string;
1269
1298
  mode?: SubagentRunMode;
1270
1299
  agent?: string;
1271
1300
  agents?: string[];
@@ -1277,7 +1306,6 @@ export interface AsyncStartedEvent {
1277
1306
  chainStepCount?: number;
1278
1307
  parallelGroups?: AsyncParallelGroupStatus[];
1279
1308
  workflowGraph?: WorkflowGraphSnapshot;
1280
- checkpoint?: ChainCheckpointState;
1281
1309
  launchContractDigest?: string;
1282
1310
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1283
1311
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
@@ -1298,6 +1326,11 @@ export type AgentRunnerConfig =
1298
1326
  command: string;
1299
1327
  args?: string[];
1300
1328
  promptDelivery?: "stdin";
1329
+ }
1330
+ | {
1331
+ type: "external-job";
1332
+ provider: string;
1333
+ options?: Record<string, unknown>;
1301
1334
  };
1302
1335
 
1303
1336
  export interface ExternalCliRunnerStatus {
@@ -1314,6 +1347,35 @@ export interface ExternalCliRunnerStatus {
1314
1347
  };
1315
1348
  }
1316
1349
 
1350
+ export interface ExternalJobRunnerStatus {
1351
+ type: "external-job";
1352
+ provider: string;
1353
+ options: Record<string, unknown>;
1354
+ capabilities: {
1355
+ stop: false;
1356
+ steer: false;
1357
+ resume: false;
1358
+ structuredOutput: false;
1359
+ toolEvents: false;
1360
+ };
1361
+ }
1362
+
1363
+ export interface ExternalJobStatus {
1364
+ provider: string;
1365
+ providerJobId?: string;
1366
+ promptDigest: string;
1367
+ options: Record<string, unknown>;
1368
+ handleUrl?: string;
1369
+ conversationUrl?: string;
1370
+ resultArtifactPath?: string;
1371
+ state: "queued" | "running" | "completed" | "failed" | "stopped" | "blocked";
1372
+ failureCode?: string;
1373
+ failureMessage?: string;
1374
+ blockingJobId?: string;
1375
+ startedAt?: number;
1376
+ updatedAt?: number;
1377
+ }
1378
+
1317
1379
  export interface ExternalProcessStatus {
1318
1380
  pid?: number;
1319
1381
  startedAt: number;
@@ -1328,6 +1390,8 @@ export interface ExternalProcessStatus {
1328
1390
  export interface AsyncStatus {
1329
1391
  lifecycleArtifactVersion?: SubagentLifecycleArtifactVersion;
1330
1392
  runId: string;
1393
+ /** Parent Pi process/window that owns local completion delivery. */
1394
+ completionOwnerId?: string;
1331
1395
  /** Host tool-call id retained when it differs from the internal run id. */
1332
1396
  toolCallId?: string;
1333
1397
  sessionId?: string;
@@ -1361,12 +1425,13 @@ export interface AsyncStatus {
1361
1425
  usageBudget?: UsageBudgetState;
1362
1426
  pid?: number;
1363
1427
  cwd?: string;
1428
+ /** Parent-resolved child session root retained for trusted restored transcript lookup. */
1429
+ sessionRoot?: string;
1364
1430
  currentStep?: number;
1365
1431
  chainStepCount?: number;
1366
1432
  pendingAppends?: number;
1367
1433
  parallelGroups?: AsyncParallelGroupStatus[];
1368
1434
  workflowGraph?: WorkflowGraphSnapshot;
1369
- checkpoint?: ChainCheckpointState;
1370
1435
  processTerminal?: ProcessTerminalV1;
1371
1436
  runFanoutBudget?: RunFanoutBudgetSnapshot;
1372
1437
  runFanoutBudgetDescriptor?: RunFanoutBudgetDescriptor;
@@ -1378,10 +1443,13 @@ export interface AsyncStatus {
1378
1443
  workflow?: Details["workflow"];
1379
1444
  parentWorkflowRunId?: string;
1380
1445
  workflowKey?: string;
1446
+ /** Set when a durable schedule launched this run, so completions can name their origin. */
1447
+ scheduleOrigin?: ScheduleOrigin;
1381
1448
  steps?: Array<{
1382
1449
  agent: string;
1383
- runner?: ExternalCliRunnerStatus;
1450
+ runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1384
1451
  externalProcess?: ExternalProcessStatus;
1452
+ externalJob?: ExternalJobStatus;
1385
1453
  /** Resolved launch context for this child step. */
1386
1454
  context?: "fresh" | "fork";
1387
1455
  /** Short caller-facing task/goal shown in fleet surfaces when available. */
@@ -1396,7 +1464,6 @@ export interface AsyncStatus {
1396
1464
  parentWorkflowRunId?: string;
1397
1465
  outputName?: string;
1398
1466
  structured?: boolean;
1399
- checkpoint?: ChainCheckpointState;
1400
1467
  status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1401
1468
  children?: NestedRunSummary[];
1402
1469
  sessionFile?: string;
@@ -1476,6 +1543,7 @@ export interface AsyncJobState {
1476
1543
  description?: string;
1477
1544
  pid?: number;
1478
1545
  sessionId?: string;
1546
+ completionOwnerId?: string;
1479
1547
  activityState?: ActivityState;
1480
1548
  lastActivityAt?: number;
1481
1549
  currentTool?: string;
@@ -1492,7 +1560,6 @@ export interface AsyncJobState {
1492
1560
  chainStepCount?: number;
1493
1561
  parallelGroups?: AsyncParallelGroupStatus[];
1494
1562
  steps?: AsyncJobStep[];
1495
- checkpoint?: ChainCheckpointState;
1496
1563
  stepsTotal?: number;
1497
1564
  runningSteps?: number;
1498
1565
  completedSteps?: number;
@@ -1570,7 +1637,6 @@ export interface ForegroundResumeRun {
1570
1637
  /** Originating parent session. Detached exits can outlive the active session. */
1571
1638
  sessionId?: string;
1572
1639
  updatedAt: number;
1573
- checkpoint?: ChainCheckpointState;
1574
1640
  children: ForegroundResumeChild[];
1575
1641
  }
1576
1642
 
@@ -1663,6 +1729,8 @@ export interface ActiveAsyncCapacitySnapshot {
1663
1729
  export interface SubagentState {
1664
1730
  baseCwd: string;
1665
1731
  currentSessionId: string | null;
1732
+ /** Reload-stable identity for this parent Pi process/window. */
1733
+ completionOwnerId?: string;
1666
1734
  /** Runtime-owned artifact resolution inputs used by Fleet transcript targeting. */
1667
1735
  artifactDirPreference?: ArtifactDirPreference;
1668
1736
  /** Runtime authority snapshot used by optional inspector controls. */
@@ -1811,6 +1879,8 @@ export interface RunSyncOptions {
1811
1879
  nestedRoute?: NestedRouteInfo;
1812
1880
  /** Override the agent's default model (format: "provider/id" or just "id") */
1813
1881
  modelOverride?: string;
1882
+ /** The override came from the running parent session, not configuration. */
1883
+ modelOverrideFromParent?: boolean;
1814
1884
  /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
1815
1885
  llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
1816
1886
  /** Override the agent's default thinking level for this run */
@@ -1915,6 +1985,8 @@ export interface MainWindowRendererConfig {
1915
1985
 
1916
1986
  export interface ExtensionConfig {
1917
1987
  asyncByDefault?: boolean;
1988
+ /** Set the context for launches that omit an explicit context. */
1989
+ defaultSubagentContext?: "fresh" | "fork";
1918
1990
  /** Optional shortcut that detaches the active foreground single-subagent run. */
1919
1991
  foregroundDetachShortcut?: string;
1920
1992
  /** Show the Claude Code-style navigable fleet. Defaults to true. */
@@ -1925,10 +1997,8 @@ export interface ExtensionConfig {
1925
1997
  fleetKeybindings?: FleetKeybindingsConfig;
1926
1998
  /** Show the under-editor async runs widget. Defaults to true, including when FleetView is enabled. */
1927
1999
  asyncWidget?: boolean;
1928
- /** Tool description variant registered for the parent-facing subagent tool. Defaults to full. */
2000
+ /** Tool description variant registered for the parent-facing subagent tool. Defaults to split metadata. */
1929
2001
  toolDescriptionMode?: ToolDescriptionMode;
1930
- /** Include legacy append-step and checkpoint controls in the registered tool schema. Defaults to false. */
1931
- legacyChainControls?: boolean;
1932
2002
  /** Inline chat rendering for the subagent tool. Defaults to rich. */
1933
2003
  inlineToolDisplay?: InlineToolDisplay;
1934
2004
  /** Density controls for the main chat subagent call/result renderer. */
@@ -1984,6 +2054,13 @@ export interface ExtensionConfig {
1984
2054
  /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
1985
2055
  artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
1986
2056
  intercomBridge?: IntercomBridgeConfig;
2057
+ /** Control how slow result-index scans are logged. Defaults to \"all\".
2058
+ * - \"all\": log every slow scan, including scans that find nothing.
2059
+ * - \"activity\": log only slow scans that found or scheduled work. Silences
2060
+ * the periodic healthy rescan that inspects zero files while no async runs
2061
+ * are pending, which otherwise spams the session transcript.
2062
+ * - \"off\": never log slow result-index scans. */
2063
+ resultScanLogging?: "all" | "activity" | "off";
1987
2064
  proactiveSkillSubagents?: ProactiveSkillSubagentsConfig | false;
1988
2065
  scheduledRuns?: ScheduledRunsConfig;
1989
2066
  /** Durable mission behavior. Missions are automatic by default; set enabled:false to disable auto-create. Explicit mission actions/fields still work. */
@@ -2067,7 +2144,10 @@ export function resolveTempScopeId(options?: {
2067
2144
 
2068
2145
  const MAX_PARALLEL = 8;
2069
2146
  export const MAX_CONCURRENCY = 4;
2070
- export const TEMP_ROOT_DIR = path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
2147
+ const configuredTempRoot = process.env.PI_SUBAGENTS_TEMP_ROOT?.trim();
2148
+ export const TEMP_ROOT_DIR = configuredTempRoot
2149
+ ? path.resolve(configuredTempRoot)
2150
+ : path.join(os.tmpdir(), `pi-subagents-${resolveTempScopeId()}`);
2071
2151
  export const RESULTS_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-results");
2072
2152
  export const ASYNC_DIR = path.join(TEMP_ROOT_DIR, "async-subagent-runs");
2073
2153
  export const CHAIN_RUNS_DIR = path.join(TEMP_ROOT_DIR, "chain-runs");
@@ -2090,7 +2170,7 @@ export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
2090
2170
  export const POLL_INTERVAL_MS = 250;
2091
2171
  export const MAX_WIDGET_JOBS = 4;
2092
2172
  export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
2093
- 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", "append-step", "approve-checkpoint", "reject-checkpoint", "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;
2173
+ 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;
2094
2174
 
2095
2175
  export const DEFAULT_FORK_PREAMBLE =
2096
2176
  "You are a delegated subagent running from a fork of the parent session. " +
@@ -102,6 +102,7 @@ export function getAgentDir(): string {
102
102
  }
103
103
 
104
104
  const statusCache = new Map<string, { mtime: number; ctime: number; size: number; ino: number; status: AsyncStatus }>();
105
+ const MAX_STATUS_CACHE_ENTRIES = 512;
105
106
 
106
107
  export function pruneStatusCacheForAsyncRoot(asyncDirRoot: string, runIds: Iterable<string>): number {
107
108
  const root = path.resolve(asyncDirRoot);
@@ -163,6 +164,8 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
163
164
  && cached.size === stat.size
164
165
  && cached.ino === stat.ino
165
166
  ) {
167
+ statusCache.delete(statusPath);
168
+ statusCache.set(statusPath, cached);
166
169
  return cached.status;
167
170
  }
168
171
 
@@ -195,6 +198,11 @@ export function readStatus(asyncDir: string): AsyncStatus | null {
195
198
  ino: stat.ino,
196
199
  status,
197
200
  });
201
+ while (statusCache.size > MAX_STATUS_CACHE_ENTRIES) {
202
+ const oldest = statusCache.keys().next().value as string | undefined;
203
+ if (oldest === undefined) break;
204
+ statusCache.delete(oldest);
205
+ }
198
206
  return status;
199
207
  }
200
208
 
@@ -0,0 +1,10 @@
1
+ export type FileWatchPurpose =
2
+ | "result-delivery"
3
+ | "supervisor-channel"
4
+ | "async-job-tracker"
5
+ | "runner-control-inbox"
6
+ | "child-steering-inbox";
7
+
8
+ export function shouldUseNativeFsWatch(_purpose: FileWatchPurpose, platform: NodeJS.Platform = process.platform): boolean {
9
+ return platform !== "darwin";
10
+ }
@@ -39,6 +39,7 @@ interface EventBus {
39
39
 
40
40
  interface SlashBridgeOptions {
41
41
  events: EventBus;
42
+ asyncByDefault: boolean;
42
43
  getContext: () => ExtensionContext | null;
43
44
  execute: (
44
45
  id: string,
@@ -79,7 +80,7 @@ export function registerSlashSubagentBridge(options: SlashBridgeOptions): {
79
80
  const request = data as Partial<SlashSubagentRequest>;
80
81
  if (typeof request.requestId !== "string" || !request.params) return;
81
82
  const { requestId } = request as SlashSubagentRequest;
82
- const normalized = normalizePublicSubagentExecution((request as SlashSubagentRequest).params);
83
+ const normalized = normalizePublicSubagentExecution((request as SlashSubagentRequest).params, { asyncByDefault: options.asyncByDefault });
83
84
  if (!normalized.ok) {
84
85
  options.events.emit(SLASH_SUBAGENT_RESPONSE_EVENT, {
85
86
  requestId,
@@ -3,7 +3,8 @@ import * as fs from "node:fs";
3
3
  import * as path from "node:path";
4
4
  import { keyText, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
5
5
  import { Key, matchesKey, truncateToWidth, type Component, type KeyId, type TUI } from "@earendil-works/pi-tui";
6
- import { BUILTIN_AGENT_NAMES, discoverAgents } from "../agents/agents.ts";
6
+ import { BUILTIN_AGENT_NAMES, discoverAgents, discoverAgentsAll, findBlockingAgentDiagnostic, resolveAgentName, type AgentConfig, type AgentDiscoveryDiagnostic, type AgentScope } from "../agents/agents.ts";
7
+ import { listRuntimeAgentConfigs, mergeRuntimeAgents } from "../agents/runtime-agent-registry.ts";
7
8
  import { resolveExistingReadPaths } from "../shared/settings.ts";
8
9
  import {
9
10
  DEFAULT_PROVIDER_MODELS_MAX_AGE_DAYS,
@@ -18,6 +19,7 @@ import type { SubagentParamsLike } from "../runs/foreground/subagent-executor.ts
18
19
  import { findModelInfo, toModelInfo } from "../shared/model-info.ts";
19
20
  import { formatTokens, shortenPath } from "../shared/formatters.ts";
20
21
  import { listAsyncRuns, formatAsyncRunProgressLabel, type AsyncRunSummary } from "../runs/background/async-status.ts";
22
+ import { encodeInspectReply, handleInspectRpcArgs, INSPECT_WIDGET_KEY } from "../runs/background/inspect-rpc.ts";
21
23
  import { listScheduledRunSummaries } from "../runs/background/scheduled-runs.ts";
22
24
  import { SUBAGENT_FANOUT_CHILD_ENV } from "../runs/shared/pi-args.ts";
23
25
  import type { SlashSubagentResponse, SlashSubagentUpdate } from "./slash-bridge.ts";
@@ -106,9 +108,22 @@ const extractExecutionFlags = (rawArgs: string): { args: string; bg: boolean; fo
106
108
  return { args, bg, fork };
107
109
  };
108
110
 
109
- const makeAgentCompletions = (state: SubagentState) => (prefix: string) => {
111
+ function discoverSlashAgents(pi: ExtensionAPI, cwd: string, scope: AgentScope): { agents: AgentConfig[]; agentDiagnostics?: AgentDiscoveryDiagnostic[] } {
112
+ const discovered = discoverAgents(cwd, scope);
113
+ if (listRuntimeAgentConfigs(pi).length === 0) return discovered;
114
+ const all = discoverAgentsAll(cwd);
115
+ const configuredAgents: AgentConfig[] = [
116
+ ...all.builtin,
117
+ ...all.package,
118
+ ...(scope !== "project" ? all.user : []),
119
+ ...(scope !== "user" ? all.project : []),
120
+ ];
121
+ return mergeRuntimeAgents(pi, discovered, configuredAgents);
122
+ }
123
+
124
+ const makeAgentCompletions = (pi: ExtensionAPI, state: SubagentState) => (prefix: string) => {
110
125
  if (!state.baseCwd || prefix.includes(" ")) return null;
111
- return discoverAgents(state.baseCwd, "both").agents
126
+ return discoverSlashAgents(pi, state.baseCwd, "both").agents
112
127
  .filter((agent) => agent.name.startsWith(prefix))
113
128
  .map((agent) => ({ value: agent.name, label: agent.name }));
114
129
  };
@@ -661,7 +676,7 @@ export function registerSlashCommands(
661
676
 
662
677
  pi.registerCommand("run", {
663
678
  description: "Run one subagent through workflowScript: /run agent[output=file] [task] [--bg] [--fork]",
664
- getArgumentCompletions: makeAgentCompletions(state),
679
+ getArgumentCompletions: makeAgentCompletions(pi, state),
665
680
  handler: async (args, ctx) => {
666
681
  const { args: cleanedArgs, bg, fork } = extractExecutionFlags(args);
667
682
  const input = cleanedArgs.trim();
@@ -671,8 +686,16 @@ export function registerSlashCommands(
671
686
  const task = firstSpace === -1 ? "" : input.slice(firstSpace + 1).trim();
672
687
 
673
688
  if (!state.baseCwd) { ctx.ui.notify("Subagent session cwd is not initialized yet", "error"); return; }
674
- const agents = discoverAgents(state.baseCwd, "both").agents;
675
- if (!agents.find((a) => a.name === agentName)) { ctx.ui.notify(`Unknown agent: ${agentName}`, "error"); return; }
689
+ const discovered = discoverSlashAgents(pi, state.baseCwd, "both");
690
+ const resolvedAgent = resolveAgentName(agentName, discovered.agents);
691
+ const candidates = resolvedAgent.error
692
+ ? discovered.agents.filter((agent) => resolveAgentName(agentName, [agent]).agent)
693
+ : resolvedAgent.agent;
694
+ const diagnostic = findBlockingAgentDiagnostic(agentName, candidates, discovered.agentDiagnostics);
695
+ if (diagnostic || resolvedAgent.error || !resolvedAgent.agent) {
696
+ ctx.ui.notify(diagnostic ? `Agent '${agentName}' has invalid configuration: ${diagnostic.error}` : resolvedAgent.error ?? `Unknown agent: ${agentName}`, "error");
697
+ return;
698
+ }
676
699
 
677
700
  let finalTask = task;
678
701
  if (inline.reads && Array.isArray(inline.reads) && inline.reads.length > 0) {
@@ -703,6 +726,23 @@ export function registerSlashCommands(
703
726
  },
704
727
  });
705
728
 
729
+ pi.registerCommand("subagents-inspect-rpc", {
730
+ description: "Host integration bridge: answer an async child inspection request with a correlated widget payload (no model turn)",
731
+ handler: async (args, ctx) => {
732
+ if (ctx.mode === "tui") {
733
+ ctx.ui.notify("Inspection replies are emitted only on RPC surfaces. Use /subagents or subagent({ action: \"status\", view: \"transcript\" }) interactively.", "info");
734
+ return;
735
+ }
736
+ if (!ctx.hasUI) return;
737
+ const reply = handleInspectRpcArgs(args, { state });
738
+ // Emit-then-retract in one handler: stdio delivers the two widget
739
+ // updates in order, the host buffers the payload by requestId, and
740
+ // the dedicated key never accumulates visible state.
741
+ ctx.ui.setWidget(INSPECT_WIDGET_KEY, encodeInspectReply(reply));
742
+ ctx.ui.setWidget(INSPECT_WIDGET_KEY, undefined);
743
+ },
744
+ });
745
+
706
746
  pi.registerCommand("subagents-guide", {
707
747
  description: "Show a packaged subagents guide topic",
708
748
  getArgumentCompletions: (prefix) => prefix.includes(" ") ? null : SUBAGENT_GUIDE_TOPICS
@@ -720,7 +760,7 @@ export function registerSlashCommands(
720
760
 
721
761
  pi.registerCommand("subagents-refine", {
722
762
  description: "Generate a bounded project-local refinement overlay for one subagent",
723
- getArgumentCompletions: makeAgentCompletions(state),
763
+ getArgumentCompletions: makeAgentCompletions(pi, state),
724
764
  handler: async (args, ctx) => {
725
765
  const parts = args.trim().split(/\s+/).filter(Boolean);
726
766
  if (parts.length !== 1) {
@@ -82,7 +82,7 @@ function buildParallelInitialResult(params: SubagentParamsLike): AgentToolResult
82
82
  details: {
83
83
  mode: "parallel",
84
84
  ...(params.async ? { background: true } : {}),
85
- ...(params.context ? { context: params.context } : {}),
85
+ ...(params.context === "fresh" || params.context === "fork" ? { context: params.context } : {}),
86
86
  results: tasks.map((task, index) => createPlaceholderResult(task.agent, task.task, "running", index)),
87
87
  progress: tasks.map((task, index) => ({
88
88
  index,
@@ -138,7 +138,7 @@ function buildChainInitialResult(params: SubagentParamsLike): AgentToolResult<De
138
138
  details: {
139
139
  mode: "chain",
140
140
  ...(params.async ? { background: true } : {}),
141
- ...(params.context ? { context: params.context } : {}),
141
+ ...(params.context === "fresh" || params.context === "fork" ? { context: params.context } : {}),
142
142
  results,
143
143
  progress: results.map((result, index) => ({
144
144
  index,
@@ -167,7 +167,7 @@ function buildSingleInitialResult(params: SubagentParamsLike): AgentToolResult<D
167
167
  details: {
168
168
  mode: "single",
169
169
  ...(params.async ? { background: true } : {}),
170
- ...(params.context ? { context: params.context } : {}),
170
+ ...(params.context === "fresh" || params.context === "fork" ? { context: params.context } : {}),
171
171
  results: [createPlaceholderResult(agent, task, "running", 0)],
172
172
  progress: [{
173
173
  index: 0,