Hooks e permissions

Customize o comportamento do Claude e defina limites de segurança

⏱ Estim. ~6 min

01 · Ler

Hooks deixam você rodar código próprio em momentos específicos do fluxo do Claude. Antes de uma ferramenta rodar? Depois de uma edição? No começo da session? Você pode interceptar esses eventos e adicionar sua lógica — formatação automática, checagens de segurança, notificações, validação customizada.

Permissions controlam o que o Claude tem permissão para fazer. Por padrão, o Claude pergunta antes de rodar comandos ou editar arquivos. Mas você pode pré-aprovar ações seguras (como npm test), bloquear as perigosas (como git push --force) e deixar o Claude rodar mais rápido em tarefas de rotina, mantendo segurança nas arriscadas.

💡 Imagine assimHooks são como pontos de inspeção numa linha de produção. Em cada posto, um inspetor (seu script) checa o trabalho, deixa passar (exit 0) ou devolve (exit 2). Permissions são como um sistema de crachá de segurança — algumas portas estão sempre abertas (ler arquivos), outras exigem um swipe (comandos), outras ficam trancadas (operações perigosas).

Pontos-chave

Hooks: rodam seu código em momentos específicos do fluxo do Claude
Permissions: controlam o que o Claude pode e não pode fazer
Hooks interceptam eventos; permissions definem as regras gerais
Juntos, eles customizam e protegem o Claude para o seu fluxo

02 · Ler

Os eventos de hook mais úteis: - PreToolUse — dispara antes de o Claude usar uma ferramenta (Read, Edit, Bash etc.). Você pode inspecionar o que ele vai fazer e bloquear. - PostToolUse — dispara depois que uma ferramenta tem sucesso. Ótimo para formatar arquivos editados automaticamente ou registrar mudanças. - SessionStart — dispara quando uma session começa. Use para injetar lembretes de contexto, especialmente após compactação. - Notification — dispara quando o Claude precisa da sua atenção. Bom para notificações de desktop. - Stop — dispara quando o Claude termina de responder.

Hooks se comunicam por exit code: exit 0 quer dizer permita a ação, exit 2 quer dizer bloqueie (a mensagem de erro no seu stderr vira o feedback do Claude).

Pontos-chave

PreToolUse: inspecionar e opcionalmente bloquear antes de a ferramenta rodar
PostToolUse: reagir depois do sucesso da ferramenta (formatar, registrar)
SessionStart: injetar contexto no início da session ou após compactação
Exit 0 = permita, Exit 2 = bloqueie (stderr vira feedback)

03 · Exemplo de código

Abaixo está um hook PostToolUse que formata arquivos automaticamente depois que o Claude edita. Mora no .claude/settings.json do seu projeto.

.claude/settings.json — hook de auto-formatação

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

O campo matcher usa regex para casar nomes de ferramentas — Edit|Write quer dizer que esse hook dispara depois de qualquer chamada das ferramentas Edit ou Write. O comando recebe JSON via stdin com os detalhes da chamada, extrai o caminho do arquivo e roda o Prettier nele. Todo arquivo que o Claude edita é formatado automaticamente.

04 · Exemplo de código

Abaixo está um hook PreToolUse que bloqueia comandos Bash perigosos.

.claude/hooks/protect.sh

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

if [[ "$CMD" =~ "rm -rf" ]]; then
  echo "Blocked: rm -rf is not allowed" >&2
  exit 2  # Block the action
fi

exit 0  # Allow everything else

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/protect.sh"
      }]
    }]
  }
}

Esse hook intercepta todo comando Bash que o Claude tenta rodar. Ele lê o comando do stdin (como JSON), checa por 'rm -rf' e bloqueia com exit code 2. A mensagem de erro no stderr diz ao Claude por que foi bloqueado, e o Claude aceita a restrição.

05 · Ler

Permissions dão regras gerais de allow/deny sem precisar escrever scripts. Elas usam wildcards para casamento flexível.

Regras allow pré-aprovam ações para o Claude não precisar perguntar: - Bash(npm run ) — qualquer script npm - Bash(git commit ) — fazer commit de mudanças - Read(*.env) — ler arquivos .env

Regras deny bloqueiam ações completamente: - Bash(git push --force ) — sem force push - Edit(package-lock.json) — não toque no lockfile - Bash(rm -rf ) — sem deleções recursivas

Regras deny sempre ganham das regras allow. A configuração é checada do mais específico ao menos específico: project local > project > user.

Pontos-chave

Regras allow: pré-aprovam ações seguras (sem prompt de permission)
Regras deny: bloqueiam ações completamente
Wildcards: Bash(npm *) casa com qualquer comando npm
Deny sempre ganha de allow em conflitos
Settings locais sobrescrevem o do project, que sobrescreve o do user

06 · Quiz

Seu hook PreToolUse detecta que o Claude quer rodar rm -rf /tmp/build. Qual exit code seu script de hook deve retornar para bloquear essa ação?

Exit code 0 — sucesso
Exit code 2 — bloquear ação
Exit code 1 — erro genérico
Exit code 255 — erro fatal

07 · Combinar

Combine cada evento de hook com o uso que mais combina.

(Esta seção é interativa — ative o JavaScript para usar.)

Outras lições deste capítulo

⚠ A experiência interativa completa precisa de JavaScript. Ative-o e recarregue a página.

※ Este é um projeto educacional independente — não é um produto oficial da Anthropic. Claude™ é uma marca registrada da Anthropic, PBC.