הסבר על hooks ב-Claude Code: כל אירוע

Q: איך בודקים hook בלי לחכות ל-Claude?

מעבירים JSON לדוגמה ב-pipe לסקריפט ובודקים את קוד היציאה: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?. אחר כך מריצים /hooks ב-Claude Code כדי לוודא שהוא רשום תחת האירוע הנכון.

Q: למה ה-hook שלי לא רץ?

הסיבות הנפוצות: JSON לא תקין ב-settings.json (פסיקים מיותרים בסוף, הערות), matcher שלא תואם בדיוק (יש הבחנה בין אותיות גדולות לקטנות), סקריפט בלי הרשאת הרצה, או תיקייה שעדיין לא סומנה כמהימנה. הפעילו את Claude Code עם claude --debug וקראו את לוג ה-debug כדי לראות מה רץ. הרשימה המלאה ב-צ'קליסט פתרון התקלות.

Q: איך מכבים את כל ה-hooks לזמן מה?

מגדירים "disableAllHooks": true בקובץ הגדרות. כדי לדלג עליהם בהרצה אחת, מפעילים את Claude Code עם --settings '{"disableAllHooks": true}'. אין מתג לכיבוי hook בודד; פשוט מסירים את הרשומה שלו. אף אחת מהאפשרויות לא מכבה hooks שהארגון הגדיר ב-managed settings.

hooks ב-Claude Code הם פקודות (או קריאות HTTP, prompts ועוד כמה סוגי handlers) ש-Claude Code מריץ אוטומטית בנקודות קבועות בסשן, למשל לפני שכלי רץ, כשנדרשת הרשאה או כש-Claude מסיים להשיב. מגדירים אותם תחת המפתח hooks בקובץ הגדרות כמו ~/.claude/settings.json. כל hook מקבל ב-stdin נתוני JSON על האירוע, ויכול להגיב דרך קוד היציאה או אובייקט JSON ב-stdout. כך הוא יכול לרשום ללוג, לשלוח התראה, לחסום פעולה או לענות בשמכם.

01איך בנוי hook

להגדרת hook יש שלוש רמות:

אירוע ה-hook, למשל PreToolUse או Stop.
קבוצת matcher, שמסננת מתי הוא מופעל, למשל "רק עבור הכלי Bash".
handler אחד או יותר, כלומר מה שבפועל רץ.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/lint-check.sh"
          }
        ]
      }
    ]
  }
}

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

02איפה נמצאים ה-hooks

קובץחל עלמשותף?

~/.claude/settings.jsonכל הפרויקטים שלכםלא, רק במחשב שלכם

.claude/settings.jsonפרויקט אחדכן, אפשר לעשות לו commit

.claude/settings.local.jsonפרויקט אחדלא

הגדרות מדיניות מנוהלותהארגון שלכםנקבע על ידי מנהלי מערכת

hooks/hooks.json של pluginכל עוד ה-plugin מופעלכן

hooks מקבצים שונים מצטרפים זה לזה ולא מחליפים זה את זה. הקלידו /hooks ב-Claude Code כדי לראות את כל ה-hooks הפעילים ומאיפה כל אחד מגיע.

בסשן אינטראקטיבי, Claude Code לא מריץ hooks, גם לא את שלכם, עד שמאשרים את חלון האמון (workspace trust) עבור התיקייה.

03סוגי handlers

רוב ה-hooks הם "type": "command", שמריץ פקודת shell. יש עוד ארבעה סוגים:

http: שולח את ה-JSON של האירוע ב-POST לכתובת URL וקורא את גוף התגובה.
mcp_tool: קורא לכלי בשרת MCP שהגדרתם.
prompt: שואל מודל של Claude שאלה חד-פעמית וקורא החלטה בפורמט JSON.
agent: מפעיל subagent שיכול לקרוא קבצים לפני שהוא מחליט (ניסיוני).

command hooks רצים עם כל הרשאות המשתמש שלכם, דרך sh -c ב-macOS וב-Linux, ודרך Git Bash (או PowerShell) ב-Windows. הוסיפו "async": true כדי להריץ hook ברקע; במצב כזה הוא כבר לא יכול לקבל החלטות.

04Matchers

ה-matcher קובע באילו מופעים של אירוע ה-hook ירוץ. מול מה הוא מתאים תלוי באירוע: שם הכלי באירועי כלים, סוג ההתראה ב-Notification, האופן שבו הסשן התחיל ב-SessionStart, וכן הלאה.

