📘 תיעוד 46

אוטומציה של פעולות באמצעות הוקים

הרץ פקודות מעטפת באופן אוטומטי כאשר Claude Code עורך קבצים, מסיים משימות או זקוק לקלט. עצב קוד, שלח התראות, אמת פקודות ואכוף כללי פרויקט.

הוקים (hooks) הם פקודות מעטפת (shell) המוגדרות על ידי המשתמש. Claude Code מריץ אותם בנקודות מסוימות במחזור החיים שלו, מה שמעניק לך שליטה דטרמיניסטית: פעולות מסוימות תמיד מתרחשות במקום להסתמך על מודל ה-LLM שיבחר להריץ אותן. השתמש בהוקים כדי לאכוף כללי פרויקט, לבצע אוטומציה של משימות חוזרות ולשלב את Claude Code עם הכלים הקיימים שלך.

להחלטות הדורשות שיקול דעת ולא כללים דטרמיניסטיים, תוכל גם להשתמש ב-הוקים מבוססי פרומפט או ב-הוקים מבוססי סוכן המשתמשים במודל Claude כדי להעריך תנאים.

לדרכים נוספות להרחיב את Claude Code, ראה skills למתן הנחיות נוספות ופקודות להרצה ל-Claude, subagents להרצת משימות בסביבות מבודדות, ו-plugins לאריזת הרחבות לשיתוף בין פרויקטים.

מדריך זה מכסה תרחישי שימוש נפוצים וכיצד להתחיל. לסכמות אירועים מלאות, פורמטים של קלט ופלט JSON ותכונות מתקדמות כמו הוקים אסינכרוניים והוקים של כלי MCP, ראה את תיעוד ההוקים.

#הגדרת ההוק הראשון שלך

כדי ליצור הוק, הוסף בלוק hooks אל קובץ הגדרות. מדריך זה יוצר הוק להתראות שולחן עבודה, כדי שתקבל התראה בכל פעם ש-Claude ממתין לקלט שלך במקום לצפות בטרמינל.

1. הוסף את ההוק להגדרות שלך פתח את ~/.claude/settings.json והוסף הוק מסוג Notification. אם הקובץ אינו קיים, צור אותו. הדוגמה להלן משתמשת ב-osascript עבור macOS, ראה קבלת התראה כאשר Claude זקוק לקלט עבור פקודות Linux ו-Windows.

   העתק

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       }
     }
   }

   אם קובץ ההגדרות שלך כבר מכיל מפתח hooks, הוסף את Notification כאח למפתחות האירועים הקיימים במקום להחליף את האובייקט כולו. כל שם אירוע הוא מפתח בתוך אובייקט ה-hooks היחיד:

   העתק

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
         }
       ],
       "Notification": [
         {
           "matcher": "",
           "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
         }
       ]
     }
   }

   תוכל גם לבקש מ-Claude לכתוב את ההוק עבורך על ידי תיאור מבוקשך ב-CLI.

2. אמת את התצורה הקלד /hooks כדי לפתוח את דפדפן ההוקים. תראה רשימה של כל אירועי ההוק הזמינים, עם ספירה לצד כל אירוע שמוגדרים בו הוקים. בחר ב-Notification כדי לוודא שההוק החדש שלך מופיע ברשימה. בחירת ההוק מציגה את פרטיו: האירוע, ה-matcher, הסוג, קובץ המקור והפקודה.

3. בדוק את ההוק לחץ על Esc כדי לחזור ל-CLI. לחץ על Shift+Tab עד ששורת המצב מציגה ⏸ manual mode on, בקש מ-Claude לבצע פעולה שדורשת הרשאה, ולאחר מכן עבור מהטרמינל לחלון אחר. אתה אמור לקבל התראת שולחן עבודה.

תפריט ה-/hooks הוא לקריאה בלבד. כדי להוסיף, לשנות או להסיר הוקים, ערוך ישירות את קובץ ה-JSON של ההגדרות שלך או בקש מ-Claude לבצע את השינוי.

#מה שתוכל לבצע באוטומציה

הוקים מאפשרים לך להריץ קוד בנקודות מפתח במחזור החיים של Claude Code: לעצב קבצים לאחר עריכות, לחסום פקודות לפני הרצתן, לשלוח התראות כאשר Claude זקוק לקלט, להזריק הקשר בתחילת הפעלה (session), ועוד. לרשימה המלאה של אירועי הוק, ראה את תיעוד ההוקים.

כל דוגמה כוללת בלוק תצורה מוכן לשימוש שתוסיף אל קובץ הגדרות.

לדוגמת ייצור של הוקים המריצים בדיקת מודל נפרדת ומזינים ממצאים בחזרה לפעלה, ראה כיצד התוסף security-guidance משתלב עם Claude Code.

#קבלת התראה כאשר Claude זקוק לקלט

קבל התראת שולחן עבודה בכל פעם ש-Claude מסיים לעבוד וזקוק לקלט שלך, כדי שתוכל לעבור למשימות אחרות מבלי לבדוק את הטרמינל.

הוק זה משתמש באירוע Notification, ש-Claude Code מפעיל כאשר Claude ממתין לקלט או להרשאה. ראה מתי כל סוג התראה מופעל לתזמון המדויק. כל חלק להלן משתמש בפקודת ההתראה המקורית של הפלטפורמה. הוסף זאת אל ~/.claude/settings.json:

#macOS

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

אם לא מופיעה התראה: פקודת osascript מנתבת התראות דרך אפליקציית עורך התסריטים (Script Editor) המובנית. אם ל-Script Editor אין הרשאת התראות, הפקודה נכשלת בשקט, ו-macOS לא תבקש ממך להעניק אותה. הרץ זאת בטרמינל פעם אחת כדי ש-Script Editor יופיע בהגדרות ההתראות שלך:

osascript -e 'display notification "test"'

שום דבר עדיין לא יופיע. פתח את System Settings > Notifications, מצא את Script Editor ברשימה, והפעל את Allow Notifications. הרץ את הפקודה שוב כדי לאשר שהתראת הבדיקה מופיעה.

#Linux

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

אם לא מופיעה התראה: פקודת notify-send זקוקה ל-daemon של התראות שולחן עבודה, שאינו קיים בשרתים ללא ממשק גרפי (headless), בהפעלות SSH וברוב הקונטיינרים. בדוק את הפקודה ישירות תחילה:

notify-send 'Claude Code' 'test'

אם הפקודה אינה נמצאת, התקן את החבילה libnotify-bin ב-Debian וב-Ubuntu, או את המקבילה בהפצה שלך.

#Windows (PowerShell)

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

