SSD Nodes Learn Hosting plans →
Guias Matt ConnorPor Matt Connor

Hooks do Claude Code: eventos, código 2 e segurança

Entenda onde configurar hooks do Claude Code, quais eventos são acionados e como o código de saída 2 bloqueia chamadas de ferramentas antes da execução.

O que é um hook do Claude Code

Hooks do Claude Code são comandos de shell que o Claude Code executa por conta própria em pontos fixos do seu ciclo de vida. Essa é a diferença fundamental entre um hook e um ficheiro de regras. Uma instrução em CLAUDE.md é um conselho, e o modelo pondera-a contra tudo o resto no seu contexto. Um hook é código, e executa independentemente de o modelo concordar ou não. Se o seu agente continua a ignorar o formatador sobre o qual o avisou duas vezes, não precisa de uma instrução mais firme. Precisa de um hook.

O mecanismo é simples. Regista um comando num ficheiro de definições sob um nome de evento. Quando esse evento é disparado, o Claude Code executa o seu comando e escreve os dados do evento na sua entrada padrão (stdin) como JSON (JavaScript object notation). O seu comando lê esses dados, realiza o seu trabalho e responde com um estado de saída. Uma saída 2 a partir de um hook PreToolUse cancela a chamada da ferramenta antes de esta ser executada, e tudo o que o seu script escreveu para a saída de erro padrão (stderr) é devolvido ao modelo como o motivo, a menos que o hook também imprima um JSON contendo uma decisão de bloqueio, cujo motivo tem precedência.

Os nomes dos eventos e os nomes dos campos aqui mencionados provêm da referência de hooks do Claude Code, verificada a 12 de novembro de 2026. Esta interface muda rapidamente, por isso verifique a referência para a sua própria versão antes de copiar JSON de qualquer publicação de blog, incluindo esta. Imprima o seu com claude --version.

Onde fica a configuração dos hooks

Um hook é um bloco JSON num ficheiro de definições. Seis localizações podem conter um hook, e o âmbito do ficheiro define o âmbito do hook.

  • ~/.claude/settings.json: todos os projetos na sua máquina, e apenas nela.
  • .claude/settings.json: um projeto, submetido no repositório, para que todos os utilizadores que o clonarem recebam o hook.
  • .claude/settings.local.json: um projeto, apenas na sua máquina.
  • Definições de política gerida: aplicadas a toda a organização e definidas por um administrador.
  • hooks/hooks.json dentro de um plugin, ativo enquanto esse plugin estiver ativado.
  • Frontmatter de uma skill ou de um subagente. Os hooks de uma skill continuam ativos durante o resto da sessão depois de a skill ser invocada, e os hooks de um subagente ficam ativos enquanto esse subagente estiver em execução.

As entradas de hooks destes ficheiros são combinadas, em vez de se substituírem. Um ficheiro de definições do projeto adiciona os seus hooks aos hooks das definições do utilizador, em vez de os substituir. Assim, um evento pode conter vários hooks provenientes de vários ficheiros. Definir "disableAllHooks": true desativa-os, com uma exceção: os hooks das definições de política gerida continuam a ser executados, exceto se essa definição também for aplicada nas definições geridas.

Execute /hooks dentro de uma sessão para listar todos os hooks atualmente registados, agrupados por evento, com o ficheiro de origem e o matcher de cada um. O menu é apenas de leitura, por isso altere um hook editando o ficheiro de definições. Normalmente, o monitor de ficheiros deteta a alteração sem ser necessário reiniciar.

Quais eventos de hooks existem no Claude Code

