Ciclo di vita dell'invio degli agenti

Che cos’è un invio

Un invio è una singola esecuzione di un singolo agente, in una singola conversazione, su un singolo adapter. Tutto ciò che lo riguarda accade su cc_server: il client invia un messaggio e poi osserva gli eventi che tornano in streaming. Non esiste alcun percorso di invio in nessun client.

Gli agenti vengono risvegliati per sei motivi, che l’esecuzione porta con sé come contesto di risveglio così che l’agente sappia perché è sveglio:

Motivo del risveglio	Attivazione
userMessage	Qualcuno ha inviato un messaggio in uno spazio, oppure ha menzionato l’agente
assignment	Un ticket è stato assegnato all’agente
pipelineStep	Un passaggio di pipeline lo ha inviato
childCompleted	Un ticket figlio è terminato
followUp	Un heartbeat di follow-up pianificato
recovery	Il percorso di ripristino ha rilanciato l’invio dopo un errore

Il contesto di risveglio porta con sé gli id che accompagnano il motivo — ticket, spazio, messaggio, esecuzione di pipeline — e vengono iniettati nell’ambiente e nel prompt dell’agente.

Composizione del prompt

Il prompt è costruito a strati, ciascuno dei quali è una sezione etichettata:

• Identità — l’id, il nome e l’id dello spazio di lavoro dell’agente stesso, con un’istruzione esplicita a passare esattamente quegli UUID agli strumenti con ambito di spazio di lavoro. Lo spazio di lavoro è intrinseco all’agente, quindi è sempre presente.
• Catalogo degli strumenti e protocolli delle risorse, poi la struttura dello spazio di lavoro.
• Override del prompt di sistema, se l’agente ne ha uno, poi la persona (parametrizzata per ruolo) e il brief del team.
• Skill — i nomi presenti sull’agente.
• Contratto di esecuzione e procedura per la modalità corrente.
• Contesto di risveglio e contesto delle menzioni: chi ha convocato l’agente e l’elenco di chi gli sta intorno.
• Blocco della modalità — generato dal profilo di capacità della modalità e dal suo elenco di strumenti materializzato, così un prompt non può mai nominare uno strumento che l’esecuzione non ha davvero.
• Contesto di memoria — fatti recuperati per l’attività.
• Contesto della conversazione — cronologia recente dello spazio, limitata a 50.000 caratteri di finestra letterale, indipendentemente dalla dimensione del contesto configurata per l’agente. La cronologia più vecchia non viene eliminata per troncamento: l’agente la recupera su richiesta con get_messages e i messaggi più vecchi semanticamente rilevanti emergono comunque.

I comandi slash vengono analizzati dal testo grezzo dell’utente

Il prompt a strati inizia con un blocco di contesto, quindi non comincia con uno slash. I comandi vengono analizzati alla lettera dal messaggio dell’utente e poi rimossi dalla coda del prompt a strati, così ogni strato di contesto sopravvive.

I comandi sono divisi tra due punti. /todo e /compact vengono intercettati nel compositore e di proposito non vengono mai memorizzati come messaggi né inviati all’agente — memorizzare /compact sposterebbe indietro di un turno il taglio della compattazione e inquinerebbe la trascrizione. /plan è gestito in entrambi i punti: il compositore cambia la modalità dello spazio, ed è ciò che fa concordare superficie degli strumenti, preset dei guardrail e prompt per questo turno e per ogni turno successivo. /goal, /loop e /skill:<name> sono gestiti all’interno dell’esecuzione stessa e solo sull’harness integrato — /goal e /loop avviano lavoro autonomo con un budget di costo, e un nome con prefisso skill: viene cercato come una skill il cui corpo SKILL.md diventa la direttiva del turno. È il namespace a tenere separati i due vocabolari: risolvere un nome nudo rispetto alle skill significava che una skill chiamata plan o compact veniva oscurata in modo permanente dal comando integrato. Un nome nudo non integrato viene comunque risolto, per i messaggi scritti prima che il namespace esistesse. Un nome non riconosciuto passa semplicemente come testo normale.

Predisposizione del worktree

