👥 פרק 11

סוכני משנה ועבודה מקבילה (Subagents)

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

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

סוכני משנה עובדים בתוך סשן יחיד. להרצת סשנים עצמאיים רבים במקביל ולמעקב ממקום אחד, ראו סוכני רקע (background agents). לסשנים נפרדים שמעבירים הודעות זה לזה, ראו העברת הודעות בין סשנים (cross-session messaging). לצוות מתואם של סשנים שקלוד מפעיל ומפקח עליהם, ראו צוותי סוכנים (agent teams).

קלוד קוד מציע חמש דרכים לעבודה על מספר משימות במקביל: סוכני משנה (subagents), תצוגת סוכנים (agent view), צוותי סוכנים (agent teams), פרויקטים (projects), ותהליכי עבודה דינמיים (dynamic workflows). הן נבדלות ברמת המעורבות שלכם, החל מניהול ישיר של כל שיחה בעצמכם ועד מתן אפשרות לקלוד לתאם קבוצת עובדים, ובשאלה האם העבודה רצה במחשב המקומי או בענן.

בכל הגישות הללו העובדים הם סשנים של קלוד (Claude sessions). כדי לשלב כלי אחר, חושפים אותו לקלוד כשרת MCP.

הרצה של כמה סשנים או סוכני משנה במקביל מכפילה את השימוש בטוקנים.

#חמש גישות לעבודה מקבילה

#בחירת הגישה המתאימה

הבחירה בגישה הנכונה תלויה בשלוש שאלות:

• מי מתאם את העבודה?
  • קלוד מאציל ואוסף תוצאות בתוך שיחה יחידה: סוכני משנה (subagents).
  • אתם מוסרים משימות עצמאיות ובודקים מאוחר יותר: תצוגת סוכנים (agent view).
  • קלוד מתכנן, מקצה ומפקח על קבוצת עובדים: צוותי סוכנים (agent teams), תכונה ניסיונית וכבויה כברירת מחדל.
  • סקריפט מחזיק בתוכנית במקום כושר השיפוט של קלוד מסיבוב לסיבוב: תהליכי עבודה דינמיים (dynamic workflows). התיעוד של תהליכי העבודה משווה אותם לסוכני משנה ולמיומנויות.
• האם העובדים צריכים לדבר זה עם זה?
  • קלוד יכול להעביר ממצאים באמצעות cross-session messaging בין סשנים שאתם מריצים בעצמכם, כולל סשנים ששיגרתם מ-agent view.
  • סוכני משנה מדווחים על תוצאות בחזרה לשיחה שיצרה אותם.
  • סשנים ב-agent view מדווחים על תוצאות רק לכם.
  • חברי צוות ב-agent team מעבירים הודעות ישירות זה לזה, וכאשר יש להם את כלי Task, הם חולקים רשימת משימות משותפת.
• האם המשימות נוגעות באותם קבצים?
  • בודדו את העבודה באמצעות worktrees. סוכני משנה וסשנים שאתם מריצים בעצמכם יכולים להשתמש כל אחד ב-worktree נפרד.
  • צוותי סוכנים אינם מבודדים חברי צוות ב-worktrees, לכן יש לחלק את העבודה כך שכל חבר צוות יהיה אחראי על קבוצת קבצים נפרדת.

#כלים תומכים בעבודה מקבילה

שלושה כלים נוספים תומכים בעבודה זו בלי להוות דרך להרצת סוכנים בעצמם:

• עצי עבודה (worktrees): מעניקים לכל סשן checkout נפרד ב-git, כך שסשנים מקבילים לעולם אינם עורכים את אותם הקבצים. משמשים לסשנים שאתם מריצים בעצמכם. סשן שמשגרים מ-agent view עובר ל-worktree משלו לפני שהוא עורך קבצים, וגם סוכני משנה שמפעילים יכולים לקבל worktree משלהם. כדי לתת לסוכן משנה עותק מבודד של המאגר, מגדירים isolation: worktree. העותק מסתעף כברירת מחדל מענף ברירת המחדל, ולא מ-HEAD של סשן האב, ומנוקה אוטומטית אם הסוכן לא ביצע שינויים. סוכן עם isolation: worktree מריץ פקודות Bash ו-PowerShell בתוך ה-worktree. פקודה שתיקיית העבודה שלה מגיעה ל-checkout הראשי נכשלת, למשל אם תיקיית ה-worktree הוסרה בזמן הריצה. הבדיקה מכסה את כל המאגר שמכיל את התיקייה שממנה הופעל קלוד קוד. כשהסשן רץ ב-worktree מקושר, הבדיקה מכסה גם את ה-checkout הראשי שאליו הוא מקושר. בפקודות Bash קלוד קוד חוסם פקודה שמפנה את git אל ה-checkout הראשי, ומסרב לפקודה כשאי אפשר לוודא מטקסט הפקודה שכל git שהיא מריצה נשאר בתוך ה-worktree, למשל כששם הפקודה מחושב בזמן ריצה. וקטורי ההפניה וכללי הצורה מפורטים בתיעוד תחת אופן אכיפת הבידוד. פקודות PowerShell מקבלות רק את בדיקת תיקיית העבודה. פקודות Monitor עוברות את אותן בדיקות תיקייה ותוכן כמו Bash. כשהשיחה הראשית עצמה רצה מבודדת ב-worktree, אותן בדיקות חלות על הסשן ועל כל סוכן משנה שהוא מפעיל, כולל סוכן בלי isolation: worktree.
• העברת הודעות בין סשנים (cross-session messaging): מאפשרת לקלוד להציג ולשלוח הודעות לסשנים אחרים של קלוד קוד במכונה זו, במכונה אחרת, או ב-Claude Code on the web, כך שסשנים שאתם מריצים בעצמכם יכולים להעביר ממצאים וסטטוס ביניהם.
• פקודת /batch: מיומנות (skill) שגורמת לקלוד לפצל שינוי גדול ל-5 עד 30 סוכני משנה מבודדים ב-worktree שכל אחד מהם פותח pull request. זהו שימוש ארוז בסוכני משנה וב-worktrees, ולא סגנון תיאום נפרד.

#תכונות נוספות להרצה ללא ליווי צמוד

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

• פקודת bash ברקע (background bash command): מריצה פקודת מעטפת אחת בלי לחסום את השיחה. אינה יוצרת סוכן.
• סוכן משנה מפוצל (forked subagent): סוכן משנה שיורש את מלוא הקשר השיחה שלכם במקום להתחיל מחדש. זו דרך להפעיל סוכן משנה, ולא משטח עבודה נפרד. הפיצול מוותר על בידוד הקלט שסוכן משנה אחר נותן: הוא רואה את אותו מצב התחלתי כמו הסשן. מתאים כשכל סוכן אחר היה צריך יותר מדי רקע כדי להיות שימושי, או כשרוצים לנסות כמה גישות במקביל מאותה נקודת התחלה. מפעילים אותו באמצעות /subtask ואחריו המשימה, בין שמצב fork mode דלוק ובין שהוא כבוי. קלוד קוד נותן לפיצול שם לפי המילים הראשונות של המשימה. קלוד גם מפעיל סוכן כזה בעצמו, בבקשת סוג fork דרך כלי Agent, כאשר מצב fork mode מופעל. המצב דלוק כברירת מחדל מגרסה v2.1.302, ובסשן טרמינל אינטראקטיבי מגרסה v2.1.232. כל עוד הוא דלוק, קלוד אינו יכול לחכות לסוכן משנה בטרמינל אינטראקטיבי, ב-VS Code, או בסשן של אפליקציית שולחן העבודה על המחשב. בגרסאות שבהן המצב אינו דלוק כברירת מחדל מגדירים CLAUDE_CODE_FORK_SUBAGENT ל-1. הערך 0 מכבה אותו בכל סוג סשן. כשתצוגת הסוכנים (agent view) כבויה, /subtask אינה זמינה ו-/fork מפעיל את סוכן המשנה המפוצל. כשהתצוגה דלוקה, /subtask מפעיל את סוכן המשנה המפוצל, ו-/fork מעתיק את כל הסשן לתוך סשן רקע חדש שרץ לצידו. פיצול רואה את אותו פרומפט מערכת, כלים, מודל והיסטוריה כמו הסשן הראשי, אבל קריאות הכלים שלו נשארות מחוץ לשיחה ורק התוצאה הסופית חוזרת. הבקשה הראשונה משתמשת מחדש במטמון הפרומפט של האב, כי פרומפט המערכת והכלים זהים, ולכן פיצול זול יותר מסוכן שמתחיל מחדש כשצריך את אותו הקשר. מטמון הפיצול משותף לסשן הראשי. מטמון של סוכן שאינו פיצול נפרד. פיצול רץ ברקע, ובקשות הרשאה של סוכן ברקע עולות בסשן הראשי. פיצול אינו יכול להפעיל פיצולים נוספים. בקריאת Agent קלוד יכול להעביר isolation: "worktree" כדי שהעריכות ייכתבו ל-worktree נפרד. כדי להשאיר את מצב הפיצול דלוק ולמנוע רק הפעלת פיצולים, חוסמים Agent(fork). כשאין הגדרה אחרת, סוכן שקלוד מפעיל מהשיחה הראשית כבר מתחיל ברקע.
• משימה מתוזמנת בענן (cloud scheduled task): מריצה סשן לפי לוח זמנים בענן, ולא במקביל במכונה המקומית.

