# 20260923 - Audit e controllo uso subagenti Sophia

**File:** `20260923_audit_subagent_usage.md`  
**Data:** 2026-09-23  
**Repository target:** `sophiadeveloper/mcp-servers`  
**Snapshot analizzato:** commit `c6f09d9c253a12b710c4a61bd0dc519585dc98e3` (`master` al momento dell'analisi)  
**Evidenza incidente:** chat Codex del 2026-09-21 contenuta in `codex_chat_con_subagenti.zip`  
**Tipo documento:** piano implementativo per agenti  
**Priorità:** alta  
**Stato:** pronto per implementazione incrementale

---

## 1. Obiettivo

Correggere la gestione dei subagenti nel framework Sophia per evitare fan-out non richiesto, duplicazione massiva del contesto, retry costosi e dipendenza fragile da modelli hardcoded, mantenendo disponibile la delega quando porta un beneficio reale.

Il comportamento target deve essere:

```text
prompt normale
    -> main agent diretto
    -> 0 subagenti Sophia

!agents / richiesta esplicita di delega
    -> 1 subagente bounded di default
    -> massimo 2 solo quando i task sono realmente indipendenti
    -> contesto minimo
    -> nessuna delega ricorsiva di default
    -> main agent responsabile di decisione e sintesi
```

Il principio da correggere è anche concettuale: i subagenti non devono essere presentati come meccanismo che riduce automaticamente token o costo complessivo.

La documentazione OpenAI corrente specifica che l'aggiunta di subagenti può aumentare il consumo di token e raccomanda il multi-agent soprattutto per workstream indipendenti e ben delimitati. Per task brevi, sequenziali o con stato condiviso è preferibile un singolo agente.

Riferimenti ufficiali:

- https://developers.openai.com/api/docs/guides/responses-multi-agent
- https://developers.openai.com/api/docs/guides/agents-api/multi-agent
- https://developers.openai.com/docs/config-file/config-reference

L'obiettivo dei subagenti Sophia deve quindi diventare:

1. riduzione del wall-clock quando esistono attività indipendenti realmente parallelizzabili;
2. isolamento del contesto quando separare i workstream aumenta la qualità;
3. verifica indipendente quando il valore della seconda analisi giustifica il costo;
4. delega di side task stretti e autosufficienti;
5. mai fan-out generico per il solo fatto che il task è complesso.

---

## 2. Evidenze dell'incidente del 2026-09-21

### 2.1 Composizione dei thread osservati

Nei rollout allegati sono presenti 22 thread complessivi:

| Categoria | Thread | Interpretazione |
|---|---:|---|
| Root/main agent | 1 | sessione principale utente |
| Subagenti esplicitamente spawned | 9 | fan-out del workflow agentico |
| `guardian_review` | 12 | review/approval native del client, da NON confondere con subagenti Sophia |
| **Totale** | **22** | |

I 9 subagenti espliciti sono:

```text
/root/frontend_staged_review
/root/backend_staged_review
/root/frontend_audit
/root/backend_audit
/root/docs_verification_audit
/root/trip_modify_perf
/root/drag_fleet_perf
/root/trip_modify_perf_retry
/root/drag_fleet_perf_retry
```

Il prompt utente che ha originato il lavoro non iniziava con `!agents`.

Quindi il fan-out non era una delega esplicitamente richiesta tramite la policy Sophia attuale.

### 2.2 Policy di progetto che favoriva il fan-out

Nel contesto della sessione era presente una versione precedente delle regole agentiche con una sezione sostanzialmente equivalente a:

```text
Delegation and parallelization
use sub-agents liberally
Delegation keeps the primary session small, reduces token consumption,
and lets independent work proceed in parallel
```

Questa policy è problematica per due motivi:

1. autorizza delegazione proattiva anche senza richiesta dell'utente;
2. presenta la delegazione come riduzione del consumo token, assunzione non valida in generale e contraddetta sia dall'incidente sia dalla documentazione OpenAI corrente.

Il repository `mcp-servers` attuale ha già corretto parte di questa policy introducendo subagenti opt-in, ma l'incidente dimostra che le copie distribuite ai progetti possono restare obsolete.

### 2.3 Uso token osservato

Dai record `thread_token_usage` finali dei rollout:

| Gruppo | Input token cumulativi | Cached input | Output | Total token cumulativi |
|---|---:|---:|---:|---:|
| Root | 11.968.103 | 11.624.960 | 40.883 | **12.008.986** |
| Subagenti Sophia | 22.355.302 | 21.528.832 | 52.561 | **22.407.863** |
| Guardian review | 417.396 | 291.840 | 2.103 | **419.499** |
| **Totale osservato** | **34.740.801** | **33.445.632** | **95.547** | **34.836.348** |

I soli subagenti espliciti hanno quindi accumulato circa **1,87 volte** i token del root thread.

I workstream più costosi sono stati:

| Subagente | Modello | Effort | Total token cumulativi |
|---|---|---|---:|
| `frontend_audit` | `gpt-5.6-luna` | high | 8.751.782 |
| `backend_audit` | `gpt-5.6-luna` | high | 7.964.893 |
| `drag_fleet_perf_retry` | `gpt-5.6-sol` | high | 2.407.129 |
| `trip_modify_perf_retry` | `gpt-5.6-sol` | high | 2.345.658 |
| `docs_verification_audit` | `gpt-5.6-luna` | medium | 938.401 |

### Importante sulla metrica

Questi numeri sono contatori cumulativi registrati nei rollout, con una quota molto alta di `cached_input_tokens`.

Non devono essere trasformati direttamente in:

- costo economico fatturato;
- percentuale di quota ChatGPT consumata;
- numero di richieste premium;
- equivalenza 1:1 con la UI degli utilizzi.

Sono però una prova forte del volume di elaborazione aggiuntivo generato dal fan-out e sono adatti al confronto before/after dello stesso tipo di workload.

### 2.4 Quattro spawn falliti per modello non supportato

Quattro thread sono terminati immediatamente perché il modello configurato non era supportato dall'account Codex + ChatGPT della sessione:

```text
frontend_staged_review -> gpt-5.4
backend_staged_review  -> gpt-5.4
trip_modify_perf        -> gpt-5.4-mini
drag_fleet_perf         -> gpt-5.4-mini
```

Errore osservato:

```text
The 'gpt-5.4' model is not supported when using Codex with a ChatGPT account.
```

oppure equivalente per `gpt-5.4-mini`.

Almeno due workstream sono poi stati rilanciati esplicitamente come:

```text
trip_modify_perf_retry -> gpt-5.6-sol / high
drag_fleet_perf_retry  -> gpt-5.6-sol / high
```

Il fallback ha quindi portato da un profilo leggero non valido a un modello più costoso con reasoning `high`.

Questo comportamento deve essere eliminato.

### 2.5 Full-history fork osservato

Le prime deleghe `code_reviewer` sono state lanciate con:

```json
{
  "fork_turns": "all"
}
```

Il runtime Codex stesso indica che il parametro controlla quanta history del parent viene propagata al child.

La policy Sophia corrente contiene già un principio migliore:

```text
Full parent-history inheritance is exceptional, never the default.
Target a delegation packet below 16 KiB when practical.
```

L'incidente mostra però che questo principio non era efficace nella configurazione/progetto effettivamente usato.

### 2.6 Broad audit invece di bounded side task

`frontend_audit` e `backend_audit` hanno ricevuto lavoro abbastanza ampio da accumulare ciascuno circa 8 milioni di token cumulativi.

Questo è l'opposto del modello desiderato:

```text
bounded subtask
+ input minimo
+ output sintetico
+ stop condition chiara
```

In un task di analisi complesso il framework deve evitare il pattern:

```text
main agent
  + frontend audit completo
  + backend audit completo
  + docs audit completo
  + review aggiuntive
  + due esplorazioni performance
```

quando un singolo main agent può prima fare discovery stretta e decidere successivamente se esiste davvero un workstream indipendente da delegare.

### 2.7 `guardian_review` non è fan-out Sophia

I 12 thread `guardian_review` sono identificati nei rollout come:

```text
source.subagent.other = guardian
```

Non devono essere attribuiti al routing Sophia dei subagenti.

Sono una categoria separata, collegata a review/approval automatiche del client.

La telemetria Sophia deve quindi distinguere almeno:

```text
root
sophia_subagent
host_guardian_review
other_host_internal
```

Senza questa separazione qualsiasi statistica sul numero di subagenti risulta fuorviante.

---

## 3. Stato corrente del repository `mcp-servers`

Il master corrente ha già introdotto diverse correzioni rispetto alla policy osservata nell'incidente.

### 3.1 Default opt-in già presente

`AGENTS.md` corrente stabilisce:

```text
I subagents sono opt-in.
Il default è main agent diretto senza subagents.
```

`scripts/hooks/prompt-routing-options.mjs` implementa:

```js
const subagentMode = hasAgents
  ? 'required'
  : (explicitSubagentRequest ? 'requested' : 'off');
```

Questa direzione va mantenuta.

### 3.2 Resolver deterministico già limitato

`scripts/hooks/subagent-routing-policy.mjs`:

- restituisce zero agenti se `subagentMode === 'off'`;
- seleziona massimo 1 ruolo in caso di lock esplicito;
- seleziona al massimo 2 raccomandazioni negli altri casi;
- filtra gli agenti dichiarati `unavailable`.

Questa è una buona base, ma governa la raccomandazione del routing, non impedisce da sola a skill/regole stale di indurre il modello a chiamare `spawn_agent`.

### 3.3 Policy corrente ancora concettualmente errata sul costo

`AGENTS.md` e `docs/agents/local-orchestration-playbook.md` dichiarano ancora:

```text
lo scopo primario dei subagents resta token/cost optimization, non parallelismo
```

Questa frase deve essere rimossa/corretta.

La documentazione OpenAI corrente afferma invece che aggiungere subagenti può aumentare l'uso token e indica il parallelismo di workstream indipendenti e l'isolamento del contesto come benefici principali.

### 3.4 Source of truth degli agenti presente ma modello concreto hardcoded

La fonte canonica è:

```text
docs/agents/canonical-subagents.yaml
```

Il renderer Codex in:

```text
scripts/portable-agents-lib.js
```

scrive attualmente sempre:

```toml
model = "<codex_model>"
model_reasoning_effort = "<reasoning_effort>"
```

Esempi correnti:

```text
scout             -> gpt-5.6-luna / medium
technical_analyst -> gpt-5.6-sol / high
code_reviewer     -> gpt-5.6-terra / medium
implementer       -> gpt-5.6-terra / medium
```

Il fatto che l'incidente abbia usato precedenti profili `gpt-5.4` / `gpt-5.4-mini` dimostra che un ID modello concreto dentro artifact persistenti può diventare obsoleto e trasformarsi in un errore di runtime.

### 3.5 Codex espone già controlli globali utili

La configurazione corrente di Codex espone nella sezione `[agents]` almeno:

```toml
[agents]
enabled = true
max_concurrent_threads_per_session = ...
default_subagent_model = "..."
default_subagent_reasoning_effort = "..."
```

Il repository upstream Codex documenta inoltre `max_depth` per il backend V1.

Questi controlli devono essere usati come hard cap host-specifico dove applicabili, mentre la policy Sophia deve restare provider-neutral.

Riferimenti:

- https://developers.openai.com/docs/config-file/config-reference
- https://github.com/openai/codex/blob/main/codex-rs/config/src/config_toml.rs

---

## 4. Diagnosi delle cause

### Causa A - Governance distribuita obsoleta

Il repository centrale oggi dice `opt-in`, ma il progetto reale della sessione conteneva ancora la vecchia policy `use them liberally`.

Quindi il problema non è solo la policy canonica ma la sua distribuzione e verifica nei repository target.

### Causa B - Modello mentale sbagliato: subagenti = risparmio token

La policy corrente del master conserva ancora questa assunzione.

Questo può spingere l'agente a delegare proprio nei casi in cui un singolo frontier model sarebbe più economico e semplice.

### Causa C - Gate di routing non autorevole end-to-end

`subagentMode=off` impedisce al resolver Sophia di raccomandare agenti, ma skill, playbook o `AGENTS.md` locali possono comunque contenere istruzioni di delegazione.

Il gate deve essere esplicitamente rispettato da ogni layer che parla di subagenti.

### Causa D - Context fork troppo ampio

`fork_turns="all"` replica il contesto parent nel child.

Su sessioni già grandi questo annulla buona parte del beneficio di isolamento e moltiplica l'elaborazione del contesto.

### Causa E - Profili modello concreti e persistenti

Un modello hardcoded può diventare:

- non disponibile sul piano corrente;
- rinominato o ritirato;
- non compatibile con quel client/provider;
- sproporzionato rispetto al side task.

### Causa F - Retry senza budget economico

Un errore di modello ha portato a retry con `gpt-5.6-sol/high`.

Il retry deve essere conservativo e non può aumentare automaticamente capacità/costo senza una policy esplicita.

### Causa G - Nessun budget di fan-out a livello di task

La policy parla di parallelismo massimo in alcuni playbook, ma manca un contratto semplice e globale del tipo:

```text
default children per user turn = 0
!agents default children = 1
automatic max = 2
nested delegation = off
failed-spawn retry = 1
```

### Causa H - Skill di orchestrazione non legata esplicitamente al gate

`mcp-master-orchestrator` e alcune skill specialistiche contengono sezioni sulla delegazione e parallelizzazione.

Devono poter orchestrare più fasi anche in un solo agente.

L'uso della skill `mcp-master-orchestrator` non deve mai essere interpretato come autorizzazione implicita a creare subagenti.

### Causa I - Telemetria che può mescolare thread di natura diversa

Se `guardian_review` viene contato come normale subagente, metriche di fan-out, costo e successo diventano inaccurate.

---

## 5. Principi di implementazione obbligatori

1. **Default Sophia: zero subagenti.**
2. **`!agents` significa delegazione esplicita, non fan-out libero.**
3. **Una richiesta naturale esplicita di delega può abilitare il routing, ma resta soggetta ai budget.**
4. **La complessità del task da sola non deve attivare subagenti.**
5. **Orchestrazione di skill e orchestrazione di processi agentici sono concetti distinti.**
6. **Un orchestrator skill può coordinare fasi in sequenza nel main agent senza creare child agent.**
7. **Non dichiarare che i subagenti riducono token/costo in generale.**
8. **Usare subagenti solo quando parallelismo, isolamento o verifica indipendente giustificano il costo aggiuntivo.**
9. **Context inheritance minimo per default.**
10. **Nessuna delega ricorsiva di default.**
11. **Nessun fallback automatico da modello economico fallito a modello top/high.**
12. **Un solo working-tree owner alla volta.**
13. **`guardian_review` e altri thread interni del client non sono subagenti Sophia.**
14. **Policy provider-neutral al centro, adapter host-specifici solo per i controlli disponibili nel client.**
15. **Non rompere i runtime esistenti senza migration e rollback.**

---

## 6. Fuori scope

Questa attività NON deve includere:

- il problema RAM/MCP del punto 1;
- la revisione completa dell'analytics multipiattaforma del punto 3;
- modifica del comportamento interno proprietario di Codex;
- disabilitazione totale e permanente del multi-agent per tutti gli utenti;
- creazione di nuovi ruoli subagent non necessari;
- redesign completo delle skill;
- ranking dei modelli AI;
- introduzione di un orchestratore LLM separato;
- modifiche al billing o ai limiti dell'account OpenAI.

La telemetria minima aggiunta qui serve solo a misurare e governare il fan-out. L'accuratezza generale delle statistiche resta punto 3.

---

# 7. Piano di implementazione

## Fase 0 - Rendere l'incidente riproducibile e misurabile

### Obiettivo

Creare un parser deterministico dei rollout Codex per misurare il fan-out senza affidarsi alla UI o a conteggi manuali.

### Nuovo script proposto

```text
scripts/audit-subagent-usage.mjs
```

### Input

Supportare almeno:

```bash
node scripts/audit-subagent-usage.mjs --input <rollout-dir>
node scripts/audit-subagent-usage.mjs --input <rollout-dir> --json <file>
node scripts/audit-subagent-usage.mjs --input <rollout-dir> --markdown <file>
```

Lo script deve essere read-only.

### Classificazione thread

Classificare ogni `session_meta` in:

```text
root
sophia_subagent
host_guardian_review
host_internal_other
unknown
```

Regole minime per Codex:

```text
source.subagent.thread_spawn -> sophia_subagent
source.subagent.other=guardian -> host_guardian_review
root session id / source vscode|cli -> root
```

Non assumere che ogni file secondario sia un subagente Sophia.

### Campi da estrarre

Per ogni thread:

```json
{
  "threadId": "...",
  "parentThreadId": "...",
  "agentPath": "/root/...",
  "agentRole": "...",
  "category": "sophia_subagent",
  "depth": 1,
  "model": "...",
  "reasoningEffort": "...",
  "status": "completed|failed|unknown",
  "errorClass": "unsupported_model|null",
  "retryOf": null,
  "forkTurns": "all|none|N|unknown",
  "inputTokens": 0,
  "cachedInputTokens": 0,
  "outputTokens": 0,
  "totalTokens": 0
}
```

### Summary richiesto

```json
{
  "rootThreads": 1,
  "sophiaSubagents": 9,
  "guardianReviews": 12,
  "failedSpawns": 4,
  "retrySpawns": 2,
  "fullHistorySpawns": 2,
  "maxDepth": 1,
  "rootTotalTokens": 12008986,
  "subagentTotalTokens": 22407863,
  "guardianTotalTokens": 419499,
  "subagentToRootTokenRatio": 1.87
}
```

I valori sopra sono fixture attesa per l'incidente, salvo eventuale normalizzazione documentata del parser.

### Test

Creare fixture minimali sintetiche, non committare l'intera chat reale se contiene materiale di progetto sensibile.

File suggeriti:

```text
tests/fixtures/subagents/root.jsonl
tests/fixtures/subagents/child-success.jsonl
tests/fixtures/subagents/child-model-failure.jsonl
tests/fixtures/subagents/guardian.jsonl
tests/subagent-usage-audit.test.mjs
```

---

## Fase 1 - Correggere la policy canonica sull'economia dei subagenti

### File target

```text
AGENTS.md
shared-agent-rules/SUBAGENTS.md
docs/agents/local-orchestration-playbook.md
docs/analisi-tecniche/analisi-tecnica-hotword-quick-subagents.md
skills/mcp-master-orchestrator/references/workflows.md
```

Aggiornare solo le sezioni che parlano di subagenti.

### Rimuovere

Formulazioni equivalenti a:

```text
primary purpose is token/cost optimization
subagents reduce token consumption
use them liberally
parallelize by default
```

### Nuovo contratto canonico

Usare un wording equivalente a:

```text
Subagents are opt-in and have additional token/context overhead.
Use them only when independent bounded workstreams, context isolation,
or independent verification justify that overhead.
Default to the main agent for short, sequential, tightly coupled,
or shared-state work.
```

In italiano nei file italiani:

```text
I subagenti sono opt-in e introducono overhead di token e coordinamento.
Usarli solo quando workstream indipendenti e delimitati, isolamento del
contesto o verifica indipendente giustificano tale costo.
```

### `!agents`

Mantenere la semantica corrente:

```text
!agents -> almeno una delega bounded
```

ma chiarire:

```text
!agents NON significa usare il massimo numero di subagenti disponibile.
```

Default operativo con `!agents`:

```text
1 child
```

Un secondo child è consentito solo se:

- il lavoro è realmente indipendente;
- non modifica la stessa risorsa;
- il main agent non deve ricostruire due volte lo stesso contesto;
- il parallelismo riduce plausibilmente il wall-clock o produce una verifica indipendente utile.

---

## Fase 2 - Rendere `subagentMode` un gate autorevole per tutte le skill

### Obiettivo

Impedire che una skill di orchestrazione o performance riattivi di fatto i subagenti quando il prompt routing è `off`.

### File target principali

```text
scripts/hooks/prompt-routing-options.mjs
scripts/hooks/subagent-routing-policy.mjs
scripts/hooks/sophia-user-prompt-submit.mjs
skills/mcp-master-orchestrator/SKILL.md
skills/mcp-master-orchestrator/references/workflows.md
skills/mcp-frontend-performance-debugger/SKILL.md
shared-agent-rules/SUBAGENTS.md
```

Cercare inoltre nel repository:

```text
delegate
delegation
subagent
sub-agent
parallelize
parallelizzazione
spawn
scout
implementer
```

Ogni istruzione trovata deve essere classificata come:

```text
ALWAYS_SAFE_DESCRIPTION
REQUIRES_SUBAGENT_GATE
HOST_SPECIFIC
LEGACY_STALE
```

### Regola autorevole

Aggiungere alla policy:

```text
subagentMode=off
  -> nessuna skill può interpretare la propria orchestrazione interna come autorizzazione a spawnare agenti

subagentMode=requested
  -> delega consentita ma discrezionale e budgeted

subagentMode=required
  -> almeno un task bounded deve essere delegato, entro i budget
```

### Orchestrator

`mcp-master-orchestrator` deve distinguere esplicitamente:

```text
skill orchestration != subagent orchestration
```

Esempio:

```text
Se subagentMode=off, esegui la sequenza di skill nel main agent.
Il fatto che il task abbia più fasi non autorizza spawn_agent.
```

La frase corrente:

```text
Per una modernizzazione legacy end-to-end, delega discovery...
```

va resa condizionale, per esempio:

```text
Quando la policy subagent del contesto consente la delega, il discovery può
essere affidato a un ruolo bounded; altrimenti esegui la stessa fase nel main agent.
```

### Test obbligatorio

Caso regressivo:

```text
prompt multi-fase complesso
senza !agents
routing skill = mcp-master-orchestrator
```

Atteso:

```text
subagentMode=off
recommendedAgents=[]
nessun hint che richieda spawn
```

---

## Fase 3 - Introdurre un budget globale di delegazione

### Nuovo modulo suggerito

```text
scripts/hooks/subagent-budget-policy.mjs
```

oppure integrare in `subagent-routing-policy.mjs` se resta coeso.

### Contratto dati

```js
{
  enabled: true,
  activationMode: 'off' | 'requested' | 'required',
  defaultChildren: 1,
  maxRecommendedChildren: 2,
  maxDepth: 1,
  maxSpawnRetriesPerTask: 1,
  contextStrategy: 'isolated',
  recursiveDelegation: false
}
```

Questi sono budget Sophia, non necessariamente controlli hard del client.

### Semantica

#### Prompt normale

```text
activationMode=off
children=0
```

#### `!agents`

```text
activationMode=required
default children=1
max automatically selected=2
```

#### Richiesta esplicita dell'utente

Se l'utente chiede esplicitamente un numero maggiore di agenti, non troncare in modo invisibile.

Il main agent deve:

- rispettare i limiti hard del client;
- evitare duplicazioni evidenti;
- segnalare eventuali riduzioni necessarie.

### Profondità

Per default:

```text
root -> child
```

Vietare:

```text
root -> child -> grandchild
```

salvo opt-in esplicito di un workflow che dimostri la necessità.

Le istruzioni dei ruoli portabili devono includere:

```text
Do not spawn or delegate to additional agents unless the parent task explicitly authorizes nested delegation.
```

Per Codex V1 usare anche `agents.max_depth` quando disponibile, ma non affidarsi solo a questo perché la documentazione upstream indica che il campo è backend-specifico.

---

## Fase 4 - Limitare la concorrenza host-side

### Codex

Estendere la gestione di `~/.codex/config.toml` con una policy conservativa.

Configurazione proposta iniziale:

```toml
[agents]
max_concurrent_threads_per_session = 2
```

**Non impostare automaticamente un numero diverso senza benchmark.**

Il valore 2 va trattato come baseline Sophia conservativa perché il framework stesso limita a massimo 2 raccomandazioni automatiche.

### Migrazione

Se l'utente possiede già:

```toml
[agents]
max_concurrent_threads_per_session = N
```

non sovrascrivere silenziosamente.

Comportamento installer:

```text
assente -> proporre default Sophia = 2
presente -> preservare + mostrare valore corrente
--force-policy -> applicare valore Sophia con backup
```

### Altri client

Claude Code, Copilot, Cursor e Antigravity devono usare il controllo nativo equivalente solo se documentato e disponibile.

Non inventare chiavi host-specifiche.

Dove non esiste hard cap, applicare solo la policy agentica Sophia.

---

## Fase 5 - Eliminare full-history inheritance come default

### Obiettivo

Nessun support subagent deve ricevere automaticamente l'intera conversazione parent.

### Regola

Per ogni delega Sophia ordinaria:

```text
fork_turns = none / isolated / equivalente host
```

seguita da un `Minimal Delegation Packet`.

### Packet massimo consigliato

Mantenere la regola già presente:

```text
< 16 KiB quando praticabile
```

### Packet obbligatorio

```text
objective
expected output
explicit scope/files
verified facts needed
constraints
out-of-scope
allowed capabilities
validation
stop conditions
```

### Full history

Consentire full history solo se il parent documenta almeno:

```text
reason=history-required
why-summary-insufficient=<motivo>
```

e se tutte le condizioni di `SUBAGENTS.md` sono soddisfatte.

### Test

Aggiungere eval/regression che fallisce se il workflow consigliato per un normale `!agents` produce:

```text
fork_turns=all
```

### Nota importante

Se il client non permette al framework di forzare tecnicamente il valore, trasformare la regola in:

1. istruzione autorevole;
2. telemetria di violazione;
3. test sui prompt/adapter generati.

Non simulare enforcement che il client non offre.

---

## Fase 6 - Rendere i profili modello resilienti

### Problema

L'incidente dimostra che un modello hardcoded in un profilo persistente può fallire prima ancora di svolgere il task.

### File target

```text
docs/agents/canonical-subagents.yaml
scripts/portable-agents-lib.js
scripts/sync-portable-agents.js
scripts/check-agents-doc.js
tests/portable-agents.test.cjs
scripts/install-user-runtime.js
scripts/check-user-runtime.js
```

### Strategia consigliata

Separare:

```text
ruolo logico
profilo capacità/costo desiderato
ID modello concreto del client
```

Non rendere l'ID modello concreto una parte indispensabile dell'identità del ruolo.

### Variante preferita per Codex

Rendere `model` e `model_reasoning_effort` opzionali nei file ruolo generati.

Se non esiste un override intenzionale e validato, lasciare che il child usi i default centrali della sezione `[agents]` oppure l'inheritance supportato dal client.

Esempio di profilo role senza pinning:

```toml
name = "scout"
description = "..."
sandbox_mode = "read-only"
```

E configurazione centralizzata:

```toml
[agents]
default_subagent_model = "<modello supportato corrente>"
default_subagent_reasoning_effort = "medium"
```

### Se si mantengono override per ruolo

Gli override devono essere:

- opzionali;
- definiti in una sola source of truth;
- aggiornabili dal generatore;
- verificati dall'installer contro il runtime corrente dove possibile;
- mai duplicati manualmente nei target derivati.

### Compatibilità schema

Modificare la validazione in `portable-agents-lib.js` in modo che:

```text
purpose/capability/permissions -> required
model override -> optional
```

Il profilo `recommended_model_profile` può restare come metadata/recommendation senza obbligare il renderer a pinning runtime.

---

## Fase 7 - Retry policy senza escalation automatica di costo

### Nuovo contratto

Per errore di tipo:

```text
unsupported model
model unavailable
invalid reasoning effort
```

applicare:

```text
retry massimo: 1
fallback: host default/inherited model
reasoning: default o medium, non upgrade automatico a high/xhigh
```

Vietare il pattern:

```text
light model fallisce
-> retry automatico con top model + high reasoning
```

### Esito se anche il retry fallisce

Il child termina e il main agent:

- continua direttamente se il side task non è indispensabile;
- oppure segnala il blocco;
- non crea una catena di nuovi agenti equivalenti.

### Deduplica retry

Aggiungere identificatore logico:

```text
delegationTaskId
retryOf
attempt
```

per evitare che due retry dello stesso task vengano contati come workstream indipendenti.

---

## Fase 8 - Correggere la distribuzione delle shared agent rules

### Obiettivo

Evitare che repository applicativi continuino per mesi con policy obsolete come `use them liberally`.

### Problema attuale

`shared-agent-rules/` è versionato, ma la distribuzione verso i repository esterni non risulta sufficientemente verificata/automatica.

Esiste `scripts/copy-agent-rules.bat`, ma una copia manuale può divergere dal canonico.

### Source of truth

Usare:

```text
shared-agent-rules/SUBAGENTS.md
```

come policy estesa canonica della delegazione.

`AGENTS.md` dei progetti deve contenere solo un bootstrap/riferimento breve, non una seconda policy completa mantenuta a mano.

### Versioning

Estendere:

```text
shared-agent-rules/manifest.json
```

con almeno:

```json
{
  "schemaVersion": 2,
  "subagentPolicyVersion": "2026-09-23",
  "files": {
    "SUBAGENTS.md": {
      "sha256": "..."
    }
  }
}
```

### Nuovo checker

Creare:

```text
scripts/check-shared-agent-rules.mjs
```

Funzioni:

```bash
node scripts/check-shared-agent-rules.mjs --project <path>
node scripts/check-shared-agent-rules.mjs --project <path> --json
```

Rilevare:

- policy canonica assente;
- hash/versione non allineati;
- vecchie copie managed;
- marker legacy noti.

### Legacy patterns da segnalare

Almeno:

```text
use them liberally
reduces token consumption
subagents are preferred by default
automatic delegation for complex tasks
```

Non fare reject su semplici occorrenze dentro documentazione storica o quote.

Il checker deve limitarsi ai file governance effettivi del progetto.

### Sync sicuro

Aggiungere, se coerente con il modello distribuzione esistente:

```text
scripts/sync-shared-agent-rules.mjs
```

con:

```text
--project
--dry-run
--backup
--check
```

Non sovrascrivere testo custom dell'utente fuori da blocchi managed.

Se il progetto possiede un `AGENTS.md` custom senza marker Sophia, mostrare diff/proposta ma non modificarlo automaticamente.

---

## Fase 9 - Aggiornare installer e runtime checker

### `scripts/install-user-runtime.js`

Aggiungere gestione conservativa di:

- limite concorrenza Codex;
- default subagent model/effort centralizzato, se scelto;
- detection di runtime agent derivati stale;
- report version shared-agent rules;
- nessun auto-upgrade del modello in caso di incompatibilità.

### `scripts/check-user-runtime.js`

Aggiungere check:

```text
codex_agents_concurrency
codex_subagent_defaults
portable_agent_profile_drift
shared_agent_rules_version
legacy_subagent_policy_detected
```

### Drift dei runtime agent

Se un file come:

```text
~/.codex/agents/code_reviewer.toml
```

non corrisponde più al renderer canonico, deve risultare `stale`.

L'incidente con `gpt-5.4` deve diventare rilevabile prima dell'uso.

---

## Fase 10 - Hardening dei ruoli portabili

### Canonical roles

Aggiornare `docs/agents/canonical-subagents.yaml` con una regola comune o rendering comune:

```text
Do not create child agents unless nested delegation was explicitly authorized by the parent task.
```

Non duplicare la frase manualmente in sette ruoli se può essere iniettata dal renderer come common runtime invariant.

### Scout

Deve restare:

```text
small context
read-only
bounded discovery
no architecture decision
```

### Technical analyst

Non deve diventare un secondo orchestrator.

### Code reviewer

Deve rivedere un oggetto delimitato e non avviare altre review parallele.

### Implementer

Un solo implementer owner del working tree per default.

### Docs writer / test writer

Non devono riaprire discovery broad del repository.

---

## Fase 11 - Correggere i workflow che suggeriscono fan-out

### `mcp-master-orchestrator/references/workflows.md`

La sezione:

```text
Prompt di orchestrazione subagent
```

deve iniziare con il gate:

```text
Applicare solo quando subagentMode != off.
```

Il limite attuale `max 2 scout` non deve essere interpretato come target da raggiungere.

Riscrivere come:

```text
1 scout di default;
secondo scout solo se esistono due fonti/workstream realmente indipendenti.
```

### `mcp-frontend-performance-debugger/SKILL.md`

La sezione `Parallelizzazione portabile` è già relativamente prudente, ma va rafforzata con:

```text
If subagentMode=off, execute the same evidence workflow sequentially in the main agent.
Complexity or performance scope alone does not authorize delegation.
```

### Altre skill

Fare inventory repository-wide e applicare la stessa regola a ogni riferimento a delegazione.

---

## Fase 12 - Telemetria minima per governance subagenti

Questa fase non sostituisce il futuro audit generale delle statistiche.

### Eventi minimi

Quando il framework può osservare una delega, registrare:

```json
{
  "event": "subagent_spawn",
  "parentThreadId": "...",
  "taskId": "...",
  "agentRole": "scout",
  "activationMode": "required",
  "reason": "user-hotword-agents",
  "contextStrategy": "isolated",
  "requestedModelProfile": "default",
  "attempt": 1
}
```

Per completion/failure:

```json
{
  "event": "subagent_complete",
  "taskId": "...",
  "status": "completed",
  "errorClass": null
}
```

### KPI

Calcolare separatamente:

```text
sophia_subagents_per_root_turn
successful_subagent_rate
failed_spawn_rate
retry_rate
full_history_spawn_rate
nested_delegation_rate
subagent_to_root_token_ratio
subagent_cached_input_ratio
subagent_wall_clock_saved_ms      # solo se misurabile correttamente
host_guardian_review_count        # categoria separata
```

### Non fare

Non sommare automaticamente:

```text
Sophia subagents + guardian_review
```

sotto una singola metrica `subagents`.

---

# 8. Test di regressione obbligatori

## 8.1 Parser/routing

| Prompt | Atteso |
|---|---|
| `correggi lo script installer` | `subagentMode=off`, 0 raccomandazioni |
| `analizza frontend e backend e proponi un piano` | `off`, 0 subagenti nonostante task complesso |
| `!agents analizza frontend e backend` | `required`, 1 child di default, max 2 se indipendenti |
| `usa un subagent per controllare il diff` | `requested`, massimo 1 reviewer |
| `usa due subagent separati per A e B` | fino a 2, se scope indipendente |
| `!quick implementa modifica` | full repo context se già previsto, 0 subagenti senza `!agents` |

## 8.2 Orchestrator

Fixture:

```text
analisi + fix + review + test + handoff
```

senza `!agents`.

Atteso:

```text
mcp-master-orchestrator può essere skill primaria
subagentMode=off
workflow sequenziale nel main agent
nessuna istruzione obbligatoria a spawnare
```

## 8.3 Full history

Per delega normale:

```text
fork_turns != all
```

oppure, se non osservabile staticamente, il prompt di orchestrazione deve chiedere esplicitamente isolated/minimal context.

## 8.4 Unsupported model

Simulare:

```text
model X -> unsupported
```

Atteso:

```text
attempt 1 fails
attempt 2 uses inherited/default safe profile
nessun upgrade automatico a high/top model
nessun attempt 3
```

## 8.5 Nested delegation

Un child riceve un task normale.

Atteso:

```text
non spawnare grandchild
```

## 8.6 Shared-rule drift

Fixture progetto con:

```text
use them liberally
reduces token consumption
```

Atteso:

```text
checker status=stale
legacy policy detected
nessuna modifica automatica senza --apply/managed block
```

## 8.7 Guardian classification

Fixture con:

```json
{"source":{"subagent":{"other":"guardian"}}}
```

Atteso:

```text
category=host_guardian_review
NOT sophia_subagent
```

## 8.8 Regression dei runtime agent

Dopo sync:

```bash
node scripts/sync-portable-agents.js
node scripts/check-agents-doc.js
```

I file generati devono essere deterministici e coerenti con il canonico.

---

# 9. Benchmark before/after

Usare almeno tre scenari rappresentativi.

## Scenario A - Task diretto medio

Esempio:

```text
analizza un bug e proponi una patch circoscritta
```

Senza `!agents`.

Target:

```text
Sophia child count = 0
```

## Scenario B - Analisi multi-dominio complessa

Esempio simile all'incidente SuperPlanning, senza `!agents`.

Target:

```text
Sophia child count = 0
```

Misurare se il main agent riesce a completare il lavoro senza degradazione sostanziale.

## Scenario C - Delega esplicita

Stesso task con:

```text
!agents
```

Eseguire varianti:

```text
1 child
2 child indipendenti
```

Confrontare:

| KPI | Single agent | 1 child | 2 child |
|---|---:|---:|---:|
| esito task | | | |
| wall-clock | | | |
| root token | | | |
| subagent token | | | |
| total token | | | |
| cached input | | | |
| spawn failure | | | |
| retry | | | |
| finding unici utili | | | |

Non fissare un target numerico di risparmio token prima del benchmark.

Se la variante multi-agent usa più token ma riduce molto il wall-clock o aumenta materialmente la copertura, documentare il trade-off invece di dichiararla inefficiente a priori.

---

# 10. Acceptance criteria

L'intervento è completato quando tutti i seguenti punti sono veri.

## Governance

1. Senza `!agents` o richiesta esplicita, la policy Sophia non invita a creare subagenti.
2. Nessuna documentazione viva afferma genericamente che i subagenti riducono token/costo.
3. `mcp-master-orchestrator` può operare integralmente nel main agent.
4. Le skill specialistiche con sezioni di parallelizzazione rispettano `subagentMode`.

## Budget

5. `!agents` produce 1 delega bounded di default.
6. Il framework non raccomanda automaticamente più di 2 child per turn.
7. Nested delegation è disabilitata per default nella governance Sophia.
8. Il retry automatico di uno stesso side task è massimo 1.

## Context

9. Full-history inheritance non è il default.
10. Il normale delegation packet è bounded e target <16 KiB quando praticabile.
11. Ogni subtask ha objective, scope, output e stop conditions.

## Modelli

12. I runtime agent non dipendono obbligatoriamente da un ID modello hardcoded per poter partire.
13. Un modello non supportato non causa fallback automatico a un modello più costoso con reasoning più alto.
14. `check-user-runtime` rileva agent profile stale rispetto al canonico.

## Distribuzione

15. Le shared agent rules hanno version/hash verificabile.
16. È disponibile un checker che rileva la vecchia policy di fan-out nei repository target.
17. La sincronizzazione non sovrascrive contenuto custom non managed senza consenso esplicito.

## Osservabilità

18. `guardian_review` non viene contato come subagente Sophia.
19. Il report distingue spawn, failure, retry, model/effort, depth e fork strategy.
20. Il fixture dell'incidente produce conteggi coerenti con 1 root, 9 child Sophia e 12 guardian.

## Test

21. `npm run test:affected -- --strict --base <baseline>` passa secondo le regole repository.
22. Test routing, portable agents e nuovi test subagent passano su Windows, macOS e Linux dove previsti dalla CI.

---

# 11. KPI di successo

| KPI | Baseline incidente | Target |
|---|---:|---:|
| Subagenti Sophia senza richiesta esplicita | 9 nello scenario osservato | **0** |
| Spawn falliti per modello non supportato | 4 | **0** dopo sync/runtime check |
| Full-history delegation ordinaria | presente | **0** |
| Nested delegation Sophia default | tecnicamente possibile | **0** |
| Retry per side task | non governato | **<= 1** |
| Child consigliati automaticamente con `!agents` | potenzialmente multipli | **1 default, max 2** |
| Token subagenti / root | ~1,87x incidente | misurare, nessun target arbitrario; deve essere giustificato dal beneficio |
| `guardian_review` mischiati a child Sophia | possibile | **0** |
| Repository con policy legacy non rilevata | incidente reale | checker deve segnalarla |

---

# 12. File che gli agenti devono ispezionare prima di modificare

Priorità alta:

```text
AGENTS.md
shared-agent-rules/AGENTS.md
shared-agent-rules/SUBAGENTS.md
shared-agent-rules/manifest.json
scripts/hooks/prompt-routing-options.mjs
scripts/hooks/subagent-routing-policy.mjs
scripts/hooks/sophia-user-prompt-submit.mjs
docs/agents/canonical-subagents.yaml
scripts/portable-agents-lib.js
scripts/sync-portable-agents.js
scripts/check-agents-doc.js
scripts/install-user-runtime.js
scripts/check-user-runtime.js
skills/mcp-master-orchestrator/SKILL.md
skills/mcp-master-orchestrator/references/workflows.md
skills/mcp-frontend-performance-debugger/SKILL.md
tests/subagent-routing-policy.test.mjs
tests/portable-agents.test.cjs
scripts/test-affected.mjs
```

Eseguire inoltre una ricerca repository-wide dei termini di delegazione prima della patch.

---

# 13. Suddivisione consigliata in PR

## PR 1 - Evidence parser e fixture incidente

Scope:

```text
scripts/audit-subagent-usage.mjs
tests/subagent-usage-audit.test.mjs
tests/fixtures/subagents/*
```

Obiettivo:

- rendere misurabile il problema;
- classificare root/child/guardian;
- congelare una baseline regressiva.

Nessun cambiamento comportamentale.

## PR 2 - Policy canonica e gate end-to-end

Scope:

```text
AGENTS.md
shared-agent-rules/SUBAGENTS.md
docs/agents/local-orchestration-playbook.md
scripts/hooks/prompt-routing-options.mjs
scripts/hooks/subagent-routing-policy.mjs
skills/mcp-master-orchestrator/*
skills con delegation wording pertinente
test routing
```

Obiettivo:

- rimuovere il falso assunto token/cost;
- rendere `subagentMode=off` autorevole;
- 1 child default, max 2 raccomandati.

## PR 3 - Context e nested-delegation hardening

Scope:

```text
docs/agents/canonical-subagents.yaml
scripts/portable-agents-lib.js
runtime agent generated
tests/portable-agents.test.cjs
```

Obiettivo:

- isolated context come default;
- divieto di child-of-child salvo opt-in;
- delegation packet bounded.

## PR 4 - Model profile resilience e retry

Scope:

```text
docs/agents/canonical-subagents.yaml
scripts/portable-agents-lib.js
scripts/install-user-runtime.js
scripts/check-user-runtime.js
config merger Codex pertinente
test installer/runtime
```

Obiettivo:

- modello runtime non rigidamente legato a ID stale;
- centralizzare default;
- retry max 1 senza escalation costosa.

## PR 5 - Shared-rule versioning e drift checker

Scope:

```text
shared-agent-rules/manifest.json
scripts/check-shared-agent-rules.mjs
scripts/sync-shared-agent-rules.mjs
README/guida distribuzione
test dedicati
```

Obiettivo:

- rilevare progetti con regole vecchie;
- sync sicuro e non distruttivo.

## PR 6 - Host concurrency cap e telemetria minima

Scope:

```text
Codex config injection/merge
installer GUI se pertinente
analytics event schema minimo
audit report
runtime checker
```

Obiettivo:

- cap Codex coerente con Sophia;
- metriche root/child/guardian separate;
- nessuna regressione degli altri client.

---

# 14. Ordine di rollout

1. Merge PR 1 e raccogli baseline su almeno 3 sessioni reali.
2. Merge PR 2 e verifica che task senza opt-in producano zero child Sophia.
3. Merge PR 3 e confronta token input con full-history vs isolated.
4. Merge PR 4 e rigenera/reinstalla i profili agenti utente.
5. Merge PR 5 e controlla almeno 2 repository applicativi reali, incluso uno con vecchie shared rules se disponibile.
6. Merge PR 6 solo dopo aver verificato che il cap di concorrenza non degradi workload legittimi.
7. Rieseguire lo scenario dell'incidente in modalità:
   - default single-agent;
   - `!agents` con 1 child;
   - `!agents` con 2 child indipendenti.
8. Documentare before/after con lo stesso parser e non con conteggi manuali.

---

# 15. Rollback

Ogni PR deve essere reversibile indipendentemente.

### Policy/routing

Rollback tramite revert dei file governance/hook senza modificare i runtime MCP.

### Profili agenti

Prima della rigenerazione utente conservare backup delle configurazioni modificate.

### Codex `[agents]`

Il merger deve preservare il valore precedente e permettere ripristino.

### Shared rules

Non eliminare copie legacy prima di aver verificato il nuovo bootstrap nel progetto target.

---

# 16. Decisioni architetturali finali da applicare

Le seguenti decisioni sono parte del piano e non devono essere riaperte dagli agenti senza nuova evidenza materiale.

### D1 - Subagents restano opt-in

```text
default = main agent diretto
```

### D2 - Complessità non equivale a delegazione

Un task multi-fase può essere orchestrato interamente nel main agent.

### D3 - Correggere il messaggio token/cost

Non usare più `token/cost optimization` come scopo primario.

### D4 - Budget conservativo

```text
1 child default con !agents
max 2 raccomandati automaticamente
max depth Sophia = 1
retry = 1
```

### D5 - Context minimal

Full history è eccezione motivata, non default.

### D6 - Nessun cost escalation fallback

Un modello leggero non disponibile non autorizza automaticamente un modello top/high.

### D7 - Shared rules versionate

La policy distribuita deve essere verificabile rispetto al canonico.

### D8 - Guardian separato

I thread di review/approval del client non sono subagenti Sophia.

---

# 17. Prompt operativo da passare all'agente implementatore

```text
Nel repository `sophiadeveloper/mcp-servers`, implementa in modo incrementale il piano `20260923_audit_subagent_usage.md`.

Obiettivo principale:
ridurre il fan-out agentico non richiesto e il consumo di contesto/token causato dal framework Sophia, mantenendo i subagenti disponibili solo come meccanismo esplicito e budgeted per workstream indipendenti.

Vincoli non negoziabili:
- default senza richiesta esplicita = zero subagenti Sophia;
- `!agents` resta opt-in vincolante ma produce 1 child bounded di default;
- massimo 2 child raccomandati automaticamente;
- nessuna delega ricorsiva di default;
- full-history inheritance non deve essere il default;
- non dichiarare che i subagenti riducono token/costo in generale;
- non fare fallback automatico da modello non supportato a modello top con reasoning più alto;
- separare `guardian_review` dai subagenti Sophia in qualsiasi audit/statistica;
- mantenere compatibilità legacy e migrazioni non distruttive;
- non modificare manualmente artifact agent derivati: cambia il canonico e rigenera.

Implementa una PR/fase per volta nell'ordine del documento.
Non anticipare le PR successive se la fase corrente non ha test e acceptance verdi.

Prima delle modifiche:
1. acquisisci baseline Git stabile;
2. leggi `AGENTS.md`, `shared-agent-rules/SUBAGENTS.md` e i file target della fase;
3. cerca nel repository tutte le istruzioni relative a delegate/subagent/parallelize/spawn;
4. classificale rispetto al nuovo gate opt-in.

Per la validazione finale usa il gate repository previsto da `AGENTS.md`:
`npm run test:affected -- --strict --base <baseline>`
con gli include necessari, senza eseguire suite ridondanti prima del gate conclusivo.

Nel report finale indica:
- file modificati;
- comportamento before/after;
- test eseguiti;
- eventuali limiti host-specifici non enforceable da Sophia;
- rischi residui;
- eventuale riavvio/reinstallazione runtime richiesta.
```

---

# 18. Done complessivo

Il punto 2 può essere considerato risolto quando un workload equivalente all'incidente mostra entrambe le proprietà:

```text
senza opt-in:
  0 Sophia subagents

con !agents:
  fan-out piccolo, bounded e misurabile
  nessun full-history non motivato
  nessun model failure evitabile
  nessun retry cost escalation
  guardian separati nelle statistiche
```

Il confronto deve essere prodotto dallo stesso audit script before/after e deve riportare sia token sia wall-clock, evitando di interpretare il solo numero di token come unico indicatore di successo.