Summary

Fixes #44239

The transform_llm_output hook fires in finalize_turn after _persist_session, and its result is never written back into the assistant message. The user sees the transformed text for the current turn, but result["messages"], the JSON session log, and the SQLite session DB all keep the raw model output — which is then replayed as context on the next turn or after a session resume. The whole response_transformed delivery chain (gateway message edit, ACP final-response delivery) ensures the transformed text is what the user sees, so the raw text resurfacing on resume is clearly unintended.

Changes — agent/turn_finalizer.py

• Move _persist_session after the transform_llm_output hook block.
• Before persisting, when the response was transformed, sync final_response back into the turn's last assistant text message via a new _sync_final_response_to_last_assistant helper. The sync walks backwards only within the current turn (stops at the user-message boundary, mirroring the reasoning extraction) and never rewrites a tool-call or non-text (multimodal) assistant message.
• The empty-response scaffolding drop keeps running early (before the turn-exit diagnostic log reads messages[-1], exactly as before), so a transformed recovery/explainer response can never resurrect a message the drop removed.
• Persistence intentionally stays before post_llm_call: that hook is observability-only per docs/observability/README.md (its return value is ignored in code — there is no override path, contrary to what [Bug]: transform_llm_output and post_llm_call hooks both produce final_response/history mismatch — same root cause as #14894 #44239 and [Bug]: post_llm_call response overrides are applied after persistence, causing final_response/history mismatch #14894 assume), and its plugins may read the session store expecting the completed turn to be present. This also means this PR takes a deliberately different approach from fix(agent): run post_llm_call hook before session persistence #14913, which moves persistence below post_llm_call.

Scope notes

While verifying #44239 I found parts of it don't match the code:

• The post_llm_call "override_response path" it describes does not exist — _invoke_hook("post_llm_call", ...)'s return value is discarded. So there is nothing to persist for that hook; this PR fixes the half of the issue that is real (transform_llm_output).
• The "reference implementation" link in the issue (M1p0/Project-Rin patch) returns 404.

Tests

New tests/agent/test_44239_transform_persist_order.py (7 tests) drives finalize_turn directly with a stub agent and a patched invoke_hook:

• transformed text lands in both result["messages"][-1] and the persisted snapshot;
• ordering: transform_llm_output → persist → post_llm_call;
• untransformed turns persist the raw text unchanged;
• the sync helper skips tool-call messages, multimodal content, and never crosses the turn boundary.

tests/agent/ + tests/run_agent/ (5773 passed) plus the gateway/ACP response_transformed suites pass; the 9 failures present are pre-existing environment/order-dependent flakes that also fail on clean main (OAuth credential-file tests) or pass in isolation on this branch (vision routing / provider parity).

Related

• [Bug]: post_llm_call response overrides are applied after persistence, causing final_response/history mismatch #14894 / fix(agent): run post_llm_call hook before session persistence #14913 — same ordering concern for post_llm_call; see scope note above.

🤖 Generated with Claude Code