Feature Request: Pre-execution hooks and tool restrictions for project guardrails

Summary

After extensive iteration on a scientific writing repository (70+ custom skills, 63 documented failure patterns, 8 supreme rules), we've reached the architectural ceiling of what documentation-based guardrails can achieve. The remaining enforcement gap requires Claude Code features that don't currently exist.

Current State

Our repository has:

• 860 lines of guardrail documentation across 8 focused guides
• 70+ skills for academic manuscript workflows
• 63 meta-learning documents capturing failure patterns
• PREVENTION-ACTION-PLAN.md mapping root causes to interventions

Quality assessment: 8.2/10 overall, but 5/10 for enforcement (blocked by platform)

The Problem

Claude Code cannot enforce rules - it can only document them. Claude frequently violates documented rules when focused on sub-tasks, even when those rules are in CLAUDE.md.

Example Violations That Cannot Be Prevented

1. Grep on structured data: Claude runs grep on .rdf files despite explicit ban, causing false "missing paper" claims
2. Single pdflatex: Claude runs pdflatex file.tex instead of master Makefile, causing unresolved references
3. Citation key hallucination: Claude invents \cite{author_keyword_year} keys without verifying they exist in Zotero

Current Workarounds (Partial Effectiveness)

| Problem | Workaround | Effectiveness |
|---------|------------|---------------|
| Grep on .rdf | tools/zrdf wrapper + documentation | ~70% |
| Single pdflatex | tools/pdflatex wrapper that redirects | ~80% |
| Citation hallucination | Zotero-first workflow in CLAUDE.md | ~60% |

The workarounds rely on Claude choosing to use them. True enforcement is impossible.

Requested Features

1. Pre-Execution Hooks (Priority 1)

Allow projects to define hooks that run before a tool executes:

# .claude/settings.yaml (hypothetical)
hooks:
  pre_bash:
    - pattern: "grep.*\\.rdf"
      action: block
      message: "Use tools/zrdf instead of grep on RDF files"
    - pattern: "^pdflatex\\s"
      action: block
      message: "Use 'make TEX=file.tex' instead of direct pdflatex"

  pre_write:
    - pattern: "\\\\cite\\{[^}]+\\}"
      action: validate
      script: "tools/validate-citation-key.sh"

Impact: Would raise enforcement from 5/10 to 9/10.

2. Tool Restrictions (Priority 2)

Allow projects to block or redirect specific commands:

tool_restrictions:
  bash:
    blocked_patterns:
      - "grep.*\\.(rdf|xml|json)"
      - "^pdflatex\\s"
    redirects:
      pdflatex: "cd manuscripts && make TEX="

3. Custom Tool Definitions (Priority 3)

Allow projects to define first-class tools that Claude sees alongside Bash, Read, etc.:

custom_tools:
  - name: "ZoteroSearch"
    command: "tools/zrdf"
    description: "Search Zotero RDF for citation keys"
    parameters:
      - name: "query"
        description: "Search term"
        required: true

This would make the correct tool as visible as Bash, reducing accidental grep usage.

4. Session State Persistence (Priority 4)

Allow projects to persist state across sessions:

session_state:
  persist:
    - violation_counts
    - verified_citation_keys
    - last_compilation_status

Impact: Would enable learning from mistakes and tracking improvement.

Why This Matters

Our repository is for academic manuscript writing where accuracy is critical:

• Hallucinated citation keys → undefined references → broken PDFs
• Wrong compilation → "Section ??" everywhere → unpublishable
• Invented statistics → academic misconduct risk

We've invested significant effort in documentation-based guardrails, but documentation cannot prevent violations - it can only describe correct behavior. Claude's tendency toward "instruction dropout" when focused on sub-tasks means even prominent CLAUDE.md rules are violated.

Evidence of Need

From our meta-learnings:

User quote: "we have to do this fuck ton of work just to build guardrails for your stochastic take on deterministic problem"

User quote: "Why in the fuck are you using grep?" (after explicit grep ban documented)

User quote: "Why do keep creating a ton of different Makefile instances?" (after Makefile rule documented)

The pattern is consistent: documentation is necessary but not sufficient.

Proposed Implementation Path

1. Start with pre_bash hooks - highest impact, simplest implementation
2. Add blocked_patterns - low complexity, high value
3. Consider custom_tools - enables project-specific tool discovery
4. Evaluate session_state - most complex, evaluate need

Related

• This repository: sci-llm-writer (if public)
• Our guardrail documentation: .claude/docs/claude-ecosystem-current-state-2026-01-25.md

Environment

• Claude Code version: Latest
• Platform: Linux
• Use case: Scientific manuscript writing with LaTeX, Zotero, custom bibliography tools

---

Thank you for considering these features. The Claude Code team has built an excellent tool - these additions would enable projects with strict correctness requirements to achieve the enforcement they need.