claude2codex 0.3.0 → 0.3.2

package/PATTERNS.md

@@ -73,6 +73,27 @@ And the meta-rule for the handoff: **require it in the contract.** Every contrac
 
 A missing or incomplete handoff is itself a review failure — you never have to argue about it, because it was a success condition.
 
+## The objective budget: your success conditions have a character limit
+
+The contract you send and the objective the goal loop audits are **not the same string**. `codex_implement` renders a compact objective from your `goal` plus every `success_condition` and sets it via `thread/goal/set`. That objective — not the full contract prompt — is what Codex's `/goal` loop checks before declaring the goal achieved. Constraints and context files never reach it; they live only in the turn prompt.
+
+It has a hard budget: `GOAL_OBJECTIVE_MAX`, default **2000 characters**, of which ~213 are fixed rendering boilerplate. The remaining ~1787 are your goal text plus the concatenation of every success condition.
+
+Two consequences:
+
+- **Prose burns the budget fast.** A ten-condition contract of ordinary English sentences lands around 1700–2000 characters. The contract that added this very check measured 1987/2000 on its first draft — 13 characters of margin, entirely by accident.
+- **Measure before you send.** `codex_estimate` reports `objective_chars`, `objective_max_chars`, and `objective_over_limit` without creating a job. Over-limit calls to `codex_implement` are rejected at submit time — no job, no process, no tokens spent — with the actual count in the error.
+
+Write success conditions as assertions, not paragraphs:
+
+```markdown
+Bad  (124 chars): The implementation should make sure that whenever a contract
+                  exceeds the configured limit, the tool refuses to create a job.
+Good  (76 chars): Over-limit contracts return isError and create no job (state dir unchanged).
+```
+
+If a task genuinely needs a longer objective, raise `GOAL_OBJECTIVE_MAX` deliberately. The usual right answer is that ten crisp conditions beat six verbose ones — and the crisp ones review better anyway.
+
 ## Review: never trust, always re-run
 
 The handoff says `bun test` passed. Run `bun test` anyway. In this repo's run every handoff happened to be truthful — and that is exactly what you can't assume, because the day one isn't, the re-run is your only defense. The review loop that worked:

package/PATTERNS.zh-CN.md

@@ -72,6 +72,27 @@ codex_implement 必须支持声明对先前 job 的依赖:被依赖的 job 成
 
 缺失或不完整的 handoff 本身就是审查失败——你永远不需要为此争论,因为它就是一条成功条件。
 
+## objective 预算:你的 Success Conditions 有字符上限
+
+你发出去的合同,和 goal loop 实际审的 objective,**不是同一个字符串**。`codex_implement` 会从 `goal` 加上每一条 `success_condition` 渲染出一个精简的 objective,通过 `thread/goal/set` 设进去。Codex 的 `/goal` 循环在宣布目标达成前,审的是这个 objective,而不是完整的合同 prompt。Constraints 和 context files 根本进不去 —— 它们只存在于 turn prompt 里。
+
+它有一条硬预算:`GOAL_OBJECTIVE_MAX`,默认 **2000 字符**,其中约 213 是固定的渲染样板。剩下约 1787 字符由你的 goal 正文和所有 success conditions 拼接而成。
+
+两个后果:
+
+- **散文最烧预算。** 十条普通英文句子写成的 success conditions,落点大约在 1700–2000 字符。加入这条检查的那份合同,初稿实测 1987/2000 —— 只剩 13 字符余量,纯属侥幸。
+- **发之前先量。** `codex_estimate` 会返回 `objective_chars`、`objective_max_chars`、`objective_over_limit`,且不创建 job。超限的 `codex_implement` 调用会在提交时被拒 —— 不建 job、不起进程、不烧 token —— 错误里直接给出实际字符数。
+
+Success conditions 要写成断言,不要写成段落:
+
+```markdown
+差(124 字符):The implementation should make sure that whenever a contract
+              exceeds the configured limit, the tool refuses to create a job.
+好( 76 字符):Over-limit contracts return isError and create no job (state dir unchanged).
+```
+
+如果某个任务确实需要更长的 objective,那就有意识地调高 `GOAL_OBJECTIVE_MAX`。但通常正确的答案是:十条精悍的条件胜过六条啰嗦的 —— 而且精悍的那种审查起来也更省事。
+
 ## 审查:永不轻信,永远重跑
 
 handoff 说 `bun test` 过了。你还是要自己跑一遍 `bun test`。在本仓库的实战中,每一份 handoff 碰巧都是诚实的——而这恰恰是你不能假设的事,因为哪天有一份不诚实,你的重跑就是唯一的防线。行之有效的审查循环:

