IBM Bob

Lifecycle hooks

Exécute des commandes shell automatiquement à des moments clés d'une session Bob Shell pour journaliser l'activité, injecter du contexte ou bloquer des actions selon ta propre logique.

Les lifecycle hooks te permettent d'exécuter des commandes shell à des moments précis d'une session Bob Shell. Utilise-les pour journaliser l'activité, injecter du contexte dans le modèle, autoriser ou bloquer des actions, ou déclencher des automatisations de suivi — sans modifier Bob Shell.

Hooks disponibles

HookQuand il s'exécuteBloquantComportement de stdout
SessionStartUne fois au démarrage d'une sessionNonInjecté comme contexte
UserPromptSubmitÀ chaque envoi d'un promptOui (exit 2)Injecté comme contexte
PreToolUseAvant l'exécution d'un outil correspondantOui (exit 2)Ignoré
PostToolUseAprès la fin d'un outil correspondantNonIgnoré
StopQuand l'agent s'arrêteNonIgnoré

Configuration

Les hooks sont définis sous la clé hooks dans ton settings.json. Bob Shell fusionne les hooks de deux emplacements :
PortéeFichier
Global (tous les workspaces)~/.bob/settings/settings.json
Workspace (projet actuel).bob/settings.json

Les hooks globaux s'exécutent toujours. Les hooks de workspace sont fusionnés par-dessus les hooks globaux et s'appliquent uniquement au projet actuel.
Important :

Les hooks de workspace ne s'exécutent que dans les dossiers de confiance. Si le dossier actuel n'est pas de confiance, le fichier .bob/settings.json n'est pas chargé et les hooks de workspace sont silencieusement ignorés. Les hooks globaux dans ~/.bob/settings/settings.json ne sont pas affectés par la confiance des dossiers.

Pour plus de détails sur la localisation et le chargement des fichiers de configuration, consulte Configurer Bob Shell.

Schéma du hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^write_file$",
        "hooks": [
          {
            "type": "command",
            "command": "sh .bob/hooks/check.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Champs de configuration

ChampTypePar défautDescription
type"command"(aucun)Obligatoire. Seul command est pris en charge.
commandstring(aucun)Obligatoire. La commande shell à exécuter. Lancée via sh -c sur macOS/Linux.
matcherstring(aucun)Optionnel. Un regex comparé au nom de l'outil (uniquement PreToolUse, PostToolUse). Omets-le pour correspondre à tous les outils.
timeoutnumber10Secondes avant l'arrêt du hook. Mets 0 pour désactiver le timeout.

Référence des hooks

S'exécute une fois au démarrage d'une nouvelle session, avant le premier tour.

Schéma stdin

{
  "event": "string",
  "session_id": "string"
}

Payload d'exemple

{
  "event": "SessionStart",
  "session_id": "ses_01abc123"
}

Stdout : Écrit dans le contexte du modèle comme information de session supplémentaire.

Bloquant : Le code de sortie 2 n'est pas pris en charge. La session démarre toujours. Les autres sorties non nulles sont journalisées et ignorées.

S'exécute à chaque envoi d'un prompt, avant qu'il soit transmis au modèle.

Schéma stdin

{
  "event": "string",
  "session_id": "string",
  "prompt": "string"
}

Payload d'exemple

{
  "event": "UserPromptSubmit",
  "session_id": "ses_01abc123",
  "prompt": "Refactor the auth module"
}

Stdout : Écrit dans le contexte du modèle avec le prompt.

Bloquant : Le code de sortie 2 empêche l'envoi du prompt. Bob Shell affiche une erreur et le prompt n'est pas soumis.

S'exécute avant qu'un outil correspondant ne soit lancé, te donnant la possibilité d'inspecter ou de bloquer l'action.

Schéma stdin

{
  "event": "string",
  "session_id": "string",
  "tool": "string",
  "input": "object"
}

Payload d'exemple

{
  "event": "PreToolUse",
  "session_id": "ses_01abc123",
  "tool": "write_file",
  "input": {
    "path": "src/index.ts",
    "content": "..."
  }
}

Stdout : Ignoré.

Bloquant : Le code de sortie 2 empêche l'outil de s'exécuter. Bob Shell signale l'outil comme bloqué et continue la session.

S'exécute après la fin d'un outil correspondant, qu'il ait réussi ou non.

Schéma stdin

{
  "event": "string",
  "session_id": "string",
  "tool": "string",
  "input": "object",
  "output": "string"
}

Payload d'exemple

{
  "event": "PostToolUse",
  "session_id": "ses_01abc123",
  "tool": "write_file",
  "input": {
    "path": "src/index.ts",
    "content": "..."
  },
  "output": "File written successfully"
}

Stdout : Ignoré.

Bloquant : Le code de sortie 2 n'a aucun effet. L'outil a déjà été exécuté.

S'exécute quand l'agent s'arrête, après la fin du dernier tour.

Schéma stdin

{
  "event": "string",
  "session_id": "string"
}

Payload d'exemple

{
  "event": "Stop",
  "session_id": "ses_01abc123"
}

Stdout : Ignoré.

Bloquant : Le code de sortie 2 n'a aucun effet. La session est déjà terminée.

Codes de sortie et blocage

Code de sortieComportementS'applique à
0Succès : le hook s'est exécuté sans problèmeTous les hooks
2Bloquer : arrêter l'action en coursUserPromptSubmit, PreToolUse
Tout autre non-zéroÉchec non bloquant : journalisé et ignoréTous les hooks
Remarque :

Seuls UserPromptSubmit et PreToolUse prennent en charge le blocage. Le code de sortie 2 de SessionStart, PostToolUse ou Stop est traité comme un échec non bloquant.

Détails des commandes

  • Répertoire de travail : Les commandes s'exécutent depuis le répertoire de travail de la tâche (le dossier dans lequel Bob travaille).
    •
  • Timeout par défaut : 10 secondes. Peut être remplacé par hook avec le champ timeout. Mets timeout à 0 pour désactiver complètement le timeout.
    •
  • Stderr : Écrit dans les logs de Bob Shell mais n'affecte pas le résultat du hook.
    •
  • Shell : Les commandes s'exécutent via sh -c sur macOS et Linux.
    •

Démarrage rapide

Ouvre ou crée ton fichier de configuration global à ~/.bob/settings/settings.json.

Ajoute une clé hooks avec le hook que tu veux utiliser. L'exemple ci-dessous exécute un script avant chaque appel à write_file :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "^write_file$",
        "hooks": [
          {
            "type": "command",
            "command": "sh ~/.bob/hooks/log-write.sh"
          }
        ]
      }
    ]
  }
}