Prima che qualsiasi cosa venga eseguita, la conversazione ottiene una propria radice di lavoro, con sotto di essa un worktree copy-on-write isolato per ogni repo. Per impostazione predefinita si tratta di ogni repo collegato allo spazio di lavoro; uno spazio PR — o uno spazio creato con una selezione esplicita — predispone solo quelli presenti nella lista consentita, e una conversazione di revisione PR fissa il suo unico repo al ref head della pull request mentre gli altri restano sul loro branch predefinito. Il checkout di origine non viene mai modificato e l’intera directory della conversazione viene recuperata quando lo spazio viene eliminato.

Il copy-on-write è l’unica implementazione ovunque rift sia distribuito, sostenuta dal native incluso. Un filesystem che non sa fare reflink — o una data dir su un volume diverso da quello del repo — fa fallire la predisposizione invece di ripiegare su un’alternativa. git worktree è il backend su Windows, dove non c’è alcun backend copy-on-write da compilare, e non è una degradazione silenziosa sugli altri host. Un rift mancante su una piattaforma che lo distribuisce è un’installazione rotta — il server si rifiuta di avviarsi invece di ripiegare in silenzio, perché un fallback silenzioso nasconde il guasto dietro un percorso più lento per sempre.

Identità e credenziali

Per ogni esecuzione vengono risolte due identità, prima che qualsiasi processo venga avviato.

Paternità Git. I commit creati da un agente sono attribuiti all’agente — <Name> (agent) <agentId@agents.control-center.local> sia in GIT_AUTHOR_* sia in GIT_COMMITTER_* — senza mai impersonare una persona. La parte locale è l’UUID dell’agente, non lo slug del suo nome. Alla persona richiedente viene riconosciuto un trailer Co-Authored-By:, trasportato nell’ambiente e indicato nel prompt di sistema. Un’identità esplicita impostata dal chiamante vince sempre su entrambe.

Identità della forge. La credenziale GitHub dell’esecuzione è sempre e solo quella del broker — un token di installazione dell’App con ambito sul repo, o il suo fallback PAT dall’ambiente — mai il token memorizzato del membro richiedente. actingUserId delimita il fallback PAT, così un membro che non è il proprietario del server non eredita la portata del server; non sovrappone un token personale all’ambiente dell’agente.

Le credenziali del provider di modelli vengono risolte in un ordine fisso e l’ordine conta:

1. un override dell’ambiente relativo al singolo adapter,
2. l’ambiente del chiamante,
3. l’archivio delle credenziali del server (aggiornando un token OAuth se è prossimo alla scadenza),
4. l’ambiente del processo.

Poiché l’override per adapter viene per primo, batte in silenzio un account del provider collegato nell’app. Se un’esecuzione viene addebitata sull’account sbagliato, quell’override è il primo posto da controllare. Le credenziali del provider sono globali per l’host — condivise tra tutti gli spazi di lavoro dell’installazione.

Il token GitHub dell’esecuzione proviene dal broker delle credenziali: un token di sola lettura, limitato al repo del worktree. Un push passa dal gateway delle esecuzioni degli agenti, che interroga la regola Eseguire il push a un remoto prima di inoltrarlo, e non viene iniettata alcuna chiave di ticketing. Vedi Sandbox e sicurezza.

Avvio

L’esecuzione viene avviata con il suo worktree come directory di lavoro e — per Claude Code — una configurazione MCP generata, così che l’agente possa raggiungere la superficie degli strumenti di Control Center. ACP e bash dell’harness ricevono un ambiente ripulito; Claude Code tramite NoSandboxAdapter eredita l’ambiente dell’host.

Il sandbox del sistema operativo avvolge un’esecuzione solo dove l’host ha un backend

cc_server sonda l’host una volta all’avvio e, quando un backend è disponibile, avvolge in esso i processi degli agenti — Seatbelt su macOS, bubblewrap su Linux e WSL2. Entrambi i punti di innesto dell’invio vengono avvolti, perché non ne condividono uno: la CLI di Claude Code passa per la porta del sandbox; gli adapter ACP e lo strumento bash dell’harness integrato passano per il gestore del sandbox. È anche ciò che applica i percorsi protetti dell’esecuzione: i tuoi checkout di repo registrati hanno la scrittura negata dentro il sandbox, in ogni modalità.

Dove non c’è alcun backend, l’esecuzione non è racchiusa in un sandbox e nient’altro cambia per compensare. Ciò significa sempre Windows (nessun wrapper nativo — microvm è un percorso separato, subordinato alla sonda, per terminali e rig) e Linux o WSL2 senza bwrap e socat nel PATH. Il server dichiara in quale stato si trova nella sua riga di log all’avvio, e --sandbox off rinuncia deliberatamente.

