🪝 פרק 8

Hooks ואוטומציית אירועים

מערכת ה-Hooks ב-Grok CLI מאפשרת להפעיל סקריפטים מקומיים במעטפת (Shell) או לשלוח קריאות HTTP POST בתגובה לאירועים מוגדרים במחזור החיים של הסשן.

באמצעות Hooks ניתן לאכוף בדיקות איכות לפני ביצוע פעולות, לחסום פקודות מסוכנות, לרשום לוגים ארגוניים, לשלוח התראות למערכות חיצוניות (כמו Slack או Webhooks), ולוודא שבדיקות אוטומטיות עוברות בהצלחה לפני שהסוכן מסיים את המשימה.

#התחלה מהירה: ה-Hook הראשון שלכם

יוצרים תיקיית הוקים אישית:

mkdir -p ~/.grok/hooks

יוצרים קובץ בשם ~/.grok/hooks/session-start.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "echo Grok CLI session started in $(pwd)" }
        ]
      }
    ]
  }
}

לאחר הפעלת סשן חדש, הפקודה /hooks תציג את רשימת ה-Hooks הפעילים שנטענו בהצלחה.

#מיקומי גילוי ורמות אמון (Trust Model)

Grok CLI סורק מספר מיקומים כדי לטעון Hooks:

כאשר אתם פותחים לראשונה פרויקט המכיל קובצי הוקים מקומיים ב-.grok/hooks/, הם מושבתים עד שתאשרו את התיקייה באמצעות הפקודה /hooks-trust בתוך הסשן, או הדגל grok --trust משורת הפקודה. רשימת התיקיות המאושרות נשמרת בקובץ ~/.grok/trusted_folders.toml ומחילה אמון גם על שרתי MCP מקומיים של הפרויקט.

#אירועי מחזור החיים של הסשן

#חוזה הנתונים ואופן התקשורת

בעת הפעלת Hook, המערכת מעבירה את פרטי האירוע כמבנה JSON בערוץ הקלט הסטנדרטי (stdin):

{
  "hookEventName": "PreToolUse",
  "sessionId": "5e31b1cc-3dca-4f69-9dea-b7d50e3da6b0",
  "cwd": "/home/user/projects/my-app",
  "workspaceRoot": "/home/user/projects/my-app",
  "toolName": "Bash",
  "toolInput": {
    "command": "npm test"
  }
}

בנוסף, מועברים משתני סביבה שימושיים: GROK_HOOK_EVENT, GROK_HOOK_NAME, GROK_SESSION_ID ו-GROK_WORKSPACE_ROOT.

#חסימת פעולה ב-PreToolUse

באירוע PreToolUse, הסקריפט יכול לאשר או לחסום את הפעולה על ידי כתיבת JSON לפלט הסטנדרטי (stdout):

{
  "action": "deny",
  "reason": "הרצת פקודות מחיקה ישירות חסומה על פי מדיניות הארגון"
}

או לאישור מפורש: {"action": "allow"}.

[!IMPORTANT] Grok CLI פועל במודל Fail-Open: רק פלט JSON מפורש של deny חוסם את הפעולה. קריסת סקריפט, חריגת זמן ריצה (Timeout) או פלט שאינו JSON תקין אינם חוסמים את הכלי, אלא מציגים אזהרה בלוגים כדי למנוע תקיעת העבודה השוטפת.

#שימוש ב-Matchers לסינון כלים

בדוגמה הבאה, ההוק יופעל רק על פקודות מערכת ועריכת קבצים:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          { "type": "command", "command": "./scripts/guard-check.sh", "timeout": 10 }
        ]
      }
    ]
  }
}

• עבור כלי מערכת: ביטוי רגולרי (Regex) התואם לשם הכלי (Bash, Write, Edit, Read).
• עבור שרתי MCP: שם הכלי מגיע בפורמט server__tool_name (למשל github__create_issue).
• עבור התראות (Notification): ניתן לסנן לפי idle_prompt (התור הסתיים וממתין לקלט) או permission_prompt (הסוכן ממתין לאישור משתמש).

על אירועים כמו Stop או UserPromptSubmit, אין להגדיר Matcher (הגדרתו תייצר אזהרה מכיוון שאירועים אלו אינם קשורים לכלי ספציפי).

#הגדרת Hooks בקובץ TOML

לארגונים ולצוותי פיתוח המעדיפים תצורה מרוכזת ב-config.toml:

[[hooks.PreToolUse]]
matcher = "Bash"
hooks = [
  { type = "command", command = "/opt/security/verify-command.sh", timeout = 5 }
]

[[hooks.Stop]]
hooks = [
  { type = "command", command = "npm run lint:check", timeout = 15 }
]

#קריאות HTTP Hooks מרוחקות

במקום להריץ סקריפט Shell מקומי, ניתן לשלוח את האירוע ישירות לשירות HTTP מרוחק:

{
  "type": "http",
  "url": "https://api.internal.example.com/grok-events",
  "timeout": 10
}

האירוע יישלח כבקשת HTTP POST עם גוף ה-JSON המלא של האירוע וכותרות מזהות.

בפרק הבא נלמד כיצד לחבר שרתי Model Context Protocol (MCP) חיצוניים ל-Grok CLI.