
ai-tool-use-validator
AI-powered tool use validation using LLM backends (Vertex AI, etc.) to evaluate command safety and correctness
- version
- 0.2.0
- GitHub stars
- 14
Install
/plugin install ai-tool-use-validator@fprochazka-claude-code-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add fprochazka/claude-code-plugins.
Contents
Discovered from sourceAgents 1
ai-tool-use-validator
AI-powered tool use validation for Claude Code using LLM backends (Vertex AI, etc.) to evaluate command safety and correctness.
What it does
Uses a PermissionRequest hook to intercept Bash commands before they execute and evaluates them with an LLM backend:
- Allow - Safe commands within the working directory or
/tmpare auto-approved - Deny with correction - Safe but suboptimal commands are blocked with feedback so Claude generates better commands
- Ask user - Potentially unsafe commands pass through to the user for manual approval
Other tools (Write, Edit, Read, etc.) are not validated and pass through to the user directly. This is intentional to avoid interfering with Claude's built-in permission modes.
Requirements
- Python 3.11+
- pipx (for installing the validator binary)
- Google Cloud SDK with Vertex AI access (for Vertex AI backend)
Installation
1. Add the marketplace and install the plugin
claude plugin marketplace add fprochazka/claude-code-plugins --scope user
claude plugin install ai-tool-use-validator@fprochazka-claude-code-plugins --scope user
2. Install the validator binary
The plugin requires a Python CLI tool. Clone the repo and install with pipx:
git clone https://github.com/fprochazka/claude-code-plugins.git
pipx install ./claude-code-plugins/plugins/ai-tool-use-validator
3. Configure GCP authentication
gcloud auth application-default login
4. Create config file
mkdir -p ~/.config/claude-code-tool-use-validator
cat > ~/.config/claude-code-tool-use-validator/config.toml << 'EOF'
project_id = "your-gcp-project-id"
region = "europe-west1"
model = "claude-opus-4-5@20251101"
EOF
5. Verify the configuration
claude-code-tool-use-validator --verify
This will test the API connection and display the response.
Example
Once installed, the validator evaluates tool calls automatically:
● Bash(npm test 2>&1 | tail -n 50)
⎿ Error: Don't truncate test output with `| tail` - if you need to see
more context later, you'd have to re-run the entire test suite.
⎿ Denied by PermissionRequest hook
● Bash(rm -rf node_modules)
⎿ (No content)
⎿ Allowed by PermissionRequest hook
Configuration
The config file is located at ~/.config/claude-code-tool-use-validator/config.toml.
| Option | Required | Default | Description |
|---|---|---|---|
project_id | Yes | - | Your GCP project ID with Vertex AI access |
region | No | global | Vertex AI region (global, us-east5, europe-west1, etc.) |
model | No | claude-opus-4-5@20251101 | Model to use for validation |
Example model IDs
Check Google Cloud documentation for available models in your project.
| Model | Example Model ID |
|---|---|
| Claude Opus 4.5 | claude-opus-4-5@20251101 |
| Claude Sonnet 4.5 | claude-sonnet-4-5@20250929 |
| Claude Haiku 3 | claude-3-haiku@20240307 |
Troubleshooting
If you get a 404 error:
- Try
region = "us-east5"instead of"global" - Verify the model is available in your project
- Run
gcloud auth application-default set-quota-project YOUR_PROJECT_ID
How it works
The plugin uses a PermissionRequest hook that invokes the claude-code-tool-use-validator binary for Bash tool calls. Other tools (Read, Write, Edit, etc.) are passed through to the user immediately - the validator intentionally does not auto-approve these to avoid interfering with Claude's built-in permission modes.
Permission dialog interaction
When a tool call triggers the hook:
- Permission dialog appears immediately - The user sees the normal approval prompt right away
- Hook runs in parallel - The validator evaluates the command while the dialog is visible
- User can respond first - If you approve/deny before the hook finishes, your choice takes precedence
- Hook can auto-decide - If the hook finishes before you respond, it can auto-approve safe commands or deny with feedback
This means you'll briefly see permission dialogs even for safe commands, but they'll disappear automatically once the validator approves them.
Validation logic
The validator:
- Receives the tool name, input parameters, and current working directory via stdin (JSON)
- Reads the session transcript for context (last user prompt, recent operations)
- Sends the context to an LLM backend for evaluation
- Returns one of three decisions:
allow- Auto-approve the tool usedenywith message - Block and provide feedback to Claudeaskor no output - Show the normal permission dialog to the user
All decisions are logged to syslog. Monitor with:
tail -f /var/log/syslog | grep claude-code-tool-validator
CLI Usage
# Verify API configuration
claude-code-tool-use-validator --verify
# Normal mode (reads JSON from stdin, used by the hook)
echo '{"tool_name": "Bash", "tool_input": {"command": "ls -la"}, "cwd": "/tmp"}' | claude-code-tool-use-validator
Supported backends
- Vertex AI (Claude via Google Cloud)
- OpenAI API
- Local models (Ollama)
Development
Testing locally
# Clone the repository
git clone https://github.com/fprochazka/claude-code-plugins.git
cd claude-code-plugins
# Install in development mode (editable)
pipx install -e ./plugins/ai-tool-use-validator
# Run Claude with the plugin loaded locally
claude --plugin-dir ./plugins/ai-tool-use-validator
# Watch syslog for decisions
tail -f /var/log/syslog | grep claude-code-tool-validator
Reinstalling after changes
pipx install -e -f ./plugins/ai-tool-use-validator
Author
Filip Procházka
License
MIT
Hooks 1
Sponsors
Details
- Marketplace
- fprochazka/claude-code-plugins
- Source
- plugins/ai-tool-use-validator
- Author
- Filip Procházka
- Category
- Security
More from fprochazka/claude-code-plugins
All 25- code-reviewv1.17.5
- diagramsv0.1.2
- gemini-cliv1.2.2
- gemini-deep-researchv1.0.0
- gitv0.3.3
- glabv1.3.5
- glab-mrv1.7.3
- gogcliv0.1.5
- llm-totov0.1.0
- markitdownv1.0.0
- metabasecliv1.0.3
- migrate-to-uvv1.2.0
- noisy-tools-in-subagentv0.7.1
- prosev0.3.2
- rabbitmqadminv0.2.1
- researchv0.1.2
- sdlcv0.23.3
- searxngcliv0.3.2
- skill-keyword-reminderv1.2.1
- slackcliv2.0.7
- teamworkv0.2.1
- use-libsrc-mcpv0.1.0
- web-researcherv1.1.1
- agent-rolesv0.8.3