# Analisi tecnica: allineamento permessi agenti Codex con Copilot e Antigravity

## Obiettivo

Allineare i permessi runtime degli agenti Codex a quanto gia' gestito per Copilot e Gemini/Antigravity, introducendo il parametro Codex `sandbox_mode` nella pipeline canonica degli agenti portabili.

La modifica deve riguardare solo il target Codex per il parametro runtime `sandbox_mode`, mantenendo invariata la logica esistente per Copilot e Gemini/Antigravity.

## Sintesi richiesta

Implementare la gestione di `sandbox_mode` per gli agenti Codex in tre punti:

1. documentazione;
2. file canonico YAML `docs/agents/canonical-subagents.yaml`;
3. generazione dei file `.codex/agents/*.toml` tramite `scripts/sync-portable-agents.js` e libreria collegata.

La modifica deve essere conservativa, deterministica e compatibile con l'attuale architettura:

- YAML canonico come fonte di verita';
- runtime Codex/Copilot/Gemini derivati;
- nessuna modifica manuale ai runtime generati, salvo output della rigenerazione;
- nessun cambio di comportamento per Copilot e Gemini/Antigravity.

## Stato attuale osservato

### Fonte canonica

Il file `docs/agents/canonical-subagents.yaml` definisce i ruoli portabili:

- `explorer`;
- `implementer`;
- `technical_analyst`;
- `code_reviewer`;
- `test_writer`.

Ogni ruolo contiene:

- `id`;
- `purpose`;
- `prioritize`;
- `avoid`;
- `output`;
- `escalate_when`;
- `recommended_model_profile`.

Il profilo modello include gia':

```yaml
recommended_model_profile:
  default_model: ...
  codex_model: ...
  copilot_model: ...
  copilot_multiplier: ...
  reasoning_effort: ...
```

### Generazione Codex attuale

La funzione `renderCodexToml(role)` in `scripts/portable-agents-lib.js` genera oggi file TOML Codex con:

```toml
name = "..."
description = "..."
model = "..."
model_reasoning_effort = "..."
developer_instructions = """
...
"""
```

Manca quindi una dichiarazione esplicita di:

```toml
sandbox_mode = "read-only"
```

o:

```toml
sandbox_mode = "workspace-write"
```

### Copilot e Gemini/Antigravity

Per Copilot, il generatore distingue gia' i tool disponibili per ruolo:

- `implementer` riceve tool di scrittura/editing;
- gli altri ruoli ricevono strumenti di ricerca/lettura.

Per Gemini/Antigravity, il generatore distingue gia' i tool disponibili per ruolo:

- `implementer` riceve anche `run_shell_command`, `replace`, `write_file`;
- gli altri ruoli ricevono tool di lettura, ricerca e MCP.

Quindi il gap e' specifico del target Codex: i ruoli read-only sono descritti come read-only nelle istruzioni, ma il runtime Codex non riceve un vincolo esplicito equivalente.

## Problema tecnico

Senza `sandbox_mode` nei file `.codex/agents/*.toml`, il comportamento effettivo dipende dalla configurazione della sessione Codex padre.

Questo puo' produrre una discrepanza tra:

- intenzione dichiarata del ruolo;
- permessi runtime effettivi.

Esempio:

- `code_reviewer` e' un ruolo read-only;
- `test_writer` e' un ruolo read-only/chat-output-only;
- `explorer` e' un ruolo discovery/read-first;
- `technical_analyst` e' un ruolo analitico;
- ma senza `sandbox_mode = "read-only"`, questi agenti potrebbero ereditare permessi piu' ampi dalla sessione principale.

La correzione deve trasformare il vincolo da sola policy testuale a vincolo runtime esplicito per Codex.

## Decisione tecnica proposta

Aggiungere un campo canonico dedicato ai permessi runtime Codex.

Nome consigliato:

```yaml
codex_sandbox_mode: read-only
```

Collocazione consigliata: dentro un nuovo blocco `runtime_permissions`, separato dal profilo modello.

Esempio:

```yaml
runtime_permissions:
  codex_sandbox_mode: read-only
```

Per `implementer`:

```yaml
runtime_permissions:
  codex_sandbox_mode: workspace-write
```

## Perche' non inserirlo in `recommended_model_profile`

`recommended_model_profile` riguarda selezione modello, reasoning e costo/pianificazione.

`sandbox_mode` e' invece un permesso runtime, quindi e' preferibile tenerlo separato per evitare ambiguita' semantica.

Struttura consigliata:

```yaml
recommended_model_profile:
  default_model: gpt-5.4-mini
  codex_model: gpt-5.4-mini
  copilot_model: Claude Haiku 4.5
  copilot_multiplier: 0.33
  reasoning_effort: medium
runtime_permissions:
  codex_sandbox_mode: read-only
```

