Hooks
Ejecuta tus propias comprobaciones antes o después de las acciones del agente.
Distingue de dónde procede cada hook
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.
Añade un hook propio
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:
{
"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:
{ "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
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:
{
"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:
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__<server>__<tool>. 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.
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
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:
{
"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
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.
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.