gh-resolve-io-prism/skills/hooks-manager/reference/commands.md

Hooks Manager Command Reference

Complete reference for all hooks-manager skill commands.

Configuration Format

Plugin Hooks (PRISM)

PRISM uses plugin-level hooks configured in hooks/hooks.json at the plugin root:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/path/to/script.py",
            "description": "What this hook does",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Critical Requirements:

• ✅ Use ${CLAUDE_PLUGIN_ROOT} for all plugin paths (not relative paths)
• ✅ Nest hooks under event names as keys
• ✅ Each matcher gets its own object with a hooks array
• ✅ Each hook needs type: "command" property

Example (PRISM's current configuration):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/enforce-story-context.py",
            "description": "Ensure workflow commands have required story context"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/track-current-story.py",
            "description": "Track story file as current workflow context"
          }
        ]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/validate-required-sections.py",
            "description": "Verify all required PRISM sections exist"
          }
        ]
      }
    ]
  }
}

User-Level Hooks

User and project-level hooks use the same format in ~/.claude/settings.json or .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python /absolute/path/to/hook.py"
          }
        ]
      }
    ]
  }
}

Note: User hooks don't have ${CLAUDE_PLUGIN_ROOT} - use absolute paths.

Schema Reference

{
  hooks: {
    [EventName: string]: Array<{
      matcher: string;              // "Bash", "Edit|Write", "*"
      hooks: Array<{
        type: "command";             // Hook type (always "command")
        command: string;             // Shell command to execute
        description?: string;        // Optional description
        timeout?: number;            // Optional timeout (default: 60s)
      }>;
    }>;
  };
}

Available Event Names:

• PreToolUse - Before tool execution
• PostToolUse - After tool completion
• UserPromptSubmit - Before AI processes prompt
• SessionStart - Session begins/resumes
• SessionEnd - Session terminates
• Stop - Claude finishes responding
• SubagentStop - Subagent completes
• PreCompact - Before memory compaction
• Notification - Claude sends notification

Matcher Patterns:

• Exact: "Bash", "Edit", "Write"
• Multiple: "Edit|Write", "Read|Glob|Grep"
• All tools: "*"
• MCP tools: "mcp__server__tool"

Exit Codes:

• 0: Success (allow operation)
• 2: Blocking error (blocks operation, feeds stderr to Claude)
• Other: Non-blocking error (stderr shown to user)

Command Categories

• Hook Management
• Testing & Debugging
• Examples & Reference
• Integration

---

Hook Management

list-hooks

Purpose: Display all configured hooks with their events and matchers

Usage: *list-hooks

Output:

📋 Configured Hooks:

User Hooks (~/.claude/settings.json):
  1. bash-logger (PreToolUse, Bash)
     Command: python hooks/log-bash.py

  2. auto-format (PostToolUse, Edit|Write)
     Command: prettier --write ${file_path}

Project Hooks (.claude/settings.json):
  3. validate-story (PreToolUse, Edit)
     Command: python hooks/validate-story.py

Total: 3 hooks (2 user, 1 project)

Options:

• *list-hooks --user - Show only user-level hooks
• *list-hooks --project - Show only project-level hooks
• *list-hooks --event PreToolUse - Filter by event type

---

create-hook

Purpose: Create new hook with guided interactive setup

Usage: *create-hook

Process:

1. Select event type (PreToolUse, PostToolUse, etc.)
2. Choose matcher pattern (tool name or *)
3. Enter command to execute
4. Add description
5. Select configuration location (user or project)

Example:

*create-hook

→ Select event type:
  1. PreToolUse (can block operations)
  2. PostToolUse (after operations complete)
  ...

Choice: 1

→ Select matcher:
  1. Bash (bash commands only)
  2. Edit|Write (file edits and writes)
  3. * (all tools)
  4. Custom pattern

Choice: 1

→ Enter command:
Command: python hooks/my-validation.py

→ Description:
Description: Validate bash commands before execution

→ Save to:
  1. User settings (global)
  2. Project settings (this project only)

Choice: 2

✅ Hook created: my-validation
   Saved to: .claude/settings.json

Advanced Usage:

• *create-hook --template [name] - Start from example template
• *create-hook --quick - Skip interactive prompts (use defaults)

---

edit-hook {name}

Purpose: Modify existing hook configuration

Usage: *edit-hook my-validation

Opens interactive editor:

Editing hook: my-validation

Current configuration:
  Event: PreToolUse
  Matcher: Bash
  Command: python hooks/my-validation.py
  Description: Validate bash commands

What would you like to edit?
  1. Event type
  2. Matcher
  3. Command
  4. Description
  5. Enable/Disable
  6. Save changes
  7. Cancel

Direct Edit:

*edit-hook my-validation --command "python3 hooks/new-validator.py"
*edit-hook my-validation --matcher "Edit|Write"
*edit-hook my-validation --disable

---

delete-hook {name}

Purpose: Remove hook from configuration

Usage: *delete-hook my-validation

Confirmation:

⚠️  Are you sure you want to delete hook: my-validation?
   Event: PreToolUse
   Matcher: Bash
   Command: python hooks/my-validation.py

   This action cannot be undone.

   Type 'yes' to confirm: yes

✅ Hook deleted: my-validation

Force delete (no confirmation):

*delete-hook my-validation --force

---

enable-hook {name}

Purpose: Enable a disabled hook

Usage: *enable-hook my-validation

Output:

✅ Hook enabled: my-validation
   Will execute on: PreToolUse (Bash)

---

disable-hook {name}

Purpose: Disable hook without deleting it

Usage: *disable-hook my-validation

Output:

✅ Hook disabled: my-validation
   Configuration preserved (can be re-enabled)

---

Testing & Debugging

test-hook {name}

Purpose: Test hook execution with sample input

Usage: *test-hook my-validation

Process:

1. Generates sample tool input JSON
2. Executes hook command
3. Captures stdout, stderr, exit code
4. Displays results

Output:

🧪 Testing hook: my-validation

Sample input:
{
  "tool_input": {
    "command": "git push --force",
    "description": "Force push to remote"
  }
}

Executing: python hooks/my-validation.py

Exit code: 2 (BLOCKED)
Stdout:
Stderr: ❌ ERROR: Force push not allowed on main branch

✅ Test complete
   Hook correctly blocks dangerous operation

Custom test input:

*test-hook my-validation --input sample.json

---

debug-hook {name}

Purpose: Show hook execution logs and debugging information

Usage: *debug-hook my-validation

Output:

🔍 Debug information for: my-validation

Configuration:
  Location: .claude/settings.json
  Event: PreToolUse
  Matcher: Bash
  Command: python hooks/my-validation.py
  Status: Enabled

Recent executions (last 10):
  1. 2025-10-24 15:30:45 - EXIT:2 - Blocked: force push
  2. 2025-10-24 15:28:12 - EXIT:0 - Allowed: normal command
  3. 2025-10-24 15:25:33 - EXIT:2 - Blocked: rm -rf /
  ...

Common issues:
  ✓ Command is executable
  ✓ Configuration syntax valid
  ✓ Matcher pattern valid
  ! Hook has blocked 30% of recent executions (review threshold?)

---

validate-config

Purpose: Check hooks configuration syntax for all settings files

Usage: *validate-config

Output:

✅ Validating hook configurations...

~/.claude/settings.json:
  ✅ Valid JSON syntax
  ✅ 2 hooks configured
  ✅ All matchers valid
  ✅ All commands exist

.claude/settings.json:
  ✅ Valid JSON syntax
  ✅ 1 hook configured
  ⚠️  Warning: Hook 'my-validation' command not found: python hooks/my-validation.py

.claude/settings.local.json:
  ℹ️  File not found (optional)

Overall: 3 hooks, 1 warning, 0 errors

Fix issues:

*validate-config --fix

---

Examples & Reference

hook-examples

Purpose: Browse pre-built hook patterns for common use cases

Usage: *hook-examples

Categories:

📚 Hook Examples Library

1. Logging & Auditing
   - bash-command-logger
   - file-change-tracker
   - workflow-auditor

2. Validation & Safety
   - file-protection
   - git-safety
   - syntax-validator

3. Automation
   - auto-formatter
   - auto-tester
   - auto-commit

4. Notifications
   - desktop-alerts
   - slack-integration
   - completion-notifier

Select category or search:

View example:

*hook-examples bash-command-logger

Name: bash-command-logger
Category: Logging & Auditing
Description: Log all bash commands to file for audit trail

Configuration:
  Event: PreToolUse
  Matcher: Bash
  Command: jq -r '"\(.tool_input.command) - \(.tool_input.description)"' >> ~/.claude/bash-log.txt

Usage: Tracks every bash command with timestamp
Security: Low risk (read-only logging)
Dependencies: jq

Install: *install-example bash-command-logger

---

event-types

Purpose: List all hook event types with detailed information

Usage: *event-types

Output:

📋 Hook Event Types

PreToolUse
  Timing: Before tool execution
  Can Block: YES ✅
  Use Cases: Validation, access control, logging
  Example: Block dangerous git operations

PostToolUse
  Timing: After tool completion
  Can Block: NO ❌
  Use Cases: Formatting, testing, cleanup
  Example: Run prettier on edited files

UserPromptSubmit
  Timing: Before AI processing
  Can Block: YES ✅
  Use Cases: Input validation, preprocessing
  Example: Check for sensitive data in prompts

... (all 9 events)

Filter by capability:

*event-types --can-block
*event-types --for-validation

---

security-guide

Purpose: Display hook security best practices and review checklist

Usage: *security-guide

Output:

🔒 Hook Security Guide

CRITICAL SECURITY PRINCIPLES:

1. Review Before Use
   ⚠️  NEVER run hooks from untrusted sources
   ✅  Always inspect hook code before installation

2. Least Privilege
   ⚠️  Hooks run with YOUR user credentials
   ✅  Limit hook permissions to minimum required

