@narumitw/pi-subagents 2.0.5 → 2.1.0

package/dist/index.ts

@@ -5,33 +5,40 @@ import {
   formatAgentCatalog,
   formatUsageStats,
   registerSubagentConsult
-} from "./chunks/chunk-YBUWBRF7.ts";
+} from "./chunks/chunk-FXI45N3J.ts";
 import {
   registerSubagentInspect
-} from "./chunks/chunk-ZHTNCZIA.ts";
+} from "./chunks/chunk-JU6LUNLP.ts";
 import {
   SubagentParams,
   hasUsableAggregator
-} from "./chunks/chunk-NIF42QMF.ts";
+} from "./chunks/chunk-FEVPWRMU.ts";
 import {
   cachedModuleLoader,
   throwIfAborted
 } from "./chunks/chunk-HOP5FXDT.ts";
 import {
   registerStatefulSubagents
-} from "./chunks/chunk-CBP76ARQ.ts";
-import "./chunks/chunk-S2IWVK3J.ts";
+} from "./chunks/chunk-PABJJYP6.ts";
+import "./chunks/chunk-TZ34IQ3M.ts";
+import "./chunks/chunk-ILEQ27AL.ts";
 import "./chunks/chunk-P7OH4XMF.ts";
 import "./chunks/chunk-N7BLVXKK.ts";
 import {
   getResultFinalOutput,
   isResultError
-} from "./chunks/chunk-AEUYS7JC.ts";
+} from "./chunks/chunk-X4NMONPE.ts";
 import "./chunks/chunk-RTCVYIZA.ts";
 import "./chunks/chunk-ONDTY4EL.ts";
-import "./chunks/chunk-O4VO6JUJ.ts";
-import "./chunks/chunk-PSK43Y6A.ts";
+import "./chunks/chunk-TM2R67J3.ts";
+import "./chunks/chunk-LASD73CM.ts";
 import "./chunks/chunk-RSUXZD6S.ts";
+import {
+  USAGE_RECORDING_DIRECTORY,
+  USAGE_RECORDING_RETENTION_DAYS,
+  USAGE_RECORDING_STUDY_ID,
+  resolveUsageRecordingEnabled
+} from "./chunks/chunk-N2T5IN4X.ts";
 import {
   DEFAULT_CONSULTATION_CWD_POLICY,
   DEFAULT_CONSULT_RESOURCE_POLICY,
@@ -40,21 +47,22 @@ import {
   inspectSubagentSettings,
   readSubagentSettings,
   resolveBlockingMaxParallelTasks
-} from "./chunks/chunk-QBORTI4W.ts";
-import "./chunks/chunk-7OBINKFM.ts";
-import "./chunks/chunk-DPPVEQAM.ts";
+} from "./chunks/chunk-TMZRHIIK.ts";
+import "./chunks/chunk-VDG7LTYE.ts";
+import "./chunks/chunk-4AQSF7AS.ts";
 import {
   SUBAGENT_COMPLETION_MESSAGE_TYPE,
   renderCompletionMessage
-} from "./chunks/chunk-QDVGH2X7.ts";
+} from "./chunks/chunk-IWC32VPY.ts";
 import {
   expansionHint,
   formatToolActivity,
   safeBlock,
   safeLine
 } from "./chunks/chunk-BFK2Z4ZF.ts";
+import "./chunks/chunk-VBDGNNLM.ts";
 import "./chunks/chunk-SWGQLFSD.ts";
-import "./chunks/chunk-I2FAK44T.ts";
+import "./chunks/chunk-JSZIP73U.ts";
 import {
   MAX_BLOCKING_PARALLEL_CONCURRENCY
 } from "./chunks/chunk-H3FP6DLR.ts";
