Docker Volume Guardrails

Sets up a PreToolUse hook that unconditionally blocks any Docker command that permanently deletes one or more volumes.

Why unconditional, with no override

This repo's own global instructions already say: "never delete volumes without explicit human confirmation." A hook only ever sees the raw command string handed to it - it has no way to observe whether a human actually confirmed this specific deletion earlier in the conversation. The only mechanical enforcement that is actually faithful to that rule is to never let the agent run this class of command at all - exactly matching git-guardrails-claude-code's own precedent for force-push and reset --hard. If a human has genuinely decided to delete a volume, they run that command themselves, outside the agent.

Companion to docker-db-guardrails, which handles a different class of mistake (a schema/data-wipe command run against the wrong database because its real target was never resolved and verified). This skill's class of mistake needs no such resolution step - volume deletion is destructive regardless of which volume it targets, so the rule is simply "never," full stop.

What Gets Blocked

• docker volume rm / docker volume remove
• docker volume prune
• docker rm -v / docker rm --volumes (removes anonymous volumes attached to a container)
• docker system prune --volumes (with or without -a)
• docker compose ... down -v / --volumes, and the legacy docker-compose down -v/--volumes binary

Ordinary volume mounting (docker run -v /host:/container ..., docker compose up) is untouched - the hook only matches -v/--volumes on the specific subcommands where that flag means "delete" (rm, down), never on run/create/up, where the identical flag means "mount."

As with docker-db-guardrails, prose that merely mentions these commands (a commit message or issue body discussing this very hook, for example) is not blocked - the hook tokenizes with shlex and excludes the values of text-carrying flags (-m/--message/--body/--title/--comment) from the scan.

Steps

1. Ask scope

Ask the user: install for this project only (.claude/settings.json) or all projects (~/.claude/settings.json)?

2. Copy the hook script

The bundled script is at: scripts/block-volume-deletion.py

Copy it to the target location based on scope:

• Project: .claude/hooks/block-volume-deletion.py
• Global: ~/.claude/hooks/block-volume-deletion.py

Make it executable with chmod +x.

3. Add hook to settings

Add to the appropriate settings file, merging into any existing hooks.PreToolUse array's "Bash" matcher entry — don't overwrite other hooks already registered there (git-guardrails-claude-code, docker-db-guardrails, etc.):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-volume-deletion.py"
          }
        ]
      }
    ]
  }
}

(Project scope: use "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-volume-deletion.py" instead.)

4. Verify

Test both directions before trusting the hook in a new environment:

SCRIPT=~/.claude/hooks/block-volume-deletion.py

# Should exit 2 (BLOCKED):
echo '{"tool_input":{"command":"docker volume rm my-app-data"}}' | "$SCRIPT"
echo '{"tool_input":{"command":"docker compose down -v"}}' | "$SCRIPT"

# Should exit 0 (allowed) — mounting a volume, and prose that merely mentions these words:
echo '{"tool_input":{"command":"docker run -v my-app-data:/data --rm image"}}' | "$SCRIPT"
echo '{"tool_input":{"command":"gh issue create --body \"should we ever allow docker volume prune?\""}}' | "$SCRIPT"

Then prove it fires live in-session: run an actual docker volume rm <some-real-volume-name> in the Bash tool and confirm the hook intercepts it with a PreToolUse:Bash hook error before it executes.

Known limitations

• No override mechanism exists by design (see above) - if this blocks a deletion the user has genuinely authorized, the answer is the user runs it themselves, not a flag or environment variable that lets the agent bypass it. Adding a bypass would let an agent self-authorize the exact thing this hook exists to prevent.
• Does not resolve command substitution or shell variables in volume names or subcommands - the threat model is an honest agent's mistake, not adversarial evasion (same scoping rationale as docker-db-guardrails).