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

> Execute lógica personalizada quando eventos específicos ocorrerem durante uma sessão

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](#where-hooks-live).

***

<div id="what-can-hooks-do">
  ## O que os Hooks podem fazer?
</div>

<CardGroup cols={2}>
  <Card title="Aplicar políticas" icon="shield">
    Bloquear comandos perigosos, exigir confirmação para ações específicas ou restringir o acesso a arquivos.
  </Card>

  <Card title="Adicionar contexto" icon="message">
    Injetar instruções ou informações adicionais quando ferramentas específicas forem chamadas.
  </Card>

  <Card title="Executar efeitos colaterais" icon="bolt">
    Executar scripts, enviar notificações ou registrar eventos quando algo acontecer.
  </Card>

  <Card title="Modificar permissões" icon="lock">
    Conceder ou restringir permissões dinamicamente com base na situação.
  </Card>
</CardGroup>

***

<div id="quick-example">
  ## Exemplo rápido
</div>

Crie `.devin/hooks.v1.json` no seu projeto:

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

***

<div id="hook-events">
  ## Eventos de hook
</div>

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                      |
| `SessionStart`      | Quando uma sessão começa                        |
| `SessionEnd`        | Quando uma sessão termina                       |

Consulte [Hooks de ciclo de vida](/pt-BR/cli/extensibility/hooks/lifecycle-hooks) para ver detalhes sobre cada evento e os dados disponíveis.

***

<div id="hook-format">
  ## Formato do hook
</div>

Cada hook tem um **tipo** (`command` ou `prompt`), um **matcher** opcional (regex na `tool_name` do evento do hook) e uma configuração:

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

<div id="command-hooks">
  ### Hooks de comando
</div>

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](#output-format) abaixo).

**Entrada** (stdin):

```json theme={null}
{
  "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](/pt-BR/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) para ver os nomes das ferramentas integradas e o formato de nome de ferramenta MCP com o qual você pode fazer correspondência.

<div id="output-format">
  ### Formato de saída
</div>

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):

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

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

| 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`, `PostToolUse`) |
| `hookSpecificOutput.additionalContext` | Texto injetado no contexto do agente (para `UserPromptSubmit`, `SessionStart`, `PostToolUse`)     |

<div id="exit-codes">
  ### Códigos de Saída
</div>

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

***

<div id="where-hooks-live">
  ## Onde os hooks ficam
</div>

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

<div id="project-level">
  ### No nível do projeto
</div>

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

<div id="user-level-global">
  ### Nível do usuário (global)
</div>

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

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

<Note>
  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](/pt-BR/cli/reference/configuration/read-config-from).
</Note>

***

<div id="verifying-hooks">
  ## Verificando hooks
</div>

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

```
/hooks
```

***

<div id="next-steps">
  ## Próximas etapas
</div>

<CardGroup cols={2}>
  <Card title="Hooks de ciclo de vida" icon="rotate" href="/pt-BR/cli/extensibility/hooks/lifecycle-hooks">
    Aprofunde-se em cada tipo de evento e nos dados disponíveis.
  </Card>

  <Card title="Configuração" icon="gear" href="/pt-BR/cli/reference/configuration/read-config-from">
    Defina de quais locais de configuração o Devin CLI lê hooks.
  </Card>
</CardGroup>