«Per favore, modifica solo le bozze» è un'istruzione di lavoro sensata. Ma non è ancora un punto di controllo tecnico. Un hook può applicare una regola ricorrente nel punto in cui è stata preparata un'azione specifica. In questo modo una richiesta generica diventa una decisione verificabile su una particolare chiamata a uno strumento.
La guida di riferimento di Claude Code descrive, tra gli altri eventi, PreToolUse: si verifica dopo che i parametri dello strumento sono stati creati e prima che la chiamata venga elaborata. L'hook può restituire una decisione. Gli esempi seguenti illustrano una nostra bozza; per essi non è stata installata né eseguita alcuna configurazione di hook.
Quali informazioni sono disponibili nel punto di decisione?
Il nostro progetto di apprendimento contiene una cartella delle bozze e, accanto, un file di riferimento. L'agente deve modificare solo le bozze. Una regola sensata considera quindi la destinazione specifica di un'azione di scrittura. Non decide se l'intero contenuto della conversazione sia affidabile.
L'interfaccia fornisce il nome dello strumento e l'input. Per una richiesta su file adatta, da questi si può determinare la destinazione. Uno strumento sconosciuto o un input incomprensibile dovrebbero attivare uno stato a sé. Un errore silenzioso nel programma di controllo non deve sembrare un percorso verificato con successo.
Una decisione è un valore di ritorno strutturato
Un valore di rifiuto illustrativo nella struttura documentata di PreToolUse si presenta così. La motivazione è formulata da noi; descrive la regola locale, non una valutazione generale dell'utente.
{
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "The target file is outside the drafts area."
}
}Questo estratto è il valore di ritorno, non un programma di controllo completo. Non contiene né la registrazione dell'hook né la lettura e il controllo dell'input. Proprio questa separazione è utile: la regola, la valutazione tecnica e l'output dell'interfaccia possono essere esaminati in modo indipendente.
L'appartenenza a un percorso è più di un prefisso corrispondente
Un semplice confronto tra stringhe di caratteri può confondere cartelle vicine con nomi simili. La tua regola dovrebbe quindi lavorare con percorsi risolti in modo univoco e verificare se la destinazione appartiene effettivamente alla cartella radice prevista. Separatori diversi e collegamenti vanno tenuti in considerazione nell'ambiente in uso.
own rule logic, schematic:
Input fully readable? Otherwise check status unknown.
Tool belongs to the write path being handled? Otherwise not checked.
Resolve target and permitted root unambiguously.
Target really inside the root? Otherwise deny.
Assess only the specific call being handled.Questo abbozzo volutamente non suggerisce una protezione completa. In particolare i programmi esterni, che a loro volta modificano altri file, richiedono una valutazione diversa rispetto a un singolo campo file. Un file iniziale consentito non dice ancora nulla su quali azioni successive esegua uno script.
Quattro prove rendono visibile la portata
In un progetto usa e getta, crea un file consentito, un riferimento protetto e una cartella vicina con un nome simile. Aggiungi un input non valido. Per ogni caso, annota in anticipo quale decisione ti aspetti. Poi esamina sia il valore di ritorno sia l'esecuzione effettiva.
Verifica anche un malfunzionamento del programma di controllo stesso. Il comportamento in caso di errore dipende dall'evento e dalla configurazione e fa quindi parte dell'accettazione. L'assenza di un messaggio non prova che la regola sia stata verificata con successo.
Per ogni prova, annota anche se l'hook è stato effettivamente raggiunto. Un'azione che segue un percorso diverso può aggirare la regola senza che il suo controllo interno dei percorsi abbia funzionato in modo errato.
Un hook non è un quadro di protezione completo
PreToolUse riguarda le chiamate agli strumenti. Il contesto può entrare nella sessione per altre vie; la guida di riferimento attuale descrive esplicitamente dei limiti a questo proposito. Un hook quindi non sostituisce né i permessi né il controllo dell'ambiente, e non è una protezione generale contro la prompt injection.
Inizia con una singola regola locale e documenta i percorsi che copre e quelli che non copre. Il vantaggio tecnico sta in un punto di controllo comprensibile. Se questo punto di controllo sia configurato correttamente nella tua versione deve dimostrarlo una prova effettiva con le interfacce appropriate.
Fonti e stato della documentazione: 25 ottobre 2026.
