hooks-automation

Hooks Automation Skill

Implements Claude Code hooks using the STATUS→PROGRESS→COMPLETE 3-phase memory sync pattern for reliable hook orchestration.

Trigger

Use this skill when:

• Implementing new Claude Code hook scripts
• Debugging existing hooks (PreToolUse, PostToolUse, UserPromptSubmit, Stop)
• Adding JSON flow-control responses to existing hooks
• Implementing memory sync between hook invocations

Hook Types

Hook	Trigger	Control Response
PreToolUse	Before any tool call	{decision: "block"|"ask"|"allow", reason?}
PostToolUse	After any tool call	{suppress?: true} (suppress tool result from context)
UserPromptSubmit	On each user message	{additionalContext: "..."} (inject context)
Stop	Before session ends	{decision: "block", reason} (prevent exit)

3-Phase Memory Sync Pattern

All hooks should implement the STATUS→PROGRESS→COMPLETE lifecycle:

STATUS Phase

On hook invocation, emit status to session manifest:

appendEvent(sessionId, { type: 'stop_check', payload: { status: 'checking', ts: Date.now() } });

PROGRESS Phase

During computation, write incremental state (for long-running hooks):

appendEvent(sessionId, { type: 'stop_check', payload: { status: 'in_progress', step: 'checking_tasks' } });

COMPLETE Phase

On completion, emit final result:

appendEvent(sessionId, { type: 'stop_check', payload: { status: 'complete', result: decision } });

JSON Flow-Control Response Format

Hooks communicate with Claude Code via stdout JSON:

// Allow (default if no output)
// No output needed

// Block with reason
console.log(JSON.stringify({ decision: 'block', reason: 'X incomplete tasks remain' }));

// Ask for approval
console.log(JSON.stringify({ decision: 'ask', reason: 'Destructive action detected', reason }));

// Inject context into next prompt
console.log(JSON.stringify({ additionalContext: 'Current session has 3 pending tasks:\n1. ...' }));