Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/**
* 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 the hook request stages (1a, 3a) have
* 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,
};
}