fix(tools): address review round 1 on tool-failure signalling

Five real defects from Bugbot, none of them cosmetic.

Tool-scoped policy never applied (high). `resolve_tool_failure_policy`
read `tool_failure_policy` off the object handed to it, but every
execution path passes the `CrewStructuredTool` wrapper, which never
carried the attribute -- and `BaseTool` never declared it in the first
place. A tool-scoped `raise`/`ignore` was silently ignored while the
docs and a unit test claimed otherwise; the test passed only because it
called the resolver directly with an authored tool. Declared the field on
`BaseTool`, propagated it through `to_structured_tool()` and
`CrewStructuredTool`, and made resolution fall back through
`_original_tool` so either shape works.

A failed call still printed the green "Completed" panel, then the red
one. That is the terminal version of the exact bug this PR is about.
Suppressed the success panel when the call reported failure.

A raised tool printed twice: `ToolUsageErrorEvent` already renders a red
panel, and the new failure panel repeated it. The event is still emitted
-- policy and traces need it -- but the duplicate console output is gone.
Both decisions now live in named predicates on `ConsoleFormatter` rather
than inline in the listener closure, so they are directly testable.

Unknown tools were reported on the ReAct path but silently ignored on all
three native paths, so the same miss was loud or silent depending on
executor style. Native paths now record `UNKNOWN_TOOL` too. This also
surfaced a live `NameError`: ruff had pruned `ToolFailureReason` from
`agent_utils` as unused, so the new branch would have crashed at runtime.

`LiteAgentOutput` had `tool_failures` but not `has_tool_failures`, which
the PR promised on all three output types -- an `AttributeError` for any
caller sharing one check across result types.

Testing: 16 further tests, 45 total. Two console tests were passing
vacuously because `emit()` dispatches sync handlers on a thread pool, so
the assertions raced the handler; they now assert on the predicates
directly, and the native-path test drains the bus with `flush()` and
checks the synchronously-written record. Full suite still matches
baseline exactly at 377 pre-existing failures.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ETacm2dMASfpMAYUiDu5YG

Author: joaomdmoura

lib/crewai/src/crewai/agents/crew_agent_executor.py

@@ -1030,6 +1030,16 @@ def _execute_single_native_tool_call(
                     ),
                 )
                 error_event_emitted = True
+        elif not from_cache:
+            # Not cached and not executable: the model asked for a tool that
+            # does not exist. The ReAct path reports this as a failure, so the
+            # native paths must too, or the same miss is silent on one and
+            # loud on the other.
+            tool_failure = ToolFailure(
+                message=result,
+                reason=ToolFailureReason.UNKNOWN_TOOL,
+                code=func_name,
+            )
 
         after_hook_context = ToolCallHookContext(
             tool_name=func_name,

lib/crewai/src/crewai/events/event_listener.py

@@ -415,6 +415,8 @@ def on_tool_usage_started(source: Any, event: ToolUsageStartedEvent) -> None:
 
         @crewai_event_bus.on(ToolUsageFinishedEvent)
         def on_tool_usage_finished(source: Any, event: ToolUsageFinishedEvent) -> None:
+            if not self.formatter.should_render_success_panel(event.failure):
+                return
             if isinstance(source, LLM):
                 self.formatter.handle_llm_tool_usage_finished(
                     event.tool_name,
@@ -444,6 +446,8 @@ def on_tool_usage_error(source: Any, event: ToolUsageErrorEvent) -> None:
         def on_tool_failure_detected(
             source: Any, event: ToolFailureDetectedEvent
         ) -> None:
+            if not self.formatter.should_render_failure_panel(event.failure):
+                return
             self.formatter.handle_tool_failure_detected(
                 event.tool_name,
                 event.failure,

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

@@ -12,6 +12,7 @@
 from rich.panel import Panel
 from rich.text import Text
 
+from crewai.tools.tool_failure import ToolFailureReason
 from crewai.version import is_current_version_yanked, is_newer_version_available
 
 
@@ -492,6 +493,26 @@ def handle_tool_usage_finished(
             content, f"✅ Tool Execution Completed (#{iteration})", "green"
         )
 
+    @staticmethod
+    def should_render_success_panel(failure: Any) -> bool:
+        """Whether a finished tool call should print the green panel.
+
+        A call that reported failure must not read as successful, so the
+        green panel is suppressed and the red one takes its place.
+        """
+        return failure is None
+
+    @staticmethod
+    def should_render_failure_panel(failure: Any) -> bool:
+        """Whether a reported failure should print its own red panel.
+
+        A tool that *raised* already produced a ``ToolUsageErrorEvent`` and
+        its own red panel, so printing a second one for the same exception is
+        pure noise. The event itself is still emitted -- only the duplicate
+        console output is skipped.
+        """
+        return getattr(failure, "reason", None) is not ToolFailureReason.EXCEPTION
+
     def handle_tool_failure_detected(
         self,
         tool_name: str,

lib/crewai/src/crewai/experimental/agent_executor.py

@@ -2046,6 +2046,8 @@ def _execute_single_native_tool_call(self, tool_call: Any) -> dict[str, Any]:
                         ),
                     )
                     error_event_emitted = True
+            else:
+                tool_failure = self._unknown_tool_failure(func_name, result)
         elif max_usage_reached:
             # Return error message when max usage limit is reached
             if original_tool:
@@ -2056,6 +2058,8 @@ def _execute_single_native_tool_call(self, tool_call: Any) -> dict[str, Any]:
             tool_failure = ToolFailure(
                 message=result, reason=ToolFailureReason.USAGE_LIMIT
             )
+        elif not from_cache:
+            tool_failure = self._unknown_tool_failure(func_name, result)
 
         # Execute after_tool_call hooks (even if blocked, to allow logging/monitoring)
         after_hook_context = ToolCallHookContext(
@@ -2109,6 +2113,19 @@ def _execute_single_native_tool_call(self, tool_call: Any) -> dict[str, Any]:
             "original_tool": original_tool,
         }
 
+    @staticmethod
+    def _unknown_tool_failure(func_name: str, result: str) -> ToolFailure:
+        """Build the failure for a tool the model asked for but we do not have.
+
+        The ReAct path reports this as a failure, so the native path must too,
+        or the same miss is silent on one and loud on the other.
+        """
+        return ToolFailure(
+            message=result,
+            reason=ToolFailureReason.UNKNOWN_TOOL,
+            code=func_name,
+        )
+
     def _extract_tool_name(self, tool_call: Any) -> str:
         """Extract tool name from various tool call formats."""
         if hasattr(tool_call, "function"):

lib/crewai/src/crewai/lite_agent_output.py

@@ -59,6 +59,15 @@ class LiteAgentOutput(BaseModel):
         ),
     )
 
