> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referência de mods
> Referência completa para mods do Claude Code: estrutura do módulo de hooks, eventos, métodos da API de mods, pontos de renderização, elementos por superfície, limites e configurações.
Consulte qualquer evento que um [mod](/docs/pt/plugins/mods/overview) pode tratar, método da API de mods que ele pode chamar ou ponto de renderização em que ele pode desenhar. As entradas abrangem a CLI do Claude Code e o aplicativo Desktop a partir da v2.1.290, e a extensão do VS Code a partir da v2.1.299. Cada entrada fornece o nome e uma descrição de uma linha, e aponta para a seção do guia que a explica, quando houver.
A referência completa são as [declarações TypeScript para mods](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts) do Claude Code, que descrevem cada evento, método e elemento, com exemplos. A cópia no GitHub pode ser mais antiga que a versão do Claude Code que você tem instalada. Quando as duas divergirem, confie [na cópia que o Claude Code grava para a sua versão](/docs/pt/plugins/mods/create#get-the-types-for-your-build).
Arquivos
Um mod é um diretório de plugin com estes arquivos:
| Arquivo | Obrigatório | Conteúdo |
| :- | :- | :- |
| `.claude-plugin/plugin.json` | Sim | O [manifesto](/docs/pt/plugins/manifest-reference) do plugin. Mods não adicionam campos obrigatórios. |
| `hooks/hooks.json` | Sim | `modules`: um array com um caminho, relativo a este arquivo, para o módulo de hooks, como em `"modules": ["./register.js"]`. Também pode conter [hooks de configuração](/docs/pt/hooks) em `hooks`. |
| O módulo de hooks, como [`hooks/register.js`](/docs/pt/plugins/mods/create#write-a-mod-yourself) | Sim | O ponto de entrada do mod. Exporta `register(on, options)`. Nomeado `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` ou `.tsx`. Um módulo ES. |
| [`types/index.d.ts`](/docs/pt/plugins/mods/interface#declare-the-values), indicado por `types` no manifesto | Quando o mod usa `$.state` ou adiciona um namespace à API de mods | Declara os valores de `PluginState` e qualquer namespace que o mod adiciona |
| Arquivos cujos nomes terminam em `.test.ts` ou `.test.tsx` | Não | Testes que o [`claude plugin test`](/docs/pt/plugins/mods/test#write-a-test) executa |
`register` recebe `on` e `options`. `options` contém os valores dos campos [`userConfig`](/docs/pt/plugins/components#user-configuration) que o manifesto declara, com os valores padrão preenchidos.
A função de hook
Um mod registra cada um de seus hooks, que são manipuladores de eventos, chamando `on` dentro de `register`. `on` recebe o nome do evento, um [matcher](/docs/pt/plugins/mods/events#filter-which-events-a-hook-handles) opcional, que é um filtro sobre os campos do evento, e o hook, como em `on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))`. `on` retorna um registro com um método, `.catch(handler)`, que define o [manipulador de erros](/docs/pt/plugins/mods/events#handle-a-hook-that-fails) do hook.
| Argumento | O que é |
| :- | :- |
| [`$`](/docs/pt/plugins/mods/events#how-a-hook-handles-an-event) | A API de mods: todos os métodos em [métodos da API de mods](#mods-api-methods). Escreva cada chamada por completo, namespace e depois método, como em `$.fs.read('notes.md')`. |
| [`e`](/docs/pt/plugins/mods/events#how-a-hook-handles-an-event) | A entrada do evento, como dados simples profundamente congelados. Para alterá-la, passe uma cópia para `next`. |
| [`next(e)`](/docs/pt/plugins/mods/events#how-a-hook-handles-an-event) | O próximo manipulador, como em um middleware. Executa os hooks depois deste e, em seguida, o comportamento do Claude Code. Resolve para o resultado do evento. |
| [`next.signal`](/docs/pt/plugins/mods/api#stop-background-work) | Um `AbortSignal` que é abortado quando o evento é abandonado |
| `next.origin` | `{ plugin, tier }` de quem disparou o evento. O próprio Claude Code é `{ plugin: 'engine', tier: 'core' }`. O `tier` de um mod é seu grupo de prioridade na [ordem em que os mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in): `prepend`, `user`, `append` ou `builtin`. |
| `next.budget` | O limite de tempo do hook em milissegundos: `next.budget.ms` é o limite inteiro e `next.budget.remainingMs` é o que resta agora |
| `next.to(e, tier)` | Pula para um tier posterior, que é `append`, `builtin` ou `core`. `next.to(e, 'append')` pula os mods que um usuário instalou. Somente um mod em `prependPlugins` ou `appendPlugins` pode chamá-lo. |
| `next.error` | Somente em um manipulador `.catch`. `kind` é `throw` ou `timeout` quando o hook falhou, e `message` é o texto do erro. `kind` é `re-entry` quando o hook foi ignorado porque o evento veio de dentro de uma chamada à API de mods feita por esse hook ou pelo código do seu mod fora de seus hooks. `re-entry` exige o Claude Code v2.1.292 ou posterior. |
| `next.error.cause` | Definido somente quando `kind` é `re-entry`. `rewritten` se um hook `tool.call` ou [`PreToolUse`](/docs/pt/hooks#pretooluse) alterou a chamada à API de mods da qual o evento veio, ou se um hook `agent.spawn` alterou um agente iniciado por essa chamada. `lent` quando um método que outro mod adiciona à API de mods disparou esse evento, a menos que `rewritten` também se aplique. `lent` exige o Claude Code v2.1.292 ou posterior e `rewritten`, v2.1.300 ou posterior. |
| `next.called` | Somente em um manipulador `.catch`. `true` quando o hook havia chamado `next`. |
Eventos
Os eventos estão agrupados pelo assunto de que tratam, cada um com quando é disparado e o que um hook nele pode retornar. Hooks em `turn.step` e `process.spawn` são geradores assíncronos, e os outros hooks são funções assíncronas.
A última coluna de cada tabela usa uma notação abreviada. `next(e)` repassa o evento sem alterações. `next({ ...e, text })` repassa uma cópia com o campo indicado alterado, como em `next({ ...e, text: e.text.trim() })`. Um objeto responde ao evento sem chamar `next`, e uma palavra como `reason` representa uma string que você escreve, como em `{ deny: 'Use the file tools.' }`.
Eventos de ferramenta são disparados em torno de cada chamada de ferramenta que o Claude faz, desde a descrição que o Claude lê até a decisão sobre se a chamada é executada:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`tool.call`](/docs/pt/plugins/mods/events#guard-or-change-a-tool-call) | Uma ferramenta está prestes a ser executada | `next(e)`, `{ deny: reason }` ou `{ result }` |
| [`tool.check`](/docs/pt/plugins/mods/events#where-settings-hooks-run-in-the-order) | O Claude Code decide se uma chamada de ferramenta pode ser executada, após os hooks `tool.call` e `PreToolUse`. `next(e)` resolve para a decisão a que chegaram as regras, o modo de permissão e esses hooks. | `{ decision }`, que é `allow`, `ask` ou `deny` |
| `tool.describe` | Uma vez para cada ferramenta, quando sua descrição é enviada pela primeira vez ao Claude. Uma segunda vez para uma ferramenta MCP quando o Claude a carrega por meio da [busca de ferramentas](/docs/pt/mcp#scale-with-mcp-tool-search), com `e.description` definido como o texto que o Claude lê para a ferramenta carregada. | `{ description }`, opcionalmente com `isDeferred` definido como `true` para colocar a ferramenta por trás da busca de ferramentas ou `false` para carregá-la antecipadamente |
Em um hook `tool.check`, leia estes campos para distinguir a chamada de um subagente da chamada da conversa principal, e para ver se sua organização exige aprovação para uma ferramenta de conector:
* **`e.agentId`**: definido quando um [subagente](/docs/pt/sub-agents) ou um [colega de equipe em processo](/docs/pt/agent-teams#choose-a-display-mode) faz a chamada, e ausente quando é a conversa principal que a faz
* **`e.ceiling`**: `ask` para uma ferramenta de conector que sua organização definiu como `ask`, em [sessões nas quais essa configuração chega ao Claude Code](/docs/pt/mcp#organization-controls-on-connector-tools)
Em `tool.check`, `e.agentId` e `e.ceiling` exigem o Claude Code v2.1.290 ou posterior.
Prompts e o que o Claude lê
Eventos de prompt abrangem o texto que o usuário digita e o texto que o Claude Code envia ao Claude por conta própria, como o system prompt e lembretes:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`prompt.submit`](/docs/pt/plugins/mods/events#rewrite-or-add-to-a-prompt) | Um prompt é enviado | `next({ ...e, text })`, `next({ ...e, context })` ou `{ drop: reason }` |
| `prompt.fill`, `prompt.suggest` | Um texto está prestes a entrar na caixa de prompt como rascunho ou como uma sugestão esmaecida | `next(e)` com o texto alterado |
| `prompt.edit` | O usuário edita a caixa de prompt | `next(e)` |
| `prompt.autocomplete` | O usuário digita na caixa de prompt e uma palavra termina no cursor. `e.token` é essa palavra. O Claude Code não espera pelo hook: suas próprias linhas de preenchimento automático aparecem primeiro. | `{ suggestions }`, uma lista de linhas `{ text, label, description }` exibidas abaixo das do próprio Claude Code. Escolher uma linha escreve seu `text` sobre a palavra. |
| `prompt.compose` | O Claude Code renderiza um system prompt | `{ sections }`, uma lista de `{ id, text, scope }` na ordem em que são enviadas |
| [`prompt.section`](/docs/pt/plugins/mods/events#rewrite-or-add-to-a-prompt) | Uma vez para cada seção nomeada do system prompt. `e.name` é o `id` da seção em `prompt.compose`. | `{ text }`, ou `{ text: null }` para omitir a seção |
| [`prompt.context`](/docs/pt/plugins/mods/events#rewrite-or-add-to-a-prompt) | Uma vez para cada conversa, para o contexto enviado com a primeira mensagem | `{ blocks }` |
| `prompt.attachment` | O Claude Code adiciona uma mensagem própria para o Claude, como um lembrete. `e.type` indica o tipo e, para os tipos que as declarações de tipos declaram, `e.detail` contém os fatos a partir dos quais o texto foi escrito. | `{ text }`, ou `{ text: null }` para omiti-la |
| `prompt.mention` | O Claude Code está prestes a ler um arquivo que um prompt menciona com @. Requer o Claude Code v2.1.290 ou posterior. | `next({ ...e, path })` para ler um arquivo diferente, ou `{ deny: reason }` |
| [`skill.prompt`](/docs/pt/plugins/mods/events#rewrite-or-add-to-a-prompt) | O texto de uma skill é expandido para o Claude | `{ text }` |
| `attribution.text` | O Claude Code compõe o texto de atribuição de um commit ou pull request | `{ text }` |
Campos de origem e de frontmatter em `skill.prompt`
Em um hook `skill.prompt`, você pode ler estes campos junto com o nome da skill em `e.skill` e o texto que o Claude lê em `e.text`:
| Campo | Tipo | O que contém |
| :- | :- | :- |
| `e.source` | string | Quem fornece a skill: `policySettings`, `userSettings` ou `projectSettings` para uma skill no [local](/docs/pt/skills#where-skills-live) corporativo, pessoal ou de projeto, respectivamente. Outras origens fornecem uma palavra como `plugin`, `mcp`, `syncedSkills` ou `built-in`. |
| `e.pluginName` | string | O nome do plugin, para uma skill cujo `e.source` é `plugin` |
| `e.path` | string | O caminho absoluto do arquivo `SKILL.md` da skill, ou do seu arquivo `.md` para uma skill escrita como um [arquivo de comando](/docs/pt/skills#where-skills-live). Ausente quando a skill não tem arquivo nesta máquina, como no caso de uma skill integrada. |
| `e.frontmatter` | object | O frontmatter do arquivo da skill, como dados simples |
| `e.frontmatterProblem` | string | O motivo pelo qual `e.frontmatter` não contém o frontmatter do arquivo ou uma de suas chaves, como em `is a list or a single value, not a table`. Ausente quando `e.frontmatter` contém o frontmatter inteiro ou a skill não tem nenhum. |
Um hook pode passar um `text` ou um `frontmatter` alterado para `next`: os hooks depois dele leem ambos, e o Claude lê o `text` final. Um hook que altera qualquer outro campo [falha](/docs/pt/plugins/mods/events#handle-a-hook-that-fails).
Em `skill.prompt`, `e.source`, `e.pluginName`, `e.path`, `e.frontmatter` e `e.frontmatterProblem` exigem o Claude Code v2.1.299 ou posterior.
Comandos e configuração
Eventos de comando e de configuração são disparados quando um comando é executado ou listado, e quando uma linha de `/config` é exibida ou alterada:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`command.run`](/docs/pt/plugins/mods/api#add-a-command) | Um comando está prestes a ser executado | `{ text }`, `{}` ou `next(e)` |
| `command.describe` | Uma vez para cada comando, para a lista de comandos | `{ description, argumentHint, isHidden }` |
| `config.set` | Uma linha de `/config` está prestes a mudar | `next({ ...e, value })` ou `{ deny: reason }` |
| `config.describe` | Uma vez para cada linha de `/config` | `{ label, description, isHidden }` |
Turnos
Eventos de turno acompanham uma resposta do início ao fim, incluindo cada requisição ao modelo dentro dela:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`turn.start`](/docs/pt/plugins/mods/events#follow-a-turn) | Um turno começa | `next(e)` |
| [`turn.step`](/docs/pt/plugins/mods/events#follow-a-turn) | Uma requisição está prestes a ir para o modelo | `yield* next(e)`, ou `next({ ...e, model })`, `next({ ...e, effort })` |
| [`turn.complete`](/docs/pt/plugins/mods/events#follow-a-turn) | Um turno terminou | `next(e)`, ou `{ text }` para mostrar uma linha abaixo da resposta |
Sessão
Eventos de sessão marcam o início, o fim e a compactação da sessão, e a troca de mensagens com outras sessões:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`session.start`](/docs/pt/plugins/mods/api#add-a-command-or-a-tool) | Uma vez para cada mod carregado, antes do primeiro prompt, e novamente após um recarregamento desse mod. Não após `/clear`, `/resume` ou `/branch`. | `next(e)` |
| `session.end` | A sessão termina, ou `/clear`, `/resume` ou `/branch` é executado. `e.reason` é `clear`, `resume`, `logout`, `prompt_input_exit` ou `other`. `/branch` informa `resume`. | `next(e)` |
| `session.compact` | A conversa está prestes a ser compactada | `{ skip: reason }` |
| [`session.receive`](/docs/pt/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](/docs/pt/plugins/mods/api#send-and-receive-messages-between-sessions) | Uma mensagem chega de, ou está prestes a ir para, outro agente ou sessão. Consulte [Enviar e receber mensagens entre sessões](/docs/pt/plugins/mods/api#send-and-receive-messages-between-sessions). | `{ consumed: reason }` para `receive`, `{ isDelivered: false, reason }` para `send` |
| `session.append` | Uma vez para cada linha que a conversa mantém, como um prompt, um bloco de resposta, um resultado de ferramenta ou um aviso, antes de ser armazenada | `next({ ...e, message })` com um `message.content` alterado, para reescrever os blocos de texto da linha ou o `content` de um bloco `tool_result` nela |
| `session.attach`, `session.detach` | Outro aplicativo se conecta à sessão ou se desconecta dela | `next(e)` |
| `session.measure` | Após cada turno e quando o percentual usado de um limite do plano muda | `next(e)` |
Subagentes
Eventos de subagente são disparados quando um tipo de subagente é oferecido ao Claude e quando um subagente ou um colega de uma equipe de agentes está prestes a iniciar:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| `agent.offer` | Um tipo de subagente é oferecido ao Claude | `{ isOffered: false }` para retê-lo |
| `agent.spawn` | Um subagente ou um colega de uma [equipe de agentes](/docs/pt/agent-teams) está prestes a iniciar. Para um colega de equipe, `e.isTeammate` é `true`. | `next({ ...e, model })` para escolher seu modelo, ou `{ deny: reason }` |
Quando o Claude retoma um subagente com a ferramenta [`SendMessage`](/docs/pt/sub-agents#resume-subagents), seu hook `agent.spawn` não é executado novamente. Para recusar as chamadas de `SendMessage` que retomam um subagente, faça a correspondência dessa ferramenta em um hook [`tool.call`](/docs/pt/plugins/mods/events#guard-or-change-a-tool-call).
Interface
Eventos de interface são disparados quando o Claude Code desenha um ponto de renderização e quando o usuário usa um controle que um mod desenhou. [Desenhar na interface](/docs/pt/plugins/mods/interface) mostra o que um hook `ui.render` retorna:
| Evento | Dispara quando |
| :- | :- |
| [`ui.render`](/docs/pt/plugins/mods/interface#pick-where-to-draw) | Um [ponto de renderização](#render-sites) está prestes a ser desenhado |
| `ui.resolve` | Os mods são carregados, uma vez para cada aplicativo, ponto de renderização e mod. O resultado é a tabela de elementos que `$.ui.resolve(e)` lê. |
| [`ui.press`](/docs/pt/plugins/mods/interface#respond-to-presses-and-typing), [`ui.input`](/docs/pt/plugins/mods/interface#respond-to-presses-and-typing), [`ui.select`](/docs/pt/plugins/mods/interface#respond-to-presses-and-typing) | Um `Button`, `Input` ou `Select` que um mod desenhou é usado |
| `ui.focus`, `ui.scroll` | O controle em foco ou a posição de rolagem de um painel ou da faixa está prestes a mudar |
| `ui.close` | Um painel está prestes a fechar. `e.id` é o painel e `e.origin.kind` é `plugin`, `person` ou `unload`. |
| [`ui.message`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | Um elemento `Client` envia dados para o seu mod |
| [`ui.fault`](/docs/pt/plugins/mods/interface#redraw-when-something-changes) | Um elemento `Client` que seu mod desenhou falhou ao carregar, desenhar ou executar. `e.phase` é `load`, `render` ou `run`, e `e.reason` é a mensagem de erro. Requer o Claude Code v2.1.289 ou posterior. |
Outros mods
Estes eventos permitem que um mod atue sobre outros mods à medida que são carregados, para recusar um deles ou alterar a API de mods que ele recebe:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`plugin.register`](/docs/pt/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | Um módulo de hooks está prestes a ser carregado. `e.uses` lista seus eventos, chamadas à API de mods, variáveis de ambiente e estado, como o `claude plugin validate` os imprime. Cada chamada é escrita sem o prefixo `$.`, como `fs.read`. | `{ refuse: reason }` |
| `engine.create` | A API de mods está sendo construída para este mod | Uma API de mods alterada, para adicionar um namespace. Um mod fora do [nível](#the-hook-function) `user` também pode reter um. |
Quando o hook de outro mod chama um método em um namespace que você adicionou em `engine.create`, as chamadas `$` do seu método são executadas no contexto desse hook até que todos os hooks nesse evento retornem. Por exemplo, um caminho relativo é resolvido em relação ao diretório de trabalho desse hook, e `$.prompt.submit` é rejeitado enquanto o turno está aguardando esse hook. As chamadas que seu método faz depois disso são executadas no próprio contexto do seu mod.
Telemetria
Eventos de telemetria são disparados para os registros de uso que o Claude Code registra em log:
| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| `telemetry.log`, `telemetry.mark` | Um registro de telemetria está prestes a ser registrado em log, ou um uso de um recurso é marcado. Em um mod que você instala, dê a um hook de telemetria o filtro `{ to: 'collector' }`, como em `on('telemetry.log', { to: 'collector' }, hook)`. Sem o filtro, o mod falha no `claude plugin validate`. `*` não corresponde a esses eventos. | `next(e)` ou `{ deny: reason }` |
Eventos de hooks de configuração
Cada [evento de hook de configuração](/docs/pt/hooks#hook-events) é um evento chamado `classic.`, como `classic.Stop` ou `classic.PostToolUse`. `e` é o JSON de stdin do hook.
Chamadas à API de mods
Cada [método da API de mods](#mods-api-methods) também é um evento, nomeado pelo seu namespace e método, como `fs.read`, `model.complete` ou `ui.open`. Um hook em um deles intercepta chamadas dos mods executados depois dele e pode retornar `next(e)`, `{ deny: reason }` ou `{ value }`.
Métodos da API de mods
A API de mods é o argumento `$` que todo hook recebe. Seus métodos estão agrupados em namespaces, como `$.ui`. Esta tabela lista os métodos de cada namespace pelo nome, então `open` na linha de `$.ui` é a chamada `$.ui.open(...)`. Os guias mostram os mais comuns em uso, e [os tipos para o seu build](/docs/pt/plugins/mods/create#get-the-types-for-your-build) documentam cada método com um exemplo.
| Namespace | Métodos |
| :- | :- |
| `$.plugin` | `name`, `root`: o nome e o diretório deste plugin |
| [`$.ui`](/docs/pt/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit` |
| [`$.command`](/docs/pt/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
| [`$.tool`](/docs/pt/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list` |
| `$.agent` | `register`, `spawn`, `list`. `list()` retorna os subagentes e colegas de equipe desta sessão, cada um com um `status` de `pending`, `running`, `waiting`, `idle`, `completed`, `failed` ou `killed`, sendo que `idle` e `waiting` exigem o Claude Code v2.1.289 ou posterior. |
| [`$.model`](/docs/pt/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |
| [`$.prompt`](/docs/pt/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. O Claude lê o texto de `submit({ text })` após uma frase que indica o seu mod como remetente. `submit({ text, asUser: true })` envia o texto como se fossem palavras do próprio usuário, sem essa frase. |
| `$.turn` | `abort` |
| [`$.session`](/docs/pt/plugins/mods/api#send-and-receive-messages-between-sessions) | `messages`, `cwd`, `root`, `model`, `turns`, `id`, `repo`, `surfaces`, `usage`, `version`, `compact`, `send`, `append`, `authorize`. `usage()` retorna `{ startedAt, context, rateLimits, cost }`: `context` tem `tokens`, `window` e `percent`, e `rateLimits` é uma lista de `{ kind, percentUsed, resetsAt }`. |
| `$.config` | `list`, `set` |
| [`$.settings`](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `get`, `set` |
| [`$.fs`](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `read`, `write`, `list`, `exists`, `stat`, `ancestors`. `write` não é atômico: ele substitui o conteúdo do arquivo no local, então outro processo pode ler um arquivo parcialmente gravado. Mantenha dados que várias sessões alteram em `$.store`. |
| [`$.store`](/docs/pt/plugins/mods/interface#keep-state) | `get`, `set`, `delete`, `keys`. Um armazenamento de chave-valor compartilhado por todas as sessões na máquina. Consulte [Salvar a partir de mais de uma sessão](/docs/pt/plugins/mods/interface#save-from-more-than-one-session). |
| [`$.state`](/docs/pt/plugins/mods/interface#keep-a-value-in-\$-state) | Estado reativo: `get`, `set`, com os auxiliares `atom`, `read`, `update`, `derive` e `memberOf` importados de `claude-code` |
| [`$.clock`](/docs/pt/plugins/mods/api#run-work-in-the-background) | `now`, `sleep`, `after`, `every` |
| [`$.http`](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `run`, `spawn` |
| [`$.mcp`](/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `call`, `connect`. `connect(server)` conecta um servidor MCP que o manifesto do seu próprio plugin lista. |
| `$.audio` | `play`, `speak` |
| `$.telemetry` | `log`, `mark`. Um registro só é enviado quando o Claude Code ou um mod integrado faz a chamada. |
Pontos de renderização
Um ponto de renderização é um ponto de extensão na interface do Claude Code. Cada linha é um valor de `e.component` em um hook `ui.render`, com os campos de `e.props` e os aplicativos que o renderizam. `e.surface` indica o aplicativo que está desenhando, como `terminal`, `desktop` ou `vscode`. [Alterar o que o Claude Code já desenha](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws) mostra o que um hook pode fazer em um ponto, com um exemplo de cada opção.
A renderização na extensão do VS Code requer a versão 2.1.299 ou posterior da extensão e uma sessão que [busque feature flags](/docs/pt/env-vars#features-that-need-feature-flag-fetching). [Desenhar na extensão do VS Code](/docs/pt/plugins/mods/interface#draw-in-the-vs-code-extension) lista o que a extensão desenha de forma diferente.
| Ponto | `e.props` | `e.requestId` | Renderizado em |
| :- | :- | :- | :- |
| [`Pane`](/docs/pt/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | O `id` do painel | Terminal, Desktop, VS Code |
| [`AbovePrompt`](/docs/pt/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Uma instância | Terminal, Desktop |
| `UserMessage` | `text`, `origin`, `isExpanded` e `task` ou `from` conforme a origem | O id da mensagem | Terminal, Desktop, VS Code |
| `AssistantMessage` | O texto da resposta | O id da mensagem | Terminal, Desktop, VS Code |
| `ToolUse`, `ToolResult`, `ToolGroup` | O nome, a entrada e o resultado da ferramenta | O id da chamada de ferramenta | Terminal, Desktop, VS Code |
| `CommandOutput` | `command`, `text` | O id da mensagem | Terminal, Desktop |
| [`AskUserQuestion`](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws) | A pergunta e as opções | O id da chamada de ferramenta | Terminal, Desktop, VS Code |
| `ToolProgress` | `kind` | O id da chamada de ferramenta | Terminal |
| [`Spinner`](/docs/pt/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | O id do agente | Terminal, Desktop, VS Code |
| `TurnDuration` | `word`, `durationMs` | O id da mensagem | Terminal |
| `InfoNotice` | `text`, `command` | O id da mensagem | Terminal |
| `SessionMode` | `modes` | Uma instância | Terminal, Desktop |
| `PromptHint` | `isDraft`, `isWorking`, `hint` | Uma instância | Terminal, Desktop |
`e.viewport` contém `columns`, `rows` e `isFullscreen`. No terminal e no aplicativo Desktop, ele está ausente até que o aplicativo tenha medido sua janela. Nesses casos, seu `rows` é a altura da janela inteira, não do seu painel. Na extensão do VS Code, ele está sempre presente.
Para ajustar uma árvore ao seu ponto, leia estas props no hook:
* **Largura de um `Pane` ou da faixa**: desenhe até `e.props.bodyColumns`
* **Altura de um `Pane` ao lado da transcrição**: quando `e.props.placement` é `'dock'`, `e.props.scroll.bodyRows` é o número de linhas que o painel tem para a sua árvore
* **Altura de um `Pane` acima do prompt**: quando `e.props.placement` é `'inline'`, o painel cresce com a sua árvore até um limite, e `bodyRows` é esse limite. Para solicitar um limite diferente, consulte o [campo `rows` de `$.ui.open`](/docs/pt/plugins/mods/interface#open-a-pane-at-the-right-time).
Uma árvore mais alta que o painel rola como um todo.
Elementos
Elementos são os blocos de construção de uma árvore que um hook `ui.render` retorna, e você os obtém de `$.ui.resolve(e)`. [Construir uma árvore a partir de elementos](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) mostra os mais comuns com a forma como o terminal os desenha, e a [galeria da interface](/docs/pt/plugins/mods/gallery) tem capturas de tela da maioria. Uma marca de seleção significa que o aplicativo pode desenhar o elemento.
| Elemento | Props principais | Terminal | Desktop | VS Code |
| :- | :- | :-: | :-: | :-: |
| [`Box`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `key`, layout flex, `gap`, `padding`, `margin`, `width`, `height`, [`borderStyle`](#box-border-styles), `backgroundColor`, `position`, `hover` | ✓ | ✓ | ✓ |
| [`Text`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, `bold`, `italic`, `underline`, `dimColor`, `inverse`, `wrap` | ✓ | ✓ | ✓ |
| [`Button`](/docs/pt/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action` | ✓ | ✓ | ✓ |
| [`Link`](/docs/pt/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. Consulte [Limites](#limits). | ✓ | ✓ | ✓ |
| [`Code`](/docs/pt/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |
| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |
| [`Input`](/docs/pt/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | Um documento SVG, até 131.072 caracteres | | ✓ | ✓ |
| [`Client`](/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key` | ✓ | ✓ | |
| [`Raster`](/docs/pt/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, `columns` até 512, `rows` até 256, `cells`. Consulte [Desenhar uma grade de células coloridas](/docs/pt/plugins/mods/interface#draw-a-grid-of-colored-cells). | ✓ | | |
| `Image` | Bytes PNG ou RGBA até 2 MiB, ou um caminho de arquivo, `columns` e `rows` até 255, e texto `alt`. | ✓ | | |
Mais regras de `Button`: `action` indica uma das próprias [ações de atalho de teclado](/docs/pt/keybindings) do Claude Code, e o atalho do usuário para ela pressiona o botão quando esse atalho é um acorde ou uma tecla com modificador. Um `hotkey` numérico em um botão na faixa também é acionado quando o usuário digita apenas esse dígito em um prompt vazio e faz uma pausa. Quando dois botões em um mesmo desenho indicam o mesmo `hotkey`, o posterior fica com ele. `autoFocus` aceita apenas `true` em qualquer controle, então omita a prop para deixá-lo desativado.
A extensão do VS Code ignora algumas props de elementos e desenha o elemento como se você as tivesse omitido:
* **`Box`**: `position` e `hover`
* **`Button`**: `hotkey`, `plain`, `autoFocus` e `action`, então o usuário pressiona um botão ali com um clique, ou com Enter quando ele estiver com o foco
* **`Code`**: `language`, `path`, `startLine`, `format` e `wrap`, então o código é desenhado sem cores nem números de linha, e um bloco `format: 'diff'` mostra o texto bruto do diff
* **`Input` e `Select`**: `autoFocus`
Estilos de borda de `Box`
Para desenhar uma borda ao redor de um `Box`, defina seu `borderStyle` como um destes nomes, como em `borderStyle: 'round'`. Cada linha informa o que o terminal desenha para esse nome e mostra a borda superior.
| `borderStyle` | O que o terminal desenha | Borda superior |
| :- | :- | :- |
| `'single'` | Linhas finas com cantos retos | `┌──┐` |
| `'double'` | Linhas duplas | `╔══╗` |
| `'round'` | Linhas finas com cantos arredondados | `╭──╮` |
| `'bold'` | Linhas grossas | `┏━━┓` |
| `'singleDouble'` | Linhas finas em cima e embaixo, linhas duplas nas laterais | `╓──╖` |
| `'doubleSingle'` | Linhas duplas em cima e embaixo, linhas finas nas laterais | `╒══╕` |
| `'classic'` | Os caracteres ASCII `+`, `-` e `\|` | `+--+` |
| `'arrow'` | Setas que apontam para dentro do `Box` | `↘↓↓↙` |
| `'dashed'` | Linhas tracejadas com cantos em branco | `╌╌` |
| `'quote'` | Uma barra, `▎`, no lado esquerdo e células em branco nos outros três lados | Em branco |
Um `Box` cujo `borderStyle` indica qualquer outro nome, como `'rounded'`, é desenhado sem borda.
Limites
Hooks e chamadas à API de mods são executados sob limites de tempo e de tamanho. O Claude Code ignora um hook que excede um limite de tempo.
| Limite | Valor |
| :- | :- |
| O tempo de execução próprio de um hook para um evento, sem contar o tempo dentro de `next` ou de uma chamada à API de mods que não seja `$.clock.sleep` | 10 segundos, ou 50 milissegundos para um hook `prompt.edit` |
| O tempo de execução de um manipulador `.catch` | 1 segundo |
| Todos os hooks `session.end` juntos | O mesmo que o [orçamento do hook SessionEnd](/docs/pt/hooks#sessionend-input), 1,5 segundo a menos que você o altere, contado a partir do momento em que os hooks `SessionEnd` das suas configurações terminam |
| Timeout de `$.process.run` | 30 segundos por padrão, no máximo 10 minutos |
| `maxTokens` de `$.model.complete` | 1024 por padrão, até 64.000 ou o limite de saída do modelo |
| `$.fs.read` e `$.fs.write` | 4 MiB para um arquivo |
| O corpo de uma requisição de `$.http.fetch` | 4 MiB, contados em caracteres. Uma chamada com um corpo maior é rejeitada. |
| O corpo de uma resposta de `$.http.fetch` | 4 MiB. `text` contém os primeiros 4 MiB e o restante não é lido. Quando o cabeçalho `Content-Length` declara mais, a chamada é rejeitada em vez disso, com um motivo que termina em `is over the 4194304-byte limit`, exceto quando a última requisição após quaisquer redirecionamentos usa o método `HEAD`. A isenção para `HEAD` requer o Claude Code v2.1.296 ou posterior. |
| Uma chamada de `$.http.fetch`, incluindo redirecionamentos e corpo | 30 segundos |
| Redirecionamentos que uma chamada de `$.http.fetch` segue | 5 |
| O motivo de `drop` de um hook ou o motivo de `deny` de `config.set` | 4.096 caracteres. O final de um motivo mais longo é cortado, e o drop ou deny ainda se aplica. O corte requer o Claude Code v2.1.292 ou posterior e, em versões anteriores, o hook [falha](/docs/pt/plugins/mods/events#handle-a-hook-that-fails) em vez disso. |
| Texto em uma árvore | Os primeiros 100.000 caracteres são desenhados |
| O `language` ou `path` de um `Code`, o `value` de uma opção de `Select` ou o `module` de um `Client` | 10.000 caracteres. Se algum for mais longo, o Claude Code [desenha sua própria versão do site](/docs/pt/plugins/mods/interface#build-a-tree-from-elements). |
| O `href` de um `Link` | 2.048 caracteres. Um `href` mais longo impede que a árvore inteira seja desenhada. |
| `$.store` | 4 MiB de JSON no total |
| `$.session.messages()` | As 4.096 entradas mais recentes |
| Redesenhos de `$.ui.invalidate('ui.render')` | Limitados a 10 por segundo, ou 30 no terminal para o painel visível, a faixa expandida e a linha de dica abaixo do prompt. Chamadas que chegam antes disso são agrupadas. |
| `$.ui.toast` | Exibido por 4 segundos, a menos que você passe `{ timeoutMs }` |
| Um painel aberto sem que o usuário tenha pedido | Posicionado a partir de 144 colunas do terminal, 110 depois que o usuário o tiver aberto uma vez |
| Escopos, como funções, blocos e loops, aninhados uns dentro dos outros em um arquivo de um módulo de hooks | 2.000 |
| Nomes de comandos, ferramentas, tipos de subagente e painéis | Letras, dígitos, `_` e `-`, até 64 caracteres |
| Um teste do `claude plugin test` | 5 segundos, a menos que o teste defina `timeoutMs` |
Configurações e variáveis de ambiente
Estas são as configurações e variáveis de ambiente que afetam os mods. A coluna Onde indica de qual arquivo de configurações ou ambiente cada uma é lida:
| Nome | Onde | O que faz |
| :- | :- | :- |
| `CLAUDE_CODE_PLUGIN_DIRS` | Ambiente, ou `env` em `~/.claude/settings.json` | Diretórios de plugin a carregar como `--plugin-dir` faz, para aplicativos aos quais você não pode passar uma flag. Caminhos absolutos separados por `:`, ou `;` no Windows. |
| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Ambiente | `1` faz com que uma sessão não interativa de longa duração recarregue os mods de `--plugin-dir` ao salvar |
| `prependPlugins`, `appendPlugins` | Configurações gerenciadas. Configurações do usuário somente em uma máquina sem configurações gerenciadas, para um usuário que não está conectado com um plano Team ou Enterprise. | Listas de ids de plugin, como `acme-guard@acme-tools`. Mods em `prependPlugins` são executados antes de todo mod que um usuário instala, e mods em `appendPlugins` são executados depois, na ordem listada. Consulte [A ordem em que os mods são executados](/docs/pt/plugins/mods/events#the-order-mods-run-in). |
| `allowManagedModsOnly` | Configurações gerenciadas, como uma [opção da guarda integrada](/docs/pt/plugins/mods/admin#set-options-on-the-built-in-guard) | Somente mods que [contam como da sua organização](/docs/pt/plugins/mods/admin#install-your-organizations-mods), e mods integrados ao Claude Code, executam seus hooks. Os hooks de configuração dos usuários continuam em execução. |
| `allowModsToOverrideDenyRules` | Configurações gerenciadas, como uma [opção da guarda integrada](/docs/pt/plugins/mods/admin#set-options-on-the-built-in-guard) | Permite que um mod instalado por um usuário aprove uma chamada de ferramenta que uma regra `deny` recusa |
| `allowManagedHooksOnly` | Configurações gerenciadas | Bloqueia hooks e mods instalados que não são da sua organização. Consulte [o que continua em execução](/docs/pt/settings-reference#what-runs-under-allowmanagedhooksonly). |
| `disableAllHooks` | Qualquer arquivo de configurações | Nas configurações gerenciadas, nenhum mod ou hook de um plugin instalado é executado. Nas suas próprias configurações, o que a sua organização gerencia continua em execução. Consulte [`disableAllHooks`](/docs/pt/settings-reference#disableallhooks). |
| `disableSideloadFlags` | Configurações gerenciadas | Rejeita `--plugin-dir` e `--plugin-url` na inicialização |
| `pluginConfigs` | Configurações do usuário ou gerenciadas | Contém valores de `userConfig` para um mod, indexados pelo id do plugin, como `acme-guard@acme-tools`, ou pelo seu nome e `@inline`, como `first-mod@inline`, para um carregado com `--plugin-dir` |
`sec-default@builtin` é uma guarda integrada ao Claude Code, listada como `cc-plugin-sec-default` em `/plugin` e no log de depuração. Ela é carregada antes de todo mod que uma pessoa instala em uma máquina com configurações gerenciadas, ou para um usuário conectado com um plano Team ou Enterprise. Se `prependPlugins` gerenciado estiver definido, a guarda só é carregada quando essa lista a indica, na posição listada. Seu código-fonte está no [diretório `mods/sec-default` do repositório do Claude Code](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).
Comandos
Estes comandos e flags carregam, inspecionam e testam um mod. Os comandos `claude` são executados no seu shell e os comandos `/` no prompt do Claude Code. Na tabela, `` representa um caminho que você digita, como em `claude plugin validate ./first-mod`. Colchetes marcam um argumento opcional.
| Comando | O que faz |
| :- | :- |
| [`/plugin`](/docs/pt/plugins/mods/overview#see-which-mods-a-session-loaded) | Mostra uma linha como `1 mod active · first-mod` abaixo de suas abas quando um mod que não é integrado foi carregado |
| [`claude plugin validate `](/docs/pt/plugins/mods/create#check-what-claude-code-reads-from-your-mod) | Lê o manifesto e o módulo de hooks de um plugin e informa erros, os eventos que ele trata e as chamadas à API de mods que ele faz. `--strict` trata avisos como erros e `--json` imprime um relatório legível por máquina. |
| [`claude plugin test [directory]`](/docs/pt/plugins/mods/test#write-a-test) | Executa todos os arquivos no diretório, ou no diretório atual quando nenhum é informado, cujo nome termina em `.test.ts` ou `.test.tsx`. Sai com status 1 quando um teste falha. |
| [`claude --plugin-dir `](/docs/pt/plugins/mods/create#write-a-mod-yourself) | Carrega um diretório de plugin para uma sessão e recarrega seu módulo de hooks quando você salva. Repita a flag para carregar vários. |
| `/reload-plugins` | Recarrega os plugins quando você o executa |