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

# Riferimento dei mod

> Riferimento completo per i mod di Claude Code: struttura del modulo degli hook, eventi, metodi dell'API dei mod, punti di rendering, elementi per superficie, limiti e impostazioni.

Consulta qualsiasi evento che un [mod](https://code.claude.com/docs/it/plugins/mods/overview.md) può gestire, qualsiasi metodo dell'API dei mod che può chiamare o qualsiasi punto di rendering in cui può disegnare. Le voci coprono la CLI di Claude Code e l'app Desktop a partire dalla v2.1.290, e l'estensione VS Code a partire dalla v2.1.299. Ogni voce riporta il nome e una descrizione di una riga e, dove presente, rimanda alla sezione della guida che lo spiega.

> [!NOTE]
>
> Il riferimento completo sono le [dichiarazioni TypeScript per i mod](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts) di Claude Code, che descrivono ogni evento, metodo ed elemento, con esempi. La copia su GitHub può essere più vecchia della versione di Claude Code che hai installato. Quando le due non coincidono, fai affidamento sulla [copia che Claude Code scrive per la tua versione](https://code.claude.com/docs/it/plugins/mods/create.md#get-the-types-for-your-build).

## File

Un mod è una directory di plugin con questi file:

| File | Obbligatorio | Contenuto |
| :- | :- | :- |
| `.claude-plugin/plugin.json` | Sì | Il [manifest](https://code.claude.com/docs/it/plugins/manifest-reference.md) del plugin. I mod non aggiungono campi obbligatori. |
| `hooks/hooks.json` | Sì | `modules`: un array con un percorso, relativo a questo file, al modulo degli hook, come in `"modules": ["./register.js"]`. Può contenere anche [hook delle impostazioni](https://code.claude.com/docs/it/hooks.md) sotto `hooks`. |
| Il modulo degli hook, ad esempio [`hooks/register.js`](https://code.claude.com/docs/it/plugins/mods/create#write-a-mod-yourself) | Sì | Il punto di ingresso del mod. Esporta `register(on, options)`. Con estensione `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` o `.tsx`. Un modulo ES. |
| [`types/index.d.ts`](https://code.claude.com/docs/it/plugins/mods/interface#declare-the-values), a meno che `types` nel manifest non indichi un altro percorso | Quando il mod usa `$.state` o aggiunge un namespace all'API dei mod | Dichiara i valori di `PluginState` e qualsiasi namespace aggiunto dal mod. Per omettere `types` dal manifest, ti serve la v2.1.299 o successiva. |
| File i cui nomi terminano con `.test.ts` o `.test.tsx` | No | Test eseguiti da [`claude plugin test`](https://code.claude.com/docs/it/plugins/mods/test#write-a-test) |

`register` riceve `on` e `options`. `options` contiene i valori dei campi [`userConfig`](https://code.claude.com/docs/it/plugins/components#user-configuration) dichiarati dal manifest, con i valori predefiniti compilati.

## La funzione hook

Un mod registra ciascuno dei suoi hook, che sono gestori di eventi, chiamando `on` all'interno di `register`. `on` accetta il nome dell'evento, un [matcher](https://code.claude.com/docs/it/plugins/mods/events.md#filter-which-events-a-hook-handles) facoltativo, che è un filtro sui campi dell'evento, e l'hook, come in `on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))`. `on` restituisce una registrazione con un solo metodo, `.catch(handler)`, che imposta il [gestore degli errori](https://code.claude.com/docs/it/plugins/mods/events.md#handle-a-hook-that-fails) dell'hook.

| Argomento | Che cos'è |
| :- | :- |
| [`$`](https://code.claude.com/docs/it/plugins/mods/events#how-a-hook-handles-an-event) | L'API dei mod: ogni metodo in [metodi dell'API dei mod](#mods-api-methods). Scrivi ogni chiamata per intero, prima il namespace e poi il metodo, come in `$.fs.read('notes.md')`. |
| [`e`](https://code.claude.com/docs/it/plugins/mods/events#how-a-hook-handles-an-event) | L'input dell'evento, come dati semplici congelati in profondità. Per modificarlo, passa una copia a `next`. |
| [`next(e)`](https://code.claude.com/docs/it/plugins/mods/events#how-a-hook-handles-an-event) | Il gestore successivo, come in un middleware. Esegue gli hook successivi a questo, poi il comportamento di Claude Code. Si risolve nel risultato dell'evento. |
| [`next.signal`](https://code.claude.com/docs/it/plugins/mods/api#stop-background-work) | Un `AbortSignal` che si interrompe quando l'evento viene abbandonato |
| `next.origin` | `{ plugin, tier }` di chi ha generato l'evento. Claude Code stesso è `{ plugin: 'engine', tier: 'core' }`. Il `tier` di un mod è il suo gruppo di priorità nell'[ordine in cui vengono eseguiti i mod](https://code.claude.com/docs/it/plugins/mods/events.md#the-order-mods-run-in): `prepend`, `user`, `append` o `builtin`. |
| `next.budget` | Il limite di tempo dell'hook in millisecondi: `next.budget.ms` è il limite complessivo e `next.budget.remainingMs` è il tempo rimanente in quel momento |
| `next.to(e, tier)` | Salta a un tier successivo, che può essere `append`, `builtin` o `core`. `next.to(e, 'append')` salta i mod installati da un utente. Solo un mod in `prependPlugins` o `appendPlugins` può chiamarlo. |
| `next.error` | Solo in un gestore `.catch`. `kind` è `throw` o `timeout` e `message` è il testo dell'errore. |
| `next.called` | Solo in un gestore `.catch`. `true` quando l'hook aveva chiamato `next`. |

## Eventi

Gli eventi sono raggruppati in base a ciò che riguardano, ciascuno con il momento in cui si attiva e ciò che un hook su di esso può restituire. Gli hook su `turn.step` e `process.spawn` sono generatori asincroni, mentre gli altri hook sono funzioni asincrone.

L'ultima colonna di ogni tabella usa una notazione abbreviata. `next(e)` passa l'evento senza modificarlo. `next({ ...e, text })` passa una copia con il campo indicato modificato, come in `next({ ...e, text: e.text.trim() })`. Un oggetto risponde all'evento senza chiamare `next`, e una parola come `reason` indica una stringa che scrivi tu, come in `{ deny: 'Use the file tools.' }`.

### Strumenti

Gli eventi degli strumenti si attivano attorno a ogni chiamata a uno strumento effettuata da Claude, dalla descrizione che Claude legge fino alla decisione se la chiamata viene eseguita:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| [`tool.call`](https://code.claude.com/docs/it/plugins/mods/events#guard-or-change-a-tool-call) | Uno strumento sta per essere eseguito | `next(e)`, `{ deny: reason }` oppure `{ result }` |
| [`tool.check`](https://code.claude.com/docs/it/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code decide se una chiamata a uno strumento può essere eseguita, dopo gli hook `tool.call` e `PreToolUse`. `next(e)` si risolve nella decisione raggiunta dalle regole, dalla modalità di permesso e da quegli hook. | `next(e)` oppure `{ decision }`, con `decision` impostato su `allow`, `ask` o `deny` e un `reason` facoltativo |
| `tool.describe` | Una volta per ogni strumento, quando la sua descrizione viene inviata per la prima volta a Claude. Una seconda volta per uno strumento MCP quando Claude lo carica tramite la [ricerca degli strumenti](https://code.claude.com/docs/it/mcp.md#scale-with-mcp-tool-search), con `e.description` impostato sul testo che Claude legge per lo strumento caricato. | `{ description }`, facoltativamente con `isDeferred` impostato su `true` per mettere lo strumento dietro la ricerca degli strumenti o su `false` per caricarlo subito. Aggiungi [`breakPromptCache: true`](#break-prompt-cache) per inviare una descrizione modificata al turno successivo. |

#### Campi dell'agente e dell'organizzazione su `tool.check`

In un hook `tool.check`, leggi questi campi per distinguere la chiamata di un subagent da quella della conversazione principale e per verificare se la tua organizzazione richiede l'approvazione per uno strumento di un connettore:

* **`e.agentId`**: impostato quando la chiamata viene effettuata da un [subagent](https://code.claude.com/docs/it/sub-agents.md) o da un [membro del team in-process](https://code.claude.com/docs/it/agent-teams.md#choose-a-display-mode), e assente quando la effettua la conversazione principale
* **`e.ceiling`**: `ask` per uno strumento di un connettore che la tua organizzazione ha impostato su `ask`, nelle [sessioni in cui tale impostazione raggiunge Claude Code](https://code.claude.com/docs/it/mcp.md#organization-controls-on-connector-tools)

Su `tool.check`, `e.agentId` e `e.ceiling` richiedono Claude Code v2.1.290 o versioni successive.

#### Il campo `e.isReadOnly` su `tool.check`

In un hook `tool.check`, `e.isReadOnly` è `true` quando lo strumento segnala questa chiamata come di sola lettura. Altrimenti il campo è assente, non `false`. Il valore è ciò che segnala lo strumento stesso, quindi leggi [Verificare se una chiamata a uno strumento è di sola lettura](https://code.claude.com/docs/it/plugins/mods/events.md#check-whether-a-tool-call-is-read-only) prima di approvare una chiamata basandoti solo su questo campo.

Su `tool.check`, `e.isReadOnly` richiede Claude Code v2.1.304 o versioni successive.

### Prompt e ciò che Claude legge

Gli eventi dei prompt riguardano il testo che l'utente digita e il testo che Claude Code invia a Claude di propria iniziativa, come il prompt di sistema e i promemoria:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| [`prompt.submit`](https://code.claude.com/docs/it/plugins/mods/events#rewrite-or-add-to-a-prompt) | Viene inviato un prompt | `next({ ...e, text })`, `next({ ...e, context })` oppure `{ drop: reason }` |
| `prompt.fill`, `prompt.suggest` | Del testo sta per essere inserito nella casella del prompt come bozza o come suggerimento attenuato | `next(e)` con il testo modificato |
| `prompt.edit` | L'utente modifica la casella del prompt | `next(e)` |
| `prompt.autocomplete` | L'utente digita nella casella del prompt e una parola termina in corrispondenza del cursore. `e.token` è quella parola. Claude Code non attende l'hook: le sue righe di completamento automatico vengono mostrate per prime. | `{ suggestions }`, un elenco di righe `{ text, label, description }` mostrate sotto quelle di Claude Code. La scelta di una riga sostituisce la parola con il suo `text`. |
| `prompt.compose` | Claude Code genera un prompt di sistema | `{ sections }`, un elenco di `{ id, text, scope }` nell'ordine in cui vengono inviati |
| [`prompt.section`](https://code.claude.com/docs/it/plugins/mods/events#rewrite-or-add-to-a-prompt) | Una volta per ogni sezione con nome del prompt di sistema. `e.name` è l'`id` della sezione in `prompt.compose`. | `{ text }` oppure `{ text: null }` per omettere la sezione. Aggiungi [`breakPromptCache: true`](#break-prompt-cache) per inviare una sezione modificata al turno successivo. |
| [`prompt.context`](https://code.claude.com/docs/it/plugins/mods/events#rewrite-or-add-to-a-prompt) | Una volta per ogni conversazione, per il contesto inviato con il primo messaggio | `{ blocks }` |
| `prompt.attachment` | Claude Code aggiunge un proprio messaggio per Claude, come un promemoria. `e.type` indica il tipo e, per i tipi dichiarati dalle definizioni dei tipi, `e.detail` contiene i dati a partire dai quali è stato scritto il testo. | `{ text }` oppure `{ text: null }` per ometterlo |
| `prompt.mention` | Claude Code sta per leggere un file menzionato con @ in un prompt. Richiede Claude Code v2.1.290 o versioni successive. | `next({ ...e, path })` per leggere un file diverso, oppure `{ deny: reason }` |
| [`skill.prompt`](https://code.claude.com/docs/it/plugins/mods/events#rewrite-or-add-to-a-prompt) | Il testo di una skill viene espanso per Claude | `{ text }` |
| `attribution.text` | Claude Code compone il testo di attribuzione di un commit o di una pull request | `{ text }` |

#### Campi di origine e frontmatter su `skill.prompt`

In un hook `skill.prompt`, puoi leggere questi campi insieme al nome della skill in `e.skill` e al testo che Claude legge in `e.text`:

| Campo | Tipo | Cosa contiene |
| :- | :- | :- |
| `e.source` | string | Chi fornisce la skill: `policySettings`, `userSettings` o `projectSettings` per una skill rispettivamente nella [posizione](https://code.claude.com/docs/it/skills.md#where-skills-live) enterprise, personale o di progetto. Le altre origini restituiscono una parola come `plugin`, `mcp`, `syncedSkills` o `built-in`. |
| `e.pluginName` | string | Il nome del plugin, per una skill il cui `e.source` è `plugin` |
| `e.path` | string | Il percorso assoluto del file `SKILL.md` della skill, o del suo file `.md` per una skill scritta come [file di comando](https://code.claude.com/docs/it/skills.md#where-skills-live). Assente quando la skill non ha alcun file su questa macchina, come nel caso di una skill integrata. |
| `e.frontmatter` | object | Il frontmatter del file della skill, come dati semplici |
| `e.frontmatterProblem` | string | Il motivo per cui in `e.frontmatter` manca il frontmatter del file o una delle sue chiavi, come in `is a list or a single value, not a table`. Assente quando `e.frontmatter` contiene l'intero frontmatter o quando la skill non ne ha. |

Un hook può passare un `text` o un `frontmatter` modificato a `next`: gli hook successivi leggono entrambi e Claude legge il `text` finale. Un hook che modifica qualsiasi altro campo [non riesce](https://code.claude.com/docs/it/plugins/mods/events.md#handle-a-hook-that-fails).

Su `skill.prompt`, `e.source`, `e.pluginName`, `e.path`, `e.frontmatter` e `e.frontmatterProblem` richiedono Claude Code v2.1.299 o versioni successive.

#### Inviare una sezione del prompt di sistema o una descrizione di uno strumento modificata con `breakPromptCache`

Per modificare una sezione o la descrizione di uno strumento in una conversazione in corso, chiama `$.ui.invalidate('prompt.section')` o `$.ui.invalidate('tool.describe')` in modo che il tuo hook venga eseguito di nuovo. Restituisci da esso `{ text, breakPromptCache: true }` oppure `{ description, breakPromptCache: true }`. Senza il campo, Claude continua a leggere il testo [salvato con la conversazione](https://code.claude.com/docs/it/cli-reference.md#system-prompt-flags-in-resumed-conversations) per una sezione o per uno strumento caricato subito, fino a una nuova conversazione o a una [compattazione](https://code.claude.com/docs/it/prompt-caching.md#compacting-the-conversation).

Il testo modificato raggiunge Claude al turno successivo e la [cache del prompt](https://code.claude.com/docs/it/prompt-caching.md) riparte da zero, quindi quel turno è più lento e più costoso. Il campo richiede Claude Code v2.1.321 o versioni successive. Dalla v2.1.299 fino alla v2.1.321, una conversazione in corso riceveva il testo modificato al turno successivo.

### Comandi e configurazione

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| [`command.run`](https://code.claude.com/docs/it/plugins/mods/api#add-a-command) | Un comando sta per essere eseguito | `{ text }`, `{}` oppure `next(e)` |
| `command.describe` | Una volta per ogni comando, per l'elenco dei comandi | `{ description, argumentHint, isHidden }` |
| `config.set` | Una riga di `/config` sta per cambiare | `next({ ...e, value })` oppure `{ deny: reason }` |
| `config.describe` | Una volta per ogni riga di `/config` | `{ label, description, isHidden }` |
| [`settings.read`](https://code.claude.com/docs/it/plugins/mods/events#settings-read-hook) | Un mod chiama [`$.settings.read`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network), oppure Claude Code costruisce le impostazioni unite della sessione. Richiede Claude Code v2.1.304 o versioni successive per la lettura effettuata da Claude Code stesso e per `e.layers` | `next(e)`, `{ value }` oppure `{ deny: reason }` |

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

* **`e.layers`**: un oggetto `{ source, settings }` per ogni origine in uso che contiene impostazioni, a partire da quella con la [precedenza](https://code.claude.com/docs/it/settings.md#settings-precedence) più bassa. Consulta [Cosa riceve un hook `settings.read`](https://code.claude.com/docs/it/plugins/mods/events#settings-read-receives).
* **`e.source`**: l'unica origine richiesta da un mod, come in `$.settings.read({ source: 'policy' })`. Assente nella lettura effettuata da Claude Code stesso e in una lettura delle impostazioni unite

### Turni

Gli eventi dei turni seguono una risposta dall'inizio alla fine, inclusa ogni richiesta al modello al suo interno:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| [`turn.start`](https://code.claude.com/docs/it/plugins/mods/events#follow-a-turn) | Inizia un turno | `next(e)` |
| [`turn.step`](https://code.claude.com/docs/it/plugins/mods/events#follow-a-turn) | Una richiesta sta per essere inviata al modello | `yield* next(e)`, oppure `next({ ...e, model })`, `next({ ...e, effort })` |
| [`turn.complete`](https://code.claude.com/docs/it/plugins/mods/events#follow-a-turn) | Un turno è terminato | `next(e)` oppure `{ text }` per mostrare una riga sotto la risposta |

### Sessione

Gli eventi della sessione segnano l'avvio, la fine e la compattazione della sessione e lo scambio di messaggi con altre sessioni:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| [`session.start`](https://code.claude.com/docs/it/plugins/mods/api#add-a-command-or-a-tool) | Una volta per ogni mod caricato, prima del primo prompt, e di nuovo dopo un ricaricamento di quel mod. Non dopo `/clear`, `/resume` o `/branch`. | `next(e)` |
| `session.end` | La sessione termina, oppure viene eseguito `/clear`, `/resume` o `/branch`. `e.reason` è `clear`, `resume`, `logout`, `prompt_input_exit` o `other`. `/branch` riporta `resume`. | `next(e)` |
| `session.compact` | La conversazione sta per essere compattata | `{ skip: reason }` |
| [`session.receive`](https://code.claude.com/docs/it/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](https://code.claude.com/docs/it/plugins/mods/api#send-and-receive-messages-between-sessions) | Un messaggio arriva da un altro agente o da un'altra sessione, o sta per esservi inviato. Consulta [Inviare e ricevere messaggi tra sessioni](https://code.claude.com/docs/it/plugins/mods/api.md#send-and-receive-messages-between-sessions). | `{ consumed: reason }` per `receive`, `{ isDelivered: false, reason }` per `send` |
| `session.append` | Una volta per ogni riga che la conversazione conserva, come un prompt, un blocco di risposta, il risultato di uno strumento o un avviso, prima che venga memorizzata | `next({ ...e, message })` con un `message.content` modificato, per riscrivere i blocchi di testo della riga o il `content` di un blocco `tool_result` al suo interno |
| `session.attach`, `session.detach` | Un'altra app si connette alla sessione o si disconnette da essa | `next(e)` |
| `session.measure` | Dopo ogni turno e quando cambia la percentuale utilizzata di un limite del piano | `next(e)` |

### Subagent

Gli eventi dei subagent si attivano quando un tipo di subagent viene offerto a Claude e quando un subagent o un membro di un team di agenti sta per avviarsi:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| `agent.offer` | Un tipo di subagent viene offerto a Claude | `{ isOffered: false }` per non renderlo disponibile |
| `agent.spawn` | Un subagent o un membro di un [team di agenti](https://code.claude.com/docs/it/agent-teams.md) sta per avviarsi, oppure un subagent che ha terminato o è stato interrotto sta per essere eseguito di nuovo. Per un membro del team, `e.isTeammate` è `true`. Per un'esecuzione ripresa, `e.resume` è impostato. | `next({ ...e, model })` per scegliere il modello di uno che si sta avviando, oppure `{ deny: reason }` |

Il tuo hook `agent.spawn` viene eseguito anche quando un subagent che ha terminato o è stato interrotto sta per essere eseguito di nuovo, ad esempio quando Claude gli invia un messaggio con lo strumento [`SendMessage`](https://code.claude.com/docs/it/sub-agents#resume-subagents). In quell'evento, `e.resume` è `{ agentId }`. Se il tuo hook conta i subagent, salta gli eventi in cui `e.resume` è impostato, in modo che un subagent ripreso non venga conteggiato di nuovo.

Restituisci `{ deny: reason }` per rifiutare un'esecuzione ripresa. L'esecuzione non si avvia e il subagent rimane com'era. Quando l'esecuzione è stata richiesta da una chiamata a `SendMessage`, Claude legge `a plugin declined the resume:` seguito dal tuo motivo come risultato di quella chiamata. Se passi un evento modificato a `next` per un'esecuzione ripresa, ad esempio un `model` diverso, Claude Code ignora la modifica.

> [!NOTE]
>
> L'evento per un'esecuzione ripresa richiede Claude Code v2.1.299 o versioni successive. Prima della v2.1.299, il tuo hook `agent.spawn` non veniva eseguito quando un subagent veniva ripreso. In quelle versioni, per rifiutare le chiamate a `SendMessage` che riprendono un subagent, individua quello strumento in un hook [`tool.call`](https://code.claude.com/docs/it/plugins/mods/events#guard-or-change-a-tool-call).

### Interfaccia

Gli eventi dell'interfaccia si attivano quando Claude Code disegna un punto di rendering e quando l'utente usa un controllo disegnato da un mod. [Disegnare nell'interfaccia](https://code.claude.com/docs/it/plugins/mods/interface.md) mostra cosa restituisce un hook `ui.render`:

| Evento | Si attiva quando |
| :- | :- |
| [`ui.render`](https://code.claude.com/docs/it/plugins/mods/interface#pick-where-to-draw) | Un [punto di rendering](#render-sites) sta per essere disegnato |
| `ui.resolve` | I mod vengono caricati, una volta per ogni app, punto di rendering e mod. Il risultato è la tabella degli elementi letta da `$.ui.resolve(e)`. |
| [`ui.press`](https://code.claude.com/docs/it/plugins/mods/interface#respond-to-presses-and-typing), [`ui.input`](https://code.claude.com/docs/it/plugins/mods/interface#respond-to-presses-and-typing), [`ui.select`](https://code.claude.com/docs/it/plugins/mods/interface#respond-to-presses-and-typing) | Viene usato un `Button`, un `Input` o un `Select` disegnato da un mod |
| `ui.focus`, `ui.scroll` | Il controllo con il focus o la posizione di scorrimento di un pannello o della banda sta per cambiare |
| `ui.close` | Un pannello sta per chiudersi. `e.id` è il pannello e `e.origin.kind` è `plugin`, `person` o `unload`. |
| [`ui.message`](https://code.claude.com/docs/it/plugins/mods/interface#build-a-tree-from-elements) | Un elemento `Client` invia dati al proprio mod |
| [`ui.fault`](https://code.claude.com/docs/it/plugins/mods/interface#redraw-when-something-changes) | Un elemento `Client` disegnato dal tuo mod non è riuscito a caricarsi, a essere disegnato o a essere eseguito. `e.phase` è `load`, `render` o `run`, e `e.reason` è il messaggio di errore. Richiede Claude Code v2.1.289 o versioni successive. |

### Altri mod

Questi eventi consentono a un mod di agire sugli altri mod mentre vengono caricati, per rifiutarne uno o modificare l'API dei mod che riceve:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| [`plugin.register`](https://code.claude.com/docs/it/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | Un modulo degli hook sta per essere caricato. `e.uses` elenca i suoi eventi, le chiamate all'API dei mod, le variabili d'ambiente e lo stato, così come li stampa `claude plugin validate`. Ogni chiamata è scritta senza il prefisso `$.`, ad esempio `fs.read`. | `{ refuse: reason }` |
| `engine.create` | L'API dei mod viene costruita per questo mod | Un'API dei mod modificata, per aggiungere un namespace. Un mod al di fuori del [livello](#the-hook-function) `user` può anche escluderne uno. |

Quando l'hook di un altro mod chiama un metodo su un namespace che hai aggiunto in `engine.create`, le chiamate `$` del tuo metodo vengono eseguite nel contesto di quell'hook finché ogni hook su quell'evento non ha restituito un risultato. Ad esempio, un percorso relativo viene risolto rispetto alla directory di lavoro di quell'hook, e `$.prompt.submit` viene rifiutata mentre il turno è in attesa di quell'hook. Le chiamate che il tuo metodo effettua dopo quel momento vengono eseguite nel contesto proprio del tuo mod.

### Telemetria

Gli eventi di telemetria si attivano per i record di utilizzo che Claude Code registra nei log:

| Evento | Si attiva quando | Un hook può restituire |
| :- | :- | :- |
| `telemetry.log`, `telemetry.mark` | Un record di telemetria sta per essere registrato nei log, oppure viene contrassegnato un utilizzo di una funzionalità. In un mod che installi, assegna a un hook di telemetria il filtro `{ to: 'collector' }`, come in `on('telemetry.log', { to: 'collector' }, hook)`. Senza il filtro, il mod non supera `claude plugin validate`. `*` non corrisponde a questi eventi. | `next(e)` oppure `{ deny: reason }` |

### Eventi degli hook delle impostazioni

Ogni [evento degli hook delle impostazioni](https://code.claude.com/docs/it/hooks.md#hook-events) è un evento denominato `classic.<Event>`, come `classic.Stop` o `classic.PostToolUse`. `e` è il JSON dello stdin dell'hook.

### Chiamate all'API dei mod

Ogni [metodo dell'API dei mod](#mods-api-methods) è anche un evento, denominato in base al suo namespace e al metodo, come `fs.read`, `model.complete` o `ui.open`. Un hook su uno di essi può restituire `next(e)`, `{ deny: reason }` oppure `{ value }`.

Alcuni di questi eventi si attivano anche per le azioni di Claude Code stesso, quindi verifica se `next.origin.plugin` è `engine` prima di rifiutarne uno.

#### Campi sulle richieste `http.fetch` di Claude Code stesso

In un hook `http.fetch`, un [`next.origin`](#the-hook-function) pari a `{ plugin: 'engine', tier: 'core' }` contrassegna una delle richieste di Claude Code stesso, come una richiesta al modello, e non una chiamata `$.http.fetch` di un mod. Dove è caricata la [protezione integrata](https://code.claude.com/docs/it/plugins/mods/admin.md#know-what-happens-by-default), il tuo hook non riceve questi eventi a meno che il tuo mod non [sia considerato un mod della tua organizzazione](https://code.claude.com/docs/it/plugins/mods/admin.md#install-your-organizations-mods).

In questi eventi, `e.init` e il `value` in cui si risolve `next(e)` possono contenere, tra gli altri, questi campi:

| Campo | Cosa significa |
| :- | :- |
| `e.init.compress` | Impostato quando Claude Code comprime il corpo dopo il tuo hook. `e.init.body` contiene il corpo non compresso. Per inviare il corpo non compresso, chiama `next({ ...e, init: { ...e.init, compress: undefined } })`. |
| `value.isStreaming` | Impostato su `true` perché Claude Code legge da sé il corpo della risposta, quindi `value.text` è vuoto. Leggi invece `value.status` e `value.headers`. Per rispondere con il tuo `text`, restituisci un `value` senza `isStreaming`. |

Questi eventi e campi richiedono Claude Code v2.1.321 o versioni successive.

## Metodi dell'API dei mod

L'API dei mod è l'argomento `$` che ogni hook riceve. I suoi metodi sono raggruppati in namespace, come `$.ui`. Questa tabella elenca i metodi di ogni namespace per nome, quindi `open` nella riga `$.ui` corrisponde alla chiamata `$.ui.open(...)`. Le guide mostrano l'uso di quelli più comuni, e [i tipi per la tua build](https://code.claude.com/docs/it/plugins/mods/create.md#get-the-types-for-your-build) documentano ogni metodo con un esempio.

| Namespace | Metodi |
| :- | :- |
| `$.plugin` | `name`, `root`: il nome e la directory di questo plugin |
| [`$.ui`](https://code.claude.com/docs/it/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/it/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` richiede Claude Code v2.1.300 o versioni successive e `place` v2.1.314 o versioni successive. |
| [`$.theme`](https://code.claude.com/docs/it/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: imposta uno sfondo che l'app Desktop o mobile disegna, e rimuove lo sfondo. Richiede Claude Code v2.1.319 o versioni successive. |
| [`$.command`](https://code.claude.com/docs/it/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
| [`$.tool`](https://code.claude.com/docs/it/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. Quando una `call` richiede l'approvazione di una persona, ad esempio una a cui un hook o la tua organizzazione risponde con `ask`, si risolve con `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`, dove `<tool>` è il nome dello strumento. |
| `$.agent` | `register`, `spawn`, `list`. `list()` restituisce i subagent e i compagni di squadra di questa sessione, ciascuno con uno `status` tra `pending`, `running`, `waiting`, `idle`, `completed`, `failed` o `killed`, dove `idle` e `waiting` richiedono Claude Code v2.1.289 o versioni successive. |
| [`$.model`](https://code.claude.com/docs/it/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |
| [`$.prompt`](https://code.claude.com/docs/it/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude legge il testo di `submit({ text })` dopo una frase che indica il tuo mod come mittente. `submit({ text, asUser: true })` invia il testo come parole dell'utente stesso, senza quella frase. |
| `$.turn` | `abort` |
| [`$.session`](https://code.claude.com/docs/it/plugins/mods/api#send-and-receive-messages-between-sessions) | `messages`, `cwd`, `root`, `model`, `turns`, `id`, `repo`, `surfaces`, `usage`, `version`, `compact`, `send`, `append`, `authorize`. `usage()` restituisce `{ startedAt, context, rateLimits, cost }`: `context` contiene `tokens`, `window` e `percent`, e `rateLimits` è un elenco di `{ kind, percentUsed, resetsAt }`. |
| `$.config` | `list`, `set` |
| [`$.settings`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network) | `get`, `set` |
| [`$.fs`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network) | `read`, `write`, `list`, `exists`, `stat`, `ancestors`. `write` non è atomico: sostituisce il contenuto del file sul posto, quindi un altro processo può leggere un file scritto solo in parte. Conserva in `$.store` i dati modificati da più sessioni. |
| [`$.store`](https://code.claude.com/docs/it/plugins/mods/interface#keep-state) | `get`, `set`, `delete`, `keys`. Un archivio chiave-valore condiviso da tutte le sessioni sulla macchina. Consulta [Salvare da più di una sessione](https://code.claude.com/docs/it/plugins/mods/interface.md#save-from-more-than-one-session). |
| [`$.state`](https://code.claude.com/docs/it/plugins/mods/interface#keep-a-value-in-\$-state) | Stato reattivo: `get`, `set`, con gli helper `atom`, `read`, `update`, `derive` e `memberOf` importati da `claude-code` |
| [`$.clock`](https://code.claude.com/docs/it/plugins/mods/api#run-work-in-the-background) | `now`, `sleep`, `after`, `every` |
| [`$.http`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network) | `run`, `spawn` |
| [`$.mcp`](https://code.claude.com/docs/it/plugins/mods/api#reach-files-processes-and-the-network) | `call`, `connect`. `connect(server)` connette un server MCP elencato nel manifest del tuo plugin. |
| `$.audio` | `play`, `speak` |
| `$.telemetry` | `log`, `mark`. Un record viene inviato solo quando la chiamata è effettuata da Claude Code o da un mod integrato. |

## Punti di rendering

Un punto di rendering è un punto di estensione nell'interfaccia di Claude Code. Ogni riga è un valore di `e.component` in un hook `ui.render`, con i campi di `e.props` e le app che lo visualizzano. `e.surface` indica l'app che sta disegnando, come `terminal`, `desktop` o `vscode`. [Modificare ciò che Claude Code disegna già](https://code.claude.com/docs/it/plugins/mods/interface.md#change-what-claude-code-already-draws) mostra cosa può fare un hook in un punto, con un esempio per ciascuna scelta.

Il rendering nell'estensione VS Code richiede la versione 2.1.299 o successiva dell'estensione. Una sessione che [non recupera i feature flag](https://code.claude.com/docs/it/env-vars.md#features-that-need-feature-flag-fetching) richiede la versione 2.1.304 o successiva. [Disegnare nell'estensione VS Code](https://code.claude.com/docs/it/plugins/mods/interface.md#draw-in-the-vs-code-extension) elenca ciò che l'estensione disegna in modo diverso.

| Punto | `e.props` | `e.requestId` | Visualizzato su |
| :- | :- | :- | :- |
| [`Pane`](https://code.claude.com/docs/it/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | L'`id` del pannello | Terminale, Desktop, VS Code |
| [`AbovePrompt`](https://code.claude.com/docs/it/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/it/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Una sola istanza | Terminale, Desktop |
| `AbovePromptList`, la pila di righe `AbovePrompt` | `rows`, un elenco con un `{ plugin, tree }` per la riga di ciascun mod, più le prop di `AbovePrompt` | Una sola istanza | Terminale, Desktop. Richiede Claude Code v2.1.323 o successiva. |
| [`Placed`](https://code.claude.com/docs/it/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | Il `requestId` restituito da `$.ui.place` | Terminale |
| [`Backdrop`](https://code.claude.com/docs/it/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Prima della v2.1.323, `scene` era `id` e `overrideColorScheme` era `colorScheme`. | `backdrop` | Superfici `desktop` e `mobile`. Il tuo hook viene eseguito quando l'app Desktop o mobile chiede di disegnare uno sfondo. |
| `UserMessage` | `text`, `origin`, `isExpanded` e `task` o `from` a seconda dell'origine | L'id della riga disegnata | Terminale, Desktop, VS Code |
| `AssistantMessage` | Il testo della risposta | L'id della riga disegnata | Terminale, Desktop, VS Code |
| `ToolUse`, `ToolResult`, `ToolGroup` | Il nome, l'input e il risultato dello strumento | L'id della chiamata allo strumento | Terminale, Desktop, VS Code |
| `CommandOutput` | `command`, `text` | L'id della riga disegnata | Terminale, Desktop |
| [`AskUserQuestion`](https://code.claude.com/docs/it/plugins/mods/interface#change-what-claude-code-already-draws) | La domanda e le opzioni | L'id della chiamata allo strumento | Terminale, Desktop, VS Code |
| `ToolProgress` | `kind` | L'id della chiamata allo strumento | Terminale |
| [`Spinner`](https://code.claude.com/docs/it/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | L'id dell'agente | Terminale, Desktop, VS Code |
| `TurnDuration` | `word`, `durationMs` | L'id della riga disegnata | Terminale |
| `InfoNotice` | `text`, `command` | Il `text` dell'avviso preceduto da `notice:` | Terminale |
| `SessionMode` | `modes` | Una sola istanza | Terminale, Desktop |
| `PromptHint` | `isDraft`, `isWorking`, `hint` | Una sola istanza | Terminale, Desktop |

`e.viewport` contiene `columns`, `rows` e `isFullscreen`. Nel terminale e nell'app Desktop, è assente finché l'app non ha misurato la propria finestra. Lì, il suo `rows` è l'altezza dell'intera finestra, non del tuo pannello. Nell'estensione VS Code, è sempre presente.

Per adattare un albero al suo punto, leggi queste prop nell'hook:

* **Larghezza di un `Pane` o della fascia**: disegna fino a `e.props.bodyColumns`
* **Altezza di un `Pane` accanto alla trascrizione**: quando `e.props.placement` è `'dock'`, `e.props.scroll.bodyRows` è il numero di righe di cui dispone il pannello per il tuo albero
* **Altezza di un `Pane` sopra il prompt**: quando `e.props.placement` è `'inline'`, il pannello cresce insieme al tuo albero fino a un limite, e `bodyRows` è quel limite. Per richiedere un limite diverso, consulta il [campo `rows` di `$.ui.open`](https://code.claude.com/docs/it/plugins/mods/interface#open-a-pane-at-the-right-time).

Un albero più alto del pannello scorre nel suo insieme.

## Elementi

Gli elementi sono i componenti di base di un albero restituito da un hook `ui.render`, e li ottieni da `$.ui.resolve(e)`. [Crea un albero a partire dagli elementi](https://code.claude.com/docs/it/plugins/mods/interface.md#build-a-tree-from-elements) mostra quelli più comuni insieme a come il terminale li disegna, e la [galleria dell'interfaccia](https://code.claude.com/docs/it/plugins/mods/gallery.md) contiene screenshot della maggior parte di essi. Un segno di spunta indica che l'app può disegnare l'elemento.

| Elemento | Prop principali | Terminale | Desktop | VS Code |
| :- | :- | :-: | :-: | :-: |
| [`Box`](https://code.claude.com/docs/it/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/it/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/it/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/it/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. Consulta [Limiti](#limits). | ✓ | ✓ | ✓ |
| [`Code`](https://code.claude.com/docs/it/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/it/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, [`rows`](https://code.claude.com/docs/it/plugins/mods/gallery#input), `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | una `source` di markup SVG fino a 131.072 caratteri, testo `alt`, `width`, `height` e `isInteractive` | | ✓ | ✓ |
| [`Client`](https://code.claude.com/docs/it/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key`, `props`, `width`, `height`, `flexGrow` | ✓ | ✓ | |
| [`Raster`](https://code.claude.com/docs/it/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, `columns` fino a 512, `rows` fino a 256, `cells`. Consulta [Disegna una griglia di celle colorate](https://code.claude.com/docs/it/plugins/mods/interface.md#draw-a-grid-of-colored-cells). | ✓ | | |
| `Image` | `key`, una `source` come byte PNG o RGBA fino a 2 MiB, oppure un percorso di file, `columns` e `rows` fino a 255, e testo `alt`. Consulta [quali terminali lo disegnano](https://code.claude.com/docs/it/plugins/mods/gallery.md#image-and-client). | ✓ | | |

Altre regole per `Button`:

* **`action`**: indica una delle [scorciatoie da tastiera](https://code.claude.com/docs/it/keybindings.md) di Claude Code, e la combinazione assegnata dall'utente a quell'azione preme il pulsante quando si tratta di un accordo o di un tasto con modificatore
* **Hotkey numerici nella banda**: un `hotkey` numerico su un pulsante nella banda si attiva anche quando l'utente digita solo quella cifra in un prompt vuoto e si ferma
* **Una banda compressa**: mentre la banda è [compressa](https://code.claude.com/docs/it/plugins/mods/interface.md#when-the-user-collapses-the-band), né una combinazione `action` né un hotkey premono un pulsante al suo interno
* **Due pulsanti sullo stesso hotkey**: quando due dei tuoi pulsanti nello stesso disegno indicano lo stesso `hotkey`, lo ottiene quello successivo. Per il pulsante di un altro mod sullo stesso tasto, consulta [Gli hotkey non fanno nulla](https://code.claude.com/docs/it/plugins/mods/troubleshoot.md#hotkeys-do-nothing).
* **`variant`**: `primary` o `secondary`, e qualsiasi altro valore genera un'eccezione. Nel terminale, un pulsante `primary` viene disegnato nel colore di accento, a meno che non sia `plain`.
* **`role`**: `dismiss` contrassegna un pulsante di chiusura, e qualsiasi altro valore genera un'eccezione. Esegui la chiusura nel tuo `onPress`. In una banda che contiene testo e una riga di pulsanti, l'app Desktop può disegnare il primo pulsante `dismiss` della riga come un proprio controllo di chiusura. Il terminale disegna il pulsante come farebbe senza `role`.

Un `Button` può contenere `children` al posto di una `label`:

* **Cosa possono essere i children**: stringhe ed elementi `Text`, come un nome seguito da un dettaglio attenuato o da un chip colorato. Claude Code rifiuta qualsiasi altro elemento all'interno di un `Button`.
* **Assegnare un nome al pulsante**: la `label` assegna il nome al pulsante e, per impostazione predefinita, corrisponde al testo dei suoi children. Assegna una `key` o una `label` a un pulsante con children diversi da una singola stringa.
* **Nel terminale**: i children vengono disegnati dove si troverebbe la label, e una pressione in qualsiasi punto su di essi conta come una sola pressione, quindi puoi trasformare ogni riga di un elenco in un singolo pulsante
* **Nell'app Desktop e nell'estensione VS Code**: il pulsante disegna la sua `label`

> [!NOTE]
>
> Un `Button` con children diversi da una singola stringa richiede Claude Code v2.1.295 o successivo.

`autoFocus` accetta solo `true` su qualsiasi controllo, quindi ometti la prop per lasciarlo disattivato.

L'estensione VS Code ignora alcune prop degli elementi e disegna l'elemento come se le avessi omesse:

* **`Box`**: `position` con i relativi `top`, `left`, `right` e `bottom`, `alignSelf`, `borderDimColor` e `hover`
* **`Text`**: `size`, `mono`, `tabular` e `hover`
* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action` e `hover`, quindi lì l'utente preme un pulsante con un clic, oppure con Invio quando ha il focus. L'estensione ignora anche `variant` e `role`.
* **`Code`**: `language`, `path`, `startLine`, `format` e `wrap`, quindi il codice viene disegnato senza colori né numeri di riga, e un blocco `format: 'diff'` mostra il testo grezzo del diff
* **`Input` e `Select`**: `autoFocus`, e `rows` su un `Input`
* **`Svg`**: `isInteractive`

### Stili del bordo di `Box`

Per disegnare un bordo attorno a un `Box`, imposta la sua `borderStyle` su uno di questi nomi, come in `borderStyle: 'round'`. Ogni riga indica cosa disegna il terminale per quel nome e mostra il bordo superiore.

| `borderStyle` | Cosa disegna il terminale | Bordo superiore |
| :- | :- | :- |
| `'single'` | Linee sottili con angoli squadrati | `┌──┐` |
| `'double'` | Linee doppie | `╔══╗` |
| `'round'` | Linee sottili con angoli arrotondati | `╭──╮` |
| `'bold'` | Linee spesse | `┏━━┓` |
| `'singleDouble'` | Linee sottili in alto e in basso, linee doppie sui lati | `╓──╖` |
| `'doubleSingle'` | Linee doppie in alto e in basso, linee sottili sui lati | `╒══╕` |
| `'classic'` | I caratteri ASCII `+`, `-` e `\|` | `+--+` |
| `'arrow'` | Frecce che puntano verso l'interno del `Box` | `↘↓↓↙` |
| `'dashed'` | Linee tratteggiate con angoli vuoti | `╌╌` |
| `'quote'` | Una barra, `▎`, lungo il lato sinistro e celle vuote sugli altri tre lati | Vuoto |

Un `Box` la cui `borderStyle` indica qualsiasi altro nome, come `'rounded'`, viene disegnato senza bordo.

### Passi di spaziatura di `Box`

Le prop di spaziatura di `Box` sono `gap`, `columnGap`, `rowGap`, `padding`, `margin` e le forme di `padding` e `margin` per un solo lato o un solo asse, come `paddingX` e `marginTop`. Ognuna accetta un numero di celle del terminale, come `gap: 1`, oppure il nome di un passo, come `gap: 'md'`. Nel terminale e nell'estensione VS Code, ogni passo corrisponde a questo numero di celle:

| Passo | Celle in orizzontale | Celle in verticale |
| :- | :- | :- |
| `'xs'` | 1 | 0 |
| `'sm'` | 1 | 0 |
| `'md'` | 2 | 1 |
| `'lg'` | 3 | 1 |
| `'xl'` | 4 | 2 |

Se imposti `gap`, `padding` o `margin` su un passo, il passo si applica contemporaneamente in orizzontale e in verticale. Ad esempio, nel terminale e nell'estensione VS Code, `padding: 'md'` corrisponde a due celle su ciascun lato e a una riga sopra e sotto.

I nomi dei passi richiedono Claude Code v2.1.299 o successivo. Su una release precedente, un albero che usa il nome di un passo non viene disegnato.

### Prop tipografiche di `Text`

Imposta `size`, `weight`, `mono` o `tabular` su un `Text` per chiedere all'app che disegna il tuo albero una dimensione del testo, uno spessore, un carattere a spaziatura fissa o cifre di larghezza uguale. Prima di fare affidamento su una prop, verifica cosa ne fanno il terminale e l'estensione VS Code. Se un'app ignora una prop che hai impostato, il tuo albero viene comunque disegnato, con il testo come se avessi omesso quella prop.

| Prop | Valori | Nel terminale | Nell'estensione VS Code |
| :- | :- | :- | :- |
| `size` | `'caption'`, `'footnote'`, `'body'`, `'heading'` o `'title'` | Ignorata: il terminale ha una sola dimensione del testo | Ignorata |
| `weight` | `'regular'`, `'medium'`, `'semibold'` o `'bold'` | `semibold` e `bold` vengono disegnati come testo in grassetto | `semibold` e `bold` vengono disegnati come testo in grassetto |
| `mono` | `true` per chiedere il carattere a spaziatura fissa dell'app | Ignorata: il terminale è sempre a spaziatura fissa | Ignorata, quindi il testo mantiene il carattere proprio dell'estensione |
| `tabular` | `true` per chiedere cifre di larghezza uguale, in modo che un numero che si aggiorna sul posto o una colonna di numeri restino allineati | Ignorata: le cifre del terminale occupano già una cella ciascuna | Ignorata |

Queste quattro prop richiedono Claude Code v2.1.299 o successivo. Su una release precedente, un albero che imposta `size`, `weight`, `mono` o `tabular` non viene disegnato.

#### Sostituisci `bold` con `weight`

`bold` su un `Text` è deprecato in favore di `weight` e funziona ancora. Per sostituirlo su un `Text` senza `weight`, cambia `bold: true` in `weight: 'semibold'` per ottenere lo stesso risultato su Claude Code v2.1.299 o successivo.

Su una release precedente alla v2.1.299, un albero che imposta `weight` non viene disegnato. Se imposti sia `bold` sia `weight` su un `Text`, `bold` non ha alcun effetto.

## Limiti

Gli hook e le chiamate all'API dei mod sono soggetti a limiti di tempo e di dimensione. Claude Code salta un hook che supera un limite di tempo. Un albero che supera il limite di annidamento, di elementi, di celle `Raster` o di byte di `Image` [non viene disegnato](https://code.claude.com/docs/it/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty).

| Limite | Valore |
| :- | :- |
| Il tempo di esecuzione proprio di un hook per un evento, senza contare il tempo trascorso dentro `next` o in una chiamata all'API dei mod diversa da `$.clock.sleep` | 10 secondi, o 50 millisecondi per un hook `prompt.edit` |
| Il tempo di esecuzione di un gestore `.catch` | 1 secondo |
| Tutti gli hook `session.end` insieme | Quanto il [budget dell'hook SessionEnd](https://code.claude.com/docs/it/hooks.md#sessionend-input), 1,5 secondi a meno che tu non lo modifichi, contati da quando terminano gli hook `SessionEnd` delle tue impostazioni |
| Timeout di `$.process.run` | 30 secondi per impostazione predefinita, 10 minuti al massimo |
| `stdout` e `stderr` di `$.process.run` | 4 MiB ciascuno. `isStdoutTruncated` o `isStderrTruncated` è `true` quando uno dei due è stato troncato. |
| `maxTokens` di `$.model.complete` | 1024 per impostazione predefinita, fino a 64.000 o al limite di output del modello |
| `$.fs.read` e `$.fs.write` | 4 MiB per un singolo file |
| Il corpo di una richiesta `$.http.fetch` | 4 MiB, contati in caratteri. Una chiamata con un corpo più grande viene rifiutata. |
| Il corpo di una risposta `$.http.fetch` | 4 MiB. `text` contiene i primi 4 MiB e il resto non viene letto. Quando l'header `Content-Length` dichiara una dimensione maggiore, la chiamata viene invece rifiutata, con un motivo che termina con `is over the 4194304-byte limit`, tranne quando l'ultima richiesta dopo eventuali reindirizzamenti usa il metodo `HEAD`. L'esenzione per `HEAD` richiede Claude Code v2.1.296 o versioni successive. |
| Una singola chiamata `$.http.fetch`, reindirizzamenti e corpo inclusi | 30 secondi |
| Reindirizzamenti seguiti da una singola chiamata `$.http.fetch` | 5 |
| Il motivo `drop` di un hook o il motivo `deny` di `config.set` | 4.096 caratteri. La parte finale di un motivo più lungo viene troncata, e il drop o il deny si applica comunque. Il troncamento richiede Claude Code v2.1.292 o versioni successive; nelle versioni precedenti l'hook invece [non riesce](https://code.claude.com/docs/it/plugins/mods/events.md#handle-a-hook-that-fails). |
| Testo in un singolo albero | Vengono disegnati i primi 100.000 caratteri |
| Il `language` o il `path` di un `Code`, il `value` di un'opzione `Select` o il `module` di un `Client` | 10.000 caratteri. Se uno è più lungo, l'hook `ui.render` che lo ha restituito [non riesce](https://code.claude.com/docs/it/plugins/mods/events.md#handle-a-hook-that-fails). |
| L'`href` di un `Link` | 2.048 caratteri. Se è più lungo, l'hook `ui.render` che lo ha restituito [non riesce](https://code.claude.com/docs/it/plugins/mods/events.md#handle-a-hook-that-fails). |
| Profondità di annidamento di un singolo albero | 32 livelli sotto l'elemento radice |
| Elementi e figli di testo in un singolo albero | 20.000 |
| Celle `Raster` in un singolo albero, ovvero le `columns` di ogni `Raster` moltiplicate per le sue `rows` | 262.144 |
| Le righe sopra il prompt, impilate | Elementi, celle `Raster` e byte di `Image` si sommano tra le righe, rispetto ai limiti di un singolo albero |
| Byte PNG o RGBA di tutte le `Image` in un singolo albero | 2 MiB |
| `$.store` | 4 MiB di JSON in totale |
| `$.session.messages()` | Le 4.096 voci più recenti |
| Ridisegni di `$.ui.invalidate('ui.render')` | Limitati a 10 al secondo, o 30 nel terminale per il riquadro visibile, la fascia espansa e la riga di suggerimento sotto il prompt. Le chiamate che arrivano prima vengono accorpate. |
| `$.ui.toast` | Mostrato per 4 secondi, a meno che tu non passi `{ timeoutMs }`. Nel [renderer classico](https://code.claude.com/docs/it/fullscreen.md#enable-fullscreen-rendering), un toast più recente di un mod può [prendere il posto di quello precedente](https://code.claude.com/docs/it/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear) che è visualizzato o in attesa di essere visualizzato. |
| Un riquadro aperto senza che l'utente lo abbia richiesto | Posizionato a partire da 144 colonne del terminale, 110 dopo che l'utente lo ha aperto una volta |
| Righe di `$.ui.place` che un singolo mod ha contemporaneamente in una conversazione | 500. Al raggiungimento del limite, una chiamata con un nuovo `id` si risolve in `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`. |
| Profondità di annidamento degli argomenti di una chiamata all'API dei mod | 28.000 livelli. Oltre questo limite, la chiamata viene rifiutata con un messaggio che termina con `nesting deeper than 28000 levels is not supported`. Richiede Claude Code v2.1.299 o versioni successive. |
| Profondità di annidamento di un evento modificato passato a `next`, al di fuori degli [hook generatori asincroni](#events) come uno su `turn.step` | 28.000 livelli. Oltre questo limite, `next` viene rifiutato con un messaggio che termina con `nesting deeper than 28000 levels is not supported`. Richiede Claude Code v2.1.299 o versioni successive. |
| Profondità di annidamento del valore restituito da un hook, al di fuori di `ui.render`, `ui.resolve` e degli hook generatori asincroni | 28.000 livelli. Oltre questo limite, il risultato dell'hook viene rifiutato e [l'avviso che lo segnala](https://code.claude.com/docs/it/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing) include `nesting deeper than 28000 levels is not supported`. Richiede Claude Code v2.1.299 o versioni successive. |
| Scope, come funzioni, blocchi e cicli, annidati l'uno dentro l'altro in un singolo file di un modulo degli hook | 2.000 |
| Nomi di comandi, strumenti, tipi di subagent e riquadri, l'`id` di una riga posizionata e la `scene` di uno sfondo | Lettere, cifre, `_` e `-`, fino a 64 caratteri |
| Un singolo test di `claude plugin test` | 5 secondi, a meno che il test non imposti `timeoutMs` |

## Impostazioni e variabili d'ambiente

Queste sono le impostazioni e le variabili d'ambiente che influiscono sui mod. La colonna Dove indica da quale file di impostazioni o ambiente viene letta ciascuna:

| Nome | Dove | Cosa fa |
| :- | :- | :- |
| `CLAUDE_CODE_PLUGIN_DIRS` | Ambiente, oppure `env` in `~/.claude/settings.json` | Directory di plugin da caricare come fa `--plugin-dir`, per le app a cui non puoi passare un flag. Percorsi assoluti separati da `:`, oppure da `;` su Windows. |
| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Ambiente | Indica se i mod vengono ricaricati al salvataggio. Consulta il [riferimento delle variabili d'ambiente](https://code.claude.com/docs/it/env-vars.md) per i valori predefiniti e i valori possibili |
| `prependPlugins`, `appendPlugins` | Impostazioni gestite. Impostazioni utente solo su una macchina senza impostazioni gestite né file [`managed-mcp.json`](https://code.claude.com/docs/it/managed-mcp#deploy-managed-mcp-json), in una sessione la cui credenziale non è un `/login` Team o Enterprise. | Elenchi di id di plugin, come `acme-guard@acme-tools`. I mod in `prependPlugins` vengono eseguiti prima di ogni mod installato da un utente, e i mod in `appendPlugins` vengono eseguiti dopo, nell'ordine elencato. Consulta [L'ordine in cui vengono eseguiti i mod](https://code.claude.com/docs/it/plugins/mods/events.md#the-order-mods-run-in). |
| `allowManagedModsOnly` | Impostazioni gestite, come [opzione della protezione integrata](https://code.claude.com/docs/it/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Solo i mod che [contano come quelli della tua organizzazione](https://code.claude.com/docs/it/plugins/mods/admin.md#install-your-organizations-mods) e i mod integrati in Claude Code eseguono i propri hook. Gli hook delle impostazioni degli utenti continuano a essere eseguiti. |
| `allowModsToOverrideDenyRules` | Impostazioni gestite, come [opzione della protezione integrata](https://code.claude.com/docs/it/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Consente a un mod installato da un utente di approvare una chiamata a uno strumento superando la maggior parte degli [esiti che restano in vigore per impostazione predefinita](https://code.claude.com/docs/it/permissions.md#precedence-among-rules-hooks-and-mods), inclusa una regola `deny` |
| `allowManagedHooksOnly` | Impostazioni gestite | Blocca gli hook e i mod installati che non appartengono alla tua organizzazione. Consulta [cosa continua a essere eseguito](https://code.claude.com/docs/it/settings-reference.md#what-runs-under-allowmanagedhooksonly). |
| `disableAllHooks` | Qualsiasi file di impostazioni | Nelle impostazioni gestite, non viene eseguito alcun mod o hook di un plugin installato. Nelle tue impostazioni, ciò che la tua organizzazione gestisce continua a essere eseguito. Consulta [`disableAllHooks`](https://code.claude.com/docs/it/settings-reference#disableallhooks). |
| `disableSideloadFlags` | Impostazioni gestite | Rifiuta `--plugin-dir` e `--plugin-url` all'avvio |
| `pluginConfigs` | Impostazioni utente o gestite | Contiene i valori di `userConfig` per un mod, indicizzati in base all'id del plugin, come `acme-guard@acme-tools`, oppure in base al suo nome seguito da `@inline`, come `first-mod@inline`, per un mod caricato con `--plugin-dir` |

`sec-default@builtin` è una protezione integrata in Claude Code, elencata come `cc-plugin-sec-default` in `/plugin` e nel log di debug. [Dove viene caricata](https://code.claude.com/docs/it/plugins/mods/admin.md#know-what-happens-by-default), viene eseguita prima di ogni mod installato da una persona. Se è impostato `prependPlugins` nelle impostazioni gestite, la protezione viene caricata solo quando quell'elenco la nomina, nella posizione indicata.

Il suo codice sorgente si trova nella [directory `mods/sec-default` del repository di Claude Code](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).

## Comandi

Questi comandi e flag caricano, ispezionano e testano un mod. I comandi `claude` vengono eseguiti nella tua shell e i comandi `/` nel prompt di Claude Code. Nella tabella, `<directory>` indica un percorso che digiti, come in `claude plugin validate ./first-mod`. Le parentesi quadre indicano un argomento facoltativo.

| Comando | Cosa fa |
| :- | :- |
| [`/plugin`](https://code.claude.com/docs/it/plugins/mods/overview#see-which-mods-a-session-loaded) | Mostra una riga come `1 mod active · first-mod` sotto le sue schede quando è stato caricato un mod non integrato |
| [`claude plugin validate <directory>`](https://code.claude.com/docs/it/plugins/mods/create#check-what-claude-code-reads-from-your-mod) | Legge il manifest e il modulo degli hook di un plugin e segnala gli errori, gli eventi che gestisce e le chiamate all'API dei mod che effettua. `--strict` tratta gli avvisi come errori e `--json` stampa un report leggibile da una macchina. |
| [`claude plugin test [directory]`](https://code.claude.com/docs/it/plugins/mods/test#write-a-test) | Esegue ogni file nella directory, o nella directory corrente se non ne specifichi una, il cui nome termina con `.test.ts` o `.test.tsx`. Termina con stato 1 quando un test fallisce. |
| [`claude --plugin-dir <directory>`](https://code.claude.com/docs/it/plugins/mods/create#write-a-mod-yourself) | Carica una directory di plugin per una sessione e ricarica il suo modulo degli hook quando salvi. Ripeti il flag per caricarne diverse. |
| `/reload-plugins` | Ricarica i plugin quando lo esegui |
