@xzzpig/pi-subagents 0.18.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 (95) hide show
  1. package/CHANGELOG.md +69 -0
  2. package/README.md +1 -1
  3. package/docs/agents.md +18 -12
  4. package/docs/configuration.md +66 -9
  5. package/docs/extension-api.md +5 -4
  6. package/docs/missions.md +13 -13
  7. package/docs/models.md +2 -2
  8. package/docs/observability.md +2 -2
  9. package/docs/standalone-background.md +1 -1
  10. package/docs/tool-reference.md +63 -86
  11. package/docs/workflows.md +170 -172
  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 +7 -0
  25. package/src/api/preflight.ts +67 -62
  26. package/src/extension/config.ts +12 -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 +68 -159
  32. package/src/extension/public-execution.ts +69 -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 +36 -133
  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/runs/background/async-execution.ts +58 -53
  42. package/src/runs/background/async-job-tracker.ts +63 -22
  43. package/src/runs/background/async-retention.ts +46 -16
  44. package/src/runs/background/await-async-run.ts +76 -0
  45. package/src/runs/background/chain-root-attachment.ts +4 -4
  46. package/src/runs/background/control-channel.ts +18 -2
  47. package/src/runs/background/notify.ts +5 -0
  48. package/src/runs/background/run-child-session.ts +4 -1
  49. package/src/runs/background/run-status.ts +6 -0
  50. package/src/runs/background/runner-aliases.ts +30 -2
  51. package/src/runs/background/runner-child-launch.ts +3 -0
  52. package/src/runs/background/scheduled-runs.ts +5 -5
  53. package/src/runs/background/subagent-runner.ts +15 -1
  54. package/src/runs/foreground/async-stop-action.ts +17 -3
  55. package/src/runs/foreground/execution.ts +130 -125
  56. package/src/runs/foreground/subagent-executor.ts +487 -288
  57. package/src/runs/shared/async-status-projection.ts +5 -0
  58. package/src/runs/shared/child-launch.ts +15 -2
  59. package/src/runs/shared/child-session.ts +92 -6
  60. package/src/runs/shared/child-tool-plan.ts +15 -3
  61. package/src/runs/shared/dynamic-fanout.ts +1 -1
  62. package/src/runs/shared/mcp-config-sources.ts +2 -1
  63. package/src/runs/shared/mcp-direct-tool-allowlist.ts +103 -11
  64. package/src/runs/shared/model-resolution.ts +29 -9
  65. package/src/runs/shared/model-scope.ts +28 -9
  66. package/src/runs/shared/nested-events.ts +55 -55
  67. package/src/runs/shared/parallel-utils.ts +2 -0
  68. package/src/runs/shared/pi-spawn.ts +7 -95
  69. package/src/runs/shared/subagent-prompt-runtime.ts +2 -0
  70. package/src/runs/shared/worktree.ts +1 -1
  71. package/src/shared/disabled-features.ts +123 -0
  72. package/src/shared/extension-context.ts +13 -0
  73. package/src/shared/model-info.ts +9 -0
  74. package/src/shared/settings.ts +1 -1
  75. package/src/shared/types.ts +21 -0
  76. package/src/slash/prompt-template-bridge.ts +2 -2
  77. package/src/slash/slash-commands.ts +10 -5
  78. package/src/slash/subagents-admin.ts +24 -24
  79. package/src/tui/fleet-status.ts +14 -6
  80. package/src/tui/fleet.ts +14 -2
  81. package/src/tui/render.ts +113 -52
  82. package/src/tui/running-tone.ts +28 -0
  83. package/src/watchdog/diff-tool.ts +23 -9
  84. package/src/watchdog/register-child.ts +3 -3
  85. package/src/watchdog/register-main.ts +3 -3
  86. package/src/watchdog/review.ts +2 -2
  87. package/src/watchdog/turn-delta.ts +1 -1
  88. package/src/workflows/chat-progress.ts +2 -2
  89. package/src/workflows/scripted-workflow.ts +117 -37
  90. package/src/workflows/structured-workflow-scripts.ts +177 -0
  91. package/src/workflows/workflow-checklist.ts +6 -0
  92. package/src/workflows/workflow-receipt.ts +8 -2
  93. package/src/workflows/workflow-resources.ts +37 -12
  94. package/src/workflows/workflow-reuse.ts +120 -0
  95. package/src/workflows/workflow-revival.ts +123 -0
@@ -2,46 +2,77 @@ import * as fs from "node:fs";
2
2
  import * as path from "node:path";
3
3
  import type { ExtensionConfig, ToolDescriptionMode } from "../shared/types.ts";
4
4
  import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
5
+ import { resolveDisabledFeatureSurface, type DisabledFeatureSurface, type SubagentSurfaceFeature } from "../shared/disabled-features.ts";
5
6
 
6
7
  const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
7
8
  const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
8
9
  const AGENT_SELECTION_GUIDANCE = 'First call {action:"list",capabilities:true}: executable, non-disabled agents only; external-cli requires runner.available === true. Passive PATH/PATHEXT/X_OK is not authentication/version/launch proof; preflight is authoritative.';
9
10
  const SUBAGENT_FAILURE_RECOVERY_GUIDANCE = "Workflow, child launch, prompt runtime, extension load or child tooling failure is a lane infrastructure blocker. Stop; report exact failure, run/status and repo/cwd/worktree/branch/ref; verify clean worktree or capture partial diff before same-protocol retry or asking the owner. Never silently switch to interactive_shell, pi -ne, Codex/Claude/Cursor CLI or foreground/external mode: governed-workflow fallback requires explicit owner approval, not Pi core's generic pi -ne hint. Explicit foreground/CLI requests and work outside that protocol remain valid.";
10
11
 
