@prismatic-io/lux 0.0.2-preview.23 → 0.0.2-preview.25

package/src/cli/init-templates.ts

@@ -1,4 +1,11 @@
-type StarterDriver = "subprocess" | "claude-code" | "codex" | "cursor" | "copilot" | "antigravity";
+type StarterDriver =
+  | "subprocess"
+  | "claude-code"
+  | "codex"
+  | "cursor"
+  | "copilot"
+  | "antigravity"
+  | "grok-build";
 
 export const luxConfigBody = (
   withExperiment: boolean,
@@ -22,6 +29,7 @@ export const luxConfigBody = (
       "claude-code": 'reasoningEffort: "low"',
       codex: 'reasoningEffort: "low"',
       cursor: "",
+      "grok-build": 'reasoningEffort: "low", permissionMode: "auto"',
       copilot: 'reasoningEffort: "low"',
       antigravity: 'reasoningEffort: "low"',
     };

package/src/cli/init.ts

@@ -13,7 +13,7 @@ import {
   STARTER_PROMPT_BODY,
 } from "./init-templates.js";
 
-const EXPLICIT_MODEL_DRIVERS = new Set(["cursor", "copilot", "antigravity"]);
+const EXPLICIT_MODEL_DRIVERS = new Set(["cursor", "copilot", "antigravity", "grok-build"]);
 
 const InitOptionsSchema = z
   .object({
@@ -21,7 +21,15 @@ const InitOptionsSchema = z
     force: z.boolean().default(false),
     experiment: z.boolean().default(false),
     driver: z
-      .enum(["subprocess", "claude-code", "codex", "cursor", "copilot", "antigravity"])
+      .enum([
+        "subprocess",
+        "claude-code",
+        "codex",
+        "cursor",
+        "copilot",
+        "antigravity",
+        "grok-build",
+      ])
       .optional(),
     model: z.string().min(1).optional(),
   })

package/src/cli/program.ts

@@ -167,7 +167,15 @@ export const buildCli = () =>
         force: z.boolean().optional().describe("Overwrite existing files"),
         experiment: z.boolean().optional().describe("Also scaffold an optimization campaign"),
         driver: z
-          .enum(["subprocess", "claude-code", "codex", "cursor", "copilot", "antigravity"])
+          .enum([
+            "subprocess",
+            "claude-code",
+            "codex",
+            "cursor",
+            "copilot",
+            "antigravity",
+            "grok-build",
+          ])
           .optional()
           .describe("Starter driver (default: deterministic subprocess)"),
         model: nonEmptyString.optional().describe("Explicit subject model; required for Cursor"),

package/src/core/harness-catalogs/grok-build.ts

@@ -0,0 +1,19 @@
+import { defineHarnessCatalog } from "../harness-catalog.js";
+
+const efforts = ["low", "medium", "high", "xhigh"] as const;
+
+export const grokBuildCatalog = defineHarnessCatalog({
+  driver: "grok-build",
+  verified: "2026-09-24",
+  sources: [
+    "grok 1.0.40: models and ACP initialize modelState",
+    "https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/15-agent-mode.md",
+  ],
+  efforts,
+  models: {
+    "grok-4.7": efforts,
+    "grok-4.7-build-fast": efforts,
+    "grok-4.6": efforts,
+    "grok-4.5": ["low", "medium", "high"],
+  },
+});

package/src/core/harness-catalogs/index.ts

@@ -4,8 +4,16 @@ import { claudeCodeCatalog } from "./claude-code.js";
 import { codexCatalog } from "./codex.js";
 import { copilotCatalog } from "./copilot.js";
 import { cursorCatalog } from "./cursor.js";
+import { grokBuildCatalog } from "./grok-build.js";
 
-export { antigravityCatalog, claudeCodeCatalog, codexCatalog, copilotCatalog, cursorCatalog };
+export {
+  antigravityCatalog,
+  claudeCodeCatalog,
+  codexCatalog,
+  copilotCatalog,
+  cursorCatalog,
+  grokBuildCatalog,
+};
 
 export const builtInHarnessCatalogs = [
   claudeCodeCatalog,
@@ -13,6 +21,7 @@ export const builtInHarnessCatalogs = [
   copilotCatalog,
   cursorCatalog,
   antigravityCatalog,
+  grokBuildCatalog,
 ] as const;
 
 export type BuiltInHarnessCatalog = (typeof builtInHarnessCatalogs)[number];

package/src/drivers/claude-code/deferred-process.ts

@@ -0,0 +1,118 @@
+import { spawnManagedProcess } from "../../core/exec.js";
+import type { ParsedDriverEvent } from "../../core/index.js";
+
+type DeferredProcessOptions = {
+  command: string;
+  args: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  input?: string;
+  signal: AbortSignal;
+  idleTimeoutMs: number;
+  turnTimeoutMs?: number;
+  parse: (line: string) => ParsedDriverEvent | ParsedDriverEvent[] | null;
+  onEvent: (event: ParsedDriverEvent) => Promise<void>;
+};
+
+const MAX_LINE_BYTES = 10_000_000;
+const MAX_STDERR_CHARS = 10_000;
+
+/** Deliver progress live, but only resume or finish after the CLI has stopped writing. */
+export const runDeferredProcess = async (options: DeferredProcessOptions) => {
+  const managed = spawnManagedProcess(options.command, options.args, {
+    cwd: options.cwd,
+    env: options.env,
+    signal: options.signal,
+  });
+  let failure: Error | undefined;
+  let idleTimer: NodeJS.Timeout | undefined;
+  let turnTimer: NodeJS.Timeout | undefined;
+  let terminal: ParsedDriverEvent | undefined;
+  let stderr = "";
+  const clearTimers = () => {
+    clearTimeout(idleTimer);
+    clearTimeout(turnTimer);
+  };
+  const fail = (error: Error) => {
+    failure ??= error;
+    clearTimers();
+    void managed.terminate();
+  };
+  const bumpIdle = () => {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(
+      () => fail(new Error(`no event for ${options.idleTimeoutMs}ms`)),
+      options.idleTimeoutMs,
+    );
+  };
+  bumpIdle();
+  if (options.turnTimeoutMs !== undefined) {
+    turnTimer = setTimeout(
+      () => fail(new Error(`Claude turn exceeded ${options.turnTimeoutMs}ms elapsed time`)),
+      options.turnTimeoutMs,
+    );
+  }
+  managed.child.stderr.setEncoding("utf8");
+  managed.child.stderr.on("data", (chunk: string) => {
+    stderr = (stderr + chunk).slice(-MAX_STDERR_CHARS);
+  });
+  const handleLine = async (line: string) => {
+    if (failure || terminal || !line.trim()) return;
+    if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+      throw new Error(`stdout line exceeded ${MAX_LINE_BYTES} bytes`);
+    }
+    const parsed = options.parse(line);
+    if (!parsed) return;
+    const events = Array.isArray(parsed) ? parsed : [parsed];
+    if (events.length === 0) return;
+    bumpIdle();
+    for (const event of events) {
+      if (event.tag === "ready" || event.tag === "progress") await options.onEvent(event);
+      else {
+        terminal = event;
+        break;
+      }
+    }
+  };
+  managed.child.stdout.setEncoding("utf8");
+  const readOutput = async () => {
+    let pending = "";
+    try {
+      for await (const chunk of managed.child.stdout) {
+        pending += chunk;
+        let newline = pending.indexOf("\n");
+        while (newline !== -1) {
+          const line = pending.slice(0, newline);
+          pending = pending.slice(newline + 1);
+          await handleLine(line);
+          newline = pending.indexOf("\n");
+        }
+        if (Buffer.byteLength(pending) > MAX_LINE_BYTES) {
+          throw new Error(`stdout line exceeded ${MAX_LINE_BYTES} bytes`);
+        }
+      }
+      if (pending) await handleLine(pending);
+    } catch (error) {
+      fail(error instanceof Error ? error : new Error(String(error)));
+    }
+  };
+  const output = readOutput();
+  managed.child.stdin.end(options.input);
+  try {
+    await managed.spawned;
+    const result = await managed.exited;
+    await output;
+    if (failure) throw failure;
+    if (options.signal.aborted) throw new Error("Claude turn aborted");
+    if (result.signal) throw new Error(`claude exited from signal ${result.signal}`);
+    if (result.exitCode !== 0 && terminal?.tag !== "error") {
+      throw new Error(`claude exited ${result.exitCode}`);
+    }
+    return terminal;
+  } finally {
+    clearTimers();
+    await managed.terminate();
+    await output;
+    if (stderr.trim()) process.stderr.write(`[claude-code] ${stderr.trimEnd()}\n`);
+  }
+};

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

@@ -13,7 +13,6 @@ import {
   type DriverEventMap,
   defineDriver,
   discoverCliVersion,
-  exec,
   type ParsedDriverEvent,
   type ReadyState,
   type StartContext,
@@ -29,6 +28,7 @@ import {
 import { prepareClaudeExperimentConfig } from "../shared/experiment-policy.js";
 import { copyRegularFileNoFollow } from "../shared/secure-copy.js";
 import { subprocessDriver } from "../subprocess/index.js";
+import { runDeferredProcess } from "./deferred-process.js";
 import { ClaudeCodeLineSchema, makeParseEvent } from "./parse-events.js";
 
 const LUX_BOOKKEEPING_FILES = new Set([
@@ -107,13 +107,22 @@ export const ClaudeCodeDriverConfigSchema = z
      * when a weaker model asks in text instead of calling `askToolName`.
      */
     textQuestionFallback: z.boolean().default(false),
-    /** Per-event idle timeout. */
+    /** Maximum silence between recognized protocol events; excludes answerer wait time. */
     idleTimeoutMs: z.number().positive().default(600_000),
+    /** Optional elapsed-time cap per defer-resume CLI invocation, regardless of activity. */
+    turnTimeoutMs: z.number().positive().optional(),
     /** Cap on outstanding interrupts before the driver aborts. */
     maxInterrupts: z.number().positive().default(20),
   })
   .strict()
   .superRefine((config, ctx) => {
+    if (config.turnTimeoutMs !== undefined && config.interactionMode !== "defer-resume") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["turnTimeoutMs"],
+        message: "turnTimeoutMs requires defer-resume mode",
+      });
+    }
     if (config.interactionMode === "defer-resume") {
       const reserved = config.extraArgs?.find((arg) =>
         ["--input-format", "--no-session-persistence", "--resume", "-r", "--settings"].some(
@@ -522,6 +531,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;
@@ -620,7 +630,7 @@ class ClaudeCodeDriverImpl implements AgentDriver {
     // 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();
+    await this.quiesce();
     const artifacts = await walkArtifacts(this.collectDir);
     if (this.isolatedWorkspace && this.artifactsDir) {
       await Promise.all(
@@ -652,6 +662,7 @@ class ClaudeCodeDriverImpl implements AgentDriver {
 
   async quiesce(): Promise<void> {
     if (this.config.interactionMode === "defer-resume") {
+      this.deferredAbort.abort();
       await this.deferredTurn;
       return;
     }
@@ -661,6 +672,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 });
@@ -728,58 +740,47 @@ 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,
+    const terminal = await runDeferredProcess({
+      command: this.config.command,
+      args: 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) } : {}),
       },
-    );
-    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;
+      ...input,
+      idleTimeoutMs: this.config.idleTimeoutMs,
+      ...(this.config.turnTimeoutMs === undefined
+        ? {}
+        : { turnTimeoutMs: this.config.turnTimeoutMs }),
+      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> {

package/src/drivers/grok-build/README.md

@@ -0,0 +1,112 @@
+# Grok.build driver
+
+The `grok-build` driver runs the native Grok.build CLI over ACP (`grok agent
+--no-leader stdio`). Install Grok.build and run `grok login` first. This is
+separate from selecting a Grok model in the Copilot driver.
+
+```ts
+{
+  defaultDriver: {
+    name: "grok-build",
+    config: {
+      model: "grok-4.5",
+      reasoningEffort: "low",
+      permissionMode: "auto",
+      sandbox: "workspace",
+    },
+  },
+  defaultAnswerer: "persona",
+}
+```
+
+Or scaffold an eval project:
+
+```sh
+lux init --driver grok-build --model grok-4.5
+```
+
+An explicit model is required; effort defaults to `low`. Lux selects both through
+`session/set_config_option` and verifies the returned values before prompting.
+Grok 1.0.40 can choose a different model on `session/new` despite the CLI model
+flag, so passing that flag alone is insufficient.
+
+## Permissions
+
+The default `auto` mode uses Grok's native safety checks, including its LLM
+classifier, to approve routine operations. It is not blanket approval. `default`
+(ask) is also supported. Lux does not expose always-approve, arbitrary extra
+arguments, or the CLI `--allow`/`--deny` flags. In Grok 1.0.40, those rule flags
+are ignored by the agent subcommand. Project permission rules require Grok folder trust. Lux leaves
+`trustProject: false` by default; an untrusted fixture's rules are ignored by
+Grok. Enable `trustProject: true` only for reviewed fixtures: it also permits
+project configuration such as hooks and MCP servers. Then put native rules in
+`.grok/config.toml` and assert the expected denial. CLI `dontAsk` is also omitted because the ACP launch path does not propagate that
+policy.
+
+For example, this native rule denies the smoke test's command:
+
+```toml
+[[permission.rules]]
+action = "deny"
+tool = "bash"
+pattern = "printf *"
+```
+
+Change `action` to `"ask"` to exercise Lux's answerer explicitly. The live
+smoke task opts into trust only for its own generated ask/deny fixtures.
+
+ACP permission requests become Lux `approve` interrupts, including the tool
+call details. The configured answerer handles those requests; `persona` uses an
+LLM with the case's task and persona constraints. Lux selects only `allow_once`
+or `reject_once`, never a remembered grant. The persona parser accepts strict
+approval JSON either bare or in one complete JSON Markdown fence; ambiguous
+text and invalid fields still deny the operation. If the agent offers no matching
+one-operation option, Lux cancels and reports an error rather than widening the
+grant. Native auto decisions are handled inside Grok and are not Lux interrupts.
+
+Permission reviews have a separate `permissionTimeoutMs` (150 seconds by
+default), while ordinary inactivity uses `idleTimeoutMs` (10 minutes). Startup
+RPCs time out after 30 seconds. Cancelled turns, process failures, unanswered
+reviews, and turns ending with pending approvals cannot count as successful runs.
+A completed turn can still contain denied tool calls: assert the expected files
+or tool results to determine whether the task succeeded.
+
+## Scope and limitations
+
+Lux requests the native `workspace` sandbox and a private process with
+`--no-leader`. `read-only` and `strict` profiles are available; disabling the
+sandbox is not a driver option. The workspace profile allows filesystem reads,
+network access, and writes to the working directory, Grok state, and temporary
+directories. It is not configuration isolation: Grok still loads user/project
+settings, compatible Claude settings, hooks, skills, and MCP configuration.
+The driver reports configuration isolation, usage, and cost as unavailable;
+controlled experiments requiring those capabilities remain unsupported.
+
+The interaction surface currently supports tool permissions. Other ACP client
+requests receive an explicit unsupported-method response. Run evidence includes
+agent messages, reasoning, tool calls/results, and collected files. Use artifact
+assertions alongside `run-succeeded`.
+
+## Validation
+
+Synthetic tests cover explicit model/effort selection, one-operation approvals
+and rejections, refusal to substitute remembered grants, permission timeouts,
+process exit during review, cancellation, idle timeout, and cleanup.
+
+Live smoke validation uses Grok.build 1.0.40 with `grok-4.5` at low effort.
+
+The opt-in live smoke task runs three real evals: a local shell write under auto
+review, an explicit ask rule answered by Lux's LLM persona, and an explicit deny
+rule that must produce a failed tool result without creating the file. It
+requires Grok and Claude Code logins and consumes model usage. Evidence stays
+in the temporary directory printed by the task:
+
+```sh
+LUX_GROK_MODEL=grok-4.5 mise run smoke:grok-build
+```
+
+References:
+
+- [Grok ACP guide](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/15-agent-mode.md)
+- [Grok permissions](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/22-permissions-and-safety.md)
+- [Grok sandbox](https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/18-sandbox.md)

package/src/drivers/grok-build/config.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { applyCatalogEffort, grokBuildCatalog } from "../../core/index.js";
+
+export const GrokBuildDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("grok"),
+    model: z.string().min(1),
+    reasoningEffort: z.enum(grokBuildCatalog.efforts).default("low"),
+    permissionMode: z.enum(["auto", "default"]).default("auto"),
+    trustProject: z.boolean().default(false),
+    sandbox: z.enum(["workspace", "read-only", "strict"]).default("workspace"),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    startupTimeoutMs: z.number().int().positive().default(30_000),
+    idleTimeoutMs: z.number().int().positive().default(600_000),
+    permissionTimeoutMs: z.number().int().positive().default(150_000),
+    maxInterrupts: z.number().int().positive().default(20),
+    maxLineBytes: z.number().int().positive().default(10_000_000),
+    maxQueuedBytes: z.number().int().positive().default(20_000_000),
+    maxToolCalls: z.number().int().positive().default(10_000),
+  })
+  .strict()
+  .transform(applyCatalogEffort(grokBuildCatalog));
+
+export type GrokBuildDriverConfig = z.infer<typeof GrokBuildDriverConfigSchema>;
+
+export const buildGrokBuildArgs = (config: GrokBuildDriverConfig): string[] => [
+  "--permission-mode",
+  config.permissionMode,
+  "--sandbox",
+  config.sandbox,
+  ...(config.trustProject ? ["--trust"] : []),
+  "agent",
+  "--no-leader",
+  "--model",
+  config.model,
+  "--reasoning-effort",
+  config.reasoningEffort,
+  "stdio",
+];