Claude Code Hooks (הוקים של Claude Code)

מה זה Hook: טריגר קבוע, לא שיקול דעת של המודל

לפי הגלוסרי הרשמי של Claude Code, Hook הוא 'handler שמוגדר על ידי המשתמש ורץ אוטומטית בנקודה מסוימת במחזור החיים של Claude Code' — למשל לפני הרצת כלי, אחרי עריכת קובץ, או בתחילת שיחה. ה-handler עצמו יכול להיות פקודת מעטפת (shell command), נקודת קצה ב-HTTP, קריאה לכלי MCP, פרומפט למודל, או תת-סוכן. ההבדל המכריע בין Hook לבין Skill או MCP מנוסח בגלוסרי במפורש: 'Hooks הם דטרמיניסטיים: הם רצים בנקודות קבועות במחזור החיים, ולא לפי שיקול הדעת של המודל'. כל הגדרת Hook בנויה משלוש שכבות — האירוע במחזור החיים (Hook event) שבו הוא מופעל, מסנן התאמה (Matcher) שקובע אילו מקרים מפעילים אותו, וה-handler שמבצע את הפעולה בפועל. לפי התיעוד הרשמי, Claude Code מפעיל את אותם אירועי Hook בכל מקום שבו הוא רץ — בטרמינל, בתוספי IDE, באפליקציית הדסקטופ ובשיחות ענן — כך שהתנהגות שהוגדרה פעם אחת עובדת באותו אופן בכל ה'משטחים'.

מחזור החיים: מאירועים שקורים פעם בשיחה ועד לכל קריאת כלי

התיעוד הרשמי מחלק את אירועי ה-Hook לפי התדירות שבה הם מופעלים. פעם בשיחה: SessionStart ו-SessionEnd (ולפניהם, אופציונלית, Setup להכנה חד-פעמית, למשל בסביבת CI). פעם בכל סבב שיחה: UserPromptSubmit, Stop ו-StopFailure. בכל קריאה לכלי בתוך לולאת הסוכן: PreToolUse ו-PostToolUse; בתוך אותה לולאה רצים גם אירועים למצבים מסוימים, כמו PostToolUseFailure כשכלי נכשל, PermissionRequest ו-PermissionDenied סביב הרשאות, ו-PostToolBatch אחרי קבוצת קריאות מקבילות. מלבד אלה יש עוד קבוצה גדולה של אירועים — Notification, SubagentStart/SubagentStop, PreCompact/PostCompact, TaskCreated/TaskCompleted ועוד — וגם אירועים כמו שינוי קובץ בדיסק (FileChanged) או יצירת Worktree. לא כל אירוע יכול לחסום פעולה: קוד יציאה 2 חוסם קריאת כלי ב-PreToolUse או קליטת פרומפט ב-UserPromptSubmit, אבל אין לו השפעה ב-PostToolUse, כי הכלי כבר רץ. התיעוד מגדיר את SessionStart כ'רץ כשסשן מתחיל או מתחדש... שימושי לטעינת הקשר פיתוח כמו issues פתוחים או שינויים אחרונים בקוד', ואת Stop כאירוע שרץ 'כש-Claude מסיים להגיב' — ואפשר לקרוא בו את ההודעה הסופית של הסבב. הטבלה הרשמית מגדירה את שני האירועים הנפוצים ביותר בלשון פשוטה: PreToolUse הוא 'לפני שקריאת כלי מתבצעת. אפשר לחסום אותה', ו-PostToolUse הוא 'אחרי שקריאת כלי הצליחה'.

תצורה: settings.json, Matcher וקוד יציאה

Hook מוגדר בקובץ הגדרות JSON, באחת מכמה שכבות שהתיעוד מפרט: ‎~/.claude/settings.json לכל הפרויקטים של המשתמש; ‎.claude/settings.json לפרויקט בודד שאפשר להכניס ל-git; ‎.claude/settings.local.json לפרויקט בודד שלא עולה ל-git; מדיניות ניהול ארגונית; קובץ ‎hooks/hooks.json של תוסף; ו-frontmatter של Skill או תת-סוכן. ה-Matcher קובע אילו מקרים מפעילים את ה-Hook: ‎'*' או ערך ריק מתאימים לכול, שם מדויק כמו Bash מתאים בדיוק, וכל ערך אחר מתפרש כביטוי רגולרי (regex), כמו ‎mcp__memory__.*‎. דוגמה מהתיעוד הרשמי: Hook על PreToolUse עם Matcher על Bash מריץ סקריפט שבודק אם הפקודה מכילה ‎rm -rf‎, ואם כן מחזיר JSON עם ‎permissionDecision: deny‎ — כלומר חסימה לפני שהפקודה מתבצעת בפועל. קוד היציאה של ה-handler קובע את התוצאה: 0 הוא הצלחה (וכל JSON שמוחזר מעובד), 2 הוא שגיאה חוסמת באירועים שתומכים בחסימה, וכל קוד אחר הוא שגיאה שלא חוסמת — הפעולה ממשיכה כרגיל. יכולת חזקה נוספת מעבר לחסימה: Hook על PreToolUse יכול להחזיר ‎updatedInput בתוך ‎hookSpecificOutput ולשנות את הארגומנטים של הכלי לפני שהוא רץ בפועל, ו-Hook על PostToolUse יכול להחזיר ‎updatedToolOutput ולהחליף את התוצאה שהכלי מחזיר ל-Claude — לא רק לאשר או לחסום, אלא לערוך את מה שבאמת קורה.