## Mapping permessi consigliato

| Ruolo | `codex_sandbox_mode` | Motivazione |
|---|---|---|
| `explorer` | `read-only` | Discovery, auditing, identificazione file e rischi. Non deve modificare file. |
| `technical_analyst` | `read-only` | Analisi multi-sorgente e raccomandazioni. Non deve implementare direttamente. |
| `code_reviewer` | `read-only` | Review di snippet, diff, commit, branch o PR. Non deve editare. |
| `test_writer` | `read-only` | Produce checklist manuali e piani test in output chat. Non deve modificare file. |
| `implementer` | `workspace-write` | Unico ruolo operativo autorizzato a produrre patch reviewable. |

Non introdurre `danger-full-access` nei profili portabili.

## File da modificare

### 1. `docs/agents/canonical-subagents.yaml`

Aggiungere `runtime_permissions.codex_sandbox_mode` a tutti i ruoli.

Esempio per `explorer`:

```yaml
  - id: explorer
    purpose: Read-first role for discovery, inspection, scoped auditing, and gap identification before implementation.
    prioritize:
      - Read before proposing edits.
      - Identify relevant files, constraints, invariants, and risks.
      - Call out uncertainty explicitly.
      - Keep recommendations small, concrete, and testable.
    avoid:
      - Making product code changes unless explicitly requested.
      - Large redesign proposals when a smaller path exists.
      - Claiming certainty when evidence is incomplete.
      - Expanding scope beyond the requested audit.
    output:
      - Current state summary.
      - Relevant files or subsystems.
      - Gaps, risks, and unknowns.
      - Recommended next steps ordered conservatively.
    escalate_when:
      - The task requires direct implementation.
      - The request depends on project-specific workflow rules.
      - The analysis reveals a cross-cutting redesign or unsafe ambiguity.
    recommended_model_profile:
      default_model: gpt-5.4-mini
      codex_model: gpt-5.4-mini
      copilot_model: Claude Haiku 4.5
      copilot_multiplier: 0.33
      reasoning_effort: medium
    runtime_permissions:
      codex_sandbox_mode: read-only
```

Esempio per `implementer`:

```yaml
    runtime_permissions:
      codex_sandbox_mode: workspace-write
```

### 2. `scripts/portable-agents-lib.js`

Aggiornare parsing, validazione e rendering.

#### Parsing YAML

La funzione `parseCanonicalYaml(content)` oggi legge `recommended_model_profile` con stato `inModelProfile`.

Aggiungere stato equivalente per `runtime_permissions`.

Possibile approccio minimale:

```js
let inModelProfile = false;
let inRuntimePermissions = false;
```

Nel ruolo iniziale:

```js
runtime_permissions: {
  codex_sandbox_mode: null,
},
```

Quando si incontra il blocco:

```js
if (/^    runtime_permissions:\s*$/.test(line)) {
  inRuntimePermissions = true;
  inModelProfile = false;
  currentListField = null;
  continue;
}
```

Quando si incontra `recommended_model_profile`, spegnere `inRuntimePermissions`:

```js
if (/^    recommended_model_profile:\s*$/.test(line)) {
  inModelProfile = true;
  inRuntimePermissions = false;
  currentListField = null;
  continue;
}
```

Parsing campo:

```js
const codexSandboxModeMatch = line.match(/^      codex_sandbox_mode:\s*(.+)\s*$/);
if (codexSandboxModeMatch && inRuntimePermissions) {
  currentRole.runtime_permissions.codex_sandbox_mode = codexSandboxModeMatch[1];
  continue;
}
```

Quando si incontra `purpose`, liste o altri blocchi, ricordarsi di spegnere entrambi gli stati se necessario.

#### Validazione

Aggiungere validazione obbligatoria:

```js
const CODEX_SANDBOX_MODES = ['read-only', 'workspace-write', 'danger-full-access'];
```

Consigliato: validare ma non usare `danger-full-access` nel canonico portabile.

Possibile validazione stretta per questo repo:

```js
const PORTABLE_CODEX_SANDBOX_MODES = ['read-only', 'workspace-write'];
```

Errore se mancante:

```js
if (!role.runtime_permissions?.codex_sandbox_mode) {
  errors.push(`Campo mancante 'runtime_permissions.codex_sandbox_mode' per ruolo ${role.id}.`);
}
```

Errore se non valido:

```js
if (
  role.runtime_permissions?.codex_sandbox_mode &&
  !PORTABLE_CODEX_SANDBOX_MODES.includes(role.runtime_permissions.codex_sandbox_mode)
) {
  errors.push(
    `Valore non valido 'runtime_permissions.codex_sandbox_mode' per ruolo ${role.id}: ${role.runtime_permissions.codex_sandbox_mode}`
  );
}
```

