[FEATURE] Proxy-level Allowed Tools Control and Enforcement

[matdev83]

[FEATURE] Proxy-level Allowed Tools Control and Enforcement

Feature Description

Add a new proxy feature for user-configurable access control of tool calling, allowing users to define allowed/disallowed lists of tools that LLMs can use/execute. This should support per-model regex-based tool name matching, with both global proxy-wide policies and granular configuration on a per-(backend x modelname) level.

Problem Statement

Currently, models can call any tool without user control at the proxy level. As this proxy aims to enhance user experience in agentic coding workflows, we need configurable access control to let users decide which tools should be allowed, especially when the agent or LLM client doesn't provide precise control.

Proposed Solution

Implement a tiered configuration mechanism with two main components:

1. Tool Definition Filtering: Strip disallowed tool definitions from requests sent to the LLM to reduce wasted turns.
2. Tool Call Blocking: Use the existing Tool Call Reactor to block disallowed tool calls in LLM responses as a hard stop.

Configuration Architecture

• Global Overrides: Controlled by CLI params, taking precedence over backend-level configuration.
• Per-Backend/Model Settings: Custom configuration for specific (backend x modelname) pairs.
• Policy Modes:
  1. Allow, then deny (whitelist with exceptions)
  2. Deny, then allow (blacklist with exceptions)
• Matching: Case-insensitive string matching (including partial matches), with regex support for advanced patterns.

Implementation Approach

Recommended Path: Combine option 1 (reactor-based blocking) with option 2 (definition redaction) for comprehensive control.

Configuration:

• Extend ToolCallReactorConfig in src/core/config/app_config.py with an access_policies list containing:
  • model_pattern: Regex for matching model names
  • agent_pattern: Optional regex for agent matching
  • allowed_patterns: List of regex patterns for allowed tools
  • blocked_patterns: List of regex patterns for blocked tools
  • default_policy: "allow" or "deny"
  • block_message: Custom message for blocked calls
• Mirror in config/schemas/tool_call_reactor_config.schema.yaml and add environment variable overrides.

Shared Evaluator Service:

• Create src/core/services/tool_access_policy_service.py
• Load policies once, compile regexes
• Expose methods: filter_definitions(ChatRequest) and is_allowed(model, agent, tool_name)

Request Filtering:

• Add middleware in RequestProcessor after redaction
• Clone ChatRequest, drop disallowed tool definitions/tool_choice entries
• Stash policy metadata in request.extra_body["tool_access"] for observability

Reactor Enforcement:

• Register ToolAccessControlHandler with high priority after dangerous-command handler in DI
• In handle(), use evaluator to decide; swallow blocked calls and return configured message with metadata

Context Hygiene:

• Ensure ToolCallReactorMiddleware can derive model_name/agent before building ToolCallContext (fallback to context["original_request"].model and response metadata)

Telemetry & UX:

• Log redactions and blocks at info level with policy names
• Increment stats in ToolCallReactorService
• Optionally surface notices to users on first blocks

Use Cases

1. Control behavior of closed-source agents or black-box LLM clients
2. Set global or per-model allowed/disallowed tool lists
3. Prevent specific tools from being used in sensitive workflows
4. Override agent behavior when fine-grained control isn't available

Implementation Ideas

See configuration and service details above. Leverage existing Tool Call Reactor infrastructure.

Testing / Documentation

• Unit tests for evaluator (allowed/blocked/default policies) and request middleware
• Reactor handler tests for swallowing behavior
• Integration tests simulating disallowed tool calls
• Update README with sample policy configurations and precedence rules (allowed overrides blocked, global overrides per-model)
• Run focused tests and full pytest suite post-implementation

After wiring, execute: ./.venv/Scripts/python.exe -m pytest

[matdev83]

This issue has been resolved! The proxy-level tool access control feature has been fully implemented with all requested components:

Implemented Components:

1. ✅ Configuration: Extended ToolCallReactorConfig with �ccess_policies in src/core/config/app_config.py
2. ✅ Service: ToolAccessPolicyService in src/core/services/tool_access_policy_service.py (457 lines)
3. ✅ Request Filtering: Middleware in RequestProcessor for filtering tool definitions
4. ✅ Reactor Enforcement: ToolAccessControlHandler in src/core/services/tool_call_handlers/tool_access_control_handler.py

Additional Implementation Details:

• Comprehensive test coverage with unit and integration tests
• Documentation in docs/tool_access_control.md
• Configuration examples in config/tool_access_control_examples.yaml
• Proper DI registration in src/core/di/services.py
• Telemetry and observability support

The feature provides both proactive filtering (removing disallowed tools from requests) and reactive blocking (stopping disallowed tool calls in responses), exactly as specified in the original issue.