GateGuard — Fact-Forcing Pre-Action Gate

A PreToolUse hook that forces Claude to investigate before editing. Instead of self-evaluation ("are you sure?"), it demands concrete facts. The act of investigation creates awareness that self-evaluation never did.

When to Activate

• Working on any codebase where file edits affect multiple modules
• Projects with data files that have specific schemas or date formats
• Teams where AI-generated code must match existing patterns
• Any workflow where Claude tends to guess instead of investigating

Core Concept

LLM self-evaluation doesn't work. Ask "did you violate any policies?" and the answer is always "no." This is verified experimentally.

But asking "list every file that imports this module" forces the LLM to run Grep and Read. The investigation itself creates context that changes the output.

Three-stage gate:

1. DENY  — block the first Edit/Write/Bash attempt
2. FORCE — tell the model exactly which facts to gather
3. ALLOW — permit retry after facts are presented

No competitor does all three. Most stop at deny.

Evidence

Two independent A/B tests, identical agents, same task:

Task	Gated	Ungated	Gap
Analytics module	8.0/10	6.5/10	+1.5
Webhook validator	10.0/10	7.0/10	+3.0
Average	9.0	6.75	+2.25

Both agents produce code that runs and passes tests. The difference is design depth.

Gate Types

Edit / MultiEdit Gate (first edit per file)

MultiEdit is handled identically — each file in the batch is gated individually.

Before editing {file_path}, present these facts:

1. List ALL files that import/require this file (search the tree — Glob/Grep, or find/grep via Bash)
2. List the public functions/classes affected by this change
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

Write Gate (first new file creation)

Before creating {file_path}, present these facts:

1. Name the file(s) and line(s) that will call this new file
2. Confirm no existing file serves the same purpose (search the tree — Glob/Grep, or find/grep via Bash)
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

Destructive Bash Gate (every destructive command)

Triggers on: rm -rf, git reset --hard, git push --force, drop table, etc.

1. List all files/data this command will modify or delete
2. Write a one-line rollback procedure
3. Quote the user's current instruction verbatim

Routine Bash Gate (once per session)

1. The current user request in one sentence
2. What this specific command verifies or produces

Parallel Batches and Partial Application

The first-touch gate evaluates each tool call independently. When several edits to a file that has not been touched yet are sent in one parallel batch, the first call is denied and the denial marks the file as checked, so the sibling edits in that batch are applied. Nothing is rolled back: the file can end up holding the sibling edits without the denied one.

The denial message names the file and warns that batch siblings may already have been applied. Treat it literally:

• Send dependent edits to a not-yet-touched file sequentially, not in a parallel batch. A definition and its first use, or an import and its call site, must not ride in the same batch.
• After a first-touch denial, present the facts, retry the denied edit, and re-read the file before building on anything else from the batch.

A batch-wide lock is not possible: hooks see tool calls one at a time, so the gate cannot know which calls arrived together.

Quick Start

Option A: Use the ECC hook (zero install)

The hook at scripts/hooks/gateguard-fact-force.js is included in this plugin. Enable it via hooks.json.

If GateGuard blocks setup or repair work, start the session with ECC_GATEGUARD=off. For hook-level control, keep using ECC_DISABLED_HOOKS with the GateGuard hook ID.

In long sessions, only the first GATEGUARD_FACT_FORCE_FULL_DENIALS fact-force denials (default 3) emit the full four-fact block; later denials are condensed to a single line carrying the denial ordinal, so near-identical blocks cannot accumulate in the context window and amplify model repetition loops (#2142). Retrying the same file or command after presenting facts never re-triggers the gate.

Graduated controls

ECC_GATEGUARD=off (or GATEGUARD_DISABLED=1) turns the gate off entirely. The variables in this table do not — each narrows one behaviour while the load-bearing destructive-Bash checks keep running:

Variable	Default	Effect
GATEGUARD_BASH_ROUTINE_DISABLED	unset (gate on)	Disables the routine-Bash gate only. The destructive-Bash gate (rm -rf, git reset --hard, drop table, dd if=, …) is unaffected.
GATEGUARD_EXEMPT_GLOBS	unset (no exemptions)	Comma-separated globs; a matching Edit/Write/MultiEdit target skips first-touch fact-forcing. Intended for low-import-value trees (tests, generated artifacts, scratch dirs) where "who imports this / what schema" carries no signal.
GATEGUARD_FACT_FORCE_FULL_DENIALS	3	How many denials emit the full four-fact block before later ones condense to a single line. 0 condenses from the very first denial.
GATEGUARD_BASH_EXTRA_DESTRUCTIVE	unset	Extra destructive-command patterns, as regex source, added to the built-in set. A malformed regex is treated as unset (built-ins still apply) and logged once to stderr.
GATEGUARD_STATE_DIR	~/.gateguard	Where per-session gate state is kept. If state cannot be persisted the gate allows the operation rather than looping, and names this variable in the warning.

GATEGUARD_BASH_ROUTINE_DISABLED accepts 1, true, on, enabled, enable, or yes (case- and whitespace-insensitive); any other value leaves the gate on.

Turning the gate off completely

Variable	Effect
ECC_GATEGUARD=off	Disables GateGuard for the session. Accepts 0, false, off, disabled, or disable.
GATEGUARD_DISABLED=1	Same effect. Recognises 1 only — the spellings above do not apply here.

For hook-level control, keep using ECC_DISABLED_HOOKS with the GateGuard hook ID.

Glob semantics for GATEGUARD_EXEMPT_GLOBS

Patterns match the entire project-relative target path. The project root is CLAUDE_PROJECT_DIR, falling back to the hook payload's cwd, then the hook process working directory. Relative globs never exempt targets outside that root. Explicit absolute globs match the entire absolute target path and may deliberately exempt paths outside the project.

Both patterns and paths use / separators and lowercase matching. * matches within a segment, ** across segments, and ? one non-separator character. **/ includes zero directories, so **/tests/** also matches tests/foo.js. Malformed patterns are dropped without granting an exemption.

Since 2.2.1, services/** only covers the project's root services tree, and *.md only covers its root Markdown files. Use **/*.md for all Markdown files within the project. Existing unanchored exemptions may need adjustment:

{
  "env": {
    "GATEGUARD_BASH_ROUTINE_DISABLED": "1",
    "GATEGUARD_EXEMPT_GLOBS": "**/tests/**,tests/**,**/*.test.*,**/docs/**,**/dist/**"
  }
}

Option B: Full package with config

pip install gateguard-ai
gateguard init

This adds .gateguard.yml for per-project configuration (custom messages, ignore paths, gate toggles).

Anti-Patterns

• Don't use self-evaluation instead. "Are you sure?" always gets "yes." This is experimentally verified.
• Don't skip the data schema check. Both A/B test agents assumed ISO-8601 dates when real data used %Y/%m/%d %H:%M. Checking data structure (with redacted values) prevents this entire class of bugs.
• Don't gate every single Bash command. Routine bash gates once per session. Destructive bash gates every time. This balance avoids slowdown while catching real risks.

Best Practices

• Let the gate fire naturally. Don't try to pre-answer the gate questions — the investigation itself is what improves quality.
• Customize gate messages for your domain. If your project has specific conventions, add them to the gate prompts.
• Use .gateguard.yml to ignore paths like .venv/, node_modules/, .git/.

Related Skills

• safety-guard — Runtime safety checks (complementary, not overlapping)
• code-reviewer — Post-edit review (GateGuard is pre-edit investigation)