Hooks

The few rules that a script checks, not just the agent.

A hook is a small script your agent tool runs at a fixed moment, such as before a shell command. A hook reads the command, not the conversation. That makes it hard to skip, and also limits what it can see. swe ships 6 hooks, and the base floor adds 1 more.

How install offers them

/kerby install shows every hook in a table, then asks: all, choose, or none. Each hook has a tier.

Tier	Hooks	What it means
locked	2	Comes with any hook install. You cannot skip it on its own — only by choosing none.
recommended	2	Blocks an action. You can skip it, and /kerby status keeps telling you it is not enforcing.
optional	3	Only warns. You can skip it.

A hook works only after install and only where your tool runs it. Claude Code runs them. Codex does not. Use status to see which hooks are really enforcing, and hooks to see what install would add, without changing anything.

In your agent:

/kerby install
/kerby status
/kerby hooks

Check what is really enforcing

swe declares how each check is enforced. A hook-backed check is really enforced only while its hook is installed. /kerby status shows both for every check: what swe declares, and what is in force now.

In your agent:

/kerby status

format · copied from SKILL.md

kerby: loaded. Detected <id list> markers in current context.
<id> — <kind> — declared: <enforcement> — effective: <enforcement>

A check whose hook is not installed shows “not registered (behavioral only)”. The rule still applies, but only as instructions.

Every hook

Secrets in staged changes (from base)pre-commit-check.sh

Runs: Before a shell command runs — from the base floor, under every rulebook
Result: Blocks the action · tier locked
Checks: secrets-staged
What it does: Scans what you are about to commit for secrets such as API keys and tokens. It uses gitleaks or betterleaks when installed, and a smaller built-in pattern list when not. This hook belongs to the base floor, so every rulebook has it.
What it misses: It reads the commit command before it runs. git add x && git commit in one command is not fully seen. The optional git pre-commit hook covers that case.
Turn it off: No variable turns it off. It is a security floor; the only way to stop it is to remove it from your settings file.

Destructive git and protected branchesprotect-git.sh

Runs: Before a shell command runs
Result: Blocks the action · tier locked
Checks: destructive-git protected-branch-commit
What it does: Stops git commands that can lose work: force push, push to a protected branch, reset --hard, clean -f, branch -D, and checkout . or restore . that throw away all local changes. It also stops a commit while you are on a protected branch.
What it misses: It reads the command as text, so a command that only mentions these words can be blocked too. That is on purpose: blocking too much is the safe side. Some indirect forms are not seen, such as a path held in a variable.
Turn it off: The data-loss blocks cannot be turned off by a variable. You run those commands yourself in a terminal. For one commit you approved on a protected branch, the agent may use CODING_RULES_ALLOW_PROTECTED_COMMIT=1 in front of that one git commit.

Existing .env filesprotect-env.sh

Runs: Before a file is written or edited
Result: Blocks the action · tier recommended
Checks: protect-env
What it does: Stops the agent from editing or overwriting an existing .env file. git cannot restore a real .env, because it is not tracked. The agent gives you the variable names to add yourself. Template files such as .env.example are allowed.
What it misses: It watches the Edit and Write tools. A shell command that writes to .env directly is not seen.
Turn it off: No variable turns it off. Decline it at install, or remove it from your settings file on purpose.

Version numbers in STATUS.mdstatus-provenance-check.sh

Runs: Before a shell command runs
Result: Blocks the action · tier recommended
Checks: status-provenance
What it does: Stops a commit when .kerby/STATUS.md states a version, a commit SHA, or a PR or issue number. STATUS.md says where the work stands. Git and the log already record what happened.
What it misses: It reads the commit command as text, and it checks the repo you are in. A wrapper such as env or bash -c, a git alias, or a commit in another repo named with -C or cd is not seen. The git pre-commit hook covers those. If its guard script is missing, it lets the commit through and says so.
Turn it off: No variable turns it off. Decline it at install. Its part in the git pre-commit hook goes only if you decline that whole hook.

Reading .env fileswarn-env-read.sh

Runs: Before a file is read
Result: Warns only, never blocks · tier optional
Checks: env-read-warning
What it does: When the agent reads a .env file, it reminds the agent never to print the secret values.
What it misses: It watches the Read tool only. cat .env in a shell is not seen.
Turn it off: CODING_RULES_HOOK_DISABLED=warn-env-read

High-stakes filesroute-high-stakes.sh

Runs: Before a file is written or edited
Result: Warns only, never blocks · tier optional
Checks: high-stakes-routing
What it does: When the agent edits a high-stakes file — migrations, auth, payments, infrastructure, CI — it reminds the agent that this change needs the full feature or bugfix workflow, not quick-task.
What it misses: Values that shape production traffic, such as timeouts or rate limits, have no file pattern. That category stays the agent’s judgment.
Turn it off: CODING_RULES_HOOK_DISABLED=route-high-stakes

Hollow tests and gate reminderhollow-test-check.sh

Runs: Before a shell command runs
Result: Warns only, never blocks · tier optional
Checks: hollow-test-heuristic
What it does: At commit time, it counts focused or skipped tests (.only, .skip) and always-true assertions in the staged test lines, and reminds the agent to run lint, tests and build. It never stops the commit.
What it misses: It cannot see fakes that only show up when tests run, such as a test run that matched zero tests.
Turn it off: CODING_RULES_HOOK_DISABLED=hollow-test-check

The git pre-commit hook

The secret scan above runs before the agent’s commit command, so it reads the command text. It cannot see git add x && git commit in one command, an alias, or a path in a variable.

/kerby install also offers a git pre-commit hook. git hands that hook the real staged files, so those cases are covered. It runs these checks:

Secrets in staged changes (from base)
Version numbers in STATUS.md

One answer at install covers all of them, so a check you declined earlier still runs here. The hook lives in your clone only — git never shares hooks with teammates — and git commit --no-verify skips it for one commit.

Hooks run at the tool call. Some rules live in the conversation, where no hook can look:

These rules are instructions only. When the hooks are not installed, every rule is. Themap on the overview shows the difference.