crush-hooks

Crush Hooks

Hooks are user-defined commands in crush.json that fire at specific points during execution, giving deterministic control over tool behavior. They run before permission checks and only on the top-level agent's tool calls — sub-agent calls (task tool, agentic_fetch, etc.) are not intercepted, though the sub-agent tool call itself is.

For the full reference, see docs/hooks/README.md. This skill covers what you need to author correct hooks.

Supported Events

Only PreToolUse is currently supported. Event names are case-insensitive and accept snake_case (PreToolUse, pretooluse, pre_tool_use all work).

Configuration

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^bash$",              // regex against tool name (optional; omit to match all)
        "command": "./hooks/my-hook.sh",   // required: shell command to run
        "timeout": 10                     // optional: seconds, default 30
      }
    ]
  }
}

Project-level hooks take precedence over global. Matching hooks are deduped by command, run in parallel, and aggregated in config order (not finish order).

Language

command is a shell command, so hooks can be written in any language by invoking the interpreter: node ./hooks/h.js, python3 ./hooks/h.py, ./hooks/h.sh, inline echo '…', etc. The rest of this skill shows bash, but the input/output contract is identical regardless of language.

Input

Environment variables:

Variable	Description
CRUSH_EVENT	Event name (e.g. PreToolUse)
CRUSH_TOOL_NAME	Tool being called (e.g. bash)
CRUSH_SESSION_ID	Current session ID
CRUSH_CWD	Working directory
CRUSH_PROJECT_DIR	Project root directory
CRUSH_TOOL_INPUT_COMMAND	For bash calls: the shell command
CRUSH_TOOL_INPUT_FILE_PATH	For file tools: the target file path

JSON on stdin:

{
  "event": "PreToolUse",
  "session_id": "313909e",
  "cwd": "/home/user/project",
  "tool_name": "bash",
  "tool_input": {"command": "rm -rf /"}
}

Output

Communicate back via exit code (+ stderr) or JSON on stdout.