@xzzpig/pi-subagents 0.6.0 → 0.8.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 (98) hide show
  1. package/CHANGELOG.md +45 -4
  2. package/README.md +1 -1
  3. package/agents/reviewer.md +12 -2
  4. package/docs/agents.md +4 -4
  5. package/docs/configuration.md +6 -6
  6. package/docs/extension-api.md +14 -4
  7. package/docs/models.md +47 -6
  8. package/docs/observability.md +14 -3
  9. package/docs/tool-reference.md +21 -6
  10. package/docs/workflows.md +7 -1
  11. package/index.ts +10 -1
  12. package/node_modules/@xzzpig/pi-components/CHANGELOG.md +102 -0
  13. package/node_modules/@xzzpig/pi-components/LICENSE +21 -0
  14. package/node_modules/@xzzpig/pi-components/README.md +59 -0
  15. package/node_modules/@xzzpig/pi-components/dist/index.d.ts +1 -0
  16. package/node_modules/@xzzpig/pi-components/dist/index.js +1 -0
  17. package/node_modules/@xzzpig/pi-components/dist/src/transcript.d.ts +345 -0
  18. package/node_modules/@xzzpig/pi-components/dist/src/transcript.js +1169 -0
  19. package/node_modules/@xzzpig/pi-components/package.json +49 -0
  20. package/node_modules/@xzzpig/pi-components/src/transcript.ts +1785 -0
  21. package/package.json +7 -3
  22. package/prompts/council.md +19 -7
  23. package/prompts/parallel-review.md +5 -1
  24. package/prompts/review-loop.md +9 -5
  25. package/skills/council-mode/SKILL.md +50 -26
  26. package/skills/pi-subagents/SKILL.md +5 -1
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +16 -1
  28. package/skills/pi-subagents/references/execution-controls.md +13 -4
  29. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -3
  30. package/skills/pi-subagents/references/prompting-and-roles.md +14 -7
  31. package/src/agents/agent-management.ts +115 -14
  32. package/src/agents/agent-serializer.ts +4 -2
  33. package/src/agents/agents.ts +226 -48
  34. package/src/api/external-job-provider.ts +10 -1
  35. package/src/api/preflight.ts +52 -19
  36. package/src/api/project-panes.ts +2 -0
  37. package/src/extension/doctor.ts +10 -0
  38. package/src/extension/fanout-child.ts +3 -2
  39. package/src/extension/index.ts +24 -4
  40. package/src/extension/public-execution.ts +12 -9
  41. package/src/extension/rpc.ts +77 -3
  42. package/src/extension/schemas.ts +7 -1
  43. package/src/extension/tool-description.ts +9 -6
  44. package/src/extension/tool-result.ts +19 -0
  45. package/src/inspectors/herdr/client.ts +3 -3
  46. package/src/inspectors/herdr/focus.ts +55 -0
  47. package/src/inspectors/herdr/project-panes.ts +228 -44
  48. package/src/integrations/herdr-status.ts +26 -4
  49. package/src/runs/background/async-execution.ts +146 -17
  50. package/src/runs/background/async-job-tracker.ts +33 -14
  51. package/src/runs/background/async-resume.ts +23 -2
  52. package/src/runs/background/async-retention.ts +1 -1
  53. package/src/runs/background/async-status.ts +10 -0
  54. package/src/runs/background/chain-root-attachment.ts +5 -0
  55. package/src/runs/background/control-channel.ts +98 -10
  56. package/src/runs/background/notify.ts +62 -1
  57. package/src/runs/background/result-watcher.ts +4 -3
  58. package/src/runs/background/run-status.ts +15 -1
  59. package/src/runs/background/stale-run-reconciler.ts +3 -0
  60. package/src/runs/background/subagent-runner.ts +333 -48
  61. package/src/runs/background/wait-completions.ts +2 -0
  62. package/src/runs/background/wait-tool.ts +4 -3
  63. package/src/runs/foreground/async-stop-action.ts +23 -2
  64. package/src/runs/foreground/execution.ts +148 -13
  65. package/src/runs/foreground/foreground-history.ts +3 -2
  66. package/src/runs/foreground/subagent-executor.ts +417 -50
  67. package/src/runs/foreground/workflow-detach-reconcile.ts +18 -6
  68. package/src/runs/shared/acceptance.ts +11 -5
  69. package/src/runs/shared/agent-contract.ts +1 -1
  70. package/src/runs/shared/child-identity.ts +36 -0
  71. package/src/runs/shared/completion-guard.ts +52 -2
  72. package/src/runs/shared/dynamic-fanout.ts +1 -1
  73. package/src/runs/shared/extension-bindings.ts +78 -0
  74. package/src/runs/shared/external-cli-runner.ts +2 -0
  75. package/src/runs/shared/external-job-bridge.ts +53 -37
  76. package/src/runs/shared/external-job-runner.ts +126 -23
  77. package/src/runs/shared/fast-mode-extension.ts +10 -0
  78. package/src/runs/shared/model-exclusions.ts +2 -1
  79. package/src/runs/shared/model-fallback.ts +48 -22
  80. package/src/runs/shared/model-scope.ts +106 -39
  81. package/src/runs/shared/mutation-evidence.ts +145 -0
  82. package/src/runs/shared/orca-progress-tabs.ts +71 -9
  83. package/src/runs/shared/parallel-utils.ts +15 -0
  84. package/src/runs/shared/pi-args.ts +78 -1
  85. package/src/runs/shared/structured-output.ts +18 -4
  86. package/src/runs/shared/subagent-prompt-runtime.ts +48 -15
  87. package/src/runs/shared/tool-availability.ts +1 -3
  88. package/src/shared/launch-contract.ts +12 -5
  89. package/src/shared/settings.ts +6 -1
  90. package/src/shared/thinking-ceiling.ts +52 -0
  91. package/src/shared/types.ts +121 -5
  92. package/src/tui/fleet-native-transcript.ts +374 -0
  93. package/src/tui/fleet-status.ts +66 -13
  94. package/src/tui/fleet-transcript.ts +47 -1
  95. package/src/tui/fleet.ts +96 -24
  96. package/src/tui/render.ts +5 -4
  97. package/src/watchdog/permission-arbiter.ts +59 -52
  98. package/src/workflows/scripted-workflow.ts +156 -12
