feat(plugin): align plugin tool types with built-in tool capabilities

[eXamadeus]

What does this PR do?

Fixes: #8327

Related: #8269, #12042

This PR aligns plugin tool types with the capabilities tools already have. Specifically:

• Exposes ToolContext fields to plugin tools: callID, extra, metadata(), and ask() to give plugins the correct context types
  • update: metadata() and ask() were added in fix: add missing metadata() and ask() defintions to ToolContext type #8269
• Adds ExecuteResult type allowing plugin tools to return structured result objects with title, metadata, output, and attachments instead of only plain strings
• Updates the registry to handle structured results from plugin tools, bypassing truncation when plugins return an ExecuteResult directly (assuming tools till truncate...we could add a check here?)
• Exports all useful intermediate-types so plugin authors can use them more ergonomically.

This enables plugins to provide richer tool responses with proper metadata updates, closer matching the flexibility of built-in tools.

How did you verify your code works?

• Added tests to ensure both string returns and object returns work as expected
• Ran TypeScript type checking
• Verified locally with a plugin in development that required proper metadata updates from plugin tools

The types all align nicely in the registry

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search, I found potential related PRs:

Potential Duplicates:

1. PR feat(plugin): align plugin tool types with built-in tool capabilities #9138 - "feat(plugin): align plugin tool types with built-in tool capabilities"

   • feat(plugin): align plugin tool types with built-in tool capabilities #9138
   • This appears to be a prior PR with the exact same title addressing the same feature alignment for plugin tool types

2. PR feat(plugin): add ToolResult type for structured tool responses #6544 - "feat(plugin): add ToolResult type for structured tool responses"

   • feat(plugin): add ToolResult type for structured tool responses #6544
   • Related to adding structured result types for plugin tools (the ExecuteResult type mentioned in your PR)

3. PR feat(plugin): add optional askPermission to ToolContext #6042 - "feat(plugin): add optional askPermission to ToolContext"

   • feat(plugin): add optional askPermission to ToolContext #6042
   • Related to exposing ToolContext fields to plugin tools

Recommendation: PR #9138 appears to be the most likely duplicate since it has the identical title. You should check if that PR is still open/active or if this PR (12050) supersedes it. PRs #6544 and #6042 appear to be related work on plugin tool capabilities but may already be merged.

[eXamadeus]

The bot is right, #9138 is the same PR and this one supersedes it. I changed base repos so I can maintain my fork easier.

#6544 is the essentially same fix, but without the test addition. I'm happy to merge, close this out, or otherwise combine efforts.

#6042 is unrelated. However, I think the changes #6042 proposes should probably be done through the SDK. The caveat is that #12042 needs to merge first. Then the Permission.ask endpoint would need to be exposed like #12046 does for Question.ask.