claude-hooks

claude-hooks is a smart PreToolUse hook designed specifically for Claude Code. This innovative tool disassembles complex Bash commands—such as those using operators like &&, ||, ;, |, $(), and newlines—into their individual components. Each sub-command is analyzed against a set of configurable permit/deny patterns defined in your Claude Code settings, ensuring a precise control over command execution.

Key Features

• Enhanced Command Validation: Unlike the default permission system, which evaluates commands as single strings, this hook scrutinizes each part of the compound command. This ensures that any potential threats are identified and handled accordingly.

• Automatic Execution: Once installed and configured, the hook automatically activates with every Bash command, enforcing existing permission patterns at the granularity of individual sub-commands.

Functionality Overview

When a command is executed, the hook processes it as follows:

1. It receives the command invocation as JSON.
2. Each compound command is decomposed into its base commands.
3. The hook loads permission patterns from multiple settings layers:
   • Global configuration: ~/.claude/settings.json
   • Project-level configuration (committed): $CLAUDE_PROJECT_DIR/.claude/settings.json
   • Local project configuration (ignored by git): $CLAUDE_PROJECT_DIR/.claude/settings.local.json
4. Each sub-command is checked against deny patterns first, followed by allow patterns.
5. A JSON response is generated to indicate the permission decision.

Command Decomposition

The hook effectively splits compound commands across various operators:

Operator	Example
&&	git add . && git commit -m "msg"
`
;	echo a; echo b
`	`
newline	Multi-line commands are split
$()	echo $(whoami)
backticks	echo `date`

Normalization Process

Before evaluating each sub-command:

• Environment Variables: Prefixes such as EDITOR=vim are stripped.
• I/O Redirections: Elements like ls > out.txt are excluded.
• Keyword Stripping: Keywords like then are disregarded when followed by actual commands.
• Whitespace Collapsing: Multiple spaces are reduced to a single space.

Matching Logic

The hook follows a strict decision-making structure:

1. A deny pattern match at any level results in the denial of the entire command.
2. A command is allowed only if every sub-command corresponds with the defined allow patterns.
3. If neither condition is met, a silent exit invokes the default prompting for permissions.

Troubleshooting & Testing

In case of permission issues, users can debug by breaking down commands and checking which sub-command fails to match the allow patterns. The hook also supports simulated command execution for testing decisions against patterns directly.

With claude-hooks, maintain strict control over command execution while maximizing the flexibility of using compound Bash commands safely.