"*", "" או היעדר matcher תואמים הכול.
אותיות, ספרות, _, -, רווחים, | ו-, מתפרשים כשמות מדויקים. Edit|Write תואם כל אחד משני הכלים.
כל דבר אחר מתפרש כביטוי רגולרי של JavaScript, כך ש-mcp__memory__.* תואם את כל הכלים משרת MCP אחד.

Matchers רגישים לאותיות רישיות. חלק מהאירועים, כולל Stop ו-UserPromptSubmit, מתעלמים מ-matchers. באירועי כלים, שדה if עם כלל הרשאה כמו "Bash(git *)" מצמצם handler בודד עוד יותר.

05קלט: מה ה-hook מקבל

כל hook מקבל ב-stdin נתוני JSON עם כמה שדות משותפים, ביניהם session_id, transcript_path, cwd ו-hook_event_name, ובנוסף שדות ייחודיים לאירוע. למשל, hook מסוג PreToolUse לקריאת Bash מקבל גם tool_name ו-tool_input.command. אפשר לקרוא אותו עם jq או כל parser של JSON:

#!/bin/bash
input=$(cat)
cmd=$(jq -r '.tool_input.command // empty' <<<"$input")
echo "Claude wants to run: $cmd" >> ~/claude-commands.log
exit 0

06פלט: קודי יציאה ו-JSON

ל-hook יש שתי דרכים להחזיר תשובה.

קודי יציאה. 0 פירושו הצלחה. 2 הוא שגיאה חוסמת: באירועים שניתן לחסום, הפעולה נעצרת וה-stderr שלכם הופך לסיבה. כל קוד אחר, כולל ה-1 הנפוץ, הוא שגיאה לא חוסמת, כך שהפעולה ממשיכה ומוצגת הודעת שגיאה של ה-hook. אם ה-hook אמור לאכוף כלל, צאו עם 2 ולא עם 1.

JSON ב-stdout. לשליטה מדויקת יותר, צאו עם 0 והדפיסו אובייקט JSON יחיד. חלק מהשדות עובדים בכל מקום, למשל continue: false כדי לעצור את Claude לגמרי. אחרים ספציפיים לאירוע: Stop משתמש ב-decision: "block" יחד עם reason, ואילו PreToolUse ו-PermissionRequest מציבים את ההחלטה בתוך hookSpecificOutput. אל תדפיסו שום דבר נוסף ל-stdout: שורה תועה מפרופיל ה-shell תמנע מ-Claude Code לקרוא את ה-JSON.

07כל אירועי ה-hook

אירועמתי מופעליכול לחסום?

SessionStartסשן מתחיל או מתחדשלא (מוסיף הקשר)

Setupהופעל עם --init-only, או עם --init / --maintenance יחד עם -pלא

