@xzzpig/pi-subagents 0.16.0 → 0.19.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/CHANGELOG.md +233 -1
  2. package/README.md +5 -3
  3. package/agents/claude-code-writer.md +1 -0
  4. package/agents/codex-exec-writer.md +1 -0
  5. package/agents/cursor-agent-writer.md +1 -0
  6. package/agents/reviewer.md +3 -2
  7. package/agents/worker.md +3 -2
  8. package/docs/agents.md +34 -21
  9. package/docs/configuration.md +82 -7
  10. package/docs/extension-api.md +75 -8
  11. package/docs/missions.md +13 -13
  12. package/docs/models.md +7 -5
  13. package/docs/observability.md +23 -13
  14. package/docs/standalone-background.md +5 -5
  15. package/docs/tool-reference.md +98 -100
  16. package/docs/watchdog.md +2 -0
  17. package/docs/workflows.md +214 -162
  18. package/inspector-runner.mjs +1 -1
  19. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  20. package/package.json +15 -9
  21. package/prompts/council.md +6 -3
  22. package/prompts/review-loop.md +1 -1
  23. package/runner-peer-loader.mjs +4 -7
  24. package/runner-peer-preload.mjs +5 -7
  25. package/skills/council-mode/SKILL.md +1 -1
  26. package/skills/pi-subagents/SKILL.md +13 -5
  27. package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
  28. package/skills/pi-subagents/references/execution-controls.md +72 -69
  29. package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
  30. package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
  31. package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
  32. package/src/agents/advertised-agent-prompt.ts +21 -41
  33. package/src/agents/agent-eject.ts +3 -3
  34. package/src/agents/agent-management.ts +63 -54
  35. package/src/agents/agent-memory.ts +90 -3
  36. package/src/agents/agent-serializer.ts +4 -4
  37. package/src/agents/agents.ts +132 -51
  38. package/src/agents/global-npm-root.ts +58 -0
  39. package/src/agents/proactive-skills.ts +4 -1
  40. package/src/agents/runtime-agent-registry.ts +14 -11
  41. package/src/agents/skills.ts +42 -9
  42. package/src/api/delegation.ts +15 -0
  43. package/src/api/inspectors.ts +27 -0
  44. package/src/api/preflight.ts +7 -2
  45. package/src/extension/config.ts +12 -4
  46. package/src/extension/control-notices.ts +3 -0
  47. package/src/extension/doctor.ts +10 -4
  48. package/src/extension/fanout-child.ts +20 -3
  49. package/src/extension/herdr-pi-bridge.ts +2 -0
  50. package/src/extension/index.ts +168 -206
  51. package/src/extension/public-execution.ts +69 -35
  52. package/src/extension/reply-workflow-script.ts +58 -0
  53. package/src/extension/rpc.ts +39 -11
  54. package/src/extension/schemas.ts +47 -138
  55. package/src/extension/subagent-guide.ts +12 -4
  56. package/src/extension/tool-activation.ts +146 -0
  57. package/src/extension/tool-description.ts +62 -27
  58. package/src/extension/upgrade-notice.ts +40 -0
  59. package/src/inspectors/ghostty/plugin.ts +13 -1
  60. package/src/inspectors/plugins.ts +70 -3
  61. package/src/integrations/herdr-status.ts +19 -3
  62. package/src/intercom/intercom-bridge.ts +2 -0
  63. package/src/intercom/native-supervisor-channel.ts +26 -16
  64. package/src/intercom/result-intercom.ts +4 -0
  65. package/src/runs/background/active-async-capacity.ts +3 -25
  66. package/src/runs/background/async-execution.ts +60 -95
  67. package/src/runs/background/async-job-tracker.ts +91 -56
  68. package/src/runs/background/async-resume.ts +16 -8
  69. package/src/runs/background/async-retention.ts +46 -16
  70. package/src/runs/background/async-status.ts +2 -0
  71. package/src/runs/background/await-async-run.ts +76 -0
  72. package/src/runs/background/binary-bootstrap.ts +34 -6
  73. package/src/runs/background/chain-root-attachment.ts +4 -4
  74. package/src/runs/background/control-channel.ts +18 -2
  75. package/src/runs/background/fleet-view.ts +51 -7
  76. package/src/runs/background/notify.ts +98 -7
  77. package/src/runs/background/pid-namespace.ts +18 -0
  78. package/src/runs/background/process-terminal-candidate.ts +98 -0
  79. package/src/runs/background/process-terminal.ts +17 -96
  80. package/src/runs/background/result-watcher.ts +1 -1
  81. package/src/runs/background/retained-children.ts +3 -2
  82. package/src/runs/background/run-child-session.ts +20 -6
  83. package/src/runs/background/run-id-resolver.ts +10 -5
  84. package/src/runs/background/run-status.ts +16 -4
  85. package/src/runs/background/runner-aliases.ts +54 -16
  86. package/src/runs/background/runner-child-launch.ts +4 -2
  87. package/src/runs/background/runner-startup-failure.ts +56 -0
  88. package/src/runs/background/scheduled-runs.ts +5 -5
  89. package/src/runs/background/stale-run-reconciler.ts +19 -3
  90. package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
  91. package/src/runs/background/subagent-runner.ts +111 -288
  92. package/src/runs/background/wait-tool.ts +2 -0
  93. package/src/runs/background/workflow-terminal-proof.ts +68 -0
  94. package/src/runs/foreground/async-stop-action.ts +17 -3
  95. package/src/runs/foreground/execution.ts +111 -139
  96. package/src/runs/foreground/prompt-audit.ts +3 -9
  97. package/src/runs/foreground/subagent-executor.ts +715 -258
  98. package/src/runs/shared/acceptance.ts +167 -68
  99. package/src/runs/shared/async-status-projection.ts +5 -0
  100. package/src/runs/shared/capability-ceiling.ts +4 -1
  101. package/src/runs/shared/child-hooks.ts +1 -16
  102. package/src/runs/shared/child-launch.ts +37 -16
  103. package/src/runs/shared/child-runtime-config.ts +3 -0
  104. package/src/runs/shared/child-session.ts +144 -8
  105. package/src/runs/shared/child-tool-plan.ts +38 -116
  106. package/src/runs/shared/dynamic-fanout.ts +1 -1
  107. package/src/runs/shared/external-cli-runner.ts +3 -1
  108. package/src/runs/shared/external-job-bridge.ts +54 -0
  109. package/src/runs/shared/git-environment.ts +29 -0
  110. package/src/runs/shared/mcp-config-sources.ts +5 -1
  111. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
  112. package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
  113. package/src/runs/shared/model-resolution.ts +35 -10
  114. package/src/runs/shared/model-scope.ts +28 -9
  115. package/src/runs/shared/nested-events.ts +12 -0
  116. package/src/runs/shared/orca-progress-tabs.ts +3 -2
  117. package/src/runs/shared/parallel-utils.ts +4 -1
  118. package/src/runs/shared/pi-spawn.ts +1 -3
  119. package/src/runs/shared/single-output.ts +11 -2
  120. package/src/runs/shared/structured-output.ts +227 -7
  121. package/src/runs/shared/subagent-control.ts +2 -16
  122. package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
  123. package/src/runs/shared/tool-availability.ts +2 -2
  124. package/src/runs/shared/tool-budget.ts +21 -0
  125. package/src/runs/shared/usage-reconciliation.ts +73 -0
  126. package/src/runs/shared/worktree.ts +36 -9
  127. package/src/shared/child-session-name.ts +4 -2
  128. package/src/shared/disabled-features.ts +123 -0
  129. package/src/shared/extension-context.ts +13 -0
  130. package/src/shared/fork-context.ts +11 -4
  131. package/src/shared/launch-contract.ts +1 -1
  132. package/src/shared/model-info.ts +9 -0
  133. package/src/shared/pruned-fork.ts +69 -56
  134. package/src/shared/settings.ts +1 -1
  135. package/src/shared/types.ts +73 -16
  136. package/src/slash/delegation-adapters.ts +25 -1
  137. package/src/slash/prompt-template-bridge.ts +18 -3
  138. package/src/slash/prompt-workflows.ts +12 -1
  139. package/src/slash/slash-commands.ts +17 -246
  140. package/src/slash/subagent-cost.ts +313 -0
  141. package/src/slash/subagents-admin.ts +4 -5
  142. package/src/tui/fleet-status.ts +38 -8
  143. package/src/tui/fleet.ts +21 -6
  144. package/src/tui/render.ts +166 -71
  145. package/src/tui/running-tone.ts +28 -0
  146. package/src/watchdog/diff-tool.ts +47 -12
  147. package/src/watchdog/permission-arbiter.ts +13 -15
  148. package/src/watchdog/register-child.ts +13 -5
  149. package/src/watchdog/register-main.ts +3 -3
  150. package/src/watchdog/review.ts +16 -16
  151. package/src/watchdog/runtime.ts +2 -1
  152. package/src/watchdog/turn-delta.ts +12 -6
  153. package/src/workflows/chat-progress.ts +2 -2
  154. package/src/workflows/scripted-workflow.ts +225 -59
  155. package/src/workflows/structured-workflow-scripts.ts +177 -0
  156. package/src/workflows/workflow-checklist.ts +6 -0
  157. package/src/workflows/workflow-child-summary.ts +4 -2
  158. package/src/workflows/workflow-receipt.ts +8 -2
  159. package/src/workflows/workflow-resources.ts +37 -12
  160. package/src/workflows/workflow-reuse.ts +120 -0
  161. package/src/workflows/workflow-revival.ts +123 -0
  162. package/src/workflows/workflow-settlement.ts +4 -1
  163. package/src/runs/shared/completion-evidence.ts +0 -89
  164. package/src/runs/shared/completion-guard.ts +0 -255
  165. package/src/runs/shared/llm-intent-arbiter.ts +0 -321
  166. package/src/runs/shared/task-intent.ts +0 -244
