hook-creator

---

LIBRARY-FIRST PROTOCOL (MANDATORY)

Before writing ANY code, you MUST check:

Step 1: Library Catalog

• Location: .claude/library/catalog.json
• If match >70%: REUSE or ADAPT

Step 2: Patterns Guide

• Location: .claude/docs/inventories/LIBRARY-PATTERNS-GUIDE.md
• If pattern exists: FOLLOW documented approach

Step 3: Existing Projects

• Location: D:\Projects\*
• If found: EXTRACT and adapt

Decision Matrix

| Match | Action | |-------|--------| | Library >90% | REUSE directly | | Library 70-90% | ADAPT minimally | | Pattern exists | FOLLOW pattern | | In project | EXTRACT | | No match | BUILD (add to library after) |

---

Purpose

Create production-ready Claude Code hooks that integrate with our RBAC security system, follow official schemas, and meet performance requirements (<20ms for pre-hooks).

When to Use This Skill

• Creating new automation hooks (pre/post operations)
• Implementing security validation hooks
• Building audit/logging hooks
• Extending the RBAC permission system
• Adding custom session management hooks

8-Stage Hook Creation Methodology

Stage 1: Hook Type Selection

Identify which of the 10 hook event types you need:

| Category | Hook Type | Purpose | |----------|-----------|---------| | Blocking | UserPromptSubmit | Validate/modify user prompts | | Blocking | SessionStart | Initialize session state | | Blocking | PreToolUse | Validate tool operations | | Blocking | PermissionRequest | Auto-approve/deny permissions | | Observational | PostToolUse | Log tool results | | Observational | Notification | Forward notifications | | Observational | Stop | Cleanup on agent stop | | Observational | SubagentStop | Track subagent completion | | Observational | PreCompact | Preserve context during compaction | | Observational | SessionEnd | Final session cleanup |

Stage 2: Schema Definition

Define input/output schemas based on hook type.

PreToolUse Input:

{
  "session_id": "string",
  "tool_name": "Bash|Read|Write|Edit|...",
  "tool_input": { "...tool-specific..." }
}

Blocking Output:

{
  "continue": true|false,
  "decision": "approve|block|modify",
  "reason": "string (if blocked)",
  "suppressOutput": false,
  "updatedInput": { "..." }
}

Non-Blocking Output:

{
  "suppressOutput": false
}

Stage 3: Template Selection

Use our pre-built templates:

• pre-hook-template.js - For blocking hooks (PreToolUse, UserPromptSubmit)
• post-hook-template.js - For observational hooks (PostToolUse, SessionEnd)
• session-hook-template.js - For session lifecycle hooks

Generate from templates:

node hook-template-generator.js --type pre --name my-validator --event PreToolUse

Stage 4: Core Logic Implementation

Implement the hook's core logic:

#!/usr/bin/env node
const fs = require('fs');

// Read input from stdin
const input = JSON.parse(fs.readFileSync(0, 'utf-8'));

// Your validation/processing logic
function processHook(input) {
  // Implement your logic here
  return { continue: true, decision: "approve" };
}

// Execute and output result
try {
  const result = processHook(input);
  console.log(JSON.stringify(result));
} catch (error) {
  console.error(`[HOOK ERROR] ${error.message}`);
  console.log(JSON.stringify({ continue: true }));  // Fail open
  process.exit(1);
}

Stage 5: RBAC Integration

For security hooks, integrate with our identity system:

const { validateAgentIdentity, loadAgentIdentityByName } = require('../utils/identity');

// Verify agent identity
const identity = loadAgentIdentityByName(input.agent_name);
const validation = validateAgentIdentity(identity);

if (!validation.valid) {
  return {
    continue: false,
    decision: "block",
    reason: `Invalid agent identity: ${validation.errors.join(', ')}`
  };
}

Stage 6: Performance Optimization

Meet performance targets:

| Hook Type | Target | Max | |-----------|--------|-----| | Pre-hooks | <20ms | 100ms | | Post-hooks | <100ms | 1000ms |

Optimization Patterns:

• Cache identity lookups
• Avoid synchronous I/O in hot paths
• Use matchers to filter events
• Batch logging operations

Stage 7: Testing

Create test scenarios:

// test-my-hook.js
const testCases = [
  {
    name: "Should approve valid operation",
    input: { tool_name: "Read", tool_input: { file_path: "/src/app.js" } },
    expectedOutput: { continue: true, decision: "approve" }
  },
  {
    name: "Should block dangerous command",
    input: { tool_name: "Bash", tool_input: { command: "rm -rf /" } },
    expectedOutput: { continue: false, decision: "block" }
  }
];

Stage 8: Registration

Register in settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "type": "command",
        "command": "node /path/to/your/hook.js",
        "timeout": 5000,
        "matcher": { "tool_name_regex": "^(Bash|Write|Edit)$" }
      }
    ]
  }
}

Hook Templates

Pre-Hook Template (Blocking)

Location: resources/templates/pre-hook-template.js

Features:

• Input validation
• Error handling with fail-open
• Performance timing
• RBAC integration point

Post-Hook Template (Observational)

Location: resources/templates/post-hook-template.js

Features:

• Async-safe logging
• Metric collection
• Non-blocking execution
• Error isolation

Output Artifacts

1. {hook-name}.js - Main hook script
2. {hook-name}.test.js - Test file
3. Settings entry for .claude/settings.json

Integration Points

• RBAC System: hooks/12fa/utils/identity.js
• Permission Checker: hooks/12fa/permission-checker.js
• Budget Tracker: hooks/12fa/budget-tracker.js
• Reference Docs: hooks/12fa/docs/CLAUDE-CODE-HOOKS-REFERENCE.md

Agents Used

| Agent | Role | |-------|------| | hook-creator | Generate hook code from templates | | coder | Implement custom logic | | reviewer | Validate hook implementation | | tester | Create and run test scenarios |

Example Invocations

Create a command validator hook:

User: "Create a hook that blocks any Bash command containing 'sudo'"

hook-creator:
  1. Hook Type: PreToolUse (blocking)
  2. Schema: PreToolUse input, blocking output
  3. Template: pre-hook-template.js
  4. Logic: Check tool_input.command for 'sudo'
  5. RBAC: Not required (simple validation)
  6. Performance: Target <10ms (regex only)
  7. Tests: Valid command, sudo command, edge cases
  8. Register in settings.json with Bash matcher

Create an audit logging hook:

User: "Create a hook that logs all file writes to an audit trail"

hook-creator:
  1. Hook Type: PostToolUse (observational)
  2. Schema: PostToolUse input, non-blocking output
  3. Template: post-hook-template.js
  4. Logic: Append to audit JSONL file
  5. RBAC: Load agent identity for WHO tag
  6. Performance: Target <50ms (file append)
  7. Tests: Successful write, failed write, large file
  8. Register with Write/Edit matcher

Security Considerations

1. Never log sensitive data - Filter passwords, API keys, tokens
2. Validate all input - Treat hook input as untrusted
3. Fail open for non-security hooks - Don't block on errors
4. Fail closed for security hooks - Block on validation errors
5. Use absolute paths - Avoid path traversal vulnerabilities

Shell Script Best Practices (Codex Recommendations)

When creating bash/shell hooks, follow these best practices:

1. Enable Strict Mode

Always start shell hooks with strict mode:

#!/bin/bash
set -euo pipefail

# -e: Exit on error
# -u: Treat unset variables as errors
# -o pipefail: Pipe fails if any command fails

2. Proper Variable Quoting

Always quote variable expansions to prevent word splitting:

# GOOD
FILE_PATH="${HOME}/.claude/state.json"
if [[ -f "$FILE_PATH" ]]; then
    cat "$FILE_PATH"
fi

# BAD - unquoted variables can break with spaces
FILE_PATH=${HOME}/.claude/state.json
if [ -f $FILE_PATH ]; then  # Breaks if path has spaces
    cat $FILE_PATH
fi

3. Defensive jq Usage

Handle jq failures gracefully:

# GOOD - handle missing keys and errors
VALUE=$(echo "$JSON" | jq -r '.key // "default"' 2>/dev/null || echo "default")

# BAD - crashes if key missing or json invalid
VALUE=$(echo "$JSON" | jq -r '.key')

4. Ensure Directories Exist

Create directories before writing:

STATE_DIR="${HOME}/.claude/my-hook"
mkdir -p "$STATE_DIR" 2>/dev/null

5. Use Environment Variables for Paths

Never hardcode project paths:

# GOOD - configurable via environment
PROJECT_PATH="${MY_PROJECT_PATH:-/default/path}"

# BAD - hardcoded, breaks on other systems
PROJECT_PATH="/c/Users/john/projects/myapp"