A referência de hooks lista trinta e três eventos, de SessionStart até SessionEnd, abrangendo compactação, subagentes, worktrees e ficheiros de configuração. No trabalho de administração de servidores, alguns deles são usados com frequência.

  • PreToolUse: antes da execução de uma chamada de ferramenta, exceto EndConversation. Este é o evento que pode bloquear a chamada.
  • PostToolUse: depois de uma chamada de ferramenta ser concluída com sucesso, exceto EndConversation. PostToolUseFailure é acionado quando a chamada falha. Portanto, um hook que tenha de observar todos os resultados precisa dos dois eventos.
  • PermissionRequest: quando uma chamada de ferramenta precisa de uma decisão de permissão. É nesse momento que seria apresentado o pedido de aprovação.
  • UserPromptSubmit: quando envia um prompt, antes de o Claude o processar. O stdout em texto simples de um hook concluído com sucesso é adicionado ao contexto do modelo.
  • SessionStart e SessionEnd: no início e no fim de cada sessão. SessionStart também é acionado depois da compactação, com o valor de matcher compact.
  • Stop: quando o Claude termina de responder. O evento ocorre uma vez por turno, não uma vez por tarefa concluída.

Nos eventos que suportam matchers, um grupo pode conter um matcher que determina quais ocorrências acionam o hook. Nos eventos de ferramentas, o matcher filtra pelo nome da ferramenta. Assim, "Edit|Write" é acionado em edições de ficheiros e em mais nenhuma operação. Os matchers distinguem maiúsculas de minúsculas. Um matcher vazio é acionado em todas as ocorrências. As ferramentas de um servidor MCP (model context protocol) usam nomes no formato mcp__<server>__<tool>. Portanto, um matcher com o valor "mcp__github__.*" captura as ferramentas de um servidor e ignora as restantes.

Os hooks Stop têm uma particularidade importante que deve conhecer antes de criar um. Um hook Stop que bloqueia envia o modelo de volta ao trabalho. Por predefinição, o Claude Code substitui o bloqueio seguinte depois de oito continuações consecutivas. A contagem é reposta sempre que o Claude chama uma ferramenta. Leia o campo stop_hook_active da entrada do hook e termine com o código 0 quando o valor for verdadeiro. Caso contrário, o hook pode continuar a enviar o Claude de volta ao trabalho.

O que um hook recebe em stdin

Quando o Claude está prestes a executar npm test, um hook PreToolUse em Bash lê estes dados em stdin:

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

Os campos de entrada comuns incluem session_id, cwd, transcript_path e hook_event_name; permission_mode não é enviado em todos os eventos. Os eventos de ferramentas adicionam tool_name, tool_input e tool_use_id. Os outros eventos têm os seus próprios campos: UserPromptSubmit recebe o texto prompt, e SessionStart recebe um source de startup, resume, clear, compact ou fork.

jq é a forma habitual de ler estes dados num script shell, e uma imagem de servidor mínima não o inclui. Instale-o primeiro com sudo apt install -y jq no Ubuntu e Debian.

O que o status de saída faz com a chamada de ferramenta em andamento

Existem três resultados.

  • Exit 0 indica sucesso, e todos os campos de decisão JSON válidos continuam a aplicar-se, incluindo bloqueio ou recusa. Em PreToolUse, exit 0 sem uma decisão não é uma aprovação, e o fluxo normal de permissões continua. Em UserPromptSubmit, UserPromptExpansion, SessionStart e PostModelSwitch, o stdout em texto simples é adicionado ao contexto do modelo. Na maioria dos outros eventos, o stdout é enviado apenas para o log de depuração.
  • Exit 2 bloqueia a ação nos eventos que podem ser bloqueados, incluindo PreToolUse, e o stderr torna-se a mensagem apresentada com o bloqueio, a menos que a saída JSON contenha uma decisão de bloqueio, cujo motivo tem precedência. Quem lê essa mensagem depende do evento. Em PreToolUse e Stop, o modelo vê-a como o motivo. Em UserPromptSubmit e PreModelSwitch, ela é apresentada a si e não é adicionada ao contexto do modelo. Em PostToolUse e PostToolUseFailure, que não podem ser bloqueados, o bloqueio é ignorado, embora o stderr continue a chegar ao modelo como feedback. Na maioria dos outros eventos que não podem ser bloqueados, o stderr é apresentado apenas a si ou ignorado. Em Stop, SubagentStop, TaskCompleted e no hook UserPromptSubmit de um plugin, exit 2 com stdout vazio e um erro de ficheiro inexistente no stderr é tratado como um erro que não bloqueia.
  • Qualquer outro código de saída com stdout em texto simples ou vazio é normalmente um erro que não bloqueia. A transcrição mostra uma notificação de erro do hook com a primeira linha do stderr depois do texto Failed with non-blocking status code:. Um JSON válido ainda pode decidir o resultado em eventos como PreToolUse, a menos que a falha do hook bloqueie a ação. WorktreeCreate falha com qualquer exit diferente de zero, e WorktreeRemove falha com um exit diferente de zero se o diretório ainda existir depois.

