fix-hook-errors

What this skill does

# Fix Plugin Hook Loading Errors

Systematic workflow for diagnosing and fixing Claude Code plugin hook validation failures.

## When This Fires

`/doctor` reports something like:
```
Plugin Errors
  └ resilient-flows@A2X [resilient-flows]: Hook load failed: [
    { "expected": "record", "code": "invalid_type", "path": ["hooks"], "message": "..." }
  ]
```

## Step 1 — Read the Error

Parse the `/doctor` output for:
- **Plugin name** and marketplace (e.g., `resilient-flows@A2X`)
- **Zod path** (e.g., `["hooks"]`) — where in the schema validation failed
- **Expected vs received** (e.g., `expected record, received array`)

Common error signatures:

| Error | Meaning |
|-------|---------|
| `expected record, received array` at `["hooks"]` | `hooks` value is `[...]` instead of `{...}` |
| `expected record, received undefined` at `["hooks"]` | Missing `"hooks"` wrapper key (flat format used instead of plugin format) |
| `Duplicate hooks file detected` | `plugin.json` explicitly declares `"hooks": "./hooks/hooks.json"` but the file is also auto-discovered |

## Step 2 — Locate All Copies

**Critical**: The plugin loader reads from CACHED copies, not the source. Find all copies:

```bash
find ~/.claude/plugins -name "hooks.json" -path "*<plugin-name>*" 2>/dev/null
find ~/.claude-work/plugins -name "hooks.json" -path "*<plugin-name>*" 2>/dev/null
```

Typical locations (all must be updated):
1. **Source**: `~/.claude/plugins/marketplaces/<marketplace>/plugins/<plugin>/hooks/hooks.json`
2. **Cache**: `~/.claude-work/plugins/cache/<marketplace>/<plugin>/<version>/hooks/hooks.json`
3. **Marketplaces mirror**: `~/.claude-work/plugins/marketplaces/<marketplace>/plugins/<plugin>/hooks/hooks.json`

## Step 3 — Fix the Schema

The canonical plugin `hooks/hooks.json` format is:

```json
{
  "description": "Optional description of what these hooks do",
  "hooks": {
    "<EventName>": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/my-hook.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
```

**Rules:**
- Top-level `"hooks"` key is **required** and must be a **record/object** (not array)
- `"description"` at top level is **optional**
- Each event name key maps to an **array of matcher groups**
- Each matcher group has `"matcher"` (regex string, `"*"`, or omitted) and `"hooks"` (array of handlers)
- Handler `"type"` must be one of: `command`, `http`, `prompt`, `agent`
- Always use `${CLAUDE_PLUGIN_ROOT}` for portable paths, quoted for spaces

**Validate event names** — only these are valid:
`SessionStart`, `SessionEnd`, `UserPromptSubmit`, `PreToolUse`, `PermissionRequest`, `PermissionDenied`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `Stop`, `StopFailure`, `TeammateIdle`, `InstructionsLoaded`, `ConfigChange`, `CwdChanged`, `FileChanged`, `WorktreeCreate`, `WorktreeRemove`, `PreCompact`, `PostCompact`, `Elicitation`, `ElicitationResult`

**Note:** `SessionStart`, `CwdChanged`, and `FileChanged` only support `command` hooks (not `prompt`/`agent`/`http`).

For the full hook schema reference, invoke the `hooks-authoring-reference` skill from this plugin.

## Step 4 — Check plugin.json

Read the plugin's `.claude-plugin/plugin.json` and verify:

1. **No explicit hooks declaration** — `hooks/hooks.json` is auto-discovered. If you see `"hooks": "./hooks/hooks.json"`, **remove it**. This causes the "Duplicate hooks file" error.
2. Check all cached copies of plugin.json too (same paths as Step 2 but for `.claude-plugin/plugin.json`).

## Step 5 — Apply Fix to ALL Copies

Write the corrected `hooks.json` to every location found in Step 2. Use the Write tool to update each file. Do NOT skip any cached copy — the loader may read from any of them.

Similarly, if plugin.json needed changes, update all copies.

## Step 6 — Verify

1. Run `/reload-plugins` — check for error count
2. Run `/doctor` — confirm the hook error is gone
3. Run `/hooks` — confirm the plugin's hooks appear under the correct events
4. Optionally: `claude --debug` to see hook registration details

## Common Pitfalls

| Pitfall | Fix |
|---------|-----|
| Fixed source but not cache | Always `find` for ALL copies and update each one |
| Used flat format (events at top level) | Plugin format requires `{"hooks": {...}}` wrapper |
| Used array format (`"hooks": [...]`) | Must be record: `"hooks": {"EventName": [...]}` |
| Added `"hooks"` to plugin.json | Remove it — auto-discovery handles standard path |
| Invalid event name | Check against the 26 valid event names above |
| `prompt`/`agent` hook on SessionStart | SessionStart only supports `command` hooks |
| Missing `"matcher"` field | Optional but recommended — use `"*"` for all |

## Escalation

If the error persists after all fixes:
- Check if the marketplace has a newer version of the plugin
- Try disabling and re-enabling the plugin via `/plugin`
- Clear the plugin cache entirely: `rm -rf ~/.claude-work/plugins/cache/<marketplace>/<plugin>/`
- Then `/reload-plugins` to force a fresh cache build