פיצולים רצים מופיעים בפאנל מתחת לקלט, שורה לסשן הראשי ושורה לכל פיצול. פיצול שהסתיים בהצלחה יורד מהפאנל מיד. פיצול שנכשל או שעצרתם נשאר 30 שניות, כמו סוכן רקע אחר. לפני v2.1.232 גם שורת פיצול שהסתיים נשארה 30 שניות.

כשתמליל של פיצול או של סוכן משנה פתוח, הודעות המשך ומיומנויות הולכות לסוכן הזה. מגרסה v2.1.314 גם /btw עונה לפי התמליל הפתוח. שאר הפקודות המובנות הולכות לשיחה הראשית. /compact, /clear ו-/rewind פועלים על השיחה הראשית, ולכן קלוד קוד מבקש אישור לפני הרצה מהתצוגה הזו. /model ו-/fast קובעים את המודל ואת מצב fast של השיחה הראשית ולא של הסוכן שבתצוגה, ולכן אינם רצים מהתצוגה הזו, ומופיעה הודעה שמסבירה למה. כדי שהסוכן שבתצוגה יקרא את ההודעה לפני שהעבודה שהוא מחכה לה מסתיימת, שולחים עם Ctrl+Enter או Ctrl+X Ctrl+S. פקודת מעטפת או סוכן משנה שאפשר להעביר לרקע עוברים לרקע וממשיכים. כשהסוכן כותב תשובה, או מחכה לעבודה שאי אפשר להעביר לרקע, הוא ממשיך וקורא את ההודעה כשזה נגמר. דורש v2.1.286 ומעלה.

#מעקב אחר עבודה שרצה

הפקודה לבדיקת עבודה שרצה תלויה בגישה שבה השתמשתם:

• עבור סשנים ברקע: הפקודה claude agents פותחת את agent view, מסך יחיד שמציג כל סשן, את מצבו, ואילו סשנים ממתינים לקלט שלכם.
• עבור סוכני משנה בסשן הנוכחי: סוכני משנה בעלי שם שרצים ברקע מופיעים בהשלמה האוטומטית של תיוג @ יחד עם הסטטוס שלהם. מגרסה v2.1.198, הפקודה /agents כבר אינה פותחת את אשף היצירה, אלא מדפיסה תזכורת לבקש מקלוד או לערוך ישירות את .claude/agents/ ואת ~/.claude/agents/. כדי ליצור ולערוך סוכני משנה מותאמים, בקשו מקלוד או ערכו את הקבצים ישירות. למרות השם הדומה, הפקודה /agents נפרדת לחלוטין מ-claude agents.
• עבור כל מה שרץ ברקע של הסשן הנוכחי: הפקודה /tasks מציגה כל פריט ומאפשרת לבדוק אותו, להתחבר אליו (attach), או לעצור אותו. סוכן רקע שהסתיים בהצלחה נשאר ברשימה מסומן כגמור, מתחת לעבודה שרצה, לאותן 30 שניות של הרמז בתחתית המסך, ותצוגת הפרטים שלו נשארת פתוחה. סוכן שנכשל או שעצרתם יוצא מהרשימה. לפני v2.1.208 סוכן שהסתיים יצא מהרשימה מיד ותצוגת הפרטים נסגרה. הרשימה מציגה את המודל של הסוכן, ומוסיפה את רמת המאמץ (effort) שנקבעה לסוכן, אם נקבעה (דורש v2.1.242 ומעלה).
• עבור תהליכי עבודה דינמיים: הפקודה /workflows מציגה ריצות פעילות וריצות שהושלמו, את השלב שבו כל אחת נמצאת, וכמה סוכנים סיימו.
• תצוגת שולחן עבודה: לתצוגה כוללת של כל הסשנים שלכם, ניתן להשתמש בסשנים מקבילים באפליקציית שולחן העבודה (desktop app).

#מתי להשתמש בסוכן משנה ומה הם נותנים

השתמשו בסוכן משנה כשמשימת צד הייתה מציפה את השיחה הראשית בתוצאות חיפוש, לוגים או תוכן קבצים שלא תצטרכו לעיין בהם שוב. קלוד מחליט מתי להאציל לפי שדה description של כל סוכן. כשיוצרים סוכן, כתבו תיאור ברור כדי שקלוד יידע מתי להשתמש בו. כדי לעודד האצלה יזומה, מומלץ לכלול בתיאור ביטויים כמו "use proactively".

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

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

לפרומפט או לתהליך עבודה לשימוש חוזר שנשארים בתוך הקשר השיחה הראשית, שקלו מיומנות (skill) במקום סוכן משנה. לשאלה על משהו שכבר נמצא בשיחה, משתמשים ב-/btw: הוא רואה את מלוא ההקשר, בלי גישה לכלים, והתשובה אינה מתווספת להיסטוריה.

דפוסים נפוצים:

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

יתרונות מרכזיים:

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

תיאורי הסוכנים תופסים מקום בחלון ההקשר, לכן שמרו אותם קצרים. כשהסכום הכולל של תיאורי הסוכנים שהגדרתם (למעט הסוכנים המובנים) עובר 15,000 טוקנים, קלוד קוד מציג אזהרה בהפעלה עם ספירת הטוקנים הכוללת, ועדיין טוען את כל הסוכנים. קצרו את שדות description והעבירו פירוט לפרומפט המערכת של הסוכן, שנטען רק כשהסוכן מופעל בפועל. כתבו כל תיאור כך שיבדיל סוכן אחד מהאחרים, ונשארו בתוך תקציב הטוקנים הזה.

אם סוכן המשנה מופץ בתוך תוסף (plugin), ניתן למדוד את מהימנות ההאצלה אליו מול פרומפטים מציאותיים באמצעות הפקודה claude plugin eval, המריצה פרומפטים עם התוסף ובלעדיו ומדרגת את התוצאות.

מעבר לסוכנים המובנים אפשר ליצור סוכנים משלכם עם פרומפטים מותאמים, הגבלת כלים, מצבי הרשאות, hooks ו-skills.

אפשר לקרוא לסוכן גם במפורש, בשלוש רמות:

• שפה טבעית: מציינים את שם הסוכן בפרומפט, וקלוד מחליט אם להאציל.
• תיוג @: מבטיח שהסוכן הזה ירוץ למשימה אחת. בוחרים אותו בהשלמה, והבחירה נכנסת בצורה @"code-reviewer (agent)". אפשר גם להקליד @agent-<name> לסוכן מקומי, ולסוכן מתוסף @agent- ואחריו השם המתוחם, למשל @agent-my-plugin:code-reviewer. בזמן ההקלדה של הצורה הידנית ההשלמה מציגה קבצים, והאזכור נפתר בשליחה. ההודעה המלאה עדיין מגיעה לקלוד, והוא כותב את פרומפט המשימה. התיוג קובע איזה סוכן יופעל, לא איזה פרומפט הוא יקבל. סוכני רקע בעלי שם שרצים כרגע מופיעים באותה השלמה, עם הסטטוס ליד השם.
• כל הסשן: claude --agent <name>, או השדה agent ב-.claude/settings.json. זה עובד עם סוכנים מובנים ועם סוכנים מותאמים. הדגל גובר על ההגדרה. פרומפט המערכת של סוכן מותאם מחליף את פרומפט ברירת המחדל של קלוד קוד, אלא אם prompt ריק. קובצי CLAUDE.md וזיכרון הפרויקט עדיין נטענים גם כשההגדרה כוללת omitClaudeMd. אם מריצים את הסשן עם -p כסוכן מותאם שיש לו פרומפט משלו, הוא גם מתחיל בלי תמונת המצב של git. השם מופיע בכותרת ההפעלה כ-@<name>. בחידוש סשן ההגבלות והמודל משוחזרים. אם הסוכן כבר לא קיים, הסשן ממשיך עם כלי ברירת המחדל ומוצגת אזהרה עם שם הסוכן. לסוכן מתוסף אפשר להעביר רק את השם. אם כמה תוספים נותנים אותו שם, מעבירים את השם המתוחם, ואם הקובץ בתת-תיקייה כוללים גם אותה, למשל my-plugin:review:security.

