[FEATURE] Native deterministic guardrail to prevent infinite agent delegation and tool loops

[Devaretanmay]

Feature Area

Core functionality

Is your feature request related to a an existing bug? Please link it here.

Yes. One of the most expensive and frustrating failure modes in multi-agent Crews is the infinite loop.
Specifically:

1. The Delegation Ping-Pong: Agent A delegates a task to Agent B, but Agent B gets confused and delegates it back to Agent A.
2. The Tool Loop: An agent gets stuck calling the exact same tool (e.g., search_web("rust")) repeatedly because the LLM fails to realize it's looping.

Currently, these loops run indefinitely, burning thousands of dollars in LLM API credits before the user manually kills the process or hits a blind max_iter limit.

Describe the solution you'd like

I propose adding a Deterministic Trajectory Guardrail to CrewAI.

Instead of relying on the LLM to "notice" it's looping (which takes 1.5+ seconds and burns tokens) or using a blind max_iter counter (which kills valid 15-step workflows at step 11), we intercept the tool execution pipeline and deterministically hash the trajectory state: (agent_role, tool_name, canonical_arguments).

If the exact same trajectory repeats within a sliding window, the guardrail instantly raises an exception locally (in ~480ns), blocking the loop before the API call ever leaves the machine.

Describe alternatives you've considered

1. Prompt Engineering ("You are looping, please stop"): Fails because the context window gets polluted with the agent's own repeated errors, making it impossible for the LLM to self-correct.
2. max_iter limits: A blind budget. It doesn't detect redundancy, it just detects time.
3. Semantic Embeddings: Too slow. Running an embedding model on every tool call adds 10ms+ of latency and heavy dependencies. We need sub-microsecond, deterministic hashing.

Additional context

I have actually already built the core engine for this exact physics problem in Rust (called Microloop), which handles the nanosecond-level trajectory hashing. I also just opened a PR to integrate this exact logic natively into LiteLLM as a guardrail callback.

My Proposal for CrewAI:
I have a working Python prototype that wraps the Crew and intercepts the Agent's tool execution pipeline (catching both standard tool loops AND delegation ping-pongs).

Before I open a formal PR, I’d love the maintainers' feedback on:

1. Integration Point: Is there a specific internal hook or callback system in CrewAI 0.105.x that is preferred for intercepting tool execution, or is wrapping the Agent.execute_tool method the cleanest approach?
2. Location: Should this live in a new crewai/guardrails/ directory, or as an external integration package?

I am happy to write the code, the tests, and the documentation for this if the team is aligned on the approach. Let me know what you think!

Willingness to Contribute

Yes, I'd be happy to submit a pull request

[0xbrainkid]

A deterministic loop guardrail gets much stronger if the trajectory hash is treated as an action receipt, not only a local dedupe key.

For delegation ping-pong, I would include a few fields beyond (agent_role, tool_name, canonical_arguments):

agent_id / profile_ref
crew_run_id
parent_task_ref
delegation_depth
authority_scope_ref
tool_name
canonical_arguments_hash

The reason is that two loops can look identical at the tool layer but differ at the authority layer. A repeated search_web("rust") call from the same agent in the same run is probably redundant. The same call after a narrowed delegation or different parent task may be legitimate. Conversely, a delegation loop can hide by changing superficial task wording while preserving the same actor pair and authority scope.

So I would split the guardrail into two checks:

1. tool trajectory repetition: same agent, same tool, same canonical argument hash inside a sliding window;
2. delegation cycle repetition: same agent pair or role pair, same parent task/action reference, same or widening authority scope.

When the guardrail fires, it should emit a small terminal record: loop_guardrail_triggered with the trajectory hash, agent/profile reference, parent task reference, and blocked reason. That makes the stop auditable instead of just being a local exception.

This maps cleanly to the AgentFolio/SATP receipt model: the runtime still owns policy and blocking, while the identity/evidence layer can later answer which agent looped, under which delegation, over which action bytes, and where the run was stopped. It also gives conformance tests something precise to assert: repeated action blocked, narrowed delegation allowed, widened delegation rejected, and terminal blocked outcome recorded.

[Devaretanmay]

A deterministic loop guardrail gets much stronger if the trajectory hash is treated as an action receipt, not only a local dedupe key.