package/README.md

@@ -4,14 +4,23 @@ An MCP server that lets Claude Code delegate implementation work to OpenAI Codex
 
 *[中文版](./README.zh-CN.md)*
 
-## The Idea
+## Demo
 
-Software development has distinct roles: **planning** what to build, **building** it, and **reviewing** the result. This project splits those roles between two AI agents:
+One real contract round-trip, recorded live: Claude drafts the Goal Contract, `codex_estimate` prices it, Codex implements under its goal loop while `codex_status` streams progress, and Claude independently re-verifies the handoff.
 
-- **Claude Code** — the architect and reviewer. Plans the work, writes specifications, reviews results.
-- **OpenAI Codex** — the implementer. Receives specifications, writes code, runs tests, reports back.
+![c2c demo — a full Claude→Codex contract round-trip](./demo/demo.gif)
 
-You (the user) are the **commander** — you decide what to build and give final approval. Claude drafts the plan, Codex executes it, Claude verifies the output.
+*Real Codex run (13k tokens, 50s), waits compressed. Replay in your terminal: `asciinema play demo/demo.cast`*
+
+## Why
+
+In 2025, AI-assisted coding meant writing detailed prompts that told the model *how* to implement things — which files to edit, what patterns to follow, sometimes nearly pseudocode. The engineer was a director; the AI was a typist that needed constant guidance.
+
+That has changed. In 2026, models are [strong enough at implementation](https://www.anthropic.com/institute/recursive-self-improvement) that micromanaging the how is no longer the best use of a human's time. The bottleneck has shifted: when implementation is cheap, the expensive mistakes are **defining the wrong problem** and **failing to catch a bad result**. Getting the implementation steps right matters far less than getting the goal right.
+
+This is why Goal Contracts are structured the way they are. They don't explain how to write the code — they define **what the code must do** (the Goal) and **how to prove it worked** (Success Conditions). The engineer's role becomes problem definition, context provision, and verification — the same things that make a good engineering manager effective at delegation.
+
+This project is built on that premise: split planning and review (where human judgment still dominates) from implementation (where models now excel), and connect them with a contract format that forces clarity on the parts that matter most.
 
 ```mermaid
 flowchart LR
@@ -22,6 +31,10 @@ flowchart LR
     Claude -.->|Delta Contract if review fails| Codex
 ```
 
+- **You** — decide what to build and give final approval.
+- **Claude Code** — the architect and reviewer. Defines the problem, writes the contract, verifies the result.
+- **OpenAI Codex** — the implementer. Receives the contract, writes code, runs tests, reports back.
+
 ## What is a Goal Contract?
 
 A Goal Contract is a structured specification that tells Codex *exactly* what to build. It has three parts:
@@ -82,15 +95,17 @@ flowchart TD
 
 ## Three-Layer Prompt Architecture
 
-When claude2codex sends work to Codex, the prompt is assembled from three layers:
+The prompt Codex works from is assembled from three layers, but only two of them come from claude2codex:
 
 1. **Protocol layer** (embedded in the MCP server) — universal rules: how to self-verify work, how to format the handoff, how to handle rework. These never change regardless of project.
 
-2. **Project layer** (optional `AGENTS.md` in the working directory) — project-specific coding conventions, toolchain instructions, architectural constraints. Injected automatically when present.
+2. **Project layer** (`AGENTS.md`) — project-specific coding conventions, toolchain instructions, architectural constraints. **Loaded by Codex itself, not by this server.** Codex discovers `AGENTS.md` files across the working directory's repository tree (plus `AGENTS.override.md`) and places them in its instructions layer, subject to its own `project_doc_max_bytes` budget. claude2codex used to inject the file a second time and no longer does.
 
 3. **Task layer** (the Goal/Delta Contract itself) — the specific work to be done this time.
 
-This separation means the MCP server works out of the box (layer 1 is always there), benefits from project context when available (layer 2), and carries the unique task specification (layer 3).
+This separation means the MCP server works out of the box (layer 1 is always there), inherits whatever project context Codex already loads (layer 2), and carries the unique task specification (layer 3).
+
+Note that the contract prompt and the **thread-goal objective** are different strings. The objective — rendered from `goal` plus every `success_condition` — is what Codex's `/goal` loop audits before declaring the goal achieved, and it has its own `GOAL_OBJECTIVE_MAX` budget. See [PATTERNS.md](PATTERNS.md#the-objective-budget-your-success-conditions-have-a-character-limit).
 
 ## Installation
 
@@ -115,6 +130,22 @@ Add to your Claude Code MCP settings:
 }
 ```
 
+### Skill (optional)
+
+The package includes a Claude Code Skill that teaches Claude the full contract workflow — drafting Goal Contracts, delegating to Codex, reviewing handoffs, and reworking failures. Install it to use `/c2c` from any project:
+
+```sh
+mkdir -p ~/.claude/skills
+cp "$(npm root -g)/claude2codex/c2c.skill.md" ~/.claude/skills/c2c.md
+```
+
+Or download directly:
+
+```sh
+mkdir -p ~/.claude/skills
+curl -fsSL https://raw.githubusercontent.com/PrestoOverture/c2c/main/c2c.skill.md -o ~/.claude/skills/c2c.md
+```
+
 ## Tools Provided
 
 | Tool | Description |
@@ -123,7 +154,7 @@ Add to your Claude Code MCP settings:
 | `codex_status` | Check job progress: state, queue position, dependency, turns, goal status, token usage, time since last activity, transcript. |
 | `codex_result` | Fetch the finished job's structured handoff. |
 | `codex_rework` | Resume the Codex thread with a Delta Contract (also accepts `context_files`). |
-| `codex_estimate` | Read-only pre-job cost estimate: rendered-prompt size plus token statistics from your local completed jobs. |
+| `codex_estimate` | Read-only pre-job cost estimate: rendered-prompt size, thread-goal objective size against `GOAL_OBJECTIVE_MAX`, plus token statistics from your local completed jobs. |
 | `codex_config` | Read-only view of Codex's current model, version, and settings. |
 
 Jobs are persisted (`C2C_STATE_DIR`), so status, results, and rework survive server restarts. Jobs beyond the concurrency cap queue FIFO; a stall watchdog reports when a running job stops making progress. See [PATTERNS.md](./PATTERNS.md) for field-tested guidance on writing contracts that pass review on the first try.
@@ -151,7 +182,7 @@ Codex then enters its goal-continuation loop: after each turn, it checks "did I
 | `CODEX_PERMISSIONS` | Unset | Permissions profile passed to Codex |
 | `CODEX_JOB_TIMEOUT_MS` | `1800000` | Maximum job duration (30 min) |
 | `CODEX_QUIET_MS` | `30000` | Quiet period before treating an active goal as finished |
-| `GOAL_OBJECTIVE_MAX` | `2000` | Maximum goal-objective string length |
+| `GOAL_OBJECTIVE_MAX` | `2000` | Maximum rendered goal-objective length; `codex_implement` rejects over-limit contracts at submit time |
 | `C2C_STATE_DIR` | `~/.claude2codex/jobs` | Persistent job registry (atomic per-job JSON files) |
 | `C2C_LOG_LEVEL` | `info` | Structured JSON logs on stderr: `silent`, `error`, `info`, `debug` |
 | `C2C_RETRIES` | `1` | Automatic retries for process failures before the first turn starts |

package/README.zh-CN.md

@@ -4,14 +4,23 @@
 
 *[English](./README.md)*
 
-## 核心理念
+## 演示
 
-软件开发有不同的角色：**规划**做什么、**动手**写代码、**审查**结果。本项目把这些角色分配给两个 AI 智能体：
+一次完整的workflow实践过程：Claude 起草 Goal Contract，`codex_estimate` 预估成本，Codex 在 goal loop 下自主实现（`codex_status` 实时流式进度），最后 Claude 独立复核 handoff。
 
-- **Claude Code** — 架构师和审查者。制定计划，撰写规格说明，审查产出。
-- **OpenAI Codex** — 实现者。接收规格说明，编写代码，运行测试，报告结果。
+![c2c 演示 — 完整的 Claude→Codex 契约往返](./demo/demo.gif)
 
-你（用户）是**指挥官** — 决定做什么并给最终批准。Claude 起草方案，Codex 执行，Claude 核验产出。
+*Codex 运行（13k tokens，50 秒），等待时间已压缩。终端回放：`asciinema play demo/demo.cast`*
+
+## 为什么做这个项目
+
+2025 年，AI 辅助编程的主流方式是写详细的 prompt 告诉模型*怎么*实现——改哪些文件、用什么模式、有时候几乎是伪代码。工程师是导演，AI 是需要不断指导的执行者。
+
+这已经变了。2026 年，模型的[实现能力已经足够强](https://www.anthropic.com/institute/recursive-self-improvement)，事无巨细地指挥"怎么写"不再是人最好的时间投入方式。瓶颈转移了：当实现变得廉价，真正昂贵的错误是**定义了错误的问题**和**没有验收出坏的结果**。把实现步骤写对，远不如把目标定义对重要。
+
+这就是为什么 Goal Contract 被设计成这样。它不解释怎么写代码——它定义**代码必须做到什么**（Goal）和**怎么证明做对了**（Success Conditions）。工程师的角色变成了问题定义、上下文补充和验收——和一个好的工程管理者委派任务时做的事情一样。
+
+这个项目建立在这个前提上：把规划和审查（人的判断力仍然占主导）与实现（模型已经足够强）分开，用一种契约格式把它们连接起来，迫使工程师在最重要的部分(问题定义和验收标准)上做到清晰。
 
 ```mermaid
 flowchart LR
