feat: public streaming + should_finalize contracts for final_turn_only

[johnnichev]

Closes #174.

The problem

Two behaviors that streaming integrators MUST rely on were source-only knowledge — a future refactor could flip them with no type/signature change and no test signal.

1. Streaming contract (documented + tested + strengthened)

Guarantee: final_turn_only=True + astream() never emits the structured answer as content chunks — on any path. Pinned clause-by-clause in tests/agent/test_structured_streaming_contract.py:

• Without single_pass: loop prose streams; the synthesis call is non-streaming; StreamChunk(event="structured_synthesis_start") fires iff a synthesis call is made (reuse and should_finalize-skip paths emit no event).
• With single_pass: content chunks are now suppressed — with the schema riding natively on every loop call, any content the model emits is the JSON envelope by construction. Tool-call chunks still stream for activity display. This closes the leak that was previously a documented caveat, which is exactly what makes the issue's "brackets on BOTH paths" ask unnecessary: there is no synthesis content to bracket, on either path.

The event/no-leak semantics are documented in AGENT.md as an explicit public contract and in the single_pass docstring.

2. should_finalize messages contract (documented + tested + backed)

Documented in the docstring and AGENT.md: messages is the run's conversation view at convergence — prior history (with memory), this turn's USER message(s), the ASSISTANT tool-call messages, and one Message(role=TOOL) per executed tool with tool_name, tool_call_id, and tool_result always populated.

To make that last guarantee true rather than aspirational: _append_tool_result now defaults tool_result to the message content, so error results and policy denials populate it too (previously only the success path did — an integrator matching on tool_result would have silently missed error turns).

Tests

13 contract tests: single_pass no-leak + tool-call chunks still visible, prose-streams/JSON-doesn't on the synthesis path, event-iff-synthesis across all three convergence paths, event chunks are content-free, predicate message-view contents (run + astream), and the tool_result invariant on success/parallel/error paths (error path was RED before the fix).

Full suite: 7,605 passed, 205 skipped (py3.12). ruff clean.

Behavior change note: single_pass + astream() stops streaming JSON as content — v1.2.0's documented caveat becomes a guarantee. single_pass is 0 days old and opt-in; this is the fix its one consumer asked for.

https://claude.ai/code/session_01L1JWChKMs9yTyK92qquhJa

[johnnichev]

Self-review (high-effort multi-agent review, 10 verified findings) — addressed in d0a27a3:

1. ✅ The headline finding: my "structured answer NEVER streams on any path" guarantee was false on the reuse path — without single_pass, the loop streams model output normally, so a converged answer that validates has already streamed before reuse decides. Contract reworded precisely, and a new StreamChunk(event="structured_reuse") fires at the reuse decision so chat surfaces can convert/retract the just-streamed bubble. The reuse-leak assertion the original test conspicuously avoided is now present and pins the honest behavior.
2. ✅ tool_call_id de-guaranteed (text-parsed tool calls have id=None); the guaranteed pair is tool_name + tool_result.
3. ✅ Legacy sessions: Message.from_dict normalizes TOOL messages persisted before this change (tool_result=None → content), so the "always populated" claim holds for restored histories; tested.
4. ✅ Changelog: single_pass suppression + tool_result unification moved under ### Changed with migration notes.
5. ⚠️→✅ The tool_result is None sentinel (PLAUSIBLE finding): not used anywhere in-repo; unified semantics kept, breaking-use migration documented in the Changed entry.
6. ✅ Policy-denial invariant test added (was untested despite being claimed).
7. ✅ _append_tool_result's now-redundant tool_result param removed.
8. ✅ single_pass mode named once (ctx.single_pass_active) instead of three inline reconstructions.
9. ✅ Contract test file self-contained (no cross-test-module imports).
10. ✅ Version pin dropped from the AGENT.md section header (changelog owns versioning).

Full suite: 7,607 passed, 205 skipped. CI green on the update pending.

[johnnichev]

Second self-review at max effort (39 agents, 15 verified findings including nits) — all addressed in 30edc6c. The big one: the contract was only implemented on the astream() chunk surface; three other consumption paths violated it:

1. ✅ stream_handler leak (run/arun): synthesis turns and single_pass loop turns no longer feed the token callback — mutation-verified tests (the first version of these tests passed trivially because the handler channel needs stream=True; caught and strengthened).
2. ✅ Fallback path zero-chunk stream: providers without native async streaming now yield tool-call chunks in astream's acomplete fallback, so single_pass suppression can't render a silent stream — mutation-verified (also caught a test-fake bug: SharedFakeProvider.__init__ shadows subclass class-attributes).
3. ✅ serve SSE dropped event chunks: forwarded as {"type": "event", ...} records now; test added; contract text extended to name all three surfaces.
4. ✅ tool_result design REVERTED to the sharper contract: success ⇒ result text, error/policy/coherence denial ⇒ None — the None marker is the documented failure discriminator (v1.2-compatible, no breaking change). from_dict round-trip fidelity restored on the @stable API; caller-seeded TOOL messages scoped out; Message docstring updated. This resolves findings 4/5/6/7-adjacent cleanly instead of patching around the unification.
5. ✅ Wording nits, all fixed: synthesis event is once-per-run (validation retries don't re-emit), structured_reuse qualified as non-single_pass consistently across the three doc surfaces, SYSTEM context injections added to the messages enumeration, Since: v1.3.0 markers, changelog restructured (Changed section scoped to the @beta single_pass surface), Case C pins no structured_reuse in single_pass, llms-full.txt regenerated.

Also filed #176: 5 pre-existing starlette auth test failures on clean main, invisible in CI (no [serve] extra in the matrix) — unrelated to this PR.

Local suite: 7,787 passed; the only failures are the pre-existing #176 set (verified failing on clean HEAD, never run in CI).