This PR won't actually fix #44840 since that person is using Claude-code via ACP and not the Zed agent, so this code path will never be exercised.

I'm not seeing this error when telling the model to call the mcp tool you mentioned:

Also I am not sure how it would fail since the model must provide invalid JSON input, it is not about the output of the tool.
Can you clarify when this is happening? Looking at the code you changed it does seem like there is something wrong, but I have not seen that error come up in practice. It would be great to have a way to reproduce it in a real world scenario.

This PR won't actually fix #44840 since that person is using Claude-code via ACP and not the Zed agent, so this code path will never be exercised.

This PR more likely fixes #40391. However, that was closed as a duplicate of #44840, which might be incorrect. In any case, we may need to reopen #40391, or I can just unlink this PR from the issue.

The issue I ran into involves using a custom OpenAI API compatibility layer. I configured the API as an OpenAI-compatible API in a Zed agent.
The error is coming from Claude's API, as you can see in the screenshot, and it is exactly what was reported in #40391.
To reproduce, I assume you either need access to an OpenAI API compatibility layer with Claude, or it might be reproducible with Claude's API directly in a Zed agent.

Also I am not sure how it would fail since the model must provide invalid JSON input, it is not about the output of the tool.
Can you clarify when this is happening?

Yes, it happens in the to_request method, when the request payload for the LLM is built. My first attempt to fix this actually involved filtering out incorrect tool uses in the to_request method:

for tool_result in self.tool_results.values() {
    // Only include tool_results that have a corresponding tool_use in the assistant message.
    // This prevents orphaned tool_result blocks that would cause API errors.
    if !included_tool_use_ids.contains(&tool_result.tool_use_id) {
        log::warn!(
            "Skipping orphaned tool_result with ID {} (no corresponding tool_use in assistant message)",
            tool_result.tool_use_id
        );
        continue;
    }
}

(See to_request if you want to look at the code of my first fix attempt.)

That approach didn't work properly due to retries on the LLM API call, and it felt wrong to me. So I dug deeper for the root cause, which led me to the proposed fix.

The cause of this error is that the Claude API is less forgiving about broken tool use/tool result pairs. Most APIs seem to ignore these cases, while Claude fails with a JSON validation error (as reported in #40391).

In any case, I think Zed should ensure it stores correct tool use/tool result pairs at all times.
Instead of adding the tool error as a tool result, we could try removing the tool use of the failed call entirely, but that doesn't feel correct either.

Note: I believe this happens in the real world when there are network glitches and an MCP answers with a 503 or similar response. The generic HTML error message then leads to a JSON parsing exception, breaking the entire conversation without the ability to retry. I haven't invested more time to prove this specific edge case, as I cannot see it happening in the logs.

@bennetbo was my previous comment answering your questions?

I took the time to do some further testing and I also found this issue to be reported in the discussion: #37653

The discussion seems to mix a couple of issues, though. Some issues are related to ACP threads, but for example this comment mentioned exactly the issue fixed by this PR (this one as well).

I tried to reproduce with Anthropic's native API and the API seems to be accepting requests with inconsistent parameters now, there are no "invalid request" errors anymore.
In addition, I tried with Claude Sonnet via Copilot as reported in this comment and this also seems to accept inconsistent requests on the API side.

So the issue seems only reproducible with some older model deployments.

I still believe it would be beneficial if Zed always sends consistent requests to the API.

Before this PR, handle_tool_use_json_parse_error_event() never added the ToolUse to pending_message.content - it only created the result. This left an orphaned tool_result without its matching tool_use.

Zed currently sends:

{
  "messages": [
    {
      "role": "assistant",
      "content": []  // Empty! No tool_use block
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_bdrk_01CvoePiwWyyT2HUfaJwtkiv",
          "content": "Error parsing input JSON: ..."
        }
      ]
    }
  ]
}

With this PR, Zed correctly sends:

{
  "messages": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "id": "toolu_bdrk_01CvoePiwWyyT2HUfaJwtkiv",
          "name": "tool_name",
          "input": {}
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_result",
          "tool_use_id": "toolu_bdrk_01CvoePiwWyyT2HUfaJwtkiv",
          "content": "Error parsing input JSON: ..."
        }
      ]
    }
  ]
}

This ensures tool_use and tool_result blocks are always properly paired, which is what Claude's API (and likely other providers) expect according to their specification.

It will also ensure better debugging experience for users, as the tool_use block provides more context about the tool that was used, making it easier to understand what went wrong.

relates to #48955

Hey, thanks again for the thorough investigation, I pushed a change to simplify the code a bit and merged main. Should be good to merge now. Thank you!