on(eventName, handler).
Construa seu primeiro mod antes de começar aqui. Para cada evento e seus campos exatos, consulte a referência ou leia os tipos para sua compilação.
Como um hook manipula um evento
Um hook fica entre um evento e o que Claude Code faria sobre ele, portanto pode observar o evento, reescrevê-lo ou respondê-lo por si mesmo. Ele recebe três argumentos: a API de mods como$, o evento como e e o próximo manipulador como next. Os manipuladores de um evento formam uma cadeia de middleware. next(e) chama o próximo manipulador, que é o hook de outro mod ou, no final da cadeia, o comportamento próprio de Claude Code, e é resolvido para o resultado. O que seu hook faz com next decide qual dos três ele faz.
Observe um evento
Para observar um evento sem alterá-lo, faça seu trabalho e retornenext(e). Este hook registra cada ferramenta que Claude está prestes a usar:
● my-mod: Claude is about to use Bash aparece na transcrição, onde my-mod é o nome do seu plugin. A ferramenta é executada como seria sem o mod.
Para agir após o evento, await next(e), faça seu trabalho e retorne o resultado. Este hook registra cada ferramenta após sua execução:
next(e) foi resolvido.
Reescreva um evento
Para alterar o que Claude Code age, como o texto de um prompt, chamenext com uma cópia modificada do evento. O evento em si é imutável: é congelado em cada profundidade e atribuir a um campo lança um erro. Este hook corta cada prompt antes de ser enviado:
await next(e), depois retorne uma cópia do resultado com um campo substituído.
Responda a um evento
Para manipular um evento você mesmo, retorne um resultado sem chamarnext. Isso interrompe a cadeia, portanto mods posteriores e o comportamento próprio de Claude Code não são executados. Este hook recusa cada comando Bash:
deny como o resultado da ferramenta. Cada evento tem sua própria forma de resultado, que a referência de eventos lista.
Filtre quais eventos um hook manipula
Para executar um hook apenas para alguns eventos, passe um filtro como o segundo argumento paraon. Claude Code chama o filtro de matcher. É um objeto cujos campos são comparados com os do evento, e o hook é executado apenas quando cada campo corresponde. Um campo pode ser um valor, uma matriz de valores permitidos ou uma expressão regular.
Cada linha neste exemplo registra a mesma função, hook, para um conjunto mais estreito de chamadas de ferramentas:
hook é executado uma vez para uma chamada Bash, Edit ou Write, e uma vez para uma chamada a uma ferramenta cujo nome começa com mcp__github__. Uma chamada para qualquer outra ferramenta, como Read, não corresponde a nenhuma das três, portanto hook não é executado para ela.
O nome do evento pode ser um wildcard. 'classic.*' corresponde a cada evento de hook de configurações. '*' corresponde a cada evento exceto os eventos de telemetria, que são registrados pelo próprio nome e com um filtro { to: 'collector' }.
Registre cada evento uma vez por matcher. Se você chamar on duas vezes para session.start sem um matcher, o módulo falhará ao carregar com on("session.start") is registered twice without a matcher. Coloque tudo o que seu mod faz no início da sessão em um hook.
Faça hook dos desenhos e controles de outros mods
Para fazer hook dos controles, painéis ou da linha acima do prompt de outro mod, passe um matcher complugin. Use o nome do mod sem seu marketplace, como em { plugin: 'other-mod' }, ou { plugin: '*' } para todos os mods. Sem plugin, um hook em ui.press, ui.input, ui.select ou ui.focus não é executado para os controles de outros mods, e um hook ui.render ignora seus painéis e suas linhas acima do prompt.
Um hook em um wildcard sem matcher, como on('*', hook) ou on('ui.*', hook), ainda é executado para todos os mods. Um wildcard com um matcher também precisa de plugin.
{ plugin: '*' } requer Claude Code v2.1.323 ou posterior. Antes da v2.1.323, um hook sem plugin era executado para todos os mods, e um hook com { plugin: '*' } não era executado. Para corresponder a todos os mods em ambas as versões, use { plugin: /./ } em ui.press, ui.input e ui.select. Para ui.focus e ui.render, use on('ui.*', hook) e verifique o nome do evento em next.event, como em if (next.event !== 'ui.focus') return next(e).Fazer hook no que o Claude está fazendo
Trate estes eventos para ver ou alterar uma chamada de ferramenta, um prompt, um turno ou uma leitura de configurações enquanto acontecem. Para cada evento e o que um hook pode retornar, consulte a referência de eventos.Proteger ou alterar uma chamada de ferramenta
Um hooktool.call vê cada ferramenta que o Claude está prestes a usar, então pode recusar a chamada, alterar seus argumentos ou deixá-la passar. tool.call é disparado quando o Claude Code está prestes a executar uma ferramenta, incluindo chamadas que um subagente faz e chamadas a ferramentas MCP. e.tool é o nome da ferramenta e os argumentos da ferramenta são campos de e, como e.command para Bash. Quando você chama next(e), o Claude Code executa a verificação de permissão e depois a ferramenta.
Este hook recusa um comando Bash que faz force push e informa ao Claude o motivo:
git push --force, o comando não é executado e nenhum prompt de permissão aparece, porque o hook nunca chama next. O Claude lê o texto de deny como o resultado da ferramenta, então escreva-o como uma instrução sobre a qual o Claude possa agir. Todos os outros comandos Bash são executados como seriam sem o mod.
Se este hook lançar um erro ou exceder o tempo limite, o Claude Code o ignora e o comando prossegue como prosseguiria sem o mod. Para recusar o comando nesse caso, adicione um handler .catch ao hook.
Para agir depois que uma ferramenta foi executada, use await next(e), faça seu trabalho e retorne o que next lhe deu. Este hook registra em log cada arquivo .mdx que o Claude altera, com $.ui.log, que adiciona uma linha esmaecida à transcrição que o Claude não lê:
.mdx, uma linha esmaecida na transcrição indica o nome do arquivo. Nada é registrado em log para outro tipo de arquivo, nem para uma chamada que foi recusada ou falhou. A visão do Claude sobre a chamada não muda, porque o hook retorna o resultado que recebeu.
Seu hook também pode alterar uma chamada, tentar novamente, respondê-la ele mesmo ou reter seu resultado:
- Alterar a chamada: passe argumentos alterados para
next. - Tentar novamente a chamada: chame
next(e)outra vez. Um hook que vêisErrorno primeiro resultado pode executar a ferramenta uma segunda vez e retornar esse resultado. - Responder você mesmo à chamada: retorne um objeto com um campo
result, sem chamarnext, e, para uma ferramenta integrada, dê aresulto formato que o próprio resultado dessa ferramenta tem nos tipos do seu build. Nenhum prompt de permissão aparece e a ferramenta não é executada, então o resultado que você retorna é tudo o que o Claude fica sabendo sobre o que aconteceu. - Reter o resultado do Claude: retorne
{ deny: reason }depois deawait next(e). O Claude lê o seu motivo no lugar do quenextretornou. Quando a ferramenta foi executada, o deny impede que o Claude veja seu resultado e não desfaz nada do que a ferramenta fez. Quando a ferramenta foi executada com sucesso, o motivo vem depois de uma nota comoBash ran, and a plugin withheld its result:.
tool.call de qualquer mod. Quando um hook gerenciado bloqueia a chamada, nenhum hook tool.call de mod é executado para essa chamada.
Reter uma chamada de ferramenta até o usuário decidir
Um hook pode pausar uma chamada de ferramenta e perguntar ao usuário o que fazer antes que ela prossiga. Um hooktool.call pode usar await antes de chamar next ou retornar, e a chamada de ferramenta permanece pendente até lá. Para fazer a pergunta ao usuário, chame $.ui.ask. Ele mostra sua pergunta acima de uma lista numerada das suas opções, no diálogo que o Claude usa para lhe perguntar algo, e resolve para o rótulo que o usuário escolher. Depois das suas opções, o diálogo adiciona uma linha para digitar uma resposta diferente e uma linha Chat about this.
O padrão RISKY neste exemplo corresponde a rm -r, rm -rf, git reset --hard e git push com --force, e não detecta outras grafias como git push -f. Este módulo pergunta antes de executar um comando Bash que corresponda ao padrão:
rm -rf build, a pergunta aparece com o comando nela, e o comando aguarda a resposta:
- O usuário escolhe Run it: o hook chama
next(e), e a verificação de permissão habitual ainda é executada depois disso - O usuário escolhe Refuse: o comando não é executado, e o Claude lê o texto de
deny - O usuário digita uma resposta:
$.ui.askresolve para o texto digitado. O hook o compara comRun it, então qualquer outro texto recusa o comando. - Ninguém responde:
$.ui.aské rejeitado quando o usuário dispensa a pergunta ou escolhe Chat about this, e em uma execuçãoclaude -p, então o blococatchmantém a resposta comoRefuse
$.ui.ask, porque esse tempo não conta para o limite de tempo do hook. O tempo gasto aguardando uma promise sua conta.
O Claude Code ignora um hook que excede o tempo limite, então o comando retido seria executado. Para recusá-lo nesse caso, encadeie um handler .catch ao registro que on retorna. Esse handler é separado do bloco catch dentro do hook.
Aprovar ou recusar uma chamada de ferramenta antes de o usuário ser consultado
Para decidir se uma chamada de ferramenta pode ser executada, tratetool.check, o evento em que o Claude Code toma essa decisão.
Para um comando ou caminho fixo, use uma regra de permissão como Bash(npm test), que não exige código. Trate tool.check quando a decisão depender do que é verdade naquele momento, como o branch Git atual ou um valor que outro hook registrou.
- O que retornar: para decidir a chamada você mesmo, retorne um objeto seu, como
{ decision: 'allow' }ou{ decision: 'deny', reason }. Para não interferir na decisão, retorne o queawait next(e)lhe dá. - O que
await next(e)lhe dá: a própria decisão do Claude Code, como um objeto cujodecisionéallow,askoudeny. Nenhum prompt de permissão aparece enquantonext(e)é executado. - Argumentos:
e.inputcontém os argumentos da ferramenta, comocommandpara Bash - Quando
tool.checké disparado: depois que os hooksPreToolUsesão executados, e antes do prompt de permissão, do classificador do modo auto ou de um hookPermissionRequest
git push enquanto o branch atual for main:
git push em main e deixa passar todas as outras chamadas:
- Em
main: o hook retornadeny, mesmo quando uma regra permitegit push - Em outro branch, e para outros comandos: a chamada recebe a decisão que receberia sem o mod
- O hook lança um erro ou excede o tempo limite: a chamada também recebe a decisão que receberia sem o mod. Para recusar a chamada nesse caso, adicione um handler
.catchque retorne{ decision: 'deny', reason: 'the reason' }.
main para todos, proteja o branch no seu host Git.
Um hook
tool.check também pode retornar allow ou ask. No modo de planejamento, para uma chamada que não é somente leitura, como a edição de um arquivo, seu hook pode tornar mais restritiva a decisão que next(e) retorna, mas não pode torná-la mais permissiva. Para as regras de permissão e as decisões de hooks PreToolUse que o allow do seu hook não pode substituir, consulte Estender permissões com hooks.Verificar se uma chamada de ferramenta é somente leitura
Em um hooktool.check, e.isReadOnly é true quando a ferramenta informa a chamada como somente leitura. Caso contrário, o campo está ausente, e não false. e.isReadOnly requer o Claude Code v2.1.304 ou posterior.
Algumas ferramentas, como Read, Grep, Glob e WebSearch, informam toda chamada como somente leitura. Bash e ferramentas MCP informam uma chamada como somente leitura nestes casos:
- Bash: o comando passa na verificação de comandos somente leitura integrada do Claude Code
- Uma ferramenta MCP: o servidor define a anotação
readOnlyHintda ferramenta comotrue
ask para toda chamada mcp__github__ que não é somente leitura e que ainda não foi negada:
Filtrar um hook tool.check pelo fato de a chamada ser somente leitura
Para limitar quais chamadas seu hook trata com base em e.isReadOnly, use o matcher para chamadas somente leitura e o corpo do hook para as demais:
- Apenas chamadas somente leitura: adicione
isReadOnly: trueao matcher, como emon('tool.check', { tool: 'Bash', isReadOnly: true }, hook) - Chamadas que não são somente leitura: teste
e.isReadOnlyno corpo do hook, como faz o exemplomcp__github__. Se você colocarisReadOnly: falseem um matcher, seu hook nunca é executado.
Reescrever ou complementar um prompt
Um hookprompt.submit vê cada prompt antes de o turno começar, então pode reescrever o texto ou complementá-lo. e.text é o que foi digitado.
Este hook adiciona o nome do branch atual para o Claude sempre que um prompt menciona um pull request:
open a PR for this change, sua mensagem aparece igual na transcrição, e o Claude também lê uma linha como Current branch: feature/auth depois dela. Um prompt que não menciona um pull request passa sem alterações, e git não é executado.
Para impedir um prompt, retorne { drop: 'the reason' } sem chamar next. O texto volta para a entrada de prompt do usuário, e ele vê Prompt dropped by a hook: seguido do seu motivo, então dirija o motivo a ele. O prompt ainda é enviado nestes casos:
- Seu hook retorna um
dropdepois que sua chamadanext(e)deixou o prompt passar: o turno ainda é executado, e o hook falha com uma mensagem que incluia drop after its next() was answered - Seu hook lança um erro ou excede o tempo limite: o Claude Code o ignora e envia o prompt. Adicione um handler
.catchpara que uma falha não envie um prompt que o hook teria impedido.
prompt.section para cada seção do system prompt, prompt.context para o contexto enviado com a primeira mensagem e skill.prompt para o texto de uma skill. Para alterar uma seção depois que uma conversa já começou, consulte Enviar uma seção do system prompt ou descrição de ferramenta alterada. Em um hook skill.prompt, você também pode ler de qual plugin ou arquivo a skill veio.
Acompanhar um turno
Um turno é tudo o que o Claude faz em resposta a um prompt. Trateturn.start, turn.step e turn.complete para acompanhar um:
Escreva um hook
turn.step como um gerador assíncrono, porque o evento é transmitido em streaming. yield* next(e) encaminha a resposta à medida que ela é transmitida e resulta no resultado final. Este hook registra em log quanto de cada requisição a API do Claude atendeu a partir do cache de prompt:
result.usage contém as contagens de tokens que a API do Claude informa para uma requisição, mais o model que respondeu: input_tokens, output_tokens, cache_read_input_tokens e cache_creation_input_tokens. O hook também é executado para as requisições de subagentes, então verifique e.agentId quando quiser apenas a conversa principal.
Para ver as chamadas de ferramenta que a própria API executou durante a requisição, como chamadas à ferramenta advisor, leia result.serverToolUses. O Claude Code não executa essas chamadas, então nenhum hook tool.call ou tool.check é disparado para elas. O campo está ausente quando a resposta não tem chamadas desse tipo, e requer o Claude Code v2.1.290 ou posterior.
Enviar uma requisição para um modelo diferente
Se uma requisiçãoturn.step falhar com um erro de modelo quando model for um alias como haiku, atualize para o Claude Code v2.1.309 ou posterior, ou use um id de modelo completo. Antes da v2.1.309, um alias era enviado como escrito.
Para enviar uma requisição para um modelo diferente, passe para next o evento com model alterado, como em yield* next({ ...e, model: 'haiku' }).
Alterar ou recusar uma leitura de configurações
Use um hooksettings.read para alterar ou recusar uma leitura de configurações, seja a de um mod ou a do próprio Claude Code:
- A leitura de um mod: um mod chama
$.settings.read. - A leitura do próprio Claude Code: seu hook é executado pela primeira vez quando o Claude Code mescla as configurações da sessão, depois que os mods da sessão foram carregados. Seu hook é executado novamente quando as configurações ou os plugins carregados mudam.
- A guarda integrada: onde a guarda integrada é carregada, ela pode ignorar este hook em um mod que você instala ou carrega com
--plugin-dir. Para verificar, procure no log de depuração porsettings.read bypassed by cc-plugin-sec-default. Se uma linha com esse texto citar o seu mod, peça ao administrador da sua organização para instalar o mod como um dos mods da organização. - A versão: o disparo do evento na leitura do próprio Claude Code, e o campo
e.layers, requerem o Claude Code v2.1.304 ou posterior.
O que um hook settings.read recebe
Em
e.layers, plugin contém as configurações que os plugins habilitados fornecem, e é apenas um nome de camada, não um source que você possa passar para $.settings.read. flag contém as configurações passadas com --settings, e policy contém as configurações gerenciadas.
Distinguir a leitura do próprio Claude Code da leitura de um mod
Verifiquenext.origin:
- A leitura do próprio Claude Code:
{ plugin: 'engine', tier: 'core' } - A leitura de um mod:
pluginé o nome do mod que fez a chamada
O que um hook settings.read pode retornar
Retorne o resultado de next(e) sem alterações para deixar a leitura como está, ou retorne um destes:
Na leitura do próprio Claude Code, monte o seu
{ value } a partir do value de next(e), já que uma chave que você omitir fica indefinida. Onde o Claude Code lê uma chave como env de cada fonte separadamente, alterá-la no seu value não tem efeito.
O que next(e) fornece a um hook settings.read
next(e) resolve para { value } ou para { deny }:
{ value }:valuesão as configurações mescladas, ou as configurações de uma fonte quandoe.sourceestá definido. Se um hook que é executado depois do seu retornou um{ value }próprio, você recebe ovaluedesse hook.{ deny }: um hook executado depois do seu recusou a leitura. Retorne esse{ deny }sem alterações.
Alterar uma configuração a partir de um hook settings.read
Primeiro verifique quais mods recebem este evento, e a partir de qual versão.
Para alterar uma chave, espalhe o value de next(e) e defina essa chave, como este hook faz com spinnerTipsEnabled. O hook não verifica next.origin, então ele altera a chave tanto na leitura do próprio Claude Code quanto na leitura mesclada de um mod:
the answer for <key> is no value the key can hold. Se o seu valor couber e a chave ainda assim não mudar, consulte por que uma chave não tem efeito.
Tratar os eventos de hooks de configuração
Hooks de configuração são os hooks de comando, HTTP, prompt e agente que você configura em arquivos de configuração. Cada evento de hook de configuração, comoStop, SessionEnd ou PostToolUse, também é um evento nomeado classic. seguido do nome do evento de hook de configuração, como classic.Stop. e é o JSON que um hook de configuração recebe no stdin, incluindo transcript_path. Onde a guarda integrada é carregada, um hook nesses eventos em um mod que você instala não é executado.
Este hook usa Stop, que é disparado quando o Claude termina de responder, para registrar em log onde a transcrição da sessão está salva:
next(e), então ele observa o evento e não altera nada em como o turno termina.
Execute ao lado de outros mods
Vários mods podem tratar o mesmo evento e qualquer um deles pode falhar. Se seu mod bloqueia chamadas de ferramentas, verifique sua posição na cadeia e o que acontece quando seu hook falha.A ordem em que os mods são executados
Hooks no mesmo evento formam uma cadeia de middleware. Cadanext de um mod chama o hook do mod seguinte, e o último next atinge o comportamento próprio de Claude Code. O primeiro mod é o mais externo: vê o evento antes dos outros e o resultado após eles, e decide se os outros são executados. Um mod posterior não pode impedir que um anterior veja um evento.
Claude Code ordena a cadeia por onde cada mod vem:
- A guarda integrada
sec-default@builtin, um mod integrado em Claude Code que/pluginlista comocc-plugin-sec-default, onde ele carrega, mods que sua organização lista emprependPluginse depois qualquer outro mod que conta como de sua organização e não está emappendPlugins - Mods que você instala
- Mods que sua organização lista em
appendPlugins - Outros mods integrados em Claude Code
dependencies em seu manifesto. Dentro de um módulo, hooks são executados na ordem em que register chamou on.
Onde hooks de configuração são executados na ordem
Os hooksPreToolUse configurados em arquivos de configurações também são executados durante uma chamada de ferramenta, em pontos fixos na cadeia de mods:
- Hooks
PreToolUsede configurações gerenciadas: são executados antes do hooktool.calldo primeiro mod. Quando um hook gerenciado bloqueia a chamada, nenhum hooktool.callde mod é executado para essa chamada. - Hooks
PreToolUsede cada outro arquivo de configurações e dehooks/hooks.jsonde plugins: são executados após o último mod chamarnext, como parte do comportamento próprio de Claude Code. Um mod que respondetool.callsem chamarnextos impede de serem executados, e um mod que chamanextvê sua decisão no resultado que retorna.
tool.check dispara após os hooks PreToolUse terem sido executados. Para saber quais regras de permissão e decisões de hooks PreToolUse o allow de um hook tool.check não pode substituir, consulte Estenda permissões com hooks.
Manipule um hook que falha
Um hook que falha não quebra a sessão e você pode decidir o que acontece em seu lugar. Quando um hook sem um manipulador.catch lança, expira ou retorna um resultado da forma errada, o que acontece a seguir depende se ele tinha chamado next:
- Falhou antes de chamar
next: Claude Code o pula e o próximo manipulador é executado em seu lugar - Falhou após
nextser resolvido: esse resultado permanece e nada é executado uma segunda vez
my-mod: tool.call hook skipped: threw Error: boom. Onde você o lê depende da sessão, como Descubra por que um mod não faz nada lista. Um hook ui.render cuja árvore não valida conta como um que retornou um resultado da forma errada.
Para fazer um hook que bloqueia chamadas falhar fechado, adicione um manipulador de erro .catch que responda em seu lugar. Aqui, guard é sua função de hook, e o manipulador testa next.called para saber se guard já tinha chamado next quando falhou:
guard lança ou expira em uma chamada Bash, Claude Code chama o manipulador com o mesmo evento:
guardfalhou antes de chamarnext: o comando não é executado e Claude lê o texto dedenycom o tipo no finalguardfalhou depois de chamarnext: onext(e)do manipulador é resolvido para o resultado que a chamada deguardproduziu, sem executar o comando novamente, e Claude lê esse resultado
guard não tinha chamado next, o comando então prossegue como prosseguiria sem o mod.
O mesmo formato de manipulador serve para uma guarda em prompt.submit ou config.set. Quando next.called for false, retorne a recusa que a referência de eventos lista para esse evento: { drop: 'the reason' } para prompt.submit, { deny: 'the reason' } para config.set.
Em tool.check e plugin.register, uma recusa retornada após next ser resolvido ainda vale, portanto retorne-a sem testar next.called:
tool.check: retorne{ decision: 'deny', reason: 'the reason' }plugin.register: retorne{ refuse: 'the reason' }, como Recuse mods quando sua verificação falhar mostra
tool.call, um deny retornado após next ser resolvido retém o resultado, impedindo que chegue a Claude.
Próximos passos
- Use a API de mods: adicione comandos e ferramentas, chame um modelo e execute trabalho em um temporizador
- Desenhe na interface: mostre o que seus hooks coletam em um painel ou acima do prompt
- Teste um mod: levante qualquer um desses eventos de um teste
- Referência de mods: cada evento, cada método de API de mods e os limites