Automatizar ações com hooks

Configure seu primeiro hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\"" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

O que você pode automatizar

Receba notificações quando Claude precisa de entrada

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

Formatar código automaticamente após edições

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
          }
        ]
      }
    ]
  }
}

Bloquear edições em arquivos protegidos

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Re-injetar contexto após compactação

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Auditar mudanças de configuração

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

Recarregar ambiente quando diretório ou arquivos mudam

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

Aprovar automaticamente prompts de permissão específicos

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input}}}'"
          }
        ]
      }
    ]
  }
}

"command": "jq -c '{hookSpecificOutput: {hookEventName: \"PermissionRequest\", decision: {behavior: \"allow\", updatedInput: .tool_input, updatedPermissions: [{type: \"setMode\", mode: \"acceptEdits\", destination: \"session\"}]}}}'"

Como hooks funcionam

• "type": "http": POST dados de evento para uma URL. Consulte HTTP hooks.
• "type": "mcp_tool": chamar uma ferramenta em um servidor MCP configurado. Consulte MCP tool hooks.
• "type": "prompt": avaliação LLM de turno único. Consulte Prompt-based hooks.
• "type": "agent": verificação multi-turno com acesso a ferramentas. Agent hooks são experimentais e podem mudar. Consulte Agent-based hooks.

Combinar resultados de múltiplos hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

Ler entrada e retornar saída

Entrada do hook

• hook_event_name: o evento que acionou o hook
• tool_name: a ferramenta que Claude está prestes a usar
• tool_input: os argumentos que Claude passou para a ferramenta. Para Bash, seu campo command contém o comando shell.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

Saída do hook

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr se torna feedback do Claude
  exit 2 # exit 2 = bloquear a ação
fi

exit 0  # exit 0 = nenhuma decisão; o fluxo de permissão normal se aplica

• Exit 0: se você sair com 0 de um hook PreToolUse, a chamada de ferramenta ainda passa pelo fluxo de permissão normal, porque exit 0 não a aprova. Para hooks UserPromptSubmit, UserPromptExpansion, SessionStart e PostModelSwitch, Claude Code adiciona stdout que trata como texto simples ao contexto do Claude.
• Exit 2: escreva um motivo para stderr. Dependendo do evento, Claude o recebe como feedback para que possa se ajustar, o usuário o vê, ou nenhuma mensagem aparece, como com ConfigChange e Elicitation. Alguns eventos não podem ser bloqueados: para SessionStart e outros, exit 2 mostra stderr ao usuário e a execução continua. Consulte comportamento do código de saída 2 por evento para a lista completa.
• Qualquer outro código de saída: para as exceções por evento, como WorktreeCreate falhando em qualquer saída diferente de zero, consulte Saída do código de saída. Em outros eventos, a menos que o hook seja um cuja falha bloqueia a ação, encontre seu caso pelo que seu hook imprimiu em stdout:
  • Um objeto analisado que passa na validação de esquema: Claude Code ignora o código de saída, apenas o JSON decide o resultado, e o hook não é relatado como um erro.
  • Um objeto analisado que falha na validação de esquema, ou stdout que Claude Code tenta analisar como JSON mas que não é JSON válido: a ação prossegue como um erro não bloqueador. Verifique o aviso <hook name> hook error para a mensagem de validação ou análise.
  • Stdout que Claude Code trata como texto simples, ou stdout vazio: a ação prossegue como um erro não bloqueador. A transcrição mostra um aviso <hook name> hook error, depois a primeira linha de stderr prefixada com Failed with non-blocking status code:. Para capturar o stderr completo, ative debug logging com claude --debug ou executando /debug no meio da sessão.

Saída JSON estruturada

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• Leituras de caminhos de rede
• Ferramentas MCP marcadas requiresUserInteraction
• Chamadas a ferramentas que um app do Agent SDK marca como always_ask, a menos que o modo de permissão aprove a chamada
• Ferramentas de conector que sua organização definiu como ask em sessões onde essa configuração chega ao Claude Code Para o que "allow" faz no modo de planejamento, consulte Aprovações de hook no modo de planejamento.

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

Filtrar hooks com matchers

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

Filtrar por nome de ferramenta e argumentos com o campo if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

Configurar local do hook

Hooks baseados em prompt

