Esegui comandi shell automaticamente in punti chiave di una sessione Bob Shell per registrare l'attività, iniettare contesto o bloccare azioni in base alla tua logica.

I lifecycle hooks ti permettono di eseguire comandi shell in punti specifici di una sessione Bob Shell. Usali per registrare l'attività, iniettare contesto nel modello, consentire o bloccare azioni, o avviare automatizzazioni di follow-up — il tutto senza modificare Bob Shell.

Hook disponibili

Hook	Quando si esegue	Bloccante	Comportamento di stdout
`SessionStart`	Una volta all'avvio di una sessione	No	Iniettato come contesto
`UserPromptSubmit`	Ogni volta che invii un prompt	Sì (exit `2`)	Iniettato come contesto
`PreToolUse`	Prima che un tool corrispondente venga eseguito	Sì (exit `2`)	Ignorato
`PostToolUse`	Dopo che un tool corrispondente è completato	No	Ignorato
`Stop`	Quando l'agente si ferma	No	Ignorato

Configurazione

Gli hook sono definiti sotto la chiave hooks nel tuo settings.json. Bob Shell unisce gli hook da due posizioni:

Ambito	File
Globale (tutti i workspace)	`~/.bob/settings/settings.json`
Workspace (progetto corrente)	`.bob/settings.json`

Gli hook globali vengono sempre eseguiti. Gli hook di workspace vengono uniti sopra quelli globali e si applicano solo al progetto corrente.

Importante:

Gli hook di workspace vengono eseguiti solo nelle cartelle attendibili. Se la cartella corrente non è attendibile, il file .bob/settings.json non viene caricato e gli hook di workspace vengono ignorati silenziosamente. Gli hook globali in ~/.bob/settings/settings.json non sono influenzati dall'attendibilità della cartella.

Per dettagli su come i file di configurazione vengono individuati e caricati, consulta Configurare Bob Shell.

Schema dell'hook

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

Campi di configurazione

Campo	Tipo	Predefinito	Descrizione
`type`	`"command"`	(nessuno)	Obbligatorio. Solo `command` è supportato.
`command`	string	(nessuno)	Obbligatorio. Il comando shell da eseguire. Viene lanciato con `sh -c` su macOS/Linux.
`matcher`	string	(nessuno)	Opzionale. Un regex confrontato con il nome del tool (solo `PreToolUse`, `PostToolUse`). Omettilo per corrispondere a tutti i tool.
`timeout`	number	`10`	Secondi prima che l'hook venga fermato. Imposta `0` per disabilitare il timeout.

Riferimento hook

Si esegue una volta all'avvio di una nuova sessione, prima del primo turno.

Schema stdin

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

Payload di esempio

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

Stdout: Scritto nel contesto del modello come informazione aggiuntiva di sessione.

Bloccante: Il codice di uscita 2 non è supportato. La sessione parte sempre. Le altre uscite non zero vengono registrate e ignorate.

Si esegue ogni volta che invii un prompt, prima che venga inviato al modello.

Schema stdin

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

Payload di esempio

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

Stdout: Scritto nel contesto del modello insieme al prompt.

Bloccante: Il codice di uscita 2 blocca l'invio del prompt. Bob Shell mostra un errore e il prompt non viene inviato.

Si esegue prima che un tool corrispondente venga avviato, dandoti la possibilità di ispezionare o bloccare l'azione.

Schema stdin

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

Payload di esempio

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

Stdout: Ignorato.

Bloccante: Il codice di uscita 2 impedisce al tool di essere eseguito. Bob Shell segnala il tool come bloccato e continua la sessione.

Si esegue dopo che un tool corrispondente è completato, indipendentemente dall'esito.

Schema stdin

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

Payload di esempio

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

Stdout: Ignorato.

Bloccante: Il codice di uscita 2 non ha effetto. Il tool è già stato eseguito.

Si esegue quando l'agente si ferma, dopo il completamento dell'ultimo turno.

Schema stdin

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

Payload di esempio

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

Stdout: Ignorato.

