Modulo 5.8 Hooks System - Claude Code Deep Dive

1

📋 All 27 Hook Events

Lifecycle

SessionStart, SessionEnd, Setup, Stop, StopFailure

Tool Execution

PreToolUse, PostToolUse, PostToolUseFailure

Agent/Subagent

SubagentStart, SubagentStop

Compaction

PreCompact, PostCompact

Permission/Policy

PermissionRequest, PermissionDenied, UserPromptSubmit, ConfigChange, InstructionsLoaded

Filesystem/Multi-Agent

CwdChanged, FileChanged, WorktreeCreate/Remove, Notification, TeammateIdle, TaskCreated/Completed, Elicitation/Result

2

🚦 Exit Code Semantics

Exit code 2 e o codigo universal "bloqueia e informa o modelo". Todos os outros non-zero sao ruido visivel apenas para o usuario. StopFailure e a unica excecao -- ignora todos os exit codes.

Evento	Exit 0	Exit 2	Outro
PreToolUse	Silencioso, tool prossegue	Tool BLOQUEADA	stderr ao user
PostToolUse	stdout em transcript	stderr ao modelo	stderr ao user
Stop	Sessao conclui	Conversa CONTINUA	Sessao conclui
UserPromptSubmit	stdout ao Claude	BLOQUEIA, apaga prompt	stderr ao user
SessionStart	stdout ao Claude	Ignorado	stderr ao user

3

🔧 5 Hook Command Types

command -- Shell subprocess. Recebe hook input como JSON no stdin. Opcoes: if, timeout, once, async, asyncRewake, shell.

prompt -- Chamada LLM unica. Modelo responde com {"ok": true/false, "reason": "..."}. Schema JSON forcado.

agent -- Sub-agente multi-turn (ate 50 turns) com acesso a todas as tools. Retorna via StructuredOutput tool.

http -- POST JSON para URL. Headers com interpolacao de env vars. SSRF guard bloqueia IPs privados.

function -- TypeScript callback in-process. Session-only, nao persistivel. Usado internamente.

4

📚 Config Sources & Priority

#	Fonte	Escopo
1	userSettings	Todos os projetos
2	projectSettings	Todos neste repo
3	localSettings	Minha maquina + este projeto
4	policySettings	Enterprise admin (MDM, read-only)
5	pluginHook	Plugin-installed
6	sessionHook	Sessao atual (in-memory)

allowManagedHooksOnly -- quando true em managed settings, APENAS managed hooks rodam. disableAllHooks em policy desabilita TUDO, incluindo managed hooks.

5

⏱️ Async & asyncRewake

Quando async: true, o hook e lancado mas Claude nao espera. Com asyncRewake: true, o hook roda em background mas o main loop acorda o modelo se o processo sai com code 2.

O registry rastreia hooks pendentes por processId. Quando o main loop faz poll via checkForAsyncHookResponses(), hooks completados sao finalizados.

6

🛡️ HTTP Hooks Security

Modelo de seguranca em tres camadas:

URL allowlist -- allowedHttpHookUrls em settings, glob patterns
Env var allowlist -- apenas variaveis listadas em allowedEnvVars sao interpoladas em headers
SSRF guard -- bloqueia IPs privados (10.x, 172.16-31.x, 192.168.x, 169.254.x). Loopback (127.x) permitido

7

🎯 Real-world Patterns

Lint-on-write (PreToolUse)

Exit 2 bloqueia a escrita e informa Claude para reconsiderar.

Session context injection (SessionStart)

stdout no exit 0 e mostrado ao Claude como contexto antes do primeiro prompt.

Stop verification (agent hook)

Sub-agente verifica implementacao inclui testes. Se {"ok": false}, sessao continua.

.envrc auto-load (CwdChanged)

Escreve exports em CLAUDE_ENV_FILE para injetar env vars em BashTool.

📋 Resumo do Modulo

✅27 hook events definidos em HOOK_EVENTS. Exit code 2 e o universal "block and tell the model"

✅5 tipos formam hierarquia de poder vs simplicidade: command -> prompt -> agent -> http -> function

✅6 fontes de config, um merge. Policy tem poderes especiais: allowManagedHooksOnly e disableAllHooks

✅HTTP hooks tem seguranca em 3 camadas: URL allowlist, env var allowlist e SSRF guard

✅asyncRewake permite que hooks background interrompam a proxima resposta do modelo via exit code 2