@thebattlearena/battle-arena-hooks 0.0.0-stage → 0.5.2

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# Hooks de Claude Code (Battle Arena)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+@thebattlearena/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`.
+
+## Qué se censura antes de enviar (`lib/sanitize.mjs`)
+
+Antes de salir de tu máquina, cada evento pasa por `lib/sanitize.mjs` (patrones en
+`lib/secret-patterns.mjs`):
+
+- **Paths de tu máquina**: tu homedir y `/Users/<x>` / `/home/<x>` → `~`.
+- **Variables sensibles por nombre** (`PASSWORD`, `*_TOKEN`, `*_SECRET`, `api_key`, `AUTH`, y en
+  estilo env `KEY` / `*_KEY`): se conserva el nombre y el valor queda en `***`.
+- **Llaves de proveedor sueltas** en cualquier texto (comando, resultado, prompt): Retell, OpenAI /
+  Anthropic, Linear, GitHub, Slack, Stripe, Google, JWT y AWS; se conserva el prefijo (`sk-***`).
+- **Headers y URLs**: `x-api-key`, `Authorization` (con o sin `Bearer`), `?api_key=` / `?token=`
+  y credenciales en URIs (`scheme://user:***@host`).
+- **Archivos `.env` leídos** (Read/Grep de un `.env`/`.env.*`/`*.env`, o `cat`/`head`/`tail`/`grep`
+  de uno por Bash): cada línea `NOMBRE=valor` del resultado queda `NOMBRE=***`.
+- Strings de más de 4000 caracteres se recortan.
+
+El colector aplica el mismo filtro al ingerir (defensa en profundidad para instalaciones viejas):
+`packages/contexts/arena/domain/services/secret-redaction.service.ts`. La paridad entre ambos la
+cuidan vectores compartidos (`packages/contexts/arena/domain/__tests__/fixtures/secret-redaction.vectors.json`)
+que corren las dos suites: `yarn workspace @thebattlearena/battle-arena-hooks test` (o
+`node --test apps/claude-hooks/test/*.test.mjs`) y el jest de la raíz.
+
+## 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 @thebattlearena/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:
+
+```bash
+npx @thebattlearena/battle-arena-hooks@latest install \
+  --url https://api.battlearena.dev --api-key sk_xxx
+```
+
+Desde el clone, el equivalente para contribuidores:
+
+```bash
+HOOK_STREAM_URL=https://api.battlearena.dev \
+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.

package/check-connection.mjs

@@ -0,0 +1,64 @@
+// Hook UserPromptSubmit: latido recurrente de conexión. Lee el status local que deja emit.mjs
+// y, si la última transmisión falló o hay eventos en cola, le avisa al usuario (systemMessage)
+// y a Claude (additionalContext) que el stream está desconectado y reintentando. Cuando todo
+// está sano, no produce ruido. No bloquea (exit 0); la reconexión es automática.
+import { getIdentity } from './lib/identity.mjs';
+import { readStatus, writeStatus } from './lib/state.mjs';
+import { drainBuffer } from './lib/drain.mjs';
+import { reauthContext, reauthSystemMessage } from './lib/reauth.mjs';
+import { TARGET } from './lib/transport.mjs';
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', () => {});
+process.stdin.on('end', async () => {
+  let status = readStatus();
+
+  // Auth: la key no sirve → requiere acción del usuario; se muestra siempre (prioritario sobre
+  // el aviso de "desconectado", que sugiere que no hay nada que hacer).
+  if (status.authError) {
+    process.stdout.write(
+      JSON.stringify({
+        systemMessage: reauthSystemMessage(TARGET, status.authStatus),
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: reauthContext(TARGET, getIdentity().email),
+        },
+      }),
+    );
+    return;
+  }
+
+  // Drenado PROACTIVO: si hay cola, la reenviamos aquí mismo en vez de esperar al próximo evento de
+  // trabajo (así una sesión que quedó con cola tras un bache del colector se recupera al escribir el
+  // siguiente prompt). drainBuffer se autoacota (MAX_DRAIN) y corta si el colector no responde, así
+  // que cuesta poco cuando está caído; al volver, la cola se vacía en pocos prompts.
+  if ((status.pending || 0) > 0) {
+    const { remaining } = await drainBuffer();
+    status =
+      remaining === 0
+        ? {
+            connected: true,
+            target: TARGET,
+            lastOk: new Date().toISOString(),
+            pending: 0,
+          }
+        : { ...status, connected: false, target: TARGET, pending: remaining };
+    writeStatus(status);
+  }
+
+  const pending = status.pending || 0;
+
+  // Conexión sana y sin cola → nada que reportar.
+  if (status.connected && pending === 0) return;
+
+  const colaTxt = pending > 0 ? ` (${pending} eventos en cola)` : '';
+  const output = {
+    systemMessage: `⚠️ hook-stream desconectado de ${TARGET}${colaTxt} — reintentando automáticamente`,
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: `El hook-stream perdió la conexión con ${TARGET}${colaTxt}. Tu actividad se está bufferando localmente y se reenviará en cuanto el colector vuelva a responder; la reconexión es automática y no requiere acción manual.`,
+    },
+  };
+  process.stdout.write(JSON.stringify(output));
+});

package/cli.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// CLI del paquete @thebattlearena/battle-arena-hooks.
+// Instala los hooks + skill del Battle Arena en ~/.claude SIN clonar el repo.
+//
+//   npx @thebattlearena/battle-arena-hooks install \
+//     --url https://api.battlearena.dev --api-key sk_xxx
+//
+// (también lee HOOK_STREAM_URL / HOOK_STREAM_API_KEY del entorno)
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+import os from 'node:os';
+
+const PKG_DIR = dirname(fileURLToPath(import.meta.url));
+const HOME = os.homedir();
+const CLAUDE = join(HOME, '.claude');
+const BA_DIR = join(CLAUDE, 'battle-arena');
+const HOOKS_DEST = join(BA_DIR, 'hooks');
+const SKILLS_DEST = join(CLAUDE, 'skills');
+const SETTINGS = join(CLAUDE, 'settings.json');
+
+const HOOK_FILES = [
+  'emit.mjs',
+  'session-start.mjs',
+  'check-connection.mjs',
+  'objective-nudge.mjs',
+  'execution-coach-nudge.mjs',
+  'pr-review-worktree.mjs',
+  'objective.mjs',
+];
+
+function arg(name) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 ? process.argv[i + 1] : undefined;
+}
+
+function gitEmail() {
+  try {
+    return execFileSync('git', ['config', 'user.email'], {
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function install() {
+  const url =
+    arg('url') || process.env.HOOK_STREAM_URL || 'https://api.battlearena.dev';
+  const key = arg('api-key') || process.env.HOOK_STREAM_API_KEY || '';
+
+  if (!gitEmail()) {
+    console.log(
+      '⚠️  git config user.email vacío — configúralo: es tu identidad en el arena.',
+    );
+  }
+
+  // 1) Hooks → ~/.claude/battle-arena/hooks (ubicación estable)
+  mkdirSync(HOOKS_DEST, { recursive: true });
+  for (const f of HOOK_FILES) cpSync(join(PKG_DIR, f), join(HOOKS_DEST, f));
+  cpSync(join(PKG_DIR, 'lib'), join(HOOKS_DEST, 'lib'), { recursive: true });
+  console.log(`✅ hooks copiados a ${HOOKS_DEST}`);
+
+  // 2) Skills del paquete → ~/.claude/skills (cada subcarpeta de skill/*)
+  const skillsRoot = join(PKG_DIR, 'skill');
+  if (existsSync(skillsRoot)) {
+    mkdirSync(SKILLS_DEST, { recursive: true });
+    const skillDirs = readdirSync(skillsRoot, { withFileTypes: true }).filter(
+      (d) => d.isDirectory(),
+    );
+    for (const d of skillDirs) {
+      cpSync(join(skillsRoot, d.name), join(SKILLS_DEST, d.name), {
+        recursive: true,
+      });
+      console.log(`✅ skill ${d.name} instalada en ${SKILLS_DEST}`);
+    }
+  }
+
+  // 3) Config (url + api-key) → ~/.claude/battle-arena/config.json. Los hooks lo leen de ahí.
+  //    Evita hornear `VAR=val node ...` en el comando, sintaxis que NO existe en Windows
+  //    (cmd/PowerShell). Así el comando es solo `node "<ruta>"`, idéntico en los 3 SOs.
+  writeFileSync(
+    join(BA_DIR, 'config.json'),
+    JSON.stringify({ url, apiKey: key || undefined }, null, 2) + '\n',
+  );
+
+  // 4) Hooks en ~/.claude/settings.json (merge idempotente, sin pisar otros)
+  const cmd = (f) => `node "${join(HOOKS_DEST, f)}"`;
+  const map = {
+    SessionStart: ['session-start.mjs'],
+    UserPromptSubmit: [
+      'emit.mjs',
+      'check-connection.mjs',
+      'objective-nudge.mjs',
+      'execution-coach-nudge.mjs',
+    ],
+    PreToolUse: ['emit.mjs'],
+    PostToolUse: ['emit.mjs', 'pr-review-worktree.mjs'],
+    Notification: ['emit.mjs'],
+    Stop: ['emit.mjs'],
+    SubagentStop: ['emit.mjs'],
+    PreCompact: ['emit.mjs'],
+    SessionEnd: ['emit.mjs'],
+  };
+
+  mkdirSync(CLAUDE, { recursive: true });
+  const settings = existsSync(SETTINGS)
+    ? JSON.parse(readFileSync(SETTINGS, 'utf8'))
+    : {};
+  settings.hooks = settings.hooks || {};
+  for (const [event, scripts] of Object.entries(map)) {
+    const groups = (settings.hooks[event] = settings.hooks[event] || []);
+    // quita entradas previas del arena (idempotente) y reescribe en su grupo
+    for (const g of groups)
+      g.hooks = (g.hooks || []).filter(
+        (h) =>
+          !/battle-arena[/\\]hooks|claude-hooks[/\\]/.test(h.command || ''),
+      );
+    settings.hooks[event] = groups.filter((g) => (g.hooks || []).length > 0);
+    settings.hooks[event].push({
+      hooks: scripts.map((f) => ({ type: 'command', command: cmd(f) })),
+    });
+  }
+  writeFileSync(SETTINGS, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`✅ hooks registrados en ${SETTINGS}`);
+  console.log(`   colector: ${url}${key ? '' : '  (sin api-key)'}`);
+  console.log(
+    '\nListo. Abre Claude Code en cualquier repo y verás el handshake del arena.',
+  );
+}
+
+const command = process.argv[2];
+if (command === 'install') {
+  install();
+} else {
+  console.log(
+    'Uso: npx @thebattlearena/battle-arena-hooks install [--url <colector>] [--api-key <key>]',
+  );
+  process.exit(command ? 1 : 0);
+}

package/emit.mjs

@@ -0,0 +1,100 @@
+// Emisor de hooks de Claude Code → colector (local primero, remoto vía HOOK_STREAM_URL).
+// Lo invoca cada hook. Enriquece el payload con la identidad del dev y lo envía a /ingest.
+// Modelo directo + auto-retry: si el envío falla, el evento se bufferea localmente y, al
+// primer envío exitoso posterior, se drena el buffer. Actualiza ~/.claude/hook-stream/status.json
+// para que los hooks de conexión sepan si avisar a Claude. SIEMPRE exit 0; nunca bloquea.
+import { randomUUID } from 'node:crypto';
+
+import { bufferEvent, readBuffer, writeStatus } from './lib/state.mjs';
+import { drainBuffer, isUnrecoverable } from './lib/drain.mjs';
+import { getIdentity } from './lib/identity.mjs';
+import { isAuthError } from './lib/reauth.mjs';
+import { numstatTotals } from './lib/git-diff.mjs';
+import { sanitize } from './lib/sanitize.mjs';
+import { TARGET, postJson } from './lib/transport.mjs';
+
+// "Código nuevo" (LOC): lo porta el evento de `git commit` (NO el push). El push corre en
+// PostToolUse después de actualizar el remote-tracking → el rango quedaba vacío (0 LOC). El commit
+// recién creado es `HEAD~1..HEAD`: timing fiable. El colector deduplica por eventId.
+const GIT_COMMIT_PATTERN = /\bgit\s+commit\b/;
+const isGitCommit = (payload) =>
+  payload.hook_event_name === 'PostToolUse' &&
+  payload.tool_name === 'Bash' &&
+  GIT_COMMIT_PATTERN.test(String(payload.tool_input?.command || ''));
+
+// Enriquece SOLO los eventos de commit con los totales del diff; el resto pasa intacto.
+function withCodeMetrics(payload) {
+  if (!isGitCommit(payload)) return {};
+  const { insertions, deletions, filesChanged } = numstatTotals();
+  if (insertions === 0 && deletions === 0) return {};
+  return { codeMetrics: { insertions, deletions, filesChanged } };
+}
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => (raw += c));
+process.stdin.on('end', () => {
+  let payload;
+  try {
+    payload = JSON.parse(raw || '{}');
+  } catch {
+    return;
+  }
+
+  // Solo reportamos repos de código con remoto (origin). Sin remoto, no nos interesa: no se emite.
+  const identity = getIdentity();
+  if (!identity.repoUrl) return;
+
+  // Censura secretos y omite paths de la máquina ANTES de que el evento salga/se persista.
+  // `eventId` único: viaja en el buffer, así un reenvío conserva el mismo id y el colector lo
+  // deduplica (entrega "al menos una vez" sin duplicar en el feed).
+  const event = sanitize({
+    ...payload,
+    ...withCodeMetrics(payload),
+    eventId: randomUUID(),
+    identity,
+    sentAt: new Date().toISOString(),
+  });
+
+  send(event).catch(() => {});
+});
+
+async function send(event) {
+  const line = JSON.stringify(event);
+  const { ok, status } = await postJson('/ingest', event);
+
+  if (!ok && isUnrecoverable(status)) return; // evento inservible: descartar, no bufferear
+
+  // Auth: la key no sirve. No buffereamos (sería en vano) y marcamos authError para que
+  // session-start / check-connection le pidan al usuario una key nueva.
+  if (!ok && isAuthError(status)) {
+    writeStatus({
+      connected: false,
+      authError: true,
+      authStatus: status,
+      target: TARGET,
+      lastFail: event.sentAt,
+      pending: readBuffer().length,
+    });
+    return;
+  }
+
+  if (!ok) {
+    bufferEvent(line);
+    writeStatus({
+      connected: false,
+      target: TARGET,
+      lastFail: event.sentAt,
+      pending: readBuffer().length,
+    });
+    return;
+  }
+
+  await drainBuffer();
+  writeStatus({
+    connected: true,
+    target: TARGET,
+    lastOk: event.sentAt,
+    pending: readBuffer().length,
+  });
+}

package/execution-coach-nudge.mjs

@@ -0,0 +1,247 @@
+// Hook UserPromptSubmit: inyecta additionalContext para que Claude invoque el skill
+// `execution-coach` (interceptor mayéutico) cuando la ejecución va subóptima. Dos partes:
+//
+//   1. AUTOEVALUACIÓN SEMÁNTICA (cada turno no trivial): le recuerda al modelo —que ya está
+//      procesando el turno— que juzgue si el pedido del usuario está vago / subespecificado /
+//      confuso. El juicio semántico lo hace el LLM, no regex frágiles aquí.
+//   2. SEÑALES DETERMINISTAS de la sesión (con throttle): contadores baratos sobre el transcript
+//      (racha sin guía, dar vueltas sobre un archivo, PRs/pushes sin converger, acoplamiento).
+//
+// Zero-dependency, best-effort, exit 0 SIEMPRE — si algo falla, no estorba el turno.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const STATE_DIR = path.join(
+  os.homedir(),
+  '.claude',
+  'battle-arena',
+  'execution-coach',
+);
+const COOLDOWN_TURNS = 5; // no repetir las señales de sesión más de una vez cada N turnos
+const WINDOW = 14; // ventana reciente (en turnos del asistente) para "vueltas"
+
+const GUIDANCE_RE =
+  /(^|\s)\/(plan|goal|verify|code-review|review|scope|aterrizar)\b/i;
+const GREETING_RE =
+  /^(hola|hey|hi|buenas|gracias|ok|oka|okay|s[ií]|dale|listo|va|perfecto)\b/i;
+// Prompts que son solo emojis/símbolos (👍, 👌🙏): triviales. `\b` no matchea emojis, así que
+// los detectamos aparte en vez de meterlos en GREETING_RE.
+const EMOJI_ONLY_RE = /^[\s\p{Extended_Pictographic}\p{Emoji_Presentation}]+$/u;
+const INFRA_IMPORT_RE =
+  /(from\s+['"]|require\(\s*['"])(typeorm|@nestjs|sequelize|mongoose|prisma|@prisma|knex|axios|pg|mysql2|redis|ioredis)/;
+const DOMAIN_PATH_RE = /(^|\/)(domain|entities|value-objects|core)\//;
+
+const SELF_ASSESS =
+  'Battle Arena — antes de responder, juzga si el pedido del usuario está claramente vago, ' +
+  'subespecificado o confuso: sin objetivo claro, sin criterio de aceptación, o sin saber para ' +
+  'quién/para qué es (p. ej. "quiero un código para desplegar el proyecto" sin decir qué app, ' +
+  'entorno ni cómo se ve "listo"). Si CLARAMENTE lo está, invoca el skill `execution-coach` para ' +
+  'interceptar con preguntas mayéuticas antes de codear. Sé conservador: ante la duda, o si el ' +
+  'pedido ya es concreto, sigue normal sin interrumpir.';
+
+function wordCount(s) {
+  return (s || '').trim().split(/\s+/).filter(Boolean).length;
+}
+
+// --- lectura defensiva del transcript .jsonl ---------------------------------
+function parseTranscript(file) {
+  const userTurns = []; // textos de turnos REALES del usuario (no tool_result)
+  const assistantTurns = []; // [{ tools: [{name, input}] }] por mensaje del asistente
+  let raw = '';
+  try {
+    raw = readFileSync(file, 'utf8');
+  } catch {
+    return { userTurns, assistantTurns };
+  }
+  // Acota el costo por turno en sesiones largas: solo las últimas N líneas. Las señales miran la
+  // actividad reciente; un /plan de hace miles de líneas no cambia que una racha actual no tenga guía.
+  const allLines = raw.split('\n');
+  const lines = allLines.length > 5000 ? allLines.slice(-5000) : allLines;
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    let ev;
+    try {
+      ev = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const msg = ev.message || ev;
+    const role = msg.role || ev.type;
+    const content = msg.content;
+    if (role === 'user') {
+      // string = prompt real; array con bloque text = prompt real; solo tool_result = NO cuenta
+      if (typeof content === 'string') {
+        userTurns.push(content);
+        continue;
+      }
+      if (Array.isArray(content)) {
+        const text = content
+          .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+          .map((b) => b.text)
+          .join(' ');
+        if (text.trim()) userTurns.push(text);
+      }
+      continue;
+    }
+    if (role === 'assistant' && Array.isArray(content)) {
+      const tools = content
+        .filter((b) => b && b.type === 'tool_use')
+        .map((b) => ({ name: b.name, input: b.input || {} }));
+      if (tools.length) assistantTurns.push({ tools });
+    }
+  }
+  return { userTurns, assistantTurns };
+}
+
+// --- señales DETERMINISTAS (contadores; nada de juicio semántico) -------------
+function detectSignals({ userTurns, assistantTurns }) {
+  const signals = [];
+  const flatTools = assistantTurns.flatMap((t) => t.tools);
+  const toolName = (n) => flatTools.filter((t) => t.name === n).length;
+  const workCount =
+    toolName('Edit') +
+    toolName('Write') +
+    toolName('MultiEdit') +
+    toolName('Bash');
+
+  // Sin intención de guiar (ni /plan /goal /verify ni ExitPlanMode) pese a trabajo real.
+  const guided =
+    userTurns.some((t) => GUIDANCE_RE.test(t)) ||
+    flatTools.some((t) => ['ExitPlanMode', 'EnterPlanMode'].includes(t.name));
+  if (userTurns.length >= 8 && workCount >= 6 && !guided) {
+    signals.push(
+      'sin guía de ejecución (muchos turnos con trabajo y ningún /plan, /goal o /verify)',
+    );
+  }
+
+  // Dando vueltas — mismo archivo editado en >=3 turnos del asistente recientes.
+  const recent = assistantTurns.slice(-WINDOW);
+  const fileTurns = new Map();
+  recent.forEach((turn, i) => {
+    const files = new Set(
+      turn.tools
+        .filter((t) => ['Edit', 'Write', 'MultiEdit'].includes(t.name))
+        .map((t) => t.input && t.input.file_path)
+        .filter(Boolean),
+    );
+    for (const f of files) {
+      if (!fileTurns.has(f)) fileTurns.set(f, new Set());
+      fileTurns.get(f).add(i);
+    }
+  });
+  const looping = [...fileTurns.entries()].find(([, turns]) => turns.size >= 3);
+  if (looping) {
+    signals.push(
+      `dando vueltas sobre el mismo archivo (${path.basename(looping[0])})`,
+    );
+  }
+
+  // No converge — PRs/pushes repetidos.
+  const bashCmds = flatTools
+    .filter((t) => t.name === 'Bash')
+    .map((t) => (t.input && t.input.command) || '');
+  const prCreates = bashCmds.filter((c) => /gh\s+pr\s+create/.test(c)).length;
+  const pushes = bashCmds.filter((c) => /git\s+push/.test(c)).length;
+  if (prCreates >= 2 || pushes >= 3) {
+    signals.push('múltiples PRs/pushes sin converger en una solución');
+  }
+
+  // Acoplamiento — edición a dominio/entities/core que importa infra/ORM/framework.
+  const coupling = flatTools.some((t) => {
+    if (!['Edit', 'Write', 'MultiEdit'].includes(t.name)) return false;
+    const fp = t.input && t.input.file_path;
+    if (!fp || !DOMAIN_PATH_RE.test(fp)) return false;
+    // Write usa `content`, Edit usa `new_string`, MultiEdit lleva el texto en `edits[].new_string`.
+    const multi = (t.input.edits || []).map((e) => e && e.new_string).join('');
+    const body = `${t.input.content || ''}${t.input.new_string || ''}${multi}`;
+    return INFRA_IMPORT_RE.test(body);
+  });
+  if (coupling) {
+    signals.push(
+      'posible acoplamiento: dominio importando infraestructura (ORM/framework)',
+    );
+  }
+
+  return signals;
+}
+
+// --- throttle por sesión (solo para las señales de sesión) --------------------
+function readState(session) {
+  try {
+    return JSON.parse(
+      readFileSync(path.join(STATE_DIR, `${session}.json`), 'utf8'),
+    );
+  } catch {
+    return { lastNudgeTurn: -Infinity };
+  }
+}
+function writeState(session, state) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(
+      path.join(STATE_DIR, `${session}.json`),
+      JSON.stringify(state),
+    );
+  } catch {}
+}
+
+// --- main ---------------------------------------------------------------------
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (c) => (raw += c));
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw || '{}');
+    const prompt = String(input.prompt || '');
+    // Sanitiza el session_id antes de usarlo como nombre de archivo del state (evita path
+    // traversal con `/` o `..`) y acótalo.
+    const session =
+      String(input.session_id || 'default')
+        .replace(/[^a-zA-Z0-9_-]/g, '_')
+        .slice(0, 128) || 'default';
+
+    // Turnos triviales (saludo/confirmación corta/solo emojis): nunca interrumpir.
+    const trimmed = prompt.trim();
+    if (
+      wordCount(prompt) < 3 ||
+      GREETING_RE.test(trimmed) ||
+      EMOJI_ONLY_RE.test(trimmed)
+    )
+      return;
+
+    const { userTurns, assistantTurns } = parseTranscript(
+      input.transcript_path,
+    );
+    const turnNo = userTurns.length;
+
+    // Las señales de sesión se incluyen con throttle (no repetir la misma queja cada turno).
+    const state = readState(session);
+    let signals = [];
+    if (turnNo - (state.lastNudgeTurn ?? -Infinity) >= COOLDOWN_TURNS) {
+      signals = detectSignals({ userTurns, assistantTurns });
+      if (signals.length)
+        writeState(session, { lastNudgeTurn: turnNo, signals });
+    }
+
+    // La autoevaluación semántica va SIEMPRE (es solo un recordatorio barato; el modelo juzga).
+    let context = SELF_ASSESS;
+    if (signals.length) {
+      context +=
+        '\n\nAdemás, señales deterministas en esta sesión (revísalas con `execution-coach` si ' +
+        'siguen vigentes):\n' +
+        signals.map((s) => `- ${s}`).join('\n');
+    }
+
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: context,
+        },
+      }),
+    );
+  } catch {
+    // best-effort: nunca estorbar el turno
+  }
+});