תיעוד 76

אסמכתת מודים

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

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

[!NOTE]

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

#קבצים

מוד הוא תיקיית תוסף עם הקבצים האלה:

קובץ	נדרש	תוכן
`.claude-plugin/plugin.json`	כן	המניפסט של התוסף. מודים לא מוסיפים שדות נדרשים.
`hooks/hooks.json`	כן	`modules`: מערך עם נתיב אחד, יחסית לקובץ הזה, אל מודול ה-hooks, כמו ב-`"modules": ["./register.js"]`. יכול גם להחזיק hooks של הגדרות תחת `hooks`.
מודול ה-hooks, כגון `hooks/register.js`	כן	נקודת הכניסה של המוד. מייצא את `register(on, options)`. נקרא `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` או `.tsx`. מודול ES.
`types/index.d.ts`, אלא אם `types` במניפסט מציין נתיב אחר	כשהמוד משתמש ב-`$.state` או מוסיף מרחב שמות ל-API של המודים	מצהיר על ערכי `PluginState` ועל כל מרחב שמות שהמוד מוסיף. כדי להשאיר את `types` מחוץ למניפסט, צריך v2.1.299 או גרסה מאוחרת יותר.
קבצים ששמם מסתיים ב-`.test.ts` או `.test.tsx`	לא	בדיקות ש-`claude plugin test` מריץ

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

#פונקציית ה-hook

מוד רושם כל אחד מה-hooks שלו, שהם מטפלי אירועים, על ידי קריאה ל-on בתוך register. on מקבל את שם האירוע, matcher אופציונלי, שהוא מסנן על שדות האירוע, ואת ה-hook, כמו ב-on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on מחזיר רישום עם מתודה אחת, .catch(handler), שמגדירה את מטפל השגיאות של ה-hook.

ארגומנט	מה זה
`$`	ה-API של המודים: כל מתודה במתודות של ה-API של המודים. כתבו כל קריאה במלואה, מרחב שמות ואז מתודה, כמו ב-`$.fs.read('notes.md')`.
`e`	הקלט של האירוע, כנתונים פשוטים שקפואים לעומק. כדי לשנות אותו, העבירו עותק אל `next`.
`next(e)`	המטפל הבא, כמו ב-middleware. מריץ את ה-hooks שאחרי זה, ואז את ההתנהגות של Claude Code. נפתר לתוצאת האירוע.
`next.signal`	`AbortSignal` שמבטל כשהאירוע ננטש
`next.origin`	`{ plugin, tier }` של מי שהפעיל את האירוע. Claude Code עצמו הוא `{ plugin: 'engine', tier: 'core' }`. ה-`tier` של מוד הוא קבוצת העדיפות שלו בסדר שבו מודים רצים: `prepend`, `user`, `append` או `builtin`.
`next.budget`	מגבלת הזמן של ה-hook באלפיות שנייה: `next.budget.ms` הוא כל המגבלה, ו-`next.budget.remainingMs` הוא מה שנשאר עכשיו
`next.to(e, tier)`	מדלג אל tier מאוחר יותר, שהוא `append`, `builtin` או `core`. `next.to(e, 'append')` מדלג על המודים שמשתמש התקין. רק מוד ב-`prependPlugins` או ב-`appendPlugins` יכול לקרוא לזה.
`next.error`	רק במטפל `.catch`. `kind` הוא `throw` או `timeout` כשה-hook נכשל, ו-`message` הוא טקסט השגיאה. `kind` הוא `re-entry` כשה-hook דולג כי האירוע הגיע מתוך קריאה ל-API של המודים על ידי ה-hook הזה או על ידי קוד המוד שלכם מחוץ ל-hooks שלו. `re-entry` דורש את Claude Code v2.1.292 או גרסה מאוחרת יותר.
`next.error.cause`	מוגדר רק כש-`kind` הוא `re-entry`. `rewritten` אם hook מסוג `tool.call` או `PreToolUse` שינה את קריאת ה-API של המודים שממנה הגיע האירוע, או אם hook מסוג `agent.spawn` שינה סוכן שהקריאה הזו התחילה. `lent` כשמתודה שמוד אחר מוסיף ל-API של המודים הפעילה את האירוע הזה, אלא אם גם `rewritten` חל. `lent` דורש את Claude Code v2.1.292 או גרסה מאוחרת יותר, ו-`rewritten` דורש v2.1.300 או גרסה מאוחרת יותר.
`next.called`	רק במטפל `.catch`. `true` כשה-hook קרא ל-`next`.

#אירועים

האירועים מקובצים לפי הנושא שלהם, ולכל אחד מצוין מתי הוא מופעל ומה הוק עליו יכול להחזיר. הוקים על turn.step ועל process.spawn הם async generators, ושאר ההוקים הם async functions.

העמודה האחרונה של כל טבלה משתמשת בכתיב מקוצר. next(e) מעביר את האירוע הלאה ללא שינוי. next({ ...e, text }) מעביר עותק שבו השדה שצוין שונה, כמו ב next({ ...e, text: e.text.trim() }). אובייקט עונה לאירוע בלי קריאה ל next, ומילה כמו reason מייצגת מחרוזת שאתם כותבים, כמו ב { deny: 'Use the file tools.' }.

#כלים

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

אירוע	מתי מופעל	מה הוק יכול להחזיר
`tool.call`	כלי עומד לרוץ	`next(e)`, `{ deny: reason }`, או `{ result }`
`tool.check`	Claude Code מחליט אם קריאת כלי רשאית לרוץ, אחרי הוקי `tool.call` ו `PreToolUse`. `next(e)` נפתר להחלטה שאליה הגיעו הכללים, מצב ההרשאה וההוקים האלה.	`next(e)` או `{ decision }`, כאשר `decision` מוגדר ל `allow`, `ask`, או `deny`, עם `reason` אופציונלי
`tool.describe`	פעם אחת לכל כלי, כשהתיאור שלו נשלח לראשונה אל Claude. פעם שנייה לכלי MCP, כש Claude טוען אותו דרך tool search, כאשר `e.description` מוגדר לטקסט ש Claude קורא עבור הכלי שנטען.	`{ description }`, ואפשר גם עם `isDeferred` שמוגדר ל `true` כדי לשים את הכלי מאחורי tool search, או ל `false` כדי לטעון אותו מראש

