smartworldarafath/Google_Antigravity_Plugins / plugins/antigravity-plugin-dev/skills/hook-development
hook-development
VerifiedThis skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${ANTIGRAVITY_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Google Antigravity plugin hooks with focus on advanced prompt-based hooks API.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 16.2 KB |
| examples/load-context.sh | script | 1.7 KB |
| examples/validate-bash.sh | script | 1.3 KB |
| examples/validate-write.sh | script | 1.2 KB |
| references/advanced.md | markdown | 10.0 KB |
| references/migration.md | markdown | 8.2 KB |
| references/patterns.md | markdown | 7.1 KB |
| scripts/README.md | markdown | 3.7 KB |
| scripts/hook-linter.sh | script | 4.1 KB |
| scripts/test-hook.sh | script | 5.2 KB |
| scripts/validate-hook-schema.sh | script | 5.0 KB |
references/advanced.md
View on GitHub# Advanced Hook Use Cases
This reference covers advanced hook patterns and techniques for sophisticated automation workflows.
## Multi-Stage Validation
Combine command and prompt hooks for layered validation:
```json
{
"PreToolUse": [
{
"matcher": "run_command",
"hooks": [
{
"type": "command",
"command": "bash ${ANTIGRAVITY_PLUGIN_ROOT}/scripts/quick-check.sh",
"timeout": 5
},
{
"type": "prompt",
"prompt": "Deep analysis of bash command: $TOOL_INPUT",
"timeout": 15
}
]
}
]
}
```
**Use case:** Fast deterministic checks followed by intelligent analysis
**Example quick-check.sh:**
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Immediate approval for safe commands
if [[ "$command" =~ ^(ls|pwd|echo|date|whoami)$ ]]; then
exit 0
fi
# Let prompt hook handle complex cases
exit 0
```
The command hook quickly approves obviously safe commands, while the prompt hook analyzes everything else.
## Conditional Hook Execution
Execute hooks based on environment or context:
```bash
#!/bin/bash
# Only run in CI environment
if [ -z "$CI" ]; then
echo '{"continue": true}' # Skip in non-CI
exit 0
fi
# Run validation logic in CI
input=$(cat)
# ... validation code ...
```
**Use cases:**
- Different behavior in CI vs local development
- Project-specific validation
- User-specific rules
**Example: Skip certain checks for trusted users:**
```bash
#!/bin/bash
# Skip detailed checks for admin users
if [ "$USER" = "admin" ]; then
exit 0
fi
# Full validation for other users
input=$(cat)
# ... validation code ...
```
## Hook Chaining via State
Share state between hooks using temporary files:
```bash
# Hook 1: Analyze and save state
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Analyze command
risk_level=$(calculate_risk "$command")
echo "$risk_level" > /tmp/hook-state-$$
exit 0
```
```bash
# Hook 2: Use saved state
#!/bin/bash
risk_level=$(cat /tmp/hook-state-$$ 2>/dev/null || echo "unknown")
if [ "$risk_level" = "high" ]; then
echo "High risk operation detected" >&2
exit 2
fi
```
**Important:** This only works for sequential hook events (e.g., PreToolUse then PostToolUse), not parallel hooks.
## Dynamic Hook Configuration
Modify hook behavior based on project configuration:
```bash
#!/bin/bash
cd "$CLAUDE_PROJECT_DIR" || exit 1
# view_file project-specific config
if [ -f ".claude-hooks-config.json" ]; then
strict_mode=$(jq -r '.strict_mode' .claude-hooks-config.json)
if [ "$strict_mode" = "true" ]; then
# Apply strict validation
# ...
else
# Apply lenient validation
# ...
fi
fi
```
**Example .claude-hooks-config.json:**
```json
{
"strict_mode": true,
"allowed_commands": ["ls", "pwd", "grep"],
"forbidden_paths": ["/etc", "/sys"]
}
```
## Context-Aware Prompt Hooks
Use transcript and session context for intelligent decisions:
```json
{
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Review the full transcript at $TRANSCRIPT_PATH. Check: 1) Were tests run after code changes? 2) Did the build succeed? 3) Were all user questions answered? 4) Is there any unfinished work? Return 'approve' only if everything is complete."
}
]
}
]
}
```
The LLM can read the transcript file and make context-aware decisions.
## Performance Optimization
### Caching Validation Results
```bash
#!/bin/bash
input=$(cat)
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
cache_key=$(echo -n "$file_path" | md5sum | cut -d' ' -f1)
cache_file="/tmp/hook-cache-$cache_key"
# Check cache
if [ -f "$cache_file" ]; then
cache_age=$(($(date +%s) - $(stat -f%m "$cache_file" 2>/dev/null || stat -c%Y "$cache_file")))
if [ "$cache_age" -lt 300 ]; then # 5 minute cache
cat "$cache_file"
exit 0
fi
fi
# Perform validation
result='{"decision": "approve"}'
# Cache result
echo "$result" > "$cache_file"
echo "$result"
```
### Parallel Execution Optimization
Since hooks run in parallel, design them to be independent:
```json
{
"PreToolUse": [
{
"matcher": "write_to_file",
"hooks": [
{
"type": "command",
"command": "bash check-size.sh", // Independent
"timeout": 2
},
{
"type": "command",
"command": "bash check-path.sh", // Independent
"timeout": 2
},
{
"type": "prompt",
"prompt": "Check content safety", // Independent
"timeout": 10
}
]
}
]
}
```
All three hooks run simultaneously, reducing total latency.
## Cross-Event Workflows
Coordinate hooks across different events:
**SessionStart - Set up tracking:**
```bash
#!/bin/bash
# Initialize session tracking
echo "0" > /tmp/test-count-$$
echo "0" > /tmp/build-count-$$
```
**PostToolUse - Track events:**
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
if [ "$tool_name" = "run_command" ]; then
command=$(echo "$input" | jq -r '.tool_result')
if [[ "$command" == *"test"* ]]; then
count=$(cat /tmp/test-count-$$ 2>/dev/null || echo "0")
echo $((count + 1)) > /tmp/test-count-$$
fi
fi
```
**Stop - Verify based on tracking:**
```bash
#!/bin/bash
test_count=$(cat /tmp/test-count-$$ 2>/dev/null || echo "0")
if [ "$test_count" -eq 0 ]; then
echo '{"decision": "block", "reason": "No tests were run"}' >&2
exit 2
fi
```
## Integration with External Systems
### Slack Notifications
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
decision="blocked"
# Send notification to Slack
curl -X POST "$SLACK_WEBHOOK" \
-H 'Content-Type: application/json' \
-d "{\"text\": \"Hook ${decision} ${tool_name} operation\"}" \
2>/dev/null
echo '{"decision": "deny"}' >&2
exit 2
```
### Database Logging
```bash
#!/bin/bash
input=$(cat)
# Log to database
psql "$DATABASE_URL" -c "INSERT INTO hook_logs (event, data) VALUES ('PreToolUse', '$input')" \
2>/dev/null
exit 0
```
### Metrics Collection
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
# Send metrics to monitoring system
echo "hook.pretooluse.${tool_name}:1|c" | nc -u -w1 statsd.local 8125
exit 0
```
## Security Patterns
### Rate Limiting
```bash
#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command')
# Track command frequency
rate_file="/tmp/hook-rate-$$"
current_minute=$(date +%Y%m%d%H%M)
if [ -f "$rate_file" ]; then
last_minute=$(head -1 "$rate_file")
count=$(tail -1 "$rate_file")
if [ "$current_minute" = "$last_minute" ]; then
if [ "$count" -gt 10 ]; then
echo '{"decision": "deny", "reason": "Rate limit exceeded"}' >&2
exit 2
fi
count=$((count + 1))
else
count=1
fi
else
count=1
fi
echo "$current_minute" > "$rate_file"
echo "$count" >> "$rate_file"
exit 0
```
### Audit Logging
```bash
#!/bin/bash
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
timestamp=$(date -Iseconds)
# Append to audit log
echo "$timestamp | $USER | $tool_name | $input" >> ~/.gemini/config/audit.log
exit 0
```
### Secret Detection
```bash
#!/bin/bash
input=$(cat)
content=$(echo "$input" | jq -r '.tool_input.content')
# Check for common secret patterns
if echo "$content" | grep -qE "(api[_-]?key|password|secret|token).{0,20}['\"]?[A-Za-z0-9]{20,}"; then
echo '{"decision": "deny", "reason": "Potential secret detected in content"}' >&2
exit 2
fi
exit 0
```
## Testing Advanced Hooks
### Unit Testing Hook Scripts
```bash
# test-hook.sh
#!/bin/bash
# Test 1: Approve safe command
result=$(echo '{"tool_input": {"command": "ls"}}' | bash validate-bash.sh)
if [ $? -eq 0 ]; then
echo "✓ Test 1 passed"
else
echo "✗ Test 1 failed"
fi
# Test 2: Block dangerous command
result=$(echo '{"tool_input": {"command": "rm -rf /"}}' | bash validate-bash.sh)
if [ $? -eq 2 ]; then
echo "✓ Test 2 passed"
else
echo "✗ Test 2 failed"
fi
```
### Integration Testing
Create test scenarios that exercise the full hook workflow:
```bash
# integration-test.sh
#!/bin/bash
# Set up test environment
export CLAUDE_PROJECT_DIR="/tmp/test-project"
export ANTIGRAVITY_PLUGIN_ROOT="$(pwd)"
mkdir -p "$CLAUDE_PROJECT_DIR"
# Test SessionStart hook
echo '{}' | bash hooks/session-start.sh
if [ -f "/tmp/session-initialized" ]; then
echo "✓ SessionStart hook works"
else
echo "✗ SessionStart hook failed"
fi
# Clean up
rm -rf "$CLAUDE_PROJECT_DIR"
```
## Best Practices for Advanced Hooks
1. **Keep hooks independent**: Don't rely on execution order
2. **Use timeouts**: Set appropriate limits for each hook type
3. **Handle errors gracefully**: Provide clear error messages
4. **Document complexity**: Explain advanced patterns in README
5. **Test thoroughly**: Cover edge cases and failure modes
6. **Monitor performance**: Track hook execution time
7. **Version configuration**: Use version control for hook configs
8. **Provide escape hatches**: Allow users to bypass hooks when needed
## Common Pitfalls
### ❌ Assuming Hook Order
```bash
# BAD: Assumes hooks run in specific order
# Hook 1 saves state, Hook 2 reads it
# This can fail because hooks run in parallel!
```
### ❌ Long-Running Hooks
```bash
# BAD: Hook takes 2 minutes to run
sleep 120
# This will timeout and block the workflow
```
### ❌ Uncaught Exceptions
```bash
# BAD: Script crashes on unexpected input
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
cat "$file_path" # Fails if file doesn't exist
```
### ✅ Proper Error Handling
```bash
# GOOD: Handles errors gracefully
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
if [ ! -f "$file_path" ]; then
echo '{"continue": true, "systemMessage": "File not found, skipping check"}' >&2
exit 0
fi
```
## Conclusion
Advanced hook patterns enable sophisticated automation while maintaining reliability and performance. Use these techniques when basic hooks are insufficient, but always prioritize simplicity and maintainability.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |