The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(hooks,skills): add gateguard fact-forcing pre-action gate
seto5a03922934ac
diff --git a/hooks/hooks.json b/hooks/hooks.jsonindex 528b03f83..0dc929707 100644--- a/hooks/hooks.json+++ b/hooks/hooks.json@@ -126,6 +126,30 @@],"description": "Check MCP server health before MCP tool execution and block unhealthy MCP calls","id": "pre:mcp-health-check"+ },+ {+ "matcher": "Edit|Write",+ "hooks": [+ {+ "type": "command",+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/gateguard-fact-force.js\"",+ "timeout": 5+ }+ ],+ "description": "Fact-forcing gate: block first Edit/Write per file and demand investigation (importers, data schemas, user instruction) before allowing",+ "id": "pre:edit-write:gateguard-fact-force"+ },+ {+ "matcher": "Bash",+ "hooks": [+ {+ "type": "command",+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/gateguard-fact-force.js\"",+ "timeout": 5+ }+ ],+ "description": "Fact-forcing gate: block destructive Bash commands and demand rollback plan; quote user instruction on first Bash per session",+ "id": "pre:bash:gateguard-fact-force"}],"PreCompact": [diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.jsnew file mode 100644index 000000000..d1e0106b7--- /dev/null+++ b/scripts/hooks/gateguard-fact-force.js@@ -0,0 +1,216 @@+#!/usr/bin/env node+/**+ * PreToolUse Hook: GateGuard Fact-Forcing Gate+ *+ * Forces Claude to investigate before editing files or running commands.+ * Instead of asking "are you sure?" (which LLMs always answer "yes"),+ * this hook demands concrete facts: importers, public API, data schemas.+ *+ * The act of investigation creates awareness that self-evaluation never did.+ *+ * Gates:+ * - Edit/Write: list importers, affected API, verify data schemas, quote instruction+ * - Bash (destructive): list targets, rollback plan, quote instruction+ * - Bash (routine): quote current instruction (once per session)+ *+ * Exit codes:+ * 0 - Allow (gate already passed for this target)+ * 2 - Block (force investigation first)+ *+ * Cross-platform (Windows, macOS, Linux).+ *+ * Full package with config support: pip install gateguard-ai+ * Repo: https://github.com/zunoworks/gateguard+ */++'use strict';++const fs = require('fs');+const path = require('path');++const MAX_STDIN = 1024 * 1024;++// Session state file for tracking which files have been gated+const STATE_DIR = path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.gateguard');+const STATE_FILE = path.join(STATE_DIR, '.session_state.json');++const DESTRUCTIVE_BASH = /\b(rm\s+-rf|git\s+reset\s+--hard|git\s+checkout\s+--|git\s+clean\s+-f|drop\s+table|delete\s+from|truncate|git\s+push\s+--force|dd\s+if=)\b/i;++// --- State management ---++function loadState() {+ try {+ if (fs.existsSync(STATE_FILE)) {+ return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));+ }+ } catch (_) { /* ignore */ }+ return { checked: [], read_files: [] };+}++function saveState(state) {+ try {+ fs.mkdirSync(STATE_DIR, { recursive: true });+ fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2), 'utf8');+ } catch (_) { /* ignore */ }+}++function markChecked(key) {+ const state = loadState();+ if (!state.checked.includes(key)) {+ state.checked.push(key);+ saveState(state);+ }+}++function isChecked(key) {+ const state = loadState();+ return state.checked.includes(key);+}++// --- Sanitize file path against injection ---++function sanitizePath(filePath) {+ return filePath.replace(/[\n\r]/g, ' ').trim().slice(0, 500);+}++// --- Gate messages ---++function editGateMsg(filePath) {+ const safe = sanitizePath(filePath);+ return [+ '[Fact-Forcing Gate]',+ '',+ `Before editing ${safe}, present these facts:`,+ '',+ '1. List ALL files that import/require this file (use Grep)',+ '2. List the public functions/classes affected by this change',+ '3. If this file reads/writes data files, cat one real record and show actual field names, structure, and date format',+ '4. Quote the user\'s current instruction verbatim',+ '',+ 'Present the facts, then retry the same operation.'+ ].join('\n');+}++function writeGateMsg(filePath) {+ const safe = sanitizePath(filePath);+ return [+ '[Fact-Forcing Gate]',+ '',+ `Before creating ${safe}, 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 (use Glob)',+ '3. If this file reads/writes data files, cat one real record and show actual field names, structure, and date format',+ '4. Quote the user\'s current instruction verbatim',+ '',+ 'Present the facts, then retry the same operation.'+ ].join('\n');+}++function destructiveBashMsg() {+ return [+ '[Fact-Forcing Gate]',+ '',+ 'Destructive command detected. Before running, present:',+ '',+ '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',+ '',+ 'Present the facts, then retry the same operation.'+ ].join('\n');+}++function routineBashMsg() {+ return [+ '[Fact-Forcing Gate]',+ '',+ 'Quote the user\'s current instruction verbatim.',+ 'Then retry the same operation.'+ ].join('\n');+}++// --- Output helpers ---++function deny(reason) {+ const output = {+ hookSpecificOutput: {+ hookEventName: 'PreToolUse',+ permissionDecision: 'deny',+ permissionDecisionReason: reason+ }+ };+ process.stdout.write(JSON.stringify(output));+ process.exit(0);+}++function allow() {+ // Output nothing = allow+ process.exit(0);+}++// --- Main ---++function main() {+ let raw = '';+ try {+ raw = fs.readFileSync(0, 'utf8').slice(0, MAX_STDIN);+ } catch (_) {+ allow();+ return;+ }++ let data;+ try {+ data = JSON.parse(raw);+ } catch (_) {+ allow();+ return;+ }++ const toolName = data.tool_name || '';+ const toolInput = data.tool_input || {};++ if (toolName === 'Edit' || toolName === 'Write') {+ const filePath = toolInput.file_path || '';+ if (!filePath) {+ allow();+ return;+ }++ // Gate: first action per file+ if (!isChecked(filePath)) {+ markChecked(filePath);+ const msg = toolName === 'Edit' ? editGateMsg(filePath) : writeGateMsg(filePath);+ deny(msg);+ return;+ }++ allow();+ return;+ }++ if (toolName === 'Bash') {+ const command = toolInput.command || '';++ // Destructive commands: always gate+ if (DESTRUCTIVE_BASH.test(command)) {+ deny(destructiveBashMsg());+ return;+ }++ // Routine bash: once per session+ if (!isChecked('__bash_session__')) {+ markChecked('__bash_session__');+ deny(routineBashMsg());+ return;+ }++ allow();+ return;+ }++ allow();+}++main();diff --git a/skills/gateguard/SKILL.md b/skills/gateguard/SKILL.mdnew file mode 100644index 000000000..4802b64bf--- /dev/null+++ b/skills/gateguard/SKILL.md@@ -0,0 +1,117 @@+---+name: gateguard+description: Fact-forcing gate that blocks Edit/Write/Bash and demands concrete investigation (importers, data schemas, user instruction) before allowing the action. Measurably improves output quality by +2.25 points vs ungated agents.+origin: community+---++# 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 Gate (first edit per file)++```+Before editing {file_path}, present these facts:++1. List ALL files that import/require this file (use Grep)+2. List the public functions/classes affected by this change+3. If this file reads/writes data files, cat one real record+ and show actual field names, structure, and date format+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 (use Glob)+3. If this file reads/writes data files, cat one real record+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)++```+Quote the user's current instruction verbatim.+```++## 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.++### Option B: Full package with config++```bash+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 one real record 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)