Verify gate

verify-gate

A discipline-and-enforcement skill that prevents agents from declaring success without evidence. Implements the pattern shipped by Anthropic in cwc-long-running-agents as a PreToolUse hook.

The prompt-only version of this rule achieves ~40% adherence (Anthropic measured). The hook-enforced version achieves ~100% because exit code 2 cannot be argued with.

When it triggers

The PreToolUse hook fires on Write and Edit tool calls. If the target file matches a configured "claim" rule, the hook checks the session transcript for a corresponding evidence Read within the freshness window (default 10 minutes).

User writes...	Hook requires recent Read of...
test-results.json	test-output.log, vitest-results.xml, pytest.xml, jest-results.json
build-status.txt	build.log, tsc-output.log
any path matching a project-level rule	the configured evidence file(s)

If no Read on evidence within the window → hook returns permissionDecision: "deny" with a structured reason naming the missing evidence. Claude sees the denial and is told what to Read before retrying.

Setup

/verify-gate install

This copies PreToolUse-verify-gate.sh to .claude/hooks/ and registers it in .claude/settings.json. If you have existing PreToolUse hooks, this is additive — they continue to fire.

Customization

Create .claude/verify-gate.json to override the default rules:

{
  "claims": [
    {
      "writes_to": "deployment.log",
      "requires_read_of": ["build.log", "smoke-test.log"]
    },
    {
      "writes_to": "release-notes.md",
      "requires_read_of": ["CHANGELOG.md"]
    }
  ],
  "evidence_freshness_minutes": 15
}

The hook matches writes_to against the basename of the file being written. Multiple requires_read_of entries are OR'd — any one of them satisfies the rule.

Configuration — .claude/catalyst.json

verify-gate reads its config from the verify_gate section of .claude/catalyst.json, falling back to the legacy .claude/verify-gate.json (deprecated, supported one release) and then built-in defaults. overreliance_min_bytes resolves env > json > 4000.

{
  "verify_gate": {
    "claims": [ { "writes_to": "test-results.json", "requires_read_of": ["test-output.log"] } ],
    "evidence_freshness_minutes": 10,
    "overreliance_min_bytes": 4000
  }
}

Migration: move the contents of an existing .claude/verify-gate.json under a verify_gate key in .claude/catalyst.json.

Commands

Command	What it does
/verify-gate install	Copy hook to .claude/hooks/ + register in .claude/settings.json
/verify-gate uninstall	Remove the hook (settings.json cleaned, hook script deleted)
/verify-gate add <write_path> <read_path>[,read_path2,...]	Append a claim rule to .claude/verify-gate.json
/verify-gate status	List currently configured claim rules + show recent blocks (from session log)

What to do when the hook blocks you

The denial response tells you exactly which file to Read. Read it, then retry the write. If the evidence is genuinely missing (e.g., the test never ran), don't trick the hook — actually produce the evidence.

If the evidence is stale (Read >10min ago), re-Read it. The freshness window catches the "I read it an hour ago and a lot has changed" failure mode.

When NOT to use

• Pure scratch workflows — quick prototypes with no claim semantics. No need to gate.
• Tasks where the writes don't claim anything — adding a comment to a doc, renaming a variable. The hook only fires on configured claim paths; everything else passes through.
• CI / autonomous runs — those should use Anthropic's cwc-long-running-agents /goal + verify-gate.sh directly; this Catalyst version is for interactive workflows.

Over-reliance rule (opt-in)

Motivated by research showing agent-generated code is less durable than human-reviewed code (Anthropic PR-acceptance gap, METR agent slowdown study, insecure-code-with-assistants findings): large volumes of unreviewed output carry elevated risk of silent drift and subtle errors.

Config	Default	Description
CATALYST_VERIFY_OVERRELIANCE	0 (off)	Set to 1 to enable the rule
CATALYST_OVERRELIANCE_MIN_BYTES	4000	Minimum write payload (bytes) to trigger

Trigger: CATALYST_VERIFY_OVERRELIANCE=1 AND a Write/Edit whose content (or new_string) is ≥ CATALYST_OVERRELIANCE_MIN_BYTES AND no file was Read in the freshness window.

Decision: permissionDecision: "ask" — not a hard deny. The agent is prompted to confirm or read relevant context first. This preserves autonomy for intentional large writes while surfacing a trust prompt for unreviewed bulk output.

Anti-pattern (bad):

# Agent writes 8000 bytes of generated code with no Read in the session.
# With flag ON → hook surfaces "ask" with over-reliance caution.
# Agent acknowledges and proceeds — or reads relevant context first.

Anti-pattern (good):

# Agent reads the target file or a test result first, then writes.
# Hook sees recent Read in-window → over-reliance check is cleared → no caution.

To enable project-wide:

export CATALYST_VERIFY_OVERRELIANCE=1
# Optionally lower the threshold for tighter review:
export CATALYST_OVERRELIANCE_MIN_BYTES=2000

Anti-patterns

• Disabling the hook to "unblock" yourself. If you're hitting blocks, the system is working. Read the evidence.
• Configuring overly broad globs in verify-gate.json. Don't block legitimate writes — keep the rule list precise.
• Setting evidence_freshness_minutes very high (>60). Stale evidence defeats the gate.
• Manually editing .claude/settings.json to remove the hook entry. Use /verify-gate uninstall so settings.json stays valid.

Composition with other Catalyst skills

• handoff writes to .claude/handoffs/<key>.json and .claude/PROJECT_STATE.md. Those paths are NOT in the default claim list, so handoff writes are never blocked by verify-gate.
• hooks does NOT install verify-gate via --all — it is a separate opt-in. Use /verify-gate install. The two compose cleanly once both are installed.

Model evolution

The hook encodes an assumption: prompt-only adherence to "Read before claim" is ~40%. May relax if future models internalize the rule without scaffolding. Review annually per Catalyst convention.