Hooks
Execute suas próprias verificações antes ou depois das ações dos agentes.
Entenda a propriedade dos hooks
Um hook executa uma ação em um evento, como antes de uma ferramenta ser usada ou depois que uma execução termina. Seus hooks ficam no settings.json global ou do workspace.
Hooks fornecidos por plugins são ativados e removidos junto com o plugin. Ao selecionar um plugin, você seleciona todos os seus hooks válidos.
Em /extensions, pressione m, abra os detalhes do plugin e inspecione a contagem de hooks e os comandos executáveis antes de instalar ou atualizar. Não há uma tela separada de aprovação por hook. Se o conteúdo do plugin ou do workspace mudar, o Clarvis mantém o novo snapshot fora de execuções ativas e pede a revisão exata do workspace quando aplicável.
Adicione um hook do operador
Coloque hooks pessoais em ~/.clarvis/settings.json ou hooks específicos do projeto em .clarvis/settings.json, na raiz do workspace. Este exemplo executa o comando de teste do projeto antes que um agente possa concluir:
{
"hooks": [
{
"event": "pre_finalize",
"command": "bun run test",
"timeout_ms": 60000,
"on_failure": "deny"
}
]
}Um comando bem-sucedido pode não escrever nada em stdout. Para retornar uma decisão explícita, escreva exatamente um objeto JSON em stdout:
{
"kind": "deny",
"message": "Os testes do projeto precisam passar antes que esta execução possa ser concluída."
}Grave logs de diagnóstico em stderr. Texto adicional em stdout torna a decisão inválida.
Restrinja um hook a chamadas de ferramentas
match está disponível apenas para pre_tool_use e post_tool_use. Os padrões de ferramentas são nomes exatos ou globs, e todo padrão de argumento é uma expressão regular JavaScript que precisa corresponder:
{
"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"
}
]
}O arquivo tooling/review-deploy.ts referenciado pode negar a chamada correspondente com um 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 : "comando de deploy";
console.error(`deploy iniciado pelo agente bloqueado: ${command}`);
process.stdout.write(
JSON.stringify({
kind: "deny",
message: "Execute deploys em um processo separado e controlado pelo operador.",
}),
);O comando do hook recebe um objeto JSON em stdin. Um evento de ferramenta inclui tool_name e tool_input; todos os eventos incluem protocol, hook_event_name e cwd.
Para documentos de hooks compartilhados com outro host, hook_event_name e tool_name usam as grafias externas compatíveis. Assim, ferramentas integradas chegam com nomes como Bash, Read e Skill, enquanto uma ferramenta MCP chega como mcp__<servidor>__<ferramenta>. O carregamento de uma skill também adiciona skill ao lado do campo nativo name. Use CLARVIS_HOOK_TOOL para o nome de wire do Clarvis e CLARVIS_HOOK_TOOL_FULL_NAME para o nome pontuado estável de uma ferramenta MCP quando o script precisar da identidade própria do Clarvis.
Hooks de controle podem retornar pass, deny ou advise. Um hook pre_tool_use também pode retornar rewrite com um objeto arguments substituto completo. Hooks session_start e pre_compact podem retornar texto em context. Eventos observadores são executados apenas para notificação e não podem bloquear a execução. Um observador user_prompt_expansion é executado uma vez antes do início de um comando de skill invocado pelo usuário; ele não é executado para um prompt comum nem para um carregamento posterior de skill iniciado pelo modelo.
Hooks são executados com seus privilégios
Os comandos de hooks são executados a partir do workspace com acesso normal ao sistema de arquivos e à rede. Eles não são executados no sandbox do agente. O Clarvis remove credenciais de provedores e variáveis de ambiente com formato de segredo, mas essa filtragem não isola o processo. Trate todo comando de hook como código executável que você escolheu executar. Um match restringe quando um hook é executado, mas não é um limite de segurança.
Use campos portáteis de ciclo de vida e hooks MCP
Documentos portáteis de hooks de plugin podem selecionar commandWindows, desanexar um comando com async, preservar um statusMessage limitado e restringir a saída capturada com additionalContextLimit. O Clarvis converte esses campos para o mesmo contrato normalizado. Comandos assíncronos compartilham um teto de oito processos em segundo plano; um comando SessionEnd / run_end sempre aguarda para não ser perdido no encerramento. Entradas portáteis de hook prompt e agent não têm contraparte executável, portanto são relatadas e ignoradas.
Um hook mcp_tool nativo ou traduzido chama um servidor já aberto sem passar pelo dispatcher de ferramentas do modelo:
{
"hooks": [
{
"event": "post_tool_use",
"type": "mcp_tool",
"server": "review",
"tool": "record",
"input": {
"tool": "${tool_name}",
"arguments": "${tool_input}"
},
"timeout_ms": 2000
}
]
}Os placeholders usam valores dos campos do evento, inclusive objetos aninhados. A chamada direta não dispara novos hooks de ferramenta. Se o servidor estiver ausente, houver timeout, cancelamento ou erro, o hook não bloqueia a execução. Por isso, on_failure não é aceito em mcp_tool. Hooks MCP portáteis em SessionEnd são ignorados porque as conexões já estão sendo fechadas.
Hooks de comando de plugin recebem o caminho resolvido do pacote em PLUGIN_ROOT, um caminho persistente e gravável em PLUGIN_DATA e os aliases de compatibilidade CODEX_PLUGIN_ROOT e CODEX_PLUGIN_DATA. Eles são caminhos, não credenciais; a filtragem normal de segredos continua valendo.
Aprove a execução no workspace
Hooks de .clarvis/settings.json não são executados até que o fingerprint exato do workspace seja aprovado. O Clarvis pergunta na entrada quando a superfície protegida é nova ou mudou. /workspace-trust continua disponível para revisar, aprovar ou revogar depois. A mesma decisão de confiança também abrange servidores MCP, seleções de plugins nas configurações, marketplaces, provedores executáveis de capacidades, um provedor de Tasks, agentes do workspace e o inventário completo de plugins do workspace pertencentes ao repositório antes da seleção do Extension Profile. Declarações de provedores de assinatura nunca são ativadas pelas configurações do workspace, mesmo após a aprovação; configure-as globalmente.
Um hook de plugin é executado quando seu plugin completo está selecionado pelo Extension Profile ativo. Um plugin global não exige uma segunda aprovação do workspace; um plugin do workspace pertencente ao repositório também precisa que o fingerprint do inventário completo de plugins do workspace esteja aprovado. O hook nunca altera uma execução já ativa.