test(code-mode): cover exec tool guidance

Kaspre · Kaspre · commit e75ca8e7bb34 · 2026-05-19T18:05:37.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,7 +6,6 @@ Docs: https://docs.openclaw.ai
 
 ### Changes
 
-- Agents/code mode: sharpen the `exec` tool description so models do not waste turns rediscovering that Node modules are unavailable, that `language` rejects values other than `"javascript"`/`"typescript"`, and that the `tools.search`/`describe`/`call` bridge is the path for shell, file, network, and other I/O. Thanks @Kaspre.
 - Agents/config: allow `agents.list[].experimental.localModelLean` so lean local-model mode can be enabled for one configured agent instead of globally.
 - Providers/xAI: add device-code OAuth login so remote and headless setups can authorize xAI without a localhost browser callback. (#84005) Thanks @fuller-stack-dev.
 
diff --git a/src/agents/code-mode.test.ts b/src/agents/code-mode.test.ts
@@ -245,6 +245,29 @@ describe("Code Mode", () => {
     expect(language).not.toHaveProperty("oneOf");
   });
 
+  it("describes code-mode runtime constraints in the model-visible exec schema", () => {
+    const { tools } = createCodeModeHarness();
+    const execTool = tools[0];
+    const parameters = execTool.parameters as {
+      properties?: Record<string, Record<string, unknown>>;
+    };
+
+    expect(execTool.description).toContain("Node.js modules");
+    expect(execTool.description).toContain("`require`/`import` are NOT available");
+    expect(execTool.description).toContain("`tools.search(query)`");
+    expect(execTool.description).toContain("enabled catalog tools allowed by policy");
+    expect(execTool.description).toContain("`tools.describe(entry.id)`");
+    expect(execTool.description).toContain("`tools.call(entry.id, args)`");
+    expect(execTool.description).toContain('"javascript" or "typescript"');
+
+    expect(parameters.properties?.code?.description).toContain("`tools` object");
+    expect(parameters.properties?.code?.description).toContain("`ALL_TOOLS`");
+    expect(parameters.properties?.code?.description).toContain("Node built-in modules are not");
+    expect(parameters.properties?.language?.description).toContain(
+      'Must be "javascript" or "typescript"',
+    );
+  });
+
   it("removes legacy Tool Search controls from the visible code mode surface", () => {
     const { config, catalogRef, tools: codeModeTools } = createCodeModeHarness();
     const compacted = applyCodeModeCatalog({
diff --git a/src/agents/code-mode.ts b/src/agents/code-mode.ts
@@ -826,7 +826,7 @@ export function createCodeModeTools(ctx: CodeModeToolContext): AnyAgentTool[] {
     name: CODE_MODE_EXEC_TOOL_NAME,
     label: "exec",
     description:
-      "Run JavaScript or TypeScript in OpenClaw code mode. Node.js modules and `require`/`import` are NOT available — for any shell, file, network, or external action, use the catalog bridge from inside your code: `tools.search(query)` to find tools, `tools.describe(name)` for the input schema, then `tools.call(name, args)`. The `language` field accepts only \"javascript\" or \"typescript\"; do not pass \"bash\", \"shell\", or other values.",
+      "Run JavaScript or TypeScript in OpenClaw code mode. Node.js modules and `require`/`import` are NOT available — for any shell, file, network, or external action, use enabled catalog tools allowed by policy from inside your code: `tools.search(query)` to find catalog entries, `tools.describe(entry.id)` for the input schema, then `tools.call(entry.id, args)`. The `language` field accepts only \"javascript\" or \"typescript\"; do not pass \"bash\", \"shell\", or other values.",
     parameters: Type.Object({
       code: Type.String({
         description:
