Investigation-gate hook

The investigation-gate hook is Code Majesty’s name for a PreToolUse hook that intercepts any Edit, Write, or Bash call referring to a type, method, or file the agent has not yet opened with the Read tool. The hook returns a block result with a remediation prompt: read the symbol first, then retry the call. This is how the 12-layer system enforces “no edit without context.”

The hook config registers a PreToolUse matcher on the editing tools:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write|Bash",
      "hooks": [{ "type": "command", "command": ".claude/hooks/investigation-gate.ps1" }]
    }]
  }
}

The script extracts symbol references from the pending tool input, checks them against the session’s read log, and returns a block decision when a reference has no evidence. A typical cycle: the agent attempts to edit CancelEndpoint.cs to call OrderService.Cancel; the gate finds no Read event covering OrderService and blocks with “OrderService.Cancel not in context — read Api/Features/Orders/OrderService.cs first.” The agent reads the file, discovers the method is actually CancelAsync(CancelCommand), and writes the correct call on the retry. The confabulation was caught before the compiler — or a reviewer — ever saw it.

When to use

• Any project where agent confabulation about non-existent or stale APIs causes more wasted cycles than human supervision can catch.
• Codebases with a high churn rate where what the agent learned an hour ago may already be wrong.

Distinguish from

A generic permission hook (which gates by tool name or path glob). The investigation gate gates by semantic dependency — what symbols the planned action references, not what tool is being called.