@@ -22,6 +31,10 @@ flowchart LR
     Claude -.->|Delta Contract 修正| Codex
 ```
 
+- **你** — 决定做什么，给最终批准。
+- **Claude Code** — 架构师和审查者。定义问题，撰写契约，验证结果。
+- **OpenAI Codex** — 实现者。接收契约，编写代码，运行测试，报告结果。
+
 ## 什么是 Goal Contract（目标契约）？
 
 Goal Contract 是一份结构化规格说明，精确告诉 Codex **要做什么**。它由三部分组成：
@@ -82,15 +95,17 @@ flowchart TD
 
 ## 三层 Prompt 架构
 
-claude2codex 向 Codex 发送任务时，prompt 由三层组装而成：
+Codex 最终工作时的 prompt 由三层组成，但只有两层来自 claude2codex：
 
 1. **协议层**（内嵌在 MCP 服务器中）— 通用规则：如何自我验证、如何格式化交接报告、如何处理返工。无论什么项目都一样。
 
-2. **项目层**（可选，工作目录中的 `AGENTS.md`）— 项目特定的编码规范、工具链说明、架构约束。存在时自动注入。
+2. **项目层**（`AGENTS.md`）— 项目特定的编码规范、工具链说明、架构约束。**由 Codex 自己加载，不是本服务器注入的。** Codex 会在工作目录所属的仓库树中查找 `AGENTS.md`（以及 `AGENTS.override.md`），放进它自己的 instructions 层，并受其 `project_doc_max_bytes` 预算约束。claude2codex 过去会重复注入一遍，现已移除。
 
 3. **任务层**（Goal/Delta Contract 本身）— 这次要做的具体工作。
 
-这种分离意味着：MCP 服务器开箱即用（第 1 层始终存在），有项目上下文时更好（第 2 层），每次任务都有独特的规格说明（第 3 层）。
+这种分离意味着：MCP 服务器开箱即用（第 1 层始终存在），直接继承 Codex 已经加载的项目上下文（第 2 层），每次任务都有独特的规格说明（第 3 层）。
+
+注意：合同 prompt 和 **thread-goal objective** 是两个不同的字符串。objective 由 `goal` 加上每一条 `success_condition` 渲染而成，是 Codex `/goal` 循环在宣布目标达成前实际审查的对象，并有自己的 `GOAL_OBJECTIVE_MAX` 预算。详见 [PATTERNS.zh-CN.md](PATTERNS.zh-CN.md#objective-预算你的-success-conditions-有字符上限)。
 
 ## 安装
 
@@ -115,6 +130,22 @@ npx claude2codex
 }
 ```
 
