> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks do ciclo de vida

> Entenda os eventos de hook e os dados disponíveis em cada etapa

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.

***

<div id="pretooluse">
  ## PreToolUse
</div>

É 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:**

```json theme={null}
{
  "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:

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

***

<div id="posttooluse">
  ## PostToolUse
</div>

É 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:**

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

***

<div id="permissionrequest">
  ## PermissionRequest
</div>

É 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:**

```json theme={null}
{
  "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)\""
        }
      ]
    }
  ]
}
```

***

<div id="userpromptsubmit">
  ## UserPromptSubmit
</div>

É 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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}
```

***

<div id="stop">
  ## Stop
</div>

É 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:**

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

<Warning>
  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.
</Warning>

***

<div id="postcompaction">
  ## PostCompaction
</div>

É 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:**

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

***

<div id="sessionstart">
  ## SessionStart
</div>

É 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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}
```

***

<div id="sessionend">
  ## SessionEnd
</div>

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 |

***

<div id="matching-multiple-events">
  ## Correspondência com vários eventos
</div>

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

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}
```

<div id="using-the-matcher">
  ## Como usar o matcher
</div>

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.

<Note>
  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.
</Note>

| 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`   |

<div id="tool-names-you-can-match">
  ### Nomes de ferramentas com os quais você pode fazer correspondência
</div>

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.