#שדות agent וארגון ב `tool.check`

בהוק tool.check, קראו את השדות האלה כדי להבחין בין קריאה של subagent לקריאה של השיחה הראשית, וכדי לראות אם הארגון שלכם דורש אישור לכלי connector:

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

ב tool.check, e.agentId ו e.ceiling דורשים Claude Code v2.1.290 או חדש יותר.

#השדה `e.isReadOnly` ב `tool.check`

בהוק tool.check, e.isReadOnly הוא true כשהכלי מדווח על הקריאה הזו כקריאה לקריאה בלבד. אחרת השדה נעדר, והוא אינו false. הערך הוא הדיווח של הכלי עצמו, לכן קראו את בדקו אם קריאת כלי היא לקריאה בלבד לפני שאתם מאשרים קריאה על סמך השדה הזה לבדו.

ב tool.check, e.isReadOnly דורש Claude Code v2.1.304 או חדש יותר.

#פרומפטים ומה ש Claude קורא

אירועי פרומפט מכסים את הטקסט שהמשתמש מקליד ואת הטקסט ש Claude Code שולח אל Claude בעצמו, כמו ה system prompt ותזכורות:

אירוע	מתי מופעל	מה הוק יכול להחזיר
`prompt.submit`	פרומפט נשלח	`next({ ...e, text })`, `next({ ...e, context })`, או `{ drop: reason }`
`prompt.fill`, `prompt.suggest`	טקסט עומד להיכנס לתיבת הפרומפט כטיוטה, או כהצעה מעומעמת	`next(e)` עם טקסט ששונה
`prompt.edit`	המשתמש עורך את תיבת הפרומפט	`next(e)`
`prompt.autocomplete`	המשתמש מקליד בתיבת הפרומפט ומילה מסתיימת במיקום הסמן. `e.token` הוא המילה הזו. Claude Code לא מחכה להוק: שורות ההשלמה האוטומטית שלו מוצגות קודם.	`{ suggestions }`, רשימה של שורות `{ text, label, description }` שמוצגות מתחת לשורות של Claude Code עצמו. בחירת שורה כותבת את ה `text` שלה על המילה.
`prompt.compose`	Claude Code מרנדר system prompt	`{ sections }`, רשימה של `{ id, text, scope }` לפי הסדר שבו הם נשלחים
`prompt.section`	פעם אחת לכל מקטע בעל שם של ה system prompt. `e.name` הוא ה `id` של המקטע ב `prompt.compose`.	`{ text }`, או `{ text: null }` כדי להשמיט את המקטע
`prompt.context`	פעם אחת לכל שיחה, עבור ההקשר שנשלח עם ההודעה הראשונה	`{ blocks }`
`prompt.attachment`	Claude Code מוסיף הודעה משלו עבור Claude, כמו תזכורת. `e.type` מציין את הסוג, ולסוגים שהטיפוסים מצהירים עליהם `e.detail` מחזיק את העובדות שמהן נכתב הטקסט.	`{ text }`, או `{ text: null }` כדי להשמיט אותה
`prompt.mention`	Claude Code עומד לקרוא קובץ שפרומפט מזכיר באמצעות @. דורש Claude Code v2.1.290 או חדש יותר.	`next({ ...e, path })` כדי לקרוא קובץ אחר, או `{ deny: reason }`
`skill.prompt`	הטקסט של skill מורחב עבור Claude	`{ text }`
`attribution.text`	Claude Code מרכיב טקסט ייחוס של commit או של pull request	`{ text }`

#שדות source ו frontmatter ב `skill.prompt`

בהוק skill.prompt אפשר לקרוא את השדות האלה יחד עם שם ה skill ב e.skill והטקסט ש Claude קורא ב e.text:

שדה	טיפוס	מה הוא מחזיק
`e.source`	string	מי מספק את ה skill: `policySettings`, `userSettings`, או `projectSettings`, עבור skill במיקום הארגוני, האישי או של הפרויקט, בהתאמה. מקורות אחרים נותנים מילה כמו `plugin`, `mcp`, `syncedSkills`, או `built-in`.
`e.pluginName`	string	שם ה plugin, עבור skill שה `e.source` שלו הוא `plugin`
`e.path`	string	הנתיב המוחלט של קובץ `SKILL.md` של ה skill, או של קובץ ה `.md` שלו עבור skill שנכתב כקובץ פקודה. נעדר כשאין ל skill קובץ במכונה הזו, כמו ב skill מובנה.
`e.frontmatter`	object	ה frontmatter של קובץ ה skill, כנתונים פשוטים
`e.frontmatterProblem`	string	הסיבה ש `e.frontmatter` חסר את ה frontmatter של הקובץ או אחד מהמפתחות שלו, כמו ב `is a list or a single value, not a table`. נעדר כש `e.frontmatter` מחזיק את כל ה frontmatter, או כשאין ל skill frontmatter.

הוק יכול להעביר text או frontmatter ששונו אל next: ההוקים שאחריו קוראים את שניהם, ו Claude קורא את ה text הסופי. הוק שמשנה כל שדה אחר נכשל.

ב skill.prompt, e.source, e.pluginName, e.path, e.frontmatter ו e.frontmatterProblem דורשים Claude Code v2.1.299 או חדש יותר.

#פקודות ותצורה

