omp-multi-harness 0.1.0

package/src/process/process-error.ts

@@ -0,0 +1,178 @@
+/** Typed, actionable errors. Every message names the fix. See _spec/10-errors-and-security.md. */
+import type { AgentName } from "../config/schema.ts";
+import { redactTail } from "./redact.ts";
+
+export type AgentErrorCode =
+	| "EXECUTABLE_NOT_FOUND"
+	| "AUTH_REQUIRED"
+	| "PROCESS_FAILED"
+	| "TIMEOUT"
+	| "CANCELLED"
+	| "INVALID_OUTPUT"
+	| "SESSION_RESUME_FAILED"
+	| "WORKSPACE_BUSY"
+	| "AGENT_DISABLED"
+	| "INVALID_CWD"
+	| "PROVIDER_LIMIT";
+
+export interface AgentErrorInit {
+	code: AgentErrorCode;
+	agent: AgentName;
+	message: string;
+	exitCode?: number | null;
+	stderrTail?: string;
+	cause?: unknown;
+}
+
+export class AgentError extends Error {
+	readonly code: AgentErrorCode;
+	readonly agent: AgentName;
+	readonly exitCode: number | null | undefined;
+	readonly stderrTail: string | undefined;
+
+	constructor(init: AgentErrorInit) {
+		super(init.message, init.cause === undefined ? undefined : { cause: init.cause });
+		this.name = "AgentError";
+		this.code = init.code;
+		this.agent = init.agent;
+		this.exitCode = init.exitCode;
+		this.stderrTail = init.stderrTail;
+	}
+}
+
+const LOGIN_COMMAND: Record<AgentName, string> = {
+	codex: "codex login",
+	claude: "claude auth login",
+};
+
+const INSTALL_HINT: Record<AgentName, string> = {
+	codex: "Install the Codex CLI, or set multiHarness.codex.executable to its full path.",
+	claude: "Install Claude Code, or set multiHarness.claude.executable to its full path.",
+};
+
+const DISPLAY: Record<AgentName, string> = { codex: "Codex", claude: "Claude Code" };
+
+/** Stderr signatures that mean "the user needs to log in", not "the task failed". */
+const AUTH_PATTERNS = [
+	/not logged in/i,
+	/please (run )?`?(codex )?login/i,
+	/authentication (required|failed)/i,
+	/unauthorized/i,
+	/invalid[_ ]api[_ ]key/i,
+	/no credentials found/i,
+	/session expired/i,
+	/oauth token (expired|invalid)/i,
+];
+
+export function looksLikeAuthFailure(stderr: string): boolean {
+	return AUTH_PATTERNS.some((p) => p.test(stderr));
+}
+
+export function executableNotFound(agent: AgentName, executable: string): AgentError {
+	return new AgentError({
+		code: "EXECUTABLE_NOT_FOUND",
+		agent,
+		message: `\`${executable}\` was not found on PATH. ${INSTALL_HINT[agent]}`,
+	});
+}
+
+export function authRequired(agent: AgentName, stderrTail?: string): AgentError {
+	// Redact before it ever touches `.message` or `.stderrTail` — both are user/log visible.
+	const tail = stderrTail === undefined ? undefined : redactTail(stderrTail);
+	return new AgentError({
+		code: "AUTH_REQUIRED",
+		agent,
+		message:
+			`${DISPLAY[agent]} is installed but not authenticated. ` +
+			`Run \`${LOGIN_COMMAND[agent]}\` in a terminal and complete its normal login flow, then retry. ` +
+			`This extension never logs in on your behalf.`,
+		stderrTail: tail,
+	});
+}
+
+export function processFailed(agent: AgentName, exitCode: number | null, stderrTail?: string): AgentError {
+	const tail = stderrTail === undefined ? undefined : redactTail(stderrTail);
+	return new AgentError({
+		code: "PROCESS_FAILED",
+		agent,
+		message: `${DISPLAY[agent]} exited with code ${exitCode ?? "null"}.${tail ? ` Last output: ${tail}` : ""}`,
+		exitCode,
+		stderrTail: tail,
+	});
+}
+
+export function timedOut(agent: AgentName, timeoutMs: number): AgentError {
+	return new AgentError({
+		code: "TIMEOUT",
+		agent,
+		message:
+			`${DISPLAY[agent]} did not finish within ${Math.round(timeoutMs / 1000)}s and was terminated. ` +
+			`Raise multiHarness.${agent}.timeoutMs or narrow the task.`,
+	});
+}
+
+export function cancelled(agent: AgentName): AgentError {
+	return new AgentError({ code: "CANCELLED", agent, message: `${DISPLAY[agent]} run was cancelled.` });
+}
+
+export function invalidOutput(agent: AgentName, detail: string): AgentError {
+	return new AgentError({
+		code: "INVALID_OUTPUT",
+		agent,
+		// `detail` often quotes a raw output fragment — redact it like any other CLI-derived text.
+		message: `Could not read a final answer from ${DISPLAY[agent]}: ${redactTail(detail)}`,
+	});
+}
+
+/**
+ * The provider refused on quota/credits/billing. Distinct from PROCESS_FAILED because
+ * retrying cannot help — observed on codex-cli 0.155.0 as
+ * "Your workspace is out of credits."
+ */
+export function providerLimit(agent: AgentName, detail: string): AgentError {
+	// `detail` is lifted straight from the CLI's failure message (spec 10) — redact it too.
+	return new AgentError({
+		code: "PROVIDER_LIMIT",
+		agent,
+		message:
+			`${DISPLAY[agent]} refused the request: ${redactTail(detail)} ` +
+			`This is a provider account limit, not a problem with the task — retrying will not help. ` +
+			`Top up or switch accounts in ${agent === "codex" ? "your OpenAI/ChatGPT" : "your Anthropic"} plan, then retry.`,
+	});
+}
+
+export function agentDisabled(agent: AgentName): AgentError {
+	return new AgentError({
+		code: "AGENT_DISABLED",
+		agent,
+		message: `${DISPLAY[agent]} is disabled in config. Set multiHarness.${agent}.enabled: true to use it.`,
+	});
+}
+
+export function invalidCwd(agent: AgentName, cwd: string, reason: string): AgentError {
+	return new AgentError({ code: "INVALID_CWD", agent, message: `Cannot run ${DISPLAY[agent]} in ${cwd}: ${reason}` });
+}
+
+export function workspaceBusy(agent: AgentName, holder: string): AgentError {
+	return new AgentError({
+		code: "WORKSPACE_BUSY",
+		agent,
+		message:
+			`Another write-capable agent (${holder}) is working in this repository. ` +
+			`Wait for it, run this read-only, or cancel it with /sessions.`,
+	});
+}
+
+/** Map a spawn-level failure onto a typed error. */
+export function fromSpawnError(agent: AgentName, executable: string, err: NodeJS.ErrnoException): AgentError {
+	if (err.code === "ENOENT") return executableNotFound(agent, executable);
+	if (err.code === "EACCES") {
+		return new AgentError({
+			code: "EXECUTABLE_NOT_FOUND",
+			agent,
+			message: `\`${executable}\` is not executable (EACCES). Check its permissions.`,
+			cause: err,
+		});
+	}
+	return new AgentError({ code: "PROCESS_FAILED", agent, message: `Failed to start ${executable}: ${redactTail(err.message)}`, cause: err });
+}