אם לא מופיעה תיבת דו-שיח: פקודה זו פותחת תיבת דו-שיח ולא התראה בפינת המסך, ולכן תיבת הדו-שיח יכולה להיפתח מאחורי חלון הטרמינל שלך. בדוק את הפקודה ישירות ב-PowerShell תחילה. אם אתה מריץ את Claude Code בתוך WSL, על powershell.exe להיות זמין ב-PATH שלך דרך תאימות Windows (interop).

ה-matcher הריק מופעל בכל סוגי ההתראות. כדי להפעיל רק באירועים ספציפיים, הגדר אותו לאחד מהערכים הבאים:

תוכנת Claude Code מתזמנת את permission_prompt באופן שונה בטרמינל לעומת Claude Desktop, תוסף VS Code ומארחים אחרים שעונים על בקשות הרשאה דרך ה-Agent SDK. ראה מתי כל סוג התראה מופעל עבור שני התזמונים.

ה-matchers מסוג agent_needs_input ו-agent_completed דורשים את Claude Code בגרסה v2.1.198 ומעלה.

ה-matchers מסוג quota_auto_resume_fired, quota_auto_resume_stale ו-quota_auto_resume_disabled דורשים את Claude Code בגרסה v2.1.234 ומעלה.

בהפעלות טרמינל, permission_prompt עבור בקשת רשת של פקודה בארגז חול דורש את Claude Code בגרסה v2.1.246 ומעלה.

הערך agent_needs_input עבור שאלת הגדרת טרמינל של חבר צוות דורש את Claude Code בגרסה v2.1.248 ומעלה.

הקלד /hooks ובחר ב-Notification כדי לאשר שההוק רשום. לסכמת האירוע המלאה, ראה את תיעוד Notification.

#עיצוב אוטומטי של קוד לאחר עריכות

הרץ אוטומטית את Prettier על כל קובץ ש-Claude עורך, כך שהעיצוב נשאר עקבי ללא התערבות ידנית.

הוק זה משתמש באירוע PostToolUse עם ה-matcher בשם Edit|Write, כך שהוא רץ רק לאחר כלי עריכת קבצים. הפקודה מחלצת את נתיב הקובץ שנערך באמצעות jq ומעבירה אותו ל-Prettier. הוסף זאת אל .claude/settings.json בתיקיית השורש של הפרויקט שלך:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

כדי לבדוק את ההוק, בקש מ-Claude להוסיף שורה עם מחרוזות במירכאות בודדות לקובץ JavaScript, ולאחר מכן פתח את הקובץ: עם הגדרות ברירת המחדל של Prettier, ההוק משכתב אותן למירכאות כפולות.

כאשר ההוק מצליח, Claude Code אינו מציג דבר בשיחה. כדי לוודא שההוק רץ, בדוק שהקובץ שנערך עוצב מחדש, או ראה טכניקות ניפוי שגיאות.

כדי לעצב מחדש קובץ ספציפי בכל דרך שבה הוא משתנה, כולל כאשר פקודת Bash משכתבת אותו, השתמש בהוק FileChanged במקום זאת.

דוגמאות ה-Bash בדף זה משתמשות ב-jq לצורך ניתוח JSON. התקן אותו באמצעות brew install jq ב-macOS, או apt-get install jq ב-Debian וב-Ubuntu, או ראה הורדות jq.

#חסימת עריכות בקבצים מוגנים

מנע מ-Claude לשנות קבצים רגישים כמו .env, package-lock.json או כל דבר ב-.git/. Claude מקבל משוב המסביר מדוע העריכה נחסמה, כדי שיוכל להתאים את גישתו.

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

1. צור את תסריט ההוק שמור זאת ב-.claude/hooks/protect-files.sh:

   העתק

   #!/bin/bash

#protect-files.sh

INPUT=$(cat) FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

#Normalize Windows backslash separators so the patterns below match

FILE_PATH="${FILE_PATH//\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do if [[ "$FILE_PATH" == "$pattern" ]]; then echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2 exit 2 fi done

exit 0

2. **הפוך את התסריט לבר-הרצה ב-macOS וב-Linux**
תסריטי הוק חייבים להיות ברי-הרצה כדי ש-Claude Code יוכל להריץ אותם:

