Custom Handlers
Each handler is a Rust function called by the gate when declarative TOML can't express the rule. The TOML declares [[custom_handlers]] with a program and handler name; the gate's Rust file implements the handler. Listed by gate.
filesystem
Path-aware logic.
| Program | Handler | What it does |
|---|---|---|
rm | check_rm | Normalises paths (// → /, /. → /); blocks destructive targets (/, ~/); flags traversal patterns (.., ../, bare *) with ask-and-warn. |
tar | check_tar | Decodes combined flags (-tvf, -xf, -cf); allows list mode, asks for extract/create. |
network
Method and flag dispatch.
| Program | Handler | What it does |
|---|---|---|
curl | check_curl | Detects HTTP method from -X/--request, presence of -d/--data, and download flags -o/-O. Routes GET to allow, mutations and downloads to ask. Also asks on GitHub content URLs (hint nudges toward gh api). |
nc | check_netcat | Hard-blocks -e (reverse shell); asks on -l (listen mode); applies the same rules to ncat and netcat aliases. |
wget | check_wget | Allows --spider (URL-resolves only); asks on downloads, recursive modes, post bodies. |
http / xh | check_httpie | Allows GET (URL-only or GET verb); asks on POST / PUT / DELETE / PATCH. |
rsync | check_rsync | Allows --dry-run / -n; asks on actual syncs (with --delete noted in the reason). |
cloud
Multi-word subcommand patterns.
| Program | Handler | What it does |
|---|---|---|
gcloud | check_gcloud | Three-word subcommand routing (gcloud compute instances create). Allows list / describe / get actions; asks on create / delete / update / deploy. |
docker | check_docker | Handles docker compose with flags between the subcommand (e.g. docker compose -f x.yml config). |
system
SQL parsing, prefix matching.
| Program | Handler | What it does |
|---|---|---|
sudo | check_sudo | Extracts the underlying command and asks with a descriptive reason naming the inner program. -l / -v / -k allow without execution. |
systemctl | check_systemctl | Checks for read-only ops (status, list-units, is-active, etc.) before falling back to declarative rules. |
apt / dnf / brew | check_apt, check_dnf, check_brew | Each package manager has its own handler that checks read-only subcommands (search, list, show, info) before falling back to declarative rules. |
pacman | check_pacman | Prefix matching on -S (sync), -R (remove), -U (upgrade), -D (database). |
make | check_make | Allows known-safe targets (test, check, lint, build, clean, format); asks for unknown targets with the target name in the reason. |
psql / mysql | check_psql, check_mysql | Parses -c / -e query strings; allows SELECT / SHOW / \d; asks on INSERT / UPDATE / DELETE. -f always asks (file content unknown). |
kill / pkill | check_kill, check_pkill | Allows -0 (process-exists check) and -l / -L (list signals). Anything else asks. |
crontab | check_crontab | Allows -l (list scheduled tasks); asks on edit or write operations. |
basics, package_managers, others
Inner-command checking, wrapper resolution.
| Program | Handler | What it does |
|---|---|---|
xargs | check_xargs | Allows only when the target command is itself in safe_commands; otherwise asks. Also handles xargs sh -c '…' by parsing the inner script. |
bash / sh / zsh | check_shell_c | Parses -c '…' arguments and runs each inner command through the gate engine. |
command | check_command_builtin | Allows command -v / -V (lookup only). Evaluates other invocations through the gate engine as transparent wrappers. |
sd | check_sd | Without file args, sd is a stdin→stdout pipe (safe). With file args, it modifies in place (ask). |
npm / pnpm / yarn / bun | check_npm, etc. | Handles devtool delegation (npm eslint, pnpm biome) by routing to the devtools gate. Bare yarn resolves to yarn install. |
uv / poetry / pipx / mise | check_uv, etc. | Routes uv run <tool> / poetry run <tool> / mise exec <tool> through the devtools gate. Mise task expansion adds another layer. |
git | extract_subcommand, check_git_add | Strips global flags (-C, --git-dir, -c) to find the real subcommand. check_git_add handles git add -A / --all / . / wildcard with extra care. |
short | check_short_api | For short api: allows GET, asks POST / PUT / PATCH / DELETE. |
The generated gate function returns Skip for any program with a custom handler. The Rust wrapper file then takes over. Without that wiring the handler never fires; see the Contributing page for the pattern.