# Codex user hooks Sophia MCP

Versione: 2026-05-13

## Scopo

Gli hook Codex sono un booster opzionale per routing e reminder operativi.
Il supporto ufficiale di questo repository, in questa fase, e' limitato agli
hook Codex documentati da OpenAI. Il file generato non e' pensato per essere
usato direttamente come configurazione hooks di VS Code/Copilot.

Non sostituiscono:

- `AGENTS.md` e regole di repository;
- `SKILL.md` e skill installate;
- server MCP e relative configurazioni;
- decisione dell'agente su quale tool usare.

In questa fase il repository genera solo un `hooks.json` ispezionabile. La
scrittura in `~/.codex/hooks.json` resta manuale.

## Compatibilita' Host

### Supportato ora

- Codex CLI / runtime Codex con configurazione utente `~/.codex/hooks.json`.
- Eventi Codex usati: `SessionStart`, `UserPromptSubmit`, `PreToolUse`.
- Output Codex usati:
  - `hookSpecificOutput.additionalContext` per `SessionStart`;
  - `hookSpecificOutput.additionalContext` per `UserPromptSubmit`;
  - `systemMessage` top-level per `PreToolUse`.

### Non supportato ora

VS Code/Copilot hooks resta fuori scope per questa micro-milestone. Anche se i
concetti sono simili, non va trattato come compatibile per copia diretta perche':

- il formato della configurazione hook e' diverso da quello generato per Codex;
- il supporto VS Code/Copilot e' ancora Preview/sperimentale;
- i matcher di VS Code/Copilot hanno semantica diversa e, nelle versioni Preview,
  possono non filtrare gli eventi come ci si aspetta;
- `UserPromptSubmit` in VS Code/Copilot non e' equivalente al `UserPromptSubmit`
  Codex usato qui per iniettare `additionalContext`;
- i payload evento e le garanzie su `cwd`, `tool_name` e campi specifici possono
  differire.

Per una compatibilita' piena futura conviene aggiungere un target separato, ad
esempio `scripts/generate-copilot-hooks.js`, invece di rendere ambiguo
`generate-codex-hooks.js`.

## Generazione

Da root repository:

```bash
node scripts/generate-codex-hooks.js --root .
node scripts/generate-codex-hooks.js --root . --force-output
node scripts/generate-codex-hooks.js --root . --fragment --output ./codex-hooks.generated.json --force-output
node scripts/generate-codex-hooks.js --root . --output ./generated/codex-hooks.json
node scripts/generate-codex-hooks.js --root . --home <home-temporanea> --check-config --json
```

Lo script:

- genera comandi `node` con path assoluti agli script in `scripts/hooks/`;
- se `--output` e' omesso, scrive in `codex-hooks.generated.json` nella root del repository;
- aggiunge il marker `--managed-by sophia-mcp-hooks`;
- non legge e non modifica `~/.codex/hooks.json`;
- non crea backup nel profilo utente;
- non patcha `~/.codex/config.toml`.

`codex-hooks.generated.json` e' ignorato da git. Se il file output esiste, anche
quello default, la scrittura fallisce salvo `--force-output`.

## Installazione Manuale

1. Generare il file o frammento.
2. Aprire `~/.codex/hooks.json`.
3. Se il file contiene hook esistenti, preservarli.
4. Copiare o mergiare manualmente i blocchi generati sotto la chiave `hooks`.
5. Verificare che i comandi puntino al repository corretto.

Non cancellare hook di altri progetti. Un esempio di hook utente non gestito e'
in `fixtures/hooks/existing-user-hooks.json`.

## Config Codex

Gli hook possono richiedere che Codex abbia la feature abilitata nel file
`~/.codex/config.toml`.

Questo repository non modifica il file in questa micro-milestone. Il comando:

```bash
node scripts/generate-codex-hooks.js --root . --check-config
```

produce solo warning quando rileva `codex_hooks = false` o stato non
determinabile. La patch conservativa di `config.toml` resta nella M8 piena.

## Hook Disponibili

- `SessionStart`: carica in contesto il contenuto di `AGENTS.md` effettivo, che rimanda alle ulteriori istruzioni.
- `UserPromptSubmit`: routing hint su docs, memory, analyst, orchestrator, review, SQL, ColdFusion, projectfs/rules, Sophia/Yii, Git/Mantis, browser/UI, Office, token discipline e sub-agent.
  Per ColdFusion e Sophia/Yii usa un router context-aware: segnali espliciti nel prompt vincono sempre; segnali generici producono hint solo se il repo attivo contiene marker coerenti.
- `PreToolUse` SQL: reminder read-only via `systemMessage`, schema first, no `SELECT *`, bind/parameter.
- `PreToolUse` ColdFusion: reminder via `systemMessage` per `evaluate` passivo, no `cfhttp`, file write o mutazioni DB.

Tutti gli hook sono non bloccanti nella prima iterazione.

## Rollback Manuale

Per disabilitare gli hook Sophia:

1. ripristinare una copia preventiva di `~/.codex/hooks.json`, se esiste;
2. oppure rimuovere solo i blocchi/comandi che contengono:

```text
scripts/hooks/sophia-
--managed-by sophia-mcp-hooks
```

Non cancellare l'intera directory `~/.codex` e non cancellare configurazioni MCP
o `config.toml`.

## Troubleshooting

- **Path repo cambiato**: rigenerare `hooks.json` con il nuovo `--root` e aggiornare manualmente il profilo.
- **Hook non partono**: verificare `codex_hooks` in `~/.codex/config.toml` e riavviare Codex se necessario.
- **Windows path con backslash**: controllare il JSON generato, non modificare manualmente gli escape.
- **Troppi reminder**: ridurre i blocchi copiati o attendere la futura fase manifest/merge.
- **Repo non disponibile**: gli hook falliscono conservativamente; aggiornare o rimuovere i comandi nel profilo.

## Validazione

Smoke locale:

```bash
node scripts/smoke-codex-hooks.js
```

Lo smoke usa directory temporanee e non modifica il profilo utente.
Include anche una root temporanea con spazi nel path per verificare quoting e
path assoluti su Windows/Linux.