3. Data Protection
   ⚠️  Malicious hooks can exfiltrate data
   ✅  Review all network operations in hooks

4. Version Control
   ✅  Commit project hooks to git
   ✅  Track changes with meaningful commits

5. Testing
   ✅  Test in safe environment first
   ✅  Use *test-hook before deployment

SECURITY CHECKLIST:

□ Hook code reviewed by team
□ No hardcoded credentials
□ No untrusted network calls
□ Error handling prevents crashes
□ Logging doesn't expose secrets
□ Exit codes correctly implemented
□ Command injection prevented
□ File permissions validated

Run: *validate-security [hook-name] for automated checks

---

Integration

install-example {name}

Purpose: Install pre-built hook from examples library

Usage: *install-example bash-command-logger

Process:

1. Downloads hook configuration from library
2. Validates dependencies are available
3. Prompts for installation location
4. Installs and tests hook

Output:

📦 Installing: bash-command-logger

Checking dependencies...
  ✅ jq found

Configuration:
  Event: PreToolUse
  Matcher: Bash
  Command: jq -r '"\(.tool_input.command)"' >> ~/.claude/bash-log.txt

Install to:
  1. User settings (all projects)
  2. Project settings (this project only)

Choice: 1

Installing...
✅ Hook installed successfully

Testing hook...
✅ Test passed

Next steps:
  - Run *test-hook bash-command-logger to verify
  - Check ~/.claude/bash-log.txt for logged commands

Force install (skip prompts):

*install-example bash-command-logger --user --force

---

export-hooks

Purpose: Export hooks to shareable JSON file

Usage: *export-hooks

Output:

📤 Exporting hooks...

Source: .claude/settings.json

Hooks to export:
  ✓ validate-story (PreToolUse)
  ✓ auto-format (PostToolUse)

Export location: hooks-export.json

✅ Exported 2 hooks to hooks-export.json

Share with team:
  git add hooks-export.json
  git commit -m "Add project hooks"

Options:

*export-hooks --output my-hooks.json
*export-hooks --user  # Export only user hooks
*export-hooks --project  # Export only project hooks

---

import-hooks {file}

Purpose: Import hooks from JSON file

Usage: *import-hooks hooks-export.json

Process:

1. Validates JSON file syntax
2. Checks for conflicts with existing hooks
3. Prompts for conflict resolution
4. Imports hooks to specified location

Output:

📥 Importing hooks from: hooks-export.json

Found 2 hooks:
  1. validate-story (PreToolUse)
  2. auto-format (PostToolUse)

Checking for conflicts...
  ⚠️  Hook 'validate-story' already exists

Conflict resolution:
  1. Skip (keep existing)
  2. Overwrite (replace with imported)
  3. Rename (keep both)

Choice for 'validate-story': 3
New name: validate-story-imported

Import to:
  1. User settings
  2. Project settings

Choice: 2

Importing...
  ✅ validate-story-imported
  ✅ auto-format

✅ Imported 2 hooks to .claude/settings.json

Run *list-hooks to see all hooks

---

Command Shortcuts

Full Command	Shortcut	Notes
*list-hooks	*lh	List all hooks
*create-hook	*ch	Create new hook
*test-hook {name}	*th {name}	Test hook
*hook-examples	*hx	Browse examples

---

Advanced Usage

Chaining Commands

# Create, test, and enable in one flow
*create-hook && *test-hook my-hook && *enable-hook my-hook

# Export and commit hooks
*export-hooks --output team-hooks.json && git add team-hooks.json && git commit

Filtering and Searching

# Find hooks by event type
*list-hooks --event PreToolUse

# Search examples by keyword
*hook-examples --search validation

# Show only enabled hooks
*list-hooks --enabled

Batch Operations

# Disable all hooks temporarily
*disable-all-hooks

# Re-enable all hooks
*enable-all-hooks

# Delete all project hooks
*delete-hooks --project --confirm

---

Troubleshooting

Command Not Found

Issue: *create-hook not recognized

Fix:

1. Ensure hooks-manager skill is loaded
2. Try *hooks to see if skill is available
3. Reload skill: /reload-skill hooks-manager

Hook Not Executing

Issue: Hook configured but not running

Debug Steps:

1. Run *validate-config to check syntax
2. Run *test-hook {name} to test execution
3. Check matcher matches the tool
4. Review Claude Code console for errors

Permission Denied

Issue: Hook command fails with permission error

Fix:

1. Make script executable: chmod +x hooks/script.py
2. Check file permissions on settings file
3. Verify Python/command is in PATH

---

Exit Codes

Hooks use exit codes to communicate results:

Code	Meaning	Usage
0	Success / Allow	Operation proceeds normally
1	Error	Hook failed but operation may proceed
2	Block	Operation blocked (PreToolUse only)
>2	Custom	Hook-specific error codes

---

Related Commands

• /hooks - Interactive hooks management UI
• *help - Show all available commands
• *security-guide - Security best practices

---

Version: 1.0.0 Last Updated: 2025-10-24