loop-guardrail

Repetitive execution loop detector for AI agents. Tracks tool-call signatures across a session, warns when the same call is repeated, and hard-stops when a call has failed too many times in a row — protecting against runaway tool loops that would otherwise burn tokens and money.

Canonicalizes JSON tool arguments (recursive key sort) so semantically identical calls always hash to the same signature.

Installation

cargo add loop-guardrail

Usage

use loop_guardrail::{ToolCallGuardrailConfig, ToolCallGuardrailController};
use serde_json::json;

let config = ToolCallGuardrailConfig {
    hard_stop_enabled: true,
    warnings_enabled: true,
    exact_failure_warn_after: 2,
    exact_failure_block_after: 3,
    ..Default::default()
};
let mut ctrl = ToolCallGuardrailController::new(Some(config));

let decision = ctrl.before_call("terminal", Some(&json!({"cmd": "ls"})));
if decision.allows_execution() {
    // run the tool, then report back:
    ctrl.after_call("terminal", Some(&json!({"cmd": "ls"})), Some("err"), Some(true));
}

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.