fix: return usable text when input guardrails reject a turn

src/praisonai-agents/praisonaiagents/agent/agent.py

@@ -7244,7 +7244,10 @@ def _guardrail_blocked_message(self, error=None):
         reason = str(error) if error else getattr(self, "_last_guardrail_error", None)
         if reason:
             logging.info(f"Agent {self.name}: guardrail block reason: {reason}")
-        return "I'm sorry, but I can't share that response because it did not pass the safety guardrail."
+        from ..guardrails.guardrail_result import _GuardrailBlockedResponse
+        return _GuardrailBlockedResponse(
+            "I'm sorry, but I can't share that response because it did not pass the safety guardrail."
+        )
 
     def _process_guardrail(self, task_output):
         """Process the guardrail validation for a task output.

src/praisonai-agents/praisonaiagents/agent/chat_mixin.py

@@ -3569,7 +3569,7 @@ def chat(self, prompt: str, temperature: Optional[float] = None, tools: Optional
             _in_ok, _in_prompt, _in_err = self._validate_input_with_guardrail(prompt)
             if not _in_ok:
                 logging.warning(f"Agent {self.name}: input blocked by guardrail: {_in_err}")
-                return None
+                return self._guardrail_blocked_message(_in_err)
             prompt = _in_prompt
 
         # Check if external managed backend is configured
@@ -4419,7 +4419,7 @@ async def achat(self, prompt: str, temperature: Optional[float] = None, tools: O
                 )
             if not _in_ok:
                 logging.warning(f"Agent {self.name}: input blocked by guardrail: {_in_err}")
-                return None
+                return self._guardrail_blocked_message(_in_err)
             prompt = _in_prompt
 
         # Check if external managed backend is configured (async parity with the
@@ -5539,7 +5539,7 @@ def _start_stream_turn(self, prompt: str, **kwargs) -> Generator[str, None, None
             _in_ok, _in_prompt, _in_err = self._validate_input_with_guardrail(prompt)
             if not _in_ok:
                 logging.warning(f"Agent {getattr(self, 'name', '')}: input blocked by guardrail: {_in_err}")
-                yield f"[Input blocked by guardrail: {_in_err}]"
+                yield self._guardrail_blocked_message(_in_err)
                 return "failed"
             prompt = _in_prompt
 

src/praisonai-agents/praisonaiagents/agent/execution_mixin.py

@@ -197,8 +197,10 @@ async def astart(self, prompt: str, **kwargs):
                 start_time = time_module.time()
                 started_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
 
+                from ..guardrails.guardrail_result import _GuardrailBlockedResponse
                 response = await self.achat(prompt, **kwargs)
-                response_str = str(response) if response else ""
+                blocked = isinstance(response, _GuardrailBlockedResponse)
+                response_str = response if blocked else (str(response) if response else "")
 
                 # Auto-save session after chat. Offloaded to a worker thread so
                 # the synchronous FileLock/JSON read-modify-write never stalls
@@ -210,7 +212,8 @@ async def astart(self, prompt: str, **kwargs):
                 # Wrap in AutonomyResult for consistent API
                 from .autonomy import AutonomyResult
                 return AutonomyResult(
-                    success=True,
+                    success=not blocked,
+                    error=response_str if blocked else None,
                     output=response_str,
                     completion_reason="caller_mode",
                     iterations=1,
@@ -294,6 +297,13 @@ def _outcome_for_result(self, result):
         existing ``completed`` semantics, so behaviour is unchanged on success.
         """
         from .run_outcome import RunOutcome, PROVIDER_BLOCK_REASONS
+        from .autonomy import AutonomyResult
+        from ..guardrails.guardrail_result import _GuardrailBlockedResponse
+
+        if isinstance(result, _GuardrailBlockedResponse):
+            return RunOutcome(reason="failed", output=str(result), error=str(result))
+        if isinstance(result, AutonomyResult) and isinstance(result.output, _GuardrailBlockedResponse):
+            return RunOutcome(reason="failed", output=str(result.output), error=result.error)
         output = str(result) if result is not None else None
         # Read the recorded classification without letting a lookup problem mask a
         # provider block as a successful ``completed``. Only an expected
@@ -626,7 +636,12 @@ def _start_with_planning(self, prompt: str, **kwargs):
         from rich.console import Console
         from rich.panel import Panel
         from rich.markdown import Markdown
-
+        from ..guardrails.guardrail_result import _GuardrailBlockedResponse
+
+        _in_ok, prompt, _in_err = self._validate_input_with_guardrail(prompt)
+        if not _in_ok:
+            return self._guardrail_blocked_message(_in_err)
+
         console = _get_console()()
 
         # Step 1: Create the plan
