Cómo funcionan los hooks

El supervisor de hooks es la parte de Pathrule que hace que las sesiones de IA se sientan como si el asistente ya conociera las convenciones de tu equipo. Se ejecuta localmente, lee de una caché, entrega las memorias y reglas relevantes y ofrece skills por nombre antes de que el asistente realice su primera acción. Las instrucciones de una skill llegan cuando la invocas.

Esta página es un modelo del funcionamiento pensado para quien usa el producto. No es un análisis a fondo de los detalles internos del runtime.

Qué es un hook

Un hook es un pequeño script que tu cliente de IA invoca en momentos bien definidos de un turno. Pathrule usa los eventos de entrega y de aplicación que cada cliente expone realmente.

• SessionStart le indica al asistente en qué espacio de trabajo está y le entrega el protocolo de Pathrule y el contexto de tu equipo, una vez por sesión.
• UserPromptSubmit acota el turno siguiente en los clientes cuyo evento de prompt acepta contexto.
• PreToolUse aporta contexto o una decisión de regla estricta antes de una acción, cuando el cliente lo acepta.
• PostToolUse registra los resultados y compensa con contexto vinculado a la ruta en los clientes cuyo evento previo a la herramienta acepta decisiones pero no contexto.
• Los eventos de detención y de fin de sesión cierran el turno. En Claude Code y Codex, una comprobación obligatoria aprobada por una persona puede mantener el turno abierto en este punto hasta que su comando se haya superado.

pathrule setup y pathrule sync, o la extensión de VS Code, registran estos hooks para Claude Code, Codex, Cursor y GitHub Copilot. Windsurf no tiene hooks de Pathrule, así que su archivo de reglas generado se encarga del arranque de la sesión y el servidor MCP local aporta contexto más profundo cuando hace falta.

Perfiles de entrega por cliente

Una regla estricta es aquella que lleva un patrón de bloqueo aprobado por una persona. Consulta Reglas como barreras de protección para ver qué bloquea y qué solo informa.

Qué hace el hook

El supervisor de hooks hace cuatro cosas, en este orden.

1. Resuelve la ruta. Asocia el directorio de trabajo con un nodo del espacio de trabajo.
2. Lee la caché. La caché local contiene un índice precalculado de memorias, reglas y skills para esa ruta.
3. Ajusta la porción. Elige una profundidad acorde a la intención. Un retoque de UI recibe una carga mínima. Una corrección de bug o una refactorización recibe una carga enfocada. Los prompts de exploración desbloquean una más profunda.
4. Devuelve la carga. El texto regresa al cliente como contexto de sistema para la acción siguiente.

En modo local, todo el flujo se ejecuta en tu máquina. En un espacio de trabajo de Cloud, el hook de prompt también envía el inicio de tu prompt (aproximadamente los primeros 1.000 caracteres) a Pathrule Cloud para que el conocimiento se pueda priorizar por significado. Si esa llamada es lenta o falla, el hook recurre a buscar coincidencias en el índice local, así que un problema de red no deja el turno sin contexto.

Qué ves

La superficie de contexto del asistente (la que expone tu editor) incorpora una sección de Pathrule. Incluye:

• La ruta que resolvió el hook, junto con las rutas donde es más probable que esté el trabajo, un recorrido que se le pide al asistente abrir antes de buscar. Pathrule registra si lo hizo.
• Las reglas que coinciden, con su prioridad.
• Las memorias más relevantes para tu prompt, entregadas con su cuerpo completo para que el asistente pueda actuar directamente sobre ellas. Las coincidencias menos seguras igual llegan como títulos con ids que puedes leer completos si quieres.
• Las skills que encajan en este ámbito, por nombre, listas para invocar con ::skill-name.

Si el hook no tiene nada nuevo y relevante para la ruta actual, no agrega nada, así que un turno sin novedades no consume contexto.

Dos canales de entrega

El conocimiento llega al asistente a través de dos canales de hook con funciones distintas.

• El canal por prompt se ejecuta una vez cuando envías un prompt, en los clientes con hook de envío de prompt (Claude Code y Codex). Es donde está la profundidad: las reglas que encajan con el prompt, las memorias con mejor coincidencia con su cuerpo completo para que el asistente actúe directamente sobre ellas, y las skills que parecen relevantes, ofrecidas por nombre. Una skill es un procedimiento, así que nunca se envía como instrucción; su cuerpo completo llega cuando la invocas con ::skill-name.
• El canal por llamada a herramienta se ejecuta antes o después de cada acción sobre archivos o en la shell, muchas veces por turno. Se mantiene liviano a propósito: los nombres y resúmenes de una línea de las reglas y memorias que aplican a la ruta que se está tocando, para que el asistente sepa qué existe ahí y pueda leer un cuerpo con una sola llamada si lo necesita.

