@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
@@ -1196,7 +1196,7 @@ export function handleCreate(params: ManagementParams, ctx: ManagementContext):
1196
1196
  const scopeRaw = cfg.scope ?? "user";
1197
1197
  if (scopeRaw !== "user" && scopeRaw !== "project") return result("config.scope must be 'user' or 'project'.", true);
1198
1198
  const scope = scopeRaw;
1199
- if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
1199
+ if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use a workflow script or /prompt-workflow for repeatable workflows.", true);
1200
1200
  const d = discoverCatalog(ctx);
1201
1201
  const projectConfigDir = getProjectConfigDir(ctx.cwd);
1202
1202
  const targetDir = scope === "user" ? d.userDir : d.projectDir ?? path.join(projectConfigDir, "agents");
@@ -1238,7 +1238,7 @@ export function handleUpdate(params: ManagementParams, ctx: ManagementContext):
1238
1238
  if (parsedConfig.status === "error") return result(parsedConfig.message, true);
1239
1239
  if (parsedConfig.status === "missing") return result("config required for update.", true);
1240
1240
  const cfg = parsedConfig.value;
1241
- if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use workflowScript or /prompt-workflow for repeatable workflows.", true);
1241
+ if (hasKey(cfg, "steps")) return result("Durable chain definitions were removed; use a workflow script or /prompt-workflow for repeatable workflows.", true);
1242
1242
  const warnings: string[] = [];
1243
1243
  const scopeHint = asDisambiguationScope(params.agentScope);
1244
1244
  const targetOrError = resolveTarget(params.agent, findAgents(params.agent, ctx, scopeHint ?? "both"), ctx.cwd, ctx, scopeHint);
@@ -8,8 +8,10 @@ import { parse as parseYaml } from "yaml";
8
8
  import * as os from "node:os";
9
9
  import * as path from "node:path";
10
10
  import { fileURLToPath } from "node:url";
11
+ import { createAtomicJsonWriter } from "../shared/atomic-json.ts";
11
12
  import type { AcceptanceInput, AcceptanceRole, AgentRunnerConfig, JsonSchemaObject, OutputMode, ToolBudgetConfig } from "../shared/types.ts";
12
13
  import { CODE_OWNED_EXTERNAL_CLI_ADAPTER_LABEL, isCodeOwnedExternalCliAdapterId, parseExternalCliCapabilityNarrowing, validateCodeOwnedProfileRunner } from "../runs/shared/external-cli-contract.ts";
14
+ import { isClaudeCodeAdapterId } from "../runs/shared/claude-code-adapter.ts";
13
15
  import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
14
16
  import { expandHomePath } from "../shared/settings.ts";
15
17
  import { KNOWN_FIELDS } from "./agent-serializer.ts";