InstructionsLoadedקובץ CLAUDE.md או .claude/rules/*.md נטעןלא

UserPromptSubmitשליחת prompt, לפני ש-Claude רואה אותוכן

UserPromptExpansionפקודה מוקלדת מתורגמת ל-promptכן

PreToolUseלפני כל קריאה לכליכן

PermissionRequestקריאה לכלי דורשת החלטת הרשאהמאשר או דוחה דרך JSON

PermissionDeniedמצב אוטומטי דוחה קריאה לכלילא

PostToolUseאחרי קריאה לכלי שהצליחהלא (הכלי כבר רץ)

PostToolUseFailureאחרי קריאה לכלי שנכשלהלא

PostToolBatchאחרי סבב של קריאות מקבילות לכלים, לפני הקריאה הבאה למודלכן

NotificationClaude Code שולח התראהלא

MessageDisplayבזמן שטקסט התשובה של Claude מוצגלא (יכול לשנות את מה שמוצג)

SubagentStart / SubagentStopsubagent מתחיל או מסייםרק SubagentStop

TaskCreated / TaskCompletedמשימה נוצרת או מסומנת כהושלמהכן

StopClaude מסיים להשיבכן (משאיר את Claude בפעולה)

StopFailureהתור מסתיים בשגיאת APIלא

TeammateIdleחבר בצוות סוכנים עומד לעבור למצב idleכן

ConfigChangeקובץ הגדרות משתנה במהלך סשןכן

CwdChangedתיקיית העבודה משתנהלא

DirectoryAddedתיקייה נוספת עם /add-dirלא

FileChangedקובץ במעקב משתנה בדיסקלא

WorktreeCreate / WorktreeRemoveworktree נוצר או מוסרכן

PreCompact / PostCompactלפני ואחרי דחיסת ההקשרPreCompact בלבד

PreModelSwitch / PostModelSwitchלפני ואחרי החלפת המודלPreModelSwitch בלבד

Elicitation / ElicitationResultשרת MCP מבקש קלט, ואחרי שעונים לוכן

SessionEndסשן מסתייםלא

Anthropic מוסיפה אירועים מדי פעם, לכן כדאי לבדוק ב-תיעוד ה-hooks את הרשימה העדכנית ואת שדות הקלט של כל אירוע.

08אילו אירועים רלוונטיים להתראות

ארבעה אירועים מכסים כמעט כל מה שרוצים לקבל עליו התראה:

Stop עבור „Claude סיים”. ראו את המדריך ל-Stop hook.
Notification עבור „Claude מחכה לך”, עם סוגים כמו permission_prompt ו-idle_prompt. ראו את המדריך ל-Notification hook.
PermissionRequest כדי לקבל התראה, או לענות, ברגע שנדרשת הרשאה. ראו את המדריך ל-PermissionRequest.
PreToolUse על הכלי AskUserQuestion, כדי לראות את שאלות הבחירה המרובה של Claude או לענות עליהן. ראו מענה לשאלות מהטלפון.

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

09איפה Claude Code Notifier נכנס לתמונה

Claude Code Notifier בנוי כולו על ה-hooks האלה. כלי שורת הפקודה החינמי שלו, ccn, רץ על Mac,‏ Windows ו-Linux. ההתקנה מוסיפה שבע רשומות hook לקובץ ~/.claude/settings.json, שכל אחת מהן מריצה ccn hook, ושומרת גיבוי חד-פעמי של הקובץ. ccn רץ כמה מילישניות לכל אירוע ואז יוצא, כך ששום דבר לא נשאר פועל ברקע.

לבדו הוא מציג התראות בדסקטופ. כשמצמידים את אפליקציית ה-iPhone או ה-Android, אותם hooks מעבירים בחזרה את התשובות שלך: לאשר או לדחות הרשאה, לענות על שאלה או לשלוח את ההוראה הבאה אחרי ש-Claude עוצר. הכלי עצמאי ואינו מתוצרת Anthropic. אם צריך רק לוג או שלב lint, כמה שורות משלך יהיו פשוטות יותר. הפרטים ב-עמוד ה-ccn.

10שאלות נפוצות

איך בודקים hook בלי לחכות ל-Claude?

מעבירים JSON לדוגמה ב-pipe לסקריפט ובודקים את קוד היציאה: echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh; echo $?. אחר כך מריצים /hooks ב-Claude Code כדי לוודא שהוא רשום תחת האירוע הנכון.

למה ה-hook שלי לא רץ?

הסיבות הנפוצות: JSON לא תקין ב-settings.json (פסיקים מיותרים בסוף, הערות), matcher שלא תואם בדיוק (יש הבחנה בין אותיות גדולות לקטנות), סקריפט בלי הרשאת הרצה, או תיקייה שעדיין לא סומנה כמהימנה. הפעילו את Claude Code עם claude --debug וקראו את לוג ה-debug כדי לראות מה רץ. הרשימה המלאה ב-צ'קליסט פתרון התקלות.

איך מכבים את כל ה-hooks לזמן מה?

מגדירים "disableAllHooks": true בקובץ הגדרות. כדי לדלג עליהם בהרצה אחת, מפעילים את Claude Code עם --settings '{"disableAllHooks": true}'. אין מתג לכיבוי hook בודד; פשוט מסירים את הרשומה שלו. אף אחת מהאפשרויות לא מכבה hooks שהארגון הגדיר ב-managed settings.

מה ה-timeout ברירת המחדל של hook?

עשר דקות (600 שניות) ל-hooks מסוג command,‏ HTTP וכלי MCP,‏ 30 שניות ל-prompt hooks ו-60 ל-agent hooks. לכמה אירועים יש ברירות מחדל קצרות יותר, ואפשר להגדיר timeout בשניות לכל handler.

Claude Code Notifier קבלו push לטלפון כש-Claude Code מסיים או צריך אתכם, ומשם אפשר לאשר, לדחות או לענות. כלי שורת הפקודה ccn זמין בחינם ל-Mac, ל-Windows ול-Linux.

הורדה ל-iOS הורדה ל-Android התקנת ccn