diff --git a/packages/opencode/src/tool/registry.ts b/packages/opencode/src/tool/registry.ts
index 35e378f080b..e6fc89f1af7 100644
--- a/packages/opencode/src/tool/registry.ts
+++ b/packages/opencode/src/tool/registry.ts
@@ -67,6 +67,11 @@ export namespace ToolRegistry {
         description: def.description,
         execute: async (args, ctx) => {
           const result = await def.execute(args as any, ctx)
+
+          if (typeof result !== 'string') {
+            return result
+          }
+
           const out = await Truncate.output(result, {}, initCtx?.agent)
           return {
             title: "",
diff --git a/packages/plugin/src/tool.ts b/packages/plugin/src/tool.ts
index f759c07d2b5..c4c74aacab7 100644
--- a/packages/plugin/src/tool.ts
+++ b/packages/plugin/src/tool.ts
@@ -1,25 +1,40 @@
 import { z } from "zod"
+import type { FilePart } from "@opencode-ai/sdk"
 
-export type ToolContext = {
+export type Metadata = {
+  [key: string]: any
+}
+
+export type ToolContext<M extends Metadata = Metadata> = {
   sessionID: string
   messageID: string
   agent: string
   abort: AbortSignal
-  metadata(input: { title?: string; metadata?: { [key: string]: any } }): void
-  ask(input: AskInput): Promise<void>
+  callID?: string
+  extra?: M
+  metadata(input: { title?: string; metadata?: M }): void
+  ask(input: AskInput<M>): Promise<void>
 }
 
-type AskInput = {
+export type AskInput<M extends Metadata = Metadata> = {
   permission: string
   patterns: string[]
   always: string[]
-  metadata: { [key: string]: any }
+  metadata: M
+}
+
+export type ExecuteResult<M extends Metadata = Metadata> = {
+  title: string
+  metadata: M
+  output: string
+  attachments?: FilePart[]
 }
 
-export function tool<Args extends z.ZodRawShape>(input: {
+export function tool<Args extends z.ZodRawShape, M extends Metadata = Metadata>(input: {
   description: string
   args: Args
-  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext): Promise<string>
+  execute(args: z.infer<z.ZodObject<Args>>, context: ToolContext<M>): Promise<string | ExecuteResult<M>>
+  formatValidationError?(error: z.ZodError): string
 }) {
   return input
 }