Hooks

Les hooks intègrent des commandes shell arbitraires au cycle de vie de la CLI Vibe Code pour filtrer, auditer ou réécrire le comportement de l'agent. Utilisez-les pour bloquer des appels d'outils dangereux, masquer des arguments avant l'exécution d'un outil, ajouter du contexte après le retour d'un outil ou forcer l'agent à reprendre une réponse insatisfaisante.

Déclarez-les dans un fichier hooks.toml et ils prennent effet au prochain lancement.

Les hooks sont déclarés dans hooks.toml. La CLI les recherche dans cet ordre :

1. ./.vibe/hooks.toml dans le répertoire de travail (niveau projet, chargé en premier, uniquement pour les dossiers de confiance).
2. ~/.vibe/hooks.toml dans votre répertoire personnel (niveau utilisateur, chargé en second).

Quand un même name apparaît dans les deux fichiers, l'entrée du projet l'emporte. Les hooks de niveau projet ne sont chargés que lorsque le répertoire de travail est de confiance.

Les sous-agents héritent de la configuration des hooks du parent, de sorte que les politiques s'appliquent de façon transitive.

Un plugin peut déclarer des hooks dans son fichier ai.mistral.vibe/hooks.toml, avec les mêmes champs que hooks.toml. Vibe préfixe chacun d'eux avec le nom du plugin, par exemple release-tools:audit-bash, et l'affiche dans /plugins.

Dans la version actuelle, Vibe n'exécute pas les hooks des plugins. Pour appliquer un hook, déclarez-le dans ./.vibe/hooks.toml ou ~/.vibe/hooks.toml.

Chaque hook est une table [[hooks]] :

[[hooks]]
name = "deny-rm-rf"
type = "pre_tool"
match = "bash"
command = "uv run python /path/to/guard-bash"
timeout = 60.0
strict = false
description = "Reject dangerous shell commands."

[[hooks]]
name = "deny-rm-rf"
type = "pre_tool"
match = "bash"
command = "uv run python /path/to/guard-bash"
timeout = 60.0
strict = false
description = "Reject dangerous shell commands."

Chaque hook est invoqué avec un objet JSON UTF-8 sur stdin contenant le contexte de session : session_id, parent_session_id, transcript_path, cwd et hook_event_name. Les hooks d'outil ajoutent des champs spécifiques (voir ci-dessous).

Les hooks répondent via leur code de sortie et leur stdout. Utilisez stderr pour les diagnostics et les logs de debug.

Champs universels de premier niveau dans la réponse JSON :

• system_message (chaîne, optionnel) — affiché à l'utilisateur dans l'interface.
• decision ("allow" | "deny", optionnel, défaut "allow") — l'effet de "deny" dépend du type de hook.
• reason (chaîne, optionnel) — accompagne decision: "deny".
• hook_specific_output (objet, optionnel) — charge utile spécifique à l'événement.

Les champs JSON inconnus sont tolérés à tous les niveaux (compatibilité ascendante). Les champs qui n'ont pas de sens pour le type de hook courant sont ignorés silencieusement.

Déclenché à chaque appel d'outil, avant la demande d'autorisation utilisateur. Le premier refus court-circuite les hooks pre_tool restants pour cet appel.

Reçoit (en plus du contexte de session) : tool_name, tool_call_id, tool_input (les arguments bruts du modèle).

tool_name est le nom complet de l'outil, comme file_system.bash ou <server>.<tool> pour les outils MCP. match accepte les noms complets comme les noms courts, donc match = "bash" fonctionne. Les commandes que l'agent lance en arrière-plan passent par process_start au lieu de bash, couvrez donc les deux dans vos gardes shell : match = "re:bash|process_start".

Peut renvoyer :

• decision: "deny" + reason — refuse l'appel ; reason devient l'erreur d'outil visible par le LLM.
• hook_specific_output.tool_input (objet) — remplacement complet des arguments du modèle. Le remplacement est de nouveau validé selon le schéma de l'outil ; un échec de validation devient un refus synthétisé. Les réécritures s'enchaînent de gauche à droite d'un hook à l'autre. Les arguments réécrits sont aussi ceux qu'affiche la demande d'autorisation, ceux avec lesquels l'outil s'exécute et ceux que voient les tours LLM suivants dans le message de l'assistant.
• system_message — interface uniquement.

Se déclenche à chaque appel d'outil si et seulement si le corps de l'outil s'est réellement exécuté. Il ne se déclenche pas si l'outil n'a jamais été exécuté : refus par pre_tool, refus au prompt d'approbation ou permission définie sur never.

Reçoit (en plus du contexte de session) :

• tool_name, tool_call_id
• tool_input (post-réécriture)
• tool_status — success ou failure
• tool_output — dict de résultat structuré ; null en cas d'échec
• tool_output_text — le texte courant que le LLM verra, mutable par les hooks précédents
• tool_error
• duration_ms — pas encore remonté (toujours 0)

Peut renvoyer :

• decision: "deny" + reason — remplace tool_output_text par reason. Le pipeline continue ; les hooks suivants voient le remplacement.
• hook_specific_output.additional_context (chaîne) — ajouté (avec un séparateur \n) à tool_output_text. Se combine avec un refus du même hook : le refus remplace d'abord, puis additional_context est ajouté au remplacement.
• system_message — interface uniquement.

Déclenché après chaque tour de l'assistant qui se termine sans appel d'outil en attente.

Reçoit (en plus du contexte de session) : aucun champ supplémentaire.

Peut renvoyer :

• decision: "deny" + reason — reason est injecté comme un nouveau message utilisateur demandant à l'agent de réessayer. Plafonné à 3 tentatives par tour pour l'ensemble des Hooks post_agent ; au-delà, Vibe accepte la réponse. Si un Hook post_agent échoue, Vibe accepte la réponse et affiche un avertissement.
• system_message — interface uniquement.

./.vibe/hooks.toml :

[[hooks]]
name = "deny-rm-rf"
type = "pre_tool"
match = "re:bash|process_start"
command = "python ./.vibe/hooks/guard-bash.py"
strict = true
description = "Reject rm -rf and other destructive shell commands."

[[hooks]]
name = "deny-rm-rf"
type = "pre_tool"
match = "re:bash|process_start"
command = "python ./.vibe/hooks/guard-bash.py"
strict = true
description = "Reject rm -rf and other destructive shell commands."

./.vibe/hooks/guard-bash.py :

import json
import sys

payload = json.load(sys.stdin)
command = payload.get("tool_input", {}).get("command", "")

if "rm -rf" in command:
    print(json.dumps({
        "decision": "deny",
        "reason": "rm -rf is blocked by the deny-rm-rf hook.",
    }))
    sys.exit(0)

# Passthrough: empty stdout, exit 0.

import json
import sys

payload = json.load(sys.stdin)
command = payload.get("tool_input", {}).get("command", "")

if "rm -rf" in command:
    print(json.dumps({
        "decision": "deny",
        "reason": "rm -rf is blocked by the deny-rm-rf hook.",
    }))
    sys.exit(0)

# Passthrough: empty stdout, exit 0.

Avec strict = true, tout crash du script ou toute sortie JSON malformée refuse également l'appel au lieu de se limiter à un avertissement.