Para fazer mais do que bloquear ou permanecer silencioso, use exit 0 e escreva um objeto JSON no stdout. Um hook PreToolUse toma uma decisão com permissionDecision:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Database drops go through a migration, not through the agent."
  }
}

"allow" ignora o prompt interativo quando as regras de permissões e os requisitos de aprovação da ferramenta o permitem, "deny" cancela a chamada e envia o motivo ao modelo, e "ask" solicita confirmação. Escolha um estilo por hook. Misturar exit 2 com uma decisão JSON no stdout mantém o bloqueio, mesmo que o JSON indique "allow".

Quando vários hooks correspondem ao mesmo evento, são executados em paralelo, com os hooks de prompt e de agente limitados a doze execuções simultâneas. Um deny de um hook não interrompe os hooks irmãos, por isso um hook de registo ainda escreve a sua linha enquanto um hook de proteção recusa a mesma chamada. Para PreToolUse, o Claude Code combina então as respostas e mantém a mais restritiva, pela seguinte ordem: deny, defer, ask, allow.

Exemplo 1: bloquear um comando destrutivo antes da execução

Guarde isto como .claude/hooks/block-destructive.sh no seu projeto:

#!/bin/bash
# Deny a Bash tool call whose command matches a banned pattern.
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

for pattern in 'rm -rf /' 'mkfs' 'dd if=' 'DROP TABLE'; do
  if printf '%s' "$COMMAND" | grep -qiF -- "$pattern"; then
    echo "Blocked by policy: the command matches '$pattern'. A human runs this one." >&2
    exit 2
  fi
done

exit 0

Torne-o executável e, em seguida, registe-o em PreToolUse dentro de .claude/settings.json:

chmod +x .claude/hooks/block-destructive.sh
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh",
            "timeout": 10,
            "statusMessage": "Checking the command against policy"
          }
        ]
      }
    ]
  }
}

Teste o script manualmente antes de confiar nele, porque um hook que falha ao processar a própria entrada normalmente permite a operação quando onFailure não está definido. No Windows sem Git Bash, um hook de comandos PreToolUse ou PermissionRequest no formato shell que falhe pode, pelo contrário, bloquear a chamada da ferramenta:

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /var/lib/postgresql"}}' \
  | .claude/hooks/block-destructive.sh
echo $?

Deve ver a linha Blocked by policy: em stderr e um código de saída 2. Forneça um comando inofensivo, como ls -la, e não deve ver qualquer saída; o código de saída deve ser 0. Numa sessão, a chamada recusada aparece na transcrição com a sua mensagem como motivo, e o modelo lê essa mensagem e adapta-se.

Uma propriedade torna isto útil: os hooks PreToolUse são executados antes da verificação do modo de permissões, em todos os modos de permissões. Por isso, uma recusa mantém-se mesmo com bypassPermissions. É isso que torna um hook útil em conjunto com o modo automático do Claude Code e as respetivas definições de permissões, em que os pedidos de confirmação são reduzidos, mas o hook continua a ser executado.

Seja claro sobre o que isto oferece. A correspondência de padrões numa cadeia de comando é uma salvaguarda contra a execução descuidada por parte de um agente. Não é uma fronteira contra um agente que tente contorná-la, porque o mesmo comando pode ser escrito de uma forma que o seu grep não deteta. As regras obrigatórias devem estar no sistema de permissões e na conta sob a qual o processo é executado.

Exemplo 2: formatar e verificar após cada edição

PostToolUse com um matcher Edit|Write é executado depois de qualquer uma dessas ferramentas de edição de ficheiros concluir com sucesso. Guarde isto como .claude/hooks/after-edit.sh:

