<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Testing Agent Tool Use Safety

## Tool Call Validation
```python
import re

BLOCKED = ["/etc/shadow", "/proc/", "rm -rf"]

def validate_args(tool: str, args: dict) -> bool:
    for val in args.values():
        if isinstance(val, str):
            for pat in BLOCKED:
                if re.search(pat, val, re.IGNORECASE):
                    return False
    return True
```

## Permission Boundary Check
```python
TOOL_PERMISSIONS = {
    "read_file": ["read"],
    "write_file": ["write"],
    "execute_command": ["execute"],
}
CONFIRMATION_REQUIRED = {"write_file", "execute_command"}

def needs_confirmation(tool: str) -> bool:
    return tool in CONFIRMATION_REQUIRED
```

## Rate Limit Enforcement
```python
import time
from collections import defaultdict

call_log: dict[str, list[float]] = defaultdict(list)

def rate_check(tool: str, limit: int = 10) -> bool:
    now = time.time()
    call_log[tool] = [t for t in call_log[tool] if now - t < 60]
    if len(call_log[tool]) >= limit:
        return False
    call_log[tool].append(now)
    return True
```

## Schema Validation
```python
SCHEMAS = {"read_file": {"path": str}, "write_file": {"path": str, "content": str}}

def check_schema(tool: str, args: dict) -> list[str]:
    errors = []
    schema = SCHEMAS.get(tool, {})
    for k, v in args.items():
        if k not in schema:
            errors.append(f"unexpected arg: {k}")
        elif not isinstance(v, schema[k]):
            errors.append(f"type error: {k}")
    return errors
```