package/src/process/redact.ts

@@ -0,0 +1,120 @@
+/**
+ * Redaction for anything that might reach a log line, an error message, a status line, or a
+ * persisted session file. See _spec/10-errors-and-security.md ("Logging", "Security
+ * requirements (hard)").
+ *
+ * Every pattern here is a false-negative-averse guess, not a credential validator — we would
+ * rather redact a git SHA that merely looks key-shaped than let a real key through. Patterns
+ * are ordered so that wider matches (PEM blocks, header lines) run before narrower token
+ * matches, and the placeholder text is chosen so it never re-matches any pattern below —
+ * that's what makes `redact` idempotent.
+ */
+
+const PLACEHOLDER = "[REDACTED]";
+
+/**
+ * Applied in order. Each is a standalone RegExp (not a matchAll accumulator) so one giant
+ * alternation doesn't become an unreadable, unmaintainable regex — and so PEM blocks (which
+ * span lines) can run before line-oriented patterns without them fighting over the same text.
+ * `replacement` is passed straight to String#replace, so `$1` etc. refer to that pattern's own
+ * capture groups.
+ */
+const PATTERNS: Array<{ re: RegExp; replacement: string }> = [
+	// PEM private key blocks — widest match first, multiline.
+	{ re: /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY-----/g, replacement: PLACEHOLDER },
+	// `Authorization: <anything>` header lines — redact the whole value, not just a token shape.
+	{ re: /authorization\s*:\s*\S+(?:\s+\S+)?/gi, replacement: PLACEHOLDER },
+	// Explicit bearer tokens outside a header line (e.g. logged as `token=Bearer xyz`).
+	{ re: /\bBearer\s+[A-Za-z0-9._~+/=-]{8,}/gi, replacement: PLACEHOLDER },
+	// OpenAI/Anthropic-style secret keys: sk-..., sk-ant-..., sk-proj-..., etc.
+	{ re: /\bsk-(?:ant-|proj-)?[A-Za-z0-9_-]{10,}/g, replacement: PLACEHOLDER },
+	// GitHub tokens: ghp_/gho_/ghu_/ghs_ (36 chars) and the newer github_pat_ format.
+	{ re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replacement: PLACEHOLDER },
+	{ re: /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, replacement: PLACEHOLDER },
+	// AWS access key id.
+	{ re: /\bAKIA[0-9A-Z]{16}\b/g, replacement: PLACEHOLDER },
+	// Google API key.
+	{ re: /\bAIza[0-9A-Za-z_-]{35}\b/g, replacement: PLACEHOLDER },
+	// JWT: three base64url segments joined by dots. Segment length floor keeps this from
+	// matching short dotted things like semver (1.20.5) — see redaction.test.ts for the
+	// false-positive trade-offs we accept.
+	{ re: /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, replacement: PLACEHOLDER },
+	// Shell-style assignments: KEY=..., API_TOKEN=..., DB_SECRET=..., MY_PASSWORD=...
+	// Value is everything up to whitespace/quote-close — redact the whole RHS, never just a
+	// prefix, since we don't know the value's shape ahead of time. Keep the key name ($1):
+	// which var leaked matters for debugging, the value never does.
+	{ re: /\b([A-Za-z_][A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASSWORD)[A-Za-z0-9_]*)\s*=\s*("[^"]*"|'[^']*'|\S+)/gi, replacement: `$1=${PLACEHOLDER}` },
+];
+
+/**
+ * Replace anything that looks like a credential with a stable placeholder. Never throws:
+ * empty strings, huge strings, and lone surrogates all fall through untouched or redacted,
+ * never raise.
+ *
+ * Idempotent by construction — `PLACEHOLDER` contains no `-`, `_`, `=`, or `.` runs long
+ * enough to satisfy any pattern above, so redacting its own output is a no-op.
+ */
+export function redact(text: string): string {
+	if (!text) return text;
+	let out = text;
+	for (const { re, replacement } of PATTERNS) out = out.replace(re, replacement);
+	return out;
+}
+
+/**
+ * Redact and cap length, for stderr/stdout tails — the main leak path in this codebase (a
+ * CLI's own error output routinely echoes back flags, env, or partial request bodies). Cuts
+ * from the front and keeps the tail, matching how `RingBuffer` in spawn-agent.ts already
+ * thinks about truncation, so a snippet always shows the most recent, most relevant lines.
+ */
+export function redactTail(text: string, maxChars = 500): string {
+	if (!text) return text;
+	const redacted = redact(text);
+	return redacted.length > maxChars ? `…${redacted.slice(redacted.length - maxChars)}` : redacted;
+}
+
+/**
+ * Allowlist, not denylist: a denylist over env var *names* fails open — any secret handed to
+ * the child under an unanticipated name (CUSTOM_API_SECRET, VENDOR_X_CRED, a typo'd variant)
+ * would sail straight through. An allowlist of known-harmless names can only fail closed:
+ * worst case we under-log, never leak. Keep this list short and boring.
+ */
+const ENV_ALLOWLIST = new Set([
+	"PATH",
+	"HOME",
+	"LANG",
+	"LC_ALL",
+	"LC_CTYPE",
+	"TERM",
+	"SHELL",
+	"PWD",
+	"OLDPWD",
+	"TMPDIR",
+	"TZ",
+	"NODE_ENV",
+	"CI",
+	"USER",
+	"LOGNAME",
+	"EDITOR",
+	"VISUAL",
+	"COLORTERM",
+]);
+
+export interface RedactedEnv {
+	/** Allowlisted vars that were present, verbatim. */
+	kept: Record<string, string>;
+	/** How many vars existed but were not on the allowlist — count only, never their names or values. */
+	omitted: number;
+}
+
+/** Safe-to-log view of an environment object. See ENV_ALLOWLIST for the "why allowlist" note. */
+export function redactEnv(env: NodeJS.ProcessEnv | Record<string, string | undefined>): RedactedEnv {
+	const kept: Record<string, string> = {};
+	let omitted = 0;
+	for (const [name, value] of Object.entries(env)) {
+		if (value === undefined) continue;
+		if (ENV_ALLOWLIST.has(name)) kept[name] = value;
+		else omitted++;
+	}
+	return { kept, omitted };
+}

package/src/process/spawn-agent.ts

@@ -0,0 +1,218 @@
+/**
+ * The only place this project spawns a process.
+ *
+ * Contract (_spec/05-process-runner.md): argument arrays only, never a shell; prompts on
+ * stdin; independent capped output buffers; timeout and AbortSignal both terminate the
+ * whole process group; exactly one resolution; every listener cleaned up.
+ */
+import { type ChildProcess, spawn } from "node:child_process";
+import { statSync } from "node:fs";
+import { realpathSync } from "node:fs";
+
+const IS_WINDOWS = process.platform === "win32";
+
+export interface SpawnAgentOptions {
+	command: string;
+	args: string[];
+	cwd: string;
+	env?: NodeJS.ProcessEnv;
+	/** Written to the child's stdin, which is then closed. Keeps prompts out of `ps`. */
+	stdin?: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	/** Milliseconds between SIGTERM and SIGKILL. */
+	killGraceMs?: number;
+	maxBufferBytes?: number;
+	onStdout?: (chunk: string) => void;
+	onStderr?: (chunk: string) => void;
+}
+
+export interface SpawnAgentResult {
+	exitCode: number | null;
+	signal: NodeJS.Signals | null;
+	stdout: string;
+	stderr: string;
+	durationMs: number;
+	timedOut: boolean;
+	cancelled: boolean;
+}
+
+/** Byte-capped buffer that keeps the tail — a runaway agent must not exhaust memory. */
+export class RingBuffer {
+	#chunks: string[] = [];
+	#bytes = 0;
+	constructor(private readonly maxBytes: number) {}
+
+	push(chunk: string): void {
+		this.#chunks.push(chunk);
+		this.#bytes += Buffer.byteLength(chunk);
+		while (this.#bytes > this.maxBytes && this.#chunks.length > 1) {
+			const dropped = this.#chunks.shift()!;
+			this.#bytes -= Buffer.byteLength(dropped);
+		}
+	}
+
+	get text(): string {
+		return this.#chunks.join("");
+	}
+}
+
+export class SpawnCwdError extends Error {}
+
+/** Terminate the child and everything it started. */
+function terminate(child: ChildProcess, signal: NodeJS.Signals): void {
+	if (child.pid === undefined || child.exitCode !== null || child.signalCode !== null) return;
+	try {
+		if (IS_WINDOWS) {
+			spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore", shell: false }).unref();
+		} else {
+			// Negative pid = the whole process group, so the CLI's own children die too.
+			process.kill(-child.pid, signal);
+		}
+	} catch {
+		try {
+			child.kill(signal);
+		} catch {
+			/* already gone */
+		}
+	}
+}
+
+export async function spawnAgent(options: SpawnAgentOptions): Promise<SpawnAgentResult> {
+	const {
+		command,
+		args,
+		cwd,
+		env = process.env,
+		stdin,
+		timeoutMs,
+		signal,
+		killGraceMs = 5_000,
+		maxBufferBytes = 1_048_576,
+		onStdout,
+		onStderr,
+	} = options;
+
+	let realCwd: string;
+	try {
+		realCwd = realpathSync(cwd);
+		if (!statSync(realCwd).isDirectory()) throw new Error("not a directory");
+	} catch (e) {
+		throw new SpawnCwdError(`${cwd}: ${(e as Error).message}`);
+	}
+
+	if (signal?.aborted) {
+		return { exitCode: null, signal: null, stdout: "", stderr: "", durationMs: 0, timedOut: false, cancelled: true };
+	}
+
+	const started = Date.now();
+	const stdout = new RingBuffer(maxBufferBytes);
+	const stderr = new RingBuffer(maxBufferBytes);
+
+	return await new Promise<SpawnAgentResult>((resolvePromise, rejectPromise) => {
+		let child: ChildProcess;
+		try {
+			child = spawn(command, args, {
+				cwd: realCwd,
+				env,
+				shell: false,
+				// Own process group so we can signal the whole tree on cancel/timeout.
+				detached: !IS_WINDOWS,
+				stdio: ["pipe", "pipe", "pipe"],
+			});
+		} catch (e) {
+			rejectPromise(e);
+			return;
+		}
+
+		let settled = false;
+		let timedOut = false;
+		let cancelled = false;
+		let graceTimer: ReturnType<typeof setTimeout> | undefined;
+		let timeoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+		const escalate = () => {
+			graceTimer = setTimeout(() => terminate(child, "SIGKILL"), killGraceMs);
+			graceTimer.unref?.();
+		};
+
+		const onAbort = () => {
+			cancelled = true;
+			terminate(child, "SIGTERM");
+			escalate();
+		};
+
+		const cleanup = () => {
+			if (timeoutTimer) clearTimeout(timeoutTimer);
+			if (graceTimer) clearTimeout(graceTimer);
+			signal?.removeEventListener("abort", onAbort);
+			child.stdout?.removeAllListeners();
+			child.stderr?.removeAllListeners();
+			child.removeAllListeners();
+		};
+
+		const settle = (result: SpawnAgentResult) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			resolvePromise(result);
+		};
+
+		const fail = (err: unknown) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			rejectPromise(err);
+		};
+
+		if (timeoutMs && timeoutMs > 0) {
+			timeoutTimer = setTimeout(() => {
+				timedOut = true;
+				terminate(child, "SIGTERM");
+				escalate();
+			}, timeoutMs);
+			timeoutTimer.unref?.();
+		}
+
+		signal?.addEventListener("abort", onAbort, { once: true });
+
+		// Persistent decoders: a multi-byte character split across chunks must not corrupt.
+		const outDecoder = new TextDecoder("utf8");
+		const errDecoder = new TextDecoder("utf8");
+
+		child.stdout?.on("data", (buf: Buffer) => {
+			const text = outDecoder.decode(buf, { stream: true });
+			if (!text) return;
+			stdout.push(text);
+			onStdout?.(text);
+		});
+		child.stderr?.on("data", (buf: Buffer) => {
+			const text = errDecoder.decode(buf, { stream: true });
+			if (!text) return;
+			stderr.push(text);
+			onStderr?.(text);
+		});
+
+		child.on("error", fail);
+
+		child.on("close", (code, sig) => {
+			settle({
+				exitCode: code,
+				signal: sig,
+				stdout: stdout.text,
+				stderr: stderr.text,
+				durationMs: Date.now() - started,
+				timedOut,
+				cancelled,
+			});
+		});
+
+		if (child.stdin) {
+			child.stdin.on("error", () => {
+				/* child may exit before we finish writing — not fatal */
+			});
+			if (stdin !== undefined) child.stdin.write(stdin);
+			child.stdin.end();
+		}
+	});
+}

