feat(plugin): add ToolResult type for structured tool responses

[aryasaatvik]

Problem

Plugin tools could only return a plain string. This prevented:

• Structured responses with titles, metadata, and attachments
• Real-time streaming updates during long-running operations
• Subagent result propagation (tool counts, progress, etc.)

Solution

Add ToolResult interface and metadata() method to plugin SDK:

• ToolResult interface: { title, metadata, output, attachments? }
• ctx.metadata(): Emit streaming updates during execution
• Backward compatible: tools can still return plain strings
• Core extraction: Tool.Result interface for unified typing

Changes

• packages/plugin/src/tool.ts - Add ToolResult interface, metadata() method
• packages/opencode/src/tool/tool.ts - Extract Tool.Result interface
• packages/opencode/src/tool/registry.ts - Handle structured results in fromPlugin

Usage

import { tool, type ToolResult } from "@opencode-ai/plugin"

export default tool({
  description: "My tool",
  args: { input: z.string() },
  async execute(args, ctx): Promise<ToolResult> {
    ctx.metadata({ title: "Processing...", metadata: { step: 1 } })
    // ... work ...
    return {
      title: "Done",
      metadata: { count: 42 },
      output: "Result text"
    }
  }
})

Related

• Resolves feat(plugin): add ToolResult type for structured tool responses #7590

[aryasaatvik]

@rekram1-node can you take a look?

[github-actions]

Thanks for your contribution!

This PR doesn't have a linked issue. All PRs must reference an existing issue.

Please:

1. Open an issue describing the bug/feature (if one doesn't exist)
2. Add Fixes #<number> or Closes #<number> to this PR description

See CONTRIBUTING.md for details.

[eXamadeus]

So I made a very similar PR here #9138 because I apparently suck at searching through GitHub issues and PRs.

The only major difference is that I added a test to ensure it works as expected and added more of the missing fields to the ToolContext. Since you wrote the solution first, I am totally happy to close out my PR in favor of this one.

Or if you want to keep the test and types, feel free to merge that into this PR (and then I can close mine out). Obviously I'm a fan of your solution because we basically wrote the same thing 😆!