+### Skill（可选）
+
+包内附带一个 Claude Code Skill，教 Claude 完整的契约工作流——起草 Goal Contract、委派给 Codex、审查 handoff、失败时返工。安装后可在任何项目中使用 `/c2c`：
+
+```sh
+mkdir -p ~/.claude/skills
+cp "$(npm root -g)/claude2codex/c2c.skill.md" ~/.claude/skills/c2c.md
+```
+
+或直接下载：
+
+```sh
+mkdir -p ~/.claude/skills
+curl -fsSL https://raw.githubusercontent.com/PrestoOverture/c2c/main/c2c.skill.md -o ~/.claude/skills/c2c.md
+```
+
 ## 提供的工具
 
 | 工具 | 说明 |
@@ -123,7 +154,7 @@ npx claude2codex
 | `codex_status` | 查看任务进度：状态、队列位置、依赖、轮次、目标状态、token 用量、距上次活动的时间、活动记录。 |
 | `codex_result` | 获取已完成任务的结构化交接报告。 |
 | `codex_rework` | 用 Delta Contract 恢复 Codex 线程进行返工（同样支持 `context_files`）。 |
-| `codex_estimate` | 只读的任务前成本预估：渲染后的 prompt 规模 + 本机已完成任务的 token 统计。 |
+| `codex_estimate` | 只读的任务前成本预估：渲染后的 prompt 规模、thread-goal objective 相对 `GOAL_OBJECTIVE_MAX` 的规模，以及本机已完成任务的 token 统计。 |
 | `codex_config` | 只读查看 Codex 当前模型、版本和配置。 |
 
 任务会持久化（`C2C_STATE_DIR`），因此状态查询、结果获取和返工在 server 重启后依然可用。超出并发上限的任务按 FIFO 排队；停滞看门狗会在运行中的任务失去进展时主动上报。关于如何写出"一次过审"的合同，参见实战指南 [PATTERNS.zh-CN.md](./PATTERNS.zh-CN.md)。
