Descarga gratis

Ganchos (hooks)

Haz que un comando o una función tuya corra en cada momento del agente: antes de una herramienta, al enviar un mensaje o al terminar.

Actualizado el · versión 2.0.145 · Markdown

Un gancho es algo tuyo que corre solo en un momento del trabajo del agente: antes de que use una herramienta, cuando envías un mensaje, cuando termina un turno. Puede dejar pasar, bloquear, pedirte permiso o añadir contexto.

De dónde vienen los ganchos

  • De un proyecto: el archivo .osiris/hooks.json en la carpeta del proyecto.
  • De un plugin que tengas activo.
  • De otro agente: los traes desde «Ajustes» › «Importar», y llegan apagados. Mira Importar de otros agentes.

La primera vez que un proyecto trae ganchos, la app te pregunta antes de ejecutar nada: la tarjeta dice que el proyecto, por su nombre, quiere ejecutar sus propios pasos automáticos en tu Mac mientras trabajas en él, y lista esos comandos. Si después cambian, vuelve a preguntar y no corren hasta que apruebes el cambio. La misma tarjeta muestra lo que los archivos de configuración del proyecto (.claude/settings.json y .claude/settings.local.json, en la carpeta y en las de encima hasta el repositorio) dejan ejecutar o abrir sin preguntar: esas reglas se aplican solo con tu sí para esa carpeta, y una regla añadida después espera tu aprobación. Lo que esos archivos rechazan o preguntan vale siempre.

Un gancho de comando

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "shell",
        "hooks": [{ "type": "command", "command": "python3 hooks/guard.py" }]
      }
    ]
  }
}

El comando recibe el evento como JSON por la entrada estándar. Si sale con el código 2, bloquea la acción y su mensaje le llega al agente.

Momentos más usados:

EventoCuándo corre
SessionStartAl empezar un chat.
SetupJusto después de que la app crea una copia de trabajo nueva (un worktree de git) para un chat o un ayudante: úsalo para instalar lo que la copia necesita. Recibe la carpeta de la copia y la carpeta de la que se hizo. Si falla, la copia se crea igual y te avisa.
UserPromptSubmitCuando envías un mensaje.
PreToolUseAntes de que el agente use una herramienta. Puede bloquearla.
PostToolUseDespués de que la usa.
StopCuando el agente termina su turno.
PreCompactAntes de compactar la conversación.

Un gancho de función

Un gancho de función es JavaScript que corre dentro de la app, sin abrir un proceso. Toma la misma decisión que un gancho de comando en una fracción del tiempo.

  1. En tu archivo de ganchos, usa el tipo function y nombra el archivo:
{ "type": "function", "file": "hooks/guard.js" }
  1. Escribe la función. Recibe el evento y devuelve su decisión:
export default function (input) {
  const command = (input.tool_input || {}).command || "";
  if (command.startsWith("rm ")) {
    return { decision: "deny", reason: "En este proyecto no se borra desde un comando." };
  }
}

Lo que puede devolver:

CampoPara qué sirve
decisionallow, deny o block.
reasonEl porqué, que lee el agente.
updatedInputLa entrada de la herramienta, corregida.
additionalContextTexto que se añade a lo que sabe el agente.

Si no devuelve nada, el trabajo sigue.

Lo que un gancho de función no puede hacer

  • No ve tus archivos, la red ni otros programas: corre aislado, solo con el lenguaje.
  • Puede leer texto dentro del proyecto con ctx.readFile. Solo llega a la red si el archivo de ganchos dice "network": true.
  • Tiene 50 ms de procesador por llamada (lo ajustas con timeout, de 5 ms a 5 s). Si se pasa, se detiene y no decide nada.
  • Un error suyo nunca rompe el turno: ves una línea con el error y el trabajo sigue.

Cuando un gancho frena algo

MensajeQué pasó
«Un gancho tuyo no dejó pasar este mensaje: …»Un gancho de UserPromptSubmit lo bloqueó.
«Un gancho tuyo detuvo este turno: …»Un gancho pidió parar.
«Un gancho tuyo no dejó compactar el contexto: …»Un gancho de PreCompact lo bloqueó.