11
- export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
12
+ type FeatureText = (feature: SubagentSurfaceFeature, text: string, disabledText?: string) => string;
13
+
14
+ function featureText(disabled: DisabledFeatureSurface): FeatureText {
15
+ return (feature, text, disabledText = "") => disabled.features.has(feature) ? disabledText : text;
16
+ }
17
+
18
+ const safetyGuidance = (on: FeatureText) => `SAFETY-CRITICAL SUBAGENT GUIDANCE:
12
19
  • Direct parent execution is the default. Invoke subagents only when delegation is authorized by the operator's current request or applicable user/project instructions; task size, complexity, risk, tool-call count, or recipe fit do not independently authorize delegation.
13
20
  • ${AGENT_SELECTION_GUIDANCE}
14
21
  • ${SUBAGENT_FAILURE_RECOVERY_GUIDANCE}
15
- • Omit action for execution. For an authorized delegated multi-step/parallel workflow: exactly one top-level subagent workflow call with async:true; children launch only inside it.
22
+ • Omit action for execution. For an authorized delegated multi-step/parallel workflow: exactly one top-level subagent ${on("workflow-scripts", "workflow call with async:true; children launch only inside it", "chain or tasks call with async:true")}.
16
23
  • Async follows asyncByDefault (normally true); async:false only to block the parent, not for final reviews/gates. Consume results at dependency barriers. Native async completion wakes this session: return control, no sleep/poll or bg_wait merely for a wake. bg_wait is for provider/detached work without native notification needing a same-turn result.
17
24
  • Ordinary child subagents are not orchestrators; only configured fanout within depth/session limits. For an authorized delegated workflow, keep one writer per cwd/worktree and isolate concurrent writers. Use fresh-context read-only reviewers when independent review was requested, then parent synthesis/fixes. Oracle/advisor unknowns use supervisor dialogue; one-shot only when requested.
18
- • Bind durable output on runs.run/runs.all, not task filename prose; return actual outputReference/outputPathMapping/artifactPaths, evidence and residual risks.
19
- • children.list is workflow-only, not an exhaustive list of direct native children: resume only resumable rows. When an intended child's exact run id is known, inspect it with {action:"status",id}; if status identifies the candidate, attempt {action:"resume",id,message}. Resume authoritatively checks eligibility, may reject it, and otherwise detaches a follow-up/challenge with the stored agent/model/tool contract. Use a labeled same-role fallback only when no known candidate exists or resume rejects eligibility. Scripts await runs.run(newKey,{resume:runId,task}); continue from latest returned runId. Each distinct resume pass needs a new stable key; same-key reuse requires identical launch parameters.
20
- • Named resources own authority; raw workflowScript/workflowScriptPath cannot use runs.host. Granted commands/relative outputs use workflow cwd, never per-step cwd.
21
- • Inspect asyncId/asyncDir (status.json, events.jsonl, logs) with status/debug.run; control with interrupt/stop/resume/steer. Read {action:"guide",topic:"tool-reference"} for controls/evidence gates.`;
25
+ • Bind durable output ${on("workflow-scripts", "on runs.run/runs.all", "with output")}, not task filename prose; return actual outputReference/outputPathMapping/artifactPaths, evidence and residual risks.
26
+ • children.list is workflow-only, not an exhaustive list of direct native children: resume only resumable rows. When an intended child's exact run id is known, inspect it with {action:"status",id}; if status identifies the candidate, attempt {action:"resume",id,message}. Resume authoritatively checks eligibility, may reject it, and otherwise detaches a follow-up/challenge with the stored agent/model/tool contract. Use a labeled same-role fallback only when no known candidate exists or resume rejects eligibility.${on("workflow-scripts", " Scripts await runs.run(newKey,{resume:runId,task}); continue from latest returned runId. Each distinct resume pass needs a new stable key; same-key reuse requires identical launch parameters.")}
27
+ ${on("workflow-scripts", "• Named resources own authority; raw scripts (workflow:true or a path) cannot use runs.host. Granted commands/relative outputs use workflow cwd, never per-step cwd.\n")}• Inspect asyncId/asyncDir (status.json, events.jsonl, logs) with status/debug.run; control with interrupt/stop/resume/steer. Read {action:"guide",topic:"tool-reference"} for controls/evidence gates.`;
22
28
 
23
- const EXECUTION_GUIDANCE = `Delegate one child with {agent,task?}; otherwise choose exactly one of {workflowScript,args?}, {workflowScriptPath,args?} or {workflow,args}. agent/task exclude workflow inputs; task excludes action. agent may target management actions. action is management/control; validate accepts either script without launching. workflowScriptPath loads from request cwd before sandbox execution.
29
+ const scriptExecutionGuidance = (on: FeatureText) => `Delegate one child with {agent,task?}; otherwise set exactly one workflow source, with optional args.
30
+ Workflow script: write it as one \`\`\`js workflow block in this reply, then call subagent({workflow:true,...}). workflow:'./path.js' (any value with '/') loads a file from request cwd; other strings name a resource.
31
+ agent/task exclude workflow; task excludes action. agent may target management actions. action is management/control; validate accepts workflow:true or a path without launching.
24
32
  Scripts: JavaScript statement bodies with explicit return, top-level await, plain helpers/Promise chains; nested async function/arrow/method helpers are rejected. Await runs.run('key',{agent,task}) before .output; await runs.all([{key,agent,task},...]) for an ordered array, not a key map. Observe every stored run promise with direct await, Promise.race or Promise.all. Await/return runs.steer(key,message,options?) for a prior key, never raw run ids; queued/delivered/missed/failed receipts are not compliance proof.
25
- Before advanced orchestration (runs.lanes, rolling fanout, mission state, handoffs), read {action:"guide",topic:"workflows"} or the pi-subagents skill. Raw-script sandboxes add deeply frozen args; all sandboxes provide runs, emit, console, JavaScript and enabled mission state, with no filesystem/shell/Pi tools/host globals. External CLI agents support native options only when their runner declares them; read guide tool-reference before passing model, structured output, acceptance/agentContract, tool budget, fast, fork context or skills/tools.
26
- Model override: first call {action:"models"}; copy exact provider/id, not agent names. Thinking uses model suffix, not watchdog-only thinking.
33
+ Before advanced orchestration (runs.lanes, rolling fanout, mission state, handoffs), read {action:"guide",topic:"workflows"} or the pi-subagents skill. Raw-script sandboxes add deeply frozen args; all sandboxes provide runs, emit, console, JavaScript and enabled mission state, with no filesystem/shell/Pi tools/host globals. External CLI agents support native options only when their runner declares them; read guide tool-reference before passing model, structured output, acceptance/agentContract, ${on("tool-budgets", "tool budget, ")}fast, fork context or skills/tools.
34
+ Model override: first call {action:"models"}; copy exact provider/id, not agent names. Thinking uses model suffix${on("watchdog", ", not watchdog-only thinking")}.
27
35
  Named resources: {workflow:'review',args:{task:'...'}} or {workflow:'run-ci',args:{command:'npm test'}}. Raw scripts also accept bounded plain-data args; raw-script args persist as evidence, so never include secrets. worktree:true requires clean source; baseRef defaults to HEAD at allocation or a supported named ref, never full 40/64-character commit IDs or revision expressions.`;
28
36
 
