Modalità

Che cos’è una modalità

Una modalità è una proprietà di uno spazio, memorizzata come una singola colonna sulla riga dello spazio. Ogni conversazione all’interno di uno spazio la condivide, thread compresi — un thread eredita la modalità del suo spazio come qualsiasi altra conversazione. Lo stesso agente può quindi trovarsi in modalità diverse in spazi diversi nello stesso momento, e cambiare la modalità di uno spazio modifica ciò che accade al turno successivo senza toccare l’agente.

Le modalità sono esattamente quattro: chat, review, plan, orchestrate. L’enum in sé non porta alcuna policy. Tutto ciò che una modalità garantisce è dichiarato una volta sola, in un profilo di capacità, da cui proietta ogni livello di applicazione:

Superficie degli strumenti — quali strumenti esistono in quella modalità, espressa come livello massimo di approvazione, una lista di autorizzazione, una lista di divieto e un insieme di classi di effetto rifiutate.
Verbo di output richiesto — ciò che l’esecuzione deve chiamare per aver consegnato qualcosa.
Classi di effetto negate — ciò che la guardia delle azioni rifiuta senza appello.
Postura del worktree — se il worktree può essere scritto. È imposta rimuovendo dalla superficie gli strumenti che mutano, ed è ciò che la fa valere su ogni host. Dove l’host dispone di un sandbox del sistema operativo, la stessa postura ritaglia anche le regole di scrittura del filesystem — una modalità di sola lettura monta il worktree in sola lettura — ma quella è una seconda copia della garanzia, non quella che fa il lavoro.
Blocco del prompt di sistema — un preambolo delle capacità generato a partire dall’elenco effettivo degli strumenti materializzati, più indicazioni scritte a mano.

Ogni livello di applicazione proietta da quell’unico profilo, perciò la superficie degli strumenti, la guardia, la postura del worktree e il prompt non possono contraddirsi.

Le quattro modalità

Chat — visualizzata come «Agente»

È la modalità predefinita e l’unica senza vincoli aggiuntivi: la superficie completa degli strumenti fino al livello di esecuzione, un worktree scrivibile, nessuna classe di effetto negata e nessun contratto di completamento. Usala per l’implementazione, la correzione di bug, le domande sulla codebase e qualsiasi cosa ad hoc.

Fai attenzione all’etichetta: nel composer la modalità è mostrata come «Agente», non «Chat».

Piano — sola lettura, un solo risultato

La modalità Piano rende il worktree di sola lettura e rimuove del tutto gli strumenti di scrittura dalla superficie, così la restrizione è strutturale anziché impartita. L’agente legge, cerca e svolge ricerca, e consegna esattamente una cosa: una chiamata a submit_plan che porta con sé un grafo di dipendenze tipizzato — un obiettivo più nodi con chiavi, titoli, descrizioni e le chiavi dei nodi da cui ciascuno dipende.

Il piano viene mostrato come una riga compatta nella conversazione e apre Plan Studio in una scheda accanto. Approvarlo compila il grafo in un’orchestrazione, esegue il lavoro generato e riporta lo spazio di authoring alla modalità agente.

Se un’esecuzione in modalità Piano termina senza aver mai chiamato submit_plan, il loop inietta prima un sollecito che dice che il piano non esiste finché quella chiamata non va a buon fine. Il sollecito autorizza esplicitamente un’onesta uscita «qui non serve alcun piano», perché la modalità Piano è un’impostazione dello spazio e una semplice domanda posta al suo interno non deve forzare un piano fittizio.

Esiste una seconda via d’uscita, separata: exit_plan_mode. È un gate di approvazione rigido, non un verbo di output — un agente che la chiama invece di submit_plan non ha consegnato nulla. La prima chiamata apre un’approvazione durevole plan_exit e restituisce pending, e lo spazio resta di sola lettura; le chiamate ripetute restano pending invece di aprire un secondo gate. Solo una volta concessa l’approvazione una chiamata successiva riporta lo spazio alla modalità chat. Un rifiuto permette all’agente di aprire una nuova richiesta per un piano rivisto.

Per uscire tu stesso dalla modalità Piano, cambia il menu a discesa della modalità nel composer (oppure premi Shift+Tab). exit_plan_mode viene decisa con lo strumento MCP decide_approval. Le righe «approvazione dell’agente» della posta in arrivo sono un’altra cosa: richieste di conferma per singolo turno provenienti da un agente in esecuzione.

Revisione — sola lettura, nessun contratto

La modalità Revisione è pensata per la revisione delle PR. Rende il worktree di sola lettura, limita la superficie degli strumenti al di sotto del livello di esecuzione e applica una lista di autorizzazione curata di strumenti di revisione, ticketing e comunicazione. Uno spazio aperto per una pull request viene creato automaticamente in modalità Revisione.

L’output dell’agente è costituito da riscontri strutturati — i nodi di revisione — e, quando una revisione viene finalizzata, da un verdetto. Un nodo porta un tipo (bug, suggestion, recommendation, question o ticket), una priorità da P0 (blocca il rilascio) a P3 (da avere se possibile), una confidenza autovalutata, un’ancora facoltativa (file più un intervallo di righe; le note sull’intero repository non ne hanno) e uno stato del ciclo di vita che passa da open a consensusReady quando un pari — mai l’autore — lo conferma. Un riscontro la cui priorità o confidenza manca o è fuori intervallo viene scartato al confine di lettura anziché inquinare il verdetto.