@@ -66,9 +74,9 @@ import {
 
 // src/config-registration.ts
 var SUBCOMMANDS = [
-  { value: "settings", label: "settings", description: "Configure subagent user settings" },
-  { value: "status", label: "status", description: "Show effective subagent settings" },
-  { value: "help", label: "help", description: "Show subagent settings help" }
+  { value: "settings", label: "settings", description: "Open grouped subagent settings" },
+  { value: "status", label: "status", description: "Show detailed subagent diagnostics" },
+  { value: "help", label: "help", description: "Show subagent first steps and safety help" }
 ];
 function registerSubagentConfigLifecycle(pi) {
   const owner = { generation: 0, controller: new AbortController() };
@@ -85,13 +93,13 @@ function registerSubagentConfigLifecycle(pi) {
 }
 function registerSubagentConfigCommand(pi, runtime, owner = registerSubagentConfigLifecycle(pi), dependencies = {}) {
   const loadConfigUi = cachedModuleLoader(
-    dependencies.loadConfigUi ?? (() => import("./chunks/config-ui-2YUCUEBM.ts"))
+    dependencies.loadConfigUi ?? (() => import("./chunks/config-ui-DDKERQHI.ts"))
   );
   const loadConfigStatus = cachedModuleLoader(
-    dependencies.loadConfigStatus ?? (() => import("./chunks/config-status-J4GPWP46.ts"))
+    dependencies.loadConfigStatus ?? (() => import("./chunks/config-status-FKGDECZ3.ts"))
   );
   pi.registerCommand("subagents", {
-    description: "Manage current-session subagents and user settings",
+    description: "Manage subagents, settings, diagnostics, and help",
     getArgumentCompletions(prefix) {
       const normalized = prefix.trim().toLowerCase();
       const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
@@ -138,7 +146,7 @@ function registerSubagentConfigCommand(pi, runtime, owner = registerSubagentConf
         }
         if (!isCurrent()) return;
         if (!subcommand) await configUi.showSubagentManager(pi, ctx, runtime, owner);
-        else await configUi.showSubagentSettings(ctx, runtime, owner);
+        else await configUi.showSubagentSettings(pi, ctx, runtime, owner);
         return;
       }
       if (ctx.mode === "tui" || ctx.hasUI) {
@@ -828,13 +836,360 @@ ${expansionHint()}`;
   );
 }
 
+// src/usage-recording.ts
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+var SHUTDOWN_FLUSH_MS = 2500;
+var SUBAGENT_TOOLS = /* @__PURE__ */ new Set([
+  "subagent",
+  "subagent_spawn",
+  "subagent_send",
+  "subagent_manage",
+  "subagent_mailbox",
+  "subagent_inspect",
+  "subagent_consult",
+  "subagent_await"
+]);
+function registerUsageRecording(pi, dependencies = {}) {
+  const deps = {
+    createId: dependencies.createId ?? randomUUID,
+    monotonicNow: dependencies.monotonicNow ?? performance.now.bind(performance),
+    getAgentDir: dependencies.getAgentDir ?? getAgentDir,
+    loadStore: dependencies.loadStore ?? (() => import("./chunks/usage-recording-store-CW3EH2SZ.ts"))
+  };
+  const pathValue = path.join(deps.getAgentDir(), USAGE_RECORDING_DIRECTORY);
+  const runtimeInstance = deps.createId();
+  let logicalSession = deps.createId();
+  let branchEpoch = 0;
+  let surfaceArm = "disabled";
+  let sessionStartedAt = deps.monotonicNow();
+  let enabled = false;
+  let eventSequence = 0;
+  let recordedEvents = 0;
+  let writeFailure = false;
+  let warningActive = false;
+  let onWarning;
+  let storePromise;
+  let writeGeneration = 0;
+  let writeTail = Promise.resolve();
+  let transitionTail = Promise.resolve();
+  let currentTurnId;
+  let turnOrdinal = 0;
+  let operationOrdinal = 0;
+  let childOrdinal = 0;
+  let runOrdinal = 0;
+  let completionOrdinal = 0;
+  const operations = /* @__PURE__ */ new Map();
+  const children = /* @__PURE__ */ new Map();
+  const runs = /* @__PURE__ */ new Map();
+  const completions = /* @__PURE__ */ new Map();
+  const agentStates = /* @__PURE__ */ new Map();
+  const activeRuns = /* @__PURE__ */ new Map();
+  pi.on("agent_start", () => record("lifecycle", { phase: "parent_agent_start" }));
+  pi.on("agent_settled", () => record("lifecycle", { phase: "parent_agent_settled" }));
+  pi.on("turn_start", () => {
+    currentTurnId = `turn-${++turnOrdinal}`;
+    record("parent_turn_start", { turnOrdinal }, currentTurnId);
+  });
+  pi.on("turn_end", (event) => {
+    record(
+      "parent_turn_end",
+      {
+        turnOrdinal,
+        ...usageNumbers(event.message.role === "assistant" ? event.message.usage : void 0)
+      },
+      currentTurnId
+    );
+    currentTurnId = void 0;
+  });
+  pi.on("tool_execution_start", (event) => {
+    if (!SUBAGENT_TOOLS.has(event.toolName)) return;
+    const operationId = `tool-${++operationOrdinal}`;
+    operations.set(event.toolCallId, { id: operationId, startedAt: offset() });
+    record("tool_start", { operationId, tool: event.toolName }, currentTurnId);
+  });
+  pi.on("tool_execution_end", (event) => {
+    if (!SUBAGENT_TOOLS.has(event.toolName)) return;
+    const operation = operations.get(event.toolCallId);
+    operations.delete(event.toolCallId);
+    record(
+      "tool_end",
+      {
+        operationId: operation?.id ?? `tool-${++operationOrdinal}`,
+        tool: event.toolName,
+        isError: event.isError,
+        ...operation ? { durationMs: Math.max(0, offset() - operation.startedAt) } : {},
+        ...usageNumbers(event.result?.usage)
+      },
+      currentTurnId
+    );
+  });
+  const controller = {
+    startSession(input) {
+      return serializeTransition(async () => {
+        enabled = false;
+        await closeStore();
+        logicalSession = deps.createId();
+        branchEpoch += 1;
+        surfaceArm = input.surfaceArm;
+        sessionStartedAt = deps.monotonicNow();
+        eventSequence = 0;
+        recordedEvents = 0;
+        writeFailure = false;
+        warningActive = false;
+        onWarning = input.onWarning;
+        currentTurnId = void 0;
+        turnOrdinal = 0;
+        operationOrdinal = 0;
+        childOrdinal = 0;
+        runOrdinal = 0;
+        completionOrdinal = 0;
+        operations.clear();
+        children.clear();
+        runs.clear();
+        completions.clear();
+        agentStates.clear();
+        activeRuns.clear();
+        enabled = input.enabled;
+        if (!enabled) return;
+        record("study_exposure", { reason: input.reason });
+        record("lifecycle", { phase: "session_start", reason: input.reason });
+        enqueue(async (store) => store.prune(USAGE_RECORDING_RETENTION_DAYS));
+        await writeTail;
+      });
+    },
+    shutdown(reason) {
+      return serializeTransition(async () => {
+        if (enabled) record("lifecycle", { phase: "session_shutdown", reason });
+        enabled = false;
+        await flushWithin(SHUTDOWN_FLUSH_MS);
+        await closeStore();
+      });
+    },
+    setEnabled(value) {
+      return serializeTransition(async () => {
+        if (value === enabled) return;
+        if (value) {
+          enabled = true;
+          record("study_exposure", { reason: "enabled_in_settings" });
+          record("lifecycle", { phase: "recording_enabled" });
+          enqueue(async (store) => store.prune(USAGE_RECORDING_RETENTION_DAYS));
+          await writeTail;
+          return;
+        }
+        record("lifecycle", { phase: "recording_disabled" });
+        enabled = false;
+        await flushWithin(SHUTDOWN_FLUSH_MS);
+        await closeStore();
+      });
+    },
+    getStatus() {
+      return {
+        enabled,
+        initialized: storePromise !== void 0,
+        retentionDays: USAGE_RECORDING_RETENTION_DAYS,
+        path: pathValue,
+        recordedEvents,
+        writeFailure
+      };
+    },
+    observeAgents(agents) {
+      if (!enabled) return;
+      for (const agent of agents) {
+        const childId = localChildId(agent.id);
+        if (agentStates.get(agent.id) !== agent.state) {
+          agentStates.set(agent.id, agent.state);
+          record("lifecycle", { phase: "child_state", childId, state: agent.state });
+        }
+        if (agent.currentRunId && activeRuns.get(agent.id) !== agent.currentRunId) {
+          activeRuns.set(agent.id, agent.currentRunId);
+          record("child_run_start", {
+            childId,
+            runId: localRunId(agent.currentRunId),
+            generation: agent.currentTurnGeneration ?? agent.turnGeneration ?? 0
+          });
+        }
+      }
+    },
+    recordChildCompletion(completion) {
+      if (!enabled) return;
+      const childId = localChildId(completion.agent.id);
+      const runId = localRunId(completion.runId);
+      const timing = completion.agent.telemetry?.timing;
+      record("child_run_end", {
+        childId,
+        runId,
+        generation: completion.generation,
+        state: completion.agent.state,
+        ...completion.agent.outcome?.status ? { outcomeStatus: completion.agent.outcome.status } : {},
+        ...completion.agent.termination?.reason ? { terminationReason: completion.agent.termination.reason } : {},
+        ...completion.agent.telemetry?.budgetSource ? {
+          timeoutBudgetSource: completion.agent.telemetry.budgetSource.timeout,
+          idleTimeoutBudgetSource: completion.agent.telemetry.budgetSource.idleTimeout,
+          turnLimitBudgetSource: completion.agent.telemetry.budgetSource.turnLimit,
+          toolCallLimitBudgetSource: completion.agent.telemetry.budgetSource.toolCallLimit
+        } : {},
+        ...timing?.startedAt !== void 0 && timing.settledAt !== void 0 ? { durationMs: Math.max(0, timing.settledAt - timing.startedAt) } : {},
+        ...transportUsageNumbers(completion.agent.telemetry?.usage)
+      });
+      recordCompletion(completion, "persisted");
+    },
+    recordCompletionDeliveryAttempt(completion, input) {
+      recordCompletion(completion, "delivery_attempt", {
+        delivery: input.delivery,
+        triggerTurn: input.triggerTurn,
+        outcome: input.outcome
+      });
+    },
+    recordCompletionVisible(completion) {
+      recordCompletion(completion, "visible");
+    }
+  };
+  return controller;
+  function record(eventType, data, turnId = currentTurnId) {
+    if (!enabled) return;
+    const event = {
+      schemaVersion: 1,
+      studyId: USAGE_RECORDING_STUDY_ID,
+      surfaceArm,
+      logicalSession,
+      runtimeInstance,
+      branchEpoch,
+      ...turnId ? { turnId } : {},
+      eventSequence: ++eventSequence,
+      monotonicOffsetMs: offset(),
+      eventType,
+      data
+    };
+    enqueue(async (store) => store.append(event), true);
+  }
+  function recordCompletion(completion, transition, extra = {}) {
+    if (!enabled) return;
+    record("completion_transition", {
+      completionId: localCompletionId(completion.completionId),
+      childId: localChildId(completion.agent.id),
+      runId: localRunId(completion.runId),
+      generation: completion.generation,
+      transition,
+      ...extra
+    });
+  }
+  function enqueue(operation, countsAsEvent = false) {
+    const generation = writeGeneration;
+    const task = writeTail.then(async () => {
+      if (generation !== writeGeneration) return false;
+      await operation(await ensureStore());
+      return true;
+    });
+    writeTail = task.then(
+      (completed) => {
+        if (completed && countsAsEvent) recordedEvents += 1;
+        writeFailure = false;
+        warningActive = false;
+      },
+      () => {
+        writeFailure = true;
+        if (!warningActive) {
+          warningActive = true;
+          safeWarn("Local subagent usage recording could not save an event; recording will retry.");
+        }
+      }
+    );
+  }
+  async function ensureStore() {
+    storePromise ??= deps.loadStore().then(({ UsageEventStore }) => new UsageEventStore(pathValue)).catch((error) => {
+      storePromise = void 0;
+      throw error;
+    });
+    return storePromise;
+  }
+  function serializeTransition(operation) {
+    const result = transitionTail.then(operation, operation);
+    transitionTail = result.catch(() => void 0);
+    return result;
+  }
+  async function flushWithin(timeoutMs) {
+    let timer;
+    try {
+      await Promise.race([
+        writeTail,
+        new Promise((resolve) => {
+          timer = setTimeout(resolve, timeoutMs);
+        })
+      ]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  async function closeStore() {
+    writeGeneration += 1;
+    const active = storePromise;
+    storePromise = void 0;
+    if (active) await active.then((store) => store.close()).catch(() => void 0);
+    await writeTail;
+    writeTail = Promise.resolve();
+  }
+  function localChildId(value) {
+    return localId(children, value, "child", () => ++childOrdinal);
+  }
+  function localRunId(value) {
+    return localId(runs, value, "run", () => ++runOrdinal);
+  }
+  function localCompletionId(value) {
+    return localId(completions, value, "completion", () => ++completionOrdinal);
+  }
+  function offset() {
+    return Math.max(0, Math.round(deps.monotonicNow() - sessionStartedAt));
+  }
+  function safeWarn(message) {
+    try {
+      onWarning?.(message);
+    } catch {
+    }
+  }
+}
+function localId(values, raw, prefix, next) {
+  const existing = values.get(raw);
+  if (existing) return existing;
+  const created = `${prefix}-${next()}`;
+  values.set(raw, created);
+  return created;
+}
+function usageNumbers(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return {};
+  const record = value;
+  return numericFields(record, ["input", "output", "cacheRead", "cacheWrite"]);
+}
+function transportUsageNumbers(value) {
+  if (!value) return {};
+  return numericFields(value, [
+    "input",
+    "output",
+    "cacheRead",
+    "cacheWrite",
+    "totalTokens",
+    "cost",
+    "turns"
+  ]);
+}
+function numericFields(record, fields) {
+  return Object.fromEntries(
+    fields.flatMap((field) => {
+      const value = record[field];
+      return typeof value === "number" && Number.isFinite(value) && value >= 0 ? [[field, value]] : [];
+    })
+  );
+}
+
 // src/subagents-extension.ts
 function subagents_extension_default(pi, dependencies = {}) {
   pi.registerMessageRenderer(SUBAGENT_COMPLETION_MESSAGE_TYPE, renderCompletionMessage);
   const loadBlockingExecution = cachedModuleLoader(
-    dependencies.loadBlockingExecution ?? (() => import("./chunks/execution-LA7HN5YF.ts"))
+    dependencies.loadBlockingExecution ?? (() => import("./chunks/execution-Q2JZLKJA.ts"))
   );
   const configOwner = registerSubagentConfigLifecycle(pi);
+  const usageRecording = registerUsageRecording(pi, dependencies.usageRecording);
   const settings = readSubagentSettings();
   let currentSettings = settings;
   let currentCatalog = "";
@@ -842,7 +1197,7 @@ function subagents_extension_default(pi, dependencies = {}) {
   const refreshBlockingCatalog = blockingEnabled ? registerBlockingSubagent(pi, () => currentSettings, loadBlockingExecution) : () => void 0;
   let refreshStatefulCatalog = () => void 0;
   let refreshConsultCatalog = () => void 0;
-  pi.on("session_start", (_event, ctx) => {
+  pi.on("session_start", async (event, ctx) => {
     const loadNotice = consumeSubagentSettingsNotice();
     const refreshedSettings = readSubagentSettings();
     const refreshedNotice = consumeSubagentSettingsNotice();
@@ -857,12 +1212,21 @@ function subagents_extension_default(pi, dependencies = {}) {
     refreshBlockingCatalog(currentCatalog);
     refreshStatefulCatalog(currentCatalog);
     refreshConsultCatalog(currentCatalog);
+    await usageRecording.startSession({
+      enabled: resolveUsageRecordingEnabled(currentSettings?.usageRecording),
+      surfaceArm: usageSurfaceArm(blockingEnabled, statefulRuntime.getRuntimeStatus().enabled),
+      reason: event.reason,
+      onWarning: (message) => {
+        if (ctx.hasUI) ctx.ui.notify(message, "warning");
+      }
+    });
   });
   const statefulRuntime = registerStatefulSubagents(pi, {
     blockingEnabled,
     settings: settings?.stateful,
     getSettings: () => currentSettings,
-    loadTransport: dependencies.loadStatefulTransport
+    loadTransport: dependencies.loadStatefulTransport,
+    usageRecording
   });
   refreshStatefulCatalog = statefulRuntime.setAgentCatalog;
   const getBlockingEnabled = () => blockingEnabled;
@@ -878,7 +1242,8 @@ function subagents_extension_default(pi, dependencies = {}) {
       getMaxParallelTasks,
       getConsultResourcePolicy,
       getConsultationCwdPolicy,
-      getDelegationCwdPolicy
+      getDelegationCwdPolicy,
+      getUsageRecordingStatus: () => usageRecording.getStatus()
     },
     dependencies.inspect
   );
@@ -898,6 +1263,15 @@ function subagents_extension_default(pi, dependencies = {}) {
       getConsultResourcePolicy,
       getConsultationCwdPolicy,
       getDelegationCwdPolicy,
+      getUsageRecordingEnabled: () => usageRecording.getStatus().enabled,
+      getUsageRecordingStatus: () => usageRecording.getStatus(),
+      setUsageRecordingEnabled: async (value) => {
+        await usageRecording.setEnabled(value);
+        currentSettings = {
+          ...currentSettings ?? {},
+          usageRecording: { ...currentSettings?.usageRecording ?? {}, enabled: value }
+        };
+      },
       setMaxParallelTasks(value) {
         const previousSettings = currentSettings;
         currentSettings = {
@@ -945,9 +1319,17 @@ function subagents_extension_default(pi, dependencies = {}) {
     configOwner,
     dependencies.config
   );
+  pi.on("session_shutdown", (event) => usageRecording.shutdown(event.reason));
+}
+function usageSurfaceArm(blockingEnabled, statefulEnabled) {
+  if (blockingEnabled && statefulEnabled) return "all";
+  if (statefulEnabled) return "async-only";
+  if (blockingEnabled) return "blocking-only";
+  return "disabled";
 }
 function registerBlockingSubagent(pi, getSettings, loadExecution) {
   let catalog = "";
+  let deprecationWarningShown = false;
   const activeControllers = /* @__PURE__ */ new Set();
   const activeWork = /* @__PURE__ */ new Set();
   const cancelAndWaitForWork = async (reason) => {
@@ -956,9 +1338,16 @@ function registerBlockingSubagent(pi, getSettings, loadExecution) {
     }
     await Promise.allSettled([...activeWork]);
   };
-  pi.on("session_start", () => cancelAndWaitForWork("Blocking subagent session replaced"));
+  pi.on("session_start", () => {
+    deprecationWarningShown = false;
+    return cancelAndWaitForWork("Blocking subagent session replaced");
+  });
   pi.on("session_shutdown", () => cancelAndWaitForWork("Blocking subagent session shut down"));
+  const statefulEnabled = () => getSettings()?.stateful?.enabled !== false;
+  const deprecationAlternatives = () => statefulEnabled() ? "Prefer the main agent for tightly coupled work, subagent_spawn for detached work, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence." : "Prefer the main agent for tightly coupled work or subagent_consult for bounded synchronous read-only evidence; enable the background workflow before using detached alternatives.";
   const baseDescription = () => [
+    "Deprecated compatibility tool: do not choose subagent for new work.",
+    deprecationAlternatives(),
     "Run specialized subagents as a blocking operation with isolated contexts.",
     "The call blocks the main agent until every worker and optional aggregator finishes, so queued steering waits.",
     "Modes: single (agent + task), parallel (tasks array), chain (sequential with {previous} placeholder), workflow (named dependency tasks with optional capability routing), or panel (independent reviewers plus evidence-preserving synthesis).",
@@ -969,14 +1358,15 @@ function registerBlockingSubagent(pi, getSettings, loadExecution) {
     `Working-directory target policy: ${getSettings()?.cwdPolicy?.delegation ?? DEFAULT_DELEGATION_CWD_POLICY}. This controls launch targets and protected project resources, not filesystem access or sandboxing.`
   ].join(" ");
   const promptGuidelines = () => [
-    "Use subagent only when delegation fits; the main agent should decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
+    statefulEnabled() ? "The subagent tool is deprecated for new work; prefer the main agent, subagent_spawn with supported completion delivery, subagent_await for an intentional retained-agent join, or subagent_consult for bounded synchronous read-only evidence." : "The subagent tool is deprecated for new work; prefer the main agent or subagent_consult for bounded synchronous read-only evidence, and enable the background workflow before using detached alternatives.",
+    "Use deprecated subagent only for an existing caller or an explicit user request whose blocking chain, fan-in, panel, or workflow semantics do not yet have a detached replacement.",
+    "When compatibility requires subagent, decide how many subagents to spawn from task shape instead of waiting for the user to specify a count.",
     "The main agent retains overall planning, immediate critical-path work, integration, final verification, and the final answer.",
     "Use no subagent for simple answers, quick targeted edits, latency-sensitive one-step work, tasks requiring frequent user back-and-forth, or critical-path work the main agent can perform directly.",
     "One ordinary implementation worker should not replace work the main agent can perform directly; use a blocking single only when intentional synchronous isolation or a user-requested specialist justifies waiting.",
     "Keep ordinary planning in the main agent, or use explicit workflow mode when a genuine dependency graph requires caller-authored orchestration.",
     "Keep ordinary review in the main agent with a review skill and deterministic checks; reserve panel mode or custom verifier agents for consequential independent verification.",
-    "Use the blocking subagent tool only when delegated outputs are required before the main agent's next action and waiting is intentional; the main agent cannot process queued steering until the call returns.",
-    "Use a blocking subagent single, parallel, chain, workflow, panel, or fan-in call only when synchronous context or output isolation is worth making the main agent unavailable while it runs.",
+    "A compatibility subagent call blocks the main agent from processing queued steering until it returns; use it only when the explicit legacy workflow justifies making Pi unavailable.",
     `If a blocking parallel subagent call is genuinely required, keep tasks independent, stay within the configured max ${resolveBlockingMaxParallelTasks(getSettings())}, and avoid write-heavy implementation touching the same files or shared state.`,
     "For parallel subagent calls, omit the aggregator key entirely unless a fan-in step is required; do not send null, empty strings, or an empty object for unused optional fields.",
     "Use workflow mode for explicit dependencies or capability routing; declare read/write or ownership scopes, require structured-v2 artifacts when downstream tasks consume them, and use retry or hedging only with the required side-effect contract.",
@@ -987,9 +1377,9 @@ function registerBlockingSubagent(pi, getSettings, loadExecution) {
   ];
   const definition = {
     name: "subagent",
-    label: "Blocking Subagent",
+    label: "Blocking Subagent \xB7 Deprecated",
     description: appendAgentCatalog(baseDescription(), catalog),
-    promptSnippet: "Run blocking isolated subagents only when their outputs are required before the main agent can continue.",
+    promptSnippet: "Deprecated blocking subagent compatibility tool; prefer detached or read-only alternatives.",
     promptGuidelines: promptGuidelines(),
     parameters: SubagentParams,
     async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -998,6 +1388,13 @@ function registerBlockingSubagent(pi, getSettings, loadExecution) {
       const effectiveSignal = signal ? AbortSignal.any([signal, lifecycleController.signal]) : lifecycleController.signal;
       const work = (async () => {
         throwIfAborted(effectiveSignal, "Blocking subagent execution was cancelled");
+        if (!deprecationWarningShown && ctx.hasUI) {
+          deprecationWarningShown = true;
+          ctx.ui.notify(
+            statefulEnabled() ? "subagent is deprecated for new work. Prefer the main agent, subagent_spawn with completion delivery, subagent_await for an intentional join, or subagent_consult for synchronous read-only evidence." : "subagent is deprecated for new work. Prefer the main agent or subagent_consult; enable the background workflow before using detached alternatives.",
+            "warning"
+          );
+        }
         let executionModule;
         try {
           executionModule = await loadExecution();