refactor(question): tool-arg errors at the boundary, drop redundant inner decode (#28570)

packages/opencode/test/tool/tool-define.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect } from "bun:test"
-import { Effect, Layer, Schema } from "effect"
+import { Cause, Effect, Exit, Layer, Schema } from "effect"
 import { Agent } from "../../src/agent/agent"
 import { MessageID, SessionID } from "../../src/session/schema"
 import { Tool } from "@/tool/tool"
@@ -10,6 +10,22 @@ const it = testEffect(Layer.mergeAll(Truncate.defaultLayer, Agent.defaultLayer))
 
 const params = Schema.Struct({ input: Schema.String })
 
+function makeCtx(): Tool.Context {
+  return {
+    sessionID: SessionID.descending(),
+    messageID: MessageID.ascending(),
+    agent: "build",
+    abort: new AbortController().signal,
+    messages: [],
+    metadata() {
+      return Effect.void
+    },
+    ask() {
+      return Effect.void
+    },
+  }
+}
+
 function makeTool(id: string, executeFn?: () => void) {
   return {
     description: "test tool",
@@ -79,19 +95,7 @@ describe("Tool.define", () => {
           },
         }),
       )
-      const ctx: Tool.Context = {
-        sessionID: SessionID.descending(),
-        messageID: MessageID.ascending(),
-        agent: "build",
-        abort: new AbortController().signal,
-        messages: [],
-        metadata() {
-          return Effect.void
-        },
-        ask() {
-          return Effect.void
-        },
-      }
+      const ctx = makeCtx()
       const tool = yield* info.init()
       const execute = tool.execute as unknown as (args: unknown, ctx: Tool.Context) => ReturnType<typeof tool.execute>
 
@@ -101,4 +105,49 @@ describe("Tool.define", () => {
       expect(calls).toEqual([{ count: 5 }, { count: 7 }])
     }),
   )
+
+  // Regression for #28438: the wrap is the canonical "untyped → typed" boundary.
+  // When the LLM emits a tool call with a payload that fails the parameter
+  // schema, the wrap must surface a typed `Tool.InvalidArgumentsError` whose
+  // `.message` is the actionable prose the AI SDK feeds back to the model.
+  it.effect("invalid args surface as Tool.InvalidArgumentsError with friendly message and JSON path", () =>
+    Effect.gen(function* () {
+      const parameters = Schema.Struct({
+        questions: Schema.Array(
+          Schema.Struct({
+            question: Schema.String,
+            options: Schema.Array(Schema.String),
+          }),
+        ),
+      })
+      const info = yield* Tool.define(
+        "qtest",
+        Effect.succeed({
+          description: "test tool",
+          parameters,
+          execute() {
+            return Effect.succeed({ title: "ok", output: "ok", metadata: { truncated: false } })
+          },
+        }),
+      )
+      const tool = yield* info.init()
+      const execute = tool.execute as unknown as (args: unknown, ctx: Tool.Context) => ReturnType<typeof tool.execute>
+
+      // Missing required `question` field on the first questions[] entry.
+      const exit = yield* execute({ questions: [{ options: ["a"] }] }, makeCtx()).pipe(Effect.exit)
+      expect(Exit.isFailure(exit)).toBe(true)
+      if (!Exit.isFailure(exit)) return
+
+      // The wrap ends with Effect.orDie, so the failure lives in the cause as a
+      // defect. Recover the typed instance from there.
+      const die = exit.cause.reasons.find(Cause.isDieReason)
+      const error = die?.defect
+      expect(error).toBeInstanceOf(Tool.InvalidArgumentsError)
+      const args = error as Tool.InvalidArgumentsError
+      expect(args.tool).toBe("qtest")
+      expect(args.message).toContain("qtest tool was called with invalid arguments")
+      expect(args.message).toContain("Please rewrite the input")
+      expect(args.message).toContain(`["questions"][0]["question"]`)
+    }),
+  )
 })