ANTI-PATTERNS TO AVOID

These patterns caused real bugs in production hooks. NEVER use them:

ANTI-PATTERN 1: Using grep -P (Perl Regex)

Problem: grep -P requires Perl regex support, not available on all systems.

# BAD - grep -P not portable
FOUND=$(echo "$TEXT" | grep -oP '(?<=<tag>).*?(?=</tag>)')

# GOOD - use bash regex matching
if [[ "$TEXT" =~ \<tag\>([^\<]+)\</tag\> ]]; then
    FOUND="${BASH_REMATCH[1]}"
fi

ANTI-PATTERN 2: Using sed -i Directly

Problem: sed -i behaves differently on macOS (requires ''), Linux, and Windows Git Bash.

# BAD - not portable
sed -i 's/old/new/' "$FILE"

# ALSO BAD - OS detection is fragile
if [[ "$(uname -s)" == "Darwin" ]]; then
    sed -i '' 's/old/new/' "$FILE"
else
    sed -i 's/old/new/' "$FILE"
fi

# GOOD - portable temp file approach
sed_inplace() {
    local pattern="$1"
    local file="$2"
    local temp_file="${file}.tmp.$$"
    sed "$pattern" "$file" > "$temp_file" && mv "$temp_file" "$file"
}
sed_inplace 's/old/new/' "$FILE"

ANTI-PATTERN 3: Hardcoded Paths

Problem: Hardcoded paths break on other systems or when projects move.

# BAD - hardcoded
cd D:/Projects/connascence
python analyze.py

# GOOD - environment variable with fallback
CONNASCENCE_PATH="${CONNASCENCE_PROJECT_PATH:-D:/Projects/connascence}"
if [[ -d "$CONNASCENCE_PATH" ]]; then
    cd "$CONNASCENCE_PATH"
    python analyze.py
else
    echo "ERROR: Connascence project not found at $CONNASCENCE_PATH" >&2
    exit 1
fi

ANTI-PATTERN 4: Missing Directory Creation

Problem: Writing to directories that don't exist causes silent failures.

# BAD - assumes directory exists
echo "$DATA" > ~/.claude/my-hook/state.json

# GOOD - ensure directory exists first
STATE_DIR="${HOME}/.claude/my-hook"
mkdir -p "$STATE_DIR" 2>/dev/null
echo "$DATA" > "$STATE_DIR/state.json"

ANTI-PATTERN 5: Blocking cat Reads

Problem: Using cat without timeout can block indefinitely if stdin never closes.

# BAD - can block forever
INPUT=$(cat)

# GOOD - use timeout or check for input
INPUT=$(timeout 5 cat 2>/dev/null || echo "{}")

# OR check if stdin has data
if [[ -t 0 ]]; then
    # No stdin data, use default
    INPUT="{}"
else
    INPUT=$(cat)
fi

ANTI-PATTERN 6: Silent Failures

Problem: Errors are silently swallowed, making debugging impossible.

# BAD - silent failure
jq '.key' "$FILE" 2>/dev/null

# GOOD - log errors to stderr, handle gracefully
if ! VALUE=$(jq -r '.key' "$FILE" 2>&1); then
    echo "[HOOK ERROR] Failed to parse $FILE: $VALUE" >&2
    VALUE="default"
fi

Hook Validation Checklist

Before deploying a hook, verify:

• [ ] Uses set -euo pipefail (or equivalent error handling)
• [ ] All variables are properly quoted
• [ ] No grep -P usage (use bash regex or grep -E)
• [ ] No direct sed -i (use temp file approach)
• [ ] No hardcoded paths (use environment variables)
• [ ] Directories created before use
• [ ] jq errors handled gracefully
• [ ] Timeout on stdin reads if applicable
• [ ] Errors logged to stderr
• [ ] Tested on target platform (Windows Git Bash/macOS/Linux)

Performance Monitoring

Add performance logging to all hooks:

const start = process.hrtime.bigint();
// ... hook logic ...
const durationMs = Number(process.hrtime.bigint() - start) / 1_000_000;
console.error(`[PERF] ${hookName} completed in ${durationMs.toFixed(2)}ms`);

Related Skills

• hooks-automation - General hook automation patterns
• cicd-intelligent-recovery - Error recovery patterns
• cascade-orchestrator - Multi-hook coordination

---

Last Updated: 2025-12-30 Integrated with: Claude Code Hooks v1.0.0