For delegation ping-pong, I would include a few fields beyond (agent_role, tool_name, canonical_arguments):

agent_id / profile_ref
crew_run_id
parent_task_ref
delegation_depth
authority_scope_ref
tool_name
canonical_arguments_hash

The reason is that two loops can look identical at the tool layer but differ at the authority layer. A repeated search_web("rust") call from the same agent in the same run is probably redundant. The same call after a narrowed delegation or different parent task may be legitimate. Conversely, a delegation loop can hide by changing superficial task wording while preserving the same actor pair and authority scope.

So I would split the guardrail into two checks:

1. tool trajectory repetition: same agent, same tool, same canonical argument hash inside a sliding window;
2. delegation cycle repetition: same agent pair or role pair, same parent task/action reference, same or widening authority scope.

When the guardrail fires, it should emit a small terminal record: loop_guardrail_triggered with the trajectory hash, agent/profile reference, parent task reference, and blocked reason. That makes the stop auditable instead of just being a local exception.

This maps cleanly to the AgentFolio/SATP receipt model: the runtime still owns policy and blocking, while the identity/evidence layer can later answer which agent looped, under which delegation, over which action bytes, and where the run was stopped. It also gives conformance tests something precise to assert: repeated action blocked, narrowed delegation allowed, widened delegation rejected, and terminal blocked outcome recorded.

@0xbrainkid This is an incredibly sharp breakdown, and you've hit the exact edge cases that break naive loop detectors in complex multi-agent systems. You are 100% right on all three points.

Treating the trajectory hash as an action receipt rather than a simple dedupe key is the exact mental model shift required for production multi-agent crews.

Here is how I propose we map your feedback to the implementation phases:

Phase 1: The Core Hook (Current PR / v0.1)

For the initial integration, we will establish the execution hook and implement the Tool Trajectory Repetition check. We will hash (agent_role, tool_name, canonical_arguments_hash). This catches the 80% use case (standard tool loops and basic delegation ping-pongs) with zero added latency.

Phase 2: Context-Aware Receipts (v0.2)

This is where we implement your "action receipt" model. We will expand the hashed state to include:

• crew_run_id / parent_task_ref (to prevent false positives when the same tool is legitimately reused across different sub-tasks).
• delegation_depth and authority_scope_ref.

This directly enables your second point: splitting the guardrail into distinct Tool Trajectory vs. Delegation Cycle checks. By hashing the actor pair and authority scope, we can catch delegation cycles even if the LLM slightly rephrases the task wording to bypass a naive string match.

Phase 3: Observability & Auditability (v0.3)

Your point about the terminal record is critical for enterprise adoption. Throwing a raw Python exception is bad for observability.
In v0.3, we will replace the raw exception with a structured loop_guardrail_triggered event. This will emit the trajectory hash, agent profile, parent task, and blocked reason to an OpenTelemetry sink. This gives DevOps/FinOps teams the exact audit trail they need to answer: Which agent looped? Under which delegation? Over which action bytes?

Thank you for laying out the SATP receipt model mapping. It gives the maintainers a very clear, conformance-testable roadmap for how this guardrail should evolve from a simple script into a rigorous runtime policy layer.

I will proceed with opening the Phase 1 PR shortly to get the core hook merged, and I'll link this issue to track the Phase 2/3 context-aware expansions.

[0xbrainkid]

That phase split makes sense. One small suggestion for Phase 1: even if the first implementation only hashes (agent_role, tool_name, canonical_arguments_hash), keep the emitted event schema forward-compatible from the start.

For example, the v0.1 event can include nullable fields now:

loop_guardrail_triggered
  trajectory_hash
  check_type = tool_trajectory | delegation_cycle
  agent_role
  agent_id? / profile_ref?
  crew_run_id?
  parent_task_ref?
  authority_scope_ref?
  tool_name
  canonical_arguments_hash
  repeat_count
  window_size
  blocked_reason

That lets Phase 2 fill in crew_run_id, parent_task_ref, and authority_scope_ref without changing the event contract that users build dashboards or tests around.

For conformance, I would add one v0.1 negative test that protects the future design: same tool and args in two different parent tasks should be easy to mark as an expected false positive today, with a TODO that flips once parent task references are wired in. That makes the known limitation explicit instead of letting people mistake Phase 1 for the final authority model.

