feat(plugin): add tool.execute.error hook

[kynnyhsap]

Add a new plugin hook that fires when tool execution throws an error, allowing plugins to log, modify, or recover from errors.

Fixes #10027

What Changed

Added tool.execute.error hook to the plugin system. The hook receives:

• input: tool name, session ID, call ID, and args
• output: mutable object with error and optional result

Plugins can either modify the error or provide a fallback result.

Example Usage

export default {
  hooks: {
    "tool.execute.error": async (input, output) => {
      console.error(`Tool ${input.tool} failed:`, output.error.message)

      // Option 1: Modify error message
      if (output.error.message.includes("rate limit")) {
        output.error = new Error("Service temporarily unavailable, please try again")
      }

      // Option 2: Recover from error by providing a result
      if (input.tool === "read" && output.error.message.includes("not found")) {
        output.result = {
          title: "File not found",
          output: `The file ${input.args.filePath} does not exist.`,
          metadata: {}
        }
      }
    }
  }
}

How I Verified

• Typecheck passes
• Manually tested hook invocation on tool errors

[github-actions]

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

The search results only show PR #10028 (the current PR itself) and other unrelated PRs about bash tool schema, memory leaks, Prometheus metrics, and shell resolution.

No duplicate PRs found

[kynnyhsap]

Manual Testing

Create a test plugin at .opencode/plugin/test-error-hook.ts:

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

export const TestErrorHookPlugin: Plugin = async (ctx) => {
  return {
    // Tool that always fails
    tool: {
      failing_tool: tool({
        description: "A tool that always throws an error for testing",
        args: {
          message: tool.schema.string().describe("Error message to throw"),
        },
        async execute(args) {
          throw new Error(`Intentional error: ${args.message}`)
        },
      }),
    },

    // Error hook to catch and handle errors
    "tool.execute.error": async (input, output) => {
      // Test 1: Modify the error message
      if (input.tool === "failing_tool" && input.args.message === "modify-me") {
        output.error = new Error("Modified error: The original error was intercepted and changed!")
      }

      // Test 2: Recover from error by returning a result
      if (input.tool === "failing_tool" && input.args.message === "recover-me") {
        output.result = {
          title: "Recovered from error",
          output: "The error was caught and handled gracefully by the plugin!",
          metadata: { recovered: true },
        }
      }
    },
  }
}

Test Prompts

1. Normal error (hook logs but doesn't modify):

   Use the failing_tool with message "normal-error"
   

   Expected: Error "Intentional error: normal-error"

2. Error modification:

   Use the failing_tool with message "modify-me"
   

   Expected: Error "Modified error: The original error was intercepted and changed!"

3. Error recovery:

   Use the failing_tool with message "recover-me"
   

   Expected: Successful result "The error was caught and handled gracefully by the plugin!"

[github-actions]

Closing this pull request because it has had no updates for more than 60 days. If you plan to continue working on it, feel free to reopen or open a new PR.