fix(core): enforce tool output truncation variants

packages/opencode/src/config/config.ts

@@ -253,17 +253,22 @@ export const Info = Schema.Struct({
     }),
   ),
   tool_output: Schema.optional(
-    Schema.Struct({
+    Schema.Union([
-      truncate: Schema.optional(Schema.Boolean).annotate({
+      Schema.Struct({
-        description: "Enable truncating tool output that exceeds the configured limits (default: true)",
+        truncate: Schema.Literal(false).annotate({ description: "Disable tool output truncation" }),
+      }).annotate({ parseOptions: { onExcessProperty: "error" } }),
+      Schema.Struct({
+        truncate: Schema.optional(Schema.Literal(true)).annotate({
+          description: "Enable truncating tool output that exceeds the configured limits (default: true)",
+        }),
+        max_lines: Schema.optional(PositiveInt).annotate({
+          description: "Maximum lines of tool output before it is truncated and saved to disk (default: 2000)",
+        }),
+        max_bytes: Schema.optional(PositiveInt).annotate({
+          description: "Maximum bytes of tool output before it is truncated and saved to disk (default: 51200)",
+        }),
       }),
-      max_lines: Schema.optional(PositiveInt).annotate({
+    ]),
-        description: "Maximum lines of tool output before it is truncated and saved to disk (default: 2000)",
-      }),
-      max_bytes: Schema.optional(PositiveInt).annotate({
-        description: "Maximum bytes of tool output before it is truncated and saved to disk (default: 51200)",
-      }),
-    }),
   ).annotate({
     description:
       "Configure tool output truncation. When output exceeds either limit, the full text is written to the truncation directory and a preview is returned.",

packages/opencode/src/skill/prompt/customize-opencode.md

@@ -23,6 +23,10 @@ shape before writing config, **fetch that URL and read the schema directly**
 rather than guessing. opencode hard-fails on invalid config, so the cost of a
 wrong shape is a broken startup.
 
+The full schema is large. Prefer using JavaScript or Bash to fetch and extract
+the relevant property definition instead of reading the entire schema into
+context when you only need to check one setting.
+
 Independently, every `opencode.json` should declare
 `"$schema": "https://opencode.ai/config.json"` so the user's editor catches
 mistakes as they type.
@@ -126,7 +130,7 @@ Every field is optional.
     "mcp_timeout": 30000
   },
 
-  "tool_output": { "truncate": false, "max_lines": 200, "max_bytes": 8192 },
+  "tool_output": { "max_lines": 200, "max_bytes": 8192 },
 
   "compaction": { "auto": true, "tail_turns": 15 }
 }
@@ -140,7 +144,6 @@ Shape notes worth being explicit about:
 - `plugin` is an array of strings or `[name, options]` tuples, not an object.
 - `mcp[name].command` is an array of strings, never a single string. `type` is required.
 - `permission` is either a string action or an object keyed by tool name.
-- `tool_output.truncate: false` disables shared tool output truncation; use `max_lines` and `max_bytes` to override its thresholds.
 
 ## Skills
 

packages/opencode/test/config/config.test.ts

@@ -1455,6 +1455,21 @@ test("config parser preserves permission order while rejecting unknown top-level
   }
 })
 
+test("tool_output only accepts thresholds when truncation is enabled", () => {
+  expect(ConfigParse.schema(Config.Info, { tool_output: { truncate: false } }, "test").tool_output).toEqual({
+    truncate: false,
+  })
+  expect(
+    ConfigParse.schema(Config.Info, { tool_output: { max_lines: 200, max_bytes: 8192 } }, "test").tool_output,
+  ).toEqual({
+    max_lines: 200,
+    max_bytes: 8192,
+  })
+  expect(() =>
+    ConfigParse.schema(Config.Info, { tool_output: { truncate: false, max_lines: 200, max_bytes: 8192 } }, "test"),
+  ).toThrow()
+})
+
 // MCP config merging tests
 
 it.instance("project config can override MCP server enabled status", () =>

packages/sdk/js/src/v2/gen/types.gen.ts

@@ -1294,11 +1294,21 @@ export type Config = {
   enterprise?: {
     url?: string
   }
-  tool_output?: {
+  /**
-    truncate?: boolean
+   * Configure tool output truncation. When output exceeds either limit, the full text is written to the truncation directory and a preview is returned.
-    max_lines?: number
+   */
-    max_bytes?: number
+  tool_output?:
-  }
+    | {
+        /**
+         * Disable tool output truncation
+         */
+        truncate: false
+      }
+    | {
+        truncate?: true
+        max_lines?: number
+        max_bytes?: number
+      }
   compaction?: {
     auto?: boolean
     prune?: boolean

packages/web/src/content/docs/config.mdx

@@ -385,6 +385,8 @@ To disable shared tool output truncation, set `truncate` to `false`:
 }
 ```
 
+`truncate: false` cannot be combined with `max_lines` or `max_bytes`; thresholds only apply when truncation is enabled.
+
 ---
 
 ### Models