omp-multi-harness 0.1.0

package/src/agents/claude.ts

@@ -0,0 +1,226 @@
+/**
+ * Claude Code adapter. Every Claude flag in this project lives in this file.
+ * Verified against Claude Code 2.1.274 (_spec/04-claude-adapter.md).
+ */
+import { randomUUID } from "node:crypto";
+import type { AgentConfig } from "../config/schema.ts";
+import { JsonlReader } from "../process/jsonl.ts";
+import {
+	AgentError,
+	authRequired,
+	cancelled,
+	invalidCwd,
+	invalidOutput,
+	looksLikeAuthFailure,
+	processFailed,
+	providerLimit,
+	timedOut,
+} from "../process/process-error.ts";
+import { resolveExecutable } from "../process/executable.ts";
+import { SpawnCwdError, spawnAgent } from "../process/spawn-agent.ts";
+import { detect } from "./availability.ts";
+import { isQuotaFailure } from "./codex-events.ts";
+import { applyClaudeEvent, newClaudeStreamState } from "./claude-events.ts";
+import { MODE_DEFAULT_READ_ONLY, type AgentRequest, type AgentResult, type AgentRunOptions, type ExternalAgent } from "./types.ts";
+
+/** Tools a read-only run may use. Anything that writes is simply absent. */
+export const READ_ONLY_TOOLS = ["Read", "Grep", "Glob"] as const;
+
+export interface ClaudeCapabilities {
+	supportsStreamJson: boolean;
+	requiresVerboseWithStreamJson: boolean;
+	supportsSessionId: boolean;
+	supportsPermissionMode: boolean;
+}
+
+/** Unknown or newer versions get the newest known capability set. */
+export function claudeCapabilities(_version: string | undefined): ClaudeCapabilities {
+	return {
+		supportsStreamJson: true,
+		// Verified on 2.1.274: stream-json under -p needs --verbose.
+		requiresVerboseWithStreamJson: true,
+		supportsSessionId: true,
+		supportsPermissionMode: true,
+	};
+}
+
+export interface BuildClaudeArgsInput {
+	request: AgentRequest;
+	config: AgentConfig;
+	capabilities: ClaudeCapabilities;
+	readOnly: boolean;
+	/** Caller-generated UUID used for a new session. */
+	sessionId: string;
+	/** Branch instead of continuing when resuming. */
+	fork?: boolean;
+}
+
+/**
+ * Build argv for `claude -p`. Two things are deliberately absent:
+ * the prompt (stdin) and the working directory (Claude Code has no -C; the spawn cwd
+ * carries it).
+ */
+export function buildClaudeArgs(input: BuildClaudeArgsInput): string[] {
+	const { request, config, capabilities, readOnly, sessionId, fork } = input;
+	const args: string[] = ["-p"];
+
+	if (capabilities.supportsStreamJson) {
+		args.push("--output-format", "stream-json");
+		if (capabilities.requiresVerboseWithStreamJson) args.push("--verbose");
+	} else {
+		args.push("--output-format", "json");
+	}
+
+	if (request.sessionId) {
+		args.push("--resume", request.sessionId);
+		if (fork) args.push("--fork-session");
+	} else if (capabilities.supportsSessionId) {
+		// Generating the id ourselves makes the OMP↔worker mapping known before the process
+		// starts, and survives a crash mid-run.
+		args.push("--session-id", sessionId);
+	}
+
+	if (readOnly && capabilities.supportsPermissionMode) {
+		args.push("--permission-mode", "plan");
+		args.push("--tools", READ_ONLY_TOOLS.join(","));
+	} else if (!readOnly && config.acceptEdits && capabilities.supportsPermissionMode) {
+		args.push("--permission-mode", "acceptEdits");
+	}
+	// else: readOnly was requested but this capability set cannot enforce it — no flag is
+	// emitted, and claudeReadOnlyEnforcement() below will honestly report `false` for it.
+
+	const model = request.model ?? config.model;
+	if (model) args.push("--model", model);
+
+	for (const dir of config.additionalDirs) args.push("--add-dir", dir);
+
+	return args;
+}
+
+/**
+ * Honest read-only enforcement (T-602): derived from the argv we actually built, never
+ * from what was merely requested. `--permission-mode plan` plus a read-only `--tools`
+ * allowlist is real enforcement — Claude cannot invoke a tool outside the allowlist,
+ * confirmed via `claude --help` (both flags exist exactly as spelled here on 2.1.277). If
+ * `capabilities.supportsPermissionMode` was false, neither flag was emitted and this
+ * correctly reports `false`.
+ */
+export function claudeReadOnlyEnforcement(args: string[], readOnly: boolean): { enforced: boolean; mechanism?: string } {
+	if (!readOnly) return { enforced: false };
+	const modeIdx = args.indexOf("--permission-mode");
+	const hasPlanMode = modeIdx !== -1 && args[modeIdx + 1] === "plan";
+	const hasToolsAllowlist = args.includes("--tools");
+	const enforced = hasPlanMode && hasToolsAllowlist;
+	return enforced ? { enforced: true, mechanism: `--permission-mode plan --tools ${READ_ONLY_TOOLS.join(",")}` } : { enforced: false };
+}
+
+export class ClaudeAgent implements ExternalAgent {
+	readonly name = "claude" as const;
+
+	constructor(private readonly config: AgentConfig) {}
+
+	async isAvailable(force = false) {
+		return detect("claude", this.config, { cwd: process.cwd(), force });
+	}
+
+	async run(request: AgentRequest, options: AgentRunOptions): Promise<AgentResult> {
+		const started = Date.now();
+		const executable = resolveExecutable(this.config.executable);
+		if (!executable) {
+			throw new AgentError({
+				code: "EXECUTABLE_NOT_FOUND",
+				agent: "claude",
+				message: `\`${this.config.executable}\` was not found on PATH. Install Claude Code, or set multiHarness.claude.executable to its full path.`,
+			});
+		}
+
+		const availability = await detect("claude", this.config, { cwd: request.cwd });
+		const capabilities = claudeCapabilities(availability.version);
+
+		const readOnly = request.readOnly ?? (request.mode ? MODE_DEFAULT_READ_ONLY[request.mode] : false);
+		const timeoutMs = request.timeoutMs ?? this.config.timeoutMs;
+		const sessionId = randomUUID();
+
+		const args = buildClaudeArgs({ request, config: this.config, capabilities, readOnly, sessionId, fork: request.fork });
+
+		const state = newClaudeStreamState();
+		const reader = new JsonlReader((value) => {
+			if (value === undefined) return;
+			const progress = applyClaudeEvent(state, value);
+			if (progress) options.onProgress?.(progress);
+		});
+
+		try {
+			options.onProgress?.({ phase: "starting" });
+
+			const result = await spawnAgent({
+				command: executable,
+				args,
+				cwd: request.cwd,
+				stdin: request.context ? `${request.context}\n\n${request.task}` : request.task,
+				timeoutMs,
+				signal: options.signal,
+				onStdout: (chunk) => reader.push(chunk),
+			});
+			reader.end();
+
+			if (result.cancelled) throw cancelled("claude");
+			if (result.timedOut) throw timedOut("claude", timeoutMs);
+
+			const failure = state.failure;
+			if (failure) {
+				if (isQuotaFailure(failure)) throw providerLimit("claude", failure);
+				if (looksLikeAuthFailure(failure)) throw authRequired("claude", failure);
+				throw processFailed("claude", result.exitCode, failure);
+			}
+
+			if (result.exitCode !== 0) {
+				const tail = result.stderr.trim().split("\n").slice(-3).join("\n");
+				if (looksLikeAuthFailure(result.stderr)) throw authRequired("claude", tail);
+				throw processFailed("claude", result.exitCode, tail);
+			}
+
+			// `??` is wrong here: a success result can carry an empty string, and that must
+			// fall through to the streamed assistant text rather than count as an answer.
+			const output = state.result?.trim() || state.lastAssistantText?.trim() || "";
+			if (!output) {
+				throw invalidOutput(
+					"claude",
+					state.sawResult
+						? "the result event carried no text"
+						: `no result event was produced (${reader.stats.lines} output lines)`,
+				);
+			}
+
+			// The CLI is the authority on its own session id; ours was only a request.
+			const effectiveSessionId = state.sessionId ?? sessionId;
+			const enforcement = claudeReadOnlyEnforcement(args, readOnly);
+
+			return {
+				agent: "claude",
+				success: true,
+				output,
+				sessionId: effectiveSessionId,
+				exitCode: result.exitCode,
+				durationMs: Date.now() - started,
+				metadata: {
+					readOnlyEnforced: enforcement.enforced,
+					readOnlyMechanism: enforcement.mechanism,
+					cliVersion: availability.version,
+					turns: state.turns,
+					costUsd: state.costUsd,
+					permissionDenials: state.permissionDenials,
+					parseErrors: reader.stats.parseErrors,
+					model: request.model ?? this.config.model ?? null,
+					sessionIdMismatch: state.sessionId !== undefined && state.sessionId !== sessionId && !request.sessionId,
+					// `--fork-session` only applies when resuming; report the request honestly
+					// either way (see buildClaudeArgs / types.ts AgentRequest.fork).
+					forked: Boolean(request.fork),
+				},
+			};
+		} catch (e) {
+			if (e instanceof SpawnCwdError) throw invalidCwd("claude", request.cwd, e.message);
+			throw e;
+		}
+	}
+}

