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

# Sistema de Hooks

> Automatize ações com hooks de lifecycle para eventos como execução de tools, inicio/fim de sessão e submissao de prompts

O **Sistema de Hooks** do ChatCLI permite que você execute ações automáticas em resposta a eventos do ciclo de vida da aplicação. Com hooks, você pode auto-formatar código após edicoes, enviar notificações, bloquear comandos perigosos, registrar logs de auditoria e muito mais.

<Info>
  Hooks são **aditivos**: configurações globais e de workspace são mescladas. Hooks de workspace complementam os globais, nunca os substituem.
</Info>

***

## Configuração

Os hooks são definidos em arquivos JSON em dois níveis:

| Nível         | Arquivo                 | Escopo                      |
| :------------ | :---------------------- | :-------------------------- |
| **Global**    | `~/.chatcli/hooks.json` | Todos os projetos e sessões |
| **Workspace** | `.chatcli/hooks.json`   | Apenas o projeto atual      |

<Tip>
  Hooks de workspace são **aditivos** -- eles se somam aos hooks globais. Se o mesmo evento tem hooks em ambos os níveis, todos são executados (globais primeiro, depois workspace).
</Tip>

### Estrutura do Arquivo

```json theme={"system"}
{
  "hooks": [
    {
      "event": "PostToolUse",
      "type": "command",
      "command": "gofmt -w {{.FilePath}}",
      "toolPattern": "write|patch",
      "description": "Auto-format Go files after edits"
    },
    {
      "event": "SessionEnd",
      "type": "http",
      "url": "https://hooks.example.com/chatcli",
      "description": "Notify team of session end"
    }
  ]
}
```

***

## Eventos Disponíveis

O ChatCLI emite 9 eventos de lifecycle aos quais hooks podem se vincular:

| Evento         | Quando dispara                               | Blocking |
| :------------- | :------------------------------------------- | :------- |
| `SessionStart` | Ao iniciar uma nova sessão do ChatCLI        | Não      |
| `SessionEnd`   | Ao encerrar a sessão (exit/quit)             | Não      |
| `PromptSubmit` | Quando o usuário submete um prompt           | Não      |
| `PreToolUse`   | **Antes** de executar uma ferramenta         | **Sim**  |
| `PostToolUse`  | **Após** executar uma ferramenta com sucesso | Não      |
| `ToolError`    | Quando uma ferramenta falha                  | Não      |
| `AgentStart`   | Ao entrar em agent/coder mode                | Não      |
| `AgentEnd`     | Ao sair de agent/coder mode                  | Não      |
| `CompactDone`  | Após uma compactação de histórico            | Não      |

<Warning>
  O evento `PreToolUse` e **blocking**: se o hook retornar exit code 2, a execução da ferramenta e **bloqueada**. Isso permite criar guardrails que impedem operações perigosas.
</Warning>

***

## Tipos de Hook

<Tabs>
  <Tab title="Command (Shell)">
    Executa um comando shell no sistema operacional. O comando tem acesso a variáveis de ambiente com contexto do evento.

    ```json theme={"system"}
    {
      "event": "PostToolUse",
      "type": "command",
      "command": "gofmt -w {{.FilePath}}",
      "toolPattern": "write|patch",
      "description": "Auto-format Go files after write/patch"
    }
    ```

    **Exit codes**:

    * `0` -- Sucesso (execução continua normalmente)
    * `1` -- Erro (logado, mas não bloqueia)
    * `2` -- **Bloqueia a operação** (apenas para `PreToolUse`)

    <Info>O comando e executado via `sh -c` no Linux/macOS e `cmd /c` no Windows.</Info>
  </Tab>

  <Tab title="HTTP (Webhook)">
    Envia uma requisicao HTTP POST para a URL especificada. O corpo da requisicao contem um JSON com os dados do evento.

    ```json theme={"system"}
    {
      "event": "SessionEnd",
      "type": "http",
      "url": "https://hooks.example.com/chatcli/events",
      "description": "Send session end notification"
    }
    ```

    **Payload JSON enviado**:

    ```json theme={"system"}
    {
      "event": "SessionEnd",
      "timestamp": "2026-03-29T14:30:00Z",
      "session_id": "abc123",
      "tool": "",
      "data": {
        "duration": "45m12s",
        "messages": 32
      }
    }
    ```

    <Tip>Webhooks são disparados de forma assincrona e não bloqueiam a execução do ChatCLI.</Tip>
  </Tab>
</Tabs>

***

## ToolPattern -- Filtro por Ferramenta

O campo `toolPattern` permite filtrar quais ferramentas acionam o hook. Ele aceita padroes **glob**:

| Pattern        | Ferramentas matched                       |
| :------------- | :---------------------------------------- |
| `write`        | Apenas `write`                            |
| `write\|patch` | `write` ou `patch`                        |
| `exec*`        | `exec`, `exec_background`, etc.           |
| `mcp_*`        | Todas as ferramentas MCP                  |
| `*`            | Todas as ferramentas (default se omitido) |

