# WP Agents Routing — Catalogo semantico e policy

**Stato:** implementato
**Data:** 20 luglio 2026
**Ambito:** agenti portabili, installer runtime, hook `UserPromptSubmit`, hotword `!agents`

## Obiettivo

Rendere deterministica e verificabile la scelta dei subagent senza introdurre auto-delega nell'hook. `!agents` continua a imporre almeno una delega delimitata; il nuovo layer indica quale ruolo portabile preferire e, quando disponibile, quale skill specialistica nominare nel task delegato.

## Decisioni

- `docs/agents/canonical-subagents.yaml` resta l'unica fonte autoritativa.
- `scripts/hooks/agent-catalog.json` è un artefatto generato e ignorato da Git, non mantenuto manualmente.
- La fonte canonica, il builder, lo schema e i test sono versionati; installer e gate di test rigenerano il catalogo prima dell'uso.
- Il catalogo contiene solo metadata di routing: nessun prompt completo, tool, comando, path utente o segreto.
- L'installer produce `~/.mcp-servers/agent-availability.json` con `configured`, `unknown` e `unavailable`.
- La policy è pura e non invoca `spawn_agent` né altri host API.
- Un agente esplicitamente nominato dall'utente costituisce un lock.
- Gli agenti `unavailable` sono esclusi; `configured` prevale su `unknown`.
- Il ruolo generico/default non appartiene al catalogo e non viene raccomandato quando esiste un ruolo dichiarato compatibile.
- Le skill di dominio non vengono duplicate in nuovi agenti: il resolver produce una coppia agente+skill.

## Contratto catalogo v1

Ogni record contiene:

- `id`, `kind: "agent"` e `semanticSummary`;
- `routingRole` e `taskPhases`;
- `capabilities`, `notFor` e `skillAffinities`;
- `writePolicy` derivata dai permessi runtime;
- `availability`, sovrascritta dal manifest locale.

La fingerprint SHA-256 esclude `generatedAt` e la fingerprint stessa. Le affinity devono risolversi contro il catalogo delle skill distribuibili.

## Policy

`resolveSubagentRouting` riceve testo, opzioni hotword, routing skill e catalogo agenti effettivo. Restituisce:

```json
{
  "mode": "required",
  "source": "deterministic-agent-policy",
  "recommendedAgents": [
    {
      "agentId": "technical_analyst",
      "skillId": "mcp-technical-analyst",
      "availability": "configured",
      "writePolicy": "read-only",
      "reasonCodes": ["analysis-task", "skill-affinity"]
    }
  ],
  "rejectedAgents": [],
  "fallbackReason": null,
  "carryForwardToImplementation": true
}
```

Il ranking usa segnali deterministici di fase, affinity con le skill già classificate, availability e ordine stabile. Il massimo è due raccomandazioni; un lock esplicito riduce l'output a un agente.

## Planning mode

Quando l'host è in planning mode, il piano deve registrare:

- agente raccomandato;
- skill associata;
- ownership delimitata;
- validazione o handoff atteso.

La delega svolta per preparare il piano non soddisfa la futura implementazione. La fase esecutiva deve applicare nuovamente la delega specializzata pianificata, salvo cambio di scope o indisponibilità sopravvenuta.

## Impatto sulle WP successive

### Milestone A

Il catalogo e la policy agenti entrano nella release deterministica: nessuna rete, evaluator o auto-spawn. Il routing skill/MCP resta autoritativo per il contenuto; il routing agenti governa solo la forma della delega.

### WP6 — Client evaluator

L'evaluator continua a selezionare esclusivamente skill e MCP. Non può inventare o selezionare agenti. La policy agenti consuma il risultato locale validato solo come possibile affinity, mantenendo lock e availability deterministici.

### WP7 — Privacy e resilienza

Il catalogo agenti è sicuro da serializzare perché non contiene prompt runtime o dati operativi. Il manifest di availability resta locale e non deve essere inviato integralmente a provider remoti.

### WP8–WP9 — Analytics

Un eventuale evento può registrare `subagentMode`, source, agent ID raccomandati, reason code e applicazione del carry-forward. Non deve registrare il testo del task delegato, prompt del subagent o contenuto delle risposte. La contabilizzazione di sessioni subagent resta separata dalla raccomandazione.

### WP10 — Eval

Il dataset deve includere casi per ruolo esplicito, generic fallback evitato, affinity agente+skill, agenti unavailable, planning carry-forward e prompt compositi. Le metriche agenti devono restare separate dalla precisione skill/MCP.

### WP11 — Installer e GUI

L'installer deve rigenerare il catalogo e aggiornare il manifest dopo l'applicazione del piano. La GUI può mostrare availability e fingerprint, ma non deve consentire di modificare metadata semantici locali fuori dalla fonte canonica.

## Compatibilità e sicurezza

- `subagentMode=off` conserva il comportamento precedente.
- L'hook mantiene massimo due blocchi di hint complessivi.
- Nessuna modifica a stdin/stdout oltre al testo controllato aggiuntivo quando la delega è richiesta.
- Nessun dato operativo MCP viene aggiunto al catalogo agenti.
- Il main agent conserva decisioni, integrazione e risposta finale.