feat: add client-side tool guard

Merged
RA
2mo ago
+479-5

Summary by cubic

Adds a configurable client-side guard that evaluates every call_tool invocation before tool lookup, discovery, or transport dispatch, so non-allowed calls never reach a native transport.

  • Supports allow, deny, review, and error verdicts; only allow dispatches, exactly once.
  • A review verdict requires an approve(call, review_verdict) method that must return allow, otherwise the call fails without dispatching.
  • bypass_tools allowlist skips guard evaluation for intentionally safe, client-owned tools.
  • Invalid verdicts, evaluator crashes, and approval failures fail closed with structured guard_* errors including the tool name, args, and verdict.
  • The guard can be a function or a table with evaluate(call); existing clients without a guard config are unaffected.

Docs and examples

  • Adds a guard example, README sections, Makefile target, and rockspec/init registration for utcp.guard.
  • Adds tests covering deny, review, error, bypass, approval, and evaluator-crash paths.