29
- export const DEFAULT_SUBAGENT_TOOL_DESCRIPTION = `${EXECUTION_GUIDANCE}\n\n${SUBAGENT_SAFETY_GUIDANCE}`;
37
+ const structuredExecutionGuidance = (on: FeatureText) => `Delegate one child with {agent,task?}. tasks:[{agent,task},...] runs children in parallel. chain:[{agent,task?,as?} or {parallel:[{agent,task},...]}] runs steps in order; a parallel step waits for all its children and a failed step stops the chain.
38
+ Chain task placeholders: {task} is the top-level task (the original request); {previous} is the prior step's output (a parallel step's outputs in order), and the default when task is omitted; {outputs.name} is the output of an earlier step with as:'name'.
39
+ agent, chain and tasks exclude each other and action. action is management/control; agent may target management actions.
40
+ External CLI agents support native options only when their runner declares them; read guide tool-reference before passing model, structured output, acceptance/agentContract, ${on("tool-budgets", "tool budget, ")}fast, fork context or skills/tools.
41
+ Model override: first call {action:"models"}; copy exact provider/id, not agent names. Thinking uses model suffix${on("watchdog", ", not watchdog-only thinking")}.
42
+ worktree:true requires clean source; baseRef defaults to HEAD at allocation or a supported named ref, never full 40/64-character commit IDs or revision expressions.`;
43
+
44
+ const defaultDescription = (on: FeatureText) => `${on("workflow-scripts", scriptExecutionGuidance(on), structuredExecutionGuidance(on))}\n\n${safetyGuidance(on)}`;
45
+
46
+ const managementDiscovery = (on: FeatureText) => [
47
+ ["list/get/models/guide"],
48
+ [on("agent-management", "create/update/delete/eject/disable/enable/reset/refine")],
49
+ [on("missions", "mission.*"), on("schedules", "schedule.*"), on("watchdog", "watchdog.*"), on("panes", "inspector.*, project.*"), on("lane-management", "lane.status/recordMerge/recordSupersession")],
50
+ [on("lane-management", "worktree.discard and plan-only worktree.cleanup")],
51
+ [`doctor${on("spawn-budget-grants", " and grant-spawn-budget")}`],
52
+ ].map((group) => group.filter(Boolean).join(", ")).filter(Boolean).join("; ");
53
+
54
+ const fullDescription = (on: FeatureText) => `${defaultDescription(on)}
55
+
56
+ WORKFLOW DETAILS:
57
+ ${on("workflow-scripts", "• runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task}]}]) runs first stages together, later stages sequentially per lane. Failures stay lane-local; only explicit structuredOutput.verdict === 'blocked' blocks a successful stage, never reviewer prose.\n")}• ${on("workflow-scripts", "Workflow child controls default onto runs.run/runs.all items; child fields override them.", "Top-level child controls apply to every chain/tasks child.")} worktree:true isolates each child and returns handoff artifacts.${on("usage-budgets", " usageBudget is shared across the workflow; already-running children are not stopped.")}
58
+ • Missions auto-attach${on("missions", " unless mission:false")}; ${on("workflow-scripts", "await state.get(key)/state.set(key,JSONValue) requires a mission. ")}See guide topic missions. Omit acceptance for reviewer/read-only calls; acceptance.review.required requests independent writer review.
59
+ • Management discovery: ${managementDiscovery(on)}. Use guide topics agents, ${on("missions", "missions, ")}observability, tool-reference, configuration, models${on("watchdog", ", watchdog")} or extension-api for exact action fields.${on("schedules", on("workflow-scripts", " Schedules take script inputs, not direct children; recipes live in the missions guide."))}`;
60
+
61
+ const allEnabled = featureText(resolveDisabledFeatureSurface({}));
62
+
63
+ export const SUBAGENT_SAFETY_GUIDANCE = safetyGuidance(allEnabled);
64
+
65
+ export const DEFAULT_SUBAGENT_TOOL_DESCRIPTION = defaultDescription(allEnabled);
30
66
 
31
67
  export const SUBAGENT_TOOL_PROMPT_SNIPPET = "For operator-requested delegation, use subagents; compose multi-child work in one workflow call.";
68
+ const STRUCTURED_SUBAGENT_TOOL_PROMPT_SNIPPET = "For operator-requested delegation, use subagents; compose multi-child work in one chain or tasks call.";
32
69
  export const SUBAGENT_TOOL_PROMPT_GUIDELINES = [
33
70
  "Do not invoke subagents unless the operator requested delegation directly or through applicable instructions.",
34
71
  ];
35
72
 
36
73
  export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = DEFAULT_SUBAGENT_TOOL_DESCRIPTION;
37
74
 
38
- export const FULL_SUBAGENT_TOOL_DESCRIPTION = `${DEFAULT_SUBAGENT_TOOL_DESCRIPTION}
39
-
40
- WORKFLOW DETAILS:
41
- • runs.lanes([{key,stages:[{key,agent,task},{key,resume:'previous',task}]}]) runs first stages together, later stages sequentially per lane. Failures stay lane-local; only explicit structuredOutput.verdict === 'blocked' blocks a successful stage, never reviewer prose.
42
- • Workflow child controls default onto runs.run/runs.all items; child fields override them. worktree:true isolates each child and returns handoff artifacts. usageBudget is shared across the workflow; already-running children are not stopped.
43
- • Missions auto-attach unless mission:false; await state.get(key)/state.set(key,JSONValue) requires a mission. See guide topic missions. Omit acceptance for reviewer/read-only calls; acceptance.review.required requests independent writer review.
44
- • Management discovery: list/get/models/guide; create/update/delete/eject/disable/enable/reset/refine; mission.*, schedule.*, watchdog.*, inspector.*, project.*, lane.status/recordMerge/recordSupersession; worktree.discard and plan-only worktree.cleanup; doctor and grant-spawn-budget. Use guide topics agents, missions, observability, tool-reference, configuration, models, watchdog or extension-api for exact action fields. Schedules take script inputs, not direct children; recipes live in the missions guide.`;
75
+ export const FULL_SUBAGENT_TOOL_DESCRIPTION = fullDescription(allEnabled);
45
76
 
