📘 תיעוד 41

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

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

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

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

[!NOTE]

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

סוכני משנה עוזרים לך:

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

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

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

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

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

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

#Explore

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

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

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

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

כשמפעילים את Explore, Claude מציין רמת יסודיות: quick לחיפושים ממוקדים, medium לחקירה מאוזנת, או very thorough לניתוח מקיף.

#Plan

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

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

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

#General-purpose

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

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

Claude מאציל ל-general-purpose כשהמשימה דורשת גם חקירה וגם שינוי, חשיבה מורכבת כדי לפרש תוצאות, או כמה שלבים תלויים.

#אחר

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

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

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

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

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

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

סוכני משנה הם קבצי Markdown עם frontmatter של YAML. כדי ליצור אחד, בקש מ-Claude לכתוב אותו עבורך, או כתוב את הקובץ בעצמך.

ההדרכה הזו יוצרת סוכן משנה ברמת המשתמש שסוקר קוד ומציע שיפורים.

1. בקש מ-Claude ליצור את סוכן המשנה

ב-Claude Code, תאר את סוכן המשנה שאתה רוצה ואיפה לשמור אותו:

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.

Claude כותב את הקובץ עם name, description, רשימת tools, model והנחיית מערכת.

2. בדוק את הקובץ

פתח את ~/.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. נסה אותו

בקש מ-Claude לאציל לסוכן המשנה החדש:

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

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

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

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

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

[!NOTE]

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

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

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

#בחירת היקף תת-הסוכן

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

תת-סוכני פרויקט (.claude/agents/) מתאימים לתת-סוכנים שמיועדים לבסיס קוד מסוים. הכניסו אותם לבקרת גרסאות כדי שהצוות יוכל להשתמש בהם ולשפר אותם בשיתוף פעולה.

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

כשמוסיפים תיקייה עם --add-dir או /add-dir, Claude Code טוען גם את תיקיית .claude/agents/ שלה, לצד תת-סוכני הפרויקט. ראו תיקיות נוספות כדי לדעת אילו סוגי תצורה נוספים נטענים מ---add-dir. כדי לשתף תת-סוכנים בין פרויקטים בלי --add-dir, השתמשו ב-~/.claude/agents/ או ב-תוסף.

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

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

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

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

תת-סוכנים שמוגדרים ב-CLI מועברים כ-JSON בעת הפעלת Claude Code. הם קיימים רק לאותו סשן ואינם נשמרים לדיסק, ולכן הם שימושיים לבדיקה מהירה או לסקריפטים של אוטומציה. אפשר להגדיר כמה תת-סוכנים בקריאה אחת של --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" קורא את ההגדרות מהקובץ הזה. בסשן אינטראקטיבי, Claude Code מסרב לנתיב קובץ. צורת הקובץ דורשת Claude Code v2.1.281 או גרסה מאוחרת יותר.

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

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

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

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

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

[!NOTE]

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

אם אתם מחברי התוסף, שלחו את ה-hooks ב-hooks/hooks.json של התוסף, ואת שרתי ה-MCP ב-.mcp.json שלו. הם חלים בכל פעם שהתוסף מופעל, ולא רק בתוך תת-הסוכן.

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

#כתיבת קבצי תת-סוכן

קובצי תת-סוכן משתמשים ב-frontmatter של YAML לתצורה, ואחריו הנחיית המערכת ב-Markdown:

[!NOTE]

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

שלושה מקרים עדיין דורשים הפעלה מחדש:

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

---
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.

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

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

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

תת-סוכן עם isolation: worktree מריץ את פקודות ה-Bash וה-PowerShell שלו בתוך ה-worktree שלו. פקודה שתיקיית העבודה שלה מגיעה ל-checkout הראשי שלכם, למשל כי תיקיית ה-worktree הוסרה בזמן שתת-הסוכן רץ, נכשלת עם שגיאה.

בדיקת תיקיית העבודה הזו מכסה את כל המאגר שמכיל את התיקייה שממנה הפעלתם את Claude Code. כשהסשן שלכם רץ ב-worktree מקושר משלו, הבדיקה מכסה גם את ה-checkout הראשי שאליו ה-worktree מקושר.

לפקודות Bash, Claude Code בודק גם את הפקודה עצמה בשתי דרכים:

• הוא חוסם פקודה שמפנה את git אל ה-checkout הראשי.
• הוא מסרב לפקודה כשאי אפשר לאמת מטקסט הפקודה שכל git שהפקודה מריצה נשאר בתוך ה-worktree, למשל כששם הפקודה מחושב בזמן ריצה.

וקטורי ההפניה וכללי הצורה מפורטים תחת איך Claude Code אוכף בידוד. פקודות PowerShell מקבלות רק את בדיקת תיקיית העבודה.

פקודות Monitor עוברות את אותן בדיקות של תיקיית עבודה ותוכן פקודה כמו פקודות Bash.

כשהשיחה הראשית עצמה רצה מבודדת ב-worktree, Claude Code מחיל את אותן בדיקות על הסשן ועל כל תת-סוכן שהוא יוצר, כולל תת-סוכנים בלי isolation: worktree. ראו איך Claude Code אוכף בידוד.

#הפניה ל-frontmatter

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

שמות שדות בני כמה מילים משתמשים ב-camelCase, כמו maxTurns ו-disallowedTools, וחייבים להתאים לטבלה בדיוק: Claude Code מתעלם משדה שהוא לא מזהה בלי לדווח על שגיאה.

• כדי למצוא שדה עם שגיאת כתיב בסוכן משנה שנטען, הרץ claude --debug במעטפת וחפש ביומן הדיבוג ב-~/.claude/debug/<session-id>.txt את does not recognize or apply. יומן הדיבוג מציין עד חמישה שדות ברמה העליונה בקובץ של סוכן המשנה ש-Claude Code לא מזהה, עם השם הסביר המיועד כששדה נתמך קרוב. דורש Claude Code v2.1.296 או חדש יותר.
• כדי לברר למה קובץ של סוכן משנה לא נטען, ראה קבצי סוכני משנה ש-Claude Code מדלג עליהם.

כתוב את cacheTtl בתוך המפה experimental, לא ברמה העליונה של ה-frontmatter.

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

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

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

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

כדי לראות את יומן הדיבוג, הרץ את Claude Code עם --debug.

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

#בדיקת ספריית agents לפני הפעלה

כדי למצוא קבצים בספריית agents שה-frontmatter שלהם לא מתפרש, הרץ claude plugin validate מול הספרייה, למשל .claude/agents או ~/.claude/agents. Claude Code בודק רק את הספרייה שאתה מציין, ולא מסמן קובץ שה-frontmatter שלו מתפרש אבל אין לו name. דורש Claude Code v2.1.233 או חדש יותר.

#בחירת מודל

השדה model קובע באיזה מודל סוכן המשנה משתמש:

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

כש-Claude מפעיל סוכן משנה, הוא יכול גם להעביר פרמטר model להפעלה הספציפית הזאת. בקריאת כלי Agent, הפרמטר הזה מקבל כינוי מודל: sonnet, opus, haiku, או fable. Claude לא יכול להעביר מזהה מודל מלא או inherit בקריאה הזאת. Claude Code פותר את המודל של סוכן המשנה בסדר הזה:

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

אם mod מותקן מגדיר מודל ב-hook agent.spawn שלו, Claude Code משתמש במודל הזה במקום פרמטר ההפעלה.

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

• המודל של השיחה הראשית שייך למשפחה הזאת: סוכן המשנה רץ על המודל המדויק של השיחה הראשית, כולל סיומת [1m] אם יש, כך שהוא מקבל את אותו חלון הקשר מורחב כמו השיחה הראשית.
• Claude Code לא יכול לזהות את משפחת המודל של השיחה הראשית, אצל ספק שאינו Anthropic API: זה יכול לקרות עם ARN של פרופיל הסקה של יישום ב-Amazon Bedrock ש-Claude Code לא פתר למודל תומך. המקרה הזה מכסה רק את הכינוי opus, ולא חל כשמגדירים ANTHROPIC_DEFAULT_OPUS_MODEL, כי אז opus מתפרש למודל שהגדרת.

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

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

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

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

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

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

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

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

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

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

CLAUDE_CODE_SUBAGENT_MODEL הוא ברירת מחדל, כך שהגדרת סוכן משנה או מודל ש-Claude מעביר עדיין קודמים לו. כדי להחיל מודל אחד על כל סוכן משנה, חבר צוות, וסוכן workflow, הגדר גם את CLAUDE_CODE_SUBAGENT_MODEL_FORCE ל-1. דורש Claude Code v2.1.257 או חדש יותר.

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

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

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

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

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

• fork
• skill שרץ בסוכן משנה עם model: inherit