#סוכנים מובנים

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

הסוכנים המובנים Explore ו-Plan מדלגים על קובצי CLAUDE.md ועל תמונת המצב של git מסשן האב, כדי שמחקר יישאר מהיר וזול. כל סוכן מובנה אחר, וכל סוכן מותאם אישית, טוענים גם את קובצי CLAUDE.md וגם את תמונת המצב של git, אלא אם הגדרת הסוכן כוללת את השדה omitClaudeMd כדי לדלג על קובצי CLAUDE.md ברמת המשתמש, הפרויקט והמקומי (דורש v2.1.271 ומעלה). קובצי מדיניות מנוהלים עדיין נטענים, חוץ מסוכן שההגדרה שלו מגיעה מהגדרות מנוהלות: שם לא נטען אף קובץ כזה. השדה מיועד לסוכן שלוקח את כל מה שהוא צריך מפרומפט ההאצלה. מתעלמים ממנו כשהסוכן רץ כסוכן הסשן הראשי דרך --agent או הגדרת agent. אצל Explore, אצל Plan, ואצל סוכן עם omitClaudeMd, קובץ CLAUDE.md של תת-תיקייה וכללים לפי נתיב עדיין נטענים כשהסוכן עובד עם קבצים שם. פירוט מלא של מה נטען באתחול מופיע בהמשך, תחת מה נטען בהפעלה.

הסוכנים statusline-setup ו-claude-code-guide מופעלים בדרך כלל אוטומטית, ואין צורך לקרוא להם ישירות.

מגרסה v2.1.198, הסוכן Explore יורש את מודל השיחה הראשית במקום לרוץ תמיד על Haiku. כשהשיחה הראשית רצה על Fable, המודל תלוי בדרך החיבור: במנוי קלוד, בחשבון Anthropic Console, או בשער LLM שמגיעים אליו דרך ANTHROPIC_BASE_URL, Explore רץ על מודל Opus שאליו נפתר הכינוי opus. ב-Amazon Bedrock, ב-Google Cloud's Agent Platform, ב-Microsoft Foundry, ב-Claude Platform on AWS, או בשער Claude apps, Explore נשאר על מודל השיחה הראשית.

CLAUDE_CODE_SUBAGENT_MODEL לבדו הוא ברירת מחדל ואינו משנה את המודל של Explore ושל Plan. כדי להחיל מודל אחד על כל סוכן משנה, על חבר צוות ועל סוכן של תהליך עבודה, מגדירים גם CLAUDE_CODE_SUBAGENT_MODEL_FORCE ל-1 (דורש v2.1.257 ומעלה). כל עוד הכפייה דלוקה, קלוד קוד מתעלם משדה model בכל הגדרה, וקלוד אינו יכול להעביר מודל כשהוא מפעיל סוכן.

• אם שני המשתנים מוגדרים, סוכני המשנה רצים על המודל שב-CLAUDE_CODE_SUBAGENT_MODEL, כולל Explore ו-Plan.
• אם מוגדר רק CLAUDE_CODE_SUBAGENT_MODEL_FORCE, סוכני המשנה רצים על מודל השיחה הראשית, חוץ מהסוכן המובנה Explore, שרץ על המודל שרשום לו בסוכנים המובנים.
• מפוצל (fork), ומיומנות שרצה בסוכן משנה עם model: inherit, נשארים על מודל השיחה הראשית גם כשהכפייה דלוקה.

כדי להריץ כל סוכן משנה על Haiku, מגדירים את שני המשתנים בבלוק env של קובץ הגדרות:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

כדי לוודא שההגדרה חלה, מריצים /tasks בזמן שסוכן משנה רץ. השורה מציגה את המודל שעליו הוא רץ.

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

1. פרמטר model של אותה קריאה. בקריאת כלי Agent הפרמטר מקבל כינוי בלבד: sonnet, opus, haiku או fable. קלוד אינו יכול להעביר בקריאה מזהה מודל מלא או inherit.
2. שדה model בהגדרה. inherit בוחר את מודל השיחה הראשית.
3. CLAUDE_CODE_SUBAGENT_MODEL, כשהוא מוגדר לכינוי או למזהה מודל.
4. מודל השיחה הראשית.

אם מוד (mod) מותקן קובע מודל בהוק agent.spawn, קלוד קוד משתמש במודל הזה במקום פרמטר model של אותה קריאה.

בשדה model אפשר כינוי sonnet, opus, haiku או fable, מזהה מלא כמו claude-opus-5-5 או claude-sonnet-5, או inherit. אותם ערכים מתקבלים כמו בדגל --model.

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

לפני v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL עמד ראשון בסדר ודרס גם את פרמטר הקריאה וגם את ה-frontmatter, כולל model: inherit. הגדרת המשתנה ל-inherit שקולה להשארתו לא מוגדר.

כינוי משפחה כמו opus בפרמטר הקריאה או ב-frontmatter נפתר למודל המדויק של השיחה הראשית, כולל סיומת [1m], כשמודל השיחה שייך לאותה משפחה, כדי שהסוכן יקבל את אותו חלון הקשר מורחב כמו השיחה הראשית. אצל ספק שאינו Anthropic API, כשקלוד קוד אינו מזהה את משפחת המודל, למשל פרופיל הסקה של יישום (application inference profile ARN) ב-Amazon Bedrock שעוד לא נפתר למודל שמאחוריו, הכלל חל רק על הכינוי opus. הוא אינו חל כשמגדירים ANTHROPIC_DEFAULT_OPUS_MODEL, כי אז opus נפתר למודל שהגדרתם. כינוי בתוך CLAUDE_CODE_SUBAGENT_MODEL תמיד נפתר לגרסה שהכינוי מצביע עליה, גם כשהוא ממשפחת השיחה הראשית.

קלוד קוד בודק את פרמטר הקריאה, את ה-frontmatter ואת משתנה הסביבה מול רשימת availableModels של הארגון. כינוי משפחה חסום, כמו opus, מוחלף בגרסה החדשה ביותר של המשפחה שהרשימה מתירה, לפי אותם כללי החלפה כמו /model. לפני v2.1.222 גם כינוי משפחה חסום רץ על המודל בירושה. לכל ערך חסום אחר, אצל ספקים שבהם ההחלפה הזו אינה פועלת, או כשאין גרסה מותרת של המשפחה, הסוכן רץ על המודל בירושה. אם הוגדר CLAUDE_CODE_SUBAGENT_MODEL, קלוד קוד מנסה אותו קודם, לפי אותם כללים. בסשן אינטראקטיבי מופיעה אזהרה עם המודל המבוקש והמודל שעליו הסוכן רץ.

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

כשמבקשים מקלוד להריץ סוכן משנה שאינו פיצול ברמת מאמץ מסוימת, הוא יכול להעביר פרמטר effort לאותה קריאה. הפרמטר דורס את שדה effort בהגדרה, ונשאר בתוקף כשממשיכים את הסוכן. משתנה הסביבה CLAUDE_CODE_EFFORT_LEVEL גובר גם על השדה וגם על הפרמטר. הפרמטר דורש v2.1.292 ומעלה. כשאין שדה effort ואין פרמטר בקריאה, והסוכן רץ על מודל השיחה הראשית, הוא רץ ברמה שנבחרה בסשן, למשל עם /effort או עם --effort. על מודל אחר הרמה הזו אינה חלה, ובוחרים אותה בשדה effort.

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

כשקלוד מפעיל את Explore הוא בוחר רמת פירוט: quick לחיפוש ממוקד, medium לחקירה מאוזנת, או very thorough לניתוח מקיף.

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

כדי להגביל סוכנים מובנים:

• לחסימת סוכן מובנה מסוים, הוסיפו אותו ל-permissions.deny, למשל Agent(Explore).
• כדי למנוע מקלוד להאציל לכל סוכן משנה שהוא, חסמו את כלי Agent ב-permissions.deny.
• כדי להסיר רק את הסוכנים המובנים Explore ו-Plan, הגדירו CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. במקרה זה קלוד יקרא ויחקור קבצים ישירות במקום להאציל אליהם (דורש v2.1.198 ומעלה).
• במצב לא אינטראקטיבי וב-Agent SDK, הגדירו CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 כדי להסיר את כל הסוכנים המובנים ולספק סוכנים מותאמים אישית בלבד.