@@ -33,6 +33,8 @@ export interface HerdrStatusBridgeOptions {
33
33
  env?: Record<string, string | undefined>;
34
34
  /** Current authoritative active-run projection, used before TTL refresh. */
35
35
  getRuns?: () => Iterable<HerdrStatusRun>;
36
+ /** Current project panes opened by this Pi session. Views are excluded. */
37
+ getProjectPaneCount?: () => number;
36
38
  runHerdr: (args: readonly string[]) => void | Promise<void>;
37
39
  ttlMs?: number;
38
40
  refreshMs?: number;
@@ -109,12 +111,27 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
109
111
  let drainPromise = Promise.resolve();
110
112
  let refreshTimer: ReturnType<typeof setInterval> | undefined;
111
113
 
112
- const label = (): string => {
113
- const agents = [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
114
+ const activeAgentNames = (): string[] => [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
115
+ const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) => total + Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0)), 0);
116
+
117
+ const label = (includeAttention = false): string => {
118
+ const agents = activeAgentNames();
119
+ const activeCount = activeSubagentCount();
114
120
  const who = agents.length > 0
115
121
  ? ` (${agents.slice(0, 3).join(", ")}${agents.length > 3 ? ", …" : ""})`
116
122
  : "";
117
- return `⏳ ${runs.size} subagent${runs.size === 1 ? "" : "s"}${who}`;
123
+ const panes = Math.max(0, options.getProjectPaneCount?.() ?? 0);
124
+ const paneText = panes > 0 ? ` · ${panes} pane${panes === 1 ? "" : "s"}` : "";
125
+ const attention = includeAttention && attentionLabels.size > 0 ? " ⚠" : "";
126
+ return `⏳ ${activeCount} subagent${activeCount === 1 ? "" : "s"}${who}${paneText}${attention}`;
127
+ };
128
+
129
+ const titleSuffix = (): string | undefined => {
130
+ if (runs.size === 0) return undefined;
131
+ const agentNames = activeAgentNames();
132
+ const activeCount = activeSubagentCount();
133
+ const target = activeCount === 1 && agentNames.length === 1 ? agentNames[0]! : String(activeCount);
134
+ return `⏳${target}${attentionLabels.size > 0 ? "⚠" : ""}`;
118
135
  };
119
136
 
120
137
  const enqueue = (args: readonly string[]): void => {
@@ -150,11 +167,13 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
150
167
  "--applies-to-source", "herdr:pi",
151
168
  "--clear-state-labels",
152
169
  "--clear-token", "summary",
170
+ "--clear-token", "title-suffix",
153
171
  "--seq", seq,
154
172
  ]);
155
173
  return;
156
174
  }
157
- const text = label();
175
+ const text = label(true);
176
+ const suffix = titleSuffix();
158
177
  published = true;
159
178
  enqueue([
160
179
  "pane", "report-metadata", paneId,
@@ -165,6 +184,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
165
184
  "--state-label", `done=${text}`,
166
185
  "--state-label", `working=${text}`,
167
186
  "--token", `summary=${text}`,
187
+ ...(suffix ? ["--token", `title-suffix=${suffix}`] : []),
168
188
  "--ttl-ms", String(ttlMs),
169
189
  "--seq", seq,
170
190
  ]);
@@ -221,6 +241,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
221
241
  const clearAttention = (): void => {
222
242
  attentionLabels.clear();
223
243
  syncBlocked();
244
+ publish();
224
245
  };
225
246
 
226
247
  const raiseAttention = (runId: string, labelText: string): void => {
@@ -228,6 +249,7 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
228
249
  acknowledgedAttention.delete(runId);
229
250
  attentionLabels.set(runId, labelText);
230
251
  syncBlocked();
252
+ publish();
231
253
  };
232
254
 
