Tool Gate Hook

tool-gate-hook

A PreToolUse hook for Claude Code and GitHub Copilot CLI (macOS, local CLI only) that does two jobs:

1. Gate: auto-allow, auto-deny, or force a prompt (ask) for tool calls, using rules you write in a TOML file. Anything no rule matches passes through to the agent's normal permission flow.
2. Observe: record every call to a JSONL audit log with the raw payload, which rules matched, in order, and which one decided. When an agent changes what it sends, the log shows you.

Both agents use the same rule engine; only the payload shape and tool names differ.

This is a workaround for the limits of the agents' built-in permission rules (for example, Bash permissions that don't hold up against a && b). It is small and rule-driven, and you need Rust to build it.
This has changed since I blogged about it. It was claude-code-permissions-hook, a Claude-only hook with [[allow]] / [[deny]] rules; it has since been renamed, given a new config format and taught to work with Copilot CLI. To see the code as it was when the blog post was written, browse the repository at that commit.

Install

Requires Rust (rustup).

This puts tool-gate-hook in ~/.cargo/bin. Agents may run hooks with a PATH that doesn't include ~/.cargo/bin; if the hook doesn't fire, use the absolute path (e.g. /Users/you/.cargo/bin/tool-gate-hook) in the registration commands below.

Quick start

Copy an example config to the default location for your agent and edit it:

--agent is required (there is no auto-detection) and --config PATH overrides the default location.

A minimal config:

See the Configuration guide for every option.

Registering the hook

User level (typical)

Claude Code, in ~/.claude/settings.json:

Copilot CLI, in ~/.copilot/hooks/tool-gate-hook.json:

Project level (opt-in)

For a…