claude2codex 0.1.0

package/README.md

@@ -0,0 +1,62 @@
+# c2c-codex — Claude↔Codex Contract Bridge (MCP server)
+
+*[中文](./README.zh-CN.md)*
+
+Claude Code is the **architect/reviewer** (see `../CLAUDE.md`); Codex is the **implementer** (see `../AGENTS.md`). This MCP server is the courier between them: it turns Goal/Delta Contracts into Codex runs and returns the structured handoff for Claude to review. It is **language-agnostic** — all verification commands come from the contract's Success Conditions, never from this server.
+
+## How it works
+
+Each job spawns `codex app-server` (Codex's JSON-RPC interface, stdio/JSONL) and drives it:
+
+```
+initialize
+→ thread/start            (or thread/resume for rework)
+→ thread/goal/set         objective = the Goal Contract, distilled  ← this is /goal
+→ turn/start              input = the full rendered contract
+→ ... Codex's goal-continuation loop runs turns until the goal is achieved ...
+→ job done when goal status is terminal (complete / budget_limited),
+  or the thread goes quiet after a turn with the goal still active
+```
+
+Setting the thread goal is the programmatic equivalent of the `/goal` slash command in the Codex TUI: Codex audits its own work against the objective after each turn and keeps going ("Goal achieved" / "Goal unmet") until it passes or hits the token budget.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `codex_implement` | Start a job from a Goal Contract (`goal`, `constraints[]`, `success_conditions[]`, optional `token_budget`, `cwd`). Returns `job_id` immediately. |
+| `codex_status` | Poll a job: state, thread id, goal status/tokens, turn count, transcript tail. |
+| `codex_result` | Fetch a finished job: final message + parsed handoff (Changed Files / Validation / Success Conditions / Risks & Deviations). A missing section ⇒ `handoff.valid: false` — per CLAUDE.md that is itself a review failure. |
+| `codex_rework` | Resume the same Codex thread with a Delta Contract (`findings[]`, `failed_conditions[]`). The existing thread goal re-engages. |
+
+## Configuration (env vars)
+
+| Var | Default | Meaning |
+|---|---|---|
+| `CODEX_BIN` | `codex` | Codex executable |
+| `CODEX_ARGS` | `app-server` | Args (space-separated) |
+| `CODEX_CWD` | server cwd | Default working directory for jobs |
+| `CODEX_MODEL` | (codex default) | Model override passed to `thread/start` |
+| `CODEX_APPROVAL_POLICY` | `never` | Codex approval policy (autonomous worker) |
+| `CODEX_PERMISSIONS` | (unset) | Codex permissions profile passthrough |
+| `CODEX_JOB_TIMEOUT_MS` | `1800000` | Hard cap per job (30 min) |
+| `CODEX_QUIET_MS` | `30000` | Quiet window after a turn before declaring a still-active goal finished |
+| `GOAL_OBJECTIVE_MAX` | `2000` | Max length of the `thread/goal/set` objective string |
+
+## Run / test
+
+```sh
+bun install
+bun test          # e2e against test/mock-codex.ts (no real Codex needed)
+bunx tsc --noEmit # typecheck
+```
+
+Registered for Claude Code in `../.mcp.json`. The server itself runs on Bun (Node ≥ 22.18 also works — the TS is erasable-syntax only).
+
+## Status / caveats
+
+- **Verified live** against `codex` 0.144.6 (2026-07-19): `test/live-smoke.ts` drove a real contract through the MCP server — `thread/goal/set` accepted, goal tracked `tokensUsed` and went `active → complete`, Codex self-verified the success condition, and the structured handoff parsed valid. Also covered by `bun test` against `test/mock-codex.ts` (no real Codex or model spend needed).
+- Requires a reasonably current Codex CLI (`npm i -g @openai/codex@latest`). Note: a stale install can fail with an instant `zsh: killed` after a macOS update — reinstalling fixes it.
+- If Codex's goals feature is unavailable in a build ("goals feature is disabled"), `thread/goal/set` failure degrades the job gracefully to single-turn mode and notes it in the transcript.
+- Goals require a persisted thread; `thread/start` defaults are used (no ephemeral threads).
+- Server→client requests (approvals) are declined automatically — jobs run with `approvalPolicy: never`; tune `CODEX_PERMISSIONS` if Codex needs broader sandbox rights.

package/README.zh-CN.md

@@ -0,0 +1,62 @@
+# c2c-codex — Claude↔Codex 契约桥接器（MCP 服务器）
+
+*[English](./README.md)*
+
+Claude Code 是**架构师/审查者**（见 `../CLAUDE.md`）；Codex 是**实现者**（见 `../AGENTS.md`）。这个 MCP 服务器是两者之间的信使：它把 Goal/Delta Contract（目标/差量契约）转化为 Codex 的运行任务，并把结构化的交接结果返回给 Claude 审查。它**与具体语言无关**——所有验证命令都来自契约中的 Success Conditions（成功条件），而不是这个服务器本身。
+
+## 工作原理
+
+每个任务都会启动一个 `codex app-server`（Codex 的 JSON-RPC 接口，基于 stdio/JSONL）并驱动它：
+
+```
+initialize
+→ thread/start            （或 rework 时用 thread/resume）
+→ thread/goal/set         objective = 提炼后的 Goal Contract  ← 相当于 /goal
+→ turn/start               input = 完整渲染后的契约内容
+→ ... Codex 的目标持续循环会不断运行 turn，直到目标达成 ...
+→ 当目标状态终止（complete / budget_limited），
+  或线程在某次 turn 后陷入沉默但目标仍处于 active 状态时，任务结束
+```
+
+设置线程目标（thread goal）在编程层面等价于 Codex TUI 里的 `/goal` 斜杠命令：Codex 会在每次 turn 之后对照目标自我审核（"Goal achieved" / "Goal unmet"），并持续运行直到通过审核或达到 token 预算上限。
+
+## 工具列表
+
+| 工具 | 用途 |
+|---|---|
+| `codex_implement` | 依据 Goal Contract（`goal`、`constraints[]`、`success_conditions[]`，可选 `token_budget`、`cwd`）启动一个任务，立即返回 `job_id`。 |
+| `codex_status` | 查询任务状态：state、thread id、goal 状态/token 消耗、turn 计数、transcript 尾部内容。 |
+| `codex_result` | 获取已完成任务的结果：最终消息 + 解析出的交接内容（Changed Files / Validation / Success Conditions / Risks & Deviations）。缺失任何一部分 ⇒ `handoff.valid: false`——依据 CLAUDE.md，这本身就算审查失败。 |
+| `codex_rework` | 用 Delta Contract（`findings[]`、`failed_conditions[]`）恢复同一个 Codex 线程。原有的线程目标会重新生效。 |
+
+## 配置（环境变量）
+
+| 变量 | 默认值 | 含义 |
+|---|---|---|
+| `CODEX_BIN` | `codex` | Codex 可执行文件 |
+| `CODEX_ARGS` | `app-server` | 参数（空格分隔） |
+| `CODEX_CWD` | 服务器自身 cwd | 任务的默认工作目录 |
+| `CODEX_MODEL` | （Codex 默认值） | 传给 `thread/start` 的模型覆盖项 |
+| `CODEX_APPROVAL_POLICY` | `never` | Codex 审批策略（自主执行模式） |
+| `CODEX_PERMISSIONS` | （未设置） | Codex 权限配置透传 |
+| `CODEX_JOB_TIMEOUT_MS` | `1800000` | 单个任务的硬性超时上限（30 分钟） |
+| `CODEX_QUIET_MS` | `30000` | 一次 turn 结束后、判定"目标仍处于 active 但已完成"之前的静默等待时间 |
+| `GOAL_OBJECTIVE_MAX` | `2000` | `thread/goal/set` objective 字符串的最大长度 |
+
+## 运行 / 测试
+
+```sh
+bun install
+bun test          # 针对 test/mock-codex.ts 做端到端测试（不需要真实 Codex）
+bunx tsc --noEmit # 类型检查
+```
+
+已在 `../.mcp.json` 中为 Claude Code 注册。服务器本身运行在 Bun 上（Node ≥ 22.18 也可以——TS 代码只使用可擦除语法）。
+
+## 状态 / 注意事项
+
+- **已通过真实环境验证**：针对 `codex` 0.144.6（2026-07-19）——`test/live-smoke.ts` 驱动了一个真实契约走完整个 MCP 服务器流程：`thread/goal/set` 被接受，目标追踪了 `tokensUsed` 并经历 `active → complete`，Codex 自我验证了成功条件，交接内容解析有效。同时也被 `bun test`（基于 `test/mock-codex.ts`）覆盖，无需真实 Codex 或模型开销。
+- 需要较新版本的 Codex CLI（`npm i -g @openai/codex@latest`）。注意：macOS 更新后，过旧的安装可能会立即 `zsh: killed`，重新安装即可解决。
+- 如果某个构建版本中 Codex 的 goals 功能不可用（"goals feature is disabled"），`thread/goal/set` 失败会优雅降级为单轮（single-turn）模式，并在 transcript 中记录说明。
+- Goals 功能依赖持久化的线程；使用 `thread/start` 的默认设置（不使用临时线程）。
+- 服务器→客户端的请求（审批类）会被自动拒绝——任务以 `approvalPolicy: never` 运行；如果 Codex 需要更宽松的沙箱权限，可调整 `CODEX_PERMISSIONS`。

package/dist/server.js

@@ -0,0 +1,638 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// src/contracts.ts
+import { readFile } from "fs/promises";
+import { join } from "path";
+var PROTOCOL_INSTRUCTIONS = `## Protocol Instructions
+
+### Execution Rules
+- Implement exactly what the contract specifies. Do not decide or expand what to build.
+- Think before coding: surface confusion and tradeoffs instead of assuming.
+- Prefer the minimum code that solves the problem. Make surgical changes and do no extra work.
+- Follow the target project's declared toolchain. Add tests whenever a Success Condition requires them.
+
+### Self-Verification
+Before declaring completion:
+1. Run the project's own typecheck/build and test commands, plus every command named in the Success Conditions. All must pass.
+2. Walk through every Success Condition and confirm it is met. If one cannot be met, say so explicitly and do not declare completion.
+3. Re-read the Constraints and confirm none were violated, including all "Do not modify" lists.
+
+### Required Handoff
+End every task with exactly these sections:
+
+### Changed Files
+- path \u2014 one-line reason
+
+### Validation
+- Commands run and their results.
+
+### Success Conditions
+- [x]/[ ] Each condition from the contract, with evidence.
+
+### Risks & Deviations
+- Known risks, assumptions, and deviations, or "none".
+
+### Rework
+For a Delta Contract, fix only its review findings and failed Success Conditions. Do not revisit work that passed review. Repeat the full Self-Verification and Required Handoff.`;
+async function optionalAgentsInstructions(cwd) {
+  try {
+    return await readFile(join(cwd, "AGENTS.md"), "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return void 0;
+    throw error;
+  }
+}
+async function renderGoalContract(c, cwd = process.cwd()) {
+  const agents = await optionalAgentsInstructions(cwd);
+  const lines = [
+    PROTOCOL_INSTRUCTIONS,
+    ...agents ? ["", "## Project Instructions", "", agents.trim()] : [],
+    "",
+    "## Goal Contract",
+    "",
+    "### Goal",
+    c.goal.trim(),
+    "",
+    "### Constraints",
+    ...c.constraints.map((x) => `- ${x}`),
+    "",
+    "### Success Conditions",
+    ...c.success_conditions.map((x) => `- [ ] ${x}`)
+  ];
+  return lines.join("\n");
+}
+function renderDeltaContract(d) {
+  const lines = [
+    PROTOCOL_INSTRUCTIONS,
+    "",
+    "## Delta Contract",
+    "",
+    "### Findings",
+    ...d.findings.map((x) => `- ${x}`),
+    "",
+    "### Failed Success Conditions",
+    ...d.failed_conditions.map((x) => `- [ ] ${x}`),
+    "",
+    "### Constraints",
+    "- Original constraints still apply. Fix only the findings above; do not touch work that passed.",
+    ...(d.constraints ?? []).map((x) => `- ${x}`)
+  ];
+  return lines.join("\n");
+}
+function renderObjective(c, maxLen) {
+  const conditions = c.success_conditions.map((x) => `(${x})`).join(" ");
+  const text = `Fulfill this Goal Contract: ${c.goal.trim()} The goal is achieved only when every Success Condition is verified: ${conditions} and a structured handoff (Changed Files / Validation / Success Conditions / Risks & Deviations) has been delivered.`;
+  return text.length <= maxLen ? text : text.slice(0, maxLen - 1) + "\u2026";
+}
+var HANDOFF_SECTIONS = [
+  "Changed Files",
+  "Validation",
+  "Success Conditions",
+  "Risks & Deviations"
+];
+function parseHandoff(text) {
+  const sections = {};
+  const headingRe = /^#{2,4}\s+(.+?):?\s*$/gm;
+  const found = [];
+  let m;
+  while ((m = headingRe.exec(text)) !== null) {
+    found.push({ name: m[1].trim(), start: m.index, contentStart: m.index + m[0].length });
+  }
+  for (let i = 0; i < found.length; i++) {
+    const end = i + 1 < found.length ? found[i + 1].start : text.length;
+    const canonical = HANDOFF_SECTIONS.find(
+      (s) => s.toLowerCase() === found[i].name.toLowerCase()
+    );
+    if (canonical) sections[canonical] = text.slice(found[i].contentStart, end).trim();
+  }
+  const missing = HANDOFF_SECTIONS.filter((s) => !(s in sections));
+  return { valid: missing.length === 0, missing: [...missing], sections };
+}
+
+// src/jobs.ts
+import { randomUUID } from "crypto";
+
+// src/codex-client.ts
+import { spawn } from "child_process";
+import { createInterface } from "readline";
+var CodexAppServer = class {
+  proc;
+  nextId = 1;
+  pending = /* @__PURE__ */ new Map();
+  opts;
+  stderrTail = [];
+  exited = false;
+  constructor(opts) {
+    this.opts = opts;
+    this.proc = spawn(opts.bin, opts.args, {
+      cwd: opts.cwd,
+      env: { ...process.env, ...opts.env },
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    const rl = createInterface({ input: this.proc.stdout });
+    rl.on("line", (line) => this.handleLine(line));
+    const rlErr = createInterface({ input: this.proc.stderr });
+    rlErr.on("line", (line) => {
+      this.stderrTail.push(line);
+      if (this.stderrTail.length > 50) this.stderrTail.shift();
+      opts.onLog?.(line);
+    });
+    this.proc.on("exit", (code) => {
+      this.exited = true;
+      for (const [, p] of this.pending) {
+        clearTimeout(p.timer);
+        p.reject(new Error(`codex app-server exited (code ${code}). stderr: ${this.stderrTail.slice(-10).join(" | ")}`));
+      }
+      this.pending.clear();
+      opts.onExit?.(code);
+    });
+    this.proc.on("error", (err) => {
+      this.exited = true;
+      for (const [, p] of this.pending) {
+        clearTimeout(p.timer);
+        p.reject(new Error(`failed to spawn ${opts.bin}: ${err.message}`));
+      }
+      this.pending.clear();
+    });
+  }
+  handleLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      this.opts.onLog?.(`unparseable line from codex: ${trimmed.slice(0, 200)}`);
+      return;
+    }
+    if (msg.id !== void 0 && msg.method === void 0) {
+      const p = this.pending.get(msg.id);
+      if (!p) return;
+      this.pending.delete(msg.id);
+      clearTimeout(p.timer);
+      if (msg.error) {
+        p.reject(new Error(`${msg.error.code ?? ""} ${msg.error.message ?? JSON.stringify(msg.error)}`.trim()));
+      } else {
+        p.resolve(msg.result);
+      }
+    } else if (msg.id !== void 0 && msg.method !== void 0) {
+      this.opts.onLog?.(`declining server request: ${msg.method}`);
+      this.send({ id: msg.id, error: { code: -32601, message: `client does not handle ${msg.method}` } });
+    } else if (msg.method !== void 0) {
+      this.opts.onNotification?.(msg.method, msg.params);
+    }
+  }
+  send(obj) {
+    if (this.exited) return;
+    this.proc.stdin.write(JSON.stringify(obj) + "\n");
+  }
+  request(method, params, timeoutMs = 6e4) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`request ${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.send({ id, method, ...params !== void 0 ? { params } : {} });
+    });
+  }
+  notify(method, params) {
+    this.send({ method, ...params !== void 0 ? { params } : {} });
+  }
+  async initialize() {
+    const result = await this.request("initialize", {
+      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.1.0" },
+      capabilities: { experimentalApi: true }
+    });
+    this.notify("initialized", {});
+    return result;
+  }
+  kill() {
+    if (!this.exited) this.proc.kill("SIGTERM");
+  }
+};
+
+// src/jobs.ts
+var jobs = /* @__PURE__ */ new Map();
+function getJob(id) {
+  return jobs.get(id);
+}
+function startJob(opts) {
+  const job = {
+    id: randomUUID().slice(0, 8),
+    kind: opts.kind,
+    state: "starting",
+    goalSet: false,
+    turns: 0,
+    transcript: [],
+    startedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  jobs.set(job.id, job);
+  void runJob(job, opts).catch((err) => {
+    finish(job, "error", void 0, String(err?.message ?? err));
+  });
+  return job;
+}
+function log(job, kind, detail) {
+  job.transcript.push({ at: (/* @__PURE__ */ new Date()).toISOString(), kind, detail: detail.slice(0, 500) });
+  if (job.transcript.length > 200) job.transcript.splice(0, job.transcript.length - 200);
+}
+function finish(job, state, client, error) {
+  if (job.state === "done" || job.state === "error" || job.state === "timeout") return;
+  job.state = state;
+  job.error = error;
+  job.endedAt = (/* @__PURE__ */ new Date()).toISOString();
+  if (job.finalMessage) job.handoff = parseHandoff(job.finalMessage);
+  client?.kill();
+}
+function extractText(item) {
+  if (typeof item?.text === "string") return item.text;
+  if (typeof item?.message === "string") return item.message;
+  if (typeof item?.content === "string") return item.content;
+  if (Array.isArray(item?.content)) {
+    const parts = item.content.map((c) => typeof c === "string" ? c : c?.text).filter((x) => typeof x === "string");
+    if (parts.length) return parts.join("\n");
+  }
+  return void 0;
+}
+function extractGoal(params) {
+  const g = params?.goal ?? params ?? {};
+  return {
+    status: g.status,
+    tokensUsed: g.tokensUsed ?? g.tokens_used,
+    tokenBudget: g.tokenBudget ?? g.token_budget,
+    timeUsedSeconds: g.timeUsedSeconds ?? g.time_used_seconds
+  };
+}
+var TERMINAL_GOAL_STATUSES = /* @__PURE__ */ new Set(["complete", "budget_limited", "budgetLimited"]);
+async function runJob(job, opts) {
+  const cfg = opts.config;
+  let activeTurn = false;
+  let quietTimer;
+  let settle;
+  const doneSignal = new Promise((res) => settle = res);
+  const progress = (event, message) => opts.onProgress?.({ jobId: job.id, event, message });
+  const client = new CodexAppServer({
+    bin: cfg.bin,
+    args: cfg.args,
+    cwd: cfg.cwd,
+    onLog: (line) => log(job, "log", line),
+    onExit: (code) => {
+      if (job.state === "starting" || job.state === "running") {
+        finish(job, "error", void 0, `codex app-server exited early (code ${code})`);
+      }
+      settle();
+    },
+    onNotification: (method, params) => handleNotification(method, params)
+  });
+  function armQuietTimer() {
+    clearTimeout(quietTimer);
+    quietTimer = setTimeout(() => {
+      log(job, "quiet", `no goal continuation within ${cfg.quietMs}ms; treating turn as final`);
+      finish(job, "done", client);
+      settle();
+    }, cfg.quietMs);
+  }
+  function handleNotification(method, params) {
+    const p = params ?? {};
+    switch (method) {
+      case "turn/started": {
+        activeTurn = true;
+        job.turns += 1;
+        clearTimeout(quietTimer);
+        log(job, "turn", `turn ${job.turns} started`);
+        progress("turn_started", `turn ${job.turns} started`);
+        break;
+      }
+      case "item/completed": {
+        const item = p.item ?? p;
+        const type = String(item?.type ?? "item");
+        if (/agent.?message/i.test(type)) {
+          const text = extractText(item);
+          if (text) {
+            job.finalMessage = text;
+            log(job, "message", text.slice(0, 200));
+            progress("agent_message", text.slice(0, 200));
+          }
+        } else if (/command/i.test(type)) {
+          log(job, "command", String(item?.command ?? item?.detail ?? ""));
+        } else {
+          log(job, "item", type);
+        }
+        break;
+      }
+      case "thread/goal/updated": {
+        job.goal = extractGoal(p);
+        log(job, "goal", `status=${job.goal.status} tokensUsed=${job.goal.tokensUsed ?? "?"}`);
+        progress("goal_updated", `goal status=${job.goal.status ?? "unknown"}`);
+        if (job.goal.status && TERMINAL_GOAL_STATUSES.has(job.goal.status) && !activeTurn) {
+          finish(job, "done", client);
+          settle();
+        }
+        break;
+      }
+      case "turn/completed":
+      case "turn/failed": {
+        activeTurn = false;
+        const status = p.turn?.status ?? (method === "turn/failed" ? "failed" : "completed");
+        log(job, "turn", `turn ended (${status})`);
+        progress("turn_ended", `turn ended (${status})`);
+        void onTurnEnded();
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  async function onTurnEnded() {
+    if (!job.goalSet) {
+      finish(job, "done", client);
+      settle();
+      return;
+    }
+    if (job.goal?.status && TERMINAL_GOAL_STATUSES.has(job.goal.status)) {
+      finish(job, "done", client);
+      settle();
+      return;
+    }
+    try {
+      const res = await client.request("thread/goal/get", { threadId: job.threadId }, 15e3);
+      if (res?.goal) {
+        job.goal = extractGoal(res);
+        if (job.goal.status && TERMINAL_GOAL_STATUSES.has(job.goal.status)) {
+          finish(job, "done", client);
+          settle();
+          return;
+        }
+      }
+    } catch (err) {
+      log(job, "log", `thread/goal/get failed: ${err?.message ?? err}`);
+    }
+    if (!activeTurn) armQuietTimer();
+  }
+  const overallTimer = setTimeout(() => {
+    finish(job, "timeout", client, `job exceeded ${cfg.jobTimeoutMs}ms`);
+    settle();
+  }, cfg.jobTimeoutMs);
+  try {
+    await client.initialize();
+    const threadParams = {
+      cwd: cfg.cwd,
+      approvalPolicy: cfg.approvalPolicy,
+      ...cfg.model ? { model: cfg.model } : {},
+      ...cfg.permissions ? { permissions: cfg.permissions } : {},
+      ...opts.reasoningEffort ? { config: { model_reasoning_effort: opts.reasoningEffort } } : {}
+    };
+    let threadRes;
+    if (opts.resumeThreadId) {
+      threadRes = await client.request("thread/resume", { threadId: opts.resumeThreadId, ...threadParams });
+      job.threadId = threadRes?.thread?.id ?? opts.resumeThreadId;
+      job.goalSet = true;
+    } else {
+      threadRes = await client.request("thread/start", { ...threadParams, sessionStartSource: "startup" });
+      job.threadId = threadRes?.thread?.id ?? threadRes?.id;
+    }
+    if (!job.threadId) throw new Error(`could not determine thread id from ${JSON.stringify(threadRes).slice(0, 300)}`);
+    log(job, "thread", `thread ${job.threadId} ${opts.resumeThreadId ? "resumed" : "started"}`);
+    if (opts.objective) {
+      try {
+        const goalRes = await client.request("thread/goal/set", {
+          threadId: job.threadId,
+          objective: opts.objective,
+          ...opts.tokenBudget ? { tokenBudget: opts.tokenBudget } : {}
+        });
+        job.goalSet = true;
+        job.goal = extractGoal(goalRes);
+        log(job, "goal", `goal set (status=${job.goal.status ?? "active"})`);
+        progress("goal_updated", `goal status=${job.goal.status ?? "active"}`);
+      } catch (err) {
+        log(job, "goal", `thread/goal/set failed (${err?.message ?? err}); continuing without goal loop`);
+        job.goalSet = false;
+      }
+    }
+    job.state = "running";
+    await client.request("turn/start", {
+      threadId: job.threadId,
+      input: [{ type: "text", text: opts.prompt }],
+      ...opts.reasoningEffort ? { effort: opts.reasoningEffort } : {}
+    });
+    await doneSignal;
+  } finally {
+    clearTimeout(overallTimer);
+    clearTimeout(quietTimer);
+    client.kill();
+  }
+}
+
+// src/config.ts
+async function readCodexConfig(cfg) {
+  const client = new CodexAppServer({ bin: cfg.bin, args: cfg.args, cwd: cfg.cwd });
+  try {
+    const initialized = await client.initialize();
+    const result = await client.request("config/read", {}, 15e3);
+    const current = result?.config ?? result ?? {};
+    return {
+      model: current.model ?? cfg.model ?? null,
+      default_effort: current.model_reasoning_effort ?? current.reasoning_effort ?? null,
+      version: initialized?.userAgent ?? initialized?.user_agent ?? "unknown",
+      config: current
+    };
+  } finally {
+    client.kill();
+  }
+}
+
+// src/server.ts
+function envInt(name, fallback) {
+  const v = process.env[name];
+  const n = v ? Number.parseInt(v, 10) : NaN;
+  return Number.isFinite(n) ? n : fallback;
+}
+function config(cwd) {
+  return {
+    bin: process.env.CODEX_BIN ?? "codex",
+    args: (process.env.CODEX_ARGS ?? "app-server").split(" ").filter(Boolean),
+    cwd: cwd ?? process.env.CODEX_CWD ?? process.cwd(),
+    model: process.env.CODEX_MODEL || void 0,
+    approvalPolicy: process.env.CODEX_APPROVAL_POLICY ?? "never",
+    permissions: process.env.CODEX_PERMISSIONS || void 0,
+    jobTimeoutMs: envInt("CODEX_JOB_TIMEOUT_MS", 18e5),
+    quietMs: envInt("CODEX_QUIET_MS", 3e4)
+  };
+}
+var OBJECTIVE_MAX = envInt("GOAL_OBJECTIVE_MAX", 2e3);
+function jobSummary(job, transcriptTail = 15) {
+  return {
+    job_id: job.id,
+    kind: job.kind,
+    state: job.state,
+    thread_id: job.threadId ?? null,
+    goal: job.goal ?? null,
+    turns: job.turns,
+    started_at: job.startedAt,
+    ended_at: job.endedAt ?? null,
+    error: job.error ?? null,
+    transcript_tail: job.transcript.slice(-transcriptTail)
+  };
+}
+function textResult(obj, isError = false) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(obj, null, 2) }],
+    isError
+  };
+}
+var server = new McpServer({ name: "c2c-codex", version: "0.1.0" });
+var reasoningEffort = z.enum(["low", "medium", "high", "xhigh", "max", "ultra"]);
+function progressReporter() {
+  let sequence = 0;
+  return (event) => {
+    sequence += 1;
+    void server.server.notification({
+      method: "notifications/progress",
+      params: {
+        progressToken: event.jobId,
+        progress: sequence,
+        message: JSON.stringify(event)
+      }
+    }).catch(() => void 0);
+  };
+}
+server.registerTool(
+  "codex_implement",
+  {
+    title: "Delegate a Goal Contract to Codex",
+    description: "Start a Codex implementation job for a Goal Contract. Sets the contract as a Codex thread goal (the /goal loop keeps Codex iterating until the objective is achieved or the token budget is hit) and sends the full contract as the first turn. Returns a job_id immediately; poll codex_status, then fetch codex_result when done. Language-agnostic: verification commands come from the contract's Success Conditions, not from this server.",
+    inputSchema: {
+      goal: z.string().min(1).describe("What the code must do when this task is done."),
+      constraints: z.array(z.string()).describe("Technical boundaries: files to touch, patterns to follow, 'Do not modify' lists."),
+      success_conditions: z.array(z.string()).min(1).describe("Checkable criteria proving the goal is met. At least one must be a runnable command/test."),
+      token_budget: z.number().int().positive().optional().describe("Optional token budget for the Codex goal loop (thread/goal/set tokenBudget)."),
+      cwd: z.string().optional().describe("Working directory for Codex. Defaults to the project directory."),
+      reasoning_effort: reasoningEffort.optional().describe("Optional Codex reasoning effort; omitted uses the Codex default.")
+    }
+  },
+  async (input) => {
+    const contract = {
+      goal: input.goal,
+      constraints: input.constraints,
+      success_conditions: input.success_conditions
+    };
+    const jobConfig = config(input.cwd);
+    const job = startJob({
+      kind: "implement",
+      prompt: await renderGoalContract(contract, jobConfig.cwd),
+      objective: renderObjective(contract, OBJECTIVE_MAX),
+      tokenBudget: input.token_budget,
+      config: jobConfig,
+      reasoningEffort: input.reasoning_effort,
+      onProgress: progressReporter()
+    });
+    return textResult({
+      job_id: job.id,
+      state: job.state,
+      note: "Job started. Poll codex_status until state is 'done', then call codex_result."
+    });
+  }
+);
+server.registerTool(
+  "codex_rework",
+  {
+    title: "Send a Delta Contract to Codex",
+    description: "Resume the Codex thread from a previous implement job and hand it a Delta Contract (review findings + failed success conditions). The existing thread goal re-engages, so the /goal loop continues until the objective passes. Returns a new job_id.",
+    inputSchema: {
+      job_id: z.string().optional().describe("The original implement job's id (preferred; resolves the thread to resume)."),
+      thread_id: z.string().optional().describe("Codex thread id, if the job registry is gone (e.g. after a restart)."),
+      findings: z.array(z.string()).min(1).describe("What is wrong, with file/line references."),
+      failed_conditions: z.array(z.string()).describe("The specific Success Conditions from the original contract that did not pass."),
+      constraints: z.array(z.string()).optional().describe("Additional constraints beyond the originals."),
+      cwd: z.string().optional().describe("Working directory for Codex. Defaults to the project directory."),
+      reasoning_effort: reasoningEffort.optional().describe("Optional Codex reasoning effort; omitted uses the Codex default.")
+    }
+  },
+  async (input) => {
+    let threadId = input.thread_id;
+    if (!threadId && input.job_id) {
+      const prev = getJob(input.job_id);
+      if (!prev) return textResult({ error: `unknown job_id ${input.job_id}` }, true);
+      threadId = prev.threadId;
+    }
+    if (!threadId) {
+      return textResult({ error: "provide job_id (of the implement job) or thread_id" }, true);
+    }
+    const job = startJob({
+      kind: "rework",
+      prompt: renderDeltaContract({
+        findings: input.findings,
+        failed_conditions: input.failed_conditions,
+        constraints: input.constraints
+      }),
+      resumeThreadId: threadId,
+      config: config(input.cwd),
+      reasoningEffort: input.reasoning_effort,
+      onProgress: progressReporter()
+    });
+    return textResult({
+      job_id: job.id,
+      resumed_thread_id: threadId,
+      state: job.state,
+      note: "Rework job started. Poll codex_status until state is 'done', then call codex_result."
+    });
+  }
+);
+server.registerTool(
+  "codex_config",
+  {
+    title: "Read current Codex configuration",
+    description: "Read-only view of the Codex CLI model, default reasoning effort, version, and current configuration.",
+    inputSchema: {
+      cwd: z.string().optional().describe("Directory whose Codex configuration should be resolved.")
+    },
+    annotations: { readOnlyHint: true }
+  },
+  async (input) => textResult(await readCodexConfig(config(input.cwd)))
+);
+server.registerTool(
+  "codex_status",
+  {
+    title: "Check a Codex job",
+    description: "Status of a running or finished Codex job: state, thread id, goal state (status/tokens), turn count, and a tail of the activity transcript.",
+    inputSchema: {
+      job_id: z.string().describe("Job id returned by codex_implement or codex_rework.")
+    }
+  },
+  async (input) => {
+    const job = getJob(input.job_id);
+    if (!job) return textResult({ error: `unknown job_id ${input.job_id}` }, true);
+    return textResult(jobSummary(job));
+  }
+);
+server.registerTool(
+  "codex_result",
+  {
+    title: "Fetch a finished Codex job's handoff",
+    description: "Final result of a finished job: Codex's final message, the parsed structured handoff (Changed Files / Validation / Success Conditions / Risks & Deviations \u2014 a missing section is itself a review failure), and final goal state. Errors if the job is still running.",
+    inputSchema: {
+      job_id: z.string().describe("Job id returned by codex_implement or codex_rework.")
+    }
+  },
+  async (input) => {
+    const job = getJob(input.job_id);
+    if (!job) return textResult({ error: `unknown job_id ${input.job_id}` }, true);
+    if (job.state === "starting" || job.state === "running") {
+      return textResult({ error: `job ${job.id} is still ${job.state}; poll codex_status` }, true);
+    }
+    return textResult({
+      ...jobSummary(job, 5),
+      final_message: job.finalMessage ?? null,
+      handoff: job.handoff ?? null
+    });
+  }
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "claude2codex",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server bridging Claude (architect/reviewer) and Codex (implementer) via Goal/Delta Contracts and Codex's thread-goal loop.",
+  "bin": {
+    "claude2codex": "dist/server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "mcp",
+    "codex",
+    "claude",
+    "ai-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PrestoOverture/c2c.git",
+    "directory": "mcp"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "bun src/server.ts",
+    "build": "tsup",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "bun-types": "^1.3.14",
+    "tsup": "^8.5.0",
+    "typescript": "^7.0.2"
+  }
+}