233
255
  const replaceRuns = (nextRuns: Iterable<HerdrStatusRun>): void => {
@@ -26,14 +26,16 @@ import { buildAgentMemoryInjection } from "../../agents/agent-memory.ts";
26
26
  import { PI_CODING_AGENT_PACKAGE_ROOT_ENV, PROMPT_REDACTED, resolveChildCwd } from "../../shared/utils.ts";
27
27
  import { buildModelCandidates, inheritsParentModel, resolveEffectiveSubagentModel, resolveModelCandidate, resolveSubagentModelOverride, type AvailableModelInfo, type ParentModel } from "../shared/model-fallback.ts";
28
28
  import { resolveToolTimeoutMs, toolTimeoutFromEnv } from "../shared/tool-timeout.ts";
29
- import type { ModelScopeConfig } from "../shared/model-scope.ts";
29
+ import { resolveModelScopesForAgent, type ModelScopeConfig } from "../shared/model-scope.ts";
30
30
  import { resolveEffectiveThinking } from "../../shared/model-info.ts";
31
+ import { assertThinkingWithinCeiling, decodeThinkingCeiling, intersectThinkingCeilings, SUBAGENT_THINKING_CEILING_ENV, type ThinkingLevel } from "../../shared/thinking-ceiling.ts";
31
32
  import { resolveExpectedWorktreeAgentCwd } from "../shared/worktree.ts";
32
33
  import { buildWorkflowGraphSnapshot } from "../shared/workflow-graph.ts";
33
34
  import { ChainOutputValidationError, validateChainOutputBindings } from "../shared/chain-outputs.ts";
34
35
  import { createStructuredOutputRuntime } from "../shared/structured-output.ts";
35
36
  import { resolveEffectiveAcceptance, validateAcceptanceInput, validateExecutionAcceptance } from "../shared/acceptance.ts";
36
37
  import { createRunFanoutBudget, writeRunFanoutBudgetDescriptor } from "../shared/run-fanout-budget.ts";
38
+ import { validateImplementationToolContract } from "../shared/completion-guard.ts";
37
39
  import {
38
40
  type AcceptanceInput,
39
41
  type AgentContract,
@@ -72,6 +74,7 @@ import { SUBAGENT_PROCESS_TERMINAL_EVENT } from "../../shared/types.ts";
72
74
  import { assertAgentAllowedByCapabilityCeiling, decodeSubagentCapabilityCeiling, intersectSubagentCapabilityCeilings, resolveCurrentSubagentCapabilityCeiling, SUBAGENT_CAPABILITY_CEILING_ENV, type ResolvedSubagentCapabilityCeiling } from "../shared/capability-ceiling.ts";
73
75
  import { agentDefinitionDigest, launchBindingDigest } from "../../shared/launch-contract.ts";
74
76
  import { resolvePermissionRules, type PermissionConfig } from "../shared/permissions.ts";
77
+ import { normalizeExtensionBindings, omitExtensionBindingsEnv, type ExtensionBindings } from "../shared/extension-bindings.ts";
75
78
 
76
79
  const require = createRequire(import.meta.url);
77
80
  const piPackageRoot = resolvePiPackageRoot();
@@ -173,6 +176,7 @@ interface AsyncChainParams {
173
176
  childIntercomTarget?: (agent: string, index: number) => string | undefined;
174
177
  nestedRoute?: NestedRouteInfo;
175
178
  acceptance?: AcceptanceInput;
179
+ fast?: boolean;
176
180
  timeoutMs?: number;
177
181
  turnBudget?: ResolvedTurnBudget;
178
182
  toolBudget?: ResolvedToolBudget;
@@ -187,6 +191,7 @@ interface AsyncChainParams {
187
191
  /** Global cap on simultaneously-running subagent tasks within the async run. */
188
192
  globalConcurrencyLimit?: number;
189
193
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
194
+ thinkingCeiling?: ThinkingLevel;
190
195
  runFanoutBudget?: RunFanoutBudgetDescriptor;
191
196
  parentWorkflowRunId?: string;
192
197
  workflowKey?: string;
@@ -221,6 +226,7 @@ interface AsyncSingleParams {
221
226
  structuredOutputSchema?: JsonSchemaObject;
222
227
  modelOverride?: string;
223
228
  modelOverrideFromParent?: boolean;
229
+ fast?: boolean;
224
230
  thinkingOverride?: AgentConfig["thinking"];
225
231
  availableModels?: AvailableModelInfo[];
226
232
  maxSubagentDepth: number;
@@ -249,10 +255,20 @@ interface AsyncSingleParams {
249
255
  toolTimeoutMsEnv?: string | undefined;
250
256
  allowZeroToolBudget?: boolean;
251
257
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
258
+ thinkingCeiling?: ThinkingLevel;
252
259
  runFanoutBudget?: RunFanoutBudgetDescriptor;
253
260
  parentWorkflowRunId?: string;
254
261
  workflowKey?: string;
262
+ workflowAwaitAsync?: boolean;
255
263
  activeAsyncCapacity?: ActiveAsyncCapacityHandle;
264
+ externalJobFollowUp?: {
265
+ sourceRunId: string;
266
+ sourceStepIndex: number;
267
+ parentProviderJobId: string;
268
+ requestId: string;
269
+ requestDigest: string;
270
+ };
271
+ extensionBindings?: ExtensionBindings;
256
272
  }
257
273
 
258
274
  interface AsyncExecutionResult {
@@ -283,6 +299,7 @@ export interface AsyncRunnerStepBuildParams {
283
299
  asyncDir: string;
284
300
  outputBaseDir?: string;
285
301
  validateOutputBindings?: boolean;
302
+ fast?: boolean;
286
303
  toolBudget?: ResolvedToolBudget;
287
304
  configToolBudget?: ResolvedToolBudget;
288
305
  /** Optional per-call hard toolTimeoutMs override from the subagent invocation. */
@@ -292,6 +309,7 @@ export interface AsyncRunnerStepBuildParams {
292
309
  /** PI_SUBAGENT_TOOL_TIMEOUT_MS override (lowest precedence). */
293
310
  toolTimeoutMsEnv?: string | undefined;
294
311
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
312
+ thinkingCeiling?: ThinkingLevel;
295
313
  }
296
314
 
297
315
  export type AsyncRunnerStepBuildResult =
@@ -493,7 +511,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, onProcessTerminal
493
511
  const cfgPath = getAsyncConfigPath(suffix);
494
512
  const runnerProcessInstanceId = randomUUID();
495
513
  const launchConfig = { ...cfg, runnerProcessInstanceId };
496
- fs.writeFileSync(cfgPath, JSON.stringify(launchConfig));
514
+ writePrivateAtomicJson(cfgPath, launchConfig);
497
515
  const runner = path.join(path.dirname(fileURLToPath(import.meta.url)), "subagent-runner.ts");
498
516
  const nodeCommand = resolveNodeExecutable();
499
517
  const launchForStartup = launchConfig as typeof launchConfig & { asyncDir?: unknown; id?: unknown; sessionId?: unknown; completionOwnerId?: unknown; revivalLease?: unknown };
@@ -525,7 +543,7 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, onProcessTerminal
525
543
  stdio: ["ignore", stdoutFd ?? "ignore", stderrFd ?? "ignore"],
526
544
  windowsHide: true,
527
545
  env: {
528
- ...process.env,
546
+ ...omitExtensionBindingsEnv(process.env),
529
547
  ...(piPackageRoot ? { [PI_CODING_AGENT_PACKAGE_ROOT_ENV]: piPackageRoot } : {}),
530
548
  },
531
549
  });
@@ -714,6 +732,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
714
732
  ...(s.progress !== undefined ? { progress: s.progress } : {}),
715
733
  ...(stepSkillInput !== undefined ? { skills: stepSkillInput } : {}),
716
734
  ...(s.model !== undefined ? { model: s.model } : {}),
735
+ ...(s.fast !== undefined ? { fast: s.fast } : {}),
717
736
  };
718
737
  };
719
738
  const buildSeqStep = (s: SequentialStep, sessionFile?: string, behaviorCwd?: string, progressPrecreated = false, resolvedBehavior?: ResolvedStepBehavior, flatIndex?: number, parallelOutputNamespace?: { stepIndex: number; taskIndex?: number }, runFanoutPath?: string) => {
@@ -726,6 +745,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
726
745
  if (s.outputSchema !== undefined) unsupported.push("structured output");
727
746
  if (s.acceptance !== undefined || params.agentContract !== undefined || s.agentContract !== undefined) unsupported.push("acceptance/agent contract");
728
747
  if (s.toolBudget !== undefined || params.toolBudget !== undefined || a.toolBudget !== undefined || params.configToolBudget !== undefined) unsupported.push("tool budget");
748
+ if ((s.fast ?? params.fast ?? a.fast) === true) unsupported.push("fast mode");
729
749
  if (params.contextForAgent?.(s.agent) === "fork") unsupported.push("fork context");
730
750
  if (unsupported.length > 0) throw new AsyncStartValidationError(`Agent '${a.name}' uses runner.type='${externalRunnerType}' and does not support: ${unsupported.join(", ")}.`);
731
751
  }
@@ -791,18 +811,48 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
791
811
  const taskText = `${readInstructions.prefix}${taskTemplate}${progressInstructions.suffix}`;
792
812
  const task = namespaceOutputPath ? taskText : injectSingleOutputInstruction(taskText, outputPath, a);
793
813
 
814
+ const modelScopes = resolveModelScopesForAgent(ctx.modelScope, a.name, ctx.currentModel);
815
+ const primaryModelFromParent = inheritsParentModel(s.model, a.model, ctx.currentModel);
794
816
  const primaryModel = externalRunner ? undefined : resolveEffectiveSubagentModel(
795
817
  s.model,
796
818
  a.model,
797
819
  ctx.currentModel,
798
820
  availableModels,
799
- ctx.currentModelProvider,
800
- { scope: ctx.modelScope },
821
+ a.modelProvider ?? ctx.currentModelProvider,
822
+ { scope: modelScopes },
801
823
  );
802
824
  const thinkingOverride = flatIndex === undefined ? undefined : thinkingOverridesByFlatIndex?.[flatIndex];
803
825
  const effectiveThinking = externalRunner ? undefined : thinkingOverride ?? a.thinking;
804
826
  const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinking, thinkingOverride !== undefined);
827
+ const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
828
+ params.thinkingCeiling,
829
+ a.maxThinking,
830
+ decodeThinkingCeiling(process.env[SUBAGENT_THINKING_CEILING_ENV]),
831
+ );
832
+ if (!externalRunner) {
833
+ try {
834
+ assertThinkingWithinCeiling({ model, configThinking: effectiveThinking, ceiling: thinkingCeiling, agent: a.name, runId: id });
835
+ } catch (error) {
836
+ throw new AsyncStartValidationError(error instanceof Error ? error.message : String(error));
837
+ }
838
+ }
805
839
  const agentContract = s.agentContract ?? params.agentContract;
840
+ const permissionRules = resolvePermissionRules(ctx.permissions, a.permissions);
841
+ const modelCandidates = externalRunner ? [] : buildModelCandidates(primaryModel, a.fallbackModels, availableModels, a.modelProvider ?? ctx.currentModelProvider, {
842
+ scope: modelScopes,
843
+ primaryModelFromParent,
844
+ }).flatMap((candidate) => {
845
+ const resolved = applyThinkingSuffix(candidate, effectiveThinking, thinkingOverride !== undefined);
846
+ return resolved ? [resolved] : [];
847
+ });
848
+ if (!externalRunner) {
849
+ try {
850
+ for (const candidate of modelCandidates) assertThinkingWithinCeiling({ model: candidate, configThinking: effectiveThinking, ceiling: thinkingCeiling, agent: a.name, runId: id });
851
+ } catch (error) {
852
+ throw new AsyncStartValidationError(error instanceof Error ? error.message : String(error));
853
+ }
854
+ }
855
+ const fast = s.fast ?? params.fast ?? a.fast;
806
856
  const toolPlan = resolvePiLaunchToolPlan({
807
857
  tools: a.tools,
808
858
  extensions: a.extensions,
@@ -811,15 +861,32 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
811
861
  cwd: stepCwd,
812
862
  requireReadTool: Boolean(resolvedSkills.length),
813
863
  structuredOutput: Boolean(s.outputSchema),
864
+ fast,
865
+ model,
866
+ modelCandidates,
814
867
  capabilityCeiling: params.capabilityCeiling,
815
868
  inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
816
869
  agentName: a.name,
870
+ permissionRules,
817
871
  });
818
872
  const launchResolvedExtensions = externalRunner ? undefined : projectLaunchResolvedChildExtensions(toolPlan);
819
- const permissionRules = resolvePermissionRules(ctx.permissions, a.permissions);
820
873
  if (externalRunner && permissionRules) {
821
874
  throw new AsyncStartValidationError(`Agent '${a.name}' uses runner.type='${externalRunnerType}', which cannot enforce native Pi child permission rules.`);
822
875
  }
876
+ if (!externalRunner) {
877
+ const contractTools = toolPlan.explicitToolAllowlist ? toolPlan.effectiveToolAllowlist : undefined;
878
+ const contractError = validateImplementationToolContract({
879
+ agent: a.name,
880
+ task,
881
+ tools: contractTools,
882
+ mcpDirectTools: toolPlan.effectiveMcpTools,
883
+ configuredExtensions: toolPlan.configuredExtensions,
884
+ requestedTools: toolPlan.requestedBuiltinTools,
885
+ acceptanceRole: a.acceptanceRole,
886
+ completionGuard: a.completionGuard,
887
+ });
888
+ if (contractError) throw new AsyncStartValidationError(contractError);
889
+ }
823
890
  return {
824
891
  parentSessionId: ctx.parentSessionId ?? ctx.currentSessionId,
825
892
  permissionRules,
@@ -836,14 +903,13 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
836
903
  structured: Boolean(s.outputSchema),
837
904
  cwd: stepCwd,
838
905
  model,
906
+ ...(fast !== undefined ? { fast } : {}),
839
907
  thinking: resolveEffectiveThinking(model, effectiveThinking),
908
+ ...(thinkingCeiling ? { thinkingCeiling } : {}),
840
909
  launchResolvedExtensions,
841
- modelCandidates: externalRunner ? undefined : buildModelCandidates(primaryModel, a.fallbackModels, availableModels, ctx.currentModelProvider, {
842
- scope: ctx.modelScope,
843
- primaryModelFromParent: inheritsParentModel(s.model, a.model, ctx.currentModel),
844
- }).map((candidate) =>
845
- applyThinkingSuffix(candidate, effectiveThinking, thinkingOverride !== undefined),
846
- ),
910
+ modelCandidates: externalRunner ? undefined : modelCandidates,
911
+ ...(primaryModelFromParent ? { skipPrimaryModelVerification: true } : {}),
912
+ ...(availableModels && availableModels.length > 0 ? { modelVerificationRegistry: availableModels } : {}),
847
913
  tools: a.tools,
848
914
  extensions: a.extensions,
849
915
  subagentOnlyExtensions: a.subagentOnlyExtensions,
@@ -876,7 +942,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
876
942
  acceptanceRole: a.acceptanceRole,
877
943
  ...(s.gateOn ? { gateOn: s.gateOn } : {}),
878
944
  ...(s.outputSchema ? { structuredOutputSchema: s.outputSchema } : {}),
879
- ...(s.outputSchema ? { structuredOutput: createStructuredOutputRuntime(s.outputSchema, path.join(asyncDir, "structured-output")) } : {}),
945
+ ...(s.outputSchema ? { structuredOutput: createStructuredOutputRuntime(s.outputSchema, path.join(asyncDir, "structured-output"), { captureAcceptanceReport: s.acceptance !== false }) } : {}),
880
946
  ...(resolvedToolBudget.budget ? { toolBudget: resolvedToolBudget.budget } : {}),
881
947
  ...(s.worktree ? { worktree: true } : {}),
882
948
  };
@@ -960,6 +1026,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
960
1026
  acceptanceRole: agent.acceptanceRole,
961
1027
  ...(s.agentContract ?? params.agentContract ? { agentContract: s.agentContract ?? params.agentContract } : {}),
962
1028
  ...(s.gateOn ? { gateOn: s.gateOn } : {}),
1029
+ ...(parallel.thinkingCeiling ? { thinkingCeiling: parallel.thinkingCeiling } : {}),
963
1030
  };
