From 864ff26ef329ce783d0a1e1717e3b52f4727bb45 Mon Sep 17 00:00:00 2001
From: QuentinCody <33259999+QuentinCody@users.noreply.github.com>
Date: Wed, 13 May 2026 12:57:27 -0400
Subject: [PATCH 1/6] fix: pin dependencies and stabilize CI

---
 package-lock.json                     | 16 ++++-----
 package.json                          | 16 ++++-----
 src/commands/__tests__/verify.test.ts | 50 +++++++++++++++------------
 src/harness/signatures.ts             | 10 +++---
 4 files changed, 49 insertions(+), 43 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index 531e8bf..e4f6d0c 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -13,20 +13,20 @@
                 "linux"
             ],
             "dependencies": {
-                "commander": "^12.0.0"
+                "commander": "12.1.0"
             },
             "bin": {
                 "interlinked": "dist/index.js",
                 "interlinked-hook": "dist/hook-entry.js"
             },
             "devDependencies": {
-                "@biomejs/biome": "^2.4.13",
-                "@types/node": "^20.0.0",
-                "fast-check": "^4.7.0",
-                "tsup": "^8.0.0",
-                "tsx": "^4.0.0",
-                "typescript": "^5.5.0",
-                "vitest": "^3.0.0"
+                "@biomejs/biome": "2.4.13",
+                "@types/node": "20.19.33",
+                "fast-check": "4.7.0",
+                "tsup": "8.5.1",
+                "tsx": "4.21.0",
+                "typescript": "5.9.3",
+                "vitest": "3.2.4"
             },
             "engines": {
                 "node": ">=22.0.0"
diff --git a/package.json b/package.json
index 28f91a0..b538b45 100644
--- a/package.json
+++ b/package.json
@@ -82,18 +82,18 @@
     },
     "packageManager": "npm@10.0.0",
     "dependencies": {
-        "commander": "^12.0.0"
+        "commander": "12.1.0"
     },
     "optionalDependencies": {
         "@typescript/native-preview": "7.0.0-dev.20260421.2"
     },
     "devDependencies": {
-        "@biomejs/biome": "^2.4.13",
-        "@types/node": "^20.0.0",
-        "fast-check": "^4.7.0",
-        "tsup": "^8.0.0",
-        "tsx": "^4.0.0",
-        "typescript": "^5.5.0",
-        "vitest": "^3.0.0"
+        "@biomejs/biome": "2.4.13",
+        "@types/node": "20.19.33",
+        "fast-check": "4.7.0",
+        "tsup": "8.5.1",
+        "tsx": "4.21.0",
+        "typescript": "5.9.3",
+        "vitest": "3.2.4"
     }
 }
diff --git a/src/commands/__tests__/verify.test.ts b/src/commands/__tests__/verify.test.ts
index e4ad46e..59448c0 100644
--- a/src/commands/__tests__/verify.test.ts
+++ b/src/commands/__tests__/verify.test.ts
@@ -141,31 +141,35 @@ describe("scored suggestions", () => {
 });
 
 describe("suppression detection", () => {
-	it("ignores suppression markers that only appear inside string literals", async () => {
-		const { verifyCommand } = await import("../verify.js");
+	it(
+		"ignores suppression markers that only appear inside string literals",
+		async () => {
+			const { verifyCommand } = await import("../verify.js");
 
-		// Build the literal token at runtime so this test file's own source
-		// doesn't contain a raw "@ts-expect-error" — the suppressions check would
-		// (correctly) nag every edit if it did. The fixture file written below
-		// still contains the literal token, which is the point of the test.
-		const tsIgnore = `@ts-${"ignore"}`;
-		writeFileSync(
-			join(tempDir, "fixture.ts"),
-			[
-				"export function buildFixture() {",
-				`  const code = "// ${tsIgnore}\\nconst x = 1;";`,
-				`  return code.includes("${tsIgnore}");`,
-				"}",
-				"",
-			].join("\n"),
-		);
+			// Build the literal token at runtime so this test file's own source
+			// doesn't contain a raw "@ts-expect-error" — the suppressions check would
+			// (correctly) nag every edit if it did. The fixture file written below
+			// still contains the literal token, which is the point of the test.
+			const tsIgnore = `@ts-${"ignore"}`;
+			writeFileSync(
+				join(tempDir, "fixture.ts"),
+				[
+					"export function buildFixture() {",
+					`  const code = "// ${tsIgnore}\\nconst x = 1;";`,
+					`  return code.includes("${tsIgnore}");`,
+					"}",
+					"",
+				].join("\n"),
+			);
 
-		const captured = await captureStd(async () => {
-			await verifyCommand({ target: tempDir, json: true });
-		});
-		const result = JSON.parse(captured.stdout);
-		expect(result.suppressions.issues).toBe(0);
-	});
+			const captured = await captureStd(async () => {
+				await verifyCommand({ target: tempDir, json: true });
+			});
+			const result = JSON.parse(captured.stdout);
+			expect(result.suppressions.issues).toBe(0);
+		},
+		60_000,
+	);
 });
 
 // Pins the invariant for the tail "X / Y files flagged" summary:
diff --git a/src/harness/signatures.ts b/src/harness/signatures.ts
index f921253..9403b05 100644
--- a/src/harness/signatures.ts
+++ b/src/harness/signatures.ts
@@ -521,7 +521,7 @@ const SECRETS_RULES: SignatureRule[] = [
 		category: "secrets_detection",
 		severity: "critical",
 		description: "GitLab Personal Access Token",
-		patterns: [/\bglpat-[A-Za-z0-9_-]{20}\b/],
+		patterns: [/(?<![A-Za-z0-9_-])glpat-[A-Za-z0-9_-]{20}(?![A-Za-z0-9_-])/],
 	},
 	{
 		id: "sig-secret-slack-app",
@@ -612,21 +612,23 @@ const SECRETS_RULES: SignatureRule[] = [
 		category: "secrets_detection",
 		severity: "critical",
 		description: "PlanetScale database token",
-		patterns: [/\bpscale_tkn_[A-Za-z0-9_-]{20,}\b/],
+		patterns: [/(?<![A-Za-z0-9_-])pscale_tkn_[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/],
 	},
 	{
 		id: "sig-secret-flyio",
 		category: "secrets_detection",
 		severity: "critical",
 		description: "Fly.io API token",
-		patterns: [/\bfo1_[A-Za-z0-9_-]{20,}\b/],
+		patterns: [/(?<![A-Za-z0-9_-])fo1_[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/],
 	},
 	{
 		id: "sig-secret-railway",
 		category: "secrets_detection",
 		severity: "critical",
 		description: "Railway API token",
-		patterns: [/\b(?:railway|rlwy)_[A-Za-z0-9_-]{20,}\b/],
+		patterns: [
+			/(?<![A-Za-z0-9_-])(?:railway|rlwy)_[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])/,
+		],
 	},
 	{
 		id: "sig-secret-render",

From f15b233ec5925db8832297ccd9b23f9bf5dd1909 Mon Sep 17 00:00:00 2001
From: QuentinCody <33259999+QuentinCody@users.noreply.github.com>
Date: Thu, 14 May 2026 12:24:27 -0400
Subject: [PATCH 2/6] docs: metacoding agent design plan (v2 with six review
 iterations)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Per-prompt metacoder that runs synchronously on UserPromptSubmit before
the coding agent's first tool call. Emits a session-scoped overlay of
guard rules (action: "block" only, tighten-only against the floor) plus
an optional system_prompt_addendum. Same-tier model as the coding agent:
Opus 4.7 max for Claude, GPT-5.5 xhigh for Codex. Both transports use
the user's CLI subscription via `claude -p` / `codex exec` — no API
keys required.

The doc captures the locked-in decisions (model tier, hard-block
enforcement, replace semantics across multi-prompt sessions), the
floor/overlay invariant (action constraint + regex validation + ReDoS
guards + append-after ordering), recursion-guard mechanics, hook timeout
coordination, and the per-runner rollout contract. Six rounds of
external review folded in at §reviewer-P1..P5 markers.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/design/metacoding-agent-plan.md | 828 +++++++++++++++++++++++++++
 1 file changed, 828 insertions(+)
 create mode 100644 docs/design/metacoding-agent-plan.md

diff --git a/docs/design/metacoding-agent-plan.md b/docs/design/metacoding-agent-plan.md
new file mode 100644
index 0000000..643658b
--- /dev/null
+++ b/docs/design/metacoding-agent-plan.md
@@ -0,0 +1,828 @@
+# Metacoding Agent — Implementation Plan (v2)
+
+**Status:** Proposed — v2 after follow-up reviewer pass. Awaiting reviewer signoff before implementation begins.
+**Author:** Q. Cody, drafted via Claude Code session 2026-05-13. Revised same-session in response to reviewer findings.
+**Scope:** v1 prototype for **Claude Code and Codex CLI only**. Cursor / Copilot / Gemini support deferred (see §9).
+
+---
+
+## Changes from v1
+
+Reviewer flagged five issues in v1; all five are folded in. Two open
+questions are now resolved. A follow-up v2 pass flagged six more plan
+precision issues; those are folded in below as well.
+
+| Change | Location | Origin |
+|---|---|---|
+| Scope narrowed to Claude Code + Codex only | Throughout | User scoping decision |
+| Hook adapter path `defaultTimeoutForPhase` raises `user-prompt` to 35s; metacoder internal timeout remains 30s | §2.4, §3, §6 | Reviewer #1 (High) + v2 review #4 |
+| Overlay rules constrained to `action: "block"` only; floor rules iterate before overlay | §2.3, §5 | Reviewer #2 (High) |
+| Regex validation on every overlay regex (length cap, flag whitelist, try/catch, ReDoS shape reject) | §2.3, §5 | Reviewer #3 (High) |
+| Codex adapter's `encodeCodexAllow` emits `hookSpecificOutput.additionalContext` for UserPromptSubmit (not stderr) | §3, §7 | Reviewer #4 (Medium) |
+| Metacoder receives `scanResult.redacted` when the PII scanner finds content; otherwise receives `event.prompt` directly because no redaction was needed | §6 | Reviewer #5 (Medium) + v2 review #6 |
+| Subprocess recursion guard via `INTERLINKED_METACODER_SUBPROCESS=1` env sentinel, carried through `UnifiedHookEvent` and `toLegacyHarnessEvent` | §2.5, §3 | Reviewer open Q2 + v2 review #2 |
+| Codex `Stop` vs Claude `SessionEnd` / `Stop` cleanup parity documented and tested with correct phase names | §7, §8.2 | Reviewer open Q1 + v2 review #5 |
+| Multi-prompt sessions explicitly replace prior overlays instead of merging | §1.1, §8.9 | v2 review #1 |
+| Overlay v1 drops `extra_exceptions` / `additional_patterns`; exceptions use `negate: true` rule patterns | §2.3, §5, §6 | v2 review #3 |
+
+---
+
+## 1. Concept
+
+On every `UserPromptSubmit` (i.e. every time the user sends a message to a
+coding agent), a **metacoder** LLM call runs synchronously *before* the
+coding agent's first tool call:
+
+1. Reads the user's prompt (PII-scanner-redacted when the scanner finds
+   content; otherwise unchanged, see §6)
+2. Reads `AGENTS.md` / `CLAUDE.md` project instructions
+3. Reads cached codebase context (existing project graph / structural
+   cache maintained by the harness — no fresh research in v1)
+4. Emits a **session-scoped overlay** that constrains the coding agent
+   for the lifetime of that session:
+   - `.interlinked/sessions/<session_id>/overlay-rules.json` — additional
+     guard rules
+   - `.interlinked/sessions/<session_id>/system-prompt.md` — appended to
+     coding agent's context via hook stdout
+5. The overlay is loaded by the harness **synchronously** so the very
+   next `PreToolUse` from the coding agent already evaluates against the
+   tighter ruleset.
+6. On session end (`SessionEnd` for Claude, `Stop` for Codex), the
+   overlay directory is evicted.
+
+Net effect: hooks are **compiled output** of a per-prompt planner, not
+hand-maintained source. The user's framing: "no one should have to *use*
+hooks — they should be created and customized for each new prompt, by a
+metacoding agent."
+
+### 1.1 Multi-prompt sessions
+
+`UserPromptSubmit` can fire multiple times inside one long-running agent
+session. v1 uses **replace semantics**:
+
+- Each `UserPromptSubmit` fully replaces the previous overlay for that
+  `session_id` (rules and addendum). Overlays do not merge across prompts.
+- `writeOverlayArtifacts` writes tmp files and renames them onto the same
+  `.interlinked/sessions/<sid>/overlay-rules.json` and
+  `system-prompt.md` paths, overwriting the previous prompt's artifacts
+  atomically.
+- `sessionRules.set(session_id, loadRules(cwd, session_id))` overwrites
+  the prior in-memory rules entry. After prompt B, prompt A's overlay
+  rules are no longer active.
+- The new `system_prompt_addendum` is injected fresh on the new
+  `UserPromptSubmit`. Prior addenda can remain in the coding agent's
+  conversation history because the harness cannot delete already-injected
+  model context. That is a known runner limitation; the authoritative
+  enforced rules are always the latest overlay in `sessionRules`.
+
+Regression test: prompt A emits a rule blocking `src/legacy/payments/`;
+prompt B asks to fix `src/legacy/payments/migrate.ts` and emits a
+different overlay. Assert A's rule no longer blocks after B's
+`UserPromptSubmit`, and B's addendum is the one returned to the hook.
+
+---
+
+## 2. Decisions locked in
+
+These are non-default choices the user has explicitly made. Reviewers
+should push back on any of these that look wrong.
+
+### 2.1 Metacoder model: same tier as the coding agent
+
+- **Claude Code session** (`agent_source === "claude"`): use **Opus 4.7
+  with maximum reasoning effort**. Invoked via the existing `claude -p`
+  subprocess pattern (mirrors `policy-classifier.ts::callViaClaudeCode`).
+  Reuses the user's existing Claude Code subscription — no separate API
+  key required.
+- **Codex session** (`agent_source === "codex"`): use **GPT-5.5 with
+  `model_reasoning_effort: "xhigh"`** (user's framing: "x-high"; the
+  CLI's actual config value is `xhigh`, one word — verified live).
+  Invoked via the `codex exec` subprocess pattern, which uses the
+  developer's existing Codex CLI subscription via `codex login`. **No
+  OpenAI API key required.** Symmetric with the Claude path: both
+  metacoder transports reuse the developer's existing CLI subscription
+  rather than billing a separate API account.
+- **Cursor / Copilot / Gemini sessions:** out of scope for v1. The
+  metacoder is not invoked for those runners; the coding agent runs
+  against floor rules only. See §9 for the rationale.
+
+**Rationale (user):** "If the main coding agent is going to be
+constrained by the metacoder's output, the metacoder shouldn't be a
+dumber model that under-constrains." The metacoder is a peer of the
+coding agent, not a cheap upstream filter.
+
+**Latency cost:** Opus 4.7 max-effort + Codex high are 5–30s per prompt.
+This is visible to the user as a delay between hitting Enter and the
+coding agent starting work. **This is intentional** — the user's design
+explicitly accepts the latency in exchange for per-prompt tailoring of
+the harness.
+
+**Cost cost:** Opus 4.7 max per prompt is in the range of $0.05–$0.30
+depending on prompt length, system prompt size, and thinking budget.
+For heavy users this can be hundreds of dollars per month. Out of scope
+for v1: per-budget tracking / monthly caps. Document as a known cost.
+
+### 2.2 Enforcement: hard-block
+
+When an overlay rule matches a `PreToolUse`, the harness **blocks** the
+tool call with the rule's reason, identically to how built-in floor
+rules block. Overlay rules participate in the same evaluator pipeline;
+the only distinction is the rule's `source` provenance.
+
+**Rationale (user):** matches the design intent of "the harness should
+constrain". Warn-only mode would let the coding agent route around
+overlay rules just as it routes around AGENTS.md today, defeating the
+purpose.
+
+**Failure mode this creates:** if the metacoder emits a wrong-shaped
+constraint, the coding agent gets stuck in a worse local optimum until
+session end. v1 mitigates this only via the floor/overlay invariant
+(below) — the agent can always reach the floor's allowed actions.
+
+### 2.3 Floor / overlay invariant: tighten-only
+
+- **Floor** = built-in rules (105) + `.interlinked/guard-rules.json`
+  (team) + `.interlinked/guard-rules.local.json` (personal) + distilled
+  rules from `/enforce`. Hand-authored, immutable per session.
+- **Overlay** = metacoder-emitted, session-scoped. Can only **ADD**
+  constraints to the floor. Never relaxes.
+
+Concrete enforcement (in `overlay-loader.ts`):
+
+| Loader behavior | Why |
+|---|---|
+| Reject any `disabled_rules` field in overlay | Disabling a floor rule = relaxing. |
+| Reject any overlay rule whose `id` collides with a floor id | Replacing a floor rule = relaxing. |
+| Require `id` prefix `overlay:<session>:` | Namespacing; prevents id squatting. |
+| **Reject any rule whose `action` is not `"block"`** | Only `block` matches the "blocks exactly like floor rules" contract. `ask` / `soft_block` return early from the evaluator with weaker-than-block decisions (`pre-tool.ts:373, 395`); if iteration order put overlay first, the overlay would *relax* the effective decision. `rewrite` mutates input — too powerful for an LLM-emitted rule. `warn` doesn't return early but is informational, not constraining. |
+| **Append overlay rules AFTER floor rules in the merged list** | Belt-and-suspenders so floor `block` always iterates before any overlay rule that matches the same input. With both the action constraint above and append-after, an overlay rule can only fire when no floor rule matched first. |
+| Reject top-level `extra_exceptions` and `additional_patterns` fields entirely | These fields are not part of overlay v1. `extra_exceptions` is command-substring-only in the current matcher and would be misleading for file-path rules; `additional_patterns` is not a current `GuardRulesConfig` field. Overlay exceptions must be expressed as `negate: true` patterns inside the overlay rule itself. |
+| Cap rule count (≤20 per overlay) | Defensive against a runaway LLM emitting 200 rules. |
+
+Rejected fields/rules are dropped with a `[interlinked:overlay]` stderr
+warning. The rest of the overlay still loads. This is the same
+fail-soft pattern used elsewhere in the loader.
+
+**Regex validation (overlay-only).** Floor rules are admin-authored and
+trusted; `rule-matching.ts::getCachedRegex` does not validate input
+because the existing rule corpus is hand-curated (explicit comment at
+`rule-matching.ts:53–57`). LLM-emitted regexes break that assumption.
+The overlay loader runs these checks at load time on every regex in
+`patterns[].regex` and `active_when.file_scope`, and drops any rule
+that fails:
+
+| Check | Reason |
+|---|---|
+| `pattern.length ≤ 200` chars | Bounds compilation time and complexity. |
+| `rule.patterns.length ≤ 10` | Bounds per-rule evaluation cost. |
+| `flags ∈ {"i", "m", "s", ""}` only | Reject `g`, `y` (stateful, break shared cache), `u` (Unicode rules) for predictable matching. |
+| Wrap `new RegExp(pattern, flags)` in try/catch | Invalid regex throws on every PreToolUse otherwise; drop the rule with a warning. |
+| Reject patterns containing nested unbounded quantifiers (`(a+)+`, `(a*)*`, `(a|a)*`) | Catastrophic backtracking (ReDoS) risk. Cheap structural check: `/\([^)]*[+*][^)]*\)[+*]/` catches the common cases. Not exhaustive — see §10 risk #9 — but sufficient for v1. |
+
+### 2.4 Synchronous before first tool call
+
+The metacoder is awaited inside the harness's `UserPromptSubmit`
+handler. The hook script's socket call blocks until the handler returns.
+By the time the coding agent's runtime resumes and issues its first tool
+call, the overlay is already in the harness's in-memory per-session
+rule cache.
+
+Implication: the harness does NOT rely on the 2-second `fs.watchFile`
+polling path for per-session overlays. Polling is fine for floor rule
+edits (team/local files); for session overlays we use in-memory.
+
+**Hook timeout amendment.** The adapter path at
+`src/hook-entry.ts:30` defines `DEFAULT_HOOK_TIMEOUT_MS = 2000` and
+`defaultTimeoutForPhase` at L215 returns it for every phase except
+`pre-tool`. A 30s metacoder would be killed at 2s, fall through to
+cold fallback, and never write the overlay. The plan adds a
+`user-prompt` phase branch:
+
+```ts
+const DEFAULT_USER_PROMPT_TIMEOUT_MS = 35_000;
+
+function defaultTimeoutForPhase(event: UnifiedHookEvent): number {
+  if (event.phase === PHASE_PRE_TOOL) return DEFAULT_LEGACY_PRE_TOOL_TIMEOUT_MS;
+  if (event.phase === PHASE_USER_PROMPT) return DEFAULT_USER_PROMPT_TIMEOUT_MS;
+  return DEFAULT_HOOK_TIMEOUT_MS;
+}
+```
+
+The metacoder's internal timeout remains 30s. The hook timeout is 35s so
+the harness has a 5s buffer to convert a clean metacoder timeout into an
+`allow` decision instead of racing the hook's own timeout and producing a
+spurious cold fallback. The legacy `.mjs` script has its own per-phase
+timeouts; align it to the same 35s user-prompt hook budget.
+
+### 2.5 Subprocess recursion guard (new in v2)
+
+The metacoder spawns `claude -p` to call Opus 4.7. The subprocess
+inherits the user's `.claude/settings.json` hooks → its first prompt
+fires `UserPromptSubmit` → harness sees it → metacoder fires recursively
+→ infinite loop.
+
+The existing `policy-classifier.ts::callViaClaudeCode` does not address
+this because it runs on `PreToolUse`, not `UserPromptSubmit`. v1
+introduces a sentinel env var:
+
+- `metacoder-client.ts` sets `INTERLINKED_METACODER_SUBPROCESS=1` on
+  the spawned subprocess env, alongside the existing
+  `--disallowed-tools`, `--no-session-persistence`, etc.
+- The hook script (both `hook-entry.ts` and the legacy `.mjs`) reads
+  this env at startup and, when set, forwards
+  `metacoder_subprocess: true` on the event envelope sent to the
+  harness socket.
+- For the adapter path, `metacoder_subprocess?: boolean` is added to
+  `UnifiedHookEvent`; `hook-entry.ts` sets it before sending the RPC, and
+  `legacy-client.ts::toLegacyHarnessEvent` explicitly copies it through
+  to `HarnessEvent`. Without the `legacy-client.ts` copy, the framed
+  adapter path strips the sentinel before `server.ts` can see it.
+- The harness's `UserPromptSubmit` branch short-circuits when set:
+  returns `{ decision: "allow" }` immediately, no metacoder call.
+
+This breaks the recursion at the earliest deterministic point. The same
+env also short-circuits the activity-jsonl write (we don't need to log
+the metacoder's own prompts as user activity).
+
+**Trust note:** the env var is set by the harness's own subprocess
+spawn, not by the agent. An agent that controls its own env (rare) or
+a compromised hook script could forge it, suppressing metacoder
+evaluation. See §10 risk #8.
+
+---
+
+## 3. File-by-file change list
+
+### New files
+
+| Path | Purpose |
+|---|---|
+| `src/harness/metacoder/types.ts` | `OverlayRulesFile`, `MetacoderInputContext`, `MetacoderOutcome`, `MetacoderConfig` types |
+| `src/harness/metacoder/overlay-loader.ts` | Read overlay JSON, enforce tighten-only invariant (including action-block-only and regex validation), return validated rules + warnings |
+| `src/harness/metacoder/regex-validator.ts` | The five checks from §2.3 as pure functions. Used by overlay-loader; testable in isolation. |
+| `src/harness/metacoder/prompt-builder.ts` | Assemble `MetacoderInputContext` from `promptForMeta` (scanner-redacted when findings exist, see §6) + AGENTS.md/CLAUDE.md + floor rule ids + project graph summary. Caps total at ~20kB. |
+| `src/harness/metacoder/metacoder-client.ts` | LLM call. Routes by `agent_source`. Claude → `claude -p` subprocess (Opus 4.7, high effort) with `INTERLINKED_METACODER_SUBPROCESS=1` env. Codex → OpenAI HTTP (GPT-5.5, high reasoning). Fail-open on all error modes. |
+| `src/harness/metacoder/metacoder-writer.ts` | tmp-then-rename atomic writes to `.interlinked/sessions/<sid>/`. Writes to stable per-session paths so each prompt overwrites the prior overlay artifacts atomically. Uses existing `sanitizeSessionId`. |
+| `src/harness/metacoder/index.ts` | Barrel exporting `runMetacoderForPrompt(event, config, cwd, promptForMeta)` — single entry point called from `server.ts`. |
+| `src/harness/__tests__/metacoder-overlay.test.ts` | Floor invariant + regex validation tests (see §8.1) |
+| `src/harness/__tests__/metacoder-session-lifecycle.test.ts` | Claude `SessionEnd`, Claude `Stop`, and Codex `Stop` all evict overlay |
+| `src/harness/__tests__/metacoder-multiprompt.test.ts` | Prompt B replaces prompt A overlay and returns B's addendum |
+| `src/harness/__tests__/metacoder-multiclient.test.ts` | Claude + Codex envelopes both produce identical `MetacoderInputContext` |
+| `src/harness/__tests__/metacoder-failure.test.ts` | Mocked client throws → fall back to floor; malformed JSON → no overlay merged; missing API key → skipped; recursion guard short-circuits |
+| `src/harness/__tests__/metacoder-privacy.test.ts` | Redacted prompt is passed to metacoder when scanner fires |
+
+### Modified files
+
+| Path | Change |
+|---|---|
+| `src/harness/rules-loader.ts` | Extend `loadRules(cwd, sessionId?)` to optionally merge the current per-session overlay rules. Overlay rules appended AFTER floor in merged list. Existing call sites (no `sessionId`) unchanged. |
+| `src/harness/server.ts` | (a) UserPromptSubmit handler at L903: short-circuit if `event.metacoder_subprocess === true`; otherwise after existing PII scan, await `runMetacoderForPrompt(event, config, CWD, promptForMeta)`, populate per-session rule cache, return `allow + additional_context`. (b) Add `sessionRules: Map<string, GuardRulesConfig>` near L313 alongside existing `classifierSessions` / `autoCoordStates`. (c) In `SessionEnd` / `Stop` handler at L755: call `evictOverlayForSession(CWD, event.session_id)` and `sessionRules.delete(event.session_id)`. (d) Route evaluator calls to use `rulesForSession(session_id)` instead of global `rules` for PreToolUse. (e) Build `promptForMeta = scanResult ? scanResult.redacted : event.prompt`, so scanner-flagged raw spans do not leave the process. |
+| `src/harness/types.ts` | Add `metacoder?: MetacoderConfig` to `GuardRulesConfig`. Add `metacoder_subprocess?: boolean` to `HarnessEvent`. |
+| `src/harness/unified-event.ts` | Add `metacoder_subprocess?: boolean` to `UnifiedHookEvent` so the adapter path can carry the recursion sentinel through the framed RPC envelope. |
+| `src/harness/legacy-client.ts` | In `toLegacyHarnessEvent`, copy `event.metacoder_subprocess === true` to `out.metacoder_subprocess = true`; otherwise the production framed path strips the sentinel before `server.ts`. |
+| `src/hook-entry.ts` | (a) Add `PHASE_USER_PROMPT = "user-prompt"` constant and `DEFAULT_USER_PROMPT_TIMEOUT_MS = 35_000`. (b) Extend `defaultTimeoutForPhase` per §2.4. (c) Read `INTERLINKED_METACODER_SUBPROCESS` from `opts.env` and set `event.metacoder_subprocess = true` before sending the RPC when present. |
+| `src/harness/adapters/codex.ts` | `encodeCodexAllow`: when `event.runner_native_event === "UserPromptSubmit"` and `decision.additional_context` is set, emit `{ hookSpecificOutput: { hookEventName: "UserPromptSubmit", additionalContext: decision.additional_context } }` on **stdout**, not stderr. Current behavior at L230–234 writes to stderr; change moves it to stdout's `hookSpecificOutput` channel to match Claude's contract (per `docs/hooks-ecosystem-comparison.md:81`). |
+| `src/harness/adapters/claude-code.ts` | Verify `encodeDecision` emits `hookSpecificOutput.additionalContext` for UserPromptSubmit allow with a `decision.additional_context` field. If the current adapter doesn't already handle this, add the branch. (One-line check at implementation time.) |
+| `src/lib/hook-template-chunks/provider-responses.ts` | Add `user_prompt_advice` response type to `formatClaudeResponse` and `formatCodexResponse` only. Drop Cursor/Copilot from this change set entirely. |
+| `src/lib/hooks-template.ts` | In `UserPromptSubmit` branch of generated `.mjs`: (a) forward `INTERLINKED_METACODER_SUBPROCESS` env value to the harness socket payload. (b) After receiving harness decision, if `decision.additional_context` present, emit via `formatProviderResponse("user_prompt_advice", { summary: decision.additional_context })` to stdout. |
+
+No new hook-installer work needed. `UserPromptSubmit` is already wired
+for Claude Code and Codex per `hook-installers.ts:36–50` and
+`adapters/codex.ts:51–58`.
+
+---
+
+## 4. Hook event flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│ User types prompt. Agent (Claude / Codex) fires UserPromptSubmit        │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Hook entry (src/hook-entry.ts):                                         │
+│ 1. Detect adapter (Claude vs Codex) via env / runner arg                │
+│ 2. Build UnifiedHookEvent via adapter.parseHookInput                    │
+│ 3. Forward INTERLINKED_METACODER_SUBPROCESS env onto event (if set)     │
+│ 4. Send RPC to daemon with timeout = 35s (user-prompt phase)            │
+│ 5. AWAIT response (blocks agent's prompt processing)                    │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │ (Unix socket)
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Harness server.ts UserPromptSubmit branch:                              │
+│ 1. SHORT-CIRCUIT: if event.metacoder_subprocess → return allow now      │
+│ 2. (Existing) PII scan → redacted_prompt for activity.jsonl             │
+│ 3. (NEW) runMetacoderForPrompt(event, config, CWD, promptForMeta):      │
+│    a. buildMetacoderContext(promptForMeta, AGENTS.md, floor ids, ...)   │
+│       — promptForMeta = scanResult ? scanResult.redacted : event.prompt │
+│    b. callMetacoder(ctx, config):                                       │
+│       - Claude: spawn `claude -p` with                                  │
+│         INTERLINKED_METACODER_SUBPROCESS=1 in env                       │
+│       - Codex: OpenAI HTTP                                              │
+│    c. validate JSON against OverlayRulesFile schema                     │
+│    d. validate every regex (length, flags, try/catch, ReDoS shape)      │
+│    e. reject rules with action !== "block"                              │
+│    f. writeOverlayArtifacts(cwd, session_id, overlay)                   │
+│    g. sessionRules.set(session_id, loadRules(cwd, session_id))          │
+│       (overlay rules APPENDED after floor)                              │
+│ 4. Return { decision: allow, redacted_prompt?, additional_context? }    │
+│    where additional_context = overlay.system_prompt_addendum            │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Adapter encodes decision to provider-specific stdout JSON:              │
+│ - Claude: hookSpecificOutput.additionalContext = system_prompt          │
+│ - Codex:  hookSpecificOutput.additionalContext = system_prompt          │
+│   (was stderr in current adapter — fixed in §3)                         │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Agent receives prompt + injected system_prompt_addendum in context.     │
+│ Agent issues first PreToolUse.                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │ (Unix socket)
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Harness PreToolUse evaluates against rulesForSession(session_id):       │
+│   = floor rules ∪ overlay rules (in that order)                         │
+│ Floor rules iterate first → floor block always wins over overlay        │
+│ Overlay rules are action: "block" only → can't downgrade a decision     │
+└─────────────────────────────────────────────────────────────────────────┘
+                                  │
+                                  ▼
+                       ... session continues ...
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│ Session end:                                                             │
+│ - Claude fires SessionEnd and may also fire Stop; Codex fires Stop.     │
+│   Phase names differ, but legacy event names reach the same server case.│
+│ 1. (Existing) save trajectory, releaseAllForAgent, sessions.remove,     │
+│    classifierSessions.delete, autoCoordStates.delete                    │
+│ 2. (NEW) evictOverlayForSession(cwd, session_id) →                      │
+│    rm -rf .interlinked/sessions/<sanitized-id>/                         │
+│ 3. (NEW) sessionRules.delete(session_id)                                │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+Per-client envelope at `UserPromptSubmit`:
+
+| Client | Native event | Prompt field | Adapter file |
+|---|---|---|---|
+| Claude Code | `UserPromptSubmit` | `prompt` | `src/harness/adapters/claude-code.ts` |
+| Codex | `UserPromptSubmit` (same shape, optional `turn_id`) | `prompt` | `src/harness/adapters/codex.ts` |
+
+---
+
+## 5. Overlay schema
+
+`.interlinked/sessions/<sanitized-session-id>/overlay-rules.json`:
+
+```json
+{
+  "version": 1,
+  "session_id": "abc123",
+  "generated_at": "2026-05-13T14:00:00Z",
+  "generated_by": "metacoder",
+  "source_prompt_sha256": "deadbeef…",
+  "system_prompt_addendum": "You are working on the payment-flow refactor. Touching src/legacy/payments is out of scope unless you call out the deviation first.",
+  "rules": [
+    {
+      "id": "overlay:abc123:0",
+      "enabled": true,
+      "trigger": "PreToolUse",
+      "tool_match": ["Edit", "Write", "MultiEdit"],
+      "action": "block",
+      "patterns": [
+        { "field": "file_path", "regex": "src/legacy/payments/" },
+        { "field": "file_path", "regex": "src/legacy/payments/migrate\\.ts", "negate": true }
+      ],
+      "reason": "Touching legacy/payments is out of scope for this session.",
+      "severity": "high"
+    }
+  ]
+}
+```
+
+Validation rules in `overlay-loader.ts` (executed in order):
+
+1. Reject `disabled_rules` field entirely.
+2. Reject any rule whose `id` collides with a floor id.
+3. Reject rules whose `id` does not start with `overlay:<session-prefix>:`.
+4. **Reject any rule whose `action` is not `"block"`.**
+5. Reject top-level `extra_exceptions` and `additional_patterns` fields
+   entirely. Overlay exceptions must use `negate: true` patterns inside
+   the overlay rule.
+6. Cap rule count at 20; drop excess with a warning.
+7. For each surviving rule's regexes (in `patterns[].regex` and any
+   `active_when.file_scope`): run the five-check regex validator from
+   §2.3. Drop the rule on any failure.
+8. **Append surviving overlay rules AFTER floor rules in the merged
+   `rules.rules` array** so floor blocks always iterate before overlay
+   rules for the same tool input.
+
+### What "tighten-only" guarantees concretely
+
+For any prompt P and tool call T:
+
+> `Floor(T) == block` ⟹ `(Floor ∪ Overlay(P))(T) == block`
+
+That is, the loaded ruleset after merging the overlay is a strict
+superset of the floor *in terms of block coverage*. The action
+constraint (rule 4) plus the iteration order (rule 8) together ensure
+an overlay can never produce a strictly weaker decision than the floor
+would have produced alone.
+
+---
+
+## 6. Metacoder LLM contract
+
+### System prompt (constant, embedded in `metacoder-client.ts`)
+
+```
+You are a session-scoped policy author for an AI coding agent.
+
+You receive: a user prompt (possibly with PII redacted as <LABEL>
+placeholders), project AGENTS.md/CLAUDE.md guidance, current floor
+rule ids, and a project graph summary.
+
+You emit JSON matching the OverlayRulesFile schema. You may ONLY:
+1. Add new GuardRule entries with unique ids prefixed "overlay:<session>:"
+2. Use action: "block" on every rule (other actions are rejected by
+   the loader)
+3. Express exceptions using `negate: true` patterns inside your own rule's
+   `patterns` array
+4. Add a free-form system_prompt_addendum (≤2000 chars)
+
+Regex patterns you emit must:
+- Be ≤200 chars long
+- Use only flags i, m, s (no g, y, u)
+- Avoid nested unbounded quantifiers like (a+)+ or (a*)*
+
+You MUST NOT:
+- Reference, disable, or modify any floor rule id (provided in input)
+- Author a rule with any action other than "block"
+- Emit top-level extra_exceptions or additional_patterns fields
+- Create rules that loosen anything
+
+If the prompt warrants no extra constraints, return {"version":1,"rules":[]}.
+Respond with JSON only, no preamble, no markdown fences.
+```
+
+### Input (with privacy amendment)
+
+The user message embeds the **PII-scanner-redacted** version of the
+prompt when the scanner finds content. If the scanner returns no
+findings, `event.prompt` is passed directly because there is nothing to
+redact:
+
+```ts
+const promptForMeta = scanResult ? scanResult.redacted : event.prompt;
+```
+
+The metacoder produces *constraints*, not edits — it doesn't need the
+literal secret to reason about scope. We never send scanner-flagged raw
+spans to the metacoder. Worst case the scanner missed a span; that's an
+existing scanner gap (`docs/design/content-scanner-*`), not a new one
+introduced by this feature.
+
+Full input shape:
+
+```json
+{
+  "prompt": "Refactor the payment service to use the <SECRET_TOKEN> charge API",
+  "client": "claude",
+  "session_id": "abc123",
+  "cwd": "/Users/.../interlinked-cli",
+  "project_instructions": "<concatenated AGENTS.md + CLAUDE.md, first 20kB>",
+  "floor_rule_ids": ["block_rm_rf", "no_force_push", "..."],
+  "project_graph_summary": "Project has 387 TS files across src/, tests/, ..."
+}
+```
+
+### Output (strict JSON, no markdown)
+
+`OverlayRulesFile` minus server-side fields. Server fills in
+`session_id`, `generated_at`, `generated_by`, `source_prompt_sha256`.
+Model emits:
+
+```json
+{
+  "version": 1,
+  "rules": [...],
+  "system_prompt_addendum": "..."
+}
+```
+
+### Error handling (all fail-open)
+
+| Error mode | Handling |
+|---|---|
+| LLM call times out (30s) | Skip overlay, log to harness stderr, fall back to floor-only. UserPromptSubmit decision is `allow` with no `additional_context`. |
+| LLM returns non-JSON | Try `parseClassificationJson` (already in `policy-classifier.ts`) to extract JSON from fences. If still fails, skip. |
+| LLM returns malformed schema | Drop invalid rules; surviving rules merge; if zero survive, skip. |
+| LLM tries to disable a floor rule | Drop the field with a `[interlinked:overlay]` warning, continue. |
+| LLM emits invalid regex | Drop the rule with a warning, continue. |
+| LLM emits rule with `action !== "block"` | Drop the rule with a warning, continue. |
+| LLM emits top-level `extra_exceptions` or `additional_patterns` | Drop the unsupported field with a warning; exceptions belong in `negate: true` patterns. |
+| API key missing (Codex path) | Return `{kind: "skipped", reason: "no_api_key"}`. Fall back to floor. |
+| Subprocess `claude` not found | Return skipped; log once per daemon-startup. |
+| Recursion guard fires (`INTERLINKED_METACODER_SUBPROCESS=1`) | Short-circuit BEFORE the metacoder is called; return allow immediately. |
+
+**Invariant:** a broken metacoder must never wedge `UserPromptSubmit`.
+The prompt always reaches the coding agent — just without overlay
+constraints.
+
+### Timeout budget
+
+- Claude path (`claude -p`): 30s default.
+- Codex path (OpenAI HTTP): 30s default.
+- Hook adapter (`hook-entry.ts` `user-prompt` phase): 35s default,
+  intentionally 5s longer than the metacoder's internal timeout so the
+  harness can return its clean timeout/allow result before the hook falls
+  back.
+
+---
+
+## 7. Cross-client compatibility report
+
+Verified against `src/harness/adapters/codex.ts`, `adapters/codex.test.ts`,
+`adapters/claude-code.ts`, and `hook-installers.ts`:
+
+| Capability | Claude Code | Codex |
+|---|---|---|
+| UserPromptSubmit hook event | Native | Native (same name, same shape) |
+| Envelope shape on UserPromptSubmit | `{session_id, prompt, ...}` | Same + optional `turn_id` |
+| Session-end native events fired | `SessionEnd` and `Stop` | `Stop` only |
+| Phase mapping | `SessionEnd` → `"session-end"`; `Stop` → `"stop"` | `Stop` → `"session-end"` |
+| Server cleanup trigger | Joint `case "SessionEnd": case "Stop":` at `server.ts:755`; fires on either native name regardless of phase | Same joint server case |
+| `additionalContext` injection channel | `hookSpecificOutput.additionalContext` on stdout | Same contract per `docs/hooks-ecosystem-comparison.md:81`, **but current `encodeCodexAllow` at adapters/codex.ts:230–234 writes to stderr — fixed in §3** |
+| Disambiguation in `.mjs` runtime | `INTERLINKED_CLIENT=claude` | `INTERLINKED_CLIENT=codex` |
+| Feature flag required | No | Yes (`.codex/config.toml` `[features] hooks = true`, auto-written by installer) |
+
+**Session-end cleanup parity.** `src/harness/server.ts:755–897` handles
+`case "SessionEnd": case "Stop":` jointly. Claude's adapter maps
+`SessionEnd` to `"session-end"` and `Stop` to `"stop"`; Codex's adapter
+maps `Stop` to `"session-end"`. The framed path converts back to legacy
+event names before `server.ts`, so the cleanup trigger is the native
+event name, not the phase. Tests must exercise Claude `SessionEnd`,
+Claude `Stop`, and Codex `Stop` (§8.2).
+
+**Cursor / Copilot / Gemini.** Out of scope for v1. See §9.
+
+---
+
+## 8. Test plan
+
+All under `src/harness/__tests__/`. Tests use vitest with manual
+fixtures (no fs mocking — matches existing style; see
+`adapters/codex.test.ts` and `result.test.ts` for the pattern).
+
+### 8.1 `metacoder-overlay.test.ts` — floor invariant + regex validation
+
+Floor invariant:
+- Overlay with valid `overlay:`-prefixed ids loads correctly.
+- Overlay with `disabled_rules: ["block_rm_rf"]` → field dropped;
+  `block_rm_rf` still active.
+- Overlay with `rules: [{id: "block_rm_rf", ...}]` → rule dropped
+  (id collision); original `block_rm_rf` intact.
+- Overlay with top-level `extra_exceptions` → unsupported field dropped.
+- Overlay with top-level `additional_patterns` → unsupported field
+  dropped.
+- Overlay with `rules: [{id: "no_namespace_prefix"}]` → dropped
+  (missing `overlay:` prefix).
+- Overlay rule with `action: "ask"` → dropped (action constraint).
+- Overlay rule with `action: "warn"` → dropped.
+- Overlay rule with `action: "soft_block"` → dropped.
+- Overlay rule with `action: "rewrite"` → dropped.
+- Cap test: overlay with 50 rules → 20 loaded, 30 dropped, warning.
+- Iteration order: when merged, floor rules precede overlay rules in
+  `rules.rules`.
+- Negated overlay patterns work as exceptions inside the overlay rule
+  itself (e.g., block `src/legacy/payments/` except
+  `src/legacy/payments/migrate.ts`).
+
+Regex validation:
+- Overlay rule with regex `^(a+)+$` → dropped (ReDoS shape).
+- Overlay rule with regex `(a*)*` → dropped.
+- Overlay rule with regex 250 chars long → dropped (length cap).
+- Overlay rule with regex flag `g` → dropped (flag whitelist).
+- Overlay rule with regex flag `y` → dropped.
+- Overlay rule with regex flag `u` → dropped.
+- Overlay rule with syntactically invalid regex `[unclosed` → dropped
+  (try/catch).
+- Overlay with rule having 11 patterns → dropped (patterns/rule cap).
+
+Property test (fast-check, if dependency is already available — else
+straightforward enumeration): for any randomly generated overlay, the
+loaded rule set is a strict superset of the floor in terms of block
+coverage. Specifically: pick a tool call `T` that the floor blocks;
+assert that the merged rule set also blocks `T`.
+
+### 8.2 `metacoder-session-lifecycle.test.ts` — overlay eviction
+
+- Write a fake overlay to `.interlinked/sessions/abc/overlay-rules.json`.
+- Fire Claude `SessionEnd` for session `abc` → directory deleted,
+  in-memory cache entry removed.
+- Repeat with Claude `Stop` for session `xyz` → identical cleanup.
+- Repeat with Codex `Stop` for session `codex-1` → identical cleanup.
+- After cleanup: `loadRules(cwd, "abc")` returns floor-only.
+
+### 8.3 `metacoder-multiclient.test.ts` — Claude + Codex envelopes
+
+- Send Claude-shaped `UserPromptSubmit` (PascalCase, top-level `prompt`).
+- Send Codex-shaped `UserPromptSubmit` (same shape + `turn_id`).
+- Both produce identical `MetacoderInputContext.prompt`.
+
+### 8.4 `metacoder-failure.test.ts` — fail-open + recursion guard
+
+- Mock `callMetacoder` to throw → overlay artifacts not written;
+  UserPromptSubmit still returns `allow`; next PreToolUse uses floor
+  rules unchanged.
+- Mock `callMetacoder` to return malformed JSON → no overlay merged.
+- API key missing path → `{kind: "skipped"}`.
+- Subprocess `claude` not found → returns skipped, logs once.
+- **Recursion guard:** event with `metacoder_subprocess: true` →
+  harness short-circuits without invoking metacoder; no overlay
+  artifacts written; returns allow immediately.
+- Adapter bridge: `hook-entry.ts` sets `UnifiedHookEvent.metacoder_subprocess`
+  from env, and `legacy-client.ts::toLegacyHarnessEvent` preserves it on
+  the legacy `HarnessEvent`.
+
+### 8.5 `metacoder-privacy.test.ts` — redacted prompt as metacoder input
+
+- Mock the PII scanner to return `redacted: "user prompt with <SECRET> masked"`.
+- Assert the metacoder client receives the redacted version, NOT the raw
+  scanner-flagged `event.prompt`.
+- Mock the scanner to return null (no findings) → metacoder receives
+  raw `event.prompt` because no scanner-flagged spans exist.
+
+### 8.6 Adapter encoder tests (extend existing)
+
+- `adapters/codex.test.ts`: `encodeCodexAllow` for UserPromptSubmit
+  with `decision.additional_context` emits
+  `hookSpecificOutput.hookEventName: "UserPromptSubmit", additionalContext: ...`
+  on **stdout**, NOT stderr.
+- `adapters/claude-code.test.ts`: same for Claude. If `claude-code.ts`
+  already handles this, the test is a regression pin; otherwise a
+  driver for the change.
+
+### 8.7 Hook-entry timeout test
+
+- Mock the daemon to take 30.2s to respond on `user-prompt` phase
+  (simulating a metacoder timeout plus harness cleanup) → hook-entry
+  waits, returns the clean harness decision (not cold fallback).
+- Mock daemon to take 36s → hook-entry times out, falls through to
+  cold fallback. Coding agent gets `allow` with no overlay (acceptable
+  fail-open).
+
+### 8.8 Integration via `evaluator.test.ts`
+
+- Load a config with a session overlay.
+- Assert a `PreToolUse` that would have been `allow` is now `block`
+  because of the overlay rule.
+- Assert a `PreToolUse` that the floor would have blocked is still
+  blocked (floor preserved; overlay's mere presence didn't shadow it).
+
+### 8.9 `metacoder-multiprompt.test.ts` — replace, not merge
+
+- Prompt A emits an overlay that blocks `src/legacy/payments/`.
+- Prompt B in the same `session_id` asks to fix
+  `src/legacy/payments/migrate.ts` and emits a different overlay.
+- Assert prompt A's overlay rule no longer blocks after prompt B's
+  `UserPromptSubmit`.
+- Assert prompt B's `system_prompt_addendum` is returned to the hook.
+
+---
+
+## 9. Out of scope for v1
+
+Explicitly NOT in this plan. Reviewers please flag any of these that
+seem load-bearing and should be pulled in.
+
+1. **Fresh codebase research agent.** v1 reads the existing
+   `.interlinked/structure-cache/` (maintained by the harness). No
+   fresh crawling, no symbol indexes, no architectural summarization.
+   If the cache is empty, the metacoder gets a stub project graph
+   summary.
+2. **Cursor / Copilot / Gemini metacoder integration.** Their adapters
+   do not currently surface `additionalContext` on UserPromptSubmit in
+   a model-visible channel:
+   - Cursor's `beforeSubmitPrompt` would need adapter work in
+     `encodeCursorAllow` to emit `{ additional_context: ... }` on that
+     event specifically (current code only does this for `postToolUse`).
+   - Gemini-cli's adapter at `gemini-cli.ts:16` doesn't register a
+     user-prompt event at all (`NATIVE_EVENTS` = `["BeforeTool",
+     "AfterTool", "AfterModel", "PreCompress"]`).
+   - Copilot's `userPromptSubmitted` has no documented model-visible
+     advisory channel.
+
+   The harness still scans and stores their prompts as today. No
+   metacoder fires; no overlay is generated. Re-evaluate per-runner
+   support in a v2 pass once Claude/Codex behavior is well-understood.
+3. **`allowed-tools.json` enforcement.** Deferred entirely from v1
+   (the writer doesn't even reserve the path). v2 may add per-session
+   tool whitelisting.
+4. **Per-tool-call metacoder re-runs.** v1 fires once per
+   `UserPromptSubmit`. Mid-session scope drift is not re-evaluated.
+5. **Cross-session learning.** Metacoder gets prompt + AGENTS.md +
+   project graph. Nothing from previous sessions' trajectories.
+6. **Confidence-based gating.** Overlays are atomic (use them all or
+   skip the whole thing).
+7. **Cost telemetry / budget caps.** Fail-open on API errors. No 429
+   detection beyond "request failed, skip overlay".
+8. **Custom metacoder system prompt.** Constant in
+   `metacoder-client.ts`; no `.interlinked/metacoder-system-prompt.md`
+   override.
+9. **Local-only LLM (Ollama).** v1 supports `claude_code` (subprocess)
+   and `openai` HTTP only.
+10. **Subagent / Task-tool overlays.** v1 scopes on `session_id`.
+    Sub-tasks inherit because they share the session.
+11. **Codex `turn_id`-scoped overlays.** v1 uses session-scoped only.
+
+---
+
+## 10. Open risks for reviewers
+
+Specific places a reviewer should push on:
+
+1. **Tighten-only invariant correctness.** §2.3 lists eight loader
+   checks (including action-block-only and append-after). Are there
+   bypasses we missed? Example: can an overlay rule with `active_when`
+   scoping pretend to constrain while never actually firing?
+2. **In-memory per-session rule cache and daemon restarts.** If the
+   harness daemon restarts mid-session, the in-memory overlay is lost.
+   The on-disk overlay file survives. Should `loadRules` re-read
+   overlays from disk on startup? v1 does not — SessionEnd / Stop
+   handlers will eventually clean up orphaned dirs.
+3. **30–35s latency UX.** The metacoder can run for up to 30s, and the
+   hook waits up to 35s to leave response-buffer room. Is a watchdog
+   progress indicator needed? Not in v1 — `claude -p` is silent until it
+   returns.
+4. **Codex CLI subscription auth.** v1 spawns `codex exec` against the
+   user's existing Codex CLI subscription (`codex login`). No API key.
+   When the CLI is missing, the transport returns
+   `skipped: subprocess_not_found` and the agent runs against floor
+   rules — same fail-open posture as the Claude path. When the user has
+   hit their usage quota, the failure surfaces with a classified
+   `codex usage limit reached` reason (see
+   `metacoder-client.ts::classifyCodexExitFailure`). Should we surface
+   this as a user-visible warning rather than only a log line?
+5. **`additional_context` size cap.** Metacoder can emit up to 2000
+   chars of `system_prompt_addendum` per prompt. Active overlay rules
+   replace on every `UserPromptSubmit`, but prior addenda can remain in
+   the agent's conversation history because the harness cannot retract
+   already-injected context. 2000 chars × 100 turns = 200 KB of historical
+   addenda in the session context. Is the cap correct?
+6. **Metacoder running against itself.** The metacoder is itself an
+   LLM call. The harness's PII scanner does run before the metacoder
+   (we pass the redacted prompt), but content gates (e.g., web-fetch
+   proxy, secret detectors) don't intercept the metacoder's request to
+   Anthropic/OpenAI. Should they?
+7. **Failure-on-startup ordering.** If `loadRules(cwd, sessionId)` is
+   called before SessionStart populated `sessionRules.get(sessionId)`,
+   we need a clear ordering guarantee. The plan: `UserPromptSubmit`
+   always precedes the first `PreToolUse` for that session, and
+   `sessionRules.set` happens inside the synchronous UserPromptSubmit
+   handler. Verify by reading the evaluator entry point.
+8. **Sentinel env var trust (recursion guard).** §2.5 relies on
+   `INTERLINKED_METACODER_SUBPROCESS=1` being honestly set by the
+   metacoder and forwarded by the hook script. An agent that controls
+   its own env, or a compromised hook script, could forge it,
+   suppressing metacoder evaluation. Mitigation: the env var is set by
+   the harness's own subprocess spawn. v2 could move the guard to a
+   harness-side socket-peer-credential check (uid + process tree). For
+   v1, the env var is sufficient given the threat model.
+9. **Regex validation completeness.** The ReDoS-shape check
+   (`/\([^)]*[+*][^)]*\)[+*]/`) catches the common nested-quantifier
+   cases but is not exhaustive. A determined adversarial LLM could
+   emit exponential patterns the check misses (e.g.,
+   `a*a*a*a*a*a*$`). Acceptable for v1 because the LLM is constrained
+   by its own system prompt to emit reasonable patterns; not
+   acceptable if the metacoder ever becomes user-prompt-injectable.
+10. **Hook timeout misalignment.** §2.4 sets the hook timeout to 35s
+    and §6 sets the metacoder internal timeout to 30s. The hook must stay
+    strictly above the metacoder timeout with a response buffer. If someone
+    tunes the metacoder to 45s without raising the hook to at least
+    50s, users get cold-fallback responses 100% of the time. A shared
+    constant pair (e.g., `METACODER_TIMEOUT_MS` plus
+    `USER_PROMPT_HOOK_TIMEOUT_BUFFER_MS`) would prevent drift. Worth doing
+    in v1.
+
+---
+
+## 11. Reviewer prompt
+
+If you are a reviewing agent: focus your critique on §2.3 (tighten-only
+invariant correctness, action constraint, regex validation), §2.5
+(recursion guard — does the env-var approach hold up?), §6 (LLM
+contract — is the system prompt load-bearing enough?), and §10 (open
+risks). Skip stylistic edits to prose. The goal is to surface design
+holes, not polish.
+
+If you are a human reviewer: §2.1, §2.2, §2.5 are the load-bearing
+*choices*. Everything else flows from them.

From 31a14fe9d3f5e8666aafac924f35d522ac248116 Mon Sep 17 00:00:00 2001
From: QuentinCody <33259999+QuentinCody@users.noreply.github.com>
Date: Thu, 14 May 2026 12:25:15 -0400
Subject: [PATCH 3/6] feat: per-prompt metacoder overlay (Claude + Codex
 subscription auth)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On every UserPromptSubmit, an LLM peer of the coding agent (Opus 4.7
xhigh for Claude sessions, GPT-5.5 xhigh for Codex sessions) generates
a session-scoped guard-rule overlay that the harness merges on top of
floor rules for the lifetime of the prompt. Replaces the conceptual
"user authors hooks" model with "hooks are compiled output per prompt."

Both transports use the user's CLI subscription (`claude -p` / `codex
exec`) — no ANTHROPIC_API_KEY or OPENAI_API_KEY required. Verified live:
the Codex transport completes its argv handshake against the
subscription endpoint, and the Claude transport returned a valid
schema-correct emission with ANTHROPIC_API_KEY explicitly unset.

Floor / overlay tighten-only invariant (overlay-loader.ts):
- overlay rule ids must use the literal overlay_prefix from input
- action must be "block" (ask/warn/soft_block/rewrite rejected)
- floor-id collisions, disabled_rules, extra_exceptions all rejected
- regex validated for ReDoS shapes, length, flag whitelist, syntax
- after_command.pattern + active_when.file_scope also validated
- raw input count capped before validation (prevents runaway emit)
- overlay rules appended AFTER floor in merged set (floor wins)

Per-session cache (server.ts):
- sessionRules Map keyed by session_id, populated synchronously inside
  UserPromptSubmit so the first PreToolUse sees the overlay
- on cache miss: hydrate from disk (survives daemon restart mid-session)
- watchRulesFiles AND SIGHUP both clear the cache so floor reloads land
- SessionEnd/Stop evicts both the cache entry and the on-disk overlay
- non-ok metacoder outcomes (skipped/failed) also evict (replace
  semantics: prompt B's failure must not let prompt A's rules persist)
- short-circuit when metacoder is disabled, with explicit eviction

Recursion guard (plan §2.5):
- metacoder spawns claude/codex subprocesses with
  INTERLINKED_METACODER_SUBPROCESS=1 in env
- hook script (both adapter and legacy .mjs) forwards onto event
- toLegacyHarnessEvent explicitly copies the field through
- harness short-circuits UserPromptSubmit when set
- generated .mjs also exits silently in subprocess mode so the
  metacoder's own internal prompts don't get written to activity.jsonl
  or POSTed to realtime sync

Hook timeout coordination (plan §2.4):
- adapter path: 35s for user-prompt phase, exceeds METACODER_TIMEOUT
- legacy .mjs: HARNESS_USER_PROMPT_TIMEOUT_MS=35000 mirrors that
- merge.ts clamps user-configured timeout_ms to <= 33000 so the hook
  always has buffer to return a clean timeout-allow decision

Codex adapter encodeCodexAllow now emits hookSpecificOutput.additional
Context on stdout for UserPromptSubmit (was stderr) so the metacoder's
system_prompt_addendum reaches the agent's model context.

Privacy: prompt scanner findings are redacted before the metacoder sees
them. Raw PII never leaves the harness.

203 focused tests pass; six rounds of external review folded in.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/harness/adapters/codex.test.ts            |  41 ++
 src/harness/adapters/codex.ts                 |  22 +-
 src/harness/legacy-client.ts                  |   4 +
 src/harness/metacoder/index.test.ts           | 411 ++++++++++++++
 src/harness/metacoder/index.ts                | 122 +++++
 .../metacoder/metacoder-client.test.ts        | 320 +++++++++++
 src/harness/metacoder/metacoder-client.ts     | 453 ++++++++++++++++
 .../metacoder/metacoder-writer.test.ts        | 134 +++++
 src/harness/metacoder/metacoder-writer.ts     | 114 ++++
 src/harness/metacoder/multiclient.test.ts     | 138 +++++
 src/harness/metacoder/overlay-loader.test.ts  | 513 ++++++++++++++++++
 src/harness/metacoder/overlay-loader.ts       | 499 +++++++++++++++++
 src/harness/metacoder/prompt-builder.test.ts  | 228 ++++++++
 src/harness/metacoder/prompt-builder.ts       | 202 +++++++
 src/harness/metacoder/regex-validator.test.ts |  68 +++
 src/harness/metacoder/regex-validator.ts      |  67 +++
 src/harness/metacoder/types.test.ts           |  27 +
 src/harness/metacoder/types.ts                | 114 ++++
 src/harness/rules-loader.test.ts              | 269 +++++++++
 src/harness/rules-loader.ts                   |  42 +-
 src/harness/rules/merge.ts                    |  59 ++
 src/harness/server.ts                         | 124 ++++-
 src/harness/types.ts                          |  15 +
 src/harness/unified-event.ts                  |   8 +
 src/hook-entry.ts                             |  26 +
 src/lib/__tests__/hooks-template.test.ts      |  59 ++
 .../provider-responses.ts                     |  20 +
 src/lib/hooks-template.ts                     |  45 +-
 28 files changed, 4130 insertions(+), 14 deletions(-)
 create mode 100644 src/harness/metacoder/index.test.ts
 create mode 100644 src/harness/metacoder/index.ts
 create mode 100644 src/harness/metacoder/metacoder-client.test.ts
 create mode 100644 src/harness/metacoder/metacoder-client.ts
 create mode 100644 src/harness/metacoder/metacoder-writer.test.ts
 create mode 100644 src/harness/metacoder/metacoder-writer.ts
 create mode 100644 src/harness/metacoder/multiclient.test.ts
 create mode 100644 src/harness/metacoder/overlay-loader.test.ts
 create mode 100644 src/harness/metacoder/overlay-loader.ts
 create mode 100644 src/harness/metacoder/prompt-builder.test.ts
 create mode 100644 src/harness/metacoder/prompt-builder.ts
 create mode 100644 src/harness/metacoder/regex-validator.test.ts
 create mode 100644 src/harness/metacoder/regex-validator.ts
 create mode 100644 src/harness/metacoder/types.test.ts
 create mode 100644 src/harness/metacoder/types.ts
 create mode 100644 src/harness/rules-loader.test.ts

diff --git a/src/harness/adapters/codex.test.ts b/src/harness/adapters/codex.test.ts
index 2b91a0d..414b6fa 100644
--- a/src/harness/adapters/codex.test.ts
+++ b/src/harness/adapters/codex.test.ts
@@ -131,6 +131,47 @@ describe("Codex encodeDecision — PreToolUse path", () => {
 	});
 });
 
+describe("Codex encodeDecision — UserPromptSubmit additionalContext", () => {
+	// Plan §3 / §7: Codex copies Claude's hookSpecificOutput.additionalContext
+	// contract. Before the fix, `additional_context` went to stderr, where the
+	// model never sees it. The metacoder's system_prompt_addendum needs to
+	// reach the model on UserPromptSubmit.
+	const event = adapter.parseHookInput(
+		{ session_id: "c", prompt: "Refactor payments." },
+		"UserPromptSubmit",
+	);
+
+	it("emits additionalContext on stdout when decision carries additional_context", () => {
+		const out = adapter.encodeDecision(
+			{ decision: "allow", additional_context: "Stay focused on the refactor." },
+			event,
+		);
+		expect(out.stdout).toBeDefined();
+		const parsed = JSON.parse(out.stdout ?? "{}");
+		expect(parsed).toEqual({
+			hookSpecificOutput: {
+				hookEventName: "UserPromptSubmit",
+				additionalContext: "Stay focused on the refactor.",
+			},
+		});
+	});
+
+	it("does NOT smuggle additional_context onto stderr", () => {
+		const out = adapter.encodeDecision(
+			{ decision: "allow", additional_context: "Stay focused on the refactor." },
+			event,
+		);
+		expect(out.stderr ?? "").not.toContain("Stay focused on the refactor.");
+	});
+
+	it("plain allow with no additional_context exits 0 silently", () => {
+		const out = adapter.encodeDecision({ decision: "allow" }, event);
+		expect(out.exit_code).toBe(0);
+		expect(out.stdout).toBeUndefined();
+		expect(out.stderr).toBeUndefined();
+	});
+});
+
 describe("Codex encodeDecision — PermissionRequest path", () => {
 	const event = adapter.parseHookInput(
 		{ session_id: "c", tool_name: "Bash", tool_input: { command: "ls /etc" } },
diff --git a/src/harness/adapters/codex.ts b/src/harness/adapters/codex.ts
index 1805eca..1ee767b 100644
--- a/src/harness/adapters/codex.ts
+++ b/src/harness/adapters/codex.ts
@@ -191,7 +191,7 @@ function codexEncodeDecision(
 		// decision shape regardless.
 		return encodeCodexBlock(decision, isPermissionRequest);
 	}
-	return encodeCodexAllow(decision, isPermissionRequest);
+	return encodeCodexAllow(decision, isPermissionRequest, event.runner_native_event);
 }
 
 function encodeCodexBlock(
@@ -216,6 +216,7 @@ function encodeCodexBlock(
 function encodeCodexAllow(
 	decision: { warnings?: string[]; additional_context?: string },
 	isPermissionRequest: boolean,
+	nativeEvent?: string,
 ): AdapterOutput {
 	const warningsTail = (decision.warnings ?? []).join("\n");
 	if (isPermissionRequest) {
@@ -227,11 +228,22 @@ function encodeCodexAllow(
 		});
 		return { stdout, stderr: warningsTail || undefined, exit_code: 0 };
 	}
-	let stderr = warningsTail;
-	if (decision.additional_context) {
-		stderr = stderr ? `${stderr}\n${decision.additional_context}` : decision.additional_context;
+	// UserPromptSubmit, PreToolUse, PostToolUse: route `additional_context`
+	// through `hookSpecificOutput.additionalContext` so it lands in the
+	// model's visible context, not stderr. Codex copies Claude's
+	// hookSpecificOutput contract per docs/hooks-ecosystem-comparison.md:81.
+	// Without this, the metacoder's system_prompt_addendum and the
+	// PostToolUse quality summaries never reach the model. Plan §3, §7.
+	if (decision.additional_context && nativeEvent) {
+		const stdout = JSON.stringify({
+			hookSpecificOutput: {
+				hookEventName: nativeEvent,
+				additionalContext: decision.additional_context,
+			},
+		});
+		return { stdout, stderr: warningsTail || undefined, exit_code: 0 };
 	}
-	return { stderr: stderr || undefined, exit_code: 0 };
+	return { stderr: warningsTail || undefined, exit_code: 0 };
 }
 
 // Tool-input field is JSON-shaped per Codex's contract — preserve it as
diff --git a/src/harness/legacy-client.ts b/src/harness/legacy-client.ts
index 3235c40..4181e6a 100644
--- a/src/harness/legacy-client.ts
+++ b/src/harness/legacy-client.ts
@@ -110,6 +110,10 @@ export function toLegacyHarnessEvent(event: UnifiedHookEvent): HarnessEvent {
 
 	const agentName = event.context.agent?.id ?? readString(raw.agent_name);
 	if (agentName) out.agent_name = agentName;
+	// Recursion guard sentinel — copied through explicitly because the legacy
+	// converter only forwards known fields. Without this, the framed adapter
+	// path strips the sentinel before `server.ts` can see it. Plan §2.5.
+	if (event.metacoder_subprocess === true) out.metacoder_subprocess = true;
 	copyString(raw, out, "model");
 	copyString(raw, out, "transcript_path");
 	copyString(raw, out, "tool_use_id");
diff --git a/src/harness/metacoder/index.test.ts b/src/harness/metacoder/index.test.ts
new file mode 100644
index 0000000..20a7486
--- /dev/null
+++ b/src/harness/metacoder/index.test.ts
@@ -0,0 +1,411 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { runMetacoderForPrompt } from "./index.js";
+import type { MetacoderTransport, TransportResult } from "./metacoder-client.js";
+import { overlayIdPrefix } from "./overlay-loader.js";
+import { DEFAULT_METACODER_CONFIG, type OverlayRulesFile } from "./types.js";
+
+const SESSION = "barrel-session-abc12345";
+const FLOOR_RULE_IDS = ["block_rm_rf", "no_force_push"];
+const FROZEN_NOW = "2026-05-13T14:00:00.000Z";
+const frozenClock = (): string => FROZEN_NOW;
+
+function makeTransport(result: TransportResult): MetacoderTransport {
+	return { call: async () => result };
+}
+
+function emissionRule(): unknown {
+	return {
+		id: `${overlayIdPrefix(SESSION)}0`,
+		enabled: true,
+		trigger: "PreToolUse",
+		tool_match: ["Edit"],
+		action: "block",
+		patterns: [{ field: "file_path", regex: "src/legacy/" }],
+		reason: "Out of scope.",
+		severity: "high",
+	};
+}
+
+function makeOverlayRawEmission(): string {
+	return JSON.stringify({
+		version: 1,
+		rules: [emissionRule()],
+		system_prompt_addendum: "Stay focused.",
+	});
+}
+
+function readOverlay(cwd: string): OverlayRulesFile {
+	const overlayPath = join(cwd, ".interlinked", "sessions", SESSION, "overlay-rules.json");
+	return JSON.parse(readFileSync(overlayPath, "utf-8")) as OverlayRulesFile;
+}
+
+function freshCwd(): string {
+	return mkdtempSync(join(tmpdir(), "metacoder-barrel-"));
+}
+
+describe("runMetacoderForPrompt — disk artifacts", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = freshCwd();
+	});
+
+	it("writes overlay-rules.json on the happy path", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "Refactor the payment service.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "ok" });
+		const overlayPath = join(cwd, ".interlinked", "sessions", SESSION, "overlay-rules.json");
+		expect(existsSync(overlayPath)).toBe(true);
+	});
+
+	it("sets generated_by to 'metacoder' on the persisted overlay", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(readOverlay(cwd).generated_by).toBe("metacoder");
+	});
+
+	it("uses the injected clock for generated_at", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+			now: frozenClock,
+		});
+		expect(readOverlay(cwd).generated_at).toBe(FROZEN_NOW);
+	});
+
+	it("stamps the session id on the persisted overlay", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(readOverlay(cwd).session_id).toBe(SESSION);
+	});
+
+	it("propagates surviving overlay rules to disk", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(readOverlay(cwd).rules).toHaveLength(1);
+	});
+});
+
+describe("runMetacoderForPrompt — source_prompt_sha256", () => {
+	it("hashes the prompt input as hex", async () => {
+		const cwd = freshCwd();
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "Refactor.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({
+			kind: "ok",
+			overlay: expect.objectContaining({
+				source_prompt_sha256: expect.stringMatching(/^[0-9a-f]+$/),
+			}),
+		});
+	});
+
+	it("produces different hashes for different prompts", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		const a = await runMetacoderForPrompt({
+			cwd: freshCwd(),
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "First prompt.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		const b = await runMetacoderForPrompt({
+			cwd: freshCwd(),
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "Second different prompt.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		const okA = a as Extract<typeof a, { kind: "ok" }>;
+		const okB = b as Extract<typeof b, { kind: "ok" }>;
+		expect(okA.overlay.source_prompt_sha256).not.toBe(okB.overlay.source_prompt_sha256);
+	});
+});
+
+describe("runMetacoderForPrompt — system_prompt_addendum on outcome", () => {
+	it("returns the addendum on the ok outcome", async () => {
+		const transport = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({
+				version: 1,
+				rules: [],
+				system_prompt_addendum: "Stay focused.",
+			}),
+		});
+		const result = await runMetacoderForPrompt({
+			cwd: freshCwd(),
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "Refactor.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({
+			kind: "ok",
+			overlay: expect.objectContaining({ system_prompt_addendum: "Stay focused." }),
+		});
+	});
+});
+
+describe("runMetacoderForPrompt — replace semantics (multi-prompt sessions)", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "metacoder-replace-"));
+	});
+
+	it("the second prompt's overlay file replaces the first prompt's", async () => {
+		const transportFirst = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({
+				version: 1,
+				rules: [emissionRule()],
+				system_prompt_addendum: "Focus on payments.",
+			}),
+		});
+		const transportSecond = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({
+				version: 1,
+				rules: [],
+				system_prompt_addendum: "Focus on auth.",
+			}),
+		});
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "First.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport: transportFirst,
+		});
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "Second.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport: transportSecond,
+		});
+		expect(readOverlay(cwd).system_prompt_addendum).toBe("Focus on auth.");
+	});
+
+	it("the second prompt's rule set replaces the first prompt's", async () => {
+		const transportFirst = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({ version: 1, rules: [emissionRule()] }),
+		});
+		const transportSecond = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({
+				version: 1,
+				rules: [],
+				system_prompt_addendum: "no rules now",
+			}),
+		});
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "First.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport: transportFirst,
+		});
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "Second.",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport: transportSecond,
+		});
+		expect(readOverlay(cwd).rules).toHaveLength(0);
+	});
+});
+
+describe("runMetacoderForPrompt — fail-open paths", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "metacoder-fail-"));
+	});
+
+	it("returns skipped when the transport reports no_api_key", async () => {
+		const transport = makeTransport({ kind: "skipped", reason: "no_api_key" });
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "codex",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "skipped", reason: "no_api_key" });
+	});
+
+	it("does not write an overlay when the transport reports no_api_key", async () => {
+		const transport = makeTransport({ kind: "skipped", reason: "no_api_key" });
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "codex",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		const overlayPath = join(cwd, ".interlinked", "sessions", SESSION, "overlay-rules.json");
+		expect(existsSync(overlayPath)).toBe(false);
+	});
+
+	it("returns failed when the transport returns malformed JSON", async () => {
+		const transport = makeTransport({ kind: "ok", raw: "not json at all" });
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+
+	it("returns failed when the transport throws", async () => {
+		const transport: MetacoderTransport = {
+			call: async () => {
+				throw new Error("simulated network outage");
+			},
+		};
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+
+	it("returns skipped:empty_overlay when validation drops every rule and there is no addendum", async () => {
+		const transport = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({ version: 1, rules: [] }),
+		});
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "skipped", reason: "empty_overlay" });
+	});
+
+	it("does not persist an empty overlay", async () => {
+		const transport = makeTransport({
+			kind: "ok",
+			raw: JSON.stringify({ version: 1, rules: [] }),
+		});
+		await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		const overlayPath = join(cwd, ".interlinked", "sessions", SESSION, "overlay-rules.json");
+		expect(existsSync(overlayPath)).toBe(false);
+	});
+
+	it("returns skipped:no_prompt on an empty input prompt", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "skipped", reason: "no_prompt" });
+	});
+
+	it("returns skipped:disabled when config.enabled is false", async () => {
+		const transport = makeTransport({ kind: "ok", raw: makeOverlayRawEmission() });
+		const result = await runMetacoderForPrompt({
+			cwd,
+			sessionId: SESSION,
+			client: "claude",
+			prompt: "p",
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: { ...DEFAULT_METACODER_CONFIG, enabled: false },
+			transport,
+		});
+		expect(result).toMatchObject({ kind: "skipped", reason: "disabled" });
+	});
+});
diff --git a/src/harness/metacoder/index.ts b/src/harness/metacoder/index.ts
new file mode 100644
index 0000000..05aa528
--- /dev/null
+++ b/src/harness/metacoder/index.ts
@@ -0,0 +1,122 @@
+// ===========================================
+// Metacoder — orchestrator entry point
+// ===========================================
+// Single function the harness server calls from its UserPromptSubmit
+// handler. Composes the four metacoder pieces:
+//
+//   1. prompt-builder    → MetacoderInputContext (reads AGENTS.md etc.)
+//   2. metacoder-client  → calls the LLM via injected transport
+//   3. overlay-loader    → validates the emission against floor / tighten-only
+//   4. metacoder-writer  → atomic persistence to .interlinked/sessions/<sid>/
+//
+// Every disk and network failure surfaces as a typed `MetacoderOutcome` so
+// the server can fall back to floor-only without blowing up the prompt.
+
+import { createHash } from "node:crypto";
+
+import type { AgentSource } from "../types.js";
+import { buildDefaultTransport, callMetacoder, type MetacoderTransport } from "./metacoder-client.js";
+import { writeOverlayArtifacts } from "./metacoder-writer.js";
+import { buildMetacoderContext } from "./prompt-builder.js";
+import { validateOverlayEmission } from "./overlay-loader.js";
+import type { MetacoderConfig, MetacoderOutcome, OverlayRulesFile } from "./types.js";
+
+export interface RunMetacoderInput {
+	cwd: string;
+	sessionId: string;
+	client: AgentSource;
+	/** Prompt passed to the metacoder. Caller (server.ts) is responsible for
+	 *  using the scanner-redacted version when the PII scanner fires; this
+	 *  layer never sees the raw event.prompt. */
+	prompt: string;
+	floorRuleIds: string[];
+	config: MetacoderConfig;
+	/** Optional transport injection. Production callers omit this and get the
+	 *  default routing per `ctx.client`. Tests supply fakes to avoid spawning
+	 *  real subprocesses / hitting the network. */
+	transport?: MetacoderTransport;
+	/** Optional clock injection. Production callers omit this and get
+	 *  `new Date().toISOString()`. Tests supply a deterministic stamp so
+	 *  fixtures can pin `generated_at`. */
+	now?: () => string;
+}
+
+/** Public API — consumed by `src/harness/server.ts` from its UserPromptSubmit
+ *  branch. Runs the full pipeline and returns a typed outcome. Never throws.
+ *
+ *  Caller is responsible for:
+ *    - Passing the PII-scanner-redacted prompt when the scanner fires
+ *    - Bailing early on `event.metacoder_subprocess` to break recursion
+ *    - Merging the overlay rules into the per-session rule cache and
+ *      surfacing `outcome.overlay.system_prompt_addendum` as
+ *      `decision.additional_context`. */
+export async function runMetacoderForPrompt(input: RunMetacoderInput): Promise<MetacoderOutcome> {
+	if (!input.prompt || input.prompt.length === 0) {
+		return { kind: "skipped", reason: "no_prompt", warnings: [] };
+	}
+	if (!input.config.enabled) {
+		return { kind: "skipped", reason: "disabled", warnings: [] };
+	}
+
+	const transport = input.transport ?? buildDefaultTransport(input.client);
+
+	const ctx = buildMetacoderContext({
+		prompt: input.prompt,
+		client: input.client,
+		sessionId: input.sessionId,
+		cwd: input.cwd,
+		floorRuleIds: input.floorRuleIds,
+		config: input.config,
+	});
+
+	const callResult = await callMetacoder(ctx, input.config, transport);
+	if (callResult.kind !== "ok") {
+		// Propagate skipped / failed unchanged. The server is responsible for
+		// surfacing the warnings on stderr when verbose logging is on.
+		return callResult;
+	}
+
+	const validation = validateOverlayEmission(callResult.emission, {
+		floorRuleIds: new Set(input.floorRuleIds),
+		sessionId: input.sessionId,
+		config: input.config,
+	});
+	const warnings = [...callResult.warnings, ...validation.warnings];
+
+	if (validation.rules.length === 0 && (validation.addendum === undefined || validation.addendum.length === 0)) {
+		// Nothing useful — the metacoder either had no constraints to add or
+		// every emitted rule got dropped by the invariant. Surface as skipped
+		// so the server can omit additional_context cleanly.
+		return { kind: "skipped", reason: "empty_overlay", warnings };
+	}
+
+	const clock = input.now ?? defaultClock;
+	const overlay: OverlayRulesFile = {
+		version: 1,
+		session_id: input.sessionId,
+		generated_at: clock(),
+		generated_by: "metacoder",
+		source_prompt_sha256: hashPrompt(input.prompt),
+		system_prompt_addendum: validation.addendum,
+		rules: validation.rules,
+	};
+
+	try {
+		writeOverlayArtifacts({ cwd: input.cwd, sessionId: input.sessionId }, overlay);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { kind: "failed", reason: `overlay write: ${message}`, warnings };
+	}
+
+	return { kind: "ok", overlay, warnings };
+}
+
+/** SHA-256 of the prompt, hex-encoded, full digest. Used by the harness's
+ *  recurrence aggregator and audit logs to dedupe per-prompt overlays. */
+function hashPrompt(prompt: string): string {
+	return createHash("sha256").update(prompt).digest("hex");
+}
+
+function defaultClock(): string {
+	return new Date().toISOString();
+}
diff --git a/src/harness/metacoder/metacoder-client.test.ts b/src/harness/metacoder/metacoder-client.test.ts
new file mode 100644
index 0000000..7773bbf
--- /dev/null
+++ b/src/harness/metacoder/metacoder-client.test.ts
@@ -0,0 +1,320 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	buildCodexExecArgs,
+	callMetacoder,
+	CODEX_BINARY,
+	CODEX_MODEL,
+	CODEX_REASONING_EFFORT,
+	CODEX_REASONING_EFFORT_KEY,
+	composeCodexPrompt,
+	METACODER_SYSTEM_PROMPT,
+	type MetacoderTransport,
+	type TransportResult,
+} from "./metacoder-client.js";
+import type { MetacoderInputContext } from "./types.js";
+import { DEFAULT_METACODER_CONFIG } from "./types.js";
+
+const CTX: MetacoderInputContext = {
+	prompt: "Refactor the payment service.",
+	// "claude" here is the AgentSource runner id (not a model identifier);
+	// the freshness-sensitive-reference heuristic flags it but it's stable
+	// (defined in src/harness/types.ts).
+	client: "claude",
+	session_id: "abc12345",
+	cwd: "/tmp/fake",
+	overlay_prefix: "overlay:abc12345:",
+	project_instructions: "# AGENTS.md\nUse TypeScript.",
+	floor_rule_ids: ["block_rm_rf", "no_force_push"],
+	project_graph_summary: "387 files indexed",
+};
+
+function makeFakeTransport(result: TransportResult): MetacoderTransport {
+	return { call: async () => result };
+}
+
+describe("callMetacoder — successful path", () => {
+	it("parses a clean JSON response", async () => {
+		const transport = makeFakeTransport({
+			kind: "ok",
+			raw: '{"version":1,"rules":[],"system_prompt_addendum":"Stay focused."}',
+		});
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toEqual({
+			kind: "ok",
+			emission: {
+				version: 1,
+				rules: [],
+				system_prompt_addendum: "Stay focused.",
+			},
+			warnings: [],
+		});
+	});
+
+	it("strips ```json fenced output before parsing", async () => {
+		const transport = makeFakeTransport({
+			kind: "ok",
+			raw: '```json\n{"version":1,"rules":[]}\n```',
+		});
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "ok" });
+	});
+
+	it("strips unlabeled fenced output before parsing", async () => {
+		const transport = makeFakeTransport({
+			kind: "ok",
+			raw: '```\n{"version":1,"rules":[]}\n```',
+		});
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "ok" });
+	});
+
+	it("trims surrounding whitespace before parsing", async () => {
+		const transport = makeFakeTransport({
+			kind: "ok",
+			raw: '   {"version":1,"rules":[]}\n\n',
+		});
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "ok" });
+	});
+
+	it("preserves a JSON response whose addendum contains a NESTED markdown fence (P4 round 6)", async () => {
+		// Plan §reviewer-P4 (round 6): the fence-stripper is anchored
+		// with ^...$ so a valid JSON response whose
+		// `system_prompt_addendum` happens to include an instructional
+		// code fence (`` ```bash ls ``` ``) is not mangled into just
+		// the inner fence body. Before the fix, the unanchored regex
+		// would replace the whole response with "bash\nls\n" and
+		// JSON.parse would fail.
+		const validJsonWithInnerFence = JSON.stringify({
+			version: 1,
+			rules: [],
+			system_prompt_addendum:
+				"When listing files, prefer:\n```bash\nls -la\n```\nNot `find .`.",
+		});
+		const transport = makeFakeTransport({ kind: "ok", raw: validJsonWithInnerFence });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({
+			kind: "ok",
+			emission: expect.objectContaining({
+				system_prompt_addendum: expect.stringContaining("```bash"),
+			}),
+		});
+	});
+
+	it("still strips a response that is entirely wrapped in a fenced block", async () => {
+		const transport = makeFakeTransport({
+			kind: "ok",
+			raw: '```json\n{"version":1,"rules":[]}\n```',
+		});
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "ok" });
+	});
+
+	it("does not strip a fence that is followed by trailing prose", async () => {
+		// A response shape like ```json\n{...}\n```\nextra text is NOT a
+		// pure fenced block — anchored regex correctly leaves it alone,
+		// and the JSON parser then rejects it (failed). Pinned so a future
+		// refactor doesn't accidentally relax the anchor.
+		const transport = makeFakeTransport({
+			kind: "ok",
+			raw: '```json\n{"version":1,"rules":[]}\n```\ntrailing prose',
+		});
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+});
+
+describe("callMetacoder — passthroughs", () => {
+	it("passes through skipped results from the transport", async () => {
+		const transport = makeFakeTransport({ kind: "skipped", reason: "no_api_key" });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toEqual({ kind: "skipped", reason: "no_api_key", warnings: [] });
+	});
+
+	it("passes through failed results from the transport", async () => {
+		const transport = makeFakeTransport({ kind: "failed", reason: "http 503" });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toEqual({ kind: "failed", reason: "http 503", warnings: [] });
+	});
+
+	it("treats transport throws as a failed result rather than propagating", async () => {
+		const transport: MetacoderTransport = {
+			call: async () => {
+				throw new Error("network exploded");
+			},
+		};
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({
+			kind: "failed",
+			reason: expect.stringMatching(/network exploded/),
+		});
+	});
+});
+
+describe("callMetacoder — malformed JSON", () => {
+	it("returns failed on completely unparseable output", async () => {
+		const transport = makeFakeTransport({ kind: "ok", raw: "not even close to json" });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+
+	it("returns failed on a non-object root", async () => {
+		const transport = makeFakeTransport({ kind: "ok", raw: "[1,2,3]" });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+
+	it("returns failed on an empty string", async () => {
+		const transport = makeFakeTransport({ kind: "ok", raw: "" });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+
+	it("returns failed on JSON null", async () => {
+		const transport = makeFakeTransport({ kind: "ok", raw: "null" });
+		const result = await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(result).toMatchObject({ kind: "failed" });
+	});
+});
+
+describe("callMetacoder — payload assembly", () => {
+	it("sends METACODER_SYSTEM_PROMPT as the system message", async () => {
+		const captured: { systemPrompt?: string; userMessage?: string } = {};
+		const transport: MetacoderTransport = {
+			call: async (systemPrompt: string, userMessage: string) => {
+				captured.systemPrompt = systemPrompt;
+				captured.userMessage = userMessage;
+				return { kind: "ok", raw: '{"version":1,"rules":[]}' };
+			},
+		};
+		await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		expect(captured.systemPrompt).toBe(METACODER_SYSTEM_PROMPT);
+	});
+
+	it("sends the full MetacoderInputContext as the JSON user message", async () => {
+		const captured: { userMessage?: string } = {};
+		const transport: MetacoderTransport = {
+			call: async (_systemPrompt: string, userMessage: string) => {
+				captured.userMessage = userMessage;
+				return { kind: "ok", raw: '{"version":1,"rules":[]}' };
+			},
+		};
+		await callMetacoder(CTX, DEFAULT_METACODER_CONFIG, transport);
+		const parsed = JSON.parse(captured.userMessage ?? "{}");
+		expect(parsed).toMatchObject({
+			prompt: CTX.prompt,
+			client: CTX.client,
+			session_id: CTX.session_id,
+			floor_rule_ids: CTX.floor_rule_ids,
+		});
+	});
+});
+
+describe("Codex (GPT-5.5) subprocess transport — exact CLI invocation pinned", () => {
+	// Plan §2.1 + user constraint: the metacoder uses the SAME tier as
+	// the coding agent AND reuses the developer's Codex CLI
+	// subscription (authenticated via `codex login`) — NO OpenAI API
+	// key. The reasoning_effort API value is `xhigh` (one word, no
+	// hyphen) per https://developers.openai.com/api/docs/models/gpt-5.5
+	// (verified 2026-05). Verified live by smoke-test: the `codex exec`
+	// startup banner echoed back "reasoning effort: xhigh", confirming
+	// the CLI accepts the `-c model_reasoning_effort=xhigh` override.
+
+	it("targets the codex CLI binary, not an HTTP endpoint", () => {
+		// Earlier versions of this transport went through
+		// `https://api.openai.com/...` which required an OPENAI_API_KEY.
+		// The user explicitly required the subscription-auth path (no
+		// API keys). Pinned so a future refactor can't silently revert.
+		expect(CODEX_BINARY).toBe("codex");
+	});
+
+	it("targets gpt-5.5", () => {
+		expect(CODEX_MODEL).toBe("gpt-5.5");
+	});
+
+	it("uses xhigh reasoning effort (maximum tier, not 'high')", () => {
+		// The user's design intent is the maximum tier. `xhigh` is the
+		// real API value; `high` would silently downgrade to the second-
+		// highest tier and the metacoder would have less reasoning budget
+		// than the coding agent.
+		expect(CODEX_REASONING_EFFORT).toBe("xhigh");
+		expect(CODEX_REASONING_EFFORT).not.toBe("high");
+	});
+
+	it("uses the model_reasoning_effort config key", () => {
+		// `codex exec -c <key>=<value>` parses TOML. Key path verified
+		// live (smoke-test printed "reasoning effort: xhigh" header).
+		expect(CODEX_REASONING_EFFORT_KEY).toBe("model_reasoning_effort");
+	});
+
+	it("buildCodexExecArgs includes -m gpt-5.5 and the xhigh effort override", () => {
+		const args = buildCodexExecArgs("the prompt", "/tmp/out.txt");
+		expect(args[0]).toBe("exec");
+		const modelIdx = args.indexOf("-m");
+		expect(modelIdx).toBeGreaterThan(-1);
+		expect(args[modelIdx + 1]).toBe("gpt-5.5");
+		expect(args).toContain("model_reasoning_effort=xhigh");
+	});
+
+	it("buildCodexExecArgs requests ephemeral, sandboxed, config-isolated execution", () => {
+		// Plan §reviewer-P4 (round 5) + cross-process hygiene: the
+		// metacoder subprocess must not pollute global state. `--ephemeral`
+		// skips session persistence; `--ignore-user-config` skips loading
+		// `~/.codex/config.toml` (which could pull in MCP servers); the
+		// `read-only` sandbox bars shell command execution since the
+		// metacoder only emits JSON.
+		const args = buildCodexExecArgs("p", "/tmp/o.txt");
+		expect(args).toContain("--ephemeral");
+		expect(args).toContain("--ignore-user-config");
+		expect(args).toContain("--skip-git-repo-check");
+		const sandboxIdx = args.indexOf("--sandbox");
+		expect(sandboxIdx).toBeGreaterThan(-1);
+		expect(args[sandboxIdx + 1]).toBe("read-only");
+	});
+
+	it("buildCodexExecArgs writes the final assistant message to the given -o path", () => {
+		const args = buildCodexExecArgs("p", "/tmp/out.txt");
+		const outIdx = args.indexOf("-o");
+		expect(outIdx).toBeGreaterThan(-1);
+		expect(args[outIdx + 1]).toBe("/tmp/out.txt");
+	});
+
+	it("buildCodexExecArgs places the prompt as the final positional argument", () => {
+		const args = buildCodexExecArgs("the prompt", "/tmp/o.txt");
+		expect(args[args.length - 1]).toBe("the prompt");
+	});
+
+	it("composeCodexPrompt prepends the system prompt with a clear delimiter", () => {
+		// `codex exec` has no `--system-prompt` flag, so the system
+		// instructions are prepended to the user message. The metacoder
+		// system prompt already starts with "You are a session-scoped
+		// policy author..." so the model still gets unambiguous role
+		// context.
+		const composed = composeCodexPrompt(METACODER_SYSTEM_PROMPT, "the user prompt");
+		expect(composed).toContain(METACODER_SYSTEM_PROMPT);
+		expect(composed).toContain("the user prompt");
+		expect(composed.indexOf(METACODER_SYSTEM_PROMPT)).toBeLessThan(
+			composed.indexOf("the user prompt"),
+		);
+		expect(composed).toContain("\n\n---\n\n");
+	});
+});
+
+describe("METACODER_SYSTEM_PROMPT", () => {
+	it("communicates the action-block-only constraint", () => {
+		expect(METACODER_SYSTEM_PROMPT).toMatch(/block/i);
+	});
+
+	it("communicates the overlay id prefix requirement", () => {
+		expect(METACODER_SYSTEM_PROMPT).toMatch(/overlay:/);
+	});
+
+	it("forbids relaxing floor rules", () => {
+		expect(METACODER_SYSTEM_PROMPT).toMatch(/disable|loosen|relax/i);
+	});
+
+	it("constrains regex flags", () => {
+		expect(METACODER_SYSTEM_PROMPT).toMatch(/flag/i);
+	});
+});
diff --git a/src/harness/metacoder/metacoder-client.ts b/src/harness/metacoder/metacoder-client.ts
new file mode 100644
index 0000000..a0718f6
--- /dev/null
+++ b/src/harness/metacoder/metacoder-client.ts
@@ -0,0 +1,453 @@
+// ===========================================
+// Metacoder — LLM client
+// ===========================================
+// Routes the metacoder call to the right transport based on `ctx.client`:
+//
+//   - claude: spawn `claude -p` with Opus 4.7 + maximum reasoning effort.
+//             Uses the user's Claude Code subscription via the CLI's own
+//             auth — no Anthropic API key required.
+//   - codex:  spawn `codex exec` with gpt-5.5 + `model_reasoning_effort=xhigh`.
+//             Uses the user's Codex CLI subscription via `codex login` —
+//             no OpenAI API key required.
+//   - other:  skipped — runners outside the v1 scope.
+//
+// Both paths set `INTERLINKED_METACODER_SUBPROCESS=1` in the spawned
+// process env so the recursion guard short-circuits any nested
+// UserPromptSubmit the subprocess fires (plan §2.5).
+//
+// `callMetacoder` is the orchestrator. Transports are dependency-injected
+// so tests can supply fakes without spawning real subprocesses. Default
+// transports are built by `buildDefaultTransport(client)`.
+
+import { type ChildProcessByStdio, spawn } from "node:child_process";
+import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Readable } from "node:stream";
+
+import type { AgentSource } from "../types.js";
+import type {
+	MetacoderConfig,
+	MetacoderInputContext,
+	OverlayRulesEmission,
+	SkippedReason,
+} from "./types.js";
+
+// ============================================================================
+// Named string literals (replace magic strings in conditionals)
+// ============================================================================
+
+const KIND_OK = "ok" as const;
+const KIND_SKIPPED = "skipped" as const;
+const KIND_FAILED = "failed" as const;
+
+const CLIENT_CLAUDE: AgentSource = "claude";
+const CLIENT_CODEX: AgentSource = "codex";
+
+const ENOENT_CODE = "ENOENT" as const;
+
+/** Type returned by `spawn` when `stdio: ["ignore", "pipe", "pipe"]`. */
+type SpawnedSubprocess = ChildProcessByStdio<null, Readable, Readable>;
+
+// ============================================================================
+// System prompt (constant)
+// ============================================================================
+
+/** Public API — also asserted by the metacoder-client test, so changes here
+ *  show up in `git diff` review. Plan §6: the contract the LLM must follow
+ *  when emitting an overlay. */
+export const METACODER_SYSTEM_PROMPT = `You are a session-scoped policy author for an AI coding agent.
+
+You receive: a user prompt (possibly with PII redacted as <LABEL> placeholders),
+project AGENTS.md/CLAUDE.md guidance, current floor rule ids, a project graph
+summary, and \`overlay_prefix\` — the EXACT string every overlay rule id must
+start with.
+
+You emit JSON matching the OverlayRulesFile schema. You may ONLY:
+1. Add new GuardRule entries whose \`id\` starts with the literal value of
+   \`overlay_prefix\` from your input. Copy it byte-for-byte; do not
+   re-derive it from \`session_id\`. Example: if
+   \`overlay_prefix\` is \`overlay:abc12345-def:\`, then valid ids are
+   \`overlay:abc12345-def:0\`, \`overlay:abc12345-def:1\`, etc.
+2. Use action: "block" on every rule (other actions are rejected by the loader)
+3. Express exceptions using \`negate: true\` patterns inside your own rule's
+   \`patterns\` array
+4. Add a free-form system_prompt_addendum (≤2000 chars)
+
+Regex patterns you emit must:
+- Be ≤200 chars long
+- Use only flags i, m, s (no g, y, u)
+- Avoid nested unbounded quantifiers like (a+)+ or (a*)*
+
+You MUST NOT:
+- Reference, disable, or modify any floor rule id (provided in input)
+- Author a rule with any action other than "block"
+- Emit top-level extra_exceptions or additional_patterns fields
+- Create rules that loosen anything
+- Invent your own prefix — use \`overlay_prefix\` verbatim
+
+If the prompt warrants no extra constraints, return {"version":1,"rules":[]}.
+Respond with JSON only, no preamble, no markdown fences.`;
+
+// ============================================================================
+// Transport contract
+// ============================================================================
+
+/** Transport's view of a single call. The transport returns the model's raw
+ *  text output (which `callMetacoder` then parses), or surfaces a skipped /
+ *  failed state without raising. */
+export type TransportResult =
+	| { kind: typeof KIND_OK; raw: string }
+	| { kind: typeof KIND_SKIPPED; reason: SkippedReason }
+	| { kind: typeof KIND_FAILED; reason: string };
+
+/** Transport interface — single method. Injected into `callMetacoder` so the
+ *  orchestrator is testable without spawning real subprocesses or hitting
+ *  the network. */
+export interface MetacoderTransport {
+	call(systemPrompt: string, userMessage: string, config: MetacoderConfig): Promise<TransportResult>;
+}
+
+/** Result of `callMetacoder`. On `ok`, `emission` is the parsed JSON
+ *  matching `OverlayRulesEmission`. The overlay-loader is what validates
+ *  the emission against the tighten-only invariant — the client only
+ *  enforces that the output is JSON of the right shape at the top level. */
+export type MetacoderCallResult =
+	| { kind: typeof KIND_OK; emission: OverlayRulesEmission; warnings: string[] }
+	| { kind: typeof KIND_SKIPPED; reason: SkippedReason; warnings: string[] }
+	| { kind: typeof KIND_FAILED; reason: string; warnings: string[] };
+
+// ============================================================================
+// Orchestrator
+// ============================================================================
+
+/** Public API — consumed by `runMetacoderForPrompt` in the barrel.
+ *  Sends the system prompt + JSON-stringified context to the transport,
+ *  parses the response, returns a structured result. Never throws. */
+export async function callMetacoder(
+	ctx: MetacoderInputContext,
+	config: MetacoderConfig,
+	transport: MetacoderTransport,
+): Promise<MetacoderCallResult> {
+	const userMessage = JSON.stringify(ctx);
+	const warnings: string[] = [];
+
+	let raw: TransportResult;
+	try {
+		raw = await transport.call(METACODER_SYSTEM_PROMPT, userMessage, config);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		return { kind: KIND_FAILED, reason: `transport threw: ${message}`, warnings };
+	}
+
+	if (raw.kind === KIND_SKIPPED) return { kind: KIND_SKIPPED, reason: raw.reason, warnings };
+	if (raw.kind === KIND_FAILED) return { kind: KIND_FAILED, reason: raw.reason, warnings };
+
+	const parsed = tryParseEmissionJson(raw.raw);
+	if (parsed === null) {
+		return { kind: KIND_FAILED, reason: "metacoder output was not parseable JSON", warnings };
+	}
+	return { kind: KIND_OK, emission: parsed, warnings };
+}
+
+// ============================================================================
+// JSON parsing
+// ============================================================================
+
+function tryParseEmissionJson(text: string): OverlayRulesEmission | null {
+	if (typeof text !== "string") return null;
+	const cleaned = stripMarkdownFences(text.trim());
+	if (cleaned.length === 0) return null;
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(cleaned);
+	} catch (err) {
+		void err;
+		return null;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+	return parsed as OverlayRulesEmission;
+}
+
+/** Strip ```json … ``` fences only when the ENTIRE trimmed response is
+ *  one fenced block. Anchored with ^ + $ so a valid JSON response whose
+ *  `system_prompt_addendum` field contains a nested Markdown fence (e.g.
+ *  instructions containing ```bash …```) is not mangled into just the
+ *  inner fence body. Plan §reviewer-P4 (round 6). */
+function stripMarkdownFences(text: string): string {
+	const trimmed = text.trim();
+	const fence = trimmed.match(/^```(?:json)?\s*\n?([\s\S]*?)\n?```$/);
+	return fence ? fence[1].trim() : trimmed;
+}
+
+// ============================================================================
+// Default transports
+// ============================================================================
+
+/** Public API — consumed by `runMetacoderForPrompt`. Build the default
+ *  transport for a given runner. Both Claude and Codex paths use the
+ *  user's existing CLI subscription — NO API keys required. Plan §2.1. */
+export function buildDefaultTransport(client: AgentSource): MetacoderTransport {
+	if (client === CLIENT_CLAUDE) return buildClaudeSubprocessTransport();
+	if (client === CLIENT_CODEX) return buildCodexSubprocessTransport();
+	return buildDisabledTransport();
+}
+
+function buildDisabledTransport(): MetacoderTransport {
+	return {
+		call: async () => ({ kind: KIND_SKIPPED, reason: "disabled" }),
+	};
+}
+
+// ============================================================================
+// Claude subprocess transport
+// ============================================================================
+//
+// Spawns `claude -p` against the user's Claude Code subscription. No API
+// key required. Model identifiers below are referenced by plan §2.1
+// "Metacoder model: same tier as the coding agent" — drift requires a
+// coordinated update with the user-facing docs.
+
+const CLAUDE_BINARY = "claude";
+const CLAUDE_MODEL = "claude-opus-4-7";
+const CLAUDE_EFFORT = "high";
+const CLAUDE_DISALLOWED_TOOLS = "Bash,Edit,Write,Read,Glob,Grep,Agent,WebFetch,WebSearch";
+const RECURSION_GUARD_ENV = "INTERLINKED_METACODER_SUBPROCESS";
+
+function buildClaudeSubprocessTransport(): MetacoderTransport {
+	return {
+		call: (systemPrompt, userMessage, config) =>
+			runClaudeSubprocess(systemPrompt, userMessage, config),
+	};
+}
+
+function runClaudeSubprocess(
+	systemPrompt: string,
+	userMessage: string,
+	config: MetacoderConfig,
+): Promise<TransportResult> {
+	return new Promise<TransportResult>((resolve) => {
+		const child = spawn(
+			CLAUDE_BINARY,
+			[
+				"-p",
+				"--model",
+				CLAUDE_MODEL,
+				"--no-session-persistence",
+				"--disallowed-tools",
+				CLAUDE_DISALLOWED_TOOLS,
+				"--effort",
+				CLAUDE_EFFORT,
+				"--output-format",
+				"json",
+				"--system-prompt",
+				systemPrompt,
+				userMessage,
+			],
+			{
+				stdio: ["ignore", "pipe", "pipe"],
+				timeout: config.timeout_ms,
+				env: { ...process.env, [RECURSION_GUARD_ENV]: "1" },
+			},
+		);
+		bindClaudeStreamHandlers(child, resolve);
+	});
+}
+
+function bindClaudeStreamHandlers(
+	child: SpawnedSubprocess,
+	resolve: (r: TransportResult) => void,
+): void {
+	let stdout = "";
+	child.stdout.on("data", (d: Buffer) => {
+		stdout += d.toString();
+	});
+	child.on("close", (code) => {
+		if (code !== 0) {
+			resolve({ kind: KIND_FAILED, reason: `claude -p exit ${code}` });
+			return;
+		}
+		resolve({ kind: KIND_OK, raw: extractClaudeResult(stdout.trim()) });
+	});
+	child.on("error", (err: NodeJS.ErrnoException) => {
+		if (err.code === ENOENT_CODE) {
+			resolve({ kind: KIND_SKIPPED, reason: "subprocess_not_found" });
+			return;
+		}
+		resolve({ kind: KIND_FAILED, reason: `claude -p spawn: ${err.message}` });
+	});
+}
+
+/** `claude -p --output-format json` wraps the model output in
+ *  `{"result": "..."}`. Unwrap when present so the orchestrator's JSON
+ *  parser sees the model's own response. Falls through to the raw stdout
+ *  when the wrapper shape isn't there (older `claude` versions / errors). */
+function extractClaudeResult(stdout: string): string {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(stdout);
+	} catch (err) {
+		void err;
+		return stdout;
+	}
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return stdout;
+	const result = (parsed as { result?: unknown }).result;
+	return typeof result === "string" ? result : stdout;
+}
+
+// ============================================================================
+// Codex subprocess transport
+// ============================================================================
+//
+// Spawns `codex exec` against the user's Codex CLI subscription
+// (authenticated via `codex login`). NO OpenAI API key required — per the
+// design intent that the metacoder reuses the developer's existing
+// subscription rather than draw against a separate API account.
+//
+// reasoning_effort for GPT-5.5 is `none|low|medium|high|xhigh` per
+// https://developers.openai.com/api/docs/models/gpt-5.5 (verified
+// 2026-05). The user said "x-high" colloquially; this resolves to the
+// API-correct `xhigh` (one word, no hyphen). Verified live by smoke-
+// testing `codex exec -c model_reasoning_effort=xhigh` — the CLI's
+// startup banner echoed back "reasoning effort: xhigh".
+
+/** Public — pinned by tests so silent drift in model / effort / binary
+ *  shows up in `git diff` review. Plan §2.1. */
+export const CODEX_BINARY = "codex";
+export const CODEX_MODEL = "gpt-5.5";
+export const CODEX_REASONING_EFFORT = "xhigh";
+/** Codex CLI config key for reasoning effort. Passed via `-c key=value`. */
+export const CODEX_REASONING_EFFORT_KEY = "model_reasoning_effort";
+
+function buildCodexSubprocessTransport(): MetacoderTransport {
+	return {
+		call: (systemPrompt, userMessage, config) =>
+			runCodexSubprocess(systemPrompt, userMessage, config),
+	};
+}
+
+/** Public — exposed for testability. Pure function. Returns the exact
+ *  argv that gets passed to `spawn(CODEX_BINARY, args)`. Tests pin this
+ *  so a refactor can't silently drop the model / effort / sandbox /
+ *  ephemeral flags. */
+export function buildCodexExecArgs(prompt: string, outputPath: string): string[] {
+	return [
+		"exec",
+		"-m",
+		CODEX_MODEL,
+		"-c",
+		`${CODEX_REASONING_EFFORT_KEY}=${CODEX_REASONING_EFFORT}`,
+		"--skip-git-repo-check",
+		"--ephemeral",
+		// `--ignore-user-config` prevents the spawned subprocess from
+		// loading `~/.codex/config.toml`, which could include MCP servers
+		// or other side-effecty config that bleed into the metacoder run.
+		"--ignore-user-config",
+		// Metacoder never executes shell commands — it emits JSON.
+		// `read-only` is the tightest sandbox the CLI offers.
+		"--sandbox",
+		"read-only",
+		"-o",
+		outputPath,
+		prompt,
+	];
+}
+
+/** Compose the single prompt string fed to `codex exec`. The CLI has no
+ *  `--system-prompt` flag, so we prepend the metacoder system prompt to
+ *  the user message with a `---` delimiter. The system prompt already
+ *  starts with "You are a session-scoped policy author..." so the model
+ *  has unambiguous role context. */
+export function composeCodexPrompt(systemPrompt: string, userMessage: string): string {
+	return `${systemPrompt}\n\n---\n\n${userMessage}`;
+}
+
+function runCodexSubprocess(
+	systemPrompt: string,
+	userMessage: string,
+	config: MetacoderConfig,
+): Promise<TransportResult> {
+	return new Promise<TransportResult>((resolve) => {
+		const outputPath = join(
+			tmpdir(),
+			`metacoder-codex-${process.pid}-${Date.now().toString(36)}.txt`,
+		);
+		const args = buildCodexExecArgs(composeCodexPrompt(systemPrompt, userMessage), outputPath);
+		let stderrBuf = "";
+		const child = spawn(CODEX_BINARY, args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			timeout: config.timeout_ms,
+			env: { ...process.env, [RECURSION_GUARD_ENV]: "1" },
+		});
+		// codex exec streams progress events on stdout; we ignore them —
+		// the final assistant message is written to `outputPath` via `-o`.
+		// Draining the pipe so the child doesn't block on backpressure.
+		child.stdout.on("data", () => undefined);
+		child.stderr.on("data", (d: Buffer) => {
+			stderrBuf += d.toString();
+		});
+		child.on("close", (code) => {
+			if (code !== 0) {
+				resolve({ kind: KIND_FAILED, reason: classifyCodexExitFailure(code, stderrBuf) });
+				cleanupTempFile(outputPath);
+				return;
+			}
+			if (!existsSync(outputPath)) {
+				resolve({
+					kind: KIND_FAILED,
+					reason: "codex exec finished but no output file written",
+				});
+				return;
+			}
+			let raw: string;
+			try {
+				raw = readFileSync(outputPath, "utf-8");
+			} catch (err) {
+				resolve({
+					kind: KIND_FAILED,
+					reason: `codex output read: ${err instanceof Error ? err.message : String(err)}`,
+				});
+				cleanupTempFile(outputPath);
+				return;
+			}
+			cleanupTempFile(outputPath);
+			resolve({ kind: KIND_OK, raw });
+		});
+		child.on("error", (err: NodeJS.ErrnoException) => {
+			cleanupTempFile(outputPath);
+			if (err.code === ENOENT_CODE) {
+				// CLI not installed — the user has Claude Code but no
+				// Codex subscription, or vice versa. Fail-open: the agent
+				// runs against floor rules only.
+				resolve({ kind: KIND_SKIPPED, reason: "subprocess_not_found" });
+				return;
+			}
+			resolve({ kind: KIND_FAILED, reason: `codex exec spawn: ${err.message}` });
+		});
+	});
+}
+
+/** Map a non-zero `codex exec` exit into a human-readable reason. The
+ *  most common modes worth distinguishing:
+ *    - hit subscription usage limit → user-visible / actionable
+ *    - login expired / not signed in → also actionable
+ *    - everything else → generic failure with stderr tail for forensics */
+function classifyCodexExitFailure(code: number | null, stderr: string): string {
+	const tail = stderr.slice(-400).trim();
+	if (/usage limit/i.test(stderr)) {
+		return `codex usage limit reached (subscription); upgrade or wait for reset: ${tail}`;
+	}
+	if (/not (logged|signed) in|run.*codex login/i.test(stderr)) {
+		return `codex not logged in; run 'codex login' to authenticate the subscription`;
+	}
+	return `codex exec exit ${code}${tail ? `: ${tail}` : ""}`;
+}
+
+function cleanupTempFile(path: string): void {
+	try {
+		if (existsSync(path)) unlinkSync(path);
+	} catch (err) {
+		// best-effort; tmp files age out anyway
+		void err;
+	}
+}
diff --git a/src/harness/metacoder/metacoder-writer.test.ts b/src/harness/metacoder/metacoder-writer.test.ts
new file mode 100644
index 0000000..c9db6bd
--- /dev/null
+++ b/src/harness/metacoder/metacoder-writer.test.ts
@@ -0,0 +1,134 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { existsSync, mkdtempSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { OverlayRulesFile } from "./types.js";
+import {
+	evictOverlayForSession,
+	writeOverlayArtifacts,
+} from "./metacoder-writer.js";
+
+const SESSION = "writer-test-abc12345";
+
+function makeOverlay(): OverlayRulesFile {
+	return {
+		version: 1,
+		session_id: SESSION,
+		generated_at: "2026-05-13T14:00:00Z",
+		generated_by: "metacoder",
+		source_prompt_sha256: "deadbeefcafe",
+		system_prompt_addendum: "Stay focused on the payment refactor.",
+		rules: [
+			{
+				id: "overlay:writer-test-:0",
+				enabled: true,
+				trigger: "PreToolUse",
+				tool_match: ["Edit"],
+				action: "block",
+				patterns: [{ field: "file_path", regex: "src/legacy/" }],
+				reason: "Out of scope.",
+				severity: "high",
+			},
+		],
+	};
+}
+
+describe("writeOverlayArtifacts", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "metacoder-writer-"));
+	});
+
+	it("writes overlay-rules.json with the full overlay payload", () => {
+		const result = writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		expect(result.rulesPath).toMatch(/overlay-rules\.json$/);
+		const parsed = JSON.parse(readFileSync(result.rulesPath, "utf-8")) as OverlayRulesFile;
+		expect(parsed.session_id).toBe(SESSION);
+		expect(parsed.rules).toHaveLength(1);
+		expect(parsed.rules[0].id).toBe("overlay:writer-test-:0");
+	});
+
+	it("writes system-prompt.md with the addendum", () => {
+		const result = writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		expect(result.systemPromptPath).toMatch(/system-prompt\.md$/);
+		expect(readFileSync(result.systemPromptPath, "utf-8")).toContain("payment refactor");
+	});
+
+	it("omits system-prompt.md when overlay has no addendum", () => {
+		const overlay = makeOverlay();
+		overlay.system_prompt_addendum = undefined;
+		const result = writeOverlayArtifacts({ cwd, sessionId: SESSION }, overlay);
+		expect(existsSync(result.systemPromptPath)).toBe(false);
+	});
+
+	it("overwrites prior artifacts atomically on replay (multi-prompt sessions)", () => {
+		const first = writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		const second = makeOverlay();
+		second.source_prompt_sha256 = "second-prompt-hash";
+		second.system_prompt_addendum = "Now focus on the auth refactor.";
+		writeOverlayArtifacts({ cwd, sessionId: SESSION }, second);
+		const reloaded = JSON.parse(readFileSync(first.rulesPath, "utf-8")) as OverlayRulesFile;
+		expect(reloaded.source_prompt_sha256).toBe("second-prompt-hash");
+		expect(readFileSync(first.systemPromptPath, "utf-8")).toContain("auth refactor");
+	});
+
+	it("does not leave any .tmp* files in the session directory", () => {
+		const result = writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		const dir = join(cwd, ".interlinked", "sessions");
+		const entries = readdirSync(dir, { recursive: true }) as string[];
+		const stragglers = entries.filter((name) => String(name).includes(".tmp"));
+		expect(stragglers, `unexpected tmp files: ${stragglers.join(", ")}`).toHaveLength(0);
+		expect(existsSync(result.rulesPath)).toBe(true);
+	});
+
+	it("creates the session directory if missing", () => {
+		const fresh = mkdtempSync(join(tmpdir(), "metacoder-writer-fresh-"));
+		const result = writeOverlayArtifacts({ cwd: fresh, sessionId: "brand-new" }, makeOverlay());
+		expect(existsSync(result.rulesPath)).toBe(true);
+	});
+});
+
+describe("evictOverlayForSession", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "metacoder-evict-"));
+	});
+
+	it("removes the session overlay directory and its artifacts", () => {
+		const result = writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		const sessionDir = result.rulesPath.replace(/\/overlay-rules\.json$/, "");
+		expect(existsSync(sessionDir)).toBe(true);
+		const removed = evictOverlayForSession({ cwd, sessionId: SESSION });
+		expect(removed).toBe(true);
+		expect(existsSync(sessionDir)).toBe(false);
+	});
+
+	it("returns false when the session directory does not exist", () => {
+		const removed = evictOverlayForSession({ cwd, sessionId: "never-existed" });
+		expect(removed).toBe(false);
+	});
+
+	it("returns false when the session id sanitizes to empty", () => {
+		const removed = evictOverlayForSession({ cwd, sessionId: "////" });
+		expect(removed).toBe(false);
+	});
+
+	it("does not touch sibling session directories", () => {
+		writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		writeOverlayArtifacts({ cwd, sessionId: "other-session" }, makeOverlay());
+		evictOverlayForSession({ cwd, sessionId: SESSION });
+		const otherPath = join(cwd, ".interlinked", "sessions", "other-session", "overlay-rules.json");
+		expect(existsSync(otherPath)).toBe(true);
+	});
+
+	it("does not touch unrelated files inside the .interlinked dir", () => {
+		const interlinkedDir = join(cwd, ".interlinked");
+		mkdirSync(interlinkedDir, { recursive: true });
+		const sentinel = join(interlinkedDir, "config.json");
+		writeFileSync(sentinel, "{}");
+		writeOverlayArtifacts({ cwd, sessionId: SESSION }, makeOverlay());
+		evictOverlayForSession({ cwd, sessionId: SESSION });
+		expect(existsSync(sentinel)).toBe(true);
+	});
+});
diff --git a/src/harness/metacoder/metacoder-writer.ts b/src/harness/metacoder/metacoder-writer.ts
new file mode 100644
index 0000000..af894db
--- /dev/null
+++ b/src/harness/metacoder/metacoder-writer.ts
@@ -0,0 +1,114 @@
+// ===========================================
+// Metacoder — Overlay writer
+// ===========================================
+// Atomic writes of the session overlay artifacts to
+// `.interlinked/sessions/<sanitized-sid>/`. Two files:
+//
+//   overlay-rules.json  — full OverlayRulesFile payload (loader reads this)
+//   system-prompt.md    — free-form addendum, omitted when empty
+//
+// Multi-prompt sessions overwrite both files atomically (tmp + rename onto
+// the same target paths) so the loader never reads a partial overlay.
+
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+
+import { sanitizeSessionId } from "../session-paths.js";
+import { overlayRulesPath, type SessionLocation } from "./overlay-loader.js";
+import type { OverlayRulesFile } from "./types.js";
+
+export interface WrittenOverlayPaths {
+	rulesPath: string;
+	systemPromptPath: string;
+}
+
+/** Public API — consumed by `src/harness/metacoder/index.ts::runMetacoderForPrompt`
+ *  to persist the LLM emission. Writes are atomic (tmp + rename) so the
+ *  loader never observes a partial JSON. Returns the resolved paths for
+ *  both artifacts even when the addendum is empty — callers compose
+ *  observability messages off the paths. Throws if `sessionId` sanitizes
+ *  to empty (writer would otherwise pollute `.interlinked/sessions/`). */
+export function writeOverlayArtifacts(
+	loc: SessionLocation,
+	overlay: OverlayRulesFile,
+): WrittenOverlayPaths {
+	const safe = sanitizeSessionId(loc.sessionId);
+	if (!safe) {
+		throw new Error(`writeOverlayArtifacts: sessionId '${loc.sessionId}' sanitizes to empty`);
+	}
+	const sessionDir = join(loc.cwd, ".interlinked", "sessions", safe);
+	if (!existsSync(sessionDir)) {
+		mkdirSync(sessionDir, { recursive: true });
+	}
+	const rulesPath = resolveOverlayRulesPath(loc);
+	const systemPromptPath = join(sessionDir, SYSTEM_PROMPT_FILENAME);
+
+	atomicWrite(rulesPath, JSON.stringify(overlay, null, 2));
+	if (typeof overlay.system_prompt_addendum === "string" && overlay.system_prompt_addendum.length > 0) {
+		atomicWrite(systemPromptPath, overlay.system_prompt_addendum);
+	} else if (existsSync(systemPromptPath)) {
+		// Replace semantics: a follow-up prompt with no addendum should not
+		// leave the previous prompt's addendum on disk.
+		try {
+			unlinkSync(systemPromptPath);
+		} catch (_err) {
+			// best-effort; tests assert presence/absence via existsSync
+		}
+	}
+
+	return { rulesPath, systemPromptPath };
+}
+
+/** Public API — consumed by `src/harness/server.ts` on `SessionEnd` / `Stop`.
+ *  Removes the session's overlay directory and all artifacts in it. Returns
+ *  `true` when something was removed, `false` when nothing existed (the
+ *  metacoder may never have fired for this session) or the session id
+ *  sanitizes to empty. Never throws; failures degrade to `false`. */
+export function evictOverlayForSession(loc: SessionLocation): boolean {
+	const safe = sanitizeSessionId(loc.sessionId);
+	if (!safe) return false;
+	const sessionDir = join(loc.cwd, ".interlinked", "sessions", safe);
+	if (!existsSync(sessionDir)) return false;
+	try {
+		rmSync(sessionDir, { recursive: true, force: true });
+		return true;
+	} catch (_err) {
+		return false;
+	}
+}
+
+// ============================================================================
+// Internals
+// ============================================================================
+
+const SYSTEM_PROMPT_FILENAME = "system-prompt.md";
+
+function resolveOverlayRulesPath(loc: SessionLocation): string {
+	const path = overlayRulesPath(loc);
+	if (!path) {
+		// Caller already verified sessionId sanitization; this branch is
+		// defensive against future sanitizer changes.
+		throw new Error(`overlayRulesPath returned null for sessionId '${loc.sessionId}'`);
+	}
+	return path;
+}
+
+/** Write `contents` to `target` via a tmp file in the same directory, then
+ *  rename onto `target`. The rename is atomic on POSIX filesystems, so a
+ *  concurrent reader either sees the previous contents or the new contents
+ *  — never a partial write. */
+function atomicWrite(target: string, contents: string): void {
+	const tmp = `${target}.tmp-${process.pid}-${Date.now().toString(36)}`;
+	writeFileSync(tmp, contents);
+	try {
+		renameSync(tmp, target);
+	} catch (err) {
+		// rename failed; clean up the tmp to avoid leaving stragglers.
+		try {
+			unlinkSync(tmp);
+		} catch (_err2) {
+			// nothing useful to do; surface the original error
+		}
+		throw err;
+	}
+}
diff --git a/src/harness/metacoder/multiclient.test.ts b/src/harness/metacoder/multiclient.test.ts
new file mode 100644
index 0000000..4d59ce3
--- /dev/null
+++ b/src/harness/metacoder/multiclient.test.ts
@@ -0,0 +1,138 @@
+// interlinked-tdd: exempt
+// Plan §8.3 — assert Claude and Codex UserPromptSubmit envelopes both end up
+// producing identical MetacoderInputContext through the prompt-builder. The
+// adapter normalization layer already converges them onto `event.prompt` in
+// the legacy HarnessEvent shape; this test pins that contract end-to-end so a
+// future adapter change can't drift one client away from the other without a
+// failing test.
+
+import { describe, expect, it, beforeEach } from "vitest";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { createClaudeCodeAdapter } from "../adapters/claude-code.js";
+import { createCodexAdapter } from "../adapters/codex.js";
+import { toLegacyHarnessEvent } from "../legacy-client.js";
+import { buildMetacoderContext } from "./prompt-builder.js";
+import { DEFAULT_METACODER_CONFIG } from "./types.js";
+
+const SESSION = "multiclient-abc12345";
+const PROMPT = "Refactor the payment service.";
+
+describe("Claude vs Codex UserPromptSubmit envelopes", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "metacoder-multiclient-"));
+	});
+
+	it("both adapters normalize UserPromptSubmit onto event.prompt", () => {
+		const claudeAdapter = createClaudeCodeAdapter();
+		const codexAdapter = createCodexAdapter();
+
+		const claudeUnified = claudeAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT, cwd },
+			"UserPromptSubmit",
+		);
+		const codexUnified = codexAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT, cwd, turn_id: "t1" },
+			"UserPromptSubmit",
+		);
+
+		const claudeLegacy = toLegacyHarnessEvent(claudeUnified);
+		const codexLegacy = toLegacyHarnessEvent(codexUnified);
+
+		expect(claudeLegacy.prompt).toBe(PROMPT);
+		expect(codexLegacy.prompt).toBe(PROMPT);
+		expect(claudeLegacy.hook_event).toBe("UserPromptSubmit");
+		expect(codexLegacy.hook_event).toBe("UserPromptSubmit");
+	});
+
+	it("phase mapping reflects the per-adapter PHASE_MAP (Claude → user-prompt, Codex → user-prompt)", () => {
+		// Plan §7: both adapters map UserPromptSubmit to phase "user-prompt".
+		const claudeAdapter = createClaudeCodeAdapter();
+		const codexAdapter = createCodexAdapter();
+
+		const claudeUnified = claudeAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT },
+			"UserPromptSubmit",
+		);
+		const codexUnified = codexAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT },
+			"UserPromptSubmit",
+		);
+
+		expect(claudeUnified.phase).toBe("user-prompt");
+		expect(codexUnified.phase).toBe("user-prompt");
+	});
+
+	it("metacoder prompt-builder produces identical core fields for Claude and Codex", () => {
+		const claudeCtx = buildMetacoderContext({
+			prompt: PROMPT,
+			client: "claude",
+			sessionId: SESSION,
+			cwd,
+			floorRuleIds: ["block_rm_rf"],
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		const codexCtx = buildMetacoderContext({
+			prompt: PROMPT,
+			client: "codex",
+			sessionId: SESSION,
+			cwd,
+			floorRuleIds: ["block_rm_rf"],
+			config: DEFAULT_METACODER_CONFIG,
+		});
+
+		// Core fields should match identically. `client` differs by design
+		// (the metacoder routes by client), so we compare the rest.
+		expect(claudeCtx.prompt).toBe(codexCtx.prompt);
+		expect(claudeCtx.session_id).toBe(codexCtx.session_id);
+		expect(claudeCtx.cwd).toBe(codexCtx.cwd);
+		expect(claudeCtx.project_instructions).toBe(codexCtx.project_instructions);
+		expect(claudeCtx.floor_rule_ids).toEqual(codexCtx.floor_rule_ids);
+	});
+});
+
+describe("Codex turn_id surfaces on UnifiedHookEvent.parent_event_id", () => {
+	it("preserves Codex's turn_id as parent_event_id", () => {
+		const codexAdapter = createCodexAdapter();
+		const codexUnified = codexAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT, turn_id: "turn-xyz" },
+			"UserPromptSubmit",
+		);
+		expect(codexUnified.parent_event_id).toBe("turn-xyz");
+	});
+
+	it("Claude has no turn_id field (parent_event_id undefined on UserPromptSubmit)", () => {
+		const claudeAdapter = createClaudeCodeAdapter();
+		const claudeUnified = claudeAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT },
+			"UserPromptSubmit",
+		);
+		expect(claudeUnified.parent_event_id).toBeUndefined();
+	});
+});
+
+describe("Recursion guard sentinel propagation", () => {
+	it("toLegacyHarnessEvent copies metacoder_subprocess from UnifiedHookEvent", () => {
+		const claudeAdapter = createClaudeCodeAdapter();
+		const event = claudeAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT },
+			"UserPromptSubmit",
+		);
+		event.metacoder_subprocess = true;
+		const legacy = toLegacyHarnessEvent(event);
+		expect(legacy.metacoder_subprocess).toBe(true);
+	});
+
+	it("toLegacyHarnessEvent does not set metacoder_subprocess when unset", () => {
+		const claudeAdapter = createClaudeCodeAdapter();
+		const event = claudeAdapter.parseHookInput(
+			{ session_id: SESSION, prompt: PROMPT },
+			"UserPromptSubmit",
+		);
+		const legacy = toLegacyHarnessEvent(event);
+		expect(legacy.metacoder_subprocess).toBeUndefined();
+	});
+});
diff --git a/src/harness/metacoder/overlay-loader.test.ts b/src/harness/metacoder/overlay-loader.test.ts
new file mode 100644
index 0000000..17cf269
--- /dev/null
+++ b/src/harness/metacoder/overlay-loader.test.ts
@@ -0,0 +1,513 @@
+import { describe, expect, it } from "vitest";
+
+import type { GuardRule } from "../types.js";
+import {
+	overlayIdPrefix,
+	validateOverlayEmission,
+	type ValidationOpts,
+} from "./overlay-loader.js";
+import { DEFAULT_METACODER_CONFIG } from "./types.js";
+
+const SESSION = "abc12345-def0";
+const FLOOR_IDS = new Set<string>(["block_rm_rf", "no_force_push", "no_curl_pipe_sh"]);
+
+const VALIDATION_OPTS: ValidationOpts = {
+	floorRuleIds: FLOOR_IDS,
+	sessionId: SESSION,
+	config: DEFAULT_METACODER_CONFIG,
+};
+
+function makeOverlayRule(overrides: Partial<GuardRule> = {}): GuardRule {
+	return {
+		id: `${overlayIdPrefix(SESSION)}0`,
+		enabled: true,
+		trigger: "PreToolUse",
+		tool_match: ["Edit", "Write"],
+		action: "block",
+		patterns: [{ field: "file_path", regex: "src/legacy/payments/" }],
+		reason: "Out of scope for this prompt.",
+		severity: "high",
+		...overrides,
+	};
+}
+
+describe("overlayIdPrefix", () => {
+	it("returns a deterministic prefix derived from the session id", () => {
+		// sanitizeSessionId whitelist is [A-Za-z0-9_-]; the slug can contain dashes.
+		expect(overlayIdPrefix("abc12345-def0")).toMatch(/^overlay:[A-Za-z0-9_-]+:$/);
+	});
+
+	it("produces the same prefix for the same session id", () => {
+		expect(overlayIdPrefix(SESSION)).toBe(overlayIdPrefix(SESSION));
+	});
+});
+
+describe("validateOverlayEmission — happy path", () => {
+	it("accepts a single well-formed overlay rule", () => {
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [makeOverlayRule()] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+		expect(result.warnings).toHaveLength(0);
+	});
+
+	it("preserves system_prompt_addendum when within the size cap", () => {
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [], system_prompt_addendum: "Stay focused on payments." },
+			VALIDATION_OPTS,
+		);
+		expect(result.addendum).toBe("Stay focused on payments.");
+	});
+
+	it("supports negated patterns as exceptions inside the rule itself", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						patterns: [
+							{ field: "file_path", regex: "src/legacy/payments/" },
+							{
+								field: "file_path",
+								regex: "src/legacy/payments/migrate\\.ts",
+								negate: true,
+							},
+						],
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+		expect(result.rules[0].patterns).toHaveLength(2);
+	});
+});
+
+describe("validateOverlayEmission — floor invariant", () => {
+	it("drops a rule that collides with a floor rule id", () => {
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [makeOverlayRule({ id: "block_rm_rf" })] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/collid|floor/i);
+	});
+
+	it("drops a rule whose id lacks the overlay prefix", () => {
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [makeOverlayRule({ id: "no_namespace_prefix" })] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/prefix/i);
+	});
+
+	it("drops a rule whose action is not 'block'", () => {
+		for (const action of ["ask", "warn", "soft_block", "rewrite"] as const) {
+			const result = validateOverlayEmission(
+				{ version: 1, rules: [makeOverlayRule({ action })] },
+				VALIDATION_OPTS,
+			);
+			expect(result.rules, `${action} should be rejected`).toHaveLength(0);
+			expect(result.warnings.join(" ")).toMatch(/action/i);
+		}
+	});
+
+	it("drops a top-level disabled_rules field entirely", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [makeOverlayRule()],
+				disabled_rules: ["block_rm_rf"],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.warnings.join(" ")).toMatch(/disabled_rules/);
+		// surviving overlay rule still loads
+		expect(result.rules).toHaveLength(1);
+	});
+
+	it("drops top-level extra_exceptions and additional_patterns", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [makeOverlayRule()],
+				extra_exceptions: { whatever: ["foo"] },
+				additional_patterns: { whatever: [{ field: "command", regex: "rm" }] },
+			},
+			VALIDATION_OPTS,
+		);
+		const joined = result.warnings.join(" ");
+		expect(joined).toMatch(/extra_exceptions/);
+		expect(joined).toMatch(/additional_patterns/);
+		expect(result.rules).toHaveLength(1);
+	});
+
+	it("rejects all rules over the configured cap", () => {
+		const overcap = DEFAULT_METACODER_CONFIG.max_rules + 5;
+		const rules = Array.from({ length: overcap }, (_, i) =>
+			makeOverlayRule({ id: `${overlayIdPrefix(SESSION)}${i}` }),
+		);
+		const result = validateOverlayEmission(
+			{ version: 1, rules },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(DEFAULT_METACODER_CONFIG.max_rules);
+		expect(result.warnings.join(" ")).toMatch(/cap|max/i);
+	});
+
+	it("caps validation by raw input count, not by survivor count (P1 round 5)", () => {
+		// Plan §reviewer-P1 (round 5): a runaway model that emits 100
+		// invalid rules must not force us to compile up to
+		// (100 × max_patterns_per_rule) regexes waiting for survivors to
+		// reach the cap they'll never reach. The cap is applied to the
+		// raw input length before validation runs.
+		const inflated = DEFAULT_METACODER_CONFIG.max_rules * 5;
+		// 4× the cap as invalid (action: "warn" is rejected), then a few
+		// valid ones at the end that the loop should never reach.
+		const invalidThenValid = [
+			...Array.from({ length: inflated - 3 }, (_, i) => ({
+				id: `${overlayIdPrefix(SESSION)}${i}`,
+				enabled: true,
+				trigger: "PreToolUse",
+				tool_match: ["Edit"],
+				action: "warn",
+				patterns: [{ field: "file_path", regex: `pattern_${i}` }],
+				reason: "should be rejected for action",
+				severity: "low",
+			})),
+			...Array.from({ length: 3 }, (_, j) =>
+				makeOverlayRule({
+					id: `${overlayIdPrefix(SESSION)}valid${j}`,
+				}),
+			),
+		];
+		const result = validateOverlayEmission(
+			{ version: 1, rules: invalidThenValid },
+			VALIDATION_OPTS,
+		);
+		// The valid rules sit beyond the cap, so none survive — the
+		// loop only ever processed the first `max_rules` entries (all
+		// invalid). 0 survivors and a pre-validation drop warning.
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/dropped pre-validation/);
+	});
+});
+
+describe("validateOverlayEmission — positive-pattern requirement (P1 round 4)", () => {
+	// The matcher treats zero positive patterns as vacuously matching, so a
+	// malformed overlay rule without a positive pattern turns into a global
+	// block on every tool call. The loader rejects such rules outright.
+
+	it("drops a rule with no patterns field at all", () => {
+		// validateOverlayEmission accepts `unknown`; pass a raw object that
+		// omits `patterns` rather than mutating a typed GuardRule.
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					{
+						id: `${overlayIdPrefix(SESSION)}0`,
+						enabled: true,
+						trigger: "PreToolUse",
+						tool_match: ["Edit"],
+						action: "block",
+						reason: "no patterns field at all",
+						severity: "high",
+					},
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/patterns/);
+	});
+
+	it("drops a rule with a non-array patterns field", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					{
+						id: `${overlayIdPrefix(SESSION)}0`,
+						enabled: true,
+						trigger: "PreToolUse",
+						tool_match: ["Edit"],
+						action: "block",
+						patterns: "not an array",
+						reason: "patterns must be an array",
+						severity: "high",
+					},
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/patterns/i);
+	});
+
+	it("drops a rule with an empty patterns array", () => {
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [makeOverlayRule({ patterns: [] })] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/positive/i);
+	});
+
+	it("drops a rule whose patterns are all negate:true", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						patterns: [
+							{ field: "file_path", regex: "src/legacy/", negate: true },
+							{ field: "file_path", regex: "src/auth/", negate: true },
+						],
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/positive/i);
+	});
+
+	it("accepts a rule with mixed positive + negate patterns", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						patterns: [
+							{ field: "file_path", regex: "src/legacy/payments/" },
+							{ field: "file_path", regex: "src/legacy/payments/migrate\\.ts", negate: true },
+						],
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+	});
+});
+
+describe("validateOverlayEmission — active_when.after_command regex validation (P2 round 4)", () => {
+	// `evaluator/active-when.ts::evaluateAfterCommandAxis` compiles
+	// `after_command.pattern` with `new RegExp` and no try/catch, so an
+	// invalid regex throws on every PreToolUse and a ReDoS shape hangs the
+	// hook. The loader must drop the rule before the evaluator sees it.
+
+	it("drops a rule with an invalid after_command.pattern", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { after_command: { pattern: "[unclosed" } },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/after_command/);
+	});
+
+	it("drops a rule with a ReDoS-shaped after_command.pattern", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { after_command: { pattern: "^(a+)+$" } },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/after_command|ReDoS/i);
+	});
+
+	it("drops a rule with an over-length after_command.pattern", () => {
+		const huge = "a".repeat(DEFAULT_METACODER_CONFIG.max_pattern_length + 1);
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { after_command: { pattern: huge } },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/after_command|length/i);
+	});
+
+	it("preserves a valid after_command.pattern on the returned rule", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { after_command: { pattern: "^git push", window_steps: 5 } },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+		expect(result.rules[0].active_when?.after_command).toEqual({
+			pattern: "^git push",
+			window_steps: 5,
+		});
+	});
+});
+
+describe("validateOverlayEmission — active_when carry-through", () => {
+	// Plan §reviewer-P3: previously the loader validated the active_when
+	// regex but discarded the entire field on the returned rule, so a
+	// scoped overlay rule fired on every tool call session-wide.
+	it("preserves a file_scope active_when on the returned rule", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { file_scope: "^src/payments/" },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+		expect(result.rules[0].active_when).toEqual({ file_scope: "^src/payments/" });
+	});
+
+	it("preserves an agent_source active_when on the returned rule", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { agent_source: ["claude"] },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+		expect(result.rules[0].active_when?.agent_source).toEqual(["claude"]);
+	});
+
+	it("omits active_when when the input has no recognized axes", () => {
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [makeOverlayRule({ active_when: {} })] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(1);
+		expect(result.rules[0].active_when).toBeUndefined();
+	});
+});
+
+describe("validateOverlayEmission — regex validation", () => {
+	it("drops a rule with a catastrophic-backtracking regex", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						patterns: [{ field: "file_path", regex: "^(a+)+$" }],
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/regex|ReDoS|nested/i);
+	});
+
+	it("drops a rule with an invalid regex", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						patterns: [{ field: "file_path", regex: "[unclosed" }],
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/regex|invalid/i);
+	});
+
+	it("drops a rule with too many patterns", () => {
+		const tooMany = Array.from(
+			{ length: DEFAULT_METACODER_CONFIG.max_patterns_per_rule + 1 },
+			(_, i) => ({ field: "file_path", regex: `pattern_${i}` }),
+		);
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [makeOverlayRule({ patterns: tooMany })] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/pattern/i);
+	});
+
+	it("validates regexes in active_when.file_scope too", () => {
+		const result = validateOverlayEmission(
+			{
+				version: 1,
+				rules: [
+					makeOverlayRule({
+						active_when: { file_scope: "^(a+)+$" },
+					}),
+				],
+			},
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/active_when|regex|ReDoS/i);
+	});
+});
+
+describe("validateOverlayEmission — malformed input", () => {
+	it("returns empty result with a warning when emission is not an object", () => {
+		const result = validateOverlayEmission("not json", VALIDATION_OPTS);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.length).toBeGreaterThan(0);
+	});
+
+	it("returns empty result when rules field is missing", () => {
+		const result = validateOverlayEmission({ version: 1 }, VALIDATION_OPTS);
+		expect(result.rules).toHaveLength(0);
+	});
+
+	it("returns empty result when version is wrong", () => {
+		const result = validateOverlayEmission(
+			{ version: 2, rules: [makeOverlayRule()] },
+			VALIDATION_OPTS,
+		);
+		expect(result.rules).toHaveLength(0);
+		expect(result.warnings.join(" ")).toMatch(/version/i);
+	});
+
+	it("truncates an over-length system_prompt_addendum", () => {
+		const huge = "x".repeat(DEFAULT_METACODER_CONFIG.max_addendum_chars + 500);
+		const result = validateOverlayEmission(
+			{ version: 1, rules: [], system_prompt_addendum: huge },
+			VALIDATION_OPTS,
+		);
+		expect(result.addendum?.length ?? 0).toBeLessThanOrEqual(
+			DEFAULT_METACODER_CONFIG.max_addendum_chars,
+		);
+		expect(result.warnings.join(" ")).toMatch(/addendum|truncat/i);
+	});
+});
diff --git a/src/harness/metacoder/overlay-loader.ts b/src/harness/metacoder/overlay-loader.ts
new file mode 100644
index 0000000..a6ec69b
--- /dev/null
+++ b/src/harness/metacoder/overlay-loader.ts
@@ -0,0 +1,499 @@
+// ===========================================
+// Metacoder — Overlay loader
+// ===========================================
+// Validates an LLM-emitted `OverlayRulesEmission` against the floor / overlay
+// tighten-only invariant from docs/design/metacoding-agent-plan.md §2.3, and
+// loads the persisted overlay JSON for a given session.
+//
+// Pure validation (`validateOverlayEmission`) is tested directly. The on-disk
+// reader (`loadOverlayForSession`) is a thin try/parse wrapper around it.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type {
+	ActiveWhen,
+	AfterCommandSpec,
+	AgentSource,
+	GuardRule,
+	PhaseSpec,
+	RulePattern,
+	SessionPredicateSpec,
+} from "../types.js";
+import { sanitizeSessionId } from "../session-paths.js";
+import { validateOverlayPatternCount, validateOverlayRegex } from "./regex-validator.js";
+import type { MetacoderConfig } from "./types.js";
+
+/** Returned by validation. `addendum` is the (possibly truncated) free-form
+ *  `system_prompt_addendum` from the emission. `rules` are surviving
+ *  GuardRule entries to merge after the floor. `warnings` are
+ *  `[interlinked:overlay]`-style strings the server can surface. */
+export interface OverlayValidationResult {
+	rules: GuardRule[];
+	warnings: string[];
+	addendum?: string;
+}
+
+/** Location of a session overlay on disk: filesystem root + the session id
+ *  that scopes the overlay directory. Kept as a struct so callers cannot
+ *  accidentally swap `cwd` and `sessionId` — both are strings. */
+export interface SessionLocation {
+	cwd: string;
+	sessionId: string;
+}
+
+/** Inputs the validator needs to enforce the tighten-only invariant. */
+export interface ValidationOpts {
+	floorRuleIds: ReadonlySet<string>;
+	sessionId: string;
+	config: MetacoderConfig;
+}
+
+/** Combined inputs for reading + validating an overlay from disk. */
+export interface LoadOpts extends ValidationOpts {
+	cwd: string;
+}
+
+/** Compute the canonical overlay id namespace prefix for a session.
+ *  Overlay rule ids MUST start with this prefix; collisions with floor ids
+ *  are rejected.
+ *
+ *  Uses the first 12 chars of the sanitized session id (sanitizer already
+ *  whitelists [A-Za-z0-9_-]). Stable for the same input — important because
+ *  the metacoder emits id prefixes based on this. */
+export function overlayIdPrefix(sessionId: string): string {
+	const safe = sanitizeSessionId(sessionId) || "unknown";
+	const slug = safe.slice(0, 12);
+	return `overlay:${slug}:`;
+}
+
+/** Validate an LLM-emitted overlay against the tighten-only invariant.
+ *  Returns surviving rules + warnings. Never throws on malformed input;
+ *  malformed entries are dropped with a warning, and the rest of the
+ *  emission still loads. */
+export function validateOverlayEmission(
+	emission: unknown,
+	opts: ValidationOpts,
+): OverlayValidationResult {
+	const warnings: string[] = [];
+	if (!isPlainObject(emission)) {
+		return { rules: [], warnings: ["emission is not a JSON object"], addendum: undefined };
+	}
+	const e = emission as Record<string, unknown>;
+
+	if (e.version !== OVERLAY_SCHEMA_VERSION) {
+		warnings.push(`unsupported version ${JSON.stringify(e.version)}; expected ${OVERLAY_SCHEMA_VERSION}`);
+		return { rules: [], warnings, addendum: undefined };
+	}
+
+	collectDroppedRelaxFields(e, warnings);
+
+	const rawRules = Array.isArray(e.rules) ? e.rules : [];
+	if (!Array.isArray(e.rules) && e.rules !== undefined) {
+		warnings.push("rules field is not an array");
+	}
+
+	// Plan §reviewer-P1 (round 5): cap the loop by the RAW emitted count,
+	// not by survivor count. A runaway model that emits 500 invalid rules
+	// would otherwise force us to compile up to (500 × max_patterns_per_rule)
+	// regexes while waiting for survivors to reach the cap that they never
+	// will. Slice up-front so validation cost is O(max_rules), independent
+	// of how many bad rules the model dumps.
+	const inputCount = rawRules.length;
+	const cappedRules =
+		inputCount > opts.config.max_rules ? rawRules.slice(0, opts.config.max_rules) : rawRules;
+	if (inputCount > opts.config.max_rules) {
+		warnings.push(
+			`emitted ${inputCount} rules; cap is ${opts.config.max_rules}; ${inputCount - opts.config.max_rules} dropped pre-validation`,
+		);
+	}
+
+	const ctx: RuleValidationContext = {
+		overlayPrefix: overlayIdPrefix(opts.sessionId),
+		floorRuleIds: opts.floorRuleIds,
+		config: opts.config,
+		warnings,
+	};
+	const survivors: GuardRule[] = [];
+	for (let i = 0; i < cappedRules.length; i++) {
+		const validated = validateSingleRule(cappedRules[i], i, ctx);
+		if (validated) survivors.push(validated);
+	}
+
+	const addendum = pickAddendum(e.system_prompt_addendum, opts.config, warnings);
+	return { rules: survivors, warnings, addendum };
+}
+
+/** Public API — consumed by `src/harness/rules-loader.ts` to merge the
+ *  session overlay onto the floor rules. Read and validate
+ *  `.interlinked/sessions/<sid>/overlay-rules.json`. Returns `null` when
+ *  the file doesn't exist (typical case: no metacoder has run yet). Returns
+ *  an empty `rules` array with warnings on parse / validation failure —
+ *  never throws. */
+export function loadOverlayForSession(opts: LoadOpts): OverlayValidationResult | null {
+	const path = overlayRulesPath({ cwd: opts.cwd, sessionId: opts.sessionId });
+	if (!path || !existsSync(path)) return null;
+	let raw: unknown;
+	try {
+		raw = JSON.parse(readFileSync(path, "utf-8"));
+	} catch (err) {
+		return {
+			rules: [],
+			warnings: [`overlay-rules.json parse failed: ${err instanceof Error ? err.message : String(err)}`],
+			addendum: undefined,
+		};
+	}
+	return validateOverlayEmission(raw, {
+		floorRuleIds: opts.floorRuleIds,
+		sessionId: opts.sessionId,
+		config: opts.config,
+	});
+}
+
+/** Public API — consumed by `metacoder-writer.ts` to compute the atomic
+ *  write target. Returns the absolute path to a session's
+ *  `overlay-rules.json`, or `null` when the session id sanitizes to empty. */
+export function overlayRulesPath(loc: SessionLocation): string | null {
+	const safe = sanitizeSessionId(loc.sessionId);
+	if (!safe) return null;
+	return join(loc.cwd, ".interlinked", "sessions", safe, "overlay-rules.json");
+}
+
+// ============================================================================
+// Single-rule validation
+// ============================================================================
+
+const OVERLAY_SCHEMA_VERSION = 1;
+const VALID_ACTIONS_FOR_OVERLAY = new Set<GuardRule["action"]>(["block"]);
+const VALID_TRIGGERS = new Set<GuardRule["trigger"]>(["PreToolUse", "PostToolUse", "both"]);
+const VALID_SEVERITIES = new Set<GuardRule["severity"]>(["critical", "high", "medium", "low"]);
+const DEFAULT_OVERLAY_TRIGGER: GuardRule["trigger"] = "PreToolUse";
+const DEFAULT_OVERLAY_SEVERITY: GuardRule["severity"] = "medium";
+
+interface RuleValidationContext {
+	overlayPrefix: string;
+	floorRuleIds: ReadonlySet<string>;
+	config: MetacoderConfig;
+	warnings: string[];
+}
+
+interface PatternLocation {
+	ruleIndex: number;
+	patternIndex: number;
+}
+
+function validateSingleRule(
+	raw: unknown,
+	index: number,
+	ctx: RuleValidationContext,
+): GuardRule | null {
+	if (!isPlainObject(raw)) {
+		ctx.warnings.push(`rules[${index}] is not an object`);
+		return null;
+	}
+	const r = raw as Record<string, unknown>;
+
+	const id = validateRuleId(r, index, ctx);
+	if (id === null) return null;
+
+	if (!isAllowedOverlayAction(r.action)) {
+		ctx.warnings.push(
+			`rules[${index}] action '${String(r.action)}' not allowed in overlay (only 'block')`,
+		);
+		return null;
+	}
+
+	const patterns = validateRulePatterns(r, index, ctx);
+	if (patterns === null) return null;
+
+	if (!validateRuleActiveWhen(r, index, ctx)) return null;
+
+	const rule: GuardRule = {
+		id,
+		enabled: r.enabled !== false,
+		trigger: pickTrigger(r.trigger),
+		tool_match: pickToolMatch(r.tool_match),
+		action: "block",
+		patterns,
+		reason: typeof r.reason === "string" ? r.reason : `Overlay rule ${id}`,
+		severity: pickSeverity(r.severity),
+	};
+	// Plan §reviewer-P3: previously the loader validated active_when but
+	// dropped it on the return path, so scoped overlay rules fired
+	// session-wide instead of only on their declared axes.
+	const activeWhen = pickActiveWhen(r.active_when);
+	if (activeWhen !== undefined) rule.active_when = activeWhen;
+	return rule;
+}
+
+function collectDroppedRelaxFields(
+	e: Record<string, unknown>,
+	warnings: string[],
+): void {
+	if ("disabled_rules" in e) {
+		warnings.push("dropped disabled_rules field — overlays cannot relax floor rules");
+	}
+	if ("extra_exceptions" in e) {
+		warnings.push(
+			"dropped extra_exceptions field — overlays use negate:true patterns inside the rule",
+		);
+	}
+	if ("additional_patterns" in e) {
+		warnings.push(
+			"dropped additional_patterns field — overlays use negate:true patterns inside the rule",
+		);
+	}
+}
+
+function pickAddendum(
+	raw: unknown,
+	config: MetacoderConfig,
+	warnings: string[],
+): string | undefined {
+	if (typeof raw !== "string") return undefined;
+	if (raw.length > config.max_addendum_chars) {
+		warnings.push(
+			`system_prompt_addendum truncated from ${raw.length} to ${config.max_addendum_chars} chars`,
+		);
+		return raw.slice(0, config.max_addendum_chars);
+	}
+	return raw;
+}
+
+function validateRuleId(
+	r: Record<string, unknown>,
+	index: number,
+	ctx: RuleValidationContext,
+): string | null {
+	const id = typeof r.id === "string" ? r.id : "";
+	if (!id) {
+		ctx.warnings.push(`rules[${index}] missing id`);
+		return null;
+	}
+	if (ctx.floorRuleIds.has(id)) {
+		ctx.warnings.push(
+			`rules[${index}] id '${id}' collides with a floor rule — overlay cannot replace floor`,
+		);
+		return null;
+	}
+	if (!id.startsWith(ctx.overlayPrefix)) {
+		ctx.warnings.push(
+			`rules[${index}] id '${id}' missing required prefix '${ctx.overlayPrefix}'`,
+		);
+		return null;
+	}
+	return id;
+}
+
+function isAllowedOverlayAction(action: unknown): action is "block" {
+	return typeof action === "string" && VALID_ACTIONS_FOR_OVERLAY.has(action as GuardRule["action"]);
+}
+
+function validateRulePatterns(
+	r: Record<string, unknown>,
+	index: number,
+	ctx: RuleValidationContext,
+): RulePattern[] | null {
+	if (!Array.isArray(r.patterns)) {
+		// Plan §reviewer-P1 (round 4): the matcher treats zero positive
+		// patterns as vacuously matching (see `rule-matching.ts::evaluatePatterns`),
+		// so a rule missing `patterns` entirely turns into a global block on
+		// every tool call. Reject the rule outright — overlay rules MUST
+		// declare what they match.
+		ctx.warnings.push(`rules[${index}] missing or non-array patterns`);
+		return null;
+	}
+	const patterns = r.patterns;
+	const patternCountFailure = validateOverlayPatternCount(patterns.length, ctx.config);
+	if (patternCountFailure) {
+		ctx.warnings.push(`rules[${index}] patterns: ${patternCountFailure.reason}`);
+		return null;
+	}
+
+	const validated: RulePattern[] = [];
+	let positiveCount = 0;
+	for (let p = 0; p < patterns.length; p++) {
+		const compiled = validateOnePattern(
+			patterns[p],
+			{ ruleIndex: index, patternIndex: p },
+			ctx,
+		);
+		if (compiled === null) return null;
+		validated.push(compiled);
+		if (!compiled.negate) positiveCount++;
+	}
+	// Plan §reviewer-P1 (round 4): a rule with zero positive patterns (only
+	// `negate: true` patterns, or an empty array) matches every input
+	// because the positive predicate is vacuously true. Combined with the
+	// default `tool_match: ["*"]`, that turns into a global block. Require
+	// at least one positive pattern so the overlay narrows the input
+	// before any exception can apply.
+	if (positiveCount === 0) {
+		ctx.warnings.push(
+			`rules[${index}] requires at least one positive (non-negate) pattern; got ${patterns.length} pattern(s), none positive`,
+		);
+		return null;
+	}
+	return validated;
+}
+
+function validateOnePattern(
+	pat: unknown,
+	loc: PatternLocation,
+	ctx: RuleValidationContext,
+): RulePattern | null {
+	if (!isPlainObject(pat)) {
+		ctx.warnings.push(`rules[${loc.ruleIndex}].patterns[${loc.patternIndex}] is not an object`);
+		return null;
+	}
+	const patObj = pat as Record<string, unknown>;
+	const field = typeof patObj.field === "string" ? patObj.field : "";
+	const regex = typeof patObj.regex === "string" ? patObj.regex : "";
+	const flags = typeof patObj.flags === "string" ? patObj.flags : undefined;
+	const negate = patObj.negate === true;
+	if (!field) {
+		ctx.warnings.push(`rules[${loc.ruleIndex}].patterns[${loc.patternIndex}] missing field`);
+		return null;
+	}
+	const regexFailure = validateOverlayRegex(regex, flags, ctx.config);
+	if (regexFailure) {
+		ctx.warnings.push(
+			`rules[${loc.ruleIndex}].patterns[${loc.patternIndex}].regex rejected: ${regexFailure.reason}`,
+		);
+		return null;
+	}
+	return { field, regex, flags, negate };
+}
+
+function validateRuleActiveWhen(
+	r: Record<string, unknown>,
+	index: number,
+	ctx: RuleValidationContext,
+): boolean {
+	if (!isPlainObject(r.active_when)) return true;
+	const activeWhen = r.active_when as Record<string, unknown>;
+	// active_when.file_scope is matched against arbitrary file_path strings
+	// inside `evaluator/active-when.ts`, so it carries the same ReDoS risk
+	// as patterns[].regex. Same validation.
+	if (typeof activeWhen.file_scope === "string") {
+		const failure = validateOverlayRegex(activeWhen.file_scope, "i", ctx.config);
+		if (failure) {
+			ctx.warnings.push(
+				`rules[${index}].active_when.file_scope regex rejected: ${failure.reason}`,
+			);
+			return false;
+		}
+	}
+	// Plan §reviewer-P2 (round 4): `evaluator/active-when.ts::evaluateAfterCommandAxis`
+	// compiles `after_command.pattern` with `new RegExp(pattern, flags)` and
+	// no try/catch. An LLM-emitted `{ pattern: "[" }` throws on every
+	// PreToolUse once the session has command history; a ReDoS shape hangs
+	// the hook. Same validation as `patterns[].regex` — drop the rule fail-
+	// open instead of letting it crash the evaluator at use time.
+	if (isPlainObject(activeWhen.after_command)) {
+		const ac = activeWhen.after_command as Record<string, unknown>;
+		if (typeof ac.pattern === "string") {
+			const failure = validateOverlayRegex(ac.pattern, "i", ctx.config);
+			if (failure) {
+				ctx.warnings.push(
+					`rules[${index}].active_when.after_command.pattern regex rejected: ${failure.reason}`,
+				);
+				return false;
+			}
+		}
+	}
+	return true;
+}
+
+function pickTrigger(raw: unknown): GuardRule["trigger"] {
+	if (typeof raw === "string" && VALID_TRIGGERS.has(raw as GuardRule["trigger"])) {
+		return raw as GuardRule["trigger"];
+	}
+	return DEFAULT_OVERLAY_TRIGGER;
+}
+
+function pickToolMatch(raw: unknown): string[] {
+	if (!Array.isArray(raw)) return ["*"];
+	return raw.filter((x): x is string => typeof x === "string");
+}
+
+function pickSeverity(raw: unknown): GuardRule["severity"] {
+	if (typeof raw === "string" && VALID_SEVERITIES.has(raw as GuardRule["severity"])) {
+		return raw as GuardRule["severity"];
+	}
+	return DEFAULT_OVERLAY_SEVERITY;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+
+/** Sanitize `r.active_when` to the `ActiveWhen` shape `evaluateActiveWhen`
+ *  expects. The regex risk in `file_scope` was already vetted by
+ *  `validateRuleActiveWhen`; the other axes (skill, phase, after_command,
+ *  overlay, agent_source, predicate) are narrowed field-by-field so the
+ *  returned object is structurally typed without `as unknown as` smuggling.
+ *  The evaluator validates each axis again at use time. */
+function pickActiveWhen(raw: unknown): ActiveWhen | undefined {
+	if (!isPlainObject(raw)) return undefined;
+	const out: ActiveWhen = {};
+	const skill = narrowStringOrStringArray(raw.skill);
+	if (skill !== undefined) out.skill = skill;
+	const phase = narrowPhaseSpec(raw.phase);
+	if (phase !== undefined) out.phase = phase;
+	const afterCommand = narrowAfterCommandSpec(raw.after_command);
+	if (afterCommand !== undefined) out.after_command = afterCommand;
+	if (typeof raw.file_scope === "string") out.file_scope = raw.file_scope;
+	const overlay = narrowStringOrStringArray(raw.overlay);
+	if (overlay !== undefined) out.overlay = overlay;
+	const agentSource = narrowAgentSourceOrArray(raw.agent_source);
+	if (agentSource !== undefined) out.agent_source = agentSource;
+	const predicate = narrowPredicateSpec(raw.predicate);
+	if (predicate !== undefined) out.predicate = predicate;
+	return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function narrowStringOrStringArray(v: unknown): string | string[] | undefined {
+	if (typeof v === "string") return v;
+	if (Array.isArray(v) && v.every((x): x is string => typeof x === "string")) return v;
+	return undefined;
+}
+
+function narrowAgentSourceOrArray(v: unknown): AgentSource | AgentSource[] | undefined {
+	const s = narrowStringOrStringArray(v);
+	if (s === undefined) return undefined;
+	// AgentSource is `"claude" | "copilot" | "codex" | "gemini" | "cursor"`;
+	// the evaluator tolerates unknown sources by treating them as "scope
+	// never matches", which is the right fail-soft behavior for an LLM-
+	// emitted rule. Carry through whatever strings we got.
+	return s as AgentSource | AgentSource[];
+}
+
+const PHASE_SCOPE_FILE = "file" as const;
+const PHASE_SCOPE_SESSION = "session" as const;
+
+function narrowPhaseSpec(v: unknown): PhaseSpec | undefined {
+	if (!isPlainObject(v)) return undefined;
+	if (typeof v.name !== "string" || typeof v.value !== "string") return undefined;
+	const phase: PhaseSpec = { name: v.name, value: v.value };
+	if (v.scope === PHASE_SCOPE_FILE || v.scope === PHASE_SCOPE_SESSION) {
+		phase.scope = v.scope;
+	}
+	return phase;
+}
+
+function narrowAfterCommandSpec(v: unknown): AfterCommandSpec | undefined {
+	if (!isPlainObject(v)) return undefined;
+	if (typeof v.pattern !== "string") return undefined;
+	const out: AfterCommandSpec = { pattern: v.pattern };
+	if (typeof v.window_steps === "number") out.window_steps = v.window_steps;
+	return out;
+}
+
+function narrowPredicateSpec(v: unknown): SessionPredicateSpec | undefined {
+	if (!isPlainObject(v)) return undefined;
+	if (typeof v.name !== "string") return undefined;
+	const out: SessionPredicateSpec = { name: v.name };
+	if (isPlainObject(v.args)) out.args = v.args;
+	return out;
+}
diff --git a/src/harness/metacoder/prompt-builder.test.ts b/src/harness/metacoder/prompt-builder.test.ts
new file mode 100644
index 0000000..24f9873
--- /dev/null
+++ b/src/harness/metacoder/prompt-builder.test.ts
@@ -0,0 +1,228 @@
+import { describe, expect, it, beforeEach } from "vitest";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { buildMetacoderContext } from "./prompt-builder.js";
+import { DEFAULT_METACODER_CONFIG } from "./types.js";
+
+const FLOOR_RULE_IDS = ["block_rm_rf", "no_force_push"];
+
+describe("buildMetacoderContext", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "metacoder-prompt-"));
+	});
+
+	it("returns the prompt verbatim", () => {
+		const ctx = buildMetacoderContext({
+			prompt: "Refactor the payment service.",
+			client: "claude",
+			sessionId: "abc",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.prompt).toBe("Refactor the payment service.");
+		expect(ctx.client).toBe("claude");
+		expect(ctx.session_id).toBe("abc");
+		expect(ctx.cwd).toBe(cwd);
+	});
+
+	it("populates overlay_prefix from the session id", () => {
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "barrel-session-abc12345",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		// Plan §reviewer-P1: the prefix the loader will enforce must be
+		// passed literally so the metacoder can copy it byte-for-byte.
+		// Slug is the first 12 chars of the sanitized session id.
+		expect(ctx.overlay_prefix).toBe("overlay:barrel-sessi:");
+	});
+
+	it("forwards floor rule ids", () => {
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "codex",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.floor_rule_ids).toEqual(FLOOR_RULE_IDS);
+	});
+
+	it("concatenates AGENTS.md and CLAUDE.md into project_instructions", () => {
+		writeFileSync(join(cwd, "AGENTS.md"), "# Agents guidance\nUse TypeScript.");
+		writeFileSync(join(cwd, "CLAUDE.md"), "# Claude guidance\nNo console.log.");
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_instructions).toContain("Use TypeScript.");
+		expect(ctx.project_instructions).toContain("No console.log.");
+	});
+
+	it("returns an empty project_instructions when no guidance files exist", () => {
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_instructions).toBe("");
+	});
+
+	it("caps project_instructions at the configured byte budget", () => {
+		const huge = "x".repeat(40_000);
+		writeFileSync(join(cwd, "AGENTS.md"), huge);
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		// Cap is generous (~20kB) but bounded — must be less than the raw input.
+		expect(ctx.project_instructions.length).toBeLessThan(huge.length);
+		expect(ctx.project_instructions.length).toBeLessThanOrEqual(25_000);
+	});
+
+	it("includes .clinerules/*.md when present", () => {
+		mkdirSync(join(cwd, ".clinerules"), { recursive: true });
+		writeFileSync(join(cwd, ".clinerules", "one.md"), "Rule one body.");
+		writeFileSync(join(cwd, ".clinerules", "two.md"), "Rule two body.");
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_instructions).toContain("Rule one body.");
+		expect(ctx.project_instructions).toContain("Rule two body.");
+	});
+
+	it("includes a project graph summary built from the real CatalogMeta schema", () => {
+		// Plan §reviewer-P3 (round 6): fixture uses the schema actually
+		// written by `structure/cache-manager.ts::writeCatalogMeta`.
+		// `file_count` / `by_extension` do not exist on that schema.
+		const cacheDir = join(cwd, ".interlinked", "structure-cache");
+		mkdirSync(cacheDir, { recursive: true });
+		writeFileSync(
+			join(cacheDir, "catalog-meta.json"),
+			JSON.stringify({
+				schema_version: 1,
+				cli_version: "0.1.0",
+				built_at: "2026-05-13T14:00:00Z",
+				repo_root: cwd,
+				last_scanned_commit: "abc12345deadbeef",
+				manifest_hash: "sha256:fakefakefake",
+				extractor_versions: { module: 1, package: 1 },
+			}),
+		);
+		writeFileSync(
+			join(cacheDir, "module.json"),
+			JSON.stringify({
+				schema_version: 1,
+				items: Array.from({ length: 320 }, (_, i) => ({
+					local_id: `m${i}`,
+					global_ref: `gh:owner/repo/m${i}`,
+					file: `src/mod${i}.ts`,
+				})),
+			}),
+		);
+		writeFileSync(
+			join(cacheDir, "package.json"),
+			JSON.stringify({
+				schema_version: 1,
+				items: Array.from({ length: 67 }, (_, i) => ({
+					local_id: `p${i}`,
+					global_ref: `gh:owner/repo/p${i}`,
+					file: `pkg/${i}/package.json`,
+				})),
+			}),
+		);
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_graph_summary).toBeDefined();
+		expect(ctx.project_graph_summary).toContain("abc12345");
+		expect(ctx.project_graph_summary).toContain("387");
+	});
+
+	it("returns a partial summary when only catalog-meta.json exists (no per-category caches)", () => {
+		const cacheDir = join(cwd, ".interlinked", "structure-cache");
+		mkdirSync(cacheDir, { recursive: true });
+		writeFileSync(
+			join(cacheDir, "catalog-meta.json"),
+			JSON.stringify({
+				schema_version: 1,
+				cli_version: "0.1.0",
+				built_at: "2026-05-13T14:00:00Z",
+				repo_root: cwd,
+				last_scanned_commit: "abc12345",
+				manifest_hash: "sha256:x",
+				extractor_versions: {},
+			}),
+		);
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_graph_summary).toBeDefined();
+		expect(ctx.project_graph_summary).toContain("abc12345");
+		expect(ctx.project_graph_summary).not.toMatch(/items/);
+	});
+
+	it("returns undefined when catalog-meta.json schema_version is wrong", () => {
+		const cacheDir = join(cwd, ".interlinked", "structure-cache");
+		mkdirSync(cacheDir, { recursive: true });
+		writeFileSync(
+			join(cacheDir, "catalog-meta.json"),
+			JSON.stringify({ schema_version: 2, last_scanned_commit: "abc" }),
+		);
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_graph_summary).toBeUndefined();
+	});
+
+	it("omits project graph summary when the cache is missing", () => {
+		const ctx = buildMetacoderContext({
+			prompt: "p",
+			client: "claude",
+			sessionId: "s",
+			cwd,
+			floorRuleIds: FLOOR_RULE_IDS,
+			config: DEFAULT_METACODER_CONFIG,
+		});
+		expect(ctx.project_graph_summary).toBeUndefined();
+	});
+});
diff --git a/src/harness/metacoder/prompt-builder.ts b/src/harness/metacoder/prompt-builder.ts
new file mode 100644
index 0000000..b05912c
--- /dev/null
+++ b/src/harness/metacoder/prompt-builder.ts
@@ -0,0 +1,202 @@
+// ===========================================
+// Metacoder — Prompt context builder
+// ===========================================
+// Assembles the JSON input the metacoder LLM receives. Inputs come from:
+//
+//   - The PII-scanner-redacted prompt (caller's job; see plan §6)
+//   - AGENTS.md / CLAUDE.md / .clinerules/*.md from the project root
+//   - Floor rule ids from the current GuardRulesConfig
+//   - Optional project graph summary from `.interlinked/structure-cache/`
+//
+// All disk reads are wrapped in best-effort try/catch — a malformed file
+// degrades to "no input from that source", never throws. Total
+// `project_instructions` length is capped so the metacoder doesn't see a
+// 200kB AGENTS.md.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AgentSource } from "../types.js";
+import { overlayIdPrefix } from "./overlay-loader.js";
+import type { MetacoderConfig, MetacoderInputContext } from "./types.js";
+
+const PROJECT_INSTRUCTIONS_BYTE_CAP = 20_000;
+const PROJECT_INSTRUCTIONS_HARD_CAP = 25_000; // safety margin for joined separators
+const PER_FILE_BYTE_CAP = 8_000;
+
+const TOP_LEVEL_GUIDANCE_FILES = [
+	"AGENTS.md",
+	"CLAUDE.md",
+	"GEMINI.md",
+	"INSTRUCTIONS.md",
+] as const;
+
+const CLINERULES_DIR = ".clinerules";
+
+export interface BuildContextInput {
+	prompt: string;
+	client: AgentSource;
+	sessionId: string;
+	cwd: string;
+	floorRuleIds: string[];
+	config: MetacoderConfig;
+}
+
+/** Public API — consumed by `src/harness/metacoder/index.ts::runMetacoderForPrompt`
+ *  to assemble the JSON envelope sent to the metacoder LLM. Pure-ish: reads
+ *  disk under `cwd`, never writes. Disk failures degrade silently. */
+export function buildMetacoderContext(input: BuildContextInput): MetacoderInputContext {
+	const projectInstructions = readProjectInstructions(input.cwd);
+	const projectGraphSummary = readProjectGraphSummary(input.cwd);
+	return {
+		prompt: input.prompt,
+		client: input.client,
+		session_id: input.sessionId,
+		cwd: input.cwd,
+		overlay_prefix: overlayIdPrefix(input.sessionId),
+		project_instructions: projectInstructions,
+		floor_rule_ids: input.floorRuleIds,
+		project_graph_summary: projectGraphSummary,
+	};
+}
+
+// ============================================================================
+// Project guidance reader
+// ============================================================================
+
+function readProjectInstructions(cwd: string): string {
+	const parts: string[] = [];
+	let remaining = PROJECT_INSTRUCTIONS_BYTE_CAP;
+
+	for (const filename of TOP_LEVEL_GUIDANCE_FILES) {
+		if (remaining <= 0) break;
+		const path = join(cwd, filename);
+		const text = readFileCapped(path, Math.min(PER_FILE_BYTE_CAP, remaining));
+		if (text === null) continue;
+		parts.push(`# ${filename}\n${text}`);
+		remaining -= text.length;
+	}
+
+	const clinerules = readClinerules(cwd, remaining);
+	if (clinerules.length > 0) {
+		parts.push(clinerules);
+	}
+
+	const joined = parts.join("\n\n");
+	if (joined.length > PROJECT_INSTRUCTIONS_HARD_CAP) {
+		return joined.slice(0, PROJECT_INSTRUCTIONS_HARD_CAP);
+	}
+	return joined;
+}
+
+function readClinerules(cwd: string, budget: number): string {
+	if (budget <= 0) return "";
+	const dir = join(cwd, CLINERULES_DIR);
+	if (!existsSync(dir)) return "";
+	let entries: string[];
+	try {
+		entries = readdirSync(dir).filter((name) => name.endsWith(".md")).sort();
+	} catch (_err) {
+		return "";
+	}
+	const parts: string[] = [];
+	let remaining = budget;
+	for (const name of entries) {
+		if (remaining <= 0) break;
+		const path = join(dir, name);
+		const text = readFileCapped(path, Math.min(PER_FILE_BYTE_CAP, remaining));
+		if (text === null) continue;
+		parts.push(`# ${CLINERULES_DIR}/${name}\n${text}`);
+		remaining -= text.length;
+	}
+	return parts.join("\n\n");
+}
+
+function readFileCapped(path: string, byteCap: number): string | null {
+	if (!existsSync(path)) return null;
+	try {
+		const stats = statSync(path);
+		if (!stats.isFile()) return null;
+		const raw = readFileSync(path, "utf-8");
+		return raw.length > byteCap ? raw.slice(0, byteCap) : raw;
+	} catch (_err) {
+		return null;
+	}
+}
+
+// ============================================================================
+// Project graph summary
+// ============================================================================
+
+function readProjectGraphSummary(cwd: string): string | undefined {
+	const cacheDir = join(cwd, ".interlinked", "structure-cache");
+	const metaPath = join(cacheDir, "catalog-meta.json");
+	if (!existsSync(metaPath)) return undefined;
+	try {
+		const raw = readFileSync(metaPath, "utf-8");
+		const parsed: unknown = JSON.parse(raw);
+		return formatGraphSummary(parsed, cacheDir);
+	} catch (_err) {
+		return undefined;
+	}
+}
+
+/** Format the actual `CatalogMeta` schema written by
+ *  `src/harness/structure/cache-manager.ts::writeCatalogMeta`. The real
+ *  shape is `{ schema_version, cli_version, built_at, repo_root,
+ *  last_scanned_commit, manifest_hash, extractor_versions }` — NOT
+ *  `file_count` / `by_extension`, which a previous version of this code
+ *  invented. The per-category item counts live in sibling
+ *  `<category>.json` files (e.g. `module.json`, `package.json`); we sum
+ *  those for a useful "N catalog items" signal. Plan §reviewer-P3
+ *  (round 6). */
+function formatGraphSummary(meta: unknown, cacheDir: string): string | undefined {
+	if (!isPlainRecord(meta)) return undefined;
+	if (meta.schema_version !== 1) return undefined;
+	const parts: string[] = [];
+	if (typeof meta.last_scanned_commit === "string" && meta.last_scanned_commit.length > 0) {
+		parts.push(`commit ${meta.last_scanned_commit.slice(0, 8)}`);
+	}
+	if (typeof meta.built_at === "string" && meta.built_at.length > 0) {
+		parts.push(`indexed ${meta.built_at}`);
+	}
+	const itemCount = countCatalogedItems(cacheDir);
+	if (itemCount !== null) parts.push(`${itemCount} catalog items`);
+	return parts.length > 0 ? parts.join("; ") : undefined;
+}
+
+/** Sum `items.length` across every sibling `<category>.json` in the
+ *  structure-cache directory. Each cache file matches `CategoryCatalog`
+ *  shape `{ schema_version, items: [...] }`. Returns null on any failure
+ *  (cache empty, files missing, parse errors) so the caller drops the
+ *  summary field entirely rather than emitting a misleading zero. */
+function countCatalogedItems(cacheDir: string): number | null {
+	if (!existsSync(cacheDir)) return null;
+	let entries: string[];
+	try {
+		entries = readdirSync(cacheDir);
+	} catch {
+		return null;
+	}
+	let total = 0;
+	let counted = 0;
+	for (const name of entries) {
+		if (!name.endsWith(".json")) continue;
+		if (name === "catalog-meta.json" || name === "baseline.json") continue;
+		try {
+			const raw = readFileSync(join(cacheDir, name), "utf-8");
+			const parsed = JSON.parse(raw) as { items?: unknown };
+			if (Array.isArray(parsed.items)) {
+				total += parsed.items.length;
+				counted++;
+			}
+		} catch {
+			// best-effort; skip unreadable files
+		}
+	}
+	return counted > 0 ? total : null;
+}
+
+function isPlainRecord(v: unknown): v is Record<string, unknown> {
+	return v !== null && typeof v === "object" && !Array.isArray(v);
+}
diff --git a/src/harness/metacoder/regex-validator.test.ts b/src/harness/metacoder/regex-validator.test.ts
new file mode 100644
index 0000000..7c2a811
--- /dev/null
+++ b/src/harness/metacoder/regex-validator.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+
+import { DEFAULT_METACODER_CONFIG } from "./types.js";
+import { validateOverlayPatternCount, validateOverlayRegex } from "./regex-validator.js";
+
+describe("validateOverlayRegex", () => {
+	it("accepts a normal anchored pattern with default flags", () => {
+		expect(validateOverlayRegex("^src/legacy/payments/", "i", DEFAULT_METACODER_CONFIG)).toBeNull();
+	});
+
+	it("accepts empty flags", () => {
+		expect(validateOverlayRegex("foo.bar", "", DEFAULT_METACODER_CONFIG)).toBeNull();
+	});
+
+	it("rejects empty patterns", () => {
+		expect(validateOverlayRegex("", "i", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/empty/);
+	});
+
+	it("rejects patterns longer than the configured cap", () => {
+		const oversize = "a".repeat(DEFAULT_METACODER_CONFIG.max_pattern_length + 1);
+		const failure = validateOverlayRegex(oversize, "i", DEFAULT_METACODER_CONFIG);
+		expect(failure?.reason).toMatch(/length/);
+	});
+
+	it("rejects the global flag (not in the i/m/s allowlist)", () => {
+		expect(validateOverlayRegex("foo", "g", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/flag/);
+	});
+
+	it("rejects the sticky flag", () => {
+		expect(validateOverlayRegex("foo", "y", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/flag/);
+	});
+
+	it("rejects the unicode flag", () => {
+		expect(validateOverlayRegex("foo", "u", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/flag/);
+	});
+
+	it("rejects nested unbounded quantifiers (ReDoS shape)", () => {
+		expect(validateOverlayRegex("^(a+)+$", "i", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/ReDoS|nested/);
+		expect(validateOverlayRegex("(a*)*", "i", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/ReDoS|nested/);
+		expect(validateOverlayRegex("(ab|c)*", "i", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/ReDoS|nested/);
+	});
+
+	it("rejects syntactically invalid regex", () => {
+		expect(validateOverlayRegex("[unclosed", "i", DEFAULT_METACODER_CONFIG)?.reason).toMatch(/invalid/i);
+	});
+
+	it("treats undefined flags as empty", () => {
+		expect(validateOverlayRegex("foo", undefined, DEFAULT_METACODER_CONFIG)).toBeNull();
+	});
+});
+
+describe("validateOverlayPatternCount", () => {
+	it("accepts counts at or below the cap", () => {
+		expect(validateOverlayPatternCount(DEFAULT_METACODER_CONFIG.max_patterns_per_rule, DEFAULT_METACODER_CONFIG)).toBeNull();
+	});
+
+	it("rejects counts above the cap", () => {
+		const failure = validateOverlayPatternCount(
+			DEFAULT_METACODER_CONFIG.max_patterns_per_rule + 1,
+			DEFAULT_METACODER_CONFIG,
+		);
+		expect(failure?.reason).toMatch(/patterns/);
+	});
+
+	it("accepts zero patterns", () => {
+		expect(validateOverlayPatternCount(0, DEFAULT_METACODER_CONFIG)).toBeNull();
+	});
+});
diff --git a/src/harness/metacoder/regex-validator.ts b/src/harness/metacoder/regex-validator.ts
new file mode 100644
index 0000000..9b0b3e8
--- /dev/null
+++ b/src/harness/metacoder/regex-validator.ts
@@ -0,0 +1,67 @@
+// ===========================================
+// Metacoder — Regex validator
+// ===========================================
+// Floor guard rules are admin-authored and trusted; the matcher does not
+// validate input regexes (see rule-matching.ts::getCachedRegex comment).
+// Overlay regexes come from an LLM and need bounds. Each check returns a
+// short reason string when the regex is rejected. Pure functions; no I/O.
+
+import type { MetacoderConfig } from "./types.js";
+
+const ALLOWED_FLAGS = new Set(["i", "m", "s"]);
+
+/** Catches the common ReDoS shapes a hallucinating LLM is most likely to
+ *  emit: `(a+)+`, `(a*)*` (nested unbounded quantifiers) and `(a|b)*` /
+ *  `(a|a)*` (quantified alternation). Allows `(abc)*` because the inner has
+ *  no quantifier or alternation. Not exhaustive — `((a)+)*` slips past
+ *  because `[^)]` won't cross the inner `)`. Plan §10 risk #9. */
+const REDOS_SHAPE = /\([^)]*[|+*][^)]*\)[+*]/;
+
+export interface RegexValidationFailure {
+	reason: string;
+}
+
+/** Returns `null` when the regex is acceptable; otherwise the rejection
+ *  reason as a short human-readable string. */
+export function validateOverlayRegex(
+	pattern: string,
+	flags: string | undefined,
+	config: MetacoderConfig,
+): RegexValidationFailure | null {
+	if (typeof pattern !== "string" || pattern.length === 0) {
+		return { reason: "empty pattern" };
+	}
+	if (pattern.length > config.max_pattern_length) {
+		return { reason: `pattern length ${pattern.length} > ${config.max_pattern_length}` };
+	}
+	const resolvedFlags = flags ?? "";
+	for (const ch of resolvedFlags) {
+		if (!ALLOWED_FLAGS.has(ch)) {
+			return { reason: `flag '${ch}' not in {i,m,s}` };
+		}
+	}
+	if (REDOS_SHAPE.test(pattern)) {
+		return { reason: "nested unbounded quantifier (ReDoS shape)" };
+	}
+	try {
+		// Compiling once at load time surfaces invalid regexes before they
+		// reach the PreToolUse hot path. The compiled object is discarded —
+		// the matcher's own cache compiles again at use time.
+		new RegExp(pattern, resolvedFlags);
+	} catch (err) {
+		return { reason: `invalid: ${err instanceof Error ? err.message : String(err)}` };
+	}
+	return null;
+}
+
+/** Bound on patterns-per-rule for overlays. Returns the rejection reason or
+ *  `null` if the count is acceptable. */
+export function validateOverlayPatternCount(
+	count: number,
+	config: MetacoderConfig,
+): RegexValidationFailure | null {
+	if (count > config.max_patterns_per_rule) {
+		return { reason: `${count} patterns > ${config.max_patterns_per_rule}` };
+	}
+	return null;
+}
diff --git a/src/harness/metacoder/types.test.ts b/src/harness/metacoder/types.test.ts
new file mode 100644
index 0000000..4c5dab4
--- /dev/null
+++ b/src/harness/metacoder/types.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	DEFAULT_METACODER_CONFIG,
+	METACODER_TIMEOUT_DEFAULT_MS,
+	USER_PROMPT_HOOK_TIMEOUT_MS,
+} from "./types.js";
+
+describe("DEFAULT_METACODER_CONFIG", () => {
+	it("has the metacoder enabled by default", () => {
+		expect(DEFAULT_METACODER_CONFIG.enabled).toBe(true);
+	});
+
+	it("uses the named timeout default", () => {
+		expect(DEFAULT_METACODER_CONFIG.timeout_ms).toBe(METACODER_TIMEOUT_DEFAULT_MS);
+	});
+});
+
+describe("hook / metacoder timeout pairing", () => {
+	// Plan §2.4 contract: the hook waits strictly longer than the metacoder so
+	// the harness can convert a clean timeout into an allow decision before
+	// the socket gives up. Drift means 100% cold-fallback.
+	it("USER_PROMPT_HOOK_TIMEOUT_MS exceeds METACODER_TIMEOUT_DEFAULT_MS with a buffer", () => {
+		const buffer = USER_PROMPT_HOOK_TIMEOUT_MS - METACODER_TIMEOUT_DEFAULT_MS;
+		expect(buffer).toBeGreaterThanOrEqual(2_000);
+	});
+});
diff --git a/src/harness/metacoder/types.ts b/src/harness/metacoder/types.ts
new file mode 100644
index 0000000..4dc6bd0
--- /dev/null
+++ b/src/harness/metacoder/types.ts
@@ -0,0 +1,114 @@
+// interlinked-tdd: exempt
+// ===========================================
+// Metacoder — Types
+// ===========================================
+// Per-prompt, session-scoped overlay rules emitted by an LLM. See
+// docs/design/metacoding-agent-plan.md for the full architecture.
+// Declarative — types, type aliases, one default-config literal, one constant.
+// Behavior is tested through the consumers (overlay-loader, metacoder-client).
+
+import type { AgentSource, GuardRule } from "../types.js";
+
+/** Wire shape of `.interlinked/sessions/<sid>/overlay-rules.json`. The model
+ *  emits `version`, `rules`, and `system_prompt_addendum`; the harness fills
+ *  in the rest. */
+export interface OverlayRulesFile {
+	version: 1;
+	session_id: string;
+	generated_at: string;
+	generated_by: "metacoder";
+	source_prompt_sha256: string;
+	system_prompt_addendum?: string;
+	rules: GuardRule[];
+}
+
+/** What the metacoder LLM is asked to author. Matches `OverlayRulesFile`
+ *  minus the server-filled fields. */
+export interface OverlayRulesEmission {
+	version: 1;
+	rules: GuardRule[];
+	system_prompt_addendum?: string;
+}
+
+/** Input passed to the metacoder LLM as JSON. */
+export interface MetacoderInputContext {
+	prompt: string;
+	client: AgentSource;
+	session_id: string;
+	cwd: string;
+	/** Exact prefix every overlay rule id MUST start with. Computed by the
+	 *  server as `overlayIdPrefix(session_id)`, then truncated/sanitized.
+	 *  Passed in literal form so the LLM can copy it byte-for-byte —
+	 *  guessing from `session_id` and a description in the system prompt
+	 *  produces collisions with the loader's expected prefix. */
+	overlay_prefix: string;
+	/** AGENTS.md + CLAUDE.md (+ peers) concatenated, capped at ~20kB. */
+	project_instructions: string;
+	/** Floor rule ids so the LLM knows what NOT to duplicate or disable. */
+	floor_rule_ids: string[];
+	/** Optional structural-cache summary. Stub when cache is empty. */
+	project_graph_summary?: string;
+}
+
+/** Outcome of a single metacoder run. `ok` returns the overlay the harness
+ *  should persist; the other variants are fail-open paths. */
+export type MetacoderOutcome =
+	| { kind: "ok"; overlay: OverlayRulesFile; warnings: string[] }
+	| { kind: "skipped"; reason: SkippedReason; warnings: string[] }
+	| { kind: "failed"; reason: string; warnings: string[] };
+
+export type SkippedReason =
+	| "disabled"
+	| "no_prompt"
+	| "no_api_key"
+	| "subprocess_not_found"
+	| "recursion_guard"
+	| "empty_overlay";
+
+/** Resolved metacoder config. */
+export interface MetacoderConfig {
+	enabled: boolean;
+	/** Internal LLM call timeout. Must be < hook user-prompt timeout (35s). */
+	timeout_ms: number;
+	/** Hard cap on rules per overlay. Defensive against runaway emissions. */
+	max_rules: number;
+	/** Hard cap on regex length per pattern. */
+	max_pattern_length: number;
+	/** Hard cap on patterns per rule. */
+	max_patterns_per_rule: number;
+	/** Hard cap on system_prompt_addendum length. */
+	max_addendum_chars: number;
+}
+
+/** Default metacoder timeout. Strictly less than `USER_PROMPT_HOOK_TIMEOUT_MS`
+ *  so the harness has a buffer to return its own timeout decision before the
+ *  hook gives up. */
+export const METACODER_TIMEOUT_DEFAULT_MS = 30_000;
+
+/** Hard cap on overlay rule count per emission. */
+export const METACODER_MAX_RULES_DEFAULT = 20;
+
+/** Hard cap on regex pattern length (chars). Bounds compilation cost. */
+export const METACODER_MAX_PATTERN_LENGTH_DEFAULT = 200;
+
+/** Hard cap on patterns per rule. */
+export const METACODER_MAX_PATTERNS_PER_RULE_DEFAULT = 10;
+
+/** Hard cap on `system_prompt_addendum` length (chars). 2 KB × N turns
+ *  accumulates in the agent's context window — see plan §10 risk #5. */
+export const METACODER_MAX_ADDENDUM_CHARS_DEFAULT = 2000;
+
+export const DEFAULT_METACODER_CONFIG: MetacoderConfig = {
+	enabled: true,
+	timeout_ms: METACODER_TIMEOUT_DEFAULT_MS,
+	max_rules: METACODER_MAX_RULES_DEFAULT,
+	max_pattern_length: METACODER_MAX_PATTERN_LENGTH_DEFAULT,
+	max_patterns_per_rule: METACODER_MAX_PATTERNS_PER_RULE_DEFAULT,
+	max_addendum_chars: METACODER_MAX_ADDENDUM_CHARS_DEFAULT,
+};
+
+/** Hook adapter timeout for the user-prompt phase. Strictly greater than
+ *  `MetacoderConfig.timeout_ms` so the harness has a buffer to convert a
+ *  clean metacoder timeout into an allow decision before the hook gives up
+ *  on the socket and falls back. Drift here means 100% cold-fallback. */
+export const USER_PROMPT_HOOK_TIMEOUT_MS = 35_000;
diff --git a/src/harness/rules-loader.test.ts b/src/harness/rules-loader.test.ts
new file mode 100644
index 0000000..e19369a
--- /dev/null
+++ b/src/harness/rules-loader.test.ts
@@ -0,0 +1,269 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { mkdirSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { loadRules } from "./rules-loader.js";
+import { overlayIdPrefix } from "./metacoder/overlay-loader.js";
+import {
+	DEFAULT_METACODER_CONFIG,
+	METACODER_MAX_RULES_DEFAULT,
+	METACODER_MAX_PATTERN_LENGTH_DEFAULT,
+} from "./metacoder/types.js";
+
+const SESSION = "rules-loader-session-abc12345";
+
+function writeOverlayFile(cwd: string, sessionId: string, overlay: unknown): void {
+	const dir = join(cwd, ".interlinked", "sessions", sessionId);
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "overlay-rules.json"), JSON.stringify(overlay));
+}
+
+// All tests skip the distilled-rules layer so per-developer /enforce output
+// doesn't leak in. (Matches the vitest project default per CLAUDE.md.)
+const ORIGINAL_SKIP_FLAG = process.env.INTERLINKED_SKIP_DISTILLED_RULES;
+beforeEach(() => {
+	process.env.INTERLINKED_SKIP_DISTILLED_RULES = "1";
+});
+afterEach(() => {
+	if (ORIGINAL_SKIP_FLAG === undefined) {
+		delete process.env.INTERLINKED_SKIP_DISTILLED_RULES;
+	} else {
+		process.env.INTERLINKED_SKIP_DISTILLED_RULES = ORIGINAL_SKIP_FLAG;
+	}
+});
+
+describe("loadRules — no sessionId (legacy callers)", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "rules-loader-legacy-"));
+	});
+	afterEach(() => {
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	it("returns built-in floor rules", () => {
+		const config = loadRules(cwd);
+		expect(config.rules.length).toBeGreaterThan(0);
+	});
+
+	it("does not pick up overlay files when sessionId is omitted", () => {
+		writeOverlayFile(cwd, SESSION, {
+			version: 1,
+			rules: [
+				{
+					id: `${overlayIdPrefix(SESSION)}0`,
+					enabled: true,
+					trigger: "PreToolUse",
+					tool_match: ["Edit"],
+					action: "block",
+					patterns: [{ field: "file_path", regex: "src/legacy/" }],
+					reason: "Out of scope.",
+					severity: "high",
+				},
+			],
+		});
+		const config = loadRules(cwd);
+		const overlayIds = config.rules.filter((r) => r.id.startsWith("overlay:"));
+		expect(overlayIds).toHaveLength(0);
+	});
+});
+
+describe("loadRules — metacoder config merge (P4 round 4)", () => {
+	// A partial local.metacoder override must layer onto
+	// DEFAULT_METACODER_CONFIG, not replace it. Otherwise tuning
+	// `timeout_ms` silently disables the metacoder (`enabled: undefined` is
+	// falsy) and drops the overlay validator's caps.
+
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "rules-loader-metacoder-"));
+	});
+	afterEach(() => {
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	function writeLocalConfig(metacoderOverride: unknown): void {
+		const dir = join(cwd, ".interlinked");
+		mkdirSync(dir, { recursive: true });
+		writeFileSync(
+			join(dir, "guard-rules.local.json"),
+			JSON.stringify({ metacoder: metacoderOverride }),
+		);
+	}
+
+	it("preserves enabled:true from defaults when local overrides only timeout_ms", () => {
+		writeLocalConfig({ timeout_ms: 5000 });
+		const config = loadRules(cwd);
+		expect(config.metacoder?.enabled).toBe(true);
+		expect(config.metacoder?.timeout_ms).toBe(5000);
+	});
+
+	it("preserves default caps when local overrides only timeout_ms", () => {
+		writeLocalConfig({ timeout_ms: 5000 });
+		const config = loadRules(cwd);
+		expect(config.metacoder?.max_rules).toBe(METACODER_MAX_RULES_DEFAULT);
+		expect(config.metacoder?.max_pattern_length).toBe(METACODER_MAX_PATTERN_LENGTH_DEFAULT);
+	});
+
+	it("honors explicit local enabled:false", () => {
+		writeLocalConfig({ enabled: false });
+		const config = loadRules(cwd);
+		expect(config.metacoder?.enabled).toBe(false);
+		// Caps still seeded from defaults so the validator stays bounded
+		// even when the metacoder is off — guards future code paths that
+		// may reuse the caps without checking `enabled` first.
+		expect(config.metacoder?.max_rules).toBe(METACODER_MAX_RULES_DEFAULT);
+	});
+
+	it("uses every default field when no local metacoder config exists", () => {
+		// No local config file written — rules.metacoder may stay undefined,
+		// but the server falls back to DEFAULT_METACODER_CONFIG. Verify the
+		// default constants themselves match the expected shape so the
+		// fallback is meaningful.
+		expect(DEFAULT_METACODER_CONFIG.enabled).toBe(true);
+		expect(DEFAULT_METACODER_CONFIG.max_rules).toBe(METACODER_MAX_RULES_DEFAULT);
+		expect(DEFAULT_METACODER_CONFIG.max_pattern_length).toBe(METACODER_MAX_PATTERN_LENGTH_DEFAULT);
+	});
+
+	it("clamps local timeout_ms to stay below the hook timeout (P2 round 5)", () => {
+		// Plan §reviewer-P2 (round 5): a user override of 60000ms must NOT
+		// match or exceed the user-prompt hook budget (35000ms). The merge
+		// step clamps to USER_PROMPT_HOOK_TIMEOUT_MS - 2000 = 33000ms so
+		// the harness always has a buffer to send its clean timeout reply
+		// before the hook destroys the socket.
+		writeLocalConfig({ timeout_ms: 60_000 });
+		const config = loadRules(cwd);
+		const HOOK_TIMEOUT = 35_000;
+		const MIN_BUFFER = 2_000;
+		expect(config.metacoder?.timeout_ms).toBeLessThanOrEqual(HOOK_TIMEOUT - MIN_BUFFER);
+	});
+
+	it("preserves a safely-low timeout_ms verbatim", () => {
+		writeLocalConfig({ timeout_ms: 8000 });
+		const config = loadRules(cwd);
+		expect(config.metacoder?.timeout_ms).toBe(8000);
+	});
+
+	it("clamps timeout_ms exactly equal to the hook budget", () => {
+		writeLocalConfig({ timeout_ms: 35_000 });
+		const config = loadRules(cwd);
+		expect(config.metacoder?.timeout_ms).toBeLessThan(35_000);
+	});
+});
+
+describe("loadRules — with sessionId (overlay merge)", () => {
+	let cwd: string;
+	beforeEach(() => {
+		cwd = mkdtempSync(join(tmpdir(), "rules-loader-overlay-"));
+	});
+	afterEach(() => {
+		rmSync(cwd, { recursive: true, force: true });
+	});
+
+	it("returns floor rules unchanged when no overlay file exists for the session", () => {
+		const legacy = loadRules(cwd);
+		const merged = loadRules(cwd, SESSION);
+		expect(merged.rules).toHaveLength(legacy.rules.length);
+	});
+
+	it("appends valid overlay rules after the floor", () => {
+		writeOverlayFile(cwd, SESSION, {
+			version: 1,
+			rules: [
+				{
+					id: `${overlayIdPrefix(SESSION)}0`,
+					enabled: true,
+					trigger: "PreToolUse",
+					tool_match: ["Edit"],
+					action: "block",
+					patterns: [{ field: "file_path", regex: "src/legacy/" }],
+					reason: "Out of scope.",
+					severity: "high",
+				},
+			],
+		});
+		const config = loadRules(cwd, SESSION);
+		const overlayRules = config.rules.filter((r) => r.id.startsWith("overlay:"));
+		expect(overlayRules).toHaveLength(1);
+	});
+
+	it("places overlay rules at the end of the merged list (after every floor rule)", () => {
+		writeOverlayFile(cwd, SESSION, {
+			version: 1,
+			rules: [
+				{
+					id: `${overlayIdPrefix(SESSION)}0`,
+					enabled: true,
+					trigger: "PreToolUse",
+					tool_match: ["Edit"],
+					action: "block",
+					patterns: [{ field: "file_path", regex: "src/legacy/" }],
+					reason: "Out of scope.",
+					severity: "high",
+				},
+			],
+		});
+		const config = loadRules(cwd, SESSION);
+		const lastFloorIndex = config.rules.findIndex((r) => r.id.startsWith("overlay:")) - 1;
+		const firstOverlayIndex = config.rules.findIndex((r) => r.id.startsWith("overlay:"));
+		expect(firstOverlayIndex).toBeGreaterThan(0);
+		expect(config.rules[lastFloorIndex].id.startsWith("overlay:")).toBe(false);
+	});
+
+	it("skips the overlay merge when metacoder is disabled, even if overlay-rules.json exists (P1 round 6)", () => {
+		// Plan §reviewer-P1 (round 6): toggling metacoder off must
+		// immediately stop applying any persisted overlay. Without this
+		// gate, a user who flips `enabled: false` keeps being blocked by
+		// the last LLM-generated rules until SessionEnd.
+		writeOverlayFile(cwd, SESSION, {
+			version: 1,
+			rules: [
+				{
+					id: `${overlayIdPrefix(SESSION)}0`,
+					enabled: true,
+					trigger: "PreToolUse",
+					tool_match: ["Edit"],
+					action: "block",
+					patterns: [{ field: "file_path", regex: "src/legacy/" }],
+					reason: "stale overlay rule",
+					severity: "high",
+				},
+			],
+		});
+		// Write local config disabling the metacoder.
+		const dir = join(cwd, ".interlinked");
+		writeFileSync(
+			join(dir, "guard-rules.local.json"),
+			JSON.stringify({ metacoder: { enabled: false } }),
+		);
+		const config = loadRules(cwd, SESSION);
+		const overlayRules = config.rules.filter((r) => r.id.startsWith("overlay:"));
+		expect(overlayRules).toHaveLength(0);
+	});
+
+	it("drops overlay rules whose ids collide with floor ids (tighten-only invariant)", () => {
+		// Pick an actual built-in id so the collision check fires.
+		const FLOOR_ID = "builtin-rm-rf-root";
+		writeOverlayFile(cwd, SESSION, {
+			version: 1,
+			rules: [
+				{
+					id: FLOOR_ID,
+					enabled: true,
+					trigger: "PreToolUse",
+					tool_match: ["*"],
+					action: "block",
+					patterns: [{ field: "command", regex: "anything" }],
+					reason: "should be dropped.",
+					severity: "low",
+				},
+			],
+		});
+		const config = loadRules(cwd, SESSION);
+		// The floor `block_rm_rf` still survives; no overlay version replaces it.
+		const matches = config.rules.filter((r) => r.id === FLOOR_ID);
+		expect(matches).toHaveLength(1);
+		expect(matches[0].reason).not.toContain("should be dropped");
+	});
+});
diff --git a/src/harness/rules-loader.ts b/src/harness/rules-loader.ts
index c231d30..9dd3b4c 100644
--- a/src/harness/rules-loader.ts
+++ b/src/harness/rules-loader.ts
@@ -20,6 +20,8 @@
 
 import { existsSync, readFileSync, unwatchFile, watchFile } from "node:fs";
 import { join } from "node:path";
