Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
feat: add generic interception-hook dispatcher (#6516)
Lucas Gomide7d21283630f2
diff --git a/lib/crewai/src/crewai/agents/crew_agent_executor.py b/lib/crewai/src/crewai/agents/crew_agent_executor.pyindex de2315e3a..040520e1f 100644--- a/lib/crewai/src/crewai/agents/crew_agent_executor.py+++ b/lib/crewai/src/crewai/agents/crew_agent_executor.py@@ -46,8 +46,8 @@ from crewai.hooks.llm_hooks import ()from crewai.hooks.tool_hooks import (ToolCallHookContext,- get_after_tool_call_hooks,- get_before_tool_call_hooks,+ run_after_tool_call_hooks,+ run_before_tool_call_hooks,)from crewai.types.callback import SerializableCallablefrom crewai.utilities.agent_utils import (@@ -951,7 +951,6 @@ class CrewAgentExecutor(BaseAgentExecutor):track_delegation_if_needed(func_name, args_dict or {}, self.task)- hook_blocked = Falsebefore_hook_context = ToolCallHookContext(tool_name=func_name,tool_input=args_dict or {},@@ -960,19 +959,7 @@ class CrewAgentExecutor(BaseAgentExecutor):task=self.task,crew=self.crew,)- before_hooks = get_before_tool_call_hooks()- try:- for hook in before_hooks:- hook_result = hook(before_hook_context)- if hook_result is False:- hook_blocked = True- break- except Exception as hook_error:- if self.agent.verbose:- PRINTER.print(- content=f"Error in before_tool_call hook: {hook_error}",- color="red",- )+ hook_blocked = run_before_tool_call_hooks(before_hook_context)if hook_blocked:result = f"Tool execution blocked by hook. Tool: {func_name}"@@ -1033,19 +1020,9 @@ class CrewAgentExecutor(BaseAgentExecutor):tool_result=result,raw_tool_result=raw_tool_result,)- after_hooks = get_after_tool_call_hooks()- try:- for after_hook in after_hooks:- after_hook_result = after_hook(after_hook_context)- if after_hook_result is not None:- result = after_hook_result- after_hook_context.tool_result = result- except Exception as hook_error:- if self.agent.verbose:- PRINTER.print(- content=f"Error in after_tool_call hook: {hook_error}",- color="red",- )+ modified_result = run_after_tool_call_hooks(after_hook_context)+ if modified_result is not None:+ result = modified_resultif not error_event_emitted:crewai_event_bus.emit(diff --git a/lib/crewai/src/crewai/events/types/hook_events.py b/lib/crewai/src/crewai/events/types/hook_events.pynew file mode 100644index 000000000..b620bcfe1--- /dev/null+++ b/lib/crewai/src/crewai/events/types/hook_events.py@@ -0,0 +1,19 @@+from typing import Literal++from crewai.events.base_events import BaseEvent+++class HookDispatchedEvent(BaseEvent):+ """Event emitted whenever an interception point dispatches to hooks.++ Only emitted when at least one hook is registered for the point, so the+ no-op fast path stays free of event overhead.+ """++ type: Literal["hook_dispatched"] = "hook_dispatched"+ interception_point: str+ outcome: Literal["proceeded", "modified", "aborted"]+ hook_count: int+ duration_ms: float+ abort_reason: str | None = None+ abort_source: str | None = Nonediff --git a/lib/crewai/src/crewai/experimental/agent_executor.py b/lib/crewai/src/crewai/experimental/agent_executor.pyindex 3c76bd8d8..96308f9c9 100644--- a/lib/crewai/src/crewai/experimental/agent_executor.py+++ b/lib/crewai/src/crewai/experimental/agent_executor.py@@ -62,8 +62,8 @@ from crewai.hooks.llm_hooks import ()from crewai.hooks.tool_hooks import (ToolCallHookContext,- get_after_tool_call_hooks,- get_before_tool_call_hooks,+ run_after_tool_call_hooks,+ run_before_tool_call_hooks,)from crewai.hooks.types import (AfterLLMCallHookCallable,@@ -1975,7 +1975,6 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):track_delegation_if_needed(func_name, args_dict, self.task)- hook_blocked = Falsebefore_hook_context = ToolCallHookContext(tool_name=func_name,tool_input=args_dict,@@ -1984,19 +1983,7 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):task=self.task,crew=self.crew,)- before_hooks = get_before_tool_call_hooks()- try:- for hook in before_hooks:- hook_result = hook(before_hook_context)- if hook_result is False:- hook_blocked = True- break- except Exception as hook_error:- if self.agent.verbose:- PRINTER.print(- content=f"Error in before_tool_call hook: {hook_error}",- color="red",- )+ hook_blocked = run_before_tool_call_hooks(before_hook_context)if hook_blocked:result = f"Tool execution blocked by hook. Tool: {func_name}"@@ -2060,19 +2047,9 @@ class AgentExecutor(Flow[AgentExecutorState], BaseAgentExecutor):tool_result=result,raw_tool_result=raw_tool_result,)- after_hooks = get_after_tool_call_hooks()- try:- for after_hook in after_hooks:- after_hook_result = after_hook(after_hook_context)- if after_hook_result is not None:- result = after_hook_result- after_hook_context.tool_result = result- except Exception as hook_error:- if self.agent.verbose:- PRINTER.print(- content=f"Error in after_tool_call hook: {hook_error}",- color="red",- )+ modified_result = run_after_tool_call_hooks(after_hook_context)+ if modified_result is not None:+ result = modified_resultif not error_event_emitted:crewai_event_bus.emit(diff --git a/lib/crewai/src/crewai/hooks/__init__.py b/lib/crewai/src/crewai/hooks/__init__.pyindex 5b9fbf7bd..16c6fe0fc 100644--- a/lib/crewai/src/crewai/hooks/__init__.py+++ b/lib/crewai/src/crewai/hooks/__init__.py@@ -6,6 +6,17 @@ from crewai.hooks.decorators import (before_llm_call,before_tool_call,)+from crewai.hooks.dispatch import (+ HookAborted,+ InterceptionPoint,+ clear as clear_hooks,+ clear_all as clear_all_hooks,+ dispatch,+ get_hooks,+ on,+ register as register_hook,+ unregister as unregister_hook,+)from crewai.hooks.llm_hooks import (LLMCallHookContext,clear_after_llm_call_hooks,@@ -74,6 +85,8 @@ def clear_all_global_hooks() -> dict[str, tuple[int, int]]:__all__ = [+ "HookAborted",+ "InterceptionPoint","LLMCallHookContext","ToolCallHookContext","after_llm_call",@@ -83,20 +96,27 @@ __all__ = ["clear_after_llm_call_hooks","clear_after_tool_call_hooks","clear_all_global_hooks",+ "clear_all_hooks","clear_all_llm_call_hooks","clear_all_tool_call_hooks","clear_before_llm_call_hooks","clear_before_tool_call_hooks",+ "clear_hooks",+ "dispatch","get_after_llm_call_hooks","get_after_tool_call_hooks","get_before_llm_call_hooks","get_before_tool_call_hooks",+ "get_hooks",+ "on","register_after_llm_call_hook","register_after_tool_call_hook","register_before_llm_call_hook","register_before_tool_call_hook",+ "register_hook","unregister_after_llm_call_hook","unregister_after_tool_call_hook","unregister_before_llm_call_hook","unregister_before_tool_call_hook",+ "unregister_hook",]diff --git a/lib/crewai/src/crewai/hooks/dispatch.py b/lib/crewai/src/crewai/hooks/dispatch.pynew file mode 100644index 000000000..2822c73dd--- /dev/null+++ b/lib/crewai/src/crewai/hooks/dispatch.py@@ -0,0 +1,424 @@+"""Generic interception-hook dispatcher.++This module is the single engine behind every CrewAI interception point. A hook+receives a typed context, may mutate it in place and/or return a replacement+payload, and may raise :class:`HookAborted` to stop the intercepted operation+with a reason and source.++The four public hook families (``before/after_llm_call`` and+``before/after_tool_call``) are adapters registered on this dispatcher, so the+legacy dialect (``register_*``/decorators/``return False``) and the new dialect+(``@on(point)`` / ``HookAborted``) share one ordered queue per point.++Design notes:+- Global registration order is preserved; execution-scoped hooks (via+ ``contextvars``) run after global ones, mirroring+ ``events/event_bus.py``'s ``_runtime_state_var`` scoping pattern.+- ``dispatch`` has a no-op fast path (a single dict lookup) when no hooks are+ registered for a point.+- Hooks are synchronous. They may be invoked from async seams, so they must not+ block on heavy I/O (same restriction as the legacy hooks).+- ``HookAborted`` propagates by design. Any other exception raised by a hook is+ swallowed (fail-open) to preserve the framework's protection against a buggy+ user hook.+"""++from __future__ import annotations++from collections.abc import Callable, Iterator+from contextlib import contextmanager+import contextvars+from enum import Enum+from functools import wraps+import inspect+import time+from typing import Any++from crewai.utilities.string_utils import sanitize_tool_name+++class InterceptionPoint(str, Enum):+ """Interception points wired by this layer.++ New points are introduced alongside the seams that dispatch them, so the+ enum only ever lists points with a live consumer. This layer ships the+ model- and tool-call boundaries, which back the legacy+ ``before/after_llm_call`` and ``before/after_tool_call`` hooks.+ """++ # Model / tool boundaries (legacy-compatible)+ PRE_MODEL_CALL = "pre_model_call"+ POST_MODEL_CALL = "post_model_call"+ PRE_TOOL_CALL = "pre_tool_call"+ POST_TOOL_CALL = "post_tool_call"+++class HookAborted(Exception): # noqa: N818 - public contract name from OSS-86+ """Raised by a hook (or a legacy adapter) to abort the intercepted operation.++ Args:+ reason: Human-readable explanation of why the operation was aborted.+ source: Optional identifier of the aborting hook (callable, string, or+ any object). Used for telemetry and failure messages.+ """++ def __init__(self, reason: str, source: Any = None) -> None:+ super().__init__(reason)+ self.reason = reason+ self.source = source+++HookFn = Callable[[Any], Any]++# (ctx, result) -> modified? A reducer maps a hook's return value onto the+# context using point-specific semantics. It may raise HookAborted.+Reducer = Callable[[Any, Any], bool]+++_global_hooks: dict[InterceptionPoint, list[HookFn]] = {+ point: [] for point in InterceptionPoint+}++_scoped_hooks_var: contextvars.ContextVar[+ dict[InterceptionPoint, list[HookFn]] | None+] = contextvars.ContextVar("crewai_scoped_hooks", default=None)+++_TELEMETRY_SOURCE = object()+++def get_global_hook_list(point: InterceptionPoint) -> list[HookFn]:+ """Return the live global hook list for a point.++ The returned list object is stable for the lifetime of the process, which+ lets legacy modules alias their module-level registries to it. Mutate it in+ place (append/remove/clear); never rebind it.+ """+ return _global_hooks[point]+++def register(point: InterceptionPoint, hook: HookFn) -> None:+ """Register a global hook for an interception point."""+ _global_hooks[point].append(hook)+++def unregister(point: InterceptionPoint, hook: HookFn) -> bool:+ """Unregister a specific global hook. Returns True if it was removed.++ When ``hook`` was registered through :func:`on` with ``agents``/``tools``+ filters, the stored callable is a wrapper rather than ``hook`` itself. The+ wrapper is stashed on ``hook._registered_hook`` at registration time, so it+ can be resolved and removed here.+ """+ hooks = _global_hooks[point]+ target = hook if hook in hooks else getattr(hook, "_registered_hook", hook)+ try:+ hooks.remove(target)+ return True+ except ValueError:+ return False+++def get_hooks(point: InterceptionPoint) -> list[HookFn]:+ """Return a copy of the global hooks registered for a point."""+ return _global_hooks[point].copy()+++def clear(point: InterceptionPoint) -> int:+ """Clear all global hooks for a point. Returns the number cleared."""+ count = len(_global_hooks[point])+ _global_hooks[point].clear()+ return count+++def clear_all() -> None:+ """Clear all global hooks across every interception point."""+ for hooks in _global_hooks.values():+ hooks.clear()+++@contextmanager+def scoped_hooks(+ hooks: dict[InterceptionPoint, list[HookFn]] | None = None,+) -> Iterator[dict[InterceptionPoint, list[HookFn]]]:+ """Enter an execution-scoped hook registry.++ Hooks registered inside this context (via :func:`register_scoped`) run after+ global hooks and are discarded when the context exits. Mirrors the event+ bus's scoped-handler pattern.+ """+ scope: dict[InterceptionPoint, list[HookFn]] = hooks if hooks is not None else {}+ token = _scoped_hooks_var.set(scope)+ try:+ yield scope+ finally:+ _scoped_hooks_var.reset(token)+++def register_scoped(point: InterceptionPoint, hook: HookFn) -> None:+ """Register a hook scoped to the current :func:`scoped_hooks` context."""+ scope = _scoped_hooks_var.get()+ if scope is None:+ raise RuntimeError(+ "register_scoped() called outside of a scoped_hooks() context"+ )+ scope.setdefault(point, []).append(hook)+++def get_scoped_hooks(point: InterceptionPoint) -> list[HookFn]:+ """Return the hooks registered in the current execution scope for a point.++ Used by seams that carry a pre-snapshotted hook list (e.g. the agent+ executors' per-executor LLM hook lists) so they can merge in+ execution-scoped hooks with the same snapshot-then-scoped ordering that+ :func:`dispatch` applies to global vs scoped hooks.+ """+ scope = _scoped_hooks_var.get()+ if not scope:+ return []+ return list(scope.get(point, []))+++def _resolve_hooks(point: InterceptionPoint) -> list[HookFn]:+ """Resolve the ordered hooks for a point: global first, then scoped."""+ global_hooks = _global_hooks[point]+ scope = _scoped_hooks_var.get()+ if scope:+ scoped = scope.get(point)+ if scoped:+ return [*global_hooks, *scoped]+ return global_hooks+++def _source_name(source: Any) -> str | None:+ """Best-effort readable name for a hook source."""+ if source is None:+ return None+ if isinstance(source, str):+ return source+ name = getattr(source, "__name__", None)+ if isinstance(name, str):+ return name+ return type(source).__name__+++def _emit_telemetry(+ point: InterceptionPoint,+ outcome: str,+ hook_count: int,+ duration_ms: float,+ abort_reason: str | None,+ abort_source: str | None,+) -> None:+ """Emit a HookDispatchedEvent. Never raises."""+ try:+ from crewai.events.event_bus import crewai_event_bus+ from crewai.events.types.hook_events import HookDispatchedEvent++ crewai_event_bus.emit(+ _TELEMETRY_SOURCE,+ event=HookDispatchedEvent(+ interception_point=point.value,+ outcome=outcome,+ hook_count=hook_count,+ duration_ms=duration_ms,+ abort_reason=abort_reason,+ abort_source=abort_source,+ ),+ )+ except Exception: # noqa: S110 - telemetry must never break dispatch+ pass+++def _default_reducer(ctx: Any, result: Any) -> bool:+ """Default payload semantics: a non-None return replaces ``ctx.payload``.++ Only reports a modification when the payload was actually applied, so a+ context without a ``payload`` attribute does not produce a misleading+ ``"modified"`` telemetry outcome.+ """+ if result is not None and hasattr(ctx, "payload"):+ ctx.payload = result+ return True+ return False+++def _invoke_hook(+ point: InterceptionPoint,+ hook: HookFn,+ ctx: Any,+ reducer: Reducer,+ verbose: bool,+) -> bool:+ """Run a single hook and apply its result via the reducer.++ Returns whether the context was modified. Raises :class:`HookAborted` (with+ ``source`` populated) to abort; any other exception is swallowed (fail-open).+ """+ try:+ result = hook(ctx)+ return reducer(ctx, result)+ except HookAborted as aborted:+ if aborted.source is None:+ aborted.source = hook+ raise+ except Exception as error:+ if verbose:+ from crewai_core.printer import PRINTER++ PRINTER.print(+ content=f"Error in {point.value} hook: {error}",+ color="yellow",+ )+ return False+++def run_hooks(+ point: InterceptionPoint,+ ctx: Any,+ hooks: list[HookFn],+ *,+ reducer: Reducer | None = None,+ verbose: bool = True,+) -> Any:+ """Execute an explicit list of hooks against a context.++ This is the shared engine used both by :func:`dispatch` (which resolves+ global + scoped hooks) and by seams that carry a pre-snapshotted hook list+ (e.g. per-executor LLM hook lists).++ Args:+ point: The interception point being dispatched.+ ctx: The typed context passed to each hook (mutated in place).+ hooks: The ordered hooks to run.+ reducer: Maps each hook's return value onto ``ctx``. Defaults to+ :func:`_default_reducer` (payload replacement). May raise+ :class:`HookAborted`.+ verbose: Whether to print swallowed-hook-error warnings.++ Returns:+ The (possibly mutated) context.++ Raises:+ HookAborted: If a hook or the reducer aborts the operation. Telemetry is+ still emitted before propagating.+ """+ if not hooks:+ return ctx++ active_reducer = reducer if reducer is not None else _default_reducer+ start = time.perf_counter()+ outcome = "proceeded"+ abort_reason: str | None = None+ abort_source: str | None = None+ modified = False++ try:+ for hook in list(hooks):+ if _invoke_hook(point, hook, ctx, active_reducer, verbose):+ modified = True+ outcome = "modified" if modified else "proceeded"+ return ctx+ except HookAborted as aborted:+ outcome = "aborted"+ abort_reason = aborted.reason+ abort_source = _source_name(aborted.source)+ raise+ finally:+ _emit_telemetry(+ point,+ outcome,+ len(hooks),+ (time.perf_counter() - start) * 1000.0,+ abort_reason,+ abort_source,+ )+++def dispatch(+ point: InterceptionPoint,+ ctx: Any,+ *,+ reducer: Reducer | None = None,+ verbose: bool = True,+) -> Any:+ """Dispatch a context to all hooks registered for a point.++ Resolves global then scoped hooks and runs them through :func:`run_hooks`.+ No-op fast path when nothing is registered.+ """+ hooks = _resolve_hooks(point)+ if not hooks:+ return ctx+ return run_hooks(point, ctx, hooks, reducer=reducer, verbose=verbose)+++def _wrap_with_filters(+ func: HookFn,+ agents: list[str] | None,+ tools: list[str] | None,+) -> HookFn:+ """Wrap a hook so it only runs for matching agents/tools (context-shape aware)."""++ @wraps(func)+ def filtered(ctx: Any) -> Any:+ if tools:+ tool_name = getattr(ctx, "tool_name", None)+ if tool_name is not None and tool_name not in tools:+ return None+ if agents:+ agent = getattr(ctx, "agent", None)+ role = getattr(agent, "role", None) if agent is not None else None+ if role is None:+ role = getattr(ctx, "agent_role", None)+ if role is not None and role not in agents:+ return None+ return func(ctx)++ return filtered+++def on(+ point: InterceptionPoint,+ *,+ agents: list[str] | None = None,+ tools: list[str] | None = None,+) -> Callable[[HookFn], HookFn]:+ """Register a function as a hook for an interception point.++ Mirrors the legacy decorators' ergonomics: supports ``agents=`` / ``tools=``+ filters and, when applied to a method inside a ``@CrewBase`` class, defers+ registration to crew initialization (crew-scoped) instead of registering+ globally.++ Example:+ >>> @on(InterceptionPoint.PRE_TOOL_CALL, tools=["delete_file"])+ ... def guard(ctx):+ ... raise HookAborted("deletion not allowed")+ """+ normalized_tools = [sanitize_tool_name(t) for t in tools] if tools else None++ def decorator(func: HookFn) -> HookFn:+ func._interception_point = point # type: ignore[attr-defined]+ if normalized_tools:+ func._filter_tools = normalized_tools # type: ignore[attr-defined]+ if agents:+ func._filter_agents = agents # type: ignore[attr-defined]++ params = list(inspect.signature(func).parameters.keys())+ is_method = len(params) >= 2 and params[0] == "self"++ if not is_method:+ hook = (+ _wrap_with_filters(func, agents, normalized_tools)+ if (agents or normalized_tools)+ else func+ )+ register(point, hook)+ # Remember the actually-registered callable so unregister_hook(func)+ # can resolve the filter wrapper.+ func._registered_hook = hook # type: ignore[attr-defined]++ return func++ return decoratordiff --git a/lib/crewai/src/crewai/hooks/llm_hooks.py b/lib/crewai/src/crewai/hooks/llm_hooks.pyindex 67108c01c..55563e84e 100644--- a/lib/crewai/src/crewai/hooks/llm_hooks.py+++ b/lib/crewai/src/crewai/hooks/llm_hooks.py@@ -5,6 +5,11 @@ from typing import TYPE_CHECKING, Any, castfrom crewai_core.printer import PRINTERfrom crewai.events.event_listener import event_listener+from crewai.hooks.dispatch import (+ HookAborted,+ InterceptionPoint,+ get_global_hook_list,+)from crewai.hooks.types import (AfterLLMCallHookCallable,AfterLLMCallHookType,@@ -150,8 +155,37 @@ class LLMCallHookContext:event_listener.formatter.resume_live_updates()-_before_llm_call_hooks: list[BeforeLLMCallHookType | BeforeLLMCallHookCallable] = []-_after_llm_call_hooks: list[AfterLLMCallHookType | AfterLLMCallHookCallable] = []+# The legacy registries are aliased to the generic dispatcher's global hook+# lists for the model-call points, so legacy registrations and new-dialect+# ``@on(InterceptionPoint.PRE_MODEL_CALL)`` hooks share one ordered queue.+_before_llm_call_hooks: list[BeforeLLMCallHookType | BeforeLLMCallHookCallable] = (+ get_global_hook_list(InterceptionPoint.PRE_MODEL_CALL)+)+_after_llm_call_hooks: list[AfterLLMCallHookType | AfterLLMCallHookCallable] = (+ get_global_hook_list(InterceptionPoint.POST_MODEL_CALL)+)+++def before_llm_call_reducer(context: LLMCallHookContext, result: object) -> bool:+ """Legacy calling convention for ``pre_model_call`` hooks.++ A ``False`` return aborts the call (mapped to :class:`HookAborted`); messages+ are modified in place, so no payload replacement occurs here.+ """+ if result is False:+ raise HookAborted(reason="before_llm_call hook returned False")+ return False+++def after_llm_call_reducer(context: LLMCallHookContext, result: object) -> bool:+ """Legacy calling convention for ``post_model_call`` hooks.++ A non-empty string return replaces the response on the context.+ """+ if result is not None and isinstance(result, str):+ context.response = result+ return True+ return Falsedef register_before_llm_call_hook(diff --git a/lib/crewai/src/crewai/hooks/tool_hooks.py b/lib/crewai/src/crewai/hooks/tool_hooks.pyindex a860c01d4..a4509bce7 100644--- a/lib/crewai/src/crewai/hooks/tool_hooks.py+++ b/lib/crewai/src/crewai/hooks/tool_hooks.py@@ -5,6 +5,12 @@ from typing import TYPE_CHECKING, Anyfrom crewai_core.printer import PRINTERfrom crewai.events.event_listener import event_listener+from crewai.hooks.dispatch import (+ HookAborted,+ InterceptionPoint,+ dispatch,+ get_global_hook_list,+)from crewai.hooks.types import (AfterToolCallHookCallable,AfterToolCallHookType,@@ -121,8 +127,81 @@ class ToolCallHookContext:event_listener.formatter.resume_live_updates()-_before_tool_call_hooks: list[BeforeToolCallHookType | BeforeToolCallHookCallable] = []-_after_tool_call_hooks: list[AfterToolCallHookType | AfterToolCallHookCallable] = []+# The legacy registries are aliased to the generic dispatcher's global hook+# lists for the tool-call points, so legacy registrations and new-dialect+# ``@on(InterceptionPoint.PRE_TOOL_CALL)`` hooks share one ordered queue.+_before_tool_call_hooks: list[BeforeToolCallHookType | BeforeToolCallHookCallable] = (+ get_global_hook_list(InterceptionPoint.PRE_TOOL_CALL)+)+_after_tool_call_hooks: list[AfterToolCallHookType | AfterToolCallHookCallable] = (+ get_global_hook_list(InterceptionPoint.POST_TOOL_CALL)+)+++def before_tool_call_reducer(context: ToolCallHookContext, result: object) -> bool:+ """Legacy calling convention for ``pre_tool_call`` hooks.++ A ``False`` return blocks the call (mapped to :class:`HookAborted`); tool+ input is modified in place, so no payload replacement occurs here.+ """+ if result is False:+ raise HookAborted(reason="before_tool_call hook returned False")+ return False+++def after_tool_call_reducer(context: ToolCallHookContext, result: object) -> bool:+ """Legacy calling convention for ``post_tool_call`` hooks.++ A non-None return replaces the tool result on the context.+ """+ if isinstance(result, str):+ context.tool_result = result+ return True+ return False+++def _hook_verbose(context: ToolCallHookContext) -> bool:+ """Whether swallowed-hook-error warnings should be printed.++ Mirrors the pre-dispatcher behavior where a failing tool hook surfaced a+ warning when the executing agent was verbose.+ """+ return bool(getattr(context.agent, "verbose", False))+++def run_before_tool_call_hooks(context: ToolCallHookContext) -> bool:+ """Run all ``pre_tool_call`` hooks against a context.++ Returns:+ True if a hook blocked execution (returned False or raised+ :class:`HookAborted`), False otherwise. Tool input mutations on the+ context persist regardless.+ """+ try:+ dispatch(+ InterceptionPoint.PRE_TOOL_CALL,+ context,+ reducer=before_tool_call_reducer,+ verbose=_hook_verbose(context),+ )+ return False+ except HookAborted:+ return True+++def run_after_tool_call_hooks(context: ToolCallHookContext) -> str | None:+ """Run all ``post_tool_call`` hooks against a context.++ Returns:+ The (possibly modified) tool result carried on the context.+ """+ dispatch(+ InterceptionPoint.POST_TOOL_CALL,+ context,+ reducer=after_tool_call_reducer,+ verbose=_hook_verbose(context),+ )+ return context.tool_resultdef register_before_tool_call_hook(diff --git a/lib/crewai/src/crewai/llms/base_llm.py b/lib/crewai/src/crewai/llms/base_llm.pyindex ece84fde0..a71126f58 100644--- a/lib/crewai/src/crewai/llms/base_llm.py+++ b/lib/crewai/src/crewai/llms/base_llm.py@@ -1007,15 +1007,14 @@ class BaseLLM(BaseModel, ABC):from crewai_core.printer import PRINTER+ from crewai.hooks.dispatch import HookAborted, InterceptionPoint, dispatchfrom crewai.hooks.llm_hooks import (LLMCallHookContext,- get_before_llm_call_hooks,+ before_llm_call_reducer,)- before_hooks = get_before_llm_call_hooks()- if not before_hooks:- return True-+ # No early global-list guard: dispatch resolves global + execution-scoped+ # hooks and has its own no-op fast path, so scoped hooks still run here.hook_context = LLMCallHookContext(executor=None,messages=messages,@@ -1024,24 +1023,19 @@ class BaseLLM(BaseModel, ABC):task=None,crew=None,)- verbose = getattr(from_agent, "verbose", True) if from_agent else Truetry:- for hook in before_hooks:- result = hook(hook_context)- if result is False:- if verbose:- PRINTER.print(- content="LLM call blocked by before_llm_call hook",- color="yellow",- )- return False- except Exception as e:- if verbose:- PRINTER.print(- content=f"Error in before_llm_call hook: {e}",- color="yellow",- )+ dispatch(+ InterceptionPoint.PRE_MODEL_CALL,+ hook_context,+ reducer=before_llm_call_reducer,+ )+ except HookAborted:+ PRINTER.print(+ content="LLM call blocked by before_llm_call hook",+ color="yellow",+ )+ return Falsereturn True@@ -1074,17 +1068,14 @@ class BaseLLM(BaseModel, ABC):if from_agent is not None or not isinstance(response, str):return response- from crewai_core.printer import PRINTER-+ from crewai.hooks.dispatch import InterceptionPoint, dispatchfrom crewai.hooks.llm_hooks import (LLMCallHookContext,- get_after_llm_call_hooks,+ after_llm_call_reducer,)- after_hooks = get_after_llm_call_hooks()- if not after_hooks:- return response-+ # No early global-list guard: dispatch resolves global + execution-scoped+ # hooks and has its own no-op fast path, so scoped hooks still run here.hook_context = LLMCallHookContext(executor=None,messages=messages,@@ -1094,20 +1085,11 @@ class BaseLLM(BaseModel, ABC):crew=None,response=response,)- verbose = getattr(from_agent, "verbose", True) if from_agent else True- modified_response = response- try:- for hook in after_hooks:- result = hook(hook_context)- if result is not None and isinstance(result, str):- modified_response = result- hook_context.response = modified_response- except Exception as e:- if verbose:- PRINTER.print(- content=f"Error in after_llm_call hook: {e}",- color="yellow",- )+ dispatch(+ InterceptionPoint.POST_MODEL_CALL,+ hook_context,+ reducer=after_llm_call_reducer,+ )- return modified_response+ return hook_context.response if hook_context.response is not None else responsediff --git a/lib/crewai/src/crewai/project/crew_base.py b/lib/crewai/src/crewai/project/crew_base.pyindex 2d35a35b3..fa945f0c5 100644--- a/lib/crewai/src/crewai/project/crew_base.py+++ b/lib/crewai/src/crewai/project/crew_base.py@@ -452,7 +452,15 @@ def _register_crew_hooks(instance: CrewInstance, cls: type) -> None:)}- if not hook_methods:+ # Methods decorated with @on(InterceptionPoint.X) carry ``_interception_point``+ # instead of the legacy markers above.+ on_methods = {+ name: method+ for name, method in cls.__dict__.items()+ if hasattr(method, "_interception_point")+ }++ if not hook_methods and not on_methods:returnfrom crewai.hooks import (@@ -588,6 +596,25 @@ def _register_crew_hooks(instance: CrewInstance, cls: type) -> None:("after_tool_call", after_tool_hook))+ if on_methods:+ from crewai.hooks.dispatch import (+ _wrap_with_filters,+ register as register_interception_hook,+ )++ for on_method in on_methods.values():+ point = on_method._interception_point+ bound_hook = on_method.__get__(instance, cls)+ tools_filter = getattr(on_method, "_filter_tools", None)+ agents_filter = getattr(on_method, "_filter_agents", None)+ hook = (+ _wrap_with_filters(bound_hook, agents_filter, tools_filter)+ if (tools_filter or agents_filter)+ else bound_hook+ )+ register_interception_hook(point, hook)+ instance._registered_hook_functions.append((point.value, hook))+instance._hooks_being_registered = Falsediff --git a/lib/crewai/src/crewai/utilities/agent_utils.py b/lib/crewai/src/crewai/utilities/agent_utils.pyindex 8a5fd9a07..e3fa001dc 100644--- a/lib/crewai/src/crewai/utilities/agent_utils.py+++ b/lib/crewai/src/crewai/utilities/agent_utils.py@@ -1453,8 +1453,8 @@ def execute_single_native_tool_call()from crewai.hooks.tool_hooks import (ToolCallHookContext,- get_after_tool_call_hooks,- get_before_tool_call_hooks,+ run_after_tool_call_hooks,+ run_before_tool_call_hooks,)info = extract_tool_call_info(tool_call)@@ -1517,7 +1517,6 @@ def execute_single_native_tool_call(track_delegation_if_needed(func_name, args_dict, task)- hook_blocked = Falsebefore_hook_context = ToolCallHookContext(tool_name=func_name,tool_input=args_dict,@@ -1526,13 +1525,7 @@ def execute_single_native_tool_call(task=task,crew=crew,)- try:- for hook in get_before_tool_call_hooks():- if hook(before_hook_context) is False:- hook_blocked = True- break- except Exception: # noqa: S110- pass+ hook_blocked = run_before_tool_call_hooks(before_hook_context)error_event_emitted = Falseif hook_blocked:@@ -1587,14 +1580,9 @@ def execute_single_native_tool_call(tool_result=result,raw_tool_result=raw_tool_result,)- try:- for after_hook in get_after_tool_call_hooks():- hook_result = after_hook(after_hook_context)- if hook_result is not None:- result = hook_result- after_hook_context.tool_result = result- except Exception: # noqa: S110- pass+ modified_result = run_after_tool_call_hooks(after_hook_context)+ if modified_result is not None:+ result = modified_resultif not error_event_emitted:crewai_event_bus.emit(@@ -1690,28 +1678,42 @@ def _setup_before_llm_call_hooks(Returns:True if LLM execution should proceed, False if blocked by a hook."""- if executor_context and executor_context.before_llm_call_hooks:- from crewai.hooks.llm_hooks import LLMCallHookContext+ if executor_context:+ from crewai.hooks.dispatch import (+ HookAborted,+ InterceptionPoint,+ get_scoped_hooks,+ run_hooks,+ )+ from crewai.hooks.llm_hooks import LLMCallHookContext, before_llm_call_reducer++ # Executor snapshot first, then execution-scoped hooks — the same+ # ordering dispatch() applies to global vs scoped hooks.+ hooks: list[Any] = [+ *executor_context.before_llm_call_hooks,+ *get_scoped_hooks(InterceptionPoint.PRE_MODEL_CALL),+ ]+ if not hooks:+ return Trueoriginal_messages = executor_context.messageshook_context = LLMCallHookContext(executor_context)try:- for hook in executor_context.before_llm_call_hooks:- result = hook(hook_context)- if result is False:- if verbose:- printer.print(- content="LLM call blocked by before_llm_call hook",- color="yellow",- )- return False- except Exception as e:+ run_hooks(+ InterceptionPoint.PRE_MODEL_CALL,+ hook_context,+ hooks,+ reducer=before_llm_call_reducer,+ verbose=verbose,+ )+ except HookAborted:if verbose:printer.print(- content=f"Error in before_llm_call hook: {e}",+ content="LLM call blocked by before_llm_call hook",color="yellow",)+ return Falseif not isinstance(executor_context.messages, list):if verbose:@@ -1748,8 +1750,9 @@ def _setup_after_llm_call_hooks(Returns:The potentially modified response (string or Pydantic model)."""- if executor_context and executor_context.after_llm_call_hooks:- from crewai.hooks.llm_hooks import LLMCallHookContext+ if executor_context:+ from crewai.hooks.dispatch import InterceptionPoint, get_scoped_hooks, run_hooks+ from crewai.hooks.llm_hooks import LLMCallHookContext, after_llm_call_reducer# Don't stringify structured tool-call payloads: the executor would# treat the result as a final answer and skip tool execution (#6529).@@ -1757,6 +1760,15 @@ def _setup_after_llm_call_hooks(if not isinstance(answer, (str, BaseModel)):return answer+ # Executor snapshot first, then execution-scoped hooks — the same+ # ordering dispatch() applies to global vs scoped hooks.+ hooks: list[Any] = [+ *executor_context.after_llm_call_hooks,+ *get_scoped_hooks(InterceptionPoint.POST_MODEL_CALL),+ ]+ if not hooks:+ return answer+original_messages = executor_context.messagesif isinstance(answer, BaseModel):@@ -1768,18 +1780,15 @@ def _setup_after_llm_call_hooks(hook_response = str(answer)hook_context = LLMCallHookContext(executor_context, response=hook_response)- try:- for hook in executor_context.after_llm_call_hooks:- modified_response = hook(hook_context)- if modified_response is not None and isinstance(modified_response, str):- hook_response = modified_response-- except Exception as e:- if verbose:- printer.print(- content=f"Error in after_llm_call hook: {e}",- color="yellow",- )+ run_hooks(+ InterceptionPoint.POST_MODEL_CALL,+ hook_context,+ hooks,+ reducer=after_llm_call_reducer,+ verbose=verbose,+ )+ if hook_context.response is not None:+ hook_response = hook_context.responseif not isinstance(executor_context.messages, list):if verbose:diff --git a/lib/crewai/src/crewai/utilities/tool_utils.py b/lib/crewai/src/crewai/utilities/tool_utils.pyindex dcb25594c..2d6e3c142 100644--- a/lib/crewai/src/crewai/utilities/tool_utils.py+++ b/lib/crewai/src/crewai/utilities/tool_utils.py@@ -6,15 +6,14 @@ from crewai.agents.parser import AgentActionfrom crewai.agents.tools_handler import ToolsHandlerfrom crewai.hooks.tool_hooks import (ToolCallHookContext,- get_after_tool_call_hooks,- get_before_tool_call_hooks,+ run_after_tool_call_hooks,+ run_before_tool_call_hooks,)from crewai.security.fingerprint import Fingerprintfrom crewai.tools.structured_tool import CrewStructuredToolfrom crewai.tools.tool_types import ToolResultfrom crewai.tools.tool_usage import ToolUsage, ToolUsageErrorfrom crewai.utilities.i18n import I18N_DEFAULT-from crewai.utilities.logger import Loggerfrom crewai.utilities.string_utils import sanitize_tool_name@@ -57,11 +56,10 @@ async def aexecute_tool_and_check_finality(fingerprint_context: Optional context for fingerprinting.crew: Optional crew instance for hook context.- Returns:+ Returns:ToolResult containing the execution result and whether it should betreated as a final answer."""- logger = Logger(verbose=crew.verbose if crew else False)tool_name_to_tool_map = {sanitize_tool_name(tool.name): tool for tool in tools}if agent_key and agent_role and agent:@@ -102,18 +100,27 @@ async def aexecute_tool_and_check_finality(crew=crew,)- before_hooks = get_before_tool_call_hooks()- try:- for hook in before_hooks:- result = hook(hook_context)- if result is False:- blocked_message = (- f"Tool execution blocked by hook. "- f"Tool: {tool_calling.tool_name}"- )- return ToolResult(blocked_message, False)- except Exception as e:- logger.log("error", f"Error in before_tool_call hook: {e}")+ if run_before_tool_call_hooks(hook_context):+ blocked_message = (+ f"Tool execution blocked by hook. Tool: {tool_calling.tool_name}"+ )+ # Run POST_TOOL_CALL even on a blocked call so monitoring hooks+ # still fire, matching the native tool-call paths.+ blocked_hook_context = ToolCallHookContext(+ tool_name=sanitized_tool_name,+ tool_input=tool_input,+ tool=tool,+ agent=agent,+ task=task,+ crew=crew,+ tool_result=blocked_message,+ raw_tool_result=blocked_message,+ )+ modified_result = run_after_tool_call_hooks(blocked_hook_context)+ return ToolResult(+ modified_result if modified_result is not None else blocked_message,+ False,+ )tool_result = await tool_usage.ause(tool_calling, agent_action.text)raw_tool_result = tool_usage.get_last_raw_result(tool_result)@@ -129,18 +136,12 @@ async def aexecute_tool_and_check_finality(raw_tool_result=raw_tool_result,)- after_hooks = get_after_tool_call_hooks()- modified_result: str = tool_result- try:- for after_hook in after_hooks:- hook_result = after_hook(after_hook_context)- if hook_result is not None:- modified_result = hook_result- after_hook_context.tool_result = modified_result- except Exception as e:- logger.log("error", f"Error in after_tool_call hook: {e}")+ modified_result = run_after_tool_call_hooks(after_hook_context)- return ToolResult(modified_result, tool.result_as_answer)+ return ToolResult(+ modified_result if modified_result is not None else tool_result,+ tool.result_as_answer,+ )tool_result = I18N_DEFAULT.errors("wrong_tool_name").format(tool=sanitized_tool_name,@@ -181,7 +182,6 @@ def execute_tool_and_check_finality(Returns:ToolResult containing the execution result and whether it should be treated as a final answer"""- logger = Logger(verbose=crew.verbose if crew else False)tool_name_to_tool_map = {sanitize_tool_name(tool.name): tool for tool in tools}if agent_key and agent_role and agent:@@ -222,18 +222,27 @@ def execute_tool_and_check_finality(crew=crew,)- before_hooks = get_before_tool_call_hooks()- try:- for hook in before_hooks:- result = hook(hook_context)- if result is False:- blocked_message = (- f"Tool execution blocked by hook. "- f"Tool: {tool_calling.tool_name}"- )- return ToolResult(blocked_message, False)- except Exception as e:- logger.log("error", f"Error in before_tool_call hook: {e}")+ if run_before_tool_call_hooks(hook_context):+ blocked_message = (+ f"Tool execution blocked by hook. Tool: {tool_calling.tool_name}"+ )+ # Run POST_TOOL_CALL even on a blocked call so monitoring hooks+ # still fire, matching the native tool-call paths.+ blocked_hook_context = ToolCallHookContext(+ tool_name=sanitized_tool_name,+ tool_input=tool_input,+ tool=tool,+ agent=agent,+ task=task,+ crew=crew,+ tool_result=blocked_message,+ raw_tool_result=blocked_message,+ )+ modified_result = run_after_tool_call_hooks(blocked_hook_context)+ return ToolResult(+ modified_result if modified_result is not None else blocked_message,+ False,+ )tool_result = tool_usage.use(tool_calling, agent_action.text)raw_tool_result = tool_usage.get_last_raw_result(tool_result)@@ -249,18 +258,12 @@ def execute_tool_and_check_finality(raw_tool_result=raw_tool_result,)- after_hooks = get_after_tool_call_hooks()- modified_result: str = tool_result- try:- for after_hook in after_hooks:- hook_result = after_hook(after_hook_context)- if hook_result is not None:- modified_result = hook_result- after_hook_context.tool_result = modified_result- except Exception as e:- logger.log("error", f"Error in after_tool_call hook: {e}")-- return ToolResult(modified_result, tool.result_as_answer)+ modified_result = run_after_tool_call_hooks(after_hook_context)++ return ToolResult(+ modified_result if modified_result is not None else tool_result,+ tool.result_as_answer,+ )tool_result = I18N_DEFAULT.errors("wrong_tool_name").format(tool=sanitized_tool_name,diff --git a/lib/crewai/tests/hooks/test_crew_scoped_hooks.py b/lib/crewai/tests/hooks/test_crew_scoped_hooks.pyindex cf567a333..b0f8e1eb2 100644--- a/lib/crewai/tests/hooks/test_crew_scoped_hooks.py+++ b/lib/crewai/tests/hooks/test_crew_scoped_hooks.py@@ -306,6 +306,62 @@ class TestCrewScopedHooks:assert len(execution_log) == 1+class TestCrewOnDecoratedMethods:+ """@on(InterceptionPoint.X) methods inside @CrewBase must register.++ Regression: CrewBase only scanned the legacy ``is_*_hook`` markers, so+ methods decorated with the generic ``@on`` decorator (which sets+ ``_interception_point``) were silently dropped and never ran.+ """++ def test_on_decorated_method_registers_and_binds_self(self):+ from crewai.hooks import InterceptionPoint, on+ from crewai.hooks.dispatch import _resolve_hooks++ execution_log = []++ @CrewBase+ class TestCrew:+ def __init__(self):+ self.name = "on-crew"++ @on(InterceptionPoint.PRE_MODEL_CALL)+ def on_pre_model(self, context):+ execution_log.append(self.name)++ @agent+ def researcher(self):+ return Agent(role="Researcher", goal="Research", backstory="Expert")++ @crew+ def crew(self):+ return Crew(agents=self.agents, tasks=[], verbose=False)++ before = len(_resolve_hooks(InterceptionPoint.PRE_MODEL_CALL))++ instance = TestCrew()++ hooks = _resolve_hooks(InterceptionPoint.PRE_MODEL_CALL)+ assert len(hooks) == before + 1++ assert (+ InterceptionPoint.PRE_MODEL_CALL.value,+ hooks[-1],+ ) in instance._registered_hook_functions++ mock_executor = Mock()+ mock_executor.messages = []+ mock_executor.agent = Mock(role="Test")+ mock_executor.task = Mock()+ mock_executor.crew = Mock()+ mock_executor.llm = Mock()+ mock_executor.iterations = 0++ hooks[-1](LLMCallHookContext(executor=mock_executor))++ assert execution_log == ["on-crew"]++class TestCrewScopedHookAttributes:"""Test that crew-scoped hooks have correct attributes set."""diff --git a/lib/crewai/tests/hooks/test_dispatch.py b/lib/crewai/tests/hooks/test_dispatch.pynew file mode 100644index 000000000..9aa5d5912--- /dev/null+++ b/lib/crewai/tests/hooks/test_dispatch.py@@ -0,0 +1,296 @@+"""Unit tests for the generic interception-hook dispatcher.++These cover the new contract (payload-in/payload-out + HookAborted), the shared+ordered queue between the legacy and new dialects on the four model/tool points,+execution-scoped hooks, fail-open exception handling, telemetry, and the no-op+fast-path overhead budget.+"""++from __future__ import annotations++from dataclasses import dataclass+import time++from crewai.events.event_bus import crewai_event_bus+from crewai.events.types.hook_events import HookDispatchedEvent+from crewai.hooks.dispatch import (+ HookAborted,+ InterceptionPoint,+ clear_all,+ dispatch,+ get_hooks,+ on,+ register,+ register_scoped,+ scoped_hooks,+ unregister as unregister_hook,+)+from crewai.hooks.llm_hooks import (+ get_before_llm_call_hooks,+ register_before_llm_call_hook,+)+import pytest+++@dataclass+class _Ctx:+ payload: object = None+ tool_name: str | None = None+ agent: object = None+ agent_role: str | None = None++[email protected](autouse=True)+def clear_dispatch_registry():+ """Ensure every test starts and ends with an empty global registry."""+ clear_all()+ yield+ clear_all()+++class TestDispatchContract:+ """The core payload-in/payload-out + HookAborted contract."""++ def test_noop_fast_path_returns_context_unchanged(self):+ ctx = _Ctx(payload="original")+ result = dispatch(InterceptionPoint.PRE_MODEL_CALL, ctx)+ assert result is ctx+ assert ctx.payload == "original"++ def test_return_value_replaces_payload(self):+ def double(ctx):+ return ctx.payload * 2++ register(InterceptionPoint.PRE_MODEL_CALL, double)+ ctx = _Ctx(payload="ab")+ dispatch(InterceptionPoint.PRE_MODEL_CALL, ctx)+ assert ctx.payload == "abab"++ def test_in_place_mutation_is_honored(self):+ def mutate(ctx):+ ctx.payload.append(1)+ return None++ register(InterceptionPoint.PRE_MODEL_CALL, mutate)+ ctx = _Ctx(payload=[])+ dispatch(InterceptionPoint.PRE_MODEL_CALL, ctx)+ assert ctx.payload == [1]++ def test_hooks_run_in_registration_order(self):+ order: list[int] = []+ register(InterceptionPoint.PRE_MODEL_CALL, lambda ctx: order.append(1))+ register(InterceptionPoint.PRE_MODEL_CALL, lambda ctx: order.append(2))+ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx())+ assert order == [1, 2]++ def test_hook_aborted_propagates_with_reason_and_source(self):+ def blocker(ctx):+ raise HookAborted(reason="nope", source="policy")++ register(InterceptionPoint.PRE_MODEL_CALL, blocker)+ with pytest.raises(HookAborted) as exc:+ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx())+ assert exc.value.reason == "nope"+ assert exc.value.source == "policy"++ def test_ordinary_exception_is_swallowed_and_later_hooks_run(self):+ ran: list[str] = []++ def boom(ctx):+ ran.append("boom")+ raise ValueError("bug in user hook")++ def after(ctx):+ ran.append("after")++ register(InterceptionPoint.PRE_MODEL_CALL, boom)+ register(InterceptionPoint.PRE_MODEL_CALL, after)+ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx(), verbose=False)+ assert ran == ["boom", "after"]+++class TestOnDecorator:+ """The @on decorator registers and filters like the legacy decorators."""++ def test_on_registers_global_hook(self):+ @on(InterceptionPoint.POST_TOOL_CALL)+ def hook(ctx):+ return None++ assert hook in get_hooks(InterceptionPoint.POST_TOOL_CALL)++ def test_tool_filter_skips_non_matching_tools(self):+ seen: list[str] = []++ @on(InterceptionPoint.PRE_TOOL_CALL, tools=["allowed_tool"])+ def hook(ctx):+ seen.append(ctx.tool_name)++ dispatch(InterceptionPoint.PRE_TOOL_CALL, _Ctx(tool_name="other_tool"))+ dispatch(InterceptionPoint.PRE_TOOL_CALL, _Ctx(tool_name="allowed_tool"))+ assert seen == ["allowed_tool"]++ def test_agent_filter_skips_non_matching_agents(self):+ seen: list[str] = []++ class _Agent:+ def __init__(self, role):+ self.role = role++ @on(InterceptionPoint.PRE_MODEL_CALL, agents=["Researcher"])+ def hook(ctx):+ seen.append(ctx.agent.role)++ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx(agent=_Agent("Writer")))+ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx(agent=_Agent("Researcher")))+ assert seen == ["Researcher"]++ def test_agent_filter_falls_back_to_agent_role(self):+ seen: list[str] = []++ @on(InterceptionPoint.PRE_TOOL_CALL, agents=["Researcher"])+ def hook(ctx):+ seen.append(ctx.agent_role)++ # No agent object, only the agent_role string (e.g. flow seams).+ dispatch(InterceptionPoint.PRE_TOOL_CALL, _Ctx(agent_role="Writer"))+ dispatch(InterceptionPoint.PRE_TOOL_CALL, _Ctx(agent_role="Researcher"))+ assert seen == ["Researcher"]++ def test_unregister_resolves_filtered_wrapper(self):+ @on(InterceptionPoint.PRE_TOOL_CALL, tools=["allowed_tool"])+ def hook(ctx):+ return None++ assert len(get_hooks(InterceptionPoint.PRE_TOOL_CALL)) == 1+ assert unregister_hook(InterceptionPoint.PRE_TOOL_CALL, hook) is True+ assert get_hooks(InterceptionPoint.PRE_TOOL_CALL) == []+++class TestSharedQueueWithLegacyDialect:+ """Legacy registrations and @on hooks compose in one ordered queue."""++ def test_on_and_legacy_share_pre_model_call_queue(self):+ def legacy(ctx):+ return None++ @on(InterceptionPoint.PRE_MODEL_CALL)+ def modern(ctx):+ return None++ register_before_llm_call_hook(legacy)++ queue = get_before_llm_call_hooks()+ assert modern in queue+ assert legacy in queue+ # registration order preserved: modern registered before legacy+ assert queue.index(modern) < queue.index(legacy)+++class TestScopedHooks:+ """Execution-scoped hooks run after globals and are discarded on exit."""++ def test_scoped_runs_after_global_then_cleared(self):+ order: list[str] = []+ register(InterceptionPoint.POST_MODEL_CALL, lambda ctx: order.append("global"))++ with scoped_hooks():+ register_scoped(InterceptionPoint.POST_MODEL_CALL, lambda ctx: order.append("scoped"))+ dispatch(InterceptionPoint.POST_MODEL_CALL, _Ctx())++ # outside the scope the scoped hook is gone+ dispatch(InterceptionPoint.POST_MODEL_CALL, _Ctx())++ assert order == ["global", "scoped", "global"]+++class TestTelemetry:+ """dispatch emits a HookDispatchedEvent only when hooks ran."""++ def test_no_event_on_empty_fast_path(self):+ events: list[HookDispatchedEvent] = []+ with crewai_event_bus.scoped_handlers():++ @crewai_event_bus.on(HookDispatchedEvent)+ def _capture(_source, event):+ events.append(event)++ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx())++ assert events == []++ def test_event_reports_outcome(self):+ events: list[HookDispatchedEvent] = []++ register(InterceptionPoint.PRE_MODEL_CALL, lambda ctx: "changed")++ with crewai_event_bus.scoped_handlers():++ @crewai_event_bus.on(HookDispatchedEvent)+ def _capture(_source, event):+ events.append(event)++ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx())+ # Telemetry handlers run on the bus's thread pool; flush so the+ # assertion doesn't race the emit.+ crewai_event_bus.flush()++ assert len(events) == 1+ assert events[0].interception_point == "pre_model_call"+ assert events[0].outcome == "modified"+ assert events[0].hook_count == 1++ def test_event_reports_abort_outcome(self):+ events: list[HookDispatchedEvent] = []++ def blocker(ctx):+ raise HookAborted(reason="blocked", source="policy")++ register(InterceptionPoint.PRE_MODEL_CALL, blocker)++ with crewai_event_bus.scoped_handlers():++ @crewai_event_bus.on(HookDispatchedEvent)+ def _capture(_source, event):+ events.append(event)++ with pytest.raises(HookAborted):+ dispatch(InterceptionPoint.PRE_MODEL_CALL, _Ctx())+ crewai_event_bus.flush()++ assert len(events) == 1+ assert events[0].interception_point == "pre_model_call"+ assert events[0].outcome == "aborted"+ assert events[0].abort_reason == "blocked"+ assert events[0].abort_source == "policy"+++class TestNoOpOverhead:+ """The no-op fast path must stay cheap (a single dict lookup)."""++ def test_noop_dispatch_overhead_is_bounded(self):+ # Relative (not absolute) budget: the no-op fast path is a dict lookup+ # plus a guard, so it should stay within a wide multiple of a bare+ # function call. This catches accidental O(n) regressions without+ # depending on absolute timing on shared CI runners.+ ctx = _Ctx()+ iterations = 100_000++ def _baseline(_c):+ return _c++ for _ in range(1000): # warm up both paths+ dispatch(InterceptionPoint.PRE_MODEL_CALL, ctx)+ _baseline(ctx)++ start = time.perf_counter()+ for _ in range(iterations):+ _baseline(ctx)+ baseline = time.perf_counter() - start++ start = time.perf_counter()+ for _ in range(iterations):+ dispatch(InterceptionPoint.PRE_MODEL_CALL, ctx)+ noop = time.perf_counter() - start++ assert noop < baseline * 50 + 5e-3diff --git a/lib/crewai/tests/hooks/test_llm_hooks.py b/lib/crewai/tests/hooks/test_llm_hooks.pyindex 7b8add697..0c917712d 100644--- a/lib/crewai/tests/hooks/test_llm_hooks.py+++ b/lib/crewai/tests/hooks/test_llm_hooks.py@@ -337,6 +337,105 @@ class TestLLMHooksIntegration:hooks = get_before_llm_call_hooks()assert len(hooks) == 0+ def test_raising_before_hook_does_not_skip_later_hooks(self, mock_executor):+ """Fail-open is per-hook: a crashing hook must not disable its neighbors.++ Regression guard for the dispatcher migration: previously the+ ``except Exception`` wrapped the whole hook loop, so a raising hook+ silently skipped every hook registered after it. Now swallowing is+ per-hook — later hooks still run and the LLM call still proceeds.+ """+ from crewai.utilities.agent_utils import _setup_before_llm_call_hooks++ ran: list[str] = []++ def crashing_hook(context):+ ran.append("crashing")+ raise ValueError("bug in user hook")++ def later_hook(context):+ ran.append("later")++ register_before_llm_call_hook(crashing_hook)+ register_before_llm_call_hook(later_hook)+ mock_executor.before_llm_call_hooks = get_before_llm_call_hooks()++ proceed = _setup_before_llm_call_hooks(+ mock_executor, printer=Mock(), verbose=False+ )++ assert ran == ["crashing", "later"]+ assert proceed is True++ def test_scoped_hooks_fire_on_agent_executor_llm_seams(self, mock_executor):+ """register_scoped hooks must run on the executor model seams.++ Regression: `_setup_before/after_llm_call_hooks` only ran the+ executor's snapshot lists, so execution-scoped hooks never fired on+ PRE/POST_MODEL_CALL during normal agent execution (while tool seams,+ which go through `dispatch`, merged them). Scoped hooks run after the+ snapshot, matching dispatch's global-then-scoped ordering.+ """+ from crewai.hooks import InterceptionPoint+ from crewai.hooks.dispatch import register_scoped, scoped_hooks+ from crewai.utilities.agent_utils import (+ _setup_after_llm_call_hooks,+ _setup_before_llm_call_hooks,+ )++ order: list[str] = []++ def snapshot_hook(context):+ order.append("snapshot")++ mock_executor.before_llm_call_hooks = [snapshot_hook]+ mock_executor.after_llm_call_hooks = []++ with scoped_hooks():+ register_scoped(+ InterceptionPoint.PRE_MODEL_CALL,+ lambda ctx: order.append("scoped_pre"),+ )+ register_scoped(+ InterceptionPoint.POST_MODEL_CALL,+ lambda ctx: order.append("scoped_post"),+ )++ proceed = _setup_before_llm_call_hooks(+ mock_executor, printer=Mock(), verbose=False+ )+ answer = _setup_after_llm_call_hooks(+ mock_executor, "answer", printer=Mock(), verbose=False+ )++ assert order == ["snapshot", "scoped_pre", "scoped_post"]+ assert proceed is True+ assert answer == "answer"++ def test_intentional_block_still_short_circuits_later_hooks(self, mock_executor):+ """A hook returning False blocks the call and skips later hooks (unchanged)."""+ from crewai.utilities.agent_utils import _setup_before_llm_call_hooks++ ran: list[str] = []++ def blocking_hook(context):+ ran.append("blocking")+ return False++ def later_hook(context):+ ran.append("later")++ register_before_llm_call_hook(blocking_hook)+ register_before_llm_call_hook(later_hook)+ mock_executor.before_llm_call_hooks = get_before_llm_call_hooks()++ proceed = _setup_before_llm_call_hooks(+ mock_executor, printer=Mock(), verbose=False+ )++ assert ran == ["blocking"]+ assert proceed is False+@pytest.mark.vcr()def test_lite_agent_hooks_integration_with_real_llm(self):"""Test that LiteAgent executes before/after LLM call hooks and prints messages correctly."""@@ -497,3 +596,77 @@ class TestLLMHooksIntegration:finally:unregister_before_llm_call_hook(before_hook)unregister_after_llm_call_hook(after_hook)+++class TestDirectLLMScopedHooks:+ """Direct (agent-less) LLM calls must honor execution-scoped hooks.++ Regression: the direct-call helpers used to short-circuit when the global+ hook list was empty, so hooks registered only for the current+ ``scoped_hooks()`` context never ran on this path.+ """++ @staticmethod+ def _stub_llm():+ from crewai.llms.base_llm import BaseLLM++ class _StubLLM(BaseLLM):+ def call(self, *args: object, **kwargs: object) -> str:+ return ""++ return _StubLLM(model="stub")++ def test_scoped_before_hook_runs_on_direct_call(self):+ from crewai.hooks import InterceptionPoint+ from crewai.hooks.dispatch import register_scoped, scoped_hooks++ llm = self._stub_llm()+ seen: list[int] = []++ with scoped_hooks():+ register_scoped(+ InterceptionPoint.PRE_MODEL_CALL,+ lambda ctx: seen.append(len(ctx.messages)),+ )+ proceed = llm._invoke_before_llm_call_hooks(+ [{"role": "user", "content": "hi"}], from_agent=None+ )++ assert proceed is True+ assert seen == [1]++ def test_scoped_before_hook_can_block_direct_call(self):+ from crewai.hooks import InterceptionPoint+ from crewai.hooks.dispatch import HookAborted, register_scoped, scoped_hooks++ llm = self._stub_llm()++ def block(ctx: LLMCallHookContext) -> None:+ raise HookAborted(reason="blocked by scoped hook")++ with scoped_hooks():+ register_scoped(InterceptionPoint.PRE_MODEL_CALL, block)+ proceed = llm._invoke_before_llm_call_hooks(+ [{"role": "user", "content": "hi"}], from_agent=None+ )++ assert proceed is False++ def test_scoped_after_hook_modifies_direct_response(self):+ from crewai.hooks import InterceptionPoint+ from crewai.hooks.dispatch import register_scoped, scoped_hooks++ llm = self._stub_llm()++ def redact(ctx: LLMCallHookContext) -> str:+ return ctx.response.replace("SECRET", "[REDACTED]")++ with scoped_hooks():+ register_scoped(InterceptionPoint.POST_MODEL_CALL, redact)+ result = llm._invoke_after_llm_call_hooks(+ [{"role": "user", "content": "hi"}],+ "contains SECRET",+ from_agent=None,+ )++ assert result == "contains [REDACTED]"diff --git a/lib/crewai/tests/hooks/test_tool_hooks.py b/lib/crewai/tests/hooks/test_tool_hooks.pyindex 14c6848a8..4978f14b8 100644--- a/lib/crewai/tests/hooks/test_tool_hooks.py+++ b/lib/crewai/tests/hooks/test_tool_hooks.py@@ -576,6 +576,75 @@ class TestToolHooksIntegration:unregister_after_tool_call_hook(after_tool_call_hook)+class TestPerHookFailOpen:+ """Fail-open is per-hook: a crashing hook must not disable its neighbors.++ Regression guards for the dispatcher migration: previously each seam's+ ``except Exception`` wrapped the whole hook loop, so a raising hook+ silently skipped every hook registered after it.+ """++ def test_raising_before_hook_does_not_skip_later_hooks_or_block(+ self, mock_tool, mock_agent+ ):+ from crewai.hooks.tool_hooks import run_before_tool_call_hooks++ mock_agent.verbose = False+ ran: list[str] = []++ def crashing_hook(context):+ ran.append("crashing")+ raise ValueError("bug in user hook")++ def later_hook(context):+ ran.append("later")++ register_before_tool_call_hook(crashing_hook)+ register_before_tool_call_hook(later_hook)++ context = ToolCallHookContext(+ tool_name="test_tool",+ tool_input={"arg": "value"},+ tool=mock_tool,+ agent=mock_agent,+ )+ blocked = run_before_tool_call_hooks(context)++ assert ran == ["crashing", "later"]+ assert blocked is False++ def test_raising_after_hook_does_not_skip_later_result_rewrites(+ self, mock_tool, mock_agent+ ):+ from crewai.hooks.tool_hooks import run_after_tool_call_hooks++ mock_agent.verbose = False+ ran: list[str] = []++ def crashing_hook(context):+ ran.append("crashing")+ raise ValueError("bug in user hook")++ def rewriting_hook(context):+ ran.append("rewriting")+ return f"{context.tool_result} [rewritten]"++ register_after_tool_call_hook(crashing_hook)+ register_after_tool_call_hook(rewriting_hook)++ context = ToolCallHookContext(+ tool_name="test_tool",+ tool_input={"arg": "value"},+ tool=mock_tool,+ agent=mock_agent,+ tool_result="original",+ )+ result = run_after_tool_call_hooks(context)++ assert ran == ["crashing", "rewriting"]+ assert result == "original [rewritten]"++class TestNativeToolCallingHooksIntegration:"""Integration tests for hooks with native function calling (Agent and Crew)."""