• "ok": true: a ação prossegue
• "ok": false: o que acontece depende do evento:
  • Stop e SubagentStop: o reason é alimentado de volta ao Claude para que ele continue trabalhando, a menos que a resposta também defina "impossible": true para marcar a condição como uma que nunca pode ser satisfeita, caso em que Claude Code permite a parada e o turno termina
  • PreToolUse: a chamada de ferramenta é negada; por padrão o turno termina e o reason de negação aparece no chat como uma linha de aviso. Defina continueOnBlock: true no hook para, em vez disso, retornar o reason ao Claude como o erro da ferramenta, para que ele possa se ajustar e continuar
  • PostToolUse: por padrão o turno termina e o reason aparece no chat como uma linha de aviso. Defina continueOnBlock: true para alimentar o reason de volta ao Claude e continuar o turno em vez disso
  • PostToolBatch, UserPromptSubmit e UserPromptExpansion: o turno termina e o reason aparece no chat como uma linha de aviso

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

Hooks baseados em agente

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

• Status 2xx: para bloquear uma chamada de ferramenta, retorne os campos hookSpecificOutput apropriados no corpo.
• Qualquer outro status, ou se a requisição falhar: o Claude Code reporta um erro não bloqueante e permite que a ação continue, exceto quando o hook é um cuja falha bloqueia a ação. Para fazer com que um endpoint com falha bloqueie a ação, defina onFailure: "block" no hook.

Limitações e solução de problemas

Limitações

• Hooks de comando se comunicam apenas através de stdout, stderr e códigos de saída. Eles não podem disparar comandos / ou chamadas de ferramenta. Texto retornado via additionalContext é injetado como um lembrete do sistema que Claude lê como texto simples. HTTP hooks se comunicam através do corpo da resposta em vez disso.
• Os timeouts do hook variam por tipo. Substitua por hook com o campo timeout em segundos.
  • command, http, mcp_tool: 10 minutos. Claude Code reduz este padrão para 30 segundos para hooks UserPromptSubmit, PreModelSwitch e PostModelSwitch, e para 10 segundos para hooks MessageDisplay.
  • prompt: 30 segundos.
  • agent: 60 segundos.
  • Hooks SessionEnd de qualquer tipo compartilham um orçamento de 1,5 segundo. Se suas configurações definirem um timeout por hook mais longo, Claude Code aumenta o orçamento para corresponder, até 60 segundos.
• Hooks PostToolUse não podem desfazer ações já que a ferramenta já foi executada.
• Hooks PermissionRequest disparam quando Claude Code está prestes a pedir permissão a você, ou quando, caso contrário, negaria automaticamente uma chamada que não pode pedir confirmação. Em modo não interativo com a flag -p, eles ainda são executados fora do modo dontAsk, e uma chamada sobre a qual nenhum hook decide e que nada mais pode responder é negada.
• Hooks Stop disparam sempre que Claude termina de responder, não apenas na conclusão de tarefas. Eles não disparam em interrupções do usuário. Erros de API disparam StopFailure em vez disso.
• Quando múltiplos hooks PreToolUse retornam updatedInput para reescrever a entrada de uma ferramenta, Claude Code não mescla as reescritas nem garante com qual reescrita a ferramenta será executada. Evite ter mais de um hook reescrevendo a entrada da mesma ferramenta.

Hooks e modos de permissão

• O que ainda prevalece sobre "allow": um hook retornando "allow" não contorna regras de negação de configurações, e não pode suprimir o prompt para:
  • Leituras de caminhos de rede
  • Ferramentas MCP marcadas requiresUserInteraction
  • Chamadas a ferramentas que um app do Agent SDK marca como always_ask, a menos que o modo de permissão aprove a chamada
  • Ferramentas de conector que sua organização definiu como ask em sessões onde essa configuração chega ao Claude Code

• "deny" em todo modo de permissão: um hook que retorna permissionDecision: "deny" bloqueia a ferramenta mesmo em modo bypassPermissions ou com --dangerously-skip-permissions. Hooks PreToolUse disparam antes de qualquer verificação de modo de permissão, em cada modo de permissão, incluindo dontAsk. Isto permite que você aplique política que usuários não podem contornar mudando seu modo de permissão.

Hook não dispara

