@prismatic-io/lux 0.0.2-preview.4 → 0.0.2-preview.41

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

@@ -1,25 +1,37 @@
-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 { cp, mkdir, realpath, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { temporaryDirectory } from "tempy";
 import { z } from "zod";
+import { agentEnvironment, InheritEnvironmentSchema } from "../../core/agent-environment.js";
+import { DurationSchema, durationMs } from "../../core/duration.js";
 import {
   type AgentDriver,
   type Answer,
   type Artifact,
+  applyCatalogEffort,
+  claudeCodeCatalog,
   DEFAULT_CLAUDE_MODEL,
   type DriverEventMap,
-  type DriverPlugin,
+  defineDriver,
   discoverCliVersion,
-  exec,
   type ParsedDriverEvent,
   type ReadyState,
   type StartContext,
+  selectModelAndReasoningEffort,
   TypedEmitter,
 } from "../../core/index.js";
+import { copyRegularFileNoFollow } from "../../core/secure-copy.js";
 import { walkArtifacts } from "../shared/artifacts.js";
-import { copyRegularFileNoFollow } from "../shared/secure-copy.js";
+import {
+  claudeConfigRoot,
+  claudeUserBehaviorHash,
+  configuredClaudeSourceHashes,
+} from "../shared/experiment-behavior.js";
+import { prepareClaudeExperimentConfig } from "../shared/experiment-policy.js";
+import { stageSkills } from "../shared/skills.js";
 import { subprocessDriver } from "../subprocess/index.js";
+import { runDeferredProcess } from "./deferred-process.js";
+import { isolatedLaunch } from "./isolation.js";
 import { ClaudeCodeLineSchema, makeParseEvent } from "./parse-events.js";
 
 const LUX_BOOKKEEPING_FILES = new Set([
@@ -33,12 +45,23 @@ const LUX_BOOKKEEPING_FILES = new Set([
 const commandName = (command: string): string => command.split(/[\\/]/).at(-1) ?? command;
 const ISOLATION_RESERVED_ARGS = new Set([
   "--add-dir",
+  "--dangerously-skip-permissions",
+  "--allow-dangerously-skip-permissions",
+  "--permission-mode",
+  "--teleport",
+  "--continue",
+  "-c",
+  "--resume",
+  "-r",
+  "--fork-session",
+  "--session-id",
   "--agent",
   "--agents",
   "--bare",
   "--mcp-config",
   "--no-session-persistence",
   "--plugin-dir",
+  "--plugin-dir-no-mcp",
   "--plugin-url",
   "--safe-mode",
   "--setting-sources",
@@ -54,6 +77,8 @@ const IsolationSchema = z
      * and `addDirs` paths are included automatically.
      */
     allowRead: z.array(z.string()).default([]),
+    /** Additional protected trees and files, including other evaluation runs. */
+    denyRead: z.array(z.string()).optional(),
   })
   .strict();
 
@@ -66,15 +91,15 @@ export const ClaudeCodeDriverConfigSchema = z
     cwdMode: z.enum(["artifacts", "runDir"]).default("artifacts"),
     cwd: z.string().optional(),
     env: z.record(z.string(), z.string()).optional(),
+    inheritEnv: InheritEnvironmentSchema.default(true),
     /** 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"),
+    reasoningEffort: z.enum(claudeCodeCatalog.efforts).optional(),
     /** 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. */
+    /** Additional pre-approvals; auto mode omits the baseline coding-tool grants. */
     allowedTools: z.array(z.string().min(1)).optional(),
     /** Plugin directories to load (`--plugin-dir`): skills, subagents, commands, hooks. */
     pluginDirs: z.array(z.string()).optional(),
@@ -82,6 +107,8 @@ export const ClaudeCodeDriverConfigSchema = z
     agent: z.string().optional(),
     /** Extra readable directories (`--add-dir`). Grant the narrowest tree the case needs. */
     addDirs: z.array(z.string()).optional(),
+    /** Standalone skill directories registered through native discovery in an isolated workspace. */
+    skillDirs: z.array(z.string().min(1)).optional(),
     /**
      * Run in a disposable workspace with local memory, persisted runs, and
      * standard credential stores denied. Live network access is retained.
@@ -93,24 +120,46 @@ export const ClaudeCodeDriverConfigSchema = z
      * `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"),
+    interactionMode: z.enum(["defer-resume", "stream-json"]).default("defer-resume"),
     /**
      * 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),
+    /** Maximum silence between recognized protocol events; excludes answerer wait time. */
+    idleTimeout: DurationSchema.default("10 minutes"),
+    /** Optional elapsed-time cap per defer-resume CLI invocation, regardless of activity. */
+    turnTimeout: DurationSchema.optional(),
     /** Cap on outstanding interrupts before the driver aborts. */
     maxInterrupts: z.number().positive().default(20),
   })
   .strict()
   .superRefine((config, ctx) => {
+    if (config.skillDirs?.length && !config.isolation) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["skillDirs"],
+        message: "skillDirs requires isolation",
+      });
+    }
+    if (config.turnTimeout !== undefined && config.interactionMode !== "defer-resume") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["turnTimeout"],
+        message: "turnTimeout requires defer-resume mode",
+      });
+    }
     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}=`),
-        ),
+        [
+          "--input-format",
+          "--no-session-persistence",
+          "--resume",
+          "-r",
+          "--settings",
+          "--permission-prompt-tool",
+          "--permission-prompts",
+        ].some((name) => arg === name || arg.startsWith(`${name}=`)),
       );
       if (reserved) {
         ctx.addIssue({
@@ -129,11 +178,12 @@ export const ClaudeCodeDriverConfigSchema = z
           "isolation requires permissionMode to be omitted or 'default'; Claude Code forces default mode while subprocess environment scrubbing is enabled",
       });
     }
-    if (config.interactionMode === "defer-resume") {
+    if (config.interactionMode === "defer-resume" && config.pluginDirs?.length) {
       ctx.addIssue({
         code: "custom",
-        path: ["interactionMode"],
-        message: "defer-resume requires session persistence and is incompatible with isolation",
+        path: ["pluginDirs"],
+        message:
+          "isolated defer-resume cannot load plugin hooks; use skillDirs for standalone skills",
       });
     }
     if (config.cwd || config.cwdMode !== "artifacts") {
@@ -153,7 +203,8 @@ export const ClaudeCodeDriverConfigSchema = z
         message: `isolation owns ${reserved}; configure isolation instead`,
       });
     }
-  });
+  })
+  .transform(applyCatalogEffort(claudeCodeCatalog));
 
 export type ClaudeCodeDriverConfig = z.infer<typeof ClaudeCodeDriverConfigSchema>;
 
@@ -166,7 +217,7 @@ const buildArgs = (config: ClaudeCodeDriverConfig): string[] => {
     "stream-json",
     "--verbose",
   ];
-  out.push("--model", config.model, "--effort", config.effort);
+  out.push("--model", config.model, ...effortArgs(config));
   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);
@@ -197,23 +248,48 @@ const deferredHookSettings = (
   },
 });
 
+const effortArgs = (config: ClaudeCodeDriverConfig): string[] =>
+  config.reasoningEffort ? ["--effort", config.reasoningEffort] : [];
+
 const allowedTools = (config: ClaudeCodeDriverConfig): string[] => [
-  ...new Set([...MINIMAL_ALLOWED_TOOLS, config.askToolName, ...(config.allowedTools ?? [])]),
+  ...new Set([
+    ...(config.permissionMode === "auto" ? [] : MINIMAL_ALLOWED_TOOLS),
+    config.askToolName,
+    ...(config.allowedTools ?? []),
+  ]),
 ];
 
 const buildDeferredArgs = (
   config: ClaudeCodeDriverConfig,
   hookPath: string,
   sessionId?: string,
+  isolation?: Awaited<ReturnType<typeof isolatedLaunch>>,
 ): string[] => {
-  const out = ["--print", "--output-format", "stream-json", "--verbose"];
-  out.push("--model", config.model, "--effort", config.effort);
+  // Native print mode removes AskUserQuestion unless a host permission surface exists.
+  // The trusted PreToolUse hook handles the question before that surface is consulted.
+  const out = [
+    "--print",
+    "--output-format",
+    "stream-json",
+    "--verbose",
+    "--permission-prompt-tool",
+    "stdio",
+  ];
+  out.push("--model", config.model, ...effortArgs(config));
   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 (!isolation) for (const dir of config.addDirs ?? []) out.push("--add-dir", dir);
+  out.push(
+    "--settings",
+    JSON.stringify({
+      ...isolation?.settings,
+      ...deferredHookSettings(config, hookPath),
+      ...(isolation ? { disableAllHooks: false } : {}),
+    }),
+  );
+  if (isolation) out.push("--strict-mcp-config", "--setting-sources", "");
   if (sessionId) out.push("--resume", sessionId);
   if (config.extraArgs) out.push(...config.extraArgs);
   return out;
@@ -269,184 +345,6 @@ process.stdin.on("end", () => {
 });
 `;
 