#!/bin/bash
# Format the edited file, then report lint failures back to the model.
INPUT=$(cat)
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
[ -z "$FILE" ] && exit 0

case "$FILE" in
  *.py)
    ruff format "$FILE" >/dev/null 2>&1
    if ! ruff check "$FILE" >&2; then
      exit 2
    fi
    ;;
  *.sh)
    if ! shellcheck "$FILE" >&2; then
      exit 2
    fi
    ;;
esac

exit 0
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/after-edit.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Peça ao Claude para adicionar uma função com indentação incorreta a um ficheiro Python e, em seguida, abra o ficheiro. O conteúdo aparece formatado. Essa é a confirmação de que o hook foi executado, porque um hook concluído com sucesso não mostra nada na conversa.

O exit 2 neste caso não desfaz nada. PostToolUse é executado depois de a ferramenta já ter concluído, por isso a edição fica guardada no disco de qualquer forma. O que o exit 2 proporciona é o envio do resultado de ruff check ao modelo como feedback, para que ele corrija o erro que acabou de introduzir em vez de prosseguir. Esta é a diferença entre uma falha de lint detetada no momento do commit e uma falha que o agente corrige no mesmo turno.

Aqui, há dois limites dos matchers que importam. Edit|Write não deteta ficheiros alterados por um comando shell, e o Claude escreve ficheiros através de Bash com frequência suficiente para que essa lacuna seja relevante. Para obter cobertura em cada chamada, faça também o match de Bash e altere o script para listar os ficheiros modificados com git status --porcelain. Para obter cobertura uma vez por turno, coloque a verificação num hook Stop.

Exemplo 3: registar cada chamada de ferramenta para auditoria

Um matcher vazio em PostToolUse é acionado em cada chamada de ferramenta concluída com sucesso, exceto EndConversation. Enviar o registo para o journal do sistema, em vez de para um ficheiro no diretório pessoal, não o torna inacessível à própria shell do agente: o acesso depende das permissões da conta. Os utilizadores podem ler os seus journals privados por utilizador, e o root e os membros de systemd-journal, adm ou wheel podem ler todos os ficheiros do journal:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{time: now|todate, session: .session_id, cwd: .cwd, tool: .tool_name, input: .tool_input}' | logger -t claude-code -p local0.info"
          }
        ]
      }
    ]
  }
}

Leia os registos com journalctl -t claude-code -o cat | tail -n 5. Com permissão para ler os registos, deverá ver uma linha JSON por cada chamada de ferramenta concluída com sucesso, exceto EndConversation, com a mais recente no fim. Se nada aparecer, verifique o acesso ao journal e se o hook foi executado; a secção de resolução de problemas abaixo explica como verificar o hook.

Adicione o mesmo bloco em PostToolUseFailure para registar as chamadas que falharam, porque PostToolUse só é acionado em caso de sucesso e um comando falhado é normalmente o mais importante. O motivo para usar logger em vez de acrescentar dados a um ficheiro no diretório pessoal é a propriedade: um hook é executado com o mesmo utilizador da shell do agente, por isso tudo o que esse utilizador pode alterar por anexação também pode truncar. O journal é escrito por systemd-journald; impedir a sua eliminação continua a depender dos privilégios da conta do agente.

Quanto tempo um hook pode executar

GráficoDefault hook timeout in seconds, by hook type and event
Os dados por trás deste gráfico
[
  {
    "label": "command, http or mcp_tool hook",
    "default_timeout_seconds": 600
  },
  {
    "label": "agent hook",
    "default_timeout_seconds": 60
  },
  {
    "label": "prompt hook",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on UserPromptSubmit, PreModelSwitch or PostModelSwitch",
    "default_timeout_seconds": 30
  },
  {
    "label": "command, http or mcp_tool on MessageDisplay",
    "default_timeout_seconds": 10
  },
  {
    "label": "any hook on SessionEnd",
    "default_timeout_seconds": 1.5
  }
]

