Tool Call Safety Validator

A TypeScript library that validates AI agent tool calls using external checker programs before execution. The library runs external programs to validate tool calls and returns whether they should be allowed or blocked.

Requirements

External Checker Protocol

External checkers are executable programs that:

• Receive tool call details via stdin as JSON
• Output validation decision via stdout as JSON with format: {"decision": "allow" | "block", "reason": "..."}
• Return exit code 0 for success, non-zero for errors
• Have a configurable timeout (default: 5 seconds)

Validation Pipeline

The validation pipeline should:

• Accept tool call details (tool name, parameters)
• Run configured checker programs in sequence
• If any checker returns "block", stop and return blocked result
• If all checkers return "allow", return allowed result
• If a checker times out or errors, treat as "allow" (fail-open)

Test Cases

• When a checker program returns {"decision": "block", "reason": "sensitive file"}, the validation result decision is "block" @test
• When all checker programs return {"decision": "allow"}, the validation result decision is "allow" @test
• When a checker times out after the configured timeout period, the validation continues and does not block the tool call @test

Implementation

@generates

API

/**
 * Configuration for an external safety checker
 */
interface CheckerConfig {
  name: string;
  path: string;
  timeout: number;
}

/**
 * Tool invocation details
 */
interface ToolInvocation {
  toolName: string;
  params: any;
}

/**
 * Validation result
 */
interface ValidationResult {
  decision: 'allow' | 'block';
  reason?: string;
  blockedBy?: string; // Name of checker that blocked
}

/**
 * Main validation pipeline class
 */
export class ValidationPipeline {
  constructor(checkers: CheckerConfig[]);

  /**
   * Validate a tool invocation using all configured checkers
   */
  validate(invocation: ToolInvocation): Promise<ValidationResult>;
}

Dependencies { .dependencies }

@google/gemini-cli-core { .dependency }

Provides the tool system types and interfaces for AI agent tool execution.