workflow-add-hook

# Add New Hook

Add a new Claude Code hook event to the claude-code-hooks project.

**Hook event name:** `$ARGUMENTS` (if empty, ask the user)

**Naming rules:**
- Hook name is **PascalCase** (e.g. `ConfigChange`, `PreToolUse`)
- Sound folder/files use **lowercase** with no separators (e.g. `configchange`, `pretooluse`)

---

## Step 0: Validate

If `$ARGUMENTS` is empty, ask the user for the hook event name. Confirm it's PascalCase. Derive the lowercase version.

## Step 1: Check Sound Files (BLOCKING)

Check if `.claude/hooks/sounds/<lowercase>/` exists with `<lowercase>.mp3` and `<lowercase>.wav`.

- **If missing:** Create the directory, tell the user to add sound files (suggest ElevenLabs with voice "Samara X"), and **STOP. Do NOT proceed until the user confirms files are added.**
- **If present:** Continue to Step 2.

## Step 2: Research the Hook

Fetch all three sources in parallel using WebFetch:
1. **Hooks Reference** — Find the hook's description, matcher support, can-block status, and special requirements
2. **Hooks Guide** — Find hook types, matcher values with examples, environment variables, and additional usage details
3. **Changelog** — Find which Claude Code version introduced this hook

**Never ask the user for version or description — always look it up.**

## Step 3: Determine Hook Properties

| Property | Rule |
|----------|------|
| `timeout` | Default `5000`. Use `30000` only for heavy init hooks (like `Setup`) |
| `once` | Only for session-lifecycle hooks (like `SessionStart`, `SessionEnd`, `PreCompact`). Ask user if unsure, default to `false` |
| `async` | Always `true` (all hooks in this project are async sound notifications) |

## Step 4: Update All Files

Read each file first, then edit. **ALL files must be updated — no exceptions.**

### Settings files (4 files)

Add the hook entry in correct position. Structure:

```json
"<HookEventName>": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py",
        "timeout": <timeout>,
        "async": true,
        "statusMessage": "<HookEventName>"
      }
    ]
  }
]
```

Add `"once": true` only if applicable.

| File | Notes |
|------|-------|
| `.claude/settings.json` | `python3` + `${CLAUDE_PROJECT_DIR}` |
| `install/settings-mac.json` | Same as above |
| `install/settings-linux.json` | Same as above |
| `install/settings-windows.json` | Uses `python` (no `3`) + relative path `.claude/hooks/scripts/hooks.py` (no `${CLAUDE_PROJECT_DIR}`) |

### `.claude/hooks/config/hooks-config.json`

Add `"disable<HookEventName>Hook": false` **before** the `"disableLogging"` line (keep `disableLogging` last).

### `.claude/hooks/scripts/hooks.py`

- Add `"<HookEventName>": "<lowercase>"` to `HOOK_SOUND_MAP` (NOT `AGENT_HOOK_SOUND_MAP`)
- Update the docstring hook count

### `.claude/hooks/HOOKS-README.md`

- Update heading count ("Official N Hooks")
- Add the hook to the numbered list with description from docs
- Update the shared config JSON block with new `disable<HookEventName>Hook` entry
- **If the hook is NOT listed in the [Official Hooks Reference](https://code.claude.com/docs/en/hooks)** (i.e. it only appears in the changelog), add a row to the "Not in Official Docs" table with the hook name, version, changelog quote, and a note that it's excluded from the official reference page
- **CRITICAL — Sweep for stale counts:** After updating the heading, grep the ENTIRE file for every occurrence of the OLD hook count (e.g. if going from 26 to 27, search for `26 hooks`, `not all 26`, `remaining \d+ hooks`, `all 26`, `of 26`). Update ALL stale count references in prose text, including:
  - The "Not in Official Docs" table notes (e.g. "(N hooks listed, Setup excluded)")
  - The Agent Frontmatter section "Not all N" and "remaining N hooks" references
  - Any cross-reference anchors containing the old count (e.g. `#official-N-hooks`)
  - The hook type classification totals (supported + command-only must sum to new total)
  - Run: `grep -n '\b<OLD_COUNT> hook' .claude/hooks/HOOKS-README.md` and `grep -n 'remaining [0-9]* hook' .claude/hooks/HOOKS-README.md` to find ALL instances

### `README.md`

- Update the **Version badge** timestamp to the current PKT time. Run `TZ=Asia/Karachi date "+%b %d, %Y %-I:%M %p PKT"` to get it, then URL-encode and replace the date in the `[![Version](...)]` badge on line 2. Also update the version number in the badge if it changed.
- Update "supports all N hooks" count
- Add a new changelog table row at the TOP:
  ```
  | <today's date> | <N> | Added `<HookEventName>` | [v<version>](<changelog-link>) | |
  ```

### `.claude/agents/claude-code-test-agent.md`

- Add the new hook to the agent's frontmatter `hooks:` section using the same pattern as existing hooks (echo hook name + timestamp to `tests-agents-hook/agent-hook-fired.log`, `timeout: 5000`, `async: true`). Use `timeout: 30000` only for `Setup`.
- Update the description line's hook count ("Tests all N Claude Code hooks")
- Add the hook to the "All N Hooks Configured" list with a one-line description
- Add the hook to the "Hook Trigger Summary" output format list
- Update all "N" hook count references in the agent body

### Demo files (3 files)

The `demo/` directory has its own hook setup that mirrors the main project. All three files must be updated:

#### `demo/.claude/settings.json`

Add the hook entry using the same structure as existing entries:

```json
"<HookEventName>": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/demo-hooks.py",
        "timeout": <timeout>,
        "async": true,
        "statusMessage": "<HookEventName>"
      }
    ]
  }
]
```

Add `"once": true` only if applicable. Use `"async": false` only for WorktreeCreate/WorktreeRemove-style hooks. Use timeout `30000` only for Setup.

#### `demo/.claude/hooks/scripts/demo-hooks.py`

- Add `"<HookEventName>": "<lowercas