Allow remote Code Mode hosts to declare the source language and model-facing exec contract

What variant of Codex are you using?

Codex CLI / App Server 0.146.0 with an external Code Mode host connected through app-server --code-mode-host.

What feature would you like to see?

Please allow a remote Code Mode host to declare the source language and the model-facing authoring contract for the native exec custom tool.

Codex App Server already has a useful runtime boundary:

Codex model
  -> native exec / wait
  -> Codex App Server
  -> --code-mode-host ws://...
  -> external Code Mode host

However, --code-mode-host currently replaces only the execution backend. The model-facing exec description is still JavaScript/V8-specific: it tells the model to emit raw JavaScript, use the global tools object, and expect a V8 isolate.

That creates a mismatch for a host that executes another source language:

model sees the JavaScript contract
  -> model emits JavaScript
  -> Codex forwards it to the external host
  -> host expects another language
  -> compilation fails

The external host currently has no supported way to tell Codex which source language, grammar, calling convention, or examples should be shown to the model.

A host-neutral solution could let an explicitly selected/trusted host advertise metadata such as:

{
  "sourceLanguage": {
    "id": "baml",
    "displayName": "BAML"
  },
  "execDescription": "...",
  "freeformGrammar": "...",
  "examples": ["..."]
}

The exact shape is not important. Two possible ownership models seem reasonable:

1. negotiate the source-language capability through the Code Mode host handshake; or
2. let local Codex configuration select a language adapter independently of --code-mode-host.

I slightly prefer handshake metadata because the runtime knows the source language it accepts. The metadata should take effect only after the user explicitly selects or trusts that host.

For example, a BAML host wants the model to author source like:

function main() -> string {
  "done"
}

Enabled Codex tools can be expressed as function parameters:

function main(
  tool_lookup: (json) -> json
) -> json {
  tool_lookup({ query: "BAML" })
}

This should still use the native exec tool. It does not require an exec_baml tool, a second agent, or a TypeScript-to-BAML translation step.

Backward compatibility is important:

• when no custom language metadata is configured, preserve the current JavaScript description and grammar exactly;
• keep the embedded JavaScript/V8 path unchanged;
• only inject another authoring contract when the user explicitly selects it.

Codex should also retain its current security and ownership boundaries:

• Codex owns the tool catalog and executes real tools;
• Codex continues to enforce approvals, sandboxing, and policy;
• the external host receives source and delegates nested tool calls through the existing protocol;
• runtime results should not dynamically rewrite future tool instructions.

If arbitrary host-provided prompt text is too broad, a constrained local language-adapter configuration would still solve the problem.

Additional information

I tested the architecture with a small patch against Codex 0.146.0:

[features.code_mode]
language = "javascript" # default
# language = "baml"

The experiment keeps the JavaScript branch on the unchanged upstream description builder and grammar. Only the explicit BAML branch substitutes the exec description, grammar, examples, and language-aware parser messages. Host selection remains independent through the official app-server --code-mode-host option.

An independent BAML host interoperates with the current WebSocket framing, handshake, execute, wait, terminate, and delegate flow. This suggests that the model-facing source-language contract and the execution host can remain separate concepts without changing the existing Code Mode lifecycle.

This proposal is intentionally generic rather than requesting that Codex embed BAML. It would make --code-mode-host a reusable runtime boundary for any non-JavaScript Code Mode implementation.

Questions for the maintainers:

1. Is --code-mode-host intended to support non-JavaScript runtimes?
2. Would source-language metadata fit the existing host handshake?
3. Would Codex prefer host-declared metadata or a local language-adapter configuration?
4. Which layer should own the description, grammar, and examples?

I can share the focused patch and interoperability tests if that would help the design discussion.