#בחירת רמת מאמץ

כדי להריץ סוכן משנה ברמת מאמץ משלו, הגדר את השדה effort בהגדרה שלו.

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

#כשלסוכן משנה אין שדה או פרמטר effort

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

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

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

#כלים זמינים

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

• Agent, כשסוכן המשנה נמצא במגבלת העומק. בפיצול הכלי נשאר ברשימה אבל מחזיר שגיאה במקום להפעיל סוכן משנה
• AskUserQuestion
• EndConversation, שיכול לסיים רק את השיחה הראשית. ראה התנהגות כלי 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 לסוכן משנה שמדווח דרכו. Claude Code מסיר כל כלי מובנה אחר מסוכן משנה ברקע, בין אם בירושה ובין אם רשום בשדה tools, כך שאותה הגדרה יכולה להיפתר לכלים שונים בחזית וברקע. ההסרה לא מדווחת על שגיאה אלא אם היא משאירה את רשימת tools נפתרת לכלום.

לפני v2.1.280, סוכני משנה ברקע לא יכלו להשתמש ב-LSP.

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

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

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

כדי להגביל כלים, השתמש בשדה tools כרשימת היתר או בשדה disallowedTools כרשימת חסימה. אם שניהם מוגדרים, disallowedTools מוחל קודם, ואז tools נפתר מול המאגר שנותר. כלי שרשום בשניהם מוסר.

הדוגמה הזו משתמשת ב-tools כדי להתיר רק את Read, Grep, Glob ו-Bash. סוכן המשנה לא יכול לערוך קבצים, לכתוב קבצים או להשתמש בכלי MCP:

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

הדוגמה הזו משתמשת ב-disallowedTools כדי לרשת את מאגר הכלים של סוכן המשנה מלבד Write ו-Edit. סוכן המשנה שומר את Bash, כלי MCP ואת שאר המאגר שלו:

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

כששום דבר ברשימת tools לא נפתר לכלי, למשל כי כל רשומה שגויה באיות או מציינת כלי שלא זמין לסוכני משנה, Claude Code בדרך כלל מסרב להפעיל את סוכן המשנה וכלי ה-Agent מחזיר שגיאה שמציינת את הרשומות שלא נפתרו. ראה Agent would be spawned with zero tools להודעה ולאופן תיקון כל רשומה.

שדות tools ו-disallowedTools מקבלים גם רשומות לשרת MCP שלם:

הדוגמה הזו מסירה כל כלי משרת ה-MCP github ושומרת כלים משרתים אחרים ואת הכלים המובנים במאגר של סוכן המשנה:

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

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

#שמות שרתי MCP שמכילים קו תחתון כפול

אם סוכן משנה לא מקבל אף אחד מהכלים משרת 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(agent_type) בשדה tools.

[!NOTE]

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

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

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

כדי לאפשר הפעלת כל סוכן משנה בלי הגבלות, השתמש ב-Agent בלי סוגריים:

tools: Agent, Read, Bash

אם משמיטים את Agent מרשימת tools לגמרי, הסוכן לא יכול להפעיל שום סוכן משנה עם כלי ה-Agent.

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

#תיחום שרתי MCP לסוכן משנה

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

[!NOTE]

השדה mcpServers חל בשני ההקשרים שבהם קובץ סוכן יכול לרוץ:

• כסוכן משנה, שמופעל דרך כלי ה-Agent או דרך אזכור @
• כסשן הראשי, שמופעל עם --agent או עם הגדרת agent

כשהסוכן הוא הסשן הראשי, הגדרות שרת מוטבעות מתחברות בהפעלה לצד שרתים מ-.mcp.json ומקובצי הגדרות, לפי אותו כלל אמון של תיקיית קובץ הסוכן. ב-/mcp, שרת מרוחק (HTTP או SSE) שכבר השתמשת בו יכול להציג את סטטוס cached. Claude Code מחבר אותו כש-Claude קורא לראשונה לאחד הכלים שלו.

כל רשומה ברשימה היא או הגדרת שרת מוטבעת או מחרוזת שמפנה לשרת MCP שכבר מוגדר בסשן שלך:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

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

הגדרות מוטבעות משתמשות באותה סכמה כמו רשומות שרת ב-.mcp.json, ממופתחות לפי שם השרת, ותומכות בסוגים stdio, http, sse ו-ws.

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