Due lacune sopravvivono al sandbox anche dove è attivo. Gli strumenti file in-process dell’harness (read, write, edit, apply patch, search, find, search_files) vengono eseguiti dentro il processo del server, quindi nessun profilo li vincola — il loro limite è il confinamento dei percorsi degli strumenti stessi più i guardrail. E Claude Code viene avviato con --dangerously-skip-permissions, quindi le sue chiamate ai file non sono controllate da Control Center e i suoi comandi di shell solo da un hook che legge la riga di comando; il sandbox del sistema operativo è il confine che li circonda.

I limiti rimanenti valgono su ogni host, con o senza sandbox: il worktree proprio dell’esecuzione (copy-on-write dove rift è distribuito; git worktree su Windows), un token del forge di sola lettura, mediato a ogni avvio e revocato alla dismissione, i push che devono superare la regola di push al gateway delle esecuzioni degli agenti, i guardrail unificati delle azioni (fail-closed — una decisione prompt senza alcun approvatore collegato viene negata) e la superficie degli strumenti che la modalità della conversazione consente. ACP e bash dell’harness ripuliscono comunque l’ambiente; Claude Code tramite NoSandboxAdapter eredita l’ambiente dell’host.

Streaming

L’esecuzione restituisce in streaming una sequenza di eventi tipizzati, che il processore di stream persiste come delta di messaggio, ripiega in segmenti di trascrizione e trasforma in eventi di messaggistica:

Evento	Cosa trasporta
thinking	Output di ragionamento, visualizzato inline
text	Output visibile
toolCall	Un’invocazione di strumento, con il suo id e argomenti strutturati
toolResult	Il risultato corrispondente, contrassegnato quando ha prodotto un errore o è uno stream parziale
usage	Conteggi di token e costo per una finestra di misurazione
error	Un errore, con il codice strutturato dell’adapter quando ne ha segnalato uno
sandboxViolation	Il sistema operativo ha negato una chiamata di sistema. Emesso solo dove un sandbox avvolge davvero il processo — vedi la nota sopra
debug	Diagnostica di runtime (marcatori di avvio, decisioni del guard, sollecitazioni del contratto)
done	L’esecuzione è terminata

Cosa delimita un’esecuzione

Non esiste deliberatamente alcun tetto di turni, da nessuna parte. Un conteggio fisso di iterazioni uccide il lavoro lungo legittimo (migrazioni, pulizia di fan-out) e non intercetta nulla che le protezioni descritte sotto non intercettino prima. Un’esecuzione termina quando:

• il modello si ferma da solo;
• una persona la ferma, oppure prende il controllo della conversazione (il che mette in pausa l’harness integrato al suo prossimo confine di turno pulito — un’esecuzione di Claude Code, che non ha un confine sicuro, viene invece fermata);
• scatta il watchdog del silenzio. Nessun output per la soglia e la sessione viene terminata con un errore silentRun. Il valore predefinito è 15 minuti, che scende a 10 nelle modalità prevalentemente in lettura (review e plan); un agente può sovrascriverlo tra 1 e 240 minuti. Il watchdog viene armato quando un processo figlio segnala il proprio PID, quindi copre la CLI di Claude Code — non l’harness integrato, che non genera alcun processo;
• scatta un limite di costo — ma solo per i comandi autonomi.

La protezione anti doom-loop non è un terminatore: tre chiamate di strumento identiche di fila e il ciclo guida l’agente a cambiare approccio.

Un turno normale non ha alcun limite di costo

La protezione dei costi nella sessione è cablata solo per /goal e /loop; ogni altra esecuzione non passa alcun budget. Per quei comandi, un segmento non presidiato può consumare 500 centesimi ($5.00) per impostazione predefinita, con una guida soft all’80% che chiede all’agente di concludere in modo pulito prima dell’arresto definitivo e un budget duraturo dell’obiettivo di 5000 centesimi ($50.00) distribuito sui segmenti. Un /goal --budget esplicito non viene mai superato di un intero segmento.

Messi insieme, un normale turno interattivo sull’harness integrato non ha tetto di turni, né limite di costo, né watchdog del silenzio. Termina quando il modello si ferma o quando lo fermi tu. È uno scambio deliberato — le alternative uccidono tutte il lavoro lungo legittimo — ma significa davvero che un’esecuzione interattiva non presidiata è delimitata da nient’altro che dal giudizio del modello stesso.

