[FEATURE] Deprecate hooks Parameter and HookProvider

[github-actions]

Overview

Deprecate the hooks parameter on Agent and the HookProvider protocol in favor of plugins and Plugin, providing a clear migration path for users.

Parent Issue: #1636

---

Problem Statement

The HookProvider naming conflates the low-level hooks primitive with high-level agent extensions. Deprecating it in favor of Plugin provides clearer semantics.

Proposed Solution

Add deprecation warnings for:

1. The hooks parameter on Agent
2. Custom implementations of HookProvider (excluding SDK built-ins)

Implementation Requirements

hooks Parameter Deprecation

# In Agent.__init__
if hooks:
    warnings.warn(
        "The 'hooks' parameter is deprecated. "
        "Check out the docs to understand how to migrate to plugins: "
        "https://strandsagents.com/latest/docs/plugins/",
        DeprecationWarning,
        stacklevel=2,
    )
    for hook in hooks:
        self.hooks.add_hook(hook)

HookProvider Deprecation

Add deprecation warning when HookProvider is subclassed, except for SDK built-in classes:

• ConversationManager and subclasses
• SessionManager and subclasses
• ModelRetryStrategy
• SteeringHandler (until migrated)

Approach Options

Option A: Module-based detection

# In HookProvider or a helper
_SDK_MODULES = {
    'strands.agent.conversation_manager',
    'strands.session',
    'strands.event_loop._retry',
    'strands.experimental.steering',
}

def _is_sdk_class(cls):
    return cls.__module__.startswith(tuple(_SDK_MODULES))

Option B: Explicit registry

_EXEMPT_CLASSES = {
    'ConversationManager',
    'SessionManager', 
    'ModelRetryStrategy',
    'SteeringHandler',
}

Deprecation Warning Message

"HookProvider is now deprecated. Check out the docs to understand how to migrate to plugins: https://strandsagents.com/latest/docs/plugins/"

Files to Modify

• src/strands/agent/agent.py - Add deprecation warning for hooks param
• src/strands/hooks/registry.py - Add deprecation mechanism for HookProvider
• tests/strands/agent/test_agent.py - Test deprecation warnings
• tests/strands/hooks/test_registry.py - Test HookProvider deprecation

Acceptance Criteria

• Deprecation warning shown when hooks parameter is used
• Deprecation warning shown when custom HookProvider is subclassed
• No warning for SDK built-in HookProvider implementations
• Unit tests verify warnings are raised appropriately
• Unit tests verify SDK classes don't trigger warnings
• Warning message includes link to migration docs
• Uses DeprecationWarning category for proper filtering

Technical Notes

• No target removal version yet - this is a soft deprecation
• hooks parameter continues to work, only accepts HookProvider (not Plugin)
• Built-in classes (SessionManager, etc.) will NOT be migrated to Plugin to avoid breaking customers

Dependencies

• Depends on: Plugin Protocol (1636.1), plugins parameter (1636.2)
• Should be done after: Documentation (1636.6) - so docs link is valid