GateGuard

Community work. Credit the original author and project in every copy or fork.

GateGuard is a PreToolUse hook. It blocks an action until the agent checks key facts.

The gate follows three steps:

1. DENY: Block the first action.
2. FORCE: List the facts the agent must find.
3. ALLOW: Let the agent retry after it shows those facts.

The gate must ask for facts. Do not ask, "Are you sure?" A yes or no answer does not prove that the agent checked the project.

When to Use

Use GateGuard when:

• One file may affect many other files.
• Data has a set shape or date style.
• New code must match old code.
• A command may delete or replace work.
• The agent may guess instead of checking.

Gate Rules

Track gate state by session, action type, and file path.

• Gate the first edit to each file.
• Gate each file in a batch edit.
• Gate the first routine shell command in a session.
• Gate every risky shell command.
• Gate a retry again if its target or command has changed.
• Do not mark a gate as passed until all facts are shown.
• Do not treat a plan or a promise as proof.
• Do not run outside tools or make web calls for a gate.
• Do not show secret values or private user data.

Read-only checks may run before the gate passes. These include file reads, file lists, code search, and safe status checks.

Edit Gate

Before editing a file, require:

Before editing {file_path}, show these facts:

1. List every file that imports, loads, or calls this file.
2. List the public functions, classes, routes, or data fields that may change.
3. If this file reads or writes data, show the field names, shape, and date style.
   Use fake or hidden values. Do not show real private data.
4. Quote the user's current request word for word.

Search the full project when safe. Skip folders such as .git/, .venv/, node_modules/, build output, and saved vendor code unless they are part of the task.

If no file uses the target, show the search used and say that no use was found.

For a batch edit, check every file before any file in the batch is changed. If the tool cannot gate each file on its own, block the whole batch and list all target files.

Treat a rename or move as both an edit and a new path. Check old users and new users.

New File Gate

Before creating a file, require:

Before creating {file_path}, show these facts:

1. Name the files and lines that will use this new file.
2. Search for an old file that may already do the same job.
3. If this file will read or write data, show the field names, shape, and date style.
   Use fake or hidden values. Do not show real private data.
4. Quote the user's current request word for word.

If the new file is a test, config file, or tool entry file, name the test runner or tool that will load it.

If no caller exists yet, name the file that will be changed to add the caller. If the file is meant for direct use, state how the user will run it.

Do not gate files made by a known build tool unless the user plans to edit those files by hand.

Risky Shell Gate

Gate every command that may delete data, lose work, replace history, or change a live system.

Examples include:

• rm -rf
• git reset --hard
• git clean
• git push --force
• DROP TABLE
• Commands that erase, replace, or send live data

Require:

Before running this command, show these facts:

1. List each file, folder, record, branch, or service it may change or delete.
2. Give a one-line way to undo the change.
3. Quote the user's current request word for word.

If the action cannot be undone, say so in plain words. Do not make up an undo step.

If a command uses a wildcard, link, variable, or short path, resolve the real targets first. Block it if the target is still not clear.

A safe test run does not pass the gate for the real command. Gate the real command too.

Routine Shell Gate

Gate only the first safe shell command in a session.

Require:

1. State the user's current request in one sentence.
2. State what this command will check or make.

Do not gate each later safe command unless its goal changes in a major way.

Example

User request:

Add a display name to user profiles.

First edit attempt:

Edit src/profile.py

Gate response:

DENY

Before editing src/profile.py, show these facts:

1. List every file that imports, loads, or calls this file.
2. List the public functions, classes, routes, or data fields that may change.
3. Show the profile data shape and date style with fake values.
4. Quote the user's current request word for word.

A valid fact report may look like this:

1. src/api/users.py imports Profile.
   tests/test_profile.py imports build_profile.
2. Profile, build_profile, and the /users/{id} reply may change.
3. Shape: {id, display_name, created_at}
   Date style: "2026/05/12 09:30"
   The value is fake.
4. "Add a display name to user profiles."

The next matching edit may pass. A later edit to another file must pass its own file gate.

Setup

Included Hook

Use scripts/hooks/gateguard-fact-force.js from this plugin. Turn it on in hooks.json.

If GateGuard blocks its own setup or repair, start that session with:

ECC_GATEGUARD=off

Use ECC_DISABLED_HOOKS when you only need to turn off the GateGuard hook. Use the hook ID set by the plugin.

Turn the gate back on after setup.

Python Package

pip install gateguard-ai
gateguard init

This creates .gateguard.yml. Use it to set gate types, ignore paths, and custom fact prompts.

Good Defaults

Ignore files that should not be checked by hand:

ignore_paths:
  - .git/
  - .venv/
  - node_modules/
  - dist/
  - build/

Do not ignore source code, tests, data rules, or live config just to make the gate quiet.

Keep gate text short and exact. Add project rules only when they help the agent find a real fact.

Common Mistakes

• Do not replace fact checks with "Are you sure?"
• Do not accept a guess as a search result.
• Do not skip data shape or date checks.
• Do not show real secrets or private records.
• Do not gate every safe shell command.
• Do not reuse a passed gate for a new file or changed command.
• Do not allow a risky command when its target is not clear.
• Do not block read-only checks needed to answer the gate.

Evidence

Two tests compared the same tasks with and without the gate:

In these tests, both versions ran and passed tests. The gated work had better design depth. Treat these results as small tests, not a promise for every project.

Related Skills

• safety-guard: Checks safety while code runs.
• code-reviewer: Reviews work after edits.