Il verdetto è ship, hold o block ed è reso solo più severo dai risultati per asse che vi confluiscono: un asse con gate fallito forza block e un asse con gate che non è potuto essere eseguito forza almeno hold. L’assenza di prove non rende mai verde un gate.

A differenza di Piano e Orchestrazione, la Revisione non porta alcun contratto di completamento. I riscontri si accumulano tramite add_review_node e vengono pubblicati da finalize_review, ed entrambe possono legittimamente essere chiamate zero volte — un agente di pipeline in esecuzione in modalità Revisione può trovarsi lì per completare un ticket.

Orchestrazione — sola lettura, propone un team

La modalità Orchestrazione trasforma un singolo obiettivo in un piano per un intero team. Come la modalità Piano è di sola lettura e non può scrivere file; sopra alla superficie di ricerca ha un unico verbo privilegiato, propose_orchestration, che emette una proposta strutturata: ruoli, un albero di sotto-ticket, un passaggio di sintesi e un budget. Il prompt nomina solo gli strumenti presenti sulla superficie, così il modello non spreca turni a raccontare assunzioni o lavoro sui ticket che non può chiamare.

Nulla nella proposta viene eseguito finché non la approvi. All’approvazione un materializzatore deterministico assume gli agenti, crea i ticket e un progetto ed esegue una pipeline generata. L’approvazione è riservata all’operatore: non esiste uno strumento MCP per farlo, quindi un agente può proporre ma non approvare mai il proprio piano. Le riproposte avviate da un agente sono limitate da un cooldown di due minuti, quindi i ripensamenti consecutivi vengono rifiutati e invitati a fondersi. Vedi Orchestrazione.

Due regole da conoscere

Il verbo di output di una modalità non può mai essere negato. submit_plan e propose_orchestration sono fissati nella superficie degli strumenti e pre-approvati oltre il filtro degli strumenti, il gate di approvazione e la guardia delle azioni, così il quadrante dell’autonomia per spazio non può mettere a tacere il risultato di una modalità. Anche l’ask_user dell’harness è fissato per lo stesso motivo: è il modo in cui un’esecuzione raggiunge l’operatore, quindi sottoporlo a un gate bloccherebbe un’esecuzione che deve chiedere qualcosa. È di livello lettura, quindi ogni modalità di sola lettura lo mantiene, ed è esente dal wrapper di approvazione — un prompt davanti a un prompt fallisce chiuso quando non c’è alcun approvatore collegato, il che negherebbe a un agente l’atto stesso di chiedere.

Le modalità di sola lettura non negano l’accesso alla rete né ai segreti. Le classi di effetto che Revisione, Piano e Orchestrazione rifiutano sono quelle che cambiano il mondo: eliminazione di file, scritture fuori dal worktree, commit, push, creazione e pubblicazione di PR, scritture di sincronizzazione dei fornitori, installazione di pacchetti, avvio di processi, mutazione dello spazio di lavoro e controllo dei recinti. L’egress di rete e l’accesso ai segreti restano ai valori predefiniti di proposito — la ricerca è l’intero scopo di una modalità di sola lettura.

Scegliere e cambiare una modalità

Il menu a discesa della modalità nel composer offre tre opzioni: Agente (chat), Piano e Orchestrazione. review non è selezionabile dall’utente — viene impostata dal sistema quando si crea uno spazio per la revisione di una PR e dai passaggi di pipeline.

Un nodo di pipeline che apre uno spazio può fissare la modalità di quella stanza con una chiave extras['mode'] (chat, review o plan). La chiave richiede una corrispondenza esatta: qualsiasi altra grafia — compresa orchestrate — viene ignorata in silenzio e la stanza ottiene il valore predefinito del body (review sul body create-space). Un passaggio agente entra in una stanza che non ha creato e non ne ridefinisce i permessi.

La risoluzione in sé è semplice. Il dispatcher legge la colonna mode dello spazio; un invio senza spazio — un one-shot, un’invocazione da CLI o un id di spazio proveniente da un altro spazio di lavoro, che semplicemente non è nel file di database di questo spazio di lavoro — si risolve in chat. Il cambio di modalità ha effetto dal turno successivo.

Dove la garanzia vale davvero

La superficie degli strumenti di una modalità è costruita e applicata dall’harness integrato. È l’unico trasporto in grado di rendere uno strumento invisibile anziché semplicemente negato, di sottoporre a un gate ogni chiamata prima che venga eseguita e di osservare un contratto di completamento.

Sul trasporto Claude Code una modalità diversa da chat viene passata come --permission-mode plan. Claude lo rispetta per convenzione; i suoi strumenti di lettura, scrittura e modifica vengono eseguiti senza essere visti e i suoi comandi di shell li controlla solo un hook che legge la riga di comando. Per quel trasporto la modalità è un’indicazione, non un confine di Control Center — vedi Il modello degli agenti.

Le liste di autorizzazione vincolano gli strumenti di livello scrittura e superiore. Il livello di lettura dell’harness integrato raggiunge comunque strumenti che nessuna lista nomina; su Claude Code, uno strumento omesso dalla lista di autorizzazione viene rifiutato che il server lo abbia o no.

Concetti correlati

Ciclo di vita dell’invio degli agenti: dove la modalità viene risolta e proiettata
Il modello degli agenti: quali trasporti possono applicare una modalità
Guardrail: la policy delle classi di effetto in cui confluisce la preimpostazione di una modalità
Orchestrazione: che cosa fa una proposta di orchestrazione approvata
Usa la modalità piano: la guida pratica passo passo