@@ -151,7 +182,7 @@ npx claude2codex
 | `CODEX_PERMISSIONS` | 未设置 | 权限配置透传 |
 | `CODEX_JOB_TIMEOUT_MS` | `1800000` | 单任务最大时长（30 分钟） |
 | `CODEX_QUIET_MS` | `30000` | 判定活跃目标已完成前的静默等待时间 |
-| `GOAL_OBJECTIVE_MAX` | `2000` | 目标字符串最大长度 |
+| `GOAL_OBJECTIVE_MAX` | `2000` | 渲染后 goal-objective 的最大长度；超限的合同会被 `codex_implement` 在提交时拒绝 |
 | `C2C_STATE_DIR` | `~/.claude2codex/jobs` | 持久化任务注册表（每任务一个原子写入的 JSON 文件） |
 | `C2C_LOG_LEVEL` | `info` | stderr 上的结构化 JSON 日志：`silent`、`error`、`info`、`debug` |
 | `C2C_RETRIES` | `1` | 首个 turn 开始前的进程故障自动重试次数 |

package/c2c.skill.md

@@ -0,0 +1,58 @@
+---
+name: c2c
+description: Delegate implementation to Codex via Goal Contracts. Draft, send, poll, review, rework.
+trigger: When the user wants to delegate implementation work to Codex, or types /c2c.
+---
+
+You are the **architect and reviewer**. Codex is the **implementer**. You draft contracts, delegate via the `codex` MCP server, and review the output. You do not implement the task yourself.
+
+If `codex_config` errors, tell the user to install the MCP server (npm: `claude2codex`).
+
+## Workflow
+
+1. **User decides** what to build or fix.
+2. **You draft a Goal Contract** (format below). Show it to the user for approval.
+3. **You send it** — `codex_estimate` to check budget, then `codex_implement`.
+4. **You poll** — `codex_status` until terminal. Report progress to the user.
+5. **You review** — `codex_result` for the handoff, then verify independently (see Review below).
+6. **User approves** your findings.
+
+If review fails → draft a **Delta Contract** → `codex_rework` (same `job_id`, thread resumes) → re-enter at step 4.
+
+## Goal Contract
+
+```
+### Goal
+What the code must do. First sentence = acceptance test in prose.
+
+### Constraints
+Only what Codex would get wrong without being told. One line of
+"only modify files needed for this task" covers the rest.
+
+### Success Conditions
+- [ ] Assertions, not paragraphs. At least one is a command whose exit code decides.
+- [ ] Handoff includes: Changed Files, Validation, Success Conditions, Risks & Deviations.
+```
+
+**Write lean contracts.** Goal and Success Conditions are what Codex acts on. Constraints are for genuine risks only — don't front-load your review checklist into the contract.
+
+## Delta Contract
+
+```
+### Findings
+- What is wrong, with file/line references.
+
+### Failed Success Conditions
+- [ ] The specific conditions that did not pass.
+
+### Constraints
+- Original constraints still apply. Fix only the findings; do not touch work that passed.
+```
+
+## Review
+
+1. Handoff must be complete (all four sections). Missing handoff = review failure.
+2. Re-run every verification command yourself — do not trust the handoff's claims.
+3. Run the project's own typecheck/build/test/lint.
+4. Flag security issues and constraint violations.
+5. Report findings to the user. Fix small issues (typos, imports) directly; do not rewrite the implementation.

package/dist/server.js

@@ -9,8 +9,6 @@ import { z } from "zod";
 
 // src/contracts.ts
 import { statSync } from "fs";
