@xzzpig/pi-subagents 0.18.0 → 0.20.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/CHANGELOG.md +129 -0
  2. package/README.md +1 -1
  3. package/docs/agents.md +32 -16
  4. package/docs/configuration.md +76 -9
  5. package/docs/extension-api.md +6 -5
  6. package/docs/missions.md +28 -14
  7. package/docs/models.md +8 -4
  8. package/docs/observability.md +10 -5
  9. package/docs/standalone-background.md +1 -1
  10. package/docs/tool-reference.md +90 -88
  11. package/docs/workflows.md +171 -173
  12. package/node_modules/@xzzpig/pi-components/package.json +4 -4
  13. package/package.json +6 -6
  14. package/prompts/review-loop.md +1 -1
  15. package/skills/council-mode/SKILL.md +1 -1
  16. package/skills/pi-subagents/SKILL.md +12 -5
  17. package/skills/pi-subagents/references/constraints-and-recipes.md +3 -3
  18. package/skills/pi-subagents/references/execution-controls.md +68 -67
  19. package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
  20. package/skills/pi-subagents/references/multi-lane-orchestration.md +1 -1
  21. package/skills/pi-subagents/references/prompting-and-roles.md +45 -48
  22. package/src/agents/advertised-agent-prompt.ts +21 -41
  23. package/src/agents/agent-management.ts +2 -2
  24. package/src/agents/agents.ts +66 -3
  25. package/src/api/preflight.ts +109 -63
  26. package/src/extension/config.ts +15 -4
  27. package/src/extension/control-notices.ts +3 -0
  28. package/src/extension/doctor.ts +1 -0
  29. package/src/extension/fanout-child.ts +12 -3
  30. package/src/extension/herdr-pi-bridge.ts +2 -0
  31. package/src/extension/index.ts +90 -174
  32. package/src/extension/public-execution.ts +72 -35
  33. package/src/extension/reply-workflow-script.ts +58 -0
  34. package/src/extension/rpc.ts +29 -10
  35. package/src/extension/schemas.ts +40 -135
  36. package/src/extension/tool-activation.ts +57 -108
  37. package/src/extension/tool-description.ts +62 -27
  38. package/src/extension/upgrade-notice.ts +40 -0
  39. package/src/integrations/herdr-status.ts +19 -3
  40. package/src/intercom/native-supervisor-channel.ts +4 -1
  41. package/src/missions/goal-driver.ts +44 -31
  42. package/src/missions/store.ts +10 -1
  43. package/src/profiles/profiles.ts +5 -2
  44. package/src/runs/background/async-execution.ts +146 -59
  45. package/src/runs/background/async-job-tracker.ts +66 -24
  46. package/src/runs/background/async-retention.ts +46 -16
  47. package/src/runs/background/await-async-run.ts +78 -0
  48. package/src/runs/background/chain-root-attachment.ts +4 -4
  49. package/src/runs/background/control-channel.ts +61 -2
  50. package/src/runs/background/notify.ts +5 -0
  51. package/src/runs/background/run-child-session.ts +17 -7
  52. package/src/runs/background/run-status.ts +6 -0
  53. package/src/runs/background/runner-aliases.ts +37 -6
  54. package/src/runs/background/runner-child-launch.ts +3 -0
  55. package/src/runs/background/scheduled-runs.ts +33 -18
  56. package/src/runs/background/stale-run-reconciler.ts +13 -2
  57. package/src/runs/background/subagent-runner.ts +58 -5
  58. package/src/runs/foreground/async-stop-action.ts +17 -3
  59. package/src/runs/foreground/command-action.ts +41 -0
  60. package/src/runs/foreground/execution.ts +145 -131
  61. package/src/runs/foreground/subagent-executor.ts +546 -296
  62. package/src/runs/shared/async-status-projection.ts +5 -0
  63. package/src/runs/shared/child-commands.ts +228 -0
  64. package/src/runs/shared/child-launch.ts +15 -2
  65. package/src/runs/shared/child-session.ts +184 -24
  66. package/src/runs/shared/child-tool-plan.ts +16 -4
  67. package/src/runs/shared/claude-code-adapter.ts +157 -2
  68. package/src/runs/shared/dynamic-fanout.ts +2 -2
  69. package/src/runs/shared/external-cli-preflight.ts +54 -6
  70. package/src/runs/shared/external-cli-runner.ts +5 -1
  71. package/src/runs/shared/mcp-config-sources.ts +2 -1
  72. package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -11
  73. package/src/runs/shared/model-resolution.ts +38 -10
  74. package/src/runs/shared/model-scope.ts +28 -9
  75. package/src/runs/shared/nested-events.ts +55 -55
  76. package/src/runs/shared/parallel-utils.ts +4 -0
  77. package/src/runs/shared/pi-spawn.ts +7 -95
  78. package/src/runs/shared/run-history.ts +87 -0
  79. package/src/runs/shared/subagent-control.ts +32 -17
  80. package/src/runs/shared/subagent-prompt-runtime.ts +14 -6
  81. package/src/runs/shared/worktree.ts +1 -1
  82. package/src/shared/disabled-features.ts +123 -0
  83. package/src/shared/extension-context.ts +13 -0
  84. package/src/shared/model-info.ts +9 -0
  85. package/src/shared/required-child-extensions.ts +39 -5
  86. package/src/shared/settings.ts +1 -1
  87. package/src/shared/types.ts +27 -1
  88. package/src/slash/prompt-template-bridge.ts +2 -2
  89. package/src/slash/slash-commands.ts +10 -5
  90. package/src/slash/subagent-cost.ts +9 -5
  91. package/src/slash/subagents-admin.ts +24 -24
  92. package/src/tui/fleet-status.ts +14 -6
  93. package/src/tui/fleet.ts +14 -2
  94. package/src/tui/render.ts +117 -56
  95. package/src/tui/running-tone.ts +28 -0
  96. package/src/watchdog/diff-tool.ts +23 -9
  97. package/src/watchdog/register-child.ts +3 -3
  98. package/src/watchdog/register-main.ts +3 -3
  99. package/src/watchdog/review.ts +2 -2
  100. package/src/watchdog/turn-delta.ts +1 -1
  101. package/src/workflows/chat-progress.ts +2 -2
  102. package/src/workflows/scripted-workflow.ts +117 -37
  103. package/src/workflows/structured-workflow-scripts.ts +177 -0
  104. package/src/workflows/workflow-checklist.ts +6 -0
  105. package/src/workflows/workflow-receipt.ts +10 -4
  106. package/src/workflows/workflow-resources.ts +44 -16
  107. package/src/workflows/workflow-reuse.ts +120 -0
  108. package/src/workflows/workflow-revival.ts +123 -0