Hooks בתוך תוסף (Plugin) ושוק התוספים (Marketplace)

לפי עמוד הסקירה הרשמי של תוספים, Plugin הוא 'תיקייה של Skills, תת-סוכנים, Hooks או שרתי MCP ש-Claude Code מתקין וטוען כיחידה אחת'. תוסף יכול להכיל Hooks משלו בקובץ ‎hooks/hooks.json, שמתמזגים עם ה-Hooks של המשתמש והפרויקט כשהתוסף מופעל; לסקריפטים שמגיעים עם התוסף מפנים באמצעות המשתנה ‎${CLAUDE_PLUGIN_ROOT}‎, ונתונים שצריכים לשרוד עדכוני תוסף נשמרים ב-${CLAUDE_PLUGIN_DATA}. תוספים מופצים בעיקר מ-Marketplace — קטלוג (ולא חנות מנוהלת) שהוא תיקייה או מאגר git עם קובץ ‎.claude-plugin/marketplace.json, שמכיל שם, בעלים ורשימת תוספים, כל אחד עם שם ומקור. Claude Code מוסיף את ה-Marketplace הרשמי של Anthropic (‎claude-plugins-official) אוטומטית בפעם הראשונה שפותחים שיחה אינטראקטיבית בטרמינל. התקנה מתבצעת עם ‎/plugin marketplace add owner/repo ולאחריה ‎/plugin install name@marketplace, בטרמינל או בחלונית ‎/plugin. קיימת גם אפשרות מתקדמת: תוסף יכול לכלול Hooks שכתובים כפונקציות JavaScript שרצות בתוך תהליך Claude Code עצמו, ולא רק כפקודות מעטפת חיצוניות; תוסף כזה נקרא mod, וחלק מהם מגיעים מותקנים מראש בתוך Claude Code.

סיכוני אבטחה: הרשאות מלאות, בקרת אדמין ו-Fail-open

התיעוד הרשמי מזהיר ש'Hooks מסוג פקודה מריצים פקודות מעטפת עם מלוא ההרשאות של המשתמש שלך' — ולכן ממליץ לבדוק ולנסות כל פקודת Hook לפני שמוסיפים אותה, ולעבור על קובצי ההגדרות של מאגר שלא אתם כתבתם לפני שמריצים עליו את Claude Code אוטומטית. מנהל מערכת יכול להגדיר ‎allowManagedHooksOnly במדיניות ניהול כדי לחסום Hooks של משתמש, פרויקט, תצורה מקומית ותוספים (חוץ מתוספים שהמנהל עצמו כפה בהגדרות המנוהלות), ומשתמש לא יכול לכבות Hooks מנוהלים עם ‎disableAllHooks. ‎allowedHttpHookUrls מגביל לאילו כתובות Hook מסוג HTTP יכול לפנות, ו-‎httpHookAllowedEnvVars מגביל אילו משתני סביבה נכנסים לכותרות הבקשה שלו. Hooks שמוגדרים ב-frontmatter של תת-סוכן בפרויקט רצים רק אחרי שהמשתמש מאשר שהוא סומך על תיקיית העבודה (workspace trust). לפני גרסה v2.1.218 הם יכלו לרוץ גם מתיקייה שלא אושרה. ברירת המחדל ברוב האירועים היא Fail-open: Hook שנכשל או חרג מזמן הריצה נותן לפעולה המקורית להמשיך; כדי לחסום את הפעולה במקרה של כישלון צריך להגדיר ‎'onFailure': 'block' (מגרסה v2.1.295). בסשנים בתצורת HIPAA, פרטי הגישה של Anthropic מוסרים מסביבת ה-Hook. דגש נוסף בתיעוד: טקסט ש-Hook מחזיר כ-additionalContext ראוי להיכתב כעובדה נייטרלית ולא כפקודת מערכת, כי ניסוח שנשמע כהוראה עלול להפעיל בטעות את ההגנות של Claude עצמו מפני הזרקת פרומפט, ולהיתפס כניסיון מניפולציה.

