👥 פרק 11

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

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

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

קלוד קוד מציע חמש דרכים לעבוד על מספר משימות במקביל: סוכני משנה (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 משלהם.
• העברת הודעות בין סשנים (cross-session messaging): מאפשרת לקלוד להציג ולשלוח הודעות לסשנים אחרים של קלוד קוד במכונה זו, במכונה אחרת, או ב-Claude Code on the web, כך שסשנים שאתם מריצים בעצמכם יכולים להעביר ממצאים וסטטוס ביניהם.
• פקודת /batch: מיומנות (skill) שגורמת לקלוד לפצל שינוי גדול ל-5 עד 30 סוכני משנה מבודדים ב-worktree שכל אחד מהם פותח pull request. זהו שימוש ארוז בסוכני משנה וב-worktrees, ולא סגנון תיאום נפרד.

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

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

• פקודת bash ברקע (background bash command): מריצה פקודת מעטפת אחת בלי לחסום את השיחה. אינה יוצרת סוכן.
• סוכן משנה מפוצל (forked subagent): סוכן משנה שיורש את מלוא הקשר השיחה שלכם במקום להתחיל מחדש. זו דרך להפעיל סוכן משנה, ולא משטח עבודה נפרד. מפעילים אותו באמצעות /subtask (דורש v2.1.212 ומעלה). קלוד גם מפעיל סוכן כזה בעצמו כאשר מצב fork mode מופעל. כדי להעתיק את כל הסשן לתוך סשן רקע חדש שרץ לצידו, משתמשים ב-/fork. כאשר תצוגת הסוכנים (agent view) כבויה, הפקודה לסוכן משנה מפוצל היא /fork במקום זאת, והפקודה /subtask אינה זמינה.
• שגרה (routine): מריצה סשן לפי לוח זמנים בענן, ולא במקביל במכונה המקומית.

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

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

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

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

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

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

#מה סוכני משנה נותנים

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

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

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

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

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

מגרסה v2.1.198, הסוכן Explore יורש את מודל השיחה הראשית במקום לרוץ תמיד על Haiku. ב-Claude API הירושה מוגבלת עד Opus, כך ש-Explore אינו רץ על מודל יקר יותר מזה שבחרתם לסשן: שיחה ראשית ברמת מודל גבוהה מריצה אותו על Opus, ושיחה על Sonnet או Haiku מריצה אותו על אותו מודל בדיוק. החריג: אם כופים את CLAUDE_CODE_SUBAGENT_MODEL על כל סוכני המשנה. בספקים אחרים (כמו Amazon Bedrock, Google Cloud Agent Platform, Microsoft Foundry, Claude Platform on AWS) הירושה היא ישירה, ללא תקרת Opus.

סוכן משתמש או פרויקט בשם 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 לנפילה חזרה.

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

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

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

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

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

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

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 שנוצרה תוך כדי עבודה.

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

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

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

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

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

יש לשמור על ערכי name ייחודיים בכל העץ: אם שני קבצים תחת אותה תיקיית agents מגדירים את אותו שם, קלוד קוד טוען רק אחד מהם לפי סדר קריאת מערכת הקבצים. בדיקת /doctor מדווחת על קבצים באותה תיקייה החולקים שם ומציעה לשנות שם או להסיר כפילויות (לפני גרסה v2.1.205 הוצג מסך אבחון נפרד).

בסוכני תוספים, תת-תיקייה הופכת לחלק מהמזהה המתוחם: קובץ בנתיב agents/review/security.md בתוסף my-plugin יירשם כמזהה my-plugin:review:security.

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

ב-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 עם שדה prompt (המקביל לגוף ה-Markdown) בתוספת שדות ה-frontmatter הנתמכים: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, omitClaudeMd, ו-isolation. כל מפתח ראשי ב-JSON הוא שם הסוכן. אסור להתחיל שם בתו מקף -.

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

סוכני תוספים (Plugin subagents): מגיעים מתוספים מותקנים. מטעמי אבטחה, סוכני תוספים אינם תומכים בשדות hooks, mcpServers או permissionMode, ומתעלמים מהם בעת הטעינה.

הגדרות סוכנים מכל ההיקפים הללו זמינות גם לחברי צוות ב-Agent Teams.

#כתיבת קובצי סוכנים והגבלות הרצה

קובץ סוכן כולל YAML frontmatter עבור הגדרות, ולאחריו פרומפט המערכת ב-Markdown:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

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

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

סוכן משנה מתחיל בתיקיית העבודה הנוכחית של השיחה הראשית. פקודות cd בתוך הסוכן אינן נשמרות בין קריאות כלי Bash או PowerShell ואינן משפיעות על השיחה הראשית.

כדי להעניק לסוכן עותק מבודד של המאגר, מגדירים isolation: worktree. סוכן כזה מריץ פקודות בתוך עץ עבודה נפרד. פקודה שתיקיית העבודה שלה פותרת ל-checkout הראשי (למשל אם עץ העבודה נמחק תוך כדי ריצה) נכשלת עם שגיאה (החל מגרסה v2.1.203). בדיקה זו מכסה את כל המאגר שממנו הופעל קלוד קוד (החל מגרסה v2.1.210).

בפקודות Bash, קלוד קוד בודק גם שפקודות אינן מנתבות את git חזרה ל-checkout הראשי ודוחה פקודות שלא ניתן לאמת בהן שהפעילות נשארת ב-worktree. פקודות Monitor עוברות את אותן בדיקות.

#שדות Frontmatter

להלן כל השדות הנתמכים ב-YAML frontmatter של קובץ סוכן משנה. רק name ו-description הם שדות חובה:

את שדה cacheTtl יש לכתוב בתוך המפה experimental ולא ברמת העל של ה-frontmatter:

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

#קובצי סוכנים שקלוד קוד מדלג עליהם

קלוד קוד מדלג על קובץ סוכן בדיסק בלי לדווח בסשן כאשר יש ב-frontmatter אחת מהבעיות הבאות:

• אין שדה name: הקובץ נחשב למסמך תיעוד שנשמר לצד הסוכנים.
• שורת --- הפותחת אינה השורה הראשונה בקובץ: הקובץ נחשב לחסר frontmatter ולתיעוד בלבד.
• שדה name שמתחיל בתו מקף - או מכיל נקודתיים :: הקובץ נפסל ונרשמת שגיאה ב-debug log.
• שדה name קיים אך חסר שדה description: הקובץ נפסל והסיבה נרשמת ב-debug log.
• תחביר ה-YAML אינו ניתן לפענוח (parse error): קלוד קוד מדלג על הקובץ ורושם שגיאה ב-debug log.

סוכן תוסף שאין לו name או שה-YAML שלו לא פוענח עדיין נטען, תחת שם הקובץ שלו.

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

#בחירת מודל

שדה model קובע באיזה מודל הסוכן ישתמש: כינוי מודל (sonnet, opus, haiku, fable), מזהה מודל מלא (כמו claude-opus-5), או inherit לשימוש במודל השיחה הראשית.

כאשר קלוד מזמן סוכן, הוא יכול גם להעביר פרמטר model להפעלה הספציפית הזו. קלוד קוד מכריע באיזה מודל להשתמש לפי הסדר הבא (עודכן בגרסה v2.1.251):

1. פרמטר model בהפעלה הנקודתית.
2. שדה model בהגדרת ה-frontmatter של הסוכן (כאשר inherit בוחר את מודל השיחה הראשית).
3. משתנה הסביבה CLAUDE_CODE_SUBAGENT_MODEL, כשהוא מוגדר לכינוי מודל או למזהה מודל.
4. מודל השיחה הראשית.

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

קלוד קוד בודק את ערכי המודל מול רשימת המודלים המורשים של הארגון (availableModels). אם הערך חסום:

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

פרמטר model מהפעלה נקודתית נשמר גם כאשר מחדשים את הסוכן או שולחים לו הודעת המשך (החל מגרסה v2.1.211). מגרסה v2.1.198 סוכני משנה יורשים גם את הגדרת החשיבה המורחבת (extended thinking) של השיחה הראשית: אם היא פעילה בסשן היא פעילה בסוכן, ואם היא כבויה היא נשארת כבויה.

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

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

• אם שני המשתנים מוגדרים, הסוכנים ירוצו על המודל שצוין ב-CLAUDE_CODE_SUBAGENT_MODEL.
• אם מוגדר רק CLAUDE_CODE_SUBAGENT_MODEL_FORCE, הסוכנים ירוצו על מודל השיחה הראשית.

דוגמה להגדרת כל סוכני המשנה על Haiku בקובץ ההגדרות:

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

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

#שליטה ביכולות וכלים

סוכני משנה יורשים את הכלים המובנים וכלי ה-MCP של השיחה הראשית, ומסוננים דרך שני מסננים:

1. מסנן ראשון (מסיר כלים מכל סוכן משנה, גם אם נרשמו ב-tools):

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

2. מסנן שני (חל על סוכני משנה הרצים ברקע, שהיא ברירת המחדל): סוכן רקע שומר על כל כלי ה-MCP, אך מתוך הכלים המובנים הוא שומר רק על: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, ו-Artifact, בתוספת SubagentHandback עבור סוכן משנה שמדווח דרכו. כל כלי מובנה אחר מוסר מסוכן הרקע. סוכן בחזית שהופעל בהפעלת cross-session messaging יורש גם את ListAgents, בעוד שסוכן ברקע אינו מקבל אותו. סוכנים מפוצלים (forks) מדלגים על שני המסננים ומקבלים את מאגר הכלים המדויק של השיחה הראשית. חברי צוות ב-Agent Teams שומרים בנוסף גם על כלי המשימות (TaskCreate, TaskGet, TaskList, TaskUpdate) וכלי cron (CronCreate, CronDelete, CronList).

להגבלת כלים משתמשים בשדה tools כרשימת היתרים (allowlist) או בשדה disallowedTools כרשימת חסימות (denylist):

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

אם שני השדות מוגדרים, disallowedTools מוחל תחילה, ולאחר מכן tools מסנן מתוך המאגר שנותר.

שני השדות תומכים בתבניות ברמת שרת MCP: תבנית mcp__<server> או mcp__<server>__* מעניקה או חוסמת את כל הכלים מאותו שרת. ב-disallowedTools, התבנית mcp__* חוסמת את כל כלי ה-MCP מכל השרתים:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

ערך ב-disallowedTools עם אפיון פקודה, כגון Bash(git push *), מסיר את כל כלי ה-Bash מהסוכן ולא רק את הפקודה התואמת. לחסימת פקודות ספציפיות תוך שמירה על הכלי, הוסיפו כלל חסימה תחת permissions.deny בהגדרות.

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

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

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

תחביר זה משמש כרשימת היתרים: רק סוכני worker ו-researcher יורשו לשיגור. תחביר זה של רשימת היתרים בתוך סוגריים פועל רק כאשר הסוכן רץ כשיחה הראשית דרך claude --agent. בתוך הגדרה של סוכן משנה רגיל, ציון Agent בשדה הכלים מאפשר לו לשגר סוכני משנה משלו (בכפוף למגבלת העומק), אך כל רשימת סוגים בתוך הסוגריים מקבלת התעלמות.

#הקצאת שרתי MCP לסוכן משנה

שדה mcpServers מעניק לסוכן גישה לשרתי MCP שאינם זמינים בשיחה הראשית. שרתים מוטבעים (inline) מתחברים בהפעלת הסוכן ומתנתקים בסיומו:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  
# הגדרה מוטבעת: מתוחמת לסוכן זה בלבד
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  
# הפניה בשם: שימוש חוזר בשרת קיים
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

הגדרת שרת MCP מוטבע מקובץ סוכן בתיקיית פרויקט או בתיקייה שנוספה עם --add-dir נטענת רק לאחר אישור אמון בתיקייה (trust folder). ללא אישור אמון, קלוד קוד מדלג על שרתים מוטבעים אלה ורושם שגיאה ב-debug log (החל מגרסה v2.1.238). שרתים המופנים בשם, שרתים ב-~/.claude/agents/, ושרתים המועברים דרך --agents נטענים ללא בדיקת אמון בתיקייה.

כמו כן, הגבלות MCP החלות על השיחה הראשית חלות גם על שרתי MCP המוצהרים ב-frontmatter של סוכן משנה: --strict-mcp-config, --bare, תצורת MCP ארגונית מנוהלת, ומדיניות allowedMcpServers ו-deniedMcpServers (החל מגרסה v2.1.153).

#מצבי הרשאות

שדה permissionMode קובע את מצב ההרשאות שבו הסוכן ירוץ: default (או manual, החל מ-v2.1.200), acceptEdits, auto, dontAsk, bypassPermissions, או plan. בהשמטה, הסוכן יורש את מצב השיחה הראשית.

מצב השיחה הראשית קובע האם הערך שהגדרתם ייושם:

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

#טעינת מיומנויות מראש (Skills)

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

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

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

#הפעלת זיכרון מתמיד (Persistent memory)

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

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

זיכרון הסוכן תלוי בתכונת auto memory: אם היא מנוטרלת באמצעות הגדרת autoMemoryEnabled או המשתנה CLAUDE_CODE_DISABLE_AUTO_MEMORY, שדה memory מושבת.

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

טיפים לשימוש בזיכרון מתמיד:

• מומלץ להשתמש ב-project כברירת מחדל כדי לאפשר שיתוף ידע בצוות דרך בקרת גרסאות.
• בקשו מהסוכן לבדוק את הזיכרון שלו לפני תחילת עבודה: "Review this PR, and check your memory for patterns you've seen before."
• בקשו מהסוכן לעדכן את הזיכרון בסיום משימה: "Now that you're done, save what you learned to your memory."
• כללו הנחיות זיכרון ישירות בגוף קובץ הסוכן:

Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

#חוקים מותנים באמצעות הוקים (Hooks)

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

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

קלוד קוד מעביר את קלט הכלי כ-JSON ב-stdin. סקריפט הבדיקה קורא את ה-JSON, מוציא את הפקודה, ויוצא בקוד יציאה 2 כדי לחסום את הפעולה:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

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

# חסימת פעולות כתיבה ב-SQL
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

יש להעניק הרשאות הרצה לסקריפט:

chmod +x ./scripts/validate-readonly-query.sh

ב-Windows, כותבים את סקריפט האימות ב-PowerShell ומוסיפים shell: powershell להגדרת ההוק.

#השבתת סוכני משנה ספציפיים

ניתן למנוע מקלוד להשתמש בסוכנים ספציפיים על ידי הוספתם למערך deny בהגדרות ההרשאות בפורמט Agent(subagent-name):

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

ניתן לחסום סוכן גם דרך דגל ה-CLI:

claude --disallowedTools "Agent(Explore)"

#הגדרת הוקים לסוכני משנה

ניתן להגדיר הוקים בשני מקומות:

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

הוקים מקובץ סוכן בתיקיית פרויקט דורשים אישור אמון בתיקייה (trust workspace dialog). עד לאישור, הסוכן ירוץ אך ההוקים ייפסלו (החל מגרסה v2.1.218).

אירועים נפוצים ב-frontmatter:

דוגמה להוקים ב-frontmatter של סוכן:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

אירועים נפוצים ברמת הפרויקט ב-settings.json:

דוגמה להגדרה ב-settings.json:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

ערך עם מקף כמו db-agent מותאם באופן מדויק החל מגרסה v2.1.195. בסוכני תוספים המזהה כולל נקודתיים (למשל my-plugin:db-agent), ולכן נבדק כביטוי רגולרי לא מעוגן; יש לעגנו עם ^ ו-$ כדי להתאים בדיוק לאותו סוכן (^my-plugin:db-agent$).

#עבודה עם סוכני משנה

#הפעלה מפורשת של סוכני משנה

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

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

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

• תיוג @: מבטיח שהסוכן המבוקש יופעל למשימה הנוכחית:

@"code-reviewer (agent)" look at the auth changes

ניתן גם להקליד ידנית @agent-<name> עבור סוכנים מקומיים, או @agent-my-plugin:code-reviewer עבור סוכני תוספים. סוכני רקע בעלי שם שרצים כעת מופיעים גם הם בתפריט ההשלמה לצד הסטטוס שלהם.

• הרצת הסשן כולו תחת סוכן משנה: באמצעות הדגל --agent <name>, הסשן כולו מאמץ את פרומפט המערכת, הגבלות הכלים והמודל של אותו סוכן:

claude --agent code-reviewer

להגדרת סוכן כברירת מחדל לכל סשן בפרויקט, הגדירו ב-.claude/settings.json:

{
  "agent": "code-reviewer"
}

#הרצה בחזית או ברקע

• סוכני חזית (Foreground): חוסמים את השיחה הראשית עד לסיום הריצה. בקשות הרשאה מוצגות ישירות בזמן אמת.
• סוכני רקע (Background): רצים במקביל בזמן שאתם ממשיכים לעבוד. כשהסוכן נתקל בקריאת כלי הדורשת אישור, קלוד קוד מקפיץ את בקשת ההרשאה בשיחה הראשית ומציין את שם הסוכן המבקש. אישור מאפשר לסוכן להמשיך, ומקש Esc דוחה את קריאת הכלי הזו בלבד בלי לעצור את הסוכן (החל מגרסה v2.1.186). מתן אישור שתקף לכל הסשן יחול על הסשן כולו, כולל השיחה הראשית.

כללי בחירת הרצה בחזית או ברקע:

• סוכן משנה ששוגר על ידי חבר צוות ב-Agent Teams רץ בחזית (קלוד קוד דוחה הגדרת background: true).
• אם הוגדר CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1, סוכנים ירוצו תמיד בחזית.
• כאשר מצב fork mode פועל (ברירת מחדל בסשן אינטראקטיבי), קלוד קוד מריץ סוכנים ברקע וקלוד אינו יכול לבקש חזית.
• כאשר fork mode כבוי (במצב headless עם -p וב-Agent SDK), קלוד מריץ סוכנים ברקע כברירת מחדל ובחזית אם הוא זקוק לתוצאה לפני המשך העבודה. הגדרת background: true ב-frontmatter משאירה את הסוכן ברקע תמיד.
• ניתן ללחוץ Ctrl+B כדי להעביר משימה שרצה כעת לרקע.

ניקוי שורות מחלונית הסוכנים:

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

#שמות סוכני משנה

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

בסשן אינטראקטיבי שבו מופעלת התכונה Agent Teams, סוכן בעל שם ששוגר מהשיחה הראשית יושק כחבר צוות (teammate) אלא אם הקריאה היא מסוג fork או שהועבר פרמטר isolation בקריאה עצמה.

#שגיאות API וקטיעות

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

החל מגרסה v2.1.199, סוכן שהריצה שלו מסתיימת בשגיאת API (כמו חריגה ממגבלת שימוש או שגיאת שרת חוזרת) מדווח על הכשל לקלוד במקום להחזיר את טקסט השגיאה כאילו היה ממצא של הסוכן:

• בחזית: אם הסוכן כבר ייצר פלט טקסטואלי, הכלי מחזיר את הפלט החלקי בליווי הערה שהסוכן נקטע. אם לא ייצר פלט או שייצר רק קריאות כלים, הפעולה נכשלת עם השגיאה Agent terminated early due to an API error.
• ברקע: הסוכן מסומן כנכשל, וההודעה שקלוד מקבל כוללת את שגיאת ה-API ואת הפלט האחרון של הסוכן.

אם מוגדרת שרשרת מודלים חלופיים (fallback model chain), קלוד קוד מעביר את הסוכן למודל הבא בשרשרת שמקבל את הבקשה.

#סריקת פלט של סוכני משנה

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

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

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

#דפוסים נפוצים ובחירה בין סוכן לשיחה הראשית

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

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

Use a subagent to run the test suite and report only the failing tests with their error messages

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

Research the authentication, database, and API modules in parallel using separate subagents

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

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

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

עקרונות מנחים מומלצים (Best practices):

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

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

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

#סוכני משנה מקוננים ומגבלות ריצה

#סוכני משנה מקוננים

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

לשינוי מגבלת העומק, הגדירו את משתנה הסביבה CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

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

#מגבלת סוכנים מקבילים

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

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

#ניהול הקשר וחידוש סוכני משנה

#מה נטען בהפעלת סוכן

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

• פרומפט מערכת: הפרומפט שמוגדר בקובץ הסוכן בתוספת פרטי סביבה בסיסיים שקלוד קוד מצרף, ולא פרומפט המערכת של קלוד קוד.
• הודעת המשימה: הודעת ההאצלה שקלוד מנסח בעת העברת המשימה.
• קובצי CLAUDE.md: כל רמה בהיררכיית CLAUDE.md שהשיחה הראשית טוענת, כולל ~/.claude/CLAUDE.md, כללי פרויקט, CLAUDE.local.md, וקובצי מדיניות מנוהלים. הסוכנים המובנים Explore ו-Plan מדלגים על כך. סוכן משנה שהגדרתו כוללת omitClaudeMd: true טוען רק את קובצי המדיניות המנוהלים, או אף קובץ כזה אם ההגדרה מגיעה מהגדרות מנוהלות (דורש v2.1.271 ומעלה). ב---agent או בהגדרת agent, קובצי CLAUDE.md נטענים כרגיל גם אם הוגדר omitClaudeMd.
• סטטוס Git: תמונת מצב מתחילת סשן האב. אינו מופיע כאשר התיקייה אינה מאגר Git או כאשר includeGitInstructions מוגדר ל-false. הסוכנים Explore ו-Plan מדלגים עליו בכל מקרה.
• מיומנויות טעונות מראש: תוכן מלא של כל מיומנות שנרשמה בשדה skills.
• רשימת עמיתים (Sibling roster): תזכורת מערכת המפרטת את main וכל סוכן בעל שם בסשן, ככתובות חוקיות עבור SendMessage (דורש v2.1.206 ומעלה, וקיום כלי SendMessage).

מה שלעולם אינו נטען בסוכן שאינו מפוצל:

• סגנון פלט (Output style): סגנון השיחה הראשית אינו חל על הסוכן.
• זיכרון אוטומטי (Auto memory): הזיכרון האוטומטי של השיחה הראשית אינו נטען (יש להשתמש בשדה memory להפעלת זיכרון לסוכן).
• גודל חלון ההקשר: נקבע לפי המודל של הסוכן ולא של סשן האב.

#חידוש סוכני משנה (Resume)

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

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

• סוכני Explore ו-Plan הם חד-פעמיים ואינם מחזירים מזהה סוכן, ולכן לא ניתן לחדש אותם.
• סוכן שעצר בשל מגבלת maxTurns מחזיר פלט חלקי שניתן להמשיך.
• קלוד משתמש בכלי SendMessage עם מזהה הסוכן או שמו כדי לחדש אותו. הסוכן מתחדש ברקע ללא קריאת Agent חדשה.
• סוכן שעצרתם בעצמכם (באמצעות x ב-/tasks או ב-SDK) אינו מתחדש אוטומטית. כדי לחדש אותו בעצמכם, הקלידו לתוך חלון התמליל שלו כל עוד השורה שלו קיימת בחלונית (החל מגרסה v2.1.191).
• סוכן שחודש מציג שוב סטטוס פעיל ב-/tasks (החל מגרסה v2.1.205).
• כלי SendMessage מאמת שהשם עדיין שייך לאותו סוכן ולא נתפס על ידי סוכן רקע חדש (החל מגרסה v2.1.199).
• סוכן מתייחס להודעות מהסוכן ששיגר אותו כהנחיות עבודה רגילות (החל מגרסה v2.1.198), אך הודעות אלה אינן יכולות לאשר הרשאות במקומכם או לשנות את הגדרות הסוכן.

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

#דחיסה אוטומטית (Auto-compaction)

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

#פיצול השיחה הנוכחית (Forking)

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

מפעילים סוכן מפוצל באמצעות הפקודה /subtask ואחריה תיאור המשימה (דורש v2.1.212 ומעלה):

/subtask draft unit tests for the parser changes so far

כאשר תצוגת הסוכנים (agent view) כבויה, הפקודה להפעלת סוכן מפוצל היא /fork.

#השוואה בין סוכן מפוצל לסוכן רגיל

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

#ניטור ושליטה בסוכנים מפוצלים בחלונית

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

כאשר תמליל סוכן פתוח, הודעות המשך נשלחות אליו, אך פקודות מערכת רצות בשיחה הראשית. הקלדת /model או /fast בתצוגה זו מציגה התראה שהשינוי חל על השיחה הראשית ולא על הסוכן המוצג (החל מגרסה v2.1.199).

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

#הפעלה וכיבוי של Fork mode

בסשן אינטראקטיבי מצב fork mode פועל כברירת מחדל (החל מגרסה v2.1.232). במצב לא אינטראקטיבי וב-Agent SDK הוא כבוי כברירת מחדל.

להגדרה ידנית, השתמשו במשתנה הסביבה CLAUDE_CODE_FORK_SUBAGENT:

• ערך 1: מפעיל את fork mode גם במצב לא אינטראקטיבי וב-SDK.
• ערך 0: מכבה את fork mode בכל סוגי הסשנים.

כדי להשאיר את fork mode פעיל אך למנוע מקלוד לפצל סוכנים, חסמו את סוג הסוכן באמצעות כלל Agent(fork) תחת permissions.deny.

#דוגמאות לסוכני משנה מותאמים

#סוקר קוד (Code reviewer)

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

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

#מאתר באגים (Debugger)

סוכן שמנתח שגיאות ומתקן אותן בקוד, כולל כלי Edit:

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

#מדען נתונים (Data scientist)

סוכן ייעודי לניתוח נתונים, שאילתות SQL וכלי bq:

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

#בודק שאילתות מסד נתונים (Database query validator)

סוכן המריץ שאילתות קריאה בלבד באמצעות הוק PreToolUse שחוסם פעולות כתיבה:

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

סקריפט האימות בנתיב ./scripts/validate-readonly-query.sh:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

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

if [ -z "$COMMAND" ]; then
  exit 0
fi

# חסימת פעולות כתיבה ויציאה בקוד 2
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

הענקת הרשאות הרצה לסקריפט:

chmod +x ./scripts/validate-readonly-query.sh