/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 is about to be shown to the user | any | Transform or hide assistant message text before display |

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 |

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) | | `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 / AGENTS.md loaded into context | any | 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 a full subagent to evaluate the event (must target `Stop` / `SubagentStop`) | `agent` (agent name) | | `mcp_tool` | Invoke an MCP tool directly (no subprocess) | `server`, `tool`, `arguments` |

`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.

Workflow

1. **Capture intent** -- ask: what should the hook do? Which lifecycle event? 2. **Select event** -- pick from the Supported Hook Events table above 3. **Define matcher** -- tool name for PreToolUse/PostToolUse, empty for global 4. **Write script** -- create `app/hooks/{event-name-kebab}.sh` 5. **Register in hooks.json** -- add entry to `app/hooks.json` 6. **Validate** -- run `scripts/validate.py`

Hook Script Conventions

• Location: `app/hooks/{event-name-kebab}.sh`
• Shebang: `#!/bin/bash`
• Header comment: script name, purpose, event, matcher
• Respect `TOOLKIT_HOOK_PROFILE` env var (`minimal` = skip non-essential hooks)
• Always `exit 0` on success (non-zero blocks the operation for Pre* hooks)
• Output goes to Claude's context as pl