Sistema de Hooks

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.

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

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

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

Estrutura do Arquivo

{
  "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 8 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
`UserPromptSubmit`	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
`PostToolUseFailure`	Quando uma ferramenta falha	Não
`PreCompact`	Antes de qualquer compactação de histórico — automática (chat, agent/coder, one-shot), `/compact` ou recovery de overflow de contexto	Não
`PostCompact`	Depois que o histórico compactado está no lugar	Não

Os eventos de compactação carregam um campo trigger (auto, manual, recovery) e, no PostCompact, um outcome (applied quando o histórico mudou, skipped quando nada mudou: no-op, resumo rejeitado, falha) no payload JSON e em CHATCLI_HOOK_TRIGGER / CHATCLI_HOOK_OUTCOME; todo PreCompact tem exatamente um PostCompact par, então um hook pode tirar snapshot do transcript antes de uma reescrita automática, logar /compact manuais separadamente ou alertar em recoveries de overflow. PreCompact roda de forma síncrona antes de o histórico mudar; PostCompact roda desacoplado do turno.

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.

Tipos de Hook

Command (Shell)
HTTP (Webhook)

Executa um comando shell no sistema operacional. O comando tem acesso a variáveis de ambiente com contexto do evento.

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

O comando e executado via sh -c no Linux/macOS e cmd /c no Windows.

Envia uma requisicao HTTP POST para a URL especificada. O corpo da requisicao contem um JSON com os dados do evento.

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

Payload JSON enviado:

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

Webhooks são disparados de forma assincrona e não bloqueiam a execução do ChatCLI.

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)

{
  "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 aplicável)	`write`
`CHATCLI_HOOK_SESSION`	ID da sessão atual	`session_abc123`
`CHATCLI_HOOK_TRIGGER`	Gatilho da compactação (só `PreCompact`/`PostCompact`)	`auto`
`CHATCLI_HOOK_OUTCOME`	Resultado da compactação (só `PostCompact`): `applied` ou `skipped`	`applied`

Todo o resto do evento — argumentos e output da ferramenta, o prompt do usuário, o diretório de trabalho, a mensagem de erro — chega como payload JSON no stdin (toolArgs, toolOutput, userPrompt, workingDir, error, trigger); leia com jq quando um hook precisar de mais do que as quatro variáveis acima.

Exemplos Completos

Auto-Format
Notificações
Bloqueio de Comandos
Auditoria

Auto-formatar arquivos Go após qualquer edicao:

{
  "hooks": [
    {
      "event": "PostToolUse",
      "type": "command",
      "command": "f=$(jq -r '.toolArgs' | grep -oE '[^ \"]+\\.go' | head -1); if [ -n \"$f\" ]; then gofmt -w \"$f\"; fi",
      "toolPattern": "write|patch",
      "description": "Auto-format Go files"
    }
  ]
}

Enviar notificação no Slack ao final de cada sessão:

{
  "hooks": [
    {
      "event": "SessionEnd",
      "type": "http",
      "url": "https://hooks.slack.com/services/T00/B00/xxx",
      "description": "Notify Slack on session end"
    }
  ]
}

Bloquear rm -rf e DROP TABLE em produção:

{
  "hooks": [
    {
      "event": "PreToolUse",
      "type": "command",
      "command": "if jq -r '.toolArgs' | grep -qE 'rm -rf|DROP TABLE'; then echo 'BLOCKED: dangerous command' >&2; exit 2; fi",
      "toolPattern": "exec*",
      "description": "Block dangerous shell commands"
    }
  ]
}

Registrar log de todas as ferramentas executadas:

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

Casos de Uso

Auto-Format

Execute formatadores (gofmt, prettier, black) automaticamente após edicoes de arquivo.

Notificações

Envie alertas para Slack, Discord ou email ao final de sessões ou em erros.

Guardrails

Bloqueie comandos perigosos (rm -rf, DROP TABLE, force push) com PreToolUse.

Auditoria

Registre todas as ações do agent em arquivos de log para compliance.

Testes Automaticos

Execute testes automaticamente após cada edicao de código.

Linting

Execute linters (golangci-lint, eslint) após cada write/patch.

Próximos Passos

Coder Security

Politicas de segurança e aprovação para operações do coder.

Segurança

Entenda o modelo de segurança do ChatCLI.

UI Compacta

Modo de exibicao minimalista para o coder mode.

Modo Coder

O ciclo completo de engenharia com hooks integrados.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

Sistema de Hooks

Configuração

Estrutura do Arquivo

Eventos Disponíveis

Tipos de Hook

ToolPattern — Filtro por Ferramenta

Variáveis de Ambiente

Exemplos Completos

Casos de Uso

Auto-Format

Notificações

Guardrails

Auditoria

Testes Automaticos

Linting

Próximos Passos

Coder Security

Segurança

UI Compacta

Modo Coder

​Configuração

​Estrutura do Arquivo

​Eventos Disponíveis

​Tipos de Hook

​ToolPattern — Filtro por Ferramenta

​Variáveis de Ambiente

​Exemplos Completos

​Casos de Uso

Auto-Format

Notificações

Guardrails

Auditoria

Testes Automaticos

Linting

​Próximos Passos

Coder Security

Segurança

UI Compacta

Modo Coder

Configuração

Estrutura do Arquivo

Eventos Disponíveis

Tipos de Hook

ToolPattern — Filtro por Ferramenta

Variáveis de Ambiente

Exemplos Completos

Casos de Uso

Próximos Passos