Destructive Command Guard

Destructive Command Guard

A high-performance Claude Code hook that intercepts and blocks destructive commands before they execute. Written in Rust with SIMD-accelerated filtering via the memchr crate and Aho-Corasick multi-pattern matching for sub-millisecond latency. Assumes agents are well-intentioned but fallible.

Overview

DCG uses a whitelist-first architecture: safe patterns are checked before destructive patterns, and unrecognized commands are allowed by default (fail-safe). This ensures legitimate workflows are never broken while known dangerous patterns are always blocked. DCG runs as a PreToolUse hook in Claude Code, receiving JSON on stdin for each Bash tool invocation and returning exit code 0 (allow) or 2 (block). It only inspects direct Bash tool invocations, not contents of shell scripts.

The processing pipeline has four stages: JSON parsing, command normalization (strips absolute paths like /usr/bin/git), SIMD quick-reject filter (skips regex for commands without git or rm), and pattern matching. The memchr crate provides hardware-accelerated substring search (SSE2/AVX2 on x86_64, NEON on ARM), while Aho-Corasick handles multi-pattern matching in O(n) time regardless of pattern count.

DCG supports 49+ modular security packs organized by category (git, filesystem, databases, containers, Kubernetes, cloud providers, infrastructure tools). Core packs (core.git, core.filesystem) are always enabled; additional packs are configured via ~/.config/dcg/config.toml or the DCG_PACKS environment variable. The dcg scan subcommand can also audit files for destructive command contexts, suitable for CI integration.

DCG is not published on crates.io; it is installed from GitHub via cargo +nightly install or prebuilt binaries for Linux, macOS, and Windows WSL. The threat model assumes agents are well-intentioned but fallible; DCG catches honest mistakes, not adversarial attacks.

Quick Reference

Common Mistakes

Delegation

• Audit which destructive commands an agent session has attempted: Use Explore agent
• Set up DCG with custom packs for a new project environment: Use Task agent
• Plan a layered safety architecture combining DCG with other guardrails: Use Plan agent

References

• Command detection and processing pipeline
• Pack configuration and environment variables
• Installation and Claude Code setup
• Safety patterns and edge cases
• Troubleshooting and FAQ

Command Detection and Processing Pipeline

Why DCG Exists

AI coding agents are powerful but fallible. They can accidentally run destructive commands:

• "Let me clean up the build artifacts" results in rm -rf ./src (typo)
• "I'll reset to the last commit" results in git reset --hard (destroys uncommitted changes)
• "Let me fix the merge conflict" results in git checkout -- . (discards all modifications)
• "I'll clean up untracked files" results in git clean -fd (permanently deletes untracked files)

DCG intercepts dangerous commands _before_ execution and blocks them with a clear explanation.

Processing Pipeline

+-------------------------------------------------------------+
|                        Claude Code                          |
|  Agent executes `rm -rf ./build`                            |
+------------------------+------------------------------------+
                         |
                         v  PreToolUse hook (stdin: JSON)
+-------------------------------------------------------------+
|                          dcg                                |
|  +------------+    +-----------+    +---------------+       |
|  |   Parse    |--->| Normalize |--->| Quick Reject  |       |
|  |   JSON     |    |  Command  |    |   Filter      |       |
|  +------------+    +-----------+    +-------+-------+       |
|                                             |               |
|                    +------------------------+               |
|                    v                                        |
|  +------------------------------------------------------+  |
|  |                Pattern Matching                       |  |
|  |  1. Check SAFE_PATTERNS (whitelist) --> Allow         |  |
|  |  2. Check DESTRUCTIVE_PATTERNS -------> Deny          |  |
|  |  3. No match -------------------------> Allow         |  |
|  +------------------------------------------------------+  |
+------------------------+------------------------------------+
                         |
                         v  stdout: JSON (deny) or empty (allow)

Stage 1: JSON Parsing

• Reads hook input from stdin
• Validates Claude Code's PreToolUse format
• Non-Bash tools immediately allowed

Stage 2: Command Normalization

• Strips absolute paths: /usr/bin/git status becomes git status
• Preserves argument paths

Stage 3: Quick Rejection Filter

• SIMD-accelerated substring search for "git" or "rm"
• Commands without these bypass regex entirely (99%+ of commands)