964
1031
  }
965
1032
  const sequential = s as SequentialStep;
@@ -1088,12 +1155,14 @@ export function executeAsyncChain(
1088
1155
  waitToolEnabled: params.waitToolEnabled,
1089
1156
  worktreeBaseDir,
1090
1157
  asyncDir,
1158
+ fast: params.fast,
1091
1159
  toolBudget: params.toolBudget,
1092
1160
  configToolBudget: params.configToolBudget,
1093
1161
  callToolTimeoutMs: params.callToolTimeoutMs,
1094
1162
  configToolTimeoutMs: params.configToolTimeoutMs,
1095
1163
  toolTimeoutMsEnv: params.toolTimeoutMsEnv ?? toolTimeoutFromEnv(),
1096
1164
  capabilityCeiling,
1165
+ thinkingCeiling: params.thinkingCeiling,
1097
1166
  });
1098
1167
  if ("error" in built) {
1099
1168
  try {
@@ -1335,6 +1404,12 @@ export function executeAsyncSingle(
1335
1404
  nestedRoute,
1336
1405
  } = params;
1337
1406
  const task = params.task ?? "";
1407
+ let extensionBindings: ExtensionBindings | undefined;
1408
+ try {
1409
+ extensionBindings = normalizeExtensionBindings(params.extensionBindings)?.value;
1410
+ } catch (error) {
1411
+ return formatAsyncStartError("single", error instanceof Error ? error.message : String(error));
1412
+ }
1338
1413
  const acceptanceErrors = validateAcceptanceInput(params.acceptance);
1339
1414
  if (acceptanceErrors.length > 0) return formatAsyncStartError("single", acceptanceErrors.join(" "));
1340
1415
  const externalRunner = agentConfig.runner?.type === "external-cli" || agentConfig.runner?.type === "external-job";
@@ -1343,6 +1418,7 @@ export function executeAsyncSingle(
1343
1418
  if (externalRunner) {
1344
1419
  const unsupported: string[] = [];
1345
1420
  if (params.modelOverride !== undefined) unsupported.push("model override");
1421
+ if ((params.fast ?? agentConfig.fast) === true) unsupported.push("fast mode");
1346
1422
  if (params.thinkingOverride !== undefined) unsupported.push("thinking override");
1347
1423
  if (params.structuredOutputSchema !== undefined) unsupported.push("structured output");
1348
1424
  if (params.acceptance !== undefined || params.agentContract !== undefined) unsupported.push("acceptance/agent contract");
@@ -1350,6 +1426,7 @@ export function executeAsyncSingle(
1350
1426
  if (params.context === "fork") unsupported.push("fork context");
1351
1427
  if ((params.skills?.length ?? 0) > 0) unsupported.push("skills");
1352
1428
  if (permissionRules) unsupported.push("native Pi child permissions");
1429
+ if (extensionBindings !== undefined) unsupported.push("extension bindings");
1353
1430
  if (unsupported.length > 0) return formatAsyncStartError("single", `Agent '${agentConfig.name}' uses runner.type='${externalRunnerType}' and does not support: ${unsupported.join(", ")}.`);
1354
1431
  }
1355
1432
  const capabilityCeiling = intersectSubagentCapabilityCeilings(params.capabilityCeiling ?? resolveCurrentSubagentCapabilityCeiling(ctx.currentSessionId), decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]));
@@ -1418,6 +1495,7 @@ export function executeAsyncSingle(
1418
1495
  ? `[Read from: ${readPaths.join(", ")}]\n\n`
1419
1496
  : "";
1420
1497
  const taskText = readsInstruction + taskWithOutputInstruction;
1498
+ const modelScopes = resolveModelScopesForAgent(ctx.modelScope, agentConfig.name, ctx.currentModel);
1421
1499
  const primaryModel = externalRunner ? undefined : params.modelOverrideFromParent
1422
1500
  ? params.modelOverride
1423
1501
  : resolveSubagentModelOverride(
@@ -1425,9 +1503,22 @@ export function executeAsyncSingle(
1425
1503
  ctx.currentModel,
1426
1504
  availableModels,
1427
1505
  ctx.currentModelProvider,
1506
+ { scope: modelScopes },
1428
1507
  );
1429
1508
  const effectiveThinking = externalRunner ? undefined : params.thinkingOverride ?? agentConfig.thinking;
1430
1509
  const model = externalRunner ? undefined : applyThinkingSuffix(primaryModel, effectiveThinking, params.thinkingOverride !== undefined);
1510
+ const thinkingCeiling = externalRunner ? undefined : intersectThinkingCeilings(
1511
+ params.thinkingCeiling,
1512
+ agentConfig.maxThinking,
1513
+ decodeThinkingCeiling(process.env[SUBAGENT_THINKING_CEILING_ENV]),
1514
+ );
1515
+ if (!externalRunner) {
1516
+ try {
1517
+ assertThinkingWithinCeiling({ model, configThinking: effectiveThinking, ceiling: thinkingCeiling, agent: agentConfig.name, runId: id });
1518
+ } catch (error) {
1519
+ return formatAsyncStartError("single", error instanceof Error ? error.message : String(error));
1520
+ }
1521
+ }
1431
1522
  const toolBudgetInput = params.toolBudget ?? agentConfig.toolBudget ?? params.configToolBudget;
1432
1523
  const resolvedToolBudget = validateToolBudgetConfig(toolBudgetInput, params.toolBudget ? "toolBudget" : agentConfig.toolBudget ? "agent.toolBudget" : "config.toolBudget");
1433
1524
  if (resolvedToolBudget.error) return formatAsyncStartError("single", resolvedToolBudget.error);
@@ -1448,18 +1539,25 @@ export function executeAsyncSingle(
1448
1539
  const initialUsageBudget = usageBudgetState(params.usageBudget, undefined);
1449
1540
  const resolvedSessionDir = params.sessionDir ?? (sessionRoot ? path.join(sessionRoot, `async-${id}`) : undefined);
1450
1541
  const structuredOutput = params.structuredOutputSchema
1451
- ? createStructuredOutputRuntime(params.structuredOutputSchema, path.join(asyncDir, "structured-output"))
1542
+ ? createStructuredOutputRuntime(params.structuredOutputSchema, path.join(asyncDir, "structured-output"), { captureAcceptanceReport: params.acceptance !== false })
1452
1543
  : undefined;
1453
1544
  const modelCandidates = externalRunner
1454
1545
  ? []
1455
- : buildModelCandidates(primaryModel, agentConfig.fallbackModels, availableModels, ctx.currentModelProvider, {
1456
- scope: ctx.modelScope,
1546
+ : buildModelCandidates(primaryModel, agentConfig.fallbackModels, availableModels, agentConfig.modelProvider ?? ctx.currentModelProvider, {
1547
+ scope: modelScopes,
1457
1548
  primaryModelFromParent: params.modelOverrideFromParent,
1458
1549
  })
1459
1550
  .flatMap((candidate) => {
1460
1551
  const resolved = applyThinkingSuffix(candidate, effectiveThinking, params.thinkingOverride !== undefined);
1461
1552
  return resolved ? [resolved] : [];
1462
1553
  });
1554
+ if (!externalRunner) {
1555
+ try {
1556
+ for (const candidate of modelCandidates) assertThinkingWithinCeiling({ model: candidate, configThinking: effectiveThinking, ceiling: thinkingCeiling, agent: agentConfig.name, runId: id });
1557
+ } catch (error) {
1558
+ return formatAsyncStartError("single", error instanceof Error ? error.message : String(error));
1559
+ }
1560
+ }
1463
1561
  const effectiveSystemPrompt = appendTurnBudgetSystemPrompt(systemPrompt, params.turnBudget);
1464
1562
  const toolPlan = resolvePiLaunchToolPlan({
1465
1563
  tools: agentConfig.tools,
@@ -1469,17 +1567,37 @@ export function executeAsyncSingle(
1469
1567
  cwd: runnerCwd,
1470
1568
  requireReadTool: Boolean(resolvedSkills.length),
1471
1569
  structuredOutput: Boolean(params.structuredOutputSchema),
1570
+ fast: params.fast ?? agentConfig.fast,
1571
+ model,
1572
+ modelCandidates,
1472
1573
  capabilityCeiling,
1473
1574
  inheritedCapabilityCeiling: decodeSubagentCapabilityCeiling(process.env[SUBAGENT_CAPABILITY_CEILING_ENV]),
1474
1575
  agentName: agentConfig.name,
1576
+ permissionRules: resolvePermissionRules(ctx.permissions, agentConfig.permissions),
1475
1577
  });
1476
1578
  const launchResolvedExtensions = externalRunner ? undefined : projectLaunchResolvedChildExtensions(toolPlan);
1579
+ if (!externalRunner) {
1580
+ const contractTools = toolPlan.explicitToolAllowlist ? toolPlan.effectiveToolAllowlist : undefined;
1581
+ const contractError = validateImplementationToolContract({
1582
+ agent: agentConfig.name,
1583
+ task: taskText,
1584
+ tools: contractTools,
1585
+ mcpDirectTools: toolPlan.effectiveMcpTools,
1586
+ configuredExtensions: toolPlan.configuredExtensions,
1587
+ requestedTools: toolPlan.requestedBuiltinTools,
1588
+ acceptanceRole: agentConfig.acceptanceRole,
1589
+ completionGuard: agentConfig.completionGuard,
1590
+ });
1591
+ if (contractError) return formatAsyncStartError("single", contractError);
1592
+ }
1477
1593
  const launchContractDigest = launchBindingDigest({
1478
1594
  definitionDigest: agentDefinitionDigest(agentConfig),
1479
1595
  task,
1480
1596
  ...(model ? { model } : {}),
1481
1597
  modelCandidates,
1598
+ ...((params.fast ?? agentConfig.fast) !== undefined ? { fast: params.fast ?? agentConfig.fast } : {}),
1482
1599
  ...(resolveEffectiveThinking(model, effectiveThinking) ? { thinking: resolveEffectiveThinking(model, effectiveThinking) } : {}),
1600
+ ...(thinkingCeiling ? { thinkingCeiling } : {}),
1483
1601
  systemPrompt: effectiveSystemPrompt,
1484
1602
  systemPromptMode: agentConfig.systemPromptMode,
1485
1603
  inheritProjectContext: agentConfig.inheritProjectContext,
@@ -1491,6 +1609,7 @@ export function executeAsyncSingle(
1491
1609
  ...(outputPath ? { outputPath } : {}),
1492
1610
  outputMode,
1493
1611
  ...(params.structuredOutputSchema ? { structuredOutputSchema: params.structuredOutputSchema } : {}),
1612
+ ...(extensionBindings ? { extensionBindings } : {}),
1494
1613
  });
1495
1614
  const resolvedAcceptance = resolveEffectiveAcceptance({
1496
1615
  explicit: params.acceptance,
@@ -1505,6 +1624,7 @@ export function executeAsyncSingle(
1505
1624
  const recoveryDescriptor: SteeringRecoveryDescriptor = {
1506
1625
  version: 1,
1507
1626
  launchContractDigest,
1627
+ ...(extensionBindings ? { extensionBindings } : {}),
1508
1628
  runFanoutBudget,
1509
1629
  sourceRunId: id,
1510
1630
  ...(params.agentContract ? { agentContract: params.agentContract } : {}),
@@ -1513,9 +1633,12 @@ export function executeAsyncSingle(
1513
1633
  ...(sessionFile ? { sessionFile } : {}),
1514
1634
  cwd: runnerCwd,
1515
1635
  ...(model ? { model } : {}),
1636
+ ...(params.fast ?? recoveryAgentConfig.fast ? { fast: params.fast ?? recoveryAgentConfig.fast } : {}),
1637
+ ...(recoveryAgentConfig.modelProvider ? { modelProvider: recoveryAgentConfig.modelProvider } : {}),
1516
1638
  ...(params.modelOverrideFromParent ? { modelOverrideFromParent: true } : {}),
1517
1639
  ...(recoveryAgentConfig.fallbackModels ? { fallbackModels: [...recoveryAgentConfig.fallbackModels] } : {}),
1518
1640
  ...(effectiveThinking ? { thinking: resolveEffectiveThinking(model, effectiveThinking) } : {}),
1641
+ ...(thinkingCeiling ? { thinkingCeiling } : {}),
1519
1642
  ...(recoveryAgentConfig.tools ? { tools: [...recoveryAgentConfig.tools] } : {}),
1520
1643
  ...(recoveryAgentConfig.extensions ? { extensions: [...recoveryAgentConfig.extensions] } : {}),
1521
1644
  ...(recoveryAgentConfig.subagentOnlyExtensions ? { subagentOnlyExtensions: [...recoveryAgentConfig.subagentOnlyExtensions] } : {}),
@@ -1567,11 +1690,16 @@ export function executeAsyncSingle(
1567
1690
  agent,
1568
1691
  task: taskText,
1569
1692
  ...(agentConfig.runner ? { runner: agentConfig.runner } : {}),
1693
+ ...(params.externalJobFollowUp ? { externalJobFollowUp: params.externalJobFollowUp } : {}),
1570
1694
  ...(params.context ? { context: params.context } : {}),
1571
1695
  cwd: runnerCwd,
1572
1696
  model,
1697
+ ...(params.fast ?? agentConfig.fast ? { fast: params.fast ?? agentConfig.fast } : {}),
1573
1698
  thinking: resolveEffectiveThinking(model, effectiveThinking),
1699
+ ...(thinkingCeiling ? { thinkingCeiling } : {}),
1574
1700
  modelCandidates,
1701
+ ...(params.modelOverrideFromParent ? { skipPrimaryModelVerification: true } : {}),
1702
+ ...(availableModels && availableModels.length > 0 ? { modelVerificationRegistry: availableModels } : {}),
1575
1703
  tools: agentConfig.tools,
1576
1704
  extensions: agentConfig.extensions,
1577
1705
  subagentOnlyExtensions: agentConfig.subagentOnlyExtensions,
@@ -1591,6 +1719,7 @@ export function executeAsyncSingle(
1591
1719
  definitionDigest: agentDefinitionDigest(agentConfig),
1592
1720
  launchBindingTask: task,
1593
1721
  launchContractDigest,
1722
+ ...(extensionBindings ? { extensionBindings } : {}),
1594
1723
  launchResolvedExtensions,
1595
1724
  effectiveAcceptance: resolvedAcceptance,
1596
1725
  ...(structuredOutput ? { structuredOutput } : {}),
@@ -1599,7 +1728,7 @@ export function executeAsyncSingle(
1599
1728
  ...(params.worktree === true ? { worktree: true } : {}),
1600
1729
  },
1601
1730
  ],
1602
- resultPath: params.parentWorkflowRunId !== undefined && params.revivalLease !== undefined
1731
+ resultPath: params.parentWorkflowRunId !== undefined && (params.revivalLease !== undefined || params.workflowAwaitAsync === true)
1603
1732
  ? workflowAwaitedAsyncResultPath(asyncDir)
1604
1733
  : inheritedNestedRoute ? nestedResultsPath(inheritedNestedRoute.rootRunId, id) : resultFilePath(DIRS.results, id),
1605
1734
  cwd: runnerCwd,
@@ -8,12 +8,14 @@ import {
8
8
  type AsyncStartedEvent,
9
9
  type ControlEvent,
10
10
  type SteeringNotice,
11
+ type SubagentChildStatusEvent,
11
12
  type SubagentState,
12
- POLL_INTERVAL_MS,
13
13
  DIRS,
14
+ SUBAGENT_CHILD_STATUS_EVENT,
14
15
  SUBAGENT_CONTROL_EVENT,
15
16
  SUBAGENT_CONTROL_INTERCOM_EVENT,
16
17
  SUBAGENT_STEERING_NOTICE_EVENT,
18
+ WIDGET_ANIMATION_INTERVAL_MS,
17
19
  } from "../../shared/types.ts";
18
20
  import { readStatus, resolveWatchPath } from "../../shared/utils.ts";
19
21
  import { normalizeParallelGroups } from "./parallel-groups.ts";
@@ -71,6 +73,7 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
71
73
  const runningJobIds = new Set<string>();
72
74
  let rootWatcher: fs.FSWatcher | undefined;
73
75
  let nextLivenessAt = Date.now() + livenessIntervalMs;
76
+ let nextWidgetAnimationAt = Date.now() + WIDGET_ANIMATION_INTERVAL_MS;
74
77
  const watch = options.watch ?? fs.watch;
75
78
  const useNativeWatcher = () => shouldUseNativeFsWatch("async-job-tracker", options.platform);
76
79
  const terminalStatus = (status: string) => status === "complete" || status === "failed" || status === "paused" || status === "stopped";
@@ -93,17 +96,8 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
93
96
  }
94
97
  };
95
98
  const requestLastWidgetRender = () => {
96
- const ctx = state.lastUiContext;
97
- if (!ctx || state.widgetsSuspended || options.widgetEnabled === false) return;
98
- try {
99
- if (ctx.hasUI) (ctx.ui as { requestRender?: () => void }).requestRender?.();
100
- } catch (error) {
101
- if (error instanceof Error && error.message.includes("extension ctx is stale")) {
102
- state.lastUiContext = null;
103
- return;
104
- }
105
- throw error;
106
- }
99
+ if (options.widgetEnabled === false) return;
100
+ rerenderLastWidget();
107
101
  };
108
102
  const refreshWidget = (ctx: ExtensionContext) => rerenderWidget(ctx);
109
103
  const restoredControlEventCursor = (asyncDir: string) => {
@@ -227,6 +221,28 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
227
221
  return;
228
222
  }
229
223
  if (!parsed || typeof parsed !== "object") return;
224
+ if ((parsed as { type?: unknown }).type === "subagent.child-status") {
225
+ const event = parsed as Partial<SubagentChildStatusEvent>;
226
+ if (event.version !== 1 || typeof event.runId !== "string" || typeof event.childId !== "string" || (event.status !== "stopping" && event.status !== "stopped") || typeof event.ts !== "number") return;
227
+ pi.events.emit(SUBAGENT_CHILD_STATUS_EVENT, {
228
+ type: "subagent.child-status",
229
+ version: 1,
230
+ runId: event.runId,
231
+ childId: event.childId,
232
+ status: event.status,
233
+ ts: event.ts,
234
+ ...(typeof event.reason === "string" ? { reason: event.reason } : {}),
235
+ source: event.source === "rpc" ? "rpc" : "async",
236
+ asyncDir: job.asyncDir,
237
+ ...(typeof event.stepIndex === "number" ? { stepIndex: event.stepIndex } : {}),
238
+ ...(typeof event.agent === "string" ? { agent: event.agent } : {}),
239
+ ...(typeof event.childRunId === "string" ? { childRunId: event.childRunId } : {}),
240
+ ...(typeof event.workflowKey === "string" ? { workflowKey: event.workflowKey } : {}),
241
+ ...(typeof event.phase === "string" ? { phase: event.phase } : {}),
242
+ ...(typeof event.label === "string" ? { label: event.label } : {}),
243
+ } satisfies SubagentChildStatusEvent);
244
+ return;
245
+ }
230
246
  if ((parsed as { type?: unknown }).type === "subagent.steering.notice") {
231
247
  const notice = parsed as Partial<SteeringNotice>;
232
248
  if (typeof notice.requestId !== "string" || typeof notice.runId !== "string" || (notice.state !== "failed" && notice.state !== "partial" && notice.state !== "recovered") || typeof notice.message !== "string") return;
@@ -556,8 +572,11 @@ export function createAsyncJobTracker(pi: Pick<ExtensionAPI, "events">, state: S
556
572
  }
557
573
  if (widgetChanged) rerenderLastWidget();
558
574
  }
559
- if (runningJobIds.size > 0) requestLastWidgetRender();
560
- }, Math.min(POLL_INTERVAL_MS, livenessIntervalMs));
575
+ if (runningJobIds.size > 0 && now >= nextWidgetAnimationAt) {
576
+ nextWidgetAnimationAt = now + WIDGET_ANIMATION_INTERVAL_MS;
577
+ requestLastWidgetRender();
578
+ }
579
+ }, Math.min(WIDGET_ANIMATION_INTERVAL_MS, livenessIntervalMs));
561
580
  state.poller.unref?.();
562
581
  };
563
582