# Hooks

Reference for this plugin's hook definitions: where to edit them, where they end up, and what the
host reads.

This document lives in `docs/` rather than next to the hooks it describes. `plugins/kyberforge/hooks/`
is a **generated mirror** — `scripts/sync-plugin-content.sh` runs `rm -rf` on it before every
rebuild, so any hand-written file placed there is deleted on the next sync with no drift warning
(a prior copy of this document was lost exactly that way). See ADR-0017.

## Where to edit

Author hooks in `plugins/kyberforge/.apm/hooks/*.json`. `apm pack --format plugin` merges every
file in that directory into a single `hooks.json`, which `sync-plugin-content.sh` copies to
`plugins/kyberforge/hooks/hooks.json` — the path Claude Code convention-scans. Never edit the
mirrored file; the `check-plugin-content-sync` pre-push hook reports it as drift.

## Claude Code structure

`hooks/hooks.json` is read by Claude Code. Structure:

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "echo 'tool used'" }
        ]
      }
    ]
  }
}
```

Supported events: `PreToolUse`, `PostToolUse`, `Notification`, `Stop`.

Use `${CLAUDE_PLUGIN_ROOT}` to reference scripts inside this plugin — the plugin runs from a cache
path after install, not its original repo location.

## GitHub Copilot CLI

Copilot reads a differently-shaped `hooks.json`: `version: 1` is required, each entry is
`type: "command"` with separate `bash` and `powershell` scripts, and the lifecycle points are
lowercase and differently named (`sessionStart`, `sessionEnd`, `userPromptSubmitted`, `preToolUse`,
`postToolUse`, `errorOccurred`, `agentStop`). See
`docs/research/docs/github-copilot-plugins/configuration.md`.

There is no separate Copilot hooks file at this plugin root. An earlier revision of this document
pointed at `hooks.json` at the plugin root for Copilot; that file was a stale artifact of the
pre-ADR-0017 sync and was deleted. Both ecosystems now resolve to the single generated
`hooks/hooks.json`, which is currently empty (`{"hooks": {}}`) — the two schemas would need
reconciling before any real hook ships to both.