chore: extension points

Introduce ContextVar-backed hooks and small API/behavior changes to improve extensibility and testability.

Changes include:
- agents: mark configure_structured_output as abstract and change its parameter to task to reflect use of task metadata.
- tracing: convert _first_time_trace_hook to a ContextVar and call .get() to safely retrieve the hook.
- console formatter: add _disable_version_check ContextVar and skip version checks when set (avoids noisy checks in certain contexts).
- flow: use current_triggering_event_id variable when scheduling listener tasks to keep naming consistent.
- hallucination guardrail: make context optional, add _validate_output_hook to allow custom validation hooks, update examples and return contract to allow hooks to override behavior.
- agent utilities: add _create_plus_client_hook for injecting a Plus client (used in tests/alternate flows), ensure structured tools have current_usage_count initialized and propagate to original tool, and fall back to creating PlusAPI client when no hook is provided.

lib/crewai/src/crewai/agents/agent_adapters/base_agent_adapter.py

@@ -37,9 +37,10 @@ class BaseAgentAdapter(BaseAgent, ABC):
             tools: Optional list of BaseTool instances to be configured
         """
 
-    def configure_structured_output(self, structured_output: Any) -> None:
+    @abstractmethod
+    def configure_structured_output(self, task: Any) -> None:
         """Configure the structured output for the specific agent implementation.
 
         Args:
-            structured_output: The structured output to be configured
+            task: The task object containing output format specifications.
         """

lib/crewai/src/crewai/crew.py

@@ -2026,7 +2026,13 @@ class Crew(FlowTrackable, BaseModel):
     @staticmethod
     def _show_tracing_disabled_message() -> None:
         """Show a message when tracing is disabled."""
-        from crewai.events.listeners.tracing.utils import has_user_declined_tracing
+        from crewai.events.listeners.tracing.utils import (
+            has_user_declined_tracing,
+            should_suppress_tracing_messages,
+        )
+
+        if should_suppress_tracing_messages():
+            return
 
         console = Console()
 

lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py

@@ -797,7 +797,13 @@ class TraceCollectionListener(BaseEventListener):
         from rich.console import Console
         from rich.panel import Panel
 
-        from crewai.events.listeners.tracing.utils import has_user_declined_tracing
+        from crewai.events.listeners.tracing.utils import (
+            has_user_declined_tracing,
+            should_suppress_tracing_messages,
+        )
+
+        if should_suppress_tracing_messages():
+            return
 
         console = Console()
 

lib/crewai/src/crewai/events/listeners/tracing/utils.py

@@ -27,7 +27,34 @@ logger = logging.getLogger(__name__)
 
 _tracing_enabled: ContextVar[bool | None] = ContextVar("_tracing_enabled", default=None)
 
-_first_time_trace_hook: Callable[[], bool] | None = None
+_first_time_trace_hook: ContextVar[Callable[[], bool] | None] = ContextVar(
+    "_first_time_trace_hook", default=None
+)
+
+_suppress_tracing_messages: ContextVar[bool] = ContextVar(
+    "_suppress_tracing_messages", default=False
+)
+
+
+def set_suppress_tracing_messages(suppress: bool) -> object:
+    """Set whether to suppress tracing-related console messages.
+
+    Args:
+        suppress: True to suppress messages, False to show them.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    return _suppress_tracing_messages.set(suppress)
+
+
+def should_suppress_tracing_messages() -> bool:
+    """Check if tracing messages should be suppressed.
+
+    Returns:
+        True if messages should be suppressed, False otherwise.
+    """
+    return _suppress_tracing_messages.get()
 
 
 def should_enable_tracing(*, override: bool | None = None) -> bool:
