Bob Shell oturumunun kritik noktalarında shell komutlarını otomatik çalıştırarak etkinlik kaydı yapın, bağlam ekleyin veya kendi mantığınıza göre işlemleri engelleyin.

Lifecycle hooks, Bob Shell oturumunun belirli noktalarında shell komutları çalıştırmanı sağlar. Etkinlik kaydı, modele bağlam enjeksiyonu, işlemleri izin verme ya da engelleme veya takip otomasyonları başlatma gibi senaryolarda Bob Shell'i değiştirmeden kullanabilirsin.

Desteklenen hooks

Hook	Ne zaman çalışır	Engelleyici	Stdout davranışı
`SessionStart`	Oturum başladığında bir kez	Hayır	Bağlam olarak enjekte edilir
`UserPromptSubmit`	Prompt gönderdiğin her seferinde	Evet (exit `2`)	Bağlam olarak enjekte edilir
`PreToolUse`	Eşleşen bir araç çalıştırılmadan önce	Evet (exit `2`)	Yoksayılır
`PostToolUse`	Eşleşen bir araç tamamlandıktan sonra	Hayır	Yoksayılır
`Stop`	Agent durduğunda	Hayır	Yoksayılır

Yapılandırma

Hooks, settings.json dosyanızdaki hooks anahtarı altında tanımlanır. Bob Shell hooks'ları iki konumdan birleştirir:

