@mono-agent/agent-runtime 0.18.1 → 0.18.2

package/src/agent/tools/web-search.js

@@ -3,11 +3,49 @@
 import { parseHTML } from "linkedom";
 import { passthroughSandbox } from "../sandbox-seam.js";
 import { readToolRuntime } from "./shared/runtime-context.js";
+import { createCountingSemaphore } from "./shared/semaphore.js";
 import { resolveSandboxPolicy } from "./shared/tool-context.js";
 
 const SEARCH_TIMEOUT_MS = 15_000;
 const SEARCH_RESPONSE_MAX_BYTES = 2 * 1024 * 1024;
 const RRF_K = 60;
+
+// Keyless engines rate-limit by source IP, and one agent can hammer them from
+// many directions at once: a single WebSearch fans out to up to four queries,
+// and every subagent runs its own web controller, so nothing below this module
+// sees the aggregate. Measured against html.duckduckgo.com: ~8 requests in ~4s
+// served normally, ~12 in ~5s tripped an `HTTP 202` anomaly page that persisted
+// for over two minutes. These bounds therefore live at MODULE scope so they
+// apply process-wide (one process is one agent instance), not per run.
+const KEYLESS_DEFAULT_THROTTLE = {
+  // Simultaneous in-flight keyless requests across the whole process.
+  maxConcurrency: 3,
+  // Minimum gap between two requests to the SAME keyless backend, i.e. ~0.67/s
+  // against roughly 2.4/s measured to trip a ban. The asymmetry is deliberate:
+  // being too slow costs a few seconds on a multi-query search, while being too
+  // fast costs a five-minute outage that escalates from a 202 challenge to an
+  // outright 403. Only the fan-out pays it — a single-query search never waits.
+  minSpacingMs: 1_500,
+  // How long a backend stays skipped after it signals rate limiting. Observed
+  // blocks outlasted several minutes, so this is deliberately longer.
+  cooldownMs: 5 * 60_000,
+};
+// Ordered keyless fallback chain. DuckDuckGo first: it yields cleaner titles and
+// snippets, but it is also the one that bans, which is precisely why Startpage
+// behind it has to actually work.
+const KEYLESS_BACKENDS = ["duckduckgo", "startpage"];
+// Markers that identify an interstitial/bot-gate body served with a 2xx status.
+const CHALLENGE_BODY_RE = /anomaly|unusual traffic|captcha|are you a robot|challenge-(?:platform|form)/iu;
+// Statuses these engines use to say "you are sending too much", all of which
+// must put the backend into cooldown rather than be retried next search.
+const RATE_LIMIT_STATUSES = new Set([202, 403, 429]);
+
+let keylessThrottle = { ...KEYLESS_DEFAULT_THROTTLE };
+let keylessSemaphore = createCountingSemaphore(keylessThrottle.maxConcurrency);
+/** @type {Map<string, number>} Backend -> epoch ms until which it is skipped. */
+const backendCooldownUntil = new Map();
+/** @type {Map<string, number>} Backend -> epoch ms its next request may start. */
+const backendNextAvailableAt = new Map();
 const TRACKING_PARAMETERS = new Set([
   "dclid",
   "fbclid",
@@ -96,11 +134,14 @@ export async function performWebSearch(
     );
   };
   const recordResult = (result) => {
+    // Chain failures are reported even when a later backend rescued the query,
+    // so a silent degradation to the fallback is still visible in the outcome.
+    if (result.failures?.length) providerFailures.push(...result.failures);
     if (result.ok) {
       anyProviderSucceeded = true;
       providersUsed.add(result.backend);
       rankedLists.push(filterByDomains(result.results, includeDomains, excludeDomains));
-    } else {
+    } else if (!result.failures?.length) {
       providerFailures.push(result);
     }
   };
@@ -124,16 +165,22 @@ export async function performWebSearch(
   }
 
   if (!anyProviderSucceeded) {
-    const reason = providerFailures.map((entry) => entry.message).filter(Boolean).join("; ")
+    // Four query variants against two backends produce the same handful of
+    // messages over and over; dedupe so the reason stays readable.
+    const reason = [...new Set(providerFailures.map((entry) => entry.message).filter(Boolean))].join("; ")
       || "No search backend was available.";
     const networkDenied = providerFailures.length > 0
       && providerFailures.every((entry) => entry.message === "Network access denied by sandbox policy.");
+    const throttled = providerFailures.some((entry) => entry.rateLimited || entry.cooldown);
     return failure(networkDenied
       ? "Error: Network access denied by sandbox policy."
-      : `Error: WebSearch failed: ${reason}`, networkDenied ? "network_denied" : "backend_unavailable", startedAt, {
+      : `Error: WebSearch failed: ${reason}`,
+    networkDenied ? "network_denied" : (throttled ? "rate_limited" : "backend_unavailable"), startedAt, {
       attempts,
       backend: config.backend,
       retryable: providerFailures.some((entry) => entry.retryable),
+      rateLimited: throttled,
+      cooldownBackends: [...backendCooldownUntil.keys()],
     });
   }
 
@@ -163,48 +210,137 @@ export async function performWebSearch(
       truncated: false,
       resultCount: merged.length,
       providerFailureCount: providerFailures.length,
+      rateLimited: providerFailures.some((entry) => entry.rateLimited || entry.cooldown),
+      cooldownBackends: [...backendCooldownUntil.keys()],
     },
     error: false,
   };
 }
 