@@ -413,8 +440,9 @@ def should_auto_collect_first_time_traces() -> bool:
     Returns:
         True if first-time user AND telemetry not disabled AND tracing not explicitly enabled, False otherwise.
     """
-    if _first_time_trace_hook is not None:
-        return _first_time_trace_hook()
+    hook = _first_time_trace_hook.get()
+    if hook is not None:
+        return hook()
 
     if _is_test_environment():
         return False
@@ -437,6 +465,9 @@ def prompt_user_for_trace_viewing(timeout_seconds: int = 20) -> bool:
     if _is_test_environment():
         return False
 
+    if should_suppress_tracing_messages():
+        return False
+
     try:
         import threading
 

lib/crewai/src/crewai/events/utils/console_formatter.py

@@ -1,3 +1,4 @@
+from contextvars import ContextVar
 import os
 import threading
 from typing import Any, ClassVar, cast
@@ -10,6 +11,36 @@ from rich.text import Text
 from crewai.cli.version import is_newer_version_available
 
 
+_disable_version_check: ContextVar[bool] = ContextVar(
+    "_disable_version_check", default=False
+)
+
+_suppress_console_output: ContextVar[bool] = ContextVar(
+    "_suppress_console_output", default=False
+)
+
+
+def set_suppress_console_output(suppress: bool) -> object:
+    """Set whether to suppress all console output.
+
+    Args:
+        suppress: True to suppress output, False to show it.
+
+    Returns:
+        A token that can be used to restore the previous value.
+    """
+    return _suppress_console_output.set(suppress)
+
+
+def should_suppress_console_output() -> bool:
+    """Check if console output should be suppressed.
+
+    Returns:
+        True if output should be suppressed, False otherwise.
+    """
+    return _suppress_console_output.get()
+
+
 class ConsoleFormatter:
     tool_usage_counts: ClassVar[dict[str, int]] = {}
 
@@ -46,6 +77,9 @@ class ConsoleFormatter:
         if not self.verbose:
             return
 
+        if _disable_version_check.get():
+            return
+
         if os.getenv("CI", "").lower() in ("true", "1"):
             return
 
@@ -79,8 +113,12 @@ To update, run: uv sync --upgrade-package crewai"""
         from crewai.events.listeners.tracing.utils import (
             has_user_declined_tracing,
             is_tracing_enabled_in_context,
+            should_suppress_tracing_messages,
         )
 
+        if should_suppress_tracing_messages():
+            return
+
         if not is_tracing_enabled_in_context():
             if has_user_declined_tracing():
                 message = """Info: Tracing is disabled.
@@ -132,6 +170,8 @@ To enable tracing, do any one of these:
 
     def print(self, *args: Any, **kwargs: Any) -> None:
         """Print to console. Simplified to only handle panel-based output."""
+        if should_suppress_console_output():
+            return
         # Skip blank lines during streaming
         if len(args) == 0 and self._is_streaming:
             return
@@ -488,6 +528,9 @@ To enable tracing, do any one of these:
         if not self.verbose:
             return
 
+        if should_suppress_console_output():
+            return
+
         self._is_streaming = True
         self._last_stream_call_type = call_type
 

lib/crewai/src/crewai/flow/flow.py

@@ -45,6 +45,7 @@ from crewai.events.listeners.tracing.utils import (
     has_user_declined_tracing,
     set_tracing_enabled,
     should_enable_tracing,
+    should_suppress_tracing_messages,
 )
 from crewai.events.types.flow_events import (
     FlowCreatedEvent,
@@ -2074,12 +2075,14 @@ class Flow(Generic[T], metaclass=FlowMeta):
                             racing_members,
                             other_listeners,
                             listener_result,
-                            triggering_event_id,
+                            current_triggering_event_id,
                         )
                     else:
                         tasks = [
                             self._execute_single_listener(
-                                listener_name, listener_result, triggering_event_id
+                                listener_name,
+                                listener_result,
+                                current_triggering_event_id,
                             )
                             for listener_name in listeners_triggered
                         ]
@@ -2626,6 +2629,8 @@ class Flow(Generic[T], metaclass=FlowMeta):
     @staticmethod
     def _show_tracing_disabled_message() -> None:
         """Show a message when tracing is disabled."""
+        if should_suppress_tracing_messages():
+            return
 
         console = Console()
 

lib/crewai/src/crewai/tasks/hallucination_guardrail.py

@@ -6,6 +6,7 @@ Classes:
     HallucinationGuardrail: Placeholder guardrail that validates task outputs.
 """
 
+from collections.abc import Callable
 from typing import Any
 
 from crewai.llm import LLM
@@ -13,32 +14,36 @@ from crewai.tasks.task_output import TaskOutput
 from crewai.utilities.logger import Logger
 
 
