@mono-agent/agent-runtime 0.18.0 → 0.18.2

package/src/ai/providers/acp-session-tokens.js

@@ -1,16 +1,31 @@
 // @ts-check
 
+import {
+  createCipheriv,
+  createDecipheriv,
+  hkdfSync,
+  randomBytes,
+} from "node:crypto";
+
 const PROFILE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
 const MAX_PROFILE_ID_LENGTH = 128;
 const MAX_RAW_TOKEN_BYTES = 4_096;
-const MAX_ENCODED_TOKEN_LENGTH = Math.ceil(MAX_RAW_TOKEN_BYTES * 4 / 3);
-const PROVIDER_SESSION_PREFIX = "acp:v1:";
-const SESSION_CURSOR_PREFIX = "acp-cursor:v1:";
+const TOKEN_KEY_BYTES = 32;
+const NONCE_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+const MAX_SEALED_TOKEN_BYTES = NONCE_BYTES + MAX_RAW_TOKEN_BYTES + AUTH_TAG_BYTES;
+const MAX_ENCODED_TOKEN_LENGTH = Math.ceil(MAX_SEALED_TOKEN_BYTES * 4 / 3);
+const PROVIDER_SESSION_PREFIX = "acp:v2:";
+const SESSION_CURSOR_PREFIX = "acp-cursor:v2:";
 const MAX_PROVIDER_SESSION_ID_LENGTH = PROVIDER_SESSION_PREFIX.length
   + MAX_PROFILE_ID_LENGTH + 1 + MAX_ENCODED_TOKEN_LENGTH;
 const MAX_SESSION_CURSOR_LENGTH = SESSION_CURSOR_PREFIX.length
   + MAX_PROFILE_ID_LENGTH + 1 + MAX_ENCODED_TOKEN_LENGTH;