+const KEYLESS_RUNNERS = {
+  duckduckgo: searchDuckDuckGo,
+  startpage: searchStartpage,
+};
+
 async function searchOneQuery(query, options) {
   const { config } = options;
+  // Every failure along the chain is kept and carried out on the winning result
+  // too. Reporting only the last one is what made a DuckDuckGo ban surface as
+  // "startpage request failed: fetch failed" and sent diagnosis the wrong way.
   const failures = [];
-  if (options.signal?.aborted) return abortedSearch(config.backend);
+  if (options.signal?.aborted) return abortedSearch(config.backend, failures);
   if (config.backend === "searxng" || (config.backend === "auto" && config.endpoint)) {
     const result = await searchSearxng(query, options);
-    if (result.ok || config.backend === "searxng") return result;
+    if (result.ok || config.backend === "searxng") return { ...result, failures };
     failures.push(result);
-    if (options.signal?.aborted) return abortedSearch(result.backend);
+    if (options.signal?.aborted) return abortedSearch(result.backend, failures);
   }
   if (config.backend === "keyless" || config.backend === "auto") {
-    const duck = await searchDuckDuckGo(query, options);
-    if (duck.ok && duck.results.length > 0) return duck;
-    if (!duck.ok) failures.push(duck);
-    if (options.signal?.aborted) return abortedSearch(duck.backend);
-    const startpage = await searchStartpage(query, options);
-    if (startpage.ok) return startpage;
-    failures.push(startpage);
-    if (duck.ok) return duck;
+    // A genuinely empty 200 is a real answer, not a transport failure — but it
+    // is only worth returning once every backend has had its turn.
+    let emptySuccess = null;
+    for (const backend of KEYLESS_BACKENDS) {
+      if (options.signal?.aborted) return abortedSearch(backend, failures);
+      if (backendInCooldown(backend)) {
+        failures.push({
+          ok: false,
+          backend,
+          message: `${backend} skipped: cooling down after rate limiting.`,
+          retryable: true,
+          cooldown: true,
+        });
+        continue;
+      }
+      const result = await KEYLESS_RUNNERS[backend](query, options);
+      if (result.ok) {
+        if (result.results.length > 0) return { ...result, failures };
+        emptySuccess = result;
+        continue;
+      }
+      // The cooldown is already open — rateLimited() sets it at detection.
+      failures.push(result);
+    }
+    if (emptySuccess) return { ...emptySuccess, failures };
   }
-  return failures[failures.length - 1] || {
-    ok: false,
-    backend: config.backend,
-    message: "No configured search backend.",
-    retryable: false,
+  return {
+    ...(failures[failures.length - 1] || {
+      ok: false,
+      backend: config.backend,
+      message: "No configured search backend.",
+      retryable: false,
+    }),
+    failures,
   };
 }
 
-function abortedSearch(backend) {
+function abortedSearch(backend, failures = []) {
   return {
     ok: false,
     backend,
     message: "WebSearch was aborted.",
     retryable: false,
+    failures,
   };
 }
 
+function backendInCooldown(backend) {
+  const until = backendCooldownUntil.get(backend);
+  if (until === undefined) return false;
+  if (Date.now() >= until) {
+    backendCooldownUntil.delete(backend);
+    return false;
+  }
+  return true;
+}
+
+/**
+ * Atomically claims this backend's next send slot and reports how long the
+ * caller must wait for it. Synchronous on purpose: concurrent callers each
+ * reserve a distinct slot instead of all reading the same "last sent at".
+ *
+ * @returns {number} Milliseconds to wait before sending.
+ */
+function reserveKeylessSlot(backend) {
+  const now = Date.now();
+  const earliest = Math.max(now, backendNextAvailableAt.get(backend) ?? 0);
+  backendNextAvailableAt.set(backend, earliest + keylessThrottle.minSpacingMs);
+  return earliest - now;
+}
+
+// Deliberately NOT unref'd: this delay is part of an in-flight search the
+// caller is awaiting. An unref'd timer lets the event loop drain while the
+// search is still pending, and a one-shot CLI turn then exits mid-query.
+// Cancellation is the signal's job, not the timer's.
+function sleep(ms, signal) {
+  if (!ms) return Promise.resolve();
+  return new Promise((resolvePromise, rejectPromise) => {
+    const onAbort = () => {
+      clearTimeout(timer);
+      // Named so fetchFailure classifies it alongside every other abort.
+      rejectPromise(Object.assign(new Error("WebSearch was aborted."), { name: "AbortError" }));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener?.("abort", onAbort);
+      resolvePromise();
+    }, ms);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener?.("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * Test hook: restores the shipped throttle values and clears cooldown/spacing
+ * state. Module-scoped state would otherwise leak between test cases.
+ *
+ * @param {{maxConcurrency?: number, minSpacingMs?: number, cooldownMs?: number}} [overrides]
+ */
+export function __resetWebSearchThrottleForTests(overrides = {}) {
+  keylessThrottle = { ...KEYLESS_DEFAULT_THROTTLE, ...overrides };
+  keylessSemaphore = createCountingSemaphore(keylessThrottle.maxConcurrency);
+  backendCooldownUntil.clear();
+  backendNextAvailableAt.clear();
+}
+
 async function searchSearxng(query, options) {
   const endpoint = options.config.endpoint;
   if (!endpoint) {
@@ -255,66 +391,143 @@ async function searchSearxng(query, options) {
   }
 }
 
-async function searchDuckDuckGo(query, options) {
-  const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
-  if (!options.sandbox.networkAllowsUrl(options.policy, url)) {
-    return { ok: false, backend: "duckduckgo", message: "Network access denied by sandbox policy.", retryable: false };
+/**
+ * Shared transport for the keyless HTML engines. Both are scraped the same way
+ * and both bot-gate the same way, so request shaping, throttling, challenge
+ * detection, and error classification live here exactly once.
+ *
+ * @param {{backend: string, label: string, url: string, init?: RequestInit, parse: (html: string) => any[]}} spec
+ */
+async function keylessHtmlSearch(spec, options) {
+  if (!options.sandbox.networkAllowsUrl(options.policy, spec.url)) {
+    return { ok: false, backend: spec.backend, message: "Network access denied by sandbox policy.", retryable: false };
   }
+  let release;
   try {
-    const response = await options.fetchImpl(url, {
-      headers: {
-        Accept: "text/html,application/xhtml+xml",
-        "Accept-Language": options.language || "en-US,en;q=0.8",
-        "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) mono-agent-web/1",
-      },
-      signal: requestSignal(options.signal),
-      redirect: "error",
-    });
-    const html = await readLimitedText(response);
-    if (!response.ok) {
+    release = await keylessSemaphore.acquire(options.signal);
+  } catch {
+    // Queued behind the concurrency bound when the turn was cancelled.
+    return { ok: false, backend: spec.backend, message: "WebSearch was aborted.", retryable: false };
+  }
+  try {
+    const waitMs = reserveKeylessSlot(spec.backend);
+    if (waitMs > 0) await sleep(waitMs, options.signal);
+    // Query variants all clear the cooldown check together and then queue here,
+    // so by the time this one is admitted a sibling may already have been
+    // blocked. Without this second look the very first block still costs a full
+    // round of requests against a backend we know is refusing them.
+    if (backendInCooldown(spec.backend)) {
       return {
         ok: false,
-        backend: "duckduckgo",
-        message: `DuckDuckGo HTTP ${response.status}`,
-        retryable: response.status === 429 || response.status >= 500,
+        backend: spec.backend,
+        message: `${spec.backend} skipped: cooling down after rate limiting.`,
+        retryable: true,
+        cooldown: true,
       };
     }
-    return { ok: true, backend: "duckduckgo", results: parseDuckDuckGoResults(html) };
-  } catch (error) {
-    return fetchFailure("duckduckgo", error);
-  }
-}
-
-async function searchStartpage(query, options) {
-  const url = `https://www.startpage.com/sp/search?query=${encodeURIComponent(query)}`;
-  if (!options.sandbox.networkAllowsUrl(options.policy, url)) {
-    return { ok: false, backend: "startpage", message: "Network access denied by sandbox policy.", retryable: false };
-  }
-  try {
-    const response = await options.fetchImpl(url, {
+    const response = await options.fetchImpl(spec.url, {
+      // "manual", not "error": these engines answer a throttled query with a
+      // redirect to a captcha page, and "error" collapses that into an opaque
+      // `TypeError: fetch failed` with no way to tell it from a real outage.
+      // The redirect is still never followed, so the open-redirect guard holds.
+      redirect: "manual",
+      ...(spec.init || {}),
+      // Headers are merged last on purpose: spreading `spec.init` afterwards
+      // would replace the whole headers object with the backend's few extra
+      // entries, and a Startpage POST without a User-Agent gets bot-gated.
       headers: {
         Accept: "text/html,application/xhtml+xml",
         "Accept-Language": options.language || "en-US,en;q=0.8",
         "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) mono-agent-web/1",
+        ...(spec.init?.headers || {}),
       },
       signal: requestSignal(options.signal),
-      redirect: "error",
     });
     const html = await readLimitedText(response);
+    // Startpage answers a blocked source IP with `303 -> /sp/captcha-block`.
+    // The destination is the block itself, never results, so following it only
+    // costs a round trip and still parses to nothing.
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location") || "";
+      return rateLimited(spec, /captcha|blocked|sorry|challenge/iu.test(location)
+        ? "captcha redirect"
+        : `HTTP ${response.status} redirect`);
+    }
+    // 202 is DuckDuckGo's soft challenge (and is `ok`, so status alone would let
+    // an interstitial through as an empty success); 403 is what it escalates to
+    // once it stops asking politely. No credentials are ever sent to these
+    // endpoints, so a 403 can only mean "blocked", never "unauthorized".
+    if (RATE_LIMIT_STATUSES.has(response.status)) {
+      return rateLimited(spec, `HTTP ${response.status}`);
+    }
     if (!response.ok) {
       return {
         ok: false,
-        backend: "startpage",
-        message: `Startpage HTTP ${response.status}`,
-        retryable: response.status === 429 || response.status >= 500,
+        backend: spec.backend,
+        message: `${spec.label} HTTP ${response.status}`,
+        retryable: response.status >= 500,
       };
     }
-    return { ok: true, backend: "startpage", results: parseStartpageResults(html) };
+    const results = spec.parse(html);
+    // A 200 that parses to nothing is ambiguous: either a genuinely empty
+    // result set or a bot gate. Only the body markers tell them apart, and
+    // conflating them is what made a ban look like "No results."
+    if (results.length === 0 && CHALLENGE_BODY_RE.test(html)) {
+      return rateLimited(spec, "interstitial challenge page");
+    }
+    return { ok: true, backend: spec.backend, results };
   } catch (error) {
-    return fetchFailure("startpage", error);
+    return fetchFailure(spec.backend, error, spec.label);
+  } finally {
+    release();
   }
 }
 
+function searchDuckDuckGo(query, options) {
+  return keylessHtmlSearch({
+    backend: "duckduckgo",
+    label: "DuckDuckGo",
+    url: `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`,
+    parse: parseDuckDuckGoResults,
+  }, options);
+}
+
+function searchStartpage(query, options) {
+  // Startpage serves its results from a form POST. The old query-string GET was
+  // answered with a 3xx, which `redirect: "error"` turned into a bare
+  // `TypeError: fetch failed` — so this backend never once returned a result,
+  // and its useless error was the only thing the operator ever saw.
+  const body = new URLSearchParams({ query, cat: "web" });
+  const withDate = { day: "d", month: "m", year: "y" }[options.timeRange];
+  if (withDate) body.set("with_date", withDate);
+  return keylessHtmlSearch({
+    backend: "startpage",
+    label: "Startpage",
+    url: "https://www.startpage.com/sp/search",
+    init: {
+      method: "POST",
+      body,
+      headers: { "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8" },
+    },
+    parse: parseStartpageResults,
+  }, options);
+}
+
+// Opens the cooldown at the moment of detection rather than letting the caller
+// do it. The semaphore slot is released before this result reaches the caller,
+// so a queued sibling would otherwise be admitted and re-check the cooldown
+// while it was still closed, and every variant in flight would hit the wire.
+function rateLimited(spec, detail) {
+  backendCooldownUntil.set(spec.backend, Date.now() + keylessThrottle.cooldownMs);
+  return {
+    ok: false,
+    backend: spec.backend,
+    message: `${spec.label} rate-limited (${detail})`,
+    retryable: true,
+    rateLimited: true,
+  };
+}
+
 export function parseDuckDuckGoResults(html) {
   const { document } = parseHTML(String(html || ""));
   const rows = [...document.querySelectorAll(".result")];
@@ -334,6 +547,10 @@ export function parseDuckDuckGoResults(html) {
 
 export function parseStartpageResults(html) {
   const { document } = parseHTML(String(html || ""));
+  // Startpage inlines emotion CSS in <style> tags nested inside the result
+  // anchors, and textContent happily returns the stylesheet as part of the
+  // title (".css-i3irj7{line-height:18px;...}Best time to visit Japan").
+  for (const node of document.querySelectorAll("style, script")) node.remove();
   const selectors = [".w-gl__result", ".result", "article"];
   const rows = selectors.flatMap((selector) => [...document.querySelectorAll(selector)]);
   const seen = new Set();
@@ -541,15 +758,34 @@ async function readLimitedText(response) {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-function fetchFailure(backend, error) {
+// undici reports transport problems as a bare `TypeError: fetch failed` and
+// keeps the real reason on `error.cause` — dropping it is what left an
+// "unexpected redirect" looking like an unexplained network fault.
+const RETRYABLE_FETCH_CODES = new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "ETIMEDOUT",
+  "EAI_AGAIN",
+  "ENOTFOUND",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EPIPE",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET",
+]);
+
+function fetchFailure(backend, error, label = backend) {
   const name = error?.name;
   const retryable = name === "AbortError"
     || name === "TimeoutError"
-    || ["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "EAI_AGAIN"].includes(error?.code ?? error?.cause?.code);
+    || RETRYABLE_FETCH_CODES.has(error?.code ?? error?.cause?.code);
+  const message = error?.message || String(error);
+  const cause = error?.cause?.message;
+  const detail = cause && cause !== message ? `${message} (${cause})` : message;
   return {
     ok: false,
     backend,
-    message: `${backend} request failed: ${error?.message || String(error)}`,
+    message: `${label} request failed: ${detail}`,
     retryable,
   };
 }

package/src/ai/providers/claude-cli.js

@@ -25,6 +25,7 @@ import {
   claudeSandboxPolicyProblem,
 } from "./claude-sandbox.js";
 import { resolveSandboxPolicy } from "../../agent/tools/shared/tool-context.js";
+import { createClaudeSubagentActivityNormalizer } from "./claude-subagent-activity.js";
 
 const CODEX_CLI_SANDBOX_POLICY_UNSUPPORTED =
   "Direct Codex CLI cannot enforce mono-agent's native srt sandbox scopes. Remove the mono-agent sandbox policy or use a Pi runtime for exact readableRoots, writableRoots, denyWrite, and network rules.";
@@ -449,6 +450,7 @@ export function buildCliCommand({
       "-p",
       "--output-format", "stream-json",
       "--include-partial-messages",
+      "--forward-subagent-text",
       "--verbose",
       ...(outputSchema ? ["--json-schema", JSON.stringify(outputSchema)] : []),
       "--model", modelWithContextWindow(model, contextWindow),
@@ -615,8 +617,29 @@ export async function generateCliResponse(systemPrompt, options = {}) {
     fileChangeSnapshots: new Map(),
     thinkingBuffer: createThinkingBuffer(),
   };
+  const subagentNormalizer = resolved.sdk === "claude-code"
+    ? createClaudeSubagentActivityNormalizer()
+    : null;
+  function emitSubagentEvents(activityEvents) {
+    for (const activity of activityEvents) {
+      events.push(activity);
+      options.onEvent?.(activity);
+    }
+  }
+  function drainSubagents(reason) {
+    if (!subagentNormalizer) return;
+    emitSubagentEvents(subagentNormalizer.drain(reason));
+  }
+  function observedSubagentCapabilities() {
+    if (!subagentNormalizer) return { invoked: null, names: [] };
+    return {
+      invoked: subagentNormalizer.subagentInvoked(),
+      names: subagentNormalizer.nativeSubagentsUsed(),
+    };
+  }
 
   const stderrTail = createStderrTail({ limit: 8 * 1024 });
+  let abortHandler = null;
   try {
     const child = spawn(commandSpec.command, commandSpec.args, {
       cwd: commandSpec.cwd,
@@ -638,43 +661,67 @@ export async function generateCliResponse(systemPrompt, options = {}) {
         options.onEvent?.(ev);
         return;
       }
-      const ev = normalizeCliEvent(raw, cliEventContext);
+      // Capture the provider session before a child event is consumed. Claude
+      // uses the same session id on parent and child records.
+      const candidateSessionId = raw.session_id ?? raw.sessionId ?? raw.thread_id ?? null;
+      if (typeof candidateSessionId === "string" && candidateSessionId.trim().length > 0) {
+        providerSessionId = candidateSessionId.trim();
+      }
+      const observation = subagentNormalizer?.observe(raw);
+      if (observation) emitSubagentEvents(observation.events);
+      // Child messages must not be normalized, added to parent text, counted as
+      // parent usage, or considered for the parent's StructuredOutput result.
+      if (observation?.consumed) return;
+      // A root user message may batch a background Agent launch acknowledgement
+      // with unrelated tool results. The normalizer removes only that launch
+      // block so the remaining parent activity still flows normally.
+      const parentRaw = observation?.forwarded ?? raw;
+      const ev = normalizeCliEvent(parentRaw, cliEventContext);
       if (ev) {
         events.push(ev);
         options.onEvent?.(ev);
       }
-      if (!isCodexReasoningEvent(raw)) {
-        const text = textFromEvent(raw);
+      if (!isCodexReasoningEvent(parentRaw)) {
+        const text = textFromEvent(parentRaw);
         pushUniqueText(texts, text);
       }
-      captureStructuredOutputFromRaw(raw);
-      if (raw.usage) usage = raw.usage;
-      // intelligence-ramp Phase 5.1: capture session_id from CLI events so the
-      // coordinator can chain it on the next continuation. Claude Code emits
-      // session_id on the init system message and again on the result event.
-      const candidateSessionId = raw.session_id ?? raw.sessionId ?? raw.thread_id ?? null;
-      if (typeof candidateSessionId === "string" && candidateSessionId.trim().length > 0) {
-        providerSessionId = candidateSessionId.trim();
-      }
-      if (raw.type === "error") {
-        const rawError = raw.message || raw.error || "cli error";
+      captureStructuredOutputFromRaw(parentRaw);
+      if (parentRaw.usage) usage = parentRaw.usage;
+      if (parentRaw.type === "error") {
+        const rawError = parentRaw.message || parentRaw.error || "cli error";
         errorMessage = typeof rawError === "string" ? rawError : JSON.stringify(rawError);
         failureKind = "provider_unavailable";
+        drainSubagents("subagent stopped because the Claude CLI stream failed");
       }
-      const resultError = resultEventError(raw, commandSpec.command);
+      const resultError = resultEventError(parentRaw, commandSpec.command);
       if (resultError) {
         errorMessage = resultError.message;
         failureKind = resultError.failureKind;
+        drainSubagents("subagent stopped because the Claude CLI stream failed");
       }
     });
 
+    child.on("error", (error) => {
+      if (!errorMessage) errorMessage = error?.message || String(error);
+      failureKind ||= "provider_unavailable";
+      drainSubagents("subagent stopped because the Claude CLI process failed");
+    });
+
     if (options.abortSignal) {
-      const abort = () => child.kill("SIGTERM");
-      if (options.abortSignal.aborted) abort();
-      else options.abortSignal.addEventListener("abort", abort, { once: true });
+      abortHandler = () => {
+        drainSubagents("subagent cancelled with the parent run");
+        child.kill("SIGTERM");
+      };
+      if (options.abortSignal.aborted) abortHandler();
+      else options.abortSignal.addEventListener("abort", abortHandler, { once: true });
     }
 
     const exitCode = await new Promise((resolve) => child.on("close", resolve));
+    drainSubagents(options.abortSignal?.aborted
+      ? "subagent cancelled with the parent run"
+      : exitCode === 0
+        ? "subagent stream closed before completion"
+        : "subagent stopped because the Claude CLI process failed");
     const stderrText = stderrTail.toString().trim();
     let cliErrorCode = null;
     if (exitCode !== 0 && !errorMessage) errorMessage = stderrText || `${commandSpec.command} exited ${exitCode}`;
@@ -706,6 +753,7 @@ export async function generateCliResponse(systemPrompt, options = {}) {
       cache_creation_tokens: cacheCreationTokens || null,
       cost_usd: costUsd,
     };
+    const subagentCapabilities = observedSubagentCapabilities();
     return {
       text,
       structuredResult,
@@ -733,14 +781,18 @@ export async function generateCliResponse(systemPrompt, options = {}) {
         promptCacheActive: (cachedTokens || 0) > 0 || (cacheCreationTokens || 0) > 0,
         thinkingEnabled: null,
         structuredOutputEnforced: !!options.outputSchema,
-        subagentInvoked: null,
+        subagentInvoked: subagentCapabilities.invoked,
         mcpServersUsed: Object.keys(options.mcpServers || {}),
-        nativeSubagentsUsed: [],
+        nativeSubagentsUsed: subagentCapabilities.names,
         toolCompactionApplied: false,
         contextCompactionApplied: null,
       }),
     };
   } catch (err) {
+    drainSubagents(options.abortSignal?.aborted
+      ? "subagent cancelled with the parent run"
+      : "subagent stopped because the Claude CLI process failed");
+    const subagentCapabilities = observedSubagentCapabilities();
     return {
       text: texts[texts.length - 1] || null,
       structuredResult,
@@ -766,14 +818,17 @@ export async function generateCliResponse(systemPrompt, options = {}) {
         promptCacheActive: null,
         thinkingEnabled: null,
         structuredOutputEnforced: !!options.outputSchema,
-        subagentInvoked: null,
+        subagentInvoked: subagentCapabilities.invoked,
         mcpServersUsed: Object.keys(options.mcpServers || {}),
-        nativeSubagentsUsed: [],
+        nativeSubagentsUsed: subagentCapabilities.names,
         toolCompactionApplied: false,
         contextCompactionApplied: null,
       }),
     };
   } finally {
+    if (abortHandler && options.abortSignal) {
+      options.abortSignal.removeEventListener?.("abort", abortHandler);
+    }
     try { rmSync(dir, { recursive: true, force: true }); } catch {}
   }
 }