46
77
  function isToolDescriptionMode(value: unknown): value is ToolDescriptionMode {
47
78
  return value === "full" || value === "compact" || value === "custom";
@@ -55,6 +86,8 @@ export interface ToolDescriptionOptions {
55
86
  cwd?: string;
56
87
  agentDir?: string;
57
88
  warn?: (message: string) => void;
89
+ /** Removes lines for disabled features from the default and full descriptions; custom descriptions are unchanged apart from the appended safety guidance. */
90
+ disabledFeatures?: DisabledFeatureSurface;
58
91
  }
59
92
 
60
93
  export interface SubagentToolPromptMetadata {
@@ -62,10 +95,10 @@ export interface SubagentToolPromptMetadata {
62
95
  promptGuidelines?: string[];
63
96
  }
64
97
 
65
- export function buildSubagentToolPromptMetadata(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}): SubagentToolPromptMetadata {
98
+ export function buildSubagentToolPromptMetadata(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, disabledFeatures?: DisabledFeatureSurface): SubagentToolPromptMetadata {
66
99
  if (config.toolDescriptionMode !== undefined) return {};
67
100
  return {
68
- promptSnippet: SUBAGENT_TOOL_PROMPT_SNIPPET,
101
+ promptSnippet: disabledFeatures?.features.has("workflow-scripts") ? STRUCTURED_SUBAGENT_TOOL_PROMPT_SNIPPET : SUBAGENT_TOOL_PROMPT_SNIPPET,
69
102
  promptGuidelines: SUBAGENT_TOOL_PROMPT_GUIDELINES,
70
103
  };
71
104
  }
@@ -146,30 +179,32 @@ function loadCustomToolDescription(options?: ToolDescriptionOptions): string | u
146
179
  return undefined;
147
180
  }
148
181
 
149
- function withMandatorySafetyGuidance(description: string): string {
182
+ function withMandatorySafetyGuidance(description: string, safety: string): string {
150
183
  const customDescription = description
151
184
  .split(SUBAGENT_SAFETY_GUIDANCE)
185
+ .flatMap((part) => part.split(safety))
152
186
  .flatMap((part) => part.split(SUBAGENT_FAILURE_RECOVERY_GUIDANCE))
153
187
  .map((part) => part.trim())
154
188
  .filter(Boolean)
155
189
  .join("\n\n");
156
190
  return customDescription
157
- ? `${customDescription}\n\n${SUBAGENT_SAFETY_GUIDANCE}`
158
- : SUBAGENT_SAFETY_GUIDANCE;
191
+ ? `${customDescription}\n\n${safety}`
192
+ : safety;
159
193
  }
160
194
 
161
195
  export function buildSubagentToolDescription(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, options?: ToolDescriptionOptions): string {
162
- if (config.toolDescriptionMode === undefined) return DEFAULT_SUBAGENT_TOOL_DESCRIPTION;
196
+ const on = options?.disabledFeatures ? featureText(options.disabledFeatures) : allEnabled;
197
+ if (config.toolDescriptionMode === undefined) return defaultDescription(on);
163
198
  const mode = resolveToolDescriptionMode(config, options);
164
199
  let description: string;
165
- if (mode === "compact") description = COMPACT_SUBAGENT_TOOL_DESCRIPTION;
200
+ if (mode === "compact") description = defaultDescription(on);
166
201
  else if (mode === "custom") {
167
202
  const custom = loadCustomToolDescription(options);
168
- if (custom) description = withMandatorySafetyGuidance(custom);
203
+ if (custom) description = withMandatorySafetyGuidance(custom, safetyGuidance(on));
169
204
  else {
170
205
  warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
171
- description = FULL_SUBAGENT_TOOL_DESCRIPTION;
206
+ description = fullDescription(on);
172
207
  }
173
- } else description = FULL_SUBAGENT_TOOL_DESCRIPTION;
208
+ } else description = fullDescription(on);
174
209
  return description;
175
210
  }
@@ -0,0 +1,40 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { fileURLToPath } from "node:url";
4
+ import packageJson from "../../package.json" with { type: "json" };
5
+ import { writeAtomicJson } from "../shared/atomic-json.ts";
6
+ import { getAgentDir } from "../shared/utils.ts";
7
+
8
+ // major.minor.patch as one comparable number; undefined for anything else.
9
+ const versionNumber = (version: unknown) => typeof version === "string" && /^\d+\.\d+\.\d+$/.test(version)
10
+ ? version.split(".").reduce((total, part) => total * 1e6 + Number(part), 0)
11
+ : undefined;
12
+
13
+ export async function showUpgradeNotice(
14
+ ctx: { hasUI: boolean; ui: { notify(message: string, type: "info"): void } },
15
+ stateDir = path.join(getAgentDir(), "pi-subagents"),
16
+ changelogPath = fileURLToPath(new URL("../../CHANGELOG.md", import.meta.url)),
17
+ version = packageJson.version,
18
+ ): Promise<void> {
19
+ if (!ctx.hasUI) return;
20
+ const statePath = path.join(stateDir, "last-seen-version.json");
21
+ const lastSeen = await fs.promises.readFile(statePath, "utf-8").then((raw) => JSON.parse(raw).version).catch(() => undefined);
22
+ const previous = versionNumber(lastSeen);
23
+ const current = versionNumber(version);
24
+ if (current === undefined || previous === current) return;
25
+ writeAtomicJson(statePath, { version });
26
+ if (previous === undefined || previous > current) return;
27
+
28
+ const bullets = (await fs.promises.readFile(changelogPath, "utf-8")).split(/^## /m).flatMap((section) => {
29
+ const released = versionNumber(/^\[([^\]]+)\]/.exec(section)?.[1]);
30
+ if (released === undefined || released <= previous || released > current) return [];
31
+ const highlights = section.split(/^### /m).find((part) => part.startsWith("Highlights")) ?? "";
32
+ return (highlights.match(/^- .*/gm) ?? []).map((bullet) => bullet.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").trim());
33
+ });
34
+ ctx.ui.notify([
35
+ `pi-subagents updated from ${lastSeen} to ${version}`,
36
+ ...bullets.slice(0, 5),
37
+ ...(bullets.length > 5 ? [`...and ${bullets.length - 5} more`] : []),
38
+ "Changelog: https://github.com/nicobailon/pi-subagents/blob/main/CHANGELOG.md",
39
+ ].join("\n"), "info");
40
+ }
@@ -5,6 +5,7 @@ import {
5
5
  } from "../shared/types.ts";
6
6
  import { previewDisplayText, sanitizeDisplayText } from "../shared/display-text.ts";
7
7
 
8
+ export const HERDR_FOREGROUND_CONTROL_CHANGED_EVENT = "pi-subagents:herdr:foreground-control-changed";
8
9
  const DEFAULT_SOURCE = "pi-subagents:herdr";
9
10
  const DEFAULT_TTL_MS = 120_000;
10
11
  const DEFAULT_REFRESH_MS = 45_000;
@@ -29,6 +30,8 @@ export interface HerdrStatusRun {
29
30
  id: string;
30
31
  agent?: string;
31
32
  agents?: string[];
33
+ /** A workflow owns busy state but is not itself a child agent. */
34
+ coordinator?: true;
32
35
  /** Explicit launch/workflow label only; raw prompts never enter pane metadata. */
33
36
  taskLabel?: string;
34
37
  needsAttention?: boolean;
@@ -100,10 +103,17 @@ function workflowTaskLabel(data: Record<string, unknown>): string | undefined {
100
103
  function startedRun(data: unknown): HerdrStatusRun | undefined {
101
104
  if (!isRecord(data) || typeof data.id !== "string" || !data.id) return undefined;
102
105
  const taskLabel = workflowTaskLabel(data);
106
+ // The workflow coordinator itself is not a running leaf: it starts with its
107
+ // own `agent: "workflow"` identity, but its actual leaves each publish their
108
+ // own start event separately. Counting the coordinator here would double it.
109
+ const isWorkflowCoordinator = data.mode === "workflow";
103
110
  return {
104
111
  id: data.id,
105
- ...(typeof data.agent === "string" ? { agent: data.agent } : {}),
106
- ...(Array.isArray(data.agents) && data.agents.every((agent) => typeof agent === "string") ? { agents: data.agents as string[] } : {}),
112
+ ...(isWorkflowCoordinator ? { coordinator: true as const } : {}),
113
+ ...(!isWorkflowCoordinator && typeof data.agent === "string" ? { agent: data.agent } : {}),
114
+ ...(isWorkflowCoordinator
115
+ ? { agents: [] }
116
+ : Array.isArray(data.agents) && data.agents.every((agent) => typeof agent === "string") ? { agents: data.agents as string[] } : {}),
107
117
  ...(taskLabel ? { taskLabel } : {}),
108
118
  };
109
119
  }
@@ -150,7 +160,10 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
150
160
  let refreshTimer: ReturnType<typeof setInterval> | undefined;
151
161
 
152
162
  const activeAgentNames = (): string[] => [...new Set([...runs.values()].flatMap((run) => run.agents?.length ? run.agents : run.agent ? [run.agent] : []))];
153
- const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) => total + Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0)), 0);
163
+ // Preserve the minimum count for ordinary runs with incomplete status;
164
+ // only an empty workflow coordinator contributes zero child agents.
165
+ const activeSubagentCount = (): number => [...runs.values()].reduce((total, run) =>
166
+ total + (run.coordinator && !run.agents?.length ? 0 : Math.max(1, run.agents?.length ?? (run.agent ? 1 : 0))), 0);
154
167
  const activeTaskLabel = (): string | undefined => [...runs.values()].reverse().find((run) => run.taskLabel)?.taskLabel;
