toolgate: decide-only endpoint and tool tags

[cinar]

Two additions to aex-toolgate that keep its approach: declarative policy, deterministic, fail closed, one record per call. Existing behaviour is unchanged and all existing tests pass.

Decide-only: POST /v1/decide/{tool}

Gate.DecideOnly and POST /v1/decide/{tool} rule on a call and record it, but forward nothing and hold nothing.

• The artifact's outcome is decided only: not executed by the gate, so the record never reads as an enforced refusal or execution.
• Only toolcall.requested and toolcall.decided are published.
• Answers 200 with decision, rule, scope, approval, message, outcome, hash, call_id, plus the usual X-Toolgate-* headers.
• Operator-only. A gated agent that can ask "would this pass?" without consequence can search the policy for values that slip through.

Use cases: callers that run tools themselves, such as the VetoBench harness (today it points UPSTREAM_URL at a no-op stub), and measuring a policy in shadow before it enforces.

Tool tags

• tool_tags labels tools with classes, and a rule can name a tag instead of a tool, so one rule governs every tool carrying the tag.

• New rule kind tool fires on the action itself, whatever the arguments, e.g. {"tag": "destructive", "kind": "tool", "effect": "escalate"}. It takes no arg and must be scoped by a tool or a tag.

• Argument rules also work by tag, e.g. a ceiling on every money tool. They keep the fail-closed rule for absent arguments.

• Validation refuses:

  • a tag on a tool missing from tool_scopes;
  • a rule on a tag no tool carries;
  • a rule setting both tool and tag;
  • a tool rule with an arg, or with neither a tool nor a tag.

  Each would otherwise leave a tool silently ungoverned or make a rule fire everywhere.

Motivation: VetoBench's Agent-SafetyBench run spans 1,627 tools. Per-tool rules don't scale, but classes ("destructive", "money", "external send") do.

Tests

• decide_test.go: the twelve calls through /v1/decide reach the same decisions as /v1/tools, nothing is forwarded, the escalated call leaves no hold, and the chain verifies with 12 records. Without the operator token: 401 and no record.
• tags_test.go: tag scoping (a tool rule on a tag, a ceiling on a tag, the absent-argument case), each validation error, and a tool rule by name.

A question, not changed here

The Rule comment says an empty tool "applies it to every tool that carries the argument", but evaluate fails closed when the argument is absent. So a rule without a tool denies every tool that lacks the argument: an amount ceiling with no tool denies list_invoices. Safe, but it makes tool-less rules unusable. Should the code or the comment change? Tags cover the use case either way.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Ptdu2pZMVdE5x6XkwcUDjj