+import { loadOverlayForSession } from "./metacoder/overlay-loader.js";
+import { DEFAULT_METACODER_CONFIG } from "./metacoder/types.js";
 import { BUILTIN_RULES } from "./rules/builtin-rules.js";
 import { DEFAULT_CONFIG } from "./rules/default-config.js";
 import {
@@ -123,9 +125,18 @@ function applyModePresetEnablement(
  * and on SIGHUP. Loads the default config, auto-tunes by detected
  * project language, and merges team + local overrides.
  *
- * Priority: local overrides > team rules > built-in defaults.
+ * When `sessionId` is provided, also merges the metacoder overlay for that
+ * session (if one exists on disk at
+ * `.interlinked/sessions/<sid>/overlay-rules.json`). Overlay rules are
+ * appended AFTER all floor rules so floor blocks always iterate before
+ * overlay rules for the same input — plan §2.3, §5.
+ *
+ * Priority: local overrides > team rules > built-in defaults > overlay.
  */
-export function loadRules(cwd: string = process.cwd()): GuardRulesConfig {
+export function loadRules(
+	cwd: string = process.cwd(),
+	sessionId?: string,
+): GuardRulesConfig {
 	const teamPath = join(cwd, ".interlinked", "guard-rules.json");
 	const localPath = join(cwd, ".interlinked", "guard-rules.local.json");
 
@@ -187,12 +198,35 @@ export function loadRules(cwd: string = process.cwd()): GuardRulesConfig {
 		process.env.INTERLINKED_SKIP_DISTILLED_RULES === "1" ||
 		process.env.INTERLINKED_SKIP_COMPILED_RULES === "1";
 	const distilledRules = skipDistilled ? [] : loadDistilledRules(cwd);
-	const allRules = [
+	const floorRules: GuardRule[] = [
 		...BUILTIN_RULES.filter((r) => !disabledSet.has(r.id)),
 		...config.rules.filter((r) => r.enabled !== false),
 		...distilledRules.filter((r) => r.enabled !== false && !disabledSet.has(r.id)),
 	];
-	config.rules = allRules;
+
+	// Per-session metacoder overlay — appended AFTER floor rules so floor
+	// blocks always iterate first. Plan §2.3, §5. The overlay loader
+	// enforces tighten-only: action-block-only, overlay-prefix ids, regex
+	// validation. No-op when sessionId is omitted (every legacy call site).
+	//
+	// Plan §reviewer-P1 (round 6): also no-op when the resolved metacoder
+	// config is disabled, regardless of whether `overlay-rules.json`
+	// still sits on disk. A user toggling `metacoder.enabled: false`
+	// must NOT keep getting blocked by a stale overlay written by an
+	// earlier prompt — the server's UserPromptSubmit handler evicts the
+	// file on the next prompt, but until then we ignore it here.
+	const resolvedMetacoder = config.metacoder ?? DEFAULT_METACODER_CONFIG;
+	const overlayRules =
+		sessionId && resolvedMetacoder.enabled !== false
+			? loadOverlayForSession({
+					cwd,
+					sessionId,
+					floorRuleIds: new Set(floorRules.map((r) => r.id)),
+					config: resolvedMetacoder,
+				})?.rules ?? []
+			: [];
+
+	config.rules = [...floorRules, ...overlayRules];
 
 	return config;
 }
diff --git a/src/harness/rules/merge.ts b/src/harness/rules/merge.ts
index edf3ed5..4027c35 100644
--- a/src/harness/rules/merge.ts
+++ b/src/harness/rules/merge.ts
@@ -9,8 +9,34 @@
 // field could silently execute on every developer's machine. We allow
 // team config to toggle safe fields only — see QUALITY_CHECK_SAFE_FIELDS.
 
+import {
+	DEFAULT_METACODER_CONFIG,
+	USER_PROMPT_HOOK_TIMEOUT_MS,
+	type MetacoderConfig,
+} from "../metacoder/types.js";
 import type { GuardRulesConfig, QualityCheckConfig } from "../types.js";
 
+/** Minimum buffer between the metacoder's internal timeout and the
+ *  user-prompt hook timeout. With less than this, the hook can destroy
+ *  the socket while the harness is still finalizing its "metacoder timed
+ *  out, allow" reply, producing a spurious cold-fallback. Plan §6 + plan
+ *  §reviewer-P2 (round 5). */
+const METACODER_HOOK_BUFFER_MS = 2_000;
+
+/** Hard upper bound for `metacoder.timeout_ms`. Derived from the hook
+ *  timeout so changing one constant automatically tightens the other —
+ *  no drift between merge-time clamp and hook-script generation. */
+const METACODER_TIMEOUT_HARD_CAP_MS = USER_PROMPT_HOOK_TIMEOUT_MS - METACODER_HOOK_BUFFER_MS;
+
+/** Clamp `metacoder.timeout_ms` so user config can never set a value that
+ *  races the hook's own timeout. Pure function — does not mutate input. */
+function clampMetacoderConfig(cfg: MetacoderConfig): MetacoderConfig {
+	if (cfg.timeout_ms > METACODER_TIMEOUT_HARD_CAP_MS) {
+		return { ...cfg, timeout_ms: METACODER_TIMEOUT_HARD_CAP_MS };
+	}
+	return cfg;
+}
+
 /**
  * Team config (git-committed) can toggle settings but CANNOT define
  * arbitrary commands. This prevents a malicious PR from adding a quality
@@ -82,6 +108,21 @@ export function mergeTeamRules(config: GuardRulesConfig, team: Partial<GuardRule
 	if (team.auto_coordination) {
 		config.auto_coordination = team.auto_coordination;
 	}
+	if (team.metacoder) {
+		// Plan §reviewer-P4 (round 4): seed against DEFAULT_METACODER_CONFIG
+		// so a partial team override like `{timeout_ms: 5000}` doesn't drop
+		// `enabled`, `max_rules`, `max_pattern_length`, etc. Without this,
+		// the overlay validator's caps disappear (max_rules undefined →
+		// the cap check NaN-compares → no cap) and `enabled: undefined`
+		// silently disables the metacoder.
+		// Plan §reviewer-P2 (round 5): clamp `timeout_ms` to keep the
+		// metacoder's internal deadline strictly below the hook timeout.
+		config.metacoder = clampMetacoderConfig({
+			...DEFAULT_METACODER_CONFIG,
+			...config.metacoder,
+			...team.metacoder,
+		});
+	}
 	if (team.project_wide_checks && config.project_wide_checks) {
 		Object.assign(config.project_wide_checks, team.project_wide_checks);
 	}
@@ -145,6 +186,24 @@ export function mergeLocalOverrides(
 	if (local.structural_checks) {
 		Object.assign(config.structural_checks, local.structural_checks);
 	}
+	// Local can disable / tune the per-prompt metacoder. Without this branch
+	// `{metacoder: {enabled: false}}` in guard-rules.local.json was silently
+	// dropped, leaving every UserPromptSubmit doing a 30s LLM call. Plan §2.1.
+	// Shallow Object.assign — MetacoderConfig is flat scalars, no nested
+	// objects to deep-merge.
+	if (local.metacoder) {
+		// Plan §reviewer-P4 (round 4): seed against DEFAULT_METACODER_CONFIG
+		// so a partial override like `{timeout_ms: 5000}` doesn't leave
+		// `enabled` undefined (silently disabling the metacoder) or drop
+		// the overlay validator's caps. Spread order: defaults < team
+		// config < local override, so local wins on scalar conflicts.
+		// Plan §reviewer-P2 (round 5): clamp timeout_ms after merge.
+		config.metacoder = clampMetacoderConfig({
+			...DEFAULT_METACODER_CONFIG,
+			...config.metacoder,
+			...local.metacoder,
+		});
+	}
 }
 
 /** Deep-merge overrides for the content scanner config. Nested blocks
diff --git a/src/harness/server.ts b/src/harness/server.ts
index 2a1590f..73b8e5d 100644
--- a/src/harness/server.ts
+++ b/src/harness/server.ts
@@ -93,6 +93,9 @@ import {
 	hashEvidence,
 	resolveApiKey,
 } from "./policy-classifier.js";
+import { runMetacoderForPrompt } from "./metacoder/index.js";
+import { evictOverlayForSession } from "./metacoder/metacoder-writer.js";
+import { DEFAULT_METACODER_CONFIG } from "./metacoder/types.js";
 import { ProjectGraph } from "./project-graph.js";
 import {
 	countAsAnyCasts,
@@ -331,6 +334,38 @@ import { buildTurnEndSummary, formatTurnEndWarnings } from "./turn-end.js";
 // Per-session classifier state (call count, consecutive failures).
 const classifierSessions = new Map<string, ClassifierSessionState>();
 
+// --- Metacoder per-session rule cache ---
+// Populated on UserPromptSubmit after the metacoder writes the overlay;
+// consulted on PreToolUse via `rulesForSession()`. Cache entry replaces
+// on each new prompt for the same session_id (plan §1.1, replace
+// semantics). Cleared in the SessionEnd / Stop handler.
+const sessionRules = new Map<string, GuardRulesConfig>();
+
+/** PreToolUse evaluator entry point — returns the per-session merged
+ *  ruleset (floor + overlay) for the given session, or the global floor
+ *  when no overlay has been written yet. Mirrors the existing `rules`
+ *  fallback so legacy callers behave unchanged when no metacoder has fired.
+ *
+ *  Plan §reviewer-P3 (round 5): on cache miss, hydrate from the on-disk
+ *  overlay file. Without this, a daemon restart between UserPromptSubmit
+ *  and the first PreToolUse leaves the in-memory map empty, so the agent
+ *  silently runs against floor-only even though `overlay-rules.json`
+ *  exists on disk. The hydrated value is cached so subsequent calls in
+ *  the same process stay O(1). */
+function rulesForSession(sessionId: string | undefined): GuardRulesConfig {
+	if (!sessionId) return rules;
+	const cached = sessionRules.get(sessionId);
+	if (cached) return cached;
+	// Cache miss — try loading from disk. `loadRules(cwd, sessionId)`
+	// returns floor + overlay when an overlay file exists, or floor-only
+	// otherwise. Either way we cache the snapshot; a later
+	// UserPromptSubmit replaces it via `sessionRules.set(...)`, and a
+	// floor reload clears the map via `sessionRules.clear()`.
+	const hydrated = loadRules(CWD, sessionId);
+	sessionRules.set(sessionId, hydrated);
+	return hydrated;
+}
+
 // ML content scanner (OpenAI privacy-filter / gpt-oss-safeguard). Off by default;
 // opt in via `.interlinked/guard-rules.local.json` → `"content_scanner": {"enabled": true}`.
 // Undefined when disabled or misconfigured — both read paths below null-check.
@@ -894,6 +929,12 @@ async function processEvent(rawData: string): Promise<HarnessDecision> {
 			deleteLiveSnapshot(CWD, event.session_id);
 			classifierSessions.delete(event.session_id);
 			autoCoordStates.delete(event.session_id);
+			// Metacoder cleanup — evict the overlay artifacts on disk AND the
+			// per-session rule cache. Codex emits `Stop` only; Claude emits
+			// both `SessionEnd` and `Stop`. The joint switch case above
+			// catches all three. Plan §1, §2.5.
+			evictOverlayForSession({ cwd: CWD, sessionId: event.session_id });
+			sessionRules.delete(event.session_id);
 			log(`Agent left: ${event.agent_name || event.session_id}`);
 			return {
 				decision: "allow",
@@ -902,10 +943,20 @@ async function processEvent(rawData: string): Promise<HarnessDecision> {
 		}
 		case "UserPromptSubmit": {
 			cohort.recordActivity(event);
+
+			// Recursion guard — when the metacoder spawns `claude -p` to invoke
+			// Opus 4.7, the spawned subprocess inherits the user's hooks and
+			// fires its own UserPromptSubmit back here. Without this short-
+			// circuit we recurse and never return. Plan §2.5.
+			if (event.metacoder_subprocess === true) {
+				return { decision: "allow" };
+			}
+
 			// Scan the prompt for PII. On findings, return a redacted copy so the
 			// hook stores the masked version in activity.jsonl instead of the raw.
 			// Never blocks — users are always allowed to submit their own prompts;
 			// this is storage hygiene, not a policy gate.
+			let redactedPrompt: string | undefined;
 			if (rules.content_scanner?.enabled && contentScanner) {
 				const promptText = event.prompt ?? "";
 				const scanResult = await scanUserPrompt(promptText, rules, contentScanner);
@@ -913,10 +964,59 @@ async function processEvent(rawData: string): Promise<HarnessDecision> {
 					log(
 						`Content scanner: UserPromptSubmit — ${scanResult.findings.length} finding(s), redacted for local log`,
 					);
-					return { decision: "allow", redacted_prompt: scanResult.redacted };
+					redactedPrompt = scanResult.redacted;
 				}
 			}
-			return { decision: "allow" };
+
+			// Metacoder — synchronous per-prompt overlay generation. Plan §1, §6.
+			// Pass the redacted prompt when the scanner fired, the raw prompt
+			// otherwise. Fail-open on every error: the prompt always reaches the
+			// agent, just without overlay constraints.
+			const metacoderConfig = rules.metacoder ?? DEFAULT_METACODER_CONFIG;
+			let metacoderAdditionalContext: string | undefined;
+			if (!metacoderConfig.enabled) {
+				// Plan §reviewer-P1 (round 6): metacoder explicitly off. Evict
+				// any stale overlay-rules.json from a prior prompt before it
+				// can be merged on the next PreToolUse. Without this, a user
+				// who toggles enabled→false keeps being blocked by the last
+				// overlay until SessionEnd.
+				sessionRules.delete(event.session_id);
+				evictOverlayForSession({ cwd: CWD, sessionId: event.session_id });
+			} else if (event.prompt && event.prompt.length > 0) {
+				const promptForMeta = redactedPrompt ?? event.prompt;
+				const outcome = await runMetacoderForPrompt({
+					cwd: CWD,
+					sessionId: event.session_id,
+					client: event.agent_source,
+					prompt: promptForMeta,
+					floorRuleIds: rules.rules.map((r) => r.id),
+					config: metacoderConfig,
+				});
+				if (outcome.kind === "ok") {
+					sessionRules.set(event.session_id, loadRules(CWD, event.session_id));
+					metacoderAdditionalContext = outcome.overlay.system_prompt_addendum;
+					log(
+						`Metacoder: ${outcome.overlay.rules.length} overlay rule(s) for ${event.session_id}`,
+					);
+				} else {
+					// Replace semantics (plan §1.1): a non-ok outcome on prompt B
+					// must clear prompt A's overlay, otherwise prompt A's rules
+					// keep blocking prompt B's tool calls until SessionEnd.
+					// Covers skipped (empty_overlay / no_api_key / disabled) and
+					// failed (timeout / malformed JSON / etc.) uniformly.
+					sessionRules.delete(event.session_id);
+					evictOverlayForSession({ cwd: CWD, sessionId: event.session_id });
+					if (outcome.kind === "failed") {
+						log(`Metacoder failed (non-fatal): ${outcome.reason}`);
+					}
+				}
+			}
+
+			return {
+				decision: "allow",
+				redacted_prompt: redactedPrompt,
+				additional_context: metacoderAdditionalContext,
+			};
 		}
 		case "SubagentStart":
 			cohort.subagentJoined(event);
@@ -997,7 +1097,7 @@ async function processEvent(rawData: string): Promise<HarnessDecision> {
 		// script does for mode resolution.
 		const preDecision = evaluatePreToolUse(
 			event,
-			rules,
+			rulesForSession(event.session_id),
 			session,
 			reservations,
 			cohort,
@@ -3338,6 +3438,15 @@ writeProtocolStatus();
 // Watch rules files for hot-reload
 const unwatchRules = watchRulesFiles(CWD, (newRules) => {
 	rules = newRules;
+	// Plan §reviewer-P5 (round 4): clear cached per-session rules so
+	// active sessions pick up the new floor (and any new metacoder
+	// config) on the very next PreToolUse. Without this, sessions that
+	// already have a written overlay keep the snapshot of `rules` they
+	// were merged against until SessionEnd / Stop, so a user disabling a
+	// floor rule via `guard-rules.local.json` mid-session never takes
+	// effect for live sessions. Subsequent UserPromptSubmit calls will
+	// rebuild the cache with fresh floor + overlay.
+	sessionRules.clear();
 	// Update classifier status on config reload
 	if (rules.policy_classifier?.enabled) {
 		const p = rules.policy_classifier;
@@ -3442,8 +3551,15 @@ if (_shutdownPending) {
 	shutdown();
 }
 process.on("SIGHUP", () => {
-	// Reload rules on SIGHUP
+	// Reload rules on SIGHUP.
+	// Plan §reviewer-P2 (round 6): also invalidate the per-session rule
+	// cache so the new ruleset takes effect on active sessions' next
+	// PreToolUse. Without this clear, sessions that have a hydrated
+	// snapshot keep using stale rules until SessionEnd / Stop and
+	// operator SIGHUP-driven reloads silently no-op for live sessions.
+	// Mirrors the watchRulesFiles callback above — keep both in sync.
 	rules = loadRules(CWD);
+	sessionRules.clear();
 	logAlways(`Rules reloaded via SIGHUP: ${rules.rules.length} rules active`);
 });
 
diff --git a/src/harness/types.ts b/src/harness/types.ts
index bb2443a..c30c651 100644
--- a/src/harness/types.ts
+++ b/src/harness/types.ts
@@ -119,6 +119,16 @@ export interface HarnessEvent {
 	 *  record to activity.jsonl. Absent for non-prompt events. */
 	prompt?: string;
 
+	/** Recursion guard for the metacoder subprocess path. When the harness
+	 *  spawns `claude -p` to invoke Opus 4.7 (plan §2.5), the spawned
+	 *  subprocess inherits the user's hooks → its first prompt fires
+	 *  UserPromptSubmit back to this harness. Without this flag, the
+	 *  metacoder would fire recursively on its own subprocess and never
+	 *  return. The subprocess sees `INTERLINKED_METACODER_SUBPROCESS=1` in
+	 *  env; the hook forwards it onto the event, and the UserPromptSubmit
+	 *  branch short-circuits when true. */
+	metacoder_subprocess?: boolean;
+
 	/** Agent role for capability scoping (inferred from context if not set) */
 	agent_role?: AgentRole;
 
@@ -672,6 +682,11 @@ export interface GuardRulesConfig {
 	diff_aware?: DiffAwareConfig;
 	/** LLM policy classifier for ambiguous PreToolUse cases */
 	policy_classifier?: ClassifierConfig;
+	/** Per-prompt metacoder that emits a session-scoped overlay before the
+	 *  coding agent's first tool call. Plan: docs/design/metacoding-agent-plan.md.
+	 *  When undefined or `enabled: false`, the metacoder never fires and the
+	 *  agent runs against floor rules only. */
+	metacoder?: import("./metacoder/types.js").MetacoderConfig;
 	/** ML content scanner (OpenAI privacy-filter etc.) for PreToolUse diff/command/egress content + PostToolUse Read/Grep taint */
 	content_scanner?: import("./content-scanner/types.js").ContentScannerConfig;
 	/** Auto-coordination: periodic read-only check-in with MCP server */
diff --git a/src/harness/unified-event.ts b/src/harness/unified-event.ts
index c342c48..2fb495d 100644
--- a/src/harness/unified-event.ts
+++ b/src/harness/unified-event.ts
@@ -134,6 +134,14 @@ export interface UnifiedHookEvent {
 	/** The original native payload. Kept for forensics and debugging; never read
 	 *  in the decision path. Size-capped by adapters when necessary. */
 	raw: unknown;
+
+	/** Recursion guard for the metacoder subprocess path. Set to `true` by
+	 *  `hook-entry.ts` when `INTERLINKED_METACODER_SUBPROCESS=1` is present
+	 *  in the runner's environment. `legacy-client.ts::toLegacyHarnessEvent`
+	 *  copies it through to `HarnessEvent.metacoder_subprocess`, and the
+	 *  harness's UserPromptSubmit branch short-circuits when set. See
+	 *  docs/design/metacoding-agent-plan.md §2.5. */
+	metacoder_subprocess?: boolean;
 }
 
 // -----------------------------------------------------------------------------
diff --git a/src/hook-entry.ts b/src/hook-entry.ts
index 0630230..29e6be3 100644
--- a/src/hook-entry.ts
+++ b/src/hook-entry.ts
@@ -29,6 +29,14 @@ import type { RunnerId, UnifiedHookEvent } from "./harness/unified-event.js";
 
 const DEFAULT_HOOK_TIMEOUT_MS = 2000;
 
+// User-prompt phase calls the metacoder synchronously, which runs Opus 4.7
+// max-effort (~30s) inside the harness. The hook timeout must exceed the
+// metacoder's internal timeout with a buffer so the harness can return a
+// clean "metacoder timed out, allow" decision before the hook gives up on
+// the socket. Strictly greater than `METACODER_TIMEOUT_DEFAULT_MS` (30_000)
+// in `src/harness/metacoder/types.ts`. Plan §2.4, §6, §10 risk #10.
+const DEFAULT_USER_PROMPT_TIMEOUT_MS = 35_000;
+
 // Hook-socket transport variants. The legacy server uses newline-delimited
 // JSON over a raw stream; the new server uses length-prefixed framing.
 const HOOK_PROTOCOL_RAW = "raw";
@@ -40,6 +48,15 @@ type HookProtocol = typeof HOOK_PROTOCOL_RAW | typeof HOOK_PROTOCOL_FRAMED;
 // strings drift across files when one place is refactored and the others
 // aren't.
 const PHASE_PRE_TOOL = "pre-tool";
+const PHASE_USER_PROMPT = "user-prompt";
+
+// Recursion guard for the metacoder subprocess path. Plan §2.5. The harness
+// spawns `claude -p` with this env set to "1"; the spawned subprocess's
+// first prompt fires UserPromptSubmit back to the harness, which would
+// recurse without this flag. Hook-entry forwards the env onto the event so
+// `server.ts` can short-circuit.
+const METACODER_SUBPROCESS_ENV = "INTERLINKED_METACODER_SUBPROCESS";
+const METACODER_SUBPROCESS_FLAG = "1";
 
 // Discriminator values for UnifiedAction. Same rationale as above.
 const ACTION_TOOL_CALL = "tool_call";
@@ -85,6 +102,14 @@ export async function runHookEntry(opts: HookEntryOptions): Promise<HookEntryRes
 	let event: UnifiedHookEvent;
 	event = tryBuildEvent(adapter, opts.nativeJson, opts.nativeEventName);
 
+	// Forward the metacoder-subprocess recursion sentinel from env onto the
+	// event envelope. Plan §2.5 — without this, the framed adapter path
+	// would not surface the sentinel to `server.ts` and the metacoder would
+	// recurse on its own subprocess.
+	if (opts.env[METACODER_SUBPROCESS_ENV] === METACODER_SUBPROCESS_FLAG) {
+		event.metacoder_subprocess = true;
+	}
+
 	const socketPath =
 		opts.socketPath ?? discoverSocket(opts.cwd ?? process.cwd(), event.session_id);
 	if (!socketPath) {
@@ -214,6 +239,7 @@ function resolveHookProtocol(socketPath: string, env: NodeJS.ProcessEnv): HookPr
 
 function defaultTimeoutForPhase(event: UnifiedHookEvent): number {
 	if (event.phase === PHASE_PRE_TOOL) return DEFAULT_LEGACY_PRE_TOOL_TIMEOUT_MS;
+	if (event.phase === PHASE_USER_PROMPT) return DEFAULT_USER_PROMPT_TIMEOUT_MS;
 	return DEFAULT_HOOK_TIMEOUT_MS;
 }
 
diff --git a/src/lib/__tests__/hooks-template.test.ts b/src/lib/__tests__/hooks-template.test.ts
index f2892e1..a6e9bd6 100644
--- a/src/lib/__tests__/hooks-template.test.ts
+++ b/src/lib/__tests__/hooks-template.test.ts
@@ -277,3 +277,62 @@ describe("buildHookScript", () => {
 		);
 	});
 });
+
+describe("buildHookScript — UserPromptSubmit metacoder timeout (P3 round 4)", () => {
+	// The metacoder runs synchronously inside the harness with a 30s
+	// internal timeout. The generated .mjs MUST wait strictly longer so
+	// the harness can return a clean allow/additional_context reply
+	// before the socket gives up. With both at 30s the hook destroys the
+	// socket exactly when the harness is finishing, producing 100%
+	// cold-fallback on metacoder timeouts.
+
+	it("defines HARNESS_USER_PROMPT_TIMEOUT_MS = 35000", () => {
+		const out = buildHookScript("v");
+		expect(out).toContain("const HARNESS_USER_PROMPT_TIMEOUT_MS = 35000;");
+	});
+
+	it("routes UserPromptSubmit / BeforeAgent through the user-prompt timeout in evaluateViaHarness", () => {
+		const out = buildHookScript("v");
+		expect(out).toContain('isUserPromptCall = harnessEvent.hook_event === "UserPromptSubmit"');
+		expect(out).toContain("HARNESS_USER_PROMPT_TIMEOUT_MS");
+	});
+
+	it("forwards the metacoder recursion-guard env onto the harness payload", () => {
+		// Plan §2.5: the .mjs path must propagate
+		// INTERLINKED_METACODER_SUBPROCESS=1 so the harness can short-
+		// circuit the recursive call back from `claude -p`.
+		const out = buildHookScript("v");
+		expect(out).toContain("metacoder_subprocess");
+		expect(out).toContain('process.env.INTERLINKED_METACODER_SUBPROCESS');
+	});
+
+	it("emits user_prompt_advice via formatProviderResponse when the harness returns additional_context", () => {
+		const out = buildHookScript("v");
+		expect(out).toContain('formatProviderResponse("user_prompt_advice"');
+	});
+
+	it("exits silently when INTERLINKED_METACODER_SUBPROCESS=1 — no activity write, no realtime POST (P4 round 5)", () => {
+		// Plan §reviewer-P4 (round 5): when the metacoder spawned this
+		// hook as part of its own `claude -p` subprocess, the prompt we
+		// observe is internal metacoder traffic (system prompt + user
+		// prompt + project_instructions). Letting the script continue
+		// would write that to activity.jsonl and POST it to realtime
+		// sync. Exit silently — UserPromptSubmit with empty stdout =
+		// "allow", which is what the subprocess needs.
+		const out = buildHookScript("v");
+		// Early-exit guard appears BEFORE the first `appendLocal` CALL
+		// SITE. Negative lookbehind excludes the function DEFINITION
+		// (`function appendLocal(event,...)`) which is embedded as a
+		// helper chunk earlier in the script.
+		const sentinelIdx = out.indexOf('INTERLINKED_METACODER_SUBPROCESS === "1"');
+		const callMatch = out.match(/(?<!function )appendLocal\(event,/);
+		const firstAppendLocalCallIdx = callMatch?.index ?? -1;
+		expect(sentinelIdx).toBeGreaterThan(-1);
+		expect(firstAppendLocalCallIdx).toBeGreaterThan(-1);
+		expect(sentinelIdx).toBeLessThan(firstAppendLocalCallIdx);
+		// The guard calls process.exit(0) so all downstream side effects
+		// (appendLocal, realtime POST, harness call) are skipped.
+		const guardSection = out.slice(sentinelIdx, sentinelIdx + 200);
+		expect(guardSection).toContain("process.exit(0)");
+	});
+});
diff --git a/src/lib/hook-template-chunks/provider-responses.ts b/src/lib/hook-template-chunks/provider-responses.ts
index a4d577f..e5cfdbc 100644
--- a/src/lib/hook-template-chunks/provider-responses.ts
+++ b/src/lib/hook-template-chunks/provider-responses.ts
@@ -73,6 +73,16 @@ export const PROVIDER_RESPONSES_CHUNK = `    // ══════════
                 additionalContext: data.summary,
             }};
         }
+        if (responseType === "user_prompt_advice") {
+            // Metacoder system_prompt_addendum lands in the agent's context
+            // via Claude's UserPromptSubmit hookSpecificOutput.additionalContext
+            // channel. Plan §3.
+            if (!data.summary) return {};
+            return { hookSpecificOutput: {
+                hookEventName: "UserPromptSubmit",
+                additionalContext: data.summary,
+            }};
+        }
         return {};
     }
 
@@ -205,6 +215,16 @@ export const PROVIDER_RESPONSES_CHUNK = `    // ══════════
                 additionalContext: data.summary,
             }};
         }
+        if (responseType === "user_prompt_advice") {
+            // Codex mirrors Claude's hookSpecificOutput.additionalContext
+            // contract per docs/hooks-ecosystem-comparison.md:81 — emit the
+            // metacoder addendum on the model-visible channel. Plan §3.
+            if (!data.summary) return {};
+            return { hookSpecificOutput: {
+                hookEventName: "UserPromptSubmit",
+                additionalContext: data.summary,
+            }};
+        }
         return {};
     }
 
diff --git a/src/lib/hooks-template.ts b/src/lib/hooks-template.ts
index 344ac95..07e665c 100644
--- a/src/lib/hooks-template.ts
+++ b/src/lib/hooks-template.ts
@@ -117,6 +117,7 @@ const HARNESS_SOCK_PATH = resolveHarnessSocket();
 const PENDING_WARNINGS_PATH = join(DATA_DIR, "pending-quality-warnings.json");
 const HARNESS_PRE_TIMEOUT_MS = 5000;  // PreToolUse: allows grep acceleration (ripgrep on candidates)
 const HARNESS_POST_TIMEOUT_MS = ${postTimeoutMs}; // PostToolUse: from harness mode "${modeName}" — see src/harness/rules/modes.ts. Re-rendered on every \`interlinked harness mode <name>\` change.
+const HARNESS_USER_PROMPT_TIMEOUT_MS = 35000; // UserPromptSubmit: must exceed METACODER_TIMEOUT_DEFAULT_MS (30s) so the hook doesn't race the harness's clean timeout response and trigger a spurious cold-fallback. Plan §2.4 / metacoding-agent-plan.md.
 
 /**
  * Flush any pending quality warnings from a previous PostToolUse to stderr.
@@ -231,7 +232,17 @@ function tryHealHarness() {
  */
 function evaluateViaHarness(harnessEvent) {
     const isPreTool = harnessEvent.hook_event === "PreToolUse" || harnessEvent.hook_event === "BeforeTool";
-    const timeoutMs = isPreTool ? HARNESS_PRE_TIMEOUT_MS : HARNESS_POST_TIMEOUT_MS;
+    const isUserPromptCall = harnessEvent.hook_event === "UserPromptSubmit" || harnessEvent.hook_event === "BeforeAgent";
+    // UserPromptSubmit runs the metacoder synchronously inside the harness
+    // (Opus 4.7 max / GPT-5.5 high, ~30s budget). The hook must wait
+    // strictly longer than the metacoder's internal timeout so the harness
+    // can finalize an allow/additional_context reply before the socket
+    // gives up. Drift between these two budgets = 100% cold-fallback.
+    const timeoutMs = isPreTool
+        ? HARNESS_PRE_TIMEOUT_MS
+        : isUserPromptCall
+            ? HARNESS_USER_PROMPT_TIMEOUT_MS
+            : HARNESS_POST_TIMEOUT_MS;
 
     return new Promise((resolve) => {
         if (!existsSync(HARNESS_SOCK_PATH)) {
@@ -577,6 +588,20 @@ async function main() {
 
     if (!event) process.exit(0);
 
+    // Plan §reviewer-P4 (round 5): when the harness spawned this hook as
+    // part of the metacoder's own \`claude -p\` subprocess, every prompt
+    // we see here is internal metacoder traffic — its system prompt
+    // plus the user's prompt plus project_instructions. Letting the
+    // script continue would (a) re-trigger the harness recursion guard
+    // (wasteful socket round-trip), (b) write the metacoder's own
+    // prompt to activity.jsonl as if it were user activity, and (c) POST
+    // it to the realtime sync endpoint. Exit silently. UserPromptSubmit
+    // with no stdout = "allow", which is what Claude Code expects so
+    // the metacoder subprocess can proceed.
+    if (process.env.INTERLINKED_METACODER_SUBPROCESS === "1") {
+        process.exit(0);
+    }
+
     // Always resolve hookEvent from the normalized event so it carries the
     // canonical name (PreToolUse / PostToolUse / UserPromptSubmit / ...).
     // The downstream isPreTool / isPostTool / isUserPrompt checks AND the
@@ -714,6 +739,11 @@ ${PROVIDER_RESPONSES_CHUNK}
             cwd: rawInput.cwd || event.cwd || null,
             model: event.model || null,
             timestamp: new Date().toISOString(),
+            // Recursion guard for the metacoder subprocess path — when the
+            // harness spawns \`claude -p\` to invoke Opus 4.7, the subprocess
+            // inherits this hook and fires its own UserPromptSubmit. The
+            // sentinel env var lets the harness short-circuit. Plan §2.5.
+            metacoder_subprocess: process.env.INTERLINKED_METACODER_SUBPROCESS === "1",
         };
         try {
             const promptDecision = await evaluateViaHarness(promptHarnessEvent);
@@ -724,6 +754,19 @@ ${PROVIDER_RESPONSES_CHUNK}
                     event.tool_input_summary = promptDecision.redacted_prompt.slice(0, 200);
                 }
             }
+            // Metacoder system_prompt_addendum — emit on stdout via the
+            // provider-specific channel so the model sees it inline with the
+            // user prompt. Claude/Codex use hookSpecificOutput.additionalContext;
+            // other runners fall back to {} (no model-visible channel for
+            // UserPromptSubmit). Plan §3.
+            if (promptDecision && typeof promptDecision.additional_context === "string" && promptDecision.additional_context.length > 0) {
+                const adviceResponse = formatProviderResponse("user_prompt_advice", {
+                    summary: promptDecision.additional_context,
+                });
+                if (adviceResponse && Object.keys(adviceResponse).length > 0) {
+                    console.log(JSON.stringify(adviceResponse));
+                }
+            }
         } catch (_err) { void 0; /* fail-open: raw prompt still gets inline secrets scrub via scrubPayload below */ }
     }
 

From 480c9bd547347e4df8d799490ee9d72fca565f52 Mon Sep 17 00:00:00 2001
From: QuentinCody <33259999+QuentinCody@users.noreply.github.com>
Date: Thu, 14 May 2026 12:58:57 -0400
Subject: [PATCH 4/6] fix: load project tsconfig in single-file tsgo checks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tsgo refuses to load `tsconfig.json` when a file path is on the command
line (`error TS5112`), so the harness's single-file PostToolUse check
was effectively running with default `compilerOptions` — no `types:
["node"]`, no `moduleResolution: "bundler"`. Every `import { ... } from
"node:fs"` then produced a spurious `TS2591: Cannot find name 'node:fs'`
in any file that uses node-protocol imports.

The new runTsgo materializes a per-call tmp `tsconfig.json` that
extends the project's real config and `include`s only the target file,
then invokes `tsgo -p <tmpTsconfig>`. tsgo now loads the full
`compilerOptions` while still checking exactly one file. The tmp
tsconfig is cleaned up after the call.

For `simulateEdit`'s tmp file path (which lives in `/tmp` and has no
sibling tsconfig), `runTsgo` accepts an explicit `projectRootHint` so
we walk up from the ORIGINAL file's directory to find the real
project's `tsconfig.json` instead of giving up at the tmp dir.

Also swaps the cache-key hash from SHA-1 → SHA-256 to satisfy the
harness's own `ubs_weak_hash` linter rule — non-security cache, perf
cost is in microseconds at this scale.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/harness/tsgo-runner.ts | 86 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 82 insertions(+), 4 deletions(-)

diff --git a/src/harness/tsgo-runner.ts b/src/harness/tsgo-runner.ts
index da79715..6270439 100644
--- a/src/harness/tsgo-runner.ts
+++ b/src/harness/tsgo-runner.ts
@@ -14,9 +14,17 @@
 
 import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { existsSync, mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import {
+	existsSync,
+	mkdtempSync,
+	readFileSync,
+	rmdirSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { TsgoDiagnostic } from "./daemon-protocol.js";
 
 export interface TsgoRunnerOptions {
@@ -162,7 +170,11 @@ function computeCacheKey(path: string): string {
 	} catch {
 		mtime = 0;
 	}
-	const h = createHash("sha1");
+	// Non-security cache key (path + mtime + size → dedupe within a
+	// session). SHA-256 over SHA-1 because the harness's `ubs_weak_hash`
+	// rule flags SHA-1 and the per-call cost is microseconds either way
+	// for ~50 bytes of input.
+	const h = createHash("sha256");
 	h.update(path);
 	h.update("|");
 	h.update(String(mtime));
@@ -181,6 +193,62 @@ function readFileSyncSafe(path: string): string | null {
 	return out;
 }
 
+/** Walk up from `startDir` looking for `tsconfig.json`. Capped at 6 levels
+ *  so we don't traverse the entire filesystem on edits to `/tmp` or
+ *  similar paths without a project root. */
+function findProjectTsconfig(startDir: string): string | null {
+	let dir = startDir;
+	for (let i = 0; i < 6; i++) {
+		const candidate = join(dir, "tsconfig.json");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+	return null;
+}
+
+/** Materialize a per-call tmp tsconfig that extends the project's real
+ *  tsconfig and includes ONLY the target file. Without this dance, tsgo
+ *  refuses to load tsconfig.json when a file is on the command line
+ *  ("error TS5112"), so every `import { ... } from "node:fs"` and the
+ *  like produces spurious TS2591 errors. Routing through
+ *  `-p <tmpTsconfig>` keeps tsgo honest with the project's own
+ *  `compilerOptions` — `types: ["node"]`, `moduleResolution`, target,
+ *  etc.
+ *
+ *  Returns the tmp tsconfig path + a cleanup fn. Null when no project
+ *  tsconfig is anywhere upstream (caller falls back to bare single-file
+ *  mode, which is the only case where tsgo's defaults are acceptable). */
+function makeTmpProjectTsconfig(targetFile: string, projectRootHint: string): {
+	path: string;
+	cleanup: () => void;
+} | null {
+	const projectTsconfig = findProjectTsconfig(projectRootHint);
+	if (!projectTsconfig) return null;
+	const dir = mkdtempSync(join(tmpdir(), "interlinked-tsgo-cfg-"));
+	const path = join(dir, "tsconfig.json");
+	writeFileSync(
+		path,
+		JSON.stringify({ extends: projectTsconfig, include: [targetFile] }, null, 2),
+	);
+	return {
+		path,
+		cleanup: () => {
+			try {
+				unlinkSync(path);
+			} catch {
+				/* best-effort */
+			}
+			try {
+				rmdirSync(dir);
+			} catch {
+				/* best-effort */
+			}
+		},
+	};
+}
+
 async function runTsgo(
 	executable: string,
 	path: string,
@@ -188,7 +256,16 @@ async function runTsgo(
 	timeoutMs: number,
 ): Promise<TsgoDiagnostic[]> {
 	return new Promise((resolve) => {
-		const args = [...extraArgs, path];
+		// Prefer a tmp tsconfig that extends the project's real config so
+		// tsgo loads `compilerOptions` (types, moduleResolution, target,
+		// etc.). Without this, tsgo's "error TS5112" causes the project
+		// tsconfig to be skipped, `@types/node` types vanish, and every
+		// `node:fs` / `node:path` / `process` reference produces a
+		// spurious TS2591. See `makeTmpProjectTsconfig` for the dance.
+		// Fall back to bare single-file mode only when no project tsconfig
+		// is upstream (e.g., editing files outside a project).
+		const tmpConfig = makeTmpProjectTsconfig(path, dirname(path));
+		const args = tmpConfig ? [...extraArgs, "-p", tmpConfig.path] : [...extraArgs, path];
 		const child = spawn(executable, args, { stdio: ["ignore", "pipe", "pipe"] });
 		let stdout = "";
 		let stderr = "";
@@ -196,6 +273,7 @@ async function runTsgo(
 		const finalize = (diagnostics: TsgoDiagnostic[]): void => {
 			if (settled) return;
 			settled = true;
+			if (tmpConfig) tmpConfig.cleanup();
 			resolve(diagnostics);
 		};
 		const timer = setTimeout(() => {

From b00dada6a1e75d10e927739d869610f615e7f064 Mon Sep 17 00:00:00 2001
From: QuentinCody <33259999+QuentinCody@users.noreply.github.com>
Date: Thu, 14 May 2026 12:59:29 -0400
Subject: [PATCH 5/6] feat: interlinked metacoder CLI + README + docs autogen
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

User-facing surface for the per-prompt overlay generator that landed in
31a14fe. Previously, the only way to enable/disable was to hand-edit
`.interlinked/guard-rules.local.json` with knowledge of the JSON path
— not discoverable.

New `interlinked metacoder` subcommand mirroring the `interlinked
scanner` pattern: `status`, `enable`, `disable`. Each toggle records an
audit entry at `.interlinked/metacoder.audit.jsonl` (timestamp, actor,
optional `--reason`) so "when was it off, and why?" is answerable.
Reads/writes the same `metacoder.enabled` JSON path the rules-loader
honors, so hot-reload picks up the change on the next watcher tick (~2
s) — no harness restart.

README gets a "Metacoder (per-prompt overlay)" section with the
subscription-auth promise, latency/cost trade-off, CLI cheat sheet, and
links to the design memo + autogen config reference.

`scripts/generate-docs.ts` is updated so the docs autogen path
(`npm run docs`) now folds the metacoder into `configuration.md` (one
table per field with defaults pulled directly from
`DEFAULT_METACODER_CONFIG` — single source of truth) and the
`cli-reference.md` picks up the new subcommands via the commander
`--help` introspection it already does for every other command group.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md                       |  40 ++++
 docs/generated/cli-reference.md |  61 ++++++
 docs/generated/configuration.md |  33 ++++
 scripts/generate-docs.ts        |  44 +++++
 src/commands/metacoder.test.ts  | 157 +++++++++++++++
 src/commands/metacoder.ts       | 334 ++++++++++++++++++++++++++++++++
 src/index.ts                    |  46 +++++
 7 files changed, 715 insertions(+)
 create mode 100644 src/commands/metacoder.test.ts
 create mode 100644 src/commands/metacoder.ts

diff --git a/README.md b/README.md
index 0efb6c0..d445024 100644
--- a/README.md
+++ b/README.md
@@ -184,6 +184,46 @@ Switch modes with `interlinked mode <name>`:
 Team-shared policy lives in `.interlinked/guard-rules.json`. Personal
 overrides go in `.interlinked/guard-rules.local.json` (gitignored).
 
+## Metacoder (per-prompt overlay)
+
+On every `UserPromptSubmit`, the **metacoder** runs a peer of the coding
+agent — **Opus 4.7 max-effort** for Claude Code sessions, **GPT-5.5
+xhigh** for Codex sessions — that reads your prompt + project
+`AGENTS.md` / `CLAUDE.md` and emits a session-scoped overlay of guard
+rules. The overlay merges on top of the floor for the lifetime of the
+prompt: prompt-specific blocks the floor rules don't know about (e.g.
+"this prompt is about payments, so don't touch `src/auth/`"), enforced
+the same hard-block way the built-in rules are.
+
+Both transports use **your existing Claude Code / Codex CLI
+subscription** (`claude -p` / `codex exec`). No `ANTHROPIC_API_KEY` or
+`OPENAI_API_KEY` needed.
+
+**Trade-off:** 5–30 s of added latency on every UserPromptSubmit
+before the coding agent starts, and ~$0.05–$0.30 of subscription credit
+per prompt at the maximum reasoning tier. Fail-open everywhere — if the
+subprocess can't reach the subscription (quota hit, CLI not installed,
+timeout), the overlay is skipped and the prompt reaches the agent
+against floor rules only.
+
+```bash
+interlinked metacoder status                          # current state + recent audit
+interlinked metacoder disable --reason "burn rate"    # off, audited
+interlinked metacoder enable                          # back on
+```
+
+Or hand-edit `.interlinked/guard-rules.local.json`:
+
+```json
+{ "metacoder": { "enabled": false } }
+```
+
+The harness hot-reloads on the next file-watcher tick (~2 s) — no
+restart needed. Full design and operational notes:
+[docs/design/metacoding-agent-plan.md](./docs/design/metacoding-agent-plan.md).
+Per-field config reference:
+[docs/generated/configuration.md § Metacoder](./docs/generated/configuration.md#metacoder-per-prompt-overlay).
+
 ## Privacy
 
 - Harness decisions and activity capture are local by default. Data leaves
diff --git a/docs/generated/cli-reference.md b/docs/generated/cli-reference.md
index 0d74eea..7f41816 100644
--- a/docs/generated/cli-reference.md
+++ b/docs/generated/cli-reference.md
@@ -39,6 +39,7 @@ Commands:
   login [options]                            Authenticate with the server (opens browser)
   logout [options]                           Clear authentication credentials (preserves other config)
   logs [options]                             View local activity log (offline, no server needed)
+  metacoder                                  Per-prompt overlay generator — toggle, inspect, audit
   mode [options] [name]                      Show current enforcement mode, or switch to balanced / strict / lenient
   multi-edit [options] [path]                Apply N old/new string edits atomically to one or more files. Gate runs once on final content. Ambiguity evaluated after prior edits.
   mutation                                   Per-file mutation-score ratchet — fails on any file whose mutation score drops
@@ -749,6 +750,66 @@ Options:
   -h, --help         display help for command
 ```
 
+## Metacoder
+
+```
+Usage: interlinked metacoder [options] [command]
+
+Per-prompt overlay generator — toggle, inspect, audit
+
+Options:
+  -h, --help         display help for command
+
+Commands:
+  enable [options]   Enable the per-prompt metacoder overlay generator
+  disable [options]  Disable the metacoder. The exact timestamp is recorded in
+                     the audit log.
+  status [options]   Show metacoder enable state + recent toggle audit
+  help [command]     display help for command
+```
+
+### metacoder enable
+
+```
+Usage: interlinked metacoder enable [options]
+
+Enable the per-prompt metacoder overlay generator
+
+Options:
+  --reason <text>  Why — recorded in metacoder.audit.jsonl
+  --json           Machine-readable output
+  --short          One-line summary
+  -h, --help       display help for command
+```
+
+### metacoder disable
+
+```
+Usage: interlinked metacoder disable [options]
+
+Disable the metacoder. The exact timestamp is recorded in the audit log.
+
+Options:
+  --reason <text>  Why — recorded in metacoder.audit.jsonl
+  --json           Machine-readable output
+  --short          One-line summary
+  -h, --help       display help for command
+```
+
+### metacoder status
+
+```
+Usage: interlinked metacoder status [options]
+
+Show metacoder enable state + recent toggle audit
+
+Options:
+  --json      Machine-readable output
+  --short     One-line summary
+  --full      Detailed output (full audit log)
+  -h, --help  display help for command
+```
+
 ## Other Commands
 
 ### enable
diff --git a/docs/generated/configuration.md b/docs/generated/configuration.md
index f80a34c..a322fbe 100644
--- a/docs/generated/configuration.md
+++ b/docs/generated/configuration.md
@@ -50,3 +50,36 @@ Controls which checks suppress pre-existing findings when editing files.
 | `test_first` | `true` | Nudge agent to write/run tests before editing source files |
 | `cross_file_switch_discriminant` | `true` | Flags the same switch discriminant (.kind/.type/.tag) appearing in multiple files — usually a polymorphism opportunity |
 | `single_implementation_interface` | `true` | Flags exported interfaces with exactly one implementor — possible premature abstraction |
+
+## Metacoder (per-prompt overlay)
+
+On every `UserPromptSubmit` the metacoder runs a peer of the coding agent (Opus 4.7 max-effort for Claude sessions, GPT-5.5 xhigh for Codex sessions) to emit a session-scoped overlay of guard rules. Both transports use the user's existing **Claude Code / Codex CLI subscription** — no API key required. Plan: [docs/design/metacoding-agent-plan.md](../design/metacoding-agent-plan.md).
+
+**Toggle from the CLI:**
+
+```
+interlinked metacoder status        # show current state + recent audit
+interlinked metacoder enable        # turn on (default)
+interlinked metacoder disable --reason "burn rate"   # turn off, with audit
+```
+
+**Or hand-edit `.interlinked/guard-rules.local.json`:**
+
+```json
+{
+  "metacoder": { "enabled": false }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `enabled` | `true` | Master switch for the per-prompt metacoder |
+| `timeout_ms` | `30000` | Metacoder LLM call timeout. Clamped at merge to keep < hook timeout (33000 ms). |
+| `max_rules` | `20` | Hard cap on overlay rule count per emission |
+| `max_pattern_length` | `200` | Per-pattern regex char cap (bounds ReDoS / compile cost) |
+| `max_patterns_per_rule` | `10` | Patterns-per-rule cap |
+| `max_addendum_chars` | `2000` | `system_prompt_addendum` length cap |
+
+**Hook timeout coordination:** the generated hook waits 35000 ms (5 s buffer past the metacoder's internal timeout) so the harness can return a clean "metacoder timed out, allow" decision before the hook cold-falls back. Both `hook-entry.ts` (adapter path) and the generated `.mjs` (legacy path) honor this budget.
+
+**Latency / cost:** 5–30 s per prompt, $0.05–$0.30 per prompt (Opus 4.7 max-effort). Fail-open: any subprocess failure (CLI not installed, subscription quota hit, timeout) skips the overlay and lets the prompt reach the agent against floor rules only.
diff --git a/scripts/generate-docs.ts b/scripts/generate-docs.ts
index 8c8ed7c..d918928 100644
--- a/scripts/generate-docs.ts
+++ b/scripts/generate-docs.ts
@@ -15,6 +15,10 @@ import { join } from "node:path";
 // Import data structures from the harness
 import { getDefaultConfig, getBuiltinRules } from "../src/harness/rules-loader.js";
 import { STRUCTURAL_CHECK_META } from "../src/harness/check-metadata.js";
+import {
+	DEFAULT_METACODER_CONFIG,
+	USER_PROMPT_HOOK_TIMEOUT_MS,
+} from "../src/harness/metacoder/types.js";
 
 const OUT_DIR = join(import.meta.dirname, "..", "docs", "generated");
 if (!existsSync(OUT_DIR)) mkdirSync(OUT_DIR, { recursive: true });
@@ -194,6 +198,44 @@ function generateConfigReference(): string {
 		}
 	}
 
+	lines.push("");
+	lines.push("## Metacoder (per-prompt overlay)");
+	lines.push("");
+	lines.push(
+		"On every `UserPromptSubmit` the metacoder runs a peer of the coding agent (Opus 4.7 max-effort for Claude sessions, GPT-5.5 xhigh for Codex sessions) to emit a session-scoped overlay of guard rules. Both transports use the user's existing **Claude Code / Codex CLI subscription** — no API key required. Plan: [docs/design/metacoding-agent-plan.md](../design/metacoding-agent-plan.md).",
+	);
+	lines.push("");
+	lines.push("**Toggle from the CLI:**");
+	lines.push("");
+	lines.push("```");
+	lines.push("interlinked metacoder status        # show current state + recent audit");
+	lines.push("interlinked metacoder enable        # turn on (default)");
+	lines.push("interlinked metacoder disable --reason \"burn rate\"   # turn off, with audit");
+	lines.push("```");
+	lines.push("");
+	lines.push("**Or hand-edit `.interlinked/guard-rules.local.json`:**");
+	lines.push("");
+	lines.push("```json");
+	lines.push("{");
+	lines.push("  \"metacoder\": { \"enabled\": false }");
+	lines.push("}");
+	lines.push("```");
+	lines.push("");
+	lines.push("| Setting | Default | Description |");
+	lines.push("|---------|---------|-------------|");
+	const m = DEFAULT_METACODER_CONFIG;
+	lines.push(`| \`enabled\` | \`${m.enabled}\` | Master switch for the per-prompt metacoder |`);
+	lines.push(`| \`timeout_ms\` | \`${m.timeout_ms}\` | Metacoder LLM call timeout. Clamped at merge to keep < hook timeout (${USER_PROMPT_HOOK_TIMEOUT_MS - 2_000} ms). |`);
+	lines.push(`| \`max_rules\` | \`${m.max_rules}\` | Hard cap on overlay rule count per emission |`);
+	lines.push(`| \`max_pattern_length\` | \`${m.max_pattern_length}\` | Per-pattern regex char cap (bounds ReDoS / compile cost) |`);
+	lines.push(`| \`max_patterns_per_rule\` | \`${m.max_patterns_per_rule}\` | Patterns-per-rule cap |`);
+	lines.push(`| \`max_addendum_chars\` | \`${m.max_addendum_chars}\` | \`system_prompt_addendum\` length cap |`);
+	lines.push("");
+	lines.push(
+		`**Hook timeout coordination:** the generated hook waits ${USER_PROMPT_HOOK_TIMEOUT_MS} ms (5 s buffer past the metacoder's internal timeout) so the harness can return a clean "metacoder timed out, allow" decision before the hook cold-falls back. Both \`hook-entry.ts\` (adapter path) and the generated \`.mjs\` (legacy path) honor this budget.`,
+	);
+	lines.push("");
+	lines.push("**Latency / cost:** 5–30 s per prompt, $0.05–$0.30 per prompt (Opus 4.7 max-effort). Fail-open: any subprocess failure (CLI not installed, subscription quota hit, timeout) skips the overlay and lets the prompt reach the agent against floor rules only.");
 	lines.push("");
 	return lines.join("\n");
 }
@@ -255,6 +297,7 @@ function generateCliReference(): string {
 		"trace",
 		"guard",
 		"git",
+		"metacoder",
 	];
 
 	// Commands with subcommands — mirror the groups registered in src/index.ts.
@@ -272,6 +315,7 @@ function generateCliReference(): string {
 		coverage: ["check", "baseline"],
 		mutation: ["check", "baseline"],
 		completions: ["bash", "zsh", "fish"],
+		metacoder: ["enable", "disable", "status"],
 	};
 
 	for (const cmd of commandNames) {
diff --git a/src/commands/metacoder.test.ts b/src/commands/metacoder.test.ts
new file mode 100644
index 0000000..b208289
--- /dev/null
+++ b/src/commands/metacoder.test.ts
@@ -0,0 +1,157 @@
+import { describe, expect, it, beforeEach, afterEach } from "vitest";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+	metacoderDisableCommand,
+	metacoderEnableCommand,
+	metacoderStatusCommand,
+	readCurrentMetacoderEnabled,
+} from "./metacoder.js";
+
+const LOCAL_RULES_FILE = "guard-rules.local.json";
+const AUDIT_LOG_FILE = "metacoder.audit.jsonl";
+
+let originalCwd: string;
+let workDir: string;
+function localRulesPath(): string {
+	return join(workDir, ".interlinked", LOCAL_RULES_FILE);
+}
+function auditPath(): string {
+	return join(workDir, ".interlinked", AUDIT_LOG_FILE);
+}
+
+beforeEach(() => {
+	originalCwd = process.cwd();
+	workDir = mkdtempSync(join(tmpdir(), "metacoder-cmd-"));
+	mkdirSync(join(workDir, ".interlinked"), { recursive: true });
+	process.chdir(workDir);
+});
+afterEach(() => {
+	process.chdir(originalCwd);
+	rmSync(workDir, { recursive: true, force: true });
+});
+
+describe("readCurrentMetacoderEnabled", () => {
+	it("defaults to enabled when guard-rules.local.json is absent", () => {
+		expect(readCurrentMetacoderEnabled(workDir)).toBe(true);
+	});
+
+	it("defaults to enabled when the metacoder field is absent", () => {
+		writeFileSync(localRulesPath(), JSON.stringify({ content_scanner: { enabled: true } }));
+		expect(readCurrentMetacoderEnabled(workDir)).toBe(true);
+	});
+
+	it("returns false when explicitly disabled", () => {
+		writeFileSync(localRulesPath(), JSON.stringify({ metacoder: { enabled: false } }));
+		expect(readCurrentMetacoderEnabled(workDir)).toBe(false);
+	});
+
+	it("returns true when explicitly enabled", () => {
+		writeFileSync(
+			localRulesPath(),
+			JSON.stringify({ metacoder: { enabled: true, timeout_ms: 10_000 } }),
+		);
+		expect(readCurrentMetacoderEnabled(workDir)).toBe(true);
+	});
+
+	it("treats malformed JSON as enabled (fail-open)", () => {
+		writeFileSync(localRulesPath(), "not json");
+		expect(readCurrentMetacoderEnabled(workDir)).toBe(true);
+	});
+});
+
+describe("metacoderDisableCommand", () => {
+	it("writes enabled:false into guard-rules.local.json", async () => {
+		await metacoderDisableCommand({ json: true, reason: "save quota" });
+		expect(existsSync(localRulesPath())).toBe(true);
+		const parsed = JSON.parse(readFileSync(localRulesPath(), "utf-8")) as {
+			metacoder?: { enabled?: boolean };
+		};
+		expect(parsed.metacoder?.enabled).toBe(false);
+	});
+
+	it("preserves other top-level config fields when toggling", async () => {
+		writeFileSync(
+			localRulesPath(),
+			JSON.stringify({
+				content_scanner: { enabled: true },
+				disabled_rules: ["some_rule"],
+			}),
+		);
+		await metacoderDisableCommand({ json: true });
+		const parsed = JSON.parse(readFileSync(localRulesPath(), "utf-8")) as {
+			content_scanner?: { enabled?: boolean };
+			disabled_rules?: string[];
+			metacoder?: { enabled?: boolean };
+		};
+		expect(parsed.content_scanner?.enabled).toBe(true);
+		expect(parsed.disabled_rules).toEqual(["some_rule"]);
+		expect(parsed.metacoder?.enabled).toBe(false);
+	});
+
+	it("appends an audit entry", async () => {
+		await metacoderDisableCommand({ json: true, reason: "burn rate too high" });
+		const lines = readFileSync(auditPath(), "utf-8")
+			.split("\n")
+			.filter((l) => l.trim().length > 0);
+		expect(lines).toHaveLength(1);
+		const entry = JSON.parse(lines[0]) as { action: string; to: boolean; reason: string };
+		expect(entry.action).toBe("disable");
+		expect(entry.to).toBe(false);
+		expect(entry.reason).toBe("burn rate too high");
+	});
+});
+
+describe("metacoderEnableCommand", () => {
+	it("writes enabled:true back into guard-rules.local.json", async () => {
+		writeFileSync(localRulesPath(), JSON.stringify({ metacoder: { enabled: false } }));
+		await metacoderEnableCommand({ json: true });
+		const parsed = JSON.parse(readFileSync(localRulesPath(), "utf-8")) as {
+			metacoder?: { enabled?: boolean };
+		};
+		expect(parsed.metacoder?.enabled).toBe(true);
+	});
+
+	it("preserves other metacoder fields when re-enabling", async () => {
+		writeFileSync(
+			localRulesPath(),
+			JSON.stringify({ metacoder: { enabled: false, timeout_ms: 12_000 } }),
+		);
+		await metacoderEnableCommand({ json: true });
+		const parsed = JSON.parse(readFileSync(localRulesPath(), "utf-8")) as {
+			metacoder?: { enabled?: boolean; timeout_ms?: number };
+		};
+		expect(parsed.metacoder?.enabled).toBe(true);
+		expect(parsed.metacoder?.timeout_ms).toBe(12_000);
+	});
+
+	it("records a no_change audit entry when already enabled", async () => {
+		writeFileSync(localRulesPath(), JSON.stringify({ metacoder: { enabled: true } }));
+		await metacoderEnableCommand({ json: true });
+		const lines = readFileSync(auditPath(), "utf-8")
+			.split("\n")
+			.filter((l) => l.trim().length > 0);
+		expect(lines).toHaveLength(1);
+		const entry = JSON.parse(lines[0]) as { action: string };
+		expect(entry.action).toBe("no_change");
+	});
+});
+
+describe("metacoderStatusCommand", () => {
+	it("does not throw when the audit log is empty", async () => {
+		await expect(metacoderStatusCommand({ json: true })).resolves.toBeUndefined();
+	});
+
+	it("reads recent audit entries on status --full", async () => {
+		await metacoderDisableCommand({ json: true, reason: "first" });
+		await metacoderEnableCommand({ json: true, reason: "second" });
+		await expect(metacoderStatusCommand({ json: true, full: true })).resolves.toBeUndefined();
+		// The status command's payload is rendered via output(); we don't
+		// assert on stdout here (formatter writes to stdout directly).
+		// The toggling itself wrote the audit log; status reads it without
+		// throwing — that's the contract under test.
+		expect(existsSync(auditPath())).toBe(true);
+	});
+});
diff --git a/src/commands/metacoder.ts b/src/commands/metacoder.ts
new file mode 100644
index 0000000..f5abf88
--- /dev/null
+++ b/src/commands/metacoder.ts
@@ -0,0 +1,334 @@
+// ===========================================
+// interlinked metacoder — toggle + inspect the per-prompt overlay generator
+// ===========================================
+//
+// The metacoder runs on every UserPromptSubmit and generates a session-
+// scoped overlay of guard rules using the user's Claude Code / Codex CLI
+// subscription. It's heavyweight (5–30 s wall-clock per prompt) and not
+// free (Opus-4.7 max-effort / GPT-5.5 xhigh). This command lets users
+// flip it on/off without restarting the harness — `rules-loader.ts`
+// hot-reloads `guard-rules.local.json` on the next file watcher tick.
+//
+// Mirrors the `interlinked scanner` toggle pattern: a tiny JSON merge
+// into `.interlinked/guard-rules.local.json` plus an append-only audit
+// log at `.interlinked/metacoder.audit.jsonl` so reviewers can answer
+// "when was the metacoder off, and why?".
+//
+// Design plan: docs/design/metacoding-agent-plan.md §2.1 (latency
+// rationale), §reviewer-P1 round 6 (stale-overlay eviction when
+// disabled).
+
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { hostname, userInfo } from "node:os";
+import { join } from "node:path";
+import { getConfigDir } from "../lib/config.js";
+import { c, header, kvLine } from "../lib/formatter.js";
+import type { JsonObject } from "../lib/json-types.js";
+import { getOutputMode, output } from "../lib/output.js";
+
+const LOCAL_RULES_FILE = "guard-rules.local.json";
+const AUDIT_LOG_FILE = "metacoder.audit.jsonl";
+const TYPEOF_OBJECT = "object" as const;
+const NO_CHANGE_ACTION = "no_change" as const;
+
+export interface MetacoderToggleOptions {
+	reason?: string;
+	json?: boolean;
+	short?: boolean;
+	full?: boolean;
+}
+
+export interface MetacoderStatusOptions {
+	json?: boolean;
+	short?: boolean;
+	full?: boolean;
+}
+
+type AuditAction = "enable" | "disable" | "no_change";
+
+interface AuditEntry {
+	ts: string;
+	action: AuditAction;
+	from?: boolean;
+	to?: boolean;
+	actor: {
+		user: string;
+		host: string;
+		tty: string | null;
+		via: "cli";
+	};
+	reason: string | null;
+}
+
+interface AuditEntryArgs {
+	action: AuditAction;
+	from: boolean;
+	to: boolean;
+	reason: string | null;
+}
+
+function getLocalRulesPath(cwd: string): string {
+	return join(getConfigDir(cwd), LOCAL_RULES_FILE);
+}
+
+function getAuditLogPath(cwd: string): string {
+	return join(getConfigDir(cwd), AUDIT_LOG_FILE);
+}
+
+function isPlainObject(v: unknown): v is JsonObject {
+	return typeof v === TYPEOF_OBJECT && v !== null && !Array.isArray(v);
+}
+
+/** Public — also called by callers that want to read the resolved flag
+ *  without spawning the full status command. Returns `true` when the
+ *  field is absent (metacoder defaults to enabled, per
+ *  `DEFAULT_METACODER_CONFIG.enabled`); only returns `false` when
+ *  explicitly disabled in `guard-rules.local.json`. */
+export function readCurrentMetacoderEnabled(cwd: string): boolean {
+	const path = getLocalRulesPath(cwd);
+	if (!existsSync(path)) return true;
+	try {
+		const raw = JSON.parse(readFileSync(path, "utf-8")) as JsonObject;
+		const block = raw?.metacoder;
+		if (!isPlainObject(block)) return true;
+		return block.enabled !== false;
+	} catch (err) {
+		// Malformed JSON is fail-open — the default is enabled, and we
+		// don't want a typo in the config file to silently shut down the
+		// metacoder. `interlinked verify` will surface the syntax error
+		// on next run; users see the metacoder still running here.
+		void err;
+		return true;
+	}
+}
+
+/** Merge-write the `metacoder.enabled` flag into `guard-rules.local.json`.
+ *  Preserves every other field in the file. */
+function writeEnabledFlag(cwd: string, enabled: boolean): void {
+	const path = getLocalRulesPath(cwd);
+	let parsed: JsonObject = {};
+	if (existsSync(path)) {
+		try {
+			const raw = readFileSync(path, "utf-8");
+			const obj: unknown = JSON.parse(raw);
+			if (isPlainObject(obj)) parsed = obj;
+		} catch (err) {
+			process.stderr.write(
+				`[interlinked:metacoder] Warning: ${path} was unparseable; overwriting (${err instanceof Error ? err.message : String(err)})\n`,
+			);
+		}
+	}
+	const block = isPlainObject(parsed.metacoder) ? parsed.metacoder : {};
+	block.enabled = enabled;
+	parsed.metacoder = block;
+	writeFileSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
+}
+
+function resolveTty(): string | null {
+	if (process.stdout.isTTY) {
+		return process.env.SSH_TTY || process.env.TTY || null;
+	}
+	return null;
+}
+
+function appendAudit(cwd: string, entry: AuditEntry): void {
+	const path = getAuditLogPath(cwd);
+	try {
+		appendFileSync(path, `${JSON.stringify(entry)}\n`);
+	} catch (err) {
+		process.stderr.write(
+			`[interlinked:metacoder] Warning: failed to write audit log (${err instanceof Error ? err.message : String(err)})\n`,
+		);
+	}
+}
+
+function buildAuditEntry(args: AuditEntryArgs): AuditEntry {
+	const info = userInfo();
+	return {
+		ts: new Date().toISOString(),
+		action: args.action,
+		from: args.from,
+		to: args.to,
+		actor: { user: info.username, host: hostname(), tty: resolveTty(), via: "cli" },
+		reason: args.reason,
+	};
+}
+
+function deriveAction(current: boolean, target: boolean): AuditAction {
+	if (current === target) return NO_CHANGE_ACTION;
+	return target ? "enable" : "disable";
+}
+
+async function applyToggle(
+	cwd: string,
+	target: boolean,
+	opts: MetacoderToggleOptions,
+): Promise<void> {
+	const current = readCurrentMetacoderEnabled(cwd);
+	const action = deriveAction(current, target);
+	writeEnabledFlag(cwd, target);
+	appendAudit(
+		cwd,
+		buildAuditEntry({ action, from: current, to: target, reason: opts.reason ?? null }),
+	);
+
+	const mode = getOutputMode(opts);
+	const auditPath = getAuditLogPath(cwd);
+	const payload = {
+		enabled: target,
+		changed: current !== target,
+		previous: current,
+		audit_path: auditPath,
+		reason: opts.reason ?? null,
+		note: "Harness hot-reloads guard-rules.local.json on the next file-watcher tick (~2 s).",
+	};
+	output(mode, payload, {
+		json: () => payload,
+		short: () =>
+			`${target ? "enabled" : "disabled"}${current === target ? " (no change)" : ""}`,
+		normal: () =>
+			renderToggleResult({ current, target, reason: opts.reason ?? null, auditPath }),
+	});
+}
+
+interface ToggleRenderArgs {
+	current: boolean;
+	target: boolean;
+	reason: string | null;
+	auditPath: string;
+}
+
+function renderToggleResult(args: ToggleRenderArgs): string {
+	const lines: string[] = [header("Metacoder")];
+	lines.push(kvLine("State", args.target ? c.green("enabled") : c.dim("disabled")));
+	if (args.current !== args.target) {
+		lines.push(
+			kvLine(
+				"Transition",
+				`${args.current ? "on" : "off"} → ${args.target ? "on" : "off"}`,
+			),
+		);
+	} else {
+		lines.push(kvLine("Transition", c.dim("no change")));
+	}
+	if (args.reason) lines.push(kvLine("Reason", args.reason));
+	lines.push(kvLine("Audit", c.dim(args.auditPath)));
+	lines.push("");
+	lines.push(
+		c.dim(
+			"Hot-reloads on the next file-watcher tick (~2 s). For active sessions, the overlay applies starting at the next UserPromptSubmit.",
+		),
+	);
+	return lines.join("\n");
+}
+
+export async function metacoderEnableCommand(opts: MetacoderToggleOptions): Promise<void> {
+	await applyToggle(process.cwd(), true, opts);
+}
+
+export async function metacoderDisableCommand(opts: MetacoderToggleOptions): Promise<void> {
+	await applyToggle(process.cwd(), false, opts);
+}
+
+export async function metacoderStatusCommand(opts: MetacoderStatusOptions): Promise<void> {
+	const cwd = process.cwd();
+	const enabled = readCurrentMetacoderEnabled(cwd);
+	const localRulesPath = getLocalRulesPath(cwd);
+	const auditPath = getAuditLogPath(cwd);
+	const recent = readRecentAudit(auditPath, 5);
+
+	const mode = getOutputMode(opts);
+	const payload = {
+		enabled,
+		local_rules_path: localRulesPath,
+		audit_path: auditPath,
+		recent_audit: recent,
+		notes: [
+			"Toggle: 'interlinked metacoder enable' / 'interlinked metacoder disable'",
+			"Auth: uses your Claude Code (claude -p) or Codex (codex exec) subscription — no API key needed",
+			"Latency: 5–30 s per prompt (Opus 4.7 max-effort / GPT-5.5 xhigh)",
+			"Design: docs/design/metacoding-agent-plan.md",
+		],
+	};
+	const ctx: StatusRenderContext = { enabled, localRulesPath, auditPath, recent };
+	output(mode, payload, {
+		json: () => payload,
+		short: () => (enabled ? "enabled" : "disabled"),
+		normal: () => renderStatusCompact(ctx),
+		full: () => renderStatusFull(ctx),
+	});
+}
+
+interface StatusRenderContext {
+	enabled: boolean;
+	localRulesPath: string;
+	auditPath: string;
+	recent: AuditEntry[];
+}
+
+/** Compact status — shows up to 3 recent audit rows. Default. */
+function renderStatusCompact(ctx: StatusRenderContext): string {
+	const COMPACT_AUDIT_LIMIT = 3;
+	return renderStatusBody(ctx, ctx.recent.slice(0, COMPACT_AUDIT_LIMIT));
+}
+
+/** Full status — shows every recent audit row currently in memory. */
+function renderStatusFull(ctx: StatusRenderContext): string {
+	return renderStatusBody(ctx, ctx.recent);
+}
+
+function renderStatusBody(ctx: StatusRenderContext, auditRows: AuditEntry[]): string {
+	const lines: string[] = [header("Metacoder")];
+	lines.push(kvLine("State", ctx.enabled ? c.green("enabled") : c.dim("disabled")));
+	lines.push(kvLine("Config", c.dim(ctx.localRulesPath)));
+	lines.push(kvLine("Audit log", c.dim(ctx.auditPath)));
+	lines.push("");
+	if (auditRows.length === 0) {
+		lines.push(c.dim("No audit entries yet. Toggle with 'interlinked metacoder enable|disable'."));
+	} else {
+		lines.push(c.dim(`Recent toggles (last ${auditRows.length}):`));
+		for (const entry of auditRows) {
+			const arrow = formatAuditArrow(entry);
+			const reason = entry.reason ? ` — ${entry.reason}` : "";
+			lines.push(c.dim(`  ${entry.ts}  ${entry.action}  ${arrow}${reason}`));
+		}
+	}
+	lines.push("");
+	lines.push(
+		c.dim("Latency: 5–30 s per UserPromptSubmit. Auth: Claude Code / Codex subscription (no API key)."),
+	);
+	lines.push(c.dim("Plan: docs/design/metacoding-agent-plan.md"));
+	return lines.join("\n");
+}
+
+/** Format the transition arrow for an audit row. Extracted so the
+ *  renderStatus loop stays flat and the nested-ternary linter rule
+ *  doesn't fire. */
+function formatAuditArrow(entry: AuditEntry): string {
+	if (entry.from === entry.to) return "•";
+	return entry.to ? "→ on" : "→ off";
+}
+
+function readRecentAudit(path: string, limit: number): AuditEntry[] {
+	if (!existsSync(path)) return [];
+	let raw: string;
+	try {
+		raw = readFileSync(path, "utf-8");
+	} catch (err) {
+		void err;
+		return [];
+	}
+	const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+	const tail = lines.slice(Math.max(0, lines.length - limit));
+	const entries: AuditEntry[] = [];
+	for (const line of tail) {
+		try {
+			entries.push(JSON.parse(line) as AuditEntry);
+		} catch (err) {
+			// Skip malformed lines — the audit log is append-only and a
+			// truncated last line during shutdown is non-fatal.
+			void err;
+		}
+	}
+	return entries.reverse();
+}
diff --git a/src/index.ts b/src/index.ts
index 03bf195..32aad92 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -640,6 +640,52 @@ scannerCmd
 		await scannerStatusCommand(opts);
 	});
 
+// ============================================================================
+// Metacoder — per-prompt overlay generator
+// ============================================================================
+// Mirrors the `interlinked scanner` toggle pattern: enable / disable / status.
+// The metacoder runs on every UserPromptSubmit and emits a session-scoped
+// overlay of guard rules via the user's Claude Code / Codex CLI subscription
+// (no API key). Heavyweight (5–30 s per prompt) so users may want it off.
+// Plan: docs/design/metacoding-agent-plan.md.
+
+const metacoderCmd = program
+	.command("metacoder")
+	.description("Per-prompt overlay generator — toggle, inspect, audit");
+
+metacoderCmd
+	.command("enable")
+	.description("Enable the per-prompt metacoder overlay generator")
+	.option("--reason <text>", "Why — recorded in metacoder.audit.jsonl")
+	.option("--json", "Machine-readable output")
+	.option("--short", "One-line summary")
+	.action(async (opts: OptionValues) => {
+		const { metacoderEnableCommand } = await import("./commands/metacoder.js");
+		await metacoderEnableCommand(opts);
+	});
+
+metacoderCmd
+	.command("disable")
+	.description("Disable the metacoder. The exact timestamp is recorded in the audit log.")
+	.option("--reason <text>", "Why — recorded in metacoder.audit.jsonl")
+	.option("--json", "Machine-readable output")
+	.option("--short", "One-line summary")
+	.action(async (opts: OptionValues) => {
+		const { metacoderDisableCommand } = await import("./commands/metacoder.js");
+		await metacoderDisableCommand(opts);
+	});
+
+metacoderCmd
+	.command("status")
+	.description("Show metacoder enable state + recent toggle audit")
+	.option("--json", "Machine-readable output")
+	.option("--short", "One-line summary")
+	.option("--full", "Detailed output (full audit log)")
+	.action(async (opts: OptionValues) => {
+		const { metacoderStatusCommand } = await import("./commands/metacoder.js");
+		await metacoderStatusCommand(opts);
+	});
+
 scannerCmd
 	.command("review")
 	.description(

From 0ec3c4110be108664c114d2d9ca2bbcb1cbbca6c Mon Sep 17 00:00:00 2001
From: QuentinCody <33259999+QuentinCody@users.noreply.github.com>
Date: Thu, 14 May 2026 13:06:44 -0400
Subject: [PATCH 6/6] fix: satisfy software-version fixture policy in metacoder
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The project's `software-version-fixtures-policy.test.ts` bans hardcoded
fast-moving model aliases (gpt-5.5, claude-opus-4-7, gemini-N, etc.) in
test files because they encode stale product knowledge. The escape
hatch is the `REAL_WORLD_VERSION_FIXTURE_OK` marker on the same line or
the line directly above, paired with a comment explaining why the real
name is the test contract.

The metacoder tests intentionally pin the exact model id — silent drift
to a different model would be a behavioral regression we want to catch.
Rephrased the describe/it block titles to drop the literal where it
wasn't load-bearing, and added marker comments above the two
assertions where the exact id IS the contract.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../metacoder/metacoder-client.test.ts        | 24 +++++++++++++------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/src/harness/metacoder/metacoder-client.test.ts b/src/harness/metacoder/metacoder-client.test.ts
index 7773bbf..3685444 100644
--- a/src/harness/metacoder/metacoder-client.test.ts
+++ b/src/harness/metacoder/metacoder-client.test.ts
@@ -211,15 +211,21 @@ describe("callMetacoder — payload assembly", () => {
 	});
 });
 
-describe("Codex (GPT-5.5) subprocess transport — exact CLI invocation pinned", () => {
+describe("Codex subprocess transport — exact CLI invocation pinned", () => {
 	// Plan §2.1 + user constraint: the metacoder uses the SAME tier as
 	// the coding agent AND reuses the developer's Codex CLI
 	// subscription (authenticated via `codex login`) — NO OpenAI API
 	// key. The reasoning_effort API value is `xhigh` (one word, no
-	// hyphen) per https://developers.openai.com/api/docs/models/gpt-5.5
-	// (verified 2026-05). Verified live by smoke-test: the `codex exec`
-	// startup banner echoed back "reasoning effort: xhigh", confirming
-	// the CLI accepts the `-c model_reasoning_effort=xhigh` override.
+	// hyphen) per the OpenAI developer docs (verified 2026-05).
+	// Verified live by smoke-test: the `codex exec` startup banner
+	// echoed back "reasoning effort: xhigh", confirming the CLI accepts
+	// the `-c model_reasoning_effort=xhigh` override.
+	//
+	// Why hardcoded model ids appear below: pinning the EXACT model
+	// identifier is the contract under test. A silent drift to a
+	// different model is a behavioral regression we want this test to
+	// catch. Each line is marked `REAL_WORLD_VERSION_FIXTURE_OK` per
+	// `software-version-fixtures-policy.test.ts`.
 
 	it("targets the codex CLI binary, not an HTTP endpoint", () => {
 		// Earlier versions of this transport went through
@@ -229,7 +235,10 @@ describe("Codex (GPT-5.5) subprocess transport — exact CLI invocation pinned",
 		expect(CODEX_BINARY).toBe("codex");
 	});
 
-	it("targets gpt-5.5", () => {
+	it("targets the documented CODEX_MODEL identifier", () => {
+		// Pinning the exact model id is the behavior under test —
+		// silent drift to another model is the regression we want to catch.
+		// REAL_WORLD_VERSION_FIXTURE_OK: source = OpenAI developer docs.
 		expect(CODEX_MODEL).toBe("gpt-5.5");
 	});
 
@@ -248,11 +257,12 @@ describe("Codex (GPT-5.5) subprocess transport — exact CLI invocation pinned",
 		expect(CODEX_REASONING_EFFORT_KEY).toBe("model_reasoning_effort");
 	});
 
-	it("buildCodexExecArgs includes -m gpt-5.5 and the xhigh effort override", () => {
+	it("buildCodexExecArgs includes -m for the model and the xhigh effort override", () => {
 		const args = buildCodexExecArgs("the prompt", "/tmp/out.txt");
 		expect(args[0]).toBe("exec");
 		const modelIdx = args.indexOf("-m");
 		expect(modelIdx).toBeGreaterThan(-1);
+		// REAL_WORLD_VERSION_FIXTURE_OK: model id is the contract under test.
 		expect(args[modelIdx + 1]).toBe("gpt-5.5");
 		expect(args).toContain("model_reasoning_effort=xhigh");
 	});