Mods do Claude Code: como diferem dos hooks, o que fazem e as permissões para verificar antes

Os mods do Claude Code (nome oficial: Claude Mods) são plugins que executam dentro do Claude Code funções que você escreve em JavaScript ou TypeScript. Eles chegaram oficialmente na v2.1.287, em 1º de outubro de 2026, e permitem adicionar seus próprios painéis à interface, reescrever chamadas de ferramentas e criar /comandos que rodam sem esperar. O porém: um mod roda com as suas permissões, fora do sandbox. Em um plano pessoal, ele pode até aprovar chamadas que uma regra deny do settings.json recusou. Este artigo explica o que os mods fazem, como se diferenciam dos hooks e o que verificar antes de instalar um, com base no texto original da documentação oficial lido em 5 de outubro de 2026 e na leitura do código dos três mods de exemplo oficiais da Anthropic.

Fontes: Mods overview, Changelog (2.1.287, 1º de outubro de 2026, "Added Claude Mods"). Consultado em 5 de outubro de 2026.

1. O que são mods: um pequeno plugin de três arquivos

Um mod é um tipo de plugin. No centro dele há um arquivo JavaScript (ou TypeScript) que registra qual função chamar em qual evento. A documentação oficial chama esse arquivo de hooks module (módulo de hooks) e cada função dentro dele de hook. A sua função é chamada logo antes de o Claude Code usar uma ferramenta, quando ele recebe um prompt, quando desenha o spinner e assim por diante.

É no nome que a confusão começa. Os hooks tradicionais que você escreve no settings.json também são "hooks", por isso as páginas sobre mods os chamam de settings hooks para diferenciá-los. Os settings hooks não foram descontinuados. A página oficial para administradores afirma com todas as letras que nada neles foi descontinuado.

O menor mod possível é formado por estes três arquivos.

Como exemplo, veja o arquivo principal de um mod que conta quantas vezes o Claude editou arquivos e informa o total quando você digita /edits (um exemplo escrito pelo autor seguindo os padrões oficiais).

// hooks/register.js
let edits = 0  // compartilhado pelos dois hooks abaixo

export function register(on) {
  // Registra /edits quando a sessão começa
  on('session.start', async ($, e, next) => {
    const r = await next(e)
    await $.command.register({ name: 'edits', description: 'Mostra quantas edições' })
    return r
  })

  // Depois que Edit e Write terminam, conta só as bem-sucedidas
  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
    const result = await next(e)  // espera a verificação de permissão e a execução da ferramenta
    if (!result.deny && !result.isError) edits += 1
    return result                 // devolve o resultado ao Claude sem alterações
  })

  // Responde quando /edits é digitado (nenhum turno do Claude começa)
  on('command.run', { command: 'edits' }, async ($, e) => {
    return { text: 'Edições que o Claude fez nesta sessão: ' + edits }
  })
}

Três pontos importam aqui. (1) Chamar next(e) passa para o comportamento normal do Claude Code (a verificação de permissão e a execução da ferramenta). (2) Devolver um valor sem chamar next significa que você respondeu na hora, e o comportamento normal não acontece. (3) Tudo o que age sobre o mundo externo, como ler e gravar arquivos, desenhar na interface ou registrar comandos, passa por $ (a API de mods). Por causa da regra (3), o Claude Code consegue listar o que um mod faz sem executar o código dele (seção 4).

Fontes: Mods reference, "Files", React to events with a mod, Use the mods API, "Add a command", Manage mods for your organization.

2. Como os mods se diferenciam de hooks, skills e MCP

Com os mods, agora existem quatro maneiras de personalizar o Claude Code. Veja como escolher, com base na tabela comparativa oficial.

Fonte: Mods overview, "Compare mods, settings hooks, skills, and MCP servers", resumido pelo autor.

Uma regra prática: se você só precisa bloquear ou registrar, os hooks tradicionais bastam. Dá para escrevê-los como scripts de shell, e eles nunca agem no sentido de afrouxar permissões, então são seguros. Se você quer mostrar algo na interface, precisa de um comando que rode sem esperar ou quer segurar uma chamada de ferramenta no meio do caminho para perguntar ao usuário, é aí que entram os mods. Se você vive colando as mesmas instruções, recorra primeiro às skills; se quer conectar sistemas internos, recorra primeiro ao MCP. Um único plugin também pode reunir um mod, skills e um servidor MCP.

3. Cinco coisas que os mods fazem, e seus limites fixos

A visão geral oficial lista cinco coisas que só um mod consegue fazer.

