git-safety-guard（git 安全卫士）

Git Safety Guard

Use this skill when setting up or configuring protection against destructive git/filesystem commands in Claude Code.

Overview

Git Safety Guard intercepts Bash commands before execution and blocks dangerous operations that could permanently destroy uncommitted work or important files. The guard uses regex pattern matching with an allowlist to distinguish between safe and dangerous variants of commands.

Key Features:

• terraphim-agent guard - CLI command for pattern checking
• PreToolUse hook - Intercept Claude Code tool calls before execution
• Allowlist support - Safe patterns override dangerous patterns
• Fail-open semantics - If guard fails, commands pass through

Architecture

Claude Code PreToolUse
      |
      v
git_safety_guard.sh (shell wrapper)
      |
      v
terraphim-agent guard --json "$COMMAND"
      |
      v
Pattern Matching (Regex)
      |
      +---> SAFE_PATTERNS (allowlist) -> Allow
      |
      +---> DESTRUCTIVE_PATTERNS -> Block with reason
      |
      +---> No match -> Allow

Commands Blocked

Commands Explicitly Allowed

For Humans

Quick Start

# Install terraphim-agent from GitHub releases (latest version)
# macOS ARM64 (Apple Silicon)
gh release download --repo terraphim/terraphim-ai \
  --pattern "terraphim-agent-aarch64-apple-darwin" --dir /tmp
chmod +x /tmp/terraphim-agent-aarch64-apple-darwin
mv /tmp/terraphim-agent-aarch64-apple-darwin ~/.cargo/bin/terraphim-agent

# macOS x86_64 (Intel)
# gh release download --repo terraphim/terraphim-ai \
#   --pattern "terraphim-agent-x86_64-apple-darwin" --dir /tmp

# Linux x86_64
# gh release download --repo terraphim/terraphim-ai \
#   --pattern "terraphim-agent-x86_64-unknown-linux-gnu" --dir /tmp

# Note: crates.io version (cargo install terraphim_agent) is outdated (v1.0.0)
# and missing the guard command. Use GitHub releases for latest features.

# Test guard command
echo "git checkout -- file.txt" | terraphim-agent guard --json
# Output: {"decision":"block","reason":"git checkout -- discards...","command":"..."}

echo "git checkout -b new-branch" | terraphim-agent guard --json
# Output: {"decision":"allow","command":"git checkout -b new-branch"}

Installation

Project-local installation:

# Copy hook script
cp .claude/hooks/git_safety_guard.sh /your/project/.claude/hooks/

# Add to .claude/settings.local.json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/git_safety_guard.sh"
      }]
    }]
  }
}

Global installation (~/.claude/):

# Run install script with --global flag
./scripts/install-terraphim-hooks.sh --global

CLI Usage

# Check a command (JSON output)
echo "git reset --hard" | terraphim-agent guard --json

# Check a command (human output - exits with code 1 if blocked)
echo "rm -rf /home/user" | terraphim-agent guard

# Fail-open mode (always exit 0)
echo "git checkout -- ." | terraphim-agent guard --fail-open

For AI Agents

Detecting Guard Availability

# Check if terraphim-agent is available
if command -v terraphim-agent >/dev/null 2>&1; then
    echo "Guard available"
elif [ -x "./target/release/terraphim-agent" ]; then
    AGENT="./target/release/terraphim-agent"
fi

Using Guard in Hooks

PreToolUse Hook Pattern:

#!/bin/bash
# Read JSON input
INPUT=$(cat)
TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name')
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

# Only process Bash commands
[ "$TOOL_NAME" != "Bash" ] && exit 0

# Check command
RESULT=$(terraphim-agent guard --json <<< "$COMMAND")

# If blocked, output deny decision
if echo "$RESULT" | jq -e '.decision == "block"' >/dev/null; then
    REASON=$(echo "$RESULT" | jq -r '.reason')
    cat <<EOF
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "BLOCKED: $REASON"
  }
}
EOF
fi

exit 0

Guard Response Format

Blocked command:

{
  "decision": "block",
  "reason": "git checkout -- discards uncommitted changes permanently. Use 'git stash' first.",
  "command": "git checkout -- file.txt",
  "pattern": "git\\s+checkout\\s+--\\s+"
}

Allowed command:

{
  "decision": "allow",
  "command": "git checkout -b new-branch"
}

Error Handling

The guard uses fail-open semantics:

• If terraphim-agent is not found: pass through unchanged
• If pattern matching fails: allow command
• Errors logged to stderr only in verbose mode

Enable verbose mode:

export TERRAPHIM_VERBOSE=1

What Happens When Blocked

When Claude tries to run a blocked command, it receives feedback like:

BLOCKED by git_safety_guard

Reason: git checkout -- discards uncommitted changes permanently. Use 'git stash' first.

Command: git checkout -- file.txt

If this operation is truly needed, ask the user for explicit permission and have them run the command manually.

The command never executes. Claude sees this feedback and should ask the user for help.

Testing

# Manual test - should be blocked
echo "git checkout -- test.txt" | terraphim-agent guard --json

# Manual test - should be allowed
echo "git checkout -b feature" | terraphim-agent guard --json

# Run unit tests
cargo test -p terraphim_agent guard_patterns

# Test hook script
echo '{"tool_name":"Bash","tool_input":{"command":"git reset --hard"}}' | \
  .claude/hooks/git_safety_guard.sh

Troubleshooting

The Incident That Prompted This

On December 17, 2025, an AI agent ran git checkout -- on multiple files containing hours of uncommitted work from another agent. This destroyed the work instantly and silently. The files were recovered from a dangling Git object via git fsck --lost-found, but it was a close call.

Instructions alone don't prevent accidents. Mechanical enforcement does.

Related Skills

• terraphim-hooks - Knowledge graph-based text replacement
• implementation - For building custom guards
• testing - For validating guard behavior
• devops - For CI/CD integration with hooks