Skip to content

pre-tool-use-validator.sh

PreToolUse (Write/Edit, Bash) — secret-shape scan, protected files, config ask-gate, per-file edit lock. Patched for Windows paths.

Source: .claude/hooks/pre-tool-use-validator.sh, wired in .claude/settings.json.

#!/bin/bash
# Pre-tool-use validator for swarm consistency
# Validates file operations to prevent conflicts in multi-agent environments

INPUT=$(cat)

# jq is required to parse tool input; fail open if unavailable (hooks are
# guardrails, not a security boundary)
command -v jq >/dev/null 2>&1 || exit 0

TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null || true)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // empty' 2>/dev/null || true)
SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)

# detect_secret: shared secret-shape scan for both Write/Edit content (below)
# and Bash commands that redirect/heredoc content into a file. Sets
# SECRET_DETECTED / SECRET_TYPE as a side effect rather than echoing a
# classification back through a subshell.
detect_secret() {
    local text="$1"
    SECRET_DETECTED=false
    SECRET_TYPE=""

    # Generic secrets (API keys, passwords, tokens)
    # `-e` on every pattern below (not just this one) is deliberate: a
    # pattern beginning with a literal `-` (the private-key one, below) gets
    # parsed as an option by BSD grep without it, erroring out instead of
    # matching — `-e` marks the argument as a pattern unconditionally, so
    # this holds regardless of what a pattern happens to start with.
    if echo "$text" | grep -qiE -e '(api[_-]?key|secret|password|token|credential).*[=:][[:space:]]*["\x27]?[a-zA-Z0-9+/]{20,}'; then
        SECRET_DETECTED=true
        SECRET_TYPE="generic secret"
    fi

    # AWS access keys (AKIA followed by 16 alphanumeric chars)
    if echo "$text" | grep -qE -e 'AKIA[0-9A-Z]{16}'; then
        SECRET_DETECTED=true
        SECRET_TYPE="AWS access key"
    fi

    # JWT tokens (three base64 segments separated by dots)
    if echo "$text" | grep -qE -e 'eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.[a-zA-Z0-9_-]+'; then
        SECRET_DETECTED=true
        SECRET_TYPE="JWT token"
    fi

    # Environment variable exports with secrets
    if echo "$text" | grep -qiE -e 'export\s+(API_KEY|SECRET|PASSWORD|TOKEN|CREDENTIAL|AWS_|PRIVATE_KEY)=["\x27]?[a-zA-Z0-9+/]{20,}'; then
        SECRET_DETECTED=true
        SECRET_TYPE="exported secret"
    fi

    # GitHub personal access tokens
    if echo "$text" | grep -qE -e 'ghp_[a-zA-Z0-9]{36}'; then
        SECRET_DETECTED=true
        SECRET_TYPE="GitHub personal access token"
    fi

    # Private keys (PEM format) — this pattern starts with a literal `-----`;
    # without `-e` above, BSD grep (macOS) treats that as option flags and
    # errors out instead of matching, silently never detecting a real
    # private key on those systems.
    if echo "$text" | grep -qE -e '-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----'; then
        SECRET_DETECTED=true
        SECRET_TYPE="private key"
    fi
}

# Bash secret-write scan: a redirect or heredoc can write secret-shaped
# content straight to disk without ever going through Write/Edit, bypassing
# the detection below entirely (e.g. a heredoc'd .env write). Ask — never
# deny, this hook can't tell a real secret from a placeholder — when the
# command both writes to a file and contains secret-shaped content. This
# covers the pre-commit, redirect-syntax path only; Trivy's CI secret-scan
# job remains the backstop for anything this and the Write/Edit scan below
# both miss (see docs/hooks.md's Secret Detection section).
if [ "$TOOL_NAME" = "Bash" ]; then
    # Named TOOL_COMMAND, not BASH_COMMAND: the latter is bash's own special
    # variable (always reflects "the command currently being executed") —
    # assigning to it here would silently get clobbered by the shell on the
    # very next statement, not hold the extracted value.
    TOOL_COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
    if echo "$TOOL_COMMAND" | grep -qE '(>>|<<|>)'; then
        detect_secret "$TOOL_COMMAND"
        if [ "$SECRET_DETECTED" = true ]; then
            echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"Potential $SECRET_TYPE detected in a Bash command that writes to a file (redirect/heredoc). Please verify this is not sensitive data.\"}}"
        fi
    fi
    exit 0
fi

# Exit if not a file operation
if [ -z "$FILE_PATH" ]; then
    exit 0
fi

PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
LOCK_DIR="$PROJECT_DIR/.claude/hooks/.locks"
mkdir -p "$LOCK_DIR"