הגבלות ה-MCP שחלות על הסשן הראשי מכסות גם שרתים שמוצהרים ב-frontmatter של סוכן משנה:

• --strict-mcp-config ו---bare
• תצורת MCP מנוהלת ארגונית
• מדיניות allowedMcpServers ו-deniedMcpServers

כשאחד מאלה חוסם שרת, Claude Code מדלג עליו ומציג אזהרה שמציינת את השרתים החסומים.

הגבלות של הגדרות מנוהלות חלות על כל סוכן משנה, בלי קשר לאופן ההגדרה שלו. --strict-mcp-config לא מסנן שרתים שאתה מעביר באופן מוטבע דרך --agents או דרך אפשרות agents של ה-SDK, כי אלה קלט מפורש של הקורא.

#אמון נדרש לשרתי MCP מוטבעים

Claude Code טוען שרת MCP מוטבע מקובץ סוכן בתיקיית .claude/agents/ של הפרויקט שלך, או ב-.claude/agents/ של תיקיית --add-dir, רק אחרי שאתה נותן אמון בתיקייה שממנה הגיע קובץ הסוכן. לפני v2.1.238, Claude Code טען את השרתים האלה בלי לבדוק אמון.

• אמון שלא נספר: אמון של תיקיית הורה, והאמון האוטומטי שסשן -p או סשן SDK מקבל עבור hooks בקובצי הגדרות
• עד אז: Claude Code מדלג על כל שרת מוטבע בקובץ הסוכן הזה וכותב את המפתח המדויק projects["<path>"].hasTrustDialogAccepted עבור ~/.claude.json אל יומן ניפוי השגיאות
• תיקיות --add-dir: תיקייה מחוץ למאגר של סביבת העבודה המהימנה שלך צריכה רשומת אמון משלה, כי קובצי .claude/agents/ שלה לא יורשים את האמון של סביבת העבודה שלך

Claude Code טוען שני סוגים של שרת בלי לבדוק אמון בתיקייה שממנה הגיע קובץ הסוכן:

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

#מצבי הרשאה

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

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

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

permissionMode מקבל את הערכים האלה, ואת manual ככינוי ל-default:

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

השתמש בשדה 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.

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

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

אם מיומנות ברשימה חסרה או מושבתת, למשל לפי מדיניות הארגון שלך, Claude Code מדלג עליה ורושם אזהרה ביומן ניפוי השגיאות.

[!NOTE]

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

#הפעלת זיכרון מתמשך

השדה 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.

בחרו היקף לפי כמה רחב הזיכרון צריך לחול:

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

כשזיכרון מופעל:

• הנחיית המערכת של סוכן המשנה כוללת הוראות לקריאה ולכתיבה לתיקיית הזיכרון.
• הנחיית המערכת של סוכן המשנה כוללת גם את 200 השורות הראשונות או 25KB מתוך MEMORY.md בתיקיית הזיכרון, המוקדם מביניהם, עם הוראות לאצור את 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." לאורך זמן זה בונה בסיס ידע שהופך את סוכן המשנה ליעיל יותר.

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

  העתק

  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

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

הדוגמה הזו יוצרת סוכן משנה שמאפשר רק שאילתות מסד נתונים לקריאה בלבד. ה-hook מסוג PreToolUse מריץ את הסקריפט שמוגדר ב-command לפני שכל פקודת Bash רצה:

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

Claude Code מעביר קלט hook כ-JSON דרך stdin לפקודות hook. סקריפט האימות קורא את ה-JSON הזה, מחלץ את פקודת ה-Bash, ויוצא עם קוד 2 כדי לחסום פעולות כתיבה:

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

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

# Block SQL write operations (case-insensitive)
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

ב-macOS וב-Linux, הפכו את הסקריפט לבר הרצה, אחרת ה-hook נכשל במקום לחסום משהו:

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

כדי לבדוק את הכלל, בקשו מסוכן המשנה להריץ משפט UPDATE: הסקריפט יוצא עם קוד 2, Claude Code חוסם את הפקודה, וסוכן המשנה רואה את ההודעה Blocked: Only SELECT queries are allowed.

ראו קלט Hook לסכמת הקלט המלאה וקודי יציאה לאופן שבו קודי יציאה משפיעים על ההתנהגות. ב-Windows, כתבו סקריפטי hook ב-PowerShell והוסיפו shell: powershell לרשומת ה-hook כמו שמוצג בהרצת hooks ב-PowerShell.

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

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

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

זה עובד גם לסוכני משנה מובנים וגם למותאמים אישית. אפשר גם להשתמש בדגל ה-CLI --disallowedTools:

claude --disallowedTools "Agent(Explore)"

ראו תיעוד הרשאות לפרטים נוספים על כללי הרשאות.

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

סוכני משנה יכולים להגדיר hooks שרצים במהלך מחזור החיים של סוכן המשנה. יש שתי דרכים להגדיר hooks:

• ב-frontmatter של סוכן המשנה: הגדירו hooks שרצים רק בזמן שסוכן המשנה הזה פעיל
• ב-settings.json: הגדירו hooks לכל הסשן שמופעלים גם בתוך סוכני משנה. אירועי כלים כמו PreToolUse ו-PostToolUse מופעלים לקריאות הכלים של סוכן המשנה באותו אופן כמו בשיחה הראשית, ו-SubagentStart ו-SubagentStop מופעלים כשסוכן משנה מתחיל או מסיים

Hooks מקבצי הגדרות, הגדרות מדיניות מנוהלות ותוספים חלים כולם בתוך סוכני משנה, כך ש-hook מסוג PreToolUse ב-settings.json רץ גם לפני כל כלי שסוכן משנה משתמש בו.

#Hooks ב-frontmatter של סוכן משנה

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

[!NOTE]

Hooks ב-frontmatter מופעלים כשהסוכן מופעל כסוכן משנה דרך כלי ה-Agent או אזכור @, וכשהסוכן רץ כסשן הראשי דרך --agent או ההגדרה agent. במקרה של הסשן הראשי הם רצים לצד כל hooks שמוגדרים ב-settings.json.

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

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

כל אירועי ה-hook נתמכים. האירועים הנפוצים ביותר לסוכני משנה הם:

הדוגמה הזו מאמתת פקודות Bash עם ה-hook PreToolUse ומריצה linter אחרי עריכות קבצים עם PostToolUse:

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

כשהסוכן מופעל כסוכן משנה, hooks מסוג Stop ב-frontmatter מומרים אוטומטית לאירועי SubagentStop.

#Hooks ברמת הפרויקט לאירועי סוכן משנה

הגדירו hooks ב-settings.json שמגיבים לאירועי מחזור חיים של סוכן משנה בסשן הראשי.

שני האירועים תומכים ב-matchers כדי לכוון לסוגי סוכנים ספציפיים לפי שם. ערך ה-matcher הוא ה-name ב-frontmatter של הסוכן לסוכני משנה ברמת הפרויקט וברמת המשתמש, או המזהה בהיקף התוסף כמו my-plugin:db-agent לסוכני משנה מתוסף. שם בהיקף מכיל נקודתיים, ולכן הוא מוערך כביטוי רגולרי לא מעוגן; עגנו אותו עם ^ ו-$, כמו ב-^my-plugin:db-agent$, כדי להתאים רק לסוכן הזה.

הדוגמה הזו מריצה סקריפט הכנה רק כשסוכן המשנה db-agent מתחיל, וסקריפט ניקוי כשכל סוכן משנה נעצר:

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

ראו Hooks לפורמט המלא של הגדרת hooks.

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

#הבנת האצלה אוטומטית

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

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

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

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

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

• שפה טבעית: נקבו בשם סוכן המשנה בהנחיה שלכם; Claude מחליט אם לאציל
• אזכור @: מבטיח שסוכן המשנה ירוץ למשימה אחת
• לכל הסשן: כל הסשן רץ כסוכן המשנה הזה דרך הדגל --agent או ההגדרה agent

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

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

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

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

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

סוכני משנה שמסופקים על ידי תוסף מופעל מופיעים בהשלמה האוטומטית תחת השם הממוקד שלהם, כמו my-plugin:code-reviewer או my-plugin:review:security כשהתוסף מארגן סוכנים לתת תיקיות. סוכני משנה ברקע בעלי שם שרצים כרגע בסשן מופיעים גם הם בהשלמה האוטומטית, ומציגים את הסטטוס שלהם ליד השם.

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

הרצת כל הסשן כסוכן משנה. העבירו --agent <name> כדי להתחיל סשן שבו השרשור הראשי עצמו מקבל את הגבלות הכלים והמודל של סוכן המשנה הזה:

claude --agent code-reviewer

אלא אם ההנחיה של הסוכן ריקה, הנחיית המערכת של סוכן משנה מותאם אישית מחליפה לגמרי את הנחיית המערכת של Claude Code, באותו אופן שבו --system-prompt עושה. קבצי CLAUDE.md וזיכרון הפרויקט עדיין נטענים דרך זרימת ההודעות הרגילה, גם כשהגדרת הסוכן מגדירה omitClaudeMd. אם מריצים את הסשן עם -p כסוכן מותאם אישית שיש לו הנחיה משלו, הוא גם מתחיל בלי תמונת מצב של סטטוס git.

שם הסוכן מופיע כ-@<name> בכותרת ההפעלה כדי שאפשר לאשר שהוא פעיל.

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

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

claude --agent security-reviewer

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

claude --agent my-plugin:security-reviewer

אם התוסף ממקם את הסוכן בתת תיקייה של תיקיית agents/ שלו, כללו את תת התיקייה בשם הממוקד, לדוגמה claude --agent my-plugin:review:security.

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

{
  "agent": "code-reviewer"
}

דגל ה-CLI גובר על ההגדרה אם שניהם קיימים.

#הרצת סוכני משנה בחזית או ברקע

סוכני משנה יכולים לרוץ בחזית או ברקע:

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

#אילו סוכני משנה רצים ברקע

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

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

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

#תן ל Claude לחכות לסוכן משנה

1. כבה את מצב fork על ידי הגדרת CLAUDE_CODE_FORK_SUBAGENT ל 0, לדוגמה ב settings.json:

   העתק

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

2. הרץ את claude שוב מהמעטפת, או פתח שיחה חדשה ב VS Code.

3. בקש מ Claude לחכות כשאתה צריך תוצאה תחילה, לדוגמה "הרץ את סוכן המשנה reviewer וחכה לדוח שלו".

כדי להמשיך לעבוד בזמן ש Claude מחכה, לחץ על Ctrl+B במסוף או לחץ על Run in background ב VS Code.

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

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

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

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

סוכן משנה ברקע יכול להשאיר פקודת Bash או PowerShell ברקע רצה אחרי סוף התור שלו. כשהפקודה מסתיימת, Claude Code שולח לסוכן המשנה התראה.

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

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

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

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

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

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

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

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

#שגיאות API בסוכני משנה

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

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

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

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

⚠ This agent switched to <model> because its earlier model could not be used.

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

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

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

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

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

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

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

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

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

#בידוד פעולות בנפח גבוה

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

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

#הרצת מחקר במקביל

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

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

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

[!WARNING]

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

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

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

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

השתמש בסוכן המשנה code-reviewer כדי למצוא בעיות ביצועים, ואז השתמש בסוכן המשנה optimizer כדי לתקן אותן

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

השתמש בשיחה הראשית כש:

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

השתמש בסוכני משנה כש:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

כברירת מחדל, כש 20 סוכני משנה רצים בהפעלה, הפעלה של עוד אחד עם הכלי Agent נכשלת עם Concurrent subagent limit reached, והשגיאה אומרת ל Claude לא לנסות שוב. ההפעלה מצליחה שוב כשמספר הרצים יורד מתחת למגבלה. כדי לשנות את המגבלה, הגדר את CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS לכל מספר שלם חיובי. הפעלות שבהן ultracode פעיל פטורות: המגבלה לא נאכפת שם. נדרש Claude Code v2.1.217 או חדש יותר.

המגבלה חוסמת רק סוכני משנה ש Claude מפעיל עם הכלי Agent, אבל ריצות אחרות תופסות את אותם מקומות:

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

סוכנים שתכונות אחרות מריצות, כמו סוכני workflow וחברי צוות סוכנים, פועלים לפי המגבלות שלהם.

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

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

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

ההקשר הראשוני של סוכן משנה שאינו fork מכיל:

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

כדי להפעיל אחד מסוכני המשנה שלך בלי קבצי CLAUDE.md של המשתמש, הפרויקט והמקומי, הגדר omitClaudeMd: true ב-frontmatter שלו או ב-JSON של --agents. עבור Explore, Plan וסוכני משנה עם omitClaudeMd, CLAUDE.md של תת-ספרייה וכללים לפי נתיב תואמים עדיין נטענים כשסוכן המשנה עובד עם קבצים שם.

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

אי אפשר לשנות אילו סוכני משנה מקבלים מצב git. רק Explore ו-Plan מדלגים עליו.

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

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

#חידוש סוכני משנה

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

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

• כשסוכן משנה מסיים, קלוד מקבל את מזהה הסוכן שלו.
• הסוכנים המובנים Explore ו-Plan הם חד-פעמיים ולא מחזירים מזהה סוכן, ולכן קלוד לא יכול לחדש אותם. השתמש ב-general-purpose או בסוכן משנה מותאם כשצריך להמשיך את העבודה.
• כשסוכן משנה נעצר במגבלת maxTurns, Claude Code מסמן את הפלט שהוחזר כחלקי, וקלוד יכול לחדש את סוכן המשנה כדי להמשיך את העבודה שלו.

קלוד משתמש בכלי SendMessage עם מזהה הסוכן או שמו בשדה to כדי לחדש אותו. SendMessage לא דורש שצוותי סוכנים יהיו מופעלים. רק הודעות פרוטוקול צוות מובנות כמו shutdown_request ו-plan_approval_response דורשות זאת. מעבר לסוכני משנה וחברי צוות, בסשנים שבהם העברת הודעות בין סשנים מופעלת, קלוד יכול להשתמש באותו כלי כדי לשלוח הודעה לסשנים אחרים שלך של Claude Code, במחשב הזה או מעבר לו.

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

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]

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

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

סוכן משנה שעצרת בעצמך, עם x ב-/tasks או בבקשת SDK מסוג stop_task, לא מתחדש אוטומטית. אם קלוד שולח לו הודעה, ההודעה נדחית וקלוד מקבל הודעה שהסוכן בוטל.

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

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

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

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

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

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

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

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

[!NOTE]

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

אם קלוד לא יכול לשלוח הודעה לסוכן משנה לפי שם אחרי שהפעלת מחדש את Claude Code וחידשת את הסשן, תן לקלוד את מזהה הסוכן של סוכן המשנה במקום זאת. שמות שקלוד נתן מהשיחה הראשית מאז הדחיסה האחרונה שלה שורדים את ההפעלה מחדש. שם מלפני הדחיסה הזו לא שורד. כדי למצוא את המזהה של שם, חפש את השם הזה בקבצי agent-{agentId}.meta.json ב-~/.claude/projects/{project}/{sessionId}/subagents/.

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

#דחיסה אוטומטית

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

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

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

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

#הגדרת חלון הדחיסה האוטומטית לסוכן משנה אחד

כדי שסוכן משנה אחד יידחס מוקדם יותר ממה שהיה נדחס אחרת, הגדר autoCompactWindow ב-frontmatter שלו למספר טוקנים מ-100000 עד 1000000. אם הגדרת CLAUDE_CODE_AUTO_COMPACT_WINDOW, סוכן המשנה משתמש בחלון של המשתנה הזה במקום, ולשדה אין השפעה, אלא אם Claude Code מתעלם מערך המשתנה. נדרש Claude Code v2.1.296 או מאוחר יותר.

ה-frontmatter הזה מגדיר autoCompactWindow ל-200,000 טוקנים לסוכן משנה שקורא קובצי לוג ארוכים:

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

כתוב את הערך כמספר שלם רגיל כמו 200000, כי ב-frontmatter Claude Code קורא את 200k כ-200, וזה מחוץ לטווח המותר. סוכן המשנה עדיין נטען ונדחס כאילו השדה לא היה קיים. כדי לבדוק אם Claude Code התעלם מהערך שלך, הרץ claude --debug במעטפת וחפש ביומן הניפוי את invalid autoCompactWindow.

אם הערך בטווח ועדיין לא רואים שינוי, בדוק את הסיבות האלה:

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

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

[!NOTE]

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

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

Claude יכול להתחיל פיצול בעצמו כשמצב פיצול פועל, כפי שהוא כברירת מחדל. כדי לעצור פיצולים, ראה כיבוי מצב פיצול.

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

/subtask draft unit tests for the parser changes so far

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

#צפייה והכוונה של פיצולים שרצים

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

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

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

כשתמליל של פיצול או של סוכן משנה פתוח, הודעות המשך וskills הולכות לסוכן הזה. ב-Claude Code v2.1.314 ואילך, /btw עונה מתוך התמליל הפתוח. פקודות מובנות אחרות הולכות לשיחה הראשית, עם אמצעי ההגנה האלה:

• /compact, /clear ו-/rewind פועלים על השיחה הראשית, ולכן Claude Code מבקש ממך לאשר לפני הרצה של אחת מהן מהתצוגה הזו.
• /model ו-/fast מגדירים את המודל ואת מצב המהיר של השיחה הראשית, לא של הסוכן הנצפה, ולכן הם לא רצים מהתצוגה הזו. הודעה מסבירה למה.