Crée le fichier de script. Ce script minimal journalise le payload JSON entrant :

#!/bin/sh
# ~/.bob/hooks/log-write.sh
cat >> ~/.bob/hooks/write-log.txt

Lance une session Bob Shell et utilise l'outil correspondant. Vérifie ~/.bob/hooks/write-log.txt pour confirmer que le hook s'est exécuté et que le payload a été écrit.

Exemples

Journaliser toutes les entrées de hooks

Écris le stdin de chaque hook dans un fichier pour le débogage :

 
#!/bin/sh
# Ajouter le payload JSON entrant avec un timestamp
echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> ~/.bob/hooks/debug.log
cat >> ~/.bob/hooks/debug.log
echo "" >> ~/.bob/hooks/debug.log

Configure cela sous n'importe quel hook :

 
{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "sh ~/.bob/hooks/debug.sh" }]
      }
    ]
  }
}

Injecter du contexte de session

Retourne du texte depuis un hook SessionStart pour l'ajouter au contexte du modèle :

 
#!/bin/sh
# Afficher les métadonnées du projet pour le modèle
echo "Project: $(basename $PWD)"
echo "Git branch: $(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo 'unknown')"
echo "Node version: $(node --version 2>/dev/null || echo 'not installed')"

Bloquer un prompt

Sors avec le code 2 depuis un hook UserPromptSubmit pour empêcher l'envoi d'un prompt :

 
#!/bin/sh
# Bloquer les prompts contenant le mot "delete"
PROMPT=$(cat | python3 -c "import sys,json; print(json.load(sys.stdin)['prompt'])")
case "$PROMPT" in
  *delete*|*DELETE*)
    echo "Prompt blocked: contains 'delete'" >&2
    exit 2
    ;;
esac

Bloquer un outil correspondant

Sors avec le code 2 depuis un hook PreToolUse pour empêcher un outil spécifique de s'exécuter :

 
#!/bin/sh
# Bloquer les opérations write_file sur des fichiers hors du répertoire src/
PATH_VAL=$(cat | python3 -c "import sys,json; print(json.load(sys.stdin)['input'].get('path',''))")
case "$PATH_VAL" in
  src/*) ;;
  *)
    echo "Blocked: writes outside src/ are not allowed" >&2
    exit 2
    ;;
esac

Lancer une automatisation de suivi depuis Stop

Utilise Stop pour démarrer un nettoyage ou un reporting après la fin d'une session :

 
#!/bin/sh
# Committer les changements staged après la fin de l'agent
cd "$PWD"
git diff --cached --quiet || git commit -m "chore: auto-commit from Bob Shell session"

Limitations actuelles

Seuls les hooks de type command et les cinq types de hooks listés ci-dessus sont pris en charge dans cette version. Les éléments suivants ne sont pas encore disponibles :
  • Types de hooks autres que command : les function hooks, inline script hooks et similaires ne sont pas pris en charge.
    •
  • Hooks planifiés : les hooks ne peuvent pas être configurés pour s'exécuter selon un timer ou en réponse à un événement externe.
    •
  • Réécriture d'entrée : les hooks ne peuvent pas modifier le prompt ou l'entrée de l'outil avant qu'il n'atteigne le modèle.
    •
  • Exécution en sandbox : les hooks s'exécutent avec tes pleines permissions utilisateur ; aucune isolation n'est appliquée.
    •
  • Télémétrie dédiée des hooks : l'activité des hooks n'est pas suivie séparément dans les analytics de session.
    •
  • Blocage depuis PostToolUse ou Stop : le code de sortie 2 n'a aucun effet pour ces hooks.
    •
Comment trouvez-vous ce sujet ?

Sur cette page

Hooks disponiblesConfigurationSchéma du hookChamps de configurationRéférence des hooksCodes de sortie et blocageDétails des commandesDémarrage rapideExemplesJournaliser toutes les entrées de hooksInjecter du contexte de sessionBloquer un promptBloquer un outil correspondantLancer une automatisation de suivi depuis StopLimitations actuelles