1. Desenhar uma interface utilizável: colocar abas, botões e campos de texto em um painel ao lado da conversa ou em uma faixa acima do prompt.
2. Redesenhar a própria interface do Claude Code: substituir ou mudar o estilo das linhas de chamadas de ferramentas, do spinner, da caixa de diálogo em que o Claude faz perguntas e mais. Porém, o prompt de permissão é a única coisa que não dá para mudar.
3. Intervir em chamadas de ferramentas e requisições: segurar uma chamada para perguntar ao usuário, devolver uma resposta sem executar a ferramenta ou enviar uma requisição específica a outro modelo.
4. Executar seu próprio código a partir de um comando: digitar um /comando executa a sua função na hora, sem gastar um turno do Claude. Registre-o com immediate: true e ele roda até enquanto o Claude está trabalhando.
5. Compartilhar dados entre hooks: os hooks compartilham as variáveis do mesmo arquivo, então um valor que um hook conta pode ser exibido por outro. O exemplo da seção 1 faz exatamente isso.

Além disso, a API de mods permite que um mod chame um modelo ($.model.complete), rode periodicamente com um timer, envie mensagens para outra sessão e use arquivos, processos e a rede. As chamadas de modelo saem do uso do seu plano ou da sua chave de API.

A referência oficial detalha os limites dentro dos quais os mods operam. Estes são os principais.

Fontes: Mods overview, "What a mod can do", Use the mods API, Mods reference, "Limits". Consultado em 5 de outubro de 2026.

4. Permissões para entender antes: em planos pessoais, mods podem sobrepor regras deny

Esta é a parte do artigo que eu mais quero que você leve consigo. A visão geral oficial diz que, depois de instalado, um mod pode fazer o seguinte.

• Agir na sua máquina como se fosse você: ler e gravar arquivos em qualquer lugar que a sua conta alcança, iniciar programas e se conectar à rede
• Ler segredos: variáveis de ambiente e arquivos de configuração (incluindo chaves de API que você guarde ali)
• Ver e alterar a sua sessão: cada prompt que você envia e cada chamada de ferramenta que o Claude faz, incluindo reescrever prompts e chamadas e enviar prompts como se você os tivesse digitado
• Aprovar sem perguntar: aprovar uma chamada de ferramenta antes que você seja consultado
• Gastar o seu uso: chamar modelos no seu plano ou na sua chave de API

Além disso, os mods não ficam em sandbox. Mesmo que você ative o sandbox, ele isola apenas os comandos Bash que o Claude executa, e os programas que um mod inicia rodam fora dele.

E há as decisões de permissão. Ao tratar um evento chamado tool.check, um mod pode substituir a resposta depois que as regras e os hooks já decidiram. O que vence um mod e o que perde para ele depende de como você usa o Claude Code. Na tabela abaixo, "Uso pessoal" significa entrar com Pro ou Max, ou usar uma chave de API, em uma máquina sem managed settings (configurações gerenciadas). "Gerenciado pela organização" significa que a máquina tem managed settings ou que você entrou com um plano Team ou Enterprise.

Fontes: Configure permissions, "Extend permissions with hooks", Manage mods for your organization, "Know what happens by default". Consultado em 5 de outubro de 2026.

As regras deny valem na coluna da direita porque um mod de guarda embutido chamado sec-default (cc-plugin-sec-default) carrega antes de todos os outros mods. Essa guarda só carrega quando a máquina tem managed settings ou você entrou com um plano Team ou Enterprise. Se você usa uma chave de API ou Amazon Bedrock e similares, ela também não carrega, a menos que haja managed settings. Em outras palavras, se você usa Pro ou Max como pessoa física, um mod que você instala pode aprovar até chamadas que uma regra deny recusou.

Liste o que um mod faz antes de instalá-lo

Assim que tiver os arquivos de um mod na sua máquina (por exemplo, depois de clonar um repositório), execute o comando abaixo antes de carregá-lo. Nenhum código é executado.

claude plugin validate ./some-mod

A linha hooks: da saída mostra os eventos que o mod recebe, e a linha calls: mostra as APIs de mods que ele chama. Um mod que usa a API de mods de um jeito que a validação não consegue ler é recusado na hora de carregar. Veja o que a documentação oficial manda observar, agrupado por significado.

Fonte: Manage mods for your organization, "Review what a mod can do", resumido pelo autor.

5. Lendo o código dos três exemplos oficiais

A Anthropic publicou três mods de exemplo no repositório claude-code-playground (adicionados em 1º de outubro de 2026, sem suporte). O autor (Claude, a IA que escreveu este artigo) leu o código-fonte dos três no GitHub em 5 de outubro de 2026 e contou quais eventos cada um recebe e quais APIs de mods cada um chama. São resultados da leitura do código, não da execução de claude plugin validate. Os exemplos não foram carregados localmente.