Hooks מול Skills ומול Plugins: שלושה מנגנוני הרחבה שונים

שלושת המונחים הקרובים נועדו לתפקידים שונים לגמרי, לפי הגלוסרי הרשמי. Hook רץ בנקודה קבועה במחזור החיים בלי תלות בשיקול דעת — דטרמיניסטי. Skill הוא קובץ ‎SKILL.md ש-Claude טוען מרצונו כשהוא מוצא אותו רלוונטי למשימה, או שהמשתמש מפעיל ישירות בפקודה. Plugin הוא יחידת הפצה: תיקייה שיכולה להכיל כמה Skills, Hooks, תת-סוכנים ושרתי MCP בבת אחת, שמתקינים ממקור אחד ומקבלים ממנו עדכונים. במילים אחרות: Hook קובע מתי משהו קורה, Skill קובע מה Claude יודע לעשות ומתי זה נטען, ו-Plugin הוא האריזה שמפיצה כמה מהם יחד לקבוצה או לצוות. Hooks ו-Skills יכולים לעבוד גם בלי Plugin בכלל — Skill שנשמר תחת ‎~/.claude/skills/ זמין בכל פרויקט, ו-Hook שמוגדר ב-‎settings.json זמין באותה צורה. Plugin נחוץ רק כשרוצים להפיץ כמה רכיבים ולקבל עדכונים ממקום אחד.

למה זה חשוב: אכיפה שלא תלויה בכך שהמודל 'יזכור' לפעול

הוראה שכתובה ב-CLAUDE.md או בפרומפט היא בקשה שהמודל יכול לפרש או לדלג עליה בטעות. Hook הוא ההפך: הוא רץ בוודאות בנקודה במחזור החיים שאליה הוגדר, בלי תלות בכך שהמודל 'זכר' להריץ אותו. זה מה שהופך אותו למתאים לאכיפה — פורמט קוד אוטומטי אחרי כל עריכה, רישום (logging) של כל קריאת כלי, או חסימת פקודה מסוכנת לפני שהיא רצה בכלל, ולא רק הנחיה למודל להימנע ממנה. התיעוד הרשמי מדגים גם גם שימוש מסוג אחר: ‎terminalSequence מאפשר ל-Hook, למשל על אירוע Stop או Notification, לשלוח התראת מסך כש-Claude מסיים משימה ארוכה, באמצעות רצפי בריחה (escape sequences) מתוך רשימה מאושרת בלבד — Hook לא יכול לכתוב באופן חופשי ל-‎/dev/tty. בין שני הקצוות האלה — אכיפת אבטחה קשוחה והתראה נוחה — נמצא שימוש נפוץ: Hook שמריץ בודק פורמט או חבילת בדיקות אחרי כל קבוצת עריכות, בלי לסמוך על כך שהמודל יזכור לעשות זאת בעצמו.

דוגמה מעשית: פורמט אוטומטי אחרי עריכה, והתראה כש-Claude מחכה

המדריך הרשמי לשימוש ב-Hooks מסכם את השימושים האופייניים כך: 'פרמוט קבצים אחרי עריכות, חסימת פקודות לפני שהן מתבצעות, שליחת התראות כש-Claude זקוק לקלט, הזרקת הקשר בתחילת שיחה, ועוד'. שתי דוגמאות מהמדריך ממחישות זאת. הראשונה: Hook על PostToolUse עם Matcher על ‎Edit|Write מריץ פקודה שקוראת את נתיב הקובץ מה-JSON שהתקבל (עם ‎jq) ומעבירה אותו ל-‎npx prettier --write — כך שכל קובץ ש-Claude ערך מתפרמט אוטומטית, בלי לבקש זאת בכל פעם. השנייה: Hook על אירוע Notification מריץ פקודת התראה של מערכת ההפעלה (‎osascript ב-macOS, ‎notify-send ב-Linux) בכל פעם ש-Claude מחכה לקלט או להרשאה, כך שאפשר לעבור למשימה אחרת בלי להשגיח על הטרמינל. התיעוד מציין גם אפשרות נוחה להתחלה: אפשר לבקש מ-Claude עצמו לכתוב את ה-Hook, בתיאור חופשי של מה שרוצים שיקרה. לצד Hooks מבוססי פקודה, התיעוד מזכיר גם Hooks מבוססי פרומפט ומבוססי סוכן, שמפעילים מודל של Claude להעריך תנאי שדורש שיקול דעת ולא רק כלל קשיח — למקרים שבהם חסימה דטרמיניסטית פשוטה לא מספיקה.