fix(sdk): stop the overflow clip from dropping media and over-clipping

[Rajarshi Datta (rajarshidattapy)]

Fixes #4954. Reopens #5060, rewritten against #5563 as requested — this targets mdrxy/sdk/preview-note-conditional, so the diff here is only the overflow-clip fix on top of that branch.

When summarization's overflow fallback clips the trailing tool-result batch, a read_file result that returned an image became a text-only "Output was truncated" notice — the image was dropped with nothing pointing at where it went. Clipped media now leaves an explicit pointer to the original file_path, and small results that happen to sit in an over-budget batch are left alone instead of being rewritten and labelled truncated.

---

_slice_read_file_tm rebuilt the message from _extract_text_from_message, which returns text blocks only, so a media-only result collapsed to "" plus a notice. It also appended that notice unconditionally, including to results that were never truncated.

Two changes:

• The truncation notice is now emitted only when the text actually exceeds the slice size, and a separate notice covers removed media. Media payloads are still not carried over — this path runs because the batch overflowed the context window, so keeping the inline base64 would defeat the clip — but the notice names the original path, which still holds the file, so the agent can re-read it.
• _is_worth_clipping skips results already smaller than the slice size. Rewriting those cannot shrink the batch: on the generic path the replacement is a large-tool-result stub with a head+tail preview, which is frequently longer than the result it replaces. Everything big enough to matter is still clipped, so the aggregate reduction the post-clip retry depends on is unchanged.

On the aggregate guarantee: the narrower reading of "leave results untouched when possible" — clip largest-first and stop once the batch is back under the threshold — breaks test_summarization_clips_read_file_batch_on_overflow and its siblings, because the keep-derived threshold is not the model's real input limit, so stopping early leaves the retry still overflowing. Skipping only what is too small to shrink gets the "don't rewrite what wasn't the problem" behavior without weakening the reduction.

New unit tests in tests/unit_tests/middleware/test_overflow_clip.py cover the media pointer, small siblings surviving intact, no false truncation notice, and async parity. The existing end-to-end clip tests still pass unchanged.

Not addressed here: on the generic (non-read_file) path, _build_evicted_content still retains media blocks inline, so an image in some other tool's result won't shrink either. That helper is shared with the archive/eviction path where retaining media is deliberate (#3990), so changing it is a separate decision rather than something to fold into this fix.

[Rajarshi Datta (rajarshidattapy)]

Mason Daugherty (@mdrxy) done, can you check this once?

[Rajarshi Datta (rajarshidattapy)]

Mason Daugherty (@mdrxy) can you review this?