enhance-hooks

Analyze hook definitions and scripts for safety, correctness, and best practices.

Parse Arguments

const args = '$ARGUMENTS'.split(' ').filter(Boolean);
const targetPath = args.find(a => !a.startsWith('--')) || '.';
const fix = args.includes('--fix');

Workflow

1. Discover - Find hook files (.md, .sh, .json)
2. Classify - Identify hook type and event
3. Parse - Extract frontmatter and script content
4. Check - Run all pattern checks against knowledge below
5. Filter - Apply certainty filtering
6. Report - Generate markdown output
7. Fix - Apply auto-fixes if --fix flag present

Hook Knowledge Reference

What Are Hooks

Hooks are automated actions triggered at specific points in a Claude Code session. They enable validation, monitoring, and control of Claude's actions through bash commands or LLM-based evaluation.

Hook Lifecycle (Complete Reference)

Hooks fire in this sequence:

SessionStart

UserPromptSubmit

PreToolUse

PermissionRequest

PostToolUse

SubagentStart

SubagentStop

Stop

PreCompact

SessionEnd

Notification

Hook Types

Command Hooks (

type: "command"

• Execute bash commands with full stdin/stdout control
• Available for all events

Prompt Hooks (

type: "prompt"

• Use LLM evaluation for intelligent, context-aware decisions
• Only supported for

  Stop

  and

  SubagentStop

  events

Configuration Locations

~/.claude/settings.json

.claude/settings.json

.claude/settings.local.json

Configuration Structure

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/format-code.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all requested tasks are complete.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matcher Syntax

Write

Edit|Write

Notebook.*

*

""

Input Schema (JSON via stdin)

All hooks receive this JSON structure:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript",
  "cwd": "/project/root",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  }
}

Exit Codes

Output Schemas

PreToolUse Decision Control:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow|deny|ask",
    "permissionDecisionReason": "Reason for decision",
    "updatedInput": {
      "command": "modified command"
    },
    "additionalContext": "Context for Claude"
  }
}

Stop/SubagentStop Control:

{
  "decision": "block",
  "reason": "Tasks incomplete: missing test coverage"
}

Environment Variables

CLAUDE_PROJECT_DIR

CLAUDE_CODE_REMOTE

CLAUDE_ENV_FILE

CLAUDE_FILE_PATHS

Practical Hook Examples

Security Firewall (PreToolUse):

#!/usr/bin/env bash
set -euo pipefail

cmd=$(jq -r '.tool_input.command // ""')

# Block dangerous patterns
if echo "$cmd" | grep -qE 'rm -rf|git reset --hard|curl.*\|.*sh'; then
  echo '{"decision": "block", "reason": "Dangerous command blocked"}' >&2
  exit 2
fi

exit 0

Auto-Formatter (PostToolUse):

#!/usr/bin/env bash
set -euo pipefail

files=$(jq -r '.tool_input.file_path // ""')

for file in $files; do
  case "$file" in
    *.py) black "$file" 2>/dev/null || true ;;
    *.js|*.ts) prettier --write "$file" 2>/dev/null || true ;;
  esac
done

exit 0

Command Logger (PreToolUse):

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')
printf '%s %s\n' "$(date -Is)" "$cmd" >> .claude/bash-commands.log
exit 0

Workflow Orchestration (SubagentStop - prompt type):

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Review the subagent's work. Did it complete all tasks?"
          }
        ]
      }
    ]
  }
}

Detection Patterns

1. Frontmatter Validation (HIGH Certainty)

Required:

• YAML frontmatter with

  ---

  delimiters

• name

  field in frontmatter

• description

  field in frontmatter

Recommended:

• timeout

  for command hooks (default: 30s)
• Hook type specification

Flag:

• Missing frontmatter delimiters
• Missing name or description

2. Script Safety (HIGH Certainty)

Required Safety Patterns:

• set -euo pipefail

  at script start
• Error handling for jq/JSON parsing
• Proper quoting of variables

Dangerous Patterns to Flag:

rm -rf

git reset --hard

curl | sh

eval "$input"

rm -r

git push --force

3. Exit Code Handling (HIGH Certainty)

Check: Scripts use correct exit codes

Flag:

• Missing

  exit 0

  for success path
• Using exit code 1 for blocking (should be 2)
• No exit code at end of script

4. Hook Type Appropriateness (HIGH Certainty)

Check: Hook type matches event

Flag:

• Prompt hooks used for events other than Stop/SubagentStop
• Missing type specification

5. Lifecycle Event Appropriateness (MEDIUM Certainty)

PreToolUse

PostToolUse

Stop

SubagentStop

SessionStart

Flag:

• PostToolUse hooks trying to block actions (too late)
• PreToolUse hooks doing heavy processing (should be fast)
• Prompt hooks on unsupported events

6. Timeout Configuration (MEDIUM Certainty)

Guidelines:

• Default: 30 seconds for command hooks
• Network operations: Always set explicit timeout
• External service calls: Set timeout based on expected latency

Flag:

• No timeout for network operations
• Timeout missing for external service calls
• Unreasonably long timeouts (>60s without justification)

7. Output Format (MEDIUM Certainty)

PreToolUse Output Fields:

• permissionDecision

  : allow, deny, or ask

• permissionDecisionReason

  : Explanation for decision

• updatedInput

  : Modified tool input (optional)

• additionalContext

  : Context for Claude (optional)

Flag:

• Invalid permissionDecision values
• Missing reason for deny decisions
• Malformed JSON output

8. Matcher Patterns (MEDIUM Certainty)

Check: Matcher syntax is valid

Flag:

• Invalid regex patterns
• Too broad matchers (

  *

  without justification)
• Matcher on events that don't support it (Stop, SubagentStop)

9. Anti-Patterns (LOW Certainty)

• Complex logic in hooks (should be simple and fast)
• Missing documentation/comments
• Hardcoded paths (should use

  $CLAUDE_PROJECT_DIR

  )
• Network calls without error handling
• Secrets/credentials in hook scripts

Auto-Fix Implementations

1. Missing safety header

#!/usr/bin/env bash
set -euo pipefail

2. Missing exit code

Add

exit 0

3. Missing frontmatter fields

---
name: hook-name
description: Hook description
timeout: 30
---

4. Wrong blocking exit code

Replace

exit 1

exit 2

Output Format

## Hook Analysis: {hook-name}

**File**: {path}
**Type**: {command|prompt|config}
**Event**: {PreToolUse|PostToolUse|Stop|...}

### Summary
- HIGH: {count} issues
- MEDIUM: {count} issues

### Frontmatter Issues ({n})
| Issue | Fix | Certainty |

### Safety Issues ({n})
| Issue | Fix | Certainty |

### Exit Code Issues ({n})
| Issue | Fix | Certainty |

### Lifecycle Issues ({n})
| Issue | Fix | Certainty |

### Output Format Issues ({n})
| Issue | Fix | Certainty |

Pattern Statistics

<bad_example>

#!/usr/bin/env bash
cmd=$(jq -r '.tool_input.command // ""')

Why it's bad: Missing

set -euo pipefail

<good_example>

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command // ""')

Why it's good: Fails fast on errors, unset variables, and pipe failures. </good_example>

Example: Wrong Exit Code for Blocking

<bad_example>

if [[ "$cmd" == *"rm -rf"* ]]; then
  echo "Blocked dangerous command" >&2
  exit 1  # Wrong!
fi

Why it's bad: Exit code 1 is non-blocking. Action will still proceed. </bad_example>

<good_example>

if [[ "$cmd" == *"rm -rf"* ]]; then
  echo '{"decision": "block", "reason": "Dangerous command"}' >&2
  exit 2  # Correct blocking exit code
fi

Why it's good: Exit code 2 blocks the action. JSON output provides context. </good_example>

Example: Prompt Hook on Wrong Event

<bad_example>

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{ "type": "prompt", "prompt": "Is this safe?" }]
      }
    ]
  }
}

Why it's bad: Prompt hooks only work for Stop and SubagentStop events. </bad_example>

<good_example>

{
  "hooks": {
    "PreToolUse": [
      {
        "hooks": [{ "type": "command", "command": "./validate.sh" }]
      }
    ]
  }
}

Why it's good: Command hooks work for all events. </good_example>

Example: Dangerous Command Pattern

<bad_example>

if echo "$cmd" | grep -q 'rm'; then
  exit 2
fi

Why it's bad: Too broad - blocks legitimate

rm file.tmp

<good_example>

if echo "$cmd" | grep -qE 'rm\s+(-rf|-fr)\s+/'; then
  exit 2
fi

Why it's good: Specific pattern targets actual dangerous commands. </good_example>

Example: Hardcoded Path

<bad_example>

log_file="/home/user/project/.claude/commands.log"

Why it's bad: Hardcoded path breaks on other machines. </bad_example>

<good_example>

log_file="$CLAUDE_PROJECT_DIR/.claude/commands.log"

Why it's good: Uses environment variable for portability. </good_example> </examples>

Constraints

• Only apply auto-fixes for HIGH certainty issues
• Be cautious about security patterns - false negatives worse than false positives
• Never remove content, only suggest improvements
• Validate against embedded knowledge reference above