libtmux_mcp.middleware.ToolErrorResultMiddleware

Description#

Replaces the stock ErrorHandlingMiddleware behavior for tools/call only. The stock transform_errors=True path funnels every non-MCP exception through a -32603 catch-all, so agents received "Internal error: Pane not found: %5" — the transform mangled every expected failure message. This subclass intercepts tool-call exceptions first (on_call_tool is the innermost hook of a middleware's chain) and returns _error_tool_result instead; non-tool messages fall through to the inherited on_message.

That inherited transform matches the not-found exception types by exact class -- error_type in (FileNotFoundError, KeyError, NotFoundError) -- so only an unknown resource URI, which fastmcp raises as NotFoundError itself, reaches a client as -32002. The tmux:// handlers raise ResourceError for a missing session, and path screening raises ResourceSecurityError, a NotFoundError subclass; neither is an exact match, so both arrive as -32603 "Internal error" -- the code that tells a client the server is broken, for what is really an absent or disallowed target.

Logging honors FastMCPError.log_level (fastmcp >= 3.3): the expected failures demoted to WARNING by ExpectedToolError no longer get re-shouted at ERROR by the stock _log_error. Argument-schema validation failures — raised by fastmcp before tool code can classify them — are treated as expected too (see _is_schema_validation_error), and when the rejected arguments include unexpected names the error result carries a synthesized suggestion telling the agent which names to drop or fix (see _error_tool_result).

Ordering invariant: must sit outside AuditMiddleware and ToolsetMiddleware. Both depend on exception semantics: audit detects failures by catching them, and toolset denials must propagate as exceptions for audit to record them. Converting the exception to a result any deeper in the stack would silently break both.