קריאת כלי Agent המשמיטה את subagent_type נכשלת עם השגיאה subagent_type is required כאשר בסשן אין סוכן general-purpose לנפילה חזרה.

בגרסה 2.1.63 הכלי Task שונה שמו ל-Agent. הפניות Task(...) קיימות בהגדרות ובהגדרות סוכן ממשיכות לעבוד ככינוי.

#יצירת סוכן משנה מותאם

סוכני משנה הם קובצי Markdown עם YAML frontmatter. אפשר לבקש מקלוד לכתוב את הקובץ, או לכתוב אותו ידנית תחת .claude/agents/ (פרויקט) או ~/.claude/agents/ (משתמש). אפשר גם להגדיר סוכנים דרך דגל ה-CLI בשם --agents או להפיץ אותם בתוספים (plugins).

מגרסה v2.1.198 הפקודה /agents כבר אינה פותחת את אשף היצירה האינטראקטיבי. הרצתה מציגה תזכורת לבקש מקלוד או לערוך ישירות את .claude/agents/ ואת ~/.claude/agents/. קובצי הסוכנים, שדות ה-frontmatter והנתיבים נותרו ללא שינוי, ורק האשף בטרמינל הוסר. בגרסאות v2.1.197 ומטה הפקודה עדיין פותחת אשף אינטראקטיבי עם לשונית Running לרשימת סוכנים פעילים ולשונית Library ליצירה, עריכה ומחיקה.

להלן ההליך ליצירת סוכן ראשון ברמת המשתמש, צעד אחר צעד:

1. לבקש מקלוד ליצור את סוכן המשנה (Ask Claude to create the subagent): תארו לקלוד קוד את הסוכן הרצוי והיכן לשמור אותו:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

קלוד יכתוב את הקובץ עם name, description, רשימת tools, model ופרומפט מערכת.

2. לבדוק את הקובץ (Review the file): פתחו את הקובץ ~/.claude/agents/code-improver.md וודאו שה-frontmatter תואם למה שביקשתם:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

מכיוון שהקובץ נשמר ב-~/.claude/agents/, הסוכן זמין בכל פרויקט במכונה שלכם. כדי להגביל אותו לפרויקט יחיד, העבירו את הקובץ לתיקיית .claude/agents/ של אותו פרויקט.

3. לנסות אותו (Try it out): בקשו מקלוד להאציל משימה לסוכן החדש:

Use the code-improver agent to suggest improvements in this project

קלוד יאציל את העבודה לסוכן החדש, שיסרוק את הפרויקט ויחזיר הצעות שיפור. בתמליל השיחה ההאצלה מופיעה כשורת קריאת כלי עם שם הסוכן ותיאור קצר של המשימה, למשל code-improver(Suggest code improvements).

אם קלוד אינו מוצא את הסוכן החדש, הפעילו מחדש את קלוד קוד ונסו שוב. הדבר קורה רק כאשר תיקיית ~/.claude/agents/ לא הייתה קיימת לפני תחילת הסשן, משום שסשן פעיל אינו מזהה תיקיית agents שנוצרה תוך כדי עבודה.

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

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

במצב לא אינטראקטיבי, --append-subagent-system-prompt מוסיף טקסט לסוף פרומפט המערכת של כל סוכן משנה, כולל סוכנים מקוננים, חוץ מסוכן מפוצל שמשתמש בפרומפט של השיחה (דורש v2.1.205 ומעלה). אם הטקסט ארוך מדי לשורת הפקודה, שומרים אותו בקובץ ומעבירים את הנתיב ב---append-subagent-system-prompt-file (דורש v2.1.261 ומעלה).

רק name ו-description הם שדות חובה. name הוא המזהה, עד 256 תווים, ושם הקובץ לא חייב להתאים לו. הוקים מקבלים את הערך כ-agent_type. שמות מרובי מילים הם camelCase, כמו maxTurns ו-disallowedTools, וצריכים להתאים בדיוק לטבלה בתיעוד. שדה לא מוכר מדולג בלי שגיאה. כדי למצוא שדה שגוי בסוכן שכן נטען, מריצים claude --debug ומחפשים בלוג ~/.claude/debug/<session-id>.txt את המחרוזת does not recognize or apply. הלוג מציין עד חמישה שדות ברמה העליונה שאינם מוכרים, ואם שדה נתמך קרוב, גם את השם הסביר. דורש v2.1.296 ומעלה. השדה tools הוא מחרוזת מופרדת בפסיקים, כמו Read, Grep, Bash, או רשימת YAML. אם משמיטים אותו, הסוכן יורש כל כלי הזמין לסוכני משנה. כדי לטעון מיומנויות מראש משתמשים בשדה skills, ולא ברישום Skill בתוך tools. מוזרק התוכן המלא של כל מיומנות, עד 32 השמות השונים הראשונים ברשימה.

שדה skills הוא ההפך מהרצת מיומנות עם context: fork. בסוכן, הסוכן שולט בפרומפט המערכת וטוען את תוכן המיומנות. במיומנות עם context: fork, תוכן המיומנות מוזרק לסוכן שציינתם. בשני המקרים הסוכן מתחיל בלי היסטוריית השיחה שלכם. כדי שהסוכן לא יוכל להפעיל מיומנויות בכלל, משמיטים את Skill מ-tools או מוסיפים אותו ל-disallowedTools.

קלוד קוד מדלג על קובץ בתיקיית agents של פרויקט, משתמש, הגדרות מנוהלות, או תיקייה שנוספה עם --add-dir, בלי לדווח על כך בסשן, באחד מהמקרים האלה:

• אין name: הקובץ נחשב תיעוד ליד הסוכנים.
• --- הפותח אינו השורה הראשונה: הקובץ נקרא בלי frontmatter ונחשב תיעוד.
• name מתחיל ב-- או מכיל :: הקובץ מדולג, ונרשמת שגיאה בלוג הדיבוג. נקודתיים שמורות למזהה מתוחם של תוסף.
• name ארוך מ-256 תווים: הקובץ מדולג, ונרשמת שגיאה בלוג הדיבוג.
• יש name ואין description: הקובץ מדולג, והסיבה נרשמת בלוג הדיבוג.
• ה-YAML אינו נפרס: לא נקראים שדות, והקובץ מדולג עם שגיאת הפענוח בלוג הדיבוג.

כדי לראות את לוג הדיבוג מריצים עם --debug. סוכן מתוסף בלי name, או עם frontmatter שלא נפרס, עדיין נטען לפי שם הקובץ. כדי למצוא קבצים שה-frontmatter שלהם אינו נפרס לפני סשן, מריצים claude plugin validate על התיקייה, למשל .claude/agents או ~/.claude/agents. הבדיקה חלה רק על התיקייה שציינתם, ואינה מסמנת קובץ שה-YAML שלו תקין אבל אין בו name (דורש v2.1.233 ומעלה).

שדות שמשתמשים בהם לעיתים קרובות, מעבר ל-name, description, tools ו-model:

אי אפשר לטעון מראש מיומנות עם disable-model-invocation: true, כי הטעינה מראש נלקחת מאותן מיומנויות שקלוד יכול להפעיל. זה כולל את /verify המצורפת, שקלוד אינו יכול להריץ בעצמו. מיומנות חסרה או כבויה, למשל לפי מדיניות הארגון, מדולגת עם אזהרה בלוג הדיבוג.

זיכרון מתמשך הוא חלק מ-auto memory. אם מכבים אותו בהגדרה autoMemoryEnabled או ב-CLAUDE_CODE_DISABLE_AUTO_MEMORY, לשדה memory אין השפעה והסוכן עולה בלי הוראות הזיכרון ובלי גישת כלי הזיכרון. כשהזיכרון דלוק, הפרומפט כולל הוראות קריאה וכתיבה לתיקייה, וגם את 200 השורות הראשונות או 25KB של MEMORY.md, המוקדם מביניהם, עם הוראה לצמצם את הקובץ אם עבר את הגבול. הכלים Read, Write ו-Edit מופעלים אוטומטית.

project מומלץ כברירת מחדל כי הידע ניתן לשיתוף ב-git. כדאי לבקש מהסוכן לבדוק את הזיכרון לפני תחילת העבודה ולשמור מה שלמד בסופה. אפשר לכתוב את ההנחיה הזו בגוף קובץ הסוכן, כדי שיעדכן את הידע בעצמו.

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

• המעקב מכסה רק תיקיות שהיו קיימות כשהסשן התחיל. אחרי יצירת קובץ הסוכן הראשון של היקף בתיקיית agents חדשה, מפעילים מחדש כדי לטעון אותו.
• קלוד קוד אינו עוקב אחרי .claude/agents/ בתוך תיקיות שנוספו עם --add-dir או /add-dir. אחרי הוספה או עריכה שם, מפעילים מחדש.
• סשן שהתחיל עם --disable-slash-commands אינו עוקב אחרי התיקיות האלה כלל.

#היקפי סוכנים (Scopes) וסדרי עדיפויות

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

סוכנים מנוהלים הם קובצי Markdown בתיקייה .claude/agents/ שבתוך תיקיית ההגדרות המנוהלות, באותו פורמט frontmatter כמו סוכני פרויקט ומשתמש. הגדרה מנוהלת גוברת על סוכן פרויקט או משתמש באותו שם.

סוכני פרויקט (.claude/agents/): מיועדים למשימות ספציפיות לבסיס קוד. מומלץ לשמור אותם ב-git לשיתוף פעולה בצוות. קלוד קוד מגלה סוכני פרויקט על ידי סריקה במעלה עץ התיקיות מתיקיית העבודה הנוכחית ועד לשורש המאגר. כאשר יותר מתיקייה מקוננת אחת מגדירה את אותו name, נבחרת ההגדרה הקרובה ביותר לתיקיית העבודה. תיקיות שנוספו עם --add-dir או /add-dir נטענות גם הן לצד סוכני הפרויקט, כולל תיקיית .claude/agents/ שלהן. כדי לשתף סוכנים בין פרויקטים בלי --add-dir, השתמשו ב-~/.claude/agents/ או בתוסף (plugin).

סוכני משתמש (~/.claude/agents/): סוכנים אישיים הזמינים בכל הפרויקטים במכונה.

קלוד קוד סורק את .claude/agents/ ואת ~/.claude/agents/ בצורה רקורסיבית, כך שניתן לארגן הגדרות בתתי-תיקיות כמו agents/review/ או agents/research/. נתיב תת-התיקייה אינו משנה את הזיהוי או את אופן ההפעלה: הזהות מגיעה רק משדה name ב-frontmatter.

שמרו על name ייחודי בכל העץ. אם שני קבצים תחת אותה תיקיית .claude/agents/, כולל תתי-התיקיות שלה, מצהירים על אותו שם, קלוד קוד טוען רק אחד מהם, לפי סדר הקריאה במערכת הקבצים. אין עדיפות מתועדת בין הקבצים האלה. בין תיקיות פרויקט מקוננות, ההגדרה הקרובה ביותר לתיקיית העבודה היא זו שנבחרת. הפקודה /doctor מדווחת על קבצים באותה תיקייה שחולקים שם, ומציעה לשנות שם או להשאיר רק אחד.

גם תיקיות agents/ של תוסף נסרקות רקורסיבית. בתוסף, תת-תיקייה בתוך agents/ נכנסת למזהה המתוחם (scoped identifier): קובץ בנתיב agents/review/security.md בתוסף my-plugin נרשם כ-my-plugin:review:security. סוכני תוסף נטענים אוטומטית לצד הסוכנים המותאמים ומופיעים בהשלמה של @ תחת השם המתוחם.

מטעמי אבטחה, סוכן מתוסף אינו תומך בשדות hooks, mcpServers ו-permissionMode. קלוד קוד מתעלם מהם בטעינה. אם צריך אותם, מעתיקים את הקובץ ל-.claude/agents/ או ל-~/.claude/agents/. אפשר גם להוסיף כללים ל-permissions.allow ב-settings.json או ב-settings.local.json, אבל הכללים חלים על כל הסשן ולא רק על סוכן התוסף. גם initialPrompt מתעלמים ממנו בסוכן שמגיע מתוסף. אם אתם מחברי התוסף, שימו את ההוקים בקובץ hooks/hooks.json של התוסף ואת שרתי ה-MCP בקובץ .mcp.json שלו. הם חלים כל עוד התוסף מופעל, ולא רק בתוך סוכן המשנה.

סוכנים מוגדרים ב-CLI (--agents): מועברים כ-JSON בעת הפעלת קלוד קוד. הם קיימים רק לאותו סשן ואינם נשמרים לדיסק, ולכן מתאימים לבדיקה מהירה או לסקריפט אוטומציה. אפשר להגדיר כמה סוכנים בקריאה אחת ל---agents.

ב-macOS, ב-Linux וב-WSL:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

ב-Windows PowerShell:

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

במצב לא אינטראקטיבי, --agents מקבל גם נתיב לקובץ JSON עם אותו אובייקט, כשההגדרה גדולה מדי לשורת הפקודה. לדוגמה, claude -p --agents ./agents.json "Review my changes" קורא את ההגדרות מהקובץ. בסשן אינטראקטיבי קלוד קוד דוחה נתיב קובץ. צורת הקובץ דורשת v2.1.281 ומעלה.

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

ההגדרה כוללת את השדות האלה:

• prompt: פרומפט המערכת של הסוכן, המקביל לגוף ה-Markdown בסוכן מבוסס קובץ. prompt יכול להיות ריק. אם בוחרים סוכן עם prompt ריק ובלי שדה memory כסוכן הסשן באמצעות --agent, פרומפט המערכת של הסשן נשאר ללא שינוי. prompt ריק דורש v2.1.281 ומעלה.
• שדות frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd, ו-isolation.
• שדות שקלוד קוד מתעלם מהם ב-JSON: color ו-experimental אינם מתקבלים כאן. קלוד קוד מתעלם מהם, וההגדרה נטענת בלעדיהם.

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

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

#מה נטען בהפעלה

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

ההקשר ההתחלתי של סוכן שאינו פיצול כולל:

• פרומפט מערכת: הפרומפט של הסוכן ועוד פרטי סביבה שקלוד קוד מוסיף. לסוכן מותאם זה גוף ה-Markdown או השדה prompt. לסוכנים מובנים יש פרומפט מוגדר מראש.
• הודעת משימה: פרומפט ההאצלה שקלוד כותב.
• קובצי CLAUDE.md: כל הרמות שהשיחה הראשית טוענת, כולל ~/.claude/CLAUDE.md, כללי פרויקט, CLAUDE.local.md, קובצי מדיניות מנוהלים, וקובצי AGENTS.md שנטענים כהוראות פרויקט. Explore ו-Plan מדלגים על זה. סוכן עם omitClaudeMd טוען רק קובצי מדיניות מנוהלים, או אף אחד מהם כשההגדרה מגיעה מהגדרות מנוהלות. אצל Explore, אצל Plan, ואצל סוכן עם omitClaudeMd, קובץ CLAUDE.md של תת-תיקייה וכללים לפי נתיב עדיין נטענים כשהסוכן עובד עם קבצים שם.
• מצב git: תמונת מצב שנקראת כשהסוכן מתחיל. לסוכן משנה ב-worktree משלו של אותו מאגר, התמונה מציגה את הענף של ה-worktree, את הסטטוס ואת הקומיטים האחרונים. חסרה מחוץ למאגר git, או כשתמונת המצב כבויה דרך includeGitInstructions. Explore ו-Plan מדלגים עליה תמיד. אי אפשר לבחור אילו סוכנים אחרים יקבלו אותה.
• מיומנויות שנטענו מראש: התוכן המלא של כל מיומנות בשדה skills, עד 32 השמות השונים הראשונים. סוכנים מובנים אינם טוענים מיומנויות מראש.
• רשימת אחים: תזכורת מערכת עם main וכל סוכן אחר בעל שם בסשן, כל אחד ערך to חוקי ל-SendMessage. מופיעה רק כשבכלים יש SendMessage ולפחות סוכן נוסף יש שם, בין שקלוד נתן אותו בהפעלה ובין שהוא חבר צוות. זו תמונה מרגע ההפעלה, וסוכנים שקיבלו שם אחר כך אינם מופיעים.

מצב של השיחה הראשית שאינו מגיע לסוכן שאינו פיצול:

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

השיחה הראשית עדיין מחזיקה את מלוא CLAUDE.md כשהיא קוראת את תוצאות הסוכנים. כלל שחייב להגיע לסוכן, למשל להתעלם מתיקיית vendor/, חוזרים עליו בפרומפט ההאצלה.

