Python: document the shape contract of FunctionInvocationContext.result - #8283

Motivation & Context

FunctionInvocationContext.result is documented with one sentence that covers two
different contracts. After call_next() it holds FunctionTool.invoke's parsed output —
a list[Content] — but the same attribute accepts a raw value of any type when middleware
override the result. A middleware author reading "Function execution result. Can be
observed after calling call_next() to see the actual execution result" reasonably writes
if not isinstance(context.result, str): return, which silently never fires: no error, no
log line. The natural unit test for that middleware — build a context, assign
result = "text", assert — passes, because the write side really does accept a string.
Test and production disagree and nothing reports it.

The repo's own function-middleware sample models the wrong side of that contract, so the
mistake is inherited by imitation.

Description & Review Guide

• What are the major changes?

The docstrings now describe the attribute as what it is: untyped. The pipeline assigns
FunctionTool.invoke's output at the innermost link of the chain only
(FunctionMiddlewarePipeline.execute), so an outer middleware observes whatever the inner
ones left behind, not the tool's output. The docs say that, name result_parser=SKIP_PARSING
as the one thing that changes the parsed shape, and state the override rule that is easy to
get wrong: only list[Content] and str survive Content.from_function_result intact —
a bare Content or a partially rebuilt list is stringified into one text item.

shared_state_middleware.py was f-stringing the list[Content] and assigning the string
back, which sent a Python repr to the model instead of the tool's text. It now rebuilds
the text items.

before:  final wire text: '[Call #1] [<agent_framework._types.Content object at 0x106cec440>]'

after:   final wire text: '[Call #1] Weather in Seattle: sunny'

Captured by driving the real FunctionMiddlewarePipeline with a real @tool and
FunctionTool.invoke as the final handler, then wrapping the result the way
_finalize_function_result does.

• What is the impact of these changes?

No runtime behavior change in the framework — docstrings plus one sample. The sample's
output text changes, for the better.

test_middleware_context_result.py::test_function_middleware_post_execution_override
is worth a look while reviewing: its final_handler returns a str, so the middleware's
if "modify" in context.result passes there while the same check would be silently False
against FunctionTool.invoke's list[Content] in production. That is the issue's point
about stub-shaped middleware tests, in this repo's own suite. I left it alone rather than
grow this PR into a test rewrite.

Deliberately not covered: the issue's suggestion 2 (a public result_text accessor, which
would let security.py drop its private _ensure_content_list) and suggestion 3 (making
the type honest at the seam, a breaking change). Both are API decisions worth their own
issue rather than a doc PR. security.py's "typically list[Content]" hedge is left as
is — with the chain behavior now documented, that wording turns out to be accurate.

Related Issue

Part of #7575

Contribution Checklist

• The code builds clean without any errors or warnings (ruff check / ruff format --check clean)
• All unit tests pass, and I have added new tests where possible — no new tests: docstrings plus one sample, no framework behavior changes. I could not run the suite locally (no uv on this machine), leaving it to CI.
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.