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

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

Auto-Format
Notificações
Bloqueio de Comandos
Auditoria

Auto-formatar arquivos Go após qualquer edicao:

{
  "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"
    }
  ]
}

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 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"
    }
  ]
}

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_FILE\" >> ~/.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

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

​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