Hooks

Los hooks son comandos definidos por ti que Theus ejecuta automáticamente en puntos concretos de su ciclo de vida: antes o después de usar una herramienta, al enviar un prompt, al iniciar o cerrar una sesión, y mucho más.

Qué son

Un hook asocia un evento (por ejemplo, "justo antes de ejecutar una herramienta") con una acción (ejecutar un comando de shell, evaluar un prompt, llamar a una URL o lanzar un subagente verificador). Cuando el evento ocurre, Theus lanza esas acciones, les entrega información del evento por stdin en formato JSON, y actúa según lo que devuelven.

Los usos típicos son: formatear código automáticamente después de cada escritura, bloquear comandos peligrosos antes de que se ejecuten, inyectar contexto adicional al enviar un prompt, o disparar notificaciones y auditorías.

El comando /hooks

Dentro de Theus, el comando slash /hooks abre un menú interactivo para revisar y gestionar la configuración de hooks por evento de herramienta, mostrando las herramientas disponibles en tu contexto actual. Es la vía recomendada para inspeccionar qué hooks están activos.

Dónde se configuran

Los hooks viven bajo la clave hooks de tu settings.json. Theus lee la configuración de varias fuentes y las combina por precedencia:

Formato de configuración

La clave hooks es un objeto donde cada clave es el nombre del evento y cada valor es una lista de matchers. Cada matcher tiene un patrón opcional (matcher) y una lista de hooks a ejecutar:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write \"$THEUS_PROJECT_DIR\""
          }
        ]
      }
    ]
  }
}

El matcher es un patrón de texto que se compara con el valor asociado al evento (para eventos de herramienta, el nombre de la herramienta, p. ej. Write o Bash). Si se omite, el matcher aplica a todos los casos del evento.

Tipos de hook

Cada entrada dentro de hooks se distingue por su campo type:

Campos comunes

• if: filtra cuándo corre el hook usando sintaxis de reglas de permiso (p. ej. "Bash(git *)"). El hook solo se lanza si la llamada de herramienta coincide con el patrón; así evitas lanzar hooks para comandos que no aplican.
• timeout: tiempo máximo en segundos para esa acción concreta.
• statusMessage: mensaje personalizado a mostrar en el spinner mientras el hook corre.
• once: si es true, el hook corre una sola vez y se elimina tras ejecutarse.
• async (solo command): si es true, el hook corre en segundo plano sin bloquear. Con asyncRewake además despierta al modelo si termina con código de salida 2 (error bloqueante).

Eventos disponibles

Estos son los eventos que puedes usar como clave dentro de hooks:

Datos que recibe el hook

Cada hook recibe por stdin un JSON con la información del evento. Todos los eventos incluyen campos base:

• session_id: identificador de la sesión.
• transcript_path: ruta al transcript de la conversación.
• cwd: directorio de trabajo actual.
• hook_event_name: nombre del evento (p. ej. PreToolUse).
• permission_mode, agent_id, agent_type: presentes según el contexto (por ejemplo, cuando el hook se dispara dentro de un subagente).

Los eventos de herramienta añaden además tool_name, tool_input y tool_use_id; PostToolUse incorpora también tool_response.

Variables de entorno

Theus expone variables útiles al proceso del hook:

• THEUS_PROJECT_DIR: raíz estable del proyecto (no la ruta del worktree), para que las rutas relativas resuelvan siempre contra el repositorio real.
• THEUS_ENV_FILE: ruta a un archivo .sh donde el hook puede escribir variables de entorno que se aplicarán a la sesión.

Cómo responde un hook

Un hook puede simplemente terminar (su código de salida y su stdout se registran), o devolver por stdout un JSON para controlar el flujo. Campos habituales:

• continue: si es false, Theus no continúa; usa stopReason para el mensaje.
• suppressOutput: oculta el stdout del transcript.
• decision: approve o block, con reason como explicación.
• systemMessage: mensaje de aviso que se muestra al usuario.
• hookSpecificOutput: salida específica del evento. Por ejemplo, en PreToolUse permite permissionDecision (allow/deny/ask) y updatedInput; en UserPromptSubmit y SessionStart, additionalContext.

Un hook también puede responder { "async": true } (con asyncTimeout opcional) para ejecutarse en segundo plano.

Ejemplos

Formatear tras cada escritura

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "prettier --write \"$THEUS_PROJECT_DIR\"" }
        ]
      }
    ]
  }
}

Bloquear un comando peligroso antes de ejecutarlo

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm -rf *)",
            "command": "echo '{\"decision\":\"block\",\"reason\":\"Comando destructivo bloqueado por política.\"}'"
          }
        ]
      }
    ]
  }
}

Inyectar contexto al enviar un prompt

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "git-context.sh" }
        ]
      }
    ]
  }
}

Si el comando imprime { "hookSpecificOutput": { "hookEventName": "UserPromptSubmit", "additionalContext": "..." } }, ese texto se añade al contexto del turno.

Verificador con subagente

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verifica que las pruebas unitarias se ejecutaron y pasaron."
          }
        ]
      }
    ]
  }
}

Controles de seguridad

Además de requerir un espacio de trabajo de confianza, la configuración admite ajustes de seguridad relevantes:

• Deshabilitar por completo la ejecución de hooks (y de la status line).
• Ejecutar únicamente los hooks definidos en la configuración gestionada por el administrador, ignorando los de usuario, proyecto y local.
• Para hooks de tipo http, restringir a qué URLs pueden apuntar mediante una allowlist con comodines (p. ej. https://hooks.example.com/*) y qué variables de entorno pueden interpolarse en las cabeceras.