hook יכול לעצור עריכה לפני שהיא משנה קובץ. זו לא דרך מושלמת להגן על קבצים, אבל לפעמים היא מונעת טעויות, ולפעמים שווה לממש אותה.
אם אנחנו רוצים לדחות כתיבה מסוימת, צריך לבדוק את הקלט המוצע לכלי לפני שהכלי רץ. hook של PreToolUse רץ בדיוק בנקודה הזאת, לפני שהקובץ משתנה. בדיקה אחרי הכתיבה יכולה לדווח מה קרה, אבל אז כבר מאוחר מדי למנוע את הקריאה הזאת לכלי.
נניח שמי שמתחזק את הפרויקט מנהל את הגרסאות בנפרד. אנחנו רוצים שהסוכן ישנה את קוד האפליקציה, אבל ישאיר את config/release.json למתחזק. נרשום hook של PreToolUse עם ה-matcher Edit או Write. לפני שאחד מהכלים האלה רץ, ה-handler קורא את נתיב הקובץ המוצע ומשווה אותו לנתיב המוגן.
נרמלו את הנתיב לפני ההשוואה, כי כתיבים שונים יכולים להצביע על אותו קובץ. נתיב יחסי, נתיב שעובר דרך .., והנתיב המוחלט מובילים כולם לאותו קובץ בפרויקט. ה-handler שלנו ממיר את הנתיב לנתיב מוחלט ובודק שהוא בתוך הפרויקט. נתיב שהוא לא מצליח לפענח, או נתיב מחוץ לפרויקט, נדחה עם סיבה נפרדת. קובץ המקור counts.py מוביל לנתיב אחר, אז ה-hook הזה משאיר אותו לתהליך ההרשאות הרגיל.
כשעורכים את הקובץ המוגן, ה-handler מדפיס את ה-JSON הזה לפלט הסטנדרטי. Claude Code קורא את התשובה ל-PreToolUse ודוחה את הקריאה לכלי, כי הערך של permissionDecision הוא deny. הקובץ נשאר בלי שינוי.
הסיבה אומרת לסוכן איזה קובץ אסור לו לערוך, ומבקשת ממנו לפנות במקום זה למתחזק. לקבצים אחרים, ה-handler לא מדפיס כלום, כך ש-Claude Code ממשיך בבדיקות ההרשאה הרגילות שלו. allow מפורש היה מאשר את הקריאה דרך ה-hook הזה, אז כשהכלל של הקובץ הזה לא חל, אנחנו לא מחזירים שום החלטה.
בהרצה המוקלטת הזאת, הסוכן ניסה לשנות את מספר הגרסה מ-1.4.0 ל-1.5.0. Claude Code דחה את העריכה והחזיר לסוכן את הסיבה של ה-hook. בקובץ נשארה הגרסה הישנה, והסוכן אמר למשתמש שהוא לא ביצע את השינוי.
ה-matcher שלנו מכסה את Edit ואת Write. פקודת Bash עדיין יכולה לכתוב לאותו קובץ בלי לעבור דרך ה-handler הזה, למשל בהפניית פלט או בהרצת סקריפט. חיפוש של מילה חשודה בפקודה לא יכול לגלות לנו כל מה שהסקריפט הזה יעשה.
ה-hook הזה שימושי כדי להרחיק עריכות רגילות מקובץ התצורה של הגרסה. אם צריך שהתהליך לא יוכל לכתוב לקובץ הזה דרך אף כלי, אכפו את המגבלה הזאת בעזרת הרשאות של מערכת הקבצים או sandbox.
עד עכשיו בדקנו אם עריכה מוצעת מותרת. עכשיו נראה שימוש אחר ב-hooks. כשהסוכן מסיים את התשובה שלו, hook של Stop יכול לבדוק את הפרויקט ולבקש מהסוכן להמשיך לעבוד. זה לא מבטל עריכות קודמות. זה נותן לסוכן סיבה להמשיך, במקום לסיים את התור עם בדיקה שידוע שהיא נכשלת.
ה-hook של Stop שלנו בודק אם הפרויקט עובר את הבדיקות שלו כשהסוכן מנסה לסיים. ה-handler מריץ את bash tools/check.sh על הקבצים הנוכחיים, עם מגבלת זמן של שתי דקות. הדוגמה הזאת משתמשת בסקריפט הבדיקה הקיים של הפרויקט. hook יכול גם לבקש ממודל שיקול דעת. זו עוד קריאה למודל, והתשובה שלו יכולה להשתנות, אז השתמשו בתוכנית כשהיא יכולה להכריע.
הסקריפט קצר. הוא מריץ את הטסטים, את בודק הטיפוסים, את הלינטר ואת בדיקת העיצוב, בסדר הזה. בסקריפט פשוט וסדרתי כזה, set -e עוצר את הריצה כשפקודה נכשלת, והסקריפט כולו נכשל איתה. אם כל הפקודות מצליחות, הסקריפט מצליח.
אם הבדיקה עוברת, ה-handler לא מדפיס כלום ולא חוסם את הסיום. אם הבדיקה נכשלת, ה-handler מחזיר החלטה לחסום, עם סיבה להמשיך לעבוד. ה-handler שלנו מעתיק לסיבה הזאת את השורות שנכשלו מפלט הטסטים, כאן, ה-assert שנכשל כי אפס שונה מחמש. שימו לב שהתשובה הזאת כתובה בתחביר אחר מזה של החלטת ההרשאה ב-PreToolUse. השתמשו בתחביר של האירוע שאתם מטפלים בו.
מה קורה אם הסוכן לא מצליח לתקן את הכישלון? בדוגמה הזאת, ה-hook מאפשר ניסיון תיקון אחד, ואז בודק שוב. אם הבדיקה השנייה עדיין נכשלת, הוא מפסיק את הניסיונות האוטומטיים ומדווח למשתמש על הבעיה שלא נפתרה. גם חריגה ממגבלת הזמן או סביבת בדיקה תקולה דורשות תשומת לב של אדם, ולכן הכישלונות האלה הולכים ישר לאזהרה.
איך ה-handler יודע שזה ניסיון חוזר? Claude Code שולח את פרטי האירוע כ-JSON לקלט הסטנדרטי של ה-handler. בקטע שמשמאל רואים את השדה stop_hook_active עם הערך true. Claude Code מדליק את הדגל הזה כשהסוכן כבר ממשיך אחרי ש-hook של Stop חסם את הסיום. ה-handler קורא את הדגל. בדוגמה הזאת הוא לא צריך לנהל מונה ניסיונות משלו. ה-handler שלנו בכל זאת מריץ שוב את בדיקת הפרויקט. אם היא נכשלת כשהדגל הזה true, ה-handler מזהיר את המשתמש במקום להחזיר עוד החלטה לחסום. כך אנחנו מגבילים את הניסיון האוטומטי החוזר.
בכישלון חוזר, ה-handler מדפיס את ה-JSON הזה עם systemMessage. Claude Code מציג את האזהרה הזאת למשתמש, והתור מסתיים. האזהרה אומרת שהבדיקות עדיין נכשלות ומפנה לקובץ הלוג שנשמר. זה שהתור הסתיים לא אומר שהעבודה עברה.
ראינו איך hook יכול לדחות קריאה ל-Edit או ל-Write על קובץ מוגן, או לבקש מהסוכן להמשיך אחרי בדיקה שנכשלה. היה נחמד אם היה hook של PreToolUse על המקרר, בחצות הלילה. הוא היה דוחה את הבקשה, עם הסיבה: "כבר אכלתם קינוח." נתראה בסרטון הבא.