Document Guard

What It’s For

Claude Code’s permission rules control which tools can run. They don’t validate what gets written once an edit is approved. That gap is what Document Guard closes: it intercepts every Edit and Write as a PreToolUse hook and validates the content against configurable rules before it reaches disk — permission rules are the firewall, Document Guard is the content inspection layer behind it.

It sits in a defense-in-depth stack alongside tool-level access control and command-blocking, and adds an audit trail on top:

Layer	What It Does
Access Control	Controls which tools Claude can use (Claude Code permission rules)
Command Protection	Blocks dangerous shell commands
Content Validation	Inspects file edits before they land (Document Guard)
Audit Trail	Logs every action for review

How to Use

Two commands:

claude plugin marketplace add davidmoneil/aifred-document-guard
claude plugin install document-guard@aifred-document-guard

Zero config. 11 protection rules active immediately. ~700 lines of vanilla Node.js, no dependencies.

The Model: Four Response Tiers

Not every violation deserves the same response — a credential leak and a missing shebang are different severities. Document Guard grades every match into one of four tiers, the same principle behind alert-fatigue management in a SOC:

Tier	Response	Example
Critical	Block the edit. Require explicit user approval to override.	Writing an AWS key into source code
High	Block the edit. Require explicit override.	Removing sections from CLAUDE.md
Medium	Warn Claude (inject context). Allow the edit.	Stripping a shebang from a shell script
Low	Log it. No friction.	Informational audit trail

Seven structural checks ship out of the box: total write block on sensitive files (.env, .credentials/), credential scanning (13 patterns — AWS keys, GitHub tokens, Stripe keys, JWTs, database connection strings, with placeholder detection to avoid false positives), key-deletion protection on config rewrites, Markdown section preservation, heading-structure preservation, frontmatter-field locking, and shebang preservation. One additional opt-in semantic check uses a local Ollama model to verify written content matches a file’s declared purpose — it always warns, never blocks, and fails open if Ollama isn’t running.

Blocking has a deliberate escape hatch, not a permanent bypass: Document Guard tells Claude how to ask the user for explicit approval, writes a single-use override file with an expiration timestamp (default 120 seconds), and consumes and logs the override on retry — the same principle as break-glass access in identity management.

What Happens When It Blocks

Claude wants to edit a file
    |
Document Guard intercepts (PreToolUse hook)
    |
Match against rules (glob patterns, most specific wins)
    |
Run applicable checks (credential scan, structural, semantic)
    |
No violations? --> Allow
Critical/High violations? --> Block + log + provide override instructions
Medium violations? --> Warn (inject context) + allow
Low violations? --> Log only

The hook runs synchronously before the edit and fails open if it crashes — a broken guard doesn’t block the workflow it’s protecting.

The Unplanned Result: It Teaches Claude

When Document Guard blocks an edit, it doesn’t just deny it — it injects context back into the conversation explaining what rule matched and why. Claude reads that feedback and adjusts for the rest of the session: block a credential leak once, and Claude stops writing credentials into tracked files for that session. The guardrail became a real-time feedback loop, not just a safety net.

Configuring It

Two-tier config, no merging: a project override at .claude/hooks/document-guard.config.js takes full precedence over the plugin’s bundled defaults. Config is plain JavaScript, not JSON, so rules can carry comments and logic:

{
  name: 'Database migrations',
  pattern: 'migrations/**',
  tier: 'high',
  checks: ['no_write_allowed'],
  message: 'Migration files are immutable once created.',
}

Limits

• It’s a content-inspection layer, not a full defense-in-depth stack by itself. It doesn’t control which tools Claude can invoke, and it doesn’t block dangerous shell commands — pair it with permission rules and a command-blocking tool.
• The semantic check is opt-in and soft by design. It requires a local Ollama instance, always warns rather than blocks, and fails open — it’s a hint, not a guarantee.
• This is v1. Rules are glob-pattern matched with specificity ranking, not git-aware — the same rule applies whether a file is staged or not. Team-wide shared rule sets and additional local-model backends beyond Ollama are open v2 considerations, not yet built.