• Execute /hooks e confirme que o hook aparece sob o evento correto
• Para um hook no frontmatter de uma skill, invoque a skill ou peça a Claude que o faça, depois execute /hooks novamente. /hooks não lista hooks de uma skill que não foi invocada na sessão. Se /hooks ainda não listar o hook, verifique outras causas, como frontmatter que não foi analisado ou um dos limites em hooks de skills
• Verifique que o padrão do matcher corresponde ao nome da ferramenta exatamente. Matchers são sensíveis a maiúsculas
• Verifique que você está acionando o tipo de evento correto: PreToolUse dispara antes da execução da ferramenta, PostToolUse dispara depois. Um hook PermissionRequest dispara quando Claude Code está prestes a pedir permissão a você; veja as limitações para os casos não-interativos

Erro de hook na saída

• Seu script saiu com um código não-zero inesperadamente. Teste-o manualmente canalizando JSON de amostra:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Verifique o código de saída
  
• Se você vir “command not found”, use caminhos absolutos ou ${CLAUDE_PROJECT_DIR} para referenciar scripts. Para evitar quoting de shell completamente, adicione "args": [] para mudar para forma exec, que gera o script diretamente sem um shell
• Se você vir “jq: command not found”, instale jq ou use Python/Node.js para análise JSON
• Se a mensagem incluir blocking because Git Bash wasn't found, você está no Windows, Claude Code não encontrou o Git Bash, e o hook que falhou ou atingiu o timeout bloqueou a chamada de ferramenta. Veja Hooks com falha no Windows sem Git Bash para as correções
• Se o aviso mostra uma mensagem de validação JSON, a stdout do seu hook foi analisada como JSON mas falhou na validação de esquema. Se mostra uma mensagem de análise JSON, a stdout parecia um objeto JSON mas não era JSON válido. Ambos acontecem mesmo em saída 0. Para corrigir uma falha de análise, construa o payload com um codificador JSON como jq em vez de concatenação de string, para que aspas e barras invertidas dentro de valores sejam escapadas. A seção Saída de código de saída da referência cobre as combinações de código de saída e JSON
• Se o script não está executando em tudo, torne-o executável: chmod +x ./my-hook.sh

/hooks mostra nenhum hook configurado

• Edições de arquivo são normalmente capturadas automaticamente. Se não tiverem aparecido após alguns segundos, o observador de arquivo pode ter perdido a mudança: reinicie sua sessão para forçar um recarregamento.
• Verifique que seu JSON é válido: vírgulas finais e comentários não são permitidos
• Confirme que o arquivo de configuração está no local correto: .claude/settings.json para hooks de projeto, ~/.claude/settings.json para hooks globais
• Se o menu mostrar Only hooks from managed settings run here, sua organização definiu allowManagedHooksOnly. Hooks nos seus arquivos de configuração de usuário, de projeto e locais não são executados e não são listados

Stop hook atinge o limite de bloqueio

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Permitir que Claude pare
fi
# ... resto da lógica do seu hook

Hook JSON não tem efeito

• Saída extra antes do JSON: algo mais escreve para stdout primeiro, geralmente um echo incondicional no seu perfil de shell, então a saída não começa mais com {. Veja Saída do perfil de shell antes do JSON.
• Um campo no nível errado: compare a colocação de cada campo contra o formato saída JSON. Por exemplo, permissionDecision pertence dentro de hookSpecificOutput, não no nível superior. Veja Campos no nível errado.

Saída do perfil de shell antes do JSON

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# Em ~/.zshrc ou ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

Campos no nível errado

Verificar o que um hook fez

• Sucesso: você não vê nada, a menos que o JSON do hook exiba algo, como systemMessage ou feedback de Stop hook.
  • Para confirmar que o hook executou, verifique seu efeito, como um arquivo reformatado
• Erro de bloqueio: na maioria dos eventos você vê a mensagem que acompanhou o bloqueio, por exemplo Blocked: rm commands are not allowed. Em alguns eventos, como ConfigChange e Elicitation, você não vê nenhuma mensagem. Código de saída 2 explica de onde vem a mensagem.
• Erro de não-bloqueio: você vê um aviso <hook name> hook error com uma explicação breve, como a primeira linha de stderr após Failed with non-blocking status code:, ou uma mensagem de validação ou análise JSON. A ação prosseguiu.

Saiba mais

• Referência de Hooks: esquemas de eventos completos, formato de saída JSON, hooks assíncronos e hooks de ferramentas MCP
• Considerações de segurança: revise antes de implantar hooks em ambientes compartilhados ou de produção
• Exemplo de validador de comando Bash: implementação de referência completa