@prismatic-io/lux 0.0.2-preview.18 → 0.0.2-preview.21

package/src/drivers/antigravity/events.ts

@@ -0,0 +1,235 @@
+import { z } from "zod";
+import {
+  type ParsedDriverEvent,
+  type TokenUsage,
+  toolCallProgress,
+  toolResultProgress,
+} from "../../core/index.js";
+import type { AntigravityDriverConfig } from "./config.js";
+
+const UsageSchema = z.object({
+  input_tokens: z.number().nonnegative().catch(0),
+  output_tokens: z.number().nonnegative().catch(0),
+  thinking_tokens: z.number().nonnegative().catch(0),
+  cache_read_tokens: z.number().nonnegative().catch(0),
+});
+
+const StepUpdateSchema = z.looseObject({
+  step_index: z.number().int().nonnegative(),
+  state: z.string().optional(),
+  step_type: z.string().optional(),
+  tool_name: z.string().optional(),
+  text_delta: z.string().optional(),
+  usage: z.unknown().optional(),
+  tool_info: z
+    .looseObject({
+      name: z.string().optional(),
+      parameters: z.unknown().optional(),
+      output: z.unknown().optional(),
+      error: z
+        .looseObject({ type: z.string().optional(), message: z.string().optional() })
+        .optional(),
+    })
+    .optional(),
+});
+
+const ResultSchema = z.looseObject({
+  conversation_id: z.string().optional(),
+  status: z.string().optional(),
+  response: z.string().optional(),
+  error: z.string().optional(),
+  num_turns: z.number().optional(),
+  usage: z.unknown().optional(),
+});
+
+const InitSchema = z.looseObject({
+  cwd: z.string().optional(),
+  tools: z.array(z.string()).optional(),
+  permission_mode: z.string().optional(),
+  model: z.string().optional(),
+  agent: z.string().optional(),
+});
+
+const AntigravityEventSchema = z.discriminatedUnion("event", [
+  z.looseObject({
+    event: z.literal("init"),
+    conversation_id: z.string().optional(),
+    init: InitSchema.optional(),
+  }),
+  z.looseObject({ event: z.literal("step_update"), step_update: StepUpdateSchema.optional() }),
+  z.looseObject({ event: z.literal("result"), result: ResultSchema.optional() }),
+]);
+
+const parseUsage = (raw: unknown): TokenUsage | null => {
+  const usage = UsageSchema.safeParse(raw).data;
+  if (!usage) return null;
+  return {
+    input: Math.max(0, usage.input_tokens - usage.cache_read_tokens),
+    output: usage.output_tokens + usage.thinking_tokens,
+    cacheRead: usage.cache_read_tokens,
+    cacheCreation: 0,
+  };
+};
+
+const outputText = (output: unknown): string => {
+  if (typeof output === "string") return output;
+  return output === undefined ? "" : JSON.stringify(output);
+};
+
+const waitingReason =
+  "Antigravity is waiting for a tool permission it cannot receive headlessly; allow the tool in its settings or set skipPermissions";
+
+type StepUpdate = z.infer<typeof StepUpdateSchema>;
+type ResultEvent = z.infer<typeof ResultSchema>;
+type InitEvent = z.infer<typeof AntigravityEventSchema> & { event: "init" };
+
+const readyEvent = (
+  event: InitEvent,
+  config: AntigravityDriverConfig,
+  cliVersion: string | undefined,
+): ParsedDriverEvent => ({
+  tag: "ready",
+  ready: {
+    agentId: "antigravity",
+    model: event.init?.model ?? config.model,
+    detail: {
+      transport: "stream-json",
+      ...(event.conversation_id ? { conversationId: event.conversation_id } : {}),
+      ...(cliVersion ? { cliVersion } : {}),
+      ...(event.init?.cwd ? { cwd: event.init.cwd } : {}),
+      ...(event.init?.tools ? { tools: event.init.tools } : {}),
+      ...(event.init?.permission_mode ? { permissionMode: event.init.permission_mode } : {}),
+      ...(event.init?.agent ? { agent: event.init.agent } : {}),
+      reasoningEffort: config.reasoningEffort,
+      modelResolution: event.init?.model ? "reported" : "requested",
+    },
+  },
+});
+
+const toolStepEvents = (
+  step: StepUpdate,
+  openTools: Set<number>,
+  ts: number,
+): ParsedDriverEvent[] => {
+  const toolUseId = `step-${step.step_index}`;
+  const name = step.tool_info?.name ?? step.tool_name ?? "tool";
+  const events: ParsedDriverEvent[] = [];
+  if (!openTools.has(step.step_index)) {
+    openTools.add(step.step_index);
+    events.push({
+      tag: "progress",
+      progress: toolCallProgress(
+        step.step_index,
+        { name, input: step.tool_info?.parameters ?? {}, toolUseId },
+        ts,
+      ),
+    });
+  }
+  if (step.state === "DONE") {
+    openTools.delete(step.step_index);
+    const error = step.tool_info?.error;
+    events.push({
+      tag: "progress",
+      progress: toolResultProgress(
+        step.step_index,
+        {
+          name,
+          toolUseId,
+          content: step.tool_info?.output ?? null,
+          isError: error !== undefined,
+          text: error?.message ?? outputText(step.tool_info?.output),
+        },
+        ts,
+      ),
+    });
+  }
+  return events;
+};
+
+const stepEvents = (
+  step: StepUpdate,
+  openTools: Set<number>,
+  ts: number,
+): ParsedDriverEvent | ParsedDriverEvent[] => {
+  if (step.step_type === "tool") return toolStepEvents(step, openTools, ts);
+  if (step.step_type === "agent_response" && step.text_delta) {
+    return {
+      tag: "progress",
+      progress: {
+        id: `antigravity-message-${step.step_index}-${ts}`,
+        kind: "agent-message",
+        payload: { text: step.text_delta },
+        ts,
+      },
+    };
+  }
+  return {
+    tag: "progress",
+    progress: {
+      id: `antigravity-step-${step.step_index}-${ts}`,
+      kind: "antigravity-step",
+      payload: step,
+      ts,
+    },
+  };
+};
+
+const resultEvent = (
+  result: ResultEvent | undefined,
+  conversationId: string | undefined,
+  usage: TokenUsage | null,
+): ParsedDriverEvent => {
+  if (result?.status === "SUCCESS") {
+    return {
+      tag: "done",
+      done: {
+        exitReason: "done",
+        summary: {
+          ...(conversationId ? { conversationId } : {}),
+          ...(result.response !== undefined ? { response: result.response } : {}),
+          ...(result.num_turns !== undefined ? { numTurns: result.num_turns } : {}),
+          ...(usage ? { usage } : { usageAvailability: "unavailable" }),
+        },
+      },
+    };
+  }
+  const status = result?.status ?? "UNKNOWN";
+  return {
+    tag: "error",
+    error: {
+      exitReason: "error",
+      reason:
+        status === "WAITING"
+          ? waitingReason
+          : `Antigravity ended with status ${status}${result?.error ? `: ${result.error}` : ""}`,
+      ...(usage ? { summary: { usage } } : {}),
+    },
+  };
+};
+
+export const makeParseEvent = (config: AntigravityDriverConfig, cliVersion?: string) => {
+  const openTools = new Set<number>();
+  let conversationId: string | undefined;
+  let usage: TokenUsage | null = null;
+  return (line: string): ParsedDriverEvent | ParsedDriverEvent[] | null => {
+    let raw: unknown;
+    try {
+      raw = JSON.parse(line);
+    } catch {
+      return null;
+    }
+    const parsed = AntigravityEventSchema.safeParse(raw);
+    if (!parsed.success) return null;
+    const event = parsed.data;
+    if (event.event === "init") {
+      conversationId = event.conversation_id;
+      return readyEvent(event, config, cliVersion);
+    }
+    if (event.event === "step_update") {
+      if (!event.step_update) return null;
+      usage = parseUsage(event.step_update.usage) ?? usage;
+      return stepEvents(event.step_update, openTools, Date.now());
+    }
+    return resultEvent(event.result, conversationId, parseUsage(event.result?.usage) ?? usage);
+  };
+};

