pause_turn with web_search: docs say re-submit response as-is, but API returns 400 — are we missing something?

[ujjwaljainnn]

The server tools docs say to handle pause_turn by passing the response back as-is:

"Pass the paused response back as-is in a subsequent request to let Claude continue its turn."

When we do exactly that, we get a 400. Wanted to check if we're misunderstanding something.

What happens

1. API returns pause_turn with an unpaired server_tool_use block (no web_search_tool_result)
2. We re-submit with that content in the assistant turn — serialized correctly as {"type": "server_tool_use", ...} (verified via SDK's _transform.py)
3. API rejects with:

messages.1: `web_search` tool use with id `srvtoolu_01UkjByNZ6pFvVLGAjWnYBjt` 
was found without a corresponding `web_search_tool_result` block

The API's own validator is rejecting the block that the API itself produced and told us to send back.

Questions

1. Is there something the docs are missing — a flag, header, or different message structure required for pause_turn resumption?
2. Does this behave differently with web_search_20260209?
3. Does re-submission only work when resetting to [user, paused_assistant] (as in the docs example), and not when appending to a multi-turn history?

Current workaround

We strip server_tool_use blocks before re-submitting, letting the model re-issue the search from scratch. This avoids the 400 but likely abandons any in-flight search state. Happy to be corrected if there's a proper way to handle this.

[nightcityblade]

Hi, I'd like to work on this. I'll submit a PR shortly.

[dtmeadows-ant]

@ujjwaljainnn sorry for the long delay here. You weren't missing a flag or header, and it's the same for web_search_20250305 and web_search_20260209: an assistant turn that ends in an unpaired server_tool_use is accepted only when it is the last message in the request (with the same tools still present) — the API then runs the pending search and carries the turn on. The messages.N: … without a corresponding web_search_tool_result block 400 is what you get when anything (typically a "continue"-style user message) is appended after the paused content; appending to a longer multi-turn history is fine as long as the paused assistant message stays last. Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/server-tools

while response.stop_reason == "pause_turn":
    # paused assistant content goes last — no user turn after it
    messages.append({"role": "assistant", "content": response.content})
    response = client.messages.create(
        model=model, max_tokens=1024, tools=tools, messages=messages  # same tools as before
    )