A metà esecuzione, un messaggio inviato a un agente in corso viene accodato come guida e consumato al confine del turno successivo, così puoi sollecitare un’esecuzione senza ucciderla. La guida, la pausa, i sottoagenti e il contratto di completamento sono funzionalità dell’harness integrato; Claude Code non ne ha nessuna.

Come viene registrata un’esecuzione

Ogni invio scrive un AgentRunLog: ora di inizio e di fine, riepilogo, conteggi di token e costo stimato (incluso il costo aggregato dai sottoagenti), adapter e modello, id del processo e percorso del log, la conversazione e qualsiasi ticket o esecuzione di pipeline a cui appartiene, più due campi di classificazione che racchiudono gran parte della verità.

• Stato è grossolano: pending, running, completed, error.
• Vitalità è la lettura più fine: alive, productive, completed, blocked, empty, looping, failed, stalled, dead.
• Famiglia di errore raggruppa i guasti in modo utile: transientUpstream, sandboxInfrastructure, budgetExceeded, processLost, silentRun, unknown.

completed non significa «consegnato»

Quando un’esecuzione termina senza il risultato che la sua modalità richiedeva — un’esecuzione in modalità plan che non ha mai chiamato submit_plan, un’esecuzione orchestrate che non ha mai proposto — lo stato resta completed, perché il processo è comunque uscito in modo pulito. Il segnale onesto sta sulla vitalità (empty), sulla famiglia di errore (silentRun) e su un riepilogo che dice esattamente cosa non è stato prodotto. Quel riepilogo è protetto: la finalizzazione non lo sovrascriverà con le ultime chiacchiere del modello.

Ciò è deliberato. Cambiare lo stato farebbe avanzare macchine a stati di ticket e pipeline che non hanno nulla a che vedere con l’artefatto mancante. Significa anche che «status: completed» da solo non basta mai per concludere che un’esecuzione sia riuscita — leggi il riepilogo.

La chiusura dell’esecuzione pubblica AgentRunCompleted e da essa dipende molto: l’aggregazione dei costi della pipeline, la ripresa di un passaggio di pipeline che era in attesa dell’esecuzione, il completamento del ticket sottostante, la mappatura di un’orchestrazione su uno stato terminale, la decisione di continuare o fermarsi del supervisore degli obiettivi, il ruolo di revisore e la valutazione del budget a esecuzione conclusa. L’elenco della presenza segue separatamente, osservando i log di esecuzione recenti anziché l’evento. La notifica «agente completato» non è in questo elenco: l’evento scatta quando termina lo stream del processo, prima che la risposta venga scritta, quindi la notifica è il MessageReceived del turno, pubblicato una volta che il messaggio è stato salvato.

I budget, a posteriori

L’applicazione del budget è una reazione, non un cancello. Quando un’esecuzione termina, il valutatore confronta la spesa dell’agente dall’inizio del mese con il suo tetto effettivo (una policy di budget collegata, se esiste, altrimenti la cifra mensile dell’agente stesso; zero significa illimitato). Superare la soglia soft registra un incidente di avviso; esaurire il budget registra un incidente hard e porta lo stato del ciclo di vita dell’agente a paused sull’organigramma. L’invio accetta comunque lavoro da quell’agente. Un trigger di pipeline BudgetThresholdCrossed può avviare lavoro di follow-up dallo stesso evento.

Discendenza dei tentativi

Ogni log di esecuzione può portare con sé una discendenza di tentativi — un id dell’esecuzione padre, un contatore di tentativi e un riepilogo di continuazione. L’albero delle esecuzioni della conversazione mostra il numero del tentativo quando è diverso da zero. Un «riprova» dalla chat è un nuovo invio con un log di esecuzione nuovo.

Concetti correlati

• Il modello degli agenti: cosa l’adapter può e non può imporre
• Modalità: da dove derivano la superficie degli strumenti e il contratto di completamento
• Guardrail: la policy delle classi di effetto che ogni chiamata controllata attraversa
• Sandbox e sicurezza: la storia dell’isolamento per intero
• Multigiocatore: guida, presa di controllo e selettore dell’autonomia
• Eventi di dominio: cosa innesca AgentRunCompleted