Stage 4: Pattern Matching

• Safe patterns checked first (short-circuit on match to allow)
• Destructive patterns checked second (match to deny)
• No match results in default allow

Critical Design Principles

Whitelist-First Architecture

Safe patterns are checked _before_ destructive patterns:

git checkout -b feature    # Matches SAFE "checkout-new-branch" --> ALLOW
git checkout -- file.txt   # No safe match, matches DESTRUCTIVE --> DENY

Fail-Safe Defaults (Default-Allow)

Unrecognized commands are allowed by default to ensure the hook never breaks legitimate workflows.

Zero False Negatives Philosophy

The pattern set prioritizes never allowing dangerous commands over avoiding false positives.

Performance Optimizations

Result: Sub-millisecond execution for typical commands.

Pattern Counts

Installation and Claude Code Setup

Quick Install (Recommended)

curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/master/install.sh?$(date +%s)" | bash

# Easy mode: auto-update PATH
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/master/install.sh?$(date +%s)" | bash -s -- --easy-mode

# System-wide (requires sudo)
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/destructive_command_guard/master/install.sh?$(date +%s)" | sudo bash -s -- --system

From Source (Requires Rust Nightly)

Requires Rust nightly toolchain (minimum Rust 1.85, edition 2024). The repository includes a rust-toolchain.toml that automatically selects the correct toolchain.

cargo +nightly install --git https://github.com/Dicklesworthstone/destructive_command_guard destructive_command_guard

Prebuilt Binaries

Available for: Linux x86_64, Linux ARM64, macOS Intel, macOS Apple Silicon, Windows

Claude Code Configuration

Add to ~/.claude/settings.json (global) or .claude/settings.json (project):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "dcg"
          }
        ]
      }
    ]
  }
}

Important: Restart Claude Code after adding the hook. Alternatively, use the /hooks interactive menu to add hooks (takes effect immediately without restart).

Hook settings can be placed in three locations:

Claude Code Hook API Context

DCG uses the PreToolUse hook event, which fires before any tool call. Claude Code supports additional hook events and types that may be relevant for layered safety:

Hook types beyond "type": "command" (what DCG uses):

• "type": "prompt" -- sends hook input to a Claude model for yes/no judgment
• "type": "agent" -- spawns a subagent that can read files and run tools to verify conditions

DCG uses "type": "command" for deterministic, sub-millisecond blocking. Prompt/agent hooks are useful for complementary checks requiring judgment.

Structured JSON Output

In addition to exit codes, PreToolUse hooks can return structured JSON on stdout for finer control:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "git reset --hard destroys uncommitted changes. Use git stash first."
  }
}

DCG uses exit codes (simpler, faster) rather than JSON output, but the JSON format supports three decisions: "allow", "deny", and "ask" (escalate to user).

CLI Usage

Test commands manually:

# Show version with build metadata
dcg --version

# Test a command
echo '{"tool_name":"Bash","tool_input":{"command":"git reset --hard"}}' | dcg

Exit Codes

Example Block Message

================================================================
BLOCKED  dcg
----------------------------------------------------------------
Reason:  git reset --hard destroys uncommitted changes. Use 'git stash' first.

Command:  git reset --hard HEAD~1

Tip: If you need to run this command, execute it manually in a terminal.
     Consider using 'git stash' first to save your changes.
================================================================

Contextual Suggestions

Pack Configuration and Environment Variables

Modular Pack System

DCG uses a modular "pack" system to organize patterns by category.

Core Packs (Always Enabled)

Database Packs

Container Packs

Kubernetes Packs

Cloud Provider Packs

Infrastructure Packs

System Packs

Other Packs

Configuring Packs

# ~/.config/dcg/config.toml
[packs]
enabled = [
    "database.postgresql",
    "containers.docker",
    "kubernetes",  # Enables all kubernetes sub-packs
]

Environment Variables

Safety Patterns and Edge Cases

What DCG Blocks

Git Commands That Destroy Uncommitted Work

Git Commands That Destroy Remote History

Git Commands That Destroy Stashed Work

Filesystem Commands

What DCG Allows

Always Safe Git Operations

git status, git log, git diff, git add, git commit, git push, git pull, git fetch, git branch -d (safe delete with merge check), git stash, git stash pop, git stash list

