pi-subagents 0.79.2 → 0.81.0

package/bundle/preflight.js

@@ -0,0 +1,425 @@
+import {
+  buildEffectiveSystemPrompt,
+  canPreferForkFromSnapshot,
+  resolveSubagentLaunchContext
+} from "./chunk-ARRKBB2B.js";
+import "./chunk-EYNJ6VL6.js";
+import {
+  loadConfig
+} from "./chunk-WSBNENFS.js";
+import {
+  nestedResultsPath,
+  processTerminalCandidatePath,
+  processTerminalPath,
+  resultFilePath
+} from "./chunk-VJHOELQP.js";
+import {
+  applyIntercomBridgeToAgent,
+  resolveIntercomBridge,
+  validateIntercomBridgeConfig
+} from "./chunk-ZP3HODFH.js";
+import {
+  AGENT_DEFINITION_PROJECTION_VERSION,
+  resolveLaunchBinding,
+  stableJsonDigest
+} from "./chunk-7F6RKT6W.js";
+import {
+  applyThinkingSuffix,
+  resolvePiLaunchToolPlan
+} from "./chunk-G5DKFLLI.js";
+import {
+  assertRequiredChildExtensionsAdmitted,
+  resolveRequiredChildExtensions
+} from "./chunk-CTPAE36Y.js";
+import {
+  getArtifactPaths,
+  getArtifactsDir
+} from "./chunk-3DC5KBVP.js";
+import {
+  assertClaudeCodeModelScope,
+  assertThinkingWithinCeiling,
+  discoverAgentSnapshot,
+  findBlockingAgentDiagnostic,
+  formatUnknownAgentError,
+  inheritsParentModel,
+  intersectThinkingCeilings,
+  isClaudeCodeAdapterId,
+  normalizeExtensionBindings,
+  normalizeSingleOutputOverride,
+  normalizeSkillInput,
+  projectScopeRequiresTrustMessage,
+  resolveAgentName,
+  resolveClaudeCodeOverride,
+  resolveEffectiveSubagentModel,
+  resolveEffectiveThinking,
+  resolveExecutionAgentScope,
+  resolveModelOrigin,
+  resolveModelScopesForAgent,
+  resolveModelSelection,
+  resolvePermissionRules,
+  resolveSingleOutputPath,
+  resolveSkillsWithFallback,
+  resolveStepBehavior,
+  unknownAgentDiagnosticContext
+} from "./chunk-ZBC44JJ3.js";
+import {
+  DIRS,
+  SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+  TEMP_ROOT_DIR
+} from "./chunk-5LFLVSTM.js";
+import "./chunk-YFCK7H2S.js";
+import {
+  capabilityCeilingAgentRestrictionMessage,
+  intersectSubagentCapabilityCeilings
+} from "./chunk-Z7KVHQHL.js";
+
+// src/api/preflight.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+var SUBAGENT_LAUNCH_CONTRACT_VERSION = 3;
+var PREFLIGHT_ORCHESTRATOR_TARGET = "preflight";
+function claudeCodeFailureCode(message) {
+  if (message.includes("subagent model scope")) return "model_scope";
+  if (message.startsWith("Thinking level '")) return "thinking_ceiling";
+  return "unsupported_mode";
+}
+function packageVersion() {
+  const packagePath = path.resolve(path.dirname(fileURLToPath(new URL("../src/api/preflight.js", import.meta.url).href)), "..", "..", "package.json");
+  const parsed = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+  if (typeof parsed.version !== "string" || !parsed.version.trim()) {
+    throw new Error(`Invalid package version in '${packagePath}'.`);
+  }
+  return parsed.version;
+}
+function digestContract(contract) {
+  return stableJsonDigest(contract);
+}
+function normalizeAvailableModels(models) {
+  return (models ?? []).map((model) => ({ ...model, fullId: model.fullId ?? `${model.provider}/${model.id}` }));
+}
+function resolveLaunchContractContext(input, agent) {
+  return resolveSubagentLaunchContext({
+    explicitContext: input.context,
+    agentDefaultContext: agent.defaultContext,
+    defaultSubagentContext: loadConfig().defaultSubagentContext,
+    canUseImplicitFork: canPreferForkFromSnapshot({
+      parentSessionFile: input.parentSessionFile,
+      leafId: input.parentLeafId
+    })
+  });
+}
+function taskWorkspaceScopeAuthorityDiagnostic(task) {
+  if (!task) return void 0;
+  const text = task.replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  const createsWorkspacePackage = /\b(?:add|create|introduce|make|set up)\b.{0,80}\b(?:new\s+)?(?:workspace\s+)?package\b/i.test(text) || /\b(?:new\s+)?package\b.{0,80}\b(?:workspace|monorepo)\b/i.test(text);
+  if (!createsWorkspacePackage) return void 0;
+  const packageOnlyAuthority = /\b(?:only|solely)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:package(?:\s+directory)?|packages\/[\w.-]+)\b/i.test(text) || /\b(?:do not|don't|must not)\b.{0,40}\b(?:edit|change|modify|touch|write(?:\s+to)?)\b.{0,80}\b(?:root|workspace|lockfile|metadata)\b/i.test(text) || /\bwithout\b.{0,40}\b(?:root|workspace|lockfile|metadata)\b.{0,40}\b(?:edit|change|modification|write)s?\b/i.test(text);
+  if (!packageOnlyAuthority) return void 0;
+  return {
+    code: "workspace_scope_authority",
+    severity: "warning",
+    message: "Task asks for a workspace package change while limiting authority to package-scope edits. New workspace packages often need root workspace metadata or lockfile changes, so confirm that authority before launch."
+  };
+}
+function candidateList(inputAgent, selected, all) {
+  return [...all.builtin, ...all.package, ...all.user, ...all.project].filter((agent) => Boolean(resolveAgentName(inputAgent, [agent]).agent)).map((agent) => ({
+    name: agent.name,
+    ...agent.localName ? { localName: agent.localName } : {},
+    ...agent.packageName ? { packageName: agent.packageName } : {},
+    source: agent.source,
+    filePath: agent.filePath,
+    ...agent.disabled === true ? { disabled: true } : {},
+    selected: Boolean(selected && agent.filePath === selected.filePath && agent.name === selected.name)
+  }));
+}
+async function resolveSubagentLaunchContract(input) {
+  const diagnostics = [];
+  const authorityDiagnostic = taskWorkspaceScopeAuthorityDiagnostic(input.task);
+  if (authorityDiagnostic) diagnostics.push(authorityDiagnostic);
+  const effectiveCwd = path.resolve(input.cwd);
+  try {
+    if (!fs.statSync(effectiveCwd).isDirectory()) {
+      return { ok: false, code: "invalid_cwd", message: `cwd '${effectiveCwd}' is not a directory.`, diagnostics };
+    }
+  } catch (error) {
+    const detail = error instanceof Error ? ` ${error.message}` : "";
+    return { ok: false, code: "invalid_cwd", message: `cwd '${effectiveCwd}' is not a directory.${detail}`, diagnostics };
+  }
+  if (input.context !== void 0 && input.context !== "fresh" && input.context !== "fork") {
+    return { ok: false, code: "unsupported_mode", message: `Unsupported context '${String(input.context)}'; expected 'fresh' or 'fork'.`, diagnostics };
+  }
+  if (input.artifactDir !== void 0 && input.artifactDir !== "project" && input.artifactDir !== "session" && input.artifactDir !== "temp") {
+    return { ok: false, code: "invalid_artifact_dir", message: `Unsupported artifactDir '${String(input.artifactDir)}'; expected 'project', 'session', or 'temp'.`, diagnostics };
+  }
+  const bridgeOverride = input.intercomBridge === void 0 ? void 0 : validateIntercomBridgeConfig({ value: input.intercomBridge, label: "intercomBridge" });
+  if (bridgeOverride && !bridgeOverride.ok) {
+    return { ok: false, code: "invalid_intercom_bridge", message: bridgeOverride.error, diagnostics };
+  }
+  if (input.orchestratorTarget !== void 0 && (typeof input.orchestratorTarget !== "string" || !input.orchestratorTarget.trim())) {
+    return { ok: false, code: "invalid_intercom_bridge", message: "orchestratorTarget must be a non-empty string when provided.", diagnostics };
+  }
+  const scope = resolveExecutionAgentScope(input.agentScope);
+  if (input.projectTrusted === false && scope === "project") {
+    const message = projectScopeRequiresTrustMessage(effectiveCwd);
+    return { ok: false, code: "restricted_agent", message, diagnostics: [...diagnostics, { code: "restricted_agent", severity: "error", message }] };
+  }
+  const parentProvider = input.preferredProvider ?? input.parentModel?.provider;
+  const discovery = discoverAgentSnapshot(effectiveCwd, scope, parentProvider, { includeChains: false, projectTrusted: input.projectTrusted });
+  const discovered = discovery.effective;
+  const resolvedAgent = resolveAgentName(input.agent, discovered.agents);
+  const ambiguousCandidates = resolvedAgent.error ? discovered.agents.filter((agent2) => resolveAgentName(input.agent, [agent2]).agent) : resolvedAgent.agent;
+  const invalidAgent = findBlockingAgentDiagnostic(input.agent, ambiguousCandidates, discovered.agentDiagnostics);
+  if (invalidAgent) {
+    const message = `Agent '${input.agent}' has invalid configuration: ${invalidAgent.error}`;
+    return { ok: false, code: "missing_agent", message, diagnostics: [{ code: "missing_agent", severity: "error", message }] };
+  }
+  if (resolvedAgent.error) {
+    return { ok: false, code: "ambiguous_agent", message: resolvedAgent.error, diagnostics };
+  }
+  if (!resolvedAgent.agent) {
+    return { ok: false, code: "missing_agent", message: formatUnknownAgentError(input.agent, unknownAgentDiagnosticContext(discovered)), diagnostics };
+  }
+  const definitionAgent = resolvedAgent.agent;
+  let extensionBindings;
+  try {
+    extensionBindings = normalizeExtensionBindings(input.extensionBindings)?.value;
+  } catch (error) {
+    return { ok: false, code: "invalid_extension_bindings", message: error instanceof Error ? error.message : String(error), diagnostics };
+  }
+  if (extensionBindings !== void 0 && (definitionAgent.runner?.type === "external-cli" || definitionAgent.runner?.type === "external-job")) {
+    return { ok: false, code: "unsupported_mode", message: `extensionBindings is not supported for runner.type='${definitionAgent.runner.type}'.`, diagnostics };
+  }
+  const context = resolveLaunchContractContext(input, definitionAgent);
+  if (context === "fork") {
+    diagnostics.push({ code: "host_required", severity: "host-required", message: "Exact fork session branching requires Pi host session snapshots." });
+  }
+  const bridge = resolveIntercomBridge({
+    config: loadConfig().intercomBridge,
+    ...bridgeOverride ? { override: bridgeOverride.value } : {},
+    context,
+    orchestratorTarget: input.orchestratorTarget ?? PREFLIGHT_ORCHESTRATOR_TARGET
+  });
+  if (bridge.active && bridge.interpolatesOrchestratorTarget && input.orchestratorTarget === void 0) {
+    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." });
+  }
+  const agent = applyIntercomBridgeToAgent(definitionAgent, bridge);
+  const effectiveCapabilityCeiling = intersectSubagentCapabilityCeilings(input.capabilityCeiling, input.inheritedCapabilityCeiling);
+  const restrictionMessage = capabilityCeilingAgentRestrictionMessage(agent.name, effectiveCapabilityCeiling);
+  if (restrictionMessage) return { ok: false, code: "restricted_agent", message: restrictionMessage, diagnostics };
+  const runId = input.runId ?? "preflight";
+  const skillInput = normalizeSkillInput(input.skill);
+  const outputOverride = normalizeSingleOutputOverride(input.output, agent.output);
+  const behavior = resolveStepBehavior(agent, {
+    ...outputOverride !== void 0 ? { output: outputOverride } : {},
+    ...input.outputMode !== void 0 ? { outputMode: input.outputMode } : {},
+    ...skillInput !== void 0 ? { skills: skillInput } : {},
+    ...input.model !== void 0 ? { model: input.model } : {},
+    ...input.outputSchema !== void 0 ? { outputSchema: input.outputSchema } : {}
+  });
+  const requestedSkills = behavior.skills === false ? [] : behavior.skills;
+  const resolvedSkills = resolveSkillsWithFallback(
+    requestedSkills,
+    effectiveCwd,
+    effectiveCwd,
+    agent.skillPath,
+    agent.filePath ? path.dirname(agent.filePath) : effectiveCwd
+  );
+  if (resolvedSkills.missing.includes("pi-subagents")) {
+    return { ok: false, code: "missing_skill", message: "The pi-subagents orchestration skill is not child-injectable.", diagnostics };
+  }
+  if (resolvedSkills.missing.length > 0) diagnostics.push({ code: "missing_skill", severity: "error", message: `Missing skills: ${resolvedSkills.missing.join(", ")}` });
+  const externalRunner = agent.runner?.type === "external-cli" || agent.runner?.type === "external-job";
+  try {
+    assertRequiredChildExtensionsAdmitted([resolveRequiredChildExtensions(input.parentSessionId)], { agent: agent.name, runnerType: agent.runner?.type });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, code: "unsupported_mode", message, diagnostics };
+  }
+  if (externalRunner && behavior.outputSchema) {
+    return { ok: false, code: "unsupported_mode", message: `Agent '${agent.name}' uses runner.type='${agent.runner?.type}' and does not support: structured output.`, diagnostics };
+  }
+  const availableModels = normalizeAvailableModels(input.availableModels);
+  const preferredProvider = agent.modelProvider ?? input.preferredProvider ?? input.parentModel?.provider;
+  const modelScopes = resolveModelScopesForAgent(discovered.modelScope, agent.name, input.parentModel, input.scopedModelIds);
+  const modelOrigin = resolveModelOrigin({ explicitModel: input.model, agentModel: agent.model, parentModel: input.parentModel });
+  const primaryModel = externalRunner ? void 0 : resolveEffectiveSubagentModel(input.model, agent.model, input.parentModel, availableModels, preferredProvider, {
+    scope: modelScopes,
+    source: modelOrigin === "explicit" ? "explicit" : "inherited"
+  });
+  const effectiveThinkingConfig = input.thinking !== void 0 ? input.thinking : agent.thinking;
+  const thinkingCeiling = externalRunner ? void 0 : intersectThinkingCeilings(
+    discovered.maxThinking,
+    input.thinkingCeiling,
+    input.inheritedThinkingCeiling
+  );
+  const model = externalRunner ? void 0 : applyThinkingSuffix(resolveModelSelection(primaryModel, availableModels, preferredProvider, {
+    scope: modelScopes,
+    primaryModelFromParent: modelOrigin === "inherited" || inheritsParentModel(input.model, agent.model, input.parentModel),
+    origin: modelOrigin
+  }).model, effectiveThinkingConfig, input.thinking !== void 0);
+  if (!externalRunner) {
+    try {
+      assertThinkingWithinCeiling({ model, configThinking: effectiveThinkingConfig, ceiling: thinkingCeiling, agent: agent.name, runId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      diagnostics.push({ code: "thinking_ceiling", severity: "error", message });
+      return { ok: false, code: "thinking_ceiling", message, diagnostics };
+    }
+  }
+  if (agent.runner?.type === "external-cli" && isClaudeCodeAdapterId(agent.runner.adapter)) {
+    try {
+      const override = resolveClaudeCodeOverride({
+        model: typeof input.model === "string" ? input.model : void 0,
+        agent,
+        thinking: typeof effectiveThinkingConfig === "string" ? effectiveThinkingConfig : void 0,
+        thinkingCeiling: intersectThinkingCeilings(discovered.maxThinking, input.thinkingCeiling, input.inheritedThinkingCeiling),
+        agentName: agent.name,
+        runId
+      });
+      assertClaudeCodeModelScope({ scopes: modelScopes, model: override?.model, agent: agent.name, runId });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const code = claudeCodeFailureCode(message);
+      diagnostics.push({ code, severity: "error", message });
+      return { ok: false, code, message, diagnostics };
+    }
+  }
+  let toolPlan;
+  const permissionRules = resolvePermissionRules(loadConfig().permissions, agent.permissions);
+  const fast = input.fast ?? agent.fast;
+  const requiredExtensions = externalRunner ? [] : resolveRequiredChildExtensions(input.parentSessionId);
+  try {
+    toolPlan = resolvePiLaunchToolPlan({
+      tools: agent.tools,
+      excludeTools: agent.excludeTools,
+      allowNestedSubagents: agent.allowNestedSubagents,
+      extensions: agent.extensions,
+      subagentOnlyExtensions: agent.subagentOnlyExtensions,
+      requiredExtensions,
+      mcpDirectTools: agent.mcpDirectTools,
+      cwd: effectiveCwd,
+      requireReadTool: resolvedSkills.resolved.length > 0,
+      structuredOutput: Boolean(behavior.outputSchema),
+      fast,
+      model,
+      capabilityCeiling: effectiveCapabilityCeiling,
+      agentName: agent.name,
+      permissionRules,
+      runtimeSnapshotHost: input.runtimeSnapshotHost
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    diagnostics.push({ code: "denied_required_tool", severity: "error", message });
+    return { ok: false, code: "denied_required_tool", message, diagnostics };
+  }
+  const artifactsEnabled = input.artifacts !== false;
+  const artifactsDir = artifactsEnabled ? getArtifactsDir(input.parentSessionFile ?? null, effectiveCwd, input.artifactDir) : void 0;
+  const artifactPaths = artifactsDir ? getArtifactPaths(artifactsDir, runId, agent.name, 0) : void 0;
+  const outputPath = resolveSingleOutputPath(behavior.output, effectiveCwd, effectiveCwd, artifactsDir ? path.join(artifactsDir, "outputs", runId) : void 0);
+  const sessionRoot = input.sessionDir ? path.join(path.resolve(input.sessionDir), runId) : input.sessionRoot ? path.join(path.resolve(input.sessionRoot), runId) : void 0;
+  const sessionDir = sessionRoot ? path.join(sessionRoot, "run-0") : void 0;
+  const lifecycleAsyncDir = input.nestedRootRunId ? path.join(TEMP_ROOT_DIR, "nested-subagent-runs", input.nestedRootRunId, runId) : path.join(DIRS.async, runId);
+  const lifecycleResultPath = input.nestedRootRunId ? nestedResultsPath(input.nestedRootRunId, runId) : resultFilePath(DIRS.results, runId);
+  if (!sessionDir) diagnostics.push({ code: "host_required", severity: "host-required", message: "No sessionRoot/sessionDir was supplied; exact child session paths require the Pi host session-root policy." });
+  if (!externalRunner && input.availableModels === void 0 && (input.model || agent.model || input.parentModel)) {
+    diagnostics.push({ code: "host_required", severity: "host-required", message: "No availableModels snapshot was supplied; model resolution may differ from the active Pi host registry." });
+  }
+  if (resolvedSkills.missing.length > 0) {
+    return { ok: false, code: "missing_skill", message: `Missing skills: ${resolvedSkills.missing.join(", ")}`, diagnostics };
+  }
+  const effectiveThinking = resolveEffectiveThinking(model, effectiveThinkingConfig);
+  const binding = resolveLaunchBinding({
+    agent,
+    task: input.task ?? "",
+    model,
+    ...fast !== void 0 ? { fast } : {},
+    ...effectiveThinking ? { thinking: effectiveThinking } : {},
+    systemPrompt: buildEffectiveSystemPrompt({ agent, resolvedSkills: resolvedSkills.resolved, cwd: effectiveCwd }),
+    skills: requestedSkills,
+    toolPlan,
+    ...outputPath ? { outputPath } : {},
+    outputMode: behavior.outputMode,
+    ...behavior.outputSchema ? { structuredOutputSchema: behavior.outputSchema } : {},
+    ...extensionBindings ? { extensionBindings } : {}
+  });
+  const candidates = candidateList(input.agent, agent, discovery.all);
+  const shadowedCandidates = candidates.filter((candidate) => !candidate.selected);
+  const contractBase = {
+    version: SUBAGENT_LAUNCH_CONTRACT_VERSION,
+    runId,
+    agent: {
+      name: agent.name,
+      ...agent.localName ? { localName: agent.localName } : {},
+      ...agent.packageName ? { packageName: agent.packageName } : {},
+      source: agent.source,
+      filePath: agent.filePath,
+      definitionProjectionVersion: AGENT_DEFINITION_PROJECTION_VERSION,
+      definitionDigest: binding.definitionDigest,
+      shadowedCandidates
+    },
+    context,
+    ...model ? { model } : {},
+    ...effectiveThinking ? { thinking: effectiveThinking } : {},
+    ...thinkingCeiling ? { thinkingCeiling } : {},
+    systemPromptMode: agent.systemPromptMode,
+    inheritProjectContext: agent.inheritProjectContext,
+    inheritGlobalContext: agent.inheritGlobalContext,
+    inheritSkills: agent.inheritSkills,
+    skills: {
+      requested: requestedSkills,
+      resolved: resolvedSkills.resolved.map((skill) => ({ name: skill.name, path: skill.path, source: skill.source })),
+      missing: resolvedSkills.missing
+    },
+    tools: {
+      requestedBuiltin: toolPlan.requestedBuiltinTools,
+      declaredBuiltin: toolPlan.declaredBuiltinTools,
+      ...toolPlan.excludeTools.length > 0 ? { excludeTools: toolPlan.excludeTools } : {},
+      effectiveAllowlist: toolPlan.effectiveToolAllowlist,
+      explicitAllowlist: toolPlan.explicitToolAllowlist,
+      requiredChildTools: toolPlan.requiredChildTools,
+      internalTools: toolPlan.internalTools,
+      mcp: toolPlan.effectiveMcpSelections,
+      effectiveMcpTools: toolPlan.effectiveMcpTools,
+      toolExtensionPaths: toolPlan.toolExtensionPaths,
+      runtimeExtensions: toolPlan.runtimeExtensions,
+      configuredExtensions: toolPlan.configuredExtensions,
+      requiredExtensionIds: toolPlan.requiredExtensions.map(({ id }) => id),
+      // Required paths are private launch authority; preflight exposes their safe IDs above.
+      extensionArgs: toolPlan.extensionArgs.filter((extensionPath) => !requiredExtensions.some(({ path: path2 }) => path2 === extensionPath)),
+      disableAmbientExtensions: toolPlan.disableAmbientExtensions,
+      fanoutAuthorized: toolPlan.fanoutAuthorized,
+      ...toolPlan.capabilityCeiling ? { capabilityCeiling: toolPlan.capabilityCeiling } : {},
+      ...toolPlan.capabilityAudit ? { capabilityAudit: toolPlan.capabilityAudit } : {}
+    },
+    intercomBridge: bridge.active && bridge.mode !== "off" ? { active: true, mode: bridge.mode } : { active: false, mode: bridge.mode },
+    roots: {
+      cwd: effectiveCwd,
+      ...sessionRoot ? { sessionRoot } : {},
+      ...sessionDir ? { sessionDir, sessionFile: path.join(sessionDir, "session.jsonl") } : {},
+      ...artifactsDir ? { artifactsDir } : {},
+      ...artifactPaths ? { artifactPaths } : {},
+      ...outputPath ? { outputPath } : {},
+      lifecycle: {
+        asyncDir: lifecycleAsyncDir,
+        resultPath: lifecycleResultPath,
+        statusPath: path.join(lifecycleAsyncDir, "status.json"),
+        eventsPath: path.join(lifecycleAsyncDir, "events.jsonl"),
+        processTerminalPath: processTerminalPath(lifecycleAsyncDir),
+        processTerminalCandidatePath: processTerminalCandidatePath(lifecycleAsyncDir)
+      }
+    },
+    protocol: {
+      lifecycleArtifactVersion: SUBAGENT_LIFECYCLE_ARTIFACT_VERSION,
+      packageVersion: packageVersion()
+    },
+    diagnostics,
+    launchContractDigest: binding.launchContractDigest
+  };
+  return { ok: true, contract: { ...contractBase, digest: digestContract(contractBase) } };
+}
+export {
+  SUBAGENT_LAUNCH_CONTRACT_VERSION,
+  resolveSubagentLaunchContract
+};

package/bundle/project-panes.js

@@ -0,0 +1,28 @@
+import {
+  PROJECT_PANES_API_VERSION,
+  PROJECT_PANE_TRUST_STATUS,
+  closeProjectPane,
+  createProjectPaneManager,
+  focusProjectPane,
+  getProjectPaneStatus,
+  openProjectPane,
+  projectPaneBindingPath,
+  readProjectPaneBinding
+} from "./chunk-V2JWDB5U.js";
+import "./chunk-7J4ZXMY7.js";
+import "./chunk-3DC5KBVP.js";
+import "./chunk-ZBC44JJ3.js";
+import "./chunk-5LFLVSTM.js";
+import "./chunk-YFCK7H2S.js";
+import "./chunk-Z7KVHQHL.js";
+export {
+  PROJECT_PANES_API_VERSION,
+  PROJECT_PANE_TRUST_STATUS,
+  closeProjectPane,
+  createProjectPaneManager,
+  focusProjectPane,
+  getProjectPaneStatus,
+  openProjectPane,
+  projectPaneBindingPath,
+  readProjectPaneBinding
+};

package/bundle/required-child-extensions.js

@@ -0,0 +1,6 @@
+import {
+  registerRequiredChildExtensions
+} from "./chunk-CTPAE36Y.js";
+export {
+  registerRequiredChildExtensions
+};

package/bundle/shared-types.js

@@ -0,0 +1,8 @@
+import {
+  DEFAULT_FORK_PREAMBLE,
+  wrapForkTask
+} from "./chunk-5LFLVSTM.js";
+export {
+  DEFAULT_FORK_PREAMBLE,
+  wrapForkTask
+};

package/bundle/workflow-resources.js

@@ -0,0 +1,7 @@
+import {
+  registerWorkflowResource
+} from "./chunk-NF7IEKBH.js";
+import "./chunk-7F6RKT6W.js";
+export {
+  registerWorkflowResource
+};

package/docs/agents.md

@@ -539,7 +539,7 @@ Examples:
 
 ### MCP tools
 
-When [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) is not installed and Pi has built-in MCP (Pi 0.99.2 or later), `mcp:server` and `mcp:server/tool` entries resolve against Pi's built-in MCP. Name the server and tool as the server reports them: `mcp:my-docs/get-item` selects the tool Pi registers as `mcp__my_docs__get_item`. The server part may also use the `-`→`_` form of its name that Pi's MCP namespace uses, such as `mcp:my_docs`. The child connects the servers in Pi's `mcp.json` (the project's `.pi/mcp.json` only when the parent trusts the project) and gets only the selected tools, as direct tools, whatever exposure the server is configured with; tools configured as `hidden` cannot be selected. Servers that an extension adds with `pi.registerMcpServer()` work in background children, because the registering extension loads there too. They do not work in foreground children, which load no ambient extensions, so a foreground launch that selects one fails and says to use `async: true`. The child waits for the selected servers' current MCP connection attempts before its first prompt, then rejects the launch if any selected tool is missing or not available as a direct tool. Pi's MCP request timeout still bounds each connection; stopping, interrupting, timing out, or shutting down the child cancels the startup wait. An unrelated server does not delay this check.
+When [pi-mcp-adapter](https://github.com/nicobailon/pi-mcp-adapter) is not installed, `mcp:server` and `mcp:server/tool` entries resolve against Pi's built-in MCP. Name the server and tool as the server reports them: `mcp:my-docs/get-item` selects the tool Pi registers as `mcp__my_docs__get_item`. The server part may also use the `-`→`_` form of its name that Pi's MCP namespace uses, such as `mcp:my_docs`. The child connects the servers in Pi's `mcp.json` (the project's `.pi/mcp.json` only when the parent trusts the project) and gets only the selected tools, as direct tools, whatever exposure the server is configured with; tools configured as `hidden` cannot be selected. Servers that an extension adds with `pi.registerMcpServer()` work in background children, because the registering extension loads there too. They do not work in foreground children, which load no ambient extensions, so a foreground launch that selects one fails and says to use `async: true`. The child waits for the selected servers' current MCP connection attempts before its first prompt, then rejects the launch if any selected tool is missing or not available as a direct tool. Pi's MCP request timeout still bounds each connection; stopping, interrupting, timing out, or shutting down the child cancels the startup wait. An unrelated server does not delay this check.
 
 When pi-mcp-adapter is installed, it keeps priority and provides the direct MCP tools. Subagents only receive direct MCP tools when `mcp:` entries are listed in their frontmatter; global `directTools: true` in the adapter's MCP config is not enough by itself. The generic `mcp` proxy tool can still be used for discovery when available. The adapter caches tool metadata at startup, so after connecting a new MCP server for the first time, restart Pi before relying on direct tools. Server `includeTools` and `excludeTools` policies are enforced while resolving cached metadata for children: both accept exact names and `*`/`?` glob patterns against raw, generated-resource, and server/short/mcp/none-prefixed names, with `excludeTools` taking precedence. `mcp:` entries must name servers from the adapter's configuration files. A server that exists only in the adapter's runtime snapshot (registered at runtime, not persisted) cannot be provided to a child: children are pi sessions inside the parent or the runner process, not `pi` processes that could receive an MCP config argument, so such a launch fails with an error saying that MCP tools must come from an ambient adapter extension in a background child. An `mcp:` entry named `subagent` does not authorize nested fanout; declare the builtin `subagent` tool or set `allowNestedSubagents: true`. If a resolved direct MCP name is missing from the child registry, pi-subagents keeps the launch failed under the strict allowlist and reports the registration mismatch; check the resolved names against what the host or pi-mcp-adapter actually registers before child startup.
 

package/docs/configuration.md

@@ -80,9 +80,9 @@ A local Pi child whose selected model is a virtual model (`pi.registerVirtualMod
 
 ## Tool activation lifecycle
 
-On Pi 0.86.1 or newer, when the model can take a new tool mid-conversation (see [`toolActivation`](#toolactivation)), a fresh unrestricted parent starts with only `subagents_enable` active while `subagent`, `bg_wait`, and `subagent_supervisor` stay registered but inactive. Calling `subagents_enable({})` preserves unrelated active tools and exposes all three on the next model request. It does not launch a child or infer authority from prompt keywords. `bg_wait` is also declared without `subagent` once another extension registers a [background-work provider](extension-api.md#background-work-provider-api), because only `bg_wait` waits for that work. `subagent_supervisor`, which answers this session's children, is also declared when a child request reaches a session that does not have it, such as one from a scheduled run. With other models, a fresh parent starts with `subagent`, `bg_wait`, and `subagent_supervisor` active and no `subagents_enable`. `contact_supervisor` is active whenever `subagent` is, with the definition children use, so a forked child declares the same tools as its parent and can reuse its prompt cache; called in a session that is not a subagent, it returns an error.
+When the model can take a new tool mid-conversation (see [`toolActivation`](#toolactivation)), a fresh unrestricted parent starts with only `subagents_enable` active while `subagent`, `bg_wait`, and `subagent_supervisor` stay registered but inactive. Calling `subagents_enable({})` preserves unrelated active tools and exposes all three on the next model request. It does not launch a child or infer authority from prompt keywords. `bg_wait` is also declared without `subagent` once another extension registers a [background-work provider](extension-api.md#background-work-provider-api), because only `bg_wait` waits for that work. `subagent_supervisor`, which answers this session's children, is also declared when a child request reaches a session that does not have it, such as one from a scheduled run. With other models, a fresh parent starts with `subagent`, `bg_wait`, and `subagent_supervisor` active and no `subagents_enable`. `contact_supervisor` is active whenever `subagent` is, with the definition children use, so a forked child declares the same tools as its parent and can reuse its prompt cache; called in a session that is not a subagent, it returns an error.
 
-The recorded native `subagent` selection is restored on resume, reload, and tree navigation, so an activated session stays activated and a cold session stays cold. The recorded `bg_wait` and `subagent_supervisor` selections are restored the same way, so a session that declared them, for example on an earlier version, keeps them. With the default `toolActivation`, the recorded `subagents_enable` selection is restored too, so a session that started without the loader never gets it later. Older history without tool-selection records keeps eager `subagent`, `bg_wait`, and `subagent_supervisor` availability. If Pi's allowlist or exclusions remove the loader, the extension does not hide `subagent` or `bg_wait`; if they remove `subagent`, the loader reports it unavailable. Hosts whose extension API lacks `getAllTools`, `getActiveTools`, or `setActiveTools` keep eager behavior and log one compatibility warning. The host version is not read from disk, so in-process hosts such as pi-web activate the same way as the Pi CLI.
+The recorded native `subagent` selection is restored on resume, reload, and tree navigation, so an activated session stays activated and a cold session stays cold. The recorded `bg_wait` and `subagent_supervisor` selections are restored the same way, so a session that declared them, for example on an earlier version, keeps them. With the default `toolActivation`, the recorded `subagents_enable` selection is restored too, so a session that started without the loader never gets it later. Older history without tool-selection records keeps eager `subagent`, `bg_wait`, and `subagent_supervisor` availability. If Pi's allowlist or exclusions remove the loader, the extension does not hide `subagent` or `bg_wait`; if they remove `subagent`, the loader reports it unavailable. The host version is not read from disk, so in-process hosts such as pi-web activate the same way as the Pi CLI.
 
 Some providers fix the tool list for a whole prompt, for example bridges that hand Pi's tools to another agent SDK. There `subagent` appears only on the next user prompt, not the next model request. Start Pi with `--exclude-tools subagents_enable` to keep `subagent` active from the start.
 
@@ -150,8 +150,8 @@ Disabling a per-call option removes only the per-call override. Configured defau
 
 `workflow-scripts` removes workflow scripts and named workflow resources from every entry point. The model can no longer write a script, and a script that still arrives from RPC `spawn` (`script` or `workflow`), `/prompt-workflow`, a saved schedule, or a delegated launch fails with an error that names the setting. Schedule inspection, pause, and delete still work, but `schedule.create` cannot succeed because it needs a script. `/run` still works: it launches its one child directly. The built-in tool description and prompt snippet drop the script guidance and describe two small inputs instead:
 
-- `tasks: [{ agent, task }, ...]` runs the children in parallel and returns their results in order.
-- `chain: [step, ...]` runs steps in order. A step is `{ agent, task?, as? }` or a parallel group `{ parallel: [{ agent, task }, ...] }`. A group waits for all of its children.
+- `tasks: [{ agent, task, cwd?, model? }, ...]` runs the children in parallel and returns their results in order.
+- `chain: [step, ...]` runs steps in order. A step is `{ agent, task?, as?, cwd?, model? }` or a parallel group `{ parallel: [{ agent, task, cwd?, model? }, ...] }`. A group waits for all of its children. `cwd` and `model` are optional and apply to that one child.
 
 A top-level `task` is the original request. Tasks can use three placeholders:
 
@@ -194,6 +194,16 @@ With `"summary"`, a tool result looks like this:
 ✓ reviewer · completed
 ```
 
+## `enableSlashCommands`
+
+```json
+{ "enableSlashCommands": false }
+```
+
+Set to `false` to register none of the pi-subagents slash commands (`/run`, `/subagents`, `/subagents-fleet`, `/subagents-watchdog`, `/prompt-workflow`, and the rest) and no [`foregroundDetachShortcut`](#foregrounddetachshortcut). The `subagent` tool, RPC, the async widget, and the extension's other features are unchanged. Prompt templates whose frontmatter has `chain:` launch through `/prompt-workflow`, so they stop working too. Defaults to `true`. Restart Pi or run `/reload` after changing it.
+
+The package's prompt shortcuts, such as `/parallel-review` and `/review-loop`, are Pi prompt templates, not commands, so this setting leaves them alone. Pi's package filter removes them: `{ "packages": [{ "source": "npm:pi-subagents", "prompts": [] }] }` in Pi's `settings.json`, or `pi config`.
+
 ## `foregroundDetachShortcut`
 
 ```json
@@ -359,7 +369,7 @@ Reports are sent only from an interactive TUI session whose standard output is a
 | failed, partial, or rejected | `error` |
 | stopped or paused | `idle` |
 
-Each record's `title` is the agent names or workflow key, and its `msg` is the current tool while working, or the outcome. Neither includes the task text. Finished runs keep their `done`, `error`, or `idle` record after they leave the async widget, for as long as they are in Fleet's recent history (the last 20 finished runs). Records of runs this session no longer tracks, for example after switching sessions, are cleared. At most 64 records are shown: running and waiting runs first, then finished ones, most recently updated first; older finished records are cleared to make room. When the extension is reloaded or the session is replaced, it clears every record it sent and the new session reports the runs it still tracks. Pi 1.1 and later reports its own state on the root record and clears every record, these included, when it quits, suspends with Ctrl+Z, or opens an external editor. After a suspend, this extension sends its records again; after an external editor, each record comes back the next time it changes. Foreground runs are not reported, and tmux drops these sequences unless you configure passthrough.
+Each record's `title` is the agent names or workflow key, and its `msg` is the current tool while working, or the outcome. Neither includes the task text. Finished runs keep their `done`, `error`, or `idle` record after they leave the async widget, for as long as they are in Fleet's recent history (the last 20 finished runs). Records of runs this session no longer tracks, for example after switching sessions, are cleared. At most 64 records are shown: running and waiting runs first, then finished ones, most recently updated first; older finished records are cleared to make room. When the extension is reloaded or the session is replaced, it clears every record it sent and the new session reports the runs it still tracks. Pi reports its own state on the root record and clears every record, these included, when it quits, suspends with Ctrl+Z, or opens an external editor. After a suspend, this extension sends its records again; after an external editor, each record comes back the next time it changes. Foreground runs are not reported, and tmux drops these sequences unless you configure passthrough.
 
 ## `activeRunsPrompt`
 

package/docs/extension-api.md

@@ -353,6 +353,33 @@ Results:
 
 Live update events are bounded progress snapshots, not patches, so consumers should replace the prior snapshot rather than merge it as a delta. Structured delegation coalesces heartbeats whose delegation-visible progress and recent output are unchanged; a duration-only heartbeat therefore does not produce another update. The terminal response remains authoritative for the complete result, error, and final usage details.
 
+Both `:update` and terminal `:response` optionally include one bounded `providerDiagnostics` snapshot:
+
+```ts
+{
+  errorCount: number,
+  lastError?: {
+    kind: "rate_limited" | "transient_other" | "unknown",
+    message: string,
+    at: number,
+  },
+  retry?: {
+    phase: "backoff" | "in_flight",
+    attempt: number,
+    maxAttempts: number,
+    delayMs: number,
+    scheduledAt: number,
+  },
+}
+```
+
+- Coverage is **observed assistant-request errors and Pi retries**, not every provider-internal HTTP attempt. Healthy long reasoning does not invent diagnostics; absence means no observation, not proof that no internal retry happened.
+- `errorCount` increments once per failed assistant `message_end` (`stopReason: "error"`), including repeated identical errors and errors without an `errorMessage`. It does not count retry scheduling, tool failures, aborts, or compaction. The first error is reported immediately, even with no output or tokens and before Pi schedules any retry.
+- Only the failed message's `errorMessage` is classified, never assistant content or tool text. `rate_limited` requires explicit throttling evidence. Text that mentions quota or billing, or says credits, balance, or an account or usage limit is exhausted, is reported as `unknown`, even when it also carries throttling or transient wording, so account exhaustion never looks like transient throttling. Other Pi-recognized transient errors use `transient_other`; anything else uses `unknown`. This classification is observational and does not change Pi's retry policy or the delegation's status/error behavior.
+- `lastError.message` is a short fixed safe description, **not** the raw provider error/body. Raw diagnostics remain in existing child artifacts. No HTTP status or provider code is inferred or exposed here. `at` and `scheduledAt` are observation-time Unix timestamps in milliseconds.
+- `auto_retry_start` schedules `backoff`; `attempt` is the 1-based retry attempt, `maxAttempts` is Pi's retry budget, and `delayMs` is Pi's planned delay, **not** a claimed server `Retry-After`. The next `agent_start`/`turn_start` changes the phase to `in_flight`. `auto_retry_end` ends the sequence after success, exhaustion, or cancellation; it is not a backoff-finished event.
+- Cumulative error history survives recovery and unrelated replacement updates. `retry` is active-only and is absent from every terminal response, including cancellation and timeout. Historical errors alone do not turn a recovered completed result into a failure.
+
 Bounds:
 
 - Schemas are capped at 64 KiB; tasks and returned text/structured values are capped at 1 MiB, with smaller bounds on identity/configuration strings and a maximum `timeoutMs` of 2,147,483,647.
@@ -600,7 +627,7 @@ The API returns discriminated structured results with canonical project root, bi
 
 A host that embeds this extension owns whether completion wakes can be delivered at all.
 
-Ordinary async and foreground completion wakes use `registerSubagentNotify` and `sendCompletion`. They listen for completion events and deliver through `pi.sendMessage(..., { triggerTurn })`. When the parent is idle, every pi-subagents notice that should start a turn (completions, supervisor asks, control and steering notices, wait subscriptions) is instead appended without a turn, followed by one user message, `PARENT_WAKE_TEXT` from `src/shared/parent-wake.ts`, sent with `pi.sendUserMessage`. Pi runs `before_agent_start` only for prompts, so this keeps extension-set system prompt sections in the woken run. A busy parent still gets the notice as a steering message. After the user aborts a parent run in a host with a UI, these notices are only appended, with no turn and no wake message, until the next parent run starts. Session shutdown stops the result watcher and disposes this completion notifier. `createWaitSubscriptionManager` is separate: it is the explicit non-blocking `bg_wait` subscription path for work without native notification, not the ordinary completion wake path.
+Ordinary async and foreground completion wakes use `registerSubagentNotify` and `sendCompletion`. They listen for completion events and deliver through `pi.sendMessage(..., { triggerTurn })`. When the parent is idle, every pi-subagents notice that should start a turn (completions, supervisor asks, control and steering notices, wait subscriptions) starts the run itself with `triggerTurn: true`; Pi runs `before_agent_start` for that run, so extension-set system prompt sections stay in it. Each such notice ends with what the parent should do (for completions, `Parent action: ...`), and no separate user message is sent. If another extension's wake (pi-intercom's, through the shared `Symbol.for("pi.idle-wake.v1")` reservation) is already starting the run, the notice is appended without a turn and that run picks it up. A busy parent still gets the notice as a steering message. After the user aborts a parent run in a host with a UI, these notices are only appended, with no turn, until the next parent run starts. Session shutdown stops the result watcher and disposes this completion notifier. `createWaitSubscriptionManager` is separate: it is the explicit non-blocking `bg_wait` subscription path for work without native notification, not the ordinary completion wake path.
 
 Each completion notice is a custom message with `customType: "subagent-notify"`. Its `content` is the text the model reads. Pi does not send `details` to the model, so hosts can use it to match a notice to its runs by id without parsing the text. `details.runs` has one entry per finished run, in the order of the notice. A grouped notice has several entries. Each entry has `agent` and `status` (`completed`, `failed`, `paused` or `stopped`). When known, an entry also has these fields:
 
@@ -616,7 +643,7 @@ Detached children do not stop when the session does. They are the host process's
 
 This matters because "is the parent busy?" is the wrong idle signal. A parent that launches a detached run and hands control back — which is what the async launch output tells it to do — is not prompting, streaming, compacting, or running a shell command. A host that reaps sessions on those signals alone will dispose exactly the session that was waiting to be woken.
 
-When pi-subagents runs inside a compatible pi-web host, it discovers the versioned `Symbol.for("@agegr/pi-web/session-liveness/v1")` registry and registers one provider for the current session. The provider reports live `queued`/`running` async jobs, active nested descendants (including foreground routes retained after their direct parent settles), foreground controls that still have a scheduling owner or active child, async runs that ended but whose result has not reached the parent (including a rejected send waiting for retry), completion notifications until Pi starts the wake message (`message_start`), even when Pi queued it behind the current turn or past `agent_settled`, and a wake prompt sent to an idle parent until its run starts (`agent_start`). Accepted wakes remain owned by the same Pi session manager and session UUID across extension reloads, until they start. Independent session managers never share this ownership, and changing the UUID on an existing manager discards the old session's wakes. A wake message Pi discards without starting keeps the session live until the session shuts down for a reason other than reload. A wake prompt whose run has not started 10 seconds later, while the parent is idle, no longer keeps the session live: an input handler consumed it or it failed, and its notices are already in the session. Retained terminal history, future schedules, and wait subscriptions do not make a session live by themselves. The registration is replaced on session changes and released during runtime shutdown or reload; other hosts remain unaffected.
+When pi-subagents runs inside a compatible pi-web host, it discovers the versioned `Symbol.for("@agegr/pi-web/session-liveness/v1")` registry and registers one provider for the current session. The provider reports live `queued`/`running` async jobs, active nested descendants (including foreground routes retained after their direct parent settles), foreground controls that still have a scheduling owner or active child, async runs that ended but whose result has not reached the parent (including a rejected send waiting for retry), completion notifications until Pi starts the wake message (`message_start`), even when Pi queued it behind the current turn or past `agent_settled`, and a turn-triggering notice sent to an idle parent until its run starts (`agent_start`). Accepted wakes remain owned by the same Pi session manager and session UUID across extension reloads, until they start. Independent session managers never share this ownership, and changing the UUID on an existing manager discards the old session's wakes. A wake message Pi discards without starting keeps the session live until the session shuts down for a reason other than reload. An idle wake whose run has not started 10 seconds later, while the parent is idle, stops holding the session live on its own; a completion notice whose run never started is still held by the undelivered-notice tracking above until the session shuts down, which records it for replay at the next start. Retained terminal history, future schedules, and wait subscriptions do not make a session live by themselves. The registration is replaced on session changes and released during runtime shutdown or reload; other hosts remain unaffected.
 
 If your host reclaims idle sessions, keep a session alive while it still has live detached work:
 

package/docs/observability.md

@@ -116,8 +116,8 @@ FleetView and the under-editor async widget are both enabled by default; set `as
 Default keys:
 
 - `↑`/`↓` or `j`/`k` — select a child
-- `Shift+K`/`Shift+J` — scroll one line
-- `PgUp`/`PgDn` — scroll one page
+- `K`/`J` (Shift+k / Shift+j) — scroll output one line
+- `PgUp`/`PgDn` — scroll output one body viewport page (structured headers stay pinned)
 - `x`/`Ctrl+O` — toggle tool details
 - `r` — refresh
 - `Esc` — close
@@ -126,6 +126,10 @@ Default keys:
 - `D` — stop a selected child's top-level async run after confirmation
 - `H` — open the selected active async child through the available Inspect plugin
 
+In fullscreen mode with Pi mouse reporting enabled, primary-click a visible roster row to select that child. Wheel or trackpad input over the output pane (including its pinned header) scrolls the same viewport as the keyboard. Owned wheel events stay inside the inspector, even at the top and bottom. New output follows the bottom until you scroll away; reaching the bottom resumes following. Steering/redo drafts and stop confirmation retain input ownership, and Prompt Audit blocks roster clicks. Footer shortcuts remain text hints, not buttons.
+
+In regular (non-fullscreen) mode, the terminal retains mouse scrolling and scrollback ownership; internal-pane wheel scrolling and roster clicking are not promised. Use the keyboard controls above to navigate clipped inspector output in either mode. The extension does not enable terminal mouse tracking.
+
 Set `fleetKeybindings` in the extension config to replace inspector-level keys when a terminal intercepts keys such as `PgUp`, `PgDn`, `Home`, or `End`. Prompt modes keep fixed keys such as `Esc`, `Enter`, `Tab`, and stop-confirmation `Y`/`N`.
 
 Enter and `H` use the available Inspect plugin. Inside tmux, this includes the bundled tmux plugin: it splits the focused window, runs the inspector pane there, and records a binding, so `status` and `close` are available and ordinary tmux keys such as the prefix keep working in the pane. On macOS with Ghostty 1.3+ (TERM_PROGRAM=ghostty), this includes the other bundled open-only plugin using Ghostty's preview AppleScript API; status and close are unavailable because no binding is written. In a child-specific inspector, type ordinary guidance and press Enter to send it through the acknowledged steer channel; `steer <message>`, `status`, and `stop` remain available as explicit controls. The bundled Herdr plugin uses Herdr 0.7.5+.