fix(tools): make ignore truly silent, stop caching failures, close 4 gaps

Six findings from the latest review round, all verified against the code
before touching it.

`ignore` was not silent. `ToolUsageFinishedEvent.failure` was set before
the policy ran, so traces still saw a failed call under a policy documented
as surfacing nothing. Worse, the console then showed *no* panel at all:
green was suppressed because `failure` was present, red was skipped because
`ignore` never emits `ToolFailureDetectedEvent`. New `reportable_failure()`
resolves the policy before the finished event and drops the flag under
`ignore`; wired into all four execution paths.

Failures were being cached. `CacheHandler.add` stored a `ToolFailure` like
any other result, so a transient error became permanent for the rest of the
run and every later hit re-reported a call that never re-ran. The cache now
refuses to store declared failures -- fixed at the single choke point rather
than at each of the four call sites.

A spent `max_usage_count` was invisible on the shared native path.
`BaseTool._claim_usage` returned a bare string that only the executors
recognising that exact message treated as a failure. It now returns a
`ToolFailure` with `USAGE_LIMIT`, so every path records it.

A guardrail returning a whole `TaskOutput` replaced the output without
carrying accumulated failures over, so earlier attempts vanished from
`CrewOutput.tool_failures`. New `merge_tool_failures()` combines and
deduplicates, and the retry-rebuild path uses it too.

A hook-blocked call inherited a cached failure and attributed it to a call
that never ran. Now cleared. Not reachable through the built-in cache once
failures stop being cached, so the test injects a custom cache handler that
does retain them -- verified to fail without the guard.

Also removed a `datetime` import left unused by the earlier console-test
rewrite.

Testing: 13 further tests, 73 total. Full suite matches baseline exactly at
377 pre-existing failures; the usage-limit suites that `_claim_usage`
touches pass unchanged; mypy clean on every changed file.

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/cache/cache_handler.py

@@ -23,6 +23,10 @@ class CacheHandler(BaseModel):
     def add(self, tool: str, input: str, output: Any) -> None:
         """Add a tool result to the cache.
 
+        Declared failures are never stored: replaying one would make a
+        transient error permanent for the rest of the run, and every later hit
+        would re-report a call that did not run.
+
         Args:
             tool: Name of the tool.
             input: Input string used for the tool.
@@ -31,6 +35,11 @@ def add(self, tool: str, input: str, output: Any) -> None:
         Notes:
             - TODO: Rename 'input' parameter to avoid shadowing builtin.
         """
+        from crewai.tools.tool_failure import ToolFailure
+
+        if isinstance(output, ToolFailure):
+            return
+
         with self._lock.w_locked():
             self._cache[f"{tool}-{input}"] = output
 

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

@@ -56,6 +56,7 @@
     detect_tool_failure,
     failure_from_exception,
     handle_tool_failure,
+    reportable_failure,
 )
 from crewai.types.callback import SerializableCallable
 from crewai.utilities.agent_utils import (
@@ -979,6 +980,9 @@ def _execute_single_native_tool_call(
         if hook_blocked:
             result = f"Tool execution blocked by hook. Tool: {func_name}"
             raw_tool_result = result
+            # The blocked message replaces any cached result, so a cached
+            # failure must not be attributed to this call.
+            tool_failure = None
         elif max_usage_reached and original_tool:
             result = f"Tool '{func_name}' has reached its usage limit of {original_tool.max_usage_count} times and cannot be used anymore."
             raw_tool_result = result
@@ -1064,7 +1068,13 @@ def _execute_single_native_tool_call(
                     agent_key=agent_key,
                     started_at=started_at,
                     finished_at=datetime.now(),
-                    failure=tool_failure,
+                    failure=reportable_failure(
+                        tool_failure,
+                        tool=structured_tool,
+                        agent=self.agent,
+                        task=self.task,
+                        crew=self.crew,
+                    ),
                 ),
             )
 

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

@@ -80,6 +80,7 @@
     detect_tool_failure,
     failure_from_exception,
     handle_tool_failure,
+    reportable_failure,
 )
 from crewai.utilities.agent_utils import (
     _llm_stop_words_applied,
@@ -2003,6 +2004,9 @@ def _execute_single_native_tool_call(self, tool_call: Any) -> dict[str, Any]:
         if hook_blocked:
             result = f"Tool execution blocked by hook. Tool: {func_name}"
             raw_tool_result = result
+            # The blocked message replaces any cached result, so a cached
+            # failure must not be attributed to this call.
+            tool_failure = None
         elif not from_cache and not max_usage_reached and output_tool is not None:
             if func_name in self._available_functions:
                 try:
@@ -2087,7 +2091,13 @@ def _execute_single_native_tool_call(self, tool_call: Any) -> dict[str, Any]:
                     agent_key=agent_key,
                     started_at=started_at,
                     finished_at=datetime.now(),
-                    failure=tool_failure,
+                    failure=reportable_failure(
+                        tool_failure,
+                        tool=structured_tool,
+                        agent=self.agent,
+                        task=self.task,
+                        crew=self.crew,
+                    ),
                 ),
             )
 

