# CodeModeOnly MVP ## Status Implemented for [#10377](https://github.com/QwenLM/qwen-code/issues/10377). The feature is opt-in and defaults off. Partly superseded by [Lazy Code Mode](lazy-code-mode.md): `tool_search` is now a top-level direct control, and `exec` omits deferred tool signatures while search is available. The exposure table and the deferred-schema paragraph below describe this MVP; `tool_call` stays hidden. ## Goal Add a `tools.codeModeOnly` setting that replaces the ordinary model-facing tool surface with one `exec` JavaScript tool plus the small set of tools that must remain direct control-plane calls. `exec` code can call ordinary tools through `tools.(args)` without bypassing Qwen Code's validation, permissions, approvals, hooks, telemetry, cancellation, concurrency, or output budgets. Direct mode is a compatibility boundary: when the setting is false, tool registration, deferred-tool behavior, provider requests, and execution remain unchanged. ## Non-goals - Hybrid direct/code exposure. - Persistent cells, globals, or values between `exec` calls. - Background jobs, `wait`, `yield`, `store`, or `load`. - Raw/freeform provider calls. - Making `tool_search` or a `tool_call` bridge available inside code mode. - A Node.js-compatible sandbox. ## Configuration ```json { "tools": { "codeModeOnly": true } } ``` The setting resolves once to the effective `ToolMode` value `direct` or `code_mode_only`. `ToolRegistry` and the execution surfaces consume that mode. `exec` is only registered when the setting is enabled, so disabling the setting also removes it from diagnostics and registry listings. ## Exposure policy The registry remains the source of truth. Exposure is a view over registered tools, never a second registry. | Category | Model top level | `tools.*` inside `exec` | | ------------------------------------------ | ----------------- | ----------------------- | | `exec` | CodeModeOnly only | No | | Direct control | Yes | No | | Ordinary registered tool | No | Yes | | Hidden bridge (`tool_search`, `tool_call`) | No | No | The direct-control allowlist is centralized and deliberately small. It covers user interaction (`ask_user_question`), delegation (`agent`), terminal output contracts, plan/goal/task/team/worktree/session controls, and ACP host controls whose lifecycle cannot safely be hidden behind an interpreted program. New tools default to code-mode-callable; adding a direct-only or hidden tool requires an explicit policy edit. Deferred tools remain registered and callable from `exec`, and keep their deferred registry state. The generated `exec` description nonetheless carries their full schemas, alongside their names and descriptions in `ALL_TOOLS`: CodeModeOnly hides `tool_search`, and a nested call never appears in history as a `functionCall`, so no later reveal can supply a schema the description omitted. CodeModeOnly skips deferred preload and ToolSearch reminders because neither mechanism is part of its model-facing protocol. ## Deterministic JavaScript interface Before each provider tool sync, the `exec` description is generated from the current registry. Tools are sorted by canonical name. A name is normalized to a JavaScript property by replacing invalid identifier characters and prefixing names that begin with a digit. If two canonical names normalize to the same property, the lexicographically first name wins and one warning names the omitted collision. The description defines: - a fresh async JavaScript execution environment; - `tools.(args)` for nested calls; - `ALL_TOOLS`, including canonical and JavaScript names; - `text(value)`, `image(value)`, `audio(value)`, and `exit()`; - TypeScript-like signatures generated deterministically from JSON Schema; - the absence of Node.js, imports, network APIs, timers, and persistent state. The nested call returns a JSON-safe object containing the real call id, tool name, status, output, and structured content. Failed and cancelled calls reject the guest promise with the scheduler/ACP error. ## Sandbox and transport `exec` runs QuickJS compiled to WebAssembly in a dedicated child process. Each call creates a fresh QuickJS runtime and context. The child process receives a small framed JSON protocol over stdio; it has no tool implementations or Qwen configuration. The parent maps JavaScript names back to canonical registry names and dispatches each call. The guest has no Node globals, `require`, `process`, filesystem, sockets, module loader, `console`, timers, `Atomics`, `SharedArrayBuffer`, or `WebAssembly`. Dynamic and static imports fail because no module loader is installed. Runtime memory and stack limits are fixed. QuickJS's interrupt hook enforces a guest CPU budget. That budget and the parent's fallback watchdog pause while the guest is suspended on registered host tools, whose own scheduler/ACP timeouts remain authoritative, and resume before guest jobs run again. This lets long builds keep their declared tool timeout without allowing guest CPU loops to escape the fixed budget. Source, protocol frames, helper output, and the final result are bounded. Cancellation aborts every nested call and terminates the child. Settling the top-level promise also cancels unawaited nested calls before teardown. No child, timer, promise handle, or guest global survives the call. The child receives a minimal sanitized environment and cannot inspect it from the guest. The separate process is defense in depth for interpreter failures; QuickJS/WASM is the guest capability boundary. ## Reentrant dispatch `CoreToolScheduler.schedule()` cannot be called recursively: a child call would queue behind its still-running parent and deadlock. Scheduler execution therefore binds an async-local `ToolCallRuntime` context at the invocation boundary. `exec` only talks to that context. The scheduler runtime batches nested calls received in one event-loop turn and runs them through a sibling scheduler configured from the same `Config` and observers. This preserves the existing build/validation, permission, confirmation, hook, execution, truncation, telemetry, and concurrency path without direct `tool.execute()` calls. Sequential guest awaits produce sequential batches; calls submitted together enter one batch. Code Mode Bash calls bypass the read-only command classifier, with the model responsible for keeping dependent calls sequential. Other tools retain their existing concurrency classification. Nested request ids include the parent id and carry `source: code_mode` plus `parentCallId`. Nested scheduler updates are merged into the owning scheduler's visible calls, and confirmation responses for nested ids are delegated to it. The outer model still receives only the completed `exec` response. ACP keeps its existing independently audited execution chain. Its invocation boundary binds the same runtime interface, with nested dispatch re-entering `Session.runTool`. Thus ACP top-level and nested calls use the same ACP permissions, approvals, hooks, telemetry, persistence, and cancellation rather than borrowing CLI scheduler state or executing tools directly. ACP serializes ordinary nested calls, matching its existing direct-tool ordering; the Core scheduler retains its existing safe-read parallel batches. ## Provider behavior All providers continue to consume `FunctionDeclaration[]` from `ToolRegistry`. In Direct mode this array is byte-for-byte the existing view. In CodeModeOnly it is the exposure-policy view, so Gemini/Qwen, OpenAI-compatible, and Anthropic adapters all receive the structured `exec` declaration without provider-specific prompting. Filtered subagent declarations apply the same policy. For a read-only teammate or a fork with an execution allowlist, `exec` is the audited gateway while the exact allowed nested names are carried in its invocation context. The same set generates the description and is checked again before Core dispatch, so an explicit allowlist can narrow code-mode-callable nested tools without becoming prompt-only policy, exposing a hidden bridge, or making `exec` recursive. For cache-compatible forks, an inherited `exec` declaration represents its ordinary bindings: an omitted `fork_tools` inherits them, while an explicit list replaces them with the requested subset. ## Failure and rollback Unknown, collided, hidden, direct-only, and recursively requested tools fail closed before scheduling. Invalid arguments continue to fail in the normal execution chain. A sandbox startup, protocol, timeout, memory, or teardown failure becomes an `exec` tool error. Rollback is setting `tools.codeModeOnly` to false. No session migration or registry cleanup is required because code mode has no persistent state and the ordinary registry was never replaced. ## Verification Unit and integration coverage must include: - Direct and CodeModeOnly exposure, deferred retention, collision handling, deterministic descriptions, and explicit subagent filtering. - Valid/invalid JavaScript, async sequencing, `Promise.all`, helper output, thrown errors, CPU loops, memory limits, imports, unavailable globals, isolation, output limits, cancellation, unawaited work, and recursive calls. - Nested permissions, confirmation, Pre/Post hooks, failures, output budgets, true-name telemetry/UI updates, MCP tools, and the scheduler deadlock regression. - Gemini/Qwen, OpenAI-compatible, Anthropic, headless, interactive, subagent, and ACP surfaces. The implementation is complete only after focused package tests, build, typecheck, E2E probes, and two clean full-diff audit passes.