@agent-compose/sdk 0.8.4 → 0.8.6

package/src/runtimes/claude-code.ts

@@ -34,9 +34,14 @@
  *     token-metering gateway's Anthropic passthrough (ADR-0039).
  */
 
-import type { AgentMessage, AgentMessageTaskNotification } from "../index.js";
+import type {
+  AgentMessage, AgentMessageCompaction, AgentMessageModelUsage, AgentMessagePlanLimits,
+  AgentMessageTaskNotification, AgentMessageTaskProgress, AgentMessageUsage,
+  WorkflowProgressEntry,
+} from "../index.js";
 import { createCliAgentRuntime, shellQuote, type CliAgentSpec, type CliReasoningEffort } from "./_cli-agent.js";
 import { formatError } from "../utils/errors.js";
+import { CLAUDE_CODE_VERSION } from "../sandbox/baked-clis.js";
 
 function now(): string { return new Date().toISOString(); }
 
@@ -171,6 +176,37 @@ export function parseTaskNotifications(
   return out;
 }
 
+/** Clamp for a steer delivered into a child's thread — same ceiling as a
+ *  notification report: plenty for any real addendum, bounded against a
+ *  runaway blob. */
+const SUBAGENT_USER_MESSAGE_MAX = 20_000;
+
+/** One user-role TEXT blob from the stream, mapped with sidechain awareness.
+ *  Task-notification blocks parse into structure wherever they appear (their
+ *  arrival side is resume-dependent — see the transport notes above). What
+ *  remains is then split by attribution: TOP-LEVEL text (no parent id) stays
+ *  unmapped exactly as before — prompt echoes and system reminders are not
+ *  agent output. SIDECHAIN text (parent id present) is a message landing in
+ *  a child subagent's thread — a delivered SendMessage steer — and forwards
+ *  as `subagent_user_message`, except harness plumbing (`<system-reminder>`
+ *  wrappers the CLI injects into child threads), which no renderer should
+ *  see. Exported for tests. */
+export function sidechainAwareUserText(
+  text: string, parentToolUseId: string | undefined, timestamp: string,
+): AgentMessage[] {
+  const notifications = parseTaskNotifications(text, timestamp);
+  if (notifications.length > 0) return notifications;
+  if (!parentToolUseId) return [];
+  const trimmed = text.trim();
+  if (trimmed.length === 0 || trimmed.startsWith("<system-reminder>")) return [];
+  return [{
+    type: "subagent_user_message",
+    text: clip(trimmed, SUBAGENT_USER_MESSAGE_MAX),
+    parentToolUseId,
+    timestamp,
+  }];
+}
+
 /** One `system`/`task_notification` stream-json event mapped onto the same
  *  structured message the XML parse produces, or null when the event names
  *  no task id. Pure and tolerant over untrusted harness JSON: absent fields
@@ -206,6 +242,275 @@ export function parseSystemTaskNotification(
   };
 }
 
+// ── Task progress (live background-workflow evidence) ───────────────────────
+//
+// While a harness Workflow (the CLI's in-harness dynamic-workflow tool)
+// runs in the background, stream-json emits `system`/`task_progress`
+// events carrying the workflow's CUMULATIVE `workflow_progress` array —
+// verified live on 2.1.241 (`-p --output-format stream-json`): the array
+// re-sends on every agent state change immediately and on a ~10s heartbeat
+// otherwise, each `workflow_agent` entry updated in place (label,
+// phase, model, state, tokens, toolCalls, durationMs). This is the ONLY
+// per-agent evidence the wire ever carries — the completion notification
+// reports aggregates only — so dropping it leaves workflow cards blind.
+// Preview text (promptPreview / resultPreview) is internal plumbing and is
+// not forwarded, same rule as task notifications.
+
+const PROGRESS_PHASES_MAX = 32;
+const PROGRESS_AGENTS_MAX = 128;
+const PROGRESS_LABEL_MAX = 200;
+const PROGRESS_ERROR_MAX = 500;
+
+const AGENT_STATES: ReadonlySet<string> = new Set(["start", "progress", "done", "error"]);
+
+/** One `system`/`task_progress` event mapped onto the structured progress
+ *  message, or null only when it names no task. Workflow tasks carry the
+ *  cumulative `workflow_progress` entries; a plain background Agent-task
+ *  heartbeat (no workflow entries — verified live on 2.1.241, ~10s cadence
+ *  while the task runs) forwards with `workflow: []` so the platform can
+ *  DECLARE the running task as session background work (the delegation-
+ *  survives-the-human contract: parks, user interrupts, and supersedes all
+ *  read the declared-children registry). Completion evidence still rides
+ *  `task_notification`. Pure and tolerant over untrusted harness JSON:
+ *  malformed entries are skipped, everything is clamped (phases keep the
+ *  FIRST 32 — they are seeded up front; agents keep the LAST 128 — late
+ *  spawns matter more than a long-settled prefix). Exported for tests. */
+export function parseSystemTaskProgress(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessageTaskProgress | null {
+  const taskId = typeof p.task_id === "string" && p.task_id.trim().length > 0 ? p.task_id.trim() : null;
+  if (!taskId) return null;
+  const raw = Array.isArray(p.workflow_progress) ? p.workflow_progress : [];
+  const nonneg = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  const str = (v: unknown, max: number): string | undefined =>
+    typeof v === "string" && v.length > 0 ? clip(v, max) : undefined;
+  const phases: WorkflowProgressEntry[] = [];
+  const agents: WorkflowProgressEntry[] = [];
+  for (const e of raw) {
+    if (typeof e !== "object" || e === null) continue;
+    const o = e as Record<string, unknown>;
+    const index = nonneg(o.index);
+    if (index === undefined) continue;
+    if (o.type === "workflow_phase") {
+      const title = str(o.title, PROGRESS_LABEL_MAX);
+      if (title && phases.length < PROGRESS_PHASES_MAX) phases.push({ kind: "phase", index, title });
+      continue;
+    }
+    if (o.type !== "workflow_agent") continue;
+    const label = str(o.label, PROGRESS_LABEL_MAX);
+    const state = typeof o.state === "string" && AGENT_STATES.has(o.state) ? o.state as "start" | "progress" | "done" | "error" : null;
+    if (!label || !state) continue;
+    agents.push({
+      kind: "agent", index, label, state,
+      ...(nonneg(o.phaseIndex) !== undefined ? { phaseIndex: nonneg(o.phaseIndex) } : {}),
+      ...(str(o.phaseTitle, PROGRESS_LABEL_MAX) ? { phaseTitle: str(o.phaseTitle, PROGRESS_LABEL_MAX) } : {}),
+      ...(str(o.model, 100) ? { model: str(o.model, 100) } : {}),
+      ...(str(o.agentId, 128) ? { agentId: str(o.agentId, 128) } : {}),
+      ...(nonneg(o.tokens) !== undefined ? { tokens: nonneg(o.tokens) } : {}),
+      ...(nonneg(o.toolCalls) !== undefined ? { toolCalls: nonneg(o.toolCalls) } : {}),
+      ...(nonneg(o.durationMs) !== undefined ? { durationMs: nonneg(o.durationMs) } : {}),
+      ...(nonneg(o.startedAt) !== undefined ? { startedAt: nonneg(o.startedAt) } : {}),
+      ...(state === "error" && str(o.error, PROGRESS_ERROR_MAX) ? { error: str(o.error, PROGRESS_ERROR_MAX) } : {}),
+      ...(o.cached === true ? { cached: true as const } : {}),
+      ...(o.skipped === true ? { skipped: true as const } : {}),
+    });
+  }
+  // Empty = a plain Agent-task heartbeat, forwarded as liveness evidence
+  // (see the header) — the workflow delta folder ignores it (no entries),
+  // and only the background-work declare consumes it.
+  const workflow = [...phases, ...agents.slice(-PROGRESS_AGENTS_MAX)];
+  const toolUseId = typeof p.tool_use_id === "string" && p.tool_use_id.length > 0 ? p.tool_use_id : null;
+  const u = (typeof p.usage === "object" && p.usage !== null ? p.usage : {}) as Record<string, unknown>;
+  const tokens = nonneg(u.total_tokens);
+  const toolUses = nonneg(u.tool_uses);
+  const durationMs = nonneg(u.duration_ms);
+  return {
+    type: "task_progress",
+    taskId: clip(taskId, 128),
+    ...(toolUseId ? { toolUseId: clip(toolUseId, 128) } : {}),
+    ...(tokens !== undefined || toolUses !== undefined || durationMs !== undefined
+      ? { usage: {
+          ...(tokens !== undefined ? { tokens } : {}),
+          ...(toolUses !== undefined ? { toolUses } : {}),
+          ...(durationMs !== undefined ? { durationMs } : {}),
+        } }
+      : {}),
+    workflow,
+    timestamp,
+  };
+}
+
+// ── Context compaction (the harness summarizing its own conversation) ───────
+//
+// Captured live against 2.1.212 (the baked E2B pin) and 2.1.241 — identical
+// wire shapes on both, `/compact` and forced-auto alike:
+//
+//   {"type":"system","subtype":"status","status":"compacting"}
+//   {"type":"system","subtype":"status","status":null,
+//    "compact_result":"success"|"failed"[,"compact_error":"…"]}
+//   {"type":"system","subtype":"init",…}                (fresh init, success only)
+//   {"type":"system","subtype":"compact_boundary","compact_metadata":
+//     {"trigger":"auto"|"manual","pre_tokens":N,"post_tokens":N,
+//      "cumulative_dropped_tokens":N,"duration_ms":N,"preserved_segment":…}}
+//
+// Followed by the continuation summary as a SYNTHETIC user message (string
+// content, `isSynthetic: true`) — deliberately NOT forwarded: it quotes
+// conversation content verbatim (its "All user messages" section replays
+// platform notices word for word), which is exactly how the 2026-08-23
+// incident re-labeled a platform system notice as a "recalled memory".
+// The boundary does not replay on later resumes (verified live).
+//
+// A compaction spans 13-21s in the small captures and MINUTES at real
+// context sizes — forwarding the lifecycle is what lets downstream render
+// the silence as work instead of death (the 94%-auto-compact dead-air
+// incident).
+
+const COMPACT_ERROR_MAX = 500;
+
+/** One `system` event of the compaction family mapped onto the structured
+ *  lifecycle message, or null when the event is not compaction-shaped (a
+ *  plain `status` event with neither the compacting status nor a
+ *  compact_result stays unmapped). Pure and tolerant over untrusted harness
+ *  JSON. Exported for tests. */
+export function parseSystemCompaction(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessageCompaction | null {
+  const nonneg = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : undefined;
+  if (p.subtype === "status") {
+    if (p.status === "compacting") return { type: "compaction", phase: "start", timestamp };
+    if (typeof p.compact_result === "string") {
+      const failed = p.compact_result !== "success";
+      const error = typeof p.compact_error === "string" && p.compact_error.length > 0
+        ? clip(p.compact_error, COMPACT_ERROR_MAX) : undefined;
+      return {
+        type: "compaction", phase: "settled",
+        result: failed ? "failed" : "success",
+        ...(failed && error ? { error } : {}),
+        timestamp,
+      };
+    }
+    return null;
+  }
+  if (p.subtype !== "compact_boundary") return null;
+  const meta = (typeof p.compact_metadata === "object" && p.compact_metadata !== null
+    ? p.compact_metadata : {}) as Record<string, unknown>;
+  const preTokens = nonneg(meta.pre_tokens);
+  const postTokens = nonneg(meta.post_tokens);
+  const droppedTokens = nonneg(meta.cumulative_dropped_tokens);
+  const durationMs = nonneg(meta.duration_ms);
+  return {
+    type: "compaction", phase: "boundary",
+    trigger: meta.trigger === "manual" ? "manual" : "auto",
+    ...(preTokens !== undefined ? { preTokens } : {}),
+    ...(postTokens !== undefined ? { postTokens } : {}),
+    ...(droppedTokens !== undefined ? { droppedTokens } : {}),
+    ...(durationMs !== undefined ? { durationMs } : {}),
+    timestamp,
+  };
+}
+
+// ── Plan limits (the account meter, off the stream) ─────────────────────────
+//
+// A subscription-funded `claude -p` reads the `anthropic-ratelimit-unified-*`
+// headers off every response and re-emits them as `rate_limit_event` lines
+// whenever its reading changes (the public Agent SDK's SDKRateLimitEvent;
+// anthropics/claude-code#50518 shows the plainly-allowed shape:
+// `{status: "allowed", resetsAt: 1729281600, rateLimitType: "five_hour"}`,
+// with `utilization` carried only once a window crosses a warning
+// threshold). `resetsAt` is epoch SECONDS. A `rejected` event is the plan's
+// wall for the request just made, with the authoritative reset. The platform
+// folds these into the funding account's meter (one reading per window) and
+// learns a cooldown from a rejected one — never from the notice text.
+
+const PLAN_LIMIT_STATUSES: ReadonlySet<string> = new Set(["allowed", "allowed_warning", "rejected"]);
+
+/** Epoch seconds (the CLI's `resetsAt`) as ISO; undefined for anything else. */
+function epochSecondsIso(v: unknown): string | undefined {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return undefined;
+  return new Date(v * 1000).toISOString();
+}
+
+/** One `rate_limit_event` mapped onto the structured plan-limits message,
+ *  or null when the event names no recognisable status. Pure and tolerant
+ *  over untrusted harness JSON: every field is forwarded only when present
+ *  and well-typed; nothing is defaulted or invented. Exported for tests. */
+export function parsePlanLimits(
+  p: Record<string, unknown>, timestamp: string,
+): AgentMessagePlanLimits | null {
+  const info = (typeof p.rate_limit_info === "object" && p.rate_limit_info !== null
+    ? p.rate_limit_info : null) as Record<string, unknown> | null;
+  if (!info || typeof info.status !== "string" || !PLAN_LIMIT_STATUSES.has(info.status)) return null;
+  const num = (v: unknown): number | undefined =>
+    typeof v === "number" && Number.isFinite(v) ? v : undefined;
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" && v.length > 0 ? clip(v, 100) : undefined;
+  const window = str(info.rateLimitType);
+  const resetsAt = epochSecondsIso(info.resetsAt);
+  const utilization = num(info.utilization);
+  const surpassedThreshold = num(info.surpassedThreshold);
+  const overageStatus = typeof info.overageStatus === "string" && PLAN_LIMIT_STATUSES.has(info.overageStatus)
+    ? info.overageStatus as AgentMessagePlanLimits["status"] : undefined;
+  const overageResetsAt = epochSecondsIso(info.overageResetsAt);
+  const overageDisabledReason = str(info.overageDisabledReason);
+  const overageInUse = typeof info.isUsingOverage === "boolean" ? info.isUsingOverage
+    : typeof info.overageInUse === "boolean" ? info.overageInUse : undefined;
+  const overage = overageStatus !== undefined || overageResetsAt !== undefined
+    || overageDisabledReason !== undefined || overageInUse !== undefined
+    ? {
+        ...(overageStatus !== undefined ? { status: overageStatus } : {}),
+        ...(overageResetsAt !== undefined ? { resetsAt: overageResetsAt } : {}),
+        ...(overageDisabledReason !== undefined ? { disabledReason: overageDisabledReason } : {}),
+        ...(overageInUse !== undefined ? { inUse: overageInUse } : {}),
+      }
+    : undefined;
+  const limitScope = str(info.limitScope);
+  const errorCode = str(info.errorCode);
+  return {
+    type: "plan_limits",
+    status: info.status as AgentMessagePlanLimits["status"],
+    ...(window !== undefined ? { window } : {}),
+    ...(resetsAt !== undefined ? { resetsAt } : {}),
+    ...(utilization !== undefined ? { utilization } : {}),
+    ...(surpassedThreshold !== undefined ? { surpassedThreshold } : {}),
+    ...(overage !== undefined ? { overage } : {}),
+    ...(limitScope !== undefined ? { limitScope } : {}),
+    ...(errorCode !== undefined ? { errorCode } : {}),
+    timestamp,
+  };
+}
+
+/** The terminal result's per-model report (`result.modelUsage`, keyed by
+ *  the raw model string) mapped onto the protocol's per-model shape, or
+ *  undefined when the result carries none. Counts the harness did not
+ *  report stay absent (the four classes default to 0 only when the entry
+ *  exists at all — an entry IS a report of that model). Pure; exported for
+ *  tests. */
+export function parseModelUsage(raw: unknown): Record<string, AgentMessageModelUsage> | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  const opt = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+  const out: Record<string, AgentMessageModelUsage> = {};
+  for (const [model, entry] of Object.entries(raw as Record<string, unknown>)) {
+    if (typeof entry !== "object" || entry === null || model.length === 0) continue;
+    const e = entry as Record<string, unknown>;
+    const thinkingTokens = opt(e.thinkingTokens);
+    const webSearchRequests = opt(e.webSearchRequests);
+    const costUsd = opt(e.costUSD);
+    out[clip(model, 200)] = {
+      inputTokens: num(e.inputTokens),
+      outputTokens: num(e.outputTokens),
+      cacheReadTokens: num(e.cacheReadInputTokens),
+      cacheCreationTokens: num(e.cacheCreationInputTokens),
+      ...(thinkingTokens !== undefined ? { thinkingTokens } : {}),
+      ...(webSearchRequests !== undefined ? { webSearchRequests } : {}),
+      ...(costUsd !== undefined ? { costUsd } : {}),
+    };
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
 /** Claude Code's real reasoning knob is its own `--effort <level>` flag
  *  (low|medium|high|xhigh|max — verified against `claude -p --help`). The
  *  CliReasoningEffort union IS the CLI's vocabulary, so the level rides the
@@ -216,6 +521,50 @@ export function parseSystemTaskNotification(
 export const CLAUDE_CODE_EFFORT_LEVELS: readonly CliReasoningEffort[] =
   ["low", "medium", "high", "xhigh", "max"];
 
+/** The Bash PreToolUse hook rtk installs for Claude Code (`rtk init -g
+ *  --hook-only` writes exactly this entry — matcher `Bash`, command
+ *  `rtk hook claude` — into ~/.claude/settings.json; the image bakes
+ *  RTK_VERSION, sandbox/baked-clis.ts, which this payload was run against).
+ *  `rtk hook claude` reads the PreToolUse JSON on stdin and, when it has a
+ *  filter for the command, answers with `updatedInput` rewriting `git
+ *  status` to `rtk git status` (ls, find, grep, test runners, bun, curl,
+ *  docker, …), so the model reads rtk's compact output. A command it
+ *  cannot compress — an unknown tool, a pipe into one, command or process
+ *  substitution, a heredoc, a file redirect, anything already prefixed
+ *  `rtk`, or a `RTK_DISABLED=1` prefix — gets no output and exit 0, which
+ *  Claude Code treats as "no decision": the original command runs
+ *  unchanged (all verified against the binary).
+ *
+ *  The wrapper fails OPEN both ways. `command -v` covers images without
+ *  rtk (the devbox, a bare Vercel VM): there a bare `rtk hook claude` would
+ *  fail every Bash call's hook with exit 127 — non-blocking, but a stderr
+ *  warning per call; rtk's own legacy shell hook degraded the same way
+ *  ("binary not found: exit 0"). The trailing `exit 0` covers an rtk that
+ *  cannot answer: Claude Code treats a PreToolUse hook's exit 2 as a BLOCK
+ *  of the tool call with stderr fed to the model, and clap exits 2 with
+ *  its usage for a subcommand it does not know — which is how the codex
+ *  hook (RTK_CODEX_HOOK_COMMAND, codex.ts) blocked every codex shell
+ *  command on 2026-10-03, when the image's rtk was a cache-served 0.45.0.
+ *  rtk's hooks never exit non-zero on purpose, so a non-zero exit is a
+ *  broken rtk, and the compressor must never cost the worker its shell:
+ *  the exit code is dropped, and the smoke gate's rtk-hook-rewrite check
+ *  is what proves the rewrite itself. */
+export const RTK_BASH_HOOK_COMMAND =
+  "command -v rtk >/dev/null 2>&1 && rtk hook claude; exit 0";
+
+/** Settings every platform `claude` launch passes as `--settings` (inline
+ *  JSON). Claude Code MERGES hook entries across its settings sources
+ *  instead of replacing them (user → project → local → flag → managed), so
+ *  this rides beside whatever the machine's own ~/.claude/settings.json
+ *  carries, and nothing is written to that file — the right outcome, since
+ *  the server never owns it: home carry tar-restores it whole across
+ *  machines and the image capture strips it as personal state. */
+export const CLAUDE_CODE_PLATFORM_SETTINGS = {
+  hooks: {
+    PreToolUse: [{ matcher: "Bash", hooks: [{ type: "command", command: RTK_BASH_HOOK_COMMAND }] }],
+  },
+} as const;
+
 export const claudeCodeSpec: CliAgentSpec = {
   kind: "claude-code",
   authEnv: "ANTHROPIC_API_KEY",
@@ -225,11 +574,14 @@ export const claudeCodeSpec: CliAgentSpec = {
   acp: { command: "npx", args: ["--yes", CLAUDE_CODE_ACP_ADAPTER] },
   // Bare-sandbox fallback only: the agent-env image bakes /usr/local/bin/claude
   // (same recipe — infra/e2b-template/build.ts), so the probe short-circuits
-  // on the platform path. Anthropic's installer drops a versioned binary under
-  // $HOME with a ~/.local/bin/claude launcher; resolve the symlink and copy
-  // the self-contained binary to a world-executable system path.
+  // on the platform path. The SAME pinned version as the image
+  // (CLAUDE_CODE_VERSION), never latest, so a machine the image predates runs
+  // what the image's machines run. Anthropic's installer drops a versioned
+  // binary under $HOME with a ~/.local/bin/claude launcher; resolve the
+  // symlink and copy the self-contained binary to a world-executable system
+  // path.
   install:
-    'curl -fsSL https://claude.ai/install.sh | bash && ' +
+    `curl -fsSL https://claude.ai/install.sh | bash -s ${CLAUDE_CODE_VERSION} && ` +
     'REAL=$(readlink -f "$HOME/.local/bin/claude") && test -f "$REAL" && ' +
     'sudo cp "$REAL" /usr/local/bin/claude && sudo chmod 0755 /usr/local/bin/claude',
   // Claude reads the prompt from stdin in -p mode.
@@ -244,9 +596,18 @@ export const claudeCodeSpec: CliAgentSpec = {
   // the same build). A message that lands after the result would start a
   // NEW turn in-process, which is why the transport's feeder stops at the
   // result line instead of forwarding past it.
-  streamInput: {
+  midTurnInput: {
+    transport: "stdin-stream",
     promptLine: (prompt) => JSON.stringify({ type: "user", message: { role: "user", content: prompt } }),
     messageLine: (text) => JSON.stringify({ type: "user", message: { role: "user", content: text } }),
+    // The ESC equivalent (verified live against claude 2.1.236): the CLI's
+    // control layer processes this OUT OF BAND — a 120s foreground Bash call
+    // aborted 6s in, the control_response answered instantly, the run ended
+    // ~100ms later with `result: error_during_execution`, and `--resume` on
+    // the same session id kept the full turn context.
+    interruptLine: (requestId) => JSON.stringify({
+      type: "control_request", request_id: requestId, request: { subtype: "interrupt" },
+    }),
   },
   buildCommand: ({ promptPath, sessionId, model, cwd, effort, streamInput }) => {
     const flags = [
@@ -268,6 +629,10 @@ export const claudeCodeSpec: CliAgentSpec = {
       // claude's own attestation env for exactly this: it lifts the flag's
       // root-user refusal (the E2B agent-env user is root).
       "--dangerously-skip-permissions",
+      // rtk's Bash PreToolUse hook (RTK_BASH_HOOK_COMMAND): shell output is
+      // compressed before it reaches the model. Flag settings merge with the
+      // machine's own settings; they never replace them.
+      `--settings ${shellQuote(JSON.stringify(CLAUDE_CODE_PLATFORM_SETTINGS))}`,
       ...(model ? [`--model ${shellQuote(model)}`] : []),
       // Reasoning effort is the CLI's own flag; the value comes from the
       // closed CliReasoningEffort set, so it is shell-safe unquoted.
@@ -285,9 +650,10 @@ export const claudeCodeSpec: CliAgentSpec = {
     // tool_use id; null at top level). Forwarded on tool_use/tool_result so
     // renderers can nest child activity under the spawning call instead of
     // flattening it into the parent transcript unattributed.
-    const parent = typeof p.parent_tool_use_id === "string" && p.parent_tool_use_id.length > 0
-      ? { parentToolUseId: p.parent_tool_use_id }
-      : {};
+    const parentId = typeof p.parent_tool_use_id === "string" && p.parent_tool_use_id.length > 0
+      ? p.parent_tool_use_id
+      : undefined;
+    const parent = parentId ? { parentToolUseId: parentId } : {};
     switch (p.type) {
       // Assistant API message: content blocks → text / thinking / tool_use.
       case "assistant": {
@@ -321,12 +687,25 @@ export const claudeCodeSpec: CliAgentSpec = {
       // User API message: the CLI echoes tool results back as user content,
       // and injects `<task-notification>` blocks (background-task completion
       // evidence) as user TEXT — parsed into structure, never dropped and
-      // never forwarded raw. Other user text (the echo of the prompt, system
-      // reminders) stays unmapped: it is not agent output.
+      // never forwarded raw. TOP-LEVEL user text (the echo of the prompt,
+      // system reminders) stays unmapped: it is not agent output. SIDECHAIN
+      // user text (parent_tool_use_id present) is a message landing in a
+      // CHILD's thread — the delivered form of a SendMessage steer to a
+      // running subagent ("queued for delivery at its next tool round") —
+      // and forwards as `subagent_user_message` so the steer renders inside
+      // the child's mini-session instead of vanishing (task #97; before
+      // this, a queued steer was visible only as the parent's opaque
+      // SendMessage tool call).
       case "user": {
         const message = p.message as { content?: ClaudeContentBlock[] | string } | undefined;
+        // HARNESS-synthesized user messages (`isSynthetic` — e.g. a
+        // post-compaction continuation summary, including a CHILD's own)
+        // are never a delivered steer: suppress the steer arm, keep the
+        // notification parse. Structural marker only, same doctrine as the
+        // `<synthetic>` model stamp above.
+        const steerParent = p.isSynthetic === true ? undefined : parentId;
         if (typeof message?.content === "string") {
-          return parseTaskNotifications(message.content, ts);
+          return sidechainAwareUserText(message.content, steerParent, ts);
         }
         const blocks = Array.isArray(message?.content) ? message.content : [];
         return blocks.flatMap((b): AgentMessage[] => {
@@ -337,7 +716,7 @@ export const claudeCodeSpec: CliAgentSpec = {
             }];
           }
           if (b.type === "text" && typeof b.text === "string") {
-            return parseTaskNotifications(b.text, ts);
+            return sidechainAwareUserText(b.text, steerParent, ts);
           }
           return [];
         });
@@ -389,14 +768,21 @@ export const claudeCodeSpec: CliAgentSpec = {
         return [];
       }
       // Terminal result: usage on success (the text already streamed via the
-      // assistant events); an honest string error on failure.
+      // assistant events); an honest string error on failure. The turn
+      // totals are the main loop's `usage`; `modelUsage` (every model the
+      // query pipeline called, with the CLI's own cost estimate) and
+      // `total_cost_usd` ride beside them as the harness reported them —
+      // cumulative for the guest session (AgentMessageUsage.byModel).
       case "result": {
         if (p.is_error === true) {
           return [{ type: "error", text: formatError(p.result ?? p.subtype ?? p), timestamp: ts }];
         }
         const u = p.usage as Record<string, number> | undefined;
         if (!u) return [];
-        return [{
+        const byModel = parseModelUsage(p.modelUsage);
+        const costUsd = typeof p.total_cost_usd === "number" && Number.isFinite(p.total_cost_usd)
+          ? p.total_cost_usd : undefined;
+        const usage: AgentMessageUsage = {
           type: "usage",
           inputTokens: u.input_tokens ?? 0,
           outputTokens: u.output_tokens ?? 0,
@@ -404,17 +790,38 @@ export const claudeCodeSpec: CliAgentSpec = {
           cacheCreationTokens: u.cache_creation_input_tokens ?? 0,
           durationMs: typeof p.duration_ms === "number" ? p.duration_ms : 0,
           numTurns: typeof p.num_turns === "number" ? p.num_turns : 1,
+          ...(byModel !== undefined ? { byModel } : {}),
+          ...(costUsd !== undefined ? { costUsd } : {}),
           timestamp: ts,
-        }];
+        };
+        return [usage];
+      }
+      // The account's plan limits as the CLI read them off the response
+      // headers (subscription-funded sessions; parsePlanLimits above).
+      case "rate_limit_event": {
+        const limits = parsePlanLimits(p, ts);
+        return limits ? [limits] : [];
       }
       // System events: init carries the session id (extractSessionId), and
       // the background-task lane rides here too — `task_notification` is
       // the completion evidence stream-json actually emits (see the section
-      // header above), so it maps to the structured message BOTH turn
-      // engines persist. Everything else under system (task_started,
-      // task_updated, background_tasks_changed, thinking_tokens) is
-      // lifecycle noise here.
+      // header above), and `task_progress` the LIVE background-task feed
+      // (parseSystemTaskProgress): per-agent workflow entries for Workflow
+      // tasks, `workflow: []` heartbeats for plain background Agent tasks —
+      // both forward so the platform can declare the running task as
+      // session background work. Compaction rides here as well (the status
+      // pair + compact_boundary — parseSystemCompaction). Everything else
+      // under system (task_started, task_updated, background_tasks_changed,
+      // thinking_tokens) is lifecycle noise here.
       case "system": {
+        if (p.subtype === "task_progress") {
+          const progress = parseSystemTaskProgress(p, ts);
+          return progress ? [progress] : [];
+        }
+        if (p.subtype === "status" || p.subtype === "compact_boundary") {
+          const compaction = parseSystemCompaction(p, ts);
+          return compaction ? [compaction] : [];
+        }
         if (p.subtype !== "task_notification") return [];
         const notification = parseSystemTaskNotification(p, ts);
         return notification ? [notification] : [];

package/src/runtimes/claude.ts

@@ -1,4 +1,4 @@
-/** Claude Agent SDK runtime — replaces the old Claude CLI subprocess runtime. */
+/** Claude Agent SDK runtime. */
 
 import { query, type HookCallback, type PreToolUseHookInput, type SDKUserMessage, type ThinkingConfig } from "@anthropic-ai/claude-agent-sdk";
 import type { AgentMessage, ModelExecutionContract, RuntimeOptions, SandboxProvider, ToolCallGateResult } from "../index.js";