+const TOKEN_DOMAIN = Buffer.from("mono-agent/acp-session-token", "utf8");
+const TOKEN_VERSION = Buffer.from("v2", "utf8");
+const HKDF_SALT = Buffer.from("mono-agent/acp-session-token/v2/hkdf", "utf8");
+const ENCRYPTION_INFO = Buffer.from("mono-agent/acp-session-token/v2/encryption", "utf8");
 
 export class AcpClientError extends Error {
   /**
@@ -45,46 +60,187 @@ function requiredTokenString(value, code, label) {
   return value;
 }
 
-/** @param {string} encoded @param {string} code @param {string} label */
-function decodeToken(encoded, code, label) {
-  if (!BASE64URL_RE.test(encoded)) throw new AcpClientError(code, `Invalid ${label} encoding.`);
-  const bytes = Buffer.from(encoded, "base64url");
-  if (bytes.length === 0 || bytes.toString("base64url") !== encoded) {
-    throw new AcpClientError(code, `Non-canonical ${label} encoding.`);
+/**
+ * The token key is binary on purpose: accepting textual secrets here would
+ * make encoding, truncation, and cross-host persistence ambiguous.
+ * @param {unknown} value
+ */
+function sessionTokenKey(value) {
+  if (!(value instanceof Uint8Array) || value.byteLength !== TOKEN_KEY_BYTES) {
+    throw new AcpClientError(
+      "invalid_token_key",
+      `ACP session token key must be exactly ${TOKEN_KEY_BYTES} bytes.`,
+    );
   }
-  if (bytes.length > MAX_RAW_TOKEN_BYTES) {
-    throw new AcpClientError(code, `${label} exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+}
+
+/** @param {unknown} key @returns {Buffer} */
+export function validateAcpSessionTokenKey(key) {
+  return Buffer.from(sessionTokenKey(key));
+}
+
+/** @param {ReadonlyArray<Uint8Array>} parts */
+function frame(parts) {
+  const size = parts.reduce((total, part) => total + 4 + part.byteLength, 0);
+  const result = Buffer.allocUnsafe(size);
+  let offset = 0;
+  for (const part of parts) {
+    result.writeUInt32BE(part.byteLength, offset);
+    offset += 4;
+    Buffer.from(part.buffer, part.byteOffset, part.byteLength).copy(result, offset);
+    offset += part.byteLength;
   }
+  return result;
+}
+
+/** @param {"session"|"cursor"} kind @param {string} profileId */
+function tokenAad(kind, profileId) {
+  return frame([
+    TOKEN_DOMAIN,
+    TOKEN_VERSION,
+    Buffer.from(kind, "utf8"),
+    Buffer.from(profileId, "utf8"),
+  ]);
+}
+
+/** @param {Uint8Array} key */
+function encryptionKey(key) {
+  const rawKey = Buffer.from(sessionTokenKey(key));
   try {
-    return requiredTokenString(new TextDecoder("utf-8", { fatal: true }).decode(bytes), code, label);
-  } catch (error) {
-    if (error instanceof AcpClientError) throw error;
-    throw new AcpClientError(code, `${label} is not valid UTF-8.`);
+    return Buffer.from(hkdfSync("sha256", rawKey, HKDF_SALT, ENCRYPTION_INFO, TOKEN_KEY_BYTES));
+  } finally {
+    rawKey.fill(0);
   }
 }
 
-/** @param {string} profileId @param {string} sessionId */
-export function encodeAcpProviderSessionId(profileId, sessionId) {
+/** @param {string} profileId @param {string} raw @param {string} code @param {string} label */
+function rawTokenBytes(profileId, raw, code, label) {
   validateAcpProfileId(profileId);
-  requiredTokenString(sessionId, "invalid_session_id", "ACP session id");
-  if (Buffer.byteLength(sessionId, "utf8") > MAX_RAW_TOKEN_BYTES) {
-    throw new AcpClientError("invalid_session_id", `ACP session id exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
+  requiredTokenString(raw, code, label);
+  const plaintext = Buffer.from(raw, "utf8");
+  if (plaintext.byteLength > MAX_RAW_TOKEN_BYTES) {
+    throw new AcpClientError(code, `${label} exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
   }
-  return `${PROVIDER_SESSION_PREFIX}${profileId}:${Buffer.from(sessionId, "utf8").toString("base64url")}`;
+  return plaintext;
 }
 
-/** Internal protocol-state decoder. This module is not a package export. @param {string} providerSessionId */
-export function decodeAcpProviderSessionId(providerSessionId) {
-  if (typeof providerSessionId !== "string") {
-    throw new AcpClientError("invalid_session_id", "ACP provider session id must be a string.");
+/**
+ * @param {"session"|"cursor"} kind
+ * @param {string} profileId
+ * @param {string} raw
+ * @param {Uint8Array} key
+ * @param {string} code
+ * @param {string} label
+ */
+function sealToken(kind, profileId, raw, key, code, label) {
+  const plaintext = rawTokenBytes(profileId, raw, code, label);
+  const aad = tokenAad(kind, profileId);
+  const nonce = randomBytes(NONCE_BYTES);
+  const derivedKey = encryptionKey(key);
+  let cipher;
+  try {
+    cipher = createCipheriv("aes-256-gcm", derivedKey, nonce);
+  } finally {
+    derivedKey.fill(0);
   }
-  if (providerSessionId.length > MAX_PROVIDER_SESSION_ID_LENGTH) {
-    throw new AcpClientError("invalid_session_id", "ACP provider session id exceeds the supported length.");
+  cipher.setAAD(aad);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return Buffer.concat([nonce, ciphertext, cipher.getAuthTag()]).toString("base64url");
+}
+
+/** @param {string} profileId @param {string} code @param {string} label */
+function tokenProfileId(profileId, code, label) {
+  try {
+    return validateAcpProfileId(profileId);
+  } catch {
+    throw new AcpClientError(code, `Invalid ${label}.`);
   }
-  const match = /^acp:v1:([^:]+):([^:]+)$/.exec(providerSessionId);
+}
+
+/**
+ * @param {string} encoded
+ * @param {string} code
+ * @param {string} label
+ */
+function sealedTokenBytes(encoded, code, label) {
+  if (!BASE64URL_RE.test(encoded)) throw new AcpClientError(code, `Invalid ${label}.`);
+  const sealed = Buffer.from(encoded, "base64url");
+  if (sealed.toString("base64url") !== encoded
+    || sealed.byteLength <= NONCE_BYTES + AUTH_TAG_BYTES
+    || sealed.byteLength > MAX_SEALED_TOKEN_BYTES) {
+    throw new AcpClientError(code, `Invalid ${label}.`);
+  }
+  return sealed;
+}
+
+/**
+ * @param {"session"|"cursor"} kind
+ * @param {string} profileId
+ * @param {string} encoded
+ * @param {Uint8Array} key
+ * @param {string} code
+ * @param {string} label
+ */
+function openToken(kind, profileId, encoded, key, code, label) {
+  const sealed = sealedTokenBytes(encoded, code, label);
+  const aad = tokenAad(kind, profileId);
+  const nonce = sealed.subarray(0, NONCE_BYTES);
+  const ciphertext = sealed.subarray(NONCE_BYTES, -AUTH_TAG_BYTES);
+  const authTag = sealed.subarray(-AUTH_TAG_BYTES);
+  const derivedKey = encryptionKey(key);
+  let decipher;
+  try {
+    decipher = createDecipheriv("aes-256-gcm", derivedKey, nonce);
+  } finally {
+    derivedKey.fill(0);
+  }
+  let plaintext;
+  try {
+    decipher.setAAD(aad);
+    decipher.setAuthTag(authTag);
+    plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch {
+    throw new AcpClientError(code, `Invalid ${label}.`);
+  }
+  try {
+    return requiredTokenString(
+      new TextDecoder("utf-8", { fatal: true }).decode(plaintext),
+      code,
+      label,
+    );
+  } catch (error) {
+    if (error instanceof AcpClientError) throw error;
+    throw new AcpClientError(code, `Invalid ${label}.`);
+  }
+}
+
+/** @param {string} profileId @param {string} sessionId @param {Uint8Array} key */
+export function encodeAcpProviderSessionId(profileId, sessionId, key) {
+  const encoded = sealToken("session", profileId, sessionId, key, "invalid_session_id", "ACP session id");
+  return `${PROVIDER_SESSION_PREFIX}${profileId}:${encoded}`;
+}
+
+/**
+ * Internal protocol-state decoder. This module is not a package export.
+ * @param {string} providerSessionId
+ * @param {Uint8Array} key
+ */
+export function decodeAcpProviderSessionId(providerSessionId, key) {
+  if (typeof providerSessionId !== "string" || providerSessionId.length > MAX_PROVIDER_SESSION_ID_LENGTH) {
+    throw new AcpClientError("invalid_session_id", "Invalid ACP provider session id.");
+  }
+  const match = /^acp:v2:([^:]+):([^:]+)$/.exec(providerSessionId);
   if (!match) throw new AcpClientError("invalid_session_id", "Invalid ACP provider session id.");
-  const profileId = validateAcpProfileId(match[1]);
-  const sessionId = decodeToken(match[2], "invalid_session_id", "ACP session id");
+  const profileId = tokenProfileId(match[1], "invalid_session_id", "ACP provider session id");
+  const sessionId = openToken(
+    "session",
+    profileId,
+    match[2],
+    key,
+    "invalid_session_id",
+    "ACP provider session id",
+  );
   return { profileId, sessionId };
 }
 
@@ -94,36 +250,33 @@ export function decodeAcpProviderSessionId(providerSessionId) {
  *
  * @param {string} providerSessionId
  * @param {string} expectedProfileId
+ * @param {Uint8Array} key Host-owned 32-byte ACP session-token key.
  * @returns {string}
  */
-export function validateAcpProviderSessionId(providerSessionId, expectedProfileId) {
+export function validateAcpProviderSessionId(providerSessionId, expectedProfileId, key) {
   const profileId = validateAcpProfileId(expectedProfileId);
-  const decoded = decodeAcpProviderSessionId(providerSessionId);
+  const decoded = decodeAcpProviderSessionId(providerSessionId, key);
   if (decoded.profileId !== profileId) {
     throw new AcpClientError("invalid_session_id", "ACP provider session belongs to a different profile.");
   }
   return providerSessionId;
 }
 
-/** @param {string} profileId @param {string} cursor */
-export function encodeAcpSessionCursor(profileId, cursor) {
-  validateAcpProfileId(profileId);
-  requiredTokenString(cursor, "invalid_cursor", "ACP session cursor");
-  if (Buffer.byteLength(cursor, "utf8") > MAX_RAW_TOKEN_BYTES) {
-    throw new AcpClientError("invalid_cursor", `ACP session cursor exceeds ${MAX_RAW_TOKEN_BYTES} bytes.`);
-  }
-  return `${SESSION_CURSOR_PREFIX}${profileId}:${Buffer.from(cursor, "utf8").toString("base64url")}`;
+/** @param {string} profileId @param {string} cursor @param {Uint8Array} key */
+export function encodeAcpSessionCursor(profileId, cursor, key) {
+  const encoded = sealToken("cursor", profileId, cursor, key, "invalid_cursor", "ACP session cursor");
+  return `${SESSION_CURSOR_PREFIX}${profileId}:${encoded}`;
 }
 
-/** @param {string} profileId @param {unknown} cursor */
-export function decodeAcpSessionCursor(profileId, cursor) {
+/** @param {string} profileId @param {unknown} cursor @param {Uint8Array} key */
+export function decodeAcpSessionCursor(profileId, cursor, key) {
   validateAcpProfileId(profileId);
   if (typeof cursor !== "string" || cursor.length > MAX_SESSION_CURSOR_LENGTH) {
     throw new AcpClientError("invalid_cursor", "ACP session cursor must be an opaque cursor returned by listAcpSessions.");
   }
-  const match = /^acp-cursor:v1:([^:]+):([^:]+)$/.exec(cursor);
-  if (!match || match[1] !== profileId) {
+  const match = /^acp-cursor:v2:([^:]+):([^:]+)$/.exec(cursor);
+  if (!match || tokenProfileId(match[1], "invalid_cursor", "ACP session cursor") !== profileId) {
     throw new AcpClientError("invalid_cursor", "ACP session cursor is invalid for this profile.");
   }
-  return decodeToken(match[2], "invalid_cursor", "ACP session cursor");
+  return openToken("cursor", profileId, match[2], key, "invalid_cursor", "ACP session cursor");
 }

package/src/ai/providers/acp-transport.js

@@ -1,5 +1,7 @@
 // @ts-check
 
+import { AsyncLocalStorage } from "node:async_hooks";
+
 // Strict, bounded ACP v1 newline transport for an owned stdio child process.
 // The SDK's stock ndJsonStream intentionally tolerates malformed input and its
 // line buffer is unbounded, which is a poor fit for a long-lived host boundary.
@@ -7,6 +9,101 @@
 const DEFAULT_MAX_LINE_BYTES = 1024 * 1024;
 const MAX_MAX_LINE_BYTES = 16 * 1024 * 1024;
 
+// @agentclientprotocol/sdk 1.3.0 sends the trailing arguments of these
+// diagnostics directly to console. Those values include raw JSON-RPC payloads
+// (and, for malformed notifications, Zod error details derived from them).
+// Preserve the useful classification while dropping payload-bearing details.
+const ACP_SDK_PAYLOAD_DIAGNOSTICS = Object.freeze({
+  error: new Set([
+    "Invalid message",
+    "Error handling notification",
+    "Got response to unknown request",
+    "Failed to parse JSON message:",
+    "ACP connection router stopped unexpectedly:",
+  ]),
+  warn: new Set([
+    "Skipping JSON line that is not an object:",
+  ]),
+});
+const acpSdkDiagnosticScope = new AsyncLocalStorage();
+let activeAcpSdkDiagnosticGuards = 0;
+/** @type {null|{
+ *   originalError: typeof console.error,
+ *   originalWarn: typeof console.warn,
+ *   guardedError: typeof console.error,
+ *   guardedWarn: typeof console.warn,
+ * }} */
+let acpSdkConsoleGuard = null;
+
+function installAcpSdkConsoleGuard() {
+  activeAcpSdkDiagnosticGuards += 1;
+  if (acpSdkConsoleGuard) return;
+
+  const originalError = console.error;
+  const originalWarn = console.warn;
+  /** @type {typeof console.error} */
+  const guardedError = (...args) => {
+    const contentFree = args[0];
+    if (acpSdkDiagnosticScope.getStore() === true
+      && typeof contentFree === "string"
+      && ACP_SDK_PAYLOAD_DIAGNOSTICS.error.has(contentFree)) {
+      Reflect.apply(originalError, console, [contentFree]);
+      return;
+    }
+    Reflect.apply(originalError, console, args);
+  };
+  /** @type {typeof console.warn} */
+  const guardedWarn = (...args) => {
+    const contentFree = args[0];
+    if (acpSdkDiagnosticScope.getStore() === true
+      && typeof contentFree === "string"
+      && ACP_SDK_PAYLOAD_DIAGNOSTICS.warn.has(contentFree)) {
+      Reflect.apply(originalWarn, console, [contentFree]);
+      return;
+    }
+    Reflect.apply(originalWarn, console, args);
+  };
+
+  acpSdkConsoleGuard = { originalError, originalWarn, guardedError, guardedWarn };
+  console.error = guardedError;
+  console.warn = guardedWarn;
+}
+
+function releaseAcpSdkConsoleGuard() {
+  activeAcpSdkDiagnosticGuards = Math.max(0, activeAcpSdkDiagnosticGuards - 1);
+  if (activeAcpSdkDiagnosticGuards !== 0 || !acpSdkConsoleGuard) return;
+  const guard = acpSdkConsoleGuard;
+  acpSdkConsoleGuard = null;
+  if (console.error === guard.guardedError) console.error = guard.originalError;
+  if (console.warn === guard.guardedWarn) console.warn = guard.originalWarn;
+}
+
+/**
+ * Open one SDK connection inside an async context that strips payload-bearing
+ * SDK console arguments. The SDK starts its detached receive loop during
+ * `connect`, so descendants retain this scope without muting concurrent host
+ * work or other ACP connections.
+ *
+ * @template {{closed: Promise<unknown>}} T
+ * @param {() => T} connect
+ * @returns {T}
+ */
+export function connectWithSafeAcpSdkDiagnostics(connect) {
+  installAcpSdkConsoleGuard();
+  let connection;
+  try {
+    connection = acpSdkDiagnosticScope.run(true, connect);
+  } catch (error) {
+    releaseAcpSdkConsoleGuard();
+    throw error;
+  }
+  void Promise.resolve(connection.closed).then(
+    releaseAcpSdkConsoleGuard,
+    releaseAcpSdkConsoleGuard,
+  );
+  return connection;
+}
+
 export class AcpTransportError extends Error {
   /**
    * @param {string} code

package/src/ai/providers/acp.js

@@ -11,6 +11,7 @@ import {
   decodeAcpProviderSessionId,
   encodeAcpProviderSessionId,
   validateAcpProviderSessionId,
+  validateAcpSessionTokenKey,
 } from "./acp-session-tokens.js";
 import {
   ownAcpSessionUpdateKind,
@@ -288,8 +289,8 @@ function selectValues(options) {
   return values;
 }
 
-/** @param {any} connection @param {any} descriptor @param {any} req @param {string} profileId @param {(notification:any)=>void} onUpdate */
-async function openSession(connection, descriptor, req, profileId, onUpdate) {
+/** @param {any} connection @param {any} descriptor @param {any} req @param {string} profileId @param {Uint8Array} key @param {(notification:any)=>void} onUpdate */
+async function openSession(connection, descriptor, req, profileId, key, onUpdate) {
   const cwd = workspaceFor(descriptor, req);
   const config = sessionConfig(descriptor);
   const baseRequest = { cwd, ...config };
@@ -297,7 +298,7 @@ async function openSession(connection, descriptor, req, profileId, onUpdate) {
     const response = await connection.newSession(baseRequest);
     return { sessionId: response.sessionId, response, resumed: false, resumeMethod: null };
   }
-  const decoded = decodeAcpProviderSessionId(req.providerSessionId);
+  const decoded = decodeAcpProviderSessionId(req.providerSessionId, key);
   if (decoded.profileId !== profileId) {
     throw new AcpClientError("invalid_session_id", "ACP provider session belongs to a different profile.");
   }
@@ -369,8 +370,13 @@ export async function generateAcpResponse(systemPrompt, req) {
   let setup = null;
   let configuration = { modeApplied: false, configOptionsApplied: [] };
   try {
+    const sessionTokenKey = validateAcpSessionTokenKey(req?.acpSessionTokenKey);
     if (req?.providerSessionId != null) {
-      providerSessionId = validateAcpProviderSessionId(req.providerSessionId, profileId);
+      providerSessionId = validateAcpProviderSessionId(
+        req.providerSessionId,
+        profileId,
+        sessionTokenKey,
+      );
     }
     connection = await connectAcpProfile(profileId, {
       resolveAcpProfile: req.resolveAcpProfile,
@@ -382,6 +388,7 @@ export async function generateAcpResponse(systemPrompt, req) {
       signal: req.abortSignal,
       context: { operation: "run", model: reference },
       operation: "run",
+      acpSessionTokenKey: sessionTokenKey,
     });
     capture({
       type: "capabilities_resolved",
@@ -395,9 +402,18 @@ export async function generateAcpResponse(systemPrompt, req) {
     const onUpdate = (notification) => {
       for (const event of normalizeUpdate(notification, state)) capture(event);
     };
-    setup = await openSession(connection, connection.descriptor, req, profileId, onUpdate);
+    setup = await openSession(
+      connection,
+      connection.descriptor,
+      req,
+      profileId,
+      sessionTokenKey,
+      onUpdate,
+    );
     sessionId = setup.sessionId;
-    providerSessionId = encodeAcpProviderSessionId(profileId, sessionId);
+    providerSessionId = setup.resumed && providerSessionId
+      ? providerSessionId
+      : encodeAcpProviderSessionId(profileId, sessionId, sessionTokenKey);
     configuration = await applyClientConfiguration(
       connection,
       sessionId,

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 {}
   }
 }