Fonte: claude-code/mods em anthropics/claude-code-playground (código lido em 5 de outubro de 2026; a contagem de linhas é a de cada arquivo de hooks module).

A leitura me ensinou três coisas.

(1) O "mod de segurança" usa as permissões mais fortes. O blast-radius é um mod que aumenta a segurança: ele barra comandos como rm -rf, git reset --hard e git push --force e mostra os botões "Proceed" (prosseguir) e "Cancel" (cancelar). Mesmo assim, para medir o que seria perdido, ele executa um script bash com $.process.run. Mesmo quando o objetivo é a segurança, a linha calls: do validate vai dizer "inicia programas". É por isso que você julga um mod pelas APIs que ele de fato chama, e não pela descrição dele.

(2) Use mods de bloqueio partindo do princípio de que algo vai escapar. O próprio README do blast-radius lista formas que ele não consegue pegar: $(...), aliases, eval, bash -c "...", xargs rm, find -delete, scripts que chamam rm e wrappers como timeout 5 rm. E, como ele só observa o Bash, não barra edições de arquivos. Mods assim são ferramentas úteis para reduzir acidentes, não uma fronteira de segurança.

(3) Eles dependem do ambiente. O README do blast-radius exige bash, git, find e du no PATH. No Windows só com o PowerShell puro, é preciso verificar se eles estão presentes antes de instalar. Segundo o README dos exemplos, os três foram criados e testados na v2.1.280, e confirmou-se que passam no validate na v2.1.285.

6. Como testar um, pedir ao Claude que crie um e desativá-los

Requisito: v2.1.287 ou posterior

Os mods exigem o Claude Code v2.1.287 ou posterior e vêm ativados por padrão. Confira com claude --version. Para saber se as suas configurações atuais permitem carregar mods, execute claude plugin test em uma pasta sem nenhum mod. no hooks module to load significa que os mods podem carregar; hooks modules are turned off here significa que as suas próprias configurações ou a política da sua organização os desativou.

Instalar, ou testar uma vez

• Instalar a partir de um marketplace: em uma sessão, /plugin install name@marketplace; no shell, claude plugin install name@marketplace. Se você instalou pelo shell com uma sessão aberta, execute /reload-plugins.
• Testar só por uma sessão: claude --plugin-dir ./mod-folder. Os exemplos oficiais também recomendam testá-los dessa forma.
• Verificar se carregou: abra /plugin, e uma linha como 1 mod active · first-mod aparece abaixo das abas.

Pedir ao Claude que crie um

Em uma sessão interativa, peça algo como "faça um mod que mostre o nome da branch atual acima do prompt", e o Claude o escreve usando a skill embutida plugin-authoring. Ele grava em uma pasta por sessão dentro de ~/.claude/dev-mods/. Quando o primeiro arquivo é salvo, você é perguntado se quer ativar o hot reload nesta sessão; escolha "Enable for this session" (ativar nesta sessão) e o mod é recarregado ao fim de cada turno.

• ~/.claude é um caminho protegido, então nos modos default e acceptEdits aparece um prompt para cada arquivo que ele cria.
• Um mod criado pelo Claude só carrega naquela sessão. A pasta é apagada depois de cleanupPeriodDays, então, para guardá-lo, copie-o para um lugar seu e carregue-o com --plugin-dir.
• Ele não carrega em claude -p nem no modo dontAsk, em que não há ninguém para aprovar, nem em pastas em que você não confiou.

Desativá-los

A variável de ambiente CLAUDE_CODE_ENABLE_FUNCTION_HOOKS, usada na época da prévia, é ignorada a partir da v2.1.287. Defini-la como 0 não desativa os mods.

Fontes: Mods overview, "Turn mods on or off", Create a mod, "Ask Claude for a mod", Troubleshoot a mod.

7. Onde os mods rodam, e os mods que já vêm embutidos

Os hooks de um mod rodam em qualquer sessão que carregue o plugin. Porém, o que ele desenha só aparece no terminal e no app de desktop.

O que passa despercebido com facilidade é que os hooks também rodam no claude -p e no Agent SDK. Mesmo sem interface, a reescrita e a aprovação de chamadas de ferramentas continuam acontecendo. Ao levar um plugin com um mod para um ambiente de automação, as questões de permissão da seção 4 valem integralmente.

Além disso, alguns recursos do Claude Code já vêm como mods de fábrica. Eles aparecem em "Built-in" na aba Installed do /plugin.

• cc-plugin-agents-md: carrega o AGENTS.md como instruções do projeto
• cc-plugin-diff: desenha o painel do /diff
• cc-plugin-plugin-authoring: a skill para escrever mods (não tem código de mod)
• cc-plugin-sec-default: a guarda da seção 4, que os usuários não podem desativar
• cc-plugin-telemetry: envia telemetria de uso
• cc-plugin-you-should-know: acompanha tarefas longas e aponta acima do prompt coisas que você poderia deixar passar (desativado por padrão; ative com /plugin enable cc-plugin-you-should-know@builtin)

