Claude Hook Writer

Status

Production Ready

Version

2.0.0 (Optimized with progressive disclosure)

Last Updated

2025-12-17

Overview

Expert guidance for writing secure, reliable, and performant Claude Code hooks. This skill validates design decisions, enforces best practices, and prevents common pitfalls.

When to Use This Skill

Designing a new Claude Code hook

Reviewing existing hook code

Debugging hook failures

Optimizing slow hooks

Securing hooks that handle sensitive data

Publishing hooks as PRPM packages

Core Principles

1. Security is Non-Negotiable

Hooks execute automatically with user permissions and can read, modify, or delete any file the user can access.

ALWAYS validate and sanitize all input.

Hooks receive JSON via stdin—never trust it blindly.

For complete security patterns

Load

references/security-requirements.md

when implementing validation or securing hooks.

2. Reliability Over Features

A hook that works 99% of the time is a broken hook. Edge cases (Unicode filenames, spaces in paths, missing tools) will happen.

Test with edge cases before deploying.

For reliability patterns

Load

references/reliability-performance.md

when handling errors or edge cases.

3. Performance Matters

Hooks block operations. A 5-second hook means Claude waits 5 seconds before continuing.

Keep hooks fast. Run heavy operations in background.

For performance optimization

Load references/reliability-performance.md when optimizing hook speed. 4. Fail Gracefully Missing dependencies, malformed input, and disk errors will occur. Handle errors explicitly. Log failures. Return meaningful exit codes. Hook Design Checklist Before writing code, answer these questions: What Event Does This Hook Target? PreToolUse - Before tool execution (modify input, validate, block) PostToolUse - After tool completes (format, log, cleanup) UserPromptSubmit - Before user input processes (validate, enhance) SessionStart - When Claude Code starts (setup, env check) SessionEnd - When Claude Code exits (cleanup, persist state) Notification - During alerts (desktop notifications, logging) Stop / SubagentStop - When responses finish (cleanup, summary) PreCompact - Before context compaction (save important context) Common mistake: Using PostToolUse for validation (too late—tool already ran). Use PreToolUse to block operations. Which Tools Should Trigger This Hook? Be specific. matcher: "" runs on every tool call. Good matchers: "Write" - Only file writes "Edit|Write" - File modifications "Bash" - Shell commands "mcp__github__" - All GitHub MCP tools Bad matchers: "*" - Everything (use only for logging/metrics) What Input Does This Hook Need? Different tools provide different input. Check what's available:

PreToolUse / PostToolUse

{

"input"

:

{

"file_path"

:

"/path/to/file.ts"

, // Read, Write, Edit

"command"

:

"npm test"

, // Bash

"old_string"

:

"..."

, // Edit

"new_string"

:

"..."

// Edit

}

}

Validate fields exist before using them:

FILE

=

$(

echo

"

$INPUT

"

|

jq

-r

'.input.file_path // empty'

)

if

[

[

-z

"

$FILE

"

]

]

;

then

echo

"No file path provided"

>

&2

exit

1

fi

Should This Be a Command Hook or Prompt Hook?

Command hooks

(

type: "command"

):

Fast (milliseconds)

Deterministic

Good for: formatting, logging, file checks

Prompt hooks

(

type: "prompt"

):

Slow (2-10 seconds)

Context-aware (uses LLM)

Good for: complex validation, security analysis, intent detection

Rule of thumb:

Use command hooks unless you need LLM reasoning.

What Exit Code Communicates Success/Failure?

exit 0

- Success (continue operation)

exit 2

- Block operation (show error to Claude)

exit 1

or other - Non-blocking error (log but continue)

For PreToolUse hooks:

Exit 2 blocks the tool from running

Exit 0 allows it (optionally with modified input)

For PostToolUse hooks:

Exit codes don't block (tool already ran)

Use exit 0 for success, 1 for logging errors

Top 5 Pitfalls (Must Know)

Pitfall #1: Not Quoting Variables

Error

Hooks break on filenames with spaces or special characters

Why

Unquoted variables split on whitespace Example :

❌ WRONG - breaks on "my file.txt"

cat $FILE prettier --write $FILE rm $FILE

✅ RIGHT - handles spaces and special chars

cat

"

$FILE

"

prettier

--write

"

$FILE

"

rm

"

$FILE

"

Why this matters

Files with spaces (

"my file.txt"

), Unicode (

"文件.txt"

), or special chars (

"file (1).txt"

) are common.

For quoting best practices

Load

references/security-requirements.md

for comprehensive input handling patterns.

Pitfall #2: Trusting Input Without Validation

Error

Hook executes on malicious or malformed input

Why

Not validating JSON fields before using them Example :

❌ DANGEROUS - no validation

FILE

$( jq -r '.input.file_path' ) rm " $FILE "

Could delete ../../../etc/passwd

✅ SAFE - validate first

FILE

$(

jq

-r

'.input.file_path // empty'

)

[

[

-n

"

$FILE

"

]

]

||

exit

1

[

[

"

$FILE

"

==

"

$CLAUDE_PROJECT_DIR

"

*

]

]

||

exit

2

[

[

"

$FILE

"

!=

*

".."

*

]

]

||

exit

2

rm

"

$FILE

"

Why this matters

Prevents path traversal attacks, protects files outside project, prevents malformed input crashes.

For complete security patterns

Load

references/security-requirements.md

.

Pitfall #3: Blocking Operations Too Long

Error

Hook takes 30+ seconds, blocking Claude

Why

Running expensive operations (tests, builds) synchronously in hook Example :

❌ BLOCKS Claude for 30 seconds

npm test npm run build

✅ RUN IN BACKGROUND - returns immediately

(

npm

test

>

/tmp/test-results.log

2

>

&1

&

)

