## Introdução
Você configurou o Claude Code no seu CI/CD. GitHub Actions roda, agent executa, testes passam, deploy sobe. Tudo automático. Ninguém aprova nada.
Até o dia que o agent decide refatorar a tabela de usuários em produção. Ou faz push forçado na main. Ou deleta um serviço que ele achou desnecessário. E ninguém viu. Ninguém aprovou. Ninguém parou.
Isso não é ficção. 88% das organizações já tiveram incidentes confirmados ou suspeitos com AI agents em 2026, segundo a Gravitee. A Microsoft lançou o Agent Governance Toolkit na semana passada — 02 de abril — especificamente para endereçar o problema de agents que executam sem aprovação humana. E o Gartner projeta que mais de 40% dos projetos com agentic AI serão cancelados até 2027 por falta de governance.
O Claude Code resolveu isso com uma linha de configuração. Desde a versão 2.1.89, existe um valor chamado `defer` nos PreToolUse hooks que pausa qualquer pipeline headless no exato momento em que você precisa de um humano na jogada.
## O Que É o `defer` em PreToolUse Hooks
O sistema de hooks do Claude Code intercepta ações antes e depois da execução. O PreToolUse dispara ANTES de qualquer tool call — Bash, Edit, Read, Write, qualquer uma.
Até a versão 2.1.88, as opções de `permissionDecision` eram três:
| Valor | O que faz |
|——-|———–|
| `allow` | Libera a tool call sem perguntar |
| `deny` | Bloqueia a tool call |
| `ask` | Pede confirmação ao usuário |
O problema: `ask` só funciona em sessões interativas (terminal aberto, humano na frente). Em `-p` mode (headless, CI/CD, SDK), não tem humano. O pipeline trava esperando input que nunca vem, ou roda em auto mode sem perguntar nada.
A versão 2.1.89 adicionou o quarto valor:
| Valor | O que faz |
|——-|———–|
| `defer` | Pausa a sessão, exporta payload JSON, sai com `stop_reason: “tool_deferred”` |
O `defer` é a ponte entre automação total e controle humano. O pipeline para. Exporta exatamente o que o agent queria fazer. Espera. Retoma quando o humano aprova.
## Como Funciona na Prática
O fluxo tem 5 etapas:
**1. Pipeline roda em modo headless**
“`bash
claude -p “Analisa o PR #247 e faz deploy se os testes passarem” \
–allowedTools “Bash,Read,Edit” \
–output-format json
“`
**2. Claude decide chamar uma tool (ex: Bash com `git push`)**
O PreToolUse hook dispara. Seu script recebe o JSON com o nome da tool e os parâmetros.
**3. Hook retorna `defer`**
“`bash
#!/bin/bash
INPUT=$(cat)
TOOL_NAME=$(echo “$INPUT” | jq -r ‘.tool_name’)
TOOL_INPUT=$(echo “$INPUT” | jq -r ‘.tool_input’)
# Se for operação de risco, pausa
if echo “$TOOL_INPUT” | grep -qE ‘(git push|deploy|drop table|rm -rf)’; then
jq -n ‘{
hookSpecificOutput: {
hookEventName: “PreToolUse”,
permissionDecision: “defer”
}
}’
exit 0
fi
# Senão, libera
jq -n ‘{
hookSpecificOutput: {
hookEventName: “PreToolUse”,
permissionDecision: “allow”
}
}’
“`
**4. Processo sai com payload `deferred_tool_use`**
“`json
{
“type”: “result”,
“subtype”: “success”,
“stop_reason”: “tool_deferred”,
“session_id”: “abc123”,
“deferred_tool_use”: {
“id”: “toolu_01abc”,
“name”: “Bash”,
“input”: {
“command”: “git push origin main”
}
}
}
“`
O payload carrega tudo: qual tool, quais parâmetros, qual session. Seu sistema externo (Slack bot, dashboard, email, webhook) recebe isso e apresenta para aprovação humana.
**5. Humano aprova → pipeline retoma**
“`bash
claude -p –resume abc123 –permission-mode auto
“`
O mesmo hook dispara novamente. Desta vez, seu script verifica que a aprovação existe e retorna `allow`. O pipeline continua de onde parou.
## Por Que Isso Importa Para Sua Software House
Na minha experiência com 300+ software houses, vejo dois extremos:
**Extremo 1: Tudo manual.** Dev roda Claude Code no terminal, aprova cada ação, supervisiona cada tool call. Seguro? Sim. Escalável? Não. Produtivo? Nem um pouco. É o equivalente a ter um piloto automático e segurar o volante o tempo todo.
**Extremo 2: Tudo autônomo.** Claude Code roda em `-p` com `–allowedTools “Bash,Read,Edit,Write”`. Sem hooks, sem restrição. O agent faz o que quiser. Rápido? Sim. Até quebrar produção.
70% das organizações rodam o modelo “AI recomenda, humano aprova” — nem manual total, nem autônomo total. Mas até agora, implementar isso no Claude Code exigia gambiarra: wrapper scripts, filas externas, polling em loops. Nada nativo.
`defer` resolve isso de forma built-in. O hook faz parte do runtime do Claude Code. Não é um plugin. Não é um MCP server. É o próprio sistema de permissões fazendo o que deveria fazer desde o início: pausar quando o risco justifica.
### O custo de NÃO ter human-in-the-loop
Os números são claros:
– **AI agents falham 70% das vezes** em tarefas multi-step em simulações (Elementum AI)
– **95% dos sistemas enterprise de AI generativa** não chegam a produção — falham na avaliação
– **40%+ dos projetos agentic AI** serão cancelados até 2027 por falta de governance (Gartner)
– **Shadow AI breaches custam US$4.63M** em média — US$670K a mais que breaches padrão (IBM 2025)
– **88% das organizações** já tiveram incidentes com AI agents (Gravitee 2026)
Para uma software house com 20 devs rodando Claude Code em CI/CD sem nenhum checkpoint:
– 20 pipelines × 10 deploys/semana = 200 ações sem aprovação
– 1 incidente grave a cada 50 deploys não supervisionados (2% failure rate é otimista)
– 4 incidentes/mês × custo médio de rollback + investigação + downtime
– Sem contar o risco regulatório: EU AI Act (agosto 2026) e Colorado AI Act (junho 2026) exigem HITL documentado para sistemas de alto risco
### O padrão que a indústria está adotando
A Microsoft não lançou o Agent Governance Toolkit por acidente no dia 02 de abril. São 7 pacotes, 5 linguagens, integração com LangChain, CrewAI, Google ADK. O componente central? **Approval workflows com quorum logic** — exatamente o padrão que `defer` implementa nativamente no Claude Code.
A diferença: o toolkit da Microsoft é um sistema externo que você precisa integrar. `defer` já está dentro do Claude Code. Uma linha no hook.
O MIT Sloan Management Review chamou isso de modelo “delegate, review and own”: agents executam o primeiro passo, engenheiros revisam outputs, ownership fica com humanos. O `defer` é exatamente o “review” nesse modelo.
## Detalhes Técnicos Que Você Precisa Saber
### Restrições
1. **Só funciona em `-p` mode** (headless/SDK). Em sessões interativas, `defer` é ignorado com warning
2. **Single tool call por turno**: se Claude faz várias tool calls simultâneas, `defer` é ignorado
3. **Sem timeout**: a sessão fica em disco indefinidamente até ser retomada
4. **Permission mode no resume**: `–resume` NÃO restaura o permission mode da sessão original. Passe o mesmo `–permission-mode` no resume
### Use case primário: `AskUserQuestion`
O caso mais natural é interceptar a tool `AskUserQuestion` — que é como o Claude pede input ao usuário. Em headless, essa tool normalmente trava. Com `defer`:
1. Claude quer perguntar algo (“qual framework usar?”)
2. Hook retorna `defer`
3. Payload exporta a pergunta com opções
4. Sua UI/Slack/dashboard mostra a pergunta
5. Usuário responde
6. Resume com `updatedInput` contendo a resposta
“`json
{
“hookSpecificOutput”: {
“hookEventName”: “PreToolUse”,
“permissionDecision”: “allow”,
“updatedInput”: {
“questions”: [
{
“question”: “Qual framework?”,
“options”: [{“label”: “React”}, {“label”: “Vue”}]
}
],
“answers”: {
“Qual framework?”: “React”
}
}
}
}
“`
### Cenário enterprise: approval gate para deploys
O cenário mais poderoso para SHs:
“`bash
#!/bin/bash
# hook-deploy-approval.sh
INPUT=$(cat)
TOOL_INPUT=$(echo “$INPUT” | jq -r ‘.tool_input.command // empty’)
SESSION_ID=$(echo “$INPUT” | jq -r ‘.session_id’)
# Detectar operações de deploy/produção
if echo “$TOOL_INPUT” | grep -qiE ‘(deploy|push.*main|push.*prod|migration|drop|truncate)’; then
# Notificar Slack
curl -s -X POST “$SLACK_WEBHOOK” \
-d “{\”text\”: \”🚨 Claude Code quer executar: $TOOL_INPUT\\nSession: $SESSION_ID\\nAprove com: /approve $SESSION_ID\”}”
# Defer — pausa pipeline
jq -n ‘{
hookSpecificOutput: {
hookEventName: “PreToolUse”,
permissionDecision: “defer”
}
}’
exit 0
fi
# Operações seguras passam
jq -n ‘{
hookSpecificOutput: {
hookEventName: “PreToolUse”,
permissionDecision: “allow”
}
}’
“`
Configuração no `.claude/settings.json`:
“`json
{
“hooks”: {
“PreToolUse”: [
{
“matcher”: “Bash”,
“hooks”: [
{
“type”: “command”,
“command”: “/opt/hooks/hook-deploy-approval.sh”
}
]
}
]
}
}
“`
### Erro handling
Se a tool que foi deferida não está mais disponível quando você retoma (ex: MCP server desconectado), o processo sai com:
“`json
{
“stop_reason”: “tool_deferred_unavailable”,
“is_error”: true
}
“`
O payload `deferred_tool_use` ainda é incluído para diagnóstico.
## Stack de Governance Completa no Claude Code
O `defer` não opera sozinho. Ele é uma peça de um sistema maior:
| Camada | Mecanismo | O que faz |
|——–|———–|———–|
| **Criação** | TaskCreated hook | Valida tasks antes de criar em agent teams |
| **Permissão** | PreToolUse hooks | Allow / deny / ask / **defer** tool calls |
| **Retry** | PermissionDenied hook | Retenta tool calls negadas pelo classifier |
| **Execução** | PostToolUse hooks | Audita após execução |
| **Sandbox** | sandbox.failIfUnavailable | Fail-closed se sandbox indisponível |
| **Skills** | disableSkillShellExecution | Bloqueia shell inline em skills |
| **Startup** | forceRemoteSettingsRefresh | Bloqueia CLI até policies carregarem |
| **Enterprise** | managed-settings.d | Distribui policies centralizadas |
O `defer` é a peça que faltava no meio: entre “bloquear” (deny) e “liberar” (allow) existia um vazio para “perguntar a alguém antes de decidir”. Agora não existe mais.
## O Que Eu Penso
Na minha experiência mentorando 300+ software houses, a maioria está num dos dois extremos: ou não usa Claude Code em CI/CD (perdendo automação), ou usa sem nenhum controle (arriscando produção).
O `defer` é o tipo de feature que não aparece em destaque no changelog — veio como “Other wins” no whats-new da semana 14 — mas muda fundamentalmente o que é possível. É a diferença entre “meu pipeline é autônomo” e “meu pipeline é autônomo COM pontos de controle”.
E com EU AI Act entrando em vigor em agosto de 2026 para sistemas de alto risco, ter human-in-the-loop documentado não é mais nice-to-have. É compliance. O `defer` gera o payload JSON que prova que houve pausa, que houve aprovação, que houve retomada. É audit trail built-in.
Se você tem 5+ devs usando Claude Code em pipelines automatizados e ainda não tem nenhum checkpoint de aprovação humana, comece pelo `defer`. Uma linha no hook. Um script de notificação. Um `/approve` no Slack. Pronto: pipeline governado.
## Conclusão
O `defer` no PreToolUse hooks do Claude Code transforma pipelines 100% autônomos em pipelines com human-in-the-loop nativo. Sem ferramentas externas, sem integrações complexas, sem trocar de plataforma.
Pausa. Exporta. Notifica. Espera. Retoma.
Cinco etapas. Uma linha de configuração. Zero dependência externa.
Se sua software house roda AI agents em produção sem nenhum ponto de aprovação humana, a pergunta não é SE vai dar problema. É QUANDO.
Sou Thulio, mentoro 300+ SHs desde 2016.
