anchi-kit 1.2.0 → 1.2.1

package/.antigravity/skills/claude-code/references/hooks-comprehensive.md

@@ -0,0 +1,622 @@
+# Hooks System - Comprehensive Guide
+
+Event-driven automation framework for Cursor with deterministic shell commands and LLM evaluations.
+
+## Quick Reference
+
+**Hook Types**: Command-based (bash) | Prompt-based (LLM evaluation)
+**Configuration**: `.cursor/settings.json` (4-tier hierarchy)
+**Events**: 10 lifecycle triggers
+**Matchers**: Exact, regex, wildcard patterns
+**Security**: User assumes full responsibility
+
+## Hook Events (10 Total)
+
+| Event | Trigger Point | Common Use Cases |
+|-------|---------------|------------------|
+| **PreToolUse** | Before tool processing | Validation, blocking operations |
+| **PermissionRequest** | Permission dialog display | Custom permission logic |
+| **PostToolUse** | After tool completion | Post-processing, auto-formatting, logging |
+| **Notification** | Notification sent | Desktop alerts, custom notifications |
+| **UserPromptSubmit** | User prompt submission | Input validation, filtering |
+| **Stop** | Main agent response complete | Session cleanup, logging |
+| **SubagentStop** | Subagent completion | Subagent monitoring |
+| **PreCompact** | Before compaction | Pre-compaction validation |
+| **SessionStart** | Session init/resume | Environment setup |
+| **SessionEnd** | Session termination | Cleanup operations |
+
+## Configuration Structure
+
+### Settings Hierarchy (Priority Order)
+
+1. **Enterprise managed**: `managed-settings.json` (IT-deployed, cannot override)
+2. **User settings**: `~/.cursor/settings.json` (global defaults)
+3. **Project settings**: `.cursor/settings.json` (team-shared, version controlled)
+4. **Local settings**: `.cursor/settings.local.json` (personal, git-ignored)
+
+### Basic Configuration
+
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolPattern",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash script command"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Tool Matchers
+
+**Exact matching**:
+```json
+"matcher": "Bash"
+```
+
+**Regex patterns**:
+```json
+"matcher": "Edit|Write"
+```
+
+**Wildcard (all tools)**:
+```json
+"matcher": "*"
+```
+
+**MCP tools**:
+```json
+"matcher": "mcp__servername__toolname"
+```
+
+**Built-in tools**: Write, Edit, Read, Bash, Task, Grep, Glob, WebFetch, WebSearch, NotebookEdit, SlashCommand, Skill
+
+## Hook Types
+
+### 1. Command-Based Hooks
+
+Execute bash scripts with full shell capabilities.
+
+**Configuration**:
+```json
+{
+  "type": "command",
+  "command": "jq -r '.tool_parameters.command' | tee -a .cursor/commands.log"
+}
+```
+
+**Input**: JSON via stdin with fields:
+- `session_id`: Current session identifier
+- `transcript_path`: Path to session transcript
+- `cwd`: Current working directory
+- `permission_mode`: Current permission setting
+- `hook_event_name`: Triggering event name
+- Event-specific fields (varies by hook)
+
+**Output Control**:
+- Exit code 0: Success, continue execution
+- Exit code 2: Blocking error, halt execution
+- Optional JSON output:
+  ```json
+  {
+    "continue": false,
+    "stopReason": "Reason for blocking",
+    "decision": {}
+  }
+  ```
+
+### 2. Prompt-Based Hooks
+
+Leverage LLM evaluation for context-aware decisions.
+
+**Supported Events**: Stop, SubagentStop only
+
+**Configuration**:
+```json
+{
+  "type": "prompt",
+  "prompt": "Analyze the session transcript and determine if...",
+  "model": "claude-3-5-sonnet-20241022"
+}
+```
+
+**Output**: Structured JSON response based on LLM evaluation
+
+## Common Use Cases
+
+### Auto-Formatting (PostToolUse)
+
+Automatically format code after edits.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(echo \"$INPUT\" | jq -r '.tool_parameters.file_path'); case \"$FILE\" in *.ts|*.js) npx prettier --write \"$FILE\" ;; *.go) gofmt -w \"$FILE\" ;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Script version** (`scripts/format-code.sh`):
+```bash
+#!/bin/bash
+FILE=$(jq -r '.tool_parameters.file_path')
+
+case "$FILE" in
+  *.ts|*.tsx|*.js|*.jsx)
+    npx prettier --write "$FILE"
+    ;;
+  *.go)
+    gofmt -w "$FILE"
+    ;;
+  *.py)
+    black "$FILE"
+    ;;
+esac
+```
+
+### File Protection (PreToolUse)
+
+Block modifications to sensitive files.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FILE=$(echo \"$INPUT\" | jq -r '.tool_parameters.file_path'); case \"$FILE\" in .env|*package-lock.json|.git/*) echo '{\"continue\":false,\"stopReason\":\"Protected file\"}'; exit 2 ;; esac"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Desktop Notifications (Notification)
+
+Custom alerts when Claude needs input.
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "MESSAGE=$(jq -r '.message'); notify-send 'Cursor' \"$MESSAGE\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Command Logger (PreToolUse)
+
+Track bash commands for compliance.
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '.tool_parameters | \"\\(.command) - \\(.description)\"' >> .cursor/commands.log"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Markdown Enhancement (PostToolUse)
+
+Auto-detect code block languages.
+
+```bash
+#!/usr/bin/env python3
+# scripts/enhance-markdown.py
+import json, sys, re
+
+data = json.load(sys.stdin)
+file_path = data['tool_parameters']['file_path']
+
+if not file_path.endswith('.md'):
+    sys.exit(0)
+
+with open(file_path, 'r') as f:
+    content = f.read()
+
+# Detect unlabeled code blocks and add language tags
+enhanced = re.sub(
+    r'```\n((?:import|function|const|let|var|class)\b.*?)```',
+    r'```javascript\n\1```',
+    content,
+    flags=re.DOTALL
+)
+
+with open(file_path, 'w') as f:
+    f.write(enhanced)
+```
+
+**Configuration**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 scripts/enhance-markdown.py"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Environment Variables
+
+**Available in all hooks**:
+- `$CLAUDE_PROJECT_DIR`: Project root path
+- `${CLAUDE_PLUGIN_ROOT}`: Plugin directory path
+
+**SessionStart only**:
+- `CLAUDE_ENV_FILE`: Persist environment variables across session
+
+**Hook input via stdin**: All data passed as JSON (parse with `jq`)
+
+## Security Framework
+
+### Critical Considerations
+
+- Users assume **full responsibility** for hook commands
+- Hooks execute with **user's environment credentials**
+- Malicious hooks can **exfiltrate data**
+
+### Best Practices
+
+**Input Validation**:
+```bash
+# Validate file paths
+FILE=$(jq -r '.tool_parameters.file_path')
+if [[ ! "$FILE" =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
+  echo '{"continue":false,"stopReason":"Invalid path"}' && exit 2
+fi
+```
+
+**Proper Quoting**:
+```bash
+# Always quote variables
+FILE=$(jq -r '.tool_parameters.file_path')
+prettier --write "$FILE"  # Correct
+prettier --write $FILE    # Wrong - vulnerable to injection
+```
+
+**Path Traversal Prevention**:
+```bash
+# Use absolute paths and validate
+REALPATH=$(realpath "$FILE")
+if [[ ! "$REALPATH" =~ ^"$CLAUDE_PROJECT_DIR" ]]; then
+  echo '{"continue":false,"stopReason":"Path outside project"}' && exit 2
+fi
+```
+
+**Command Whitelisting**:
+```bash
+# Whitelist allowed commands
+COMMAND=$(jq -r '.tool_parameters.command')
+case "$COMMAND" in
+  npm\ install|npm\ test|npm\ run\ *)
+    # Allowed
+    ;;
+  *)
+    echo '{"continue":false,"stopReason":"Command not allowed"}' && exit 2
+    ;;
+esac
+```
+
+## Hook Management
+
+### Setup via /hooks Command
+
+```bash
+claude
+> /hooks
+```
+
+Interactive setup wizard for hook configuration.
+
+### Manual Configuration
+
+Edit `.cursor/settings.json` or `.cursor/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [...],
+    "PostToolUse": [...]
+  }
+}
+```
+
+### Testing Hooks
+
+```bash
+# Enable debug mode
+claude --debug
+
+# Test hook with sample input
+echo '{"session_id":"test","tool_parameters":{"command":"ls"}}' | bash scripts/test-hook.sh
+```
+
+### Debugging
+
+**Check logs**:
+```bash
+cat .cursor/logs/hooks.log
+```
+
+**Common issues**:
+- Verify script permissions: `chmod +x scripts/*.sh`
+- Check JSON syntax in settings
+- Validate script paths (relative to project root)
+- Test stdin parsing: `echo '{}' | jq`
+
+## Plugin Integration
+
+Hooks can be bundled in plugins for distribution.
+
+**Plugin structure**:
+```
+my-plugin/
+├── plugin.json
+├── hooks/
+│   └── settings.json  # Hook configurations
+└── scripts/
+    └── hook-script.sh
+```
+
+**plugin.json**:
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Plugin with hooks",
+  "hooks": "hooks/settings.json"
+}
+```
+
+**hooks/settings.json**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/hook-script.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Advanced Patterns
+
+### Conditional Execution
+
+```bash
+#!/bin/bash
+# Only run in production branch
+BRANCH=$(git branch --show-current)
+if [[ "$BRANCH" == "main" ]]; then
+  # Execute hook logic
+  echo "Running on production"
+fi
+```
+
+### Multi-step Processing
+
+```bash
+#!/bin/bash
+FILE=$(jq -r '.tool_parameters.file_path')
+
+# Step 1: Format
+prettier --write "$FILE"
+
+# Step 2: Lint
+eslint --fix "$FILE"
+
+# Step 3: Test
+npm test -- "$FILE"
+```
+
+### Notification Integration
+
+```bash
+#!/bin/bash
+# Slack webhook notification
+MESSAGE=$(jq -r '.message')
+curl -X POST "$SLACK_WEBHOOK_URL" \
+  -H 'Content-Type: application/json' \
+  -d "{\"text\":\"$MESSAGE\"}"
+```
+
+### Error Handling
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+FILE=$(jq -r '.tool_parameters.file_path')
+
+# Validate file exists
+if [[ ! -f "$FILE" ]]; then
+  echo '{"continue":false,"stopReason":"File not found"}' >&2
+  exit 2
+fi
+
+# Process file
+prettier --write "$FILE" || {
+  echo '{"continue":false,"stopReason":"Format failed"}' >&2
+  exit 2
+}
+```
+
+## Performance Considerations
+
+**Keep hooks fast**: <100ms execution time ideal
+
+**Async operations**:
+```bash
+#!/bin/bash
+# Run in background for long operations
+{
+  # Long-running task
+  npm run build
+} &
+```
+
+**Caching**:
+```bash
+#!/bin/bash
+CACHE_FILE=".cursor/cache/format-cache"
+FILE_HASH=$(md5sum "$FILE" | cut -d' ' -f1)
+
+# Check cache
+if grep -q "$FILE_HASH" "$CACHE_FILE" 2>/dev/null; then
+  echo "Using cached result" >&2
+  exit 0
+fi
+
+# Process and cache
+prettier --write "$FILE"
+echo "$FILE_HASH" >> "$CACHE_FILE"
+```
+
+## Example: Complete Hook System
+
+**File**: `.cursor/settings.json`
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .cursor/scripts/validate-bash.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .cursor/scripts/protect-files.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .cursor/scripts/auto-format.sh"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .cursor/scripts/desktop-notify.sh"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash .cursor/scripts/log-usage.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Review the session and log key accomplishments.",
+            "model": "claude-3-5-sonnet-20241022"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Reference Links
+
+- **Hooks Guide**: https://code.cursor.com/docs/en/hooks-guide
+- **Hooks API Reference**: https://code.cursor.com/docs/en/hooks
+- **Settings Configuration**: https://code.cursor.com/docs/en/settings
+- **Plugins Reference**: https://code.cursor.com/docs/en/plugins-reference
+- **GitHub Examples**: https://github.com/anthropics/claude-code/tree/main/examples/hooks
+
+## See Also
+
+- **Settings**: `references/configuration.md`
+- **Plugins**: `references/hooks-and-plugins.md` (plugin-specific)
+- **MCP Integration**: `references/mcp-integration.md`
+- **Security Best Practices**: `references/best-practices.md`