#כלים, הרשאות והוקסים

סוכן משנה יורש את הכלים המובנים ואת כלי ה-MCP של השיחה הראשית, ואז שני מסננים מצמצמים אותם. ב-macOS, ב-Linux וב-WSL סוכן יכול לקבל גם את Glob ואת Grep כשאין אותם בשיחה הראשית. פיצול מדלג על שני המסננים ומקבל את מאגר הכלים המדויק של השיחה.

המסנן הראשון מסיר את הכלים האלה גם אם הם רשומים ב-tools:

• Agent, כשהסוכן בתקרת העומק. בפיצול הכלי נשאר ברשימה אבל מחזיר שגיאה במקום להפעיל סוכן.
• AskUserQuestion
• EndConversation, שיכול לסיים רק את השיחה הראשית
• EnterPlanMode
• ExitPlanMode, אלא אם permissionMode של הסוכן הוא plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

המסנן השני חל על סוכן שרץ ברקע, וזו ברירת המחדל. חוץ מ-Agent ומ-ExitPlanMode, שנשארים לפי תנאי המסנן הראשון בכל מקום, סוכן ברקע שומר כל כלי MCP ורק את הכלים המובנים האלה: Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage ו-Artifact, ובנוסף SubagentHandback לסוכן שמדווח דרכו. כל כלי מובנה אחר מוסר, בין שעבר בירושה ובין שנרשם ב-tools, בלי שגיאה, אלא אם רשימת tools נשארת בלי אף כלי. לפני v2.1.280 סוכן ברקע לא יכול היה להשתמש ב-LSP. אותה הגדרה יכולה להיפתר לכלים שונים בחזית וברקע. פיצול, וסוכן חזית שממשיכים אותו, שומרים את סט הכלים מהמקום שבו רצו לראשונה.

ListAgents עובר את המסננים כמו כל כלי מובנה: סוכן בחזית יורש אותו בסשן שבו העברת הודעות בין סשנים מופעלת, וסוכן ברקע אינו שומר אותו. חברי צוות שומרים בנוסף את TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete ו-CronList. בסשן בלי כלי המשימות, גם סוכני המשנה אינם מקבלים אותם, גם אם הם רצים על מודל אחר. חבר צוות בתוך התהליך עוקב אחרי הסשן באותו אופן. כדי לדעת אם לחבר צוות בחלון מפוצל יש את כלי המשימות, עיינו בתיעוד בזמינות כלי המשימות.

tools הוא רשימת היתר ו-disallowedTools הוא רשימת חסימה. אם שניהם מוגדרים, קודם מוחל disallowedTools ואחר כך tools על מה שנשאר. כלי שמופיע בשניהם מוסר. אם שום רשומה ב-tools אינה נפתרת לכלי, למשל כשכל הרשומות שגויות בכתיב או מציינות כלי שאינו זמין לסוכני משנה, קלוד קוד בדרך כלל מסרב להפעיל את הסוכן וכלי Agent מחזיר שגיאה עם הרשומות שלא נפתרו. שני השדות מקבלים גם רשומה לשרת MCP שלם. ב-tools, הרשומה mcp__<server>__* נותנת כל כלי של השרת. ב-disallowedTools, mcp__<server> או mcp__<server>__* מסירים את כלי השרת, ו-mcp__* מסיר כל כלי MCP. רשומת disallowedTools עם מפרט, כמו Bash(git push *), מסירה את כל הכלי. כדי להשאיר את Bash ולחסום פקודות מסוימות, מוסיפים כלל כמו Bash(git push *) ל-permissions.deny. הכלל חל על השיחה הראשית ועל סוכני המשנה.

מלכודת בשם שרת שמכיל __: אם הסוכן לא מקבל אף כלי משרת MCP ששמו מכיל __, כמו reports__v2, בודקים את רשומות mcp__. ב-tools כותבים mcp__, את שם השרת המלא, ואז __*, למשל mcp__reports__v2__*. בלי __* בסוף, הרשומה mcp__reports__v2 אינה תואמת לאף כלי של השרת. ב-disallowedTools, הרשומות mcp__reports או mcp__reports__* מיועדות לשרת בשם reports. עם אחת מהן הסוכן מאבד גם כל כלי של reports__v2, כי שמות הכלים האלה מתחילים ב-mcp__reports__. כדי להסיר רק את כלי השרת reports, רושמים אותם אחד אחד, למשל mcp__reports__run_query.

כשסוכן רץ כחוט הראשי עם claude --agent, תחביר Agent(agent_type) בשדה tools הוא רשימת היתר של סוגים שהוא יכול להפעיל. בלי סוגריים, Agent מאפשר כל סוג. אם Agent חסר לגמרי, הסוכן אינו יכול להפעיל סוכני משנה. ניסיון להפעיל סוג שאינו ברשימה נכשל, והסוכן רואה בפרומפט רק את הסוגים שהותרו. כדי לחסום סוגים מסוימים ולהשאיר את השאר, משתמשים ב-permissions.deny. בתוך הגדרת סוכן משנה, רשימת סוגים בתוך הסוגריים מדולגת: עצם הרישום של Agent מאפשר הפעלה כל עוד תקרת העומק מרשה.

אם לא מגדירים permissionMode, הסוכן יורש את מצב ההרשאות של השיחה הראשית. מצב השיחה הראשית קובע אם הערך שהגדרתם ישמש:

• ב-bypassPermissions, ב-acceptEdits או במצב auto, הסוכן רץ באותו מצב והערך שהגדרתם מדולג. במצב auto המסווג בודק את קריאות הכלים של הסוכן עם כללי החסימה וההיתר של השיחה הראשית, ובסיום בודק גם את העבודה ואת הדוח הסופי לפני שהדוח נמסר.
• ב-plan, הסוכן נשאר במצב תכנון בכל permissionMode שהגדרתם, אלא אם הוא רץ כחבר צוות לפי כללי צוותי הסוכנים. אם הגדרתם dontAsk, הסוכן גם אינו מבקש מכם אישור: פעולה שמצב תכנון היה מבקש לאשר נדחית.
• ב-default או ב-dontAsk, הסוכן רץ במצב שהגדרתם, חוץ משני מקרים שבהם הוא נשאר במצב של השיחה הראשית: הצהרה על bypassPermissions (החריג דורש v2.1.267 ומעלה), או הצהרה על auto כשמצב auto אינו זמין לסוכן, למשל כשקובץ הגדרות מגדיר disableAutoMode או כשהמודל של הסוכן אינו תומך במצב auto. סוכן רץ ב-bypassPermissions רק כשגם השיחה הראשית במצב הזה.

שרת מוטמע ב-mcpServers מתחבר כשהסוכן מתחיל, לפי כלל האמון של תיקיית קובץ הסוכן, ומתנתק כשהסוכן מסיים. הפניה בשם משתפת את החיבור של סשן האב. הגדרה מוטמעת משתמשת באותה סכמה כמו רשומה ב-.mcp.json, ותומכת בסוגים stdio, http, sse ו-ws. כדי ששרת MCP לא ייכנס לשיחה הראשית בכלל, ושתיאורי הכלים שלו לא יצרכו שם הקשר, מגדירים אותו מוטמע כאן ולא ב-.mcp.json. הסוכן מקבל את הכלים, והשיחה הראשית לא. כשהסוכן הוא הסשן הראשי, שרת מוטמע מתחבר בהפעלה לצד שרתים מ-.mcp.json ומקובצי הגדרות, לפי אותו כלל אמון. ב-/mcp, שרת מרוחק (HTTP או SSE) שכבר השתמשתם בו יכול להופיע בסטטוס cached, וקלוד קוד מתחבר אליו כשקלוד קורא לראשונה לאחד הכלים שלו. שרת מוטמע בקובץ תחת .claude/agents/ של הפרויקט, או תחת .claude/agents/ של --add-dir, נטען רק אחרי אמון בתיקייה שממנה הגיע הקובץ. לפני v2.1.238 השרתים האלה נטענו בלי בדיקת אמון. אמון בתיקיית אב, והאמון האוטומטי שסשן -p או SDK מקבל להוקסים בקובצי הגדרות, אינם נספרים. עד אז קלוד קוד מדלג על כל שרת מוטמע בקובץ וכותב ללוג הדיבוג את המפתח projects["<path>"].hasTrustDialogAccepted של ~/.claude.json. תיקיית --add-dir מחוץ למאגר של סביבת העבודה המהימנה צריכה רשומת אמון משלה. בלי בדיקת אמון לתיקיית הקובץ נטענים שם של שרת שכבר מוגדר, ושרת מוטמע בקובץ מ-~/.claude/agents/, מ---agents, מאפשרות agents של ה-SDK, או מהגדרות מנוהלות.