155
168
 
156
169
  const label = (includeAttention = false): string => {
@@ -340,6 +353,9 @@ export function registerHerdrStatusBridge(options: HerdrStatusBridgeOptions): He
340
353
  };
341
354
 
342
355
  if (enabled) {
356
+ subscribe(HERDR_FOREGROUND_CONTROL_CHANGED_EVENT, () => {
357
+ if (rootSession && options.getRuns) refresh();
358
+ });
343
359
  subscribe(SUBAGENT_ASYNC_STARTED_EVENT, (data) => {
344
360
  if (!rootSession) return;
345
361
  const run = startedRun(data);
@@ -8,6 +8,7 @@ import type { ChildSupervisorMetadata } from "../runs/shared/child-runtime-confi
8
8
  import { INTERCOM_DETACH_REQUEST_EVENT, POLL_INTERVAL_MS, TEMP_ROOT_DIR, type ControlEvent, type IntercomEventBus, type SubagentState } from "../shared/types.ts";
9
9
  import { writeAtomicJson } from "../shared/atomic-json.ts";
10
10
  import { shouldUseNativeFsWatch } from "../shared/watch-strategy.ts";
11
+ import { MODEL_ONLY_TOOL } from "../shared/extension-context.ts";
11
12
  import {
12
13
  SUPERVISOR_REQUEST_MESSAGE_TYPE,
13
14
  SUPERVISOR_REPLY_ENTRY_TYPE,
@@ -259,6 +260,7 @@ export function registerNativeSupervisorClient(pi: ExtensionAPI, metadata: Child
259
260
  if (!metadata || hasTool(pi, "contact_supervisor")) return;
260
261
  const tool: ToolDefinition<typeof ContactSupervisorParamsSchema, Record<string, unknown>> = {
261
262
  name: "contact_supervisor",
263
+ ...MODEL_ONLY_TOOL,
262
264
  label: "Contact Supervisor",
263
265
  description: "Contact the parent/supervisor session for a blocking decision, structured interview, or progress update.",
264
266
  parameters: ContactSupervisorParamsSchema,
@@ -585,6 +587,7 @@ function publicPendingRequests(pending: Map<string, PendingSupervisorRequest>):
585
587
  function buildParentSupervisorTool(pi: ExtensionAPI, pending: Map<string, PendingSupervisorRequest>, state: SubagentState, onLifecycle: SupervisorRequestLifecycleObserver, discover: () => void, runState: (request: SupervisorRequest) => SubagentState): ToolDefinition<typeof IntercomParamsSchema, Record<string, unknown>> {
586
588
  return {
587
589
  name: NATIVE_SUPERVISOR_TOOL_NAME,
590
+ ...MODEL_ONLY_TOOL,
588
591
  label: "Subagent Supervisor",
589
592
  description: "Native pi-subagents supervisor channel. Use reply/pending/status to answer child subagent requests without overriding pi-intercom.",
590
593
  parameters: IntercomParamsSchema,
@@ -788,7 +791,7 @@ export function createNativeSupervisorChannel(pi: ExtensionAPI, state: SubagentS
788
791
  if (poller) return;
789
792
  poller = timers.setInterval(() => {
790
793
  poll();
791
- if (!useNativeWatcher() && (platform === "darwin" || deps.getChannelDirs) && !hasTransportDemand()) {
794
+ if (!useNativeWatcher() && !hasTransportDemand()) {
792
795
  if (poller) timers.clearInterval(poller);
793
796
  poller = undefined;
794
797
  }
@@ -112,14 +112,14 @@ function resolveAsyncPiPackageRoot(env: NodeJS.ProcessEnv = process.env): string
112
112
  function resolveJitiCliFromPackageJson(packageJsonPath: string): string | undefined {
113
113
  if (!fs.existsSync(packageJsonPath)) return undefined;
114
114
  const packageRoot = path.dirname(packageJsonPath);
115
- let parsed: unknown;
116
- try {
117
- parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
118
- } catch {
119
- return undefined;
120
- }
121
- if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
122
- const pkg = parsed as { bin?: string | Record<string, string> };
115
+ let parsed: unknown;
116
+ try {
117
+ parsed = JSON.parse(fs.readFileSync(packageJsonPath, "utf-8"));
118
+ } catch {
119
+ return undefined;
120
+ }
121
+ if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
122
+ const pkg = parsed as { bin?: string | Record<string, string> };
123
123
  const binField = pkg.bin;
124
124
  const binPath = typeof binField === "string"
125
125
  ? binField
@@ -181,13 +181,14 @@ interface AsyncExecutionContext {
181
181
  permissions?: PermissionConfig;
182
182
  currentModelProvider?: string;
183
183
  currentModel?: ParentModel;
184
+ scopedModelIds?: string[];
184
185
  /** Optional model-scope enforcement resolved from subagent settings. */
185
186
  modelScope?: ModelScopeConfig;
186
187
  /** Parent-authoritative trust state for profile-aware project config merging. */
187
188
  projectTrusted?: boolean;
188
189
  /** Exact trusted parent cwd; project config applies only when it matches the child cwd. */
189
190
  trustedProjectCwd?: string;
190
- modelResponseAliases?: Record<string, string[]>;
191
+ modelResponseAliases?: Record<string, string[]>;
191
192
  /** Whether the parent session has an interactive UI. */
192
193
  interactive?: boolean;
193
194
  /** The executor's own child runtime when the launch comes from an in-process child. */
@@ -270,7 +271,7 @@ interface AsyncSingleParams {
270
271
  recoveryAgentConfig?: AgentConfig;
271
272
  /** Selected global sandbox profile carried across revival. */
272
273
  sandbox?: string;
273
- requiredExtensions?: RequiredChildExtensionSnapshot;
274
+ requiredExtensions?: RequiredChildExtensionSnapshot;
274
275
  ctx: AsyncExecutionContext;
275
276
  cwd?: string;
276
277
  requestedCwd?: string;
@@ -429,8 +430,8 @@ export function isAsyncAvailable(): boolean {
429
430
  }
430
431
 
431
432
  export function resolveAsyncRunnerLogPaths(cfg: Record<string, unknown>): { stdoutPath: string; stderrPath: string } | undefined {
432
- const asyncDir = typeof cfg.asyncDir === "string"
433
- ? cfg.asyncDir
433
+ const asyncDir = typeof cfg.asyncDir === "string"
434
+ ? cfg.asyncDir
434
435
  : undefined;
435
436
  if (!asyncDir) return undefined;
436
437
  return {
@@ -738,8 +739,8 @@ function spawnRunner(cfg: object, suffix: string, cwd: string, initialStatus: Om
738
739
  ? [...preload, "--experimental-strip-types", runner, cfgPath]
739
740
  : [...preload, jitiCliPath!, runner, cfgPath];
740
741
  const runnerEnv: NodeJS.ProcessEnv = {
741
- // Fork: profile env inherited from the parent must not leak into children.
742
- ...omitGitRoutingEnv(omitInheritedProfileEnv(omitExtensionBindingsEnv(process.env))),
742
+ // Fork: profile env inherited from the parent must not leak into children.
743
+ ...omitGitRoutingEnv(omitInheritedProfileEnv(omitExtensionBindingsEnv(process.env))),
743
744
  ...childCacheRetentionEnv(),
744
745
  [PI_CODING_AGENT_PACKAGE_ROOT_ENV]: binaryHost ? undefined : piPackageRoot,
745
746
  // npm must override inherited bundled layouts (#2071); binaries retain release assets.
@@ -897,16 +898,16 @@ class UnavailableSubagentSkillError extends Error {}
897
898
  class AsyncStartValidationError extends Error {}
898
899
 
899
900
  function profileProjectTrustedForCwd(ctx: AsyncExecutionContext, cwd: string): boolean {
900
- return ctx.projectTrusted === true
901
- && ctx.trustedProjectCwd !== undefined
902
- && path.resolve(ctx.trustedProjectCwd) === path.resolve(cwd);
901
+ return ctx.projectTrusted === true
902
+ && ctx.trustedProjectCwd !== undefined
903
+ && path.resolve(ctx.trustedProjectCwd) === path.resolve(cwd);
903
904
  }
904
905
 
905
906
  function profileProjectTrustError(agent: AgentConfig, ctx: AsyncExecutionContext): string {
906
- if (ctx.projectTrusted !== true) {
907
- return `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but the project is not trusted. Trust the project and retry.`;
908
- }
909
- return `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but the child cwd is not an exact trusted project root. Launch from that trusted cwd and retry.`;
907
+ if (ctx.projectTrusted !== true) {
908
+ return `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but the project is not trusted. Trust the project and retry.`;
909
+ }
910
+ return `Agent '${agent.name}' selects sandbox profile '${agent.sandbox}' from project scope, but the child cwd is not an exact trusted project root. Launch from that trusted cwd and retry.`;
910
911
  }
911
912
 
912
913
  export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildParams): AsyncRunnerStepBuildResult {
@@ -1017,7 +1018,7 @@ export function buildAsyncRunnerSteps(id: string, params: AsyncRunnerStepBuildPa
1017
1018
  if (effectiveBehavior.outputSchema !== undefined) unsupported.push("structured output");
1018
1019
  if (s.acceptance !== undefined || params.agentContract !== undefined || s.agentContract !== undefined) unsupported.push("acceptance/agent contract");
1019
1020
  if (s.toolBudget !== undefined || params.toolBudget !== undefined || a.toolBudget !== undefined || params.configToolBudget !== undefined) unsupported.push("tool budget");
1020
- if (a.sandbox !== undefined) unsupported.push("sandbox profile");
1021
+ if (a.sandbox !== undefined) unsupported.push("sandbox profile");
1021
1022
  if ((s.fast ?? params.fast ?? a.fast) === true) unsupported.push("fast mode");
1022
1023
  if (params.contextForAgent?.(s.agent) === "fork") unsupported.push("fork context");
1023
1024
  if (unsupported.length > 0) throw new AsyncStartValidationError(`Agent '${a.name}' uses runner.type='${externalRunnerType}' and does not support: ${unsupported.join(", ")}.`);
@@ -1053,10 +1054,10 @@ if (a.sandbox !== undefined) unsupported.push("sandbox profile");
1053
1054
  resolvedBehavior: effectiveBehavior,
1054
1055
  });
1055
1056
  const { stepCwd, instructionCwd, readExistenceCwd, behavior, namespaceOutputPath, outputPath, skillNames } = launchPlan;
1056
- const profileChildCwd = behaviorCwd ?? stepCwd;
1057
- if (a.sandbox && (a.source === "project" || a.override?.scope === "project") && !profileProjectTrustedForCwd(ctx, profileChildCwd)) {
1058
- throw new AsyncStartValidationError(profileProjectTrustError(a, ctx));
1059
- }
1057
+ const profileChildCwd = behaviorCwd ?? stepCwd;
1058
+ if (a.sandbox && (a.source === "project" || a.override?.scope === "project") && !profileProjectTrustedForCwd(ctx, profileChildCwd)) {
1059
+ throw new AsyncStartValidationError(profileProjectTrustError(a, ctx));
1060
+ }
1060
1061
  const { resolved: resolvedSkills, missing: missingSkills } = resolveSkillsWithFallback(
1061
1062
  skillNames,
1062
1063
  stepCwd,
@@ -1081,7 +1082,7 @@ throw new AsyncStartValidationError(profileProjectTrustError(a, ctx));
1081
1082
  const taskText = `${readInstructions.prefix}${taskTemplate}${progressInstructions.suffix}`;
1082
1083
  const task = namespaceOutputPath ? taskText : injectSingleOutputInstruction(taskText, outputPath, a);
1083
1084
 
1084
- const modelScopes = resolveModelScopesForAgent(ctx.modelScope, a.name, ctx.currentModel);
1085
+ const modelScopes = resolveModelScopesForAgent(ctx.modelScope, a.name, ctx.currentModel, ctx.scopedModelIds);
1085
1086
  const modelOrigin = resolveModelOrigin({ explicitModel: s.model, agentModel: a.model, parentModel: ctx.currentModel });
1086
1087
  const primaryModelFromParent = modelOrigin === "inherited";
1087
1088
  const primaryModel = externalRunner ? undefined : resolveEffectiveSubagentModel(
@@ -1130,7 +1131,7 @@ throw new AsyncStartValidationError(profileProjectTrustError(a, ctx));
1130
1131
  if (launchRuleError) throw new AsyncStartValidationError(launchRuleError);
1131
1132
  const fast = s.fast ?? params.fast ?? a.fast;
1132
1133
  const requiredExtensions = externalRunner ? [] : ctx.childRuntime?.requiredExtensions ?? resolveRequiredChildExtensions(ctx.parentSessionId ?? ctx.currentSessionId ?? undefined);
1133
- const hostAvailableBuiltins = getHostBuiltinToolNames(ctx.pi);
1134
+ const hostAvailableBuiltins = getHostBuiltinToolNames(ctx.pi);
1134
1135
  const toolPlan = resolvePiLaunchToolPlan({
1135
1136
  tools: a.tools,
1136
1137
  excludeTools: a.excludeTools,
@@ -1149,8 +1150,8 @@ const hostAvailableBuiltins = getHostBuiltinToolNames(ctx.pi);
1149
1150
  agentName: a.name,
1150
1151
  permissionRules,
1151
1152
  runtimeSnapshotHost: ctx.pi,
1152
- sandbox: a.sandbox,
1153
- hostAvailableBuiltins,
1153
+ sandbox: a.sandbox,
1154
+ hostAvailableBuiltins,
1154
1155
  });
1155
1156
  const launchResolvedExtensions = externalRunner ? undefined : projectLaunchResolvedChildExtensions(toolPlan);
1156
1157
  if (externalRunner && permissionRules) {
@@ -1159,8 +1160,8 @@ hostAvailableBuiltins,
1159
1160
  return {
1160
1161
  parentSessionId: launchParentSessionId,
1161
1162
  permissionRules,
1162
- ...(ctx.projectTrusted !== undefined ? { projectTrusted: ctx.projectTrusted } : {}),
1163
- ...(ctx.trustedProjectCwd ? { trustedProjectCwd: ctx.trustedProjectCwd } : {}),
1163
+ ...(ctx.projectTrusted !== undefined ? { projectTrusted: ctx.projectTrusted } : {}),
1164
+ ...(ctx.trustedProjectCwd ? { trustedProjectCwd: ctx.trustedProjectCwd } : {}),
1164
1165
  ...(params.capabilityCeiling ? { capabilityCeiling: params.capabilityCeiling } : {}),
1165
1166
  ...(runFanoutPath ? { runFanoutPath } : {}),
1166
1167
  agent: s.agent,
@@ -1194,8 +1195,9 @@ hostAvailableBuiltins,
1194
1195
  subagentOnlyExtensions: a.subagentOnlyExtensions,
1195
1196
  ...(!externalRunner ? { requiredExtensions } : {}),
1196
1197
  mcpDirectTools: a.mcpDirectTools,
1198
+ ...(toolPlan.builtinMcpTools ? { builtinMcpTools: toolPlan.builtinMcpTools } : {}),
1197
1199
  mutationTools: a.mutationTools,
1198
- ...(a.sandbox ? { sandbox: a.sandbox } : {}),
1200
+ ...(a.sandbox ? { sandbox: a.sandbox } : {}),
1199
1201
  systemPrompt,
1200
1202
  systemPromptMode: a.systemPromptMode,
1201
1203
  inheritProjectContext: a.inheritProjectContext,
@@ -1524,6 +1526,7 @@ export function executeAsyncChain(
1524
1526
  piPackageRoot,
1525
1527
  childSessionFactoryModule: childSessionFactoryModule(),
1526
1528
  inheritedChildRuntime: inheritedChildRuntime(ctx.childRuntime),
1529
+ projectTrusted: ctx.projectTrusted,
1527
1530
  worktreeSetupHook,
1528
1531
  worktreeSetupHookTimeoutMs,
1529
1532
  worktreeBaseDir,
@@ -1755,7 +1758,7 @@ export function executeAsyncSingle(
1755
1758
  const externalRunner = agentConfig.runner?.type === "external-cli" || agentConfig.runner?.type === "external-job";
1756
1759
  const externalRunnerType = agentConfig.runner?.type;
1757
1760
  const permissionRules = resolvePermissionRules(ctx.permissions, agentConfig.permissions);
1758
- const sandbox = params.sandbox ?? agentConfig.sandbox;
1761
+ const sandbox = params.sandbox ?? agentConfig.sandbox;
1759
1762
  if (externalRunner) {
1760
1763
  const unsupported: string[] = [];
1761
1764
  if (params.modelOverride !== undefined) unsupported.push("model override");
@@ -1764,7 +1767,7 @@ const sandbox = params.sandbox ?? agentConfig.sandbox;
1764
1767
  if (params.structuredOutputSchema !== undefined) unsupported.push("structured output");
1765
1768
  if (params.acceptance !== undefined || params.agentContract !== undefined) unsupported.push("acceptance/agent contract");
1766
1769
  if (params.toolBudget !== undefined || agentConfig.toolBudget !== undefined || params.configToolBudget !== undefined) unsupported.push("tool budget");
1767
- if (sandbox !== undefined) unsupported.push("sandbox profile");
1770
+ if (sandbox !== undefined) unsupported.push("sandbox profile");
1768
1771
  if (params.context === "fork") unsupported.push("fork context");
1769
1772
  if ((params.skills?.length ?? 0) > 0) unsupported.push("skills");
1770
1773
  if (permissionRules) unsupported.push("native Pi child permissions");
@@ -1806,9 +1809,9 @@ if (sandbox !== undefined) unsupported.push("sandbox profile");
1806
1809
  : params.worktree === true && managedWorktreeProvider === "native"
1807
1810
  ? resolveExpectedWorktreeAgentCwd(runnerCwd, `${id}-s0`, 0, worktreeBaseDir)
1808
1811
  : machine?.cwd ?? runnerCwd;
1809
- if (sandbox && (agentConfig.source === "project" || agentConfig.override?.scope === "project") && !profileProjectTrustedForCwd(ctx, instructionCwd)) {
1810
- return formatAsyncStartError("single", profileProjectTrustError(agentConfig, ctx));
1811
- }
1812
+ if (sandbox && (agentConfig.source === "project" || agentConfig.override?.scope === "project") && !profileProjectTrustedForCwd(ctx, instructionCwd)) {
1813
+ return formatAsyncStartError("single", profileProjectTrustError(agentConfig, ctx));
1814
+ }
1812
1815
  const readExistenceCwd = params.worktree === true ? runnerCwd : instructionCwd;
1813
1816
  const skillNames = params.skills ?? agentConfig.skills ?? [];
1814
1817
  const availableModels = params.availableModels;
@@ -1863,7 +1866,7 @@ return formatAsyncStartError("single", profileProjectTrustError(agentConfig, ctx
1863
1866
  ? `[Read from: ${readPaths.join(", ")}]\n\n`
1864
1867
  : "";
1865
1868
  const taskText = readsInstruction + taskWithOutputInstruction;
1866
- const modelScopes = resolveModelScopesForAgent(ctx.modelScope, agentConfig.name, ctx.currentModel);
1869
+ const modelScopes = resolveModelScopesForAgent(ctx.modelScope, agentConfig.name, ctx.currentModel, ctx.scopedModelIds);
1867
1870
  const modelOrigin = resolveModelOrigin({
1868
1871
  fromParent: params.modelOverrideFromParent,
1869
1872
  storedOrigin: params.modelOrigin,
@@ -1938,7 +1941,7 @@ return formatAsyncStartError("single", profileProjectTrustError(agentConfig, ctx
1938
1941
  }
1939
1942
  }
1940
1943
  const requiredExtensions = externalRunner ? [] : params.requiredExtensions ?? ctx.childRuntime?.requiredExtensions ?? resolveRequiredChildExtensions(ctx.parentSessionId ?? ctx.currentSessionId ?? undefined);
1941
- const hostAvailableBuiltins = getHostBuiltinToolNames(ctx.pi);
1944
+ const hostAvailableBuiltins = getHostBuiltinToolNames(ctx.pi);
1942
1945
  const toolPlan = resolvePiLaunchToolPlan({
1943
1946
  tools: agentConfig.tools,
1944
1947
  excludeTools: agentConfig.excludeTools,
@@ -1957,8 +1960,8 @@ const hostAvailableBuiltins = getHostBuiltinToolNames(ctx.pi);
1957
1960
  agentName: agentConfig.name,
1958
1961
  permissionRules: resolvePermissionRules(ctx.permissions, agentConfig.permissions),
1959
1962
  runtimeSnapshotHost: ctx.pi,
1960
- sandbox,
1961
- hostAvailableBuiltins,
1963
+ sandbox,
1964
+ hostAvailableBuiltins,
1962
1965
  });
1963
1966
  const launchResolvedExtensions = externalRunner ? undefined : projectLaunchResolvedChildExtensions(toolPlan);
1964
1967
  const fast = params.fast ?? agentConfig.fast;
@@ -1970,11 +1973,11 @@ hostAvailableBuiltins,
1970
1973
  ...(fast !== undefined ? { fast } : {}),
1971
1974
  ...(launchThinking ? { thinking: launchThinking } : {}),
1972
1975
  systemPrompt,
1973
- systemPromptMode: agentConfig.systemPromptMode,
1974
- inheritProjectContext: agentConfig.inheritProjectContext,
1975
- inheritGlobalContext: agentConfig.inheritGlobalContext,
1976
- inheritSkills: agentConfig.inheritSkills,
1977
- sandbox,
1976
+ systemPromptMode: agentConfig.systemPromptMode,
1977
+ inheritProjectContext: agentConfig.inheritProjectContext,
1978
+ inheritGlobalContext: agentConfig.inheritGlobalContext,
1979
+ inheritSkills: agentConfig.inheritSkills,
1980
+ sandbox,
1978
1981
  skills: resolvedSkills.map((skill) => skill.name),
1979
1982
  toolPlan,
1980
1983
  ...(outputPath ? { outputPath } : {}),
@@ -2003,7 +2006,7 @@ sandbox,
2003
2006
  sourceRunId: id,
2004
2007
  ...(params.agentContract ? { agentContract: params.agentContract } : {}),
2005
2008
  agent,
2006
- ...(sandbox ? { sandbox } : {}),
2009
+ ...(sandbox ? { sandbox } : {}),
2007
2010
  launchResolvedExtensions,
2008
2011
  ...(sessionFile ? { sessionFile } : {}),
2009
2012
  cwd: runnerCwd,
@@ -2068,8 +2071,8 @@ sandbox,
2068
2071
  {
2069
2072
  parentSessionId: launchParentSessionId,
2070
2073
  permissionRules,
2071
- ...(ctx.projectTrusted !== undefined ? { projectTrusted: ctx.projectTrusted } : {}),
2072
- ...(ctx.trustedProjectCwd ? { trustedProjectCwd: ctx.trustedProjectCwd } : {}),
2074
+ ...(ctx.projectTrusted !== undefined ? { projectTrusted: ctx.projectTrusted } : {}),
2075
+ ...(ctx.trustedProjectCwd ? { trustedProjectCwd: ctx.trustedProjectCwd } : {}),
2073
2076
  ...(capabilityCeiling ? { capabilityCeiling } : {}),
2074
2077
  agent,
2075
2078
  task: taskText,
@@ -2098,8 +2101,9 @@ sandbox,
2098
2101
  subagentOnlyExtensions: agentConfig.subagentOnlyExtensions,
2099
2102
  ...(!externalRunner ? { requiredExtensions } : {}),
2100
2103
  mcpDirectTools: agentConfig.mcpDirectTools,
2104
+ ...(toolPlan.builtinMcpTools ? { builtinMcpTools: toolPlan.builtinMcpTools } : {}),
2101
2105
  mutationTools: agentConfig.mutationTools,
2102
- ...(sandbox ? { sandbox } : {}),
2106
+ ...(sandbox ? { sandbox } : {}),
2103
2107
  systemPrompt,
2104
2108
  systemPromptMode: agentConfig.systemPromptMode,
2105
2109
  inheritProjectContext: agentConfig.inheritProjectContext,
@@ -2144,6 +2148,7 @@ sandbox,
2144
2148
  ...(capabilityCeiling ? { capabilityCeiling } : {}),
2145
2149
  piPackageRoot,
2146
2150
  childSessionFactoryModule: childSessionFactoryModule(),
2151
+ projectTrusted: ctx.projectTrusted,
2147
2152
  inheritedChildRuntime: inheritedChildRuntime(ctx.childRuntime),
2148
2153
  worktreeSetupHook,
2149
2154
  worktreeSetupHookTimeoutMs,
@@ -2240,7 +2245,7 @@ sandbox,
2240
2245
  mode: "single",
2241
2246
  state: "running",
2242
2247
  agent,
2243
- ...(sandbox ? { sandbox } : {}),
2248
+ ...(sandbox ? { sandbox } : {}),
2244
2249
  agents: [agent],
2245
2250
  chainStepCount: 1,
2246
2251
  ...(timeoutMs !== undefined ? { timeoutMs, deadlineAt } : {}),
@@ -2261,7 +2266,7 @@ sandbox,
2261
2266
  completionOwnerId: ctx.completionOwnerId ?? currentCompletionOwnerId(),
2262
2267
  mode: "single",
2263
2268
  agent,
2264
- ...(sandbox ? { sandbox } : {}),
2269
+ ...(sandbox ? { sandbox } : {}),
2265
2270
  task: task?.trim() ? PROMPT_REDACTED : undefined,
2266
2271
  goal: (params.goal ?? task).trim() ? PROMPT_REDACTED : undefined,
2267
2272
  cwd: runnerCwd,