Hook Creator

hooks.json Entry Format

{
    "_source": "ai-toolkit",
    "matcher": "",
    "hooks": [
        {
            "type": "command",
            "command": "\"$HOME/.softspark/ai-toolkit/hooks/{script-name}.sh\""
        }
    ]
}

Required fields:

• _source: always "ai-toolkit" (used by merge/strip logic)
• matcher: tool name or regex for Pre/PostToolUse, empty string for global events
• hooks[].type: "command", "http", "prompt", "agent", or "mcp_tool" (ai-toolkit uses "command")
• hooks[].command: path to script using $HOME/.softspark/ai-toolkit/hooks/ prefix (for type: command)

Optional fields (read from Claude Code docs, not emitted by ai-toolkit by default):

Common to every handler type:

• hooks[].if: one permission-rule filter (e.g. "Bash(git push*)"); evaluated only for tool events
• hooks[].timeout: seconds to wait before canceling the handler (type and event defaults apply if omitted)
• hooks[].statusMessage: short message surfaced in the UI while the hook runs
• hooks[].once: run once per session; only honored in skill frontmatter and ignored in settings files or agent frontmatter

Command-handler fields:

• hooks[].args: argument vector for exec form. Prefer exec form when a command uses ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT}, or ${CLAUDE_PLUGIN_DATA} path placeholders
• hooks[].async: run in the background without blocking; background hooks cannot return decisions
• hooks[].asyncRewake: run in the background and wake Claude on exit code 2; implies async
• hooks[].shell: choose bash or powershell for shell form; ignored when args selects exec form

Prompt and agent handlers both require hooks[].prompt; type: agent does not accept an agent name field. Agent handlers are experimental, so prefer command for production enforcement.

MessageDisplay has no matcher, runs once per rendered batch in interactive sessions, and defaults to a 10-second timeout. Its displayContent output changes only the screen text; Claude and the transcript retain the original response. DirectoryAdded is always asynchronous and non-blocking regardless of the handler configuration.

Script Template

#!/bin/bash
# {script-name}.sh — {One-line purpose}.
#
# Fires on: {EventName}
# Matcher: {matcher or "all"}
# Skipped when TOOLKIT_HOOK_PROFILE=minimal.

PROFILE="${TOOLKIT_HOOK_PROFILE:-standard}"
[ "$PROFILE" = "minimal" ] && exit 0

# --- Hook logic here ---

exit 0

Rules

• MUST use one script per hook entry — no inline multi-line commands inside hooks.json
• MUST keep Pre* hooks fast and deterministic — they gate every matching tool call, slow hooks throttle the whole agent
• NEVER write secrets, tokens, or credentials to stdout — hook output is injected into LLM context and can be extracted
• NEVER exit non-zero from a Post* or Stop hook unless you intend to block further processing; exit 0 is the safe default
• CRITICAL: respect the TOOLKIT_HOOK_PROFILE env var. Profile minimal must be a no-op for non-essential hooks.
• MANDATORY: test the script standalone (bash app/hooks/{name}.sh) before adding it to hooks.json

Gotchas

• PreToolUse hooks that exit non-zero block the tool call. A slow or flaky hook (network call, lock contention) becomes a DoS against Claude's own workflow. Keep Pre hooks to pure-bash checks of local state.
• Hook output (stdout) is injected verbatim into the model's context. A hook that runs git log --all prints hundreds of lines the model then has to wade through — be surgical, print only what matters.
• The path in hooks.json is resolved relative to the user's machine, not the ai-toolkit repo. Use $HOME/.softspark/ai-toolkit/hooks/<name>.sh as the canonical location (installer symlinks there).
• SessionStart with matcher startup|compact fires on both fresh starts AND after context compaction. Hooks that assume "new session" will mis-fire after compaction — check for explicit context markers if the distinction matters.
• Bash hooks on Windows (without WSL) will not run. If the hook must work cross-platform, wrap it in a Node or Python script and call from the bash stub — or flag the hook as posix-only in the description.

Validation Checklist

After creating the hook:

• Script exists in app/hooks/ and is executable (chmod +x)
• Entry added to app/hooks.json with _source: "ai-toolkit"
• Event name matches a supported lifecycle event
• scripts/validate.py passes
• Script runs without errors: bash app/hooks/{name}.sh
• Hook count in README.md and docs updated if needed

When NOT to Use

• For a skill (slash command) — use /skill-creator
• For an agent definition — use /agent-creator
• For a git pre-commit hook (not a Claude Code hook) — use /git-mastery or scripts/install_git_hooks.py
• For one-off automation that is not tied to a Claude Code event — use a plain shell script outside the toolkit
• To modify an existing toolkit hook — edit the file directly; this skill is create-only