fix(schema): accept tools.codeMode at agent-entry scope (#83388)

HCL · HCL · commit f9bfa5d12d0e · 2026-05-18T10:29:44.000+08:00
docs/reference/code-mode.md describes 'tools.codeMode.enabled: true' as
settable on 'the agent or runtime config'. The top-level ToolsSchema
already accepts codeMode, but AgentToolsSchema is .strict() and didn't
include the key, so gateway startup rejected the documented per-agent
shape with 'agents.list.0.tools: Unrecognized key: "codeMode"'.

Add 'codeMode: CodeModeSchema' to AgentToolsSchema. The schema is the
same one consumed at the top level, so the boolean shorthand and the
full object form (enabled/runtime/timeoutMs/languages/...) all behave
identically at the per-agent scope. strict() is preserved on the inner
schema; unknown nested keys still reject.

Adds 1 regression case in zod-schema.agent-defaults.test.ts covering:
- per-agent { codeMode: { enabled: true } } shape accepts
- boolean codeMode: true shape accepts
- full options object accepts
- unknown nested key still rejected (strict() preserved)
diff --git a/src/config/zod-schema.agent-defaults.test.ts b/src/config/zod-schema.agent-defaults.test.ts
@@ -342,6 +342,48 @@ describe("agent defaults schema", () => {
     expect(config.agents?.list?.[0]?.contextTokens).toBe(1_048_576);
   });
 
+  it("accepts per-agent tools.codeMode.enabled (#83388)", () => {
+    // docs/reference/code-mode.md describes `tools.codeMode.enabled: true` as
+    // settable at the agent level. Pre-fix AgentToolsSchema was .strict() and
+    // didn't include codeMode, so gateway startup rejected the documented
+    // shape with `agents.list.0.tools: Unrecognized key: "codeMode"`.
+    expectSchemaSuccess(
+      AgentEntrySchema.safeParse({
+        id: "test-agent",
+        tools: { codeMode: { enabled: true } },
+      }),
+    );
+    // Boolean form should also work, mirroring the top-level CodeModeSchema union.
+    expectSchemaSuccess(
+      AgentEntrySchema.safeParse({
+        id: "test-agent",
+        tools: { codeMode: true },
+      }),
+    );
+    // Full object form with documented options.
+    expectSchemaSuccess(
+      AgentEntrySchema.safeParse({
+        id: "test-agent",
+        tools: {
+          codeMode: {
+            enabled: true,
+            runtime: "quickjs-wasi",
+            timeoutMs: 5000,
+            languages: ["javascript"],
+          },
+        },
+      }),
+    );
+    // Unknown nested key still rejected (strict() preserved on the inner schema).
+    expectSchemaFailurePath(
+      AgentEntrySchema.safeParse({
+        id: "test-agent",
+        tools: { codeMode: { unknownKey: 1 } },
+      }),
+      "tools.codeMode",
+    );
+  });
+
   it("rejects non-positive contextTokens on agent entries and defaults", () => {
     expectSchemaFailurePath(
       AgentEntrySchema.safeParse({ id: "ops", contextTokens: 0 }),
diff --git a/src/config/zod-schema.agent-runtime.ts b/src/config/zod-schema.agent-runtime.ts
@@ -703,6 +703,12 @@ const MessageToolConfigSchema = z
 const AgentToolsSchema = z
   .object({
     ...CommonToolPolicyFields,
+    // #83388: per-agent code-mode enablement matches the doc surface
+    // (`docs/reference/code-mode.md` describes `tools.codeMode.enabled` as
+    // an "agent or runtime" config). The top-level ToolsSchema already
+    // accepts `codeMode`; mirror it here so a per-agent override can be
+    // tested without forcing fleet-wide behavior change.
+    codeMode: CodeModeSchema,
     elevated: z
       .object({
         enabled: z.boolean().optional(),