#### Rendering TOML Codex

Aggiornare `renderCodexToml(role)` aggiungendo:

```js
const sandboxMode = role.runtime_permissions.codex_sandbox_mode;
```

E nel return TOML:

```js
`sandbox_mode = "${sandboxMode}"`,
```

Output atteso:

```toml
name = "explorer"
description = "Read-first role for discovery, inspection, scoped auditing, and gap identification before implementation."
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"
developer_instructions = """
...
"""
```

Per `implementer`:

```toml
sandbox_mode = "workspace-write"
```

### 3. `scripts/check-agents-doc.js`

Verificare se usa `computeExpectedTargets()` e `validateCanonicalRoles()` dalla libreria.

Se si limita a confrontare runtime attesi e file effettivi, potrebbe non richiedere modifiche dirette oltre alla libreria.

Se contiene validazioni testuali specifiche sui campi canonici, aggiornare anche li' per includere `runtime_permissions.codex_sandbox_mode`.

### 4. Documentazione runtime agenti

Aggiornare `.codex/agents/README.md` per indicare che il target Codex include anche `sandbox_mode`, derivato dal canonico.

Proposta:

```markdown
## Codex sandbox policy

Codex runtime agents include `sandbox_mode` generated from
`docs/agents/canonical-subagents.yaml`.

- read-only roles use `sandbox_mode = "read-only"`;
- `implementer` uses `sandbox_mode = "workspace-write"`;
- `danger-full-access` is intentionally not used in portable runtime agents.
```

### 5. Documentazione playbook

Aggiornare `docs/agents/local-orchestration-playbook.md` nella sezione boundary/routing o parallelismo.

Proposta:

```markdown
## Codex runtime permissions

Codex sandbox permissions are encoded in the canonical role schema and generated into `.codex/agents/*.toml`.

Current policy:

- `explorer`, `technical_analyst`, `code_reviewer`, `test_writer`: `read-only`;
- `implementer`: `workspace-write`.

Do not widen Codex permissions in generated runtime files. Change the canonical YAML and regenerate.
```

## File generati attesi

Dopo la modifica e la rigenerazione, i file sotto `.codex/agents/*.toml` devono contenere `sandbox_mode`.

Attesi:

```text
.codex/agents/explorer.toml             sandbox_mode = "read-only"
.codex/agents/technical_analyst.toml    sandbox_mode = "read-only"
.codex/agents/code_reviewer.toml        sandbox_mode = "read-only"
.codex/agents/test_writer.toml          sandbox_mode = "read-only"
.codex/agents/implementer.toml          sandbox_mode = "workspace-write"
```

Non sono attesi cambi funzionali nei runtime Copilot e Gemini/Antigravity, salvo differenze di rigenerazione non intenzionali da evitare.

## Comandi di sviluppo e verifica

Eseguire dalla root del repository:

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

Verifiche manuali consigliate:

```bash
grep -R "sandbox_mode" .codex/agents
```

Output atteso indicativo:

```text
.codex/agents/explorer.toml:sandbox_mode = "read-only"
.codex/agents/implementer.toml:sandbox_mode = "workspace-write"
.codex/agents/technical_analyst.toml:sandbox_mode = "read-only"
.codex/agents/code_reviewer.toml:sandbox_mode = "read-only"
.codex/agents/test_writer.toml:sandbox_mode = "read-only"
```

Verifica che Copilot/Gemini non cambino in modo inatteso:

```bash
git diff -- .copilot/agents .gemini/agents
```

L'output dovrebbe essere vuoto, salvo modifiche intenzionali non previste da questa task.

Verifica completa diff:

```bash
git diff -- docs/agents/canonical-subagents.yaml scripts/portable-agents-lib.js scripts/check-agents-doc.js .codex/agents .copilot/agents .gemini/agents docs/agents/local-orchestration-playbook.md .codex/agents/README.md
```

## Criteri di accettazione

La task e' completata quando:

1. `docs/agents/canonical-subagents.yaml` contiene `runtime_permissions.codex_sandbox_mode` per tutti i ruoli.
2. `scripts/portable-agents-lib.js` parse-a e valida `runtime_permissions.codex_sandbox_mode`.
3. `renderCodexToml(role)` genera `sandbox_mode` nei file `.codex/agents/*.toml`.
4. Tutti i ruoli read-only generano `sandbox_mode = "read-only"`.
5. `implementer` genera `sandbox_mode = "workspace-write"`.
6. `danger-full-access` non e' usato nei runtime portabili.
7. La documentazione spiega la policy Codex sandbox.
8. `node scripts/sync-portable-agents.js` completa senza errori.
9. `node scripts/check-agents-doc.js` completa senza errori.
10. I runtime Copilot e Gemini/Antigravity non subiscono cambi non correlati.

## Vincoli di implementazione

- Non modificare manualmente `.codex/agents/*.toml` come fonte primaria: devono essere rigenerati.
- Non introdurre nuovi ruoli.
- Non introdurre la griglia `spark/high/max`.
- Non modificare i modelli attuali.
- Non usare `gpt-5.3-codex-spark`, perche' non risulta disponibile nell'endpoint locale attuale.
- Non cambiare tool Copilot o Gemini/Antigravity.
- Non introdurre `danger-full-access`.
- Mantenere compatibilita' con l'attuale parser YAML minimale custom.
- Evitare refactor ampi del generatore.

## Rischi e mitigazioni

### Rischio: parser YAML custom fragile

Il parser attuale non e' un parser YAML generale, ma un parser line-based per lo schema canonico.

Mitigazione:

- aggiungere il nuovo blocco seguendo la stessa indentazione esistente;
- mantenere struttura semplice key/value;
- aggiornare validazione con errori espliciti.

### Rischio: drift runtime

Se i file `.codex/agents/*.toml` vengono modificati manualmente, il check puo' fallire o la modifica puo' essere sovrascritta.

Mitigazione:

- modificare solo canonico e generatore;
- rigenerare con `sync-portable-agents.js`;
- validare con `check-agents-doc.js`.

### Rischio: estensione impropria a Copilot/Gemini

`sandbox_mode` e' specifico Codex. Copilot e Gemini usano meccanismi diversi basati sui tool disponibili.

Mitigazione:

- non generare `sandbox_mode` nei target non Codex;
- mantenere invariati `copilotToolsForRole()` e `geminiToolsForRole()` salvo bug non correlati.

## Patch plan consigliato per Codex

Usare questa sequenza:

1. Leggere:
   - `docs/agents/canonical-subagents.yaml`;
   - `scripts/portable-agents-lib.js`;
   - `scripts/check-agents-doc.js`;
   - `.codex/agents/README.md`;
   - `docs/agents/local-orchestration-playbook.md`.
2. Aggiornare il canonico con `runtime_permissions.codex_sandbox_mode`.
3. Aggiornare parser e validatore in `scripts/portable-agents-lib.js`.
4. Aggiornare `renderCodexToml(role)` per generare `sandbox_mode`.
5. Aggiornare documentazione Codex/playbook.
6. Eseguire:
   ```bash
   node scripts/sync-portable-agents.js
   node scripts/check-agents-doc.js
   ```
7. Controllare il diff, verificando che Copilot/Gemini non cambino.
8. Riportare nel riepilogo:
   - file modificati;
   - mappatura permessi applicata;
   - comandi eseguiti;
   - eventuali limiti o follow-up.

## Mission card pronta per Codex

```markdown
Mission:
Allineare i permessi runtime degli agenti Codex con la separazione read/write gia' presente nei target Copilot e Gemini/Antigravity, aggiungendo `sandbox_mode` al canonico YAML e alla generazione `.codex/agents/*.toml`.

Owned write scope:
- docs/agents/canonical-subagents.yaml
- scripts/portable-agents-lib.js
- scripts/check-agents-doc.js, solo se necessario
- .codex/agents/*.toml, solo come output generato
- .codex/agents/README.md
- docs/agents/local-orchestration-playbook.md

Allowed read scope:
- .codex/agents/
- .copilot/agents/
- .gemini/agents/
- scripts/
- docs/agents/

Do not touch:
- modelli esistenti
- tool Copilot
- tool Gemini/Antigravity
- ruoli canonici
- struttura generale delle skill
- configurazioni MCP non correlate
- runtime generati a mano senza passare dal generatore

Behavioral requirements:
- mantenere lo YAML canonico come fonte di verita'
- mantenere generazione deterministica
- introdurre solo `sandbox_mode` per Codex
- non usare `danger-full-access`
- evitare refactor ampi del parser custom

Validation expected:
- node scripts/sync-portable-agents.js
- node scripts/check-agents-doc.js
- grep -R "sandbox_mode" .codex/agents
- git diff -- .copilot/agents .gemini/agents

Output needed:
- elenco file modificati
- mapping finale ruolo -> sandbox_mode
- comandi eseguiti e risultato
- eventuali rischi residui

Stop condition:
Fermarsi e segnalare se il parser YAML richiede un refactor ampio, se i check esistenti falliscono per cause non correlate, o se la modifica comporta cambi non richiesti ai target Copilot/Gemini.
```