+_validate_output_hook: Callable[..., tuple[bool, Any]] | None = None
+
+
 class HallucinationGuardrail:
     """Placeholder for the HallucinationGuardrail feature.
 
     Attributes:
-        context: The reference context that outputs would be checked against.
+        context: Optional reference context that outputs would be checked against.
         llm: The language model that would be used for evaluation.
         threshold: Optional minimum faithfulness score that would be required to pass.
         tool_response: Optional tool response information that would be used in evaluation.
 
     Examples:
-        >>> # Basic usage with default verdict logic
+        >>> # Basic usage without context (uses task expected_output as context)
+        >>> guardrail = HallucinationGuardrail(llm=agent.llm)
+
+        >>> # With context for reference
         >>> guardrail = HallucinationGuardrail(
-        ...     context="AI helps with various tasks including analysis and generation.",
         ...     llm=agent.llm,
+        ...     context="AI helps with various tasks including analysis and generation.",
         ... )
 
         >>> # With custom threshold for stricter validation
         >>> strict_guardrail = HallucinationGuardrail(
-        ...     context="Quantum computing uses qubits in superposition.",
         ...     llm=agent.llm,
-        ...     threshold=8.0,  # Would require score >= 8 to pass in enterprise version
+        ...     threshold=8.0,  # Require score >= 8 to pass
         ... )
 
         >>> # With tool response for additional context
         >>> guardrail_with_tools = HallucinationGuardrail(
-        ...     context="The current weather data",
         ...     llm=agent.llm,
         ...     tool_response="Weather API returned: Temperature 22°C, Humidity 65%",
         ... )
@@ -46,16 +51,17 @@ class HallucinationGuardrail:
 
     def __init__(
         self,
-        context: str,
         llm: LLM,
+        context: str | None = None,
         threshold: float | None = None,
         tool_response: str = "",
     ):
         """Initialize the HallucinationGuardrail placeholder.
 
         Args:
-            context: The reference context that outputs would be checked against.
             llm: The language model that would be used for evaluation.
+            context: Optional reference context that outputs would be checked against.
+                If not provided, the task's expected_output will be used as context.
             threshold: Optional minimum faithfulness score that would be required to pass.
             tool_response: Optional tool response information that would be used in evaluation.
         """
@@ -78,16 +84,17 @@ class HallucinationGuardrail:
     def __call__(self, task_output: TaskOutput) -> tuple[bool, Any]:
         """Validate a task output against hallucination criteria.
 
-        In the open source, this method always returns that the output is valid.
-
         Args:
             task_output: The output to be validated.
 
         Returns:
             A tuple containing:
-                - True
-                - The raw task output
+                - True if validation passed, False otherwise
+                - The raw task output if valid, or error feedback if invalid
         """
+        if callable(_validate_output_hook):
+            return _validate_output_hook(self, task_output)
+
         self._logger.log(
             "warning",
             "Premium hallucination detection skipped (use for free at https://app.crewai.com)\n",

lib/crewai/src/crewai/utilities/agent_utils.py

@@ -42,6 +42,8 @@ if TYPE_CHECKING:
     from crewai.llm import LLM
     from crewai.task import Task
 
+_create_plus_client_hook: Callable[[], Any] | None = None
+
 
 class SummaryContent(TypedDict):
     """Structure for summary content entries.
@@ -91,7 +93,11 @@ def parse_tools(tools: list[BaseTool]) -> list[CrewStructuredTool]:
 
     for tool in tools:
         if isinstance(tool, CrewAITool):
-            tools_list.append(tool.to_structured_tool())
+            structured_tool = tool.to_structured_tool()
+            structured_tool.current_usage_count = 0
+            if structured_tool._original_tool:
+                structured_tool._original_tool.current_usage_count = 0
+            tools_list.append(structured_tool)
         else:
             raise ValueError("Tool is not a CrewStructuredTool or BaseTool")
 
@@ -818,10 +824,13 @@ def load_agent_from_repository(from_repository: str) -> dict[str, Any]:
     if from_repository:
         import importlib
 
-        from crewai.cli.authentication.token import get_auth_token
-        from crewai.cli.plus_api import PlusAPI
+        if callable(_create_plus_client_hook):
+            client = _create_plus_client_hook()
+        else:
+            from crewai.cli.authentication.token import get_auth_token
+            from crewai.cli.plus_api import PlusAPI
 
-        client = PlusAPI(api_key=get_auth_token())
+            client = PlusAPI(api_key=get_auth_token())
         _print_current_organization()
         response = client.get_agent(from_repository)
         if response.status_code == 404:

lib/crewai/src/crewai/utilities/printer.py

@@ -4,6 +4,8 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Final, Literal, NamedTuple
 
+from crewai.events.utils.console_formatter import should_suppress_console_output
+
 
 if TYPE_CHECKING:
     from _typeshed import SupportsWrite
@@ -77,6 +79,8 @@ class Printer:
             file: A file-like object (stream); defaults to the current sys.stdout.
             flush: Whether to forcibly flush the stream.
         """
+        if should_suppress_console_output():
+            return
         if isinstance(content, str):
             content = [ColoredText(content, color)]
         print(

lib/crewai/tests/agents/agent_adapters/test_base_agent_adapter.py

@@ -51,6 +51,10 @@ class ConcreteAgentAdapter(BaseAgentAdapter):
         # Dummy implementation for MCP tools
         return []
 
+    def configure_structured_output(self, task: Any) -> None:
+        # Dummy implementation for structured output
+        pass
+
     async def aexecute_task(
         self,
         task: Any,