⏳ Ciclo de vida de uma sessao
Os 18 pontos onde Claude Code pode chamar um hook seu. Mapa visual completo.
Hooks que rodam antes da primeira mensagem do usuario. SessionStart, CurrentDir detection, env setup.
E aqui que voce injeta identidade e contexto. Ponto de maior alavancagem.
Session initialization, warm-up hooks.
Hook que dispara antes de cada mensagem do usuario ser enviada ao modelo.
E o hook mais poderoso para injecao dinamica: contexto por pergunta.
Per-turn injection, dynamic context.
Hooks antes e depois de cada tool call (Read, Write, Bash, etc.). Permite validar ou registrar.
Uteis para compliance (bloquear Bash perigoso) ou logging. Pouco usados para memoria.
Tool lifecycle, gate and observe.
PreCompact: antes do resumo. PostCompact: depois. A janela de sobrevivencia e no Pre.
Sem PreCompact, voce perde contexto critico toda vez que a sessao passa de ~170k tokens.
Survival hook, re-injection window.
Roda quando voce fecha a sessao. Usado para comprimir working memory e atualizar contexto.
SessionEnd e onde a promotion 3-strikes e a sumarizacao via Gemini acontecem.
End-of-life, post-session jobs.
Diagrama temporal com todos os 18 pontos marcados, agrupados por fase. Memorize as 5 fases.
Diagramado, voce escolhe o hook certo em segundos ao inves de ler documentacao.
Lifecycle map, mental model.
🗂️ Taxonomia: tabela de consulta rapida
Cada um dos 18 hooks com: quando dispara, payload, caso de uso tipico.
Dois hooks que delimitam a sessao. Os pilares para memoria persistente.
O par SessionStart/End e a base do "injeta no comeco, aprende no fim".
Bookend pattern, session boundaries.
UserPromptSubmit dispara antes do modelo responder. Stop apos cada resposta completa.
Injecao dinamica por turno usa UserPromptSubmit. Avaliacao pos-resposta usa Stop.
Turn-level, per-message.
Antes e depois de cada ferramenta executada. Permite validar, registrar ou bloquear.
Usados para compliance e observabilidade. Para memoria, raramente.
Tool gating, exec observability.
Hook que dispara na transicao para compactacao. Unico do seu grupo.
E a unica forma deterministica de sobreviver a compactacao.
Compaction gate.
Hooks de eventos laterais: notificacoes ao usuario, eventos de IDE, etc.
Raramente tocam em memoria, mas conhece-los evita confusao.
Peripheral hooks, IDE integration.
Tabela de 18 linhas com: nome, quando dispara, payload principal, output esperado, caso de uso.
Sera sua referencia daqui em diante. Marque ou imprima.
Reference table, cheat sheet.
⚙️ Schema do settings.json
Onde viver, qual a estrutura, permissoes e ordem de resolucao.
Tres niveis: /etc, ~/.claude, .claude no projeto. Merge com precedencia.
Coloque memoria pessoal em user, memoria de projeto em project.
Scope resolution, merge order.
Chave "hooks" com objeto por evento. Cada evento recebe array de matchers + commands.
Sem saber a estrutura, voce erra no primeiro try e perde tempo.
Matcher array, command spec.
Hooks rodam comandos bash. Deve haver lista de allow para comandos confiaveis, deny para perigosos.
Hook com comando inesperado pode ser prompt-injected. Permissoes mitigam.
Command allowlist, injection defense.
Matcher filtra: "so dispara se a tool e Bash", "so se prompt contem X". Hooks sem matcher rodam sempre.
Matchers evitam disparar hook toda hora, economizando tempo e tokens.
Conditional firing, matcher syntax.
Arquivo real com 3 hooks (SessionStart, PreCompact, UserPromptSubmit), cada linha comentada.
Copiar exemplo funcional e mais rapido que ler docs.
Reference config, annotated sample.
(1) path relativo que nao resolve, (2) env vars ausentes, (3) JSON com trailing comma, (4) permissoes faltando.
Conhecer as 4 armadilhas economiza horas de debug.
Debugging gotchas, path resolution.
📬 Payload: stdin, stdout, additionalContext
Como seu hook recebe dados e como responde. A interface que define o que e possivel.
Claude Code escreve JSON no stdin do comando. Campos comuns: session_id, cwd, hook_event_name, transcript_path.
Saber o schema do input define o que seu hook pode decidir.
Hook input, JSON schema.
Voce escreve JSON no stdout. Campos uteis: additionalContext (texto injetado), decision (allow/deny).
additionalContext e o mecanismo central de injecao de memoria.
Hook output, additionalContext.
0 = sucesso. 1 = erro recuperavel. 2 = bloqueio duro (cancela tool). Controle fino via exit + stderr.
Exit 2 e o unico jeito deterministico de bloquear acoes em hooks de tool.
Exit semantics, control flow.
String retornada nesse campo e anexada ao prompt do proximo turno. E assim que memoria entra.
90% da Trilha 4 e sobre o que colocar nesse campo e quando.
Context injection, prompt augmentation.
Hooks tem timeout (tipicamente 10-30s). Se estourar, Claude continua sem o output.
Scripts que chamam API (Gemini) precisam ter timeout proprio menor que o do hook.
Hook timeout, graceful fallback.
Hook e so um programa bash ou script. Teste com echo do JSON de input. Rapido, sem precisar rodar Claude.
Ciclo de feedback curto e a diferenca entre hook que funciona e hook que voce desiste.
Local testing, pipe input.
⚡ Hooks sincronos vs assincronos
Quando seu hook bloqueia Claude e quando nao. Decisao arquitetural que importa.
Hooks que retornam additionalContext sao sincronos. Claude bloqueia ate receber resposta.
Define que voce precisa de scripts rapidos nesses pontos.
Blocking hook, latency budget.
SessionEnd e alguns outros podem disparar processo em background. Claude nao espera.
Tarefas pesadas (chamada Gemini, indexacao) devem ser async no SessionEnd.
Async, background job.
Dentro do hook sincrono, voce roda o trabalho pesado em background com nohup ... & e retorna imediato.
Padrao resolve o melhor de dois mundos.
Decoupling, nohup.
Hook sincrono >500ms = experiencia ruim. >2s = Claude parece travado. Mantenha <100ms.
Otimizar sync vale mais que adicionar features.
Perf budget, UX impact.
Se duas sessoes escrevem no mesmo context.md, voce precisa de flock ou fila. Simples mas essencial.
Corrupcao de memoria e o pior bug pra diagnosticar.
File locking, race conditions.
SessionStart: sync (precisa do contexto). PreCompact: sync. SessionEnd: async (nao bloqueia proxima sessao).
Decidir certo desde o comeco evita refatorar depois.
Rule of thumb, hook discipline.
🐛 Depuracao e logging de hooks
Como saber se seu hook disparou, o que ele recebeu e o que retornou.
No inicio do hook: echo "$(date) $input" >> ~/.claude/hook.log.
Log simples resolve 90% dos "por que nao disparou?".
Append log, minimal trace.
Em outro terminal: tail -f ~/.claude/hook.log. Veja cada disparo em tempo real.
Feedback loop de 1 segundo para validar hooks.
Live tailing.
Use echo "info" >&2 para exibir debug no proprio Claude.
Feedback inline, sem trocar de janela.
stderr visibility.
Prepare um JSON de exemplo salvo em arquivo. Rode cat input.json | ./hook.sh antes de plugar no Claude.
Testa 10x mais rapido que via Claude Code.
Dev loop, mocked input.
Hook incrementa contador em arquivo por evento. Voce ve taxa e distribuicao ao longo do dia.
Metrica revela padrao inesperado (ex: PreCompact disparando mais do que voce esperava).
Event counting.
Lista: permission denied, script nao executavel, JSON invalido, path relativo, env var ausente, etc.
Ter checklist salva 80% do tempo de debug.
Runbook, common failures.