xtrm-tools 0.7.3 → 0.7.4

package/.xtrm/skills/default/hook-development/references/patterns.md

@@ -0,0 +1,412 @@
+# Common Hook Patterns
+
+This reference provides common, proven patterns for implementing Claude Code hooks. Use these patterns as starting points for typical hook use cases.
+
+## Pattern 1: Security Validation
+
+Block dangerous file writes using prompt-based hooks:
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "File path: $TOOL_INPUT.file_path. Verify: 1) Not in /etc or system directories 2) Not .env or credentials 3) Path doesn't contain '..' traversal. Return 'approve' or 'deny'."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Use for:** Preventing writes to sensitive files or system directories.
+
+## Pattern 2: Test Enforcement
+
+Ensure tests run before stopping:
+
+```json
+{
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Review transcript. If code was modified (Write/Edit tools used), verify tests were executed. If no tests were run, block with reason 'Tests must be run after code changes'."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Use for:** Enforcing quality standards and preventing incomplete work.
+
+## Pattern 3: Context Loading
+
+Load project-specific context at session start:
+
+```json
+{
+  "SessionStart": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Example script (load-context.sh):**
+```bash
+#!/bin/bash
+cd "$CLAUDE_PROJECT_DIR" || exit 1
+
+# Detect project type
+if [ -f "package.json" ]; then
+  echo "📦 Node.js project detected"
+  echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
+elif [ -f "Cargo.toml" ]; then
+  echo "🦀 Rust project detected"
+  echo "export PROJECT_TYPE=rust" >> "$CLAUDE_ENV_FILE"
+fi
+```
+
+**Use for:** Automatically detecting and configuring project-specific settings.
+
+## Pattern 4: Notification Logging
+
+Log all notifications for audit or analysis:
+
+```json
+{
+  "Notification": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-notification.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Use for:** Tracking user notifications or integration with external logging systems.
+
+## Pattern 5: MCP Tool Monitoring
+
+Monitor and validate MCP tool usage:
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "mcp__.*__delete.*",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Deletion operation detected. Verify: Is this deletion intentional? Can it be undone? Are there backups? Return 'approve' only if safe."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Use for:** Protecting against destructive MCP operations.
+
+## Pattern 6: Build Verification
+
+Ensure project builds after code changes:
+
+```json
+{
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Check if code was modified. If Write/Edit tools were used, verify the project was built (npm run build, cargo build, etc). If not built, block and request build."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Use for:** Catching build errors before committing or stopping work.
+
+## Pattern 7: Permission Confirmation
+
+Ask user before dangerous operations:
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Command: $TOOL_INPUT.command. If command contains 'rm', 'delete', 'drop', or other destructive operations, return 'ask' to confirm with user. Otherwise 'approve'."
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Use for:** User confirmation on potentially destructive commands.
+
+## Pattern 8: Code Quality Checks
+
+Run linters or formatters on file edits:
+
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-quality.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Example script (check-quality.sh):**
+```bash
+#!/bin/bash
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path')
+
+# Run linter if applicable
+if [[ "$file_path" == *.js ]] || [[ "$file_path" == *.ts ]]; then
+  npx eslint "$file_path" 2>&1 || true
+fi
+```
+
+**Use for:** Automatic code quality enforcement.
+
+## Pattern Combinations
+
+Combine multiple patterns for comprehensive protection:
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Validate file write safety"
+        }
+      ]
+    },
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Validate bash command safety"
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Verify tests run and build succeeded"
+        }
+      ]
+    }
+  ],
+  "SessionStart": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
+        }
+      ]
+    }
+  ]
+}
+```
+
+This provides multi-layered protection and automation.
+
+## Pattern 9: Temporarily Active Hooks
+
+Create hooks that only run when explicitly enabled via flag files:
+
+```bash
+#!/bin/bash
+# Hook only active when flag file exists
+FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-security-scan"
+
+if [ ! -f "$FLAG_FILE" ]; then
+  # Quick exit when disabled
+  exit 0
+fi
+
+# Flag present, run validation
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path')
+
+# Run security scan
+security-scanner "$file_path"
+```
+
+**Activation:**
+```bash
+# Enable the hook
+touch .enable-security-scan
+
+# Disable the hook
+rm .enable-security-scan
+```
+
+**Use for:**
+- Temporary debugging hooks
+- Feature flags for development
+- Project-specific validation that's opt-in
+- Performance-intensive checks only when needed
+
+**Note:** Must restart Claude Code after creating/removing flag files for hooks to recognize changes.
+
+## Pattern 10: Configuration-Driven Hooks
+
+Use JSON configuration to control hook behavior:
+
+```bash
+#!/bin/bash
+CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/my-plugin.local.json"
+
+# Read configuration
+if [ -f "$CONFIG_FILE" ]; then
+  strict_mode=$(jq -r '.strictMode // false' "$CONFIG_FILE")
+  max_file_size=$(jq -r '.maxFileSize // 1000000' "$CONFIG_FILE")
+else
+  # Defaults
+  strict_mode=false
+  max_file_size=1000000
+fi
+
+# Skip if not in strict mode
+if [ "$strict_mode" != "true" ]; then
+  exit 0
+fi
+
+# Apply configured limits
+input=$(cat)
+file_size=$(echo "$input" | jq -r '.tool_input.content | length')
+
+if [ "$file_size" -gt "$max_file_size" ]; then
+  echo '{"decision": "deny", "reason": "File exceeds configured size limit"}' >&2
+  exit 2
+fi
+```
+
+**Configuration file (.claude/my-plugin.local.json):**
+```json
+{
+  "strictMode": true,
+  "maxFileSize": 500000,
+  "allowedPaths": ["/tmp", "/home/user/projects"]
+}
+```
+
+**Use for:**
+- User-configurable hook behavior
+- Per-project settings
+- Team-specific rules
+- Dynamic validation criteria
+
+## 10. OS Notification on Idle (Prompt or Command)
+
+A very common pattern is to notify the user when Claude is waiting for input (e.g., waiting for permission). Use the `Notification` event.
+
+### macOS (AppleScript)
+```json
+{
+  "Notification": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Linux (notify-send)
+```json
+{
+  "Notification": [
+    {
+      "matcher": "*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## 11. Quality Gate / Linting (PostToolUse)
+
+Run code quality checks immediately after Claude edits a file. If issues are found, the hook exits with `2` and outputs the errors to `stderr`. Claude sees these errors in the tool result and automatically attempts to fix them.
+
+**Key Concepts for this Pattern:**
+- Target only file modification tools: `"matcher": "Write|Edit|MultiEdit"`
+- **Speed is critical:** Use caching (e.g., TSConfig hashing) because this hook runs on *every* edit. If it takes >1s, the agent loop feels sluggish.
+- Exit code must be `2` to indicate a recoverable error to Claude.
+- Output JSON on `stderr` containing the error details.
+
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit|MultiEdit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "node ${CLAUDE_PLUGIN_ROOT}/examples/quality-check.js"
+        }
+      ]
+    }
+  ]
+}
+```
+
+*See `examples/quality-check.js` for a real-world implementation of a fast, caching TypeScript/ESLint checker.*

package/.xtrm/skills/default/hook-development/scripts/README.md

@@ -0,0 +1,164 @@
+# Hook Development Utility Scripts
+
+These scripts help validate, test, and lint hook implementations before deployment.
+
+## validate-hook-schema.sh
+
+Validates `hooks.json` configuration files for correct structure and common issues.
+
+**Usage:**
+```bash
+./validate-hook-schema.sh path/to/hooks.json
+```
+
+**Checks:**
+- Valid JSON syntax
+- Required fields present
+- Valid hook event names
+- Proper hook types (command/prompt)
+- Timeout values in valid ranges
+- Hardcoded path detection
+- Prompt hook event compatibility
+
+**Example:**
+```bash
+cd my-plugin
+./validate-hook-schema.sh hooks/hooks.json
+```
+
+## test-hook.sh
+
+Tests individual hook scripts with sample input before deploying to Claude Code.
+
+**Usage:**
+```bash
+./test-hook.sh [options] <hook-script> <test-input.json>
+```
+
+**Options:**
+- `-v, --verbose` - Show detailed execution information
+- `-t, --timeout N` - Set timeout in seconds (default: 60)
+- `--create-sample <event-type>` - Generate sample test input
+
+**Example:**
+```bash
+# Create sample test input
+./test-hook.sh --create-sample PreToolUse > test-input.json
+
+# Test a hook script
+./test-hook.sh my-hook.sh test-input.json
+
+# Test with verbose output and custom timeout
+./test-hook.sh -v -t 30 my-hook.sh test-input.json
+```
+
+**Features:**
+- Sets up proper environment variables (CLAUDE_PROJECT_DIR, CLAUDE_PLUGIN_ROOT)
+- Measures execution time
+- Validates output JSON
+- Shows exit codes and their meanings
+- Captures environment file output
+
+## hook-linter.sh
+
+Checks hook scripts for common issues and best practices violations.
+
+**Usage:**
+```bash
+./hook-linter.sh <hook-script.sh> [hook-script2.sh ...]
+```
+
+**Checks:**
+- Shebang presence
+- `set -euo pipefail` usage
+- Stdin input reading
+- Proper error handling
+- Variable quoting (injection prevention)
+- Exit code usage
+- Hardcoded paths
+- Long-running code detection
+- Error output to stderr
+- Input validation
+
+**Example:**
+```bash
+# Lint single script
+./hook-linter.sh ../examples/validate-write.sh
+
+# Lint multiple scripts
+./hook-linter.sh ../examples/*.sh
+```
+
+## Typical Workflow
+
+1. **Write your hook script**
+   ```bash
+   vim my-plugin/scripts/my-hook.sh
+   ```
+
+2. **Lint the script**
+   ```bash
+   ./hook-linter.sh my-plugin/scripts/my-hook.sh
+   ```
+
+3. **Create test input**
+   ```bash
+   ./test-hook.sh --create-sample PreToolUse > test-input.json
+   # Edit test-input.json as needed
+   ```
+
+4. **Test the hook**
+   ```bash
+   ./test-hook.sh -v my-plugin/scripts/my-hook.sh test-input.json
+   ```
+
+5. **Add to hooks.json**
+   ```bash
+   # Edit my-plugin/hooks/hooks.json
+   ```
+
+6. **Validate configuration**
+   ```bash
+   ./validate-hook-schema.sh my-plugin/hooks/hooks.json
+   ```
+
+7. **Test in Claude Code**
+   ```bash
+   claude --debug
+   ```
+
+## Tips
+
+- Always test hooks before deploying to avoid breaking user workflows
+- Use verbose mode (`-v`) to debug hook behavior
+- Check the linter output for security and best practice issues
+- Validate hooks.json after any changes
+- Create different test inputs for various scenarios (safe operations, dangerous operations, edge cases)
+
+## Common Issues
+
+### Hook doesn't execute
+
+Check:
+- Script has shebang (`#!/bin/bash`)
+- Script is executable (`chmod +x`)
+- Path in hooks.json is correct (use `${CLAUDE_PLUGIN_ROOT}`)
+
+### Hook times out
+
+- Reduce timeout in hooks.json
+- Optimize hook script performance
+- Remove long-running operations
+
+### Hook fails silently
+
+- Check exit codes (should be 0 or 2)
+- Ensure errors go to stderr (`>&2`)
+- Validate JSON output structure
+
+### Injection vulnerabilities
+
+- Always quote variables: `"$variable"`
+- Use `set -euo pipefail`
+- Validate all input fields
+- Run the linter to catch issues

package/.xtrm/skills/default/hook-development/scripts/hook-linter.sh

@@ -0,0 +1,153 @@
+#!/bin/bash
+# Hook Linter
+# Checks hook scripts for common issues and best practices
+
+set -euo pipefail
+
+# Usage
+if [ $# -eq 0 ]; then
+  echo "Usage: $0 <hook-script.sh> [hook-script2.sh ...]"
+  echo ""
+  echo "Checks hook scripts for:"
+  echo "  - Shebang presence"
+  echo "  - set -euo pipefail usage"
+  echo "  - Input reading from stdin"
+  echo "  - Proper error handling"
+  echo "  - Variable quoting"
+  echo "  - Exit code usage"
+  echo "  - Hardcoded paths"
+  echo "  - Timeout considerations"
+  exit 1
+fi
+
+check_script() {
+  local script="$1"
+  local warnings=0
+  local errors=0
+
+  echo "🔍 Linting: $script"
+  echo ""
+
+  if [ ! -f "$script" ]; then
+    echo "❌ Error: File not found"
+    return 1
+  fi
+
+  # Check 1: Executable
+  if [ ! -x "$script" ]; then
+    echo "⚠️  Not executable (chmod +x $script)"
+    ((warnings++))
+  fi
+
+  # Check 2: Shebang
+  first_line=$(head -1 "$script")
+  if [[ ! "$first_line" =~ ^#!/ ]]; then
+    echo "❌ Missing shebang (#!/bin/bash)"
+    ((errors++))
+  fi
+
+  # Check 3: set -euo pipefail
+  if ! grep -q "set -euo pipefail" "$script"; then
+    echo "⚠️  Missing 'set -euo pipefail' (recommended for safety)"
+    ((warnings++))
+  fi
+
+  # Check 4: Reads from stdin
+  if ! grep -q "cat\|read" "$script"; then
+    echo "⚠️  Doesn't appear to read input from stdin"
+    ((warnings++))
+  fi
+
+  # Check 5: Uses jq for JSON parsing
+  if grep -q "tool_input\|tool_name" "$script" && ! grep -q "jq" "$script"; then
+    echo "⚠️  Parses hook input but doesn't use jq"
+    ((warnings++))
+  fi
+
+  # Check 6: Unquoted variables
+  if grep -E '\$[A-Za-z_][A-Za-z0-9_]*[^"]' "$script" | grep -v '#' | grep -q .; then
+    echo "⚠️  Potentially unquoted variables detected (injection risk)"
+    echo "   Always use double quotes: \"\$variable\" not \$variable"
+    ((warnings++))
+  fi
+
+  # Check 7: Hardcoded paths
+  if grep -E '^[^#]*/home/|^[^#]*/usr/|^[^#]*/opt/' "$script" | grep -q .; then
+    echo "⚠️  Hardcoded absolute paths detected"
+    echo "   Use \$CLAUDE_PROJECT_DIR or \$CLAUDE_PLUGIN_ROOT"
+    ((warnings++))
+  fi
+
+  # Check 8: Uses CLAUDE_PLUGIN_ROOT
+  if ! grep -q "CLAUDE_PLUGIN_ROOT\|CLAUDE_PROJECT_DIR" "$script"; then
+    echo "💡 Tip: Use \$CLAUDE_PLUGIN_ROOT for plugin-relative paths"
+  fi
+
+  # Check 9: Exit codes
+  if ! grep -q "exit 0\|exit 2" "$script"; then
+    echo "⚠️  No explicit exit codes (should exit 0 or 2)"
+    ((warnings++))
+  fi
+
+  # Check 10: JSON output for decision hooks
+  if grep -q "PreToolUse\|Stop" "$script"; then
+    if ! grep -q "permissionDecision\|decision" "$script"; then
+      echo "💡 Tip: PreToolUse/Stop hooks should output decision JSON"
+    fi
+  fi
+
+  # Check 11: Long-running commands
+  if grep -E 'sleep [0-9]{3,}|while true' "$script" | grep -v '#' | grep -q .; then
+    echo "⚠️  Potentially long-running code detected"
+    echo "   Hooks should complete quickly (< 60s)"
+    ((warnings++))
+  fi
+
+  # Check 12: Error messages to stderr
+  if grep -q 'echo.*".*error\|Error\|denied\|Denied' "$script"; then
+    if ! grep -q '>&2' "$script"; then
+      echo "⚠️  Error messages should be written to stderr (>&2)"
+      ((warnings++))
+    fi
+  fi
+
+  # Check 13: Input validation
+  if ! grep -q "if.*empty\|if.*null\|if.*-z" "$script"; then
+    echo "💡 Tip: Consider validating input fields aren't empty"
+  fi
+
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  if [ $errors -eq 0 ] && [ $warnings -eq 0 ]; then
+    echo "✅ No issues found"
+    return 0
+  elif [ $errors -eq 0 ]; then
+    echo "⚠️  Found $warnings warning(s)"
+    return 0
+  else
+    echo "❌ Found $errors error(s) and $warnings warning(s)"
+    return 1
+  fi
+}
+
+echo "🔎 Hook Script Linter"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo ""
+
+total_errors=0
+
+for script in "$@"; do
+  if ! check_script "$script"; then
+    ((total_errors++))
+  fi
+  echo ""
+done
+
+if [ $total_errors -eq 0 ]; then
+  echo "✅ All scripts passed linting"
+  exit 0
+else
+  echo "❌ $total_errors script(s) had errors"
+  exit 1
+fi