Explicitly Safe Patterns

Safe Alternative: --force-with-lease

git push --force-with-lease   # ALLOWED - refuses if remote has unseen commits
git push --force              # BLOCKED - can overwrite others' work

Edge Cases Handled

Path Normalization

/usr/bin/git reset --hard          # Blocked
/usr/local/bin/git checkout -- .   # Blocked
/bin/rm -rf /home/user             # Blocked

Flag Ordering Variants

rm -rf /path          # Combined flags
rm -fr /path          # Reversed order
rm -r -f /path        # Separate flags
rm --recursive --force /path    # Long flags

All variants are handled.

Shell Variable Expansion

rm -rf $TMPDIR/build           # Allowed (temp)
rm -rf ${TMPDIR}/build         # Allowed
rm -rf "$TMPDIR/build"         # Allowed
rm -rf "${TMPDIR:-/tmp}/build" # Allowed

Staged vs Worktree Restore

git restore --staged file.txt    # Allowed (unstaging only)
git restore -S file.txt          # Allowed (short flag)
git restore file.txt             # BLOCKED (discards changes)
git restore --worktree file.txt  # BLOCKED (explicit worktree)
git restore -S -W file.txt       # BLOCKED (includes worktree)

Security Considerations

What DCG Protects Against

• Accidental data loss from git checkout -- or git reset --hard
• Remote history destruction from force pushes
• Stash loss from git stash drop/clear
• Filesystem accidents from rm -rf outside temp directories

What DCG Does NOT Protect Against

• Malicious actors (can bypass the hook)
• Non-Bash commands (Python/JavaScript file writes, API calls)
• Committed but unpushed work
• Commands inside scripts (./deploy.sh contents not inspected)

Threat Model

DCG assumes the AI agent is well-intentioned but fallible. It catches honest mistakes, not adversarial attacks.

Troubleshooting and FAQ

Troubleshooting

Hook Not Blocking Commands

1. Verify ~/.claude/settings.json has hook configuration 2. Restart Claude Code (or use /hooks menu to reload) 3. Check matcher is case-sensitive: "Bash" not "bash" 4. Test manually:

echo '{"tool_name":"Bash","tool_input":{"command":"git reset --hard"}}' | dcg
echo $?  # Should print 2

5. Enable verbose mode in Claude Code with Ctrl+O to see hook output in transcript 6. Run claude --debug for full execution details including which hooks matched

Hook Blocking Safe Commands

1. Check if there is an edge case not covered 2. File a GitHub issue 3. Temporary bypass: DCG_BYPASS=1 or run command manually

Processing Timeout

DCG enforces a 200ms maximum processing time. If a command exceeds this threshold, it is immediately allowed with a warning logged. This prevents any single hook invocation from blocking the agent indefinitely.

FAQ

Q: Why block `git branch -D` but allow `git branch -d`?

Lowercase -d only deletes branches fully merged. Uppercase -D force-deletes regardless of merge status, potentially losing commits.

Q: Why is `git push --force-with-lease` allowed?

Force-with-lease refuses to push if the remote has commits you have not seen, preventing accidental overwrites.

Q: Why block all `rm -rf` outside temp directories?

Recursive forced deletion is extremely dangerous. A typo or wrong variable can delete critical files. Temp directories are designed to be ephemeral.

Q: What if I really need to run a blocked command?

DCG instructs the agent to ask for permission. Run the command manually in a separate terminal after making a conscious decision.

Integration with Claude Code

DCG integrates natively as a PreToolUse hook in Claude Code. The hook receives JSON on stdin containing tool_name and tool_input fields, and returns structured JSON output or uses exit codes to control execution:

• Exit code 0: Command is safe, proceed with execution
• Exit code 2: Command is blocked, Claude Code prevents execution and receives the reason

The hook configuration can be placed in any of the three Claude Code settings files:

• ~/.claude/settings.json (user-global)
• .claude/settings.json (project-specific, committed)
• .claude/settings.local.json (project-specific, not committed)

DCG also provides a dcg scan subcommand that extracts executable command contexts from files and evaluates them using the same pattern engine, suitable for CI integration and repository auditing.

Agent Compatibility

For agents without PreToolUse support, install DCG as a git pre-commit hook for partial protection (covers git operations only).