Hooks do ciclo de vida

Cada evento de hook é acionado em um ponto específico do ciclo de vida do agente. Use o campo matcher (uma regex aplicada ao tool_name do evento de hook) para filtrar quais invocações de ferramenta acionam seu hook.

PreToolUse

É acionado antes de uma ferramenta ser executada. Use isso para bloquear, modificar ou adicionar contexto às chamadas de ferramentas. Dados de stdin:

Campo	Descrição	Exemplo
`tool_name`	Nome da ferramenta sendo chamada	`exec`, `edit`, `mcp__github__create_issue`
`tool_input`	Argumentos passados para a ferramenta	`{ "command": "rm -rf /", "shell_id": "main" }`

Exemplo — Bloquear comandos destrutivos:

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); sys.exit(2 if 'rm -rf' in cmd else 0)\""
        }
      ]
    }
  ]
}

Exemplo — Exigir confirmação para escritas fora de src/: Use um script que analisa a entrada da ferramenta e retorna uma decisão:

{
  "PreToolUse": [
    {
      "matcher": "edit",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-edit-path.sh",
          "timeout": 5
        }
      ]
    }
  ]
}

Exemplo — Reescrever comandos antes da execução: Um hook pode reescrever de forma transparente a entrada da ferramenta ao imprimir hookSpecificOutput.updatedInput em stdout (consulte Formato de saída). Por exemplo, um script de hook que encaminha comandos de shell por meio de um wrapper:

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

Os argumentos reescritos são incorporados à chamada da ferramenta antes da execução — o agente executa o comando atualizado em vez do original.

PostToolUse

É acionado após a execução de uma ferramenta. Use isso para logging, validação ou para acionar ações subsequentes. Dados de stdin:

Campo	Descrição
`tool_name`	Nome da ferramenta executada
`tool_input`	Argumentos que foram passados
`tool_response`	Objeto com `success` (boolean), `output` (string) e `error` (string ou null)

Exemplo — Registrar em log todos os comandos do shell:

{
  "PostToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-command-log'"
        }
      ]
    }
  ]
}

PermissionRequest

É acionado quando o agente precisa de uma decisão sobre permissão. Use isso para implementar uma lógica de aprovação personalizada. Dados de stdin:

Campo	Descrição
`tool_name`	Ferramenta que está solicitando permissão
`tool_input`	Argumentos da chamada da ferramenta

Exemplo — Aprovar automaticamente comandos git:

{
  "PermissionRequest": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); print(json.dumps({'decision': 'approve'})) if cmd.startswith('git ') else sys.exit(0)\""
        }
      ]
    }
  ]
}

UserPromptSubmit

É acionado quando o usuário envia uma mensagem. Use isto para adicionar contexto ou acionar workflows. Dados de stdin:

Campo	Descrição
`prompt`	O texto da mensagem do usuário

Exemplo — Injete contexto em todos os prompts:

{
  "UserPromptSubmit": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"UserPromptSubmit\", \"additionalContext\": \"Deploys require an approved change ticket.\"}}'"
        }
      ]
    }
  ]
}

O comando imprime additionalContext dentro de um objeto hookSpecificOutput no stdout, marcado com o nome do evento. Esse texto é injetado no contexto do agente:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}

Stop

É acionado quando o agente decide parar (encerrar seu turno). Use isso para adicionar instruções adicionais ou evitar que ele pare cedo demais. Dados de stdin:

Campo	Descrição
`stop_hook_active`	Indica se um hook de parada já está ativo

Exemplo — Lembre o agente de executar testes:

{
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"decision\": \"block\", \"reason\": \"Please run the test suite before stopping.\"}'"
        }
      ]
    }
  ]
}

Tenha cuidado com hooks de parada que bloqueiam — eles podem fazer o agente entrar em loop se a condição não acabar sendo atendida.

PostCompaction

É acionado após a compactação de contexto ser concluída com sucesso. Use isso para registrar em log, acionar ações subsequentes ou reinjetar contexto que possa ter sido perdido durante a compactação. Dados de stdin:

Campo	Descrição
`summary`	Texto de resumo produzido pelo compactador (pode ser nulo se nenhum resumo tiver sido gerado)

Exemplo — Registrar eventos de compactação:

{
  "PostCompaction": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-compaction-log'"
        }
      ]
    }
  ]
}

SessionStart

É acionado quando uma nova sessão é iniciada. Use-o para inicialização, registro em log ou configuração do ambiente. Dados de stdin:

Campo	Descrição
`source`	Como a sessão foi iniciada

Exemplo — Executar script de configuração:

{
  "SessionStart": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/dev-setup.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

Um comando SessionStart também pode injetar contexto ao imprimir additionalContext dentro de um objeto hookSpecificOutput no stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}

SessionEnd

Ocorre quando uma sessão termina. Use este evento para limpeza ou registro final. Dados de stdin:

Campo	Descrição
`reason`	Motivo do encerramento da sessão

Correspondência com vários eventos

Um único arquivo de hooks pode definir hooks para vários eventos:

{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}

Como usar o matcher

O campo matcher é uma regex aplicada ao tool_name do evento do hook. Ele está disponível para eventos relacionados a ferramentas: PreToolUse, PostToolUse e PermissionRequest. Para eventos que não envolvem ferramentas (UserPromptSubmit, Stop, PostCompaction, SessionStart e SessionEnd), não há tool_name; use "" ou omita o matcher para executar o hook em todos os eventos desse tipo.

O matcher não é um glob de permissão. Padrões como mcp__github__* são úteis em permissões, mas matchers de hook são regexes. Use mcp__github__.* em um matcher de hook.

Matcher	Corresponde a
`""` (vazio) ou omitido	Todos os nomes de ferramentas em eventos de ferramenta
`"exec"`	Nomes de ferramentas que contêm `exec`
`"^exec$"`	Apenas a ferramenta `exec`
`"^(exec\|edit)$"`	Apenas `exec` ou `edit`
`"^mcp__.*"`	Todas as ferramentas MCP
`"^mcp__github__.*"`	Todas as ferramentas do servidor MCP `github`
`"^mcp__github__create_issue$"`	A ferramenta `create_issue` do servidor MCP `github`

Nomes de ferramentas com os quais você pode fazer correspondência

Os matchers de hook operam sobre os mesmos nomes de ferramentas visíveis externamente que os scripts de hook recebem via stdin como tool_name. Os nomes exatos de ferramentas disponíveis podem variar conforme o modo da CLI, o modelo e as integrações ativadas. Os nomes públicos mais comuns das ferramentas principais são:

read
edit
grep
glob
exec

As ferramentas de servidor MCP aparecem como mcp__<server>__<tool>. Por exemplo, uma ferramenta de servidor MCP github chamada create_issue aparece como mcp__github__create_issue. Para outras ferramentas, faça correspondência com o tool_name exato mostrado no stdin do hook. Para confirmar o conjunto completo disponível na sua sessão atual, adicione temporariamente um hook PostToolUse com matcher: "" e registre o payload do stdin.

​PreToolUse

​PostToolUse

​PermissionRequest

​UserPromptSubmit

​Stop

​PostCompaction

​SessionStart

​SessionEnd

​Correspondência com vários eventos

​Como usar o matcher

​Nomes de ferramentas com os quais você pode fazer correspondência

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Stop

PostCompaction

SessionStart

SessionEnd

Correspondência com vários eventos

Como usar o matcher

Nomes de ferramentas com os quais você pode fazer correspondência