# Windows (local patch, not upstream): Claude Code passes `D:\dir\file` paths
# and CLAUDE_PROJECT_DIR may be `D:\dir`, `d:/dir` or `/d/dir`. Normalize both
# to `d:/dir/...` before comparing, or the prefix strip fails, REL_PATH stays
# absolute with `\` and `:`, the lock mkdir below fails and EVERY Write/Edit
# is denied (and the config ask-gate never matches).
norm_path() {
    local p="${1//\\//}"
    if [[ "$p" =~ ^/([a-zA-Z])/(.*)$ ]]; then p="${BASH_REMATCH[1]}:/${BASH_REMATCH[2]}"; fi
    if [[ "$p" =~ ^([a-zA-Z]):(.*)$ ]]; then p="${BASH_REMATCH[1],,}:${BASH_REMATCH[2]}"; fi
    printf '%s' "${p%/}"
}
NORM_PROJECT=$(norm_path "$PROJECT_DIR")
NORM_FILE=$(norm_path "$FILE_PATH")

# Get relative path for lock file naming
if [[ "$NORM_FILE" == "$NORM_PROJECT"/* ]]; then
    REL_PATH="${NORM_FILE#"$NORM_PROJECT"/}"
else
    REL_PATH="$NORM_FILE"
fi

# Create safe lock file name (`:` is not valid in Windows file names)
LOCK_FILE="$LOCK_DIR/$(echo "$REL_PATH" | tr '/:' '__').lock"

# Check for concurrent edits (swarm conflict prevention)
if [ -f "$LOCK_FILE" ]; then
    LOCK_SESSION=$(jq -r '.session_id // empty' <"$LOCK_FILE" 2>/dev/null || true)
    LOCK_TIME=$(jq -r '.timestamp // 0' <"$LOCK_FILE" 2>/dev/null || echo 0)
    [[ "$LOCK_TIME" =~ ^[0-9]+$ ]] || LOCK_TIME=0
    CURRENT_TIME=$(date +%s)

    # Lock expires after 120 seconds
    if [ $((CURRENT_TIME - LOCK_TIME)) -lt 120 ] && [ "$LOCK_SESSION" != "$SESSION_ID" ]; then
        echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"File '$REL_PATH' is being edited by another agent. Wait for completion or coordinate via the task tracker.\"}}"
        exit 0
    fi
fi

# Block edits to critical system files
PROTECTED_PATTERNS=(
    ".git/"
    ".env"
    ".mcp.json"
)

for pattern in "${PROTECTED_PATTERNS[@]}"; do
    if [[ "$REL_PATH" == *"$pattern"* ]]; then
        echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"Cannot modify protected file: $REL_PATH. Use appropriate commands or escalate.\"}}"
        exit 0
    fi
done

# Config-write ask-gate: these paths carry /tailor's propose-only contract
# (.claude/skills/tailor/SKILL.md — "/tailor proposes only, it never
# silently writes to .claude/rules/, .claude/settings.json, CLAUDE.md, or
# any other tracked config file"). A direct Write/Edit bypasses that review
# step, so ask rather than silently proceeding — deliberately "ask", not
# "deny": a legitimate direct edit (including this hardening plan's own
# commits) should still be able to proceed once confirmed.
case "$REL_PATH" in
    .claude/settings.json|.claude/rules/*|CLAUDE.md)
        echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"Editing $REL_PATH changes tracked framework configuration that /tailor normally proposes for review rather than writing directly (see tailor/SKILL.md's Output Contract). Confirm this direct edit is intentional.\"}}"
        exit 0
        ;;
esac

# Skip secret detection for test files
if [[ "$REL_PATH" == *.test.ts ]] || [[ "$REL_PATH" == *.spec.ts ]] || \
   [[ "$REL_PATH" == *.test.tsx ]] || [[ "$REL_PATH" == *.spec.tsx ]] || \
   [[ "$REL_PATH" == *.test.js ]] || [[ "$REL_PATH" == *.spec.js ]]; then
    # Test files may contain mock secrets — skip detection
    :
elif [[ "$TOOL_NAME" == "Write" || "$TOOL_NAME" == "Edit" ]]; then
    CONTENT=$(echo "$INPUT" | jq -r '.tool_input.content // .tool_input.new_string // empty' 2>/dev/null || true)

    detect_secret "$CONTENT"

    if [ "$SECRET_DETECTED" = true ]; then
        echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"Potential $SECRET_TYPE detected in content. Please verify this is not sensitive data.\"}}"
        exit 0
    fi
fi

# Acquire lock for this file atomically using mkdir
LOCK_DIR_ATOMIC="$LOCK_FILE.lock"
if mkdir "$LOCK_DIR_ATOMIC" 2>/dev/null; then
    # Successfully acquired lock
    echo "{\"session_id\": \"$SESSION_ID\", \"timestamp\": $(date +%s), \"tool\": \"$TOOL_NAME\"}" > "$LOCK_FILE"
    rmdir "$LOCK_DIR_ATOMIC"
else
    # Failed to acquire lock - deny instead of proceeding
    echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"Failed to acquire file lock - another agent may be editing this file. Wait and retry.\"}}"
    exit 0
fi

exit 0