claude-permissions-hook

claude-permissions-hook

A permission hook for Claude Code with granular rule-based control. Provides fine-grained, context-aware permission decisions for Claude Code tool calls — allowing safe commands automatically while prompting or blocking risky ones.

Installation

Install as a Claude Code plugin:

claude plugin add npm:claude-permissions-hook

Or install from npm directly:

npm install -g claude-permissions-hook

Usage

The hook runs automatically as a Claude Code PreToolUse hook. It reads tool call details from stdin and returns a permission decision (allow, ask, or deny) on stdout.

# Test the hook manually
echo '{"session_id":"s","transcript_path":"/tmp/t","cwd":"/tmp","permission_mode":"default","hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git status"},"tool_use_id":"t"}' | claude-permissions-hook hook --config my-config.kdl

Permission Modes

The hook respects Claude Code's permission modes. allow and deny from config are absolute. ask is modulated by mode:

Config Decision	bypassPermissions	dontAsk	default / plan / acceptEdits
allow	allow	allow	allow
deny	deny	deny	deny
ask	allow	deny	ask
unlisted	—	—	—

Unlisted programs (not in any config list) return no opinion — Claude handles them natively.

Configuration

The hook discovers your config automatically in this order:

1. --config /path/to/config.kdl (explicit CLI argument)
2. $CLAUDE_PERMISSIONS_HOOK_CONFIG environment variable
3. ~/.config/claude-permissions-hook/config.kdl (XDG default)

If no config is found, the hook returns ask for everything — prompting you to set one up.

# Explicit path
claude-permissions-hook hook --config ~/.config/claude-permissions.kdl

# Or set the environment variable
export CLAUDE_PERMISSIONS_HOOK_CONFIG=~/.config/claude-permissions.kdl

# Or place it in the default location
mkdir -p ~/.config/claude-permissions-hook
cp example-config.kdl ~/.config/claude-permissions-hook/config.kdl

Config Format (KDL)

bash {
    allow "git" "cargo" "npm" "node" "ls" "cat" "echo"
    deny "rm" "shutdown" "reboot"
    ask "docker" "kubectl" "curl"
}

• allow — auto-approve these programs
• deny — always block these programs
• ask — prompt for confirmation (modulated by permission mode)
• unlisted — programs not in any list get no opinion from the hook

Lookup precedence: deny > ask > allow.

Multi-Command Handling

For chained commands (&&, ||, ;, |), the hook evaluates each program and takes the most restrictive decision. If any program is denied, the whole command is denied.

Without a config (no --config, no env var, no default file), the hook returns ask for everything, prompting you to set up a config file.

Command-Wrapper Transparency

The hook evaluates programs by their actual name, unwrapping a small set of transparent launchers automatically:

Transparent launchers
command, env, nohup, exec, builtin

For example, env TERM=xterm git status is evaluated as git, not env.

Limitation: Launchers not in this list (e.g. sudo, nice, time, xargs) are evaluated as the program name itself — the wrapped target is not inspected.

This means a config like:

bash {
    allow "sudo"
    deny "rm"
}

will allow sudo rm -rf / (evaluated as sudo, which is in the allow list) — the deny "rm" rule does not fire.

Guidance: Avoid pairing allow rules on unlisted launchers with deny rules on their potential targets. Either deny the launcher itself, or add the target explicitly:

bash {
    deny "sudo"   # block sudo entirely
    deny "rm"
}

Development

See CONTRIBUTING.md for development setup, running tests, and code style guidelines.

Quick Start

# Build
cargo build

# Run tests
cargo nextest run

# Lint
cargo clippy --all-targets

# Format
cargo fmt

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before submitting a pull request.

License

MIT — see LICENSE file.