The core invariant I would preserve across all phases: the guardrail should never silently summarize a blocked loop as a normal task failure. It should produce a terminal blocked outcome with enough identity/action material that another layer can later attach reputation or incident evidence without scraping logs.

[Devaretanmay]

That phase split makes sense. One small suggestion for Phase 1: even if the first implementation only hashes (agent_role, tool_name, canonical_arguments_hash), keep the emitted event schema forward-compatible from the start.

For example, the v0.1 event can include nullable fields now:

loop_guardrail_triggered
  trajectory_hash
  check_type = tool_trajectory | delegation_cycle
  agent_role
  agent_id? / profile_ref?
  crew_run_id?
  parent_task_ref?
  authority_scope_ref?
  tool_name
  canonical_arguments_hash
  repeat_count
  window_size
  blocked_reason

That lets Phase 2 fill in crew_run_id, parent_task_ref, and authority_scope_ref without changing the event contract that users build dashboards or tests around.

For conformance, I would add one v0.1 negative test that protects the future design: same tool and args in two different parent tasks should be easy to mark as an expected false positive today, with a TODO that flips once parent task references are wired in. That makes the known limitation explicit instead of letting people mistake Phase 1 for the final authority model.

The core invariant I would preserve across all phases: the guardrail should never silently summarize a blocked loop as a normal task failure. It should produce a terminal blocked outcome with enough identity/action material that another layer can later attach reputation or incident evidence without scraping logs.

This is brilliant feedback, and I completely agree. Treating the guardrail as an observability and telemetry primitive from Day 1 is the right move, rather than bolting it on later.
Here is how I will implement your suggestions in the PR:

1. Forward-Compatible Event Schema:
   I will define a strict GuardrailBlockEvent dataclass (or Pydantic model) that matches your schema exactly. Even in v0.1, fields like crew_run_id and parent_task_ref will be present but set to None. This ensures that any downstream dashboard or test relying on the schema won't break when Phase 2 wires in the actual task hierarchy.
2. The Core Invariant (No Silent Summarization):
   I will introduce a specific MicroloopBlockedException (distinct from a standard ToolExecutionError or ValueError). When the guardrail triggers, it will raise this exception with the full GuardrailBlockEvent payload attached. The exception message will explicitly state it is a terminal guardrail block, ensuring CrewAI's core (or telemetry hooks) can catch it and emit a distinct "blocked" outcome rather than feeding it back to the LLM as a standard "tool failed" retry.
3. The Negative Test (Protecting the Future Design):
   I will add a specific test case: test_same_tool_different_parent_tasks_is_known_false_positive. It will assert that calling the same tool/args in Task A and Task B currently triggers the guardrail (since v0.1 lacks parent_task_ref), but it will include a clear # TODO: Phase 2 will wire parent_task_ref to isolate these comment. This makes the boundary explicit.
   I'll start drafting the PR with this exact structure. Thank you for the architectural guidance!

[0xbrainkid]

That implementation shape is exactly the right boundary: the runtime owns the block, while the event/exception carries enough identity and action material for later audit.

One concrete conformance split I would keep in the PR is:

raises MicroloopBlockedException
exception.event.check_type == "tool_trajectory"
exception.event.trajectory_hash is stable for canonical-equivalent args
exception.event.blocked_reason is explicit
LLM retry path does not receive it as a normal tool failure
telemetry/log hook can serialize GuardrailBlockEvent without scraping exception text

That last point is worth testing because it preserves the SATP-style receipt boundary: downstream systems should be able to consume the structured blocked outcome directly, not infer it from logs or natural-language error strings.

For the known false-positive test, I would mark the assertion with the intended future invariant too:

v0.1: same tool/args across parent tasks blocks
v0.2: same tool/args across different parent_task_ref does not block

That gives reviewers a clean reason to accept the nullable fields now without treating them as unused complexity: they are preserving the public event contract before parent-task identity is fully wired in.

[Billionaire664]

"This thread converged on exactly the right invariant — a blocked loop should produce a structured terminal event, not a swallowed exception or a retry-disguised-as-failure. We hit this same design problem building a production spend gate (Valta) and landed on something structurally close to the GuardrailBlockEvent model above, worth comparing notes on since it's already running in production.

