fix: document run_stream() event contract and warn on thinking + streaming

[sjwan01]

Summary

The run_stream() event contract was undocumented and misleading, and the default thinking_enabled=True silently inherits a pydantic-ai streaming defect.

Three verified problems (real-API reproduction on deepseek-v4-flash, pydantic-ai 2.22.0 and 2.25.0):

1. Upstream defect (not fixable here): thinking + streaming + tools nondeterministically drops post-tool-call text — the agent loop terminates after a tool returns (no second ModelResponse); run_end.output is not a reliable fallback. Non-streaming run() is always complete.
2. Contract gap: run_stream() forwards only chunks yielded by extensions implementing on_agent_runner_event_stream; chain-mode events never reach the consumer. A bare consumer receives only run_end. The old docstring said "yields events one by one", which misled first-time users.
3. Default value: thinking_enabled=True (default) inherits problem 1.

Changes (5 files, +164/−14)

• run_stream() docstring — precise event contract: runtime events delivered to streaming extensions; chain-mode events never forwarded; bare consumer receives only run_end.
• Extension.on_agent_runner_event_stream docstring — cross-references the contract; notes that without it no token/tool events reach callers.
• AgentRunner.run_stream() warns once (first iteration) when thinking_enabled=True — the intent to stream is only known at call time, so the warning fires when the caller actually consumes the stream, not at construction. run() never warns.
• README Known issues — records the pydantic-ai defect (verified mechanism + versions) and the non-streaming run() workaround; fixes the misleading Public API description; documents the streaming-extension hook.
• Tests (TDD) — 4 new tests for the warning (fires once, dedup, run() silence, thinking_enabled=False silence) + 1 contract test (chain-only extension yields nothing to the consumer).

Verification

• make check: ruff ✅ mypy strict ✅ 146 passed, 7 skipped (7 = Postgres, run in CI)
• CI will run the full matrix (Python 3.11–3.14) including the Postgres tests.

Known limits

• This is documentation + warning only — the upstream pydantic-ai defect (problem 1) is not fixed here (blocked upstream). The warning and README make the hazard visible before it is hit; run() or thinking_enabled=False are the workarounds.
• A runtime path for bare consumers to observe token/tool events (run_with_events()) is a separate proposal, not part of this PR.