@@ -9,6 +9,7 @@ import * as path from "node:path";
9
9
  import { fileURLToPath } from "node:url";
10
10
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
11
11
  import {
12
+ formatUnresolvedBuiltinMcpSelectors,
12
13
  formatUnresolvedMcpDirectToolSelectors,
13
14
  resolveMcpDirectToolResolution,
14
15
  type McpRuntimeSnapshotHost,
@@ -62,45 +63,10 @@ const SUBAGENT_RUNTIME_EXTENSION_PATHS = new Set([
62
63
  export function isSubagentRuntimeExtensionPath(extensionPath: string): boolean {
63
64
  return SUBAGENT_RUNTIME_EXTENSION_PATHS.has(path.normalize(extensionPath));
64
65
  }
65
- const FAST_MODE_ALLOWED_MODELS = new Set([
66
- "openai-codex/gpt-5.6-luna",
67
- "openai-codex/gpt-5.6-sol",
68
- ]);
69
- const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
70
66
  const PI_BUILTIN_TOOL_NAMES = new Set(["read", "bash", "powershell", "edit", "write", "grep", "find", "ls"]);
71
- const REPOSITORY_INSPECTION_TOOLS = new Set(["read", "grep", "find", "ls", "bash", "powershell"]);
72
- const REVIEW_OR_SCOUT_AGENT_PATTERN = /\b(?:reviewer|scout)\b/i;
73
-
74
- export function isReviewOrScoutLaneAgent(agentName: string | undefined): boolean {
75
- return typeof agentName === "string" && REVIEW_OR_SCOUT_AGENT_PATTERN.test(agentName);
76
- }
77
-
78
- export function missingPermittedRepositoryInspectionTools(
79
- unavailableHostBuiltins: readonly string[],
80
- excludeTools: readonly string[] = [],
81
- ): string[] {
82
- const excluded = new Set(excludeTools);
83
- return unavailableHostBuiltins.filter((tool) => REPOSITORY_INSPECTION_TOOLS.has(tool) && !excluded.has(tool));
84
- }
85
-
86
- export function formatReviewLaneToolContractFailure(input: {
87
- agentName?: string;
88
- missingTools: readonly string[];
89
- requestedTools?: readonly string[];
90
- effectiveTools: readonly string[];
91
- ceilingSources?: readonly string[];
92
- excludeTools?: readonly string[];
93
- }): string {
94
- const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
95
- return [
96
- `${subject}: tool contract could not be satisfied; host runtime does not provide permitted required repository tools [${input.missingTools.join(", ")}].`,
97
- `Requested tool names: ${input.requestedTools ? `[${input.requestedTools.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${input.effectiveTools.join(", ")}].`,
98
- ...(input.ceilingSources?.length ? [`Active capability ceiling sources: [${input.ceilingSources.join(", ")}].`] : []),
99
- ...(input.excludeTools?.length ? [`Explicit excludeTools: [${input.excludeTools.join(", ")}].`] : []),
100
- "This is a lane infrastructure failure, not a completed review/scout result.",
101
- ].join(" ");
102
- }
103
-
67
+ // Priority tier is an OpenAI-Codex request field; other providers reject or ignore it.
68
+ const FAST_MODE_PROVIDER_PREFIX = "openai-codex/";
69
+ const OPENAI_PROMPT_CACHE_KEY_MAX_LENGTH = 64;
104
70
  export function deriveForkPromptCacheKey(parentSessionId: string | undefined): string | undefined {
105
71
  const parent = parentSessionId?.trim();
106
72
  if (!parent) return undefined;
@@ -160,9 +126,9 @@ function resolveFastModeExtension(input: Pick<ResolvePiLaunchToolPlanInput, "fas
160
126
  if (candidates.length === 0) {
161
127
  throw new Error(`fast mode requires an explicit supported native OpenAI-Codex model${input.agentName ? ` for agent '${input.agentName}'` : ""}.`);
162
128
  }
163
- const unsupported = candidates.filter((model) => !FAST_MODE_ALLOWED_MODELS.has(model));
129
+ const unsupported = candidates.filter((model) => !model.startsWith(FAST_MODE_PROVIDER_PREFIX));
164
130
  if (unsupported.length > 0) {
165
- throw new Error(`fast mode supports only ${[...FAST_MODE_ALLOWED_MODELS].join(", ")}; unsupported model${unsupported.length === 1 ? "" : "s"}: ${unsupported.join(", ")}.`);
131
+ throw new Error(`fast mode supports only native ${FAST_MODE_PROVIDER_PREFIX}* models; unsupported model${unsupported.length === 1 ? "" : "s"}: ${unsupported.join(", ")}.`);
166
132
  }
167
133
  return [FAST_MODE_EXTENSION_PATH];
168
134
  }
@@ -205,7 +171,10 @@ export interface ResolvePiLaunchToolPlanInput {
205
171
  * empty or ceiling-restricted allowlists are not a minimum-tool contract.
206
172
  * Non-core names remain allowed and are validated in the child's registry.
207
173
  */
208
- hostAvailableBuiltins?: readonly string[];}
174
+ hostAvailableBuiltins?: readonly string[];
175
+ /** The parent's built-in MCP selections; the background runner has no host to resolve selectors against. */
176
+ builtinMcpTools?: ResolvedMcpDirectToolSelection[];
177
+ }
209
178
 
210
179
  export interface PiLaunchToolPlan {
211
180
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
@@ -216,6 +185,8 @@ export interface PiLaunchToolPlan {
216
185
  resolvedMcpSelections: ResolvedMcpDirectToolSelection[];
217
186
  effectiveMcpSelections: ResolvedMcpDirectToolSelection[];
218
187
  effectiveMcpTools: string[];
188
+ /** Effective selections granted from Pi's built-in MCP; undefined when the selectors did not resolve against it. */
189
+ builtinMcpTools?: ResolvedMcpDirectToolSelection[];
219
190
  explicitToolAllowlist: boolean;
220
191
  internalTools: string[];
221
192
  effectiveToolAllowlist: string[];
@@ -231,8 +202,6 @@ export interface PiLaunchToolPlan {
231
202
  capabilityAudit?: SubagentCapabilityAudit;
232
203
  /** Non-fatal launch warnings; they do not change behavior. */
233
204
  warnings: string[];
234
- /** Builtin tools the agent declared but the host runtime does not provide. */
235
- unavailableHostBuiltins: string[];
236
205
  }
237
206
 
238
207
  function extensionIdentifier(value: string): string {
@@ -361,32 +330,6 @@ export function resolvePermissionSystemExtension(): string | undefined {
361
330
  return undefined;
362
331
  }
363
332
 
364
- /**
365
- * Extract the names of builtin tools the host provides. Use this to pass
366
- * `hostAvailableBuiltins` to `resolvePiLaunchToolPlan` so child tool plans
367
- * intersect known core slots with what the host actually supports. Wrapped
368
- * core slots count regardless of source; host-specific builtins count too.
369
- *
370
- * Returns `undefined` when builtin tool discovery fails or yields nothing,
371
- * so callers skip the intersection (fail-safe to allowing all declared tools).
372
- * This handles test mocks without proper tool registration and hosts whose
373
- * getAllTools() throws before extensions load.
374
- */
375
- export function getHostBuiltinToolNames(pi: Pick<ExtensionAPI, "getAllTools">): string[] | undefined {
376
- try {
377
- const builtins = pi
378
- .getAllTools()
379
- .filter((tool) => {
380
- const source = (tool.sourceInfo as { source?: string } | undefined)?.source;
381
- return source === "builtin" || PI_BUILTIN_TOOL_NAMES.has(tool.name);
382
- })
383
- .map((tool) => tool.name);
384
- return builtins.length > 0 ? builtins : undefined;
385
- } catch {
386
- return undefined;
387
- }
388
- }
389
-
390
333
  export function resolvePiLaunchToolPlan(
391
334
  input: ResolvePiLaunchToolPlanInput,
392
335
  ): PiLaunchToolPlan {
@@ -402,21 +345,11 @@ export function resolvePiLaunchToolPlan(
402
345
  capabilityCeiling?.allowedTools === undefined
403
346
  ? undefined
404
347
  : new Set(capabilityCeiling.allowedTools);
405
- const hostAvailableSet =
406
- input.hostAvailableBuiltins === undefined
407
- ? undefined
408
- : new Set(input.hostAvailableBuiltins);
409
348
  const requestedBuiltinTools =
410
349
  input.tools?.filter(
411
350
  (tool) =>
412
351
  !(tool.includes("/") || tool.endsWith(".ts") || tool.endsWith(".js")),
413
352
  ) ?? [];
414
- if (input.requireReadTool && hostAvailableSet && !hostAvailableSet.has("read")) {
415
- const agentLabel = input.agentName ? ` for agent '${input.agentName}'` : "";
416
- throw new Error(
417
- `Host runtime does not provide required tool 'read'${agentLabel} for lazy skill loading.`,
418
- );
419
- }
420
353
  if (input.requireReadTool && allowedToolSet && !allowedToolSet.has("read")) {
421
354
  throw new Error(
422
355
  `Capability ceiling from ${capabilityCeiling?.sources.join(", ") || "unknown source"} excludes required tool 'read' for lazy skill loading.`,
@@ -434,12 +367,7 @@ export function resolvePiLaunchToolPlan(
434
367
  ? ["read", ...requestedBuiltinTools]
435
368
  : requestedBuiltinTools
436
369
  ).filter((tool) => !allowedToolSet || allowedToolSet.has(tool));
437
- const declaredBuiltinTools = hostAvailableSet
438
- ? ceilingFilteredBuiltinTools.filter((tool) => !PI_BUILTIN_TOOL_NAMES.has(tool) || hostAvailableSet.has(tool))
439
- : ceilingFilteredBuiltinTools;
440
- const unavailableHostBuiltins = hostAvailableSet
441
- ? ceilingFilteredBuiltinTools.filter((tool) => PI_BUILTIN_TOOL_NAMES.has(tool) && !hostAvailableSet.has(tool))
442
- : [];
370
+ const declaredBuiltinTools = ceilingFilteredBuiltinTools;
443
371
  const excludeTools = [...new Set((input.excludeTools ?? []).map((tool) => tool.trim()).filter(Boolean))];
444
372
  const excludedToolSet = new Set(excludeTools);
445
373
  const effectiveDeclaredBuiltinTools = declaredBuiltinTools.filter((tool) => !excludedToolSet.has(tool));
@@ -460,16 +388,21 @@ export function resolvePiLaunchToolPlan(
460
388
  );
461
389
  const mcpResolution = capabilityCeiling?.denyExtensions
462
390
  ? { selections: [], unresolvedSelectors: [] }
463
- : resolveMcpDirectToolResolution(input.mcpDirectTools, input.cwd, input.runtimeSnapshotHost);
391
+ : input.builtinMcpTools
392
+ // The runner applies the same ceilings again; filtering is idempotent.
393
+ ? { selections: input.builtinMcpTools, unresolvedSelectors: [], builtin: true as const }
394
+ : resolveMcpDirectToolResolution(input.mcpDirectTools, input.cwd, input.runtimeSnapshotHost);
464
395
  if (mcpResolution.runtimeServerNames?.length) {
465
396
  throw new Error(formatRuntimeSnapshotMcpServersError(input.agentName, mcpResolution.runtimeServerNames));
466
397
  }
467
398
  if (mcpResolution.unresolvedSelectors.length > 0) {
468
- throw new Error(formatUnresolvedMcpDirectToolSelectors(mcpResolution.unresolvedSelectors));
399
+ throw new Error(mcpResolution.builtin
400
+ ? formatUnresolvedBuiltinMcpSelectors(input.agentName, mcpResolution.unresolvedSelectors)
401
+ : formatUnresolvedMcpDirectToolSelectors(mcpResolution.unresolvedSelectors));
469
402
  }
470
403
  const resolvedMcpSelections = mcpResolution.selections;
471
404
  const resolvedMcpNames = new Set(resolvedMcpSelections.map((selection) => selection.name));
472
- const legacyMcpNameCounts = countLegacyUnderscoreMcpToolNames(resolvedMcpSelections);
405
+ const legacyMcpNameCounts = mcpResolution.builtin ? new Map<string, number>() : countLegacyUnderscoreMcpToolNames(resolvedMcpSelections);
473
406
  const effectiveMcpSelections = resolvedMcpSelections.filter(
474
407
  (selection) =>
475
408
  !allowedToolSet ||
@@ -479,6 +412,7 @@ export function resolvePiLaunchToolPlan(
479
412
  const effectiveMcpTools = effectiveMcpSelections.map(
480
413
  (selection) => selection.name,
481
414
  );
415
+ const builtinMcpTools = mcpResolution.builtin ? effectiveMcpSelections : undefined;
482
416
  const explicitToolAllowlist =
483
417
  input.tools !== undefined ||
484
418
  (input.mcpDirectTools?.length ?? 0) > 0 ||
@@ -567,32 +501,6 @@ export function resolvePiLaunchToolPlan(
567
501
  ]),
568
502
  ]
569
503
  : undefined;
570
- const missingPermittedRepositoryTools = input.tools !== undefined
571
- ? missingPermittedRepositoryInspectionTools(unavailableHostBuiltins, excludeTools)
572
- : [];
573
- if (missingPermittedRepositoryTools.length > 0 && isReviewOrScoutLaneAgent(input.agentName)) {
574
- throw new Error(formatReviewLaneToolContractFailure({
575
- agentName: input.agentName,
576
- missingTools: missingPermittedRepositoryTools,
577
- requestedTools: requestedToolNames,
578
- effectiveTools: effectiveToolAllowlist,
579
- ceilingSources: capabilityCeiling?.sources,
580
- excludeTools,
581
- }));
582
- }
583
- // Host pruning also happens without a ceiling (and therefore without an
584
- // audit). Use the existing non-fatal launch warnings rather than inventing
585
- // a ceiling or treating the requested allowlist as a minimum requirement.
586
- if (unavailableHostBuiltins.length > 0) {
587
- const subject = input.agentName ? `Agent '${input.agentName}'` : "Subagent";
588
- warnings.push(
589
- `${subject}: host runtime tool availability omitted [${unavailableHostBuiltins.join(", ")}]. `
590
- + `Requested tool names: ${requestedToolNames ? `[${requestedToolNames.join(", ")}]` : "not explicitly specified"}; effective tool allowlist: [${effectiveToolAllowlist.join(", ")}]. `
591
- + (capabilityCeiling ? `Active capability ceiling sources: [${capabilityCeiling.sources.join(", ") || "unknown source"}]. ` : "")
592
- + (excludeTools.length > 0 ? `Explicit excludeTools: [${excludeTools.join(", ")}]. ` : "")
593
- + "This is a non-fatal tool-plan diagnostic, not verification of the child's runtime tool menu.",
594
- );
595
- }
596
504
  const capabilityAudit = capabilityCeiling
597
505
  ? ({
598
506
  ceiling: capabilityCeiling,
@@ -630,7 +538,6 @@ export function resolvePiLaunchToolPlan(
630
538
  capabilityCeilingAgentRestrictionSources(capabilityCeiling),
631
539
  }
632
540
  : {}),
633
- ...(unavailableHostBuiltins.length > 0 ? { unavailableHostBuiltins } : {}),
634
541
  } satisfies SubagentCapabilityAudit)
635
542
  : undefined;
636
543
  return {
@@ -642,6 +549,7 @@ export function resolvePiLaunchToolPlan(
642
549
  resolvedMcpSelections,
643
550
  effectiveMcpSelections,
644
551
  effectiveMcpTools,
552
+ builtinMcpTools,
645
553
  explicitToolAllowlist,
646
554
  internalTools,
647
555
  effectiveToolAllowlist,
@@ -654,7 +562,6 @@ export function resolvePiLaunchToolPlan(
654
562
  extensionArgs,
655
563
  disableAmbientExtensions,
656
564
  warnings,
657
- unavailableHostBuiltins,
658
565
  ...(capabilityAudit ? { capabilityAudit } : {}),
659
566
  };
660
567
  }
@@ -688,3 +595,18 @@ function legacyUnderscoreMcpToolName(selection: ResolvedMcpDirectToolSelection):
688
595
  const prefix = selection.name.slice(0, -suffix.length);
689
596
  return `${prefix.replace(/-/g, "_")}${suffix}`;
690
597
  }
598
+
599
+ export function getHostBuiltinToolNames(pi: Pick<ExtensionAPI, "getAllTools">): string[] | undefined {
600
+ try {
601
+ const builtins = pi
602
+ .getAllTools()
603
+ .filter((tool) => {
604
+ const source = (tool.sourceInfo as { source?: string } | undefined)?.source;
605
+ return source === "builtin" || PI_BUILTIN_TOOL_NAMES.has(tool.name);
606
+ })
607
+ .map((tool) => tool.name);
608
+ return builtins.length > 0 ? builtins : undefined;
609
+ } catch {
610
+ return undefined;
611
+ }
612
+ }
@@ -50,7 +50,7 @@ const DYNAMIC_PARALLEL_KEYS = new Set(["agent", "task", "phase", "label", "outpu
50
50
  const RUNNER_DYNAMIC_PARALLEL_KEYS = new Set([
51
51
  ...DYNAMIC_PARALLEL_KEYS,
52
52
  "outputName", "structured", "inheritProjectContext", "inheritGlobalContext", "inheritSkills", "skills", "outputPath", "namespaceOutputPath", "maxSubagentDepth", "timeoutMs", "waitToolEnabled", "waitToolDefaultTimeoutMs",
53
- "structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "mutationTools", "capabilityCeiling", "completionGuard", "systemPrompt",
53
+ "structuredOutput", "structuredOutputSchema", "tools", "excludeTools", "allowNestedSubagents", "extensions", "subagentOnlyExtensions", "mcpDirectTools", "builtinMcpTools", "mutationTools", "capabilityCeiling", "systemPrompt",
54
54
  "systemPromptMode", "thinking", "requestedModel", "sessionFile", "effectiveAcceptance", "acceptanceInput", "acceptanceRole", "parentSessionId", "requiredExtensions", "launchResolvedExtensions", "requestedCwd", "machineEnv",
55
55
  ]);
56
56
  const DYNAMIC_COLLECT_KEYS = new Set(["as", "outputSchema"]);
@@ -6,6 +6,7 @@ import { finished } from "node:stream/promises";
6
6
  import type { ExternalProcessStatus, ProcessTreeTerminal } from "../../shared/types.ts";
7
7
  import { createOwnedProcessTreeController, type OwnedProcessTreeController } from "../background/owned-process-tree.ts";
8
8
  import { omitExtensionBindingsEnv } from "./extension-bindings.ts";
9
+ import { omitGitRoutingEnv } from "./git-environment.ts";
9
10
  import {
10
11
  invalidateExternalCliPreflight,
11
12
  preflightExternalCli,
@@ -86,7 +87,8 @@ function narrowLimit(value: number | undefined, ceiling: number, label: string):
86
87
  }
87
88
 
88
89
  function externalEnvironment(allowlist: readonly string[] | undefined, values: Readonly<Record<string, string>> | undefined): NodeJS.ProcessEnv {
89
- if (!allowlist) return omitExtensionBindingsEnv(process.env);
90
+ // An adapter allowlist is a deliberate choice, so only the inherited default is filtered.
91
+ if (!allowlist) return omitGitRoutingEnv(omitExtensionBindingsEnv(process.env));
90
92
  const allowed = new Set(allowlist);
91
93
  const env: NodeJS.ProcessEnv = {};
92
94
  for (const key of allowed) {
@@ -3,6 +3,8 @@ import * as fs from "node:fs";
3
3
  import * as os from "node:os";
4
4
  import * as path from "node:path";
5
5
  import { writeAtomicJson } from "../../shared/atomic-json.ts";
6
+ import { readStatus } from "../../shared/utils.ts";
7
+ import { isActiveAsyncState } from "../background/active-run-index.ts";
6
8
  import {
7
9
  ExternalJobProviderError,
8
10
  getExternalJobProvider,
@@ -19,6 +21,7 @@ export const EXTERNAL_JOB_BRIDGE_REQUEST_DIR = "external-job-requests";
19
21
  const EXTERNAL_JOB_BRIDGE_RESPONSE_DIR = "external-job-responses";
20
22
  const DEFAULT_OPERATION_TIMEOUT_MS = 120_000;
21
23
  const POLL_INTERVAL_MS = 50;
24
+ const CHILD_BRIDGE_SWEEP_INTERVAL_MS = 1_000;
22
25
  const MAX_REQUESTS_PER_SWEEP = 100;
23
26
 
24
27
  interface ExternalJobBridgeRequest {
@@ -309,6 +312,57 @@ function readClaimHandle(provider: string, claimDir: string): ExternalJobHandle
309
312
  }
310
313
  }
311
314
 
315
+ export function externalJobBridgeEligibility(steps: unknown): "required" | "not-required" | "unknown" {
316
+ if (!Array.isArray(steps)) return "unknown";
317
+ for (const step of steps) {
318
+ const runner = (step as { runner?: unknown } | null)?.runner;
319
+ if (runner === undefined) continue;
320
+ if (!runner || typeof runner !== "object" || Array.isArray(runner)) return "unknown";
321
+ const runnerType = (runner as { type?: unknown }).type;
322
+ if (typeof runnerType !== "string") return "unknown";
323
+ if (runnerType === "external-job") return "required";
324
+ if (runnerType !== "pi" && runnerType !== "external-cli") return "unknown";
325
+ }
326
+ return "not-required";
327
+ }
328
+
329
+ /** Services the bridges of external-job runs that a child session launched; only the root has an async job tracker. */
330
+ export function createChildExternalJobBridgeSweeper() {
331
+ const runs = new Map<string, string>();
332
+ let timer: ReturnType<typeof setInterval> | undefined;
333
+ const sweep = (): number => {
334
+ for (const [runId, asyncDir] of runs) {
335
+ try {
336
+ const status = readStatus(asyncDir);
337
+ // The launch status has no runner metadata until the runner starts, so re-check on every sweep.
338
+ if (externalJobBridgeEligibility(status?.steps) !== "not-required") serviceExternalJobBridgeRequests(asyncDir);
339
+ if (status && !isActiveAsyncState(status.state)) runs.delete(runId);
340
+ } catch (error) {
341
+ console.error(`Failed to service external-job bridge requests for '${asyncDir}':`, error);
342
+ }
343
+ }
344
+ if (runs.size === 0 && timer) {
345
+ clearInterval(timer);
346
+ timer = undefined;
347
+ }
348
+ return runs.size;
349
+ };
350
+ return {
351
+ track(runId: string, asyncDir: string): void {
352
+ runs.set(runId, asyncDir);
353
+ if (timer) return;
354
+ timer = setInterval(sweep, CHILD_BRIDGE_SWEEP_INTERVAL_MS);
355
+ timer.unref?.();
356
+ },
357
+ sweep,
358
+ dispose(): void {
359
+ runs.clear();
360
+ if (timer) clearInterval(timer);
361
+ timer = undefined;
362
+ },
363
+ };
364
+ }
365
+
312
366
  export function serviceExternalJobBridgeRequests(asyncDir: string): void {
313
367
  let files: string[];
314
368
  try {
@@ -0,0 +1,29 @@
1
+ const GIT_ROUTING_VARIABLES = new Set([
2
+ "GIT_ALTERNATE_OBJECT_DIRECTORIES",
3
+ "GIT_COMMON_DIR",
4
+ "GIT_CONFIG",
5
+ "GIT_CONFIG_COUNT",
6
+ "GIT_CONFIG_PARAMETERS",
7
+ "GIT_DIR",
8
+ "GIT_GRAFT_FILE",
9
+ "GIT_IMPLICIT_WORK_TREE",
10
+ "GIT_INDEX_FILE",
11
+ "GIT_NAMESPACE",
12
+ "GIT_NO_REPLACE_OBJECTS",
13
+ "GIT_OBJECT_DIRECTORY",
14
+ "GIT_PREFIX",
15
+ "GIT_REPLACE_REF_BASE",
16
+ "GIT_SHALLOW_FILE",
17
+ "GIT_WORK_TREE",
18
+ ]);
19
+
20
+ function isGitRoutingVariable(name: string): boolean {
21
+ // Windows environment names are case-insensitive, and Git for Windows reads them that way.
22
+ const upper = name.toUpperCase();
23
+ return GIT_ROUTING_VARIABLES.has(upper) || /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(upper);
24
+ }
25
+
26
+ /** Remove inherited values that can route Git commands away from the child cwd. */
27
+ export function omitGitRoutingEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
28
+ return Object.fromEntries(Object.entries(env).filter(([name]) => !isGitRoutingVariable(name)));
29
+ }
@@ -3,6 +3,7 @@ import * as os from "node:os";
3
3
  import * as path from "node:path";
4
4
  import { findConfiguredProjectRoot } from "../../agents/agents.ts";
5
5
  import { getAgentDir, getConfigDirName, getProjectConfigDir } from "../../shared/utils.ts";
6
+ import type { McpToolPrefix } from "./mcp-direct-tool-grant.ts";
6
7
 
7
8
  const PACKAGE_CONFIG_ROOT = "npm";
8
9
  const PACKAGE_GIT_ROOT = "git";
@@ -32,11 +33,14 @@ export interface McpServerDefinition {
32
33
  exposeResources?: boolean;
33
34
  includeTools?: string[];
34
35
  excludeTools?: string[];
36
+ /** Per-server override of the global `settings.toolPrefix`, matching the adapter. */
37
+ toolPrefix?: McpToolPrefix;
35
38
  protocolVersion?: string;
36
39
  directTools?: boolean | string[];
37
40
  httpTransport?: string;
38
41
  pluginDataDir?: string;
39
42
  literalEnv?: boolean;
43
+ inheritEnv?: boolean;
40
44
  }
41
45
 
42
46
  export function isMcpServerDefinition(value: unknown): value is McpServerDefinition {
@@ -50,7 +54,7 @@ export function isMcpServerDefinition(value: unknown): value is McpServerDefinit
50
54
  for (const field of ["env", "headers"] as const) {
51
55
  if (value[field] !== undefined && !isStringRecord(value[field])) return false;
52
56
  }
53
- for (const field of ["exposeResources", "literalEnv"] as const) {
57
+ for (const field of ["exposeResources", "literalEnv", "inheritEnv"] as const) {
54
58
  if (value[field] !== undefined && typeof value[field] !== "boolean") return false;
55
59
  }
56
60
  if (value.requestHeadersCommand !== undefined && !isRequestHeadersCommand(value.requestHeadersCommand)) return false;
@@ -67,6 +67,17 @@ export interface McpRuntimeSnapshotHost {
67
67
  events: {
68
68
  emit(event: string, request: McpRuntimeSnapshotRequest): void;
69
69
  };
70
+ getAllTools?(): readonly McpHostToolInfo[];
71
+ getCommands?(): readonly { name: string; sourceInfo: { path: string } }[];
72
+ /** Pi 0.99: servers extensions added with `pi.registerMcpServer()`. */
73
+ getMcpServers?(): readonly { name: string }[];
74
+ }
75
+
76
+ /** A `pi.getAllTools()` entry; `exposure` and `namespace` exist only from Pi 0.99. */
77
+ export interface McpHostToolInfo {
78
+ name: string;
79
+ exposure?: string;
80
+ namespace?: { name: string };
70
81
  }
71
82
 
72
83
  interface CachedTool {
@@ -96,6 +107,8 @@ export interface McpDirectToolResolution {
96
107
  /** Normal loaded config plus the selected runtime server definitions. */
97
108
  mcpConfig?: McpConfig;
98
109
  runtimeServerNames?: string[];
110
+ /** Set when the selectors were resolved against Pi's built-in MCP instead of pi-mcp-adapter. */
111
+ builtin?: true;
99
112
  }
100
113
 
101
114
  export function resolveMcpDirectToolResolution(
@@ -106,6 +119,9 @@ export function resolveMcpDirectToolResolution(
106
119
  ): McpDirectToolResolution {
107
120
  const selectors = normalizeMcpDirectToolSelectors(mcpDirectTools);
108
121
  if (selectors.length === 0) return { selections: [], unresolvedSelectors: [] };
122
+ if (usesBuiltinMcp(runtimeSnapshotHost)) {
123
+ return resolveBuiltinMcpSelections(selectors, runtimeSnapshotHost.getAllTools?.() ?? []);
124
+ }
109
125
 
110
126
  const config = configOverride ?? loadMcpConfig(cwd);
111
127
  const { servers: selectedServers, tools: selectedTools } = parseMcpDirectToolSelectors(selectors);
@@ -146,6 +162,75 @@ export function resolveMcpDirectToolSelections(
146
162
  return resolveMcpDirectToolResolution(mcpDirectTools, cwd, runtimeSnapshotHost).selections;
147
163
  }
148
164
 
165
+ /**
166
+ * pi-mcp-adapter keeps priority whenever it is loaded. 2.x registers /mcp, so Pi does not load its
167
+ * built-in MCP. 3.x always registers /mcp-adapter and leaves /mcp to the built-in MCP.
168
+ */
169
+ function usesBuiltinMcp(host: McpRuntimeSnapshotHost | undefined): host is McpRuntimeSnapshotHost {
170
+ const commands = host?.getCommands?.() ?? [];
171
+ return commands.find((command) => command.name === "mcp")?.sourceInfo.path === "builtin:mcp"
172
+ && !commands.some((command) => /^mcp-adapter(?::\d+)?$/.test(command.name));
173
+ }
174
+
175
+ /**
176
+ * Pi names built-in MCP tools `mcp__<server>__<tool>` with invalid characters replaced by `_`,
177
+ * in the namespace `mcp__<server>`. An overlong name, or one an earlier tool already took (`a_b`
178
+ * before `a.b`), gets a suffix hashed from the raw server and tool (Pi's `createMcpToolName`), so
179
+ * that suffixed name identifies the tool. The unsuffixed name may belong to another raw tool; the
180
+ * child checks each granted tool's raw identity before it exposes the tool.
181
+ */
182
+ function resolveBuiltinMcpSelections(selectors: string[], tools: readonly McpHostToolInfo[]): McpDirectToolResolution {
183
+ const selections: ResolvedMcpDirectToolSelection[] = [];
184
+ const unresolvedSelectors: string[] = [];
185
+ for (const selector of selectors) {
186
+ const slash = selector.indexOf("/");
187
+ const server = slash === -1 ? selector : selector.slice(0, slash);
188
+ const inServer = tools.filter((tool) => tool.namespace?.name === `mcp__${server}`);
189
+ const toolName = slash === -1 ? undefined : builtinMcpToolNames(server, selector.slice(slash + 1)).find((name) => inServer.some((tool) => tool.name === name));
190
+ const matches = inServer.filter((tool) => tool.exposure !== "hidden" && (slash === -1 || tool.name === toolName));
191
+ if (matches.length === 0) unresolvedSelectors.push(selector);
192
+ for (const tool of matches) {
193
+ if (!selections.some((selection) => selection.name === tool.name)) selections.push({ name: tool.name, selector });
194
+ }
195
+ }
196
+ return { selections, unresolvedSelectors, builtin: true };
197
+ }
198
+
199
+ /** The names Pi's `createMcpToolName` can give a raw tool, the hash-suffixed one first. */
200
+ function builtinMcpToolNames(server: string, tool: string): string[] {
201
+ const name = `mcp__${server}__${tool}`.replace(/[^A-Za-z0-9_-]/g, "_");
202
+ const hash = createHash("sha256").update(`${server}\0${tool}`).digest("hex").slice(0, 8);
203
+ const suffixed = `${name.slice(0, 64 - hash.length - 1)}_${hash}`;
204
+ return name.length <= 64 ? [suffixed, name] : [suffixed];
205
+ }
206
+
207
+ export function formatUnresolvedBuiltinMcpSelectors(agentName: string | undefined, selectors: readonly string[]): string {
208
+ const subject = agentName ? `Agent '${agentName}'` : "Subagent";
209
+ return `${subject} selects MCP tools that Pi's built-in MCP does not offer: ${selectors.map((selector) => `mcp:${selector}`).join(", ")}. The server may be missing, disconnected, still connecting, or its tools hidden; check /mcp.`;
210
+ }
211
+
212
+ /**
213
+ * Selected servers that only an extension registered, which a child without ambient extensions
214
+ * never has. A server of the same name in an `mcp.json` the child reads takes precedence; like Pi,
215
+ * the project file is read only when the project is trusted.
216
+ */
217
+ export function extensionOnlyMcpServers(selections: readonly ResolvedMcpDirectToolSelection[], host: McpRuntimeSnapshotHost, cwd: string, projectTrusted: boolean): string[] {
218
+ const registered = new Set(host.getMcpServers?.().map(({ name }) => name));
219
+ const servers = [...new Set(selections.map(({ selector }) => selector.split("/")[0]!))].filter((server) => registered.has(server));
220
+ if (servers.length === 0) return [];
221
+ const files = [path.join(getAgentDir(), "mcp.json"), ...(projectTrusted ? [path.join(cwd, ".pi", "mcp.json")] : [])];
222
+ const configured = new Set(files.flatMap((file) => {
223
+ let parsed: unknown;
224
+ try {
225
+ parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
226
+ } catch {
227
+ return [];
228
+ }
229
+ return isRecord(parsed) && isRecord(parsed.mcpServers) ? Object.keys(parsed.mcpServers) : [];
230
+ }));
231
+ return servers.filter((server) => !configured.has(server));
232
+ }
233
+
149
234
  function loadMetadataCache(): MetadataCache | null {
150
235
  const cachePath = path.join(getAgentDir(), "mcp-cache.json");
151
236
  let parsed: unknown;
@@ -262,15 +347,17 @@ function loadMcpConfig(cwd: string): McpConfig {
262
347
  }
263
348
 
264
349
  function getConfigPaths(projectRoot: string): string[] {
265
- const piGlobalPath = path.join(getAgentDir(), "mcp.json");
266
- const projectPath = path.resolve(projectRoot, ".mcp.json");
267
- const projectPiPath = path.resolve(getProjectConfigDir(projectRoot), "mcp.json");
268
- const sources: string[] = [];
269
- if (GENERIC_GLOBAL_CONFIG_PATH !== piGlobalPath) sources.push(GENERIC_GLOBAL_CONFIG_PATH);
270
- sources.push(piGlobalPath);
271
- if (projectPath !== piGlobalPath) sources.push(projectPath);
272
- if (projectPiPath !== piGlobalPath && projectPiPath !== projectPath) sources.push(projectPiPath);
273
- return sources;
350
+ const agentDir = getAgentDir();
351
+ const projectDir = getProjectConfigDir(projectRoot);
352
+ // pi-mcp-adapter 3.x reads mcp-adapter.json. Pi's own mcp.json files belong to
353
+ // Pi's built-in MCP support, so servers there are never adapter-registered.
354
+ const candidates = [
355
+ GENERIC_GLOBAL_CONFIG_PATH,
356
+ path.join(agentDir, "mcp-adapter.json"),
357
+ path.resolve(projectRoot, ".mcp.json"),
358
+ path.join(projectDir, "mcp-adapter.json"),
359
+ ];
360
+ return [...new Set(candidates)];
274
361
  }
275
362
 
276
363
  function readConfig(configPath: string): McpConfig | null {
@@ -301,7 +388,7 @@ function parseServerEntries(value: unknown): Record<string, ServerEntry> {
301
388
 
302
389
  function parseSettings(value: unknown): McpConfig["settings"] | undefined {
303
390
  if (!isRecord(value)) return undefined;
304
- const toolPrefix = value.toolPrefix === "server" || value.toolPrefix === "short" || value.toolPrefix === "none" ? value.toolPrefix : undefined;
391
+ const toolPrefix = value.toolPrefix === "server" || value.toolPrefix === "short" || value.toolPrefix === "none" || value.toolPrefix === "mcp" ? value.toolPrefix : undefined;
305
392
  const directTools = typeof value.directTools === "boolean" ? value.directTools : undefined;
306
393
  const settings: NonNullable<McpConfig["settings"]> = {
307
394
  ...(toolPrefix ? { toolPrefix } : {}),
@@ -381,11 +468,16 @@ function isServerCacheValid(entry: ServerCacheEntry | undefined, definition: Ser
381
468
  }
382
469
 
383
470
  export function computeMcpServerHash(definition: ServerEntry): string {
471
+ // Aligned with pi-mcp-adapter's computeServerHash; since 3.1.0 stdio hashes include
472
+ // inheritEnv/literalEnv. A mismatch leaves that server's cached direct-tool selectors unresolved.
473
+ const isStdio = definition.command !== undefined;
474
+ const literalEnv = isStdio && definition.literalEnv === true;
384
475
  const identity: Record<string, unknown> = {
385
- command: definition.command,
476
+ command: resolveConfigPath(definition.command),
386
477
  args: definition.args,
387
478
  socket: resolveConfigPath(definition.socket),
388
- env: interpolateEnvRecord(definition.env),
479
+ env: literalEnv ? definition.env : interpolateEnvRecord(definition.env),
480
+ ...(isStdio ? { inheritEnv: definition.inheritEnv !== false, literalEnv } : {}),
389
481
  cwd: resolveConfigPath(definition.cwd),
390
482
  url: resolveServerUrl(definition),
391
483
  headers: interpolateEnvRecord(definition.headers),