feat(agent): add add_hook convenience method for hook registration

[Unshure]

Motivation

Currently, registering a hook requires accessing the internal hooks registry:

agent.hooks.add_callback(BeforeModelCallEvent, my_callback)

This exposes implementation details and is less discoverable for users. Plugin authors and users who want to add hooks directly need a cleaner, more intuitive API.

Resolves #1686

Public API Changes

The Agent class now has an add_hook method that provides a cleaner API for registering hook callbacks:

# Before - accessing internal registry
agent.hooks.add_callback(BeforeModelCallEvent, my_callback)

# After - cleaner public API with explicit event type
agent.add_hook(my_callback, BeforeModelCallEvent)

# After - event type inferred from callback type hint
def my_callback(event: BeforeModelCallEvent) -> None:
    print(f"Model call for: {event.agent.name}")

agent.add_hook(my_callback)  # event_type inferred automatically

The add_callback method on HookRegistry also supports type inference:

# With explicit event type
registry.add_callback(BeforeModelCallEvent, my_handler)

# With event type inferred from type hint
registry.add_callback(my_typed_handler)

When event_type is not provided, it's inferred from the callback's first parameter type hint. A ValueError is raised with a helpful message if inference fails.

Use Cases

• Direct hook registration: Users can register callbacks without accessing internal hooks registry
• Plugin development: Plugin init_plugin implementations can use this cleaner API
• Quick prototyping: Lambda callbacks for debugging or logging are easier to add
• Type-safe registration: Typed callbacks automatically register for the correct event type

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

Assessment: Approve

Clean implementation of a convenience method that improves hook registration DX. The code is well-tested and documented.

Review Notes

• API Design: The method signature mirrors HookRegistry.add_callback which provides consistency. Per API_BAR_RAISING.md, this is a minimal change (convenience wrapper) where PR review is sufficient without requiring designated API reviewer.
• Testing: Good coverage of sync callbacks, async callbacks, and delegation verification.
• Type Annotations: Note that TEvent is imported from ..hooks.registry rather than the public strands.hooks module, which is fine for internal use but users won't have access to this TypeVar for their own generic type annotations (they don't typically need it).

Nice addition that aligns with SDK tenet #4 (the obvious path is the happy path).

[Unshure]

/strands

[Unshure]

/strands

[Unshure]

/strands

[Unshure]

/strands Support a list of event_types, and a union type for the callback event type. Any, or BaseEvent will support all lifecycle events

[Unshure]

/strands Lets actually just keep it to a single event for now. We can add a list or a union later