Hooks de Claude Code (Battle Arena)

Scripts zero-dependency que corren en la máquina de cada dev y emiten los eventos de las sesiones de Claude Code al colector (apps/public-api). NO les agregues imports de node_modules: la promesa es instalación-cero.

| Script | Hook | Qué hace | | --------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | emit.mjs | todos | Enriquece con identidad git, sanitiza y postea a /ingest; buffer local si el colector no responde | | session-start.mjs | SessionStart | Handshake + inyecta ranking (/v1/leaderboard/rank) y alerta de rama protegida | | check-connection.mjs | UserPromptSubmit | Avisa si hay desconexión o eventos en cola | | objective-nudge.mjs | UserPromptSubmit | Recuerda invocar la skill arena-objective | | execution-coach-nudge.mjs | UserPromptSubmit | Detecta señales de ejecución subóptima en el transcript y, con throttle por sesión, sugiere invocar la skill execution-coach | | pr-review-worktree.mjs | PostToolUse | Al detectar gh pr create, inyecta contexto para OFRECER (opt-in) la skill pr-review-loop; no crea worktrees ni lanza nada (de eso se encarga la skill si el usuario acepta) |

Skills distribuidas con el paquete (se copian a ~/.claude/skills/): arena-objective, arena-self-review, execution-coach (interceptor mayéutico durante la ejecución), scope-technical-task (coach de alcance pre-ejecución; el interceptor le hace handoff) y pr-review-loop (atiende la review de Copilot de un PR: corrige → gates → commit → responder/resolver hilos → re-review, hasta converger).

PR review loop (pr-review-worktree + skill pr-review-loop)

Al crear un PR con gh pr create, el hook pr-review-worktree sugiere (no lanza) activar la skill pr-review-loop. Es opt-in: la skill primero pregunta al usuario si quiere activarlo, explicando qué hará y el costo (cada re-review consume Copilot/Actions de la org) y cuántas iteraciones tolera. Si acepta, el ciclo corre en un subagente en segundo plano con worktree aislado (no bloquea la sesión ni toca el main tree): esperar review → corregir → tsc/lint → commit + git push origin HEAD:<branch> → responder/resolver hilos → re-review, hasta converger o agotar el tope. Al terminar avisa; si no convergió, indica explícitamente qué haría continuar y vuelve a preguntar. Nunca mergea (decisión humana). También se invoca a mano: /pr-review-loop <url-o-número>.

El hook pr-review-worktree queda activo solo tras (re)instalar los hooks —npx @getsupervisor/battle-arena-hooks@latest install o, desde el clone, bash apps/claude-hooks/install.sh (ambos pasan por cli.mjs, la misma fuente)—. Una instalación previa no lo tiene registrado hasta actualizar.

Estado local: ~/.claude/hook-stream/{status.json, buffer.ndjson} y, para el throttle del interceptor, ~/.claude/battle-arena/execution-coach/<session>.json.

Manejo de errores del colector

emit.mjs clasifica la respuesta de /ingest:

• 400 / 413 / 422 (evento malformado/enorme) → se descarta (no se reintenta).
• timeout / 5xx / 429 → se bufferea y se reenvía al primer envío exitoso.
• 401 / 403 (API key inválida o revocada, p. ej. tras rotar la key o reiniciar el backend) → no se bufferea (reintentar con la misma key es en vano). Se marca authError en status.json y los hooks de superficie (session-start, check-connection) le piden al usuario que genere una key nueva y reinstale con npx @getsupervisor/battle-arena-hooks@latest install --url <url> --api-key <NUEVA_KEY>. Tras un envío exitoso con la key nueva, el flag se limpia solo. Lógica compartida en lib/reauth.mjs.

Instalación rápida

La forma recomendada (cualquier SO, sin clonar) es el paquete npm — ver README raíz:

npx @getsupervisor/battle-arena-hooks@latest install \
  --url https://api.battle-arena.getsupervisor.ai --api-key sk_xxx

Desde el clone, el equivalente para contribuidores:

HOOK_STREAM_URL=https://api.battle-arena.getsupervisor.ai \
HOOK_STREAM_API_KEY=sk_xxx \
bash apps/claude-hooks/install.sh

Configuración

El instalador (cli.mjs) guarda el endpoint + api-key en ~/.claude/battle-arena/config.json y registra los hooks en ~/.claude/settings.json con comandos node "<ruta>" (sin VAR=valor inline, que no existe en Windows). Los hooks leen, en orden de prioridad:

1. Variables de entorno HOOK_STREAM_URL / HOOK_STREAM_API_KEY (si están seteadas).
2. config.json ({ "url": "...", "apiKey": "..." }).
3. Default http://127.0.0.1:4500.

HOOK_STREAM_API_KEY con ARENA_REQUIRE_AUTH=true necesita scopes arena:read (handshake/ranking) y arena:write (objetivos); /ingest acepta cualquier api-key válida.

El nudge de objetivos requiere además instalar la skill arena-objective en cada repo (o global en ~/.claude/skills/): ver docs/how-to/install-arena-objective-skill.md.

Cutover desde el colector legacy (speech-analytics/tooling/hook-stream)

1. Levanta battle-arena en el puerto 4500 (apagando antes el yarn hook-stream legacy) — la ruta /ingest y el compat /objective son idénticos: los hooks viejos siguen funcionando sin tocarlos.
2. Restaura el histórico si quieres conservar el leaderboard: pg_dump de la DB hook_stream → battle_arena (mismas tablas/columnas).
3. Actualiza tus settings para apuntar a estos hooks (ruta absoluta al clone) y borra los del repo legacy cuando todo el equipo haya migrado.