(

npm run build

>

/tmp/build.log

2

>

&1

&

)

exit

0

Why this matters

Slow hooks create bad user experience. Target < 100ms for PreToolUse, < 500ms for PostToolUse.

For performance optimization

Load

references/reliability-performance.md

.

Pitfall #4: Wrong Exit Code for Blocking

Error

PreToolUse hook doesn't actually block the operation

Why

Using exit 1 instead of exit 2 Example :

❌ WRONG - logs error but doesn't block

if [ [ $FILE == ".env" ] ] ; then echo "Don't edit .env"

&2 exit 1

Tool still runs!

fi

✅ RIGHT - actually blocks

if [ [ $FILE == ".env" ] ] ; then echo "Blocked: .env is protected"

&2 exit 2

Tool is blocked

fi

Why this matters

Exit 1 only logs errors. Exit 2 is required to block in PreToolUse hooks.

For exit code patterns

Load

references/hook-templates.md

for complete hook response patterns.

Pitfall #5: Assuming Tools Exist

Error

Hook crashes when dependency is missing

Why

Not checking if tool is installed before using Example :

❌ BREAKS if prettier not installed

prettier --write " $FILE "

✅ SAFE - check first

if command -v prettier &> /dev/null ; then prettier --write " $FILE " else echo "prettier not installed, skipping"

&2 exit 0

Success exit, just skip

fi

Why this matters

Users may not have all tools installed. Hooks should degrade gracefully.

For reliability patterns

Load

references/reliability-performance.md

.

Critical Rules

Always Do

✅ Validate all JSON input before using (

jq -r '... // empty'

)

✅ Quote all variables containing paths or user input

✅ Use absolute paths for scripts (

${CLAUDE_PLUGIN_ROOT}/...

)

✅ Block sensitive files (

.env

,

*.key

, credentials)

✅ Check if required tools exist (

command -v toolname

)

✅ Set reasonable timeouts (< 5s for PreToolUse)

✅ Run heavy operations in background

✅ Test with edge cases (spaces, Unicode, special chars)

✅ Use exit 2 to block in PreToolUse hooks

✅ Log errors to stderr or file, not stdout

Never Do

❌ Trust JSON input without validation

❌ Use unquoted variables ($FILE instead of "$FILE")

❌ Use relative paths for scripts

❌ Skip path sanitization (check for

..

, validate in project)

❌ Assume tools are installed

❌ Block for > 1 second in PreToolUse hooks

❌ Use exit 1 when you mean to block (use exit 2)

❌ Log sensitive data to stdout or files

❌ Use

matcher: "*"

unless truly necessary

When to Load References

Load reference files when working on specific hook aspects:

Security Requirements (

references/security-requirements.md

)

Load when:

Implementing input validation and sanitization

Securing hooks that handle sensitive data

Blocking sensitive files (

.env

, keys, credentials)

Preventing path traversal attacks

Understanding security vulnerabilities and best practices

Testing security with malicious input

Reliability & Performance (

references/reliability-performance.md

)

Load when:

Handling missing dependencies or tools

Setting timeouts and handling slow operations

Optimizing hook performance (< 100ms target)

Running heavy operations in background

Caching expensive results

Testing with edge cases (Unicode, spaces, deep paths)

Deduplicating expensive operations

Code Templates (

references/code-templates.md

)

Load when:

Starting a new hook and need working examples

Implementing format-on-save functionality

Blocking sensitive files from modification

Logging commands or operations

Using prompt-based security analysis

Customizing templates for specific use cases

Testing & Debugging (

references/testing-debugging.md

)

Load when:

Writing test cases for hooks

Debugging hook failures or unexpected behavior

Testing with edge cases (malformed JSON, missing fields)

Checking hook execution in transcript (Ctrl-R)

Profiling hook performance

Creating automated test suites

Publishing Guide (

references/publishing-guide.md

)

Load when:

Publishing hooks to PRPM registry

Creating package manifest (prpm.json)

Configuring hook.json with advanced options

Using

continue

,

stopReason

,

suppressOutput

,

systemMessage

Writing README.md for users

Understanding versioning and publishing commands

Quick Reference (

references/quick-reference.md

)

Load when:

Need quick syntax lookup (exit codes, jq patterns)

Looking up environment variables

Finding common bash patterns (file validation, background execution)

Checking hook events and matchers

Need performance tips summary

Looking up JSON input structure

Final Checklist

Before publishing a hook:

Validates all stdin input with jq

Quotes all variables

Uses absolute paths for scripts

Blocks sensitive files (

.env

,

*.key

, etc.)

Handles missing tools gracefully

Sets reasonable timeout (< 5s for PreToolUse)

Logs errors to stderr or file, not stdout

Tests with edge cases (spaces, Unicode, malformed JSON)

Tests in real Claude Code session

Documents dependencies in README

Uses semantic versioning

Clear description and tags

Using Bundled Resources

This skill includes 6 reference files for on-demand loading:

Security & Reliability

(2 files):

security-requirements.md

- Input validation, path sanitization, blocking sensitive files

reliability-performance.md

- Error handling, timeouts, performance optimization

Implementation

(2 files):

code-templates.md

- Working hook examples (format-on-save, block-sensitive, logger, etc.)

quick-reference.md

- Fast syntax lookup (exit codes, jq patterns, environment vars)

Testing & Publishing

(2 files):

testing-debugging.md

- Test patterns, edge cases, debugging techniques

publishing-guide.md

- PRPM packaging, advanced configuration, README template

Load references on-demand when specific knowledge is needed. See "When to Load References" section for triggers.

Resources

Claude Code Hooks Docs

PRPM Hook Packages

Last verified

2025-12-17 |

Version

2.0.0