Por padrão, um hook de comando tem 600 segundos para executar, ou seja, dez minutos. Alguns eventos reduzem esse tempo de forma significativa. Os hooks SessionEnd partilham um orçamento de 1.5 segundos entre todos, por isso a limpeza no fim da sessão tem de ser rápida. No entanto, definir um timeout mais longo para um hook nos ficheiros de configuração aumenta esse orçamento partilhado até ao mesmo valor, com um máximo de 60 segundos.

Um hook síncrono de comando, HTTP ou ferramenta MCP que atinge o tempo limite é cancelado e normalmente não produz nenhuma decisão. Em PreModelSwitch, atingir o tempo limite bloqueia a mudança. Num mecanismo de proteção PreToolUse, o tempo limite normalmente permite que a chamada da ferramenta prossiga para o fluxo normal de permissões, com a exceção do Windows descrita acima quando onFailure não está definido. Por esse motivo, mantenha os scripts de proteção pequenos. A partir da versão 2.1.295, pode inverter esse comportamento predefinido num hook command ou http com "onFailure": "block". Isso transforma um tempo limite, uma falha ou um código de saída inesperado num bloqueio. No entanto, não tem efeito em Stop, SubagentStop, TaskCompleted, TeammateIdle nem nos hooks de comando em segundo plano. Para operações lentas que não exigem uma resposta imediata, como enviar um log para outro local, defina "async": true. Nesse caso, o hook é executado em segundo plano sem atrasar a chamada da ferramenta.

Hooks, ficheiros de regras, skills e servidores MCP

Quatro coisas são frequentemente confundidas porque todas alteram o comportamento de um agente. Apenas uma deixa de ser uma sugestão.

Um ficheiro de regras (CLAUDE.md ou um ficheiro em .claude/rules/) é texto carregado no contexto do modelo. Orienta o comportamento, mas não impõe nada. Numa conversa longa, com um diff grande e um pedido novo do utilizador, uma das suas linhas pode ser ignorada. Esse é o mecanismo normal por trás de agentes que ignoram as instruções que escreveu.

Uma skill é uma pasta com instruções e scripts que o modelo carrega quando considera que a skill é relevante. Essa decisão é a finalidade de uma skill e também o seu limite: o modelo continua a decidir. Pode ver os dois lados numa skill como Ponytail, que orienta um agente para a menor alteração que funciona, porque ela define como uma tarefa completa deve ser abordada de uma forma que nenhum hook conseguiria, mas apenas enquanto o modelo decidir carregá-la.

Um servidor MCP (model context protocol) fornece ao modelo novas ferramentas para chamar. Amplia aquilo a que o agente pode aceder. Não faz com que o agente use essas ferramentas e é um processo separado que tem de operar, o que constitui uma tarefa própria: consulte como executar servidores MCP num VPS.

Um hook é o único dos quatro que é executado sem uma decisão do modelo. Use um ficheiro de regras para uma preferência e uma skill para um procedimento que o modelo deve seguir quando se aplicar. Use um hook para o passo que tem de acontecer sempre ou para aquilo que nunca pode acontecer. A comparação mais aprofundada, incluindo os casos em que uma skill é melhor do que um ficheiro de regras, está em a comparação entre skills, MCP e ficheiros de regras.

Um plugin é uma forma de empacotamento, não um quinto mecanismo. Agrupa hooks e skills numa única unidade instalável. É assim que uma equipa distribui a mesma proteção por todas as máquinas: consulte como funcionam os plugins do Claude Code.

A decisão de segurança num VPS partilhado

Um hook é código que o agente dispara, e é executado como o utilizador que iniciou o Claude Code. Herda as permissões de ficheiro e o ambiente desse utilizador. Num portátil, isto é uma questão de fluxo de trabalho. Num VPS onde um agente é executado sem supervisão, é uma questão de segurança com quatro partes práticas.

