Expose input messages to BeforeInvocationEvent

[athewsey]

Description

Add the incoming messages to BeforeInvocationEvent, so that this hook can be used for implementing guardrails that check (and perhaps redact) user inputs before kicking off the event loop or raising MessageAddedEvents.

Related Issues

#1006

Documentation PR

None yet - Should be some small updates required if we go ahead. I can work on this if reviewers are OK with the change in principle?

Type of Change

New feature

Testing

Updated existing unit tests to validate the messages are passed through correctly (both in structured output and normal agent invocation).

⚠️ For now I have not added any test to explicitly validate that if a BeforeInvocationEvent hook edits the input messages in place, these will be reflected in the rest of the invocation. Do we want to commit to this?

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• (⚠️ See note above) 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.

[mkmeral]

Thanks for the PR, and I'm sorry for the delayed response.

The feature and PR makes a lot of sense, I just had 2 small comments.

[mkmeral]

can we just send the new messages? I think that would allow devs to differentiate between new messages (what we pass), and agent.messages (what already exists in history).

[mkmeral]

do we need to update the span?

[Unshure]

Apologies for the delay on this issue, but we have made some significant changes since this was submitted. We need to rebase this pr in order to fit with the current state of the codebase.

[cagataycali]

Hey @athewsey! 👋

I noticed this PR has merge conflicts. The feat/agent-interface PR (#1126) was recently merged, which likely caused the conflict.

Since this is a valuable feature (tagged as ready for contribution and paper cut), I'd be happy to help rebase this if you'd like - just let me know!

The feature makes a lot of sense for implementing early guardrails on user input before it gets added to memory. I saw @mkmeral's feedback from Jan 8th - looks like the PR just needs:

1. Rebase onto latest main
2. Address the two small comments from the review

Would love to see this land! 🚀

---

Comment from strands-coder autonomous agent 🦆

[cagataycali]

Nice work @athewsey! 👏 This PR addresses a real need for input-side guardrails - being able to inspect and potentially redact user input before it enters the agent flow.

🔍 Review Summary

What I Like

• Clean implementation that passes messages to BeforeInvocationEvent
• The structured_output code reorganization is sensible - moving validation before the tracing span
• Comprehensive test updates
• Good backward compatibility considerations

Implementation Notes

Breaking Change Consideration

This is technically a breaking change since BeforeInvocationEvent now requires the messages parameter. Any existing code that manually creates BeforeInvocationEvent(agent=agent) will fail.

Consider making messages optional with a default:

@dataclass
class BeforeInvocationEvent(HookEvent):
    """Event emitted at the start of agent operations."""
    messages: Messages = field(default_factory=list)  # Optional with default empty list

Or update the docstring to clearly indicate this is now required.

Span Attributes

I notice you moved the span attributes from set_attributes() to the start_as_current_span() call. This is cleaner, but just confirming this produces identical OTEL output?

Documentation

As you mentioned in the PR description, docs update needed. The use case for input guardrails is compelling - would be great to see an example in the hooks documentation.

Suggested Enhancement (Optional)

For guardrail implementations, it might be helpful to also include a stop_invocation() method or flag on the event:

@dataclass
class BeforeInvocationEvent(HookEvent):
    messages: Messages
    _abort_invocation: bool = field(default=False, init=False)
    
    def abort(self) -> None:
        self._abort_invocation = True

This would let hooks cleanly abort without raising exceptions. But this could be a follow-up!

Tests

✅ Tests look comprehensive - good coverage of both regular agent calls and structured_output flows.

Verdict

LGTM with minor consideration for the breaking change aspect. The core implementation is solid.

🦆

---

Review by Strands-Coder

[Unshure]

Closing as this is already implemented: #1474