Match CodeMode guidance to exact return shapes

docs/code-mode.md

@@ -164,11 +164,12 @@ Reserve `print()` for supplementary logging: printed text is surfaced separately
 
 | Scenario | Return |
 |---|---|
-| No print output | Last expression value |
-| Final assignment with no trailing expression | `{}` |
+| No print output with a final expression | Last expression value |
+| Final assignment with no trailing expression or print output | `{}` |
 | Print output with no final expression | `{'output': '<printed text>'}` |
-| Print output with a final expression | `{'output': '<printed text>', 'result': <last expression>}` |
-| Multimodal content (e.g. images) | Returned natively for model processing |
+| Print output with a plain final expression | `{'output': '<printed text>', 'result': <last expression>}` |
+| Multimodal final expression with no print output | Returned natively for model processing |
+| Print output with a multimodal final expression | List with printed text followed by native multimodal content |
 
 ## REPL state
 

pydantic_ai_harness/code_mode/README.md

@@ -155,11 +155,12 @@ result
 
 | Scenario | Return |
 |---|---|
-| No print output | Last expression value |
-| Final assignment with no trailing expression | `{}` |
+| No print output with a final expression | Last expression value |
+| Final assignment with no trailing expression or print output | `{}` |
 | Print output with no final expression | `{"output": "<printed text>"}` |
-| Print output with a final expression | `{"output": "<printed text>", "result": <last expression>}` |
-| Multimodal content (e.g. images) | Returned natively for model processing |
+| Print output with a plain final expression | `{"output": "<printed text>", "result": <last expression>}` |
+| Multimodal final expression with no print output | Returned natively for model processing |
+| Print output with a multimodal final expression | List with printed text followed by native multimodal content |
 
 ## REPL state
 

pydantic_ai_harness/code_mode/_toolset.py

@@ -117,7 +117,8 @@ State is preserved between calls (REPL-style). Set `restart: true` to reset stat
 
 The last expression's value is automatically captured as the return value -- you do **not** need to \
 `print()` it. End the snippet with the value to return as a bare expression. A final assignment stores \
-the value but does not return it. When nothing is printed, `run_code` returns `{}`. For example:
+the value but does not return it. Without a final expression or print output, `run_code` returns `{}`. \
+For example:
 
 ```python
 result = some_expression
@@ -128,7 +129,8 @@ Avoid `print()` for return values as it produces Python string representations,
 Use `print()` only for supplementary logging or debug output.
 
 Returns the last expression's value directly. If `print()` was called, returns \
-`{"output": "<printed text>"}` and adds `"result": <last expression>` when one exists.\
+`{"output": "<printed text>"}` with no final expression and adds `"result": <last expression>` for a \
+plain final expression. Multimodal final expressions remain top-level in a list alongside the printed text.\
 """
 
 

tests/code_mode/test_code_mode.py

@@ -247,9 +247,10 @@ class TestCodeMode:
         assert description is not None
         assert 'End the snippet with the value to return as a bare expression.' in description
         assert 'result = some_expression\nresult' in description
-        assert '`run_code` returns `{}`' in description
+        assert 'Without a final expression or print output, `run_code` returns `{}`.' in description
         assert 'results = await asyncio.gather' not in description
-        assert 'adds `"result": <last expression>` when one exists' in description
+        assert 'adds `"result": <last expression>` for a plain final expression' in description
+        assert 'Multimodal final expressions remain top-level' in description
 
     async def test_run_code_function_examples_are_expressions(self) -> None:
         """Async, sync, and mixed function examples do not end on assignments."""