Hook Authoring Guide

When NOT To Use

• Auditing a hook that already exists (use abstract:hooks-eval)
• Choosing where a hook should live (use abstract:hook-scope-guide)
• Authoring a skill rather than a hook (use abstract:skill-authoring)

Hook Authoring Guide

Overview

Hooks are event interceptors that allow you to extend Claude Code and Claude Agent SDK behavior by executing custom logic at specific points in the agent lifecycle. They enable validation before tool use, logging after actions, context injection, workflow automation, and security enforcement.

This skill teaches you how to write effective, secure, and performant hooks for both declarative JSON (Claude Code) and programmatic Python (Claude Agent SDK) use cases.

Key Capabilities

• PreToolUse: Validate, filter, or transform tool inputs before execution; inject context (2.1.9+)
• PostToolUse: Log, analyze, or modify tool outputs after execution
• UserPromptSubmit: Inject context or filter user messages before processing
• Stop/SubagentStop: Cleanup, final reporting, or result aggregation
• TeammateIdle/TaskCompleted: Multi-agent coordination and orchestration (2.1.33+)
• PreCompact: State preservation before context window compaction

New in 2.1.9: PreToolUse hooks can now return additionalContext to inject information before a tool executes. This enables patterns like cache hints, security warnings, or relevant context injection.

Quick Start

Your First Hook (JSON - Claude Code)

Create a simple logging hook in .claude/settings.json:

{
  "PostToolUse": [
    {
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "echo \"$(date): Executed $(jq -r '.tool_name')\" >> ~/.claude/audit.log"
      }]