@moondeck/station 0.0.0-stage → 1.0.0

package/lib/agents/claude.ts

@@ -0,0 +1,918 @@
+/**
+ * ClaudeSession — a real AgentSession backed by the Claude Code CLI in
+ * stream-json mode, run inside the task environment (ADR-010).
+ *
+ *   claude --print --input-format stream-json --output-format stream-json \
+ *          --verbose --no-session-persistence
+ *
+ * The CLI is a persistent bidirectional process: uai writes one JSON
+ * line per user turn to stdin and reads a stream of JSON event lines
+ * from stdout. Same binary, same subscription auth as the TUI — not the
+ * paid API (docs/interaction-model.md).
+ *
+ * Protocol mapping lives in the pure `mapClaudeLine` function so it can
+ * be unit-tested against fixture lines without spawning anything.
+ *
+ * ⚠️ VERIFY-ON-MAC: the exact stream-json envelope — especially the
+ * permission/control-request shape — must be checked against the
+ * installed `claude` build. The mapping is isolated here precisely so
+ * those fixups stay in one place.
+ */
+
+import { requireContainerRuntimeOperational } from "../runtime-guard";
+import type { TaskEnvironmentAgentSessionSurface } from "../task-environment/types";
+import { newId } from "../ulid";
+import { createAgentTransport, type LineTransport } from "./transport";
+import { rateLimitErrorUsage, resetSecondsToEpochMs } from "./rate-limit";
+import { register } from "./registry";
+import { CLAUDE_MODELS } from "../../src/engine-models";
+import {
+  DISPATCH_INPUT_SCHEMA,
+  DISPATCH_RECIPIENT_ID_PATTERN,
+  DISPATCH_TOOL_NAME,
+  MAX_DISPATCH_INSTRUCTION_CHARS,
+  MAX_DISPATCH_RECIPIENT_ID_CHARS,
+  MAX_DISPATCH_RECIPIENTS,
+  parseDispatchInput,
+  type DispatchInput,
+} from "./dispatch";
+import { extractResultUsage } from "./usage";
+import type {
+  AgentEvent,
+  AgentEventHandler,
+  AgentAccountUsage,
+  AgentKind,
+  AgentSession,
+  RosterAgent,
+} from "./types";
+
+// Published Claude model aliases the CLI accepts via `--model`. The CLI
+// resolves these aliases to the current dated snapshots, so this list is
+// stable across point releases. UPDATE WHEN MODELS CHANGE (new family or a
+// retired alias). Order is display order in the cloud picker.
+// The model list is host-agent/src/engine-models.ts (CLAUDE_MODELS).
+
+// Opus ("opus" alias = Opus 4.8) stays the default; "fable" (Claude
+// Fable 5, the Mythos-class flagship) is opt-in per agent. Update
+// alongside CLAUDE_MODELS.
+const CLAUDE_DEFAULT_MODEL = "opus";
+
+// Reasoning levels passed through via `claude --effort <level>`. Taken from
+// the CLI's `--help`: `--effort <level>` accepts (low, medium, high, xhigh,
+// max). UPDATE WHEN THE CLI CHANGES its effort levels.
+const CLAUDE_EFFORTS = ["low", "medium", "high", "xhigh", "max"];
+
+// High is the default reasoning level. Update alongside CLAUDE_EFFORTS.
+const CLAUDE_DEFAULT_EFFORT = "high";
+
+// ADR-083: cheap defaults apply at the enforcement boundary as well as in the
+// picker. Explicit per-agent choices still win; an API client that omits them
+// must not accidentally run the communicator on Claude's costly account
+// defaults merely because it bypassed the web recommendation button.
+const CLAUDE_COMMUNICATOR_MODEL = "haiku";
+const CLAUDE_COMMUNICATOR_EFFORT = "low";
+
+/**
+ * ADR-083's one host-owned communicator tool. The server is deliberately
+ * dependency-free and rides in the adapter argv so an updated host can add it
+ * to an already-built task image. It performs no routing itself: Claude's
+ * structured tool_use block is the durable runner output, and ClaudeSession
+ * correlates its successful tool_result into the typed AgentEvent the
+ * orchestrator forwards.
+ *
+ * Keeping the MCP server a constant also keeps the strict config independent
+ * of project/user MCP files. The communicator gets exactly this server, never
+ * the task's arbitrary extension set.
+ */
+export const CLAUDE_DISPATCH_TOOL = `mcp__uai__${DISPATCH_TOOL_NAME}`;
+
+export const CLAUDE_DISPATCH_MCP_SOURCE = String.raw`
+import { createInterface } from "node:readline";
+
+const RECIPIENT_ID = new RegExp(${JSON.stringify(DISPATCH_RECIPIENT_ID_PATTERN)});
+
+const TOOL = {
+  name: "dispatch",
+  title: "Dispatch work to Moondeck crew agents",
+  description:
+    "Send one concrete instruction to one or more Moondeck crew agents. Use this instead of naming agents in prose; prose stays in the normal human-facing lane.",
+  inputSchema: ${JSON.stringify(DISPATCH_INPUT_SCHEMA)},
+};
+
+const write = (value) => process.stdout.write(JSON.stringify(value) + "\n");
+const ok = (id, result) => write({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) =>
+  write({ jsonrpc: "2.0", id, error: { code, message } });
+const validArguments = (value) =>
+  value &&
+  typeof value === "object" &&
+  !Array.isArray(value) &&
+  Array.isArray(value.recipients) &&
+  value.recipients.length > 0 &&
+  value.recipients.length <= ${MAX_DISPATCH_RECIPIENTS} &&
+  value.recipients.every(
+    (recipient) =>
+      typeof recipient === "string" &&
+      recipient.length <= ${MAX_DISPATCH_RECIPIENT_ID_CHARS} &&
+      RECIPIENT_ID.test(recipient),
+  ) &&
+  new Set(value.recipients).size === value.recipients.length &&
+  typeof value.instruction === "string" &&
+  value.instruction.trim().length > 0 &&
+  value.instruction.length <= ${MAX_DISPATCH_INSTRUCTION_CHARS};
+
+createInterface({ input: process.stdin, crlfDelay: Infinity }).on(
+  "line",
+  (line) => {
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (!message || typeof message !== "object" || !("id" in message)) return;
+    if (message.method === "initialize") {
+      ok(message.id, {
+        protocolVersion: message.params?.protocolVersion ?? "2025-06-18",
+        capabilities: { tools: {} },
+        serverInfo: { name: "uai-dispatch", version: "1" },
+      });
+      return;
+    }
+    if (message.method === "ping") {
+      ok(message.id, {});
+      return;
+    }
+    if (message.method === "tools/list") {
+      ok(message.id, { tools: [TOOL] });
+      return;
+    }
+    if (message.method === "tools/call") {
+      if (
+        message.params?.name !== "dispatch" ||
+        !validArguments(message.params?.arguments)
+      ) {
+        ok(message.id, {
+          content: [{ type: "text", text: "Dispatch rejected: provide 1-${MAX_DISPATCH_RECIPIENTS} unique recipient ids and a non-empty instruction." }],
+          isError: true,
+        });
+        return;
+      }
+      ok(message.id, {
+        content: [{ type: "text", text: "Dispatch request accepted by the host; Moondeck will validate recipients and delivery." }],
+      });
+      return;
+    }
+    fail(message.id, -32601, "Method not found");
+  },
+);
+`;
+
+const CLAUDE_DISPATCH_MCP_CONFIG = JSON.stringify({
+  mcpServers: {
+    uai: {
+      command: "node",
+      args: ["--input-type=module", "--eval", CLAUDE_DISPATCH_MCP_SOURCE],
+      // The trusted bridge needs no task/provider credentials. Override the
+      // secrets the host intentionally forwards to Claude instead of enabling
+      // Claude's global subprocess scrub, which hard-requires bubblewrap and
+      // makes the CLI abort in existing task images that do not contain it.
+      env: {
+        CLAUDE_CODE_OAUTH_TOKEN: "",
+        ANTHROPIC_API_KEY: "",
+        ANTHROPIC_AUTH_TOKEN: "",
+        UAI_TASK_TOKEN: "",
+      },
+      // Claude defers MCP schemas by default. Dispatch is a core action named
+      // in the preamble, so it must be connected and visible on prompt one.
+      alwaysLoad: true,
+    },
+  },
+});
+
+const CLAUDE_COMMUNICATOR_SETTINGS = JSON.stringify({
+  disableAllHooks: true,
+  enabledPlugins: {},
+});
+
+/**
+ * `--safe-mode` cannot be used here: Claude 2.1.220 disables even an explicit
+ * `--mcp-config` in safe mode, which makes the host-owned dispatch tool
+ * disappear. Recreate the customization lockdown while leaving that one
+ * strict MCP server available. These values override any agent/account env.
+ */
+const CLAUDE_COMMUNICATOR_ENV: Record<string, string> = {
+  CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
+  CLAUDE_CODE_DISABLE_BUNDLED_SKILLS: "1",
+  CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+  CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1",
+  CLAUDE_CODE_DISABLE_POLICY_SKILLS: "1",
+  CLAUDE_CODE_DISABLE_WORKFLOWS: "1",
+  CLAUDE_CODE_SKIP_PLUGIN_MCP_SERVERS: "1",
+  CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS: "1",
+  ENABLE_CLAUDEAI_MCP_SERVERS: "false",
+  // Some hosts export this globally. Claude's current implementation aborts
+  // when it is enabled but the task image has no bubblewrap binary.
+  CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: "",
+  // The enforced profile dispatches through its host-owned MCP event, not the
+  // task CLI. Keep the bearer token and API origin out of the Claude process
+  // itself (not merely its MCP child), where Read could otherwise inspect
+  // /proc/self/environ and recover a permission-null task credential.
+  UAI_TASK_TOKEN: "",
+  UAI_API_URL: "",
+};
+
+// ---------------------------------------------------------------------------
+// Pure protocol mapping — stream-json line → AgentEvent[].
+// ---------------------------------------------------------------------------
+
+/** Narrow an unknown to a plain object. */
+function isObj(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null;
+}
+
+function parseLineObject(raw: string): Record<string, unknown> | null {
+  try {
+    const value: unknown = JSON.parse(raw);
+    return isObj(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Map one stream-json stdout line to zero or more AgentEvents.
+ *
+ * Contract:
+ *   - `stream_event` content_block_delta(text) → `message_delta`
+ *   - `assistant` message tool_use blocks      → `tool_call`
+ *   - `result`                                 → `message_complete` + `turn_complete`
+ *   - control/permission request               → `permission_request`
+ *   - anything else                            → []  (ignored)
+ *
+ * A malformed line yields []. The mapper is intentionally total and
+ * side-effect free.
+ */
+export function mapClaudeLine(raw: string, now: number = Date.now()): AgentEvent[] {
+  const json = parseLineObject(raw);
+  if (!json) return [];
+
+  const type = json.type;
+
+  // Claude Code 2.1.306 emits this exact stream-json envelope. Its embedded
+  // schema defines reset timestamps as Unix seconds and utilization as a
+  // fraction (normally 0..1).
+  if (type === "rate_limit_event" && isObj(json.rate_limit_info)) {
+    const usage = mapClaudeRateLimitInfo(json.rate_limit_info, now);
+    return usage ? [{ type: "account_usage", usage }] : [];
+  }
+
+  // --- streaming text deltas --------------------------------------------
+  if (type === "stream_event" && isObj(json.event)) {
+    const event = json.event;
+    if (
+      event.type === "content_block_delta" &&
+      isObj(event.delta) &&
+      event.delta.type === "text_delta" &&
+      typeof event.delta.text === "string"
+    ) {
+      return [{ type: "message_delta", text: event.delta.text }];
+    }
+    return [];
+  }
+
+  // --- full assistant message: harvest tool calls -----------------------
+  if (type === "assistant" && isObj(json.message)) {
+    const content = json.message.content;
+    if (!Array.isArray(content)) return [];
+    const out: AgentEvent[] = [];
+    for (const block of content) {
+      if (isObj(block) && block.type === "tool_use") {
+        const name = typeof block.name === "string" ? block.name : "tool";
+        if (name === CLAUDE_DISPATCH_TOOL) {
+          // Dispatch is intentionally absent here. Claude emits this assistant
+          // block before it calls the MCP server; ClaudeSession correlates the
+          // later tool_result and emits only after the call succeeds.
+          continue;
+        }
+        out.push({
+          type: "tool_call",
+          id: typeof block.id === "string" ? block.id : newId(),
+          title: name,
+          detail: safeStringify(block.input),
+        });
+      }
+    }
+    return out;
+  }
+
+  // --- turn result ------------------------------------------------------
+  if (type === "result") {
+    const text = typeof json.result === "string" ? json.result : "";
+    const usage = extractResultUsage(json);
+    if (json.is_error === true) {
+      // An errored turn still cost tokens — meter it.
+      const message = text || "claude returned an error";
+      const accountUsage = rateLimitErrorUsage(message, now);
+      return [
+        ...(accountUsage
+          ? [{ type: "account_usage", usage: accountUsage } as const]
+          : []),
+        // ADR-076: a rate-limit/usage-cap error is failed over to another
+        // account by the orchestrator rather than surfaced to the user.
+        accountUsage
+          ? {
+              type: "error",
+              message,
+              retryable: "rate_limit",
+              ...(accountUsage.resetsAt === undefined
+                ? {}
+                : { resetsAt: accountUsage.resetsAt }),
+            }
+          : { type: "error", message },
+        { type: "turn_complete", usage },
+      ];
+    }
+    return [
+      { type: "message_complete", text },
+      { type: "turn_complete", usage },
+    ];
+  }
+
+  // --- permission / control request -------------------------------------
+  // ⚠️ VERIFY-ON-MAC: confirm this envelope against the real CLI.
+  if (type === "control_request" && isObj(json.request)) {
+    const req = json.request;
+    if (req.subtype === "can_use_tool") {
+      return [
+        {
+          type: "permission_request",
+          id: typeof json.request_id === "string" ? json.request_id : newId(),
+          title:
+            typeof req.tool_name === "string"
+              ? `Allow ${req.tool_name}?`
+              : "Permission requested",
+          detail: safeStringify(req.input),
+        },
+      ];
+    }
+    return [];
+  }
+
+  return [];
+}
+
+const CLAUDE_WINDOW_MINUTES: Readonly<Record<string, number>> = {
+  five_hour: 5 * 60,
+  seven_day: 7 * 24 * 60,
+  seven_day_opus: 7 * 24 * 60,
+  seven_day_sonnet: 7 * 24 * 60,
+  seven_day_overage_included: 7 * 24 * 60,
+};
+
+function utilizationPercent(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return undefined;
+  }
+  return Math.min(100, value * 100);
+}
+
+/** Map Claude Code 2.1.306's embedded `RateLimitInfo` schema. */
+export function mapClaudeRateLimitInfo(
+  info: Record<string, unknown>,
+  observedAt: number = Date.now(),
+): AgentAccountUsage | null {
+  const status =
+    info.status === "allowed"
+      ? "allowed"
+      : info.status === "allowed_warning"
+        ? "warning"
+        : info.status === "rejected"
+          ? "limited"
+          : null;
+  if (!status) return null;
+
+  const windows: AgentAccountUsage["windows"] = [];
+  const seen = new Set<string>();
+  if (isObj(info.unifiedWindows)) {
+    for (const window of [
+      "five_hour",
+      "seven_day",
+      "seven_day_overage_included",
+    ] as const) {
+      const value = info.unifiedWindows[window];
+      if (!isObj(value)) continue;
+      const usedPercent = utilizationPercent(value.utilization);
+      const resetsAt = resetSecondsToEpochMs(value.resetsAt, observedAt);
+      windows.push({
+        window,
+        windowMinutes: CLAUDE_WINDOW_MINUTES[window],
+        ...(usedPercent === undefined ? {} : { usedPercent }),
+        ...(resetsAt === undefined ? {} : { resetsAt }),
+      });
+      seen.add(window);
+    }
+  }
+
+  const rateLimitType =
+    typeof info.rateLimitType === "string" &&
+    info.rateLimitType.length > 0 &&
+    info.rateLimitType.length <= 64
+      ? info.rateLimitType
+      : undefined;
+  const resetsAt = resetSecondsToEpochMs(info.resetsAt, observedAt);
+  if (rateLimitType && !seen.has(rateLimitType)) {
+    const usedPercent = utilizationPercent(info.utilization);
+    windows.push({
+      window: rateLimitType,
+      ...(CLAUDE_WINDOW_MINUTES[rateLimitType] === undefined
+        ? {}
+        : { windowMinutes: CLAUDE_WINDOW_MINUTES[rateLimitType] }),
+      ...(usedPercent === undefined ? {} : { usedPercent }),
+      ...(resetsAt === undefined ? {} : { resetsAt }),
+    });
+  }
+
+  return {
+    status,
+    ...(resetsAt === undefined ? {} : { resetsAt }),
+    ...(typeof info.isUsingOverage === "boolean"
+      ? { usingOverage: info.isUsingOverage }
+      : {}),
+    windows,
+    source: "claude-rate-limit-event",
+    observedAt,
+    ...(rateLimitType === undefined
+      ? {}
+      : { coverage: { kind: "window" as const, window: rateLimitType } }),
+  };
+}
+
+function safeStringify(v: unknown): string {
+  if (v === undefined) return "";
+  if (typeof v === "string") return v;
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The session.
+// ---------------------------------------------------------------------------
+
+const CLAUDE_BASE_ARGS = [
+  "--print",
+  "--input-format",
+  "stream-json",
+  "--output-format",
+  "stream-json",
+  "--verbose",
+  // uai owns durable chat persistence. Claude Code's JSON transcript
+  // files are an implementation detail and can contain redacted
+  // thinking blocks. Replaying those from disk has caused Anthropic API
+  // 400s when a later turn sees a changed thinking block, so keep each
+  // managed stream-json process in-memory only.
+  "--no-session-persistence",
+];
+
+const CLAUDE_FULL_ACCESS_ARGS = [
+  ...CLAUDE_BASE_ARGS,
+  // Full tool access, no per-call prompts. Safe here precisely because
+  // a uai task runs in a throwaway, isolated container operating on a
+  // disposable worktree (ADR-001 / ADR-010) — the container *is* the
+  // sandbox. Without this, stream-json has no interactive approver and
+  // every Write/Bash silently self-denies.
+  "--dangerously-skip-permissions",
+  // MCP servers come from the uai-managed file, EXPLICITLY (ADR-057/061).
+  // Discovered project .mcp.json servers sit behind a per-server approval
+  // that headless --print can never answer ("⏸ Pending approval"), which
+  // silently loaded a stale subset. --mcp-config bypasses the approval
+  // gate; --strict-mcp-config keeps stray host-copied user configs out.
+  // setupMcpTaskConfig always writes this file (empty when no connections)
+  // before sessions spawn.
+  "--mcp-config",
+  "/workspace/.mcp.json",
+  "--strict-mcp-config",
+];
+
+/**
+ * ADR-157 Astronaut profile: the normal tool set, minus Claude Code's native
+ * subagents. An Astronaut's helpers must be crew agents the task can see and
+ * bill; a built-in Agent/Task subagent would run (and spend) outside the crew.
+ */
+const CLAUDE_ASTRONAUT_ARGS = [
+  ...CLAUDE_FULL_ACCESS_ARGS,
+  "--disallowedTools",
+  "Agent,Task",
+];
+
+/**
+ * ADR-083 communicator profile. This is deliberately an engine-level tool
+ * boundary, not prompt advice: setting sources, hooks, skills, workflows and
+ * plug-in MCP are suppressed; the explicit tool set contains no shell or
+ * mutation primitive; `dontAsk` denies anything outside it; and strict MCP
+ * exposes only Uai's host-owned dispatch tool.
+ */
+const CLAUDE_COMMUNICATOR_ARGS = [
+  ...CLAUDE_BASE_ARGS,
+  "--setting-sources",
+  "",
+  "--settings",
+  CLAUDE_COMMUNICATOR_SETTINGS,
+  "--disable-slash-commands",
+  "--no-chrome",
+  "--permission-mode",
+  "dontAsk",
+  "--tools",
+  "Read,Glob,Grep",
+  "--allowedTools",
+  CLAUDE_DISPATCH_TOOL,
+  "--disallowedTools",
+  "Bash,Edit,Write,NotebookEdit,Agent,Task,WebFetch,WebSearch",
+  "--mcp-config",
+  CLAUDE_DISPATCH_MCP_CONFIG,
+  "--strict-mcp-config",
+];
+
+export class ClaudeSession implements AgentSession {
+  readonly agentId: string;
+  readonly kind: AgentKind = "claude";
+
+  private readonly proc: LineTransport;
+  private readonly handlers = new Set<AgentEventHandler>();
+  private readonly pendingDispatches = new Map<string, DispatchInput>();
+  private readonly settledDispatches = new Set<string>();
+  private closed = false;
+  // Claude's `total_cost_usd` is CUMULATIVE across the persistent session
+  // process (ADR-061 keeps one claude alive across turns), so per-turn cost is
+  // the delta from the previous turn — otherwise summing turns over-counts
+  // wildly (live 2026-07-22: a 4-turn task billed ~4x). Token counts, by
+  // contrast, are per-turn already. A fresh CLI starts at zero; attaching an
+  // existing durable CLI restores its counter at the saved outbox checkpoint.
+  // Undefined means the bounded history could not prove a baseline: skip one
+  // estimate instead of rebilling the session's whole previous spend.
+  private lastCumulativeCostUsd: number | undefined = 0;
+  private costSessionId: string | undefined;
+  private readonly costBySession = new Map<string, number>();
+
+  constructor(args: {
+    taskId: string;
+    agent: RosterAgent;
+    environment: TaskEnvironmentAgentSessionSurface;
+    systemPreamble: string;
+    executionProfile?: "communicator" | "astronaut";
+    attachCompatibilityKey?: string;
+    agentEnv?: Record<string, string>;
+    claudeSettings?: Record<string, unknown>;
+  }) {
+    this.agentId = args.agent.id;
+
+    // The uai channel briefing (how to @-mention, the agent roster, the
+    // project's defaultPrompt) is passed as a real system prompt via
+    // `--append-system-prompt`, so it applies to every turn — not
+    // smuggled into the first user message.
+    const cliArgs = [
+      ...(args.executionProfile === "communicator"
+        ? CLAUDE_COMMUNICATOR_ARGS
+        : args.executionProfile === "astronaut"
+          ? CLAUDE_ASTRONAUT_ARGS
+          : CLAUDE_FULL_ACCESS_ARGS),
+    ];
+    if (args.claudeSettings) {
+      // Empty helper settings and fallbackModel override inherited values.
+      // Preserve native settings sources, including project hooks/plugins.
+      // Connection env separately pins routing with PROVIDER_MANAGED_BY_HOST.
+      const settings = {
+        ...(args.executionProfile === "communicator" ? JSON.parse(CLAUDE_COMMUNICATOR_SETTINGS) as Record<string, unknown> : {}),
+        ...args.claudeSettings,
+      };
+      cliArgs.push("--settings", JSON.stringify(settings));
+    }
+    if (process.env.UAI_CLAUDE_INCLUDE_PARTIAL_MESSAGES === "1") {
+      cliArgs.push("--include-partial-messages");
+    }
+    // Explicit task configuration wins; the communicator uses its declared
+    // fast/cheap defaults when the task left either choice unspecified.
+    const model =
+      args.agent.model ??
+      (args.executionProfile === "communicator"
+        ? CLAUDE_COMMUNICATOR_MODEL
+        : undefined);
+    if (model) {
+      cliArgs.push("--model", model);
+    }
+    const effort =
+      args.agent.effort ??
+      (args.executionProfile === "communicator"
+        ? CLAUDE_COMMUNICATOR_EFFORT
+        : undefined);
+    if (effort) {
+      cliArgs.push("--effort", effort);
+    }
+    if (args.systemPreamble.trim().length > 0) {
+      cliArgs.push("--append-system-prompt", args.systemPreamble);
+    }
+    // Forward host-resident Claude auth into the headless exec. Headless
+    // `--print` does NOT use the interactive subscription/keychain path, so
+    // it needs CLAUDE_CODE_OAUTH_TOKEN (from `claude setup-token`) or an
+    // API key. These live in the host-agent's env (never the cloud, ADR-015);
+    // only ones actually set are forwarded.
+    // ADR-061: durable by default — the CLI is owned by an in-container
+    // runner and survives host restarts (attach resumes it); legacy pipes
+    // behind UAI_DURABLE_SESSIONS=0. Claude is host-side stateless, so a
+    // live runner can be re-attached (allowAttach). A communicator profile is
+    // never attached, and the orchestrator also supplies a persisted policy
+    // compatibility key for normal-tools Secretaries. That second fence makes
+    // the reverse rolling upgrade safe: an old restricted runner cannot be
+    // inherited after the default policy changes back to normal tools.
+    this.proc = createAgentTransport({
+      taskId: args.taskId,
+      agentId: this.agentId,
+      environment: args.environment,
+      cli: "claude",
+      cliArgs,
+      passEnv: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+      explicitEnv:
+        args.executionProfile === "communicator"
+          ? { ...(args.agentEnv ?? {}), ...CLAUDE_COMMUNICATOR_ENV }
+          : (args.agentEnv ?? {}),
+      allowAttach: args.executionProfile !== "communicator",
+      attachCompatibilityKey: args.attachCompatibilityKey,
+      kind: "claude",
+      debugLabel: `claude:${this.agentId}`,
+      restoreProtocolState: {
+        accepts: (line) => {
+          const json = parseLineObject(line);
+          return json?.type === "result" && this.validCumulativeCost(json) !== undefined;
+        },
+        restore: (lines, complete) => {
+          this.lastCumulativeCostUsd = complete ? 0 : undefined;
+          this.costSessionId = undefined;
+          this.costBySession.clear();
+          for (const line of lines) {
+            const json = parseLineObject(line);
+            if (json) this.perTurnCost({ type: "turn_complete", usage: { costUsd: this.validCumulativeCost(json) } }, json);
+          }
+        },
+      },
+    });
+    this.proc.onLine((line) => {
+      for (const event of this.dispatchEventsForLine(line)) this.emit(event);
+      const json = parseLineObject(line);
+      for (const event of mapClaudeLine(line)) this.emit(this.perTurnCost(event, json));
+    });
+    this.proc.onExit((code) => {
+      if (this.closed) return;
+      const tail = this.proc.stderrTail.trim();
+      // Surface an error event when:
+      //   - the process exited non-zero, OR
+      //   - it exited 0 but stderr says "Claude configuration file not
+      //     found". That message means Claude silently bailed because
+      //     its config was unlinked (Docker Desktop macOS atomic-write
+      //     race). The orchestrator handles this by repairing the
+      //     config and respawning, but only if it sees the error event.
+      const configMissing =
+        /Claude configuration file not found/i.test(tail);
+      if (code !== 0 || configMissing) {
+        this.emit({
+          type: "error",
+          message:
+            `claude process exited (${code ?? "spawn failed"})` +
+            (tail
+              ? `:\n${tail}`
+              : " — no stderr. Is the claude CLI installed in the task container, and is the container running?"),
+        });
+      }
+      this.clearDispatches();
+      this.closed = true;
+      this.emit({ type: "exit", code: code ?? -1 });
+    });
+  }
+
+  onEvent(handler: AgentEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => this.handlers.delete(handler);
+  }
+
+  private emit(event: AgentEvent): void {
+    if (this.closed && event.type !== "exit") return;
+    for (const h of this.handlers) h(event);
+  }
+
+  /**
+   * Claude writes an assistant tool_use before invoking MCP, then a user
+   * tool_result carrying the same id. Waking crew on the first line would turn
+   * a rejected or failed tool call into real work, so hold validated input
+   * until the matching result succeeds. The settled set makes replayed output
+   * idempotent for the remainder of the turn.
+   */
+  private dispatchEventsForLine(raw: string): AgentEvent[] {
+    const json = parseLineObject(raw);
+    if (!json) return [];
+
+    if (json.type === "assistant" && isObj(json.message)) {
+      const content = json.message.content;
+      if (!Array.isArray(content)) return [];
+      for (const block of content) {
+        if (
+          !isObj(block) ||
+          block.type !== "tool_use" ||
+          block.name !== CLAUDE_DISPATCH_TOOL ||
+          typeof block.id !== "string" ||
+          this.settledDispatches.has(block.id)
+        ) {
+          continue;
+        }
+        const input = parseDispatchInput(block.input);
+        if (input) this.pendingDispatches.set(block.id, input);
+        else this.pendingDispatches.delete(block.id);
+      }
+      return [];
+    }
+
+    if (json.type === "user" && isObj(json.message)) {
+      const content = json.message.content;
+      if (!Array.isArray(content)) return [];
+      const events: AgentEvent[] = [];
+      for (const block of content) {
+        if (
+          !isObj(block) ||
+          block.type !== "tool_result" ||
+          typeof block.tool_use_id !== "string"
+        ) {
+          continue;
+        }
+        const pending = this.pendingDispatches.get(block.tool_use_id);
+        if (!pending) continue;
+        this.pendingDispatches.delete(block.tool_use_id);
+        this.settledDispatches.add(block.tool_use_id);
+        if (block.is_error !== true) {
+          events.push({
+            type: "dispatch",
+            dispatchId: block.tool_use_id,
+            ...pending,
+          });
+        }
+      }
+      return events;
+    }
+
+    if (json.type === "result") this.clearDispatches();
+    return [];
+  }
+
+  private clearDispatches(): void {
+    this.pendingDispatches.clear();
+    this.settledDispatches.clear();
+  }
+
+  private validCumulativeCost(json: Record<string, unknown>): number | undefined {
+    const cost = json.total_cost_usd;
+    // A synthetic crash result may carry zeroed counters. It cannot erase a
+    // prior baseline or make the following result rebill the whole session.
+    return typeof cost === "number" && Number.isFinite(cost) && cost >= 0 &&
+      !(cost === 0 && json.is_error === true) ? cost : undefined;
+  }
+
+  /** SDK streaming results carry session-cumulative estimated USD; usage
+   * tokens are per-turn. /clear, /reset and /new change session_id and reset
+   * cost even when the new counter already exceeds the old one. */
+  private perTurnCost(event: AgentEvent, json: Record<string, unknown> | null): AgentEvent {
+    if (event.type !== "turn_complete" || event.usage?.costUsd === undefined) {
+      return event;
+    }
+    const cumulative = json && this.validCumulativeCost(json);
+    const withoutCost = () => {
+      const { costUsd: _cost, ...usage } = event.usage!;
+      return { ...event, usage };
+    };
+    if (cumulative === null || cumulative === undefined) return withoutCost();
+    const sessionId = typeof json?.session_id === "string" ? json.session_id : undefined;
+    const previous = sessionId !== undefined && this.costBySession.has(sessionId)
+      ? this.costBySession.get(sessionId)
+      : sessionId !== undefined && this.costSessionId !== undefined && sessionId !== this.costSessionId
+        ? 0 : this.lastCumulativeCostUsd;
+    // A decreasing counter in the same identified session is stale/replayed
+    // output, not proof of a reset. Keep the last known baseline.
+    if (previous !== undefined && cumulative < previous && sessionId !== undefined && this.costBySession.has(sessionId)) {
+      return withoutCost();
+    }
+    this.lastCumulativeCostUsd = cumulative;
+    this.costSessionId = sessionId ?? this.costSessionId;
+    if (sessionId !== undefined) this.costBySession.set(sessionId, cumulative);
+    if (previous === undefined) return withoutCost();
+    const delta = cumulative - previous;
+    // Older result envelopes without session_id retain the counter-reset
+    // fallback; current SDK frames identify that boundary explicitly.
+    return {
+      ...event,
+      usage: { ...event.usage, costUsd: delta >= 0 ? delta : cumulative },
+    };
+  }
+
+  async send(text: string): Promise<void> {
+    if (this.closed) return;
+    // The transport can outlive the command that created it. Gate each new
+    // turn at its actual runner boundary, while still allowing interrupt and
+    // close traffic during runtime recovery.
+    requireContainerRuntimeOperational();
+    this.proc.writeLine({
+      type: "user",
+      message: { role: "user", content: text },
+    });
+  }
+
+  async interrupt(): Promise<void> {
+    if (this.closed) return;
+    // Claude Code's stream-json control channel: an `interrupt` control-request
+    // stops the in-flight turn (the SDK's ESC). Safe to send when idle — the
+    // CLI acks with a control_response we don't need to track.
+    // ⚠️ VERIFY-ON-MAC: confirm the control-request `interrupt` envelope.
+    this.proc.writeLine({
+      type: "control_request",
+      request_id: newId(),
+      request: { subtype: "interrupt" },
+    });
+  }
+
+  async resolvePermission(
+    requestId: string,
+    decision: "accept" | "decline",
+  ): Promise<void> {
+    if (this.closed) return;
+    // ⚠️ VERIFY-ON-MAC: confirm the control-response envelope.
+    this.proc.writeLine({
+      type: "control_response",
+      request_id: requestId,
+      response: {
+        subtype: "can_use_tool",
+        behavior: decision === "accept" ? "allow" : "deny",
+      },
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) {
+      await this.proc.close();
+      return;
+    }
+    this.closed = true;
+    this.clearDispatches();
+    await this.proc.close();
+    this.emit({ type: "exit", code: 0 });
+    this.handlers.clear();
+  }
+}
+
+// Register the Claude adapter at module load (ADR-021). The `--model`
+// pass-through above means `model` flows from the roster entry to the CLI.
+register({
+  kind: "claude",
+  label: "Claude",
+  supportedModels: () => [...CLAUDE_MODELS],
+  defaultModel: CLAUDE_DEFAULT_MODEL,
+  supportedEfforts: () => [...CLAUDE_EFFORTS],
+  defaultEffort: CLAUDE_DEFAULT_EFFORT,
+  executionProfiles: [
+    {
+      id: "communicator",
+      mechanism: "claude-explicit-tool-boundary-v2",
+      defaultModel: CLAUDE_COMMUNICATOR_MODEL,
+      defaultEffort: CLAUDE_COMMUNICATOR_EFFORT,
+    },
+    {
+      id: "astronaut",
+      mechanism: "claude-disallowed-agent-task-v1",
+    },
+  ],
+  // Usable only when a Claude credential is in the env (injected into task
+  // containers at task-up). Gates advertisement (ADR-044 P2).
+  available: () =>
+    Boolean(
+      process.env.CLAUDE_CODE_OAUTH_TOKEN ||
+        process.env.ANTHROPIC_API_KEY ||
+        process.env.ANTHROPIC_AUTH_TOKEN,
+    ),
+  create: async ({
+    taskId,
+    agent,
+    environment,
+    systemPreamble,
+    executionProfile,
+    attachCompatibilityKey,
+    agentEnv,
+    claudeSettings,
+  }) =>
+    new ClaudeSession({
+      taskId,
+      agent,
+      environment,
+      systemPreamble,
+      executionProfile,
+      attachCompatibilityKey,
+      agentEnv,
+      claudeSettings,
+    }),
+});