HOL Guard Tool Policy

Gate command-bearing tools through HOL Guard before they execute

HOL Guard checks every shell command your agent proposes and only lets safe ones run.

HOL Guard is an external, optional security engine. Install it separately, then wrap your command-bearing tools with one @wrap_tool_call policy — every unsafe command is blocked before it runs.

Quick Start

1. Install HOL Guard

   HOL Guard is a separate CLI. Install it once:

   pip install hol-guard

2. Add the guard policy to your agent

   import json
   import shutil
   import subprocess
   
   from praisonaiagents import Agent, tool
   from praisonaiagents.hooks import wrap_tool_call, ToolRequest, ToolResponse
   
   COMMAND_BEARING_TOOLS = {"run_shell"}
   GUARD_TIMEOUT_SECONDS = 10
   
   
   @tool
   def run_shell(command: str) -> str:
       """Run a shell command and return its output."""
       result = subprocess.run(command, shell=True, capture_output=True, text=True)
       return result.stdout or result.stderr
   
   
   def _inspect_with_hol_guard(command: str) -> bool:
       if not shutil.which("hol-guard"):
           return False
       try:
           completed = subprocess.run(
               ["hol-guard", "command", "test", command, "--json"],
               capture_output=True, text=True, timeout=GUARD_TIMEOUT_SECONDS,
           )
       except (subprocess.TimeoutExpired, OSError):
           return False
       if completed.returncode != 0:
           return False
       try:
           verdict = json.loads(completed.stdout)
       except (json.JSONDecodeError, ValueError):
           return False
       if not isinstance(verdict, dict):
           return False
       decision = str(verdict.get("decision", "")).lower()
       return decision in ("allow", "benign")
   
   
   @wrap_tool_call
   def hol_guard_tool_policy(request: ToolRequest, call_next):
       if request.tool_name not in COMMAND_BEARING_TOOLS:
           return call_next(request)
   
       command = request.arguments.get("command", "")
   
       if _inspect_with_hol_guard(command):
           return call_next(request)
   
       blocked_message = "Blocked by HOL Guard: command was not explicitly allowed."
       return ToolResponse(
           tool_name=request.tool_name,
           result=blocked_message,
           error=blocked_message,
           context=request.context,
       )
   
   
   agent = Agent(
       name="GuardedShellBot",
       instructions="You run shell commands only when they are safe.",
       tools=[run_shell],
       hooks=[hol_guard_tool_policy],
   )

3. Run and see a blocked command

   agent.start("Delete every file with: rm -rf /")

   HOL Guard inspects the command, returns a non-allow verdict, and the agent receives the blocked message instead of running the tool.

How It Works

Every command-bearing tool call passes through HOL Guard’s CLI before it can execute.

Tools that are not in COMMAND_BEARING_TOOLS skip the guard entirely and run untouched.

Configuration Options

Tune the policy by editing the constants in the example.

Fail-Closed Decision Matrix

The policy runs the tool only on an explicit safe verdict — everything else blocks.

User Interaction Flow

A real user asks for an unsafe command; HOL Guard blocks it and the agent refuses politely.

Common Patterns

Widen the tool allow-list — add more command-bearing tools to the set:

COMMAND_BEARING_TOOLS = {"run_shell", "run_script", "exec_command"}

Log every blocked verdict with an after_tool hook:

from praisonaiagents.hooks import after_tool, ToolResponse

@after_tool
def log_blocks(response: ToolResponse):
    if response.error:
        print(f"[guard] blocked {response.tool_name}: {response.error}")
    return response

Combine with before_tool argument validation for defense in depth:

from praisonaiagents.hooks import before_tool, ToolRequest

@before_tool
def require_command(request: ToolRequest):
    if request.tool_name in COMMAND_BEARING_TOOLS and not request.arguments.get("command"):
        raise ValueError("run_shell requires a non-empty command.")
    return request

Best Practices

Related