# Analisi tecnica aggiornata — `!quick` e subagents opt-in in `mcp-servers` > **Aggiornamento di policy:** la hotword iniziale `!agents` è ora un mandato di orchestrazione: produce `subagentMode=required` e richiede almeno una delega concreta. Le richieste testuali senza hotword restano `requested`; le parti storiche seguenti vanno lette alla luce di questo contratto. ## Sintesi esecutiva La decisione aggiornata cambia in modo sostanziale la parte sugli agenti: - `!quick` resta la hotword per richiedere **light context**. - `!agents` è la hotword per **imporre orchestrazione** tramite subagents. - Non serve una hotword di bypass come `!direct`, perche' l'uso dei subagents e' gia' **opt-in by design**. - Non va introdotta alcuna attivazione automatica dei subagents tramite euristiche. - Il comportamento di default deve restare: **main agent diretto, nessun subagent**. La modifica consigliata diventa quindi piu' semplice e piu' robusta: ```text !quick -> usa contesto leggero quando possibile !agents -> impone almeno una delega a un subagent per un sotto-task delimitato ``` Il punto chiave e' separare due dimensioni indipendenti: 1. **Context routing**: quanto contesto caricare. 2. **Subagent routing**: se l'utente ha richiesto esplicitamente l'uso dei subagents. La prima dimensione puo' usare euristiche conservative per distinguere task generici da task repository. La seconda invece non deve usare euristiche automatiche: i subagents si attivano solo con `!agents` o con una richiesta esplicita nel prompt, per esempio “usa un subagent per leggere questi file”. ## Decisione finale proposta | Tema | Decisione aggiornata | |---|---| | Carattere hotword | `!`, non `@`, per evitare conflitti con IDE e context picker | | Light context | `!quick` | | Subagents | `!agents` | | Bypass subagents | Non necessario | | Hotword `!direct` | Da non introdurre | | Attivazione automatica subagents | Da non introdurre | | Default senza hotword | Main agent diretto, contesto full se il task sembra progettuale | | Obiettivo subagents | Token/cost optimization su richiesta esplicita | | Parallelismo | Non e' obiettivo primario | | Responsabilita' finale | Sempre main agent | ## Razionale della correzione Nel design precedente erano state considerate tre modalita' agentiche: ```ts type AgentMode = "auto" | "force" | "direct"; ``` Questa modellazione e' piu' complessa del necessario e rischia di introdurre un comportamento contrario al design atteso: l'attivazione automatica dei subagents. Se i subagents sono gia' per design uno strumento su richiesta, allora: - `auto` non va aggiunto; - `direct` non serve, perche' il default e' gia' diretto; - `force` puo' essere rinominato o interpretato come richiesta esplicita, non come delega cieca. Modello aggiornato consigliato: ```ts type ContextMode = "light" | "full"; type SubagentMode = "off" | "requested"; interface PromptRoutingOptions { contextMode: ContextMode; subagentMode: SubagentMode; strippedPrompt: string; detectedHotwords: string[]; reasons: string[]; warnings: string[]; } ``` Semantica: - `subagentMode="off"`: non usare subagents. Questo e' il default. - `subagentMode="required"`: la hotword iniziale `!agents` impone al main agent di delegare almeno un sotto-task delimitato a un ruolo appropriato prima di completare la richiesta. - `subagentMode="requested"`: una frase esplicita senza hotword richiede delega ma resta discrezionale; il main agent valuta sotto-task delimitati, sicuri e convenienti in termini token/costo. Alternativa, se si vuole mantenere il nome `AgentMode` per compatibilita' interna: ```ts type AgentMode = "default" | "requested"; ``` Dove `default` significa main agent diretto e `requested` significa opt-in esplicito ai subagents. ## Scope funzionale aggiornato ### Hotword supportate | Hotword | Posizione valida | Effetto | |---|---|---| | `!quick` | Solo inizio prompt | Richiede light context | | `!agents` | Solo inizio prompt | Richiede/abilita subagents | Le hotword devono poter essere combinate: ```text !quick !agents analizza questi estratti e sintetizza i punti principali !agents cerca nei file indicati e fammi una sintesi !quick spiegami questa riga SQL ``` Le hotword riconosciute devono essere rimosse dal testo usato per routing, scoring e intent detection. ### Hotword non supportate Non introdurre: ```text !direct !noagents !bypass !nohooks ``` Motivazione: - `!direct` e' ridondante: il comportamento diretto e' gia' il default. - `!bypass` e `!nohooks` sono pericolose semanticamente: sembrano disattivare controlli, regole o policy. - `!noagents` e' inutile finche' non esiste un'automazione dei subagents da spegnere. ## Regole di context routing `!quick` agisce solo sul caricamento del contesto pesante, non sulle regole core. ### Comportamento atteso | Input | `contextMode` | `subagentMode` | Note | |---|---:|---:|---| | `!quick spiegami questa SQL` | `light` | `off` | risposta diretta, niente bootstrap pesante | | `!quick spiegami convert(varchar(10), DT, 103)` | `light` | `off` | domanda generica SQL | | `!agents analizza questi log` | `full` o `light` secondo contesto | `requested` | subagents opt-in | | `!quick !agents sintetizza questi log` | `light` se non repo task | `requested` | contesto leggero + subagents richiesti | | `correggi lo script installer` | `full` | `off` | task repository, main agent diretto | | `!quick implementa modifica agli hook` | `full` | `off` | repo task prevale su light | | `usa un subagent per leggere questi file` | `full` | `requested` | richiesta esplicita anche senza hotword | ### Precedenza 1. Regole core, safety, policy e tool guardrail restano sempre attivi. 2. Task repository esplicito forza `contextMode=full` anche con `!quick`. 3. `!agents` non forza `contextMode=full` da solo: abilita i subagents, ma il context routing resta separato. 4. In caso di dubbio sul context routing, scegliere `full`. 5. In caso di dubbio sui subagents, scegliere `off`. ## Regole di subagent routing ### Principio base I subagents non devono essere attivati automaticamente dagli hook. L'uso dei subagents e' opt-in: - tramite hotword iniziale `!agents`; - oppure tramite richiesta esplicita nel prompt, per esempio: - “usa un subagent per...”; - “delega a uno scout...”; - “fai analizzare questi file a un agente dedicato...”. ### Scopo primario I subagents servono principalmente a: - ridurre token consumati dal main agent; - usare modelli piu' economici per sotto-task semplici; - limitare il contesto fornito ai task secondari; - tenere il main agent focalizzato su integrazione, decisioni e risposta finale. Non devono essere usati principalmente per: - parallelizzare per forza; - aumentare velocita' a costo di piu' complessita'; - esternalizzare decisioni critiche; - delegare modifiche rischiose senza supervisione. ### Casi adatti ai subagents quando richiesti Usare subagents solo se richiesti e se il sotto-task e' delimitato, a basso rischio e conveniente: - lettura mirata di file lunghi; - estrazione di fatti da log, config, documentazione o codice; - sintesi locale di un documento o output verboso; - checklist di test manuale; - validazione semplice di un output gia' prodotto; - confronto circoscritto tra alternative; - ricerca puntuale di pattern in piu' file; - preparazione di bozza non decisionale. ### Casi da non delegare Anche con `!agents`, non delegare ciecamente: - decisioni architetturali finali; - modifiche coordinate su piu' file senza supervisione; - operazioni distruttive; - gestione credenziali, segreti, sicurezza o policy; - scelte irreversibili; - patch finale; - integrazione finale della risposta; - task cosi' piccoli che la delega costa piu' del beneficio. Il main agent mantiene sempre la responsabilita' conclusiva. ## Evidenze dal repository lette per l'analisi ### Hook `UserPromptSubmit` File principale: ```text scripts/hooks/sophia-user-prompt-submit.mjs ``` Evidenze osservate: - Il file e' gia' un motore euristico di routing. - Raccoglie stringhe da payload con campi come `prompt`, `userPrompt`, `input`, `message`, `content`, `text`, `messages`. - Analizza intent, skill score, guardrail e contesto repository. - Emette `hookSpecificOutput.additionalContext`. - Non risulta, dai file letti, una riscrittura effettiva del prompt utente. - Contiene gia' una categoria guardrail `subagents`, ma oggi produce solo un hint generico quando incontra parole come `subagent`, `delegazione`, `parallelismo`, `worker`, `scout`, `implementer`. Inferenza: - Il posto corretto per il parsing di `!quick` e `!agents` e' prima di scoring/tokenize/matchIntent. - Il testo da passare alle funzioni di scoring deve essere `strippedPrompt`, non il prompt originale con hotword. - Se l'host Codex non supporta replacement del prompt, le hotword saranno rimosse solo dal routing interno e dichiarate nello `additionalContext`. ### Hook `SessionStart` File: ```text scripts/hooks/sophia-session-start.mjs ``` Evidenze osservate: - Carica `AGENTS.md`. - Aggiunge sempre una istruzione `Sophia Taxonomy Bootstrap` per docs/memory. Inferenza: - `!quick` su `UserPromptSubmit` non puo' rimuovere contesto gia' iniettato a inizio sessione. - Per rendere `!quick` realmente efficace, conviene valutare una seconda fase in cui `SessionStart` resta minimale e la taxonomy docs/memory viene spostata nel percorso full-mode. - Questa parte va fatta con cautela per non rompere il comportamento consolidato. ### Regole e agenti File rilevanti: ```text AGENTS.md docs/mcp-skills-agents-development-guide.md docs/agents/local-orchestration-playbook.md docs/agents/canonical-subagents.yaml .codex/agents/README.md ``` Evidenze osservate: - `AGENTS.md` contiene governance minima e routing essenziale. - La guida viva documenta l'architettura MCP/Skills/Agents e gli hook Codex. - Il playbook locale definisce ruoli e disciplina di parallelismo/scope. - `canonical-subagents.yaml` contiene gia' ruoli distinti come `scout`, `technical_analyst`, `implementer`, `code_reviewer`, `test_writer`. - I runtime `.codex/agents/*.toml`, `.copilot/agents/*.agent.md`, `.gemini/agents/*.md` sono derivati da `docs/agents/canonical-subagents.yaml` e non vanno editati manualmente. Inferenza: - Non serve creare nuovi agenti per questa modifica. - Serve soprattutto correggere le regole di ingaggio: subagents opt-in, token/cost optimization, no automatic activation. ## Piano tecnico aggiornato ### Fase 1 — Parser hotword centralizzato Creare un modulo testabile, per esempio: ```text scripts/hooks/prompt-routing-options.mjs ``` Responsabilita': - riconoscere hotword solo all'inizio del prompt; - supportare `!quick` e `!agents`; - rimuovere le hotword dal testo usato dal routing; - rilevare task repository per forzare context full; - rilevare richiesta esplicita di subagents anche senza hotword; - produrre struttura stabile. Pseudo-interfaccia: ```ts type ContextMode = "light" | "full"; type SubagentMode = "off" | "requested"; interface PromptRoutingOptions { contextMode: ContextMode; subagentMode: SubagentMode; strippedPrompt: string; detectedHotwords: string[]; reasons: string[]; warnings: string[]; } ``` Pseudo-logica: ```js const HOTWORDS = new Set(['!quick', '!agents']); function parsePromptRoutingOptions(rawText) { const leadingWhitespace = rawText.match(/^\s*/)?.[0] || ''; const trimmedLeft = rawText.slice(leadingWhitespace.length); const parts = trimmedLeft.split(/\s+/); const detectedHotwords = []; let index = 0; while (index < parts.length && HOTWORDS.has(parts[index].toLowerCase())) { detectedHotwords.push(parts[index].toLowerCase()); index += 1; } const strippedPrompt = parts.slice(index).join(' ').trim(); const hasQuick = detectedHotwords.includes('!quick'); const hasAgents = detectedHotwords.includes('!agents'); const repoTaskDetected = detectRepoTask(strippedPrompt); const explicitSubagentRequest = hasAgents || detectExplicitSubagentRequest(strippedPrompt); const contextMode = repoTaskDetected ? 'full' : hasQuick ? 'light' : 'full'; const subagentMode = explicitSubagentRequest ? 'requested' : 'off'; return { contextMode, subagentMode, strippedPrompt, detectedHotwords, reasons: buildReasons({ hasQuick, hasAgents, repoTaskDetected, explicitSubagentRequest }), warnings: [] }; } ``` Nota: in questa versione non serve `detectGenericQuestion` per attivare subagents. Al massimo puo' essere usata, in modo conservativo, solo per context light se si decide di introdurre light automatico. Per ora la raccomandazione e' mantenere `!quick` esplicito e full come default. ### Fase 2 — Integrare il parser in `sophia-user-prompt-submit.mjs` Modifiche consigliate: 1. Dopo il calcolo di `text`, chiamare `parsePromptRoutingOptions(text)`. 2. Usare `routing.strippedPrompt` per: - `tokenize`; - `scoreSkills`; - `matchComposite`; - `matchGuardrails`; - `matchIntent`; - pattern Chrome/reuse e simili. 3. Aggiungere un hint di controllo routing quando sono presenti hotword o richiesta subagents. 4. Mantenere fallback conservativo: se il parser fallisce, usare comportamento esistente. Esempio di `additionalContext` per `!quick`: ```text Sophia routing control: contextMode=light reason=hotword:!quick. Core rules, safety and tool guardrails remain active. Avoid project-heavy docs/memory/repo bootstrap unless the stripped prompt requires it. ``` Esempio per `!agents`: ```text Sophia routing control: subagentMode=requested reason=hotword:!agents. Subagents are opt-in and should be used only for bounded, low-risk extraction, summarization, checklist or validation tasks when token/cost efficient. Main agent owns final decisions and response. ``` Esempio combinato: ```text Sophia routing control: contextMode=light reason=hotword:!quick; subagentMode=requested reason=hotword:!agents. Core rules remain active. Keep delegated subagent context minimal and bounded. ``` ### Fase 3 — Logging analytics Aggiungere campi al logging gia' esistente: ```js logAnalyticsEventBestEffort({ ts: new Date().toISOString(), event: "UserPromptSubmit", hook: "sophia-user-prompt-submit", matched: hints.length > 0, contextMode: routing.contextMode, subagentMode: routing.subagentMode, detectedHotwords: routing.detectedHotwords, reasons: routing.reasons }); ``` Log testuale consigliato, se il sistema produce log leggibili: ```text [mcp-context] mode=light reason=hotword:!quick [mcp-context] mode=full reason=repo-task-detected-overrides:!quick [mcp-agents] mode=requested reason=hotword:!agents [mcp-agents] mode=off reason=default-opt-in-design ``` ### Fase 4 — Refactor prudente di `SessionStart` Questa fase e' consigliata, ma va trattata separatamente per ridurre rischio regressioni. Obiettivo: - `SessionStart` deve caricare solo bootstrap core. - La discovery docs/memory taxonomy non deve essere sempre suggerita per ogni sessione se l'utente poi fa una domanda generica. Opzione conservativa: 1. Lasciare `AGENTS.md` in `SessionStart`. 2. Sostituire la taxonomy instruction sempre-attiva con una formulazione condizionale: ```text For project/repository tasks, discover docs/memory taxonomy before relying on project knowledge. For generic quick questions, do not perform docs/memory bootstrap unless explicitly needed. ``` 3. In `UserPromptSubmit`, quando `contextMode=full`, aggiungere la taxonomy instruction completa. 4. In `contextMode=light`, aggiungere un reminder opposto: non caricare docs/memory/repo context pesante se non necessario. Questa modifica rende `!quick` piu' efficace senza eliminare i guardrail core. ### Fase 5 — Aggiornare `AGENTS.md` Aggiungere una sezione breve, coerente con il fatto che `AGENTS.md` deve restare sintetico: ```md ## Hotword operative e subagents - `!quick` richiede contesto leggero: restano attivi guardrail core, safety e policy, ma non caricare docs/memory/repo context pesante salvo necessita' evidente. - `!agents` richiede esplicitamente l'uso dei subagents quando utile per sotto-task semplici, delimitati e a basso rischio. - I subagents sono opt-in: non attivarli automaticamente tramite euristiche. - Il default e' main agent diretto senza subagents. - Lo scopo primario dei subagents e' token/cost optimization, non parallelismo. - Il main agent mantiene responsabilita' su decisioni, patch finale, integrazione e risposta conclusiva. ``` Non aggiungere `!direct`. ### Fase 6 — Aggiornare `docs/agents/local-orchestration-playbook.md` Aggiungere una sezione esplicita: ```md ## Subagents opt-in and token/cost discipline Subagents are opt-in. Do not activate them automatically from generic heuristics. Use them only when the user explicitly asks, for example with `!agents` or direct delegation wording. Primary purpose is token/cost optimization, not parallelism. Delegate bounded, low-risk discovery, extraction, summarization, checklist generation, and simple validation. Keep delegated context minimal. Do not delegate final architecture, security-sensitive decisions, coordinated patches, irreversible operations, or final response integration. ``` ### Fase 7 — Valutare `canonical-subagents.yaml` Non e' obbligatorio modificare subito il YAML canonico. Se si decide di rafforzare le policy dei ruoli, intervenire solo su `docs/agents/canonical-subagents.yaml` e poi rigenerare i runtime derivati. Possibile aggiunta a `scout`: ```yaml prioritize: - Token-efficient scoped discovery with minimal necessary context. - Extract facts, paths, constraints, and candidate files for the main agent. avoid: - Making final architectural, security, or implementation decisions. - Reading broad repository context when the delegated subtask is narrow. ``` Possibile aggiunta a `test_writer`: ```yaml prioritize: - Produce bounded test checklists from provided evidence without expanding scope. avoid: - Turning checklist generation into broad product analysis unless explicitly requested. ``` Dopo modifiche al canonico: ```bash node scripts/sync-portable-agents.js node scripts/check-agents-doc.js ``` ## Test e validazioni consigliate ### Test parser | Input | Atteso | |---|---| | `!quick spiegami SQL` | `contextMode=light`, `subagentMode=off`, hotword rimossa | | `!agents analizza questi log` | `subagentMode=requested`, hotword rimossa | | `!quick !agents sintetizza questi log` | `contextMode=light`, `subagentMode=requested` | | `ciao !quick spiegami` | nessuna hotword riconosciuta | | `!quick implementa modifica agli hook` | `contextMode=full`, reason repo task override | | `usa un subagent per leggere questi file` | `subagentMode=requested` anche senza hotword | | `spiegami questa SQL` | `contextMode=full` o comportamento esistente, `subagentMode=off` | ### Test da rimuovere/non creare Non creare test per: - `!direct`; - conflitto `!agents !direct`; - `agentMode=auto`; - bypass automatico subagents. ### Smoke hook Aggiornare `scripts/smoke-codex-hooks.js` con fixture minime: - `prompt-quick.json` - `prompt-agents.json` - `prompt-quick-agents.json` - `prompt-quick-repo-task.json` - `prompt-explicit-subagent-request.json` Asserzioni: - `!quick` produce `contextMode=light` quando non e' un repo task. - repo task con `!quick` produce `contextMode=full`. - `!agents` produce `subagentMode=requested`. - senza `!agents` e senza richiesta esplicita, `subagentMode=off`. - le hotword non contaminano skill scoring e intent detection. - comportamento esistente senza hotword non regredisce. ### Comandi ```bash node scripts/smoke-codex-hooks.js node scripts/generate-codex-hooks.js --root . --force-output node scripts/generate-antigravity-hooks.js --root . --force-output ``` Se cambiano agenti canonici: ```bash node scripts/sync-portable-agents.js node scripts/check-agents-doc.js ``` Se cambia installer/runtime generale: ```bash npm test ``` ## Rischi e mitigazioni ### Rischio 1 — `!quick` interpretato come bypass controlli Mitigazione: - documentare che `!quick` non disattiva core rules, safety, policy o tool guardrail; - evitare nomi come `!bypass`, `!nohooks`, `!unsafe`; - logging esplicito: `Core rules remain active`. ### Rischio 2 — Subagents usati automaticamente nonostante il design opt-in Mitigazione: - non introdurre `agentMode=auto`; - default `subagentMode=off`; - test regressivo che verifica assenza di subagent directive senza `!agents` o richiesta esplicita; - aggiornare AGENTS/playbook con regola “subagents are opt-in”. ### Rischio 3 — `!agents` interpretato come parallelismo obbligatorio Mitigazione: - usare wording `subagentMode=requested`, non `parallel`; - additionalContext deve parlare di token/cost optimization; - richiedere sotto-task bounded, low-risk, minimal context; - main agent mantiene decisioni e risposta finale. ### Rischio 4 — `!quick` non puo' eliminare contesto gia' caricato da `SessionStart` Mitigazione: - fase 1: implementare `!quick` su `UserPromptSubmit` senza cambiare `SessionStart`; - fase 2: rendere condizionale la taxonomy bootstrap; - non rimuovere AGENTS/core bootstrap. ### Rischio 5 — Prompt rewrite non supportato dall'host Codex Mitigazione: - non basare la fase 1 su replacement prompt; - usare `strippedPrompt` internamente per scoring; - documentare il limite; - se Codex supporta un campo ufficiale per replacement, aggiungere solo dopo verifica. ## Acceptance criteria aggiornati La modifica e' accettabile quando: 1. `!quick` e `!agents` sono riconosciuti solo all'inizio del prompt. 2. Le hotword riconosciute sono escluse dal testo usato per scoring/hints. 3. `!quick` imposta `contextMode=light` solo quando non c'e' un task repository esplicito. 4. Un task repository esplicito forza `contextMode=full` anche con `!quick`. 5. Senza `!agents` o richiesta esplicita, `subagentMode=off`. 6. Con `!agents`, `subagentMode=requested`. 7. Non esiste attivazione automatica dei subagents tramite euristiche. 8. Non esiste hotword `!direct`. 9. Core rules, safety, policy e tool guardrail restano sempre attivi. 10. Logging include `contextMode`, `subagentMode`, hotword rilevate e reason. 11. Smoke test coprono hotword, repo override e regressione senza hotword. 12. Documentazione locale aggiornata senza modificare manualmente runtime derivati. ## Prompt operativo aggiornato per Codex ```text Nel repository `sophiadeveloper/mcp-servers`, implementa una modifica incrementale e conservativa per supportare hotword di routing prompt e chiarire l'uso opt-in dei subagents. Decisione funzionale aggiornata: - Supportare `!quick` per richiedere light context. - Supportare `!agents` per richiedere esplicitamente l'uso dei subagents. - Non introdurre `!direct`. - Non introdurre attivazione automatica dei subagents. - Il default resta main agent diretto senza subagents. - I subagents sono opt-in by design: usarli solo con `!agents` o richiesta esplicita nel prompt. Obiettivi: 1. separare context routing e subagent routing; 2. mantenere sempre attive core rules, safety, policy e tool guardrail; 3. evitare caricamento di contesto pesante per domande generiche quando l'utente usa `!quick`; 4. consentire subagents solo su richiesta esplicita, con finalita' primaria di token/cost optimization; 5. evitare che i subagents siano interpretati come parallelismo automatico. Modello dati consigliato: ```ts type ContextMode = "light" | "full"; type SubagentMode = "off" | "requested"; interface PromptRoutingOptions { contextMode: ContextMode; subagentMode: SubagentMode; strippedPrompt: string; detectedHotwords: string[]; reasons: string[]; warnings: string[]; } ``` Requisiti hotword: 1. Riconoscere solo hotword a inizio prompt. 2. Supportare solo: - `!quick` - `!agents` 3. Permettere combinazioni, per esempio: - `!quick !agents sintetizza questi log` 4. Rimuovere le hotword dal testo usato per scoring, intent detection e hints. 5. Non aggiungere `!direct`, `!bypass`, `!nohooks`, `!noagents`. Requisiti context routing: 1. `!quick` imposta `contextMode=light` solo se il prompt stripped non e' un task repository esplicito. 2. Task repository espliciti devono forzare `contextMode=full`, anche con `!quick`. 3. In caso di dubbio sul contesto, usare `full`. 4. `!quick` non deve mai disattivare regole core, safety, policy o tool guardrail. Requisiti subagent routing: 1. Default: `subagentMode=off`. 2. `!agents` imposta `subagentMode=requested`. 3. Anche senza hotword, una richiesta esplicita tipo “usa un subagent per...” puo' impostare `subagentMode=requested`. 4. Non attivare subagents automaticamente tramite euristiche su task generici. 5. Con `subagentMode=requested`, usare subagents solo per sotto-task semplici, delimitati, a basso rischio e convenienti in termini token/costo. 6. Il main agent mantiene responsabilita' su decisioni, patch finale, integrazione e risposta conclusiva. Interventi richiesti: 1. Creare un parser testabile, per esempio `scripts/hooks/prompt-routing-options.mjs`. 2. Integrare il parser in `scripts/hooks/sophia-user-prompt-submit.mjs`. 3. Usare `strippedPrompt` per scoring/hints. 4. Aggiungere `additionalContext` chiaro con `contextMode`, `subagentMode` e reason. 5. Aggiungere logging analytics con `contextMode`, `subagentMode`, `detectedHotwords`, `reasons`. 6. Valutare in modo conservativo se rendere condizionale la taxonomy bootstrap in `scripts/hooks/sophia-session-start.mjs`; non rimuovere il core bootstrap. 7. Aggiornare `AGENTS.md` con regole concise per `!quick`, `!agents` e subagents opt-in. 8. Aggiornare `docs/agents/local-orchestration-playbook.md` con disciplina token/cost delegation. 9. Aggiornare la guida viva se pertinente. 10. Aggiungere fixture e smoke test. Esempi attesi: Input: `!quick spiegami convert(varchar(10), RIGHE.DT_CONS_PREC, 103)` Routing: - `contextMode=light` - `subagentMode=off` - `strippedPrompt=spiegami convert(varchar(10), RIGHE.DT_CONS_PREC, 103)` Input: `!agents analizza questi log e dimmi le anomalie principali` Routing: - `subagentMode=requested` - eventuale delega solo per estrazione/sintesi/validazione semplice - main agent integra e decide la risposta finale Input: `!quick !agents sintetizza questi log` Routing: - `contextMode=light` se non e' task repository - `subagentMode=requested` Input: `!quick implementa modifica agli hook Codex` Routing: - `contextMode=full` - reason: repo task overrides `!quick` - `subagentMode=off` se non e' presente `!agents` Input: `correggi lo script installer` Routing: - `contextMode=full` - `subagentMode=off` Validazioni richieste: - `node scripts/smoke-codex-hooks.js` - `node scripts/generate-codex-hooks.js --root . --force-output` - `node scripts/generate-antigravity-hooks.js --root . --force-output` - se cambi `docs/agents/canonical-subagents.yaml`: - `node scripts/sync-portable-agents.js` - `node scripts/check-agents-doc.js` Non modificare manualmente file runtime derivati in `.codex/agents`, `.copilot/agents` o `.gemini/agents`. Documenta eventuale limite se Codex hook non supporta la riscrittura reale del prompt. ``` ## Delta rispetto alla versione precedente del documento Da rimuovere: ```text !direct agentMode=auto agentMode=direct conflitto !agents vs !direct attivazione automatica subagents hotword di bypass subagents ``` Da mantenere: ```text !quick !agents core rules sempre attive context light vs full logging e reason test hotword subagents come token/cost optimization responsabilita' finale del main agent ``` Da aggiungere/chiarire: ```text subagents opt-in by design default = main agent diretto nessuna euristica automatica per subagents !agents = richiesta esplicita, non parallelismo obbligatorio ``` ## Prossimi passi consigliati 1. Implementare parser e test unitari senza toccare subito `SessionStart`. 2. Integrare il parser in `sophia-user-prompt-submit.mjs` usando `strippedPrompt` per scoring. 3. Aggiornare smoke test. 4. Aggiornare `AGENTS.md` e playbook locale. 5. Valutare in una seconda PR il refactor del bootstrap docs/memory di `SessionStart`. 6. Valutare solo successivamente modifiche a `canonical-subagents.yaml`.