SKILL: 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:

json

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

Blocking Output:

json

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

Non-Blocking Output:

json

{
  "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:

bash

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

Stage 4: Core Logic Implementation

Implement the hook's core logic:

javascript

#!/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:

javascript

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:

javascript

// 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

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

{hook-name}.js - Main hook script
{hook-name}.test.js - Test file
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

Never log sensitive data - Filter passwords, API keys, tokens
Validate all input - Treat hook input as untrusted
Fail open for non-security hooks - Don't block on errors
Fail closed for security hooks - Block on validation errors
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:

bash

#!/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:

bash

# 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:

bash

# 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:

bash

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

5. Use Environment Variables for Paths

Never hardcode project paths:

bash

# 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.

bash

# 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.

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.

bash

# 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.

bash

# 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.

bash

# 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.

bash

# 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:

javascript

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

Search AI Tools

Install this agent skill to your Project

SKILL.md

SKILL: Hook Creator

LIBRARY-FIRST PROTOCOL (MANDATORY)

Step 1: Library Catalog

Step 2: Patterns Guide

Step 3: Existing Projects

Decision Matrix

Purpose

When to Use This Skill

8-Stage Hook Creation Methodology

Stage 1: Hook Type Selection

Stage 2: Schema Definition

Stage 3: Template Selection

Stage 4: Core Logic Implementation

Stage 5: RBAC Integration

Stage 6: Performance Optimization

Stage 7: Testing

Stage 8: Registration

Hook Templates

Pre-Hook Template (Blocking)

Post-Hook Template (Observational)

Output Artifacts

Integration Points

Agents Used

Example Invocations

Security Considerations

Shell Script Best Practices (Codex Recommendations)

1. Enable Strict Mode

2. Proper Variable Quoting

3. Defensive jq Usage

4. Ensure Directories Exist

5. Use Environment Variables for Paths

ANTI-PATTERNS TO AVOID

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

ANTI-PATTERN 2: Using sed -i Directly

ANTI-PATTERN 3: Hardcoded Paths

ANTI-PATTERN 4: Missing Directory Creation

ANTI-PATTERN 5: Blocking cat Reads

ANTI-PATTERN 6: Silent Failures

Hook Validation Checklist

Performance Monitoring

Related Skills