fix(sessions): store displayText when the user's turn lands, not at turn end

[philmerrell]

Follow-up to #988, found while validating it on dev. Pre-existing, and not caused by that change.

The bug

displayText is the clean copy of what the user typed — what the UI renders whenever the prompt sent to the model was augmented (RAG context, attachment guidance, an MCP App context block, or the <interruption_note> addressed to the model after an interrupted turn).

It was written by one call site in the stream coordinator's success path, as the last thing a turn does. Nothing on the Stop, disconnect, or error paths wrote it. So any turn that didn't reach that line left the raw augmented prompt as the only thing the UI could render:

• Transiently, for every augmented turn: reload while it's still streaming and the model-directed note is sitting in the user's own chat bubble.
• Permanently, for any turn that never completes: the D# record is never written, so it's there on every load, forever.

The permanent case lands where it hurts most. A turn only carries an interruption note because the previous turn was interrupted — so notes are disproportionately likely to end up on turns that get interrupted too.

Reproduced on dev on both GPT-5.6 Luna and Claude Haiku 4.5 — not model-specific:

displayText (D#) records: [10, 14]      ← only the turns that completed
user messages:            10, 12, 14, 16, 18

Message 18 renders <interruption_note>… in the user bubble on every load.

The fix

DisplayTextHook writes the record on MessageAddedEvent — the moment the user's message enters history, before the model call — so every later exit path already has it. Verified against the installed SDK: the prompt becomes a role-user message appended via Agent._append_messages (agent.py:1289 → 1541).

Writing at request start instead would risk a record keyed to an index the failed turn never filled, which a later message would then inherit; anchoring to the append keeps index and record together.

Two subtleties the hook respects:

• Not every role-user message is the user. Tool results carry that role under Bedrock Converse, and Strands prepends a synthetic tool-result message ahead of the prompt when history ends on a dangling toolUse — precisely the shape an interrupted tool turn leaves behind, i.e. the case this hook exists for. Content carrying toolResult/toolUse is skipped so the arm is spent on the user's own message.
• The agent instance is cached across turns (@-mention forks conversation history: the mention turn and the plain turns run on two different cached agents #741/Compaction state forks the same way conversation history did: two session managers, one DynamoDB row #751), so the hook is armed unconditionally at the head of every turn, including to None — same discipline as the turn_lease stamp beside it.

The coordinator's original write stays as a backstop for wrappers that carry no hook (voice, tests) and for a failed hook write, gated on wrote_this_turn so the normal path still makes exactly one put.

Tests

• test_display_text_hook.py (12): writes on append; ignores assistant messages; one-shot across tool results; the synthetic-repair message does not consume the arm; re-arming replaces the previous turn's state and clears wrote_this_turn; storage failure never reaches the turn.
• test_display_text_write.py (7): the coordinator arms every turn with this turn's text and index, arms to None when the prompt wasn't modified, and runs its backstop only when the hook didn't write (verified to fail without the guard).
• tests/agents + tests/shared/test_sessions_metadata.py: 1,497 passing.

Known limitation, not addressed here

The message index still comes from initial_message_count. In the rare case where Strands inserts the synthetic tool-result repair message, the user's real index shifts by one and the record would miss — pre-existing behaviour, identical before and after this change, and out of scope here.

🤖 Generated with Claude Code