Hook Authoring
Design and implement Claude Code hooks across session lifecycle, tool calls, permissions, and agent coordination instead of guessing event names and payload shapes.
Overview
Hook Authoring is an agent skill for the Build phase that documents and guides implementation of Claude Code lifecycle, tool, permission, and coordination hooks.
Install
npx skills add https://github.com/athola/claude-night-market --skill hook-authoringWhat is this skill?
- Quick reference aligned to Claude Code 2.1.50 covering lifecycle, tool, permission, communication, agent, config, contex
- Documents PreToolUse / PostToolUse / PostToolUseFailure interception for validation, metrics, and error fallbacks
- Agent coordination hooks: SubagentStart, SubagentStop, TeammateIdle, TaskCompleted with continue:false teammate control
- ConfigChange and InstructionsLoaded hooks for reacting to settings and augmenting loaded instructions (2.1.33–2.1.49+)
- PreCompact hook for preserving critical context before session compaction
- Hook quick reference anchored to Claude Code 2.1.50 with 2.1.69+ teammate continue controls
Adoption & trust: 1 installs on skills.sh; 304 GitHub stars; 2/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You want Claude Code to validate tools, forward notifications, or coordinate subagents, but the hook event matrix and version-specific behavior are easy to misconfigure.
Who is it for?
Solo builders shipping Claude Code plugins who need a structured map of hook events from 2.1.20 through 2.1.69 behavior notes.
Skip if: Teams only using stock Claude Code without custom hooks, or beginners who have not yet run a single PreToolUse example in settings.
When should I use this skill?
When implementing or debugging Claude Code hooks for plugins, including lifecycle, tool, permission, and agent coordination events.
What do I get? / Deliverables
You can pick the correct hook type for each interception point and implement handlers with the right payload semantics for your plugin or night-market extension.
- Hook handler implementations mapped to specific Claude Code events
- Documented interception strategy for tools, permissions, and subagent coordination
Recommended Skills
Journey fit
Hook authoring extends the agent runtime itself—canonical placement is Build because you are implementing tooling that wraps Claude Code sessions. The readme is a hook-type catalog and authoring guide for Claude Code plugins, which is specialized agent-tooling rather than generic backend or frontend work.
How it compares
Authoring reference for Claude Code hook events—not a generic Git pre-commit hook tutorial or an MCP server integration.
Common Questions / FAQ
Who is hook-authoring for?
Indie agent builders extending Claude Code with plugins who need accurate hook names, phases, and version notes while coding handlers.
When should I use hook-authoring?
In Build (agent-tooling) while designing session guards and metrics; in Ship (review) when auditing what your hooks auto-approve; in Operate (iterate) when adjusting TeammateIdle or TaskCompleted chaining after production friction.
Is hook-authoring safe to install?
The skill is documentation for powerful interception points—review the Security Audits panel on this page and treat PermissionRequest auto-approve patterns as high-risk until you test them.
SKILL.md
READMESKILL.md - Hook Authoring
# Hook Types Overview Claude Code hook lifecycle events and their use cases. Hooks intercept specific moments in the session to inject context, validate actions, or transform outputs. ## Quick Reference (Claude Code 2.1.50) ### Lifecycle Hooks - **Setup**: One-time plugin initialization - **SessionStart**: Session initialization, context setup - **SessionEnd**: Session cleanup, metrics collection - **Stop**: Graceful shutdown, final logging ### Tool Execution Hooks - **PreToolUse**: Validation, logging, state management - **PostToolUse**: Result processing, metrics, cleanup - **PostToolUseFailure**: Error handling, fallback (2.1.20+) ### Permission Hooks - **PermissionRequest**: Auto-approve/deny patterns ### Communication Hooks - **UserPromptSubmit**: Input validation, routing - **Notification**: System notification forwarding (2.1.20+) ### Agent Coordination Hooks - **SubagentStart**: Track agent spawns (2.1.20+) - **SubagentStop**: Collect results, cleanup - **TeammateIdle**: Work assignment (2.1.33+). Supports `{"continue": false}` to stop teammate (2.1.69+). - **TaskCompleted**: Task chaining (2.1.33+). Supports `{"continue": false}` to stop teammate (2.1.69+). ### Configuration Hooks - **ConfigChange**: React to settings changes (2.1.49+) - **InstructionsLoaded**: Augment instructions (2.1.33+) ### Context Hooks - **PreCompact**: Preserve critical context before compaction ### Worktree Hooks (2.1.50+, plugin fix 2.1.69+) - **WorktreeCreate**: Initialize worktree state. Command-only (no Python SDK callback, no matchers). Must print absolute worktree path on stdout. Plugin-registered hooks were silently ignored before 2.1.69; now they fire correctly. - **WorktreeRemove**: Cleanup worktree state. Command-only (no Python SDK callback, no matchers). Receives `worktree_path` in input. Cannot block removal. Plugin-registered hooks were silently ignored before 2.1.69; now they fire correctly. ### ExitWorktree Tool (2.1.72+) New built-in tool to leave an `EnterWorktree` session mid-conversation. Parameters: - `action` (required): `"keep"` (leave worktree on disk) or `"remove"` (delete worktree and branch) - `discard_changes` (optional, default false): required `true` when action is `"remove"` and the worktree has uncommitted files or unmerged commits Restores the session CWD and clears CWD-dependent caches (system prompt, memory files, plans). Hooks can match on `ExitWorktree` in `PreToolUse`/`PostToolUse`. **Worktree isolation fixes (2.1.72+)**: Task tool resume now correctly restores CWD in worktree sessions. Background task notifications include `worktreePath` and `worktreeBranch` fields. ### HTTP Hooks (2.1.63+) Hooks can POST JSON to a URL instead of running shell commands. Use `"type": "http"` with a `"url"` field. The hook POSTs the standard hook input as JSON and expects a standard hook response JSON body. Useful for enterprise/sandboxed environments where shell execution is restricted. See `Skill(abstract:hook-authoring)` for full configuration details. ### Hook Event Fields: agent_id and agent_type (2.1.69+) All hook events now include an `agent_id` field for subagent sessions and an `agent_type` field for both subagent sessions and `--agent` invocations. Use these fields to distinguish which agent triggered the hook and to implement agent-specific hook logic. ```json { "session_id": "sess_abc", "hook_event_name": "PreToolUse", "agent_id": "backend@my-team", "agent_type": "implementer", "tool_name": "Bash", "tool_input": { "command": "make test" } } ``` Status line hooks also gain a `worktree` field (2.1.69+) containing `name`, `path`, `branch`, and `originalRepoDir` when running in a `--worktree` session. ### Cron Scheduling Tools (2.1.71+) Three new built-in tools for scheduled tasks: `CronCreate`, `CronList`, and `CronDelete`. Hooks can match on these tool names in `PreToolUse` and `PostToolUse` events. The `/loop` command uses `CronCreate` internally.