Bloccante: Il codice di uscita 2 non ha effetto. La sessione è già terminata.

Codici di uscita e blocco

Codice di uscita	Comportamento	Si applica a
`0`	Successo: l'hook è stato eseguito senza problemi	Tutti gli hook
`2`	Blocca: interrompe l'azione corrente	`UserPromptSubmit`, `PreToolUse`
Qualsiasi altro valore non zero	Errore non bloccante: registrato e ignorato	Tutti gli hook

Nota:

Solo UserPromptSubmit e PreToolUse supportano il blocco. Il codice di uscita 2 da SessionStart, PostToolUse o Stop è trattato come un errore non bloccante.

Dettagli dei comandi

Directory di lavoro: I comandi vengono eseguiti dalla directory di lavoro del task (la cartella in cui Bob sta lavorando).

Timeout predefinito: 10 secondi. Può essere sovrascritto per hook con il campo timeout. Imposta timeout a 0 per disabilitare completamente il timeout.

Stderr: Scritto nei log di Bob Shell ma non influisce sul risultato dell'hook.

Shell: I comandi vengono eseguiti con sh -c su macOS e Linux.

Per iniziare

Apri o crea il tuo file di configurazione globale in ~/.bob/settings/settings.json.

Aggiungi una chiave hooks con l'hook che vuoi usare. L'esempio seguente esegue uno script prima di ogni chiamata a write_file:

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

Crea il file di script. Questo script minimale registra il payload JSON in ingresso:

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

Avvia una sessione Bob Shell e usa il tool corrispondente. Controlla ~/.bob/hooks/write-log.txt per confermare che l'hook è stato eseguito e il payload è stato scritto.

Esempi

Registrare tutti gli input degli hook

Scrivi lo stdin di ogni hook in un file per il debug:

#!/bin/sh
# Aggiunge il payload JSON in ingresso con 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

Configuralo sotto qualsiasi hook:

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

Iniettare contesto di sessione

Restituisci testo da un hook SessionStart per aggiungerlo al contesto del modello:

#!/bin/sh
# Mostra i metadati del progetto per il modello
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')"

Bloccare un prompt

Esci con codice 2 da un hook UserPromptSubmit per impedire l'invio di un prompt:

#!/bin/sh
# Blocca i prompt che contengono la parola "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

Bloccare un tool corrispondente

Esci con codice 2 da un hook PreToolUse per impedire l'esecuzione di un tool specifico:

#!/bin/sh
# Blocca le operazioni write_file su file fuori dalla directory 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

Avviare automatizzazione di follow-up da Stop

Usa Stop per avviare pulizia o reporting dopo la fine di una sessione:

#!/bin/sh
# Committa le modifiche staged dopo che l'agente ha terminato
cd "$PWD"
git diff --cached --quiet || git commit -m "chore: auto-commit from Bob Shell session"

Limitazioni attuali

In questa versione sono supportati solo gli hook di tipo command e i cinque tipi di hook elencati sopra. I seguenti non sono ancora disponibili:

Tipi di hook diversi da command: function hook, inline script hook e simili non sono supportati.

Hook pianificati: gli hook non possono essere impostati per eseguirsi su un timer o in risposta a un evento esterno.

Riscrittura dell'input: gli hook non possono modificare il prompt o l'input del tool prima che raggiunga il modello.

Esecuzione in sandbox: gli hook vengono eseguiti con i tuoi permessi utente completi; non viene applicato alcun isolamento.

Telemetria dedicata degli hook: l'attività degli hook non viene tracciata separatamente nelle analytics di sessione.

Blocco da PostToolUse o Stop: il codice di uscita 2 non ha effetto per questi hook.

Lifecycle hooks

Hook disponibili

Configurazione

Schema dell'hook

Campi di configurazione

Riferimento hook

Codici di uscita e blocco

Dettagli dei comandi

Per iniziare

Esempi

Registrare tutti gli input degli hook

Iniettare contesto di sessione

Bloccare un prompt

Bloccare un tool corrispondente

Avviare automatizzazione di follow-up da Stop

Limitazioni attuali

In questa pagina