Pular para o conteúdo principal
Os hooks permitem executar lógica personalizada em resposta a eventos no ciclo de vida do agente. Você pode usar hooks para aplicar políticas, adicionar contexto, registrar ações, modificar permissões ou integrar-se a sistemas externos. Os hooks são configurados em formato JSON. Coloque-os no diretório .devin/ do seu projeto (ou em uma configuração em nível de usuário), e a Devin CLI os executará nos eventos correspondentes do ciclo de vida. Hooks existentes em diretórios .claude/ também são detectados automaticamente — consulte Onde os hooks ficam.

​
O que os Hooks podem fazer?

Aplicar políticas

Bloquear comandos perigosos, exigir confirmação para ações específicas ou restringir o acesso a arquivos.

Adicionar contexto

Injetar instruções ou informações adicionais quando ferramentas específicas forem chamadas.

Executar efeitos colaterais

Executar scripts, enviar notificações ou registrar eventos quando algo acontecer.

Modificar permissões

Conceder ou restringir permissões dinamicamente com base na situação.

​
Exemplo rápido

Crie .devin/hooks.v1.json no seu projeto: 
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}
Executa ./scripts/check-command.sh antes de cada execução de comando de shell. O script recebe os dados do evento pela stdin e pode bloquear a ação retornando um código de saída diferente de zero.

​
Eventos de hook

Os hooks podem responder a estes eventos de ciclo de vida:
EventoQuando é acionado
PreToolUseAntes de uma ferramenta ser executada
PostToolUseDepois que uma ferramenta é concluída
PermissionRequestQuando é preciso tomar uma decisão de permissão
UserPromptSubmitQuando o usuário envia uma mensagem
StopQuando o agente quer parar
SessionStartQuando uma sessão começa
SessionEndQuando uma sessão termina
Consulte Hooks de ciclo de vida para ver detalhes sobre cada evento e os dados disponíveis.

​
Formato do hook

Cada hook tem um tipo (command ou prompt), um matcher opcional (regex na tool_name do evento do hook) e uma configuração: 
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}
CampoDescrição
matcherRegex comparada ao tool_name do evento do hook. Uma string vazia ou a omissão de matcher corresponde a todos os nomes de ferramenta.
type"command" para executar um comando de shell ou "prompt" para avaliar um prompt de LLM.
commandComando de shell a ser executado (para o tipo command).
promptPrompt de LLM a ser avaliado (para o tipo prompt).
timeoutTempo limite em segundos (opcional).

​
Hooks de comando

Os hooks de comando executam um comando no shell. Os dados do evento são enviados como JSON em stdin, e o comando pode retornar JSON em stdout para controlar o resultado (consulte Formato de saída abaixo). Entrada (stdin): 
{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}
A variável de ambiente DEVIN_PROJECT_DIR é definida automaticamente como o diretório raiz do projeto. Consulte Como usar o Matcher para ver os nomes das ferramentas integradas e o formato de nome de ferramenta MCP com o qual você pode fazer correspondência.

​
Formato de saída

Um hook de comando pode imprimir um objeto JSON em stdout para controlar o resultado. Para aprovar ou bloquear uma ação, retorne um campo decision no nível superior (com um reason opcional): 
{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}
Para injetar texto no contexto do agente, retorne additionalContext dentro de um objeto hookSpecificOutput identificado com o nome do evento: 
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Remember: deploys require an approved change ticket."
  }
}
Campo de saídaDescrição
decision"approve" para permitir a ação ou "block" para bloqueá-la
reasonExplicação exibida ao agente
hookSpecificOutput.hookEventNameEvento ao qual a saída se aplica (por exemplo, UserPromptSubmit, SessionStart, PostToolUse)
hookSpecificOutput.additionalContextTexto injetado no contexto do agente (para UserPromptSubmit, SessionStart, PostToolUse)

​
Códigos de Saída

CódigoSignificado
0Sucesso — o hook continua normalmente
2Bloqueio — a ação é negada
OutrosErro — é registrado, mas não bloqueia

​
Onde os hooks ficam

O Devin CLI lê hooks nos seguintes locais. Todos usam o mesmo formato JSON.

​
No nível do projeto

LocalizaçãoDescrição
.devin/hooks.v1.jsonArquivo de hooks independente (recomendado)
.devin/config.jsonchave "hooks" no arquivo de configuração
.devin/config.local.jsonchave "hooks" (override local, ignorado pelo Git)
.claude/settings.jsonchave "hooks" (formato do Claude Code)
.claude/settings.local.jsonchave "hooks" (formato do Claude Code)

​
Nível do usuário (global)

LocalDescrição
~/.config/devin/config.json (%APPDATA%\devin\config.json no Windows)chave "hooks" na configuração do usuário
~/.claude.jsonchave "hooks" (formato Claude Code)
~/.claude/settings.jsonchave "hooks" (formato Claude Code)
~/.claude/settings.local.jsonchave "hooks" (formato Claude Code)
Em .devin/hooks.v1.json, o objeto hooks é o arquivo inteiro (não é necessária nenhuma chave de encapsulamento). Em todos os outros locais, hooks fica aninhado sob a chave "hooks" em um arquivo de configurações.
Os hooks dos caminhos .claude/ são carregados quando read_config_from.claude está ativado (padrão). Se necessário, você pode desativar isso na sua configuração do usuário.

​
Verificando hooks

Use o comando /hooks para ver todos os hooks carregados no momento e seus arquivos de origem: 
/hooks

​
Próximas etapas

Hooks de ciclo de vida

Aprofunde-se em cada tipo de evento e nos dados disponíveis.

Configuração

Defina de quais locais de configuração o Devin CLI lê hooks.