# 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.

Crear software · Actualizado: 2026-11-02 · versión 2.0.145 · https://nobreiniers.com/ayuda/hooks/

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](https://nobreiniers.com/ayuda/import-from-other-agents/).

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

```json
{
  "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:

| Evento | Cuándo corre |
|---|---|
| `SessionStart` | Al empezar un chat. |
| `Setup` | Justo 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. |
| `UserPromptSubmit` | Cuando envías un mensaje. |
| `PreToolUse` | Antes de que el agente use una herramienta. Puede bloquearla. |
| `PostToolUse` | Después de que la usa. |
| `Stop` | Cuando el agente termina su turno. |
| `PreCompact` | Antes 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:

```json
{ "type": "function", "file": "hooks/guard.js" }
```

2. Escribe la función. Recibe el evento y devuelve su decisión:

```js
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:

| Campo | Para qué sirve |
|---|---|
| `decision` | `allow`, `deny` o `block`. |
| `reason` | El porqué, que lee el agente. |
| `updatedInput` | La entrada de la herramienta, corregida. |
| `additionalContext` | Texto que se añade a lo que sabe el agente. |

Si no devuelve nada, el trabajo sigue.

> **Nota:** En nuestras pruebas, la misma decisión antes de una herramienta tardó 0,24 ms como gancho de función y 29 ms como gancho de comando en Python (la mediana de cada uno).

## 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

| Mensaje | Qué 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ó. |