Um hook num repositório é código que não escreveu. .claude/settings.json é submetido (committed), portanto, clonar um repositório e iniciar uma sessão dentro dele pode registar hooks que vieram com o repositório. Numa sessão interativa, o Claude Code protege os hooks do projeto atrás da caixa de diálogo de confiança do espaço de trabalho para essa pasta, o que significa que aceitar a confiança é o momento em que decide executá-los. Leia primeiro o bloco hooks. Uma sessão claude -p ou SDK, que é como um agente sem supervisão é normalmente executado, nunca mostra essa caixa de diálogo e trata a pasta como confiável, pelo que os hooks do repositório são executados sem pedir autorização. Reveja os seus ficheiros .claude/ antes de criar scripts contra eles, ou execute com --settings '{"disableAllHooks": true}'.

Um hook vê a entrada completa da ferramenta. Um hook de auditoria que regista tool_input escreve cada argumento de cada comando num log, incluindo qualquer token que tenha ficado na linha de comandos. Esse log necessita então da mesma proteção que o segredo, o que faz parte do problema mais vasto de manter segredos fora do alcance de um agente de IA.

Um hook pode escrever no contexto do modelo. O stdout em texto simples de um hook SessionStart ou UserPromptSubmit bem-sucedido é adicionado à conversa. Um hook que canaliza texto do exterior, de um gestor de problemas ou de um ficheiro de log, está a entregar texto não confiável ao modelo como se o tivesse digitado você mesmo. Um hook que reencaminha uma nota de outra sessão do Claude Code no mesmo VPS está a fazer a mesma coisa, e a saída de um agente não tem mais direito à sua confiança do que a do gestor de problemas. Trate esse stdout como entrada em vez de saída.

O privilégio é o controlo real. Execute o agente como um utilizador dedicado sem privilégios, apenas com as regras sudo de que necessita. Uma negação PreToolUse vale a pena, e é concebida como um esforço máximo: a referência diz o mesmo sobre o filtro if e recomenda a utilização do sistema de permissões quando necessita de uma negação rígida. As regras de permissão e a conta sob a qual o processo é executado são as partes que resistem sob pressão.

Uma propriedade mantém-se em todos os modos de permissão. Os hooks PreToolUse disparam antes da verificação do modo de permissão em todos os modos, pelo que um hook que devolve deny bloqueia a ferramenta mesmo sob bypassPermissions. Os hooks podem tornar mais rigoroso o que as regras de permissão permitem. Não podem torná-lo mais permissivo. A exceção é um mod. Numa máquina sem definições geridas e sem ficheiro managed-mcp.json, numa sessão que não está autenticada através de /login num plano Team ou Enterprise, um mod instalado que lida com tool.check pode aprovar uma chamada que o seu hook PreToolUse bloqueou. Com definições geridas, um ficheiro managed-mcp.json, ou uma credencial /login de Team ou Enterprise para a sessão, uma chamada que um hook PreToolUse bloqueou permanece bloqueada por predefinição, independentemente do ficheiro de definições de onde o hook provém. Uma sessão que é executada com uma chave de API ou um CLAUDE_CODE_OAUTH_TOKEN de longa duração, que é como muitos servidores a executam, conta como não autenticada mesmo quando um login está armazenado. Verifique o que os mods do Claude Code podem alterar antes de instalar um num servidor.

Por que meu hook não está sendo executado?

