Document every CodeMode return shape

docs/code-mode.md

@@ -166,7 +166,8 @@ Reserve `print()` for supplementary logging: printed text is surfaced separately
 |---|---|
 | No print output | Last expression value |
 | Final assignment with no trailing expression | `{}` |
-| With print output | `{'output': '<printed text>', 'result': <last expression>}` |
+| 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 |
 
 ## REPL state

pydantic_ai_harness/code_mode/README.md

@@ -157,7 +157,8 @@ result
 |---|---|
 | No print output | Last expression value |
 | Final assignment with no trailing expression | `{}` |
-| With print output | `{"output": "<printed text>", "result": <last expression>}` |
+| 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 |
 
 ## REPL state

pydantic_ai_harness/code_mode/_toolset.py

@@ -127,8 +127,8 @@ result
 Avoid `print()` for return values as it produces Python string representations, not structured data. \
 Use `print()` only for supplementary logging or debug output.
 
-Returns the last expression's value directly. If `print()` was also called, returns \
-`{"output": "<printed text>", "result": <last expression>}`.\
+Returns the last expression's value directly. If `print()` was called, returns \
+`{"output": "<printed text>"}` and adds `"result": <last expression>` when one exists.\
 """
 
 

tests/code_mode/test_code_mode.py

@@ -249,6 +249,7 @@ class TestCodeMode:
         assert 'result = some_expression\nresult' in description
         assert '`run_code` returns `{}`' in description
         assert 'results = await asyncio.gather' not in description
+        assert 'adds `"result": <last expression>` when one exists' in description
 
     async def test_run_code_function_examples_are_expressions(self) -> None:
         """Async, sync, and mixed function examples do not end on assignments."""