package/src/drivers/antigravity/index.ts

@@ -0,0 +1,109 @@
+import {
+  type AgentDriver,
+  type Answer,
+  type Artifact,
+  type DriverEventMap,
+  defineDriver,
+  discoverCliVersion,
+  type ReadyState,
+  type StartContext,
+  selectModelAndReasoningEffort,
+} from "../../core/index.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+import { subprocessDriver } from "../subprocess/index.js";
+import {
+  type AntigravityDriverConfig,
+  AntigravityDriverConfigSchema,
+  buildAntigravityArgs,
+  formatAntigravityPrompt,
+} from "./config.js";
+import { makeParseEvent } from "./events.js";
+
+class AntigravityDriver implements AgentDriver {
+  private inner: AgentDriver | null = null;
+  private pendingAttach: Array<(inner: AgentDriver) => void> = [];
+  private cwd: string | null = null;
+  private artifactsDir: string | null = null;
+  private readonly config: AntigravityDriverConfig;
+
+  constructor(config: AntigravityDriverConfig) {
+    this.config = config;
+  }
+
+  on<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    if (this.inner) this.inner.on(event, handler);
+    else this.pendingAttach.push((inner) => inner.on(event, handler));
+  }
+
+  off<K extends keyof DriverEventMap>(event: K, handler: (e: DriverEventMap[K]) => void): void {
+    if (this.inner) this.inner.off(event, handler);
+    else this.pendingAttach.push((inner) => inner.off(event, handler));
+  }
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    if (this.inner) throw new Error("Antigravity driver cannot be started twice");
+    this.cwd = this.config.cwd ?? ctx.artifactsDir;
+    this.artifactsDir = ctx.artifactsDir;
+    const cliVersion = await discoverCliVersion(this.config.command);
+    const inner = await subprocessDriver.create({
+      command: this.config.command,
+      args: buildAntigravityArgs(this.config),
+      cwd: this.cwd,
+      env: this.config.env,
+      protocol: "custom",
+      parseEvent: makeParseEvent(this.config, cliVersion),
+      formatPrompt: formatAntigravityPrompt,
+      closeStdinAfterPrompt: true,
+      idleTimeoutMs: this.config.idleTimeoutMs,
+      maxLineBytes: this.config.maxLineBytes,
+      maxInterrupts: 1,
+    });
+    for (const attach of this.pendingAttach) attach(inner);
+    this.pendingAttach = [];
+    this.inner = inner;
+    return inner.start(ctx);
+  }
+
+  async respond(_answer: Answer): Promise<void> {
+    throw new Error("Antigravity headless sessions cannot receive mid-run responses");
+  }
+
+  async quiesce(): Promise<void> {
+    await this.inner?.close();
+  }
+
+  async collect(): Promise<Artifact[]> {
+    await this.quiesce();
+    if (!this.cwd) return [];
+    const artifacts = await walkArtifacts(this.cwd);
+    return this.cwd === this.artifactsDir
+      ? artifacts
+      : artifacts.map((artifact) => ({ ...artifact, root: this.cwd as string }));
+  }
+
+  async close(): Promise<void> {
+    await this.inner?.close();
+  }
+}
+
+export const antigravityDriver = defineDriver({
+  name: "antigravity",
+  configSchema: AntigravityDriverConfigSchema,
+  runtime: (config) => ({
+    commands: [config.command],
+    capabilities: {
+      interactive: false,
+      "tool-calls": true,
+      "tool-results": true,
+      artifacts: true,
+      usage: true,
+      cost: false,
+      isolation: false,
+    },
+  }),
+  selectHarness: selectModelAndReasoningEffort,
+  create: (config) => new AntigravityDriver(config),
+});
+
+export type { AntigravityDriverConfig };
+export { AntigravityDriverConfigSchema, buildAntigravityArgs, makeParseEvent };

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