En Claude Code y Codex, tanto el canal de prompt como el canal previo a la herramienta llegan al asistente. Cursor y GitHub Copilot no aceptan contexto en su evento de prompt, así que el hook de inicio de sesión lleva el arranque y el hook posterior a la herramienta lleva los nombres vinculados a la ruta.

Ningún canal se repite. Un cuerpo que ya se entregó en la sesión no vuelve a aparecer, y uno editado vuelve a llegar la próxima vez que sea relevante.

Qué queda en disco

Un cliente con el hook de Pathrule instalado recibe el protocolo y el contexto del equipo desde el hook de inicio de sesión en lugar de desde su archivo de instrucciones. En Claude Code, el contexto de inicio de sesión se integra en el prompt del sistema, así que sobrevive a la compactación de la conversación. El archivo de instrucciones (CLAUDE.md, AGENTS.md, la regla de Cursor o las instrucciones de Copilot) conserva solo una nota breve de Pathrule, y Pathrule elimina las copias del protocolo y los archivos de conocimiento por directorio que escribió en versiones anteriores. Tu propio contenido en esos archivos se mantiene.

Hay dos casos en los que se conservan los archivos compilados:

• Un cliente sin hook de Pathrule, como Windsurf, o un cliente cuyo hook no está instalado, conserva el protocolo completo y los archivos de conocimiento por ruta, porque nada más los entregaría.
• Si una versión anterior de Pathrule movió tu propio archivo de instrucciones a una copia de seguridad que todavía no se ha restaurado, Pathrule conserva el archivo completo hasta que se resuelva esa copia, para que nunca veas una nota breve mientras tus propias instrucciones están en otro lugar.

Para conservar los archivos compilados incluso con el hook instalado, define PATHRULE_SIGNATURE_MODE=off en el entorno del runtime de Pathrule.

Cuando el hook no alcanza

Los hooks están diseñados para el caso común. El asistente siempre puede recurrir a las herramientas MCP cuando necesita más.

• Para prompts de exploración ("enumera todo lo que sabemos sobre facturación"), el asistente llama directamente a pathrule_get_context.
• Para obtener el cuerpo completo de una memoria, el asistente llama a pathrule_read_memory con el id que aparece en el hook.
• Para escrituras (el usuario pide guardar una convención o una regla), el asistente usa la herramienta de escritura correspondiente.

El hook es la vía rápida. MCP es la vía profunda. Ambos comparten la misma fuente de verdad.

El alcance por ruta lo mantiene pequeño

El hook devuelve una porción ajustada según el directorio de trabajo.

• Un cambio en apps/web/dashboard no trae reglas sobre migraciones de base de datos.
• Un cambio en services/billing/webhooks trae las reglas de facturación y la skill de reenvío de webhooks, no las convenciones del sitio de marketing.
• Un prompt de exploración en la raíz del repositorio trae una visión general del espacio de trabajo, no todos los cuerpos.

El alcance por ruta es lo que mantiene pequeño el contexto entregado, en comparación con un único archivo de instrucciones global que cada sesión carga completo.

Cuando no aparece nada

Si abres una sesión y la sección de Pathrule está vacía, ejecuta el diagnóstico.

pathrule doctor

Es de solo lectura y comprueba:

• Tu inicio de sesión, organización y espacio de trabajo.
• Si la carpeta actual está asociada a un espacio de trabajo.
• Si la entrada MCP de Pathrule está instalada en cada cliente de IA.
• Qué archivos gestionados por Pathrule hay en la carpeta, y qué superficie y versión de Pathrule los escribió.

La salida termina con el siguiente comando que debes ejecutar cuando algo requiere atención. Agrega --json para obtener el informe completo, que también incluye la versión de Node y señala cualquier entrada MCP que apunte a un runtime que ya no existe.

Para volver a dejar en su lugar las piezas locales, ejecuta:

pathrule repair

La reparación reescribe las entradas MCP obsoletas, reinstala el script del hook y el registro del hook en cada cliente, vuelve a sincronizar los archivos complementarios y la caché local que lee el hook, y ejecuta el diagnóstico otra vez.

Si en algún momento quieres desactivar todos los hooks de Pathrule a la vez, crea ~/.pathrule/kill-hooks. La siguiente llamada al hook pasa sin hacer nada; elimina el archivo para volver a activar los hooks.

Qué leer a continuación

• Descripción general de MCP para conocer las herramientas que respaldan la vía profunda.
• Conceptos clave para conocer el modelo de datos del que lee el hook.
• Instalación de la CLI para instalar el runtime que aloja el supervisor de hooks.