```json theme={"system"}
{
  "event": "PreToolUse",
  "type": "command",
  "command": "echo 'BLOCKED: exec not allowed' && exit 2",
  "toolPattern": "exec*",
  "description": "Block all exec commands"
}
```

***

## Variáveis de Ambiente

Hooks do tipo `command` recebem variáveis de ambiente com contexto do evento:

| Variável               | Descrição                                 | Exemplo              |
| :--------------------- | :---------------------------------------- | :------------------- |
| `CHATCLI_HOOK_EVENT`   | Nome do evento que disparou o hook        | `PostToolUse`        |
| `CHATCLI_HOOK_TOOL`    | Nome da ferramenta (se aplicavel)         | `write`              |
| `CHATCLI_HOOK_SESSION` | ID da sessão atual                        | `session_abc123`     |
| `CHATCLI_HOOK_FILE`    | Caminho do arquivo afetado (se aplicavel) | `/project/main.go`   |
| `CHATCLI_HOOK_CWD`     | Diretório de trabalho atual               | `/Users/dev/project` |
| `CHATCLI_HOOK_MODE`    | Modo atual (chat, agent, coder)           | `agent`              |

***

## Exemplos Completos

<Tabs>
  <Tab title="Auto-Format">
    Auto-formatar arquivos Go após qualquer edicao:

    ```json theme={"system"}
    {
      "hooks": [
        {
          "event": "PostToolUse",
          "type": "command",
          "command": "if [[ \"$CHATCLI_HOOK_FILE\" == *.go ]]; then gofmt -w \"$CHATCLI_HOOK_FILE\"; fi",
          "toolPattern": "write|patch",
          "description": "Auto-format Go files"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Notificações">
    Enviar notificação no Slack ao final de cada sessão:

    ```json theme={"system"}
    {
      "hooks": [
        {
          "event": "SessionEnd",
          "type": "http",
          "url": "https://hooks.slack.com/services/T00/B00/xxx",
          "description": "Notify Slack on session end"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Bloqueio de Comandos">
    Bloquear `rm -rf` e `DROP TABLE` em produção:

    ```json theme={"system"}
    {
      "hooks": [
        {
          "event": "PreToolUse",
          "type": "command",
          "command": "if echo \"$CHATCLI_HOOK_ARGS\" | grep -qE 'rm -rf|DROP TABLE'; then echo 'BLOCKED: dangerous command' >&2; exit 2; fi",
          "toolPattern": "exec*",
          "description": "Block dangerous shell commands"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="Auditoria">
    Registrar log de todas as ferramentas executadas:

    ```json theme={"system"}
    {
      "hooks": [
        {
          "event": "PostToolUse",
          "type": "command",
          "command": "echo \"$(date -u +%Y-%m-%dT%H:%M:%SZ) $CHATCLI_HOOK_EVENT $CHATCLI_HOOK_TOOL $CHATCLI_HOOK_FILE\" >> ~/.chatcli/audit.log",
          "description": "Audit log for all tool executions"
        }
      ]
    }
    ```
  </Tab>
</Tabs>

***

## Casos de Uso

<CardGroup cols={2}>
  <Card title="Auto-Format" icon="wand-magic-sparkles">
    Execute formatadores (gofmt, prettier, black) automaticamente após edicoes de arquivo.
  </Card>

  <Card title="Notificações" icon="bell">
    Envie alertas para Slack, Discord ou email ao final de sessões ou em erros.
  </Card>

  <Card title="Guardrails" icon="shield-halved">
    Bloqueie comandos perigosos (rm -rf, DROP TABLE, force push) com PreToolUse.
  </Card>

  <Card title="Auditoria" icon="clipboard-list">
    Registre todas as ações do agent em arquivos de log para compliance.
  </Card>

  <Card title="Testes Automaticos" icon="flask-vial">
    Execute testes automaticamente após cada edicao de código.
  </Card>

  <Card title="Linting" icon="broom">
    Execute linters (golangci-lint, eslint) após cada write/patch.
  </Card>
</CardGroup>

***

## Próximos Passos

<CardGroup cols={2}>
  <Card title="Coder Security" icon="shield-halved" href="/pt/features/coder-security">
    Politicas de segurança e aprovação para operações do coder.
  </Card>

  <Card title="Segurança" icon="shield-halved" href="/pt/features/security">
    Entenda o modelo de segurança do ChatCLI.
  </Card>

  <Card title="UI Compacta" icon="minimize" href="/pt/features/compact-ui">
    Modo de exibicao minimalista para o coder mode.
  </Card>

  <Card title="Modo Coder" icon="code" href="/pt/core-concepts/coder-mode">
    O ciclo completo de engenharia com hooks integrados.
  </Card>
</CardGroup>