@@ -7,6 +7,8 @@ import {
   type AgentDriver,
   type Answer,
   type Artifact,
+  applyCatalogEffort,
+  claudeCodeCatalog,
   DEFAULT_CLAUDE_MODEL,
   type DriverEventMap,
   defineDriver,
@@ -15,6 +17,7 @@ import {
   type ParsedDriverEvent,
   type ReadyState,
   type StartContext,
+  selectModelAndReasoningEffort,
   TypedEmitter,
 } from "../../core/index.js";
 import { walkArtifacts } from "../shared/artifacts.js";
@@ -74,13 +77,12 @@ export const ClaudeCodeDriverConfigSchema = z
     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"),
+    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(),
@@ -159,7 +161,8 @@ export const ClaudeCodeDriverConfigSchema = z
         message: `isolation owns ${reserved}; configure isolation instead`,
       });
     }
-  });
+  })
+  .transform(applyCatalogEffort(claudeCodeCatalog));
 
 export type ClaudeCodeDriverConfig = z.infer<typeof ClaudeCodeDriverConfigSchema>;
 
@@ -172,7 +175,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);
@@ -203,8 +206,15 @@ 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 = (
@@ -213,7 +223,7 @@ const buildDeferredArgs = (
   sessionId?: string,
 ): string[] => {
   const out = ["--print", "--output-format", "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);
@@ -881,6 +891,7 @@ export const claudeCodeDriver = defineDriver({
       };
     },
   },
+  selectHarness: selectModelAndReasoningEffort,
   create: (config) => new ClaudeCodeDriverImpl(config),
 });
 

