feat(hooks): expose input messages to BeforeInvocationEvent #9

github-actions · 2026-01-13T18:58:34Z

Motivation

Hook providers implementing input-side guardrails (PII detection, content moderation, prompt attack prevention) need access to input messages before they are added to the agent's conversation history. The BeforeInvocationEvent previously only provided a reference to the agent with no visibility into incoming messages, forcing guardrail implementations to hook on MessageAddedEvent instead—which runs after messages are already in memory and creates ordering dependencies with session/memory managers.

Resolves #8

Public API Changes

BeforeInvocationEvent now includes a writable messages attribute:

# Before: no access to input messages
class InputGuardrail(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(BeforeInvocationEvent, self.check_input)
    
    async def check_input(self, event: BeforeInvocationEvent) -> None:
        # Could only access event.agent, no messages available
        pass

# After: can inspect and modify messages before processing
class InputGuardrail(HookProvider):
    def register_hooks(self, registry: HookRegistry) -> None:
        registry.add_callback(BeforeInvocationEvent, self.check_input)
    
    async def check_input(self, event: BeforeInvocationEvent) -> None:
        if event.messages is None:
            return
        for message in event.messages:
            if contains_pii(message["content"]):
                message["content"] = redact_pii(message["content"])

The messages attribute defaults to None for backward compatibility with deprecated code paths.

Use Cases

PII Redaction: Scan and redact sensitive information before messages are added to conversation history
Content Moderation: Filter toxic or inappropriate content before processing
Prompt Attack Prevention: Detect and block malicious prompt injection attempts early in the invocation lifecycle

Unshure · 2026-01-13T20:27:40Z

docs/HOOKS.md

+
+## Input Guardrails with BeforeInvocationEvent
+
+The `BeforeInvocationEvent` provides access to input messages through its `messages` attribute, enabling hooks to implement input-side guardrails that run before messages are added to the agent's conversation history.
+
+### Use Cases
+
+- **PII Detection/Redaction**: Scan and redact sensitive information before processing
+- **Content Moderation**: Filter toxic or inappropriate content
+- **Prompt Attack Prevention**: Detect and block malicious prompt injection attempts
+
+### Example: Input Redaction Hook
+
+```python
+from strands import Agent
+from strands.hooks import BeforeInvocationEvent, HookProvider, HookRegistry
+
+class InputGuardrailHook(HookProvider):
+    def register_hooks(self, registry: HookRegistry) -> None:
+        registry.add_callback(BeforeInvocationEvent, self.check_input)
+
+    async def check_input(self, event: BeforeInvocationEvent) -> None:
+        if event.messages is None:
+            return
+
+        for message in event.messages:
+            if message.get("role") == "user":
+                content = message.get("content", [])
+                for block in content:
+                    if "text" in block:
+                        # Option 1: Redact in-place
+                        block["text"] = redact_pii(block["text"])
+
+                        # Option 2: Abort invocation by raising an exception
+                        # if contains_malicious_content(block["text"]):
+                        #     raise ValueError("Malicious content detected")
+
+agent = Agent(hooks=[InputGuardrailHook()])
+agent("Process this message")  # Guardrail runs before message is added to memory
+```
+
+### Key Behaviors
+
+- `messages` defaults to `None` for backward compatibility (e.g., when invoked from deprecated methods)
+- `messages` is writable, allowing hooks to modify content in-place
+- The `AfterInvocationEvent` is always triggered even if a hook raises an exception, maintaining the paired event guarantee


Remove this. Its too specific for this document.

Done - removed the Input Guardrails section from HOOKS.md.

Unshure · 2026-01-13T20:29:12Z

src/strands/hooks/events.py

+    The messages attribute provides access to the input messages for this invocation,
+    allowing hooks to inspect or modify message content before processing. This is
+    particularly useful for implementing input guardrails (e.g., PII detection,
+    content moderation, prompt attack prevention) that need to run before messages
+    are added to the agent's conversation history.
+


Remove this. the purpose of messages should be covered in the Attributes.

Done - removed the detailed guardrails description from the docstring.

Unshure · 2026-01-13T20:29:44Z

src/strands/hooks/events.py

+            to redact or transform content before processing. May be None for
+            backward compatibility or when invoked from deprecated methods.


Suggested change

to redact or transform content before processing. May be None for

backward compatibility or when invoked from deprecated methods.

to redact or transform content before processing.

Done - removed the backward compatibility note from the attribute description.

Unshure · 2026-01-13T20:33:08Z

tests/strands/agent/hooks/test_events.py

+def test_before_invocation_event_messages_set_on_init(agent, sample_messages):
+    """Test that BeforeInvocationEvent.messages can be set on initialization."""
+    event = BeforeInvocationEvent(agent=agent, messages=sample_messages)
+    assert event.messages is sample_messages
+    assert event.messages == [{"role": "user", "content": [{"text": "Hello, agent!"}]}]


Remove this since its a no-op test.

Done - removed the no-op test.

Unshure · 2026-01-13T20:34:41Z

/strands

Add messages attribute to BeforeInvocationEvent to enable input-side guardrails for PII detection, content moderation, and prompt attack prevention. Hooks can now inspect and modify messages before they are added to the agent's conversation history. - Add writable messages attribute to BeforeInvocationEvent (None default) - Pass messages parameter from _run_loop() to BeforeInvocationEvent - Add unit tests for new messages attribute and writability - Add integration tests for message modification use case - Update docs/HOOKS.md with input guardrails documentation Resolves #8

- Remove detailed Input Guardrails section from docs/HOOKS.md - Simplify BeforeInvocationEvent docstring per review - Remove backward compatibility note from messages attribute - Remove no-op test for messages initialization

Unshure · 2026-01-14T15:21:45Z

tests/strands/agent/test_agent_hooks.py

+    # Verify BeforeInvocationEvent includes messages
+    before_event_2 = next(events)
+    assert isinstance(before_event_2, BeforeInvocationEvent)


Any reason this can't be something like:

assert next(events) == BeforeInvocationEvent(agent=agent, messages=agent.messages[0:1])

That would be a lot more concise & readable

Good point! Updated to use the concise equality comparison pattern.

Unshure · 2026-01-14T15:22:00Z

/strands

Use concise equality comparison for BeforeInvocationEvent assertions instead of verbose instance checks and property assertions.

Unshure reviewed Jan 13, 2026

View reviewed changes

github-actions bot added strands-running and removed strands-running labels Jan 13, 2026

strands-agent added 2 commits January 13, 2026 15:49

refactor: address review feedback

128730b

- Remove detailed Input Guardrails section from docs/HOOKS.md - Simplify BeforeInvocationEvent docstring per review - Remove backward compatibility note from messages attribute - Remove no-op test for messages initialization

Unshure force-pushed the agent-tasks/8 branch from d244c27 to 128730b Compare January 13, 2026 20:49

github-actions bot added the size/m label Jan 13, 2026

Unshure had a problem deploying to manual-approval January 13, 2026 20:49 — with GitHub Actions Failure

Unshure reviewed Jan 14, 2026

View reviewed changes

github-actions bot added the strands-running label Jan 14, 2026

refactor: simplify test assertions per review

a0ad6ec

Use concise equality comparison for BeforeInvocationEvent assertions instead of verbose instance checks and property assertions.

github-actions bot removed the strands-running label Jan 14, 2026

Use overwritten messages array for the agent

b204bbe

Unshure had a problem deploying to manual-approval January 15, 2026 18:49 — with GitHub Actions Failure

github-actions bot added size/m and removed size/m labels Jan 15, 2026

Fix mypy issue

e803dbb

github-actions bot added size/m and removed size/m labels Jan 15, 2026

Unshure had a problem deploying to manual-approval January 15, 2026 19:20 — with GitHub Actions Failure

Unshure force-pushed the main branch from 6382fc9 to 6dcd247 Compare January 21, 2026 00:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(hooks): expose input messages to BeforeInvocationEvent #9

feat(hooks): expose input messages to BeforeInvocationEvent #9

Uh oh!

github-actions bot commented Jan 13, 2026

Uh oh!

Unshure Jan 13, 2026

Uh oh!

github-actions bot Jan 13, 2026

Uh oh!

Unshure Jan 13, 2026

Uh oh!

github-actions bot Jan 13, 2026

Uh oh!

Unshure Jan 13, 2026

Uh oh!

github-actions bot Jan 13, 2026

Uh oh!

Unshure Jan 13, 2026

Uh oh!

github-actions bot Jan 13, 2026

Uh oh!

Unshure commented Jan 13, 2026

Uh oh!

Unshure Jan 14, 2026

Uh oh!

github-actions bot Jan 14, 2026

Uh oh!

Unshure commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		to redact or transform content before processing. May be None for
		backward compatibility or when invoked from deprecated methods.

feat(hooks): expose input messages to BeforeInvocationEvent #9

Are you sure you want to change the base?

feat(hooks): expose input messages to BeforeInvocationEvent #9

Uh oh!

Conversation

github-actions bot commented Jan 13, 2026

Motivation

Public API Changes

Use Cases

Uh oh!

Unshure Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Unshure Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Unshure Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Unshure Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 13, 2026

Choose a reason for hiding this comment

Uh oh!

Unshure commented Jan 13, 2026

Uh oh!

Unshure Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

Unshure commented Jan 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants