gatetrap: harmless trap tests for AI-agent approval gates

Problem

AI agents are often set up to ask a person before a risky action, but almost nobody tests whether that step holds. An approval can be reused, the details can change after a person said yes, an old approval can still work days later, and on some platforms a safety check that crashes or times out lets the action through. These failures are silent: nothing looks wrong until the action has already happened.

Goal

A small, free kit that anyone can run against their own approval gate to see, case by case, which known failures get through, judged by what actually ran rather than by what the gate says about itself.

My role

Sole author: research, design, implementation, tests and documentation.

Solution

A trap tool server that any AI agent can connect to, whose tools look like real actions (read, change or delete a record, send a payment) but only write a harmless marker when they run. A runner plays ten numbered failure cases against the gate under test and counts the markers, so the count decides pass or fail. Connectors drive a Claude Code safety hook exactly as Claude Code documents it, or any other gate through a simple one-line-per-step protocol.

How it works

The trap server speaks the Model Context Protocol, the standard way AI agents reach tools, with no third-party code. Every tool call appends one line to a test file and does nothing else.

For each case the runner creates a fresh folder, starts a fresh trap server and a fresh connection to the gate, then plays the steps: a person approves, withdraws or waits, and the agent tries an action, sometimes twice at the same moment.

When the gate lets an action through, the runner calls the real trap tool. Afterwards it counts the markers that belong to that case and compares the count with what the case expects.

The ten cases cover an action with no approval, an exact approval used once, reuse, changed details, expiry, withdrawal, simultaneous retries, a gate that crashes on unexpected input, a safety rule that silently matches no tool, and an approval for one action used for another. Each case cites the public report or official documentation it comes from.

One case is a control: if a gate blocks everything, its other passes are marked inconclusive, because blocking everything would otherwise look perfect.

Every report ends with what a pass does not mean.

Technical challenges

Reproducing Claude Code's documented hook rules exactly, including that a hook which exits with an unexpected code or times out does not block the action.

Applying Claude Code's rules for which tools a safety rule covers, where a name without a pattern matches nothing at all.

Testing two identical retries arriving at the same moment, where a check-then-use gate can let both through.

Judging by observed effects instead of trusting the gate's own answer.

Keeping the kit free of dependencies so anyone can read and trust it.

Capabilities

Trap tool server any agent can call
Ten numbered failure cases with cited sources
Pass or fail decided by what actually ran
Claude Code hook connector following the documented rules
Generic connector for any approval gate
Safety-rule coverage check
Control case that exposes block-everything gates
Plain-text and JSON reports

Technology

Impact

Public and free to run, with ten tests of its own. A strict example gate passes every case and a deliberately naive one fails nine of ten, each failure matching a mistake built into it. In a live Claude Code session the kit's results matched the real client: the strict gate blocked an unapproved delete, an exactly approved payment ran once, and a safety check that crashed let a delete run anyway, which is the documented behaviour one case tests for.

Skills demonstrated

AI agent safety and approval design
Test design from real failure reports
Model Context Protocol servers
Claude Code hooks
Testing retries and simultaneous requests
Open-source maintenance