Guía / artifact / HOOK

Artifact HOOK: automatiza en un evento

Usa un artifact HOOK para un script que un provider soportado ejecuta cuando ocurre un evento mapeado de sesión, prompt, tool o agente.

Las props del hook

Un hook tiene tres propiedades requeridas en content. trigger es el nombre neutral del evento, hook_category describe la familia esperada por el contrato de distribución y entrypoint apunta al archivo ejecutable del bundle.

trigger Usa valores mapeados como session_start, prompt_submit, pre_action, post_action, permission_request, subagent_start, subagent_stop, context_pre_compact o agent_stop. Los mapas cambian por provider.
hook_category Declara la categoría requerida por el contrato del artifact. Mantenla estable al actualizar para que los consumidores entiendan su comportamiento.
entrypoint Path ejecutable relativo como hooks/on-prompt.sh. Debe estar en files y al aplicarlo se marca chmod 0755.

Hook de ejemplo

Este hook recibe su evento mediante el adapter del provider. El script se copia a un directorio administrado por HubBound y se registra con metadata de ownership.

{
  "trigger": "prompt_submit",
  "hook_category": "command",
  "entrypoint": "hooks/on-prompt.sh"
}

Seguridad y portabilidad

Un hook es código ejecutable. Revísalo como código, mantenlo pequeño y haz explícito su comportamiento. Triggers desconocidos se saltan suavemente en providers sin un mapping nativo confiable; no se traducen silenciosamente a otro evento.

  • Nunca pongas secretos en script o manifest; léelos del entorno que provea usuario o provider.
  • Evita comandos destructivos por defecto y falla cerrado cuando falte input requerido.
  • Usa shell portable o documenta el runtime cuando el hook necesite un intérprete específico.
  • Incluye cada helper importado en files; el snapshot no sigue paths arbitrarios de runtime.

Qué hace install

Los providers soportados copian todos los archivos a un directorio administrado de hooks, marcan ownership, hacen ejecutable el entrypoint y registran el evento mapeado. Uninstall retira solo el registro y archivos que pertenecen a HubBound.

Guía de deploy