package/src/routing/handoff.ts

@@ -0,0 +1,59 @@
+/** Compact context handoff and output shaping. See _spec/02-agent-interface.md. */
+import type { AgentMode, AgentResult } from "../agents/types.ts";
+
+/** Truncate from the middle so both the opening and the conclusion survive. */
+export function truncateMiddle(text: string, maxChars: number): { text: string; truncated: boolean } {
+	if (text.length <= maxChars) return { text, truncated: false };
+	const keep = Math.max(200, Math.floor((maxChars - 80) / 2));
+	const head = text.slice(0, keep);
+	const tail = text.slice(-keep);
+	const dropped = text.length - head.length - tail.length;
+	return { text: `${head}\n\n[… ${dropped.toLocaleString()} characters omitted …]\n\n${tail}`, truncated: true };
+}
+
+const MODE_PREAMBLE: Record<AgentMode, string> = {
+	analyze: "Analyze and explain. Do not modify any files.",
+	plan: "Produce a concrete plan. Do not modify any files.",
+	review: "Review the code and report findings, most important first. Do not modify any files.",
+	implement: "Implement the change. Keep the diff minimal and focused.",
+	debug: "Find the root cause first, then fix it.",
+	test: "Run the relevant tests and repair what fails.",
+};
+
+export interface HandoffInput {
+	task: string;
+	mode?: AgentMode;
+	context?: string;
+	maxChars: number;
+}
+
+/**
+ * Build the text sent to a worker: a short mode preamble, optional caller context, then the
+ * task. Never the OMP transcript — the worker can read the repository itself.
+ */
+export function buildHandoff(input: HandoffInput): string {
+	const sections: string[] = [];
+	if (input.mode) sections.push(MODE_PREAMBLE[input.mode]);
+	if (input.context?.trim()) {
+		const { text } = truncateMiddle(input.context.trim(), input.maxChars);
+		sections.push(`Context from the supervisor:\n${text}`);
+	}
+	sections.push(`Task:\n${input.task.trim()}`);
+	return sections.join("\n\n");
+}
+
+/** One-line summary used in run lists and status lines. */
+export function summarize(task: string, max = 60): string {
+	const flat = task.replace(/\s+/g, " ").trim();
+	return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+/** Compact, human-readable rendering of a finished run. */
+export function renderResult(result: AgentResult, maxOutputChars: number): { text: string; truncated: boolean } {
+	const { text, truncated } = truncateMiddle(result.output, maxOutputChars);
+	const seconds = (result.durationMs / 1000).toFixed(1);
+	const bits = [result.agent, `${seconds}s`];
+	if (result.sessionId) bits.push(`session ${result.sessionId.slice(0, 8)}`);
+	if (result.metadata?.readOnlyEnforced === true) bits.push("read-only");
+	return { text: `[${bits.join(" · ")}]\n${text}`, truncated };
+}

package/src/routing/prompt.ts

@@ -0,0 +1,72 @@
+/**
+ * Routing guidance for the OMP supervisor (T-503).
+ *
+ * OMP's `ToolDefinition` has **no** `promptSnippet` / `promptGuidelines` fields — those are
+ * upstream `pi` only (verified against 18.2.6). Guidance therefore rides in two supported
+ * places: each tool's `description`, and the `before_agent_start` event, whose result may
+ * return a replacement `systemPrompt: string[]` ("Extensions chain in order"). That event is
+ * the only system-prompt contribution surface `ExtensionAPI` offers; nothing here invents a
+ * field that does not exist.
+ */
+import type { ExtensionAPI } from "@oh-my-pi/pi-coding-agent";
+import type { MultiHarnessConfig } from "../config/schema.ts";
+
+/** One line per agent — also the capability summary handed to the router model. */
+export const AGENT_SCOPES = {
+	codex:
+		"Codex — implementation, debugging, refactoring, tests, repository modification, targeted code review.",
+	claude:
+		"Claude — architecture analysis, planning, design review, broad repository reasoning, second opinions, conceptual risk.",
+} as const;
+
+/** What each tool is for, in the supervisor's own words. */
+export const TOOL_SCOPES = {
+	ask_codex: "Hand one self-contained coding task to the Codex CLI and get its answer.",
+	ask_claude: "Hand one self-contained reasoning or review task to the Claude Code CLI and get its answer.",
+	delegate: "Same surface, but `agent: \"auto\"` lets the harness pick; the result always reports how it routed.",
+	agent_runs: "Manage background runs: list, status, result, cancel, wait. This is how you join fan-out work.",
+} as const;
+
+/**
+ * The system-prompt contribution. Preferences, not a workflow: the supervisor must stay
+ * free to answer directly or to call one agent only (_spec/12 E).
+ */
+export const ROUTING_GUIDANCE = [
+	"# Delegating to external coding agents (multi-harness)",
+	"",
+	`${AGENT_SCOPES.codex}`,
+	`${AGENT_SCOPES.claude}`,
+	"",
+	`- ask_codex — ${TOOL_SCOPES.ask_codex}`,
+	`- ask_claude — ${TOOL_SCOPES.ask_claude}`,
+	`- delegate — ${TOOL_SCOPES.delegate}`,
+	`- agent_runs — ${TOOL_SCOPES.agent_runs}`,
+	"",
+	"These are preferences, not a required workflow:",
+	"- Do not delegate trivial work, and do not invoke both agents when one suffices.",
+	"- For hard tasks, consider Claude plans → Codex implements → Claude reviews read-only → Codex fixes.",
+	"- Prefer a read-only review before giving another agent write access to the same files.",
+	"- Use background runs only when two tasks are genuinely independent; join them with agent_runs.",
+	"- State each task as a self-contained instruction: a worker cannot see this conversation.",
+].join("\n");
+
+export interface RoutingGuidanceDeps {
+	pi: ExtensionAPI;
+	getConfig: () => MultiHarnessConfig;
+}
+
+/**
+ * Append {@link ROUTING_GUIDANCE} to the system prompt, gated on
+ * `multiHarness.routing.promptGuidance`. Registered during load; the handler re-reads config
+ * per turn so toggling it takes effect without a restart.
+ */
+export function registerRoutingGuidance({ pi, getConfig }: RoutingGuidanceDeps): void {
+	pi.on("before_agent_start", (event) => {
+		const config = getConfig();
+		if (!config.enabled || !config.routing.promptGuidance) return;
+		// `event.systemPrompt` is the freshly computed base each turn, so appending cannot
+		// accumulate — the guard is for hosts that replay a prepared prompt.
+		if (event.systemPrompt.includes(ROUTING_GUIDANCE)) return;
+		return { systemPrompt: [...event.systemPrompt, ROUTING_GUIDANCE] };
+	});
+}