Siga estas etapas pela ordem. Cada etapa identifica o sintoma que você verá.

  • Execute /hooks e verifique se o hook aparece no evento esperado. Um hook ausente no menu normalmente indica um erro de sintaxe JSON no ficheiro de configurações, porque vírgulas finais e comentários não são permitidos, ou que o ficheiro não está numa das seis localizações anteriores.
  • Compare o matcher exatamente com o nome da ferramenta. Os matchers diferenciam maiúsculas de minúsculas, portanto "bash" nunca corresponde à ferramenta Bash.
  • Execute o script manualmente com dados de entrada de exemplo, como no exemplo 1 anterior. Um código de saída inesperado indica um erro no script; verifique também o stdout, porque um JSON válido ainda pode fornecer uma decisão em eventos como PreToolUse.
  • Uma mensagem com o texto jq: command not found significa que jq não está disponível nessa máquina. Um command not found para o seu próprio script significa que o caminho não foi resolvido; use ${CLAUDE_PROJECT_DIR} ou um caminho absoluto. Se o script nunca for executado, provavelmente não tem permissão de execução.
  • O hook imprime JSON válido e nada acontece. No macOS e no Linux, um hook em formato shell é executado através de sh -c numa shell não interativa, mas algumas configurações ainda carregam o seu perfil, como BASH_ENV apontando para ~/.bashrc. Se esse perfil imprimir um banner, o banner será acrescentado ao seu JSON. O stdout deixa de começar com {, portanto Claude Code interpreta todo o conteúdo como texto simples e ignora a decisão. Como o hook terminou com o código 0, a transcrição não mostra nenhum erro. Na maioria dos eventos, esse texto é enviado apenas para o log de depuração. Nos eventos UserPromptSubmit, UserPromptExpansion, SessionStart e PostModelSwitch, ele é acrescentado ao contexto do modelo, incluindo o banner. Envolva qualquer echo no seu perfil para que seja executado apenas em shells interativas.
  • Se o problema persistir, inicie a sessão com claude --debug-file /tmp/claude.log e execute tail -f /tmp/claude.log num segundo terminal. O log de depuração regista quais hooks corresponderam, o código de saída devolvido por cada um e tudo o que escreveram no stdout e no stderr.

FAQ

Qual é a diferença entre um hook do Claude Code e uma instrução CLAUDE.md?

Uma instrução CLAUDE.md é texto no contexto do modelo. Por isso, compete pela atenção com a conversa e com o pedido atual, e o modelo pode ponderá-la em relação a esses elementos. Um hook é um comando de shell que o Claude Code executa num ponto fixo do seu ciclo de vida. Por isso, é executado em todas as ocorrências do respetivo evento, independentemente da decisão do modelo. Use uma instrução para expressar uma preferência. Use um hook para uma etapa que tem de ocorrer sempre ou para uma ação que nunca pode ocorrer.

Como impeço o Claude Code de executar um comando de shell específico?

Registe um hook PreToolUse com um matcher Bash que leia o comando de .tool_input.command, escreva o motivo em stderr e termine com o código 2. O Claude Code cancela a chamada e mostra o seu motivo ao modelo. Isto acontece antes da verificação do modo de permissões, portanto a negação mantém-se mesmo no modo bypassPermissions. A correspondência baseada numa cadeia de comandos é uma proteção, não uma fronteira de segurança, porque o mesmo comando pode ser escrito de uma forma que o padrão não deteta. Por isso, complemente-a com regras de permissões e com uma conta sem privilégios.

O meu hook imprime JSON válido, mas nada acontece. Porquê?

Verifique se o seu perfil de shell imprime texto antes do JSON. No macOS e no Linux, um hook sem um campo args é executado através de sh -c. Em configurações que ainda carregam o seu perfil, como BASH_ENV apontar para ~/.bashrc, um perfil que imprime um banner coloca esse texto em stdout antes do JSON. Como a saída já não começa por {, o Claude Code trata tudo como texto simples e ignora a decisão. Como o hook terminou com o código 0, o transcript não mostra nenhum erro. Proteja qualquer echo no seu perfil com um teste de shell interativo. Depois, confirme a correção lendo o log de depuração a partir de claude --debug-file /tmp/claude.log.

É seguro executar hooks do Claude Code num servidor partilhado?

Os hooks são executados com o utilizador que iniciou o Claude Code e com as permissões de ficheiros desse utilizador. Por isso, um hook pode fazer tudo o que essa conta puder fazer. Duas práticas cobrem a maior parte do risco: execute o agente com uma conta dedicada sem privilégios e com uma política sudo restrita; e leia o bloco hooks de qualquer repositório antes de aceitar a caixa de diálogo de confiança da respetiva área de trabalho ou de executar claude -p nesse repositório, porque os hooks do projeto são incluídos em .claude/settings.json e o modo -p nunca mostra essa caixa de diálogo. Defina "disableAllHooks": true no seu ficheiro de definições para desativar os hooks, exceto os hooks geridos que exigem essa definição ao nível gerido. Uma definição de projeto false pode substituir uma definição de utilizador true.

Este artigo foi útil?