infraweaver 0.1.0

package/src/agents/claude.ts

@@ -0,0 +1,1588 @@
+/**
+ * Claude Code agent — secure harness around the `claude` CLI.
+ *
+ * mirrors the opencode harness's security model:
+ * - native exec tools (Bash, Monitor, REPL, Workflow) blocked via BOTH
+ *   --disallowedTools AND managed-settings.json `permissions.deny` (the agent
+ *   cannot shell out / run code outside the MCP shell). the managed-settings
+ *   deny is the authoritative, bypass-immune layer: `--disallowedTools` alone
+ *   (a `cliArg`-source deny) was observed to leak under
+ *   `--dangerously-skip-permissions`, surfacing a secret env marker via the
+ *   native Bash tool. managed-settings denies are `policySettings`-source,
+ *   highest precedence, and survive bypassPermissions mode.
+ * - managed-settings.json: filesystem sandbox — deny /proc, /sys reads
+ * - MCP ShellTool provides restricted shell (filtered env, no secrets)
+ * - MCP server injected via --mcp-config (not replacing project config)
+ * - ASKPASS handles git auth separately (token never in subprocess env)
+ *
+ * the agent process itself gets full env (needs LLM API keys, PATH, etc.).
+ * security is enforced at the tool layer, not the process layer.
+ */
+import { execFileSync } from "node:child_process";
+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { performance } from "node:perf_hooks";
+import { setTimeout as sleep } from "node:timers/promises";
+import {
+  buildClaudePretoolGateSettings,
+  buildClaudePretoolGateSource,
+  CLAUDE_PRETOOL_GATE_FILENAME,
+} from "#app/agents/claudePretoolGate";
+import { startGateServer } from "#app/agents/gateServer";
+import {
+  GIT_NATIVE_READ_DENY_CLAUDE,
+  GIT_NATIVE_WRITE_DENY_CLAUDE,
+  harnessTmpdirWriteDenyClaude,
+  runnerHomeWriteDenyClaude,
+} from "#app/agents/nativeFsDenies";
+import { finalizeAgentResult } from "#app/agents/postRun";
+import {
+  REVIEWER_AGENT_NAME,
+  REVIEWER_SYSTEM_PROMPT,
+} from "#app/agents/reviewer";
+import { writePolicyPath } from "#app/agents/writePolicy";
+import type { DispatchRecorder } from "#app/agents/dispatchMetrics";
+import {
+  formatWithLabel,
+  ORCHESTRATOR_LABEL,
+  SessionLabeler,
+} from "#app/agents/sessionLabeler";
+import {
+  type AgentResult,
+  type AgentRunContext,
+  type AgentUsage,
+  agent,
+  agentHomeEnv,
+  baseAgentEnv,
+  buildAgentUsage,
+  logTokenTable,
+  mergeAgentUsage,
+  MAX_STDERR_LINES,
+  MCP_SERVER_TOKEN_ENV,
+} from "#app/agents/shared";
+import {
+  type RunTokenQuota,
+  TokenQuotaExceededError,
+} from "#app/agents/tokenQuota";
+import { PRODUCT_NAME } from "#app/brand";
+import { infraweaverMcpName } from "#app/external";
+import {
+  BEDROCK_MODEL_ID_ENV,
+  isBedrockAnthropicId,
+  isVertexAnthropicId,
+  VERTEX_MODEL_ID_ENV,
+} from "#app/models";
+import {
+  AGENT_ACTIVITY_TIMEOUT_MS,
+  getIdleMs,
+  markActivity,
+} from "#app/utils/activity";
+import { preflightClaudeSubscription } from "#app/utils/claudeSubscription";
+import { formatJsonValue, log } from "#app/utils/cli";
+import { installFromNpmTarball } from "#app/utils/install";
+import { findProviderErrorMatch } from "#app/utils/providerErrors";
+import { installBundledSkills } from "#app/utils/skills";
+import {
+  DEFAULT_MAX_RETAINED_BYTES,
+  SPAWN_ACTIVITY_TIMEOUT_CODE,
+  SpawnTimeoutError,
+  spawn,
+  TailBuffer,
+} from "#app/utils/subprocess";
+import {
+  OPENTOFU_MCP_SERVER_NAME,
+  resolveOpenTofuMcp,
+} from "#app/utils/opentofuMcp";
+import {
+  resolveTerraformMcp,
+  TERRAFORM_MCP_SERVER_NAME,
+} from "#app/utils/terraformMcp";
+import { ThinkingTimer } from "#app/utils/timer";
+import type { TodoTracker } from "#app/utils/todoTracking";
+import { getDevDependencyVersion } from "#app/utils/version";
+import { applyClaudeVertexEnv } from "#app/utils/vertex";
+
+async function installClaudeCli(): Promise<string> {
+  return await installFromNpmTarball({
+    packageName: "@anthropic-ai/claude-code",
+    version: getDevDependencyVersion("@anthropic-ai/claude-code"),
+    // 2.1.113+ ships a native binary (bin/claude.exe) instead of cli.js; the
+    // package postinstall copies it from the platform optionalDependency, so we
+    // need installDependencies to run that postinstall.
+    executablePath: "bin/claude.exe",
+    installDependencies: true,
+  });
+}
+
+/**
+ * Native claude-code tools that execute arbitrary shell/code and therefore
+ * bypass Infraweaver's security boundary (the restricted MCP `shell` tool with a
+ * filtered, secret-free env). These run inside the agent process with full env,
+ * so leaving any of them enabled defeats both `shell: "disabled"` AND the
+ * env-filtering that the MCP shell relies on even when shell is enabled.
+ *
+ * As of claude-code 2.1.150 the exec surface is no longer just `Bash`:
+ *   - `Monitor` runs a shell command/script (the `command` field)
+ *   - `REPL` runs arbitrary JavaScript (can `require("node:child_process")`)
+ *   - `Workflow` orchestrates subagents/pipelines that can reach the above
+ * Each is denied at top level and inside `Agent(...)` (Task subagents), mirroring
+ * the existing `Bash` / `Agent(Bash)` pair. Denying a tool that isn't registered
+ * in a given run is a harmless no-op, so this list is also forward-safe.
+ *
+ * `CLAUDE_EXEC_TOOL_DENY_RULES` is wired into TWO surfaces: `--disallowedTools`
+ * (removes the tools from the advertised list) and managed-settings.json
+ * `permissions.deny` (the authoritative, bypass-immune deny — see
+ * buildManagedSettings). The flag alone proved insufficient: under
+ * `--dangerously-skip-permissions` the native Bash tool ran despite
+ * `--disallowedTools Bash`, leaking a per-run secret marker.
+ */
+const CLAUDE_EXEC_TOOLS = ["Bash", "Monitor", "REPL", "Workflow"] as const;
+export const CLAUDE_EXEC_TOOL_DENY_RULES = [
+  ...CLAUDE_EXEC_TOOLS,
+  ...CLAUDE_EXEC_TOOLS.map((t) => `Agent(${t})`),
+];
+const CLAUDE_DISALLOWED_TOOLS = CLAUDE_EXEC_TOOL_DENY_RULES.join(",");
+
+// ── config ─────────────────────────────────────────────────────────────────────
+
+// Claude Code expands `${VAR}` in .mcp.json values, including HTTP-server
+// `headers` (code.claude.com/docs/en/mcp-configuration "Environment variable
+// expansion"), so the on-disk mcp.json carries only this placeholder — never the
+// raw token, which travels via MCP_SERVER_TOKEN_ENV on the agent's spawn env.
+const INFRAWEAVER_MCP_AUTH_HEADER = `Bearer \${${MCP_SERVER_TOKEN_ENV}}`;
+
+export function writeMcpConfig(ctx: AgentRunContext): string {
+  const configDir = join(ctx.tmpdir, ".claude");
+  mkdirSync(configDir, { recursive: true });
+  const configPath = join(configDir, "mcp.json");
+  // opt-in second server: HashiCorp's terraform-mcp-server (registry
+  // toolset, docker stdio) for live module/provider knowledge.
+  const terraformMcp = resolveTerraformMcp(ctx.payload);
+  if (terraformMcp.kind === "docker_missing")
+    log.info(`» ${terraformMcp.note}`);
+  // opt-in sibling: the OpenTofu registry MCP server (hosted HTTP, no docker) —
+  // OpenTofu Registry knowledge for an OpenTofu-first repo.
+  const opentofuMcp = resolveOpenTofuMcp(ctx.payload);
+  writeFileSync(
+    configPath,
+    JSON.stringify({
+      mcpServers: {
+        [infraweaverMcpName]: {
+          type: "http",
+          url: ctx.mcpServerUrl,
+          headers: { Authorization: INFRAWEAVER_MCP_AUTH_HEADER },
+        },
+        ...(terraformMcp.kind === "available"
+          ? {
+              [TERRAFORM_MCP_SERVER_NAME]: {
+                type: "stdio",
+                command: terraformMcp.command,
+                args: terraformMcp.args,
+              },
+            }
+          : {}),
+        ...(opentofuMcp.kind === "available"
+          ? {
+              [OPENTOFU_MCP_SERVER_NAME]: {
+                type: "http",
+                url: opentofuMcp.url,
+              },
+            }
+          : {}),
+      },
+    }),
+  );
+  return configPath;
+}
+
+/**
+ * Drop the PreToolUse gate script + its `--settings` JSON into the per-run
+ * tmpdir and return the absolute path to the settings file. The script
+ * blocks state-mutating MCP tool calls when `agent_id` is non-empty (i.e.,
+ * the call originates inside a Task/Agent subagent dispatch). See
+ * action/agents/claudePretoolGate.ts for the contract.
+ *
+ * Two paths register the gate:
+ *   1. flag settings (`--settings <path>`) — covers non-CI runs (`pnpm dev:run`,
+ *      local dev) where `installManagedSettings` is a no-op.
+ *   2. managed settings (/etc/claude-code/managed-settings.json) — covers CI,
+ *      where `allowManagedHooksOnly: true` filters flag-settings hooks. The
+ *      same hook entry is embedded in `buildManagedSettings` below.
+ *
+ * The flag settings also carry the native exec-tool `permissions.deny`
+ * (via `buildClaudePretoolGateSettings`) so non-CI runs (where managed
+ * settings are absent) still block native Bash et al. at a settings-source
+ * deny, not just the `--disallowedTools` cliArg deny that proved leaky under
+ * `--dangerously-skip-permissions`.
+ */
+function writePretoolGateAssets(
+  ctx: AgentRunContext,
+  stopHookPath?: string,
+): {
+  scriptPath: string;
+  settingsPath: string;
+} {
+  const scriptPath = join(ctx.tmpdir, CLAUDE_PRETOOL_GATE_FILENAME);
+  writeFileSync(
+    scriptPath,
+    buildClaudePretoolGateSource(
+      ctx.subagentDeniedTools,
+      writePolicyPath(ctx.tmpdir),
+    ),
+  );
+  chmodSync(scriptPath, 0o755);
+  const settingsPath = join(ctx.tmpdir, "infraweaver-claude-settings.json");
+  const settings = buildClaudePretoolGateSettings(
+    scriptPath,
+    CLAUDE_EXEC_TOOL_DENY_RULES,
+  );
+  // the harness-owned tmpdir files (this gate script, the Stop hook, the
+  // write-policy JSON) are executed/re-read during the run, so a native write
+  // to any of them is command execution — deny in the flag settings too so
+  // non-CI runs (no managed settings) carry the same fence.
+  settings.permissions.deny.push(...harnessTmpdirWriteDenyClaude(ctx.tmpdir));
+  if (stopHookPath) {
+    // register the Stop hook here as well as in managed settings: in CI
+    // `allowManagedHooksOnly` filters this flag-settings copy (no double
+    // fire), while non-CI runs — where managed settings are never installed —
+    // otherwise have no Stop hook at all, making gate retries and reflection
+    // dead locally while finalizeAgentResult still hard-fails on their
+    // absence.
+    (settings.hooks as Record<string, unknown>).Stop = [
+      { hooks: [{ type: "command", command: stopHookPath }] },
+    ];
+  }
+  writeFileSync(settingsPath, JSON.stringify(settings));
+  return { scriptPath, settingsPath };
+}
+
+/**
+ * Build the `--agents` JSON definition for the `loupe` subagent.
+ *
+ * The Claude Code path always runs against an Anthropic model (see
+ * resolveAgent), so we hardcode the cheaper-sibling downshift: lenses run
+ * on Sonnet, the orchestrator stays on whatever model `--model` was passed.
+ *
+ * Per-call model override is also possible (Task tool's `model` arg accepts
+ * 'sonnet' | 'opus' | 'haiku') and takes precedence over what's set here —
+ * we don't pass it; the per-subagent `model` field is the right default.
+ *
+ * The `model` is route-aware: the bare Anthropic-API id `claude-sonnet-5`
+ * is only valid on the direct API. On Bedrock (`eu.anthropic.…`) and Vertex
+ * (`@`-versioned) routes that id is rejected, and claude-code does not
+ * translate per-agent model names — so on those routes we omit `model`
+ * entirely and the lens inherits the orchestrator's (already valid) model.
+ *
+ * Kept in lockstep with the `claude-sonnet` alias in models.ts (the opencode
+ * path derives the same target via deriveSubagentModels); bump both together.
+ *
+ * The non-mutative + non-recursive contract is enforced by the prose system
+ * prompt baked into the agent — see action/agents/reviewer.ts for why we
+ * no longer wire per-agent `disallowedTools` here.
+ */
+export function buildAgentsJson(routeAware?: {
+  isBedrock: boolean;
+  isVertex: boolean;
+}): string {
+  const inheritOrchestratorModel =
+    routeAware?.isBedrock || routeAware?.isVertex;
+  const agents = {
+    [REVIEWER_AGENT_NAME]: {
+      description:
+        "Read-only review subagent for lens-based code review (correctness, security, billing-subsystem, etc.). " +
+        "Reads only — no writes, no state-changing shell or MCP calls, no nested subagent dispatch.",
+      prompt: REVIEWER_SYSTEM_PROMPT,
+      // omit on non-direct-API routes so the id can't be rejected by the provider.
+      ...(inheritOrchestratorModel ? {} : { model: "claude-sonnet-5" }),
+    },
+  };
+  return JSON.stringify(agents);
+}
+
+// ── model helpers ─────────────────────────────────────────────────────────────
+
+// claude CLI expects bare model names (e.g. "claude-sonnet-5"), not provider-prefixed specifiers
+export function stripProviderPrefix(specifier: string): string {
+  const slashIndex = specifier.indexOf("/");
+  return slashIndex > 0 ? specifier.slice(slashIndex + 1) : specifier;
+}
+
+// `high` is the model's tuned default ("equivalent to not setting the parameter"
+// per Anthropic docs). `max` is "absolute maximum capability with no constraints
+// on token spending" — meaningfully slower and burns more thinking budget per
+// turn. We default everyone to `high`; PRs that genuinely need full-send can
+// opt in via a future per-run override rather than paying the wall-time cost on
+// every Opus run.
+function resolveEffort(_model: string | undefined): "high" {
+  return "high";
+}
+
+// ── NDJSON event types ─────────────────────────────────────────────────────────
+
+interface ContentBlock {
+  type: string;
+  text?: string;
+  id?: string;
+  name?: string;
+  input?: unknown;
+  tool_use_id?: string;
+  content?: string | unknown;
+  is_error?: boolean;
+  [key: string]: unknown;
+}
+
+// SDK schema (per claude-agent-sdk docs) puts `session_id` and
+// `parent_tool_use_id` at the top level of every Assistant/User/System/Result
+// message, not inside `message`. Subagent events carry a non-null
+// `parent_tool_use_id` pointing at the orchestrator's Task/Agent tool_use id.
+interface ClaudeSystemEvent {
+  type: "system";
+  session_id?: string;
+  parent_tool_use_id?: string | null;
+  [key: string]: unknown;
+}
+
+interface ClaudeAssistantEvent {
+  type: "assistant";
+  session_id?: string;
+  parent_tool_use_id?: string | null;
+  message?: {
+    role?: string;
+    content?: ContentBlock[];
+    model?: string;
+    usage?: {
+      input_tokens?: number;
+      output_tokens?: number;
+      cache_creation_input_tokens?: number;
+      cache_read_input_tokens?: number;
+    };
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+interface ClaudeUserEvent {
+  type: "user";
+  session_id?: string;
+  parent_tool_use_id?: string | null;
+  message?: {
+    role?: string;
+    content?: ContentBlock[];
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+}
+
+interface ClaudeResultEvent {
+  type: "result";
+  subtype?: string;
+  // claude CLI sets `is_error: true` (alongside `subtype: "success"`) when
+  // an upstream provider fails mid-stream. `api_error_status` carries the
+  // provider HTTP status (e.g. 401 for invalid API key). per the official
+  // SDK types, `api_error_status` is `number | null`, and the `error_*`
+  // subtypes carry their actionable payload in `errors: string[]` instead
+  // of `result`.
+  is_error?: boolean;
+  api_error_status?: number | null;
+  errors?: string[];
+  result?: string;
+  session_id?: string;
+  num_turns?: number;
+  total_cost_usd?: number;
+  total_input_tokens?: number;
+  total_output_tokens?: number;
+  usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+  };
+  [key: string]: unknown;
+}
+
+// additional event types emitted by Claude CLI (handled as no-ops / debug)
+interface ClaudeStreamEvent {
+  type: "stream_event";
+  [key: string]: unknown;
+}
+interface ClaudeToolProgressEvent {
+  type: "tool_progress";
+  [key: string]: unknown;
+}
+interface ClaudeToolUseSummaryEvent {
+  type: "tool_use_summary";
+  [key: string]: unknown;
+}
+interface ClaudeAuthStatusEvent {
+  type: "auth_status";
+  [key: string]: unknown;
+}
+
+type ClaudeEvent =
+  | ClaudeSystemEvent
+  | ClaudeAssistantEvent
+  | ClaudeUserEvent
+  | ClaudeResultEvent
+  | ClaudeStreamEvent
+  | ClaudeToolProgressEvent
+  | ClaudeToolUseSummaryEvent
+  | ClaudeAuthStatusEvent;
+
+// ── runner ──────────────────────────────────────────────────────────────────────
+
+type RunParams = {
+  label: string;
+  cmd: string;
+  args: string[];
+  cwd: string;
+  env: Record<string, string | undefined>;
+  todoTracker?: TodoTracker | undefined;
+  onActivityTimeout?: (() => void) | undefined;
+  onToolUse?:
+    | ((event: { toolName: string; input: unknown }) => void)
+    | undefined;
+  /** per-run token ceiling (LLM10). `label` is the accumulator's source key, so
+   *  a `--resume` retry is charged on top of the attempt it resumes rather than
+   *  replacing it. Absent → nothing to enforce. */
+  tokenQuota?: RunTokenQuota | undefined;
+  /** specialist-routing watch (agents/dispatchMetrics.ts). Passed as the bare
+   *  recorder rather than the whole `toolState` — this runner drives a
+   *  subprocess and has no business reading run state it cannot act on.
+   *  Optional for the same reason `tokenQuota` is: subagent and test call sites
+   *  have nothing to record. */
+  dispatchMetrics?: DispatchRecorder | undefined;
+};
+
+type ClaudeRunResult = AgentResult & {
+  sessionId?: string | undefined;
+  /** set when the failure was a synthetic-stop with a retryable provider
+   * status — the session is intact and worth a `--resume` retry. */
+  retryableTransient?: boolean | undefined;
+};
+
+/**
+ * Provider statuses worth a resume-retry: rate limit (429) and upstream 5xx
+ * (500–599, which includes Anthropic's 529 "overloaded"). Deterministic
+ * failures (401 auth, 400 validation) are excluded — resuming would just
+ * replay the same error at full cost.
+ */
+export function isRetryableApiStatus(
+  status: number | null | undefined,
+): boolean {
+  if (typeof status !== "number") return false;
+  return status === 429 || (status >= 500 && status < 600);
+}
+
+/**
+ * Backoff schedule for transient-failure resume retries (one entry per
+ * retry). Bounded at two: a blip clears within seconds; anything that
+ * survives ~20s of backoff is an outage the run cannot wait out.
+ */
+const TRANSIENT_RESUME_RETRY_DELAYS_MS: readonly number[] = [5_000, 15_000];
+
+/**
+ * Continue prompt for a `--resume` retry after a transient provider failure.
+ * The interrupted turn's tail may or may not have been applied server-side,
+ * so the prompt asks the model to re-check before repeating its last action.
+ */
+export const TRANSIENT_RESUME_PROMPT =
+  "SESSION INTERRUPTED — the previous turn was cut short by a transient provider error (rate limit or upstream outage), not by anything you did. " +
+  "Continue the task from where you left off. Re-check the result of your last action before repeating it — it may or may not have completed.";
+
+/**
+ * Return the tail of `text` capped at `maxCodeUnits` UTF-16 code units,
+ * dropping any partial first line. used in the exit-non-zero stdout fallback
+ * so we never surface a truncated NDJSON event to operators —
+ * `result.stdout.slice(-2048)` would otherwise cut mid-line and produce a
+ * syntactically broken JSON fragment. code units rather than bytes because
+ * `String.prototype.slice` operates on UTF-16 units; for multi-byte UTF-8
+ * content the effective byte budget can be up to 4× the nominal limit.
+ */
+export function tailLines(text: string, maxCodeUnits: number): string {
+  if (text.length <= maxCodeUnits) return text;
+  const tail = text.slice(-maxCodeUnits);
+  const firstNewline = tail.indexOf("\n");
+  // if no newline in window or it's at the very start, return as-is;
+  // otherwise drop the partial first line.
+  return firstNewline > 0 && firstNewline < tail.length - 1
+    ? tail.slice(firstNewline + 1)
+    : tail;
+}
+
+/** Monotonic id so each `runClaude` invocation charges the quota under its own
+ *  source key. Process-local and never persisted — see `quotaSource` below. */
+let quotaSourceCounter = 0;
+function nextQuotaSourceId(): number {
+  quotaSourceCounter += 1;
+  return quotaSourceCounter;
+}
+
+export async function runClaude(params: RunParams): Promise<ClaudeRunResult> {
+  const startTime = performance.now();
+  let eventCount = 0;
+
+  // per-session labeler so parallel subagent log lines can be differentiated.
+  // claude-agent-sdk runs subagents inside the orchestrator's session — they
+  // share `session_id` — and stamps every subagent message with a non-null
+  // `parent_tool_use_id` pointing at the Agent tool_use that spawned them.
+  // we bind each Agent tool_use id to its dispatched label up front, then
+  // labelFor short-circuits to the direct mapping when parent_tool_use_id is
+  // set. orchestrator events (parent_tool_use_id === null) flow through the
+  // sessionID path and bind to ORCHESTRATOR_LABEL on first sighting.
+  const labeler = new SessionLabeler();
+  function eventLabel(event: {
+    session_id?: string;
+    parent_tool_use_id?: string | null;
+  }): string {
+    return labeler.labelFor(
+      event.session_id ?? null,
+      event.parent_tool_use_id ?? null,
+    );
+  }
+  function withLabel(label: string, message: string): string {
+    return label === ORCHESTRATOR_LABEL
+      ? message
+      : formatWithLabel(label, message);
+  }
+
+  // one ThinkingTimer per session — sharing a single timer across sessions
+  // conflated cross-session interleaving as parent thinking time. each timer
+  // formats its log lines through the session label so attribution is visible.
+  const thinkingTimers = new Map<string, ThinkingTimer>();
+  function timerFor(label: string): ThinkingTimer {
+    let t = thinkingTimers.get(label);
+    if (!t) {
+      const formatLine = (line: string) =>
+        label === ORCHESTRATOR_LABEL ? line : formatWithLabel(label, line);
+      t = new ThinkingTimer(formatLine);
+      thinkingTimers.set(label, t);
+    }
+    return t;
+  }
+
+  let finalOutput = "";
+  let sessionId: string | undefined;
+  let resultErrorSubtype: string | null = null;
+  // captures the structured error string from a result event with
+  // `is_error: true` (e.g. mid-stream provider auth failures the CLI
+  // surfaces as `subtype: "success"` synthetic-stop events, or the
+  // `errors[]` array from `error_*` subtypes). preferred over raw
+  // stdout/stderr in the exit-non-zero path so the GitHub Actions
+  // `##[error]` line shows the actionable message instead of an 8KB+
+  // NDJSON dump.
+  let lastResultError: string | null = null;
+  // set only for synthetic-stop `subtype: "success"` + `is_error: true`
+  // events, where `accumulatedTokens` from prior `assistant` events is
+  // stale and logging it would mislead operators into thinking billable
+  // tokens were spent on a successful turn. deliberately NOT set for
+  // `error_max_turns` / `error_during_execution` / `error_*` subtypes
+  // because those runs genuinely consumed tokens and operators need
+  // billing visibility for them.
+  let syntheticStopFailure = false;
+  // provider HTTP status from the synthetic-stop result event, used to decide
+  // whether the failure is worth a `--resume` retry (see isRetryableApiStatus).
+  let lastApiErrorStatus: number | null = null;
+  let accumulatedTokens = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  // Claude CLI reports a single end-of-run `total_cost_usd` on the result
+  // event. per-message events don't carry cost, so there's nothing to sum —
+  // we just capture the final value when it arrives.
+  let accumulatedCostUsd = 0;
+  let tokensLogged = false;
+
+  // LLM10. The activity watchdog bounds silence; a remediation loop that keeps
+  // emitting tokens is never silent, so it needs its own bound. Aborting the
+  // spawn is what actually stops consumption — returning a flag would let the
+  // CLI keep burning tokens until it happened to finish.
+  const quotaAbort = new AbortController();
+  // The source key must be unique PER INVOCATION, not per label: a `--resume`
+  // retry reuses the label but starts a fresh accumulator from zero, and the
+  // quota charges only increases — so a shared key would make every retry's
+  // tokens free until it happened to exceed the previous attempt's total.
+  const quotaSource = `${params.label}#${nextQuotaSourceId()}`;
+  function chargeTokenQuota(): void {
+    const quota = params.tokenQuota;
+    if (!quota || quotaAbort.signal.aborted) return;
+    if (!quota.observe(quotaSource, accumulatedTokens)) return;
+    log.info(`» ${params.label}: ${quota.gap()}`);
+    quotaAbort.abort(new TokenQuotaExceededError(quota.gap()));
+  }
+
+  function buildUsage(): AgentUsage | undefined {
+    return buildAgentUsage({
+      agent: "claude",
+      input: accumulatedTokens.input,
+      output: accumulatedTokens.output,
+      cacheRead: accumulatedTokens.cacheRead,
+      cacheWrite: accumulatedTokens.cacheWrite,
+      costUsd: accumulatedCostUsd,
+    });
+  }
+
+  const handlers = {
+    system: (event: ClaudeSystemEvent) => {
+      // claude-agent-sdk only emits system:init for the top-level query, so
+      // this binds the orchestrator label and never appears in subagent flow.
+      // we still route through eventLabel so a subagent system event (if the
+      // SDK ever adds one) wouldn't go silently misattributed.
+      const label = eventLabel(event);
+      log.debug(withLabel(label, `» ${params.label} system event`));
+    },
+    assistant: (event: ClaudeAssistantEvent) => {
+      const content = event.message?.content;
+      if (!content) return;
+
+      const label = eventLabel(event);
+      const boxTitle =
+        label === ORCHESTRATOR_LABEL
+          ? params.label
+          : `${params.label} [${label}]`;
+
+      for (const block of content) {
+        if (block.type === "text" && block.text?.trim()) {
+          const message = block.text.trim();
+          log.box(message, { title: boxTitle });
+          // only the orchestrator's text becomes the run's "output" — subagent
+          // report-back text would otherwise clobber the parent's final answer.
+          if (label === ORCHESTRATOR_LABEL) {
+            finalOutput = message;
+          }
+        } else if (block.type === "tool_use") {
+          const toolName = block.name || "unknown";
+          // only the orchestrator's tool calls feed the diff-coverage tracker —
+          // a specialist subagent reading the diff cannot satisfy the primary
+          // reviewer's coverage obligation. Matches the opencode path's
+          // `isOrchestrator` gate on ctx.onToolUse.
+          if (params.onToolUse && label === ORCHESTRATOR_LABEL) {
+            params.onToolUse({
+              toolName,
+              input: block.input,
+            });
+          }
+          timerFor(label).markToolCall();
+          const inputFormatted = formatJsonValue(block.input || {});
+          const toolCallLine =
+            inputFormatted !== "{}"
+              ? `» ${toolName}(${inputFormatted})`
+              : `» ${toolName}()`;
+          log.info(withLabel(label, toolCallLine));
+
+          // when the orchestrator dispatches a subagent, bind the Agent
+          // tool_use id to the dispatched label so future events carrying
+          // `parent_tool_use_id === block.id` resolve directly to the right
+          // lens. v2.1.63+ renamed the tool to "Agent"; older versions
+          // emitted "Task". match both for forward-compat.
+          if (
+            (toolName === "Task" || toolName === "Agent") &&
+            block.input &&
+            typeof block.input === "object"
+          ) {
+            const taskInput = block.input as {
+              description?: string;
+              subagent_type?: string;
+              prompt?: string;
+            };
+            const dispatchedLabel = labeler.recordTaskDispatch(
+              taskInput,
+              block.id ?? null,
+            );
+            // the specialist-routing watch. counted here, at the Task call, not
+            // at completion: a dispatch that errors out still cost the routing
+            // decision and usually the tokens. See agents/dispatchMetrics.ts.
+            params.dispatchMetrics?.recordDispatch(dispatchedLabel);
+            log.info(
+              withLabel(
+                label,
+                `» dispatching subagent: ${dispatchedLabel}` +
+                  (taskInput.subagent_type
+                    ? ` (subagent_type=${taskInput.subagent_type})`
+                    : ""),
+              ),
+            );
+          }
+
+          // agent's explicit MCP report_progress takes priority over todo tracking
+          if (toolName.includes("report_progress") && params.todoTracker) {
+            log.debug("» report_progress detected, disabling todo tracking");
+            params.todoTracker.cancel();
+          }
+
+          // parse TodoWrite events for live progress tracking. only honor the
+          // orchestrator's todos — subagents emit their own todo lists which
+          // would otherwise clobber the visible progress comment.
+          if (
+            toolName === "TodoWrite" &&
+            params.todoTracker?.enabled &&
+            label === ORCHESTRATOR_LABEL
+          ) {
+            params.todoTracker.update(block.input);
+          }
+        }
+      }
+
+      // accumulate per-message usage if available. capture cache fields too
+      // so the fallback token table (used when no final `result` event fires)
+      // still reports the full breakdown instead of silently dropping cache.
+      const msgUsage = event.message?.usage;
+      if (msgUsage) {
+        accumulatedTokens.input += msgUsage.input_tokens || 0;
+        accumulatedTokens.output += msgUsage.output_tokens || 0;
+        accumulatedTokens.cacheRead += msgUsage.cache_read_input_tokens || 0;
+        accumulatedTokens.cacheWrite +=
+          msgUsage.cache_creation_input_tokens || 0;
+        // attribute the same message to orchestrator-vs-subagent. `label`
+        // already resolved above from session_id / parent_tool_use_id, so this
+        // costs one addition and no extra bookkeeping — and per-message is the
+        // only granularity at which the two are separable at all (the terminal
+        // `result` event reports one run-wide total).
+        params.dispatchMetrics?.recordTokens(
+          label,
+          (msgUsage.input_tokens || 0) +
+            (msgUsage.cache_read_input_tokens || 0) +
+            (msgUsage.cache_creation_input_tokens || 0) +
+            (msgUsage.output_tokens || 0),
+        );
+        // per-message is the only point at which a runaway is still cheap to
+        // stop; the `result` event arrives after the tokens are already spent.
+        chargeTokenQuota();
+      }
+    },
+    user: (event: ClaudeUserEvent) => {
+      const content = event.message?.content;
+      if (!content) return;
+
+      const label = eventLabel(event);
+
+      for (const block of content) {
+        if (typeof block === "string") continue;
+        if (block.type === "tool_result") {
+          timerFor(label).markToolResult();
+
+          const outputContent =
+            typeof block.content === "string"
+              ? block.content
+              : Array.isArray(block.content)
+                ? (block.content as unknown[])
+                    .map((entry: unknown) =>
+                      typeof entry === "string"
+                        ? entry
+                        : typeof entry === "object" &&
+                            entry !== null &&
+                            "text" in entry
+                          ? String((entry as { text: unknown }).text)
+                          : JSON.stringify(entry),
+                    )
+                    .join("\n")
+                : String(block.content);
+
+          if (block.is_error) {
+            log.info(withLabel(label, `» tool error: ${outputContent}`));
+          } else {
+            log.debug(withLabel(label, `» tool output: ${outputContent}`));
+          }
+        }
+      }
+    },
+    result: (event: ClaudeResultEvent) => {
+      if (event.session_id) sessionId = event.session_id;
+      const subtype = event.subtype || "unknown";
+      const numTurns = event.num_turns || 0;
+
+      // claude CLI emits synthetic-stop result events with `subtype: "success"`
+      // but `is_error: true` when an upstream provider fails mid-stream (e.g.
+      // 401 from anthropic). short-circuit before the usage/token-table path
+      // so we don't log a usage table for a failed attempt and so downstream
+      // (`resultErrorSubtype` branch) surfaces the structured error. gated on
+      // `subtype === "success"` because the `error_*` subtypes also set
+      // `is_error: true` but carry their payload in `errors: string[]` and
+      // are handled by the dedicated branches below.
+      if (event.is_error === true && subtype === "success") {
+        const apiStatus = event.api_error_status;
+        lastResultError =
+          event.result?.trim() ||
+          `claude reported is_error=true with no result text (api_error_status=${apiStatus ?? "unknown"})`;
+        resultErrorSubtype = subtype;
+        syntheticStopFailure = true;
+        lastApiErrorStatus = typeof apiStatus === "number" ? apiStatus : null;
+        log.info(
+          `» ${params.label} result error: subtype=${subtype}, api_error_status=${apiStatus ?? "unknown"}, message=${lastResultError}`,
+        );
+        return;
+      }
+
+      if (subtype === "success") {
+        // extract detailed usage from result event (most accurate source).
+        // note: `input` here is non-cached input tokens only, matching the
+        // semantics of OpenCode's step_finish.tokens.input — the logTokenTable
+        // helper sums Input + Cache Read + Cache Write + Output into the Total
+        // column so consumers get the real billable figure.
+        const usage = event.usage;
+        const inputTokens = usage?.input_tokens || 0;
+        const cacheRead = usage?.cache_read_input_tokens || 0;
+        const cacheWrite = usage?.cache_creation_input_tokens || 0;
+        const outputTokens = usage?.output_tokens || 0;
+        // guard against NaN/Infinity from malformed CLI output poisoning the total
+        const costUsd =
+          typeof event.total_cost_usd === "number" &&
+          Number.isFinite(event.total_cost_usd)
+            ? event.total_cost_usd
+            : 0;
+
+        accumulatedTokens = {
+          input: inputTokens,
+          output: outputTokens,
+          cacheRead,
+          cacheWrite,
+        };
+        accumulatedCostUsd = costUsd;
+        // the authoritative figure REPLACES the per-message accumulation above,
+        // so the quota charges only the increase (see tokenQuota.ts). This turn
+        // is already over — recording it keeps a multi-attempt run's total
+        // honest, which is what bounds the NEXT attempt.
+        chargeTokenQuota();
+
+        log.info(
+          `» ${params.label} result: subtype=${subtype}, turns=${numTurns}`,
+        );
+
+        if (!tokensLogged) {
+          logTokenTable({
+            input: inputTokens,
+            cacheRead,
+            cacheWrite,
+            output: outputTokens,
+            costUsd,
+          });
+          tokensLogged = true;
+        }
+      } else if (subtype === "error_max_turns") {
+        resultErrorSubtype = subtype;
+        lastResultError = event.errors?.join("\n").trim() || null;
+        log.info(
+          `» ${params.label} max turns reached: ${JSON.stringify(event)}`,
+        );
+      } else if (subtype === "error_during_execution") {
+        resultErrorSubtype = subtype;
+        lastResultError = event.errors?.join("\n").trim() || null;
+        log.info(`» ${params.label} execution error: ${JSON.stringify(event)}`);
+      } else if (subtype.startsWith("error")) {
+        resultErrorSubtype = subtype;
+        lastResultError = event.errors?.join("\n").trim() || null;
+        log.info(
+          `» ${params.label} result: subtype=${subtype}, data=${JSON.stringify(event)}`,
+        );
+      } else {
+        log.info(
+          `» ${params.label} result: subtype=${subtype}, data=${JSON.stringify(event)}`,
+        );
+      }
+
+      if (event.result?.trim()) {
+        finalOutput = event.result.trim();
+      }
+    },
+    // additional Claude CLI event types — debug-logged only
+    stream_event: () => {},
+    tool_progress: () => {},
+    tool_use_summary: () => {},
+    auth_status: () => {},
+  };
+
+  const recentStderr: string[] = [];
+  // ring buffer of recent non-JSON stdout lines. Claude CLI prints
+  // human-readable TTY chrome (status bubbles, quota notices, etc.)
+  // alongside the NDJSON event stream. when the CLI exits non-zero without
+  // emitting a structured error event, these lines are the only actionable
+  // signal — preferring them over the NDJSON tail keeps progress comments
+  // readable. issue #643.
+  const recentNonJsonStdout: string[] = [];
+
+  let lastProviderError: string | null = null;
+
+  // capped accumulator — see opencode.ts for rationale (issue #680).
+  const output = new TailBuffer(DEFAULT_MAX_RETAINED_BYTES);
+  let stdoutBuffer = "";
+
+  // parse + dispatch a single already-trimmed NDJSON line. shared between the
+  // streaming chunk handler and the post-exit flush of the final unterminated
+  // line, so a `result` event on a stream that ends without a trailing newline
+  // is never dropped.
+  const dispatchLine = (trimmed: string): void => {
+    let event: ClaudeEvent;
+    try {
+      event = JSON.parse(trimmed) as ClaudeEvent;
+    } catch {
+      log.debug(`» non-JSON stdout line: ${trimmed.substring(0, 200)}`);
+      recentNonJsonStdout.push(trimmed);
+      if (recentNonJsonStdout.length > MAX_STDERR_LINES)
+        recentNonJsonStdout.shift();
+      return;
+    }
+
+    eventCount++;
+    log.debug(JSON.stringify(event, null, 2));
+
+    const handler = handlers[event.type as keyof typeof handlers];
+    if (!handler) {
+      log.debug(`» ${params.label} event (unhandled): type=${event.type}`);
+      return;
+    }
+    try {
+      (handler as (e: ClaudeEvent) => void)(event);
+    } catch (err) {
+      log.info(
+        `» ${params.label} handler for type=${event.type} threw: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  };
+
+  try {
+    const result = await spawn({
+      cmd: params.cmd,
+      args: params.args,
+      cwd: params.cwd,
+      env: params.env,
+      // flat agent idle budget — long synchronous MCP tool calls (issue #760)
+      // sit well under it, so no per-toolcall suspend bracketing is needed.
+      activityTimeout: AGENT_ACTIVITY_TIMEOUT_MS,
+      onActivityTimeout: params.onActivityTimeout,
+      // LLM10: kills the CLI (and its group) the moment the run's token
+      // ceiling is reached. See chargeTokenQuota above.
+      abortSignal: quotaAbort.signal,
+      stdio: ["ignore", "pipe", "pipe"],
+      // run claude in its own process group so SIGKILL on activity timeout /
+      // outer cancellation reaches any subprocesses it spawns (rg, file
+      // watchers, mcp transports, etc). claude (2.1.113+) is now a native
+      // binary like opencode-ai/bin/opencode, so detached + killGroup is
+      // required to avoid orphaning the binary and its children.
+      killGroup: true,
+      // claude already drains every chunk via onStdout (NDJSON parsing) and
+      // onStderr (recentStderr ring buffer). retaining a second copy in the
+      // spawn wrapper would grow unbounded for long sessions and previously
+      // crashed the wrapper with RangeError. see issue #680.
+      retain: "none",
+      onStdout: async (chunk) => {
+        // capture idle BEFORE markActivity resets the clock, so the gap that
+        // elapsed while the agent was silent (inside a long tool call) is
+        // actually observable — reading it after markActivity always yields ~0.
+        const idleBeforeChunk = getIdleMs();
+        const text = chunk.toString();
+        output.append(text);
+        markActivity();
+
+        if (idleBeforeChunk > 10000) {
+          log.info(
+            `» no activity for ${(idleBeforeChunk / 1000).toFixed(1)}s (${params.label} may be processing internally) (${eventCount} events processed so far)`,
+          );
+        }
+
+        stdoutBuffer += text;
+        const lines = stdoutBuffer.split("\n");
+        stdoutBuffer = lines.pop() || "";
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+          dispatchLine(trimmed);
+        }
+      },
+      onStderr: (chunk) => {
+        const trimmed = chunk.trim();
+        if (!trimmed) return;
+
+        recentStderr.push(trimmed);
+        if (recentStderr.length > MAX_STDERR_LINES) recentStderr.shift();
+
+        const match = findProviderErrorMatch(trimmed);
+        if (match) {
+          lastProviderError = match.label;
+          log.info(
+            `» provider error detected (${match.label}): ${match.excerpt}`,
+          );
+        } else {
+          log.debug(trimmed);
+        }
+      },
+    });
+
+    // flush a final line that arrived without a trailing newline. the CLI's
+    // terminal `{"type":"result",…}` event can land here if the stream ends
+    // (or is SIGKILLed) between the write and its `\n` — dropping it would lose
+    // the authoritative usage/cost and the structured is_error payload.
+    const tail = stdoutBuffer.trim();
+    if (tail) dispatchLine(tail);
+
+    if (result.exitCode === 0) {
+      await params.todoTracker?.flush();
+    } else {
+      params.todoTracker?.cancel();
+    }
+
+    const duration = performance.now() - startTime;
+    log.info(
+      `» ${params.label} completed in ${Math.round(duration)}ms with exit code ${result.exitCode}`,
+    );
+
+    if (eventCount === 0) {
+      const stderrContext = recentStderr.join("\n");
+      const diagnosis = lastProviderError
+        ? `provider error: ${lastProviderError}`
+        : "unknown cause (no stdout events received)";
+      log.info(`» ${params.label} produced 0 events (${diagnosis})`);
+      if (stderrContext) log.info(`» last stderr output:\n${stderrContext}`);
+    }
+
+    // skip the fallback token table only for the synthetic-stop
+    // `subtype: "success"` + `is_error: true` case: `accumulatedTokens` from
+    // prior `assistant` events is stale there and logging it would mislead
+    // operators into thinking billable tokens were spent on a successful turn.
+    // `error_max_turns` / `error_during_execution` / `error_*` subtypes
+    // represent runs that genuinely consumed tokens, so they still get the
+    // table for billing visibility.
+    if (
+      !tokensLogged &&
+      !syntheticStopFailure &&
+      (accumulatedTokens.input > 0 ||
+        accumulatedTokens.output > 0 ||
+        accumulatedTokens.cacheRead > 0 ||
+        accumulatedTokens.cacheWrite > 0)
+    ) {
+      logTokenTable({ ...accumulatedTokens, costUsd: accumulatedCostUsd });
+      tokensLogged = true;
+    }
+
+    const usage = buildUsage();
+    const retryableTransient =
+      syntheticStopFailure && isRetryableApiStatus(lastApiErrorStatus);
+
+    if (result.exitCode !== 0) {
+      const errorContext = lastProviderError ? ` (${lastProviderError})` : "";
+      // prefer the structured `lastResultError` (parsed from a result event
+      // with `is_error: true`) over raw stdout. raw stdout is the full NDJSON
+      // event stream — dumping it into a GitHub Actions `##[error]` line both
+      // hides the actionable provider message and pollutes the run log. cap
+      // the stdout fallback to the last 2KB so it stays readable when neither
+      // a structured error nor stderr is available.
+      //
+      // result.stdout / result.stderr are empty because we pass retain:"none"
+      // to spawn (see issue #680); the agent layer keeps its own bounded
+      // mirrors via `output` (TailBuffer) and `recentStderr` (ring buffer).
+      const stdoutSnapshot = output.toString();
+      const stderrSnapshot = recentStderr.join("\n");
+      const truncatedStdout = stdoutSnapshot
+        ? tailLines(stdoutSnapshot, 2048)
+        : "";
+      // prefer non-JSON stdout (human-readable TTY chrome the CLI prints,
+      // including status bubbles and quota notices) over the raw NDJSON
+      // tail. when the CLI exits 1 without emitting `is_error` (issue #643),
+      // the NDJSON fallback would otherwise dump 2KB of `system/init` events
+      // into the progress comment with no mention of the actual cause.
+      const nonJsonStdoutSnapshot = recentNonJsonStdout.join("\n");
+      const errorMessage =
+        lastResultError ||
+        stderrSnapshot ||
+        nonJsonStdoutSnapshot ||
+        truncatedStdout ||
+        `unknown error - no output from Claude CLI${errorContext}`;
+      log.error(
+        `${params.label} exited with code ${result.exitCode}${errorContext}: ${errorMessage}`,
+      );
+      log.debug(`stdout: ${stdoutSnapshot.substring(0, 500)}`);
+      log.debug(`stderr: ${stderrSnapshot.substring(0, 500)}`);
+      return {
+        success: false,
+        output: finalOutput || stdoutSnapshot,
+        error: errorMessage,
+        usage,
+        sessionId,
+        retryableTransient,
+      };
+    }
+
+    if (eventCount === 0 && lastProviderError) {
+      return {
+        success: false,
+        output: finalOutput || output.toString(),
+        error: `provider error: ${lastProviderError}`,
+        usage,
+        sessionId,
+      };
+    }
+
+    if (resultErrorSubtype) {
+      return {
+        success: false,
+        output: finalOutput || output.toString(),
+        error: lastResultError || `result subtype: ${resultErrorSubtype}`,
+        usage,
+        sessionId,
+        retryableTransient,
+      };
+    }
+
+    return {
+      success: true,
+      output: finalOutput || output.toString(),
+      usage,
+      sessionId,
+    };
+  } catch (error) {
+    params.todoTracker?.cancel();
+    const duration = performance.now() - startTime;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    const isActivityTimeout =
+      error instanceof SpawnTimeoutError &&
+      error.code === SPAWN_ACTIVITY_TIMEOUT_CODE;
+
+    // A quota abort is a decision we made, not a fault to diagnose. Appending
+    // the hang diagnosis ("N events processed before the hang") would misdirect
+    // the operator into looking for a stall that never happened.
+    if (error instanceof TokenQuotaExceededError) {
+      log.info(
+        `» ${params.label} stopped after ${(duration / 1000).toFixed(1)}s: ${errorMessage}`,
+      );
+      return {
+        success: false,
+        output: finalOutput || output.toString(),
+        error: errorMessage,
+        usage: buildUsage(),
+        sessionId,
+      };
+    }
+
+    const stderrContext = recentStderr.slice(-10).join("\n");
+    const diagnosis = lastProviderError
+      ? `likely cause: ${lastProviderError}`
+      : eventCount === 0
+        ? "Claude produced 0 stdout events - check if the API is reachable"
+        : `${eventCount} events were processed before the hang`;
+
+    log.info(
+      `» ${params.label} ${isActivityTimeout ? "hung" : "failed"} after ${(duration / 1000).toFixed(1)}s: ${errorMessage}`,
+    );
+    log.info(`» diagnosis: ${diagnosis}`);
+    if (stderrContext)
+      log.info(
+        `» recent stderr (last ${Math.min(recentStderr.length, 10)} lines):\n${stderrContext}`,
+      );
+
+    return {
+      success: false,
+      output: finalOutput || output.toString(),
+      error: `${errorMessage} [${diagnosis}]`,
+      usage: buildUsage(),
+      sessionId,
+    };
+  }
+}
+
+// ── managed settings ────────────────────────────────────────────────────────────
+
+const MANAGED_SETTINGS_DIR = "/etc/claude-code";
+const MANAGED_SETTINGS_PATH = `${MANAGED_SETTINGS_DIR}/managed-settings.json`;
+
+// managed-settings.json has absolute highest precedence in Claude Code's config hierarchy.
+// it cannot be overridden by user, project, or local settings — safe against malicious PRs.
+//
+// permissions.deny blocks native tools (Read, Grep, Edit, Glob) from accessing /proc and /sys,
+// the git surfaces (blanket Edit(.git/**) write deny + narrow .git/config read deny — see
+// nativeFsDenies.ts), and any path passed in via ctx.secretDenyPaths (codex auth dir, vertex
+// creds dir, etc.).
+// sandbox.filesystem.denyRead blocks the Bash tool sandbox from reading those paths.
+// allowManagedPermissionRulesOnly prevents malicious PRs from adding allow rules that override
+// our deny rules — safe in CI because --dangerously-skip-permissions makes allow/ask irrelevant.
+// allowManagedHooksOnly prevents malicious project hooks from bypassing deny rules.
+// Per Claude Code permissions docs, Read(...) deny ALSO blocks file-reading Bash commands
+// (cat, head, tail, sed) and survives bypassPermissions mode. See wiki/security.md and
+// wiki/codex-auth.md.
+
+/**
+ * env var carrying the gate-server URL to the Claude subprocess. the Stop
+ * hook curls it on every stop; an absent value disables the hook (e.g.
+ * non-CI local dev paths that don't install managed settings either).
+ */
+const STOP_HOOK_GATE_URL_ENV = "INFRAWEAVER_GATE_URL";
+// `_TOKEN` suffix is intentional: filterEnv() strips it from the agent's shell
+// sandbox, so only the Stop hook (a child of this process) can authenticate to
+// the gate server. See gateServer.ts.
+const STOP_HOOK_GATE_TOKEN_ENV = "INFRAWEAVER_GATE_TOKEN";
+
+/**
+ * managed Stop hook. swaps the old `--resume <sessionId>` follow-up
+ * subprocesses (reflection + every gate retry — cost audit on PR #792
+ * showed reflection alone burned ~$0.85 / 111K cache_write per Opus run,
+ * almost all of it wasted re-running `getAttachmentMessages` in the fresh
+ * process) for a `{decision: "block", reason: ...}` injection inside the
+ * live `queryLoop`. existing session context is already in the prompt
+ * cache so only the new reason text is fresh cache_write.
+ *
+ * the script is intentionally minimal — all decision logic lives in the
+ * sidecar gate server (`gateServer.ts`), which reads live `ctx.toolState`
+ * mutations from the same process the MCP server runs in. budget +
+ * one-shot tracking lives there too, so re-fires across multiple stops in
+ * one session are safe. claude-code's 8-consecutive-block override is the
+ * last-line backstop.
+ */
+export function buildStopHookScript(): string {
+  return [
+    "#!/usr/bin/env bash",
+    "set -euo pipefail",
+    `url="\${${STOP_HOOK_GATE_URL_ENV}:-}"`,
+    `tok="\${${STOP_HOOK_GATE_TOKEN_ENV}:-}"`,
+    'if [ -z "$url" ]; then exit 0; fi',
+    // jq is a hard dependency of every later line; under `set -euo pipefail` a
+    // missing binary would abort mid-pipeline as an unexplained exit 1 (a
+    // silent allow). fail the same way, but say why — the gate server's
+    // delivery accounting (commit-on-flush) keeps its state consistent either
+    // way, this is purely for operator visibility.
+    'command -v jq >/dev/null 2>&1 || { echo "infraweaver-stop-hook: jq not found — allowing stop" >&2; exit 0; }',
+    "cat >/dev/null",
+    // a curl failure (timeout, refused) falls back to an allow. the gate
+    // server only commits budget/one-shot state once the response has flushed
+    // to this curl, so an undelivered decision is re-decided on the next stop
+    // rather than silently lost.
+    'response=$(curl -fsS --max-time 30 -H "Authorization: Bearer $tok" "$url" 2>/dev/null || printf \'{"block":false}\')',
+    // tolerate an unparseable body (proxy interference, truncation): fall
+    // back to an allow with a stderr note instead of dying under `set -e`.
+    'block=$(printf "%s" "$response" | jq -r ".block // false" 2>/dev/null || { echo "infraweaver-stop-hook: unparseable gate response — allowing stop" >&2; printf "false"; })',
+    'if [ "$block" != "true" ]; then exit 0; fi',
+    'reason=$(printf "%s" "$response" | jq -r ".reason // \\"\\"")',
+    'if [ -z "$reason" ]; then exit 0; fi',
+    'jq -n --arg reason "$reason" \'{decision: "block", reason: $reason}\'',
+    "",
+  ].join("\n");
+}
+
+export interface ManagedSettingsParams {
+  ctx: AgentRunContext;
+  stopHookPath: string | null;
+  pretoolGateScriptPath: string;
+}
+
+export function buildManagedSettings(
+  params: ManagedSettingsParams,
+): Record<string, unknown> {
+  const secretDenyPaths = params.ctx.secretDenyPaths ?? [];
+  const toolDeny = secretDenyPaths.flatMap((path) => [
+    `Read(${path}/**)`,
+    `Read(/${path}/**)`,
+    `Grep(${path}/**)`,
+    `Grep(/${path}/**)`,
+    `Edit(${path}/**)`,
+    `Edit(/${path}/**)`,
+    `Glob(${path}/**)`,
+    `Glob(/${path}/**)`,
+  ]);
+  // single builder for both the PreToolUse gate hook and the native exec-tool
+  // deny — both fields are consumed here (and identically in the flag-settings
+  // path via writePretoolGateAssets), keeping CLAUDE_EXEC_TOOL_DENY_RULES the
+  // single source.
+  const gate = buildClaudePretoolGateSettings(
+    params.pretoolGateScriptPath,
+    CLAUDE_EXEC_TOOL_DENY_RULES,
+  );
+  const base: Record<string, unknown> = {
+    allowManagedPermissionRulesOnly: true,
+    allowManagedHooksOnly: true,
+    permissions: {
+      deny: [
+        // native exec tools — the authoritative, bypass-immune deny.
+        // `--disallowedTools` (a cliArg-source deny) leaked under
+        // `--dangerously-skip-permissions`; policySettings denies survive
+        // bypassPermissions mode. covers top-level + Agent(...) subagent use.
+        ...gate.permissions.deny,
+        "Read(//proc/**)",
+        "Read(//sys/**)",
+        "Grep(//proc/**)",
+        "Grep(//sys/**)",
+        "Edit(//proc/**)",
+        "Edit(//sys/**)",
+        "Glob(//proc/**)",
+        "Glob(//sys/**)",
+        // git surfaces — blanket Edit(.git/**) write deny (nothing legit
+        // writes .git via native tools; real commits go through MCP git tools
+        // outside this gate) + narrow Read/Grep/Glob(.git/config) read deny.
+        // mirrors opencode's edit-blanket / read-narrow split. canonical:
+        // action/agents/nativeFsDenies.ts.
+        ...GIT_NATIVE_WRITE_DENY_CLAUDE,
+        ...GIT_NATIVE_READ_DENY_CLAUDE,
+        ...runnerHomeWriteDenyClaude(process.env.HOME),
+        ...toolDeny,
+      ],
+    },
+    sandbox: {
+      filesystem: {
+        denyRead: ["/proc", "/sys", ...secretDenyPaths],
+      },
+    },
+  };
+  // PreToolUse gate replicated into managed settings so it survives the
+  // `allowManagedHooksOnly: true` policy gate (see
+  // src/utils/hooks/hooksConfigSnapshot.ts in claude-code source). the Stop
+  // hook (gate-server retries) is layered into the same `hooks` object when
+  // present so both fire under managed settings.
+  const hooks: Record<string, unknown> = {
+    ...gate.hooks,
+  };
+  if (params.stopHookPath) {
+    hooks.Stop = [
+      {
+        hooks: [{ type: "command", command: params.stopHookPath }],
+      },
+    ];
+  }
+  base.hooks = hooks;
+  return base;
+}
+
+function installManagedSettings(params: ManagedSettingsParams): void {
+  if (process.env.CI !== "true") return;
+
+  const content = JSON.stringify(buildManagedSettings(params), null, 2);
+  try {
+    execFileSync("sudo", ["mkdir", "-p", MANAGED_SETTINGS_DIR]);
+    execFileSync("sudo", ["tee", MANAGED_SETTINGS_PATH], {
+      input: content,
+      stdio: ["pipe", "ignore", "pipe"],
+    });
+    log.debug(`» wrote managed settings to ${MANAGED_SETTINGS_PATH}`);
+  } catch (err) {
+    // fail closed: managed settings carry the bypass-immune layer
+    // (allowManagedHooksOnly, /proc + secret denyRead, the .git write fence).
+    // Without them the run would proceed under --dangerously-skip-permissions
+    // with only the flag-settings deny, so a malicious PR's project hooks
+    // could execute and Read(/proc/self/environ) could exfiltrate API keys.
+    // A CI run that cannot install this layer must not start.
+    throw new Error(
+      `failed to install managed settings (the bypass-immune security layer) — refusing to run without it: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
+// ── agent ───────────────────────────────────────────────────────────────────────
+
+export const claude = agent({
+  name: "claude",
+  install: installClaudeCli,
+  run: async (ctx) => {
+    const cliPath = await installClaudeCli();
+
+    const specifier = ctx.resolvedModel;
+    // claude-code on Bedrock takes the bare AWS model ID — no provider prefix
+    // to strip, since the ID is already in `provider.model` form (e.g.
+    // `eu.anthropic.claude-opus-4-7`). detect via the env-var sentinel: if
+    // BEDROCK_MODEL_ID is set and matches the resolved specifier, this is a
+    // bedrock route. see `wiki/model-resolution.md` for the routing pattern.
+    const bedrockModelId = process.env[BEDROCK_MODEL_ID_ENV]?.trim();
+    const isBedrockRoute =
+      specifier !== undefined &&
+      bedrockModelId !== undefined &&
+      bedrockModelId === specifier &&
+      isBedrockAnthropicId(specifier);
+    const vertexModelId = process.env[VERTEX_MODEL_ID_ENV]?.trim();
+    const isVertexRoute =
+      specifier !== undefined &&
+      vertexModelId !== undefined &&
+      vertexModelId === specifier &&
+      isVertexAnthropicId(specifier);
+    const model = !specifier
+      ? undefined
+      : isBedrockRoute
+        ? specifier
+        : isVertexRoute
+          ? undefined
+          : stripProviderPrefix(specifier);
+
+    const homeEnv = agentHomeEnv(ctx.tmpdir);
+
+    mkdirSync(join(homeEnv.XDG_CONFIG_HOME, "claude"), { recursive: true });
+
+    installBundledSkills({ home: homeEnv.HOME });
+
+    const mcpConfigPath = writeMcpConfig(ctx);
+    const effort = resolveEffort(model);
+
+    // reflection + every gate retry (dirty tree, unsubmitted review, summary
+    // stale) move from post-exit `--resume <sessionId>` subprocesses to a
+    // managed Stop hook that curls a sidecar gate server. see
+    // `buildStopHookScript` for the cost rationale (PR #792 audit) and
+    // `gateServer.ts` for the decision policy. Written before the gate assets
+    // so its path can be registered in the flag settings too (non-CI parity).
+    const stopHookPath = join(ctx.tmpdir, "infraweaver-stop-hook.sh");
+    writeFileSync(stopHookPath, buildStopHookScript(), { mode: 0o755 });
+
+    // PreToolUse gate that hard-blocks state-mutating MCP tool calls from
+    // subagents (the `agent_id` field is non-empty in the hook input only
+    // for subagent-originated calls — verified against
+    // yasasbanukaofficial/claude-code src/utils/hooks.ts createBaseHookInput).
+    // Wired via two surfaces so it fires in both CI and local (see
+    // writePretoolGateAssets / buildManagedSettings comments).
+    const pretoolGate = writePretoolGateAssets(ctx, stopHookPath);
+
+    installManagedSettings({
+      ctx,
+      stopHookPath,
+      pretoolGateScriptPath: pretoolGate.scriptPath,
+    });
+
+    // base args shared between initial run and continue runs
+    const baseArgs = [
+      "--output-format",
+      "stream-json",
+      "--dangerously-skip-permissions",
+      "--mcp-config",
+      mcpConfigPath,
+      "--settings",
+      pretoolGate.settingsPath,
+      "--verbose",
+      "--effort",
+      effort,
+      "--disallowedTools",
+      CLAUDE_DISALLOWED_TOOLS,
+      "--agents",
+      buildAgentsJson({ isBedrock: isBedrockRoute, isVertex: isVertexRoute }),
+    ];
+
+    if (model) {
+      baseArgs.push("--model", model);
+    }
+
+    // agent process gets full env — needs LLM API keys, PATH, locale, etc.
+    // security is enforced via managed-settings.json, --disallowedTools (native exec tools), and MCP tool filtering.
+    //
+    // bedrock route: claude-code reads `CLAUDE_CODE_USE_BEDROCK=1` to switch
+    // its provider implementation from the direct Anthropic API to Bedrock.
+    // AWS_BEARER_TOKEN_BEDROCK / AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY +
+    // AWS_REGION are already in process.env from the workflow's `env:` block.
+    // see https://docs.claude.com/en/docs/claude-code/amazon-bedrock.
+    //
+    // we only force CLAUDE_CODE_USE_BEDROCK=1 when this is a Infraweaver-routed
+    // bedrock run; if the user has set the env var manually for some other
+    // reason (e.g. always-Bedrock org policy), `...process.env` already
+    // carries it through and we don't disturb it.
+    const repoDir = process.cwd();
+
+    // PWD is pinned to the repo dir — see baseAgentEnv for why.
+    const env: NodeJS.ProcessEnv = baseAgentEnv(homeEnv, repoDir);
+    // Claude Code auto-compacts the session at its detected model window: 200K
+    // stays 200K, a 1M-context model uses 500K. Setting this keeps long
+    // Remediate/Build runs from hitting the hard context limit mid-task. Respect
+    // an operator override; revalidate when the pinned CLI or model windows change.
+    env.CLAUDE_CODE_AUTO_COMPACT_WINDOW ||= "500000";
+    if (isBedrockRoute) {
+      env.CLAUDE_CODE_USE_BEDROCK = "1";
+    }
+    if (isVertexRoute) {
+      applyClaudeVertexEnv(env);
+      env.ANTHROPIC_MODEL = specifier;
+    }
+
+    // claude-code's `Vw()` resolver prefers ANTHROPIC_API_KEY over the OAuth
+    // token when both are set, so we strip the API key to fall through to the
+    // Max-subscription path. bedrock route uses AWS creds and is excluded.
+    // the strip is gated on a 1-token preflight: an exhausted (session/weekly
+    // limit) or revoked subscription would otherwise kill the run at its first
+    // model call with a working API key sitting unused in env.
+    if (
+      env.CLAUDE_CODE_OAUTH_TOKEN &&
+      !isBedrockRoute &&
+      env.ANTHROPIC_API_KEY
+    ) {
+      const preflight = await preflightClaudeSubscription({
+        token: env.CLAUDE_CODE_OAUTH_TOKEN,
+        model,
+      });
+      if (preflight.usable) {
+        log.debug(
+          "» CLAUDE_CODE_OAUTH_TOKEN present — stripping ANTHROPIC_API_KEY from Claude Code env so the OAuth subscription is used",
+        );
+        delete env.ANTHROPIC_API_KEY;
+      } else {
+        log.info(
+          `» Claude subscription unusable (${preflight.reason}) — falling back to ANTHROPIC_API_KEY`,
+        );
+        delete env.CLAUDE_CODE_OAUTH_TOKEN;
+      }
+    }
+
+    log.info(`» effort: ${effort}`);
+    log.debug(
+      `» starting ${PRODUCT_NAME} (Claude Code): ${cliPath} ${baseArgs.join(" ")}`,
+    );
+    log.debug(`» working directory: ${repoDir}`);
+
+    // gate server lives only as long as the claude subprocess does. the
+    // Stop hook curls `gateServer.url` and turns the response into its
+    // `{decision: "block", reason}` payload (or exits 0 to allow stop).
+    await using gateServer = await startGateServer(ctx);
+
+    const runParams = {
+      label: PRODUCT_NAME,
+      cmd: cliPath,
+      cwd: repoDir,
+      env: {
+        ...env,
+        [STOP_HOOK_GATE_URL_ENV]: gateServer.url,
+        [STOP_HOOK_GATE_TOKEN_ENV]: gateServer.token,
+        // the MCP client (this Claude process) expands ${INFRAWEAVER_MCP_TOKEN}
+        // in mcp.json headers from here; filterEnv() strips it from the MCP
+        // shell sandbox so a sandboxed command can't read it.
+        [MCP_SERVER_TOKEN_ENV]: ctx.mcpServerToken,
+      },
+      todoTracker: ctx.todoTracker,
+      onActivityTimeout: ctx.onActivityTimeout,
+      onToolUse: ctx.onToolUse,
+      tokenQuota: ctx.tokenQuota,
+      // spread into the `--resume` attempt too, so a retry's dispatches and
+      // tokens land in the same run-level tally rather than being lost.
+      dispatchMetrics: ctx.toolState.dispatchMetrics,
+    };
+
+    let result = await runClaude({
+      ...runParams,
+      args: [...baseArgs, "-p", ctx.instructions.full],
+    });
+
+    // bounded resume-retry: a mid-run synthetic-stop with a retryable provider
+    // status (429 / 5xx / 529) would otherwise discard the whole session even
+    // though the CLI supports `--resume` and the session context is intact — a
+    // 90-minute run must not die on one transient blip. each `--resume`
+    // invocation emits a fresh session_id, so the resume target is refreshed
+    // from every attempt. usage is merged across attempts for billing.
+    let resumeSessionId = result.sessionId;
+    for (const delayMs of TRANSIENT_RESUME_RETRY_DELAYS_MS) {
+      if (
+        result.success ||
+        result.retryableTransient !== true ||
+        !resumeSessionId
+      )
+        break;
+      log.info(
+        `» transient provider failure (${result.error ?? "unknown"}) — resuming session ${resumeSessionId} in ${Math.round(delayMs / 1000)}s`,
+      );
+      await sleep(delayMs);
+      const attempt = await runClaude({
+        ...runParams,
+        args: [
+          ...baseArgs,
+          "--resume",
+          resumeSessionId,
+          "-p",
+          TRANSIENT_RESUME_PROMPT,
+        ],
+      });
+      result = {
+        ...attempt,
+        usage: mergeAgentUsage(result.usage, attempt.usage),
+      };
+      resumeSessionId = attempt.sessionId ?? resumeSessionId;
+    }
+
+    // every follow-up turn (reflection + gate retries) has already happened
+    // inside this single subprocess via the Stop hook, so usage aggregation
+    // and resume orchestration are no-ops. all that remains is the terminal
+    // hard-fail render: when the budget exhausted with `stopHook` /
+    // `unsubmittedReview` still failing, flip `success` to false with the
+    // same error shape `runPostRunRetryLoop` produced pre-migration.
+    return finalizeAgentResult({ ctx, result });
+  },
+});