← Home

⚡ Guia de Hooks 10

Hooks são scripts JavaScript (Node.js) determinísticos executados em eventos específicos do ciclo de vida de uma sessão de agente. Diferente de instruções (que o agente pode ignorar), hooks garantem execução — rodam como processos reais, recebem JSON via stdin e retornam JSON via stdout. Os hooks globais são configurados em hooks/hooks.json e os agent-scoped ficam no frontmatter de cada agent.

O output do hook comunica uma decisão ao agente. As formas principais são: permissionDecision (allow/deny/ask) para PreToolUse, decision: "block" + reason para Stop (força o agente a reconsiderar), e additionalContext para injetar contexto adicional.

PreToolUse
Stop
SubagentStart
SessionStart
PreCompact
UserPromptSubmit
🛡️

pre-commit-guard

PreToolUse

Guarda contra operações git perigosas. Intercepta chamadas a run_in_terminal que envolvem git commit, git push ou git tag e aplica regras diferentes para cada uma. Suporta comandos encadeados (;, &&, ||) — cada comando git é avaliado independentemente e a decisão mais restritiva vence (deny > ask > allow).

Lógica detalhada
  • git commit: verifica se tem flag -m com mensagem conventional commits (feat, fix, docs, chore, etc.). Se válido → allow. Se inválido ou sem -m → deny
  • git push: sempre retorna ask — pede confirmação do usuário
  • git tag: sempre retorna ask — pede confirmação do usuário
  • Outros comandos: passthrough silencioso (exit 0)
Usado por
orchestrator implementor
Como o output chega ao agente
→ Retorna hookSpecificOutput.permissionDecision com valores "allow", "deny", ou "ask". O campo additionalContext fornece a razão (ex: "Commit message must follow conventional commits pattern").
Exemplo de trigger: O agente tenta executar git commit -m "added stuff" → hook intercepta, detecta que a mensagem não segue conventional commits → retorna deny com explicação. O agente reformula para git commit -m "feat: add new feature" → hook retorna allow.
📊

context-confidence-check

Stop

Valida que a tabela de confiança da Phase 2 (skill contextação) tem evidência de ferramentas para cada eixo 🟡 (Médio) ou 🔴 (Baixo). Cross-referencia as ferramentas listadas com o transcript da sessão para confirmar que foram realmente usadas.

Lógica detalhada
  • Busca no transcript o padrão de tabela: | Axis | Confidence | Justification | Tools used |
  • Para cada eixo 🟡/🔴: verifica se a coluna "Tools used" não está vazia
  • Para cada ferramenta listada: confirma que aparece no transcript como chamada real
  • Eixos 🟢 (Alta) são ignorados — não requerem evidência de ferramenta
  • Se não há tabela de confiança no output → passthrough (exit 0)
Usado por
orchestrator implementor researcher validator
Como o output chega ao agente
→ Retorna decision: "block" + reason se algum eixo 🟡/🔴 não tem evidência de ferramentas, ou se uma ferramenta listada não aparece no transcript. O agente é forçado a corrigir antes de finalizar.
Exemplo de trigger: O researcher entrega uma análise com eixo "Dependencies" classificado 🟡 mas a coluna "Tools used" está vazia → hook bloqueia e exige que o agente pesquise com ferramentas antes de aceitar a classificação.
📋

output-format

Stop

Lembra o agente de seguir o formato de output correto: Research Summary (para o researcher) ou Validation Report (para o validator). Garante que a entrega sempre inclua as seções obrigatórias definidas no output template de cada agente.

Lógica detalhada
  • Sempre retorna block com reminder sobre o formato obrigatório
  • Protege contra loop infinito: se stop_hook_active está true, faz exit 0
  • Não valida o conteúdo — apenas lembra o formato esperado
Usado por
researcher validator
Como o output chega ao agente
→ Retorna decision: "block" + reason com mensagem: "Verify your output follows the required format: Research Summary (researcher) or Validation Report (validator) with all mandatory sections." O agente revisa seu output antes de entregar.
Exemplo de trigger: O researcher prepara uma resposta sem o formato "Research Summary" com seções obrigatórias (Key Findings, Open Questions, Assumptions) → hook bloqueia e pede revisão do formato.
💬

skill-feedback

Stop

Captura feedback de skills quando o usuário expressou insatisfação ou correções foram necessárias. Lembra o agente de seguir o Feedback Protocol descrito na skill para criar reviews estruturados — mas somente quando validado pelo usuário, nunca autonomamente.

Lógica detalhada
  • Sempre retorna block com instrução de checagem de feedback
  • O agente deve verificar: alguma skill com Feedback Protocol foi usada? O usuário reclamou?
  • Se houve insatisfação → perguntar ao usuário o que falhou → criar review estruturado
  • Se a sessão foi bem → ignorar completamente
  • NUNCA gera feedback sem validação do usuário
Usado por
orchestrator implementor researcher validator
Como o output chega ao agente
→ Retorna decision: "block" + reason com instrução completa sobre quando e como capturar feedback. O agente avalia a sessão e, se houve problemas, segue o Feedback Protocol da skill usada para criar o review em .vscode/skill-reviews/.
Exemplo de trigger: O agente usou a skill task-intent mas pulou a etapa de confirmar intent, e o usuário reclamou que implementou a coisa errada → hook bloqueia e pede ao agente para perguntar o que especificamente falhou e criar um review seguindo o protocolo da skill.
✅

stop-checklist

Stop

Lembra o implementor de completar seu checklist de qualidade antes de finalizar: rodar testes, produzir task map (se decisões foram tomadas) e verificar que o quality checklist está satisfeito.

Lógica detalhada
  • Sempre retorna block com 3 perguntas de checklist
  • 1) "Você rodou os testes?" — garante que testes foram executados
  • 2) "Produziu task map?" — se decisões foram tomadas, exige documentação
  • 3) "Quality checklist satisfeito?" — verifica conformidade final
  • Protege contra loop infinito via stop_hook_active
Usado por
implementor
Como o output chega ao agente
→ Retorna decision: "block" + reason: "Before finishing: 1) Did you run tests? 2) Did you produce a task map (if decisions were made)? 3) Is the quality checklist satisfied?" O agente avalia cada ponto antes de entregar.
Exemplo de trigger: O implementor termina uma refatoração significativa e tenta finalizar → hook bloqueia e pergunta se testes foram rodados e se um task map foi criado para documentar as decisões.
📝

subagent-audit

SubagentStart

Loga decisões de roteamento de sub-agentes. Sempre que um sub-agente é criado, registra o nome e timestamp em stderr para auditoria. Não interfere no fluxo — retorna JSON vazio para permitir a execução normalmente.

Lógica detalhada
  • Lê o campo agentName do JSON de input
  • Gera timestamp no formato yyyy-MM-dd HH:mm:ss
  • Escreve log para stderr: [timestamp] Subagent started: agentName
  • Retorna {} — não bloqueia, não injeta contexto
  • Usar stderr garante que o log não afeta o output do hook
Usado por
orchestrator
Como o output chega ao agente
→ Retorna {} (JSON vazio) — passthrough completo. O agente não recebe nenhuma instrução adicional. O valor é o log em stderr, útil para debugging e auditoria das decisões de roteamento do orchestrator.
Exemplo de trigger: O orchestrator decide delegar para o researcher → hook escreve [2026-03-16 14:30:22] Subagent started: researcher em stderr → sub-agente inicia normalmente.
📚

lesson-injector

PreToolUse

Injeta lições aprendidas relevantes no contexto do agente antes de cada prompt. Faz keyword matching bilíngue (pt-BR + en) no prompt do user para extrair tags, busca lições em ~/.copilot/lessons/ com frontmatter compatível, e retorna os resumos das top 5 lições por confidence. O agente pode então usar read_file para acessar detalhes completos.

Lógica detalhada
  • Lê o prompt do user via stdin JSON (chatMessage com fallbacks)
  • Keyword matching bilíngue: mapeia palavras-chave para tags (ex: "criar"/"new" → create, "corrigir"/"fix" → fix)
  • Se nenhuma tag matched → exit silencioso (não injeta nada)
  • Busca arquivos L*.md em ~/.copilot/lessons/, parseia frontmatter YAML via regex
  • Filtra por interseção de tags entre lições e tags matched do prompt
  • Ordena por confidence DESC, pega top 5
  • Injeta resumos (seção ## Resumo de cada lição) com limit de 500 chars
Usado por
orchestrator implementor researcher validator
Como o output chega ao agente
→ Retorna decision: "add" + content com formato: "Lições aprendidas relevantes (tags: X, Y): - [L003] resumo... (confidence: 0.8)". O agente lê o resumo e pode fazer read_file ~/.copilot/lessons/L003-*.md se precisar do registro completo.
Exemplo de trigger: User prompt contém "editar o hook de pre-commit" → tags matched: modify, hooks → hook encontra L005 com tags [modify, hooks] e confidence 0.8 → injeta resumo no contexto antes do agente processar o prompt.
🔍

verify-claims

Stop

Verifica referências a arquivos nas mensagens do assistant contra chamadas reais de ferramentas no transcript. Analisa apenas a interação atual (do último user.message em diante), evitando falsos positivos de menções antigas. Implementado em JavaScript — sem dependências externas.

Lógica detalhada
  • Lê o transcript JSONL da sessão via transcript_path do hook input
  • Escopo: encontra o último user.message no transcript e analisa só dali em diante
  • Coleta paths acessados por ferramentas: read_file, grep_search, file_search, semantic_search, run_in_terminal, list_dir, create_file, etc.
  • Extrai paths mencionados no content de assistant.message via regex (absolutos e relativos)
  • Compara: paths mencionados que não foram acessados por nenhuma ferramenta → unverified
  • Paths curtos (<6 chars) são ignorados. Matching usa endsWith bidirecional
  • Se todos os paths foram verificados → passthrough silencioso (exit 0)
  • Se há unverified → block com lista dos paths não verificados (máx. 10)
Usado por
orchestrator implementor researcher validator
Como o output chega ao agente
→ Retorna decision: "block" + reason listando os paths mencionados sem verificação prévia: "UNVERIFIED FILE REFERENCES — these paths were mentioned without prior tool verification: [lista]. Verify with tools (read_file, grep_search, list_dir) or mark as assumed." O agente deve verificar cada path com ferramentas ou marcar como assumed.
Exemplo de trigger: O agente menciona src/utils/helpers.ts na resposta sem ter chamado read_file, grep_search ou qualquer tool nesse arquivo → hook bloqueia e lista o path. O agente então usa read_file para verificar ou marca explicitamente como "assumed".
🚀

session-context

SessionStart

Injeta automaticamente contexto de git e projeto no início de cada sessão. Elimina a necessidade do agente rodar git status, git log ou verificar package.json manualmente — essas informações já estão disponíveis no contexto.

Lógica detalhada
Usado por
orchestrator implementor researcher validator
Como o output chega ao agente
→ Retorna hookSpecificOutput.additionalContext com resumo compacto: "Project: skill-kit@0.6.0 | Branch: main | HEAD: c7b6793 docs: update CHANGELOG | Uncommitted changes: 3 files" seguido dos commits recentes. Máximo 800 chars.
Exemplo de trigger: Uma nova sessão inicia em um repo git com package.json → hook injeta "Project: my-app@1.2.0 | Branch: feat/auth | HEAD: abc1234 feat: add login | Uncommitted changes: 2 files" no contexto. O agente já sabe o estado do repo sem precisar rodar comandos.
💾

context-save

PreCompact

Salva um snapshot do estado da sessão em disco antes da compactação de contexto. Isso permite que o agente recupere detalhes que seriam perdidos durante a compressão — arquivos editados, comandos executados, decisões tomadas e itens pendentes.

Lógica detalhada
Usado por
orchestrator implementor researcher validator
Como o output chega ao agente
→ Retorna hookSpecificOutput.additionalContext: "Session context snapshot saved to docs/maps/session-{id}-snapshot.md. If detail was lost during compaction, read this file to recover state." O agente pode ler o snapshot se precisar de detalhes após compactação.
Exemplo de trigger: O contexto da sessão atinge o limite e a plataforma dispara PreCompact → hook salva snapshot com 5 arquivos editados, 3 comandos, 2 decisões e 1 TODO em docs/maps/session-abc123-snapshot.md. Após compactação, o agente pode ler o arquivo para recuperar detalhes perdidos.