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

package/src/core/platform-process.ts

@@ -81,11 +81,11 @@ const executableNames = (
   return [command, ...extensions.map((extension) => `${command}${extension.toLowerCase()}`)];
 };
 
-const resolveExecutable = (
+export const resolveExecutable = (
   command: string,
-  environment: NodeJS.ProcessEnv,
-  platform: SupportedPlatform,
-  cwd: string,
+  environment: NodeJS.ProcessEnv = process.env,
+  platform: SupportedPlatform = currentPlatform(),
+  cwd: string = process.cwd(),
 ): string | undefined => {
   if (isAbsolute(command) || command.includes("/") || command.includes("\\")) {
     const candidate = resolvePath(cwd, command);
@@ -175,10 +175,29 @@ const signalPosixGroup = (child: ChildProcess, signal: NodeJS.Signals): void =>
   }
 };
 
+const windowsAncestorPids = (
+  processes: readonly IProcessInfo[],
+  owner: { pid: number; ppid: number },
+): Set<number> => {
+  // Windows retains historical parent PIDs; reuse can make unrelated live
+  // processes appear beneath a new child. Never reap the caller's own ancestry.
+  const protectedPids = new Set([owner.pid]);
+  const byPid = new Map(processes.map((entry) => [entry.pid, entry]));
+  let ancestorPid = owner.ppid;
+  while (ancestorPid > 0 && !protectedPids.has(ancestorPid)) {
+    protectedPids.add(ancestorPid);
+    ancestorPid = byPid.get(ancestorPid)?.ppid ?? 0;
+  }
+  return protectedPids;
+};
+
 export const windowsDescendants = (
   rootPid: number,
   processes: readonly IProcessInfo[],
+  owner: { pid: number; ppid: number } = process,
 ): IProcessInfo[] => {
+  const protectedPids = windowsAncestorPids(processes, owner);
+  if (!validWindowsPid(rootPid) || protectedPids.has(rootPid)) return [];
   const descendants: IProcessInfo[] = [];
   const parentPids = new Set([rootPid]);
   let found = true;
@@ -186,6 +205,8 @@ export const windowsDescendants = (
     found = false;
     for (const candidate of processes) {
       if (
+        validWindowsPid(candidate.pid) &&
+        !protectedPids.has(candidate.pid) &&
         !parentPids.has(candidate.pid) &&
         parentPids.has(candidate.ppid) &&
         !descendants.some((descendant) => descendant.pid === candidate.pid)
@@ -200,17 +221,33 @@ export const windowsDescendants = (
   return root ? [root, ...descendants] : descendants;
 };
 
-const windowsProcessList = async (pid: number): Promise<IProcessInfo[]> => {
+const windowsProcessList = async (): Promise<IProcessInfo[]> => {
   const { getAllProcesses } = await import("@vscode/windows-process-tree");
   return new Promise((resolve) => {
-    getAllProcesses((processes) => resolve(windowsDescendants(pid, processes)));
+    getAllProcesses(resolve);
   });
 };
 
-const forceWindowsTree = async (pid: number): Promise<void> => {
+export const forceWindowsTree = async (
+  pid: number,
+  discover: (pid: number) => Promise<IProcessInfo[]> = windowsProcessList,
+  signal: (pid: number) => void = signalWindowsProcess,
+  discoveryTimeoutMs = 2_000,
+  stillOwned: () => boolean = () => true,
+): Promise<void> => {
+  if (!stillOwned() || !safeWindowsSignalTarget(pid)) return;
   let processes: IProcessInfo[] = [];
+  let timer: NodeJS.Timeout | undefined;
   try {
-    processes = await windowsProcessList(pid);
+    processes = await Promise.race([
+      Promise.resolve().then(() => discover(pid)),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error(`process discovery timed out after ${discoveryTimeoutMs}ms`)),
+          discoveryTimeoutMs,
+        );
+      }),
+    ]);
   } catch (error) {
     process.emitWarning(
       `Windows descendant discovery failed; only the direct child can be terminated: ${
@@ -218,12 +255,25 @@ const forceWindowsTree = async (pid: number): Promise<void> => {
       }`,
       { code: "LUX_WINDOWS_PROCESS_DISCOVERY" },
     );
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+  // Discovery is asynchronous; an exited leader can already have a recycled PID.
+  if (!stillOwned() || windowsAncestorPids(processes, process).has(pid)) return;
+  const descendants = windowsDescendants(pid, processes);
+  for (const process of descendants.toReversed()) {
+    if (safeWindowsSignalTarget(process.pid)) signal(process.pid);
   }
-  for (const process of processes.toReversed()) signalWindowsProcess(process.pid);
-  if (!processes.some((process) => process.pid === pid)) signalWindowsProcess(pid);
+  if (!descendants.some((process) => process.pid === pid)) signal(pid);
 };
 
+const validWindowsPid = (pid: number): boolean => Number.isSafeInteger(pid) && pid > 0;
+
+const safeWindowsSignalTarget = (pid: number): boolean =>
+  validWindowsPid(pid) && pid !== process.pid && pid !== process.ppid;
+
 const signalWindowsProcess = (pid: number): void => {
+  if (!safeWindowsSignalTarget(pid)) return;
   try {
     process.kill(pid, "SIGKILL");
   } catch {
@@ -252,19 +302,18 @@ export const posixProcessPlatform = (
 });
 
 export const windowsProcessPlatform = (
-  forceTree: (pid: number) => Promise<void> = forceWindowsTree,
+  forceTree: (pid: number, stillOwned: () => boolean) => Promise<void> = (pid, stillOwned) =>
+    forceWindowsTree(pid, undefined, undefined, undefined, stillOwned),
 ): ProcessPlatform => ({
   detached: false,
   processTreeFor: (child) => {
     const pid = child.pid;
     let forced: Promise<void> | undefined;
+    const stillOwned = (): boolean => child.exitCode == null && child.signalCode == null;
     const forceOnce = (): Promise<void> => {
       if (forced) return forced;
-      const leaderHasExited =
-        (child.exitCode !== null && child.exitCode !== undefined) ||
-        (child.signalCode !== null && child.signalCode !== undefined);
-      if (pid === undefined || leaderHasExited) forced = Promise.resolve();
-      else forced = forceTree(pid);
+      if (pid === undefined || !stillOwned()) forced = Promise.resolve();
+      else forced = forceTree(pid, stillOwned);
       return forced;
     };
     return {

package/src/core/reference-defaults.ts

@@ -0,0 +1,47 @@
+import type { AnswererRef, DriverRef } from "./case.js";
+import { mergePluginConfig } from "./harness-matrix.js";
+
+export const withDriverDefaults = (
+  reference: DriverRef | undefined,
+  defaults: Record<string, unknown> | undefined,
+): DriverRef | undefined => {
+  if (!reference || !defaults) return reference;
+  const selected = typeof reference === "string" ? { name: reference } : reference;
+  return { ...selected, config: mergePluginConfig(defaults, selected.config) };
+};
+
+export const mergeDriverReference = (
+  base: DriverRef | undefined,
+  local: DriverRef | undefined,
+): DriverRef | undefined => {
+  if (local === undefined) return base;
+  if (base === undefined) return local;
+  const first = typeof base === "string" ? { name: base } : base;
+  const second = typeof local === "string" ? { name: local } : local;
+  if (first.name !== second.name) return local;
+  return {
+    name: second.name,
+    config: mergePluginConfig(first.config, second.config),
+    ...((second.execution ?? first.execution)
+      ? { execution: second.execution ?? first.execution }
+      : {}),
+  };
+};
+
+export const mergeAnswererReference = (
+  base: AnswererRef | undefined,
+  local: AnswererRef | undefined,
+): AnswererRef | undefined => {
+  const merged = mergeDriverReference(base, local);
+  if (typeof merged !== "object" || merged.name !== "persona") return merged;
+  const first = typeof base === "object" ? base.config : undefined;
+  const second = typeof local === "object" ? local.config : undefined;
+  if (!first || !second || typeof first !== "object" || typeof second !== "object") return merged;
+  if (!("provider" in second) || ("provider" in first && second.provider === first.provider))
+    return merged;
+  const config = { ...(merged.config as Record<string, unknown>) };
+  for (const key of ["model", "command", "reasoningEffort"]) {
+    if (!(key in second)) delete config[key];
+  }
+  return { name: merged.name, config };
+};

package/src/core/run.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
+import { ActionTimingSchema } from "./action-events.js";
+import { AgentActivitySchema } from "./agent-activity.js";
 import { EvalCaseSchema } from "./case.js";
 import { ArtifactSchema } from "./driver.js";
+import { DriverMetricsSchema } from "./driver-metrics.js";
+import { EnvironmentDeclarationSchema } from "./environment.js";
 import { ErrorEventReasonSchema, ReadyStateSchema, RunEventSchema } from "./events.js";
 import { ToolOutcomeSummarySchema } from "./tool-events.js";
 import { RunUsageSchema } from "./usage.js";
@@ -24,7 +28,24 @@ export const RunProvenanceSchema = z.object({
     arch: z.string(),
     node: z.string(),
     bun: z.exactOptional(z.string()),
+    host: z.exactOptional(
+      z.object({
+        osRelease: z.string(),
+        cpuModels: z.array(z.string()),
+        logicalCpuCount: z.number().int().nonnegative(),
+        availableParallelism: z.number().int().positive(),
+        totalMemoryBytes: z.number().int().nonnegative(),
+      }),
+    ),
   }),
+  environment: z.exactOptional(
+    z.object({
+      /** Declared by the author, not independently verified or enforced by Lux. */
+      declared: z.exactOptional(EnvironmentDeclarationSchema),
+      /** Effective Lux worker limit for this run's suite; direct runs use one. */
+      concurrency: z.number().int().positive(),
+    }),
+  ),
   source: z.exactOptional(
     z.object({
       /** Case path relative to its repository root, when one was found. */
@@ -49,6 +70,8 @@ export const RunProvenanceSchema = z.object({
   fixturesHash: z.exactOptional(z.string()),
   subjectHash: z.exactOptional(z.string()),
   profileId: z.exactOptional(z.string()),
+  /** Harness matrix permutation (`driver:model:effort`) this run was filed under. */
+  permutationId: z.exactOptional(z.string()),
   experimentId: z.exactOptional(z.string()),
   variantId: z.exactOptional(z.string()),
   candidateId: z.exactOptional(z.string()),
@@ -103,6 +126,8 @@ export const RunMetadataSchema = z.object({
    * eval overhead.
    */
   usage: RunUsageSchema,
+  /** Absent in older records; zero alone did not establish availability. */
+  agentUsageAvailability: z.exactOptional(z.enum(["reported", "unavailable"])),
   modelAccounting: z.exactOptional(
     z.object({
       agentCalls: z.number().int().nonnegative(),
@@ -112,6 +137,8 @@ export const RunMetadataSchema = z.object({
     }),
   ),
   cost: z.exactOptional(z.object({ usd: z.exactOptional(z.number()) })),
+  /** Driver-defined scalar measurements with display and optimization semantics. */
+  driverMetrics: z.exactOptional(DriverMetricsSchema),
   interruptCounts: z.object({ ask: z.number(), approve: z.number(), custom: z.number() }),
   /** Legacy raw count of progress events whose kind is `tool-call`. */
   toolCallCount: z.exactOptional(z.number()),
@@ -124,6 +151,10 @@ export const RunMetadataSchema = z.object({
   ),
   /** Wall-clock per phase, derived from the lifecycle event stream. */
   phaseDurationMs: z.exactOptional(PhaseDurationsSchema),
+  /** Driver-reported semantic action latency, measured from `start-driver`. */
+  actionTiming: z.exactOptional(ActionTimingSchema),
+  /** Per-agent lifecycle and activity derived from the attributed event stream. */
+  agentActivity: z.exactOptional(z.array(AgentActivitySchema)),
   /**
    * Harness/infrastructure failure that invalidates this run as candidate
    * evidence. A driver-reported subject failure intentionally leaves this

package/src/core/usage.ts

@@ -121,3 +121,11 @@ export const parseAgentUsage = (raw: unknown): TokenUsage | null => {
   if (!AGENT_USAGE_KEYS.some((key) => key in raw)) return null;
   return AgentUsageSchema.safeParse(raw).data ?? null;
 };
+
+/** Legacy nonzero counts remain usable; legacy zero counts are unknown. */
+export const hasAgentUsage = (metadata: {
+  usage: RunUsage;
+  agentUsageAvailability?: "reported" | "unavailable";
+}): boolean =>
+  metadata.agentUsageAvailability === "reported" ||
+  (metadata.agentUsageAvailability === undefined && !isUsageEmpty(metadata.usage.agent));

package/src/drivers/antigravity/README.md

@@ -0,0 +1,171 @@
+# Antigravity driver
+
+The `antigravity` driver runs Google Antigravity CLI (`agy`) in its headless
+streaming mode: `agy --input-format stream-json --output-format stream-json`.
+Install the CLI and sign in before Lux starts it; headless runs fail with
+`authentication required` when no cached credential exists.
+
+```ts
+{
+  name: "antigravity",
+  config: {
+    model: "YOUR_ANTIGRAVITY_MODEL",
+    reasoningEffort: "low",
+  },
+}
+```
+
+`model` is required and Lux never inherits the CLI default. Use a base slug
+such as `gemini-3.8-flash`; `reasoningEffort` takes Antigravity's own `low`,
+`medium`, or `high` and selects that variant through `--effort`. The harness
+catalog in `core/harness-catalogs/antigravity.ts` lists which levels each model
+offers (Gemini Flash has three, Gemini 3.1 Pro has `low` and `high`, Claude and
+GPT-OSS have none), and an effort outside that list is rejected before the CLI
+starts. When no effort is set, a model with levels runs at `low`.
+
+Lux writes one `user` event with the case prompt, closes stdin, and reads
+`init`, `step_update`, and `result` events. Tool steps become paired
+`tool-call` and `tool-result` events keyed by step index, response deltas become
+`agent-message` progress, other steps stay visible as `antigravity-step`
+progress, and the final `result` usage is recorded as agent usage. The terminal
+response is also retained as message evidence when it was not already streamed.
+Both `DONE` and `ERROR` tool steps close the corresponding tool call; failed
+steps retain their error message. A result with `denied_actions` is an error even
+when Antigravity reports `SUCCESS`. `WAITING` and other non-success statuses are
+also errors. Configure the required scoped permissions for the
+headless evaluation; Lux does not retry a denial with broader permissions.
+
+Lux explicitly selects `mode: "accept-edits"` for coding tasks. Set `mode: "plan"`
+for planning runs. On Antigravity 1.2.10, omitting `--mode` can leave terminal
+workspaces read-only even when native file tools can edit them and scoped write
+grants exist. `accept-edits` permits workspace writes within the terminal sandbox;
+it does not disable that sandbox or authorize outside-sandbox execution.
+
+## Run-scoped configuration
+
+Lux can own the CLI settings for a run:
+
+```ts
+{
+  name: "antigravity",
+  config: {
+    model: "gemini-3.1-pro",
+    reasoningEffort: "low",
+    sandbox: true,
+    permissionMode: "proceed-in-sandbox",
+    permissions: { allow: ["read_url(registry.npmjs.org)"] },
+  },
+}
+```
+
+This mode gives only the child process a private home directory. Lux writes
+`enableTerminalSandbox: true`, `toolPermission: "proceed-in-sandbox"`, and the
+configured `permissions` there. It does not edit the user's settings, copy their
+history/plugins, or reuse their project records. Concurrent runs get distinct
+homes. `permissionMode: "inherit"` is the default and preserves the previous
+behavior. Scoped mode requires `sandbox: true`, rejects `skipPermissions: true`
+and a host `project`, and supports scoped `allow`, `deny`, and `ask` lists.
+
+Authentication must work in that private home. An inherited `GEMINI_API_KEY` is
+passed to the CLI. For file-based OAuth, Lux copies only the CLI's
+`antigravity-oauth-token` into the private runtime, using the normal CLI token
+path by default or an explicit `authTokenFile`. The copy has mode 0600 inside
+a mode-0700 runtime directory; token refresh cannot modify the source file.
+On macOS, `reuseKeychain: true` explicitly opts into reading Antigravity’s own
+Keychain entry (service `gemini`, account `antigravity`) when the default token
+file is absent. Lux writes that credential only to the private runtime and
+removes it on close. This option defaults to false. Do not put secret values in
+committed Lux configuration.
+
+Before deleting a private runtime, Lux snapshots native deliverables from its
+`brain` directory under `antigravity-artifacts/` in the task artifacts. This keeps
+handoff documents available to graders even when the final response only links
+to them. Hidden CLI logs, revision copies, metadata, and symlinks are excluded;
+collection fails explicitly above 500 files or 32 MiB. Existing user-home brain
+history is never scanned in inherited mode.
+
+The runtime is outside task artifacts and removed on driver close, collection,
+and startup failure. A force-killed Lux process cannot run cleanup; private
+runtime directories have the `lux-antigravity-home-` prefix in the OS temp root.
+This is configuration separation, not a complete OS security boundary; the
+driver continues declaring `isolation: false`.
+
+Grant scoped file and documentation access as needed, including read access to
+language runtimes installed outside system directories. `command(...)` allow
+rules can authorize outside-sandbox execution too. Keep them absent when that
+execution must remain unapproved; `unsandboxed(...)` rules were ignored in the
+observed macOS CLI. The terminal sandbox and native file-tool permissions are
+separate. Extra CLI arguments remain caller-controlled.
+
+Each run creates a fresh Antigravity project and passes its canonical working
+directory through `--add-dir` and an explicit task-workspace prompt preamble.
+Set `project` to reuse an explicitly configured
+project, and `addDirs` for additional reference directories. Process cwd alone
+does not select an Antigravity project. Project selection does not grant tool
+permissions: Antigravity 1.2.10 can still deny workspace writes in headless mode.
+`skipPermissions` remains false by default and must be explicitly enabled to
+bypass tool permission checks.
+
+The headless protocol carries no user questions or permission prompts, so the
+driver is not interactive. In inherited mode, Antigravity still reads user
+settings and conversation history. Controlled experiments are not
+declared.
+
+Regression tests cover the `ERROR` tool step followed by `SUCCESS` with denied
+actions observed in an authenticated Antigravity 1.2.10 session.
+
+## Live readiness checks
+
+From a Lux checkout, after installing locked dependencies and authenticating `agy`:
+
+```sh
+LUX_ANTIGRAVITY_MODEL=gemini-3.1-pro mise run smoke:antigravity
+```
+
+This opt-in smoke test consumes model usage. It runs four bounded checks in
+fresh artifact workspaces: a tool-free protocol response, a Node write/read
+check, native handoff-document capture, and a local HTTP server/client check. It stops on the first failure and
+retains events, fixtures, and results under `.lux-runs/antigravity-smoke/`.
+After building, select one stage with
+`LUX_ANTIGRAVITY_MODEL=gemini-3.1-pro node scripts/smoke-antigravity.mjs protocol`
+(or `workspace` / `artifact` / `loopback`); `--list` makes no model calls.
+
+The script uses `permissionMode: "proceed-in-sandbox"` with scoped read access to
+the running Node installation, plus localhost grants for the loopback stage.
+It never changes global settings. Authenticate
+with an inherited `GEMINI_API_KEY`, a normal CLI OAuth token file, or
+`LUX_ANTIGRAVITY_AUTH_TOKEN_FILE` pointing to such a file. To opt into macOS
+Keychain reuse, set `LUX_ANTIGRAVITY_REUSE_KEYCHAIN=1`. On macOS with CLI 1.2.12,
+private-runtime authentication and sandboxed file writes passed on 2026-09-29.
+The loopback check failed with `connect EPERM 127.0.0.1`; its missing fixture
+evidence correctly failed the smoke test despite normal agent completion.
+
+`--sandbox` alone does not select an execution policy: a native 1.2.12 probe on
+macOS with only `enableTerminalSandbox: true` denied the command, then returned
+`SUCCESS` with empty text and `denied_actions`. Lux correctly classifies that
+result as an error. A separate tool-free live probe passed in inherited mode;
+it does not establish private-runtime authentication.
+
+A passing protocol check establishes authentication and streaming only.
+Workspace and loopback checks require fixture-produced evidence; a completed
+agent response alone cannot pass them. These checks do not establish skill
+quality, package-install access, or complete sandbox isolation. Scoped access
+to a runtime outside system directories may also be necessary.
+
+On macOS, native 1.2.11 probes could write/build in editing mode but could
+not connect to their own loopback HTTP server: direct connections returned
+`EPERM`, and proxy requests rejected literal IPs or nonstandard HTTP ports.
+That failure occurred without Lux. Recheck the installed CLI with `loopback`
+before running suites that depend on local HTTP fixtures. Domain grants alone
+have not been shown to resolve this restriction. Keep a native reproduction
+separate from driver traces when diagnosing it; do not treat it as skill failure
+or bypass the sandbox to obtain a passing score.
+
+Protocol references:
+
+- [Antigravity CLI headless mode](https://antigravity.google/docs/cli/headless/)
+- [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli)
+
+- [Antigravity terminal sandbox](https://antigravity.google/docs/sandbox?tab=cli)
+- [CLI settings reference](https://antigravity.google/docs/cli/reference/)
+- [Native artifacts](https://antigravity.google/docs/cli/artifacts/)

package/src/drivers/antigravity/artifacts.ts

@@ -0,0 +1,37 @@
+import { readFile, realpath } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { writeArtifactSnapshot } from "../../core/artifact-snapshot.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+
+export const captureAntigravityArtifacts = async (
+  home: string,
+  destination: string,
+): Promise<void> => {
+  const brain = join(home, ".gemini/antigravity-cli/brain");
+  let root: string;
+  try {
+    root = await realpath(brain);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  if (!root.startsWith(`${await realpath(home)}${sep}`))
+    throw new Error("Antigravity artifact directory escaped its private runtime");
+  // Native revisions and CLI bookkeeping are not authored deliverables.
+  const artifacts = (await walkArtifacts(brain)).filter(
+    ({ path }) => !/\.(?:metadata\.json|resolved(?:\.\d+)?)$/.test(path),
+  );
+  if (!artifacts.length) return;
+  const maxBytes = 32 * 1024 * 1024;
+  if (artifacts.reduce((total, artifact) => total + (artifact.size ?? 0), 0) > maxBytes)
+    throw new Error("Antigravity native artifacts exceed the 32 MiB collection limit");
+  const files = Object.fromEntries(
+    await Promise.all(artifacts.map(async ({ path }) => [path, await readFile(join(brain, path))])),
+  );
+  await writeArtifactSnapshot({
+    artifactsDir: destination,
+    name: "antigravity-artifacts",
+    files,
+    maxBytes,
+  });
+};

package/src/drivers/antigravity/config.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+import { InheritEnvironmentSchema } from "../../core/agent-environment.js";
+import { DurationSchema } from "../../core/duration.js";
+import { antigravityCatalog, applyCatalogEffort } from "../../core/index.js";
+
+export const AntigravityDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("agy"),
+    /** Antigravity model slugs often bake in an effort; never inherit the CLI default. */
+    model: z.string().min(1),
+    /** Pin coding mode: an inherited plan mode makes sandboxed workspaces read-only. */
+    mode: z.enum(["accept-edits", "plan"]).default("accept-edits"),
+    reasoningEffort: z.enum(antigravityCatalog.efforts).optional(),
+    agent: z.string().min(1).optional(),
+    /** Use an existing project; otherwise each run creates a fresh project. */
+    project: z.string().min(1).optional(),
+    addDirs: z.array(z.string().min(1)).default([]),
+    /**
+     * Auto-approve every tool permission. Off by default: a headless turn that
+     * needs approval can report WAITING or SUCCESS with denied_actions; both fail.
+     */
+    skipPermissions: z.boolean().default(false),
+    /** Enable Antigravity's terminal sandbox restrictions. */
+    sandbox: z.boolean().default(false),
+    /** Own the CLI settings in a private runtime home instead of changing user settings. */
+    permissionMode: z.enum(["inherit", "proceed-in-sandbox"]).default("inherit"),
+    permissions: z
+      .object({
+        allow: z.array(z.string().min(1)).default([]),
+        deny: z.array(z.string().min(1)).default([]),
+        ask: z.array(z.string().min(1)).default([]),
+      })
+      .strict()
+      .optional(),
+    /** Optional CLI-format OAuth token file for the private runtime; never logged. */
+    authTokenFile: z.string().min(1).optional(),
+    /** Explicitly authorize copying this application's macOS Keychain credential. */
+    reuseKeychain: z.boolean().default(false),
+    cwd: z.string().optional(),
+    env: z.record(z.string(), z.string()).optional(),
+    inheritEnv: InheritEnvironmentSchema.optional(),
+    extraArgs: z.array(z.string()).optional(),
+    idleTimeout: DurationSchema.default("10 minutes"),
+    maxLineBytes: z.number().positive().default(10_000_000),
+  })
+  .strict()
+  .superRefine((config, ctx) => {
+    if (config.permissionMode === "proceed-in-sandbox") {
+      if (!config.sandbox || config.skipPermissions)
+        ctx.addIssue({
+          code: "custom",
+          message: "proceed-in-sandbox requires sandbox: true and skipPermissions: false",
+        });
+      if (config.project)
+        ctx.addIssue({
+          code: "custom",
+          path: ["project"],
+          message: "A private Antigravity runtime cannot reuse a host project",
+        });
+    } else if (config.permissions || config.authTokenFile || config.reuseKeychain) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          "permissions, authTokenFile, and reuseKeychain require permissionMode: proceed-in-sandbox",
+      });
+    }
+  })
+  .transform(applyCatalogEffort(antigravityCatalog));
+
+export type AntigravityDriverConfig = z.infer<typeof AntigravityDriverConfigSchema>;
+
+export const buildAntigravityArgs = (config: AntigravityDriverConfig, cwd?: string): string[] => [
+  "--input-format",
+  "stream-json",
+  "--output-format",
+  "stream-json",
+  "--model",
+  config.model,
+  "--mode",
+  config.mode,
+  ...(config.project ? ["--project", config.project] : ["--new-project"]),
+  ...(cwd ? ["--add-dir", cwd] : []),
+  ...config.addDirs.flatMap((directory) => ["--add-dir", directory]),
+  ...(config.reasoningEffort ? ["--effort", config.reasoningEffort] : []),
+  ...(config.agent ? ["--agent", config.agent] : []),
+  ...(config.skipPermissions ? ["--dangerously-skip-permissions"] : []),
+  ...(config.sandbox ? ["--sandbox"] : []),
+  ...(config.extraArgs ?? []),
+];
+
+export const formatAntigravityPrompt = (prompt: string): string =>
+  JSON.stringify({ event: "user", message: { content: prompt } });