@@ -669,6 +684,8 @@ def _start_with_planning(self, prompt: str, **kwargs):
 
             # Execute the step
             result = self.chat(step_prompt, **kwargs)
+            if isinstance(result, _GuardrailBlockedResponse):
+                return result
             results.append({"step": i + 1, "description": step.description, "result": result})
 
             # Update context for next step (use full result, not truncated)
@@ -807,6 +824,10 @@ def start(self, prompt: Optional[str] = None, **kwargs: Any) -> Union[str, Gener
                     kwargs['stream'] = self.stream
                 else:
                     kwargs['stream'] = sys.stdout.isatty()
+            _in_ok, prompt, _in_err = self._validate_input_with_guardrail(prompt)
+            if not _in_ok:
+                blocked = self._guardrail_blocked_message(_in_err)
+                return iter((blocked,)) if kwargs.get('stream') else blocked
             return self._delegate_to_backend(prompt, **kwargs)
 
         # ─────────────────────────────────────────────────────────────────────
@@ -844,16 +865,19 @@ def start(self, prompt: Optional[str] = None, **kwargs: Any) -> Union[str, Gener
                 self._load_history_context()
 
                 # Use chat() — all tools, approval, doom-loop per-tool work
+                from ..guardrails.guardrail_result import _GuardrailBlockedResponse
                 response = self.chat(prompt, **kwargs)
-                response_str = str(response) if response else ""
+                blocked = isinstance(response, _GuardrailBlockedResponse)
+                response_str = response if blocked else (str(response) if response else "")
 
                 # Auto-save session after chat
                 self._auto_save_session()
 
                 # Wrap in AutonomyResult for consistent API
                 from .autonomy import AutonomyResult
                 return AutonomyResult(
-                    success=True,
+                    success=not blocked,
+                    error=response_str if blocked else None,
                     output=response_str,
                     completion_reason="caller_mode",
                     iterations=1,

src/praisonai-agents/praisonaiagents/agents/agents.py

@@ -571,11 +571,17 @@ def _process_task_result(agents_instance, context, agent_output):
     Eliminates duplication in result processing between sync/async paths.
     """
     from .protocols import TaskResult
+    from ..guardrails.guardrail_result import _GuardrailBlockedResponse
 
     task = context.task
     task_id = context.task_id
     executor_agent = context.executor_agent
     llm = context.llm
+
+    if isinstance(agent_output, _GuardrailBlockedResponse):
+        object.__setattr__(task, "_guardrail_rejection_terminal", True)
+        task.status = "failed"
+        return TaskResult(task_output=None, success=False, error="Agent input or output was blocked by a guardrail.")
 
     if agent_output:
         # Store the response in memory
@@ -1822,7 +1828,11 @@ async def _arun_task_body(self, task_id, task):
         while task.status != "completed" and retries < task_max:
             logger.debug(f"Attempt {retries+1} for task {task_id}")
             if task.status in ["not started", "in progress"]:
+                object.__setattr__(task, "_guardrail_rejection_terminal", False)
                 task_output = await self.aexecute_task(task_id)
+                # Empty output can also mark failure, but remains retryable.
+                if getattr(task, "_guardrail_rejection_terminal", False):
+                    return
                 if task_output and self.completion_checker(task, task_output.raw):
                     # Apply guardrail validation using shared helper (offloaded to
                     # a thread so a blocking LLM guardrail does not stall the loop)
@@ -2422,7 +2432,11 @@ def _run_task_body(self, task_id, task):
         while task.status != "completed" and retries < task_max:
             logger.debug(f"Attempt {retries+1} for task {task_id}")
             if task.status in ["not started", "in progress"]:
+                object.__setattr__(task, "_guardrail_rejection_terminal", False)
                 task_output = self.execute_task(task_id)
+                # Empty output can also mark failure, but remains retryable.
+                if getattr(task, "_guardrail_rejection_terminal", False):
+                    return
                 if task_output and self.completion_checker(task, task_output.raw):
                     # Apply guardrail validation using shared helper
                     task_output, should_retry = self._apply_task_guardrail(task, task_id, task_output)

src/praisonai-agents/praisonaiagents/guardrails/guardrail_result.py

@@ -10,6 +10,10 @@
 from ..output.models import TaskOutput
 
 
+class _GuardrailBlockedResponse(str):
+    """User-facing text carrying a rejection marker for internal task callers."""
+
+
 class GuardrailResult(BaseModel):
     """Result of a guardrail validation."""