אירוע	מתי מופעל	מה הוק יכול להחזיר
`command.run`	פקודה עומדת לרוץ	`{ text }`, `{}`, או `next(e)`
`command.describe`	פעם אחת לכל פקודה, עבור רשימת הפקודות	`{ description, argumentHint, isHidden }`
`config.set`	שורה של `/config` עומדת להשתנות	`next({ ...e, value })` או `{ deny: reason }`
`config.describe`	פעם אחת לכל שורה של `/config`	`{ label, description, isHidden }`
`settings.read`	מוד קורא ל `$.settings.read`, או Claude Code בונה את ההגדרות הממוזגות של הסשן. דורש Claude Code v2.1.304 או חדש יותר בקריאה העצמית של Claude Code ועבור `e.layers`	`next(e)`, `{ value }`, או `{ deny: reason }`

#`e.layers` ו `e.source` ב `settings.read`

e.layers: אובייקט { source, settings } אחד לכל מקור שבשימוש ומחזיק הגדרות, קדימות נמוכה ראשונה. ראו מה הוק settings.read מקבל.
e.source: המקור האחד שמוד ביקש, כמו ב $.settings.read({ source: 'policy' }). נעדר בקריאה העצמית של Claude Code ובקריאה של ההגדרות הממוזגות

#תורות

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

אירוע	מתי מופעל	מה הוק יכול להחזיר
`turn.start`	תור מתחיל	`next(e)`
`turn.step`	בקשה אחת עומדת להישלח אל המודל	`yield* next(e)`, או `next({ ...e, model })`, `next({ ...e, effort })`
`turn.complete`	תור הסתיים	`next(e)`, או `{ text }` כדי להציג שורה מתחת לתשובה

#סשן

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

אירוע	מתי מופעל	מה הוק יכול להחזיר
`session.start`	פעם אחת לכל מוד שנטען, לפני הפרומפט הראשון, ושוב אחרי טעינה מחדש של המוד הזה. לא אחרי `/clear`, `/resume`, או `/branch`.	`next(e)`
`session.end`	הסשן מסתיים, או שרצים `/clear`, `/resume`, או `/branch`. `e.reason` הוא `clear`, `resume`, `logout`, `prompt_input_exit`, או `other`. `/branch` מדווח `resume`.	`next(e)`
`session.compact`	השיחה עומדת להידחס	`{ skip: reason }`
`session.receive`, `session.send`	הודעה מגיעה מסוכן או מסשן אחר, או עומדת להישלח אליהם. ראו שליחה וקבלה של הודעות בין סשנים.	`{ consumed: reason }` עבור `receive`, `{ isDelivered: false, reason }` עבור `send`
`session.append`	פעם אחת לכל שורה שהשיחה שומרת, כמו פרומפט, בלוק תגובה, תוצאת כלי או התראה, לפני שהיא נשמרת	`next({ ...e, message })` עם `message.content` ששונה, כדי לשכתב את בלוקי הטקסט של השורה או את ה `content` של בלוק `tool_result` שבתוכה
`session.attach`, `session.detach`	אפליקציה אחרת מתחברת לסשן או מתנתקת ממנו	`next(e)`
`session.measure`	אחרי כל תור, וכשמשתנה אחוז השימוש של מגבלת תוכנית	`next(e)`

#Subagents

אירועי subagent מופעלים כשסוג של subagent מוצע ל Claude, וכש subagent או חבר צוות של agent team עומד להתחיל:

אירוע	מתי מופעל	מה הוק יכול להחזיר
`agent.offer`	סוג subagent מוצע ל Claude	`{ isOffered: false }` כדי לא להציע אותו
`agent.spawn`	subagent או חבר צוות בצוות סוכנים עומד להתחיל, או subagent שסיים או נעצר עומד לרוץ שוב. עבור חבר צוות, `e.isTeammate` הוא `true`. עבור ריצה שמחודשת, `e.resume` מוגדר.	`next({ ...e, model })` כדי לבחור את המודל של אחד שמתחיל, או `{ deny: reason }`

הוק agent.spawn שלכם רץ גם כש subagent שסיים או נעצר עומד לרוץ שוב, כמו כש Claude שולח אליו הודעה עם הכלי SendMessage. באירוע הזה, e.resume הוא { agentId }. אם ההוק שלכם סופר subagents, דלגו על האירועים שבהם e.resume מוגדר, כדי ש subagent שחודש לא ייספר שוב.

החזירו { deny: reason } כדי לסרב לריצה שמחודשת. הריצה לא מתחילה, וה subagent נשאר כפי שהיה. כשקריאת SendMessage ביקשה את הריצה, Claude קורא את a plugin declined the resume: ואחריו את הסיבה שלכם, כתוצאה של הקריאה הזו. אם אתם מעבירים אירוע ששונה אל next עבור ריצה שמחודשת, כמו model אחר, Claude Code מתעלם מהשינוי.

[!NOTE]

האירוע לריצה שמחודשת דורש Claude Code v2.1.299 או חדש יותר. לפני v2.1.299, הוק agent.spawn שלכם לא רץ כש subagent חודש. בגרסאות האלה, כדי לסרב לקריאות SendMessage שמחדשות subagent, התאימו את הכלי הזה בהוק tool.call.

#ממשק

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

אירוע	מתי מופעל
`ui.render`	אתר רינדור עומד להיצבע
`ui.resolve`	מודים נטענים, פעם אחת לכל אפליקציה, אתר רינדור ומוד. התוצאה היא טבלת האלמנטים ש `$.ui.resolve(e)` קורא.
`ui.press`, `ui.input`, `ui.select`	נעשה שימוש ב `Button`, ב `Input`, או ב `Select` שמוד צייר
`ui.focus`, `ui.scroll`	הפקד שבמיקוד, או מיקום הגלילה של חלונית או של ה band, עומד להשתנות
`ui.close`	חלונית עומדת להיסגר. `e.id` הוא החלונית, ו `e.origin.kind` הוא `plugin`, `person`, או `unload`.
`ui.message`	אלמנט `Client` שולח נתונים למוד שלו
`ui.fault`	אלמנט `Client` שהמוד שלכם צייר נכשל בטעינה, בציור או בריצה. `e.phase` הוא `load`, `render`, או `run`, ו `e.reason` הוא הודעת השגיאה. דורש Claude Code v2.1.289 או חדש יותר.

#מודים אחרים

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

אירוע	מתי מופעל	מה הוק יכול להחזיר
`plugin.register`	מודול הוקים עומד להיטען. `e.uses` מפרט את האירועים שלו, קריאות ה API של המודים, משתני הסביבה והמצב, כפי ש `claude plugin validate` מדפיס אותם. כל קריאה נכתבת בלי הקידומת `$.`, כמו `fs.read`.	`{ refuse: reason }`
`engine.create`	ה API של המודים נבנה עבור המוד הזה	API של מודים ששונה, כדי להוסיף namespace. מוד שמחוץ לדרגה `user` יכול גם למנוע אחד.

כשהוק של מוד אחר קורא למתודה על namespace שהוספתם ב engine.create, קריאות ה $ של המתודה שלכם רצות בהקשר של ההוק הזה עד שכל הוק על האירוע הזה מחזיר. לדוגמה, נתיב יחסי נפתר מול תיקיית העבודה של ההוק הזה, ו $.prompt.submit נדחה בזמן שהתור ממתין להוק הזה. קריאות שהמתודה שלכם מבצעת אחרי זה רצות בהקשר של המוד שלכם עצמו.

#טלמטריה

אירועי טלמטריה מופעלים עבור רשומות השימוש ש Claude Code רושם:

אירוע	מתי מופעל	מה הוק יכול להחזיר
`telemetry.log`, `telemetry.mark`	רשומת טלמטריה עומדת להירשם, או ששימוש אחד בתכונה מסומן. במוד שאתם מתקינים, תנו להוק טלמטריה את המסנן `{ to: 'collector' }`, כמו ב `on('telemetry.log', { to: 'collector' }, hook)`. בלי המסנן, המוד נכשל ב `claude plugin validate`. `*` לא מתאים לאירועים האלה.	`next(e)`, או `{ deny: reason }`

#אירועי הוק של הגדרות

כל אירוע הוק של הגדרות הוא אירוע בשם classic.<Event>, כמו classic.Stop או classic.PostToolUse. e הוא ה JSON ב stdin של ההוק.

#קריאות API של מודים

כל מתודת API של מודים היא גם אירוע, שנקרא על שם ה namespace והמתודה שלו, כמו fs.read, model.complete, או ui.open. הוק על אחד מהם מיירט קריאות מהמודים שרצים אחריו, ויכול להחזיר next(e), { deny: reason }, או { value }.

#שיטות ה-API של מודים

ה-API של מודים הוא הארגומנט $ שכל hook מקבל. השיטות שלו מקובצות במרחבי שמות, כמו $.ui. הטבלה הזו מפרטת את השיטות של כל מרחב שמות לפי שם, כך ש-open בשורה של $.ui הוא הקריאה $.ui.open(...). המדריכים מראים את הנפוצות בשימוש, והטיפוסים לבילד שלך מתעדים כל שיטה עם דוגמה.

מרחב שמות	שיטות
`$.plugin`	`name`, `root`: השם והספרייה של הפלאגין הזה
`$.ui`	`resolve`, `invalidate`, `open`, `close`, `panes`, `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`
`$.command`	`register`, `run`, `list`
`$.tool`	`register`, `call`, `check`, `list`
`$.agent`	`register`, `spawn`, `list`. `list()` מחזיר את סוכני המשנה וחברי הצוות של הסשן הזה, לכל אחד `status` של `pending`, `running`, `waiting`, `idle`, `completed`, `failed`, או `killed`, כאשר `idle` ו-`waiting` דורשים את Claude Code v2.1.289 או חדש יותר.
`$.model`	`complete`, `fork`, `classify`
`$.prompt`	`submit`, `read`, `fill`, `suggest`, `compose`. Claude קורא טקסט מ-`submit({ text })` אחרי משפט שמציין את המוד שלך כשולח. `submit({ text, asUser: true })` שולח את הטקסט כמילים של המשתמש עצמו, בלי המשפט הזה.
`$.turn`	`abort`
`$.session`	`messages`, `cwd`, `root`, `model`, `turns`, `id`, `repo`, `surfaces`, `usage`, `version`, `compact`, `send`, `append`, `authorize`. `usage()` מחזיר `{ startedAt, context, rateLimits, cost }`: ל-`context` יש `tokens`, `window`, ו-`percent`, ו-`rateLimits` הוא רשימה של `{ kind, percentUsed, resetsAt }`.
`$.config`	`list`, `set`
`$.settings`	`read`
`$.env`	`get`, `set`
`$.fs`	`read`, `write`, `list`, `exists`, `stat`, `ancestors`. `write` אינו אטומי: הוא מחליף את תוכן הקובץ במקום, כך שתהליך אחר יכול לקרוא קובץ שנכתב חלקית. שמור נתונים שכמה סשנים משנים ב-`$.store`.
`$.store`	`get`, `set`, `delete`, `keys`. מאגר מפתח-ערך שכל סשן במכונה חולק. ראה שמירה מיותר מסשן אחד.
`$.state`	מצב ריאקטיבי: `get`, `set`, עם העוזרים `atom`, `read`, `update`, `derive`, ו-`memberOf` שמיובאים מ-`claude-code`
`$.clock`	`now`, `sleep`, `after`, `every`
`$.http`	`fetch`
`$.process`	`run`, `spawn`
`$.mcp`	`call`, `connect`. `connect(server)` מתחבר לשרת MCP שהמניפסט של הפלאגין שלך עצמו מציין.
`$.audio`	`play`, `speak`
`$.telemetry`	`log`, `mark`. רשומה נשלחת רק כאשר Claude Code או מוד מובנה מבצע את הקריאה.

#אתרי רינדור

אתר רינדור הוא נקודת הרחבה בממשק של Claude Code. כל שורה היא ערך של e.component ב-hook של ui.render, עם השדות של e.props והאפליקציות שמרנדרות אותו. e.surface מציין את האפליקציה שמציירת, כמו terminal, desktop, או vscode. שינוי מה ש-Claude Code כבר מצייר מראה מה hook יכול לעשות באתר, עם דוגמה לכל בחירה.

רינדור בתוסף VS Code דורש גרסת תוסף 2.1.299 או חדשה יותר. סשן שלא מושך דגלי פיצ'ר צריך 2.1.304 או חדש יותר. ציור בתוסף VS Code מפרט מה התוסף מצייר בצורה שונה.

אתר	`e.props`	`e.requestId`	מרונדר ב-
`Pane`	`title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view`	ה-`id` של ה-pane	טרמינל, Desktop, VS Code
`AbovePrompt`	`hasSurvey`, `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view`	מופע אחד	טרמינל, Desktop
`UserMessage`	`text`, `origin`, `isExpanded`, ו-`task` או `from` לפי origin	מזהה ההודעה	טרמינל, Desktop, VS Code
`AssistantMessage`	הטקסט של התשובה	מזהה ההודעה	טרמינל, Desktop, VS Code
`ToolUse`, `ToolResult`, `ToolGroup`	השם, הקלט והתוצאה של הכלי	מזהה קריאת הכלי	טרמינל, Desktop, VS Code
`CommandOutput`	`command`, `text`	מזהה ההודעה	טרמינל, Desktop
`AskUserQuestion`	השאלה והאפשרויות	מזהה קריאת הכלי	טרמינל, Desktop, VS Code
`ToolProgress`	`kind`	מזהה קריאת הכלי	טרמינל
`Spinner`	`word`, `message`, `suffix`, `mode`	מזהה הסוכן	טרמינל, Desktop, VS Code
`TurnDuration`	`word`, `durationMs`	מזהה ההודעה	טרמינל
`InfoNotice`	`text`, `command`	מזהה ההודעה	טרמינל
`SessionMode`	`modes`	מופע אחד	טרמינל, Desktop
`PromptHint`	`isDraft`, `isWorking`, `hint`	מופע אחד	טרמינל, Desktop

e.viewport מחזיק את columns, rows, ו-isFullscreen. בטרמינל ובאפליקציית Desktop הוא חסר עד שהאפליקציה מדדה את החלון שלה. שם, rows שלו הוא הגובה של כל החלון, לא של ה-pane שלך. בתוסף VS Code הוא תמיד נוכח.

כדי להתאים עץ לאתר שלו, קרא את ה-props האלה ב-hook:

רוחב של Pane או של ה-band: צייר אל e.props.bodyColumns
גובה של Pane לצד התמליל: כאשר e.props.placement הוא 'dock', e.props.scroll.bodyRows הוא מספר השורות שיש ל-pane עבור העץ שלך
גובה של Pane מעל הפרומפט: כאשר e.props.placement הוא 'inline', ה-pane גדל עם העץ שלך עד גבול, ו-bodyRows הוא הגבול הזה. כדי לבקש גבול אחר, ראה את שדה rows של $.ui.open.

עץ שגבוה מה-pane נגלל כמכלול.

#אלמנטים

אלמנטים הם אבני הבניין של עץ ש-hook של ui.render מחזיר, ומקבלים אותם מ-$.ui.resolve(e). בניית עץ מאלמנטים מראה את הנפוצים עם האופן שבו הטרמינל מצייר אותם, ולגלריית הממשק יש צילומי מסך של רובם. סימן וי אומר שהאפליקציה יכולה לצייר את האלמנט.

אלמנט	מאפיינים עיקריים	טרמינל	Desktop	VS Code
`Box`	`key`, פריסת flex, `gap`, `padding`, `margin`, `width`, `height`, `minWidth`, `minHeight`, `borderStyle`, `borderColor`, `borderDimColor`, `backgroundColor`, `position`, `top`, `left`, `right`, `bottom`, `overflow`, `display`, `hover`	✓	✓	✓
`Text`	`color`, `backgroundColor`, `bold`, `italic`, `underline`, `strikethrough`, `dimColor`, `inverse`, `wrap`, `size`, `weight`, `mono`, `tabular`, `hover`	✓	✓	✓
`Button`	`key`, `label`, `children`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `variant`, `role`, `hover`	✓	✓	✓
`Link`	`href`, `label`. ראה מגבלות.	✓	✓	✓
`Code`	`source`, `language`, `path`, `startLine`, `format`, `wrap`	✓	✓	✓
`Markdown`	`text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks`	✓	✓	✓
`Input`	`key`, `label`, `placeholder`, `value`, `submitLabel`, `rows`, `onSubmit`, `onInput`, `autoFocus`	✓	✓	✓
`Select`	`key`, `label`, `options`, `value`, `onSelect`, `autoFocus`	✓	✓	✓
`Svg`	`source` של סימון SVG עד 131,072 תווים, טקסט `alt`, `width`, `height`, ו-`isInteractive`		✓	✓
`Client`	`module`, `key`, `props`, `width`, `height`, `flexGrow`	✓	✓
`Raster`	`key`, `columns` עד 512, `rows` עד 256, `cells`. ראה ציור רשת של תאים צבעוניים.	✓
`Image`	`key`, `source` כמו בייטים של PNG או RGBA עד 2 MiB, או נתיב קובץ, `columns` ו-`rows` עד 255, וטקסט `alt`. ראה אילו טרמינלים מציירים אותו.	✓

כללי Button נוספים:

action: מציין אחת מפעולות קיצורי המקשים של Claude Code עצמו, וה-binding של המשתמש אליה לוחץ על הכפתור כאשר ה-binding הזה הוא chord או מקש עם מודיפייר
קיצורי ספרה ב-band: hotkey של ספרה על כפתור ב-band מופעל גם כאשר המשתמש מקליד את הספרה הזו לבדה לתוך פרומפט ריק ועוצר
band מכווץ: בזמן שה-band מכווץ, לא binding של action ולא hotkey לוחצים על כפתור בתוכו
שני כפתורים על hotkey אחד: כאשר שני כפתורים בציור אחד מציינים את אותו hotkey, המאוחר מביניהם מקבל אותו
variant: primary או secondary, וכל ערך אחר זורק. בטרמינל, כפתור primary מצויר בצבע ההדגשה אלא אם הוא plain.
role: dismiss מסמן כפתור סגירה, וכל ערך אחר זורק. בצע את הסגירה ב-onPress שלך. ב-band שמחזיק טקסט ושורה של כפתורים, אפליקציית Desktop יכולה לצייר את כפתור ה-dismiss הראשון בשורה כבקר הסגירה שלה. הטרמינל מצייר את הכפתור כפי שהיה מצייר בלי role.

Button יכול להחזיק children במקום label:

מה ה-children יכולים להיות: מחרוזות ואלמנטי Text, כמו שם שאחריו פרט עמום או צ'יפ צבעוני. Claude Code מסרב לכל אלמנט אחר בתוך Button.
מתן שם לכפתור: ה-label נותן שם לכפתור וברירת המחדל שלו היא הטקסט של ה-children שלו. תן לכפתור עם children שאינם מחרוזת אחת key או label.
בטרמינל: ה-children מצוירים במקום שבו ה-label היה מצויר, ולחיצה בכל מקום עליהם נחשבת כלחיצה אחת, כך שאפשר להפוך כל שורה של רשימה לכפתור יחיד
באפליקציית Desktop ובתוסף VS Code: הכפתור מצייר את ה-label שלו

[!NOTE]

Button עם children שאינם מחרוזת יחידה דורש את Claude Code v2.1.295 או חדש יותר.

autoFocus מקבל רק true על כל בקרה, לכן השמט את ה-prop כדי להשאיר אותו כבוי.

תוסף VS Code מתעלם מחלק מה-props של אלמנטים ומצייר את האלמנט כאילו השמטת אותם:

Box: position עם top, left, right, ו-bottom שלו, alignSelf, borderDimColor, ו-hover
Text: size, mono, tabular, ו-hover
Button: hotkey, plain, autoFocus, action, ו-hover, כך שהמשתמש לוחץ שם על כפתור בלחיצה, או עם Enter אחרי שיש לו פוקוס. התוסף מתעלם גם מ-variant ומ-role.
Code: language, path, startLine, format, ו-wrap, כך שהקוד מצויר בלי צבעים או מספרי שורות, ובלוק format: 'diff' מציג את הטקסט הגולמי של ה-diff
Input ו-Select: autoFocus, ו-rows על Input
Svg: isInteractive

#סגנונות מסגרת של `Box`

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

`borderStyle`	מה הטרמינל מצייר	קצה עליון
`'single'`	קווים דקים עם פינות מרובעות	`┌──┐`
`'double'`	קווים כפולים	`╔══╗`
`'round'`	קווים דקים עם פינות מעוגלות	`╭──╮`
`'bold'`	קווים עבים	`┏━━┓`
`'singleDouble'`	קווים דקים למעלה ולמטה, קווים כפולים בצדדים	`╓──╖`
`'doubleSingle'`	קווים כפולים למעלה ולמטה, קווים דקים בצדדים	`╒══╕`
`'classic'`	תווי ה-ASCII `+`, `-`, ו-`\|`	`+--+`
`'arrow'`	חצים שמצביעים אל תוך ה-`Box`	`↘↓↓↙`
`'dashed'`	קווים מקווקווים עם פינות ריקות	`╌╌`
`'quote'`	פס, `▎`, לאורך הצד השמאלי ותאים ריקים בשלושת הצדדים האחרים	ריק

Box ש-borderStyle שלו מציין כל שם אחר, כמו 'rounded', מצויר בלי מסגרת.

#מדרגות ריווח של `Box`

ה-props של ריווח ב-Box הם gap, columnGap, rowGap, padding, margin, והצורות של צד אחד ושל ציר אחד של padding ושל margin, כמו paddingX ו-marginTop. כל אחד מקבל מספר של תאי טרמינל כמו gap: 1, או שם מדרגה כמו gap: 'md'. בטרמינל ובתוסף VS Code, כל מדרגה היא מספר התאים הזה:

מדרגה	תאים לרוחב	תאים למטה
`'xs'`	1	0
`'sm'`	1	0
`'md'`	2	1
`'lg'`	3	1
`'xl'`	4	2

אם מגדירים את gap, padding, או margin למדרגה, המדרגה חלה לרוחב ולמטה בבת אחת. לדוגמה, בטרמינל ובתוסף VS Code, padding: 'md' הוא שני תאים בכל צד ושורה אחת מעל ומתחת.

שמות מדרגות דורשים את Claude Code v2.1.299 או חדש יותר. במהדורה מוקדמת יותר, עץ שמשתמש בשם מדרגה אינו מצויר.

#props טיפוגרפיה של `Text`

הגדר size, weight, mono, או tabular על Text כדי לבקש מהאפליקציה שמציירת את העץ שלך גודל טקסט, משקל, גופן ברוחב אחיד, או ספרות ברוחב שווה. לפני שמסתמכים על prop, בדוק מה הטרמינל ותוסף VS Code עושים איתו. אם אפליקציה מתעלמת מ-prop שהגדרת, העץ שלך עדיין מצויר שם, עם הטקסט כאילו השמטת את ה-prop הזה.

