Hooks

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 saindo com o código 2 (ou imprimindo um objeto JSON "decision": "block"); qualquer outro código de saída diferente de zero é registrado como erro e não bloqueia — veja Códigos de saída.

Eventos de hook

Os hooks podem responder a estes eventos de ciclo de vida:

Evento	Quando é acionado
`PreToolUse`	Antes de uma ferramenta ser executada
`PostToolUse`	Depois que uma ferramenta é concluída
`PermissionRequest`	Quando é preciso tomar uma decisão de permissão
`UserPromptSubmit`	Quando o usuário envia uma mensagem
`Stop`	Quando o agente quer parar
`PostCompaction`	Após a compactação de contexto ser concluída com êxito
`SessionStart`	Quando uma sessão começa
`SessionEnd`	Quando 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
        }
      ]
    }
  ]
}

Campo	Descrição
`matcher`	Regex 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.
`command`	Comando de shell a ser executado (para o tipo `command`).
`prompt`	Prompt de LLM a ser avaliado (para o tipo `prompt`).
`timeout`	Tempo 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 /"
  },
  "session_id": "3f8d1c2a-...",
  "prompt_id": "b71e9d40-..."
}

Cada payload de evento também inclui dois IDs de correlação além dos campos do evento:

Campo	Descrição
`session_id`	ID estável da sessão do agente. Use-o para correlacionar invocações de hooks ao longo de toda a sessão.
`prompt_id`	ID por turno, renovado a cada prompt do usuário. Todos os hooks acionados durante o mesmo turno compartilham um `prompt_id`. Ausente em eventos que ocorrem antes do primeiro prompt do usuário (por exemplo, `SessionStart`).

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."
  }
}

Para reescrever de forma transparente a entrada de uma ferramenta antes da execução, retorne updatedInput dentro de um hookSpecificOutput de PreToolUse. Os campos em updatedInput são mesclados aos argumentos da ferramenta, então você pode atualizar apenas um subconjunto deles (por exemplo, só command):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

Campo de saída	Descrição
`decision`	`"approve"` para permitir a ação ou `"block"` para bloqueá-la
`reason`	Explicação exibida ao agente
`hookSpecificOutput.hookEventName`	Evento ao qual a saída se aplica (por exemplo, `UserPromptSubmit`, `SessionStart`, `PreToolUse`, `PostToolUse`)
`hookSpecificOutput.additionalContext`	Texto injetado no contexto do agente (para `UserPromptSubmit`, `SessionStart`, `PostToolUse`)
`hookSpecificOutput.updatedInput`	Objeto mesclado aos argumentos da ferramenta antes da execução (para `PreToolUse`)

Códigos de Saída

Código	Significado
0	Sucesso — o hook continua normalmente
2	Bloqueio — a ação é negada
Outros	Erro — é registrado, mas não bloqueia

Onde os hooks ficam

O Devin CLI lê hooks nos seguintes locais. Todos usam o mesmo formato JSON. Os arquivos de hook no nível do projeto são detectados no diretório de trabalho e em seus diretórios ancestrais até a raiz do repositório, da mesma forma que skills e rules são carregados.

No nível do projeto

Localização	Descrição
`.devin/hooks.v1.json`	Arquivo de hooks independente (recomendado)
`.devin/config.json`	chave `"hooks"` no arquivo de configuração
`.devin/config.local.json`	chave `"hooks"` (override local, ignorado pelo Git)
`.claude/settings.json`	chave `"hooks"` (formato do Claude Code)
`.claude/settings.local.json`	chave `"hooks"` (formato do Claude Code)

Nível do usuário (global)

Local	Descrição
`~/.config/devin/config.json` (`%APPDATA%\devin\config.json` no Windows)	chave `"hooks"` na configuração do usuário
`~/.claude.json`	chave `"hooks"` (formato Claude Code)
`~/.claude/settings.json`	chave `"hooks"` (formato Claude Code)
`~/.claude/settings.local.json`	chave `"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

Primeiros passos

Integrações do Editor

Extensibilidade

Enterprise

Referência

Changelog

O que os Hooks podem fazer?

Aplicar políticas

Adicionar contexto

Executar efeitos colaterais

Modificar permissões

Exemplo rápido

Eventos de hook

Formato do hook

Hooks de comando

Formato de saída

Códigos de Saída

Onde os hooks ficam

No nível do projeto

Nível do usuário (global)

Verificando hooks

Próximas etapas

Hooks de ciclo de vida

Configuração

​O que os Hooks podem fazer?

Aplicar políticas

Adicionar contexto

Executar efeitos colaterais

Modificar permissões

​Exemplo rápido

​Eventos de hook

​Formato do hook

​Hooks de comando

​Formato de saída

​Códigos de Saída

​Onde os hooks ficam

​No nível do projeto

​Nível do usuário (global)

​Verificando hooks

​Próximas etapas

Hooks de ciclo de vida

Configuração

O que os Hooks podem fazer?

Exemplo rápido

Eventos de hook

Formato do hook

Hooks de comando

Formato de saída

Códigos de Saída

Onde os hooks ficam

No nível do projeto

Nível do usuário (global)

Verificando hooks

Próximas etapas