@prismatic-io/lux 0.0.1

package/src/drivers/claude-code/index.ts

@@ -0,0 +1,866 @@
+import { cp, mkdir, readdir, realpath, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { temporaryDirectory } from "tempy";
+import { z } from "zod";
+import {
+  type AgentDriver,
+  type Answer,
+  type Artifact,
+  DEFAULT_CLAUDE_MODEL,
+  type DriverEventMap,
+  type DriverPlugin,
+  discoverCliVersion,
+  exec,
+  type ParsedDriverEvent,
+  type ReadyState,
+  type StartContext,
+  TypedEmitter,
+} from "../../core/index.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+import { copyRegularFileNoFollow } from "../shared/secure-copy.js";
+import { subprocessDriver } from "../subprocess/index.js";
+import { ClaudeCodeLineSchema, makeParseEvent } from "./parse-events.js";
+
+const LUX_BOOKKEEPING_FILES = new Set([
+  "events.jsonl",
+  "case.json",
+  "run.json",
+  "artifacts.json",
+  "grading.json",
+  ".lux-claude-hitl-hook.cjs",
+]);
+const commandName = (command: string): string => command.split(/[\\/]/).at(-1) ?? command;
+const ISOLATION_RESERVED_ARGS = new Set([
+  "--add-dir",
+  "--agent",
+  "--agents",
+  "--bare",
+  "--mcp-config",
+  "--no-session-persistence",
+  "--plugin-dir",
+  "--plugin-url",
+  "--safe-mode",
+  "--setting-sources",
+  "--settings",
+  "--strict-mcp-config",
+]);
+const MINIMAL_ALLOWED_TOOLS = ["Read", "Write", "Edit", "Bash", "Glob", "Grep"] as const;
+
+const IsolationSchema = z
+  .object({
+    /**
+     * Additional read-only trees available to Bash in an isolated run. Plugin
+     * and `addDirs` paths are included automatically.
+     */
+    allowRead: z.array(z.string()).default([]),
+  })
+  .strict();
+
+export const ClaudeCodeDriverConfigSchema = z
+  .object({
+    command: z.string().default("claude"),
+    /** Extra args appended to the default arg list. */
+    extraArgs: z.array(z.string()).optional(),
+    /** Where Claude Code runs. "artifacts" maps to ctx.artifactsDir. */
+    cwdMode: z.enum(["artifacts", "runDir"]).default("artifacts"),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    /** Low-cost by default; choose a larger model explicitly when needed. */
+    model: z.string().min(1).default(DEFAULT_CLAUDE_MODEL),
+    /** Claude effort level; low by default to control eval cost. */
+    effort: z.enum(["low", "medium", "high", "max"]).default("low"),
+    /** Permission mode passed to claude. */
+    permissionMode: z
+      .enum(["acceptEdits", "auto", "bypassPermissions", "default", "dontAsk", "manual", "plan"])
+      .optional(),
+    /** Additional tools pre-approved beyond Lux's minimal coding and ask tools. */
+    allowedTools: z.array(z.string().min(1)).optional(),
+    /** Plugin directories to load (`--plugin-dir`): skills, subagents, commands, hooks. */
+    pluginDirs: z.array(z.string()).optional(),
+    /** Route the session to a named subagent (`--agent`); bare or namespaced name. */
+    agent: z.string().optional(),
+    /** Extra readable directories (`--add-dir`). Grant the narrowest tree the case needs. */
+    addDirs: z.array(z.string()).optional(),
+    /**
+     * Run in a disposable workspace with local memory, persisted runs, and
+     * standard credential stores denied. Live network access is retained.
+     */
+    isolation: IsolationSchema.optional(),
+    /** Tool name that, when invoked, surfaces as an `ask` interrupt. */
+    askToolName: z.string().default("AskUserQuestion"),
+    /**
+     * `defer-resume` uses Claude Code's persisted tool deferral protocol.
+     * `stream-json` is the legacy live-stdin protocol for compatible stubs.
+     */
+    interactionMode: z.enum(["defer-resume", "stream-json"]).default("stream-json"),
+    /**
+     * Treat a terminal agent message containing a question as an interrupt
+     * when a weaker model asks in text instead of calling `askToolName`.
+     */
+    textQuestionFallback: z.boolean().default(false),
+    /** Per-event idle timeout. */
+    idleTimeoutMs: z.number().positive().default(600_000),
+    /** Cap on outstanding interrupts before the driver aborts. */
+    maxInterrupts: z.number().positive().default(20),
+  })
+  .strict()
+  .superRefine((config, ctx) => {
+    if (config.interactionMode === "defer-resume") {
+      const reserved = config.extraArgs?.find((arg) =>
+        ["--input-format", "--no-session-persistence", "--resume", "-r", "--settings"].some(
+          (name) => arg === name || arg.startsWith(`${name}=`),
+        ),
+      );
+      if (reserved) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["extraArgs"],
+          message: `defer-resume owns ${reserved}`,
+        });
+      }
+    }
+    if (!config.isolation) return;
+    if (config.permissionMode && config.permissionMode !== "default") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["permissionMode"],
+        message:
+          "isolation requires permissionMode to be omitted or 'default'; Claude Code forces default mode while subprocess environment scrubbing is enabled",
+      });
+    }
+    if (config.interactionMode === "defer-resume") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["interactionMode"],
+        message: "defer-resume requires session persistence and is incompatible with isolation",
+      });
+    }
+    if (config.cwd || config.cwdMode !== "artifacts") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["isolation"],
+        message: "isolation requires cwdMode 'artifacts' and does not allow an explicit cwd",
+      });
+    }
+    const reserved = config.extraArgs?.find((arg) =>
+      [...ISOLATION_RESERVED_ARGS].some((name) => arg === name || arg.startsWith(`${name}=`)),
+    );
+    if (reserved) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["extraArgs"],
+        message: `isolation owns ${reserved}; configure isolation instead`,
+      });
+    }
+  });
+
+export type ClaudeCodeDriverConfig = z.infer<typeof ClaudeCodeDriverConfigSchema>;
+
+const buildArgs = (config: ClaudeCodeDriverConfig): string[] => {
+  const out = [
+    "--print",
+    "--output-format",
+    "stream-json",
+    "--input-format",
+    "stream-json",
+    "--verbose",
+  ];
+  out.push("--model", config.model, "--effort", config.effort);
+  if (config.permissionMode) out.push("--permission-mode", config.permissionMode);
+  out.push("--allowed-tools", ...allowedTools(config));
+  for (const dir of config.pluginDirs ?? []) out.push("--plugin-dir", dir);
+  if (config.agent) out.push("--agent", config.agent);
+  for (const dir of config.addDirs ?? []) out.push("--add-dir", dir);
+  if (config.extraArgs) out.push(...config.extraArgs);
+  return out;
+};
+
+const shellArgument = (value: string): string => `'${value.replaceAll("'", "'\\''")}'`;
+
+const deferredHookSettings = (
+  config: ClaudeCodeDriverConfig,
+  hookPath: string,
+): Record<string, unknown> => ({
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: config.askToolName,
+        hooks: [
+          {
+            type: "command",
+            command: `${shellArgument(process.execPath)} ${shellArgument(hookPath)}`,
+          },
+        ],
+      },
+    ],
+  },
+});
+
+const allowedTools = (config: ClaudeCodeDriverConfig): string[] => [
+  ...new Set([...MINIMAL_ALLOWED_TOOLS, config.askToolName, ...(config.allowedTools ?? [])]),
+];
+
+const buildDeferredArgs = (
+  config: ClaudeCodeDriverConfig,
+  hookPath: string,
+  sessionId?: string,
+): string[] => {
+  const out = ["--print", "--output-format", "stream-json", "--verbose"];
+  out.push("--model", config.model, "--effort", config.effort);
+  if (config.permissionMode) out.push("--permission-mode", config.permissionMode);
+  out.push("--allowed-tools", ...allowedTools(config));
+  for (const dir of config.pluginDirs ?? []) out.push("--plugin-dir", dir);
+  if (config.agent) out.push("--agent", config.agent);
+  for (const dir of config.addDirs ?? []) out.push("--add-dir", dir);
+  out.push("--settings", JSON.stringify(deferredHookSettings(config, hookPath)));
+  if (sessionId) out.push("--resume", sessionId);
+  if (config.extraArgs) out.push(...config.extraArgs);
+  return out;
+};
+
+const DEFERRED_HOOK_SOURCE = `let input = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => { input += chunk; });
+process.stdin.on("end", () => {
+  const hook = JSON.parse(input);
+  const raw = process.env.LUX_CLAUDE_DEFERRED_ANSWER;
+  const answer = raw ? JSON.parse(raw) : null;
+  const defer = () => process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "defer"
+    }
+  }));
+  if (!answer || answer.id !== hook.tool_use_id) return defer();
+  const questions = Array.isArray(hook.tool_input?.questions) ? hook.tool_input.questions : [];
+  let answers;
+  if (answer.kind === "ask") {
+    try {
+      const parsed = JSON.parse(answer.text);
+      answers = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    } catch {
+      answers = null;
+    }
+    answers ??= Object.fromEntries(questions
+      .map((question) => question?.question)
+      .filter((question) => typeof question === "string")
+      .map((question) => [question, answer.text]));
+  } else {
+    answers = {};
+  }
+  if (questions.length === 0) {
+    return process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow",
+        updatedInput: hook.tool_input,
+        additionalContext: \`The user responded to this message: \${answer.text}\`
+      }
+    }));
+  }
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "allow",
+      updatedInput: { ...hook.tool_input, answers }
+    }
+  }));
+});
+`;
+
+const isWithin = (parent: string, child: string): boolean =>
+  child === parent || child.startsWith(`${parent}${sep}`);
+
+const permissionPath = (tool: "Edit" | "Read", path: string, directory: boolean): string => {
+  const absolute = resolve(path).replaceAll("\\", "/");
+  return `${tool}(//${absolute.replace(/^\/+/, "")}${directory ? "/**" : ""})`;
+};
+
+/**
+ * Permission rules have no "allow inside deny" override, so isolate a root by
+ * denying every sibling around explicitly allowed descendants.
+ */
+const carvedPermissionDenials = async (
+  tool: "Edit" | "Read",
+  root: string,
+  allowed: readonly string[],
+): Promise<string[]> => {
+  const normalizedRoot = resolve(root);
+  const inside = allowed
+    .map((path) => resolve(path))
+    .filter((path) => isWithin(normalizedRoot, path));
+  if (inside.some((path) => path === normalizedRoot)) return [];
+  if (inside.length === 0) return [permissionPath(tool, normalizedRoot, true)];
+
+  const out: string[] = [];
+  const walk = async (dir: string): Promise<void> => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const path = join(dir, entry.name);
+      if (inside.some((allowedPath) => allowedPath === path)) continue;
+      if (entry.isDirectory() && inside.some((allowedPath) => isWithin(path, allowedPath))) {
+        await walk(path);
+      } else {
+        out.push(permissionPath(tool, path, entry.isDirectory()));
+      }
+    }
+  };
+  await walk(normalizedRoot);
+  return out;
+};
+
+const carvedReadDenials = (root: string, allowed: readonly string[]): Promise<string[]> =>
+  carvedPermissionDenials("Read", root, allowed);
+
+const existingRealpaths = async (paths: readonly string[]): Promise<string[]> => {
+  const found = await Promise.all(
+    paths.map(async (path) => {
+      try {
+        return await realpath(resolve(path));
+      } catch {
+        return null;
+      }
+    }),
+  );
+  return [...new Set(found.filter((path): path is string => path !== null))];
+};
+
+const compactRoots = (paths: readonly string[]): string[] =>
+  [...new Set(paths)]
+    .sort((a, b) => a.length - b.length || a.localeCompare(b))
+    .filter((path, index, roots) => !roots.slice(0, index).some((root) => isWithin(root, path)));
+
+const isolatedLaunch = async (
+  config: ClaudeCodeDriverConfig,
+  ctx: StartContext,
+  workspace: string,
+): Promise<{ args: string[]; env: Record<string, string> }> => {
+  const homeRoots = await existingRealpaths([
+    homedir(),
+    ...(config.env?.HOME ? [config.env.HOME] : []),
+  ]);
+  const sensitiveHomePaths = homeRoots.flatMap((home) => [
+    join(home, ".aws"),
+    join(home, ".config", "gcloud"),
+    join(home, ".docker", "config.json"),
+    join(home, ".git-credentials"),
+    join(home, ".gnupg"),
+    join(home, ".kube"),
+    join(home, ".netrc"),
+    join(home, ".npmrc"),
+    join(home, ".ssh"),
+  ]);
+  const protectedRoots = await existingRealpaths([
+    ...(ctx.runsRoot ? [ctx.runsRoot] : [ctx.runDir]),
+    ...(process.env.CLAUDE_CONFIG_DIR ? [process.env.CLAUDE_CONFIG_DIR] : []),
+    ...(config.env?.CLAUDE_CONFIG_DIR ? [config.env.CLAUDE_CONFIG_DIR] : []),
+    ...sensitiveHomePaths,
+    ...homeRoots.flatMap((home) => [
+      join(home, ".claude", "projects"),
+      join(home, ".claude", "memory"),
+    ]),
+  ]);
+  const denyRoots = compactRoots(protectedRoots);
+  const allowed = compactRoots(
+    await existingRealpaths([
+      ...(config.pluginDirs ?? []),
+      ...(config.addDirs ?? []),
+      ...(config.isolation?.allowRead ?? []),
+    ]),
+  );
+  const overlapping = allowed.find(
+    (path) =>
+      (path !== workspace && isWithin(path, workspace)) ||
+      denyRoots.some((root) => isWithin(path, root)) ||
+      protectedRoots.some((root) => isWithin(root, path)),
+  );
+  if (overlapping) {
+    throw new Error(`isolation read carve-out overlaps a protected boundary: ${overlapping}`);
+  }
+  const readOnlyRoots = allowed.filter((path) => !isWithin(workspace, path));
+  const editDenyRoots = compactRoots([...denyRoots, ...readOnlyRoots]);
+  const [readDenials, writeDenials] = await Promise.all([
+    Promise.all(denyRoots.map((root) => carvedPermissionDenials("Read", root, allowed))),
+    Promise.all(editDenyRoots.map((root) => carvedPermissionDenials("Edit", root, []))),
+  ]);
+  const denyRules = [...readDenials.flat(), ...writeDenials.flat()];
+  const sandboxSettings = {
+    disableAllHooks: true,
+    permissions: { deny: denyRules },
+    sandbox: {
+      enabled: true,
+      failIfUnavailable: true,
+      allowUnsandboxedCommands: false,
+      filesystem: {
+        denyRead: denyRoots,
+        denyWrite: denyRoots,
+        allowRead: allowed,
+      },
+      // Filesystem isolation does not disable the live docs and package
+      // registry access that cases are intended to exercise.
+      network: { allowedDomains: ["*"] },
+    },
+  };
+  const stateDir = join(workspace, ".lux-claude");
+  const tmpDir = join(stateDir, "tmp");
+  const cacheDir = join(stateDir, "cache");
+  const pluginCacheDir = join(stateDir, "plugins");
+  await Promise.all([
+    mkdir(tmpDir, { recursive: true }),
+    mkdir(cacheDir, { recursive: true }),
+    mkdir(pluginCacheDir, { recursive: true }),
+  ]);
+  return {
+    args: [
+      // --add-dir also discovers skills and agents. Isolation treats addDirs
+      // as data-only read grants, so expose them through the filesystem policy
+      // above without passing the discovery flag to Claude.
+      ...buildArgs({ ...config, addDirs: undefined }),
+      "--no-session-persistence",
+      "--strict-mcp-config",
+      // Authentication is independent of filesystem setting sources. Keep
+      // these empty instead of using --safe-mode: safe mode would also disable
+      // the explicitly requested plugin's skills, commands, and agents.
+      "--setting-sources",
+      "",
+      "--settings",
+      JSON.stringify(sandboxSettings),
+    ],
+    env: {
+      ...(config.env ?? {}),
+      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
+      CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+      CLAUDE_CODE_SKIP_PROMPT_HISTORY: "1",
+      CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1",
+      CLAUDE_CODE_SUBPROCESS_ENV_SCRUB: "1",
+      CLAUDE_CODE_AUTO_CONNECT_IDE: "false",
+      CLAUDE_CODE_PLUGIN_CACHE_DIR: pluginCacheDir,
+      CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL: "1",
+      DISABLE_AUTOUPDATER: "1",
+      TMPDIR: tmpDir,
+      XDG_CACHE_HOME: cacheDir,
+      npm_config_cache: join(cacheDir, "npm"),
+      BUN_INSTALL_CACHE_DIR: join(cacheDir, "bun"),
+    },
+  };
+};
+
+const formatPrompt = (text: string): string =>
+  `${JSON.stringify({
+    type: "user",
+    message: { role: "user", content: [{ type: "text", text }] },
+  })}\n`;
+
+const formatAnswer = (answer: Answer): string => {
+  let content: string;
+  if (answer.kind === "ask") {
+    content = answer.text;
+  } else if (answer.kind === "approve") {
+    content = `${answer.approved ? "approved" : "denied"}${answer.reason ? `: ${answer.reason}` : ""}`;
+  } else {
+    content = typeof answer.payload === "string" ? answer.payload : JSON.stringify(answer.payload);
+  }
+  const event = {
+    type: "user",
+    message: {
+      role: "user",
+      content: [{ type: "tool_result", tool_use_id: answer.id, content }],
+    },
+  };
+  return `${JSON.stringify(event)}\n`;
+};
+
+class ClaudeCodeDriverImpl implements AgentDriver {
+  private inner: AgentDriver | null = null;
+  private readonly emitter = new TypedEmitter<DriverEventMap>();
+  // The attach closure captures its (event, handler) pair with narrow types,
+  // so the queue stays type-safe without per-entry casts; the identity pair
+  // rides along so off() can drop a queued attach symmetrically.
+  private pendingAttach: Array<{
+    event: keyof DriverEventMap;
+    handler: unknown;
+    attach: (inner: AgentDriver) => void;
+  }> = [];
+  private readonly config: ClaudeCodeDriverConfig;
+  private collectDir: string | null = null;
+  private artifactsDir: string | null = null;
+  private runDir: string | null = null;
+  private isolatedWorkspace: string | null = null;
+  private deferredContext: StartContext | null = null;
+  private deferredCwd: string | null = null;
+  private deferredHookPath: string | null = null;
+  private deferredSessionId: string | null = null;
+  private deferredParser: ReturnType<typeof makeParseEvent> | null = null;
+  private deferredReady:
+    | {
+        resolve: (ready: ReadyState) => void;
+        reject: (error: Error) => void;
+      }
+    | undefined;
+  private deferredPendingId: string | null = null;
+  private deferredTextQuestionPending = false;
+  private deferredLastAgentText: string | null = null;
+  private deferredTextQuestionIndex = 0;
+  private deferredInterrupts = 0;
+  private deferredTerminal = false;
+  private deferredTurn: Promise<void> | null = null;
+
+  constructor(config: ClaudeCodeDriverConfig) {
+    this.config = config;
+  }
+
+  on<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    if (this.config.interactionMode === "defer-resume") {
+      this.emitter.on(event, handler);
+      return;
+    }
+    if (!this.inner) {
+      this.pendingAttach.push({ event, handler, attach: (inner) => inner.on(event, handler) });
+      return;
+    }
+    this.inner.on(event, handler);
+  }
+
+  off<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    if (this.config.interactionMode === "defer-resume") {
+      this.emitter.off(event, handler);
+      return;
+    }
+    if (!this.inner) {
+      this.pendingAttach = this.pendingAttach.filter(
+        (queued) => queued.event !== event || queued.handler !== handler,
+      );
+      return;
+    }
+    this.inner.off(event, handler);
+  }
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    if (this.config.interactionMode === "defer-resume") {
+      return this.startDeferred(ctx);
+    }
+    let cwd =
+      this.config.cwd ?? (this.config.cwdMode === "artifacts" ? ctx.artifactsDir : ctx.runDir);
+    let args = buildArgs(this.config);
+    let env = this.config.env;
+    if (this.config.isolation) {
+      const workspace = await realpath(temporaryDirectory({ prefix: "lux-claude-workspace-" }));
+      await cp(ctx.artifactsDir, workspace, { recursive: true });
+      this.isolatedWorkspace = workspace;
+      cwd = workspace;
+      const launch = await isolatedLaunch(this.config, ctx, workspace);
+      args = launch.args;
+      env = launch.env;
+    }
+    this.collectDir = cwd;
+    this.artifactsDir = ctx.artifactsDir;
+    this.runDir = ctx.runDir;
+    const cliVersion =
+      commandName(this.config.command) === "claude"
+        ? await discoverCliVersion(this.config.command)
+        : undefined;
+    const inner = await subprocessDriver.create({
+      command: this.config.command,
+      args,
+      cwd,
+      env,
+      protocol: "custom",
+      parseEvent: makeParseEvent(this.config, cliVersion),
+      formatAnswer,
+      formatPrompt,
+      idleTimeoutMs: this.config.idleTimeoutMs,
+      maxInterrupts: this.config.maxInterrupts,
+    });
+    for (const queued of this.pendingAttach) queued.attach(inner);
+    this.pendingAttach = [];
+    this.inner = inner;
+    return inner.start(ctx);
+  }
+
+  async respond(answer: Answer): Promise<void> {
+    if (this.config.interactionMode === "defer-resume") {
+      if (!this.deferredContext || !this.deferredSessionId) {
+        throw new Error("claude-code driver: no deferred session to resume");
+      }
+      if (answer.id !== this.deferredPendingId) {
+        throw new Error(
+          `claude-code driver: answer '${answer.id}' does not match deferred tool '${this.deferredPendingId ?? "none"}'`,
+        );
+      }
+      const textQuestion = this.deferredTextQuestionPending;
+      this.deferredPendingId = null;
+      this.deferredTextQuestionPending = false;
+      this.launchDeferredTurn(answer, textQuestion);
+      return;
+    }
+    if (!this.inner) throw new Error("claude-code driver: respond called before start");
+    return this.inner.respond(answer);
+  }
+
+  async collect(): Promise<Artifact[]> {
+    if (!this.collectDir) return [];
+    // A terminal protocol event can arrive before the CLI and its descendants
+    // have exited. Quiesce the whole process tree before walking/copying files
+    // so it cannot swap a checked regular file into a symlink.
+    await this.inner?.close();
+    const artifacts = await walkArtifacts(this.collectDir);
+    if (this.isolatedWorkspace && this.artifactsDir) {
+      await Promise.all(
+        artifacts.map(async (artifact) => {
+          const target = join(this.artifactsDir as string, artifact.path);
+          await mkdir(dirname(target), { recursive: true });
+          await rm(target, { force: true });
+          await copyRegularFileNoFollow(
+            this.isolatedWorkspace as string,
+            join(this.isolatedWorkspace as string, artifact.path),
+            target,
+          );
+        }),
+      );
+      return artifacts;
+    }
+    // Consumers resolve artifact paths against <runDir>/artifacts by default;
+    // a walk of any other root must say what its paths are relative to, or
+    // the judge and file assertions silently miss every file.
+    if (this.collectDir === this.artifactsDir) return artifacts;
+    const root = this.collectDir;
+    // Walking the run dir itself would list Lux's own bookkeeping as agent
+    // work product; only top-level files can collide with these names.
+    const withRoot = artifacts.map((a) => ({ ...a, root }));
+    return root === this.runDir
+      ? withRoot.filter((a) => !LUX_BOOKKEEPING_FILES.has(a.path))
+      : withRoot;
+  }
+
+  async quiesce(): Promise<void> {
+    if (this.config.interactionMode === "defer-resume") {
+      await this.deferredTurn;
+      return;
+    }
+    await this.inner?.close();
+  }
+
+  async close(): Promise<void> {
+    try {
+      if (this.config.interactionMode === "defer-resume") {
+        this.emitter.removeAllListeners();
+        if (this.deferredHookPath) {
+          await rm(this.deferredHookPath, { force: true });
+          this.deferredHookPath = null;
+        }
+      } else {
+        await this.inner?.close();
+      }
+    } finally {
+      if (this.isolatedWorkspace) {
+        await rm(this.isolatedWorkspace, { recursive: true, force: true });
+        this.isolatedWorkspace = null;
+      }
+    }
+  }
+
+  private async startDeferred(ctx: StartContext): Promise<ReadyState> {
+    const cwd =
+      this.config.cwd ?? (this.config.cwdMode === "artifacts" ? ctx.artifactsDir : ctx.runDir);
+    this.collectDir = cwd;
+    this.artifactsDir = ctx.artifactsDir;
+    this.runDir = ctx.runDir;
+    this.deferredContext = ctx;
+    this.deferredCwd = cwd;
+    this.deferredHookPath = join(ctx.runDir, ".lux-claude-hitl-hook.cjs");
+    await writeFile(this.deferredHookPath, DEFERRED_HOOK_SOURCE);
+    const cliVersion =
+      commandName(this.config.command) === "claude"
+        ? await discoverCliVersion(this.config.command)
+        : undefined;
+    this.deferredParser = makeParseEvent(this.config, cliVersion);
+    const ready = new Promise<ReadyState>((resolveReady, reject) => {
+      this.deferredReady = { resolve: resolveReady, reject };
+    });
+    this.launchDeferredTurn();
+    return ready;
+  }
+
+  private launchDeferredTurn(answer?: Answer, resumeWithAnswer = false): void {
+    let task!: Promise<void>;
+    task = (async () => {
+      try {
+        await this.runDeferredTurn(answer, resumeWithAnswer);
+      } catch (error) {
+        await this.failDeferred(error);
+      } finally {
+        if (this.deferredTurn === task) this.deferredTurn = null;
+      }
+    })();
+    this.deferredTurn = task;
+  }
+
+  private async runDeferredTurn(answer?: Answer, resumeWithAnswer = false): Promise<void> {
+    const ctx = this.deferredContext;
+    const cwd = this.deferredCwd;
+    const hookPath = this.deferredHookPath;
+    const parse = this.deferredParser;
+    if (!ctx || !cwd || !hookPath || !parse) {
+      throw new Error("claude-code driver: deferred session was not initialized");
+    }
+    const resuming = this.deferredSessionId !== null;
+    let input: { input: string } | undefined;
+    if (!resuming) {
+      input = { input: ctx.prompt };
+    } else if (resumeWithAnswer && answer?.kind === "ask") {
+      input = { input: answer.text };
+    }
+    const result = await exec(
+      this.config.command,
+      buildDeferredArgs(this.config, hookPath, this.deferredSessionId ?? undefined),
+      {
+        cwd,
+        env: {
+          ...process.env,
+          LUX_RUN_DIR: ctx.runDir,
+          LUX_ARTIFACTS_DIR: ctx.artifactsDir,
+          ...this.config.env,
+          ...(answer ? { LUX_CLAUDE_DEFERRED_ANSWER: JSON.stringify(answer) } : {}),
+        },
+        ...input,
+        timeoutMs: this.config.idleTimeoutMs,
+        signal: ctx.abortSignal,
+      },
+    );
+    if (result.stderr.trim()) {
+      for (const line of result.stderr.trimEnd().split("\n")) {
+        process.stderr.write(`[claude-code] ${line}\n`);
+      }
+    }
+    for (const line of result.stdout.split("\n")) {
+      if (!line.trim()) continue;
+      try {
+        const envelope = ClaudeCodeLineSchema.safeParse(JSON.parse(line));
+        if (
+          envelope.success &&
+          (envelope.data.type === "system" || envelope.data.type === "result") &&
+          envelope.data.session_id
+        ) {
+          this.deferredSessionId = envelope.data.session_id;
+        }
+      } catch {
+        // The parser below deliberately ignores unmodeled output.
+      }
+      const parsed = parse(line);
+      if (!parsed) continue;
+      for (const event of Array.isArray(parsed) ? parsed : [parsed]) {
+        await this.dispatchDeferred(event);
+      }
+    }
+    if (result.timedOut) {
+      throw new Error(`no event for ${this.config.idleTimeoutMs}ms`);
+    }
+    if (result.signal) throw new Error(`claude exited from signal ${result.signal}`);
+    if (result.exitCode !== 0 && !this.deferredTerminal) {
+      throw new Error(`claude exited ${result.exitCode}`);
+    }
+    if (!resuming && this.deferredReady) {
+      throw new Error("claude exited before ready");
+    }
+  }
+
+  private async dispatchDeferred(event: ParsedDriverEvent): Promise<void> {
+    if (this.deferredTerminal) return;
+    if (event.tag === "ready") {
+      this.deferredReady?.resolve(event.ready);
+      this.deferredReady = undefined;
+      return;
+    }
+    if (event.tag === "progress") {
+      if (
+        event.progress.kind === "agent-message" &&
+        typeof (event.progress.payload as { text?: unknown })?.text === "string"
+      ) {
+        this.deferredLastAgentText = (event.progress.payload as { text: string }).text;
+      }
+      await this.emitter.emit("progress", event.progress);
+      return;
+    }
+    if (event.tag === "interrupt") {
+      this.deferredLastAgentText = null;
+      this.deferredInterrupts++;
+      if (this.deferredInterrupts > this.config.maxInterrupts) {
+        this.deferredTerminal = true;
+        await this.emitter.emit("error", {
+          exitReason: "max-interactions",
+          reason: `exceeded maxInterrupts (${this.config.maxInterrupts})`,
+        });
+        return;
+      }
+      this.deferredPendingId = event.interrupt.id;
+      await this.emitter.emit("interrupt", event.interrupt);
+      return;
+    }
+    if (
+      event.tag === "done" &&
+      this.config.textQuestionFallback &&
+      this.deferredLastAgentText?.includes("?")
+    ) {
+      const question = this.deferredLastAgentText;
+      this.deferredLastAgentText = null;
+      this.deferredInterrupts++;
+      if (this.deferredInterrupts > this.config.maxInterrupts) {
+        this.deferredTerminal = true;
+        await this.emitter.emit("error", {
+          exitReason: "max-interactions",
+          reason: `exceeded maxInterrupts (${this.config.maxInterrupts})`,
+        });
+        return;
+      }
+      this.deferredTextQuestionIndex++;
+      const id = `text-question-${this.deferredTextQuestionIndex}`;
+      this.deferredPendingId = id;
+      this.deferredTextQuestionPending = true;
+      await this.emitter.emit("interrupt", {
+        kind: "ask",
+        id,
+        question,
+        context: { fallback: "terminal-agent-message" },
+      });
+      return;
+    }
+    this.deferredTerminal = true;
+    if (event.tag === "done") await this.emitter.emit("done", event.done);
+    else await this.emitter.emit("error", event.error);
+  }
+
+  private async failDeferred(error: unknown): Promise<void> {
+    if (this.deferredTerminal) return;
+    this.deferredTerminal = true;
+    const reason = error instanceof Error ? error.message : String(error);
+    if (this.deferredReady) {
+      this.deferredReady.reject(new Error(reason));
+      this.deferredReady = undefined;
+      return;
+    }
+    await this.emitter.emit("error", {
+      exitReason: reason.startsWith("no event for") ? "idle-timeout" : "error",
+      reason,
+    });
+  }
+}
+
+export const claudeCodeDriver: DriverPlugin<ClaudeCodeDriverConfig> = {
+  name: "claude-code",
+  configSchema: ClaudeCodeDriverConfigSchema,
+  create: (config) => new ClaudeCodeDriverImpl(config),
+};
+
+// Internal exports for testing
+export {
+  buildArgs,
+  buildDeferredArgs,
+  carvedReadDenials,
+  copyRegularFileNoFollow,
+  formatAnswer,
+  formatPrompt,
+  makeParseEvent,
+  walkArtifacts,
+};