> ## 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](https://code.claude.com/docs/pt/plugins/mods/overview.md) 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.

> [!NOTE]
>
> 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](https://code.claude.com/docs/pt/plugins/mods/create.md#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](https://code.claude.com/docs/pt/plugins/manifest-reference.md) 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](https://code.claude.com/docs/pt/hooks.md) em `hooks`. |
| O módulo de hooks, como [`hooks/register.js`](https://code.claude.com/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`](https://code.claude.com/docs/pt/plugins/mods/interface#declare-the-values), a menos que `types` no manifesto indique outro caminho | Quando o mod usa `$.state` ou adiciona um namespace à API de mods | Declara os valores de `PluginState` e qualquer namespace que o mod adiciona. Para omitir `types` do manifesto, você precisa da v2.1.299 ou posterior. |
| Arquivos cujos nomes terminam em `.test.ts` ou `.test.tsx` | Não | Testes que o [`claude plugin test`](https://code.claude.com/docs/pt/plugins/mods/test#write-a-test) executa |

`register` recebe `on` e `options`. `options` contém os valores dos campos [`userConfig`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/events.md#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](https://code.claude.com/docs/pt/plugins/mods/events.md#handle-a-hook-that-fails) do hook.

| Argumento | O que é |
| :- | :- |
| [`$`](https://code.claude.com/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`](https://code.claude.com/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)`](https://code.claude.com/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`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/events.md#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`, e `message` é o texto do erro. |
| `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.' }`.

### Ferramentas

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`](https://code.claude.com/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`](https://code.claude.com/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. | `next(e)` ou `{ decision }`, com `decision` definido como `allow`, `ask` ou `deny` e um `reason` opcional |
| `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](https://code.claude.com/docs/pt/mcp.md#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. Adicione [`breakPromptCache: true`](#break-prompt-cache) para enviar uma descrição alterada no próximo turno. |

#### Campos de agente e de organização em `tool.check`

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](https://code.claude.com/docs/pt/sub-agents.md) ou um [colega de equipe em processo](https://code.claude.com/docs/pt/agent-teams.md#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](https://code.claude.com/docs/pt/mcp.md#organization-controls-on-connector-tools)

Em `tool.check`, `e.agentId` e `e.ceiling` exigem o Claude Code v2.1.290 ou posterior.

#### O campo `e.isReadOnly` em `tool.check`

Em um hook `tool.check`, `e.isReadOnly` é `true` quando a ferramenta informa esta chamada como somente leitura. Caso contrário, o campo fica ausente, e não `false`. O valor é o próprio relato da ferramenta, então leia [Verificar se uma chamada de ferramenta é somente leitura](https://code.claude.com/docs/pt/plugins/mods/events.md#check-whether-a-tool-call-is-read-only) antes de aprovar uma chamada com base apenas neste campo.

Em `tool.check`, `e.isReadOnly` exige o Claude Code v2.1.304 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`](https://code.claude.com/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`](https://code.claude.com/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. Adicione [`breakPromptCache: true`](#break-prompt-cache) para enviar uma seção alterada no próximo turno. |
| [`prompt.context`](https://code.claude.com/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`](https://code.claude.com/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](https://code.claude.com/docs/pt/skills.md#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](https://code.claude.com/docs/pt/skills.md#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](https://code.claude.com/docs/pt/plugins/mods/events.md#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.

#### Enviar uma seção do system prompt ou uma descrição de ferramenta alterada com `breakPromptCache`

Para alterar uma seção ou uma descrição de ferramenta em uma conversa em andamento, chame `$.ui.invalidate('prompt.section')` ou `$.ui.invalidate('tool.describe')` para que seu hook seja executado novamente. Retorne `{ text, breakPromptCache: true }` ou `{ description, breakPromptCache: true }` a partir dele. Sem o campo, o Claude continua lendo o texto [salvo com a conversa](https://code.claude.com/docs/pt/cli-reference.md#system-prompt-flags-in-resumed-conversations) para uma seção ou uma ferramenta carregada antecipadamente até uma nova conversa ou uma [compactação](https://code.claude.com/docs/pt/prompt-caching.md#compacting-the-conversation).

O texto alterado chega ao Claude no próximo turno, e o [cache de prompt](https://code.claude.com/docs/pt/prompt-caching.md) recomeça, então esse turno é mais lento e mais caro. O campo requer o Claude Code v2.1.321 ou posterior. Da v2.1.299 até a v2.1.321, uma conversa em andamento recebia o texto alterado no próximo turno.

### Comandos e configuração

| Evento | Dispara quando | Um hook pode retornar |
| :- | :- | :- |
| [`command.run`](https://code.claude.com/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 }` |
| [`settings.read`](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-hook) | Um mod chama [`$.settings.read`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network), ou o Claude Code monta as configurações mescladas da sessão. Requer o Claude Code v2.1.304 ou posterior na leitura do próprio Claude Code e para `e.layers` | `next(e)`, `{ value }` ou `{ deny: reason }` |

#### `e.layers` e `e.source` em `settings.read`

* **`e.layers`**: um objeto `{ source, settings }` para cada origem em uso que contém configurações, da menor [precedência](https://code.claude.com/docs/pt/settings.md#settings-precedence) para a maior. Consulte [O que um hook `settings.read` recebe](https://code.claude.com/docs/pt/plugins/mods/events#settings-read-receives).
* **`e.source`**: a única origem que um mod solicitou, como em `$.settings.read({ source: 'policy' })`. Ausente na leitura do próprio Claude Code e em uma leitura das configurações mescladas

### 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`](https://code.claude.com/docs/pt/plugins/mods/events#follow-a-turn) | Um turno começa | `next(e)` |
| [`turn.step`](https://code.claude.com/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`](https://code.claude.com/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`](https://code.claude.com/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`](https://code.claude.com/docs/pt/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/api.md#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](https://code.claude.com/docs/pt/agent-teams.md) está prestes a iniciar, ou um subagente que terminou ou foi interrompido está prestes a ser executado novamente. Para um colega de equipe, `e.isTeammate` é `true`. Para uma execução retomada, `e.resume` é definido. | `next({ ...e, model })` para escolher o modelo de um que está iniciando, ou `{ deny: reason }` |

Seu hook `agent.spawn` também é executado quando um subagente que terminou ou foi interrompido está prestes a ser executado novamente, como quando o Claude envia a ele uma mensagem com a ferramenta [`SendMessage`](https://code.claude.com/docs/pt/sub-agents#resume-subagents). Nesse evento, `e.resume` é `{ agentId }`. Se o seu hook conta subagentes, ignore os eventos em que `e.resume` está definido, para que um subagente retomado não seja contado novamente.

Retorne `{ deny: reason }` para recusar uma execução retomada. A execução não começa, e o subagente permanece como estava. Quando uma chamada de `SendMessage` solicitou a execução, o Claude lê `a plugin declined the resume:` seguido do seu motivo como o resultado dessa chamada. Se você passar um evento alterado para `next` em uma execução retomada, como um `model` diferente, o Claude Code ignora a alteração.

> [!NOTE]
>
> O evento para uma execução retomada requer o Claude Code v2.1.299 ou posterior. Antes da v2.1.299, seu hook `agent.spawn` não era executado quando um subagente era retomado. Nessas versões, para recusar as chamadas de `SendMessage` que retomam um subagente, faça a correspondência dessa ferramenta em um hook [`tool.call`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/interface.md) mostra o que um hook `ui.render` retorna:

| Evento | Dispara quando |
| :- | :- |
| [`ui.render`](https://code.claude.com/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`](https://code.claude.com/docs/pt/plugins/mods/interface#respond-to-presses-and-typing), [`ui.input`](https://code.claude.com/docs/pt/plugins/mods/interface#respond-to-presses-and-typing), [`ui.select`](https://code.claude.com/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`](https://code.claude.com/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | Um elemento `Client` envia dados para o seu mod |
| [`ui.fault`](https://code.claude.com/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`](https://code.claude.com/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](https://code.claude.com/docs/pt/hooks.md#hook-events) é um evento chamado `classic.<Event>`, 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 pode retornar `next(e)`, `{ deny: reason }` ou `{ value }`.

Alguns desses eventos também são disparados para as ações do próprio Claude Code, então verifique se `next.origin.plugin` é `engine` antes de recusar um deles.

#### Campos nas requisições `http.fetch` do próprio Claude Code

Em um hook `http.fetch`, um [`next.origin`](#the-hook-function) de `{ plugin: 'engine', tier: 'core' }` marca uma das requisições do próprio Claude Code, como uma requisição ao modelo, e não uma chamada `$.http.fetch` de um mod. Onde a [guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#know-what-happens-by-default) está carregada, seu hook não recebe esses eventos, exceto se o seu mod [contar como um mod da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#install-your-organizations-mods).

Nesses eventos, `e.init` e o `value` para o qual `next(e)` resolve podem conter estes campos, entre outros:

| Campo | O que significa |
| :- | :- |
| `e.init.compress` | Definido quando o Claude Code comprime o corpo depois do seu hook. `e.init.body` contém o corpo não comprimido. Para enviar o corpo sem compressão, chame `next({ ...e, init: { ...e.init, compress: undefined } })`. |
| `value.isStreaming` | Definido como `true` porque o próprio Claude Code lê o corpo da resposta, então `value.text` fica vazio. Em vez disso, leia `value.status` e `value.headers`. Para responder com o seu próprio `text`, retorne um `value` sem `isStreaming`. |

Esses eventos e campos exigem o Claude Code v2.1.321 ou posterior.

## 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](https://code.claude.com/docs/pt/plugins/mods/create.md#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`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/pt/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` exige o Claude Code v2.1.300 ou posterior e `place`, a v2.1.314 ou posterior. |
| [`$.theme`](https://code.claude.com/docs/pt/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: define um plano de fundo para o aplicativo Desktop ou móvel desenhar e remove o plano de fundo. Exige o Claude Code v2.1.319 ou posterior. |
| [`$.command`](https://code.claude.com/docs/pt/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
| [`$.tool`](https://code.claude.com/docs/pt/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. Quando uma `call` precisa da aprovação de uma pessoa, como uma que um hook ou a sua organização responde com `ask`, ela é resolvida com `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`, em que `<tool>` é o nome da ferramenta. |
| `$.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`](https://code.claude.com/docs/pt/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |
| [`$.prompt`](https://code.claude.com/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`](https://code.claude.com/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`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `get`, `set` |
| [`$.fs`](https://code.claude.com/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`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/interface.md#save-from-more-than-one-session). |
| [`$.state`](https://code.claude.com/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`](https://code.claude.com/docs/pt/plugins/mods/api#run-work-in-the-background) | `now`, `sleep`, `after`, `every` |
| [`$.http`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](https://code.claude.com/docs/pt/plugins/mods/api#reach-files-processes-and-the-network) | `run`, `spawn` |
| [`$.mcp`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/interface.md#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. Uma sessão que [não busca feature flags](https://code.claude.com/docs/pt/env-vars.md#features-that-need-feature-flag-fetching) precisa da versão 2.1.304 ou posterior. [Desenhar na extensão do VS Code](https://code.claude.com/docs/pt/plugins/mods/interface.md#draw-in-the-vs-code-extension) lista o que a extensão desenha de forma diferente.

| Ponto | `e.props` | `e.requestId` | Renderizado em |
| :- | :- | :- | :- |
| [`Pane`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | O `id` do painel | Terminal, Desktop, VS Code |
| [`AbovePrompt`](https://code.claude.com/docs/pt/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/pt/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Uma instância | Terminal, Desktop |
| `AbovePromptList`, a pilha de linhas `AbovePrompt` | `rows`, uma lista com um `{ plugin, tree }` para a linha de cada mod, mais as props de `AbovePrompt` | Uma instância | Terminal, Desktop. Requer Claude Code v2.1.323 ou posterior. |
| [`Placed`](https://code.claude.com/docs/pt/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | O `requestId` que `$.ui.place` retornou | Terminal |
| [`Backdrop`](https://code.claude.com/docs/pt/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Antes da v2.1.323, `scene` era `id` e `overrideColorScheme` era `colorScheme`. | `backdrop` | Superfícies `desktop` e `mobile`. Seu hook é executado quando o aplicativo Desktop ou mobile solicita desenhar um plano de fundo. |
| `UserMessage` | `text`, `origin`, `isExpanded` e `task` ou `from` conforme a origem | O id da linha desenhada | Terminal, Desktop, VS Code |
| `AssistantMessage` | O texto da resposta | O id da linha desenhada | 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 linha desenhada | Terminal, Desktop |
| [`AskUserQuestion`](https://code.claude.com/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`](https://code.claude.com/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 linha desenhada | Terminal |
| `InfoNotice` | `text`, `command` | O `text` do aviso prefixado com `notice:` | 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`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/interface.md#build-a-tree-from-elements) mostra os mais comuns com a forma como o terminal os desenha, e a [galeria da interface](https://code.claude.com/docs/pt/plugins/mods/gallery.md) 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`](https://code.claude.com/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `key`, layout flex, [`gap`, `padding`, `margin`](#box-spacing-steps), `width`, `height`, `minWidth`, `minHeight`, [`borderStyle`](#box-border-styles), `borderColor`, `borderDimColor`, `backgroundColor`, `position`, `top`, `left`, `right`, `bottom`, `overflow`, `display`, `hover` | ✓ | ✓ | ✓ |
| [`Text`](https://code.claude.com/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, [`bold`](#text-bold), `italic`, `underline`, `strikethrough`, `dimColor`, `inverse`, `wrap`, [`size`, `weight`, `mono`, `tabular`](#text-typography), `hover` | ✓ | ✓ | ✓ |
| [`Button`](https://code.claude.com/docs/pt/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `children`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `variant`, `role`, `hover` | ✓ | ✓ | ✓ |
| [`Link`](https://code.claude.com/docs/pt/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. Consulte [Limites](#limits). | ✓ | ✓ | ✓ |
| [`Code`](https://code.claude.com/docs/pt/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |
| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |
| [`Input`](https://code.claude.com/docs/pt/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, [`rows`](https://code.claude.com/docs/pt/plugins/mods/gallery#input), `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | um `source` de marcação SVG de até 131.072 caracteres, texto `alt`, `width`, `height` e `isInteractive` | | ✓ | ✓ |
| [`Client`](https://code.claude.com/docs/pt/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key`, `props`, `width`, `height`, `flexGrow` | ✓ | ✓ | |
| [`Raster`](https://code.claude.com/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](https://code.claude.com/docs/pt/plugins/mods/interface.md#draw-a-grid-of-colored-cells). | ✓ | | |
| `Image` | `key`, um `source` como bytes PNG ou RGBA de até 2 MiB, ou um caminho de arquivo, `columns` e `rows` até 255, e texto `alt`. Consulte [quais terminais o desenham](https://code.claude.com/docs/pt/plugins/mods/gallery.md#image-and-client). | ✓ | | |

Mais regras de `Button`:

* **`action`**: indica uma das próprias [ações de atalho de teclado](https://code.claude.com/docs/pt/keybindings.md) 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
* **Hotkeys numéricos na faixa**: 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
* **Uma faixa recolhida**: enquanto a faixa está [recolhida](https://code.claude.com/docs/pt/plugins/mods/interface.md#when-the-user-collapses-the-band), nem um atalho de `action` nem um hotkey pressiona um botão nela
* **Dois botões com o mesmo hotkey**: quando dois dos seus botões em um mesmo desenho indicam o mesmo `hotkey`, o posterior fica com ele. Para o botão de outro mod na mesma tecla, consulte [Hotkeys não fazem nada](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#hotkeys-do-nothing).
* **`variant`**: `primary` ou `secondary`, e qualquer outro valor lança um erro. No terminal, um botão `primary` é desenhado na cor de destaque, a menos que seja `plain`.
* **`role`**: `dismiss` marca um botão de fechar, e qualquer outro valor lança um erro. Faça o fechamento no seu `onPress`. Em uma faixa que contém texto e uma fileira de botões, o aplicativo Desktop pode desenhar o primeiro botão `dismiss` da fileira como seu próprio controle de fechar. O terminal desenha o botão como faria sem `role`.

Um `Button` pode conter `children` no lugar de um `label`:

* **O que os children podem ser**: strings e elementos `Text`, como um nome seguido de um detalhe esmaecido ou um chip colorido. O Claude Code recusa qualquer outro elemento dentro de um `Button`.
* **Nomear o botão**: o `label` nomeia o botão e, por padrão, é o texto de seus children. Dê um `key` ou um `label` a um botão com children que não sejam uma única string.
* **No terminal**: os children são desenhados onde o label estaria, e um clique em qualquer ponto deles conta como um único pressionamento, então você pode transformar cada linha de uma lista em um único botão
* **No aplicativo Desktop e na extensão do VS Code**: o botão desenha seu `label`

> [!NOTE]
>
> Um `Button` com children que não sejam uma única string exige o Claude Code v2.1.295 ou posterior.

`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` com seus `top`, `left`, `right` e `bottom`, `alignSelf`, `borderDimColor` e `hover`
* **`Text`**: `size`, `mono`, `tabular` e `hover`
* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action` e `hover`, então o usuário pressiona um botão ali com um clique, ou com Enter quando ele estiver com o foco. A extensão também ignora `variant` e `role`.
* **`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`, e `rows` em um `Input`
* **`Svg`**: `isInteractive`

### 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.

### Passos de espaçamento de `Box`

As props de espaçamento de `Box` são `gap`, `columnGap`, `rowGap`, `padding`, `margin` e as formas de um lado e de um eixo de `padding` e `margin`, como `paddingX` e `marginTop`. Cada uma aceita um número de células do terminal, como `gap: 1`, ou um nome de passo, como `gap: 'md'`. No terminal e na extensão do VS Code, cada passo corresponde a esta quantidade de células:

| Passo | Células na horizontal | Células na vertical |
| :- | :- | :- |
| `'xs'` | 1 | 0 |
| `'sm'` | 1 | 0 |
| `'md'` | 2 | 1 |
| `'lg'` | 3 | 1 |
| `'xl'` | 4 | 2 |

Se você definir `gap`, `padding` ou `margin` como um passo, o passo se aplica na horizontal e na vertical ao mesmo tempo. Por exemplo, no terminal e na extensão do VS Code, `padding: 'md'` equivale a duas células de cada lado e uma linha acima e abaixo.

Nomes de passos exigem o Claude Code v2.1.299 ou posterior. Em uma versão anterior, uma árvore que usa um nome de passo não é desenhada.

### Props de tipografia de `Text`

Defina `size`, `weight`, `mono` ou `tabular` em um `Text` para pedir ao aplicativo que desenha sua árvore um tamanho de texto, um peso, uma fonte monoespaçada ou dígitos de largura igual. Antes de depender de uma prop, verifique o que o terminal e a extensão do VS Code fazem com ela. Se um aplicativo ignorar uma prop que você definiu, sua árvore ainda é desenhada ali, com o texto como se você tivesse omitido essa prop.

| Prop | Valores | No terminal | Na extensão do VS Code |
| :- | :- | :- | :- |
| `size` | `'caption'`, `'footnote'`, `'body'`, `'heading'` ou `'title'` | Ignorada: o terminal tem um único tamanho de texto | Ignorada |
| `weight` | `'regular'`, `'medium'`, `'semibold'` ou `'bold'` | `semibold` e `bold` são desenhados como texto em negrito | `semibold` e `bold` são desenhados como texto em negrito |
| `mono` | `true` para pedir a fonte monoespaçada do aplicativo | Ignorada: o terminal é sempre monoespaçado | Ignorada, então o texto mantém a fonte própria da extensão |
| `tabular` | `true` para pedir dígitos de largura igual, para que um número que é atualizado no lugar ou uma coluna de números permaneça alinhado | Ignorada: os dígitos do terminal já têm uma célula de largura | Ignorada |

Essas quatro props exigem o Claude Code v2.1.299 ou posterior. Em uma versão anterior, uma árvore que define `size`, `weight`, `mono` ou `tabular` não é desenhada.

#### Substituir `bold` por `weight`

`bold` em um `Text` foi descontinuado em favor de `weight` e ainda funciona. Para substituí-lo em um `Text` sem `weight`, altere `bold: true` para `weight: 'semibold'` para obter o mesmo resultado no Claude Code v2.1.299 ou posterior.

Em uma versão anterior à v2.1.299, uma árvore que define `weight` não é desenhada. Se você definir tanto `bold` quanto `weight` em um `Text`, `bold` não tem efeito.

## 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. Uma árvore acima do limite de aninhamento, de elementos, de células de `Raster` ou de bytes de `Image` [não é desenhada](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty).

| 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](https://code.claude.com/docs/pt/hooks.md#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 |
| `stdout` e `stderr` de `$.process.run` | 4 MiB cada. `isStdoutTruncated` ou `isStderrTruncated` é `true` quando um deles foi cortado. |
| `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](https://code.claude.com/docs/pt/plugins/mods/events.md#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 hook `ui.render` que o retornou [falha](https://code.claude.com/docs/pt/plugins/mods/events.md#handle-a-hook-that-fails). |
| O `href` de um `Link` | 2.048 caracteres. Se for mais longo, o hook `ui.render` que o retornou [falha](https://code.claude.com/docs/pt/plugins/mods/events.md#handle-a-hook-that-fails). |
| Profundidade de aninhamento de uma árvore | 32 níveis abaixo do elemento raiz |
| Elementos e filhos de texto em uma árvore | 20.000 |
| Células de `Raster` em uma árvore, o `columns` de cada `Raster` multiplicado pelo seu `rows` | 262.144 |
| As linhas acima do prompt, empilhadas | Elementos, células de `Raster` e bytes de `Image` se somam entre as linhas, em relação aos limites de uma árvore |
| Bytes PNG ou RGBA de todas as `Image`s em uma árvore | 2 MiB |
| `$.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 }`. No [renderizador clássico](https://code.claude.com/docs/pt/fullscreen.md#enable-fullscreen-rendering), um toast mais recente de um mod pode [tomar o lugar do mais antigo](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear) que está sendo exibido ou aguardando para ser exibido. |
| 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 |
| Linhas de `$.ui.place` que um mod tem em uma conversa ao mesmo tempo | 500. No limite, uma chamada com um novo `id` é resolvida como `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`. |
| Profundidade de aninhamento dos argumentos de uma chamada à API de mods | 28.000 níveis. Além disso, a chamada é rejeitada com uma mensagem que termina em `nesting deeper than 28000 levels is not supported`. Requer o Claude Code v2.1.299 ou posterior. |
| Profundidade de aninhamento de um evento alterado passado para `next`, fora de [hooks de gerador assíncrono](#events) como um em `turn.step` | 28.000 níveis. Além disso, `next` é rejeitado com uma mensagem que termina em `nesting deeper than 28000 levels is not supported`. Requer o Claude Code v2.1.299 ou posterior. |
| Profundidade de aninhamento do valor de retorno de um hook, fora de `ui.render`, `ui.resolve` e hooks de gerador assíncrono | 28.000 níveis. Além disso, o resultado do hook é recusado, e [o aviso que o relata](https://code.claude.com/docs/pt/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing) inclui `nesting deeper than 28000 levels is not supported`. Requer o Claude Code v2.1.299 ou posterior. |
| 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, o `id` de uma linha posicionada e o `scene` de um pano de fundo | 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 | Se os mods são recarregados ao salvar. Consulte a [referência de variáveis de ambiente](https://code.claude.com/docs/pt/env-vars.md) para os padrões e valores |
| `prependPlugins`, `appendPlugins` | Configurações gerenciadas. Configurações do usuário somente em uma máquina sem configurações gerenciadas nem arquivo [`managed-mcp.json`](https://code.claude.com/docs/pt/managed-mcp#deploy-managed-mcp-json), em uma sessão cuja credencial não é um `/login` 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](https://code.claude.com/docs/pt/plugins/mods/events.md#the-order-mods-run-in). |
| `allowManagedModsOnly` | Configurações gerenciadas, como uma [opção da guarda integrada](https://code.claude.com/docs/pt/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Somente mods que [contam como da sua organização](https://code.claude.com/docs/pt/plugins/mods/admin.md#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](https://code.claude.com/docs/pt/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Permite que um mod instalado por um usuário aprove uma chamada de ferramenta passando por cima da maioria dos [resultados que permanecem em vigor por padrão](https://code.claude.com/docs/pt/permissions.md#precedence-among-rules-hooks-and-mods), incluindo uma regra `deny` |
| `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](https://code.claude.com/docs/pt/settings-reference.md#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`](https://code.claude.com/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. [Onde ela é carregada](https://code.claude.com/docs/pt/plugins/mods/admin.md#know-what-happens-by-default), ela é executada antes de todo mod que uma pessoa instala. 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, `<directory>` representa um caminho que você digita, como em `claude plugin validate ./first-mod`. Colchetes marcam um argumento opcional.

| Comando | O que faz |
| :- | :- |
| [`/plugin`](https://code.claude.com/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 <directory>`](https://code.claude.com/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]`](https://code.claude.com/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 <directory>`](https://code.claude.com/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 |
