toolfence 0.1.0__tar.gz

toolfence-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rik Banerjee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

toolfence-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: toolfence
+Version: 0.1.0
+Summary: Deterministic runtime security for AI agent tools
+License-File: LICENSE
+Author: Rik Banerjee
+Author-email: rikban@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Description-Content-Type: text/markdown
+
+# ToolFence
+
+**Deterministic runtime security for AI agent tools.**
+
+LLMs can hallucinate and be prompt-engineered, allowing faulty agent actions to slip through. ToolFence helps solve this by enforcing strict and deterministic rules.
+
+ToolFence is a lightweight Python framework that sits between your LLM and your tool functions. When an agent calls a tool, ToolFence intercepts the call, evaluates your rules, and either passes it through, blocks it, or escalates it for user approval — all before your tool function runs. Rules are Python code, not LLM instructions, so they cannot be overridden by a clever prompt.
+
+---
+
+## Why ToolFence
+
+LLMs are good at deciding *what* to do. They are not reliable enforcers of *what is allowed*. A well-crafted prompt can convince an LLM to ignore its own safety instructions. ToolFence allows a quick and simple way to enforce policy at the code layer — outside the prompt, outside the model, and outside the reach of any user input.
+
+```
+User prompt → LLM → tool call → [ToolFence] → tool execution
+                                      ↑
+                          deterministic rules run here
+```
+
+---
+
+## Installation
+
+```bash
+pip install toolfence
+```
+
+---
+
+## Quick example
+
+```python
+from toolfence import secure, AgentManager, Rule, BlockedToolCall
+
+manager = AgentManager()
+manager.set_default_approval_handler(lambda ctx: input(f'Do you approve {ctx.tool_call.tool} to execute? ') == 'yes')
+
+manager.set_rules(
+    tool = "transfer_funds",
+    rules=[
+        # Hard block — never transfer over $10,000
+        Rule(
+            id="transfer-hard-limit",
+            description="Transfers over $10,000 are never permitted.",
+            condition=lambda ctx: ctx.tool_call.arguments.amount > 10000,
+            action="block"
+        ),
+        # Escalate — transfers over $1,000 need user approval
+        Rule(
+            id="transfer-large-escalate",
+            description="Transfers over $1,000 require approval.",
+            condition=lambda ctx: ctx.tool_call.arguments.amount > 1000,
+            action="escalate"
+        ),
+    ],
+)
+
+@secure(manager)
+def transfer_funds(from_account: str, to_account: str, amount: float) -> dict:
+    return {"status": "transferred", "amount": amount}
+
+manager.validate()
+
+try:
+    transfer_funds("ACC-001", "ACC-002", 15000.0)
+except BlockedToolCall as e:
+    print(e.message)  # "Transfers over $10,000 are never permitted."
+```
+
+---
+
+## Features
+
+- **Hard block rules** — write Python conditions that unconditionally prevent a tool call from executing
+- **Escalation rules** — pause execution and require user approval before proceeding
+- **Evidence verification** — load trusted data (e.g., database, API) and verify LLM-supplied arguments against it, catching hallucinations and prompt injection
+- **Argument checking** — validate argument presence and types before rules even run
+- **Async support** — works with async tools and async approval handlers
+- **Config validation** — catch misconfigured rules, missing handlers, and configuration mistakes before your agent runs
+- **Structured errors** — every blocked tool call raises `BlockedToolCall` with a message for your agent's LLM
+- **Full history** — every tool call (passed or blocked) is recorded in `AgentManager.history`
+- **Easy Integration** — easily integrates with other frameworks and workflows such as LangChain
+
+---
+
+## How it works
+
+```
+@secure(manager)
+def my_tool(arg: str) -> dict: ...
+```
+
+Decorating a function with `@secure` registers it with the `AgentManager` and wraps it with the ToolFence interceptor. Every call to `my_tool` now runs through:
+
+1. **Argument checking** — are all required arguments present and correctly typed?
+2. **Block rules** — does any block rule condition return `True`? If so, raise `BlockedToolCall`.
+3. **Escalation rules** — does any escalation rule condition return `True`? If so, call the approval handler. If denied, raise `BlockedToolCall`.
+4. **Execute** — all checks passed, run the real tool function.
+5. **Record** — log the call to `AgentManager.history`.
+
+---
+
+## Documentation
+
+- [Getting Started](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/getting-started.md)
+- [Core Concepts](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/core-concepts.md)
+- [Rules](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/rules.md)
+- [Evidence](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/evidence.md)
+- [Approval Handlers](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/approval-handlers.md)
+- [API Reference](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/api-reference.md)
+
+---
+
+## Examples
+
+- [`examples/example_basic.py`](https://github.com/Rik-Banerjee/toolfence/blob/main/examples/example_basic.py) — minimal setup with block and escalation rules
+- [`examples/example_evidence.py`](https://github.com/Rik-Banerjee/toolfence/blob/main/examples/example_evidence.py) — evidence verification and prompt injection prevention
+

toolfence-0.1.0/README.md

@@ -0,0 +1,118 @@
+# ToolFence
+
+**Deterministic runtime security for AI agent tools.**
+
+LLMs can hallucinate and be prompt-engineered, allowing faulty agent actions to slip through. ToolFence helps solve this by enforcing strict and deterministic rules.
+
+ToolFence is a lightweight Python framework that sits between your LLM and your tool functions. When an agent calls a tool, ToolFence intercepts the call, evaluates your rules, and either passes it through, blocks it, or escalates it for user approval — all before your tool function runs. Rules are Python code, not LLM instructions, so they cannot be overridden by a clever prompt.
+
+---
+
+## Why ToolFence
+
+LLMs are good at deciding *what* to do. They are not reliable enforcers of *what is allowed*. A well-crafted prompt can convince an LLM to ignore its own safety instructions. ToolFence allows a quick and simple way to enforce policy at the code layer — outside the prompt, outside the model, and outside the reach of any user input.
+
+```
+User prompt → LLM → tool call → [ToolFence] → tool execution
+                                      ↑
+                          deterministic rules run here
+```
+
+---
+
+## Installation
+
+```bash
+pip install toolfence
+```
+
+---
+
+## Quick example
+
+```python
+from toolfence import secure, AgentManager, Rule, BlockedToolCall
+
+manager = AgentManager()
+manager.set_default_approval_handler(lambda ctx: input(f'Do you approve {ctx.tool_call.tool} to execute? ') == 'yes')
+
+manager.set_rules(
+    tool = "transfer_funds",
+    rules=[
+        # Hard block — never transfer over $10,000
+        Rule(
+            id="transfer-hard-limit",
+            description="Transfers over $10,000 are never permitted.",
+            condition=lambda ctx: ctx.tool_call.arguments.amount > 10000,
+            action="block"
+        ),
+        # Escalate — transfers over $1,000 need user approval
+        Rule(
+            id="transfer-large-escalate",
+            description="Transfers over $1,000 require approval.",
+            condition=lambda ctx: ctx.tool_call.arguments.amount > 1000,
+            action="escalate"
+        ),
+    ],
+)
+
+@secure(manager)
+def transfer_funds(from_account: str, to_account: str, amount: float) -> dict:
+    return {"status": "transferred", "amount": amount}
+
+manager.validate()
+
+try:
+    transfer_funds("ACC-001", "ACC-002", 15000.0)
+except BlockedToolCall as e:
+    print(e.message)  # "Transfers over $10,000 are never permitted."
+```
+
+---
+
+## Features
+
+- **Hard block rules** — write Python conditions that unconditionally prevent a tool call from executing
+- **Escalation rules** — pause execution and require user approval before proceeding
+- **Evidence verification** — load trusted data (e.g., database, API) and verify LLM-supplied arguments against it, catching hallucinations and prompt injection
+- **Argument checking** — validate argument presence and types before rules even run
+- **Async support** — works with async tools and async approval handlers
+- **Config validation** — catch misconfigured rules, missing handlers, and configuration mistakes before your agent runs
+- **Structured errors** — every blocked tool call raises `BlockedToolCall` with a message for your agent's LLM
+- **Full history** — every tool call (passed or blocked) is recorded in `AgentManager.history`
+- **Easy Integration** — easily integrates with other frameworks and workflows such as LangChain
+
+---
+
+## How it works
+
+```
+@secure(manager)
+def my_tool(arg: str) -> dict: ...
+```
+
+Decorating a function with `@secure` registers it with the `AgentManager` and wraps it with the ToolFence interceptor. Every call to `my_tool` now runs through:
+
+1. **Argument checking** — are all required arguments present and correctly typed?
+2. **Block rules** — does any block rule condition return `True`? If so, raise `BlockedToolCall`.
+3. **Escalation rules** — does any escalation rule condition return `True`? If so, call the approval handler. If denied, raise `BlockedToolCall`.
+4. **Execute** — all checks passed, run the real tool function.
+5. **Record** — log the call to `AgentManager.history`.
+
+---
+
+## Documentation
+
+- [Getting Started](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/getting-started.md)
+- [Core Concepts](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/core-concepts.md)
+- [Rules](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/rules.md)
+- [Evidence](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/evidence.md)
+- [Approval Handlers](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/approval-handlers.md)
+- [API Reference](https://github.com/Rik-Banerjee/toolfence/blob/main/docs/api-reference.md)
+
+---
+
+## Examples
+
+- [`examples/example_basic.py`](https://github.com/Rik-Banerjee/toolfence/blob/main/examples/example_basic.py) — minimal setup with block and escalation rules
+- [`examples/example_evidence.py`](https://github.com/Rik-Banerjee/toolfence/blob/main/examples/example_evidence.py) — evidence verification and prompt injection prevention

toolfence-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "toolfence"
+version = "0.1.0"
+description = "Deterministic runtime security for AI agent tools"
+authors = [
+    {name = "Rik Banerjee",email = "rikban@gmail.com"}
+]
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+dependencies = [
+]
+
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[dependency-groups]
+test = [
+    "pytest (>=9.0.2,<10.0.0)",
+    "pytest-asyncio (>=1.3.0,<2.0.0)"
+]

toolfence-0.1.0/src/toolfence/__init__.py

@@ -0,0 +1,4 @@
+from .toolfence import AgentManager
+from .toolfence_secure import secure
+from .toolfence_data import Rule, BlockedToolCall, BlockReason, ToolCallRecord
+from .toolfence_config import ToolFenceSetupError

toolfence-0.1.0/src/toolfence/toolfence.py

@@ -0,0 +1,136 @@
+import inspect
+from typing import Callable, Dict, List, Set
+
+from .toolfence_data import (
+    Context,
+    DynamicData,
+    Rule,
+    Tool,
+    ToolCall,
+    ToolCallRecord,
+    ValidationResult,
+    _create_tool_call_record,
+)
+from .toolfence_validation import run_block_rules, run_escalation_rules
+from .toolfence_config import (
+    ConfigIssue,
+    ToolFenceSetupError,
+    check_approval_handler,
+    check_default_approval_handler,
+    check_rule,
+    validate_manager,
+)
+
+
+class AgentManager:
+    def __init__(self, version: str = "default"):
+        self.version = version
+
+        self.tools: Dict[str, Tool] = {}
+        self.history: List[ToolCallRecord] = []
+        self.evidence: DynamicData = DynamicData()
+
+        self.block_rules: Dict[str, List[Rule]] = {}
+        self.escalation_rules: Dict[str, List[Rule]] = {}
+        self.arg_checking_tools: Set[str] = set()
+
+        self.default_approval_handler: Callable[[Context], bool] | None = None
+        self.tool_approval_handlers: Dict[str, Callable[[Context], bool] | str] = {}
+
+        self.rule_ids: Dict[str, str] = {}
+
+    def set_evidence(self, key: str, value) -> None:
+        setattr(self.evidence, key, value)
+
+
+    def set_rules(
+        self,
+        tool: str,
+        rules: List[Rule] = [],
+        approval_handler: Callable[[Context], bool] | str = "default",
+        arg_checking: bool = True,
+    ) -> None:
+
+        # Structural check
+        issues: List[ConfigIssue] = []
+        duplicates = set()
+
+        for rule in rules:
+            # Duplicate ID check
+            if isinstance(rule.id, str) and rule.id.strip():
+                if rule.id in self.rule_ids or rule.id in duplicates:
+                    issues.append(ConfigIssue(
+                        level="error",
+                        location=f"rule:{rule.id} (tool:{tool})",
+                        message=(
+                            f'Rule ID "{rule.id}" is already used by tool '
+                            f'"{tool if rule.id in duplicates else self.rule_ids[rule.id]}". Rule IDs must be unique.'
+                        ),
+                    ))
+                    continue
+                else:
+                    duplicates.add(rule.id)
+
+            issues.extend(check_rule(rule, tool))
+
+        if approval_handler != "default":
+            issues.extend(check_approval_handler(approval_handler, tool))
+
+        errors = [i for i in issues if i.level == "error"]
+        warnings = [i for i in issues if i.level == "warning"]
+
+        if warnings:
+            print(f'ToolFence configuration warnings for "{tool}":')
+            for w in warnings:
+                print(w)
+
+        if errors:
+
+            error_lines = "\n".join(str(e) for e in errors)
+            raise ToolFenceSetupError(
+                f'ToolFence configuration errors in set_rules("{tool}") — '
+                f'fix these before running the agent:\n{error_lines}'
+            )
+
+        self.tool_approval_handlers[tool] = approval_handler
+
+        if arg_checking:
+            self.arg_checking_tools.add(tool)
+
+        block_rules = []
+        escalation_rules = []
+
+        for rule in rules:
+            self.rule_ids[rule.id] = tool
+            if rule.action == "block":
+                block_rules.append(rule)
+            else:
+                escalation_rules.append(rule)
+
+        self.block_rules[tool] = block_rules
+        self.escalation_rules[tool] = escalation_rules
+
+    def set_default_approval_handler(self, handler: Callable[[Context], bool]) -> None:
+        # Structural check
+        issues = check_default_approval_handler(handler)
+
+        errors = [i for i in issues if i.level == "error"]
+        warnings = [i for i in issues if i.level == "warning"]
+
+        if warnings:
+            print("ToolFence configuration warnings for default approval handler:")
+            for w in warnings:
+                print(w)
+
+        if errors:
+            error_lines = "\n".join(str(e) for e in errors)
+            raise ToolFenceSetupError(
+                f"ToolFence configuration errors in set_default_approval_handler() — "
+                f"fix these before running the agent:\n{error_lines}"
+            )
+
+        self.default_approval_handler = handler
+
+    # Full ToolFence configuration check
+    def validate(self) -> None:
+        validate_manager(self)

toolfence-0.1.0/src/toolfence/toolfence_config.py

@@ -0,0 +1,226 @@
+import inspect
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, List
+
+from .toolfence_data import Rule
+
+if TYPE_CHECKING:
+    from .toolfence import AgentManager
+
+
+
+
+class ToolFenceSetupError(Exception):
+    def __init__(self, message: str):
+        self.message = message
+        super().__init__(message)
+
+
+@dataclass
+class ConfigIssue:
+    level: str       # "error" or "warning"
+    location: str    # e.g. "tool:transfer_funds", "rule:transfer-limit", "handler:default"
+    message: str
+
+    def __str__(self) -> str:
+        return f"  [{self.level.upper()}] {self.location}: {self.message}"
+
+# Checks for number of params the handler accepts
+def _handler_param_count(handler) -> int:
+    if inspect.isfunction(handler) or inspect.isbuiltin(handler):
+        return len(inspect.signature(handler).parameters)
+
+    if inspect.ismethod(handler):
+        return len(inspect.signature(handler).parameters)
+
+    if hasattr(handler, '__call__'):
+        params = list(inspect.signature(handler.__call__).parameters.values())
+        return len([p for p in params if p.name != 'self'])
+
+    return -1
+
+
+# Validate a rule
+def check_rule(rule: Rule, tool: str) -> List[ConfigIssue]:
+    issues = []
+    location = f"rule:{rule.id} (tool:{tool})"
+
+    # Rule ID must be non-empty, non-whitespace
+    if not isinstance(rule.id, str) or not rule.id.strip():
+        issues.append(ConfigIssue(
+            level="error",
+            location=f"rule (tool:{tool})",
+            message="Rule ID must be a non-empty, non-whitespace string.",
+        ))
+        return issues
+
+    # Condition must be callable
+    if not callable(rule.condition):
+        issues.append(ConfigIssue(
+            level="error",
+            location=location,
+            message=f"Condition is not callable. Got {type(rule.condition).__name__}.",
+        ))
+        return issues
+
+    # Condition must accept exactly one argument (context)
+    param_count = _handler_param_count(rule.condition)
+    if param_count != 1:
+        issues.append(ConfigIssue(
+            level="error",
+            location=location,
+            message=(
+                f"Condition must accept exactly one argument (context). "
+                f"Got {param_count} parameter(s)."
+            ),
+        ))
+
+    # Action must be "block" or "escalate"
+    if rule.action not in ("block", "escalate"):
+        issues.append(ConfigIssue(
+            level="error",
+            location=location,
+            message=(
+                f'Invalid action "{rule.action}". '
+                f'Valid actions are "block" or "escalate".'
+            ),
+        ))
+
+    return issues
+
+# Validate approval handler
+def check_approval_handler(handler, tool: str) -> List[ConfigIssue]:
+    issues = []
+    location = f"handler (tool:{tool})"
+
+    if not callable(handler):
+        issues.append(ConfigIssue(
+            level="error",
+            location=location,
+            message=f"Approval handler is not callable. Got {type(handler).__name__}.",
+        ))
+        return issues
+
+    # Handler must accept exactly one argument (context)
+    param_count = _handler_param_count(handler)
+    if param_count != 1:
+        issues.append(ConfigIssue(
+            level="error",
+            location=location,
+            message=(
+                f"Approval handler must accept exactly one argument (context). "
+                f"Got {param_count} parameter(s)."
+            ),
+        ))
+
+    return issues
+
+# Validate default handler
+def check_default_approval_handler(handler) -> List[ConfigIssue]:
+    return check_approval_handler(handler, tool="default")
+
+
+
+# Run full AgentManager configuration checks
+def validate_manager(manager: "AgentManager") -> None:
+    issues: List[ConfigIssue] = []
+
+    registered_tools = set(manager.tools.keys())
+    configured_tools = set(manager.block_rules.keys()) | set(manager.escalation_rules.keys())
+
+    # Escalation rules must have approval handler
+    for tool, rules in manager.escalation_rules.items():
+        if not rules:
+            continue
+
+        handler = manager.tool_approval_handlers.get(tool)
+
+        if handler is None:
+            issues.append(ConfigIssue(
+                level="error",
+                location=f"tool:{tool}",
+                message=(
+                    'Tool has escalation rule(s) but no approval handler configured. '
+                    'Pass approval_handler= to set_rules() or call set_default_approval_handler().'
+                ),
+            ))
+        elif handler == "default" and manager.default_approval_handler is None:
+            issues.append(ConfigIssue(
+                level="error",
+                location=f"tool:{tool}",
+                message=(
+                    'Tool has escalation rule(s) that rely on the default approval handler, '
+                    'but no default handler has been set. '
+                    'Call set_default_approval_handler() before running the agent.'
+                ),
+            ))
+
+    # Check for async handlers assigned to sync tools
+    for tool, handler in manager.tool_approval_handlers.items():
+        if handler == "default":
+            handler = manager.default_approval_handler
+        if handler is None or not inspect.iscoroutinefunction(handler):
+            continue
+
+        tool_obj = manager.tools.get(tool)
+        if tool_obj is not None and not tool_obj.is_async:
+            issues.append(ConfigIssue(
+                level="error",
+                location=f"tool:{tool}",
+                message=(
+                    f'Approval handler is async but "{tool}" is a sync tool. '
+                    f'Use a sync handler or convert the tool to async.'
+                ),
+            ))
+
+    # set_rules called for a tool not decorated with @secure
+    for tool in configured_tools:
+        if tool not in registered_tools:
+            issues.append(ConfigIssue(
+                level="warning",
+                location=f"tool:{tool}",
+                message=(
+                    f'set_rules() was called for "{tool}" but no @secure-decorated function '
+                    f'with that name has been registered. '
+                    f'Check for a name mismatch or missing @secure decorator.'
+                ),
+            ))
+
+    # @secure tools with no set_rules call
+    for tool in registered_tools:
+        if tool not in configured_tools:
+            issues.append(ConfigIssue(
+                level="warning",
+                location=f"tool:{tool}",
+                message=(
+                    f'"{tool}" is decorated with @secure but set_rules() was never called for it. '
+                    f'It will run with no rules and no arg checking.'
+                ),
+            ))
+
+    # Default handler set but no escalation rules anywhere
+    has_any_escalation = any(bool(rules) for rules in manager.escalation_rules.values())
+    if manager.default_approval_handler is not None and not has_any_escalation:
+        issues.append(ConfigIssue(
+            level="warning",
+            location="handler:default",
+            message=(
+                "A default approval handler is set but no escalation rules exist anywhere. "
+                "The handler will never be called."
+            ),
+        ))
+
+    errors   = [i for i in issues if i.level == "error"]
+    warnings = [i for i in issues if i.level == "warning"]
+
+    if warnings:
+        print("ToolFence configuration warnings:")
+        for w in warnings:
+            print(w)
+
+    if errors:
+        error_lines = "\n".join(str(e) for e in errors)
+        raise ToolFenceSetupError(
+            f"ToolFence configuration errors found — fix these before running the agent:\n"
+            f"{error_lines}"
+        )

toolfence-0.1.0/src/toolfence/toolfence_data.py

@@ -0,0 +1,89 @@
+from dataclasses import dataclass
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, Callable, List
+import uuid
+
+
+class DynamicData:
+    pass
+
+@dataclass(frozen=True)
+class ToolCall:
+    tool: str
+    arguments: DynamicData
+
+
+@dataclass(frozen=True)
+class Tool:
+    name: str
+    parameters: Dict[str, Dict]
+    is_async: bool
+
+
+@dataclass(frozen=True)
+class ToolCallRecord:
+    uuid: str
+    tool: str
+    arguments: DynamicData
+    timestamp: datetime
+    blocked: bool
+    reason: str
+
+
+@dataclass(frozen=True)
+class Context:
+    tool_call: ToolCall
+    evidence: DynamicData
+    history: List[ToolCallRecord]
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    description: str
+    condition: Callable[[Context], bool]
+    action: str  # "block" | "escalate"
+
+@dataclass(frozen=True)
+class ValidationResult:
+    blocked: bool
+    requires_approval: bool
+    message: str
+    rule_id: str | None = None
+
+
+class BlockReason(str, Enum):
+    RULE_TRIGGERED         = "RULE_TRIGGERED"
+    APPROVAL_DENIED        = "APPROVAL_DENIED"
+    NO_APPROVAL_HANDLER    = "NO_APPROVAL_HANDLER"
+    ASYNC_HANDLER_MISMATCH = "ASYNC_HANDLER_MISMATCH"
+    MISSING_ARGUMENT       = "MISSING_ARGUMENT"
+    INVALID_ARGUMENT_TYPE  = "INVALID_ARGUMENT_TYPE"
+
+
+
+class BlockedToolCall(Exception):
+    def __init__(self, tool: str, reason: BlockReason, message: str, record: ToolCallRecord):
+        self.tool = tool
+        self.reason = reason
+        self.message = message
+        self.record = record
+        super().__init__(f"[{reason}] {tool}: {message}")
+
+
+
+def _create_tool_call_record(
+    tool_call: ToolCall,
+    blocked: bool,
+    reason: str,
+) -> ToolCallRecord:
+    return ToolCallRecord(
+        uuid=str(uuid.uuid4()),
+        tool=tool_call.tool,
+        arguments=tool_call.arguments,
+        timestamp=datetime.utcnow(),
+        blocked=blocked,
+        reason=reason,
+    )
+

toolfence-0.1.0/src/toolfence/toolfence_secure.py

@@ -0,0 +1,230 @@
+import inspect
+from functools import wraps
+from typing import Callable, Dict, List
+
+from .toolfence_data import (
+    BlockReason,
+    BlockedToolCall,
+    Context,
+    DynamicData,
+    Rule,
+    Tool,
+    ToolCall,
+    ToolCallRecord,
+    ValidationResult,
+    _create_tool_call_record,
+)
+from .toolfence_validation import run_block_rules, run_escalation_rules
+from .toolfence import AgentManager
+
+
+
+def _block(manager: AgentManager, tool_call: ToolCall, reason: BlockReason, message: str) -> None:
+    record = _create_tool_call_record(tool_call, True, reason.value)
+    manager.history.append(record)
+    raise BlockedToolCall(tool_call.tool, reason, message, record)
+
+
+def _pass(manager: AgentManager, tool_call: ToolCall) -> None:
+    record = _create_tool_call_record(tool_call, False, "")
+    manager.history.append(record)
+
+
+def _build_tool_call(fn_name: str, signature, args, kwargs) -> ToolCall:
+    bound = signature.bind_partial(*args, **kwargs)
+    bound.apply_defaults()
+
+    arguments = DynamicData()
+    for key, value in bound.arguments.items():
+        setattr(arguments, key, value)
+
+    return ToolCall(tool=fn_name, arguments=arguments)
+
+
+def _build_context(manager: AgentManager, tool_call: ToolCall) -> Context:
+    return Context(
+        tool_call=tool_call,
+        evidence=manager.evidence,
+        history=manager.history,
+    )
+
+
+def _build_tool(tool_name: str, parameters: Dict, is_async: bool) -> Tool:
+    filtered_parameters = {}
+
+    for parameter in parameters:
+        parameter_data = {'type': 'no_type', 'hasDefault': False}
+
+        annotation = parameters[parameter].annotation
+        default = parameters[parameter].default
+
+        if annotation != inspect._empty:
+            parameter_data['type'] = annotation
+
+        if default != inspect._empty:
+            parameter_data['hasDefault'] = True
+
+        filtered_parameters[parameter] = parameter_data
+
+    return Tool(
+        name=tool_name,
+        parameters=filtered_parameters,
+        is_async=is_async,
+    )
+
+
+def _validate_approval_handler(
+    manager: AgentManager,
+    tool_call: ToolCall,
+    is_async_tool: bool,
+) -> Callable:
+    approval_handler = manager.tool_approval_handlers.get(tool_call.tool)
+
+    if approval_handler == "default":
+        if manager.default_approval_handler is None:
+            _block(
+                manager, tool_call,
+                BlockReason.NO_APPROVAL_HANDLER,
+                f'No default approval handler set. Provide one via set_default_approval_handler().',
+            )
+        approval_handler = manager.default_approval_handler
+
+    if not is_async_tool and inspect.iscoroutinefunction(approval_handler):
+        _block(
+            manager, tool_call,
+            BlockReason.ASYNC_HANDLER_MISMATCH,
+            f'Approval handler for "{tool_call.tool}" is async but the tool is sync. '
+            f'Use a sync handler or make the tool async.',
+        )
+
+    return approval_handler
+
+
+def _execute_validation(manager: AgentManager, tool_call: ToolCall, context: Context) -> ValidationResult:
+    block_result = run_block_rules(
+        context,
+        manager.block_rules.get(tool_call.tool, []),
+    )
+
+    if block_result.blocked:
+        return block_result
+
+    return run_escalation_rules(
+        context,
+        manager.escalation_rules.get(tool_call.tool, []),
+    )
+
+
+def _arg_checking(manager: AgentManager, tool_name: str, tool_call: ToolCall) -> None:
+    if tool_name not in manager.arg_checking_tools:
+        return
+
+    arguments = dict(vars(tool_call.arguments).items())
+    parameters = manager.tools[tool_name].parameters
+
+
+    for parameter in parameters:
+        if parameter not in arguments:
+            _block(
+                manager, tool_call,
+                BlockReason.MISSING_ARGUMENT,
+                f'"{tool_call.tool}" is missing required argument "{parameter}".',
+            )
+        else:
+            expected_type = parameters[parameter]['type']
+            if expected_type != 'no_type':
+                if not isinstance(arguments[parameter], expected_type):
+                    _block(
+                        manager, tool_call,
+                        BlockReason.INVALID_ARGUMENT_TYPE,
+                        f'"{tool_call.tool}" received invalid type for argument "{parameter}". '
+                        f'Expected {expected_type.__name__}, got {type(arguments[parameter]).__name__}.',
+                    )
+
+
+
+# @secure decorator
+def secure(manager: AgentManager):
+    def decorator(fn):
+        signature = inspect.signature(fn)
+        tool_name = fn.__name__
+        parameters = dict(signature.parameters)
+        is_async = inspect.iscoroutinefunction(fn)
+
+        manager.tools[tool_name] = _build_tool(tool_name, parameters, is_async)
+
+        # Build sync wrapper
+        if not is_async:
+
+            @wraps(fn)
+            def wrapper(*args, **kwargs):
+                tool_call = _build_tool_call(tool_name, signature, args, kwargs)
+                _arg_checking(manager, tool_name, tool_call)
+
+                context = _build_context(manager, tool_call)
+                result = _execute_validation(manager, tool_call, context)
+
+                if result.blocked:
+                    _block(
+                        manager, tool_call,
+                        BlockReason.RULE_TRIGGERED,
+                        f'Rule "{result.rule_id}" blocked this call: {result.message}',
+                    )
+
+                if result.requires_approval:
+                    approval_handler = _validate_approval_handler(manager, tool_call, False)
+                    if not approval_handler(context):
+                        _block(
+                            manager, tool_call,
+                            BlockReason.APPROVAL_DENIED,
+                            f'"{tool_call.tool}" was denied by the approval handler.',
+                        )
+
+                result = fn(*args, **kwargs)
+                _pass(manager, tool_call)
+                return result
+
+            return wrapper
+
+        # Build async wrapper
+        else:
+
+            @wraps(fn)
+            async def wrapper(*args, **kwargs):
+                tool_call = _build_tool_call(tool_name, signature, args, kwargs)
+                _arg_checking(manager, tool_name, tool_call)
+
+                context = _build_context(manager, tool_call)
+                result = _execute_validation(manager, tool_call, context)
+
+                if result.blocked:
+                    _block(
+                        manager, tool_call,
+                        BlockReason.RULE_TRIGGERED,
+                        f'Rule "{result.rule_id}" blocked this call: {result.message}',
+                    )
+
+                if result.requires_approval:
+                    approval_handler = _validate_approval_handler(manager, tool_call, True)
+                    is_async_handler = inspect.iscoroutinefunction(approval_handler)
+
+                    approved = (
+                        await approval_handler(context)
+                        if is_async_handler
+                        else approval_handler(context)
+                    )
+
+                    if not approved:
+                        _block(
+                            manager, tool_call,
+                            BlockReason.APPROVAL_DENIED,
+                            f'"{tool_call.tool}" was denied by the approval handler.',
+                        )
+
+                result = await fn(*args, **kwargs)
+                _pass(manager, tool_call)
+                return result
+
+            return wrapper
+
+    return decorator

toolfence-0.1.0/src/toolfence/toolfence_validation.py

@@ -0,0 +1,53 @@
+from typing import List
+
+from .toolfence_data import Context, Rule, ValidationResult
+
+
+def _evaluate_rule(rule: Rule, context: Context) -> bool:
+    return rule.condition(context)
+
+
+def run_block_rules(context: Context, rules: List[Rule]) -> ValidationResult:
+    for rule in rules:
+        try:
+            triggered = _evaluate_rule(rule, context)
+        except Exception as e:
+            return ValidationResult(
+                blocked=True,
+                requires_approval=False,
+                message=f'Rule "{rule.id}" raised an exception: {e}',
+                rule_id=rule.id,
+            )
+
+        if triggered:
+            return ValidationResult(
+                blocked=True,
+                requires_approval=False,
+                message=rule.description,
+                rule_id=rule.id,
+            )
+
+    return ValidationResult(blocked=False, requires_approval=False, message="")
+
+
+def run_escalation_rules(context: Context, rules: List[Rule]) -> ValidationResult:
+    for rule in rules:
+        try:
+            triggered = _evaluate_rule(rule, context)
+        except Exception as e:
+            return ValidationResult(
+                blocked=True,
+                requires_approval=False,
+                message=f'Rule "{rule.id}" raised an exception: {e}',
+                rule_id=rule.id,
+            )
+
+        if triggered:
+            return ValidationResult(
+                blocked=False,
+                requires_approval=True,
+                message=rule.description,
+                rule_id=rule.id,
+            )
+
+    return ValidationResult(blocked=False, requires_approval=False, message="")