| name | gatekeeper |
|---|---|
| description | Rule-driven decision gates for anything that needs a verdict before it proceeds: agent selection, routing, triage, approvals. Each gate is a YAML rulebook: deterministic hard rules decide what code can decide, Jev (TypeSafe System One) answers the semantic questions as typed Choice, Noul, or Score judgments, and confidence bands turn answers into allow, route, suggest, confirm, escalate, or block. Rosters come from installed Claude Code agents and skills or from a JSON index, with rollup by group. Runs as Claude Code hooks in shadow, advise, or enforce mode (ships in shadow). Use for "/gatekeeper", "gatekeeper", "which agent should handle this", "why was that blocked", "tune the gate", "bench the gate", "write a new gate", "add a rule", "is the gate healthy", or "gatekeeper doctor". |
| argument-hint | doctor | judge | explain | roster | lint | bench | log | mode | new-gate |
Gatekeeper
Repo: this skill's folder (installed as a symlink at ~/.claude/skills/gatekeeper).
CLI: python3 ~/.claude/skills/gatekeeper/bin/gatekeeper <command>, or bin/gatekeeper from the repo.
A gate name resolves to gates/local/<gate>.yaml (private, git-ignored) first,
then gates/<gate>.yaml, then examples/<gate>/<gate>.yaml. A path to a YAML
file works anywhere a gate name does, except log --gate, which takes the gate's gate: name.
event -> hard_rules (code) -> judgments (one Jev request) -> decide (first match) -> verdict + log
Commands
| Ask | Run |
|---|---|
| What would the gate decide? | bin/gatekeeper judge <gate> "<text>" [--project P] [--json] |
| Why did it decide that? | bin/gatekeeper explain <gate> "<text>" |
| Which handlers can it pick? | bin/gatekeeper roster <gate> [--all] |
| Is the rulebook sound? | bin/gatekeeper lint <gate> |
| How good are the thresholds? | bin/gatekeeper bench <gate> [--file F] (live; about $0.00006 per row on a 24-handler roster, $0.0004 at 143) |
| What happened recently? | bin/gatekeeper log [--tail N] |
| Turn enforcement on or off | bin/gatekeeper mode <gate> shadow|advise|enforce|off |
| Is it still working? | bin/gatekeeper doctor [gate] [--offline] [--json] [--days N] [--project P] (exit 1 on any FAIL) |
judge, explain, and bench call Jev and need TYPESAFE_API_KEY. The
client reads it from the environment, then the file named by
GATEKEEPER_ENV_FILE, then ~/.config/gatekeeper/env. Never print it.
Editing a rulebook (gates/<gate>.yaml)
- Read the rulebook and
gates/_schema.jsonfirst. - Put anything a regex or comparison can decide in
hard_rules. Put only the semantic part injudgments. - One narrow question per judgment. A Choice needs an escape option when nothing may fit.
- Bands are per judgment and follow the cost of a wrong call. They stay
untuned guesses until
benchover reviewed labels says otherwise. - Bump
versionwhenever a rule, band, or option changes, so the log shows which rulebook made each decision. - Run
bin/gatekeeper lint <gate>andpython3 -m pytest -qbefore reporting done.
New gate
Copy the shape of gates/agent-selection.yaml: state.fields names the event
fields Jev sees, judgments holds the questions, and decide maps answers to
verdicts. A new domain (for example email triage) needs a new YAML file plus
whatever adapter turns its input into an event dict. The engine does not change.
Rosters from an index
A gate can route to Markdown procedures instead of Claude Code agents: set
roster.sources: [index] and point roster.index.file at a JSON list (fields
for name, description, group, and path are configurable). Add rollup: group
to the Choice and the engine also sums probabilities by group, so a decide rule
can use group_band: act when the exact handler is unclear but its group is
not. See examples/marketing-team/. Such gates run in advise mode.
Enforcement (agent-selection)
The hooks are installed with scripts/install_hooks.py (--global or
--project, dry run by default). shadow only logs what it would inject or
deny. advise injects the verdict as context but never blocks or denies. enforce injects the
route as context and denies Agent or Skill calls that break an act-band route
or a forbid rule. GATEKEEPER=off disables every hook at once. The hooks
fail open: a Jev outage never blocks work. A handler named in the prompt is
never denied. Harness messages (passthrough) are never judged. See README
"Safety rules".
Keep it working
The gate fails open, so a broken gate looks exactly like a quiet one. Run
bin/gatekeeper doctor monthly, after installing or removing agents or skills,
after a Claude Code update, and always before mode ... enforce. It checks the
key, that the pinned model still answers, what jev-latest now serves, hook
installs, the fail-open rate in the log, harness messages that slipped past
passthrough, handlers no rule covers, and whether the bench is stale.
- FAIL: fix before anything else. The gate is not judging.
- WARN: fix soon. Each line carries its own
fix:. - INFO: a choice for the user (for example a newer Jev version to bench).
- Never move
model:or a band without a fresh bench on the new setting.
Rules
- Gatekeeper decides who handles work. It never sends, publishes, or spends.
- Typed output guarantees the shape, not the truth. Tune on labelled data.
- Only a hand-reviewed bench can move a threshold. Draft labels
(
label_source: claude-draft) are a starting point. - Re-check the Jev model, limits, and price against
GET https://api.typesafe.ai/v1/modelsand docs.typesafe.ai before relying on them.