# Hooks {#hooks} > Ejecuta tus propias comprobaciones antes o después de las acciones del agente. ## Distingue de dónde procede cada hook {#understand-hook-ownership} Un hook ejecuta una acción al producirse un evento, por ejemplo antes de llamar a una herramienta o al terminar una ejecución. Tus hooks se guardan en `settings.json`, global o del espacio de trabajo. Los hooks de un plugin se activan y eliminan junto con él. Seleccionar el plugin incluye todos sus hooks válidos. Desde `/extensions`, pulsa `m`, abre los detalles del plugin y revisa el número de hooks y sus comandos antes de instalarlo o actualizarlo. No hay una pantalla de aprobación por hook. Si cambia el contenido del plugin o del espacio, Clarvis mantiene la nueva selección fuera de las ejecuciones activas y solicita la revisión exacta del espacio cuando corresponda.
Detalles de seguridad de un plugin con un hook activo y los comandos exactos de hooks y MCP
Antes de activar, ve a Security y revisa todos los comandos ejecutables de los hooks.
## Añade un hook propio {#add-an-operator-hook} Guarda los hooks personales en `~/.clarvis/settings.json` y los del proyecto en `.clarvis/settings.json`, en la raíz del espacio de trabajo. Este ejemplo ejecuta las pruebas del proyecto antes de permitir que el agente termine: ```json { "hooks": [ { "event": "pre_finalize", "command": "bun run test", "timeout_ms": 60000, "on_failure": "deny" } ] } ``` Un comando correcto puede no escribir nada en stdout. Para devolver un veredicto explícito, escribe exactamente un objeto JSON: ```json { "kind": "deny", "message": "The project tests must pass before this run can finish." } ``` Envía los registros de diagnóstico a stderr. Cualquier texto adicional en stdout invalida el veredicto. ## Limita el hook a llamadas concretas {#scope-a-hook-to-tool-calls} `match` solo se admite en `pre_tool_use` y `post_tool_use`. Los patrones de herramientas son nombres exactos o globs. Cada patrón de argumento es una expresión regular de JavaScript y todos deben coincidir: ```json { "hooks": [ { "event": "pre_tool_use", "match": { "tool": "shell", "args": { "command": "(^|\\s)deploy(\\s|$)" } }, "command": "bun run tooling/review-deploy.ts", "timeout_ms": 5000, "on_failure": "deny" } ] } ``` El archivo `tooling/review-deploy.ts` puede denegar la llamada coincidente con un motivo claro: ```ts const input = (await Bun.stdin.json()) as { tool_input?: { command?: unknown }; }; const command = typeof input.tool_input?.command === "string" ? input.tool_input.command : "deploy command"; console.error(`blocked agent-initiated deployment: ${command}`); process.stdout.write( JSON.stringify({ kind: "deny", message: "Run deployments from a separate operator-controlled process.", }), ); ``` El comando recibe un objeto JSON por stdin. Los eventos de herramientas incluyen `tool_name` y `tool_input`; todos incluyen `protocol`, `hook_event_name` y `cwd`. Para documentos compartidos con otros anfitriones, `hook_event_name` y `tool_name` usan nombres externos compatibles. Las herramientas integradas llegan como `Bash`, `Read` o `Skill`; las MCP como `mcp____`. Cargar una skill también añade `skill` junto a su campo nativo `name`. Si el script necesita la identidad de Clarvis, usa `CLARVIS_HOOK_TOOL` para el nombre interno y `CLARVIS_HOOK_TOOL_FULL_NAME` para el nombre MCP estable separado por puntos. Los hooks de control pueden devolver `pass`, `deny` o `advise`. Un `pre_tool_use` también puede devolver `rewrite` con un objeto `arguments` que sustituya todos los argumentos. `session_start` y `pre_compact` pueden devolver texto `context`. Los eventos de observación solo notifican y no bloquean la ejecución. `user_prompt_expansion` se dispara una vez antes de un comando de skill invocado por el usuario; no se dispara para un prompt normal ni para una carga posterior iniciada por el modelo. ::: warning Los hooks usan tus privilegios Los comandos de hooks se ejecutan desde el espacio de trabajo con acceso normal a archivos y red, fuera del sandbox del agente. Clarvis elimina credenciales de proveedores y variables que parecen contener secretos, pero filtrar no aísla el proceso. Trata cada hook como código que has elegido ejecutar. `match` limita cuándo se ejecuta, no es una barrera de seguridad. ::: ## Usa campos portátiles y hooks MCP {#use-portable-lifecycle-fields-and-mcp-hooks} Los documentos portátiles pueden elegir `commandWindows`, ejecutar en segundo plano con `async`, conservar un `statusMessage` limitado y restringir la salida capturada con `additionalContextLimit`. Clarvis los adapta al mismo contrato de hooks. Los comandos asíncronos comparten un máximo de ocho procesos en segundo plano. Un comando `SessionEnd` / `run_end` siempre espera para no perderse al cerrar el proceso. Las entradas portátiles `prompt` y `agent` no tienen equivalente ejecutable: se notifican y se omiten. Un hook `mcp_tool`, nativo o adaptado, llama a un servidor ya abierto sin pasar por el distribuidor de herramientas del modelo: ```json { "hooks": [ { "event": "post_tool_use", "type": "mcp_tool", "server": "review", "tool": "record", "input": { "tool": "${tool_name}", "arguments": "${tool_input}" }, "timeout_ms": 2000 } ] } ``` Los marcadores leen recursivamente campos del evento. La llamada directa no puede disparar hooks de herramientas de forma recursiva. Si faltan servidor o herramienta, hay espera agotada, cancelación o error, el hook deja continuar; por eso `on_failure` no es válido en `mcp_tool`. Los hooks MCP portátiles de `SessionEnd` se omiten porque el conjunto de conexiones ya se está cerrando. Los hooks de comandos de plugins reciben la ruta del paquete en `PLUGIN_ROOT`, un directorio persistente de escritura en `PLUGIN_DATA` y los alias compatibles `CODEX_PLUGIN_ROOT` y `CODEX_PLUGIN_DATA`. Son rutas, no credenciales; se mantiene el filtrado de secretos. ## Aprueba la ejecución del espacio de trabajo {#approve-workspace-execution} Los hooks de `.clarvis/settings.json` no se ejecutan hasta aprobar la huella exacta del espacio. Clarvis pregunta al entrar si la huella es nueva o ha cambiado. `/workspace-trust` permite revisar, aprobar o revocar después. Esa misma decisión cubre los MCP del espacio, selecciones de plugins en ajustes, marketplaces, proveedores ejecutables de capacidades, proveedor de Tasks, agentes locales y todo el inventario de plugins del repositorio, antes de seleccionar el Extension Profile. Los proveedores de suscripción nunca se activan desde ajustes del espacio, ni siquiera tras aprobarlos; configúralos globalmente.
Revisión de confianza con la huella protegida y las aportaciones ejecutables de plugins
La revisión al entrar vincula los hooks y el resto de la configuración ejecutable protegida a una huella exacta.
Un hook de plugin se ejecuta si su plugin completo está seleccionado en el perfil activo. Los plugins globales no necesitan otra aprobación del espacio; los del repositorio requieren que se confíe en la huella de todo el inventario local. El hook no cambia una ejecución ya iniciada. ## Consulta también {#see-also} - [Extension Profiles](/es-ES/guide/extension-profiles) - [Plugins](/es-ES/guide/plugins) - [Servidores MCP](/es-ES/guide/mcp-servers) - [Referencia de extensiones](/es-ES/reference/extensions) - [Variables de entorno](/es-ES/reference/environment-variables) --- [HTML canónico](https://clarvis.dev/es-ES/guide/hooks) [Índice de documentación](https://clarvis.dev/es-ES/llms.txt)