```bash
chmod +x .claude/hooks/protect-files.sh

3. רשום את ההוק הוסף הוק מסוג PreToolUse אל .claude/settings.json שמריץ את התסריט לפני כל קריאה לכלי Edit או Write:

   העתק

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             {
               "type": "command",
               "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
             }
           ]
         }
       ]
     }
   }

4. בדוק את ההוק בקש מ-Claude להוסיף הערה לקובץ ה-.env שלך. Claude Code חוסם את העריכה לפני שהיא רצה ומעביר את ההודעה :Blocked של התסריט ל-Claude כמשוב.

#הזרקה מחדש של הקשר לאחר דחיסה

כאשר חלון ההקשר של Claude מתמלא, דחיסה (compaction) מתמצתת את השיחה כדי לפנות מקום. פעולה זו עלולה לגרום לאובדן פרטים חשובים. השתמש בהוק מסוג SessionStart עם ה-matcher בשם compact כדי להזריק מחדש הקשר קריטי לאחר כל דחיסה.

Claude Code מוסיף להקשר של Claude טקסט רגיל שהפקודה שלך כותבת ל-stdout. דוגמה זו מזכירה ל-Claude מוסכמות פרויקט ועבודה שבוצעה לאחרונה. הוסף זאת אל .claude/settings.json בתיקיית השורש של הפרויקט שלך:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

תוכל להחליף את ה-echo בכל פקודה המייצרת פלט דינמי, כמו git log --oneline -5 כדי להציג התחייבויות אחרונות. להזרקת הקשר בכל תחילת הפעלה, שקול להשתמש ב-CLAUDE.md במקום זאת. למשתני סביבה, ראה את CLAUDE_ENV_FILE בתיעוד.

#ביקורת שינויי תצורה

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

דוגמה זו מוסיפה כל שינוי ליומן ביקורת. הוסף זאת אל ~/.claude/settings.json:

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

ה-matcher מסנן לפי סוג התצורה: user_settings, project_settings, local_settings, policy_settings או skills. כדי לחסום שינוי מלהיכנס לתוקף, צא עם קוד 2 או החזר {"decision": "block"}. ראה את תיעוד ConfigChange עבור סכמת הקלט המלאה.

כדי לוודא שההוק מתעד שינויים, ערוך קובץ הגדרות בעורך אחר בזמן שהפעלה רצה, ולאחר מכן פתח את ~/claude-config-audit.log: ההוק מוסיף שורת JSON אחת לכל שינוי עם חותמת הזמן, המקור ונתיב הקובץ.

#טעינה מחדש של הסביבה כאשר התיקייה או הקבצים משתנים

ישנם פרויקטים המגדירים משתני סביבה שונים בהתאם לתיקייה שבה אתה נמצא. כלים כמו direnv עושים זאת אוטומטית במעטפת שלך, אך כלי ה-Bash של Claude אינו קולט את השינויים הללו בעצמו.

שילוב של הוק SessionStart עם הוק CwdChanged פותר זאת. SessionStart טוען את המשתנים עבור התיקייה שבה אתה מפעיל את הכלי, ו-CwdChanged טוען אותם מחדש בכל פעם ש-Claude משנה תיקייה. שניהם כותבים אל CLAUDE_ENV_FILE, ש-Claude Code מריץ כהקדמה לתסריט לפני כל פקודת Bash. הוסף זאת אל ~/.claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

הרץ direnv allow פעם אחת בכל תיקייה שיש בה .envrc כדי של-direnv תהיה הרשאה לטעון אותו. אם אתה משתמש ב-devbox או ב-nix במקום ב-direnv, אותו דפוס פועל עם devbox shellenv או devbox global shellenv במקום direnv export bash.

כדי להגיב לקבצים ספציפיים במקום לכל שינוי תיקייה, השתמש ב-FileChanged עם matcher המפרט את שמות הקבצים למעקב, מופרדים באמצעות |. בעת בניית רשימת המעקב, Claude Code מפצל ערך זה לשמות קבצים מילוליים במקום להעריך אותו כביטוי רגולרי. ראה FileChanged למידע על האופן שבו אותו ערך מסנן גם אילו קבוצות הוק ירוצו כאשר קובץ משתנה. דוגמה זו עוקבת אחר .envrc ו-.env בתיקיית העבודה:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

ראה את ערכי התיעוד CwdChanged ו-FileChanged עבור סכמות קלט, פלט watchPaths ופרטי CLAUDE_ENV_FILE.

#אישור אוטומטי של בקשות הרשאה ספציפיות

דלג על תיבת הדו-שיח של האישור עבור קריאות לכלים שאתה תמיד מאפשר. דוגמה זו מאשרת אוטומטית את ExitPlanMode, הכלי ש-Claude קורא לו כאשר הוא מסיים להציג תוכנית ומבקש להמשיך, כך שלא תתבקש לאשר בכל פעם שתוכנית מוכנה.

שלא כמו דוגמאות קוד היציאה לעיל, אישור אוטומטי מחייב את ההוק שלך לכתוב החלטת JSON ל-stdout. תוכנת Claude Code מריצה הוקים מסוג PermissionRequest כאשר היא עומדת לבקש ממך הרשאה, ואם ההוק שלך מחזיר "behavior": "allow", Claude Code עונה על הבקשה מטעמך.

ה-matcher מגביל את תחום ההוק ל-ExitPlanMode בלבד, כך ששום בקשה אחרת אינה מושפעת. הוסף זאת אל ~/.claude/settings.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

כאשר ההוק מאשר, Claude Code יוצא ממצב תוכנית ומשחזר את מצב ההרשאות שהיה פעיל לפני שנכנסת למצב תוכנית. התמליל מציג "Allowed by PermissionRequest hook" במקום שבו תיבת הדו-שיח הייתה אמורה להופיע. נתיב ההוק שומר תמיד על השיחה הנוכחית: הוא אינו יכול לנקות את ההקשר ולהתחיל הפעלת יישום חדשה כפי שתיבת הדו-שיח יכולה.

כדי להגדיר מצב הרשאות ספציפי במקום זאת, פלט ההוק שלך יכול לכלול מערך updatedPermissions עם ערך setMode. הערך של mode הוא כל מצב הרשאה כמו default, acceptEdits או bypassPermissions, והערך destination: "session" מחיל אותו עבור ההפעלה הנוכחית בלבד.

הערך bypassPermissions חל רק אם התחלת את ההפעלה כאשר מצב עקיפה כבר היה זמין: --dangerously-skip-permissions, --permission-mode bypassPermissions, --allow-dangerously-skip-permissions, או permissions.defaultMode: "bypassPermissions" ב-הגדרות משתמש, הגדרות --settings או הגדרות מנוהלות. הוא אינו חל אם מצב עקיפה מושבת על ידי permissions.disableBypassPermissionsMode, או אם התחלת את ההפעלה ב-מצב מוגבל.

תוכנת Claude Code לעולם אינה שומרת זאת כ-defaultMode.

כדי להעביר את ההפעלה ל-acceptEdits, ההוק שלך כותב JSON זה ל-stdout:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

שמור על ה-matcher מצומצם ככל האפשר. התאמה ל-.* או השארת ה-matcher ריק תאשר אוטומטית כל בקשת הרשאה לכלי, כולל כתיבת קבצים ופקודות מעטפת. ראה את תיעוד PermissionRequest לקבלת הערכה המלאה של שדות ההחלטה.

#כיצד פועלים הוקים

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

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

• "type": "http": שולח נתוני אירוע ב-POST אל כתובת URL. ראה הוקים של HTTP.
• "type": "mcp_tool": קורא לכלי בשרת MCP שכבר מחובר. ראה הוקים של כלי MCP.
• "type": "prompt": הערכת LLM בתור יחיד. ראה הוקים מבוססי פרומפט.
• "type": "agent": אימות רב-תורות עם גישה לכלים. הוקים של סוכן הם ניסיוניים ועשויים להשתנות. ראה הוקים מבוססי סוכן.

#שילוב תוצאות ממספר הוקים

כאשר מספר הוקים תואמים לאותו אירוע, הפקודה של כל הוק רצה עד לסיומה לפני ש-Claude Code ממזג את התוצאות. הוק אחד שמחזיר deny אינו עוצר הוקים אחים מלהתבצע. אל תסתמך על deny של הוק אחד כדי למנוע תופעות לוואי בהוק אחר.

לאחר שכל ההוקים התואמים מסתיימים, Claude Code משלב את הפלטים שלהם. עבור החלטות הרשאה של PreToolUse, התשובה המגבילה ביותר היא זו שחלה, בסדר הבא: deny, defer, ask, allow. טקסט מתוך additionalContext נשמר מכל הוק ומועבר ל-Claude יחד.

הדוגמה להלן רושמת שני הוקים של PreToolUse על Bash. הראשון מוסיף כל פקודה לקובץ יומן ויוצא עם 0. השני מריץ תסריט שיוצא עם 2 כדי לדחות כאשר הפקודה מכילה rm -rf:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

כאשר Claude מנסה להריץ rm -rf /tmp/build, שני ההוקים מתבצעים במקביל. הוק הרישום ליומן כותב את הפקודה אל ~/.claude/bash.log ויוצא עם 0, מה שלא מדווח על שום החלטה. הוק מעקה הבטיחות יוצא עם 2, מה שדוחה את הקריאה לכלי. הדחייה מקבלת עדיפות, ולכן Claude Code חוסם את הפקודה ומציג ל-Claude את ה-stderr של מעקה הבטיחות. רשומת היומן עדיין נכתבת מכיוון שהוק הרישום כבר רץ.

#קריאת קלט והחזרת פלט

הוקים מתקשרים עם Claude Code דרך stdin, stdout, stderr וקודי יציאה. כאשר אירוע מופעל, Claude Code מעביר נתונים ספציפיים לאירוע כ-JSON ל-stdin של התסריט שלך. התסריט שלך קורא נתונים אלה, מבצע את עבודתו ואומר ל-Claude Code מה לעשות הלאה באמצעות קוד היציאה.

#קלט ההוק

כל אירוע כולל שדות משותפים כמו session_id, מזהה ייחודי עבור ההפעלה, ו-cwd, תיקיית העבודה בעת הפעלת האירוע, אך כל סוג אירוע מוסיף נתונים שונים. כאשר Claude מריץ פקודת Bash, הוק מסוג PreToolUse מקבל שדות אלה ב-stdin:

• hook_event_name: האירוע שהפעיל את ההוק
• tool_name: הכלי ש-Claude עומד להשתמש בו
• tool_input: הארגומנטים ש-Claude העביר לכלי. עבור Bash, השדה command שלו מחזיק את פקודת המעטפת.

לדוגמה, קלט הוק עבור פקודת npm test נראה כך:

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

התסריט שלך יכול לנתח את ה-JSON הזה ולפעול על סמך כל אחד מהשדות הללו. הוקים של UserPromptSubmit מקבלים במקום זאת את טקסט ה-prompt, הוקים של SessionStart מקבלים source מבין startup, resume, clear, compact או fork, וכן הלאה. ראה שדות קלט נפוצים בתיעוד עבור שדות משותפים, ואת הסעיף של כל אירוע עבור סכמות ספציפיות לאירוע.

#פלט ההוק

התסריט שלך אומר ל-Claude Code מה לעשות הלאה על ידי כתיבה ל-stdout או ל-stderr ויציאה עם קוד ספציפי. הוק ה-PreToolUse הבא חוסם פקודה:

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  
# stderr becomes Claude's feedback
  exit 2                                               
# exit 2 = block the action
fi

exit 0  
# exit 0 = no decision; the normal permission flow applies

קוד היציאה קובע מה יקרה הלאה:

• יציאה 0: ההוק שלך אינו מדווח על התנגדות באמצעות קוד היציאה שלו.
  • עבור הוק מסוג PreToolUse אין זה מאשר את הקריאה לכלי: זרימת ההרשאות הרגילה עדיין חלה.
  • עבור הוקים של UserPromptSubmit, UserPromptExpansion, SessionStart ו-PostModelSwitch, תוכנת Claude Code מוסיפה להקשר של Claude את מה שנכתב ל-stdout שבו היא מתייחסת כטקסט רגיל.
• יציאה 2: תוכנת Claude Code חוסמת את הפעולה. כתוב סיבה ל-stderr. המקום שבו היא תנחת תלוי באירוע: אירועים מסוימים מזינים אותה ל-Claude כמשוב כדי שיוכל להתאים את עצמו, אחרים מציגים אותה למשתמש, וחלק קטן, כמו ConfigChange ו-Elicitation, אינם מציגים שום הודעה. אירועים מסוימים אינם ניתנים לחסימה: עבור SessionStart ואחרים, יציאה 2 מציגה את stderr למשתמש והביצוע נמשך. ראה התנהגות קוד יציאה 2 לפי אירוע לרשימה המלאה.
• כל קוד יציאה אחר: עבור רוב האירועים, התוצאה תלויה במה שההוק שלך הדפיס ל-stdout:
  • אובייקט מנותח שעובר אימות סכמה: Claude Code מתעלם מקוד היציאה, ה-JSON לבדו קובע את התוצאה, וההוק אינו מדווח כשגיאה. החריגים לכל אירוע, כמו WorktreeCreate שנכשל בכל יציאה שאינה אפס, מפורטים בסעיף פלט קוד יציאה בתיעוד.
  • אובייקט מנותח שנכשל באימות סכמה, או stdout ש-Claude Code מנסה לנתח כ-JSON אך אינו JSON תקין: שגיאה שאינה חוסמת; ההודעה נושאת את הודעת האימות או הניתוח.
  • פלט stdout ש-Claude Code מתייחס אליו כטקסט רגיל, או פלט stdout ריק: הפעולה נמשכת כשגיאה שאינה חוסמת. התמליל מציג הודעת שגיאת הוק, ולאחר מכן את השורה הראשונה של stderr עם הקידומת :Failed with non-blocking status code. כדי לתפוס את ה-stderr המלא, הפעל רישום ניפוי שגיאות באמצעות claude --debug או על ידי הרצת /debug במהלך ההפעלה.

#פלט JSON מובנה

קודי יציאה מאפשרים לך רק לחסום או להישאר שקט. לשליטה רבה יותר, צא עם 0 והדפס אובייקט JSON ל-stdout במקום זאת.

השתמש ביציאה 2 כדי לחסום עם הודעת stderr, או ביציאה 0 עם JSON לשליטה מובנית. בחר גישה אחת לכל הוק. לגבי מה שקורה כאשר אתה משלב ביניהן, ראה פלט קוד יציאה.

לדוגמה, הוק מסוג PreToolUse יכול לדחות קריאה לכלי ולומר ל-Claude מדוע, או להסלים אותה למשתמש לקבלת אישור:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

עם "deny", Claude Code מבטל את הקריאה לכלי ומזין את permissionDecisionReason בחזרה ל-Claude.

ב-PreToolUse, תוכנת Claude Code מטפלת בכל ערך של permissionDecision באופן הבא:

• "allow": מדלג על בקשת ההרשאה האינטראקטיבית. כללי דחייה ובקשה (deny ו-ask), כולל רשימות דחייה מנוהלות ברמת הארגון, עדיין חלים, וכך גם בקשות אישור עבור כלי MCP המסומנים ב-requiresUserInteraction ועבור כלי מחבר שהארגון שלך הגדיר כ-ask בהפעלות שבהן הגדרה זו מגיעה ל-Claude Code
• "deny": מבטל את הקריאה לכלי ושולח את הסיבה ל-Claude
• "ask": מציג את בקשת ההרשאה למשתמש כרגיל

ערך רביעי, "defer", זמין ב-מצב לא-אינטראקטיבי עם הדגל -p. הוא יוצא מהתהליך תוך שמירת הקריאה לכלי כך שמעטפת ה-Agent SDK תוכל לאסוף קלט ולהמשיך. ראה דחיית קריאה לכלי למועד מאוחר יותר בתיעוד.

הוק מסוג PreModelSwitch מחזיר את אותו שדה permissionDecision: הערך "allow" מאפשר להחלפת המודל להמשיך, והערך "deny" מבטל אותה. הערך "ask" דורש ממך לאשר את ההחלפה כאשר אתה מריץ /model בהפעלה אינטראקטיבית; בכל מקום אחר, Claude Code מתייחס ל-"ask" כסירוב. ראה בקרת החלטות PreModelSwitch.

אירועים אחרים משתמשים בדפוסי החלטה שונים. לדוגמה, הוקים של PostToolUse ו-Stop משתמשים בשדה ברמה העליונה decision: "block", בעוד ש-PermissionRequest משתמש ב-hookSpecificOutput.decision.behavior. ראה את טבלת הסיכום בתיעוד לפירוט מלא לפי אירוע.

עבור הוקים של UserPromptSubmit, השתמש במקום זאת ב-hookSpecificOutput.additionalContext כדי להזריק טקסט להקשר של Claude. קנן את additionalContext בתוך hookSpecificOutput; אם תמקם אותו ברמה העליונה של ה-JSON, תוכנת Claude Code תתעלם ממנו בשקט. לדוגמה, פלט זה מוסיף את מצב הענף הנוכחי לכל פרומפט:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

ראה בקרת החלטות UserPromptSubmit עבור מבנה הפלט המלא, כולל חסימת פרומפטים והגדרת כותרת ההפעלה.

הוקים עם type: "prompt" מטפלים בפלט באופן שונה: ראה הוקים מבוססי פרומפט.

#סינון הוקים באמצעות Matchers

ללא matcher, הוק מופעל בכל התרחשות של האירוע שלו. Matchers מאפשרים לך לצמצם זאת. לדוגמה, אם ברצונך להריץ מעצב רק לאחר עריכות קבצים, ולא לאחר כל קריאה לכלי, הוסף matcher להוק ה-PostToolUse שלך:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

ה-matcher בשם "Edit|Write" מופעל רק כאשר Claude משתמש בכלי Edit או Write, ולא כאשר הוא משתמש ב-Bash, ב-Read או בכל כלי אחר. ב-Claude Code בגרסה v2.1.191 ומעלה, פסיק מפריד בין חלופות באותו אופן, כך ש-"Edit, Write" שקול לחלוטין. ראה תבניות Matcher לאופן שבו שמות רגילים וביטויים רגולריים מוערכים.

תוכנת Claude יכולה גם ליצור או לשנות קבצים על ידי הרצת פקודות מעטפת. אם ההוק שלך חייב לראות כל שינוי בקובץ, למשל עבור סריקת תאימות או רישום ביקורת ביומן, הוסף הוק מסוג Stop שסורק את עץ העבודה פעם אחת בכל תור. לכיסוי לפי כל קריאה במקום זאת, התאם גם ל-Bash|PowerShell ודאג שהתסריט שלך יפרט קבצים ששונו ושאינם במעקב באמצעות git status --porcelain. הסעיף קלט הוק PowerShell מסביר מדוע התאמה ל-Bash בלבד אינה מספיקה. כדי להריץ הוק כאשר קובץ ספציפי משתנה בדיסק, לא משנה מה כתב אותו, השתמש בהוק FileChanged.

כל סוג אירוע מתאים לפי שדה ספציפי:

החלקים להלן מציגים עוד כמה matchers על סוגי אירועים שונים:

#רישום כל פקודת Bash ליומן

התאם רק לקריאות לכלי Bash ותעד כל פקודה לקובץ. האירוע PostToolUse מופעל לאחר שהפקודה מסתיימת, כך ש-tool_input.command מכיל את מה שרץ. ההוק מקבל את נתוני האירוע כ-JSON ב-stdin, והפקודה jq -r '.tool_input.command' מחלצת רק את מחרוזת הפקודה, ש->> משרשרת לקובץ היומן:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

#התאמת כלי MCP

כלי MCP משתמשים במוסכמת שמות שונה מכלים מובנים: mcp__<server>__<tool>, כאשר <server> הוא שם שרת ה-MCP ו-<tool> הוא הכלי שהוא מספק. לדוגמה, mcp__github__search_repositories או mcp__filesystem__read_file. כלים משרת המסופק כחלק מתוסף משתמשים במקטע שרת מתוחם, כגון mcp__plugin_my-plugin_db__query. השתמש ב-matcher מסוג ביטוי רגולרי כדי למקד לכל הכלים משרת מסוים, או להתאמה בין שרתים עם תבנית כמו mcp__.*__write.*. ראה התאמת כלי MCP בתיעוד לרשימת הדוגמאות המלאה.

הפקודה להלן מחלצת את שם הכלי מקלט ה-JSON של ההוק באמצעות jq וכותבת אותו ל-stderr. כתיבה ל-stderr שומרת על stdout נקי לפלט JSON ושולחת את ההודעה ל-יומן ניפוי השגיאות:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

#ניקוי בסיום ההפעלה

האירוע SessionEnd תומך ב-matchers על סיבת סיום ההפעלה. הוק זה מופעל רק עבור הסיבה clear, המוגדרת כאשר אתה מריץ /clear, ולא ביציאות רגילות:

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

#סינון לפי שם הכלי והארגומנטים באמצעות השדה if

השדה if משתמש ב-תחביר כללי הרשאות כדי לסנן הוקים לפי שם הכלי והארגומנטים יחד, כך שתהליך ההוק נוצר רק כאשר הקריאה לכלי תואמת. זה חורג מעבר ל-matcher, שמסנן ברמת הקבוצה לפי שם הכלי בלבד.

לדוגמה, תצורה זו מריצה הוק רק כאשר Claude משתמש בפקודות git ולא בכל פקודות ה-Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

השאלה אם פקודת ההוק שלך תרוץ תלויה במבנה תבנית ה-if שלך ובפקודת ה-Bash ש-Claude מפעיל:

כאשר Claude Code אינו יכול לקבוע אילו פקודות קלט ה-Bash מריץ, הוא מריץ את ההוק שלך ללא קשר לתבנית. טבלת התאמת Bash מכסה את מבני הפקודות ש-Claude Code יכול ושאינו יכול לצמצם לפי תת-פקודה. מכיוון שהסינון מבוצע בשיטת מיטב המאמצים, השתמש ב-מערכת ההרשאות ולא בהוק כדי לאכוף אישור או דחייה קשיחים.

השדה if מקבל את אותן תבניות כמו כללי הרשאה: "Bash(git *)", "Edit(*.ts)" וכן הלאה. כדי להתאים למספר שמות כלים, השתמש במטפלים נפרדים שלכל אחד מהם ערך if משלו, או בצע התאמה ברמת ה-matcher שבה נתמכת חלופה באמצעות קו אנכי.

השדה if פועל רק באירועי כלים: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest ו-PermissionDenied. הוספתו לכל אירוע אחר מונעת מההוק לרוץ.

#הגדרת מיקום ההוק

המקום שבו אתה מוסיף הוק קובע את היקפו:

הרץ /hooks ב-Claude Code כדי לעיין בכל ההוקים המוגדרים כשהם מקובצים לפי אירוע.

כדי להשבית הוקים, הגדר "disableAllHooks": true בקובץ ההגדרות שלך. תוכנת Claude Code קוראת את הערך שנשאר לאחר החלת קדימות ההגדרות, כך שקובץ הגדרות של פרויקט יכול לדרוס את הקובץ שלך. הוקים המוגדרים בהגדרות מנוהלות עדיין ירוצו אלא אם disableAllHooks מוגדר גם שם. לטווח ההשפעה המלא של כל רמה, ראה את disableAllHooks.

אם אתה עורך קובצי הגדרות ישירות בזמן ש-Claude Code רץ, מעקב הקבצים קולט בדרך כלל שינויים בהוקים באופן אוטומטי.

#הוקים מבוססי פרומפט

להחלטות הדורשות שיקול דעת ולא כללים דטרמיניסטיים, השתמש בהוקים מסוג type: "prompt". במקום להריץ פקודת מעטפת, Claude Code שולח את הפרומפט שלך ואת נתוני הקלט של ההוק למודל Claude, כברירת מחדל Haiku, כדי לקבל את ההחלטה. תוכל לציין מודל שונה באמצעות השדה model אם דרושה לך יכולת גבוהה יותר.

תפקידו היחיד של המודל הוא להחזיר את החלטתו כ-JSON:

• "ok": true: הפעולה ממשיכה
• "ok": false: מה שקורה תלוי באירוע:
  • Stop ו-SubagentStop: ה-reason מוזן בחזרה ל-Claude כדי שימשיך לעבוד, אלא אם התגובה מגדירה גם "impossible": true כדי לסמן את התנאי ככזה שלעולם אינו יכול להתקיים, ובמקרה זה Claude Code מאפשר את העצירה והתור מסתיים
  • PreToolUse: הקריאה לכלי נדחית; כברירת מחדל התור מסתיים וה-reason לדחייה מופיע בצ'אט כשורת אזהרה. הגדר continueOnBlock: true בהוק כדי להחזיר במקום זאת את ה-reason ל-Claude כשגיאת הכלי, כדי שיוכל להתאים את עצמו ולהמשיך. לפני גרסה v2.1.210, ה-reason לדחייה הוחזר ל-Claude כשגיאת הכלי והתור נמשך
  • PostToolUse: כברירת מחדל התור מסתיים וה-reason מופיע בצ'אט כשורת אזהרה. הגדר continueOnBlock: true כדי להזין את ה-reason בחזרה ל-Claude ולהמשיך את התור במקום זאת
  • PostToolBatch, UserPromptSubmit ו-UserPromptExpansion: התור מסתיים וה-reason מופיע בצ'אט כשורת אזהרה

דוגמה זו משתמשת בהוק Stop כדי לשאול את המודל האם כל המשימות המבוקשות הושלמו. אם המודל מחזיר "ok": false מכיוון שהתנאי עדיין לא התקיים, Claude ממשיך לעבוד ומשתמש ב-reason כהנחיה הבאה שלו:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

לאפשרויות תצורה מלאות, ראה הוקים מבוססי פרומפט בתיעוד.

#הוקים מבוססי סוכן

הוקים של סוכן הם ניסיוניים. ההתנהגות והתצורה עשויות להשתנות במהדורות עתידיות. לתהליכי עבודה בסביבת ייצור, העדף הוקים של פקודה.

כאשר אימות דורש בדיקת קבצים או הרצת פקודות, השתמש בהוקים מסוג type: "agent". שלא כמו הוקים של פרומפט, המבצעים קריאת LLM יחידה, הוקים של סוכן מייצרים סוכן-משנה שיכול לקרוא קבצים, לחפש בקוד ולהשתמש בכלים אחרים כדי לאמת תנאים לפני החזרת החלטה.

הוקים של סוכן משתמשים בפורמט תגובה של "ok" / "reason" עם פסק זמן (timeout) ארוך יותר כברירת מחדל של 60 שניות ועד 50 תורות של שימוש בכלים. הם אינם תומכים בשדה impossible של הוקי פרומפט. כאשר ok: false, תוכנת Claude Code מטפלת בהוק של סוכן באותו אופן שבו היא מטפלת בהוק פרומפט עם continueOnBlock: true באותו אירוע, כך שב-PreToolUse וב-PostToolUse התור נמשך; להוקים של סוכן אין שדה continueOnBlock. ראה תצורת הוק של סוכן עבור השדות, כולל מציין המקום $ARGUMENTS ש-Claude Code מחליף בקלט ה-JSON של ההוק.

דוגמה זו מאמתת שהבדיקות עוברות לפני שהיא מאפשרת ל-Claude לעצור:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

השתמש בהוקים של פרומפט כאשר נתוני קלט ההוק לבדם מספיקים לקבלת החלטה. השתמש בהוקים של סוכן כאשר עליך לאמת משהו מול המצב בפועל של בסיס הקוד.

לאפשרויות תצורה מלאות, ראה הוקים מבוססי סוכן בתיעוד.

#הוקים של HTTP

השתמש בהוקים מסוג type: "http" כדי לשלוח ב-POST נתוני אירוע לנקודת קצה של HTTP במקום להריץ פקודת מעטפת. נקודת הקצה מקבלת את אותו ה-JSON שהוק פקודה היה מקבל ב-stdin, ומחזירה תוצאות דרך גוף תגובת ה-HTTP באותו פורמט JSON.

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

דוגמה זו שולחת ב-POST כל שימוש בכלי לשירות רישום מקומי:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

על נקודת הקצה להחזיר גוף תגובה מסוג JSON המשתמש באותו פורמט פלט כמו הוקים של פקודה. כדי לחסום קריאה לכלי, החזר תגובת 2xx עם שדות ה-hookSpecificOutput המתאימים. קודי סטטוס HTTP לבדם אינם יכולים לחסום פעולות.

ערכי כותרות (headers) תומכים בהטמעת משתני סביבה באמצעות תחביר $VAR_NAME או ${VAR_NAME}. רק משתנים המפורטים במערך allowedEnvVars מפוענחים; כל שאר ההפניות ל-$VAR נשארות ריקות.

לאפשרויות תצורה מלאות וטיפול בתגובות, ראה הוקים של HTTP בתיעוד.

#מגבלות ופתרון בעיות

#מגבלות

זכור את האילוצים הבאים בעת תכנון הוקים:

• הוקים של פקודה מתקשרים דרך stdin, stdout, stderr וקודי יציאה בלבד. הם אינם יכולים להפעיל פקודות / או קריאות לכלים. טקסט המוחזר דרך additionalContext מוזרק כתזכורת מערכת ש-Claude קורא כטקסט רגיל. הוקים של HTTP מתקשרים דרך גוף התגובה במקום זאת.
• פסקי זמן של הוקים משתנים לפי הסוג. ניתן לדרוס עבור כל הוק בנפרד באמצעות השדה timeout בשניות.
  • command, http, mcp_tool: 10 דקות. תוכנת Claude Code מורידה ברירת מחדל זו ל-30 שניות עבור הוקים מסוג UserPromptSubmit, PreModelSwitch ו-PostModelSwitch, ול-10 שניות עבור MessageDisplay.
  • prompt: 30 שניות.
  • agent: 60 שניות.
  • הוקים מכל סוג של SessionEnd חולקים תקציב של 1.5 שניות. אם ההגדרות שלך קובעות timeout ארוך יותר לכל הוק, Claude Code מעלה את התקציב בהתאם, עד ל-60 שניות.
• הוקים של PostToolUse אינם יכולים לבטל פעולות מכיוון שהכלי כבר בוצע.
• הוקים של PermissionRequest מופעלים כאשר Claude Code עומד לבקש ממך הרשאה.
  • ב-מצב לא-אינטראקטיבי עם הדגל -p, בקשה זו קיימת רק כאשר קריאת החזרה (callback) מסוג canUseTool של ה-Agent SDK מספקת אותה. בהפעלות רגילות עם -p או עם --permission-prompt-tool, השתמש בהוקים מסוג PreToolUse לקבלת החלטות הרשאה אוטומטיות במקום זאת.
  • סוכני-משנה הפועלים ברקע אינם יכולים להציג בקשה במצב לא-אינטראקטיבי. Claude Code עדיין מריץ את ההוקים עבור הקריאות שלהם לכלים, ואם שום הוק אינו מחזיר החלטה, הוא דוחה את הקריאה. בהפעלה אינטראקטיבית, בקשות של סוכני-משנה ברקע צפות בהפעלה הראשית שלך וההוקים מופעלים כרגיל.
• הוקים מסוג Stop מופעלים בכל פעם ש-Claude מסיים להגיב, לא רק בהשלמת משימה. הם אינם מופעלים בעת קטיעות מצד המשתמש. שגיאות API מפעילות את StopFailure במקום זאת.
• כאשר מספר הוקים של PreToolUse מחזירים updatedInput כדי לשכתב את ארגומנטי הכלי, האחרון שמסיים נכנס לתוקף. מכיוון שהוקים רצים במקביל, הסדר אינו דטרמיניסטי. הימנע מכך שיותר מהוק אחד ישנה את הקלט של אותו כלי.

#הוקים ומצבי הרשאה

הוקים של PreToolUse מופעלים לפני כל בדיקת מצב הרשאה, בכל מצב הרשאה, כולל dontAsk. הוק שמחזיר permissionDecision: "deny" חוסם את הכלי אפילו במצב bypassPermissions או עם --dangerously-skip-permissions. הדבר מאפשר לך לאכוף מדיניות שמשתמשים אינם יכולים לעקוף על ידי שינוי מצב ההרשאות שלהם.

ההפך אינו נכון: הוק שמחזיר "allow" אינו עוקף כללי דחייה מההגדרות, ואינו יכול להשתיק את בקשת האישור עבור כלי MCP המסומנים ב-requiresUserInteraction או עבור כלי מחבר שהארגון שלך הגדיר כ-ask בהפעלות שבהן הגדרה זו מגיעה ל-Claude Code. הוקים יכולים להחמיר הגבלות אך לא להקל בהן מעבר למה שכללי ההרשאות מתירים.

#ההוק אינו מופעל

ההוק מוגדר אך אינו מתבצע לעולם.

• הרץ /hooks ואשר שההוק מופיע תחת האירוע הנכון
• בדוק שתבנית ה-matcher תואמת בדיוק לשם הכלי. Matchers רגישים לאותיות גדולות וקטנות
• ודא שאתה מפעיל את סוג האירוע הנכון: PreToolUse מופעל לפני ביצוע הכלי, PostToolUse מופעל אחריו. הוק מסוג PermissionRequest מופעל כאשר Claude Code עומד לבקש ממך הרשאה; ראה את המגבלות עבור המקרים הלא-אינטראקטיביים

#שגיאת הוק בפלט

אתה רואה הודעה כמו "... :PreToolUse hook error" בתמליל.

• התסריט שלך יצא עם קוד שאינו אפס באופן בלתי צפוי. בדוק אותו ידנית על ידי העברת JSON לדוגמה בצינור:

  העתק

  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?

#Check the exit code

* אם אתה רואה "command not found", השתמש בנתיבים מוחלטים או ב-`${CLAUDE_PROJECT_DIR}` כדי להפנות לתסריטים. כדי להימנע לחלוטין מבעיות מירכאות במעטפת, הוסף `"args": []` כדי לעבור ל-[תצורת exec](/docs/en/hooks#exec-form-and-shell-form), המפעילה את התסריט ישירות ללא מעטפת
* אם אתה רואה "jq: command not found", התקן את `jq` או השתמש ב-Python או ב-Node.js לצורך ניתוח JSON
* אם ההודעה מציגה הודעת אימות JSON, פלט ה-stdout של ההוק שלך נותח כ-JSON אך נכשל באימות הסכמה. אם היא מציגה הודעת ניתוח JSON, פלט ה-stdout נראה כמו אובייקט JSON אך לא היה JSON תקין. שניהם מתרחשים אפילו ביציאה עם קוד 0.

כדי לתקן כשל ניתוח, בנה את המטען (payload) באמצעות מקודד JSON כגון `jq` במקום שרשור מחרוזות, כך שמירכאות וקווים נטויים לאחור בתוך ערכים יעברו מילוט. הסעיף [פלט קוד יציאה](/docs/en/hooks#exit-code-output) בתיעוד מכסה את השילובים בין קודי יציאה ל-JSON
* אם התסריט אינו רץ כלל, הפוך אותו לבר-הרצה: `chmod +x ./my-hook.sh`

### תפריט ‎/hooks אינו מציג הוקים מוגדרים

ערכת קובץ הגדרות אך ההוקים אינם מופיעים בתפריט.

* עריכות קבצים נקלטות בדרך כלל באופן אוטומטי. אם הן לא הופיעו לאחר מספר שניות, ייתכן שמעקב הקבצים פספס את השינוי: הפעל מחדש את ההפעלה שלך כדי לאלץ טעינה מחדש.
* ודא שה-JSON שלך תקין: פסיקים נגררים והערות אינם מותרים
* אשר שקובץ ההגדרות נמצא במיקום הנכון: `.claude/settings.json` עבור הוקים של פרויקט, `~/.claude/settings.json` עבור הוקים גלובליים

### הוק מסוג Stop פוגע בתקרת החסימות

תוכנת Claude ממשיכה לעבוד במקום לעצור, ואז מסיים את התור עם אזהרה שהוק ה-Stop חסם יותר מדי פעמים ברצף.

תוכנת Claude Code עוקפת הוק מסוג Stop לאחר שהוא חוסם שמונה פעמים ברציפות ללא התקדמות. על תסריט ההוק שלך לבדוק אם הוא כבר הפעיל המשך. נתח את השדה `stop_hook_active` מתוך קלט ה-JSON וצא מוקדם אם הוא `true`:

```bash
#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
exit 0  
# Allow Claude to stop
fi
# ... rest of your hook logic

