Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

feat(openai-codex): render Claude Code tools into a freeform exec tool

Jack Rudenko38ad55a2b602
diff --git a/packages/cli/src/code-mode/exec-tool.ts b/packages/cli/src/code-mode/exec-tool.ts
new file mode 100644
index 00000000..d839b1a5
--- /dev/null
+++ b/packages/cli/src/code-mode/exec-tool.ts
@@ -0,0 +1,292 @@
+/**
+ * The exec tool: ONE freeform custom tool whose input is JavaScript that calls
+ * Claude Code's tools as `tools.<Name>(args)`.
+ *
+ * The definition follows the official Codex client's (R1 §1c,
+ * `evidence/r1/exec-tool.json`): `type: "custom"`, `name: "exec"`, the same
+ * lark grammar (with its optional `// @exec:` first-line pragma), and a
+ * description whose head explains the runtime, followed by one section per
+ * nested tool in Codex's form:
+ *
+ * ### `Name`
+ * <the tool's description>
+ *
+ * exec tool declaration:
+ * ```ts
+ * declare const tools: { Name(args: {…}): Promise<string>; };
+ * ```
+ *
+ * The head lists only what claudish's sandbox implements (`text()`, `exit()`,
+ * `tools`, `ALL_TOOLS`); Codex's `image()`, `store()`, `notify()`, timers and
+ * yield are absent, so the model is never told about a helper that would throw.
+ *
+ * Sections are rendered from `claudeRequest.tools` AFTER Layer 4 (step 3c) has
+ * rewritten descriptions, so names are Claude Code's own, never the step-5
+ * encoded names. A size budget keeps the description bounded on sessions with
+ * many MCP tools: a section is at most `perToolBytes` (its description is cut to
+ * fit; the full text stays in `ALL_TOOLS`), sections are added in Claude Code's
+ * order up to `totalBytes`, and the rest are listed as deferred tools by name
+ * and first sentence. Every tool stays callable either way.
+ */
+
+import { log } from "../logger.js";
+import { schemaToTs } from "./schema-to-ts.js";
+import { ToolNameTable, normalizeToolIdent } from "./tool-names.js";
+
+/** The exec tool's grammar, verbatim from the Codex client's definition. */
+export const EXEC_TOOL_GRAMMAR =
+ "\nstart: pragma_source | plain_source\npragma_source: PRAGMA_LINE NEWLINE SOURCE\nplain_source: SOURCE\n\nPRAGMA_LINE: /[ \\t]*\\/\\/ @exec:[^\\r\\n]*/\nNEWLINE: /\\r?\\n/\nSOURCE: /[\\s\\S]+/\n";
+
+/** The exec tool's name on the wire. */
+export const EXEC_TOOL_NAME = "exec";
+
+/**
+ * The output budget the exec description states when discovery publishes no
+ * token truncation policy: the protocol default the Codex exec description
+ * itself states ("Defaults to 10000 tokens"). A rule, not model data.
+ */
+export const DEFAULT_EXEC_MAX_OUTPUT_TOKENS = 10_000;
+
+/** Description size limits (claudish policy; UTF-8 bytes). */
+export interface ExecToolBudget {
+ /** One nested tool's section, heading to closing fence. */
+ perToolBytes: number;
+ /** Every rendered section together. */
+ totalBytes: number;
+}
+
+export const DEFAULT_EXEC_TOOL_BUDGET: ExecToolBudget = {
+ perToolBytes: 6 * 1024,
+ totalBytes: 48 * 1024,
+};
+
+/** The Responses custom tool definition sent upstream. */
+export interface ExecToolDefinition {
+ type: "custom";
+ name: typeof EXEC_TOOL_NAME;
+ description: string;
+ format: { type: "grammar"; syntax: "lark"; definition: string };
+}
+
+/** One entry of the sandbox's `ALL_TOOLS` global. */
+export interface ExecToolMeta {
+ /** The identifier a script calls (`tools[name]`). */
+ name: string;
+ description: string;
+ inputSchema: unknown;
+}
+
+export interface RenderedExecTool {
+ tool: ExecToolDefinition;
+ /** Identifier ↔ Claude Code name for every callable tool. */
+ names: ToolNameTable;
+ /** `ALL_TOOLS`: every callable tool with its full description and schema. */
+ allTools: ExecToolMeta[];
+ /** Claude Code names listed only under "Deferred tools" (over the budget). */
+ deferred: string[];
+}
+
+/** A Claude Code tool as it arrives in `claudeRequest.tools`. */
+export interface ClaudeToolLike {
+ name?: unknown;
+ description?: unknown;
+ input_schema?: unknown;
+}
+
+export interface RenderExecToolOptions {
+ /** The `max_output_tokens` default the description states. Default 10,000. */
+ defaultMaxOutputTokens?: number;
+}
+
+function utf8Bytes(text: string): number {
+ return Buffer.byteLength(text, "utf8");
+}
+
+/** `text` cut to at most `maxBytes` UTF-8 bytes at a line (else character) boundary. */
+function cutToBytes(text: string, maxBytes: number): string {
+ if (maxBytes <= 0) return "";
+ if (utf8Bytes(text) <= maxBytes) return text;
+ let lo = 0;
+ let hi = text.length;
+ while (lo < hi) {
+ const mid = Math.ceil((lo + hi) / 2);
+ if (utf8Bytes(text.slice(0, mid)) <= maxBytes) lo = mid;
+ else hi = mid - 1;
+ }
+ const head = text.slice(0, lo);
+ const nl = head.lastIndexOf("\n");
+ return nl > head.length / 2 ? head.slice(0, nl) : head;
+}
+
+/** The first sentence (or first line) of a description, for the deferred list. */
+function firstSentence(description: string): string {
+ const line = description.trim().split(/\r?\n/)[0] ?? "";
+ const match = /^(.+?[.!?])(\s|$)/.exec(line);
+ const sentence = (match ? match[1] : line).trim();
+ return sentence.length > 200 ? `${sentence.slice(0, 199)}…` : sentence;
+}
+
+function execToolHead(defaultMaxOutputTokens: number): string {
+ return [
+ "Run JavaScript code to orchestrate/compose tool calls",
+ "- Evaluates the provided JavaScript code in a fresh sandbox as the body of an async function, so top-level `await` works.",
+ '- All nested tools are available on the global `tools` object, for example `await tools.Read({ file_path: "/abs/path" })`. Tool names are exposed as normalized JavaScript identifiers.',
+ "- Nested tool methods take an object as their input argument.",
+ "- Nested tools return a string: the tool's result text. A failed or denied call rejects with a string (the tool's error text), so use `Promise.allSettled` to inspect every result.",
+ "- Runs raw JavaScript -- no Node, no file system, no network access, no console, no timers.",
+ "- Accepts raw JavaScript source text, not JSON, quoted strings, or markdown code fences.",
+ '- You may optionally start the tool input with a first-line pragma like `// @exec: {"max_output_tokens": 1000}`.',
+ `- \`max_output_tokens\` sets the token budget for direct \`exec\` results. Defaults to ${defaultMaxOutputTokens} tokens.`,
+ "- When the script finishes, nested tool calls it never awaited are discarded and never run.",
+ "",
+ "- Global helpers:",
+ "- `exit()`: Immediately ends the current script successfully (like an early return from the top level).",
+ "- `text(value: string | number | boolean | undefined | null)`: Appends a text item. Non-string values are stringified with `JSON.stringify(...)` when possible.",
+ "- `ALL_TOOLS`: metadata for the enabled nested tools as `{ name, description, inputSchema }` entries.",
+ "",
+ "Batch independent searches and reads in one exec using await Promise.allSettled([...]); inspect every result.",
+ "When calling `exec`, parallelize independent tool calls by awaiting Promises.",
+ ].join("\n");
+}
+
+function renderSection(ident: string, description: string, schema: unknown): string {
+ const declaration = `declare const tools: { ${ident}(args: ${schemaToTs(schema)}): Promise<string>; };`;
+ const body = description.trim();
+ return [
+ `### \`${ident}\``,
+ ...(body ? [body] : []),
+ "",
+ "exec tool declaration:",
+ "```ts",
+ declaration,
+ "```",
+ ].join("\n");
+}
+
+/**
+ * One section within `perToolBytes`: the full description when it fits, else
+ * the description cut to fit with a pointer to `ALL_TOOLS`; undefined when the
+ * declaration alone exceeds the budget (the tool is then deferred).
+ */
+function sectionWithinBudget(
+ ident: string,
+ description: string,
+ schema: unknown,
+ perToolBytes: number
+): string | undefined {
+ const full = renderSection(ident, description, schema);
+ if (utf8Bytes(full) <= perToolBytes) return full;
+ const bare = renderSection(ident, "", schema);
+ const marker = "\n[description shortened; the full text is in ALL_TOOLS]";
+ const room = perToolBytes - utf8Bytes(bare) - utf8Bytes(marker) - 1;
+ if (room < 0) return undefined;
+ const cut = cutToBytes(description.trim(), room);
+ return renderSection(ident, cut ? `${cut}${marker}` : marker.trim(), schema);
+}
+
+/** The "Deferred tools" list: identifier and first sentence of each. */
+function deferredSection(
+ deferred: readonly string[],
+ names: ToolNameTable,
+ allTools: readonly ExecToolMeta[]
+): string {
+ const lines = deferred.map((name) => {
+ const ident = names.identFor(name) ?? name;
+ const meta = allTools.find((m) => m.name === ident);
+ const sentence = firstSentence(meta?.description ?? "");
+ return sentence ? `- \`${ident}\` — ${sentence}` : `- \`${ident}\``;
+ });
+ return `### Deferred tools\n${lines.join("\n")}`;
+}
+
+/**
+ * Every callable tool's `ALL_TOOLS` entry, the sections that fit the budget,
+ * and the names deferred past it.
+ */
+function layOutSections(
+ named: ReadonlyArray<ClaudeToolLike & { name: string }>,
+ names: ToolNameTable,
+ limits: ExecToolBudget
+): { sections: string[]; deferred: string[]; allTools: ExecToolMeta[] } {
+ const sections: string[] = [];
+ const deferred: string[] = [];
+ // One entry per kept table name (a repeated name or a skipped collision is not callable).
+ const seen = new Set<string>();
+ const callable = named.filter((tool) => {
+ if (seen.has(tool.name) || names.identFor(tool.name) === undefined) return false;
+ seen.add(tool.name);
+ return true;
+ });
+ const allTools: ExecToolMeta[] = callable.map((tool) => ({
+ name: names.identFor(tool.name) ?? normalizeToolIdent(tool.name),
+ description: typeof tool.description === "string" ? tool.description : "",
+ inputSchema: tool.input_schema ?? {},
+ }));
+ let used = 0;
+ let overflowed = false;
+
+ for (const [i, tool] of callable.entries()) {
+ const { name: ident, description, inputSchema } = allTools[i];
+ const section = overflowed
+ ? undefined
+ : sectionWithinBudget(ident, description, inputSchema, limits.perToolBytes);
+ const size = section === undefined ? 0 : utf8Bytes(section) + 2;
+ if (section === undefined || used + size > limits.totalBytes) {
+ // Claude Code's order is kept: once one section does not fit the total,
+ // every later tool is deferred too. A tool whose declaration alone
+ // exceeds the per-tool budget is deferred on its own.
+ if (section !== undefined) overflowed = true;
+ deferred.push(tool.name);
+ continue;
+ }
+ sections.push(section);
+ used += size;
+ }
+ return { sections, deferred, allTools };
+}
+
+/**
+ * The exec tool for `tools` (Claude Code's tool list, in its order).
+ *
+ * Tools without a string name are ignored; a name whose identifier collides
+ * with an earlier one is skipped (logged by `ToolNameTable`) and not callable.
+ */
+export function renderExecTool(
+ tools: readonly ClaudeToolLike[],
+ budget: Partial<ExecToolBudget> = {},
+ options: RenderExecToolOptions = {}
+): RenderedExecTool {
+ const limits: ExecToolBudget = { ...DEFAULT_EXEC_TOOL_BUDGET, ...budget };
+ const defaultMaxOutputTokens = options.defaultMaxOutputTokens ?? DEFAULT_EXEC_MAX_OUTPUT_TOKENS;
+ const named = tools.filter(
+ (t): t is ClaudeToolLike & { name: string } => typeof t?.name === "string" && t.name !== ""
+ );
+ const names = new ToolNameTable(named.map((t) => t.name));
+ const { sections, deferred, allTools } = layOutSections(named, names, limits);
+
+ const parts = [execToolHead(defaultMaxOutputTokens)];
+ if (deferred.length > 0) {
+ parts.push(
+ "Some deferred nested tools are omitted from this description. They are still available on the global `tools` object and listed in `ALL_TOOLS`.\nTo find one, filter `ALL_TOOLS` by `name` and `description`."
+ );
+ }
+ parts.push(...sections);
+ if (deferred.length > 0) {
+ parts.push(deferredSection(deferred, names, allTools));
+ log(
+ `[CodeMode] exec tool: ${sections.length} tool(s) described, ${deferred.length} deferred over the ${limits.totalBytes}-byte budget`
+ );
+ }
+
+ return {
+ tool: {
+ type: "custom",
+ name: EXEC_TOOL_NAME,
+ description: parts.join("\n\n"),
+ format: { type: "grammar", syntax: "lark", definition: EXEC_TOOL_GRAMMAR },
+ },
+ names,
+ allTools,
+ deferred,
+ };
+}
diff --git a/packages/cli/src/code-mode/schema-to-ts.ts b/packages/cli/src/code-mode/schema-to-ts.ts
new file mode 100644
index 00000000..085feb76
--- /dev/null
+++ b/packages/cli/src/code-mode/schema-to-ts.ts
@@ -0,0 +1,153 @@
+/**
+ * A tool's JSON Schema `input_schema` rendered as a TypeScript type, for the
+ * `exec tool declaration:` block of the exec tool's description.
+ *
+ * The form follows the official Codex client's renderer (R1 §1c,
+ * `render_json_schema_to_typescript`): each property's description becomes a
+ * `//` comment above it, required properties are bare and optional ones carry
+ * `?`. Supported: `enum`, `const`, `anyOf` / `oneOf` unions, type arrays,
+ * arrays (and tuples), nested objects to a depth of 4, `additionalProperties`.
+ * Anything else, and anything deeper, is `unknown` — the type is guidance for
+ * the model; Claude Code validates the real call.
+ */
+
+/** Deepest object/array nesting rendered; below it a value is `unknown`. */
+export const MAX_SCHEMA_DEPTH = 4;
+
+type Schema = Record<string, unknown>;
+
+const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+function isSchema(value: unknown): value is Schema {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function literal(value: unknown): string {
+ if (value === null) return "null";
+ if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+ return JSON.stringify(value);
+ }
+ return "unknown";
+}
+
+function union(parts: string[]): string {
+ const unique = [...new Set(parts)];
+ if (unique.length === 0) return "unknown";
+ if (unique.includes("unknown")) return "unknown";
+ return unique.join(" | ");
+}
+
+function propertyKey(name: string): string {
+ return IDENTIFIER.test(name) ? name : JSON.stringify(name);
+}
+
+function commentLines(description: unknown, pad: string): string[] {
+ if (typeof description !== "string") return [];
+ const text = description.trim();
+ if (!text) return [];
+ return text.split(/\r?\n/).map((line) => `${pad}// ${line.trimEnd()}`.trimEnd());
+}
+
+function renderObject(schema: Schema, depth: number, indent: number): string {
+ const properties = isSchema(schema.properties) ? schema.properties : undefined;
+ const additional = schema.additionalProperties;
+ if (!properties) {
+ if (isSchema(additional)) {
+ return `Record<string, ${render(additional, depth + 1, indent)}>`;
+ }
+ return "Record<string, unknown>";
+ }
+ const names = Object.keys(properties);
+ if (names.length === 0) return "{}";
+ const required = new Set(
+ Array.isArray(schema.required) ? schema.required.filter((r) => typeof r === "string") : []
+ );
+ const pad = " ".repeat(indent + 1);
+ const lines: string[] = ["{"];
+ for (const name of names) {
+ const prop = properties[name];
+ lines.push(...commentLines(isSchema(prop) ? prop.description : undefined, pad));
+ const optional = required.has(name) ? "" : "?";
+ lines.push(`${pad}${propertyKey(name)}${optional}: ${render(prop, depth + 1, indent + 1)};`);
+ }
+ if (isSchema(additional)) {
+ lines.push(`${pad}[key: string]: ${render(additional, depth + 1, indent + 1)};`);
+ }
+ lines.push(`${" ".repeat(indent)}}`);
+ return lines.join("\n");
+}
+
+function renderArray(schema: Schema, depth: number, indent: number): string {
+ const tuple = Array.isArray(schema.prefixItems)
+ ? schema.prefixItems
+ : Array.isArray(schema.items)
+ ? schema.items
+ : undefined;
+ if (tuple) {
+ return `[${tuple.map((item) => render(item, depth + 1, indent)).join(", ")}]`;
+ }
+ if (schema.items === undefined) return "Array<unknown>";
+ return `Array<${render(schema.items, depth + 1, indent)}>`;
+}
+
+function renderType(type: string, schema: Schema, depth: number, indent: number): string {
+ switch (type) {
+ case "string":
+ return "string";
+ case "number":
+ case "integer":
+ return "number";
+ case "boolean":
+ return "boolean";
+ case "null":
+ return "null";
+ case "array":
+ return renderArray(schema, depth, indent);
+ case "object":
+ return renderObject(schema, depth, indent);
+ default:
+ return "unknown";
+ }
+}
+
+function render(schema: unknown, depth: number, indent: number): string {
+ if (!isSchema(schema)) return "unknown";
+ if (depth > MAX_SCHEMA_DEPTH) return "unknown";
+ if ("const" in schema) return literal(schema.const);
+ if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+ return union(schema.enum.map(literal));
+ }
+ const branches = Array.isArray(schema.anyOf)
+ ? schema.anyOf
+ : Array.isArray(schema.oneOf)
+ ? schema.oneOf
+ : undefined;
+ if (branches && branches.length > 0) {
+ return union(branches.map((branch) => render(branch, depth, indent)));
+ }
+ const type = schema.type;
+ if (Array.isArray(type)) {
+ return union(
+ type
+ .filter((t): t is string => typeof t === "string")
+ .map((t) => renderType(t, schema, depth, indent))
+ );
+ }
+ if (typeof type === "string") return renderType(type, schema, depth, indent);
+ if (isSchema(schema.properties)) return renderObject(schema, depth, indent);
+ if (schema.items !== undefined || Array.isArray(schema.prefixItems)) {
+ return renderArray(schema, depth, indent);
+ }
+ return "unknown";
+}
+
+/**
+ * `schema` as the TypeScript type of a nested tool's `args` parameter.
+ * A schema that is not an object, or names no properties, renders as `{}` /
+ * `Record<string, unknown>` (never a primitive: nested tools take an object).
+ */
+export function schemaToTs(schema: unknown): string {
+ if (!isSchema(schema)) return "Record<string, unknown>";
+ const rendered = render({ ...schema, type: "object" }, 1, 0);
+ return rendered === "unknown" ? "Record<string, unknown>" : rendered;
+}
diff --git a/packages/cli/src/code-mode/tool-names.ts b/packages/cli/src/code-mode/tool-names.ts
new file mode 100644
index 00000000..cfb68074
--- /dev/null
+++ b/packages/cli/src/code-mode/tool-names.ts
@@ -0,0 +1,82 @@
+/**
+ * Claude Code tool names as JavaScript identifiers on the exec tool's `tools`
+ * object.
+ *
+ * The official Codex client normalises a nested tool's name by replacing every
+ * character outside `[A-Za-z0-9_$]` with `_` (a leading digit too), and when two
+ * names collide the LATER one is skipped (R1 §1c,
+ * `code-mode-protocol/src/description.rs`). claudish applies the same rule to
+ * Claude Code's own tool names, so `mcp__my-server__run` is called as
+ * `tools.mcp__my_server__run`, and keeps the table both ways: the identifier a
+ * script calls, and the name the tool_use block must carry.
+ */
+
+import { log } from "../logger.js";
+
+/** `name` as a JavaScript identifier: `[A-Za-z0-9_$]` kept, the rest `_`, no leading digit. */
+export function normalizeToolIdent(name: string): string {
+ let ident = name.replace(/[^A-Za-z0-9_$]/g, "_");
+ if (ident === "") ident = "_";
+ if (/^[0-9]/.test(ident)) ident = `_${ident.slice(1)}`;
+ return ident;
+}
+
+/** One nested tool: the identifier a script calls and Claude Code's own name. */
+export interface ToolNameEntry {
+ ident: string;
+ name: string;
+}
+
+/**
+ * The identifier ↔ original-name table for one request's tool list, in Claude
+ * Code's order. Built once per request from `claudeRequest.tools`.
+ */
+export class ToolNameTable {
+ private readonly byIdent = new Map<string, ToolNameEntry>();
+ private readonly byName = new Map<string, ToolNameEntry>();
+ /** Names dropped because their identifier was already taken. */
+ readonly skipped: string[] = [];
+
+ constructor(names: readonly string[]) {
+ for (const name of names) {
+ if (typeof name !== "string" || name === "") continue;
+ if (this.byName.has(name)) continue;
+ const ident = normalizeToolIdent(name);
+ const taken = this.byIdent.get(ident);
+ if (taken) {
+ this.skipped.push(name);
+ log(
+ `[CodeMode] tool ${JSON.stringify(name)} skipped: its identifier ${ident} is already ` +
+ `taken by ${JSON.stringify(taken.name)}`
+ );
+ continue;
+ }
+ const entry: ToolNameEntry = { ident, name };
+ this.byIdent.set(ident, entry);
+ this.byName.set(name, entry);
+ }
+ }
+
+ /** Every kept entry, in Claude Code's order. */
+ entries(): ToolNameEntry[] {
+ return [...this.byIdent.values()];
+ }
+
+ /** The identifier a script calls for Claude Code's `name`, or undefined (unknown or skipped). */
+ identFor(name: string): string | undefined {
+ return this.byName.get(name)?.ident;
+ }
+
+ /** Claude Code's name for the identifier `ident`, or undefined. */
+ nameFor(ident: string): string | undefined {
+ return this.byIdent.get(ident)?.name;
+ }
+
+ has(ident: string): boolean {
+ return this.byIdent.has(ident);
+ }
+
+ get size(): number {
+ return this.byIdent.size;
+ }
+}