-import { readFile } from "fs/promises";
-import { join } from "path";
 var PROTOCOL_INSTRUCTIONS = `## Protocol Instructions
 
 ### Execution Rules
@@ -42,14 +40,6 @@ End every task with exactly these sections:
 
 ### 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;
-  }
-}
 function renderContextFiles(contextFiles2) {
   if (!contextFiles2?.length) return [];
   return [
@@ -63,11 +53,9 @@ function renderContextFiles(contextFiles2) {
     ""
   ];
 }
-async function renderGoalContract(c, cwd = process.cwd()) {
-  const agents = await optionalAgentsInstructions(cwd);
+function renderGoalContract(c) {
   const lines = [
     PROTOCOL_INSTRUCTIONS,
-    ...agents ? ["", "## Project Instructions", "", agents.trim()] : [],
     "",
     "## Goal Contract",
     "",
@@ -102,10 +90,13 @@ function renderDeltaContract(d) {
   ];
   return lines.join("\n");
 }
-function renderObjective(c, maxLen) {
+function renderObjectiveDetails(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";
+  return {
+    objective: text.length <= maxLen ? text : text.slice(0, maxLen - 1) + "\u2026",
+    objectiveChars: text.length
+  };
 }
 var HANDOFF_SECTIONS = [
   "Changed Files",
@@ -146,6 +137,11 @@ var CodexAppServer = class {
   stderrTail = [];
   exitError;
   exited = false;
+  /**
+   * Spawns a new Codex child process and sets up event listeners for stdout and stderr streams.
+   *
+   * @param opts - Configuration options specifying executable path, arguments, environment, and event callbacks
+   */
   constructor(opts) {
     this.opts = opts;
     this.proc = spawn(opts.bin, opts.args, {
@@ -167,6 +163,12 @@ var CodexAppServer = class {
       this.handleExit(null, new Error(`failed to spawn ${opts.bin}: ${err.message}`));
     });
   }
+  /**
+   * Handles Codex child process termination or spawn failure, rejecting pending requests and notifying listeners.
+   *
+   * @param code - Exit code of the child process, or null if terminated abnormally
+   * @param error - Error instance causing process exit, if any (optional)
+   */
   handleExit(code, error) {
     if (this.exited) return;
     this.exited = true;
@@ -181,6 +183,11 @@ var CodexAppServer = class {
     this.pending.clear();
     this.opts.onExit?.(code, this.exitError);
   }
+  /**
+   * Parses a single output line received from Codex stdout and dispatches it as a request response or notification.
+   *
+   * @param line - Raw text line emitted by the child process stdout
+   */
   handleLine(line) {
     const trimmed = line.trim();
     if (!trimmed) return;
@@ -208,10 +215,23 @@ var CodexAppServer = class {
       this.opts.onNotification?.(msg.method, msg.params);
     }
   }
+  /**
+   * Serializes an object to JSON and writes it to the child process's standard input stream.
+   *
+   * @param obj - Object to send to the child process
+   */
   send(obj) {
     if (this.exited) return;
     this.proc.stdin.write(JSON.stringify(obj) + "\n");
   }
+  /**
+   * Sends a correlated JSON-RPC request to Codex and returns a Promise that resolves with the response or times out.
+   *
+   * @param method - RPC method name to invoke
+   * @param params - Optional parameter object passed with the request
+   * @param timeoutMs - Maximum time to wait for a response in milliseconds, defaulting to 60,000ms
+   * @returns Promise resolving with the response result
+   */
   request(method, params, timeoutMs = 6e4) {
     if (this.exited) {
       return Promise.reject(this.exitError ?? new Error("codex app-server is not running"));
@@ -226,17 +246,31 @@ var CodexAppServer = class {
       this.send({ id, method, ...params !== void 0 ? { params } : {} });
     });
   }
+  /**
+   * Sends a one-way notification message to Codex without waiting for a response.
+   *
+   * @param method - Notification method name
+   * @param params - Optional parameter object passed with the notification
+   */
   notify(method, params) {
     this.send({ method, ...params !== void 0 ? { params } : {} });
   }
+  /**
+   * Sends the initial handshake request to Codex and emits the initialized notification upon response.
+   *
+   * @returns Promise resolving with the server initialization response payload
+   */
   async initialize() {
     const result = await this.request("initialize", {
-      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.0" },
+      clientInfo: { name: "claude2codex", title: "Claude\u2194Codex Contract Bridge", version: "0.3.1" },
       capabilities: { experimentalApi: true }
     });
     this.notify("initialized", {});
     return result;
   }
+  /**
+   * Gracefully terminates the running Codex child process via SIGTERM signal.
+   */
   kill() {
     if (!this.exited) this.proc.kill("SIGTERM");
   }
@@ -258,7 +292,7 @@ function writeLog(level, event, fields = {}) {
 // src/store.ts
 import { accessSync, constants, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from "fs";
 import { homedir } from "os";
-import { join as join2 } from "path";
+import { join } from "path";
 var MAX_JOBS = 50;
 var warned = false;
 function warnOnce(error) {
@@ -269,7 +303,7 @@ function warnOnce(error) {
   });
 }
 function defaultStateDir() {
-  return process.env.C2C_STATE_DIR ?? join2(homedir(), ".claude2codex", "jobs");
+  return process.env.C2C_STATE_DIR ?? join(homedir(), ".claude2codex", "jobs");
 }
 function createJobStore(dir = defaultStateDir()) {
   const records = /* @__PURE__ */ new Map();
@@ -281,7 +315,7 @@ function createJobStore(dir = defaultStateDir()) {
     for (const name of readdirSync(dir)) {
       if (!name.endsWith(".json")) continue;
       try {
-        const job = JSON.parse(readFileSync(join2(dir, name), "utf8"));
+        const job = JSON.parse(readFileSync(join(dir, name), "utf8"));
         if (!job?.id || !job?.startedAt || !Array.isArray(job.transcript)) continue;
         if (job.state === "blocked" || job.state === "queued" || job.state === "starting" || job.state === "running") {
           job.state = "error";
@@ -300,8 +334,24 @@ function createJobStore(dir = defaultStateDir()) {
     warnOnce(error);
   }
   return {
+    /**
+     * Retrieves a job from memory by its unique identifier.
+     *
+     * @param id - Unique job identifier to look up
+     * @returns The matching Job object, or undefined if not found
+     */
     getJob: (id) => records.get(id),
+    /**
+     * Returns a list of all currently cached jobs.
+     *
+     * @returns Array of cached Job objects
+     */
     listJobs: () => [...records.values()],
+    /**
+     * Persists job state and transcript history to memory cache and atomic disk storage.
+     *
+     * @param job - Job object to be saved
+     */
     save(job) {
       const record = { ...job, transcript: job.transcript.slice(-200) };
       records.set(job.id, record);
@@ -317,8 +367,8 @@ function createJobStore(dir = defaultStateDir()) {
   };
 }
 function atomicWrite(dir, job) {
-  const target = join2(dir, `${job.id}.json`);
-  const temp = join2(dir, `.${job.id}.${process.pid}.${Date.now()}.tmp`);
+  const target = join(dir, `${job.id}.json`);
+  const temp = join(dir, `.${job.id}.${process.pid}.${Date.now()}.tmp`);
   writeFileSync(temp, JSON.stringify(job), { encoding: "utf8", mode: 384 });
   renameSync(temp, target);
 }
@@ -329,7 +379,7 @@ function prune(dir, records) {
   for (const job of entries.slice(MAX_JOBS)) {
     records.delete(job.id);
     try {
-      unlinkSync(join2(dir, `${job.id}.json`));
+      unlinkSync(join(dir, `${job.id}.json`));
     } catch (error) {
       if (error?.code !== "ENOENT") throw error;
     }
@@ -852,6 +902,7 @@ function config(cwd) {
   };
 }
 var OBJECTIVE_MAX = envInt("GOAL_OBJECTIVE_MAX", 2e3);
+var objectiveBudgetDescription = `The rendered thread-goal objective has a GOAL_OBJECTIVE_MAX budget of ${OBJECTIVE_MAX} characters; over-limit calls are rejected.`;
 function jobSummary(job, transcriptTail = 15) {
   return {
     job_id: job.id,
@@ -879,7 +930,7 @@ function textResult(obj, isError = false) {
     isError
   };
 }
-var server = new McpServer({ name: "c2c-codex", version: "0.3.0" });
+var server = new McpServer({ name: "c2c-codex", version: "0.3.1" });
 var reasoningEffort = z.enum(["low", "medium", "high", "xhigh", "max", "ultra"]);
 var contextFiles = z.array(z.object({
   path: z.string().min(1),
@@ -946,9 +997,9 @@ server.registerTool(
     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."),
+      goal: z.string().min(1).describe(`What the code must do when this task is done. ${objectiveBudgetDescription}`),
       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."),
+      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. ${objectiveBudgetDescription}`),
       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."),
       context_files: contextFiles.optional().describe("Files or directories Codex should read before implementing."),