@@ -89,6 +91,7 @@ export interface BuiltinAgentOverrideBase {
89
91
 
90
92
  interface BuiltinAgentOverrideConfig {
91
93
  description?: string;
94
+ advertise?: boolean;
92
95
  machine?: string | false;
93
96
  output?: string | false;
94
97
  outputMode?: OutputMode;
@@ -968,7 +971,58 @@ function readSettingsFileStrict(filePath: string): Record<string, unknown> {
968
971
 
969
972
  function writeSettingsFile(filePath: string, settings: Record<string, unknown>): void {
970
973
  fs.mkdirSync(path.dirname(filePath), { recursive: true });
971
- fs.writeFileSync(filePath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
974
+ const targetPath = resolveSettingsWriteTarget(filePath);
975
+ let existingMode: number | undefined;
976
+ try {
977
+ existingMode = fs.statSync(targetPath).mode & 0o7777;
978
+ } catch (error) {
979
+ if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
980
+ }
981
+ if (existingMode !== undefined) fs.accessSync(targetPath, fs.constants.W_OK);
982
+
983
+ const tempMode = existingMode === undefined ? undefined : existingMode | 0o200;
984
+ // Reuse the atomic temp/rename path while retaining settings' newline and existing mode.
985
+ const writeAtomicSettings = createAtomicJsonWriter({
986
+ mode: tempMode,
987
+ fs: {
988
+ mkdirSync: fs.mkdirSync,
989
+ writeFileSync: (tempPath, data, options) => {
990
+ return fs.writeFileSync(tempPath, `${data}\n`, options);
991
+ },
992
+ renameSync: (sourcePath, destinationPath) => {
993
+ if (existingMode !== undefined) fs.chmodSync(sourcePath, existingMode);
994
+ fs.renameSync(sourcePath, destinationPath);
995
+ },
996
+ rmSync: fs.rmSync,
997
+ },
998
+ });
999
+ writeAtomicSettings(targetPath, settings);
1000
+ }
1001
+
1002
+ function resolveSettingsWriteTarget(filePath: string): string {
1003
+ let targetPath = filePath;
1004
+ for (;;) {
1005
+ try {
1006
+ return fs.realpathSync.native(targetPath);
1007
+ } catch (error) {
1008
+ if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
1009
+ // A trailing separator requires a directory; it cannot name a new settings file.
1010
+ if (targetPath.endsWith("/") || targetPath.endsWith(path.sep)) throw error;
1011
+ }
1012
+
1013
+ // A missing target is allowed only when its physical parent already exists.
1014
+ const parentPath = fs.realpathSync.native(path.dirname(targetPath));
1015
+ const unresolvedPath = path.join(parentPath, path.basename(targetPath));
1016
+ let linkText: string;
1017
+ try {
1018
+ linkText = fs.readlinkSync(unresolvedPath);
1019
+ } catch (error) {
1020
+ if (!(error instanceof Error && "code" in error && error.code === "ENOENT")) throw error;
1021
+ return unresolvedPath;
1022
+ }
1023
+ // Keep link text intact so the filesystem follows directory links before "..".
1024
+ targetPath = path.isAbsolute(linkText) ? linkText : `${parentPath}${path.sep}${linkText}`;
1025
+ }
972
1026
  }
973
1027
 
974
1028
  function parseOverrideStringArrayOrFalse(
@@ -1003,7 +1057,7 @@ function parseToolsOverride(
1003
1057
  throw new Error(`Builtin override '${meta.name}' in '${meta.filePath}' has invalid 'tools'; expected an array of strings, "inherit", or false.`);
1004
1058
  }
1005
1059
 
1006
- function validateOptionalMachine(value: unknown, label: string): string | undefined {
1060
+ export function validateOptionalMachine(value: unknown, label: string): string | undefined {
1007
1061
  if (value === undefined || value === false) return undefined;
1008
1062
  if (typeof value !== "string" || !value.trim()) throw new Error(label + " must be a non-empty string or false.");
1009
1063
  const machine = value.trim();
@@ -1035,6 +1089,11 @@ function parseBuiltinOverrideEntry(
1035
1089
  }
1036
1090
  }
1037
1091
 
1092
+ if ("advertise" in input) {
1093
+ if (typeof input.advertise === "boolean") override.advertise = input.advertise;
1094
+ else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'advertise'; expected a boolean.`);
1095
+ }
1096
+
1038
1097
  if ("output" in input) {
1039
1098
  if ((typeof input.output === "string" && input.output.trim()) || input.output === false) override.output = input.output;
1040
1099
  else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'output'; expected a non-empty string or false.`);
@@ -1500,6 +1559,7 @@ function applyBuiltinOverride(
1500
1559
  };
1501
1560
 
1502
1561
  if (override.description !== undefined) next.description = override.description;
1562
+ if (override.advertise !== undefined) next.advertise = override.advertise;
1503
1563
  if (override.machine !== undefined) { if (override.machine === false) delete next.machine; else next.machine = override.machine; }
1504
1564
  if (override.output !== undefined) { if (override.output === false) delete next.output; else next.output = override.output; }
1505
1565
  if (override.outputMode !== undefined) next.outputMode = override.outputMode;
@@ -2072,8 +2132,11 @@ function parseAgentRunnerFrontmatter(raw: string | undefined, agentName: string)
2072
2132
 
2073
2133
  function validateExternalRunnerProfile(frontmatter: Record<string, string>, agentName: string, runner: AgentRunnerConfig | undefined): void {
2074
2134
  if (runner?.type !== "external-cli" && runner?.type !== "external-job") return;
2135
+ // The code-owned Claude Code adapters accept an explicit model and thinking level:
2136
+ // both are translated into their own argv rather than into a Pi child model.
2137
+ const adapterAcceptsOverrides = runner.type === "external-cli" && isClaudeCodeAdapterId(runner.adapter);
2075
2138
  const unsupported = ["tools", "excludeTools", "allowNestedSubagents", "allowedAgents", "model", "thinking", "extensions", "subagentOnlyExtensions", "mutationTools", "maxSubagentDepth", "skills", "skill", "skillPath", "toolBudget", "sandbox", "permission-profile", "permission", "permissions"]
2076
- .filter((field) => frontmatter[field] !== undefined);
2139
+ .filter((field) => frontmatter[field] !== undefined && !(adapterAcceptsOverrides && (field === "model" || field === "thinking")));
2077
2140
  if (unsupported.length > 0) {
2078
2141
  throw new Error(`Agent '${agentName}' uses runner.type='${runner.type}' and declares unsupported Pi-only fields: ${unsupported.join(", ")}.`);
2079
2142
  }
@@ -6,6 +6,7 @@ import { resolveExecutionAgentScope } from "../agents/agent-scope.ts";
6
6
  import { normalizeSkillInput, resolveSkillsWithFallback } from "../agents/skills.ts";
7
7
  import { inheritsParentModel, resolveEffectiveSubagentModel, resolveModelOrigin, resolveModelSelection, type AvailableModelInfo, type ParentModel } from "../runs/shared/model-resolution.ts";
8
8
  import { resolveModelScopesForAgent } from "../runs/shared/model-scope.ts";
9
+ import { assertClaudeCodeModelScope, isClaudeCodeAdapterId, resolveClaudeCodeOverride } from "../runs/shared/claude-code-adapter.ts";
9
10
  import { applyThinkingSuffix, resolvePiLaunchToolPlan, type PiLaunchToolPlan } from "../runs/shared/child-tool-plan.ts";
10
11
  import { buildEffectiveSystemPrompt } from "../runs/shared/effective-system-prompt.ts";
11
12
  import { normalizeSingleOutputOverride, resolveSingleOutputPath } from "../runs/shared/single-output.ts";
@@ -15,7 +16,7 @@ import { assertThinkingWithinCeiling, intersectThinkingCeilings, type ThinkingLe
15
16
  import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type IntercomBridgeConfig, type IntercomBridgeMode, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
16
17
  import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
17
18
  import { resolvePermissionRules } from "../runs/shared/permissions.ts";
18
- import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
19
+ import type { McpRuntimeSnapshotHost, ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
19
20
  import { resolveStepBehavior } from "../shared/settings.ts";
20
21
  import { canPreferForkFromSnapshot, resolveSubagentLaunchContext } from "../shared/fork-context.ts";
21
22
  import { loadConfig } from "../extension/config.ts";
@@ -27,7 +28,7 @@ import { resultFilePath } from "../runs/background/result-files.ts";
27
28
  import { nestedResultsPath } from "../runs/shared/nested-events.ts";
28
29
  import { normalizeExtensionBindings, type ExtensionBindings } from "../runs/shared/extension-bindings.ts";
29
30
  import { projectScopedProfileTrustError } from "../runs/shared/sandbox-profile-guard.ts";
30
- import { resolveRequiredChildExtensions } from "../shared/required-child-extensions.ts";
31
+ import { assertRequiredChildExtensionsAdmitted, resolveRequiredChildExtensions } from "../shared/required-child-extensions.ts";
31
32
 
32
33
  // v3: the contract reports the resolved Intercom bridge state and binds its
33
34
  // prompt and tools into launchContractDigest, matching execution (#2127).
@@ -46,10 +47,11 @@ export type SubagentLaunchContractReasonCode =
46
47
  | "unsupported_mode"
47
48
  | "restricted_agent"
48
49
  | "thinking_ceiling"
50
+ | "model_scope"
49
51
  | "invalid_extension_bindings"
50
- | "untrusted_project"
51
- | "sandbox_unavailable"
52
- | "permission_profile_unavailable"
52
+ | "untrusted_project"
53
+ | "sandbox_unavailable"
54
+ | "permission_profile_unavailable"
53
55
  | "invalid_intercom_bridge";
54
56
 
55
57
  export type SubagentLaunchContractDiagnosticCode = SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning" | "workspace_scope_authority";
@@ -72,6 +74,8 @@ export interface SubagentLaunchContractInput {
72
74
  thinkingCeiling?: ThinkingLevel;
73
75
  inheritedThinkingCeiling?: ThinkingLevel;
74
76
  parentModel?: ParentModel;
77
+ /** Scoped-model snapshot (`provider/id` strings); drives the `scoped` allow token. Omitting it degrades `scoped` to `inherit`, so callers comparing preflight with execution must pass the session snapshot. */
78
+ scopedModelIds?: readonly string[];
75
79
  availableModels?: ReadonlyArray<AvailableModelInfo | { provider: string; id: string; fullId?: string; reasoning?: boolean }>;
76
80
  preferredProvider?: string;
77
81
  skill?: string | string[] | boolean;
@@ -94,12 +98,14 @@ export interface SubagentLaunchContractInput {
94
98
  nestedRootRunId?: string;
95
99
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
96
100
  inheritedCapabilityCeiling?: ResolvedSubagentCapabilityCeiling;
97
- /** Host-affirmed trust state for a project-scoped profile selection. */
98
- projectTrusted?: boolean;
99
- /** Exact trusted project cwd. When omitted, an affirmative trust assertion applies only to `cwd`. */
100
- trustedProjectCwd?: string;
101
- /** Builtin tool names the host runtime provides; used to intersect agent-declared tools. */
102
- hostAvailableBuiltins?: readonly string[];
101
+ /** Host-affirmed trust state for a project-scoped profile selection. */
102
+ projectTrusted?: boolean;
103
+ /** Exact trusted project cwd. When omitted, an affirmative trust assertion applies only to `cwd`. */
104
+ trustedProjectCwd?: string;
105
+ /** Builtin tool names the host runtime provides; used to intersect agent-declared tools. */
106
+ hostAvailableBuiltins?: readonly string[];
107
+ /** The calling extension's `pi`, so `mcp:` selectors resolve against the MCP the launch uses. Without it, preflight cannot see Pi's built-in MCP and resolves through pi-mcp-adapter's configuration. */
108
+ runtimeSnapshotHost?: McpRuntimeSnapshotHost;
103
109
  /** Per-launch bridge config; replaces the global `intercomBridge` config exactly as the tool and delegation overrides do. */
104
110
  intercomBridge?: IntercomBridgeConfig;
105
111
  /**
@@ -189,7 +195,7 @@ export interface SubagentLaunchContract {
189
195
  model?: string;
190
196
  thinking?: string;
191
197
  thinkingCeiling?: ThinkingLevel;
192
- sandbox?: string;
198
+ sandbox?: string;
193
199
  systemPromptMode: AgentConfig["systemPromptMode"];
194
200
  inheritProjectContext: boolean;
195
201
  inheritGlobalContext: boolean;
@@ -212,17 +218,28 @@ export type SubagentLaunchContractResult =
212
218
  | { ok: true; contract: SubagentLaunchContract }
213
219
  | { ok: false; code: SubagentLaunchContractReasonCode; message: string; diagnostics: SubagentLaunchContractDiagnostic[] };
214
220
 
221
+ /**
222
+ * Classify a Claude Code override failure for the launch contract. The messages
223
+ * are owned by the adapter and the scope check, so this maps them explicitly
224
+ * instead of defaulting every rejection to the ceiling.
225
+ */
226
+ function claudeCodeFailureCode(message: string): SubagentLaunchContractReasonCode {
227
+ if (message.includes("subagent model scope")) return "model_scope";
228
+ if (message.startsWith("Thinking level '")) return "thinking_ceiling";
229
+ return "unsupported_mode";
230
+ }
231
+
215
232
  function packageVersion(): string {
216
233
  const packagePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json");
217
- try {
218
- const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8")) as { version?: unknown };
219
- if (typeof parsed.version !== "string" || !parsed.version.trim()) {
220
- throw new Error("version must be a non-empty string.");
234
+ try {
235
+ const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8")) as { version?: unknown };
236
+ if (typeof parsed.version !== "string" || !parsed.version.trim()) {
237
+ throw new Error("version must be a non-empty string.");
238
+ }
239
+ return parsed.version;
240
+ } catch (error) {
241
+ throw new Error(`Invalid package version in '${packagePath}': ${error instanceof Error ? error.message : String(error)}`);
221
242
  }
222
- return parsed.version;
223
- } catch (error) {
224
- throw new Error(`Invalid package version in '${packagePath}': ${error instanceof Error ? error.message : String(error)}`);
225
- }
226
243
  }
227
244
 
228
245
  function digestContract(contract: Omit<SubagentLaunchContract, "digest">): string {
@@ -350,38 +367,38 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
350
367
  diagnostics.push({ code: "host_required", severity: "host-required", message: "The intercomBridge instruction file names the supervisor session; supply orchestratorTarget to bind the exact child prompt." });
351
368
  }
352
369
  const agent = applyIntercomBridgeToAgent(definitionAgent, bridge);
353
- const trustedProjectCwd = input.projectTrusted === true
354
- ? path.resolve(input.trustedProjectCwd ?? effectiveCwd)
355
- : undefined;
356
- const projectScoped = agent.source === "project" || agent.override?.scope === "project";
357
- const profileTrustError = projectScopedProfileTrustError({
358
- kind: "sandbox",
359
- agentName: agent.name,
360
- profileName: agent.sandbox ?? "",
361
- projectScoped: Boolean(agent.sandbox) && projectScoped,
362
- trustedCwd: trustedProjectCwd,
363
- effectiveCwd,
364
- messageStyle: "preflight",
365
- }) ?? projectScopedProfileTrustError({
366
- kind: "permission",
367
- agentName: agent.name,
368
- profileName: agent.permissionProfile ?? "",
369
- projectScoped: Boolean(agent.permissionProfile) && projectScoped,
370
- trustedCwd: trustedProjectCwd,
371
- effectiveCwd,
372
- messageStyle: "preflight",
373
- });
374
- if (profileTrustError) {
375
- return { ok: false, code: "untrusted_project", message: profileTrustError, diagnostics: [{ code: "untrusted_project", severity: "error", message: profileTrustError }] };
376
- }
377
- if (agent.sandbox && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
378
- const message = `Agent '${agent.name}' requests sandbox profile '${agent.sandbox}', but runner.type='${agent.runner.type}' cannot load the native pi-sandbox extension.`;
379
- return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
380
- }
381
- if (agent.permissionProfile && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
382
- const message = `Agent '${agent.name}' requests permission profile '${agent.permissionProfile}', but runner.type='${agent.runner.type}' cannot load the native pi-permission-system extension.`;
383
- return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
384
- }
370
+ const trustedProjectCwd = input.projectTrusted === true
371
+ ? path.resolve(input.trustedProjectCwd ?? effectiveCwd)
372
+ : undefined;
373
+ const projectScoped = agent.source === "project" || agent.override?.scope === "project";
374
+ const profileTrustError = projectScopedProfileTrustError({
375
+ kind: "sandbox",
376
+ agentName: agent.name,
377
+ profileName: agent.sandbox ?? "",
378
+ projectScoped: Boolean(agent.sandbox) && projectScoped,
379
+ trustedCwd: trustedProjectCwd,
380
+ effectiveCwd,
381
+ messageStyle: "preflight",
382
+ }) ?? projectScopedProfileTrustError({
383
+ kind: "permission",
384
+ agentName: agent.name,
385
+ profileName: agent.permissionProfile ?? "",
386
+ projectScoped: Boolean(agent.permissionProfile) && projectScoped,
387
+ trustedCwd: trustedProjectCwd,
388
+ effectiveCwd,
389
+ messageStyle: "preflight",
390
+ });
391
+ if (profileTrustError) {
392
+ return { ok: false, code: "untrusted_project", message: profileTrustError, diagnostics: [{ code: "untrusted_project", severity: "error", message: profileTrustError }] };
393
+ }
394
+ if (agent.sandbox && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
395
+ const message = `Agent '${agent.name}' requests sandbox profile '${agent.sandbox}', but runner.type='${agent.runner.type}' cannot load the native pi-sandbox extension.`;
396
+ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
397
+ }
398
+ if (agent.permissionProfile && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
399
+ const message = `Agent '${agent.name}' requests permission profile '${agent.permissionProfile}', but runner.type='${agent.runner.type}' cannot load the native pi-permission-system extension.`;
400
+ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
401
+ }
385
402
  const effectiveCapabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
386
403
  const restrictionMessage = capabilityCeilingAgentRestrictionMessage(agent.name, effectiveCapabilityCeiling);
387
404
  if (restrictionMessage) return { ok: false, code: "restricted_agent", message: restrictionMessage, diagnostics };
@@ -409,12 +426,19 @@ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "un
409
426
  if (resolvedSkills.missing.length > 0) diagnostics.push({ code: "missing_skill", severity: "error", message: `Missing skills: ${resolvedSkills.missing.join(", ")}` });
410
427
 
411
428
  const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
429
+ // Machine placement has no preflight input; execution enforces it. Preview the runner-type admission here.
430
+ try {
431
+ assertRequiredChildExtensionsAdmitted([resolveRequiredChildExtensions(input.parentSessionId)], { agent: agent.name, runnerType: agent.runner?.type });
432
+ } catch (error) {
433
+ const message = error instanceof Error ? error.message : String(error);
434
+ return { ok: false, code: "unsupported_mode", message, diagnostics };
435
+ }
412
436
  if (externalRunner && behavior.outputSchema) {
413
437
  return { ok: false, code: "unsupported_mode", message: `Agent '${agent.name}' uses runner.type='${agent.runner?.type}' and does not support: structured output.`, diagnostics };
414
438
  }
415
439
  const availableModels = normalizeAvailableModels(input.availableModels);
416
440
  const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
417
- const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel);
441
+ const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel, input.scopedModelIds);
418
442
  const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
419
443
  const primaryModel = externalRunner
420
444
  ? undefined
@@ -442,6 +466,27 @@ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "un
442
466
  return { ok: false, code: "thinking_ceiling", message, diagnostics };
443
467
  }
444
468
  }
469
+ // The Claude Code adapters accept a model and a level that never become a Pi child
470
+ // model, so validate has to run the same two checks the launch runs, or validate
471
+ // would report ok for a launch that then fails.
472
+ if (agent.runner?.type === "external-cli" && isClaudeCodeAdapterId(agent.runner.adapter)) {
473
+ try {
474
+ const override = resolveClaudeCodeOverride({
475
+ model: typeof input.model === "string" ? input.model : undefined,
476
+ agent,
477
+ thinking: typeof effectiveThinkingConfig === "string" ? effectiveThinkingConfig : undefined,
478
+ thinkingCeiling: intersectThinkingCeilings(discovered.maxThinking, input.thinkingCeiling, input.inheritedThinkingCeiling),
479
+ agentName: agent.name,
480
+ runId,
481
+ });
482
+ assertClaudeCodeModelScope({ scopes: modelScopes, model: override?.model, agent: agent.name, runId });
483
+ } catch (error) {
484
+ const message = error instanceof Error ? error.message : String(error);
485
+ const code = claudeCodeFailureCode(message);
486
+ diagnostics.push({ code, severity: "error", message });
487
+ return { ok: false, code, message, diagnostics };
488
+ }
489
+ }
445
490
  let toolPlan: PiLaunchToolPlan;
446
491
  const permissionRules = resolvePermissionRules(loadConfig().permissions, agent.permissions);
447
492
  const fast = input.fast ?? agent.fast;
@@ -463,15 +508,16 @@ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "un
463
508
  capabilityCeiling: effectiveCapabilityCeiling,
464
509
  agentName: agent.name,
465
510
  permissionRules,
466
- sandbox: agent.sandbox,
467
- permissionProfile: agent.permissionProfile,
468
- hostAvailableBuiltins: input.hostAvailableBuiltins,
511
+ sandbox: agent.sandbox,
512
+ permissionProfile: agent.permissionProfile,
513
+ hostAvailableBuiltins: input.hostAvailableBuiltins,
514
+ runtimeSnapshotHost: input.runtimeSnapshotHost,
469
515
  });
470
516
  } catch (error) {
471
517
  const message = error instanceof Error ? error.message : String(error);
472
- const code: SubagentLaunchContractReasonCode = agent.sandbox ? "sandbox_unavailable" : agent.permissionProfile ? "permission_profile_unavailable" : "denied_required_tool";
473
- diagnostics.push({ code, severity: "error", message });
474
- return { ok: false, code, message, diagnostics };
518
+ const code: SubagentLaunchContractReasonCode = agent.sandbox ? "sandbox_unavailable" : agent.permissionProfile ? "permission_profile_unavailable" : "denied_required_tool";
519
+ diagnostics.push({ code, severity: "error", message });
520
+ return { ok: false, code, message, diagnostics };
475
521
  }
476
522
  const artifactsEnabled = input.artifacts !== false;
477
523
  const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir) : undefined;
@@ -502,8 +548,8 @@ return { ok: false, code, message, diagnostics };
502
548
  model,
503
549
  ...(fast !== undefined ? { fast } : {}),
504
550
  ...(effectiveThinking ? { thinking: effectiveThinking } : {}),
505
- ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
506
- ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
551
+ ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
552
+ ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
507
553
  systemPrompt: buildEffectiveSystemPrompt({ agent, resolvedSkills: resolvedSkills.resolved, cwd: effectiveCwd, ...(outputPath ? { outputPath } : {}) }),
508
554
  skills: requestedSkills,
509
555
  toolPlan,
@@ -531,8 +577,8 @@ return { ok: false, code, message, diagnostics };
531
577
  ...(model ? { model } : {}),
532
578
  ...(effectiveThinking ? { thinking: effectiveThinking } : {}),
533
579
  ...(thinkingCeiling ? { thinkingCeiling } : {}),
534
- ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
535
- ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
580
+ ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
581
+ ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
536
582
  systemPromptMode: agent.systemPromptMode,
537
583
  inheritProjectContext: agent.inheritProjectContext,
538
584
  inheritGlobalContext: agent.inheritGlobalContext,
@@ -10,6 +10,11 @@ import { validatePermissionConfig } from "../runs/shared/permissions.ts";
10
10
  import { MAX_ABANDONED_SLOT_RELEASE_AFTER_MS, MIN_ABANDONED_SLOT_RELEASE_AFTER_MS } from "../runs/background/active-async-capacity.ts";
11
11
  import { normalizeWorktreeBranchPrefix } from "../runs/shared/worktree.ts";
12
12
  import { validateModelResponseAliases } from "../shared/model-response-aliases.ts";
13
+ import { validateDisabledFeatures } from "../shared/disabled-features.ts";
14
+
15
+ // Explicit route identity, worktree, checkpoint, and tool-surface policies must not be silently
16
+ // discarded and replaced by the built-in defaults after validation fails.
17
+ const FAIL_CLOSED_CONFIG_KEYS = ["worktreeProvider", "worktreeBranchPrefix", "modelResponseAliases", "modelExclusions", "checkpointBeforeDeadlineMs", "disabledFeatures", "scheduledRuns", "toolActivation", "authorityPolicy", "permissions", "toolBudget"];
13
18
 
14
19
  const ARTIFACT_DIR_PREFERENCES = new Set<ArtifactDirPreference>(["project", "session", "temp"]);
15
20
  const FLEET_KEYBINDING_ACTION_SET = new Set<string>(FLEET_KEYBINDING_ACTIONS);
@@ -55,6 +60,8 @@ export function resolveScheduledStoreRoot(value: string): string {
55
60
  function validateScheduledRunsConfig(value: unknown): void {
56
61
  if (value === undefined) return;
57
62
  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("config.scheduledRuns must be a JSON object");
63
+ const enabled = (value as Record<string, unknown>).enabled;
64
+ if (enabled !== undefined && typeof enabled !== "boolean") throw new Error("config.scheduledRuns.enabled must be a boolean");
58
65
  const storeRoot = (value as Record<string, unknown>).storeRoot;
59
66
  if (storeRoot === undefined) return;
60
67
  if (typeof storeRoot !== "string" || !storeRoot.trim()) throw new Error("config.scheduledRuns.storeRoot must be a non-empty string");
@@ -165,10 +172,17 @@ function validateConfig(config: Record<string, unknown>): void {
165
172
  if (config.resultScanLogging !== undefined && config.resultScanLogging !== "all" && config.resultScanLogging !== "activity" && config.resultScanLogging !== "off") {
166
173
  throw new Error('config.resultScanLogging must be "all", "activity", or "off"');
167
174
  }
175
+ if (config.asyncWidgetCollapsed !== undefined && typeof config.asyncWidgetCollapsed !== "boolean") {
176
+ throw new Error("config.asyncWidgetCollapsed must be a boolean");
177
+ }
178
+ if (config.toolActivation !== undefined && config.toolActivation !== "auto" && config.toolActivation !== "dynamic" && config.toolActivation !== "eager") {
179
+ throw new Error('config.toolActivation must be "auto", "dynamic", or "eager"');
180
+ }
168
181
  validateMissionStoreConfig(config.missions);
169
182
  validateAuthorityPolicy(config.authorityPolicy);
170
183
  validatePermissionConfig(config.permissions);
171
184
  validateScheduledRunsConfig(config.scheduledRuns);
185
+ validateDisabledFeatures(config.disabledFeatures);
172
186
  validateFleetKeybindingsConfig(config.fleetKeybindings);
173
187
  validateArtifactConfig(config.artifactConfig);
174
188
  validateCapacityConfig(config.capacity);
@@ -217,12 +231,9 @@ export function loadConfig(): ExtensionConfig {
217
231
  return readConfigForUpdate(configPath);
218
232
  } catch (error) {
219
233
  if (error instanceof PrunedForkConfigError) throw error;
220
- // Explicit route identity, worktree, and checkpoint policies must not be silently
221
- // discarded and replaced by the built-in defaults after validation fails.
222
234
  try {
223
235
  const raw = JSON.parse(fs.readFileSync(configPath, "utf-8")) as unknown;
224
- if (raw && typeof raw === "object" && !Array.isArray(raw)
225
- && (Object.hasOwn(raw, "worktreeProvider") || Object.hasOwn(raw, "worktreeBranchPrefix") || Object.hasOwn(raw, "modelResponseAliases") || Object.hasOwn(raw, "modelExclusions") || Object.hasOwn(raw, "checkpointBeforeDeadlineMs"))) throw error;
236
+ if (raw && typeof raw === "object" && !Array.isArray(raw) && FAIL_CLOSED_CONFIG_KEYS.some((key) => Object.hasOwn(raw, key))) throw error;
226
237
  } catch (readError) {
227
238
  if (readError === error) throw error;
228
239
  }
@@ -10,6 +10,8 @@ export interface SubagentControlMessageDetails {
10
10
  asyncDir?: string;
11
11
  childIntercomTarget?: string;
12
12
  noticeText?: string;
13
+ /** Status-only copy of a supervisor request; the tracker sends the notice later if the request is still unanswered. */
14
+ noticeDeferred?: boolean;
13
15
  }
14
16
 
15
17
  export function controlNoticeTarget(details: SubagentControlMessageDetails): string | undefined {
@@ -48,6 +50,7 @@ export function handleSubagentControlNotice(input: {
48
50
  details: SubagentControlMessageDetails;
49
51
  }): void {
50
52
  if (!input.details?.event || input.details.event.type === "active_long_running") return;
53
+ if (input.details.noticeDeferred) return;
51
54
  if (input.details.source === "foreground") {
52
55
  // A foreground tool blocks Pi from displaying this message. The run can
53
56
  // finish before Pi flushes it, and queued messages cannot be withdrawn.
@@ -234,6 +234,7 @@ function formatPermissionSystemSection(): string[] {
234
234
 
235
235
  function formatWorkflowScriptSection(): string[] {
236
236
  return [
237
+ "- launch: write a ```js workflow block in the reply, then call subagent({ workflow: true }); or pass a file as workflow: \"./path.js\"",
237
238
  "- helpers: runs.run, runs.all, runs.steer, runs.status, runs.ref/refs, emit, console",
238
239
  "- recovery: if runs.all is missing, reload or update pi-subagents; await Promise.all([runs.run(...)]) is also supported",
239
240
  ];
@@ -13,10 +13,13 @@ import { createNativeSupervisorChannel, NATIVE_SUPERVISOR_TOOL_NAME, resolveSupe
13
13
  import { readStatus } from "../shared/utils.ts";
14
14
  import { resolveSubagentIntercomTarget } from "../intercom/intercom-bridge.ts";
15
15
  import { createSubagentParamsSchema } from "./schemas.ts";
16
+ import { resolveDisabledFeatureSurface } from "../shared/disabled-features.ts";
16
17
  import { finalizeToolResult } from "./tool-result.ts";
18
+ import { removedModelWorkflowFieldError } from "./public-execution.ts";
17
19
  import { loadConfig, resolveAsyncByDefault } from "./config.ts";
18
20
  import { SUBAGENT_ASYNC_STARTED_EVENT, type AsyncStartedEvent, type Details, type SubagentState } from "../shared/types.ts";
19
21
  import { createChildExternalJobBridgeSweeper } from "../runs/shared/external-job-bridge.ts";
22
+ import { MODEL_ONLY_TOOL } from "../shared/extension-context.ts";
20
23
 
21
24
  function getSubagentSessionRoot(parentSessionFile: string | null): string {
22
25
  if (parentSessionFile) {
@@ -211,17 +214,23 @@ export default function registerFanoutChildSubagentExtension(pi: ExtensionAPI, c
211
214
  findPendingAsks: supervisorChannel.findPendingAsks,
212
215
  });
213
216
 
214
- const params = createSubagentParamsSchema();
217
+ const disabledFeatures = resolveDisabledFeatureSurface(config);
218
+ const listEnabled = (actions: string[]) => actions.filter((action) => !disabledFeatures.actions.has(action)).join(", ");
219
+ const blockedActions = listEnabled(["create", "update", "delete", "eject", "disable", "enable", "reset", "grant-spawn-budget", "lane.recordMerge", "lane.recordSupersession"]);
220
+ const params = createSubagentParamsSchema(disabledFeatures);
215
221
  const tool: ToolDefinition<typeof params, Details> = {
216
222
  name: "subagent",
223
+ ...MODEL_ONLY_TOOL,
217
224
  label: "Subagent",
218
225
  description: [
219
226
  "Delegate to subagents from child-safe fanout mode.",
220
- "Allowed management/control actions: list, get, status, lane.status, interrupt, resume, steer, doctor.",
221
- "Mutating management actions (create, update, delete, eject, disable, enable, reset, grant-spawn-budget, lane.recordMerge, lane.recordSupersession) are blocked in this mode.",
227
+ `Allowed management/control actions: ${listEnabled(["list", "get", "status", "lane.status", "interrupt", "resume", "steer", "doctor"])}.`,
228
+ ...(blockedActions ? [`Mutating management actions (${blockedActions}) are blocked in this mode.`] : []),
222
229
  ].join("\n"),
223
230
  parameters: params,
224
231
  async execute(id, params, signal, onUpdate, ctx) {
232
+ const removedField = removedModelWorkflowFieldError(params);
233
+ if (removedField) throw new Error(removedField);
225
234
  return finalizeToolResult(await executor.executePublic(id, params as SubagentParamsLike, signal ?? new AbortController().signal, onUpdate, ctx));
226
235
  },
227
236
  };
@@ -13,6 +13,7 @@ import { buildAgentMemoryInjection } from "../agents/agent-memory.ts";
13
13
  import { appendAgentRefinementOverlay } from "../agents/agent-refinements.ts";
14
14
  import { rewriteSubagentPrompt } from "../runs/shared/subagent-prompt-runtime.ts";
15
15
  import { resolveExistingReadPaths } from "../shared/settings.ts";
16
+ import { MODEL_ONLY_TOOL } from "../shared/extension-context.ts";
16
17
 
17
18
  interface PendingRequest { operation: "prompt" | "steer" | "follow-up" | "abort" | "supervisor-reply"; text?: string; supervisorId?: string }
18
19
  interface BridgeContext {
@@ -75,6 +76,7 @@ export default function registerHerdrPiBridge(pi: ExtensionAPI): void {
75
76
 
76
77
  pi.registerTool({
77
78
  name: "contact_supervisor",
79
+ ...MODEL_ONLY_TOOL,
78
80
  label: "Contact supervisor",
79
81
  description: "Contact the parent/supervisor session for a blocking decision, structured interview, or progress update.",
80
82
  parameters: Type.Object({ reason: Type.Union([Type.Literal("need_decision"), Type.Literal("interview_request"), Type.Literal("progress_update")]), message: Type.Optional(Type.String({ maxLength: 65_536 })), interview: Type.Optional(Type.Unknown()) }, { additionalProperties: false }),