git-guardrails-claude-code

Guide a user through installing a Claude Code PreToolUse hook that blocks dangerous git commands before they execute.

This Agent Forge port is guidance-first: do not install hooks, edit .claude/settings.json, edit ~/.claude/settings.json, or create executable hook files unless the user explicitly asks for installation in the current task.

What gets blocked

The reference hook blocks commands matching these patterns:

• git push, including force-push variants
• git reset --hard
• git clean -f and git clean -fd
• git branch -D
• git checkout .
• git restore .
• Short forms that still contain push --force or reset --hard

When a command is blocked, the hook exits with code 2 and prints a message explaining which dangerous pattern matched.

Workflow

1. Confirm scope

Ask the user where they want the guardrail installed:

• Project only: .claude/settings.json with the hook script under .claude/hooks/block-dangerous-git.sh
• Global: ~/.claude/settings.json with the hook script under ~/.claude/hooks/block-dangerous-git.sh

If the user only asks for advice or review, provide the guidance and stop before editing files.

2. Review the reference hook

Use the bundled reference as the source for the script content:

references/block-dangerous-git.sh.md

Keep it as documentation unless installation is explicitly requested. If installing, copy the shell script content from the reference into the selected hook path and make that copied file executable.

chmod +x .claude/hooks/block-dangerous-git.sh

For global installs, use the global hook path instead:

chmod +x ~/.claude/hooks/block-dangerous-git.sh

3. Merge hook settings

Add a PreToolUse hook for the Bash tool. If the settings file already exists, merge into the existing JSON and preserve all unrelated settings and hooks.

Project-scoped hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

Global hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-dangerous-git.sh"
          }
        ]
      }
    ]
  }
}

Do not replace an existing hooks.PreToolUse array. Append the new command hook only if an equivalent command is not already present.

4. Customize intentionally

Ask whether the user wants to add or remove blocked patterns before installation. Keep the defaults unless the user chooses a different policy.

Common customizations:

• Allow ordinary git push but keep blocking git push --force.
• Add git checkout -- . or repo-specific destructive commands.
• Add explanatory text that matches the team's git policy.

Document any customization in the response so future agents understand the local policy.

5. Verify with sample JSON

Test the installed or candidate script by piping Claude Code hook JSON into it:

echo '{"tool_input":{"command":"git push origin main"}}' | .claude/hooks/block-dangerous-git.sh

Expected result:

• Exit code: 2
• Stderr includes BLOCKED
• Message includes the matched pattern, such as git push

Also test an allowed command:

echo '{"tool_input":{"command":"git status --short"}}' | .claude/hooks/block-dangerous-git.sh

Expected result:

• Exit code: 0
• No block message

Agent Forge safety notes

• Preserve non-interactive shell behavior; never run commands that wait for input.
• Do not run a real dangerous git command to test the hook.
• Do not install this hook as part of a porting or documentation task.
• Do not overwrite settings files. Parse and merge JSON when installation is requested.
• Keep project-specific installs in the target project, not in this harness, unless the user explicitly chooses this repository as the target.