Our events are hash-chained rather than just schema'd — each blocked/approved decision is appended to an append-only log where entry.hash = SHA256(entry.payload + previous.hash). That gets you something the nullable-field schema above doesn't fully cover yet: tamper-evidence. Anyone consuming the audit trail downstream (FinOps, incident review, a reputation layer like the SATP model you're sketching) can verify the sequence wasn't edited after the fact — not just that the schema was populated correctly.

Fields we settled on, mapped to your GuardrailBlockEvent naming:

event_hash → trajectory_hash equivalent, but chained to prev_hash
event_type → check_type ("spend_denied", "spend_approved", "policy_blocked")
agent_id → agent_id / profile_ref
triggered_by → the caller (SDK, delegation, direct call)
reasoning → blocked_reason (structured, not free text)
affected_resource_id → maps to your authority_scope_ref idea — which wallet/budget was checked
created_at + prev_hash → gives you the "was this the Nth block or was something skipped" guarantee
One thing worth flagging from production experience: the "same tool/args across parent tasks blocks in v0.1" false positive you're accepting as a known limitation is exactly the failure mode that burns trust fastest with real users — someone hits it once, assumes the guardrail is broken, and disables it. We ended up scoping checks to a resource identity (wallet_id) rather than pure trajectory hash from day one specifically to avoid that false-positive tax, at the cost of needing the authority-scope concept earlier than your phased plan calls for. Might be worth pulling authority_scope_ref into Phase 1 even as a required (not nullable) field if the false-positive cost is what you're trying to avoid at adoption time.

Happy to share the full audit chain schema/implementation if it's useful reference material for the Phase 3 observability work — it's live and handling real traffic, so the edge cases you'd hit are probably the same ones we already debugged."

[Devaretanmay]

Hi @Billionaire664, this is incredibly valuable feedback, especially coming from a production spend gate like Valta. Learning from systems that are already handling real traffic is exactly how we avoid building theoretical architecture that fails in the wild.

Here are my thoughts on your points:

1. Hash-Chaining for Tamper-Evidence (Brilliant)
You are 100% right. A simple schema isn't enough for FinOps or incident review; they need cryptographic proof that the audit trail wasn't retroactively altered. Appending prev_hash to create an append-only, tamper-evident log is a massive upgrade to the observability layer. We will absolutely adopt this hash-chaining model for the Phase 3 GuardrailBlockEvent implementation.

2. Pulling authority_scope_ref into Phase 1 (The Tradeoff)
I see exactly where you're coming from—the "false-positive tax" is real, and hitting it once is often enough to make a user disable the guardrail entirely.

However, for the initial PR to CrewAI, we have to make a calculated tradeoff. Wiring in full authority scope and parent-task tracking requires deep introspection into how CrewAI manages delegation context internally. If we make the Phase 1 PR too architecturally heavy, it risks not getting merged at all.

Our strategy is to ship the execution hook and the basic trajectory hash in v0.1 to get the guardrail into the codebase, explicitly documenting the cross-task false positive as a known limitation (protected by the negative test we discussed). Then, in v0.2, we immediately wire in the parent_task_ref and authority_scope_ref to eliminate that tax. We have to walk before we run, but the v0.2 architecture is being designed specifically to solve the exact failure mode you flagged.

3. Sharing the Valta Schema
I would absolutely love to see the full audit chain schema and implementation from Valta. Having a battle-tested reference for the hash-chained events will save us weeks of trial and error when we build out the Phase 3 telemetry.

If you can drop a link to a gist, a repo, or even just paste the core data structures here, it would be immensely helpful for the Loopless runtime design.

Thanks for jumping in and sharing the production scars. This is exactly how we build a robust, enterprise-grade execution layer.

[Billionaire664]

Here it is — pulled it out into a standalone reference repo so it's easier to browse/reuse than a comment dump:

github.com/Billionaire664/valta-audit-chain

Covers both pieces: the pre-call spend gate (src/spend-gate.ts) and the hash-chained audit log (src/audit-chain.ts + verify.ts), plus an example showing them composed together (src/example.ts). README has the production notes — the false-positive/scoping tradeoffs we hit building this are probably close to what you'll hit in Phase 2.

MIT licensed, take whatever's useful."

[Tuttotorna]

I think this is the right failure class to make deterministic, but I would separate loop detection from unsupported-transition detection.

A repeated trajectory is not always invalid:

• same tool + same args can be a valid retry if new support appeared
• same tool + same args is a loop if no new evidence/state/result changed
• delegation A → B → A is invalid only if the second handoff does not add new support
• max_iter is only a budget guard, not a correctness guard

So the guardrail should not only hash:

(agent_role, tool_name, canonical_arguments)

It should also include the transition support state:

{
"transition_id": "...",
"agent_role": "...",
"tool_name": "...",
"arguments_hash": "sha256:...",
"required_support": ["..."],
"observed_support": ["..."],
"state_delta_hash": "sha256:...",
"terminal_result_seen": true | false
}

Then the invariant becomes:

do not block because a trajectory repeats;
block because the same transition repeats without new support.

A deterministic rejection rule could be:

same trajectory hash

• same required support
• no new observed support
• no state delta
• no terminal result
  = unsupported repeat / loop

This preserves valid long workflows while stopping the expensive failure mode earlier than max_iter.

Suggested fixture pair:

accept:
same tool/args repeat, but new observed support or terminal result changed

reject:
same tool/args repeat, no new support, no state delta, no terminal result

That would make the guardrail more precise than a pure duplicate-call detector.

[Billionaire664]

This is the right refinement — distinguishing "repeated trajectory" from "repeated trajectory with no new support" is exactly the gap a pure hash-dedupe misses. A retry after new state exists is legitimate work; the same call with nothing changed is the failure mode worth blocking.

Interesting parallel from the spend-gate side: we hit a version of this same problem with retries after a spend_denied. A naive gate would just re-deny an identical retry forever, which is correct in most cases — but not if a human approved an override, or a budget reset, or the wallet's daily window rolled over since the last denial. So "should this repeat be allowed" isn't just (agent, action, args) — it's that tuple plus whether the authorization state changed since the last attempt. Structurally the same shape as your observed_support / state_delta_hash — in our domain "new support" = "did the thing that caused the denial actually change," not just "did time pass" or "did the agent retry."

The accept/reject fixture pair you laid out is the right test to anchor this to — without it, "no new support" is hand-wavy and every implementation will define it slightly differently. Worth pinning down what counts as observed_support concretely (a new tool result? a new upstream state read? just doesn't count if it's the same cached value re-read) before this becomes a spec, or two different guardrail implementations will disagree on the same input.

[Tuttotorna]

Exactly.

The important part is that the repeat check should not be based only on trajectory identity.

A repeated trajectory is valid if the support field changed.
A repeated trajectory with no new support is the loop condition.

So the conformance boundary should be:

Accept:
same agent/action/args trajectory,
but observed_support changed through a real state delta:
human override,
budget reset,
new upstream result,
new tool result,
fresh external state,
policy/window rollover.

Reject:
same agent/action/args trajectory,
same observed_support,
same state_delta_hash,
same cached upstream value,
no new authorization,
no new result,
no new external state.

That makes “no new support” testable instead of implementation-specific.

The key is to hash the support field, not only the call tuple.

[Billionaire664]

Agreed — hashing the support field rather than just the call tuple is the right anchor. Practically: include observed_support (or its hash) as an input to the trajectory hash itself, not a separate check run after. That way if the support state changes, the hash changes naturally, and 'is this a new trajectory or the same one' falls out of the hash comparison instead of needing a second bespoke check layered on top.

Good place to land this."

[Tuttotorna]

Agreed.

That formulation removes the ambiguity.

The trajectory hash should not represent only the call identity.

It should represent the transition attempt:

agent/action/args
+
observed_support_hash

Then the runtime does not need a separate subjective rule for “is this really new?”

If the support field changed, the trajectory identity changes.
If the support field did not change, the repeat remains the same unsupported transition.

That makes loop blocking testable without blocking legitimate retries after a real state or authorization delta.

[mayank609]

@Devaretanmay I really like the deterministic approach because it avoids spending tokens to detect something software can identify locally. One thing I'd also consider is tracking forward progress alongside trajectory hashes. In production we've seen loops where the tool arguments change slightly each iteration, so the hash never repeats even though the agent isn't getting any closer to completing the task. Combining trajectory detection with progress signals (changes in state, retrieved information, or task completion) could reduce both exact loops and semantic loops.