כדי שהסוכן הנצפה יקרא את ההודעה שלך לפני שהעבודה שהוא ממתין לה מסתיימת, שלח אותה עם Ctrl+Enter או Ctrl+X Ctrl+S. כל פקודת מעטפת או סוכן משנה שהסוכן ממתין לו ויכול לעבור לרקע עובר לשם וממשיך לרוץ. כשהסוכן כותב תשובה, או ממתין לעבודה שלא יכולה לעבור לרקע, הוא ממשיך וקורא את ההודעה שלך אחרי שזה מסתיים. נדרש Claude Code v2.1.286 ואילך.

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

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

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

כש-Claude יוצר פיצול דרך כלי Agent, הוא יכול להעביר isolation: "worktree" כך שעריכות הקבצים של הפיצול נכתבות ל-git worktree נפרד במקום ל-checkout שלך. פיצול לא יכול ליצור פיצולים נוספים.

#כיבוי מצב פיצול

מצב פיצול מאפשר ל-Claude להתחיל פיצול בעצמו. כדי לעצור את Claude מלהתחיל פיצולים:

• עצירת פיצולים בלבד: הוסף "Agent(fork)" ל-permissions.deny בהגדרות שלך.
• כיבוי מצב פיצול: הגדר את CLAUDE_CODE_FORK_SUBAGENT ל-0, לפי השלבים בתן ל-Claude להמתין לסוכן משנה.

בזמן שמצב פיצול פועל, Claude גם לא יכול להמתין לסוכן משנה בטרמינל אינטראקטיבי, ב-VS Code, או בסשני שולחן עבודה במחשב שלך. מצב פיצול פועל כברירת מחדל מ-Claude Code v2.1.302, ובסשן טרמינל אינטראקטיבי מ-v2.1.232.

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

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

[!TIP]

שיטות עבודה מומלצות:

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

#סוקר קוד

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

---
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.

#מנפה באגים

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

#מדען נתונים

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

---
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.

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

סוכן משנה שמאפשר גישת Bash אבל מאמת פקודות כדי להתיר רק שאילתות SQL לקריאה בלבד. הדוגמה הזו מראה איך להשתמש ב-hooks של PreToolUse לאימות מותנה כשצריך שליטה עדינה יותר ממה ששדה tools מספק.

---
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.

Claude Code מעביר קלט hook כ-JSON דרך stdin לפקודות hook. סקריפט האימות קורא את ה-JSON הזה, מחלץ את הפקודה שמורצת, ובודק אותה מול רשימת פעולות כתיבה של SQL. אם מזוהה פעולת כתיבה, הסקריפט יוצא עם קוד 2 כדי לחסום הרצה ומחזיר הודעת שגיאה ל-Claude דרך stderr.

צור את סקריפט האימות בכל מקום בפרויקט. הנתיב חייב להתאים לשדה command בתצורת ה-hook שלך:

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

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

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

# Block write operations (case-insensitive)
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

ב-macOS וב-Linux, הפוך את הסקריפט לניתן להרצה:

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

ב-Windows, כתוב את סקריפט האימות ב-PowerShell והוסף shell: powershell לרשומת ה-hook. ראה הרצת hooks ב-PowerShell.

ה-hook מקבל JSON דרך stdin עם פקודת Bash ב-tool_input.command. קוד יציאה 2 חוסם את הפעולה ומזין את הודעת השגיאה בחזרה ל-Claude. ראה Hooks לפרטים על קודי יציאה וקלט Hook לסכמת הקלט המלאה.

הנחיית המערכת אומרת לסוכן המשנה לסרב לבקשות כתיבה, כך שה-hook הוא גיבוי: אם סוכן המשנה מנסה כתיבה בכל זאת, Claude Code חוסם את הפקודה וסוכן המשנה רואה את ההודעה Blocked: Write operations not allowed. Use SELECT queries only.

#הצעדים הבאים

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

• הפצת סוכני משנה עם תוספים כדי לשתף סוכני משנה בין צוותים או פרויקטים
• הרצת Claude Code באופן תכנותי עם Agent SDK עבור CI/CD ואוטומציה
• שימוש בשרתי MCP כדי לתת לסוכני משנה גישה לכלים ולנתונים חיצוניים