tool-gates

---

Features

Feature	Description
Approval Learning	Tracks approved commands and saves patterns to settings.json via TUI or CLI
Settings Integration	Respects your settings.json allow/deny/ask rules - won't bypass your explicit permissions
Accept Edits Mode	Auto-allows file-editing commands (sd, prettier --write, etc.) when in acceptEdits mode
Modern CLI Hints	Suggests modern alternatives (bat, rg, fd, etc.) via additionalContext for Claude to learn
AST Parsing	Uses tree-sitter-bash for accurate command analysis
Compound Commands	Handles &&, ||, |, ; chains correctly
Security First	Catches pipe-to-shell, eval, command injection patterns
Unknown Protection	Unrecognized commands require approval
Claude Code Plugin	Install as a plugin with the /tool-gates:review skill for interactive approval management
400+ Commands	13 specialized gates with comprehensive coverage
File Guards	Blocks symlinked AI config files (CLAUDE.md, .cursorrules, etc.) to prevent confused reads/edits
Security Reminders	Scans Write/Edit content for 26 anti-patterns (secrets, XSS, injection, etc.) across 3 tiers
Tool Blocking	Configurable rules to block tools (Glob, Grep, firecrawl on GitHub) with domain filtering
Skill Auto-Approval	Auto-approve Skill tool calls based on project directory conditions. No external hook scripts needed
Configuration	~/.config/tool-gates/config.toml for feature toggles, custom block rules, and file guard extensions
Health Check	tool-gates doctor verifies config, hooks, cache files, and flags legacy remnants
Fast	Static native binary, no interpreter overhead

---

How It Works

flowchart TD
    CC[Claude Code] --> TOOL{Tool Type}
    TOOL -->|Bash| CMD[Bash Command]
    TOOL -->|Write/Edit| FILE[File Operation]

    subgraph PTU [PreToolUse Hook]
        direction TB
        PTU_CHECK[tool-gates check] --> PTU_DEC{Decision}
        PTU_DEC -->|dangerous| PTU_DENY[deny]
        PTU_DEC -->|risky| PTU_ASK[ask + track]
        PTU_DEC -->|safe| PTU_CTX{Context?}
        PTU_CTX -->|main session| PTU_ALLOW[allow ✓]
        PTU_CTX -->|subagent| PTU_IGNORED[ignored by Claude]
    end

    subgraph PTU_FILE [PreToolUse - File Tools]
        direction TB
        FG[Symlink guard] --> FG_DEC{Symlink?}
        FG_DEC -->|guarded symlink| FG_DENY[deny - use real path]
        FG_DEC -->|ok| SEC{Content scan}
        SEC -->|hardcoded secret| SEC_DENY[deny - Tier 1]
        SEC -->|safe| SEC_PASS[pass through]
    end

    CMD --> PTU
    FILE --> PTU_FILE

    PTU_IGNORED --> INTERNAL[Claude internal checks]
    INTERNAL -->|path outside cwd| PR_HOOK

    subgraph PR_HOOK [PermissionRequest Hook]
        direction TB
        PR_CHECK[tool-gates re-check] --> PR_DEC{Decision}
        PR_DEC -->|safe| PR_ALLOW[allow ✓]
        PR_DEC -->|dangerous| PR_DENY[deny]
        PR_DEC -->|risky| PR_PROMPT[show prompt]
    end