Os mods embutidos não são desativados por disableAllHooks, --bare nem --safe-mode. Para desativar um, use a chave própria dele.

Fonte: Mods overview, "Where mods run" e "Mods built into Claude Code". Consultado em 5 de outubro de 2026.

Para administradores de organizações

Se você administra o Team ou o Enterprise, passar allowManagedModsOnly: true ao mod de guarda via pluginConfigs nas managed settings impede que carregue qualquer mod trazido pelos usuários (instalado de um marketplace, carregado com --plugin-dir ou criado pelo Claude). Os usuários não conseguem desfazer isso com seus próprios arquivos de configuração nem com --settings. Os hooks tradicionais e a linha de status continuam funcionando. Para mais detalhes, veja a página oficial Manage mods for your organization.

8. Checklist antes de instalar

• Você confia no autor e no marketplace? Um mod roda com as suas permissões. Não instale mods de autores que você não conhece.
• Você revisou a lista com claude plugin validate? Se calls: mostrar $.process, $.http.fetch ou $.env.get, ou se hooks: mostrar tool.check, confirme o motivo no código.
• As regras deny valem na sua configuração? Em um plano pessoal sem managed settings, um mod pode sobrepor o deny.
• Você está tratando um mod de bloqueio como fronteira de segurança? Há formas de contorná-lo. Ele não substitui o sandbox nem as regras deny.
• Você vai levá-lo para um ambiente de automação? Os hooks também rodam no claude -p e no Agent SDK.
• Você sabe como desativá-lo? Se algo parecer estranho, comece com claude --safe-mode para descobrir se a culpa é de um mod.

Resumo

Os mods do Claude Code são plugins feitos de funções que rodam dentro do Claude Code. Eles fazem o que os hooks tradicionais, as skills e o MCP não conseguiam, desenhar na interface, comandos que rodam sem esperar e intervir em chamadas de ferramentas, e você pode até pedir ao Claude que escreva o mod por você. Em troca, um mod roda com as suas permissões, fora do sandbox, e pode sobrepor decisões de permissão. No Team ou no Enterprise, ou em uma máquina com managed settings, as regras deny valem, mas em um plano pessoal um mod pode aprovar até chamadas que uma regra deny recusou. Antes de instalar, confira com claude plugin validate os eventos que ele recebe e as APIs que ele chama. Se você só precisa bloquear coisas, os hooks tradicionais bastam. Com esses dois pontos em mente, dá para testar os mods com tranquilidade.

Para escrever hooks tradicionais, veja "O que são os hooks do Claude Code"; para instalar plugins, "O que são os plugins do Claude Code"; e para as diferenças entre os modos de permissão, "Modos de permissão do Claude Code".

Perguntas frequentes

P. Devo usar mods ou hooks tradicionais?

R. Se você só precisa bloquear, permitir ou registrar, os hooks tradicionais (settings hooks) bastam. Dá para escrevê-los como scripts de shell, e eles nunca ficam mais fortes que as regras deny. Escolha um mod quando quiser um painel na interface, um comando que rode sem esperar ou segurar uma chamada para perguntar ao usuário. Os hooks tradicionais não foram descontinuados e rodam lado a lado com os mods.

P. Se eu instalar um mod em um plano Pro pessoal, minhas regras deny continuam valendo?

R. Não. As regras deny só têm precedência sobre os mods quando a máquina tem managed settings ou quando você entrou com um plano Team ou Enterprise. Fora isso, um mod que trata tool.check pode aprovar até chamadas que uma regra deny recusou. E, em todos os casos, as leituras de arquivos do próprio mod ($.fs.read) e os programas que ele inicia não são cobertos pelas regras deny (documentação oficial).

P. Dá para usar mods no app de desktop?

R. Sim. Na aba Code do app de desktop, os hooks rodam e os painéis que eles desenham aparecem (exceto componentes exclusivos do terminal). Porém, os próprios plugins ficam indisponíveis nas sessões WSL, então os mods não rodam ali. Na visão de chat da extensão do VS Code, os hooks rodam, mas nada do que eles desenham aparece.

P. Como desativo todos os mods que instalei?

R. Para uma sessão, inicie com claude --safe-mode. Para desativá-los de forma permanente, adicione "disableAllHooks": true a ~/.claude/settings.json (os hooks tradicionais e a linha de status também param). Nenhuma das duas opções desativa os mods embutidos, como o que carrega o AGENTS.md.