Custom plugin tools receive undefined args when AI omits optional parameters (same root cause as #9020)

[gilisho]

Description

Custom tools defined via @opencode-ai/plugin receive undefined for optional args when the AI model omits them. This is the same root cause as #9020, which was fixed for MCP tools in #11203 but not for custom plugin tools.

Steps to Reproduce

1. Define a custom tool with an optional parameter that has a Zod .default():

import { tool } from "@opencode-ai/plugin";
import { randomUUID } from "crypto";

export default tool({
  description: "Generate one or more UUID v4s.",
  args: {
    count: tool.schema.number().min(1).max(10).default(1).describe("Number of UUIDs to generate."),
  },
  async execute(args) {
    return Array.from({ length: args.count }, () => randomUUID()).join("\n");
  },
});

2. When the AI calls this tool without specifying count, the tool receives { count: undefined } (or {})
3. The Zod .default(1) is never applied, so args.count is undefined
4. Array.from({ length: undefined }) produces an empty array, and the tool returns ""

Expected Behavior

args.count should be 1 (the Zod default), or at minimum the args should be coerced from undefined to {} so Zod can apply defaults during parsing.

Actual Behavior

args.count is undefined. The Zod .default() is never triggered because the args are passed directly to execute() without being parsed through the Zod schema.

Context

The fix in #11203 patched this for MCP tools in packages/opencode/src/mcp/index.ts:

- arguments: args as Record<string, unknown>,
+ arguments: (args || {}) as Record<string, unknown>,

But custom plugin tools go through a different code path (likely packages/opencode/src/tool/) where the same coercion was not applied.

Workaround

Handle undefined manually in the execute function:

async execute(args) {
  const count = args.count ?? 1;
  return Array.from({ length: count }, () => randomUUID()).join("\n");
},

Environment

• OpenCode version: 1.2.27
• Model: Claude Sonnet 4.6

[gilisho]

Root Cause Analysis

Dug into the OpenCode source — there are actually two bugs causing this:

Bug 1: fromPlugin() in registry.ts skips Zod parsing entirely

Plugin tools created via fromPlugin() bypass Tool.define() and return raw Tool.Info objects. Args from the AI model are passed directly to execute() without any Zod parsing:

// packages/opencode/src/tool/registry.ts — fromPlugin()
execute: async (args, toolCtx) => {
  const pluginCtx = { ... } as unknown as PluginToolContext
  const result = await def.execute(args as any, pluginCtx)  // <-- args passed raw, no Zod parse
}

Since Zod never sees the args, .default() values are never applied.

Bug 2: Tool.define() in tool.ts parses but discards the result

Even for built-in tools that go through Tool.define(), the Zod .parse() result is used for validation only — the parsed value (with defaults applied) is thrown away:

// packages/opencode/src/tool/tool.ts — Tool.define()
try {
  toolInfo.parameters.parse(args)  // <-- parsed result discarded!
} catch (error) { ... }
const result = await execute(args, ctx)  // <-- original args, no defaults

Additionally, in prompt.ts, the Zod schema is converted to JSON Schema via jsonSchema() for the AI SDK, and JSON Schema has no concept of Zod defaults — so no defaults are applied at that layer either.

Suggested Fix

Fix 1 — registry.ts fromPlugin(): parse args through the Zod schema before executing:

- const result = await def.execute(args as any, pluginCtx)
+ const parsed = z.object(def.args).parse(args || {})
+ const result = await def.execute(parsed as any, pluginCtx)

Fix 2 — tool.ts Tool.define(): use the parsed result instead of discarding it:

+ let parsed: typeof args
  try {
-   toolInfo.parameters.parse(args)
+   parsed = toolInfo.parameters.parse(args)
  } catch (error) { ... }
- const result = await execute(args, ctx)
+ const result = await execute(parsed, ctx)

Fix 1 addresses plugin tools specifically. Fix 2 makes Zod defaults work for all tools (including built-in ones).