package/src/drivers/codex/config.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { DEFAULT_CODEX_MODEL, ReasoningEffortSchema } from "../../core/index.js";
+import { applyCatalogEffort, codexCatalog, DEFAULT_CODEX_MODEL } from "../../core/index.js";
 
 export type CodexConfigValue =
   | string
@@ -28,7 +28,7 @@ export const CodexDriverConfigSchema = z
   .object({
     command: z.string().default("codex"),
     model: z.string().min(1).default(DEFAULT_CODEX_MODEL),
-    reasoningEffort: ReasoningEffortSchema.default("low"),
+    reasoningEffort: z.enum(codexCatalog.efforts).optional(),
     sandbox: z
       .enum(["read-only", "workspace-write", "danger-full-access"])
       .default("workspace-write"),
@@ -46,6 +46,8 @@ export const CodexDriverConfigSchema = z
     strictConfig: z.boolean().default(false),
     interactionMode: z.enum(["app-server", "exec"]).default("app-server"),
     approvalPolicy: z.enum(["untrusted", "on-request", "never"]).default("on-request"),
+    /** Native reviewer for eligible approvals; auto_review requires app-server and on-request. */
+    approvalsReviewer: z.enum(["user", "auto_review"]).default("user"),
     isolation: IsolationSchema.optional(),
     maxInterrupts: z.number().positive().default(20),
     maxLineBytes: z.number().positive().default(10_000_000),
@@ -53,6 +55,16 @@ export const CodexDriverConfigSchema = z
   })
   .strict()
   .superRefine((config, ctx) => {
+    if (
+      config.approvalsReviewer === "auto_review" &&
+      (config.interactionMode !== "app-server" || config.approvalPolicy !== "on-request")
+    ) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["approvalsReviewer"],
+        message: "auto_review requires app-server interaction mode and on-request approval policy",
+      });
+    }
     if (config.interactionMode === "app-server" && config.profile) {
       ctx.addIssue({
         code: "custom",
@@ -82,7 +94,13 @@ export const CodexDriverConfigSchema = z
         message: "isolation requires app-server interaction mode",
       });
     }
-  });
+  })
+  .transform(applyCatalogEffort(codexCatalog));
+
+const effortArgs = (config: CodexDriverConfig): string[] =>
+  config.reasoningEffort
+    ? ["--config", `model_reasoning_effort=${tomlValue(config.reasoningEffort)}`]
+    : [];
 
 export type CodexDriverConfig = z.infer<typeof CodexDriverConfigSchema>;
 