@@ -966,13 +1017,19 @@ server.registerTool(
       success_conditions: input.success_conditions,
       context_files: resolvedContext.files
     };
-    const prompt = await renderGoalContract(contract, jobConfig.cwd);
+    const prompt = renderGoalContract(contract);
     const dependencyError = dependencyValidationError(input.depends_on);
     if (dependencyError) return textResult({ error: dependencyError }, true);
+    const renderedObjective = renderObjectiveDetails(contract, OBJECTIVE_MAX);
+    if (renderedObjective.objectiveChars > OBJECTIVE_MAX) {
+      return textResult({
+        error: `Rendered objective is ${renderedObjective.objectiveChars} characters, exceeding the GOAL_OBJECTIVE_MAX limit of ${OBJECTIVE_MAX}. Shorten goal or success_conditions, or raise GOAL_OBJECTIVE_MAX.`
+      }, true);
+    }
     const job = startJob({
       kind: "implement",
       prompt,
-      objective: renderObjective(contract, OBJECTIVE_MAX),
+      objective: renderedObjective.objective,
       tokenBudget: input.token_budget,
       contextFiles: resolvedContext.files?.map((file) => file.path),
       dependsOn: input.depends_on,
@@ -993,10 +1050,10 @@ server.registerTool(
     title: "Estimate a Goal Contract's token cost",
     description: "Read-only estimate made before starting a job. Measures the fully rendered Goal Contract prompt and returns approx_prompt_tokens using an approximate characters/4 heuristic, plus local completed-job history.",
     inputSchema: {
-      goal: z.string().min(1).describe("What the code must do when this task is done."),
+      goal: z.string().min(1).describe(`What the code must do when this task is done. ${objectiveBudgetDescription}`),
       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."),
-      cwd: z.string().optional().describe("Working directory used to render the prompt. Defaults to the project directory."),
+      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. ${objectiveBudgetDescription}`),
+      cwd: z.string().optional().describe("Working directory used to resolve relative context_files paths. Defaults to the project directory."),
       context_files: contextFiles.optional().describe("Files or directories included in the rendered prompt.")
     },
     annotations: { readOnlyHint: true }
@@ -1005,16 +1062,21 @@ server.registerTool(
     const jobConfig = config(input.cwd);
     const resolvedContext = await resolveContextFiles(input.context_files, jobConfig.cwd);
     if (resolvedContext.missing.length) return missingContextFiles(resolvedContext.missing);
-    const prompt = await renderGoalContract({
+    const contract = {
       goal: input.goal,
       constraints: input.constraints,
       success_conditions: input.success_conditions,
       context_files: resolvedContext.files
-    }, jobConfig.cwd);
+    };
+    const prompt = renderGoalContract(contract);
+    const renderedObjective = renderObjectiveDetails(contract, OBJECTIVE_MAX);
     const history = implementHistory();
     return textResult({
       prompt_chars: prompt.length,
       approx_prompt_tokens: Math.ceil(prompt.length / 4),
+      objective_chars: renderedObjective.objectiveChars,
+      objective_max_chars: OBJECTIVE_MAX,
+      objective_over_limit: renderedObjective.objectiveChars > OBJECTIVE_MAX,
       history,
       estimated_total_tokens: history?.median_total_tokens ?? null,
       note: history ? "Estimated total tokens are based on local history and vary with task complexity." : "No completed implement job history is available; estimates based on local history vary with task complexity."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude2codex",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "MCP server bridging Claude (architect/reviewer) and Codex (implementer) via Goal/Delta Contracts and Codex's thread-goal loop.",
   "bin": {
@@ -9,7 +9,8 @@
   "files": [
     "dist",
     "PATTERNS.md",
-    "PATTERNS.zh-CN.md"
+    "PATTERNS.zh-CN.md",
+    "c2c.skill.md"
   ],
   "keywords": [
     "mcp",
@@ -30,7 +31,8 @@
     "start": "bun src/server.ts",
     "build": "tsup",
     "test": "bun test",
-    "prepack": "cp ../README.md ../README.zh-CN.md ../PATTERNS.md ../PATTERNS.zh-CN.md ."
+    "prepack": "cp ../README.md ../README.zh-CN.md ../PATTERNS.md ../PATTERNS.zh-CN.md ../c2c.skill.md .",
+    "postpack": "rm -f README.md README.zh-CN.md PATTERNS.md PATTERNS.zh-CN.md c2c.skill.md"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",