המגבלות שחלות על הסשן הראשי חלות גם על שרתים ב-frontmatter: --strict-mcp-config ו---bare, תצורת MCP מנוהלת בארגון, ומדיניות allowedMcpServers ו-deniedMcpServers. שרת חסום מדולג ומופיעה אזהרה עם שמות השרתים. מגבלות של הגדרות מנוהלות חלות על כל סוכן משנה. --strict-mcp-config אינו מסנן שרתים מוטמעים שהועברו ב---agents או באפשרות agents של ה-SDK.

הוקים ב-frontmatter רצים רק בזמן שהסוכן פעיל, וגם כשהסוכן הוא הסשן הראשי דרך --agent או הגדרת agent, לצד הוקים מ-settings.json. כל אירועי ההוק נתמכים. הנפוצים בסוכן משנה הם PreToolUse לפי שם הכלי, PostToolUse לפי שם הכלי, ו-Stop בלי matcher, שמומר בזמן ריצה ל-SubagentStop כשהסוכן הופעל כסוכן משנה. כדי שהוקים של סוכן פרויקט ירוצו, מאשרים את תיבת האמון של התיקייה שמכילה את קובץ הסוכן. אמון בתיקיית אב אינו מספיק, וסשן -p אינו נחשב אמון. עד אז הסוכן רץ, ההוקסים מדולגים, ונרשמת שגיאה בלוג הדיבוג. הוקים מ-~/.claude/agents/ ומהגדרות --agents רצים בלי הצעד הזה. תיקייה מ---add-dir מחוץ למאגר המהימן צריכה אמון נפרד.

ב-macOS וב-Linux סקריפט הוק מסוג command צריך להיות בר הרצה, אחרת ההוק נכשל במקום לחסום. ב-Windows כותבים את הסקריפט ב-PowerShell ומוסיפים shell: powershell לרשומת ההוק. קלוד קוד מעביר את קלט ההוק כ-JSON ב-stdin. יציאה בקוד 2 חוסמת את הפעולה ומחזירה את ההודעה לקלוד דרך stderr.

הוקים מ-settings.json, ממדיניות מנוהלת ומתוספים חלים גם בתוך סוכני משנה. PreToolUse ו-PostToolUse נורים על קריאות הכלים של הסוכן, ו-SubagentStart ו-SubagentStop נורים כשסוכן מתחיל או מסיים. ה-matcher הוא שדה name, או המזהה המתוחם של תוסף כמו my-plugin:db-agent. שם מתוחם מכיל נקודתיים ולכן נבדק כביטוי רגולרי לא מעוגן. כדי להתאים רק לסוכן הזה מעגנים עם ^ ו-$, למשל ^my-plugin:db-agent$.

חסימת סוג מסוים היא Agent(subagent-name) במערך deny, או בדגל --disallowedTools. זה עובד לסוכנים מובנים ולסוכנים מותאמים.

#חזית, רקע, המשך ומגבלות

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

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

• ב-claude -p וב-Agent SDK קלוד יכול לחכות, לפי שיקול דעתו או כשמבקשים ממנו.
• בטרמינל אינטראקטיבי, ב-VS Code ובסשן של אפליקציית שולחן העבודה על המחשב, כדי שקלוד יוכל לחכות לסוכן משנה מכבים את מצב fork mode. המצב דלוק כברירת מחדל, כפי שמתואר למעלה.

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

כדי שקלוד יחכה לסוכן משנה:

1. מכבים את מצב fork mode: מגדירים CLAUDE_CODE_FORK_SUBAGENT ל-0, למשל בבלוק env של settings.json:

{
  "env": {
    "CLAUDE_CODE_FORK_SUBAGENT": "0"
  }
}

2. מריצים claude מחדש מהמעטפת, או פותחים שיחה חדשה ב-VS Code.
3. מבקשים מקלוד לחכות כשצריך את התוצאה קודם, למשל להריץ את סוכן הביקורת ולחכות לדוח.

כדי להמשיך לעבוד בזמן שקלוד מחכה, לוחצים Ctrl+B בטרמינל, או בוחרים Run in background ב-VS Code.

אם במקום לכבות את מצב הפיצול מגדירים CLAUDE_CODE_DISABLE_BACKGROUND_TASKS ל-1, קלוד מחכה לכל סוכן משנה ומשימות הרקע כבויות, כולל Ctrl+B.

שדה background: true משאיר את הסוכן ברקע גם כשקלוד מבקש לחכות לו. סוכן ברקע יכול להשאיר פקודת Bash או PowerShell ברקע אחרי סוף התור שלו. כשהפקודה מסתיימת, קלוד קוד שולח לסוכן התראה. התוצאה של הסוכן מגיעה לקלוד כהתראת סיום בתור מאוחר יותר, והוא מחכה לה לפני שהוא מדווח. אם שואלים קודם על ההתקדמות, הוא מדווח שהסוכן עדיין רץ.

קלוד קוד מסיר שורת סוכן רקע מהפאנל שמתחת לקלט באחת משתי דרכים. כשהסוכן מסתיים בהצלחה, השורה יורדת מיד, וחוץ ממצב קורא מסך מופיע בתחתית המסך /tasks to see subagents למשך 30 שניות. בזמן הזה מריצים /tasks ולוחצים Enter על הסוכן כדי לפתוח את התמליל. לפני v2.1.232 השורה נשארה 30 שניות גם אחרי סיום מוצלח, כמו בשורת כישלון, ובלי רמז בתחתית. כשהסוכן נכשל או שאתם עוצרים אותו, השורה נשארת 30 שניות. כדי לנקות מוקדם יותר, בוחרים את השורה ולוחצים x.

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

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

• בסשן טרמינל אינטראקטיבי רק הסיכום של הסוכן העליון חוזר אליכם, כי סוכן שמפעיל סוכני רקע מחכה לתוצאות לפני שהוא מסיים.
• ב-claude -p וב-Agent SDK הסוכן המפעיל מחכה כל עוד מצב fork mode דלוק. אם מכבים את מצב הפיצול, סוכנים מקוננים מתחילים ברקע. הסוכן המפעיל אינו מחכה לסוכן רקע מקונן, ואם הסוכן המקונן ממשיך אחרי שהמפעיל הסתיים הוא מדווח לשיחה הראשית.

משנים את התקרה ב-CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH. הערך 1 מכבה קינון. הערך 2 מאפשר שכבה שנייה שאינה מפעילה הלאה.

בטרמינל קלוד קוד מציג סוכנים מקוננים כעץ בפאנל שמתחת לקלט, ומסמן כל שורה שעדיין יש לה צאצאים בפאנל בספירת (+N). פתיחת שורה מציגה את האחים של הסוכן ואת הילדים הישירים, עם נתיב חזרה ל-main.

שתי תקרות נפרדות: עומק הקינון, ומספר סוכנים רצים במקביל. אין תקרה על סך הסוכנים לאורך הסשן. כברירת מחדל, כש-20 סוכנים רצים, הפעלה נוספת בכלי Agent נכשלת עם Concurrent subagent limit reached, והשגיאה אומרת לקלוד לא לנסות שוב. הפעלה מצליחה שוב כשהמספר יורד מתחת לתקרה. משנים ב-CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS לכל מספר שלם חיובי (דורש v2.1.217 ומעלה). סשן עם ultracode פעיל פטור. התקרה חוסמת רק הפעלה בכלי Agent. פיצול מתוך הסשן עם /subtask תופס מקום ואינו נחסם. המשך של סוכן שכבר הסתיים תופס מקום חדש בלי בדיקה, ולכן יכול לעבור את התקרה. סוכני תהליך עבודה וחברי צוות עוקבים אחרי תקרות משלהם.

