/hook-creator

name: hook-creator
description: "Create new Claude Code lifecycle hook (PreToolUse/PostToolUse/Stop/SessionStart) with bash + hooks.json. Triggers: create hook, lifecycle hook, PreToolUse, PostToolUse, hook event."
effort: high
disable-model-invocation: true
argument-hint: "[hook event or description]"
allowed-tools: Read, Write, Edit, Bash, Grep, Glob

Hook Creator

$ARGUMENTS

Create a new Claude Code hook following ai-toolkit conventions.

Supported Hook Events

Core lifecycle

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `SessionStart` | Session begins, resumes, or clears | `startup\|resume\|clear` | Context injection, rules reminder | | `SessionEnd` | Session is closing | any | Flush logs, save transcripts | | `UserPromptSubmit` | User submits a prompt | any | Prompt governance, usage tracking | | `Notification` | Claude sends a notification | any | OS alerts, Slack pings | | `MessageDisplay` | Assistant message text streams in completed-line batches | none | Return `displayContent` to replace the rendered batch without changing the transcript |

Tool lifecycle

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `PreToolUse` | Before a tool executes | tool name (e.g. `Bash`) or `if:` rule | Safety guards, validation, `"defer"` for headless | | `PostToolUse` | After a tool executes | tool name | Feedback loops, logging, format-on-save | | `PostToolUseFailure` | After a tool fails | tool name | Failure telemetry, recovery hints | | `PostToolBatch` | After a batch of tool calls completes | any | Batch summaries, aggregate validation |

Turn lifecycle

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `Stop` | Claude finishes responding | any | Quality checks, session save | | `StopFailure` | Turn ends due to an API error (rate limit, auth) | any | Alerting, fallback behavior | | `UserPromptExpansion` | Claude expands or rewrites a submitted prompt | any | Prompt policy and context shaping |

Subagent lifecycle

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `SubagentStart` | Subagent launches | any | Observability | | `SubagentStop` | Subagent completes | any | Result validation |

Compaction

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `PreCompact` | Before context compaction; can block with exit 2 or `{"decision":"block"}` | any | Context preservation | | `PostCompact` | After compaction completes | any | Re-inject state that was summarized away |

Model changes

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `PreModelSwitch` | Before a user/client model switch; exit 2 or `decision: "block"` cancels it | canonical target model | Model policy; requires Claude Code 2.1.251+ | | `PostModelSwitch` | After the session model changes; cannot block | canonical target model | Model-specific context; requires Claude Code 2.1.251+ |

Permissions & elicitation

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `PermissionRequest` | Tool awaiting permission; can return `updatedInput` | any | Headless approval flows | | `PermissionDenied` | Auto-mode classifier denied a tool call; return `{retry: true}` to allow retry | any | Coach the model, log denials | | `Elicitation` | MCP `elicitation/create` request arrives | any | Intercept / override MCP UI prompts | | `ElicitationResult` | Elicitation response ready to be sent back | any | Validate / transform elicitation replies |

Agent Teams

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `TaskCreated` | New task registered via `TaskCreate` | any | Audit, assignment routing | | `TaskCompleted` | Agent Teams task finished | any | Lint, type check, notify | | `TeammateIdle` | Agent Teams member idle | any | Completeness reminder |

Worktrees & environment

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `WorktreeCreate` | Worktree is being created; `type: "http"` can return `hookSpecificOutput.worktreePath` | any | Provision worktree dirs | | `WorktreeRemove` | Worktree is being removed | any | Cleanup | | `CwdChanged` | Working directory changes during a session | any | Reactive env management (e.g., direnv) | | `DirectoryAdded` | A working directory was added with `/add-dir` or SDK `register_repo_root`; runs asynchronously after the add and cannot block it | `slash_command\|register_repo_root` | Prepare a newly added repository | | `FileChanged` | Tracked file is modified on disk | any | Re-lint, reload config | | `ConfigChange` | Settings / config file changed | any | Re-validate, warn on drift |

Setup / bootstrap

| Event | Fires When | Matcher | Typical Use | |-------|-----------|---------|-------------| | `Setup` | First-run / initialization | any | Project bootstrap | | `InstructionsLoaded` | CLAUDE.md or `.claude/rules/*.md` loaded into context | load reason | Verify presence of mandatory rules |

Hook Handler Types

Claude Code supports five handler `type` values in `hooks.json`:

| Type | Purpose | Required fields | |------|---------|-----------------| | `command` | Run a shell script / binary | `command` (path + args) | | `http` | Call a local or remote HTTP endpoint | `url` | | `prompt` | Inject a prompt to the fast inline model and use its verdict | `prompt` | | `agent` | Spawn an experimental tool-using subagent to evaluate the event | `prompt` | | `mcp_tool` | Invoke an already-connected MCP tool | `server`, `tool`; optional `input` object |

`command` remains the default and ai-toolkit's hook entries all use it. The other types are documented here so you can author them by hand when needed.

`PermissionRequest` accepts `prompt` hooks but skips `agent` hooks. Both