📘 תיעוד 7

הוקים

הוק הוא פקודת מעטפת או נקודת קצה HTTP שגרוק קורא לה כשמתרחש אירוע במחזור החיים: לחסום פקודה מסוכנת לפני שהיא רצה, לתעד שימוש בכלי, להריץ פורמטר אחרי עריכות, או לשלוח התראה כשתור מסתיים.

#הגדרה

הוקים הם קבצי JSON. הוקים אישיים נמצאים ב-~/.grok/hooks/*.json. הוקים של פרויקט נמצאים ב-<project>/.grok/hooks/*.json. נקראים גם קובצי הוקים של Claude Code (.claude/settings.json) ושל Cursor (.cursor/hooks.json), כולל שמות האירועים ב-camelCase של Cursor.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "bin/safety-check.sh", "timeout": 10 }]
      }
    ]
  }
}

matcher הוא ביטוי רגולרי שנבדק מול שם הכלי (שמות כלים של Claude כמו Bash, Read ו-Edit ממופים אוטומטית לשמות של גרוק). השמט אותו כדי להתאים להכל. type הוא "command" או "http" (עם url שאליו נשלח POST של האירוע). timeout הוא בשניות, ברירת המחדל 5. ניהול ובדיקה של ההוקים שנטענו נעשים בלשונית /hooks של מודאל ההרחבות.

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

#אירועים

#חוזה הסקריפט

האירוע מגיע כ-JSON ב-stdin, וכולל את hookEventName, sessionId, cwd, workspaceRoot, ולאירועי כלים גם את toolName ו-toolInput. כל תהליך הוק מקבל גם את GROK_HOOK_EVENT, GROK_HOOK_NAME, GROK_SESSION_ID ו-GROK_WORKSPACE_ROOT בסביבה שלו.

הוק PreToolUse מחליט על ידי כתיבת JSON ל-stdout:

{ "decision": "deny", "reason": "Unsafe command detected" }

קוד יציאה 0 מאפשר, קוד יציאה 2 דוחה. כל השאר: פסקי זמן, קריסות, פלט לא תקין, הוא fail-open: הכישלון נרשם בסשן אבל הקריאה לכלי ממשיכה. רק deny מפורש חוסם. לאירועים פסיביים, stdout מתעלם. יציאה 0 בהצלחה.