Tool Gates

Tool Gates evaluates shell commands, file operations, and tool calls before they run. It combines tree-sitter parsing with a non-configurable safety floor and per-tool policy, then returns the narrowest safe decision for the active client.

Read the documentation →

Why Tool Gates? · Quick start · How it works · Clients · Configuration

[!IMPORTANT]

Claude Code Auto Mode changes the job of a permission hook. New Claude Code sessions on Pro, Max, and Team plans use Auto Mode by default unless a different default is already pinned. Auto Mode does not bypass Tool Gates. Tool Gates still evaluates each supported hook call before Claude's classifier: known-safe calls can run, hard-denied calls remain blocked, and selected irreversible actions can still require a human. See Tool Gates and Auto Mode and Anthropic's rollout announcement.

Why Tool Gates?

Native permission systems have different wire formats, defaults, and ideas of what counts as safe. Tool Gates puts one predictable policy layer in front of them.

Without a shared gate	With Tool Gates
Repeated prompts encourage broad, permanent allow rules	Known-safe operations can be approved precisely
Text matching misses shell structure inside chains and pipelines	Commands are parsed as syntax with tree-sitter-bash
A probabilistic classifier makes every borderline decision	Deterministic denials and explicit human holds run first
Client behavior drifts across Claude, Codex, and Antigravity	One gate engine renders a client-native result
An approval disappears after the session	Successful human approvals can be reviewed and saved intentionally

Tool Gates is a guardrail layer, not a sandbox or a replacement for code review. Its purpose is to reduce needless friction while keeping deterministic policy in the loop as agents become more autonomous.

Quick start

Install with Homebrew on macOS or Linux:

brew install camjac251/tap/tool-gates

Add the Claude Code hooks and verify the installation:

tool-gates hooks add -s user
tool-gates doctor

For binaries, Cargo installation, and upgrades, see the installation guide.

tool-gates hooks add --codex
tool-gates doctor

# User hooks: ~/.gemini/config/hooks.json
tool-gates hooks add --antigravity

# Optional project hooks: .agents/hooks.json
tool-gates hooks add --antigravity -s project

# Add native allow rules for recognized read-only commands
tool-gates agy allowlist --apply

tool-gates doctor

Gemini CLI support is deprecated and retained only for existing installations. New Google client integrations should target Antigravity.

tool-gates hooks add --gemini
tool-gates doctor

How it works

Every supported client is normalized into the same gate pipeline. Raw-command checks run before AST parsing, configured rules are merged with the deterministic safety floor, and only then is the result translated into the client's native hook format.

flowchart LR
    CALL[Tool call] --> NORMALIZE[Normalize client input]
    NORMALIZE --> FLOOR[Raw safety floor]
    FLOOR --> PARSE[Parse command or inspect tool input]
    PARSE --> GATES[Apply gates and settings]
    GATES --> DECISION{Decision}

    DECISION -->|allow| RUN[Execute]
    DECISION -->|deny| STOP[Block with reason and recovery]
    DECISION -->|ask or defer| CLIENT{Client permission layer}

    CLIENT -->|Claude Auto| CLASSIFIER[Safety classifier]
    CLIENT -->|Manual or held ask| HUMAN[Human approval]
    CLIENT -->|Codex or Antigravity| NATIVE[Native policy]

    CLASSIFIER --> RUN
    CLASSIFIER --> STOP
    HUMAN --> RUN
    HUMAN --> STOP
    NATIVE --> RUN
    NATIVE --> STOP

    RUN --> POST[Post-tool reminders and approval tracking]

Engine outcome	Meaning	What happens next
Allow	The operation matches known-safe policy	It runs immediately where the client honors hook allows
Ask / defer	The operation is mutating, unknown, or needs another decision	The user, Claude's Auto classifier, or the client's native policy decides
Deny	The safety floor or an explicit block rule rejected the operation	Execution stops with a specific reason and, when available, a safer recovery action

Read the architecture and hook model for the full precedence and serialization contracts.

Tool Gates and Auto Mode

Auto Mode replaces many human approval prompts with a separate safety classifier. It does not make deterministic hooks redundant; it changes which layer resolves an undecided call.

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