feat(hooks): add BeforeReduceContextEvent and AfterReduceContextEvent

Emit hook events around reactive context reduction so observability
plugins can subscribe directly instead of polling
conversation_manager.removed_message_count for deltas. Events are
fired from the single reduce_context() call site in the event loop,
so third-party ConversationManager implementations are covered
automatically without interface changes.

Closes #2048

Author: Vincent Bai

src/strands/agent/agent.py

@@ -43,8 +43,10 @@
 from ..handlers.callback_handler import PrintingCallbackHandler, null_callback_handler
 from ..hooks import (
     AfterInvocationEvent,
+    AfterReduceContextEvent,
     AgentInitializedEvent,
     BeforeInvocationEvent,
+    BeforeReduceContextEvent,
     HookCallback,
     HookProvider,
     HookRegistry,
@@ -992,8 +994,28 @@ async def _execute_event_loop_cycle(
 
         except ContextWindowOverflowException as e:
             # Try reducing the context size and retrying
+            message_count_before = len(self.messages)
+            await self.hooks.invoke_callbacks_async(
+                BeforeReduceContextEvent(
+                    agent=self,
+                    exception=e,
+                    message_count=message_count_before,
+                )
+            )
+
             self.conversation_manager.reduce_context(self, e=e)
 
+            message_count_after = len(self.messages)
+            await self.hooks.invoke_callbacks_async(
+                AfterReduceContextEvent(
+                    agent=self,
+                    exception=e,
+                    messages_removed=message_count_before - message_count_after,
+                    message_count_before=message_count_before,
+                    message_count_after=message_count_after,
+                )
+            )
+
             # Sync agent after reduce_context to keep conversation_manager_state up to date in the session
             if self._session_manager:
                 self._session_manager.sync_agent(self)

src/strands/hooks/__init__.py

@@ -35,12 +35,14 @@ def log_end(self, event: AfterInvocationEvent) -> None:
     # Multiagent hook events
     AfterMultiAgentInvocationEvent,
     AfterNodeCallEvent,
+    AfterReduceContextEvent,
     AfterToolCallEvent,
     AgentInitializedEvent,
     BeforeInvocationEvent,
     BeforeModelCallEvent,
     BeforeMultiAgentInvocationEvent,
     BeforeNodeCallEvent,
+    BeforeReduceContextEvent,
     BeforeToolCallEvent,
     MessageAddedEvent,
     MultiAgentInitializedEvent,
@@ -54,6 +56,8 @@ def log_end(self, event: AfterInvocationEvent) -> None:
     "AfterToolCallEvent",
     "BeforeModelCallEvent",
     "AfterModelCallEvent",
+    "BeforeReduceContextEvent",
+    "AfterReduceContextEvent",
     "AfterInvocationEvent",
     "MessageAddedEvent",
     "HookEvent",

src/strands/hooks/events.py

@@ -308,6 +308,60 @@ def should_reverse_callbacks(self) -> bool:
         return True
 
 
+@dataclass
+class BeforeReduceContextEvent(HookEvent):
+    """Event triggered before the agent's conversation context is reduced.
+
+    This event is fired when a ``ContextWindowOverflowException`` is raised during
+    an event loop cycle and the agent is about to invoke
+    ``conversation_manager.reduce_context()`` to make room and retry. Hook providers
+    can use this event to observe or log the reactive compaction path.
+
+    Attributes:
+        exception: The exception that triggered context reduction. Typically a
+            ``ContextWindowOverflowException``.
+        message_count: The number of messages in the agent's conversation history
+            immediately before reduction is applied.
+    """
+
+    exception: Exception | None = None
+    message_count: int = 0
+
+
+@dataclass
+class AfterReduceContextEvent(HookEvent):
+    """Event triggered after the agent's conversation context has been reduced.
+
+    This event is fired after ``conversation_manager.reduce_context()`` completes
+    successfully in response to a ``ContextWindowOverflowException``. Observability
+    plugins can subscribe to this event to record compaction activity without
+    having to poll ``conversation_manager.removed_message_count`` for deltas.
+
+    Note: This event uses reverse callback ordering, meaning callbacks registered
+    later will be invoked first during cleanup.
+
+    Attributes:
+        exception: The exception that triggered context reduction. Typically a
+            ``ContextWindowOverflowException``.
+        messages_removed: Number of messages removed during this reduction
+            (``message_count_before - message_count_after``).
+        message_count_before: Number of messages in the conversation history before
+            reduction was applied.
+        message_count_after: Number of messages in the conversation history after
+            reduction completed.
+    """
+
+    exception: Exception | None = None
+    messages_removed: int = 0
+    message_count_before: int = 0
+    message_count_after: int = 0
+
+    @property
+    def should_reverse_callbacks(self) -> bool:
+        """True to invoke callbacks in reverse order."""
+        return True
+
+
 # Multiagent hook events start here
 @dataclass
 class MultiAgentInitializedEvent(BaseHookEvent):

tests/strands/agent/test_agent.py

@@ -21,7 +21,13 @@
 from strands.agent.conversation_manager.sliding_window_conversation_manager import SlidingWindowConversationManager
 from strands.agent.state import AgentState
 from strands.handlers.callback_handler import PrintingCallbackHandler, null_callback_handler
-from strands.hooks import BeforeInvocationEvent, BeforeModelCallEvent, BeforeToolCallEvent
+from strands.hooks import (
+    AfterReduceContextEvent,
+    BeforeInvocationEvent,
+    BeforeModelCallEvent,
+    BeforeReduceContextEvent,
+    BeforeToolCallEvent,
+)
 from strands.interrupt import Interrupt
 from strands.models.bedrock import DEFAULT_BEDROCK_MODEL_ID, BedrockModel
 from strands.session.repository_session_manager import RepositorySessionManager
@@ -529,6 +535,78 @@ def test_agent__call__retry_with_reduced_context(mock_model, agent, tool, agener
     assert conversation_manager_spy.apply_management.call_count == 1
 
 
+def test_agent__call__emits_reduce_context_events(mock_model, agent, agenerator):
+    """Verify Before/AfterReduceContextEvent fire with correct metadata when overflow triggers reduction."""
+    messages: Messages = [
+        {"role": "user", "content": [{"text": "Hello!"}]},
+        {"role": "assistant", "content": [{"text": "Hi!"}]},
+        {"role": "user", "content": [{"text": "Whats your favorite color?"}]},
+        {"role": "assistant", "content": [{"text": "Blue!"}]},
+    ]
+    agent.messages = messages
+
+    before_events: list[BeforeReduceContextEvent] = []
+    after_events: list[AfterReduceContextEvent] = []
+
+    agent.hooks.add_callback(BeforeReduceContextEvent, before_events.append)
+    agent.hooks.add_callback(AfterReduceContextEvent, after_events.append)
+
+    trigger_exception = ContextWindowOverflowException(RuntimeError("Input is too long for requested model"))
+    mock_model.mock_stream.side_effect = [
+        trigger_exception,
+        agenerator(
+            [
+                {"contentBlockStart": {"start": {}}},
+                {"contentBlockDelta": {"delta": {"text": "Green!"}}},
+                {"contentBlockStop": {}},
+                {"messageStop": {"stopReason": "end_turn"}},
+            ]
+        ),
+    ]
+
+    agent("And now?")
+
+    assert len(before_events) == 1
+    assert len(after_events) == 1
+
+    before_event = before_events[0]
+    assert before_event.agent is agent
+    assert before_event.exception is trigger_exception
+    # Before reduction runs, the prompt "And now?" has already been appended to messages (5 total).
+    assert before_event.message_count == 5
+
+    after_event = after_events[0]
+    assert after_event.agent is agent
+    assert after_event.exception is trigger_exception
+    assert after_event.message_count_before == 5
+    assert after_event.message_count_after < after_event.message_count_before
+    assert after_event.messages_removed == after_event.message_count_before - after_event.message_count_after
+    assert after_event.messages_removed > 0
+
+
+def test_agent__call__no_reduce_context_events_on_success(mock_model, agent, agenerator):
+    """Verify reduce-context events are NOT fired on a normal successful invocation."""
+    before_events: list[BeforeReduceContextEvent] = []
+    after_events: list[AfterReduceContextEvent] = []
+
+    agent.hooks.add_callback(BeforeReduceContextEvent, before_events.append)
+    agent.hooks.add_callback(AfterReduceContextEvent, after_events.append)
+
+    mock_model.mock_stream.return_value = agenerator(
+        [
+            {"contentBlockStart": {"start": {}}},
+            {"contentBlockDelta": {"delta": {"text": "ok"}}},
+            {"contentBlockStop": {}},
+            {"messageStop": {"stopReason": "end_turn"}},
+        ]
+    )
+
+    agent("Hello?")
+
+    assert before_events == []
+    assert after_events == []
+
+
 def test_agent__call__always_sliding_window_conversation_manager_doesnt_infinite_loop(mock_model, agent, tool):
     conversation_manager = SlidingWindowConversationManager(window_size=500, should_truncate_results=False)
     conversation_manager_spy = unittest.mock.Mock(wraps=conversation_manager)

tests/strands/hooks/test_events.py

@@ -1,4 +1,4 @@
-"""Tests for multi-agent execution lifecycle events."""
+"""Tests for agent and multi-agent execution lifecycle events."""
 
 from unittest.mock import Mock
 
@@ -7,9 +7,12 @@
 from strands.hooks import (
     AfterMultiAgentInvocationEvent,
     AfterNodeCallEvent,
+    AfterReduceContextEvent,
     BaseHookEvent,
     BeforeMultiAgentInvocationEvent,
     BeforeNodeCallEvent,
+    BeforeReduceContextEvent,
+    HookEvent,
     MultiAgentInitializedEvent,
 )
 
@@ -105,3 +108,59 @@ def test_after_events_should_reverse_callbacks(orchestrator):
 
     assert after_node_event.should_reverse_callbacks is True
     assert after_invocation_event.should_reverse_callbacks is True
+
+
+@pytest.fixture
+def agent():
+    """Mock agent for testing."""
+    return Mock()
+
+
+def test_before_reduce_context_event_defaults(agent):
+    """BeforeReduceContextEvent has sensible defaults and inherits from HookEvent."""
+    event = BeforeReduceContextEvent(agent=agent)
+
+    assert event.agent is agent
+    assert event.exception is None
+    assert event.message_count == 0
+    assert event.should_reverse_callbacks is False
+    assert isinstance(event, HookEvent)
+
+
+def test_before_reduce_context_event_with_fields(agent):
+    """BeforeReduceContextEvent carries the trigger exception and message count."""
+    exc = RuntimeError("overflow")
+    event = BeforeReduceContextEvent(agent=agent, exception=exc, message_count=12)
+
+    assert event.exception is exc
+    assert event.message_count == 12
+
+
+def test_after_reduce_context_event_defaults(agent):
+    """AfterReduceContextEvent has sensible defaults and runs callbacks in reverse."""
+    event = AfterReduceContextEvent(agent=agent)
+
+    assert event.agent is agent
+    assert event.exception is None
+    assert event.messages_removed == 0
+    assert event.message_count_before == 0
+    assert event.message_count_after == 0
+    assert event.should_reverse_callbacks is True
+    assert isinstance(event, HookEvent)
+
+
+def test_after_reduce_context_event_with_fields(agent):
+    """AfterReduceContextEvent carries before/after counts and the original exception."""
+    exc = RuntimeError("overflow")
+    event = AfterReduceContextEvent(
+        agent=agent,
+        exception=exc,
+        messages_removed=3,
+        message_count_before=10,
+        message_count_after=7,
+    )
+
+    assert event.exception is exc
+    assert event.messages_removed == 3
+    assert event.message_count_before == 10
+    assert event.message_count_after == 7