Async guardrail retries block the event loop, async tool calls skip circuit-breaker protection, and memory.HooksManager's cascade hooks are never invoked

[MervinPraison]

Scope

src/praisonai-agents/praisonaiagents only (package praisonaiagents). Out of scope by design: documentation, tests, coverage, file size/line count, and generic performance/robustness suggestions — these are three functional gaps where an async code path silently fails to do what its sync sibling (or its own documented contract) does.

Every snippet below was read directly from the current branch (not paraphrased from a research pass) and cross-checked against prior closed audit issues to rule out duplicates — see the "Prior-art check" under each finding.

---

1. Async guardrail validation makes a blocking, synchronous LLM call from inside async def methods — it stalls the whole event loop, not just the one agent

Files: guardrails/protocols.py:37-77, guardrails/llm_guardrail.py:115-152,198-243, agent/agent.py:6614-6699, agents/agents.py:1283-1326,1399-1421,1718-1843

GuardrailProtocol only declares synchronous methods — there is no avalidate_input/avalidate_output anywhere:

# guardrails/protocols.py:37-50
def validate_input(self, content: str, **kwargs) -> Tuple[bool, str]:
    ...
def validate_output(self, content: str, **kwargs) -> Tuple[bool, str]:
    ...

LLMGuardrail (the built-in implementation used whenever Agent(guardrail="some description") is used, and by GuardrailChain) implements those with a blocking network call:

# guardrails/llm_guardrail.py:114-120 (_validate, used by validate_output)
if hasattr(self.llm, 'chat'):
    response = self.llm.chat(validation_prompt, temperature=0.1)
elif hasattr(self.llm, 'get_response'):
    response = self.llm.get_response(validation_prompt, temperature=0.1)

# guardrails/llm_guardrail.py:229-237 (_llm_validate, used by validate_input/validate_tool_call)
if hasattr(self.llm, 'get_response'):
    response = self.llm.get_response(prompt=prompt, verbose=False, markdown=False, stream=False)

Both are plain def, no await, no executor. The async guardrail-retry helper calls this synchronous chain directly, unawaited, from inside its own async def:

# agent/agent.py:6693-6699
async def _aapply_guardrail_with_retry(self, response_text, prompt, ...):
    while retry_count <= self.max_guardrail_retries:
        success, result, error = self._validate_with_guardrail(current_response)  # <- sync, blocks on LLM I/O

_validate_with_guardrail (agent/agent.py:6614-6638) calls self._process_guardrail(task_output) which invokes self._guardrail_fn(task_output) — for a string/LLMGuardrail guardrail this is exactly the blocking get_response/chat call above.

The multi-agent async entry points (arun_task, driven under asyncio.gather for concurrent tasks, and astart) go through the identical synchronous chain via _apply_task_guardrail:

# agents/agents.py:1418-1421 (inside async def arun_task)
task_output = await self.aexecute_task(task_id)
if task_output and self.completion_checker(task, task_output.raw):
    task_output, should_retry = self._apply_task_guardrail(task, task_id, task_output)  # <- sync

# agents/agents.py:1843 (inside async def astart) — identical pattern
task_output, should_retry = self._apply_task_guardrail(task, task_id, task_output)

_apply_task_guardrail (agents/agents.py:1283-1326) calls task._process_guardrail(task_output) → same blocking LLMGuardrail chain.

The team already knows this exact hazard class — but only closed half of it. agent/agent.py:6481-6489 has this comment while constructing a string guardrail:

# agent/agent.py:6481-6489
# A string guardrail is an output-quality validator. Although the
# resulting LLMGuardrail also exposes ``validate_input`` (via
# GuardrailProtocol), it must NOT be invoked as an input gate here:
# doing so would fire an extra, synchronous LLM call on every
# chat()/achat() (a hot-path regression, and blocking on the async
# event loop). Mark it so input validation skips it.
self._guardrail_fn._praison_output_only = True

This only prevents the input-side gate from firing an extra blocking call. The output-side gate — the primary, unavoidable use of every guardrail, string or object — still runs the identical blocking call from _aapply_guardrail_with_retry/arun_task/astart, and a directly-constructed LLMGuardrail/GuardrailChain instance (the callable(self.guardrail) branch at agent/agent.py:6433) never gets _praison_output_only set at all, so it isn't even partially covered.

