fix(tools): preserve tool flow when caller appends unrelated messages (closes #1536)

[0xdeadd]

Closes #1536.

The bug

The reporter found that calling append_messages inside the tool_runner loop body causes an infinite tool-call loop. Their root-cause analysis is correct: any append_messages call sets _messages_modified = True, which causes __run__ to skip the auto-append of the assistant message + tool result. The next iteration sends a request with no tool result, the model re-asks for the same tool call, repeat forever.

Why the flag is wrong

_messages_modified was conflating two distinct use cases:

1. Modifying tool results — caller appends a custom tool_result to override the SDK's auto-generated one. Auto-append should skip.
2. Append an unrelated user message ([Bug] append_messages() inside tool runner loop causes infinite loop (advanced usage docs example) #1536) — caller appends, say, "be concise in your response" between iterations. The tool result still needs to be threaded back in, otherwise the loop breaks.

A single boolean can't distinguish these — one means "I handled the tool flow," the other means "I added context, please continue normally."

The fix

Replace the flag-based gate with a content-based check: auto-append is skipped only when the last user message already contains a tool_result block whose tool_use_id matches the one we were about to write. Unrelated messages don't match, so the tool flow stays correctly threaded.

Applied symmetrically to sync and async __run__.

Tests

• New unit test test_tool_response_already_appended_detects_matching_tool_result covers:
  • Empty history → no match
  • History with an unrelated user message (the [Bug] append_messages() inside tool runner loop causes infinite loop (advanced usage docs example) #1536 case) → no match → auto-append still runs
  • History with a matching tool_result (modifying-tool-results case) → match → auto-append skipped
  • Mismatched tool_use_id → no match
• Full tests/lib/tools/test_runners.py passes: 13 passed, 1 xfailed.
• Existing test_custom_message_handling xfail is preserved — that pattern depends on additional re-threading logic (inserting the assistant message before the caller's tool result) and snapshot updates that are out of scope for this fix.

Repro from the issue

The reporter's repro (the "be concise" message inside the loop body) now terminates correctly: the tool result is auto-appended, the model sees its own tool answer, and produces the final text on the next iteration. Verified locally.