Module tool_guardrails 

Per-turn tool-call guardrails.

Sits alongside the existing recent_tool_call_keys circuit breaker (which short-circuits identical-(tool,args) calls after N repeats). This module adds two finer-grained signals from hermes-agent’s tool_guardrails.py:

• Idempotent no-progress: if a read-only tool returns the same result hash N times for the same args, append a guidance suffix to the tool result asking the model to use what it already has instead of repeating.
• Same-tool failure streak: if any tool fails N times this turn — with ANY args — append guidance suggesting a different approach.

Both signals only emit warnings (the result still goes back to the model); they never block execution. The existing duplicate-call circuit breaker handles the blocking case for identical (tool, args) repeats.

The Controller is reset per turn by the agent loop.

Structs

GuardrailController

ToolGrantRule

ToolPolicyConfig

Config-driven pre-tool-call policy (tool_policy in config.yaml).

Enums

PolicyDecision

Outcome of evaluating one pending tool call against the policy.

ToolPolicyMode

Pre-tool-call policy mode. Off preserves historical behavior (no policy evaluation at all); Warn logs violations to the audit trail but lets the call run; Block short-circuits the call with an error tool_result.

Functions

evaluate_tool_policy

Evaluate tool_name against the configured policy. Pure — callers handle audit logging and short-circuiting.

evaluate_tool_policy_for_auth

Evaluate the global policy and the caller’s least-privilege capability grants. A grant never weakens a global block.

evaluate_tool_policy_for_auth_with_risk

Like evaluate_tool_policy_for_auth but with the tool’s effective risk supplied by the caller (registration-time overrides such as MCP server trust tiers).

evaluate_tool_policy_with_risk

Like evaluate_tool_policy but with the tool’s effective risk supplied by the caller — used when a registration-time override (e.g. an MCP server trust tier) replaces the name-derived risk.