Concrete failure scenario

import asyncio
from praisonaiagents import Agent, PraisonAIAgents, Task

def slow_but_valid(x): return "ok " + x

agent1 = Agent(name="A", instructions="Echo the input.", guardrail="Output must be under 20 words")
agent2 = Agent(name="B", instructions="Echo the input.")

t1 = Task(description="respond", agent=agent1)
t2 = Task(description="respond quickly", agent=agent2)

# Both tasks run concurrently under asyncio.gather() inside arun_all_tasks/astart.
# Task 1's guardrail check fires a *synchronous* LLM call inside an async method,
# so the event loop is blocked for that call's full latency — Task 2 (and any
# other concurrently-running agent/task in the same process) makes zero progress
# until Task 1's guardrail LLM round trip completes, even though Task 2 has
# nothing to do with Task 1's guardrail.
PraisonAIAgents(agents=[agent1, agent2], tasks=[t1, t2]).astart()

Suggested fix

Add avalidate_input/avalidate_output/avalidate_tool_call to GuardrailProtocol with a default that offloads the sync method via loop.run_in_executor (the same pattern already used correctly elsewhere in this file — see agent/async_memory_mixin.py's _run_memory_in_thread, which offloads synchronous Memory calls exactly this way). Give LLMGuardrail a real async implementation using await self.llm.aget_response(...) where available. Have _aapply_guardrail_with_retry and _apply_task_guardrail's callers (arun_task, astart) call the async surface instead of the sync one.

Prior-art check

Not a duplicate of #3907 (fixed by PR #3908, which wired up input-side validate_input never being called at all, and BEFORE_LLM/AFTER_LLM hooks not firing on async chat) — that fix did not touch _aapply_guardrail_with_retry or _apply_task_guardrail, and both still call the blocking chain today as shown above. Not a duplicate of #3573 (LLMGuardrail failing open on ambiguous replies — a correctness issue, not an event-loop-blocking issue) or #1961 (code duplication between run_task()/arun_task(), not blocking behavior).

---

2. Async tool execution has zero circuit-breaker protection — the sync path has it, and the async path has dead code that assumes it exists

Files: tools/circuit_breaker.py:233-278, agent/tool_execution.py:2081-2297, agent/execution_mixin.py:1542-1859

CircuitBreaker.acall() is a complete, correctly async-safe implementation:

# tools/circuit_breaker.py:233-247
async def acall(self, func: Callable, *args, **kwargs) -> Any:
    with self._lock:
        self._stats.total_requests += 1
        if self._stats.state == CircuitState.OPEN:
            if not self._should_attempt_reset():
                self._stats.rejected_requests += 1
                ...
                raise CircuitBreakerException(self.name, self._stats.state)

The sync tool path routes every call through it, opening the circuit after repeated failures per tool/agent:

# agent/tool_execution.py:2280 (inside _execute_tool_with_circuit_breaker_impl)
result = breaker.call(func, *args, **kwargs)

The async tool path (_execute_tool_async_impl, the method backing every achat()/async multi-agent tool call) never touches it — confirmed today with a fresh grep, zero matches for circuit_breaker/CircuitBreaker/breaker\. anywhere in execution_mixin.py. It even carries a dead check that presupposes it was wired up:

# agent/execution_mixin.py:1563-1568 (inside _execute_tool_async_with_retry)
if (result.get("approval_denied") or
        result.get("permission_denied") or
        result.get("approval_error") or
        result.get("circuit_open") or        # <- nothing on the async path ever sets this key
        result.get("loop_blocked") or
        result.get("_praison_retryable") is False):
    return result

Note: this is not a re-report of the loop-guard/doom-loop gap from #4000 — that was fixed by merged PR #4005, and execution_mixin.py does now call loop_guard.check()/.record() (lines 1696-1831). Only the circuit breaker itself was left out of that fix, despite #4000's own title naming "circuit breaker" as part of the gap and the merged PR's diff only adding loop-guard parity.

Concrete failure scenario

import asyncio
from praisonaiagents import Agent

def flaky_tool(query: str) -> str:
    raise RuntimeError("downstream service down")  # always fails, e.g. a broken API

agent = Agent(name="Worker", tools=[flaky_tool])

# Sync: after repeated failures, _execute_tool_with_circuit_breaker trips the
# breaker and short-circuits further calls to flaky_tool.
agent.chat("Keep calling flaky_tool until it works.")

# Async: the identical agent via achat() has no circuit breaker on this path —
# the LLM can retry the same failing tool call every turn indefinitely, hammering
# the broken downstream service, with the "circuit_open" retry-skip at
# execution_mixin.py:1566 never actually triggering.
asyncio.run(agent.achat("Keep calling flaky_tool until it works."))

Suggested fix

In _execute_tool_async_impl, wrap the actual tool invocation through breaker.acall(...) using the same tool_{id(self)}_{function_name} breaker-naming/weakref-finalizer scheme the sync path already uses (agent/tool_execution.py:2205-2220), and set result["circuit_open"] = True when CircuitBreakerException is raised so the already-present (but currently dead) check at execution_mixin.py:1566 starts doing something.

Prior-art check

#4000 ("Async tool-execution loop has no circuit breaker or doom-loop guard") was closed as completed via merged PR #4005 — but that PR added only loop-guard/doom-loop parity (verified: loop_guard/GuardAction now appear throughout execution_mixin.py). Circuit-breaker parity, the other half of #4000's own title, was not part of that diff and remains completely absent today, as shown by the fresh grep above returning zero matches.

---

3. memory/hooks.py's HooksManager (cascade hooks for file/command/prompt events) is fully built, documented, and publicly exported — but .execute() is never called anywhere

Files: memory/hooks.py:1-45,83,222,405, memory/__init__.py:32,157-165,224-226

The module documents a complete pre/post hook system, configured via .praisonai/hooks.json, for eight events:

# memory/hooks.py:1-34
"""
Cascade Hooks System for PraisonAI Agents.
...
Configuration (.praisonai/hooks.json):
    {
        "hooks": {
            "pre_write_code": "./scripts/lint.sh",
            "post_write_code": "./scripts/format.sh",
            "pre_run_command": "./scripts/validate.sh",
            "post_user_prompt": "./scripts/log.sh"
        },
        "timeout": 30,
        "enabled": true
    }

Hook Events:
- pre_read_code / post_read_code
- pre_write_code / post_write_code
- pre_run_command / post_run_command
- pre_user_prompt / post_user_prompt
"""
class HooksManager:      # memory/hooks.py:83
    def execute(self, ...):   # memory/hooks.py:222 — runs the configured script for an event
        ...
def create_hooks_manager(...):  # memory/hooks.py:405
    ...

memory/__init__.py documents and re-exports it as a first-class public feature:

# memory/__init__.py:32
- HooksManager: Pre/post operation hooks
...
# memory/__init__.py:157-165
if name == "HooksManager":
    from .hooks import HooksManager
    return HooksManager
if name == "create_hooks_manager":
    from .hooks import create_hooks_manager
    return create_hooks_manager

A repo-wide grep for .execute( calls on a HooksManager/create_hooks_manager instance, or for any of the eight event-name string literals (pre_read_code, post_write_code, pre_run_command, post_user_prompt, etc.) outside memory/hooks.py itself, returns zero matches in the entire praisonaiagents package — no file-tool, no command-execution tool, and no prompt-intake code in agent/tool_execution.py or agent/chat_mixin.py ever calls HooksManager.execute(...). This is a completely separate system from the actively-used hooks/ package (HookEvent.BEFORE_TOOL/BEFORE_LLM/etc., wired via HookRunner throughout chat_mixin.py/tool_execution.py) — easy to conflate by name, but only one of the two is live. The only consumer anywhere in the monorepo is the praisonai wrapper's praisonai hooks list/stats CLI command (praisonai/cli/legacy/subcommand_handlers.py:308-339), and that only calls hooks.get_stats() for introspection/printing — never .execute().

Concrete failure scenario

# .praisonai/hooks.json
# {
#   "hooks": { "pre_write_code": "./scripts/block_secrets.sh" },
#   "enabled": true
# }

from praisonaiagents.memory import create_hooks_manager
hooks = create_hooks_manager(workspace_path=".")
# A user follows the module's own docstring, expecting any agent file-write
# operation to run ./scripts/block_secrets.sh first and be blocked on a
# non-zero exit code. Nothing in the agent/tool-execution pipeline ever calls
# hooks.execute(HookEvent.PRE_WRITE_CODE, ...), so agent-driven file writes
# proceed unconditionally — the configured guard script never runs, with no
# error, warning, or any observable difference in behavior.

Suggested fix

Either wire HooksManager.execute() into the actual file-write/read and command-execution tool implementations and into prompt intake (mirroring how hooks/runner.py's HookRunner is already invoked at the relevant agent/tool_execution.py/agent/chat_mixin.py call sites), or remove the class/export and its docstring until it is actually wired up — the current state gives a false impression of an active safety/observability control.

Prior-art check

Not a duplicate of #3085's Gap 1 ("the entire hooks/middleware.py extension point... never executed", fixed by merged PR #3086) — that finding and fix were about hooks/middleware.py's wrap_tool_call/MiddlewareManager (passed via Agent(hooks=[...])), a different module and different mechanism from memory/hooks.py's HooksManager. A repo search for HooksManager/cascade hook/memory/hooks.py in prior issues returns no matches.

---

Validation notes

• Every snippet above was read from the current src/praisonai-agents/praisonaiagents tree at the cited lines on this run, not carried over from a prior audit.
• Finding 1 was cross-checked by tracing the full call chain from arun_task/astart/achat() down to the actual self.llm.get_response(...) call, confirming no await/executor offload exists anywhere in that chain, and by reading the _praison_output_only comment in full to confirm it covers only the input-side gate.
• Finding 2 was cross-checked against Async tool-execution loop has no circuit breaker or doom-loop guard, even after the recent async-timeout fix #4000/PR fix: add loop-guard/doom-loop parity to async tool-execution path #4005 specifically: loop_guard/GuardAction now appear at execution_mixin.py:1696-1831 (confirming that part of Async tool-execution loop has no circuit breaker or doom-loop guard, even after the recent async-timeout fix #4000 is genuinely fixed), while circuit_breaker/CircuitBreaker still return zero matches in the same file.
• Finding 3 was cross-checked with a repo-wide grep for every one of the eight documented hook-event string literals and for HooksManager/create_hooks_manager outside memory/hooks.py, and by reading the one real call site in the praisonai wrapper CLI to confirm it only reads stats and never executes a hook.
• Searched existing issues (search_issues) before filing; the closest prior matches (Async tool-execution loop has no circuit breaker or doom-loop guard, even after the recent async-timeout fix #4000, Guardrail input-side validation, async LLM hooks, and managed-backend streaming silently diverge from their own documented contracts (praisonaiagents core) #3907, Dead middleware hooks, guardrail/retry bypass in nested workflow patterns, and unsynchronized Workflow state under concurrent runs #3085, Core SDK: LLMGuardrail still fails open on ambiguous LLM replies, FailoverManager has no locking despite being a shared credential pool, and tool-output run isolation is silently disabled by an attribute typo #3573, Core SDK: identical guardrail-validation and task-callback blocks duplicated between sync run_task() and async arun_task() #1961, Policy/guardrail enforcement silently no-ops in three independent paths (praisonaiagents core) #3631, Hierarchical process manager-id guard is dead code, async tool execution drops timeout/circuit-breaker enforcement, and GuardrailConfig policy strings are unenforced #3789) were each individually opened, read in full, and confirmed to cover a different specific mechanism or to have left this particular gap out of their merged fix, as noted under each finding.

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[praisonai-triage-agent]

Claude encountered an error —— View job

---

Analyzing issue #4281

• Read AGENTS.md guidelines
• Verify finding 1: async guardrail blocking event loop
• Verify finding 2: async tool circuit-breaker missing
• Verify finding 3: memory HooksManager never invoked
• Architecture validation & routing decision
• Implement minimal fixes
• Test
• Push & create PR

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.