-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",
@@ -475,9 +373,7 @@ const formatAnswer = (answer: Answer): string => {
 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.
+  // Typed closures retain handler identity so off() can detach queued listeners.
   private pendingAttach: Array<{
     event: keyof DriverEventMap;
     handler: unknown;
@@ -488,6 +384,8 @@ class ClaudeCodeDriverImpl implements AgentDriver {
   private artifactsDir: string | null = null;
   private runDir: string | null = null;
   private isolatedWorkspace: string | null = null;
+  private isolationControlDir: string | null = null;
+  private deferredIsolation: Awaited<ReturnType<typeof isolatedLaunch>> | undefined;
   private deferredContext: StartContext | null = null;
   private deferredCwd: string | null = null;
   private deferredHookPath: string | null = null;
@@ -506,6 +404,7 @@ class ClaudeCodeDriverImpl implements AgentDriver {
   private deferredInterrupts = 0;
   private deferredTerminal = false;
   private deferredTurn: Promise<void> | null = null;
+  private deferredAbort = new AbortController();
 
   constructor(config: ClaudeCodeDriverConfig) {
     this.config = config;
@@ -544,15 +443,20 @@ class ClaudeCodeDriverImpl implements AgentDriver {
     let cwd =
       this.config.cwd ?? (this.config.cwdMode === "artifacts" ? ctx.artifactsDir : ctx.runDir);
     let args = buildArgs(this.config);
-    let env = this.config.env;
+    let env = agentEnvironment(process.env, this.config.inheritEnv, 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;
+      const launch = await this.prepareIsolation(ctx);
+      cwd = this.isolatedWorkspace as string;
+      args = [
+        ...buildArgs({ ...this.config, addDirs: undefined }),
+        "--no-session-persistence",
+        "--strict-mcp-config",
+        "--setting-sources",
+        "",
+        "--settings",
+        JSON.stringify(launch.settings),
+      ];
+      env = agentEnvironment(process.env, this.config.inheritEnv, launch.env);
     }
     this.collectDir = cwd;
     this.artifactsDir = ctx.artifactsDir;
@@ -566,11 +470,12 @@ class ClaudeCodeDriverImpl implements AgentDriver {
       args,
       cwd,
       env,
+      inheritEnv: false,
       protocol: "custom",
       parseEvent: makeParseEvent(this.config, cliVersion),
       formatAnswer,
       formatPrompt,
-      idleTimeoutMs: this.config.idleTimeoutMs,
+      idleTimeout: this.config.idleTimeout,
       maxInterrupts: this.config.maxInterrupts,
     });
     for (const queued of this.pendingAttach) queued.attach(inner);
@@ -601,10 +506,8 @@ class ClaudeCodeDriverImpl implements AgentDriver {
 
   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();
+    // Stop descendants before collecting: terminal events can precede their exit.
+    await this.quiesce();
     const artifacts = await walkArtifacts(this.collectDir);
     if (this.isolatedWorkspace && this.artifactsDir) {
       await Promise.all(
@@ -621,21 +524,24 @@ class ClaudeCodeDriverImpl implements AgentDriver {
       );
       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.
+    // Assertions need an explicit root for artifacts collected outside artifactsDir.
     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.
+    // Top-level bookkeeping in runDir is not agent work product.
     const withRoot = artifacts.map((a) => ({ ...a, root }));
     return root === this.runDir
       ? withRoot.filter((a) => !LUX_BOOKKEEPING_FILES.has(a.path))
       : withRoot;
   }
 
+  async verificationWorkspace(): Promise<string | undefined> {
+    await this.quiesce();
+    return this.isolatedWorkspace ?? undefined;
+  }
+
   async quiesce(): Promise<void> {
     if (this.config.interactionMode === "defer-resume") {
+      this.deferredAbort.abort();
       await this.deferredTurn;
       return;
     }
@@ -645,6 +551,7 @@ class ClaudeCodeDriverImpl implements AgentDriver {
   async close(): Promise<void> {
     try {
       if (this.config.interactionMode === "defer-resume") {
+        await this.quiesce();
         this.emitter.removeAllListeners();
         if (this.deferredHookPath) {
           await rm(this.deferredHookPath, { force: true });
@@ -654,16 +561,37 @@ class ClaudeCodeDriverImpl implements AgentDriver {
         await this.inner?.close();
       }
     } finally {
-      if (this.isolatedWorkspace) {
-        await rm(this.isolatedWorkspace, { recursive: true, force: true });
-        this.isolatedWorkspace = null;
-      }
+      await Promise.all(
+        [this.isolatedWorkspace, this.isolationControlDir]
+          .filter((path) => path !== null)
+          .map((path) => rm(path, { recursive: true, force: true })),
+      );
+      this.isolatedWorkspace = null;
+      this.isolationControlDir = null;
     }
   }
 
+  private async prepareIsolation(
+    ctx: StartContext,
+  ): Promise<Awaited<ReturnType<typeof isolatedLaunch>>> {
+    this.isolatedWorkspace = await realpath(
+      temporaryDirectory({ prefix: "lux-claude-workspace-" }),
+    );
+    this.isolationControlDir = await realpath(
+      temporaryDirectory({ prefix: "lux-claude-control-" }),
+    );
+    await cp(ctx.artifactsDir, this.isolatedWorkspace, { recursive: true });
+    await stageSkills(this.config.skillDirs ?? [], this.isolatedWorkspace, ".claude");
+    return isolatedLaunch(this.config, ctx, this.isolatedWorkspace, this.isolationControlDir);
+  }
+
   private async startDeferred(ctx: StartContext): Promise<ReadyState> {
-    const cwd =
+    let cwd =
       this.config.cwd ?? (this.config.cwdMode === "artifacts" ? ctx.artifactsDir : ctx.runDir);
+    if (this.config.isolation) {
+      this.deferredIsolation = await this.prepareIsolation(ctx);
+      cwd = this.isolatedWorkspace as string;
+    }
     this.collectDir = cwd;
     this.artifactsDir = ctx.artifactsDir;
     this.runDir = ctx.runDir;
@@ -712,58 +640,51 @@ class ClaudeCodeDriverImpl implements AgentDriver {
     } 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;
+    const terminal = await runDeferredProcess({
+      command: this.config.command,
+      args: buildDeferredArgs(
+        this.config,
+        hookPath,
+        this.deferredSessionId ?? undefined,
+        this.deferredIsolation,
+      ),
+      cwd,
+      env: agentEnvironment(process.env, this.config.inheritEnv, {
+        ...(this.deferredIsolation?.env ?? this.config.env),
+        LUX_RUN_DIR: ctx.runDir,
+        LUX_ARTIFACTS_DIR: ctx.artifactsDir,
+        ...(answer ? { LUX_CLAUDE_DEFERRED_ANSWER: JSON.stringify(answer) } : {}),
+      }),
+      ...input,
+      idleTimeoutMs: durationMs(this.config.idleTimeout),
+      ...(this.config.turnTimeout === undefined
+        ? {}
+        : { turnTimeoutMs: durationMs(this.config.turnTimeout) }),
+      signal: AbortSignal.any([ctx.abortSignal, this.deferredAbort.signal]),
+      parse: (line) => {
+        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.
         }
-      } 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");
+        return parse(line);
+      },
+      onEvent: (event) => this.dispatchDeferred(event),
+    });
+    if (this.deferredReady) {
+      throw new Error(
+        terminal?.tag === "error" ? terminal.error.reason : "claude exited before ready",
+      );
     }
+    if (terminal) await this.dispatchDeferred(terminal);
+    if (!terminal) throw new Error("claude exited before a terminal result");
   }
 
   private async dispatchDeferred(event: ParsedDriverEvent): Promise<void> {
@@ -847,17 +768,42 @@ class ClaudeCodeDriverImpl implements AgentDriver {
   }
 }
 
-export const claudeCodeDriver: DriverPlugin<ClaudeCodeDriverConfig> = {
+export const claudeCodeDriver = defineDriver({
   name: "claude-code",
   configSchema: ClaudeCodeDriverConfigSchema,
+  runtime: (config) => ({
+    commands: [config.command],
+    capabilities: {
+      interactive: true,
+      "tool-calls": true,
+      "tool-results": true,
+      artifacts: true,
+      subagents: true,
+      usage: true,
+      cost: true,
+      isolation: Boolean(config.isolation),
+    },
+  }),
+  experiment: {
+    version: "1",
+    prepare: prepareClaudeExperimentConfig,
+    identity: async (config, { rootDir }) => {
+      const configRoot = claudeConfigRoot({ config });
+      return {
+        configRoot,
+        userBehaviorHash: await claudeUserBehaviorHash(configRoot),
+        sources: await configuredClaudeSourceHashes({ name: "claude-code", config }, rootDir),
+      };
+    },
+  },
+  selectHarness: selectModelAndReasoningEffort,
   create: (config) => new ClaudeCodeDriverImpl(config),
-};
+});
 
 // Internal exports for testing
 export {
   buildArgs,
   buildDeferredArgs,
-  carvedReadDenials,
   copyRegularFileNoFollow,
   formatAnswer,
   formatPrompt,