@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
@@ -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);
@@ -89,6 +89,7 @@ export interface BuiltinAgentOverrideBase {
89
89
 
90
90
  interface BuiltinAgentOverrideConfig {
91
91
  description?: string;
92
+ advertise?: boolean;
92
93
  machine?: string | false;
93
94
  output?: string | false;
94
95
  outputMode?: OutputMode;
@@ -1035,6 +1036,11 @@ function parseBuiltinOverrideEntry(
1035
1036
  }
1036
1037
  }
1037
1038
 
1039
+ if ("advertise" in input) {
1040
+ if (typeof input.advertise === "boolean") override.advertise = input.advertise;
1041
+ else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'advertise'; expected a boolean.`);
1042
+ }
1043
+
1038
1044
  if ("output" in input) {
1039
1045
  if ((typeof input.output === "string" && input.output.trim()) || input.output === false) override.output = input.output;
1040
1046
  else throw new Error(`Builtin override '${name}' in '${filePath}' has invalid 'output'; expected a non-empty string or false.`);
@@ -1500,6 +1506,7 @@ function applyBuiltinOverride(
1500
1506
  };
1501
1507
 
1502
1508
  if (override.description !== undefined) next.description = override.description;
1509
+ if (override.advertise !== undefined) next.advertise = override.advertise;
1503
1510
  if (override.machine !== undefined) { if (override.machine === false) delete next.machine; else next.machine = override.machine; }
1504
1511
  if (override.output !== undefined) { if (override.output === false) delete next.output; else next.output = override.output; }
1505
1512
  if (override.outputMode !== undefined) next.outputMode = override.outputMode;
@@ -15,7 +15,7 @@ import { assertThinkingWithinCeiling, intersectThinkingCeilings, type ThinkingLe
15
15
  import { SUBAGENT_LIFECYCLE_ARTIFACT_VERSION, type ArtifactDirPreference, type ArtifactPaths, type IntercomBridgeConfig, type IntercomBridgeMode, type JsonSchemaObject, type OutputMode } from "../shared/types.ts";
16
16
  import { capabilityCeilingAgentRestrictionMessage, intersectSubagentCapabilityCeilings, type ResolvedSubagentCapabilityCeiling, type SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
17
17
  import { resolvePermissionRules } from "../runs/shared/permissions.ts";
18
- import type { ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
18
+ import type { McpRuntimeSnapshotHost, ResolvedMcpDirectToolSelection } from "../runs/shared/mcp-direct-tool-allowlist.ts";
19
19
  import { resolveStepBehavior } from "../shared/settings.ts";
20
20
  import { canPreferForkFromSnapshot, resolveSubagentLaunchContext } from "../shared/fork-context.ts";
21
21
  import { loadConfig } from "../extension/config.ts";
@@ -47,9 +47,9 @@ export type SubagentLaunchContractReasonCode =
47
47
  | "restricted_agent"
48
48
  | "thinking_ceiling"
49
49
  | "invalid_extension_bindings"
50
- | "untrusted_project"
51
- | "sandbox_unavailable"
52
- | "permission_profile_unavailable"
50
+ | "untrusted_project"
51
+ | "sandbox_unavailable"
52
+ | "permission_profile_unavailable"
53
53
  | "invalid_intercom_bridge";
54
54
 
55
55
  export type SubagentLaunchContractDiagnosticCode = SubagentLaunchContractReasonCode | "host_required" | "snapshot_warning" | "workspace_scope_authority";
@@ -72,6 +72,8 @@ export interface SubagentLaunchContractInput {
72
72
  thinkingCeiling?: ThinkingLevel;
73
73
  inheritedThinkingCeiling?: ThinkingLevel;
74
74
  parentModel?: ParentModel;
75
+ /** 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. */
76
+ scopedModelIds?: readonly string[];
75
77
  availableModels?: ReadonlyArray<AvailableModelInfo | { provider: string; id: string; fullId?: string; reasoning?: boolean }>;
76
78
  preferredProvider?: string;
77
79
  skill?: string | string[] | boolean;
@@ -94,12 +96,14 @@ export interface SubagentLaunchContractInput {
94
96
  nestedRootRunId?: string;
95
97
  capabilityCeiling?: ResolvedSubagentCapabilityCeiling;
96
98
  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[];
99
+ /** Host-affirmed trust state for a project-scoped profile selection. */
100
+ projectTrusted?: boolean;
101
+ /** Exact trusted project cwd. When omitted, an affirmative trust assertion applies only to `cwd`. */
102
+ trustedProjectCwd?: string;
103
+ /** Builtin tool names the host runtime provides; used to intersect agent-declared tools. */
104
+ hostAvailableBuiltins?: readonly string[];
105
+ /** 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. */
106
+ runtimeSnapshotHost?: McpRuntimeSnapshotHost;
103
107
  /** Per-launch bridge config; replaces the global `intercomBridge` config exactly as the tool and delegation overrides do. */
104
108
  intercomBridge?: IntercomBridgeConfig;
105
109
  /**
@@ -189,7 +193,7 @@ export interface SubagentLaunchContract {
189
193
  model?: string;
190
194
  thinking?: string;
191
195
  thinkingCeiling?: ThinkingLevel;
192
- sandbox?: string;
196
+ sandbox?: string;
193
197
  systemPromptMode: AgentConfig["systemPromptMode"];
194
198
  inheritProjectContext: boolean;
195
199
  inheritGlobalContext: boolean;
@@ -214,15 +218,15 @@ export type SubagentLaunchContractResult =
214
218
 
215
219
  function packageVersion(): string {
216
220
  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.");
221
+ try {
222
+ const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8")) as { version?: unknown };
223
+ if (typeof parsed.version !== "string" || !parsed.version.trim()) {
224
+ throw new Error("version must be a non-empty string.");
225
+ }
226
+ return parsed.version;
227
+ } catch (error) {
228
+ throw new Error(`Invalid package version in '${packagePath}': ${error instanceof Error ? error.message : String(error)}`);
221
229
  }
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
230
  }
227
231
 
228
232
  function digestContract(contract: Omit<SubagentLaunchContract, "digest">): string {
@@ -350,38 +354,38 @@ export async function resolveSubagentLaunchContract(input: SubagentLaunchContrac
350
354
  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
355
  }
352
356
  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
- }
357
+ const trustedProjectCwd = input.projectTrusted === true
358
+ ? path.resolve(input.trustedProjectCwd ?? effectiveCwd)
359
+ : undefined;
360
+ const projectScoped = agent.source === "project" || agent.override?.scope === "project";
361
+ const profileTrustError = projectScopedProfileTrustError({
362
+ kind: "sandbox",
363
+ agentName: agent.name,
364
+ profileName: agent.sandbox ?? "",
365
+ projectScoped: Boolean(agent.sandbox) && projectScoped,
366
+ trustedCwd: trustedProjectCwd,
367
+ effectiveCwd,
368
+ messageStyle: "preflight",
369
+ }) ?? projectScopedProfileTrustError({
370
+ kind: "permission",
371
+ agentName: agent.name,
372
+ profileName: agent.permissionProfile ?? "",
373
+ projectScoped: Boolean(agent.permissionProfile) && projectScoped,
374
+ trustedCwd: trustedProjectCwd,
375
+ effectiveCwd,
376
+ messageStyle: "preflight",
377
+ });
378
+ if (profileTrustError) {
379
+ return { ok: false, code: "untrusted_project", message: profileTrustError, diagnostics: [{ code: "untrusted_project", severity: "error", message: profileTrustError }] };
380
+ }
381
+ if (agent.sandbox && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
382
+ const message = `Agent '${agent.name}' requests sandbox profile '${agent.sandbox}', but runner.type='${agent.runner.type}' cannot load the native pi-sandbox extension.`;
383
+ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
384
+ }
385
+ if (agent.permissionProfile && (agent.runner?.type === "external-cli" || agent.runner?.type === "external-job")) {
386
+ const message = `Agent '${agent.name}' requests permission profile '${agent.permissionProfile}', but runner.type='${agent.runner.type}' cannot load the native pi-permission-system extension.`;
387
+ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "unsupported_mode", severity: "error", message }] };
388
+ }
385
389
  const effectiveCapabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
386
390
  const restrictionMessage = capabilityCeilingAgentRestrictionMessage(agent.name, effectiveCapabilityCeiling);
387
391
  if (restrictionMessage) return { ok: false, code: "restricted_agent", message: restrictionMessage, diagnostics };
@@ -414,7 +418,7 @@ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "un
414
418
  }
415
419
  const availableModels = normalizeAvailableModels(input.availableModels);
416
420
  const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
417
- const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel);
421
+ const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel, input.scopedModelIds);
418
422
  const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
419
423
  const primaryModel = externalRunner
420
424
  ? undefined
@@ -463,15 +467,16 @@ return { ok: false, code: "unsupported_mode", message, diagnostics: [{ code: "un
463
467
  capabilityCeiling: effectiveCapabilityCeiling,
464
468
  agentName: agent.name,
465
469
  permissionRules,
466
- sandbox: agent.sandbox,
467
- permissionProfile: agent.permissionProfile,
468
- hostAvailableBuiltins: input.hostAvailableBuiltins,
470
+ sandbox: agent.sandbox,
471
+ permissionProfile: agent.permissionProfile,
472
+ hostAvailableBuiltins: input.hostAvailableBuiltins,
473
+ runtimeSnapshotHost: input.runtimeSnapshotHost,
469
474
  });
470
475
  } catch (error) {
471
476
  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 };
477
+ const code: SubagentLaunchContractReasonCode = agent.sandbox ? "sandbox_unavailable" : agent.permissionProfile ? "permission_profile_unavailable" : "denied_required_tool";
478
+ diagnostics.push({ code, severity: "error", message });
479
+ return { ok: false, code, message, diagnostics };
475
480
  }
476
481
  const artifactsEnabled = input.artifacts !== false;
477
482
  const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir) : undefined;
@@ -502,8 +507,8 @@ return { ok: false, code, message, diagnostics };
502
507
  model,
503
508
  ...(fast !== undefined ? { fast } : {}),
504
509
  ...(effectiveThinking ? { thinking: effectiveThinking } : {}),
505
- ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
506
- ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
510
+ ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
511
+ ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
507
512
  systemPrompt: buildEffectiveSystemPrompt({ agent, resolvedSkills: resolvedSkills.resolved, cwd: effectiveCwd, ...(outputPath ? { outputPath } : {}) }),
508
513
  skills: requestedSkills,
509
514
  toolPlan,
@@ -531,8 +536,8 @@ return { ok: false, code, message, diagnostics };
531
536
  ...(model ? { model } : {}),
532
537
  ...(effectiveThinking ? { thinking: effectiveThinking } : {}),
533
538
  ...(thinkingCeiling ? { thinkingCeiling } : {}),
534
- ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
535
- ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
539
+ ...(agent.sandbox ? { sandbox: agent.sandbox } : {}),
540
+ ...(agent.permissionProfile ? { permissionProfile: agent.permissionProfile } : {}),
536
541
  systemPromptMode: agent.systemPromptMode,
537
542
  inheritProjectContext: agent.inheritProjectContext,
538
543
  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"];
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,14 @@ 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.toolActivation !== undefined && config.toolActivation !== "auto" && config.toolActivation !== "dynamic" && config.toolActivation !== "eager") {
176
+ throw new Error('config.toolActivation must be "auto", "dynamic", or "eager"');
177
+ }
168
178
  validateMissionStoreConfig(config.missions);
169
179
  validateAuthorityPolicy(config.authorityPolicy);
170
180
  validatePermissionConfig(config.permissions);
171
181
  validateScheduledRunsConfig(config.scheduledRuns);
182
+ validateDisabledFeatures(config.disabledFeatures);
172
183
  validateFleetKeybindingsConfig(config.fleetKeybindings);
173
184
  validateArtifactConfig(config.artifactConfig);
174
185
  validateCapacityConfig(config.capacity);
@@ -217,12 +228,9 @@ export function loadConfig(): ExtensionConfig {
217
228
  return readConfigForUpdate(configPath);
218
229
  } catch (error) {
219
230
  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
231
  try {
223
232
  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;
233
+ if (raw && typeof raw === "object" && !Array.isArray(raw) && FAIL_CLOSED_CONFIG_KEYS.some((key) => Object.hasOwn(raw, key))) throw error;
226
234
  } catch (readError) {
227
235
  if (readError === error) throw error;
228
236
  }
@@ -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 }),