feat(tools): evaluate Codex-style code mode (single grammar-constrained exec tool that calls tools as an API)

[Yeachan-Heo]

Migrated from #5770 (originally opened by @Yeachan-Heo).

Proposed in the community channel by DBC, referencing codex-rs/core/src/tools/spec_plan.rs / tools/code_mode/execute_spec.rs in openai/codex.

What Codex does

Codex exposes one freeform tool (ToolSpec::Freeform) whose format is a Lark grammar, and whose description enumerates the available tools as a callable API. The model writes a script that chains several tool calls; the runtime executes it and returns one result. Tool exposure is a three-way axis (DIRECT / DEFERRED / CODE_MODE), so a tool can be reachable only from inside code mode, and ToolMode::CodeModeOnly drops direct function exposure entirely.

Two separable wins:

1. Schema budget — not shipping N tool schemas in every request.
2. Round-trip batching — N dependent tool calls become one model turn instead of N.

Where we already are

• (1) is largely covered: hidden tools + search_tool_bm25 activation is our deferred-exposure equivalent.
• The wire prerequisite exists: packages/ai/src/providers/openai-responses.ts already emits type: "custom" grammar tools (the freeform apply_patch variant), so a grammar-constrained exec tool needs no new provider plumbing on the OpenAI Responses path.
• (2) is not covered at all today.

The real question

Code mode's payoff is conditioned on GPT post-training for that exact tool shape. Anthropic and the OpenAI-compatible providers have no freeform/grammar tool type, so a port either becomes OpenAI-Responses-only or degrades to a plain string-argument function whose quality is unmeasured.

Proposed gate before any implementation

Measure, do not assume:

• Use packages/orchestration-token-benchmark to compare direct function calling vs a code-mode exec tool on the same task set: total input tokens, total turns, wall clock, and task success.
• Run it on at least one GPT model and one non-GPT model. If the non-GPT arm regresses, code mode ships as a per-provider capability flag, never as a default.
• Only then decide between CodeModeOnly (drop direct exposure) and code mode as an additional exposure axis.

Not filing an implementation plan yet: the numbers decide the shape.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]