Summary

Multimodal file_read shipped in v0.22.0, but on the main streaming session path a tool-loaded image silently never reached the model — the agent was told "Image loaded for model-visible inspection" and then confabulated the contents (e.g. shown the akka.net logo, it described an invented "NetClaw dashboard wireframe").

Fixes #1264.

Root cause

The streaming tool-completion path hands its mutable accumulator to the media nudge and immediately clears it:

// LlmSessionActor.ApplyToolCallRecorded (same shape in CompleteToolBatch)
AddModelInputMediaNudge(_pendingModelInputMediaReferences); // stores THIS list instance
_pendingModelInputMediaReferences.Clear();                  // ...then empties it

SessionState.BuildNudgeMessage / AddUserMessage stored that list by reference into SerializableChatMessage.MediaReferences (an init property with no defensive copy). The .Clear() then emptied the nudge's media references before FireLlmCall → SessionMessageAssembler.Assemble → ChatMessageConverter.ToAiMessage hydrated them into DataContent. Net effect: text-only message, no image, hallucination.

Why it was sneaky:

• The tool genuinely succeeded (materialization copied the file to session media), so the existing handoff-failure warning never fired.
• Sub-agents were unaffected because they hydrate the image to DataContent immediately at nudge-creation; the main session defers hydration to assembly time (for prefix-cache stability), leaving a window for the Clear() to corrupt the aliased list.
• The non-streaming completion path passes a fresh list and is unaffected — but the CLI/headless and normal chat use streaming, hence the "always" reproduction.

Fix

Defensively snapshot the caller's list ([.. mediaReferences]) at the two SessionState message constructors, so the immutable persistence message owns its own copy regardless of caller behavior. Two-line production change, with comments documenting the aliasing/clear hazard.

Verification

• Unit regression tests (SessionStateTests): build a List, hand it to AddSystemNudge/AddUserMessage, .Clear() it, assert the message still carries the media reference. Fail without the snapshot.
• Actor-level integration test (LlmSessionImageDeliveryTests): drives a streaming file_read image load through LlmSessionActor and asserts image DataContent reaches the chat client on the next LLM call. Confirmed it fails without the fix (exact message: "Tool-loaded image never reached the model…") and passes with it — this was the missing coverage that let the bug ship.
• End-to-end: ran a patched daemon against a real vision model — the agent now correctly describes the image, and the trace prompt dump shows DataContent mediaType=image/png on the wire.
• Full Netclaw.Actors.Tests suite: 2175 passing. dotnet slopwatch analyze: 0 issues. Copyright headers verified.

Files

• src/Netclaw.Actors/Sessions/SessionState.cs — the fix
• src/Netclaw.Actors.Tests/Sessions/SessionStateTests.cs — unit regression tests
• src/Netclaw.Actors.Tests/Sessions/LlmSessionImageDeliveryTests.cs — new integration test

Follow-up

Audio/video model input is out of scope for this fix (images only today) and is tracked separately in #1266.