Kapsam	Dosya
Global (tüm workspace'ler)	`~/.bob/settings/settings.json`
Workspace (mevcut proje)	`.bob/settings.json`

Global hooks her zaman çalışır. Workspace hooks'ları global hooks'ların üzerine eklenir ve yalnızca mevcut proje için geçerlidir.

Önemli:

Workspace hooks'ları yalnızca güvenilir klasörlerde çalışır. Mevcut klasör güvenilir değilse .bob/settings.json dosyası yüklenmez ve workspace hooks'ları sessizce atlanır. ~/.bob/settings/settings.json içindeki global hooks'lar klasör güveninden etkilenmez.

Ayar dosyalarının nasıl bulunduğu ve yüklendiği hakkında ayrıntılar için bkz. Bob Shell'i yapılandırma.

Hook şeması

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

Yapılandırma alanları

Alan	Tür	Varsayılan	Açıklama
`type`	`"command"`	(yok)	Zorunlu. Yalnızca `command` desteklenir.
`command`	string	(yok)	Zorunlu. Çalıştırılacak shell komutu. macOS/Linux'ta `sh -c` ile çalıştırılır.
`matcher`	string	(yok)	İsteğe bağlı. Araç adına karşı eşleştirilen bir regex (yalnızca `PreToolUse`, `PostToolUse`). Tüm araçları eşleştirmek için atla.
`timeout`	number	`10`	Hook durdurulmadan önce geçen saniye. Timeout'u devre dışı bırakmak için `0` yap.

Hook referansı

Yeni bir oturum başladığında, ilk turdan önce bir kez çalışır.

Stdin şeması

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

Örnek payload

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

Stdout: Ek oturum bilgisi olarak modelin bağlamına yazılır.

Engelleyici: Exit kodu 2 desteklenmez. Oturum her zaman başlar. Diğer sıfır dışı çıkışlar kaydedilir ve yoksayılır.

Bir prompt gönderdiğin her seferinde, modele iletilmeden önce çalışır.

Stdin şeması

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

Örnek payload

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

Stdout: Prompt ile birlikte modelin bağlamına yazılır.

Engelleyici: Exit kodu 2 promptun gönderilmesini engeller. Bob Shell bir hata gösterir ve prompt iletilmez.

Eşleşen bir araç çalıştırılmadan önce çalışır; işlemi inceleme veya engelleme fırsatı verir.

Stdin şeması

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

Örnek payload

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

Stdout: Yoksayılır.

Engelleyici: Exit kodu 2 aracın çalışmasını önler. Bob Shell aracı engellenmiş olarak bildirir ve oturuma devam eder.

Eşleşen bir araç tamamlandıktan sonra, başarılı olup olmadığından bağımsız olarak çalışır.

Stdin şeması

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

Örnek payload

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

Stdout: Yoksayılır.

Engelleyici: Exit kodu 2 etkisizdir. Araç zaten çalıştırıldı.

Agent durduğunda, son tur tamamlandıktan sonra çalışır.

Stdin şeması

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

Örnek payload

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

Stdout: Yoksayılır.

Engelleyici: Exit kodu 2 etkisizdir. Oturum zaten sona erdi.

Exit kodları ve engelleme

Exit kodu	Davranış	Uygulanır
`0`	Başarı: hook sorunsuz çalıştı	Tüm hooks
`2`	Engelle: mevcut işlemi durdur	`UserPromptSubmit`, `PreToolUse`
Diğer sıfır dışı değerler	Engelleyici olmayan hata: kaydedilir ve yoksayılır	Tüm hooks

Not:

Engellemeyi yalnızca UserPromptSubmit ve PreToolUse destekler. SessionStart, PostToolUse veya Stop'tan gelen exit kodu 2, engelleyici olmayan bir hata olarak değerlendirilir.

Komut detayları

Çalışma dizini: Komutlar, görev çalışma dizininden (Bob'un çalıştığı klasörden) çalıştırılır.

Varsayılan timeout: 10 saniye. timeout alanıyla hook başına geçersiz kılınabilir. Timeout'u tamamen devre dışı bırakmak için timeout'u 0 yap.

Stderr: Bob Shell'in loglarına yazılır ancak hook sonucunu etkilemez.

Shell: Komutlar macOS ve Linux'ta sh -c ile çalıştırılır.

Başlarken

~/.bob/settings/settings.json konumundaki global ayarlar dosyasını aç veya oluştur.

Kullanmak istediğin hook ile bir hooks anahtarı ekle. Aşağıdaki örnek her write_file çağrısından önce bir betik çalıştırır:

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

Betik dosyasını oluştur. Bu minimal betik gelen JSON payload'ını kaydeder:

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

Bir Bob Shell oturumu başlat ve eşleşen aracı kullan. Hook'un çalıştığını ve payload'ın yazıldığını doğrulamak için ~/.bob/hooks/write-log.txt dosyasını kontrol et.

Örnekler

Tüm hook girdilerini kaydet

Hata ayıklama için her hook'un stdin'ini bir dosyaya yaz:

#!/bin/sh
# Gelen JSON payload'ını zaman damgasıyla ekle
echo "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> ~/.bob/hooks/debug.log
cat >> ~/.bob/hooks/debug.log
echo "" >> ~/.bob/hooks/debug.log

Bunu herhangi bir hook altında yapılandır:

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

Oturum bağlamı enjekte et

Modelin bağlamına eklemek için SessionStart hook'undan metin döndür:

#!/bin/sh
# Modelin kullanması için proje metadata'sını çıkar
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')"

Bir promptu engelle

Promptun gönderilmesini önlemek için UserPromptSubmit hook'undan exit kodu 2 ile çık:

#!/bin/sh
# "delete" kelimesini içeren promptları engelle
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

Eşleşen bir aracı engelle

Belirli bir aracın çalışmasını önlemek için PreToolUse hook'undan exit kodu 2 ile çık:

#!/bin/sh
# src/ dizini dışındaki dosyalar üzerinde write_file işlemlerini engelle
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

Stop'tan takip otomasyonu çalıştır

Oturum bittikten sonra temizlik veya raporlama başlatmak için Stop kullan:

#!/bin/sh
# Agent bittikten sonra staged değişiklikleri commit et
cd "$PWD"
git diff --cached --quiet || git commit -m "chore: auto-commit from Bob Shell session"

Mevcut kısıtlamalar

Bu sürümde yalnızca command hooks ve yukarıda listelenen beş hook türü desteklenmektedir. Aşağıdakiler henüz mevcut değildir:

command dışındaki hook türleri: function hooks, inline script hooks ve benzerleri desteklenmez.

Zamanlanmış hooks: Hooks bir zamanlayıcıya veya harici bir olaya yanıt olarak çalıştırılacak şekilde ayarlanamaz.

Girdi yeniden yazma: Hooks, modele ulaşmadan önce prompt veya araç girdisini değiştiremez.

Sandbox çalıştırma: Hooks tam kullanıcı izinlerinizle çalışır; herhangi bir izolasyon uygulanmaz.

Özel hook telemetrisi: Hook etkinliği oturum analitiğinde ayrıca takip edilmez.

PostToolUse veya Stop'tan engelleme: Bu hook'lar için exit kodu 2 etkisizdir.

Lifecycle hooks

Bu sayfada