This 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 ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.
/plugin marketplace add astrosteveo/harness/plugin install harness@astrosteveo-marketplaceThis skill inherits all available tools. When active, it can use any tool Claude has access to.
examples/load-context.shexamples/validate-bash.shexamples/validate-write.shreferences/advanced.mdreferences/migration.mdreferences/patterns.mdscripts/README.mdscripts/hook-linter.shscripts/test-hook.shscripts/validate-hook-schema.shHooks are event-driven automation scripts that execute in response to Claude Code events. Use hooks to validate operations, enforce policies, add context, and integrate external tools into workflows.
Key capabilities:
Use LLM-driven decision making for context-aware validation:
{
"type": "prompt",
"prompt": "Evaluate if this tool use is appropriate: $TOOL_INPUT",
"timeout": 30
}
Supported events: Stop, SubagentStop, UserPromptSubmit, PreToolUse
Benefits:
Execute bash commands for deterministic checks:
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
"timeout": 60
}
Use for:
How long a hook should run before canceling. Specified in seconds.
Defaults: Command hooks (60s), Prompt hooks (30s)
Set to true to run the hook only once per session. After the first successful execution, the hook is removed.
Note: This option is only supported for hooks defined in skills and slash commands, not for agents or settings-based hooks.
{
"type": "command",
"command": "./scripts/one-time-setup.sh",
"once": true
}
Use cases:
For plugin hooks in hooks/hooks.json, use wrapper format:
{
"description": "Brief explanation of hooks (optional)",
"hooks": {
"PreToolUse": [...],
"Stop": [...],
"SessionStart": [...]
}
}
Key points:
description field is optionalhooks field is required wrapper containing actual hook eventsExample:
{
"description": "Validation hooks for code quality",
"hooks": {
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"
}
]
}
]
}
}
For user settings in .claude/settings.json, use direct format:
{
"PreToolUse": [...],
"Stop": [...],
"SessionStart": [...]
}
Key points:
Important: The examples below show the hook event structure that goes inside either format. For plugin hooks.json, wrap these in {"hooks": {...}}.
Execute before any tool runs. Use to approve, deny, or modify tool calls.
Example (prompt-based):
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety. Check: system paths, credentials, path traversal, sensitive content. Return 'approve' or 'deny'."
}
]
}
]
}
Output for PreToolUse:
{
"hookSpecificOutput": {
"permissionDecision": "allow|deny|ask",
"updatedInput": {"field": "modified_value"}
},
"systemMessage": "Explanation for Claude"
}
Execute after tool completes successfully. Use to react to results, provide feedback, or log.
Example:
{
"PostToolUse": [
{
"matcher": "Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Analyze edit result for potential issues: syntax errors, security vulnerabilities, breaking changes. Provide feedback."
}
]
}
]
}
Output behavior:
Execute after tool execution fails. Use to handle errors, provide recovery suggestions, or log failures.
Example:
{
"PostToolUseFailure": [
{
"matcher": "Bash",
"hooks": [
{
"type": "prompt",
"prompt": "Analyze the command failure and suggest fixes or alternative approaches."
}
]
}
]
}
Execute when a permission dialog is shown to the user. Use to automatically allow or deny permissions based on rules.
Example:
{
"PermissionRequest": [
{
"matcher": "Write",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/check-permission.sh"
}
]
}
]
}
Recognizes the same matcher values as PreToolUse.
Execute when main agent considers stopping. Use to validate completeness.
Example:
{
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify task completion: tests run, build succeeded, questions answered. Return 'approve' to stop or 'block' with reason to continue."
}
]
}
]
}
Decision output:
{
"decision": "approve|block",
"reason": "Explanation",
"systemMessage": "Additional context"
}
Execute when a subagent is started. Use to configure subagent behavior or log subagent invocations.
Example:
{
"SubagentStart": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/log-subagent.sh"
}
]
}
]
}
Execute when subagent considers stopping. Use to ensure subagent completed its task.
Similar to Stop hook, but for subagents.
Execute when user submits a prompt. Use to add context, validate, or block prompts.
Example:
{
"UserPromptSubmit": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Check if prompt requires security guidance. If discussing auth, permissions, or API security, return relevant warnings."
}
]
}
]
}
Execute when Claude Code session begins. Use to load context and set environment.
Matchers:
startup - Normal startupresume - Invoked from --resume, --continue, or /resumeclear - Invoked from /clearcompact - Invoked from auto or manual compactExample:
{
"SessionStart": [
{
"matcher": "startup",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh"
}
]
}
]
}
Special capability: Persist environment variables using $CLAUDE_ENV_FILE:
echo "export PROJECT_TYPE=nodejs" >> "$CLAUDE_ENV_FILE"
See examples/load-context.sh for complete example.
Execute when session ends. Use for cleanup, logging, and state preservation.
The reason field in hook input will be one of: clear, logout, prompt_input_exit, other.
Execute before context compaction. Use to add critical information to preserve.
Matchers:
manual - Invoked from /compactauto - Invoked from auto-compact (due to full context window)Execute when Claude sends notifications. Use to react to user notifications.
Matchers:
permission_prompt - Permission requests from Claude Codeidle_prompt - When Claude is waiting for user input (after 60+ seconds idle)auth_success - Authentication success notificationselicitation_dialog - When Claude Code needs input for MCP tool elicitationExample:
{
"Notification": [
{
"matcher": "permission_prompt",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/notify-permission.sh"
}
]
}
]
}
{
"continue": true,
"suppressOutput": false,
"systemMessage": "Message for Claude"
}
continue: If false, halt processing (default true)suppressOutput: Hide output from transcript (default false)systemMessage: Message shown to Claude0 - Success (stdout shown in transcript)2 - Blocking error (stderr fed back to Claude)All hooks receive JSON via stdin with common fields:
{
"session_id": "abc123",
"transcript_path": "/path/to/transcript.txt",
"cwd": "/current/working/dir",
"permission_mode": "ask|allow",
"hook_event_name": "PreToolUse"
}
Event-specific fields:
tool_name, tool_input, tool_resultuser_promptreasonAccess fields in prompts using $TOOL_INPUT, $TOOL_RESULT, $USER_PROMPT, etc.
Available in all command hooks:
$CLAUDE_PROJECT_DIR - Absolute path to the project root directory (where Claude Code was started). Use this to reference project files in a portable way.
$CLAUDE_PLUGIN_ROOT - Absolute path to the plugin directory. Essential for plugin hooks - always use this instead of hardcoded paths to ensure hooks work regardless of where the plugin is installed.
$CLAUDE_ENV_FILE - (SessionStart only) File path where you can persist environment variables for subsequent bash commands. Write export VAR=value lines to this file:
echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
echo 'export API_KEY=your-key' >> "$CLAUDE_ENV_FILE"
$CLAUDE_CODE_REMOTE - Set to "true" if running in remote (web) environment, not set or empty for local CLI. Use to run different logic based on execution context:
if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
# Remote-specific logic
else
# Local CLI logic
fi
Always use ${CLAUDE_PLUGIN_ROOT} in plugin hook commands for portability:
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
}
Reference project files with ${CLAUDE_PROJECT_DIR}:
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
}
In plugins, define hooks in hooks/hooks.json:
{
"PreToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "prompt",
"prompt": "Validate file write safety"
}
]
}
],
"Stop": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "Verify task completion"
}
]
}
],
"SessionStart": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/load-context.sh",
"timeout": 10
}
]
}
]
}
Plugin hooks merge with user's hooks and run in parallel.
Exact match:
"matcher": "Write"
Multiple tools:
"matcher": "Read|Write|Edit"
Wildcard (all tools):
"matcher": "*"
Regex patterns:
"matcher": "mcp__.*__delete.*" // All MCP delete tools
Note: Matchers are case-sensitive.
// All MCP tools
"matcher": "mcp__.*"
// Specific plugin's MCP tools
"matcher": "mcp__plugin_asana_.*"
// All file operations
"matcher": "Read|Write|Edit"
// Bash commands only
"matcher": "Bash"
Always validate inputs in command hooks:
#!/bin/bash
set -euo pipefail
input=$(cat)
tool_name=$(echo "$input" | jq -r '.tool_name')
# Validate tool name format
if [[ ! "$tool_name" =~ ^[a-zA-Z0-9_]+$ ]]; then
echo '{"decision": "deny", "reason": "Invalid tool name"}' >&2
exit 2
fi
Check for path traversal and sensitive files:
file_path=$(echo "$input" | jq -r '.tool_input.file_path')
# Deny path traversal
if [[ "$file_path" == *".."* ]]; then
echo '{"decision": "deny", "reason": "Path traversal detected"}' >&2
exit 2
fi
# Deny sensitive files
if [[ "$file_path" == *".env"* ]]; then
echo '{"decision": "deny", "reason": "Sensitive file"}' >&2
exit 2
fi
See examples/validate-write.sh and examples/validate-bash.sh for complete examples.
# GOOD: Quoted
echo "$file_path"
cd "$CLAUDE_PROJECT_DIR"
# BAD: Unquoted (injection risk)
echo $file_path
cd $CLAUDE_PROJECT_DIR
{
"type": "command",
"command": "bash script.sh",
"timeout": 10
}
Defaults: Command hooks (60s), Prompt hooks (30s)
All matching hooks run in parallel:
{
"PreToolUse": [
{
"matcher": "Write",
"hooks": [
{"type": "command", "command": "check1.sh"}, // Parallel
{"type": "command", "command": "check2.sh"}, // Parallel
{"type": "prompt", "prompt": "Validate..."} // Parallel
]
}
]
}
Design implications:
Create hooks that activate conditionally by checking for a flag file or configuration:
Pattern: Flag file activation
#!/bin/bash
# Only active when flag file exists
FLAG_FILE="$CLAUDE_PROJECT_DIR/.enable-strict-validation"
if [ ! -f "$FLAG_FILE" ]; then
# Flag not present, skip validation
exit 0
fi
# Flag present, run validation
input=$(cat)
# ... validation logic ...
Pattern: Configuration-based activation
#!/bin/bash
# Check configuration for activation
CONFIG_FILE="$CLAUDE_PROJECT_DIR/.claude/plugin-config.json"
if [ -f "$CONFIG_FILE" ]; then
enabled=$(jq -r '.strictMode // false' "$CONFIG_FILE")
if [ "$enabled" != "true" ]; then
exit 0 # Not enabled, skip
fi
fi
# Enabled, run hook logic
input=$(cat)
# ... hook logic ...
Use cases:
Best practice: Document activation mechanism in plugin README so users know how to enable/disable temporary hooks.
Important: Hooks are loaded when Claude Code session starts. Changes to hook configuration require restarting Claude Code.
Cannot hot-swap hooks:
hooks/hooks.json won't affect current sessionclaude againTo test hook changes:
claude or ccclaude --debugHooks are validated when Claude Code starts:
Use /hooks command to review loaded hooks in current session.
claude --debug
Look for hook registration, execution logs, input/output JSON, and timing information.
Test command hooks directly:
echo '{"tool_name": "Write", "tool_input": {"file_path": "/test"}}' | \
bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh
echo "Exit code: $?"
Ensure hooks output valid JSON:
output=$(./your-hook.sh < test-input.json)
echo "$output" | jq .
| Event | When | Use For |
|---|---|---|
| PreToolUse | Before tool | Validation, modification |
| PostToolUse | After tool succeeds | Feedback, logging |
| PostToolUseFailure | After tool fails | Error handling, recovery |
| PermissionRequest | Permission dialog shown | Auto-allow/deny |
| UserPromptSubmit | User input | Context, validation |
| Stop | Agent stopping | Completeness check |
| SubagentStart | Subagent begins | Configuration, logging |
| SubagentStop | Subagent done | Task validation |
| SessionStart | Session begins | Context loading |
| SessionEnd | Session ends | Cleanup, logging |
| PreCompact | Before compact | Preserve context |
| Notification | User notified | Logging, reactions |
DO:
DON'T:
For detailed patterns and advanced techniques, consult:
references/patterns.md - Common hook patterns (8+ proven patterns)references/migration.md - Migrating from basic to advanced hooksreferences/advanced.md - Advanced use cases and techniquesWorking examples in examples/:
validate-write.sh - File write validation examplevalidate-bash.sh - Bash command validation exampleload-context.sh - SessionStart context loading exampleDevelopment tools in scripts/:
validate-hook-schema.sh - Validate hooks.json structure and syntaxtest-hook.sh - Test hooks with sample input before deploymenthook-linter.sh - Check hook scripts for common issues and best practicesclaude --debug for detailed logsjq to validate hook JSON outputTo implement hooks in a plugin:
hooks/hooks.jsonscripts/validate-hook-schema.sh hooks/hooks.jsonscripts/test-hook.sh before deploymentclaude --debugFocus on prompt-based hooks for most use cases. Reserve command hooks for performance-critical or deterministic checks.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This 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 ${CLAUDE_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 Claude Code plugin hooks with focus on advanced prompt-based hooks API.