lib/crewai/src/crewai/task.py

@@ -56,6 +56,7 @@
     ToolFailurePolicy,
     ToolFailureRecord,
     collect_tool_failures,
+    merge_tool_failures,
 )
 from crewai.utilities.config import process_config
 from crewai.utilities.constants import NOT_SPECIFIED, _NotSpecified
@@ -1361,7 +1362,12 @@ def _invoke_guardrail_function(
                     task_output.pydantic = pydantic_output
                     task_output.json_dict = json_output
                 elif isinstance(guardrail_result.result, TaskOutput):
+                    # A guardrail may return a whole new output; carry the
+                    # accumulated failures over or earlier attempts vanish.
                     task_output = guardrail_result.result
+                    task_output.tool_failures = merge_tool_failures(
+                        accumulated_failures, task_output.tool_failures
+                    )
 
                 return task_output
 
@@ -1423,7 +1429,9 @@ def _invoke_guardrail_function(
                 agent=agent.role,
                 output_format=self._get_output_format(),
                 messages=agent.last_messages,  # type: ignore[attr-defined]
-                tool_failures=accumulated_failures + collect_tool_failures(agent),
+                tool_failures=merge_tool_failures(
+                    accumulated_failures, collect_tool_failures(agent)
+                ),
             )
             accumulated_failures = list(task_output.tool_failures)
 
@@ -1476,7 +1484,12 @@ async def _ainvoke_guardrail_function(
                     task_output.pydantic = pydantic_output
                     task_output.json_dict = json_output
                 elif isinstance(guardrail_result.result, TaskOutput):
+                    # A guardrail may return a whole new output; carry the
+                    # accumulated failures over or earlier attempts vanish.
                     task_output = guardrail_result.result
+                    task_output.tool_failures = merge_tool_failures(
+                        accumulated_failures, task_output.tool_failures
+                    )
 
                 return task_output
 
@@ -1538,7 +1551,9 @@ async def _ainvoke_guardrail_function(
                 agent=agent.role,
                 output_format=self._get_output_format(),
                 messages=agent.last_messages,  # type: ignore[attr-defined]
-                tool_failures=accumulated_failures + collect_tool_failures(agent),
+                tool_failures=merge_tool_failures(
+                    accumulated_failures, collect_tool_failures(agent)
+                ),
             )
             accumulated_failures = list(task_output.tool_failures)
 

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

@@ -38,7 +38,7 @@
     build_schema_hint,
     format_description_for_llm,
 )
-from crewai.tools.tool_failure import ToolFailurePolicy
+from crewai.tools.tool_failure import ToolFailure, ToolFailurePolicy, ToolFailureReason
 from crewai.types.callback import SerializableCallable, _resolve_dotted_path
 from crewai.utilities.string_utils import sanitize_tool_name
 
@@ -299,21 +299,26 @@ def _validate_kwargs(self, kwargs: dict[str, Any]) -> dict[str, Any]:
                 ) from e
         return kwargs
 
-    def _claim_usage(self) -> str | None:
+    def _claim_usage(self) -> ToolFailure | None:
         """Atomically check max usage and increment the counter.
 
         Returns:
-            None if usage was claimed successfully, or an error message
-            string if the tool has reached its usage limit.
+            None if usage was claimed, otherwise a :class:`ToolFailure`. A
+            structured result rather than a bare string so every execution
+            path records a spent limit, instead of only the ones that
+            recognise the message.
         """
         with self._usage_lock:
             if (
                 self.max_usage_count is not None
                 and self.current_usage_count >= self.max_usage_count
             ):
-                return (
-                    f"Tool '{self.name}' has reached its usage limit of "
-                    f"{self.max_usage_count} times and cannot be used anymore."
+                return ToolFailure(
+                    message=(
+                        f"Tool '{self.name}' has reached its usage limit of "
+                        f"{self.max_usage_count} times and cannot be used anymore."
+                    ),
+                    reason=ToolFailureReason.USAGE_LIMIT,
                 )
             self.current_usage_count += 1
             return None

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

@@ -208,6 +208,32 @@ def resolve_tool_failure_policy(
     return ToolFailurePolicy.WARN
 
 
+def merge_tool_failures(
+    *groups: list[ToolFailureRecord],
+) -> list[ToolFailureRecord]:
+    """Concatenate failure lists, dropping records already present.
+
+    Guardrail retries rebuild the output from overlapping sources, so identity
+    is not enough to avoid duplicates.
+    """
+    merged: list[ToolFailureRecord] = []
+    seen: set[tuple[Any, ...]] = set()
+    for group in groups:
+        for record in group:
+            key = (
+                record.tool_name,
+                record.failure.message,
+                record.failure.code,
+                record.task_id,
+                str(record.tool_args),
+            )
+            if key in seen:
+                continue
+            seen.add(key)
+            merged.append(record)
+    return merged
+
+
 def collect_tool_failures(agent: Any) -> list[ToolFailureRecord]:
     """Return the failures recorded on an agent, tolerating custom agents.
 
@@ -227,6 +253,26 @@ def _record_on_agent(agent: Any, record: ToolFailureRecord) -> None:
         failures.append(record)
 
 
+def reportable_failure(
+    failure: ToolFailure | None,
+    *,
+    tool: Any = None,
+    agent: BaseAgent | LiteAgent | None = None,
+    task: Task | None = None,
+    crew: Crew | None = None,
+) -> ToolFailure | None:
+    """Return the failure to attach to ``ToolUsageFinishedEvent``.
+
+    ``None`` under :attr:`ToolFailurePolicy.IGNORE`, so that policy really does
+    surface nothing -- neither a record, nor an event, nor a flag on the
+    finished event that a trace UI would render as a failure.
+    """
+    if failure is None:
+        return None
+    policy = resolve_tool_failure_policy(tool=tool, agent=agent, task=task, crew=crew)
+    return None if policy is ToolFailurePolicy.IGNORE else failure
+
+
 def handle_tool_failure(
     failure: ToolFailure,
     *,

lib/crewai/src/crewai/tools/tool_usage.py

@@ -29,6 +29,7 @@
     ToolFailureReason,
     detect_tool_failure,
     failure_from_exception,
+    reportable_failure,
 )
 from crewai.utilities.agent_utils import (
     get_tool_names,
@@ -1017,7 +1018,12 @@ def on_tool_use_finished(
                 "finished_at": datetime.datetime.fromtimestamp(finished_at),
                 "from_cache": from_cache,
                 "output": result,
-                "failure": self.last_failure,
+                "failure": reportable_failure(
+                    self.last_failure,
+                    tool=tool,
+                    agent=self.agent,
+                    task=self.task,
+                ),
             }
         )
         if self.task:

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

@@ -37,6 +37,7 @@
     detect_tool_failure,
     failure_from_exception,
     handle_tool_failure,
+    reportable_failure,
 )
 from crewai.tools.tool_types import ToolResult
 from crewai.utilities.errors import AgentRepositoryError
@@ -1678,6 +1679,9 @@ def execute_single_native_tool_call(
     if hook_blocked:
         result = f"Tool execution blocked by hook. Tool: {func_name}"
         raw_tool_result = result
+        # The blocked message replaces any cached result, so a cached failure
+        # must not be attributed to this call.
+        tool_failure = None
     elif not from_cache:
         if func_name in available_functions and output_tool is not None:
             try:
@@ -1755,7 +1759,13 @@ def execute_single_native_tool_call(
                 plan_step_description=plan_step_description,
                 started_at=started_at,
                 finished_at=datetime.now(),
-                failure=tool_failure,
+                failure=reportable_failure(
+                    tool_failure,
+                    tool=structured_tool,
+                    agent=agent,
+                    task=task,
+                    crew=crew,
+                ),
             ),
         )