feat(hooks): add BeforeStreamChunkEvent for stream chunk interception

[fede-kamel]

Motivation

There's currently no way to intercept stream chunks before they're processed. Hooks fire after processing, so modifications don't affect the TextStreamEvent or final message content.

The current hook lifecycle has a gap during streaming:

BeforeModelCallEvent
    ↓
[MODEL STREAMS CHUNKS]  ← no hook here currently
    ↓
AfterModelCallEvent

BeforeModelCallEvent fires before chunks exist. AfterModelCallEvent fires after chunks have already been streamed to the user. Neither allows chunk interception.

This adds BeforeStreamChunkEvent that fires before each chunk is processed, allowing:

• Chunk modification (affects downstream processing and final message)
• Chunk filtering via skip=True (excludes from all events and final message)
• Access to invocation_state for context

Resolves #1760

Use Cases

• Content redaction: Modify sensitive data before it reaches the user
• Filtering: Skip certain chunks entirely (skip=True)
• Real-time monitoring: Observe streaming without modifying
• Content transformation: Translation, formatting, etc.

Public API Changes

New event: BeforeStreamChunkEvent

from strands.hooks import BeforeStreamChunkEvent

async def redact_chunks(event: BeforeStreamChunkEvent):
    if "contentBlockDelta" in event.chunk:
        delta = event.chunk["contentBlockDelta"]["delta"]
        if "text" in delta:
            # modify the chunk - affects TextStreamEvent and final message
            event.chunk = {"contentBlockDelta": {"delta": {"text": "[REDACTED]"}}}
            # or skip entirely
            # event.skip = True

agent.hooks.add_callback(BeforeStreamChunkEvent, redact_chunks)

Properties:

• chunk (writable) - the raw stream chunk
• skip (writable) - set True to exclude chunk from processing
• invocation_state (read-only) - context dict from invocation

Reproduction and Demonstration

Issue reproduction (main branch): https://gist.github.com/fede-kamel/9d93429a3d6d7676906e41eb60890d46

Working demonstration (feature branch): https://gist.github.com/fede-kamel/a6a78d8d35eb9707d80c2327cd17b462

Type of Change

New feature

Testing

• I ran hatch run prepare (lint, format, tests all pass)

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.