@@ -110,7 +128,7 @@ export const buildExecArgs = (config: CodexDriverConfig): string[] => {
   for (const [key, value] of Object.entries(config.config ?? {})) {
     args.push("--config", `${key}=${tomlValue(value)}`);
   }
-  args.push("--config", `model_reasoning_effort=${tomlValue(config.reasoningEffort)}`);
+  args.push(...effortArgs(config));
   if (config.extraArgs) args.push(...config.extraArgs);
   args.push("-");
   return args;
@@ -122,7 +140,7 @@ export const buildAppServerArgs = (config: CodexDriverConfig): string[] => {
   for (const [key, value] of Object.entries(config.config ?? {})) {
     args.push("--config", `${key}=${tomlValue(value)}`);
   }
-  args.push("--config", `model_reasoning_effort=${tomlValue(config.reasoningEffort)}`);
+  args.push(...effortArgs(config));
   if (config.extraArgs) args.push(...config.extraArgs);
   return args;
 };

package/src/drivers/codex/index.ts

@@ -12,6 +12,7 @@ import {
   discoverCliVersion,
   type ReadyState,
   type StartContext,
+  selectModelAndReasoningEffort,
   spawnManagedProcess,
   type TokenUsage,
   TypedEmitter,
@@ -189,7 +190,9 @@ class CodexAppServerDriverImpl implements AgentDriver {
       : [];
     const threadConfig: Record<string, CodexConfigValue> = {
       ...(this.config.config ?? {}),
-      model_reasoning_effort: this.config.reasoningEffort,
+      ...(this.config.reasoningEffort
+        ? { model_reasoning_effort: this.config.reasoningEffort }
+        : {}),
       ...(this.config.isolation
         ? {
             project_doc_max_bytes: 0,
@@ -212,13 +215,21 @@ class CodexAppServerDriverImpl implements AgentDriver {
       cwd,
       runtimeWorkspaceRoots: this.config.addDirs ?? [],
       approvalPolicy: this.config.approvalPolicy,
-      approvalsReviewer: "user",
+      approvalsReviewer: this.config.approvalsReviewer,
       ...(this.config.isolation
         ? { permissions: "lux-isolated" }
         : { sandbox: this.config.sandbox }),
       config: threadConfig,
       ephemeral: this.config.ephemeral,
     });
+    if (
+      this.config.approvalsReviewer === "auto_review" &&
+      started.approvalsReviewer !== "auto_review"
+    ) {
+      throw new Error(
+        "codex app-server did not enable the requested auto_review approvals reviewer",
+      );
+    }
     const thread = asRecord(started.thread);
     if (!thread || typeof thread.id !== "string") {
       throw new Error("codex app-server returned an invalid thread/start response");
@@ -229,6 +240,7 @@ class CodexAppServerDriverImpl implements AgentDriver {
       model: typeof started.model === "string" ? started.model : this.config.model,
       detail: {
         threadId: thread.id,
+        approvalsReviewer: this.config.approvalsReviewer,
         ...(typeof thread.sessionId === "string" ? { sessionId: thread.sessionId } : {}),
         ...(this.cliVersion ? { cliVersion: this.cliVersion } : {}),
       },
@@ -762,6 +774,7 @@ export const codexDriver = defineDriver({
     identity: (config, { rootDir }) =>
       configuredClaudeSourceHashes({ name: "codex", config }, rootDir),
   },
+  selectHarness: selectModelAndReasoningEffort,
   create: (config) =>
     config.interactionMode === "app-server"
       ? new CodexAppServerDriverImpl(config)

package/src/drivers/copilot/README.md

@@ -0,0 +1,52 @@
+# Copilot driver
+
+The `copilot` driver runs GitHub Copilot CLI as an Agent Client Protocol (ACP)
+server (`copilot --acp`). Install the CLI and run `copilot login` before Lux
+starts it. Your GitHub plan must allow Copilot CLI model access.
+
+```ts
+{
+  name: "copilot",
+  config: {
+    model: "YOUR_COPILOT_MODEL",
+    reasoningEffort: "low",
+    allowTools: ["shell(git:*)"],
+  },
+}
+```
+
+`model` is required because Copilot's `auto` selection can pick any model in
+the plan. Lux passes `--model` and `--effort` on the command line. Copilot's
+`--effort` accepts `none` through `max`, but each model honors only a subset
+and silently falls back on the rest, so the harness catalog in
+`core/harness-catalogs/copilot.ts` records the levels per model id and Lux
+rejects a level the model does not honor. Models whose levels are not published
+(Gemini, Grok, Kimi, MAI) are listed with no effort. When no effort is set, a
+model with levels runs at `low`. The session reports the requested model, not
+a confirmed one. `lux doctor` compares the catalog's model ids with
+`copilot help config` and warns when they differ.
+
+Tool permission requests arrive as ACP `session/request_permission` calls and
+become `approve` interrupts. Lux answers with the one-operation option only and
+never selects a remembered grant. `allowTools` and `denyTools` pass Copilot
+permission patterns; `allowAllTools` approves everything, which turns the
+interactive capability off. The `ask_user` tool is disabled by default because
+Copilot has no ACP wire for it; set `askUser: true` only when the harness can
+answer it another way.
+
+Copilot loads no `AGENTS.md` instructions and no bundled GitHub MCP server
+unless `customInstructions` or `builtinMcps` are enabled. Auto-update is always
+off. The driver provides no ambient-configuration isolation: Copilot still
+reads `~/.copilot` settings, MCP configuration, and credentials. Usage and
+cost are recorded as unknown; `--usage-output-file` cannot be combined with
+`--acp`.
+
+The adapter is covered by synthetic protocol and lifecycle tests. It has not
+been validated against an authenticated Copilot session.
+
+Protocol references:
+
+- [Copilot CLI command-line reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-programmatic-reference)
+- [Copilot CLI permissions](https://docs.github.com/en/copilot/concepts/agents/copilot-cli/about-copilot-cli)
+- [ACP session modes](https://agentclientprotocol.com/protocol/session-modes)
+- [ACP tool calls and permissions](https://agentclientprotocol.com/protocol/tool-calls)

package/src/drivers/copilot/config.ts

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { applyCatalogEffort, copilotCatalog } from "../../core/index.js";
+
+export const CopilotDriverConfigSchema = z
+  .object({
+    command: z.string().min(1).default("copilot"),
+    /** Copilot's catalog changes per plan; never inherit its `auto` selection. */
+    model: z.string().min(1),
+    reasoningEffort: z.enum(copilotCatalog.efforts).optional(),
+    mode: z.enum(["agent", "plan", "autopilot"]).default("agent"),
+    /** Permission patterns approved without an interrupt (`--allow-tool`). */
+    allowTools: z.array(z.string().min(1)).optional(),
+    denyTools: z.array(z.string().min(1)).optional(),
+    /** Approve every tool without interrupts; permissions stop being evidence. */
+    allowAllTools: z.boolean().default(false),
+    /** Keep the `ask_user` tool available; it is disabled by default because ACP has no wire for it. */
+    askUser: z.boolean().default(false),
+    /** Load AGENTS.md and related instruction files from the workspace. */
+    customInstructions: z.boolean().default(false),
+    /** Enable Copilot's bundled GitHub MCP server. */
+    builtinMcps: z.boolean().default(false),
+    addDirs: z.array(z.string()).optional(),
+    extraArgs: z.array(z.string()).optional(),
+    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),
+    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(copilotCatalog));
+
+export type CopilotDriverConfig = z.infer<typeof CopilotDriverConfigSchema>;
+
+export const buildCopilotArgs = (config: CopilotDriverConfig): string[] => [
+  "--acp",
+  "--no-auto-update",
+  "--model",
+  config.model,
+  ...(config.reasoningEffort ? ["--effort", config.reasoningEffort] : []),
+  ...(config.askUser ? [] : ["--no-ask-user"]),
+  ...(config.customInstructions ? [] : ["--no-custom-instructions"]),
+  ...(config.builtinMcps ? [] : ["--disable-builtin-mcps"]),
+  ...(config.allowAllTools ? ["--allow-all-tools"] : []),
+  ...(config.allowTools ?? []).map((tool) => `--allow-tool=${tool}`),
+  ...(config.denyTools ?? []).map((tool) => `--deny-tool=${tool}`),
+  ...(config.addDirs ?? []).flatMap((dir) => ["--add-dir", dir]),
+  ...(config.extraArgs ?? []),
+];
+
+export const COPILOT_MODE_IDS: Record<CopilotDriverConfig["mode"], string> = {
+  agent: "https://agentclientprotocol.com/protocol/session-modes#agent",
+  plan: "https://agentclientprotocol.com/protocol/session-modes#plan",
+  autopilot: "https://agentclientprotocol.com/protocol/session-modes#autopilot",
+};