מאפיין	ערכים	בטרמינל	בתוסף VS Code
`size`	`'caption'`, `'footnote'`, `'body'`, `'heading'`, או `'title'`	מתעלמים: לטרמינל יש גודל טקסט אחד	מתעלמים
`weight`	`'regular'`, `'medium'`, `'semibold'`, או `'bold'`	`semibold` ו-`bold` מצוירים כטקסט מודגש	`semibold` ו-`bold` מצוירים כטקסט מודגש
`mono`	`true` כדי לבקש את הגופן ברוחב האחיד של האפליקציה	מתעלמים: הטרמינל תמיד ברוחב אחיד	מתעלמים, כך שהטקסט שומר על הגופן של התוסף עצמו
`tabular`	`true` כדי לבקש ספרות ברוחב שווה, כך שמספר שמתעדכן במקום או עמודה של מספרים נשארים מיושרים	מתעלמים: הספרות של הטרמינל כבר ברוחב של תא אחד	מתעלמים

ארבעת ה-props האלה דורשים את Claude Code v2.1.299 או חדש יותר. במהדורה מוקדמת יותר, עץ שמגדיר size, weight, mono, או tabular אינו מצויר.

#החלפת `bold` ב-`weight`

bold על Text מוצא משימוש לטובת weight ועדיין עובד. כדי להחליף אותו על Text בלי weight, שנה את bold: true ל-weight: 'semibold' לאותה תוצאה ב-Claude Code v2.1.299 או חדש יותר.

במהדורה מוקדמת מ-v2.1.299, עץ שמגדיר weight אינו מצויר. אם מגדירים גם bold וגם weight על Text, ל-bold אין השפעה.

#מגבלות

קריאות ל-API של hooks ושל mods רצות תחת מגבלות זמן וגודל. Claude Code מדלג על hook שחורג ממגבלת זמן. עץ שחורג ממגבלת הקינון, האלמנטים, תאי Raster, או הבייטים של Image אינו מצויר.

מגבלה	ערך
זמן הריצה של hook עצמו לאירוע אחד, בלי למנות זמן בתוך `next` או קריאת API של mods מלבד `$.clock.sleep`	10 שניות, או 50 אלפיות השנייה ל-hook של `prompt.edit`
זמן הריצה של מטפל `.catch`	שנייה אחת
כל ה-hooks של `session.end` יחד	משך תקציב ה-SessionEnd hook, 1.5 שניות אלא אם משנים אותו, נספר מהרגע שבו ה-hooks של `SessionEnd` בהגדרות שלך מסתיימים
פסק זמן של `$.process.run`	30 שניות כברירת מחדל, 10 דקות לכל היותר
`stdout` ו-`stderr` של `$.process.run`	4 MiB כל אחד. `isStdoutTruncated` או `isStderrTruncated` הוא `true` כשאחד מהם נחתך.
`maxTokens` של `$.model.complete`	1024 כברירת מחדל, עד 64,000 או מגבלת הפלט של המודל
`$.fs.read` ו-`$.fs.write`	4 MiB לקובץ אחד
גוף בקשה של `$.http.fetch`	4 MiB, נספר בתווים. קריאה עם גוף גדול יותר נדחית.
גוף תשובה של `$.http.fetch`	4 MiB. `text` מחזיק את 4 ה-MiB הראשונים והשאר אינו נקרא. כשכותרת `Content-Length` מצהירה על יותר, הקריאה נדחית במקום זאת, עם סיבה שמסתיימת ב-`is over the 4194304-byte limit`, למעט כשהבקשה האחרונה אחרי הפניות כלשהן משתמשת במתודה `HEAD`. הפטור של `HEAD` דורש את Claude Code v2.1.296 או מאוחר יותר.
קריאת `$.http.fetch` אחת, כולל הפניות וגוף	30 שניות
הפניות שקריאת `$.http.fetch` אחת עוקבת אחריהן	5
סיבת `drop` של hook או סיבת `deny` של `config.set`	4,096 תווים. הסוף של סיבה ארוכה יותר נחתך, וה-drop או ה-deny עדיין חלים. החיתוך דורש את Claude Code v2.1.292 או מאוחר יותר, ובגרסאות מוקדמות יותר ה-hook נכשל במקום זאת.
טקסט בעץ אחד	100,000 התווים הראשונים מצוירים
`language` או `path` של `Code`, `value` של אפשרות `Select`, או `module` של `Client`	10,000 תווים. אם אחד ארוך יותר, ה-hook של `ui.render` שהחזיר אותו נכשל.
`href` של `Link`	2,048 תווים. אם הוא ארוך יותר, ה-hook של `ui.render` שהחזיר אותו נכשל.
עומק קינון של עץ אחד	32 רמות מתחת לאלמנט השורש
אלמנטים וילדי טקסט בעץ אחד	20,000
תאי `Raster` בעץ אחד, `columns` כפול `rows` של כל `Raster`	262,144
בייטים של PNG או RGBA של כל ה-`Image` בעץ אחד	2 MiB
`$.store`	4 MiB של JSON בסך הכל
`$.session.messages()`	4,096 הרשומות החדשות ביותר
ציורים מחדש של `$.ui.invalidate('ui.render')`	מוגבלים ל-10 בשנייה, או 30 בטרמינל עבור החלונית הגלויה, הפס המורחב, ושורת הרמז מתחת לפרומפט. קריאות שמגיעות מוקדם יותר מאוחדות.
`$.ui.toast`	מוצג 4 שניות אלא אם מעבירים `{ timeoutMs }`. ב-מרנדר הקלאסי, toast חדש יותר של mod יכול לתפוס את מקומו של הישן שלו שמוצג או ממתין להצגה.
חלונית שנפתחת בלי שהמשתמש ביקש	ממוקמת מ-144 עמודות טרמינל, 110 אחרי שפתחו אותה פעם אחת
עומק קינון של ארגומנטים של קריאת API של mods	28,000 רמות. מעבר לכך, הקריאה נדחית עם הודעה שמסתיימת ב-`nesting deeper than 28000 levels is not supported`. דורש את Claude Code v2.1.299 או מאוחר יותר.
עומק קינון של אירוע שהשתנה שמועבר ל-`next`, מחוץ ל-hooks של async generator כמו אחד על `turn.step`	28,000 רמות. מעבר לכך, `next` נדחה עם הודעה שמסתיימת ב-`nesting deeper than 28000 levels is not supported`. דורש את Claude Code v2.1.299 או מאוחר יותר.
עומק קינון של ערך החזרה של hook, מחוץ ל-`ui.render`, `ui.resolve`, ו-hooks של async generator	28,000 רמות. מעבר לכך, תוצאת ה-hook נדחית, ו-ההודעה שמדווחת על כך כוללת את `nesting deeper than 28000 levels is not supported`. דורש את Claude Code v2.1.299 או מאוחר יותר.
scopes, כמו פונקציות, בלוקים ולולאות, שמקוננים זה בתוך זה בקובץ אחד של מודול hooks	2,000
שמות של פקודה, כלי, סוג subagent וחלונית	אותיות, ספרות, `_` ו-`-`, עד 64 תווים
בדיקה אחת של `claude plugin test`	5 שניות אלא אם הבדיקה מגדירה `timeoutMs`

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

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