package/src/agents/codex-events.ts

@@ -0,0 +1,149 @@
+/**
+ * Interpretation of `codex exec --json` output.
+ *
+ * Event shapes captured from codex-cli 0.155.0 (2026-09-18):
+ *   {"type":"thread.started","thread_id":"01a0…"}
+ *   {"type":"turn.started"}
+ *   {"type":"item.completed","item":{"id":"item_0","type":"error","message":"…"}}
+ *   {"type":"error","message":"…"}
+ *   {"type":"turn.failed","error":{"message":"…"}}
+ *
+ * Shapes drift between versions, so nothing here switches on an exhaustive list of event
+ * names: keys are searched from a candidate list and anything unrecognized is ignored
+ * (_spec/03-codex-adapter.md).
+ */
+export interface CodexStreamState {
+	sessionId?: string;
+	/** Last assistant text seen, used only if the -o file is empty. */
+	lastAgentMessage?: string;
+	/** Terminal failure reported by the stream itself, even when the exit code is 0. */
+	failure?: string;
+	turnCompleted: boolean;
+	itemCount: number;
+	/**
+	 * Set once a terminal event (`turn.completed`, `turn.failed`, or top-level `error`) has
+	 * been recorded. A real stream carries at most one of these; a duplicate or out-of-order
+	 * repeat (garbled stream, buggy CLI) must not flip an already-decided outcome — losing a
+	 * real success to a stray late failure event would be worse than ignoring the duplicate.
+	 */
+	settled: boolean;
+}
+
+export interface CodexProgressEvent {
+	phase: string;
+	detail?: string;
+	raw?: string;
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+	return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+function firstString(source: Record<string, unknown>, keys: string[]): string | undefined {
+	for (const key of keys) {
+		const v = source[key];
+		if (typeof v === "string" && v.length > 0) return v;
+	}
+	return undefined;
+}
+
+const SESSION_KEYS = ["thread_id", "session_id", "conversation_id", "threadId", "sessionId"];
+const TEXT_KEYS = ["text", "message", "content", "last_agent_message"];
+
+/** Human-friendly phase for an item type. Unknown types fall back to the raw type. */
+function phaseForItem(itemType: string): string {
+	switch (itemType) {
+		case "agent_message":
+		case "assistant_message":
+			return "writing response";
+		case "command_execution":
+		case "local_shell_call":
+			return "running a command";
+		case "file_change":
+		case "patch_apply":
+			return "editing files";
+		case "reasoning":
+			return "thinking";
+		case "mcp_tool_call":
+			return "calling a tool";
+		case "web_search":
+			return "searching the web";
+		case "error":
+			return "reported a problem";
+		default:
+			return itemType.replace(/_/g, " ");
+	}
+}
+
+/** Feed one parsed event; mutates state and optionally yields a progress update. */
+export function applyCodexEvent(state: CodexStreamState, value: unknown): CodexProgressEvent | null {
+	const event = asRecord(value);
+	if (!event) return null;
+
+	const type = typeof event.type === "string" ? event.type : "";
+
+	// Session id can appear on any event; take the first one we see.
+	if (!state.sessionId) {
+		const direct = firstString(event, SESSION_KEYS);
+		const nested = asRecord(event.thread) ?? asRecord(event.session) ?? asRecord(event.conversation);
+		state.sessionId = direct ?? (nested ? firstString(nested, [...SESSION_KEYS, "id"]) : undefined);
+	}
+
+	if (type === "thread.started") return { phase: "starting", raw: type };
+	if (type === "turn.started") return { phase: "working", raw: type };
+
+	if (type === "turn.completed") {
+		if (!state.settled) {
+			state.turnCompleted = true;
+			state.settled = true;
+		}
+		return { phase: "completed", raw: type };
+	}
+
+	if (type === "turn.failed") {
+		const error = asRecord(event.error);
+		const message = (error ? firstString(error, ["message", "detail"]) : undefined) ?? "the turn failed";
+		if (!state.settled) {
+			state.failure = message;
+			state.settled = true;
+		}
+		return { phase: "failed", detail: state.failure ?? message, raw: type };
+	}
+
+	if (type === "error") {
+		const message = firstString(event, ["message", "detail"]) ?? "unknown error";
+		if (!state.settled) {
+			state.failure = message;
+			state.settled = true;
+		}
+		return { phase: "failed", detail: state.failure ?? message, raw: type };
+	}
+
+	if (type === "item.completed" || type === "item.started" || type === "item.updated") {
+		const item = asRecord(event.item);
+		if (!item) return null;
+		const itemType = typeof item.type === "string" ? item.type : "item";
+		if (type === "item.completed") state.itemCount++;
+
+		if (itemType === "agent_message" || itemType === "assistant_message") {
+			const text = firstString(item, TEXT_KEYS);
+			if (text) state.lastAgentMessage = text;
+		}
+
+		// An `error` item is informational (e.g. a truncated skill description), not fatal —
+		// only top-level `error` / `turn.failed` end the run.
+		const detail = itemType === "command_execution" ? firstString(item, ["command", "cmd"]) : undefined;
+		return { phase: phaseForItem(itemType), detail, raw: `${type}:${itemType}` };
+	}
+
+	return null;
+}
+
+export function newCodexStreamState(): CodexStreamState {
+	return { turnCompleted: false, itemCount: 0, settled: false };
+}
+
+/** Provider-side limits are worth their own message — refilling is the fix, not retrying. */
+export function isQuotaFailure(message: string): boolean {
+	return /out of credits|quota|rate.?limit|billing|insufficient.*(credit|balance)|usage limit/i.test(message);
+}

package/src/agents/codex.ts

@@ -0,0 +1,236 @@
+/**
+ * Codex CLI adapter. Every Codex flag in this project lives in this file.
+ * Verified against codex-cli 0.155.0 (_spec/03-codex-adapter.md).
+ */
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentConfig } from "../config/schema.ts";
+import { JsonlReader } from "../process/jsonl.ts";
+import {
+	AgentError,
+	authRequired,
+	cancelled,
+	invalidCwd,
+	invalidOutput,
+	looksLikeAuthFailure,
+	processFailed,
+	providerLimit,
+	timedOut,
+} from "../process/process-error.ts";
+import { resolveExecutable } from "../process/executable.ts";
+import { SpawnCwdError, spawnAgent } from "../process/spawn-agent.ts";
+import { detect } from "./availability.ts";
+import { applyCodexEvent, isQuotaFailure, newCodexStreamState } from "./codex-events.ts";
+import { MODE_DEFAULT_READ_ONLY, type AgentRequest, type AgentResult, type AgentRunOptions, type ExternalAgent } from "./types.ts";
+
+export interface CodexCapabilities {
+	supportsJson: boolean;
+	supportsOutputLastMessage: boolean;
+	supportsResumeSubcommand: boolean;
+	/**
+	 * Whether this codex build honors `-s <mode>` at all. Verified present on 0.155.0
+	 * (`codex exec --help` lists `-s, --sandbox <SANDBOX_MODE>`). Kept as a capability
+	 * (rather than assumed) so an adapter talking to a codex build that dropped or renamed
+	 * the flag can still report `readOnlyEnforced: false` truthfully instead of guessing.
+	 */
+	supportsSandboxMode: boolean;
+}
+
+/** Unknown or newer versions get the newest known capability set. */
+export function codexCapabilities(_version: string | undefined): CodexCapabilities {
+	return { supportsJson: true, supportsOutputLastMessage: true, supportsResumeSubcommand: true, supportsSandboxMode: true };
+}
+
+export interface BuildCodexArgsInput {
+	request: AgentRequest;
+	config: AgentConfig;
+	capabilities: CodexCapabilities;
+	/** Path for `-o`; omitted when the capability is unavailable. */
+	lastMessageFile?: string;
+	/** True when cwd is not inside a git repository. */
+	skipGitRepoCheck?: boolean;
+	readOnly: boolean;
+	/**
+	 * Branch instead of continuing a resumed session. Codex has no `--fork-session`
+	 * equivalent (verified via `codex exec --help`), so a forked run simply omits the
+	 * `resume <id>` subcommand and starts fresh — see `AgentRequest.fork` in types.ts.
+	 */
+	fork?: boolean;
+}
+
+/**
+ * Build argv for `codex exec`. The prompt is NOT here: it goes over stdin (`-`), keeping
+ * task text out of `ps` and clear of argv limits.
+ */
+export function buildCodexArgs(input: BuildCodexArgsInput): string[] {
+	const { request, config, capabilities, lastMessageFile, skipGitRepoCheck, readOnly, fork } = input;
+	const args: string[] = ["exec"];
+
+	if (request.sessionId && capabilities.supportsResumeSubcommand && !fork) {
+		args.push("resume", request.sessionId);
+	}
+
+	if (capabilities.supportsJson) args.push("--json");
+	args.push("-C", request.cwd);
+	if (capabilities.supportsSandboxMode) args.push("-s", readOnly ? "read-only" : "workspace-write");
+
+	if (lastMessageFile && capabilities.supportsOutputLastMessage) args.push("-o", lastMessageFile);
+	if (skipGitRepoCheck) args.push("--skip-git-repo-check");
+
+	const model = request.model ?? config.model;
+	if (model) args.push("-m", model);
+
+	for (const dir of config.additionalDirs) args.push("--add-dir", dir);
+
+	// `-` = read the prompt from stdin. Always last.
+	args.push("-");
+	return args;
+}
+
+/**
+ * Honest read-only enforcement (T-602): derived from the argv we actually built, never
+ * from what was merely requested. `-s read-only` is an OS-enforced sandbox (seatbelt on
+ * macOS, landlock on Linux) — real isolation, not a request the model can ignore — so it
+ * is safe to report `true` when, and only when, that exact flag pair is present. If
+ * `capabilities.supportsSandboxMode` is false the flag was never emitted and this
+ * correctly reports `false`: we never claim isolation we could not prove.
+ */
+export function codexReadOnlyEnforcement(args: string[], readOnly: boolean): { enforced: boolean; mechanism?: string } {
+	if (!readOnly) return { enforced: false };
+	const idx = args.indexOf("-s");
+	const enforced = idx !== -1 && args[idx + 1] === "read-only";
+	return enforced ? { enforced: true, mechanism: "-s read-only" } : { enforced: false };
+}
+
+function isGitRepo(cwd: string): boolean {
+	try {
+		return Bun.spawnSync({ cmd: ["git", "rev-parse", "--is-inside-work-tree"], cwd, stdout: "ignore", stderr: "ignore" })
+			.exitCode === 0;
+	} catch {
+		return false;
+	}
+}
+
+export class CodexAgent implements ExternalAgent {
+	readonly name = "codex" as const;
+
+	constructor(private readonly config: AgentConfig) {}
+
+	async isAvailable(force = false) {
+		return detect("codex", this.config, { cwd: process.cwd(), force });
+	}
+
+	async run(request: AgentRequest, options: AgentRunOptions): Promise<AgentResult> {
+		const started = Date.now();
+		const executable = resolveExecutable(this.config.executable);
+		if (!executable) {
+			throw new AgentError({
+				code: "EXECUTABLE_NOT_FOUND",
+				agent: "codex",
+				message: `\`${this.config.executable}\` was not found on PATH. Install the Codex CLI, or set multiHarness.codex.executable to its full path.`,
+			});
+		}
+
+		const availability = await detect("codex", this.config, { cwd: request.cwd });
+		const capabilities = codexCapabilities(availability.version);
+
+		const readOnly = request.readOnly ?? (request.mode ? MODE_DEFAULT_READ_ONLY[request.mode] : false);
+		const timeoutMs = request.timeoutMs ?? this.config.timeoutMs;
+
+		const tempDir = mkdtempSync(join(tmpdir(), "multi-harness-"));
+		const lastMessageFile = join(tempDir, "last-message.txt");
+
+		const args = buildCodexArgs({
+			request,
+			config: this.config,
+			capabilities,
+			lastMessageFile,
+			skipGitRepoCheck: !isGitRepo(request.cwd),
+			readOnly,
+			fork: request.fork,
+		});
+
+		const state = newCodexStreamState();
+		const reader = new JsonlReader((value) => {
+			if (value === undefined) return;
+			const progress = applyCodexEvent(state, value);
+			if (progress) options.onProgress?.(progress);
+		});
+
+		try {
+			options.onProgress?.({ phase: "starting" });
+
+			const result = await spawnAgent({
+				command: executable,
+				args,
+				cwd: request.cwd,
+				stdin: request.context ? `${request.context}\n\n${request.task}` : request.task,
+				timeoutMs,
+				signal: options.signal,
+				onStdout: (chunk) => reader.push(chunk),
+			});
+			reader.end();
+
+			if (result.cancelled) throw cancelled("codex");
+			if (result.timedOut) throw timedOut("codex", timeoutMs);
+
+			const failure = state.failure;
+			if (failure) {
+				if (isQuotaFailure(failure)) throw providerLimit("codex", failure);
+				if (looksLikeAuthFailure(failure)) throw authRequired("codex", failure);
+				throw processFailed("codex", result.exitCode, failure);
+			}
+
+			// Codex logs unrelated warnings to stderr, so stderr alone never decides failure.
+			if (result.exitCode !== 0) {
+				const tail = result.stderr.trim().split("\n").slice(-3).join("\n");
+				if (looksLikeAuthFailure(result.stderr)) throw authRequired("codex", tail);
+				throw processFailed("codex", result.exitCode, tail);
+			}
+
+			let output = "";
+			try {
+				output = readFileSync(lastMessageFile, "utf8").trim();
+			} catch {
+				/* the file is absent when the CLI had nothing to write */
+			}
+			if (!output) output = state.lastAgentMessage?.trim() ?? "";
+			if (!output) {
+				throw invalidOutput(
+					"codex",
+					reader.stats.parsed === 0
+						? `no JSON events were produced (${reader.stats.lines} output lines) — does this codex version support --json?`
+						: "the run finished without a final message",
+				);
+			}
+
+			const enforcement = codexReadOnlyEnforcement(args, readOnly);
+
+			return {
+				agent: "codex",
+				success: true,
+				output,
+				sessionId: state.sessionId,
+				exitCode: result.exitCode,
+				durationMs: Date.now() - started,
+				metadata: {
+					readOnlyEnforced: enforcement.enforced,
+					readOnlyMechanism: enforcement.mechanism,
+					cliVersion: availability.version,
+					items: state.itemCount,
+					parseErrors: reader.stats.parseErrors,
+					model: request.model ?? this.config.model ?? null,
+					// Codex has no `--fork-session`; a forked request omits `resume` and starts a
+					// fresh session instead (see buildCodexArgs / types.ts), reported honestly here.
+					forked: Boolean(request.fork),
+				},
+			};
+		} catch (e) {
+			if (e instanceof SpawnCwdError) throw invalidCwd("codex", request.cwd, e.message);
+			throw e;
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	}
+}

package/src/agents/types.ts

@@ -0,0 +1,81 @@
+/** Provider-neutral agent interface. See _spec/02-agent-interface.md. */
+import type { AgentMode, AgentName } from "../config/schema.ts";
+
+export type { AgentMode, AgentName };
+
+export interface AgentRequest {
+	agent: AgentName;
+	task: string;
+	cwd: string;
+	mode?: AgentMode;
+	/** Prior worker session id to resume. */
+	sessionId?: string;
+	/**
+	 * Fork the resumed session instead of continuing it, so two runs can share a parent
+	 * without racing on one worker session. Claude honors this via `--fork-session`; Codex
+	 * has no equivalent, so a forked Codex run starts fresh instead (_spec/08).
+	 */
+	fork?: boolean;
+	/** Compact handoff context — never the OMP transcript. */
+	context?: string;
+	timeoutMs?: number;
+	/** Request provider-enforced read-only execution. */
+	readOnly?: boolean;
+	/** Per-call worker model override; falls back to config, then the CLI's own config. */
+	model?: string;
+}
+
+export interface AgentResult {
+	agent: AgentName;
+	success: boolean;
+	/** Final textual answer only — never the raw event stream. */
+	output: string;
+	sessionId?: string;
+	exitCode: number | null;
+	durationMs: number;
+	stderr?: string;
+	metadata?: Record<string, unknown>;
+}
+
+export interface AgentProgress {
+	/** e.g. "starting", "inspecting repository", "running tests", "completed" */
+	phase: string;
+	detail?: string;
+	/** Provider-native event kind — debug logs only. */
+	raw?: string;
+}
+
+export interface AgentRunOptions {
+	signal: AbortSignal;
+	onProgress?: (event: AgentProgress) => void;
+}
+
+export type AuthState = "ok" | "logged-out" | "unknown";
+
+export interface AgentAvailability {
+	agent: AgentName;
+	available: boolean;
+	executablePath?: string;
+	version?: string;
+	auth: AuthState;
+	/** One line, safe to display. Never contains credentials. */
+	authDetail: string;
+	/** Present when `available` is false. */
+	reason?: string;
+}
+
+export interface ExternalAgent {
+	readonly name: AgentName;
+	isAvailable(force?: boolean): Promise<AgentAvailability>;
+	run(request: AgentRequest, options: AgentRunOptions): Promise<AgentResult>;
+}
+
+/** Mode defaults. An explicit readOnly on the request always wins. */
+export const MODE_DEFAULT_READ_ONLY: Record<AgentMode, boolean> = {
+	analyze: true,
+	plan: true,
+	review: true,
+	implement: false,
+	debug: false,
+	test: false,
+};