Hook Author
Guided workflow for authoring and installing governance hooks to the ~/.ai/hooks/ enforcement plane. Covers the full lifecycle: describe the behavior → write the script → validate → install → test. Supported events: PreToolUse, PostToolUse, Stop, SubagentStop, PreCompact, UserPromptSubmit. Triggers on: /hook-author, 'author a hook', 'create a hook', 'write a governance hook'.
| Name | Type | Description |
|---|---|---|
behavior_description | string | What the hook should enforce or observe. |
event optional | string | The Claude Code event to hook into (PreToolUse, PostToolUse, Stop, etc.). |
blocking optional | boolean | Whether the hook should block execution on violation. |
| Name | Type | Description |
|---|---|---|
hook_script | string | The Python hook script ready to install at ~/.ai/hooks/. |
settings_entry | object | The settings.json hooks entry to wire the hook. |
- writes Python script to ~/.ai/hooks/
- edits ~/.claude/settings.json to wire the hook
Guide the user through authoring a governance hook. Step 1 DESCRIBE: ask what behavior the hook should enforce. Which event (PreToolUse/PostToolUse/Stop/etc.)? Blocking or non-blocking? What trigger pattern? Step 2 WRITE: implement the hook in Python following the _lib.py conventions in ~/.ai/hooks/. For blocking hooks: emit JSON {hookSpecificOutput: {permissionDecision: 'deny', permissionDecisionReason: '...'}}. For non-blocking: emit modified payload or nothing. Always exit 0. Step 3 VALIDATE: run --self-check to verify the hook loads without errors. Step 4 INSTALL: add to ~/.claude/settings.json hooks array. Step 5 TEST: trigger the hook manually and verify it behaves correctly. Also publish as a hook atom to ai-atoms. End each step with Did/Next/Blocked/Artifact.