@@ -44,6 +44,8 @@ export interface RunnerSubagentStep {
44
44
  contextLimit?: number;
45
45
  fast?: boolean;
46
46
  thinking?: string;
47
+ /** Trailing Claude Code argv for an explicit model/thinking request. */
48
+ claudeCodeOverrideArgs?: string[];
47
49
  thinkingCeiling?: import("../../shared/model-info.ts").ThinkingLevel;
48
50
  requestedModel?: string;
49
51
  /** The primary model is inherited from the parent session and should not be verified against the child-reported active registry model. */
@@ -60,6 +62,8 @@ export interface RunnerSubagentStep {
60
62
  /** Private immutable host policy snapshot serialized to the native runner. */
61
63
  requiredExtensions?: import("../../shared/required-child-extensions.ts").RequiredChildExtensionSnapshot;
62
64
  mcpDirectTools?: string[];
65
+ /** The parent's resolution of `mcpDirectTools` against Pi's built-in MCP; the runner has no host to repeat it. */
66
+ builtinMcpTools?: import("./mcp-direct-tool-grant.ts").ResolvedMcpDirectToolSelection[];
63
67
  mutationTools?: string[];
64
68
  sandbox?: string;
65
69
  permissionProfile?: string;
@@ -5,25 +5,18 @@ import { PI_CODING_AGENT_PACKAGE_ROOT_ENV } from "../../shared/utils.ts";
5
5
 
6
6
  export const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
7
7
  export const PI_SUBAGENT_PI_BINARY_ENV = "PI_SUBAGENT_PI_BINARY";
8
- export const PI_PACKAGE_DIR_ENV = "PI_PACKAGE_DIR";
9
8
 
10
- export function findPiPackageRootFromEntry(
11
- entryPoint: string,
12
- deps: Pick<PiSpawnDeps, "platform" | "existsSync" | "readFileSync"> = {},
13
- ): string | undefined {
14
- const pathApi = (deps.platform ?? process.platform) === "win32" ? path.win32 : path.posix;
15
- const existsSync = deps.existsSync ?? fs.existsSync;
16
- const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
17
- let dir = pathApi.dirname(entryPoint);
18
- while (dir !== pathApi.dirname(dir)) {
19
- const packageJsonPath = pathApi.join(dir, "package.json");
20
- if (existsSync(packageJsonPath)) {
21
- const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as {
9
+ export function findPiPackageRootFromEntry(entryPoint: string): string | undefined {
10
+ let dir = path.dirname(entryPoint);
11
+ while (dir !== path.dirname(dir)) {
12
+ const packageJsonPath = path.join(dir, "package.json");
13
+ if (fs.existsSync(packageJsonPath)) {
14
+ const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8")) as {
22
15
  name?: unknown;
23
16
  };
24
17
  if (pkg.name === PI_CODING_AGENT_PACKAGE) return dir;
25
18
  }
26
- dir = pathApi.dirname(dir);
19
+ dir = path.dirname(dir);
27
20
  }
28
21
  return undefined;
29
22
  }
@@ -64,87 +57,6 @@ export interface PiSpawnDeps {
64
57
  env?: NodeJS.ProcessEnv;
65
58
  }
66
59
 
67
- export type RunningPiPackageRoot =
68
- | { root: string; source: "argv" | "PI_PACKAGE_DIR" | "PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT" | "bun-adjacent" | "bun-share" }
69
- | { reason: string };
70
-
71
- function validateRunningPiRoot(
72
- root: string,
73
- source: Exclude<RunningPiPackageRoot, { reason: string }>["source"],
74
- readFileSync: (filePath: string, encoding: "utf-8") => string,
75
- manifestPath: string,
76
- ): RunningPiPackageRoot {
77
- const sourceLabel = source === "PI_SUBAGENTS_PI_CODING_AGENT_PACKAGE_ROOT" ? `${source} override` : source;
78
- let parsed: unknown;
79
- try {
80
- parsed = JSON.parse(readFileSync(manifestPath, "utf-8"));
81
- } catch (error) {
82
- const message = error instanceof Error ? error.message : String(error);
83
- return { reason: `Could not read a valid Pi package manifest at ${manifestPath} (${sourceLabel}): ${message}` };
84
- }
85
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || (parsed as { name?: unknown }).name !== PI_CODING_AGENT_PACKAGE) {
86
- return { reason: `${manifestPath} is not ${PI_CODING_AGENT_PACKAGE} (${sourceLabel})` };
87
- }
88
- return { root, source };
89
- }
90
-
91
- /** Resolve only package roots that can be attributed to the process that owns this session. */
92
- export function resolveRunningPiPackageRoot(deps: PiSpawnDeps = {}): RunningPiPackageRoot | undefined {
93
- const env = deps.env ?? process.env;
94
- const platform = deps.platform ?? process.platform;
95
- const pathApi = platform === "win32" ? path.win32 : path.posix;
96
- const argv1 = deps.argv1 ?? process.argv[1];
97
- const readFileSync = deps.readFileSync ?? ((filePath, encoding) => fs.readFileSync(filePath, encoding));
98
- const existsSync = deps.existsSync ?? fs.existsSync;
99
- const realpathSync = deps.realpathSync ?? fs.realpathSync;
100
-
101
- if (argv1) {
102
- let entry: string | undefined;
103
- try {
104
- entry = realpathSync(argv1);
105
- } catch {
106
- // Virtual Bun entries and non-filesystem launchers continue to explicit host evidence.
107
- }
108
- if (entry) {
109
- try {
110
- const root = findPiPackageRootFromEntry(entry, { platform, existsSync, readFileSync });
111
- if (root) return { root, source: "argv" };
112
- } catch (error) {
113
- return { reason: `Could not inspect the running Pi entry at ${entry}: ${error instanceof Error ? error.message : String(error)}` };
114
- }
115
- }
116
- }
117
-
118
- for (const [source, value] of [
119
- [PI_PACKAGE_DIR_ENV, env[PI_PACKAGE_DIR_ENV]],
120
- [PI_CODING_AGENT_PACKAGE_ROOT_ENV, env[PI_CODING_AGENT_PACKAGE_ROOT_ENV]],
121
- ] as const) {
122
- const root = value?.trim();
123
- if (root) return validateRunningPiRoot(root, source, readFileSync, pathApi.join(root, "package.json"));
124
- }
125
-
126
- const bunVersion = deps.bunVersion ?? process.versions.bun;
127
- if (!bunVersion || !argv1 || !/^(?:\/\$bunfs\/|B:[\\/]~BUN[\\/])/.test(argv1)) return undefined;
128
- const imagePath = deps.execPath ?? process.execPath;
129
- let canonicalImage = imagePath;
130
- try {
131
- canonicalImage = realpathSync(imagePath);
132
- } catch {
133
- // A validated adjacent manifest can still establish ownership when canonicalization is unavailable.
134
- }
135
- const imageDir = pathApi.dirname(canonicalImage);
136
- const candidates = [
137
- { root: imageDir, source: "bun-adjacent" as const },
138
- { root: pathApi.resolve(imageDir, "..", "share", "pi-coding-agent"), source: "bun-share" as const },
139
- ];
140
- for (const candidate of candidates) {
141
- const manifestPath = pathApi.join(candidate.root, "package.json");
142
- if (!existsSync(manifestPath)) continue;
143
- return validateRunningPiRoot(candidate.root, candidate.source, readFileSync, manifestPath);
144
- }
145
- return undefined;
146
- }
147
-
148
60
  /** Compiled Pi's entrypoint is virtual; execPath is the real (possibly renamed) image. */
149
61
  export function resolveBunPiExecutable(deps: PiSpawnDeps = {}): string | undefined {
150
62
  const bunVersion = deps.bunVersion ?? process.versions.bun;
@@ -133,6 +133,93 @@ function appendPrivateHistoryLine(historyPath: string, line: string): void {
133
133
  }
134
134
  }
135
135
 
136
+ function backgroundRunHistoryTask(steps: readonly unknown[], resultMode: string): string {
137
+ const step = steps.length === 1 && typeof steps[0] === "object" && steps[0] !== null
138
+ ? (steps[0] as { task?: unknown; launchBindingTask?: unknown })
139
+ : undefined;
140
+ if (step) {
141
+ const task = typeof step.launchBindingTask === "string" && step.launchBindingTask ? step.launchBindingTask : step.task;
142
+ if (typeof task === "string" && task) return task;
143
+ }
144
+ return resultMode || "run";
145
+ }
146
+
147
+ export interface BackgroundRunHistoryEntry {
148
+ agent: string;
149
+ task: string;
150
+ exitCode: number;
151
+ durationMs: number;
152
+ terminal: Pick<NonNullable<Parameters<typeof recordRun>[4]>, "stopped" | "interrupted" | "timedOut" | "processSignal">;
153
+ }
154
+
155
+ const TERMINAL_STEP_STATUSES = new Set(["complete", "completed"]);
156
+ /** Steps that reached THEIR OWN terminal state — run-wide flags must not relabel them. */
157
+ const SELF_TERMINAL_STEP_STATUSES = new Set(["complete", "completed", "failed", "rejected"]);
158
+
159
+ /**
160
+ * Census rows for one finished background run. Single-step runs keep the exact
161
+ * foreground shape (agent + task text). Multi-step runs record ONE ROW PER CHILD
162
+ * STEP so `loadRunsForAgent(agent)` sees every child — a composite-only row would
163
+ * stay invisible to per-agent lookups. Per-step prompts are never hashed:
164
+ * multi-step rows hash the mode label only.
165
+ *
166
+ * Fidelity rules:
167
+ * - a row is recorded only for children that actually LAUNCHED (a child
168
+ * session was dispatched). Status alone cannot decide this: `stopRunner()`,
169
+ * `timeoutRunner()`, fail-fast skips, and usage-budget skips all relabel
170
+ * never-launched steps to terminal statuses (`stopped`, `failed`+`timedOut,
171
+ * `failed`+`skipped) before the run ends — the runner therefore threads an
172
+ * explicit `launched` fact per step. `pending` and `launched: false` steps
173
+ * get no row — unrun agents must not accumulate attempts or failures;
174
+ * - run-level terminal flags (stopped/interrupted/timedOut) apply only to steps
175
+ * that did not reach a terminal state of their own — a child that completed
176
+ * or failed BEFORE a sibling was interrupted keeps its own outcome, because
177
+ * recordRun() lets those flags override the exit code;
178
+ * - self-terminal steps carry their own timedOut/stopped flags instead.
179
+ */
180
+ export function planBackgroundRunHistory(input: {
181
+ steps: readonly unknown[];
182
+ resultMode: string;
183
+ statusSteps: ReadonlyArray<{ agent?: unknown; status?: unknown; durationMs?: number; timedOut?: boolean; stopped?: boolean; launched?: boolean }>;
184
+ stepResults?: ReadonlyArray<{ processSignal?: unknown } | undefined>;
185
+ runDurationMs: number;
186
+ stopped?: boolean;
187
+ interrupted?: boolean;
188
+ timedOut?: boolean;
189
+ }): BackgroundRunHistoryEntry[] {
190
+ const runTerminal: BackgroundRunHistoryEntry["terminal"] = {
191
+ ...(input.stopped ? { stopped: true } : {}),
192
+ ...(input.interrupted ? { interrupted: true } : {}),
193
+ ...(input.timedOut ? { timedOut: true } : {}),
194
+ };
195
+ const task = backgroundRunHistoryTask(input.steps, input.resultMode);
196
+ const rows: BackgroundRunHistoryEntry[] = [];
197
+ for (const [index, step] of input.statusSteps.entries()) {
198
+ if (typeof step.agent !== "string" || !step.agent) continue;
199
+ // `launched === false` marks steps the runner never dispatched a child
200
+ // session for, regardless of the status they were later relabeled to.
201
+ if (step.status === "pending" || step.launched === false) continue;
202
+ const succeeded = typeof step.status === "string" && TERMINAL_STEP_STATUSES.has(step.status);
203
+ const ownTerminal: BackgroundRunHistoryEntry["terminal"] = {
204
+ ...(step.timedOut === true ? { timedOut: true } : {}),
205
+ ...(step.stopped === true ? { stopped: true } : {}),
206
+ };
207
+ // A step that reached its own terminal state (completed, or failed/rejected
208
+ // before a sibling was interrupted) keeps its own outcome; run-wide flags
209
+ // would relabel it in recordRun().
210
+ const terminal = typeof step.status === "string" && SELF_TERMINAL_STEP_STATUSES.has(step.status) ? ownTerminal : { ...runTerminal, ...ownTerminal };
211
+ const processSignal = input.stepResults?.[index]?.processSignal;
212
+ rows.push({
213
+ agent: step.agent,
214
+ task,
215
+ exitCode: succeeded ? 0 : 1,
216
+ durationMs: typeof step.durationMs === "number" ? step.durationMs : input.runDurationMs,
217
+ terminal: processSignal === undefined ? terminal : { ...terminal, processSignal: typeof processSignal === "string" ? processSignal : null },
218
+ });
219
+ }
220
+ return rows;
221
+ }
222
+
136
223
  export function recordRun(
137
224
  agent: string,
138
225
  task: string,
@@ -190,7 +190,8 @@ export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: C
190
190
  export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
191
191
  const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
192
192
  const contextHash = createHash("sha256").update(formatControlNudge(event)).digest("hex").slice(0, 8);
193
- return `${childKey}:${event.type}:${event.reason ?? "idle"}:${contextHash}`;
193
+ const callKey = event.reason === "tool_open_threshold" && event.toolCallId ? `:${event.toolCallId}` : "";
194
+ return `${childKey}:${event.type}:${event.reason ?? "idle"}${callKey}:${contextHash}`;
194
195
  }
195
196
 
196
197
  export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
@@ -228,42 +229,56 @@ export function formatControlNoticeMessage(event: ControlEvent, childIntercomTar
228
229
  const nudgeMessage = formatControlNudge(event);
229
230
  const steerCommand = `subagent({ action: "steer", id: "${runTarget}", ${event.index !== undefined ? `index: ${event.index}, ` : ""}message: ${JSON.stringify(nudgeMessage)} })`;
230
231
  const nestedResumeCommand = `subagent({ action: "resume", id: "${runTarget}", message: ${JSON.stringify(nudgeMessage)} })`;
232
+ const facts = formatLongRunningFacts(event);
233
+ const head = (title: string) => [
234
+ `${title}: ${event.agent}`,
235
+ `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
236
+ `Signal: ${event.message}`,
237
+ facts ? `Facts: ${facts}` : undefined,
238
+ ];
239
+ const status = `Status: subagent({ action: "status", id: "${runTarget}" })`;
240
+ const lines = (items: Array<string | undefined>) => items.filter((line): line is string => Boolean(line)).join("\n");
231
241
  if (event.type === "active_long_running") {
232
- const facts = formatLongRunningFacts(event);
233
- return [
234
- `Subagent active but long-running: ${event.agent}`,
235
- `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
236
- `Signal: ${event.message}`,
237
- facts ? `Facts: ${facts}` : undefined,
242
+ return lines([
243
+ ...head("Subagent active but long-running"),
238
244
  "Hint: Inspect status first. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
239
245
  `Top-level live async nudge: ${steerCommand}`,
240
246
  `Routed live nested nudge: ${nestedResumeCommand}`,
241
247
  childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
242
- `Status: subagent({ action: "status", id: "${runTarget}" })`,
248
+ status,
243
249
  `Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
244
- ].filter((line): line is string => Boolean(line)).join("\n");
250
+ ]);
251
+ }
252
+
253
+ if (event.reason === "tool_open_threshold" && event.currentTool === "bash") {
254
+ const command = (label: string, action: string) => `${label}: subagent(${JSON.stringify({ action, id: runTarget, ...(event.index !== undefined ? { index: event.index } : {}), toolCallId: event.toolCallId })})`;
255
+ return lines([
256
+ ...head("Subagent needs attention"),
257
+ "Hint: Inspect the running command and recent output before nudging. A queued steer does not cancel an in-flight bash call. A dev server or watch command may intentionally never return. Elapsed time alone does not prove the command is stuck.",
258
+ "Recovery: For a local Pi child explicitly granted subagent_command, yield a needed persistent command or cancel the exact incorrect command, then steer the child. Query command.status to confirm the result. If command controls are unavailable, inspect partial changes and interruption scope before interrupt/resume; interrupt is run-scoped and may affect siblings.",
259
+ ...(event.toolCallId ? [command("Command", "command.status"), command("Yield", "command.yield"), command("Cancel", "command.cancel")] : []),
260
+ status,
261
+ `Transcript: subagent({ action: "status", id: "${runTarget}", view: "transcript"${event.index !== undefined ? `, index: ${event.index}` : ""} })`,
262
+ ]);
245
263
  }
246
264
 
247
265
  const supervisorHint = event.reason === "supervisor_request"
248
266
  ? "Supervisor request: reply to the pending request. If subagent_supervisor pending is empty, check intercom pending because an external intercom tool may own the request."
249
267
  : undefined;
250
- const facts = formatLongRunningFacts(event);
251
- return [
252
- `Subagent needs attention: ${event.agent}`,
253
- `Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
254
- `Signal: ${event.message}`,
255
- facts ? `Facts: ${facts}` : undefined,
268
+ return lines([
269
+ ...head("Subagent needs attention"),
256
270
  event.recentFailureSummary ? `Recent failures: ${event.recentFailureSummary}` : undefined,
257
271
  supervisorHint,
258
272
  "Hint: Inspect status first unless the run is clearly blocked. Use steer for a top-level live async child, routed resume for a live nested child, or resume to revive a paused/completed/failed child.",
259
273
  `Top-level live async nudge: ${steerCommand}`,
260
274
  `Routed live nested nudge: ${nestedResumeCommand}`,
261
275
  childIntercomTarget ? `Direct intercom target: ${childIntercomTarget}` : undefined,
262
- `Status: subagent({ action: "status", id: "${runTarget}" })`,
276
+ status,
263
277
  `Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
264
- ].filter((line): line is string => Boolean(line)).join("\n");
278
+ ]);
265
279
  }
266
280
 
281
+
267
282
  export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
268
283
  const statusLabel = event.type === "active_long_running"
269
284
  ? "subagent active but long-running"
@@ -22,6 +22,7 @@ import { captureWatchdogDiffBaseline, createWatchdogDiffTool, WATCHDOG_DIFF_TOOL
22
22
  import { inheritedNestedRouteOf } from "./nested-events.ts";
23
23
  import { registerWaitTool } from "../background/wait-tool.ts";
24
24
  import { drainOutstandingWork } from "../background/auto-drain.ts";
25
+ import { MODEL_ONLY_TOOL } from "../../shared/extension-context.ts";
25
26
  import {
26
27
  childSupervisorMetadata,
27
28
  evaluateChildToolDiagnostic,
@@ -266,17 +267,22 @@ export function rewriteForkCacheProviderRequest(event: BeforeProviderRequestEven
266
267
  return { ...payload, prompt_cache_key: key };
267
268
  }
268
269
 
269
- function portableToolId(id: string): string {
270
+ function portableToolId(id: string, preserveBoundedCompositeToolIds = false): string {
270
271
  if (PORTABLE_TOOL_ID_PATTERN.test(id) && id.length <= MAX_PORTABLE_TOOL_ID_LENGTH) return id;
272
+ // Codex splits call_id|item_id on replay; each wire ID must remain portable and bounded.
273
+ if (preserveBoundedCompositeToolIds) {
274
+ const parts = id.split("|");
275
+ if (parts.length === 2 && parts.every((part) => PORTABLE_TOOL_ID_PATTERN.test(part) && part.length <= MAX_PORTABLE_TOOL_ID_LENGTH)) return id;
276
+ }
271
277
  const encoded = `tool_${Buffer.from(id).toString("base64url") || "empty"}`;
272
278
  if (encoded.length <= MAX_PORTABLE_TOOL_ID_LENGTH) return encoded;
273
279
  return `tool_${createHash("sha256").update(id).digest("base64url")}`;
274
280
  }
275
281
 
276
- function sanitizeToolHistoryMessage(message: unknown): unknown {
282
+ function sanitizeToolHistoryMessage(message: unknown, preserveBoundedCompositeToolIds = false): unknown {
277
283
  const m = message as { role?: string; content?: unknown; toolCallId?: unknown };
278
284
  if (m?.role === "toolResult" && typeof m.toolCallId === "string") {
279
- const toolCallId = portableToolId(m.toolCallId);
285
+ const toolCallId = portableToolId(m.toolCallId, preserveBoundedCompositeToolIds);
280
286
  return toolCallId === m.toolCallId ? message : { ...m, toolCallId };
281
287
  }
282
288
  if (m?.role !== "assistant" || !Array.isArray(m.content)) return message;
@@ -284,7 +290,7 @@ function sanitizeToolHistoryMessage(message: unknown): unknown {
284
290
  const content = m.content.map((block) => {
285
291
  const b = block as { type?: string; id?: unknown };
286
292
  if (b?.type !== "toolCall" || typeof b.id !== "string") return block;
287
- const id = portableToolId(b.id);
293
+ const id = portableToolId(b.id, preserveBoundedCompositeToolIds);
288
294
  if (id === b.id) return block;
289
295
  changed = true;
290
296
  return { ...b, id };
@@ -301,7 +307,7 @@ function stripAssistantSubagentToolCallBlocks(message: unknown): unknown | undef
301
307
  return { ...m, content: filteredContent };
302
308
  }
303
309
 
304
- export function stripParentOnlySubagentMessages(messages: unknown[], options: { sanitizeToolIds?: boolean; preserveFanoutToolHistory?: boolean } = {}): unknown[] {
310
+ export function stripParentOnlySubagentMessages(messages: unknown[], options: { sanitizeToolIds?: boolean; preserveBoundedCompositeToolIds?: boolean; preserveFanoutToolHistory?: boolean } = {}): unknown[] {
305
311
  const preserveCurrentFanoutToolHistory = options.preserveFanoutToolHistory === true;
306
312
  const sanitizeToolIds = options.sanitizeToolIds ?? true;
307
313
  let changed = false;
@@ -316,7 +322,7 @@ export function stripParentOnlySubagentMessages(messages: unknown[], options: {
316
322
  changed = true;
317
323
  continue;
318
324
  }
319
- const sanitized = sanitizeToolIds ? sanitizeToolHistoryMessage(stripped) : stripped;
325
+ const sanitized = sanitizeToolIds ? sanitizeToolHistoryMessage(stripped, options.preserveBoundedCompositeToolIds === true) : stripped;
320
326
  if (stripped !== message || sanitized !== stripped) changed = true;
321
327
  filtered.push(sanitized);
322
328
  }
@@ -417,6 +423,7 @@ function registerStructuredOutputTool(pi: ExtensionAPI, structured: NonNullable<
417
423
  }) => void;
418
424
  registerTool({
419
425
  name: "structured_output",
426
+ ...MODEL_ONLY_TOOL,
420
427
  label: "Structured Output",
421
428
  description: "Submit the required final structured output for this subagent step. This terminates the step.",
422
429
  parameters,
@@ -522,6 +529,7 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI, config?:
522
529
  if (!event || typeof event !== "object" || !("messages" in event) || !Array.isArray(event.messages)) return undefined;
523
530
  const messages = stripParentOnlySubagentMessages(event.messages, {
524
531
  sanitizeToolIds: !COMPOSITE_TOOL_ID_APIS.has(ctx?.model?.api ?? ""),
532
+ preserveBoundedCompositeToolIds: ctx?.model?.api === "openai-codex-responses",
525
533
  preserveFanoutToolHistory: config.fanoutChild,
526
534
  });
527
535
  if (messages === event.messages) return undefined;
@@ -20,7 +20,7 @@ const WORKTREE_NAMING_BRANCH_MAX_BYTES = 256;
20
20
  const WORKTREE_COMMAND_OUTPUT_MAX_BYTES = 128 * 1024;
21
21
  const WORKTRUNK_COMMAND = process.platform === "win32" ? "git" : "wt";
22
22
  const WORKTRUNK_ARG_PREFIX = process.platform === "win32" ? ["wt"] : [];
23
- export const MACHINE_DIFF_OPTIONS = ["--no-color", "--no-ext-diff", "--no-textconv", "--default-prefix", "--line-prefix=", "--no-relative"] as const;
23
+ export const MACHINE_DIFF_OPTIONS = ["--no-color", "--no-ext-diff", "--no-textconv", "--src-prefix=a/", "--dst-prefix=b/", "--line-prefix=", "--no-relative"] as const;
24
24
  const MACHINE_PATCH_OPTIONS = [...MACHINE_DIFF_OPTIONS, "--binary"] as const;
25
25
  const PATCH_VALIDATION_OPTIONS = ["apply", "--check", "--cached", "--reverse", "--binary", "--whitespace=nowarn"] as const;
26
26
 
@@ -0,0 +1,123 @@
1
+ /**
2
+ * Opt-in feature groups an operator can remove from the parent-facing `subagent` tool.
3
+ * Groups own parameters and actions that enabled features do not need, so hiding them
4
+ * cannot remove a field that enabled behavior still needs. `preflight` is the one shared
5
+ * parameter: it is script-only, so `workflow-scripts` removes it too. Per-call options
6
+ * disable only the per-call override; configured defaults keep applying.
7
+ */
8
+ export const SUBAGENT_FEATURES = {
9
+ "agent-management": {
10
+ actions: ["create", "update", "delete", "eject", "disable", "enable", "reset", "refine", "refine.show", "refine.rollback"],
11
+ params: ["config"],
12
+ },
13
+ watchdog: {
14
+ actions: ["watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model"],
15
+ params: ["scope", "target", "thinking"],
16
+ },
17
+ panes: {
18
+ actions: ["inspector.open", "inspector.command", "inspector.status", "inspector.close", "project.open", "project.status", "project.close"],
19
+ params: ["focus"],
20
+ },
21
+ missions: {
22
+ actions: ["mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close"],
23
+ params: ["mission", "missionUpdate", "missionStatus", "missionScope", "missionId", "runMode", "runStatus", "summary"],
24
+ },
25
+ "lane-management": {
26
+ actions: ["lane.status", "lane.recordMerge", "lane.recordSupersession", "worktree.discard", "worktree.cleanup"],
27
+ params: ["handoffPath", "laneId", "merge", "supersession", "repo", "planId"],
28
+ },
29
+ "spawn-budget-grants": { actions: ["grant-spawn-budget"], params: ["additional"] },
30
+ preflight: { actions: [], params: ["preflight"] },
31
+ "lane-metadata": { actions: [], params: ["lane"] },
32
+ gates: { actions: [], params: ["gate"] },
33
+ "usage-budgets": { actions: [], params: ["usageBudget"] },
34
+ "tool-budgets": { actions: [], params: ["toolBudget"] },
35
+ "control-overrides": { actions: [], params: ["control"] },
36
+ "extension-bindings": { actions: [], params: ["extensionBindings"] },
37
+ "external-machines": { actions: [], params: ["machine"] },
38
+ "workflow-scripts": { actions: ["validate"], params: ["workflow", "args", "preflight", "globalConcurrencyLimit", "maxSubagentSpawnsPerRun"] },
39
+ } as const satisfies Record<string, { actions: readonly string[]; params: readonly string[] }>;
40
+
41
+ export type SubagentFeature = keyof typeof SUBAGENT_FEATURES;
42
+
43
+ /** Schedules are turned off by `scheduledRuns.enabled: false`, not by `disabledFeatures`. */
44
+ export type SubagentSurfaceFeature = SubagentFeature | "schedules";
45
+
46
+ const SCHEDULE_SURFACE = {
47
+ actions: ["schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"],
48
+ params: ["name", "at", "every", "sessionOnly", "quiet", "on", "timezone", "overlap", "catchUp"],
49
+ } as const;
50
+
51
+ export function validateDisabledFeatures(value: unknown): void {
52
+ if (value === undefined) return;
53
+ if (!Array.isArray(value)) throw new Error("config.disabledFeatures must be an array of feature names");
54
+ const seen = new Set<string>();
55
+ for (const entry of value) {
56
+ if (entry === "schedules") throw new Error(`config.disabledFeatures does not accept "schedules"; set config.scheduledRuns.enabled to false instead`);
57
+ if (typeof entry !== "string" || !Object.hasOwn(SUBAGENT_FEATURES, entry)) {
58
+ throw new Error(`config.disabledFeatures entry ${JSON.stringify(entry)} is not one of: ${Object.keys(SUBAGENT_FEATURES).join(", ")}`);
59
+ }
60
+ if (seen.has(entry)) throw new Error(`config.disabledFeatures lists "${entry}" more than once`);
61
+ seen.add(entry);
62
+ }
63
+ }
64
+
65
+ /** Disabled features, and each disabled parameter and action mapped to the setting that disabled it. */
66
+ export interface DisabledFeatureSurface {
67
+ features: ReadonlySet<SubagentSurfaceFeature>;
68
+ params: ReadonlyMap<string, string>;
69
+ actions: ReadonlyMap<string, string>;
70
+ }
71
+
72
+ interface FeatureConfig {
73
+ disabledFeatures?: readonly SubagentFeature[];
74
+ scheduledRuns?: { enabled?: boolean };
75
+ }
76
+
77
+ function featureSurface(feature: SubagentSurfaceFeature): { actions: readonly string[]; params: readonly string[]; disabledBy: string } {
78
+ if (feature === "schedules") return { ...SCHEDULE_SURFACE, disabledBy: "scheduledRuns.enabled=false" };
79
+ return { ...SUBAGENT_FEATURES[feature], disabledBy: `disabledFeatures "${feature}"` };
80
+ }
81
+
82
+ export function resolveDisabledFeatureSurface(config: FeatureConfig): DisabledFeatureSurface {
83
+ const features = new Set<SubagentSurfaceFeature>(config.disabledFeatures);
84
+ if (config.scheduledRuns?.enabled === false) features.add("schedules");
85
+ const params = new Map<string, string>();
86
+ const actions = new Map<string, string>();
87
+ for (const feature of features) {
88
+ const surface = featureSurface(feature);
89
+ // A parameter shared with workflow-scripts is always attributed to workflow-scripts,
90
+ // whatever order the config lists the features in.
91
+ for (const param of surface.params) if (feature === "workflow-scripts" || !params.has(param)) params.set(param, surface.disabledBy);
92
+ for (const action of surface.actions) actions.set(action, surface.disabledBy);
93
+ }
94
+ return { features, params, actions };
95
+ }
96
+
97
+ /** Returns why a request uses a disabled feature, or undefined when every requested field is enabled. */
98
+ export function disabledFeatureUseError(request: object, surface: DisabledFeatureSurface, label = "subagent"): string | undefined {
99
+ const params = request as Record<string, unknown>;
100
+ const action = typeof params.action === "string" ? params.action.trim() : undefined;
101
+ const disabledAction = action === undefined ? undefined : surface.actions.get(action);
102
+ if (disabledAction) return `${label} action '${action}' is disabled by config ${disabledAction}.`;
103
+ for (const [param, disabledBy] of surface.params) {
104
+ if (params[param] !== undefined) return `${label} option '${param}' is disabled by config ${disabledBy}.`;
105
+ }
106
+ // workflowScript is the internal carrier for slash, prompt-workflow, RPC, and scheduled scripts.
107
+ // Callers check the original request, before the package lowers chain/tasks into its own script.
108
+ if (params.workflowScript !== undefined && surface.features.has("workflow-scripts")) {
109
+ return `${label} workflow scripts are disabled by config ${featureSurface("workflow-scripts").disabledBy}.`;
110
+ }
111
+ return undefined;
112
+ }
113
+
114
+ /** Lists what config disabled, for prepending to static reference docs that describe the full tool. */
115
+ export function disabledFeatureNotice(surface: DisabledFeatureSurface): string | undefined {
116
+ if (surface.features.size === 0) return undefined;
117
+ const lines = [...surface.features].map((feature) => {
118
+ const { actions, params, disabledBy } = featureSurface(feature);
119
+ const parts = [`options ${params.join(", ")}`, ...(actions.length > 0 ? [`actions ${actions.join(", ")}`] : [])];
120
+ return `- ${disabledBy}: ${parts.join("; ")}`;
121
+ });
122
+ return `Disabled by config in this session. The reference below still lists these, but calls that use them are rejected:\n${lines.join("\n")}`;
123
+ }
@@ -1,11 +1,24 @@
1
1
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
2
2
 
3
+ /**
4
+ * Declares a tool to the model but keeps it out of codemode scripts and other `ctx.executeTool()`
5
+ * callers. These tools need model-issued calls: nested calls hide their progress, block the script
6
+ * on supervisor replies, and drop `terminate`. Pi 0.99 reads `exposure`; the pinned SDK types
7
+ * predate it and older hosts ignore it.
8
+ */
9
+ export const MODEL_ONLY_TOOL = { exposure: "model-only" } as const;
10
+
3
11
  /** Pi exposes replaced extension contexts as ordinary Errors without a stable code. */
4
12
  export function isStaleExtensionContextError(error: unknown): boolean {
5
13
  return error instanceof Error
6
14
  && /extension ctx is stale|extension context no longer active|stale after session replacement or reload/i.test(error.message);
7
15
  }
8
16
 
17
+ /** Pi throws this from action methods while extensions are still loading, before it binds the runtime. */
18
+ export function isUnboundExtensionRuntimeError(error: unknown): boolean {
19
+ return error instanceof Error && /extension runtime not initialized/i.test(error.message);
20
+ }
21
+
9
22
  /** Run a synchronous operation against a cached UI context without leaking replacement errors. */
10
23
  export function withCachedUiContext<T>(
11
24
  ctx: ExtensionContext | null | undefined,
@@ -60,6 +60,15 @@ export function resolveEffectiveThinking(model: string | undefined, configThinki
60
60
  return THINKING_LEVELS.find((level) => level === configThinking);
61
61
  }
62
62
 
63
+ /** The recorded thinking level of one child: the first known level among the places it is recorded. */
64
+ export function childThinkingLevel(...sources: Array<{ thinking?: string } | undefined>): ThinkingLevel | undefined {
65
+ for (const source of sources) {
66
+ const level = THINKING_LEVELS.find((candidate) => candidate === source?.thinking);
67
+ if (level) return level;
68
+ }
69
+ return undefined;
70
+ }
71
+
63
72
  export function splitKnownThinkingSuffix(model: string): { baseModel: string; thinkingSuffix: string } {
64
73
  const colonIdx = model.lastIndexOf(":");
65
74
  if (colonIdx === -1) return { baseModel: model, thinkingSuffix: "" };