+    @property
+    def has_tool_failures(self) -> bool:
+        """Whether any tool reported a failure while producing this output.
+
+        Same name and meaning as on ``TaskOutput`` and ``CrewOutput``, so a
+        check written for one result type works on all three.
+        """
+        return bool(self.tool_failures)
+
     plan: str | None = Field(
         default=None, description="The execution plan that was generated, if any"
     )

lib/crewai/src/crewai/tools/base_tool.py

@@ -38,6 +38,7 @@
     build_schema_hint,
     format_description_for_llm,
 )
+from crewai.tools.tool_failure import ToolFailurePolicy
 from crewai.types.callback import SerializableCallable, _resolve_dotted_path
 from crewai.utilities.string_utils import sanitize_tool_name
 
@@ -184,6 +185,14 @@ def _serialize_result_schema(
         default=None,
         description="Maximum number of times this tool can be used. None means unlimited usage.",
     )
+    tool_failure_policy: ToolFailurePolicy | None = Field(
+        default=None,
+        description=(
+            "Overrides the agent's and task's tool_failure_policy for this tool "
+            "only. Leave None to inherit. Use to tighten a single destructive "
+            "tool to 'raise', or to exempt a chatty one with 'ignore'."
+        ),
+    )
     current_usage_count: int = Field(
         default=0,
         description="Current number of times this tool has been used.",
@@ -402,6 +411,7 @@ def to_structured_tool(self) -> CrewStructuredTool:
             max_usage_count=self.max_usage_count,
             current_usage_count=self.current_usage_count,
             cache_function=self.cache_function,
+            tool_failure_policy=self.tool_failure_policy,
         )
         structured_tool._original_tool = self
         return structured_tool

lib/crewai/src/crewai/tools/structured_tool.py

@@ -21,7 +21,7 @@
 )
 from typing_extensions import Self
 
-from crewai.tools.tool_failure import ToolFailure
+from crewai.tools.tool_failure import ToolFailure, ToolFailurePolicy
 from crewai.utilities.logger import Logger
 from crewai.utilities.pydantic_schema_utils import (
     create_model_from_schema,
@@ -212,6 +212,7 @@ class CrewStructuredTool(BaseModel):
     result_as_answer: bool = Field(default=False)
     max_usage_count: int | None = Field(default=None)
     current_usage_count: int = Field(default=0)
+    tool_failure_policy: ToolFailurePolicy | None = Field(default=None)
     cache_function: Any = Field(default=None, exclude=True)
     _logger: Logger = PrivateAttr(default_factory=Logger)
     _original_tool: Any = PrivateAttr(default=None)

lib/crewai/src/crewai/tools/tool_failure.py

@@ -204,8 +204,15 @@ def resolve_tool_failure_policy(
 
     Most specific wins: tool, then task, then agent, then crew, then
     :attr:`ToolFailurePolicy.WARN`.
+
+    Execution paths hand over either a :class:`~crewai.tools.base_tool.BaseTool`
+    or the ``CrewStructuredTool`` that wraps it, so the tool scope is read
+    through the wrapper as well -- otherwise a tool-scoped policy would be
+    silently ignored on every native function-calling path.
     """
-    for source in (tool, task, agent, crew):
+    original_tool = getattr(tool, "_original_tool", None) if tool is not None else None
+
+    for source in (tool, original_tool, task, agent, crew):
         if source is None:
             continue
         policy = getattr(source, "tool_failure_policy", None)

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

@@ -33,6 +33,7 @@
 )
 from crewai.tools.tool_failure import (
     ToolFailure,
+    ToolFailureReason,
     detect_tool_failure,
     failure_from_exception,
     handle_tool_failure,
@@ -1717,6 +1718,16 @@ def execute_single_native_tool_call(
                     ),
                 )
                 error_event_emitted = True
+        else:
+            # Not cached and not executable: the model asked for a tool that
+            # does not exist. The ReAct path reports this as a failure, so the
+            # native paths must too, or the same miss is silent on one and
+            # loud on the other.
+            tool_failure = ToolFailure(
+                message=result,
+                reason=ToolFailureReason.UNKNOWN_TOOL,
+                code=func_name,
+            )
 
     after_hook_context = ToolCallHookContext(
         tool_name=func_name,