שם	מיקום	מה זה עושה
`CLAUDE_CODE_PLUGIN_DIRS`	סביבה, או `env` ב-`~/.claude/settings.json`	תיקיות תוספים לטעינה כמו ש-`--plugin-dir` עושה, לאפליקציות שאי אפשר להעביר להן דגל. נתיבים מוחלטים מופרדים ב-`:`, או `;` ב-Windows.
`CLAUDE_CODE_PLUGIN_DIR_WATCH`	סביבה	`1` גורם לסשן לא אינטראקטיבי ארוך לטעון מחדש mods של `--plugin-dir` בשמירה
`prependPlugins`, `appendPlugins`	הגדרות מנוהלות. הגדרות משתמש רק במכונה בלי הגדרות מנוהלות, בסשן שהאישור שלו אינו `/login` של Team או Enterprise.	רשימות של מזהי תוספים, כמו `acme-guard@acme-tools`. mods ב-`prependPlugins` רצים לפני כל mod שמשתמש מתקין, ו-mods ב-`appendPlugins` רצים אחרי, בסדר הרשום. ראו הסדר שבו mods רצים.
`allowManagedModsOnly`	הגדרות מנוהלות, כאפשרות בשומר המובנה	רק mods שנחשבים של הארגון שלך, ו-mods מובנים ב-Claude Code, מריצים את ה-hooks שלהם. hooks של הגדרות המשתמשים ממשיכים לרוץ.
`allowModsToOverrideDenyRules`	הגדרות מנוהלות, כאפשרות בשומר המובנה	מאפשר ל-mod שמשתמש התקין לאשר קריאת כלי שכלל `deny` מסרב לה
`allowManagedHooksOnly`	הגדרות מנוהלות	חוסם hooks ו-mods מותקנים שאינם של הארגון שלך. ראו מה ממשיך לרוץ.
`disableAllHooks`	כל קובץ הגדרות	בהגדרות מנוהלות, שום mod או hook מתוסף מותקן אינו רץ. בהגדרות שלך, מה שהארגון שלך מנהל ממשיך לרוץ. ראו `disableAllHooks`.
`disableSideloadFlags`	הגדרות מנוהלות	דוחה את `--plugin-dir` ואת `--plugin-url` בהפעלה
`pluginConfigs`	הגדרות משתמש או מנוהלות	מחזיק ערכי `userConfig` ל-mod, לפי מפתח שהוא מזהה התוסף, כמו `acme-guard@acme-tools`, או השם שלו ו-`@inline`, כמו `first-mod@inline`, עבור אחד שנטען עם `--plugin-dir`

sec-default@builtin הוא שומר מובנה ב-Claude Code, רשום כ-cc-plugin-sec-default ב-/plugin ובלוג הדיבוג. הוא נטען לפני כל mod שאדם מתקין במכונה עם הגדרות מנוהלות, או בסשן שהאישור שלו הוא /login של Team או Enterprise. אם prependPlugins מנוהל מוגדר, השומר נטען רק כשהרשימה הזו מציינת אותו, במיקום הרשום.

המקור שלו נמצא בתיקיית mods/sec-default של מאגר Claude Code.

#פקודות

הפקודות והדגלים האלה טוענים, בודקים ובוחנים mod. פקודות claude רצות במעטפת שלך ופקודות / בפרומפט של Claude Code. בטבלה, <directory> מייצג נתיב שאתה מקליד, כמו ב-claude plugin validate ./first-mod. סוגריים מרובעים מסמנים ארגומנט אופציונלי.

פקודה	מה היא עושה
`/plugin`	מציג שורה כמו `1 mod active · first-mod` מתחת ללשוניות שלו כש-mod שאינו מובנה נטען
`claude plugin validate <directory>`	קורא את המניפסט של תוסף ואת מודול ה-hooks ומדווח על שגיאות, האירועים שהוא מטפל בהם, וקריאות ה-API של mods שהוא מבצע. `--strict` מתייחס לאזהרות כשגיאות ו-`--json` מדפיס דוח קריא למכונה.
`claude plugin test [directory]`	מריץ כל קובץ תחת התיקייה, או התיקייה הנוכחית כשלא נותנים אחת, ששמו מסתיים ב-`.test.ts` או `.test.tsx`. יוצא עם סטטוס 1 כשבדיקה נכשלת.
`claude --plugin-dir <directory>`	טוען תיקיית תוסף לסשן אחד וטוען מחדש את מודול ה-hooks שלו כששומרים. חוזרים על הדגל כדי לטעון כמה.
`/reload-plugins`	טוען מחדש תוספים כשמריצים אותו