אם ההוק שלך זקוק באופן לגיטימי ליותר משמונה איטרציות כדי להתכנס, העלה את התקרה באמצעות CLAUDE_CODE_STOP_HOOK_BLOCK_CAP.

#ל-JSON של ההוק אין השפעה

ההוק שלך מדפיס JSON תקין, אך ההחלטה אינה נכנסת לתוקף ושום שגיאה אינה מופיעה בתמליל. בדוק איזו סיבה רלוונטית:

• פלט נוסף לפני ה-JSON: משהו אחר כותב ל-stdout תחילה, בדרך כלל פקודת echo ללא תנאי בפרופיל המעטפת שלך, כך שהפלט כבר אינו מתחיל ב-{ ו-Claude Code אינו מנתח אותו כ-JSON. הסיבה והתיקון מופיעים לאחר רשימה זו.
• שדה ברמה הלא נכונה: השווה את מיקומו של כל שדה מול פורמט פלט JSON. לדוגמה, permissionDecision שייך לתוך hookSpecificOutput, ולא ברמה העליונה.

כאשר Claude Code מריץ הוק פקודה בתצורת מעטפת, כזה ללא args, הוא מפעיל sh -c ב-macOS וב-Linux, את Git Bash ב-Windows, או את PowerShell כאשר Git Bash אינו מותקן כברירת מחדל. מעטפת זו אינה אינטראקטיבית, אך Git Bash ותצורות מסוימות, כגון BASH_ENV המצביע על ~/.bashrc, עדיין טוענות את הפרופיל שלך. אם אותו פרופיל מכיל הוראות echo ללא תנאי, הפלט מתווסף לפני ה-JSON של ההוק שלך:

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

הפלט המשולב כבר אינו מתחיל ב-{, ולכן Claude Code מתייחס לכל ה-stdout כטקסט רגיל ומתעלם מה-JSON. ביציאה עם קוד 0 שום דבר אינו מדווח בתמליל; ניסיון הניתוח נרשם רק ב-יומן ניפוי השגיאות. כדי לתקן זאת, עטוף הצהרות echo בפרופיל המעטפת שלך כך שירוצו רק במעטפות אינטראקטיביות:

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

המשתנה $- מכיל דגלי מעטפת, ו-i משמעו אינטראקטיבי. הוקים רצים במעטפות שאינן אינטראקטיביות, ולכן ה-echo נמנע.

כאשר ההוק שלך מחזיר permissionDecision או additionalContext ברמה העליונה במקום בתוך hookSpecificOutput, ה-JSON עדיין מנותח, ו-Claude Code מתעלם מהשדות שלא מוקמו כראוי מבלי לדווח על שגיאה. כדי לראות מאילו שדות הוא התעלם, הפעל את Claude Code עם claude --debug וחפש ב-יומן ניפוי השגיאות את המחרוזת Hook JSON output had unrecognized keys.

#טכניקות ניפוי שגיאות

לחץ על Ctrl+O כדי לפתוח את תצוגת התמליל כדי לבדוק את תוצאת הרצת ההוק:

• הרצה מוצלחת: אינך רואה דבר, אלא אם ה-JSON של ההוק מציג משהו, כגון systemMessage או משוב של הוק Stop.
  • כדי לוודא שהוק רץ, בדוק את השפעתו, כמו קובץ שעוצב מחדש, או הפעל רישום ניפוי שגיאות כפי שמתואר להלן והפעל את ההוק שוב
• שגיאה חוסמת: ברוב האירועים אתה רואה את המשוב של ההוק. כאשר ה-JSON של ההוק קיבל החלטה חוסמת, המשוב הוא הסיבה מאותה החלטה; אחרת זה ה-stderr של ההוק. במספר מועט של אירועים, כגון ConfigChange ו-Elicitation, חסימה אינה מציגה שום הודעה.
• שגיאה שאינה חוסמת: הפעולה נמשכה, ואתה רואה הודעת שגיאת הוק עם הסבר קצר, כגון השורה הראשונה של stderr עם הקידומת :Failed with non-blocking status code, או הודעת אימות או ניתוח JSON.

אילו שילובים של קודי יציאה ו-JSON מפיקים כל תוצאה, כולל החריגים לפי אירוע, מוגדר בסעיף פלט קוד יציאה בתיעוד.

לקבלת פרטי ביצוע מלאים כולל אילו הוקים תאמו, קודי היציאה שלהם, stdout ו-stderr, קרא את יומן ניפוי השגיאות. הפעל את Claude Code עם claude --debug-file /tmp/claude.log כדי לכתוב לנתיב ידוע, ולאחר מכן הרץ tail -f /tmp/claude.log בטרמינל אחר. אם התחלת ללא דגל זה, הרץ /debug במהלך ההפעלה כדי להפעיל רישום ולמצוא את נתיב היומן.

#למידע נוסף

• תיעוד ההוקים: סכמות אירועים מלאות, פורמט פלט JSON, הוקים אסינכרוניים והוקים של כלי MCP
• שיקולי אבטחה: עיין לפני פריסת הוקים בסביבות משותפות או בסביבות ייצור
• דוגמה למאמת פקודות Bash: מימוש ייחוס מלא