כל הפעלה יוצרת מופע חדש. כדי להמשיך סוכן קיים מבקשים מקלוד להמשיך: הוא משתמש ב-SendMessage עם מזהה הסוכן או שמו בשדה to. סוכן שממשיכים אותו שומר את מלוא היסטוריית השיחה, כולל קריאות כלים, תוצאות והנמקה. אם הפעיל סוכני רקע משלו, ההיסטוריה כוללת גם את התוצאות שהם החזירו בזמן שרץ, והוא ממשיך מהמקום שבו עצר. לפני v2.1.304, סוכן שקלוד שלח לו הודעה או חידש אותו מיד אחרי שסיים יכול היה לשכוח את העבודה האחרונה שלו. SendMessage אינו דורש שצוותי סוכנים יהיו מופעלים. רק הודעות פרוטוקול צוות, כמו shutdown_request ו-plan_approval_response, דורשות זאת. בסשן עם העברת הודעות בין סשנים, אותו כלי מגיע גם לסשנים אחרים של קלוד קוד. Explore ו-Plan הם חד-פעמיים ואינם מחזירים מזהה, ולכן אי אפשר להמשיך אותם. כשמגיעים ל-maxTurns, הפלט מסומן כחלקי, ואם יש מזהה מצוין שאפשר לשלוח הודעה כדי להמשיך מהמקום שבו הסוכן עצר.

הודעה לסוכן שהסתיים, או שנעצר עם TaskStop אחרי שהריצה יצאה, ממשיכה אותו ברקע בלי קריאת Agent חדשה. הריצה שומרת את סט הכלים מהמקום שבו הסוכן רץ לראשונה, ויכולה להמשיך לקרוא את מטמון הפרומפט שהריצה המקורית חיממה. סוכן עם SendMessage יכול לשלוח את ההודעה בעצמו. בסשן אינטראקטיבי הסוכן המחודש מדווח לסוכן שחידש אותו, לא לשיחה הראשית, והסוכן המפעיל מחכה לתוצאה. הודעה לסוכן שאליו הוא מדווח, כמו המפעיל שלו, מחדשת את הסוכן בלי להפנות את התוצאות. סוכן שעצרתם בעצמכם עם x ב-/tasks, או בבקשת stop_task ב-SDK, אינו מתחדש אוטומטית: ההודעה נדחית וקלוד מקבל שהסוכן בוטל. כל עוד שורת הסוכן בפאנל, הקלדה בתמליל שלו מחדשת אותו בעצמכם, ואחרי זה הודעה מקלוד יכולה לחדש אותו שוב. חידוש מתחיל ריצה חדשה תחת אותו מזהה, ולכן סוכן שכבר נכשל או הסתיים מופיע שוב כרץ ברשימת המשימות ובאירועי המשימות של ה-Agent SDK.

SendMessage בודק ששם עדיין מצביע על אותו סוכן. אם סוכן חדש תפס את השם, למשל סוכן רקע שהופעל מחדש ושימש באותו שם, השליחה נדחית והשגיאה מציינת לאיזה סוכן השם מגיע עכשיו. כדי להגיע לסוכן הקודם כל עוד הוא רץ, פונים במזהה שהתקבל בהפעלה. הבדיקה חלה על השיחה הנוכחית ומתאפסת ב-/clear. הסוכן מתייחס להודעות מהסוכן שהפעיל אותו כהנחיית משימה, כולל תיקון כיוון באמצע משימה, בתוך הרשאותיו. אף הודעה מסוכן אינה אישור לבקשת הרשאה ממתינה, ואינה יכולה לשנות הרשאות, CLAUDE.md או תצורה. רק מערכת ההרשאות, או הודעות שלכם, יכולות לאשר.

אפשר גם לבקש מקלוד את מזהה הסוכן. המזהים נמצאים גם בתמלילים ב-~/.claude/projects/{project}/{sessionId}/subagents/, כל אחד בקובץ agent-{agentId}.jsonl. דחיסת השיחה הראשית אינה נוגעת בהם. הם נשמרים עם הסשן, ואפשר להמשיך סוכן אחרי הפעלה מחדש על ידי חידוש אותו סשן. קלוד קוד מוחק אותם אחרי cleanupPeriodDays, 30 יום כברירת מחדל.

אחרי הפעלה מחדש וחידוש הסשן, אם קלוד אינו מצליח לפנות לסוכן משנה לפי שם, נותנים לו את מזהה הסוכן. שמות שקלוד נתן מהשיחה הראשית מאז הדחיסה האחרונה שורדים את ההפעלה מחדש. שם שקדם לדחיסה הזו אינו שורד. כדי למצוא מזהה של שם, מחפשים את השם בקבצי agent-{agentId}.meta.json באותה תיקיית subagents. אחרי הודעה אחת לפי מזהה השם עובד שוב, אלא אם סוכן חדש יותר תפס אותו. לפני v2.1.299 אף שם לא שרד הפעלה מחדש, ושליחה לפי שם נדחתה גם כשהמזהה עדיין עבד. לסוכן שעלה כחבר צוות חלות במקום זה מגבלות צוותי הסוכנים.

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

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

כדי שסוכן אחד יידחס מוקדם יותר, מגדירים autoCompactWindow ב-frontmatter לספירת טוקנים מ-100000 עד 1000000 (דורש v2.1.296 ומעלה). אם CLAUDE_CODE_AUTO_COMPACT_WINDOW מוגדר, הסוכן משתמש בחלון של המשתנה והשדה אינו משפיע, אלא אם קלוד קוד מתעלם מערך המשתנה. כותבים מספר שלם רגיל, כמו 200000. ב-frontmatter הערך 200k נקרא כ-200, מחוץ לטווח המותר: הסוכן עדיין נטען ונדחס כאילו השדה לא קיים. כדי לבדוק אם הערך דולג, מריצים claude --debug ומחפשים בלוג הדיבוג invalid autoCompactWindow. אם הערך בטווח ועדיין אין שינוי, שני גורמים אפשריים: הערך אינו נמוך מחלון הדחיסה האוטומטית שהסוכן היה יורש, או שהסשן כולו רץ כסוכן הזה דרך --agent או הגדרת agent, ושם לשדה אין השפעה.

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

כשתשובת סוכן נחתכת באמצע הזרם, ויש בה טקסט בלי קריאות כלים, קלוד קוד מבקש מהסוכן להמשיך, גם בסשן אינטראקטיבי. הריצה מסתיימת על השגיאה רק אחרי שההמשכים נוצלו. סיום על שגיאת API, כמו מגבלת שימוש או שגיאת שרת חוזרת, מדווח לקלוד ככישלון ולא כממצאים של הסוכן. בחזית, אם מגבלת קצב, עומס או שגיאת שרת חותכים סוכן שכבר הפיק טקסט, כלי Agent מחזיר את הפלט החלקי עם הערה שהסוכן נחתך ולא סיים. סוכן שלא הפיק כלום, או שהפלט היחיד שלו היה קריאות כלים, נכשל עם Agent terminated early due to an API error ואחריו פירוט השגיאה. ברקע הסוכן מסומן ככושל, וההודעה שקלוד מקבל מציינת את שגיאת ה-API וכוללת את הפלט האחרון. אם הדוח נפתח בשורה ⚠ This agent switched to <model> because its earlier model could not be used., הסוכן סיים על מודל גיבוי. אם מוגדרת שרשרת מודל גיבוי והכישלון מכוסה בה, למשל מודל לא זמין, הסוכן עובר למודל הראשון בשרשרת שמקבל את הבקשה וממשיך לעבוד במקום לסיים על השגיאה. אחרי שהשגיאה חולפת, מבקשים מקלוד לנסות שוב או להמשיך את הסוכן.

לפני שקלוד קורא את הדוח הסופי, קלוד קוד סורק אותו. הסריקה אינה מוחקת ואינה מנסחת מחדש. היא מכניסה לוכסן הפוך לטקסט שמחקה פלט של קלוד קוד, כמו תג <system-reminder> או שורה שמתחילה ב-Human: או ב-Assistant:, ומוסיפה שורת סמן שמתחילה ב-[harness: subagent output matched instruction-shaped pattern(s): כשהדוח מחקה תג כזה או מזכיר הגדרות הרשאה כמו bypassPermissions או --dangerously-skip-permissions. אזכור הגדרת הרשאה מקבל את שורת הסמן, והטקסט עצמו נשאר. הסריקה אינה שופטת אם התוכן זדוני, וקריאת כלי שהדוח מוביל אליה עדיין עוברת את בדיקות ההרשאה ואת ארגז החול. הסריקה אינה תחליף להגבלת מה שסוכן המשנה יכול להגיע אליו. דוח שחוזר כתוצאת הסוכן מגיע תחת כותרת שמסמנת אותו כפלט סוכן משנה. הכותרת מציינת שהנחיות או טענות אישור בתוך הדוח הן מילים של סוכן המשנה, ואין להן סמכות מכם. דוח של סוכן ברקע מגיע בתוך התראת סיום, שמסומנת כאירוע אוטומטי.

#להעמקה

הגדרת סוכני משנה וכל שדות התצורה ובחירת סוג הסוכן.