strands.interventions.handler

Base class for intervention handlers.

Handlers override the lifecycle methods they care about. Default implementations return Proceed. The framework detects which methods are overridden and only registers hook callbacks for those.

OnError

What to do when a handler throws during evaluation.

• 'throw' — rethrow the error (default, safest: a broken policy check blocks execution)
• 'proceed' — log the error and continue as if the handler returned Proceed. This mode is fail-open: a broken handler silently stops enforcing its policy. Use only when availability matters more than enforcement.
• 'deny' — log the error and treat it as a Deny (fail-closed)

InterventionHandler

class InterventionHandler(ABC)

Defined in: src/strands/interventions/handler.py:31

Base class for intervention handlers.

Subclasses must define a name attribute and override the lifecycle methods they care about at the class level. The framework detects which methods are overridden and only calls those. Instance-level assignments (e.g., handler.before_tool_call = my_func) are not detected.

Example:

class CedarAuth(InterventionHandler):
    name = "cedar-auth"

    def before_tool_call(self, event):
        if not self.is_authorized(event):
            return Deny(reason="not authorized")
        return Proceed()

name

@property
@abstractmethod
def name() -> str

Defined in: src/strands/interventions/handler.py:53

Unique name identifying this handler.

on_error

@property
def on_error() -> OnError

Defined in: src/strands/interventions/handler.py:58

What to do when this handler throws. Defaults to ‘throw’.

before_invocation

def before_invocation(event: BeforeInvocationEvent,
                      **kwargs: Any) -> Proceed | Deny | Guide | Transform

Defined in: src/strands/interventions/handler.py:62

Called before an agent invocation begins.

before_tool_call

def before_tool_call(
        event: BeforeToolCallEvent,
        **kwargs: Any) -> Proceed | Deny | Guide | Confirm | Transform

Defined in: src/strands/interventions/handler.py:66

Called before a tool is executed.

after_tool_call

def after_tool_call(event: AfterToolCallEvent,
                    **kwargs: Any) -> Proceed | Transform

Defined in: src/strands/interventions/handler.py:72

Called after a tool execution completes.

before_model_call

def before_model_call(event: BeforeModelCallEvent,
                      **kwargs: Any) -> Proceed | Deny | Guide | Transform

Defined in: src/strands/interventions/handler.py:76

Called before the model is invoked.

after_model_call

def after_model_call(event: AfterModelCallEvent,
                     **kwargs: Any) -> Proceed | Guide | Transform

Defined in: src/strands/interventions/handler.py:80

Called after the model invocation completes.